@wodzik/cubecore 0.1.0

package/core/method.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The method engine's data model: a method is an ordered list of stages, each
+ * a check on the CANONICAL view (see checks.ts / frames.ts). Concrete methods
+ * live in their own packages (@cubecore/cfop, roux, zz, petrus, lbl) —
+ * adding one needs no engine change.
+ *
+ * Stages may report a `detail` (e.g. which F2L slot was just finished), in
+ * canonical terms; the tracker translates it to physical faces.
+ */
+import type { State } from "./state.js";
+export interface Stage {
+    id: string;
+    label: string;
+    done(s: State): boolean;
+    /** Canonical slot / sub-step finished at this stage, given the details already reported. */
+    detail?(s: State, earlier: readonly string[]): string | undefined;
+    /**
+     * The case this stage starts from (e.g. "OLL 27", "T", "OLL skip"),
+     * recognised on the state the previous stage finished in.
+     */
+    recognize?(s: State): string | undefined;
+}
+export interface Method {
+    id: string;
+    name: string;
+    stages: readonly Stage[];
+}
+/**
+ * Four stages "`label` 1…4" for things finished in any order (F2L pairs,
+ * LBL corners…): stage n is done once `count` lists n items (and `guard`
+ * holds); its detail is the item that was just added.
+ */
+export declare function countedStages(prefix: string, label: string, count: (s: State) => readonly string[], guard: (s: State) => boolean): Stage[];
+/** Orient, permute, AUF — the last layer of CFOP, ZZ and Petrus. */
+export declare const LAST_LAYER_STAGES: readonly Stage[];

package/core/method.js

@@ -0,0 +1,30 @@
+/**
+ * The method engine's data model: a method is an ordered list of stages, each
+ * a check on the CANONICAL view (see checks.ts / frames.ts). Concrete methods
+ * live in their own packages (@cubecore/cfop, roux, zz, petrus, lbl) —
+ * adding one needs no engine change.
+ *
+ * Stages may report a `detail` (e.g. which F2L slot was just finished), in
+ * canonical terms; the tracker translates it to physical faces.
+ */
+import * as C from "./checks.js";
+const newItem = (done, earlier) => done.find((x) => !earlier.includes(x));
+/**
+ * Four stages "`label` 1…4" for things finished in any order (F2L pairs,
+ * LBL corners…): stage n is done once `count` lists n items (and `guard`
+ * holds); its detail is the item that was just added.
+ */
+export function countedStages(prefix, label, count, guard) {
+    return [1, 2, 3, 4].map((n) => ({
+        id: `${prefix}-${n}`,
+        label: `${label} ${n}`,
+        done: (s) => guard(s) && count(s).length >= n,
+        detail: (s, earlier) => newItem(count(s), earlier),
+    }));
+}
+/** Orient, permute, AUF — the last layer of CFOP, ZZ and Petrus. */
+export const LAST_LAYER_STAGES = [
+    { id: "oll", label: "OLL", done: (s) => C.f2lSolved(s) && C.topOriented(s) },
+    { id: "pll", label: "PLL", done: C.solvedUpToAuf },
+    { id: "auf", label: "AUF", done: C.isSolved },
+];

package/core/moves.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Moves as facelet permutations, derived from geometry.ts.
+ *
+ * Families: face turns U R F D L B, slices M E S (M follows L, E follows D,
+ * S follows F), wide turns u r f d l b (also written Uw, Rw…), and whole-cube
+ * rotations x y z (x follows R, y follows U, z follows F).
+ *
+ * A permutation `p` is applied as `next[i] = prev[p[i]]`.
+ */
+import { type Axis } from "./geometry.js";
+export type MoveFamily = "U" | "R" | "F" | "D" | "L" | "B" | "u" | "r" | "f" | "d" | "l" | "b" | "M" | "E" | "S" | "x" | "y" | "z";
+/** 1 = clockwise quarter, 2 = half, -1 = counter-clockwise (prime). */
+export type Amount = 1 | 2 | -1;
+export interface Move {
+    family: MoveFamily;
+    amount: Amount;
+    /**
+     * Signed quarter turns as written, when that says more than `amount`:
+     * R2' = -2 (a half turn, counter-clockwise), R3 = 3, R3' = -3. Only the
+     * way to turn (arrows, display) — the state uses `amount`.
+     */
+    written?: number;
+}
+export type MoveKind = "face" | "wide" | "slice" | "rotation";
+interface FamilyDef {
+    axis: Axis;
+    /** Counter-clockwise quarter turns about +axis for ONE clockwise turn of this family. */
+    q: 1 | -1;
+    /** Which layer coordinates along the axis turn. */
+    layers: readonly number[];
+    kind: MoveKind;
+}
+export declare const FAMILY: Record<MoveFamily, FamilyDef>;
+export declare const MOVE_FAMILIES: MoveFamily[];
+export type Permutation = Uint8Array;
+export declare function identityPermutation(): Permutation;
+/** `a` then `b`. */
+export declare function composePermutations(a: Permutation, b: Permutation): Permutation;
+export declare function movePermutation(move: Move): Permutation;
+export declare function moveKind(move: Move): MoveKind;
+export declare function invertMove(move: Move): Move;
+export declare function formatMove(move: Move): string;
+/** Signed quarter turns the way it's meant to be turned (written, else from the amount: R2 = 2). */
+export declare const writtenQuarters: (move: Move) => number;
+/** Normalise a quarter-turn count to an Amount, or null for a full turn. */
+export declare function toAmount(quarters: number): Amount | null;
+export declare const amountQuarters: (a: Amount) => number;
+export {};

package/core/moves.js

@@ -0,0 +1,88 @@
+/**
+ * Moves as facelet permutations, derived from geometry.ts.
+ *
+ * Families: face turns U R F D L B, slices M E S (M follows L, E follows D,
+ * S follows F), wide turns u r f d l b (also written Uw, Rw…), and whole-cube
+ * rotations x y z (x follows R, y follows U, z follows F).
+ *
+ * A permutation `p` is applied as `next[i] = prev[p[i]]`.
+ */
+import { FACELETS, FACELET_COUNT, faceletAt, rotate } from "./geometry.js";
+const ALL = [-1, 0, 1];
+export const FAMILY = {
+    R: { axis: 0, q: -1, layers: [1], kind: "face" },
+    L: { axis: 0, q: 1, layers: [-1], kind: "face" },
+    U: { axis: 1, q: -1, layers: [1], kind: "face" },
+    D: { axis: 1, q: 1, layers: [-1], kind: "face" },
+    F: { axis: 2, q: -1, layers: [1], kind: "face" },
+    B: { axis: 2, q: 1, layers: [-1], kind: "face" },
+    r: { axis: 0, q: -1, layers: [1, 0], kind: "wide" },
+    l: { axis: 0, q: 1, layers: [-1, 0], kind: "wide" },
+    u: { axis: 1, q: -1, layers: [1, 0], kind: "wide" },
+    d: { axis: 1, q: 1, layers: [-1, 0], kind: "wide" },
+    f: { axis: 2, q: -1, layers: [1, 0], kind: "wide" },
+    b: { axis: 2, q: 1, layers: [-1, 0], kind: "wide" },
+    M: { axis: 0, q: 1, layers: [0], kind: "slice" },
+    E: { axis: 1, q: 1, layers: [0], kind: "slice" },
+    S: { axis: 2, q: -1, layers: [0], kind: "slice" },
+    x: { axis: 0, q: -1, layers: ALL, kind: "rotation" },
+    y: { axis: 1, q: -1, layers: ALL, kind: "rotation" },
+    z: { axis: 2, q: -1, layers: ALL, kind: "rotation" },
+};
+export const MOVE_FAMILIES = Object.keys(FAMILY);
+export function identityPermutation() {
+    return Uint8Array.from({ length: FACELET_COUNT }, (_, i) => i);
+}
+/** `a` then `b`. */
+export function composePermutations(a, b) {
+    const out = new Uint8Array(FACELET_COUNT);
+    for (let i = 0; i < FACELET_COUNT; i++)
+        out[i] = a[b[i]];
+    return out;
+}
+function quarterPermutation(def) {
+    const perm = identityPermutation();
+    for (const f of FACELETS) {
+        if (!def.layers.includes(f.pos[def.axis]))
+            continue;
+        const dest = faceletAt(rotate(f.pos, def.axis, def.q), rotate(f.normal, def.axis, def.q));
+        perm[dest] = f.index;
+    }
+    return perm;
+}
+const PERMS = new Map();
+for (const family of MOVE_FAMILIES) {
+    const q1 = quarterPermutation(FAMILY[family]);
+    const q2 = composePermutations(q1, q1);
+    const q3 = composePermutations(q2, q1);
+    PERMS.set(`${family}1`, q1);
+    PERMS.set(`${family}2`, q2);
+    PERMS.set(`${family}-1`, q3);
+}
+export function movePermutation(move) {
+    return PERMS.get(`${move.family}${move.amount}`);
+}
+export function moveKind(move) {
+    return FAMILY[move.family].kind;
+}
+export function invertMove(move) {
+    const out = { family: move.family, amount: move.amount === 2 ? 2 : -move.amount };
+    if (move.written !== undefined)
+        out.written = -move.written;
+    return out;
+}
+export function formatMove(move) {
+    if (move.written !== undefined) {
+        const n = Math.abs(move.written);
+        return move.family + (n === 1 ? "" : String(n)) + (move.written < 0 ? "'" : "");
+    }
+    return move.family + (move.amount === 2 ? "2" : move.amount === -1 ? "'" : "");
+}
+/** Signed quarter turns the way it's meant to be turned (written, else from the amount: R2 = 2). */
+export const writtenQuarters = (move) => move.written ?? (move.amount === -1 ? -1 : move.amount);
+/** Normalise a quarter-turn count to an Amount, or null for a full turn. */
+export function toAmount(quarters) {
+    const n = ((quarters % 4) + 4) % 4;
+    return n === 0 ? null : n === 1 ? 1 : n === 2 ? 2 : -1;
+}
+export const amountQuarters = (a) => (a === -1 ? 3 : a);

package/core/notation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Algorithm notation: parse, format, invert, simplify, mirror, metrics.
+ *
+ * Accepted: face turns (R R' R2 R2' R3), wide turns in both spellings
+ * (r / Rw, r' / Rw'), slices M E S, rotations x y z, grouping with repetition
+ * `(R U R' U')3`, commutators `[A, B]` = A B A' B', conjugates `[A: B]` =
+ * A B A'. Typographic apostrophes (’ ′) are accepted, `//` starts a comment,
+ * `.` is a pause (one beat). parseAlg flattens everything to a Move[];
+ * parseAlgDocument also says where each move came from in the text.
+ */
+import { type Move } from "./moves.js";
+export declare class NotationError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/** Where a move (or pause) came from in the text: [start, end) character offsets. */
+export interface SourceRange {
+    start: number;
+    end: number;
+}
+/**
+ * An algorithm as written: the moves, where each came from in the text
+ * (repeats and commutator inverses point at the move they copy), pauses (`.`,
+ * one beat each — `pausesBefore[k]` counts the beats before move k), and
+ * `// comments`. For showing the text in sync with playback.
+ */
+export interface AlgDocument {
+    moves: Move[];
+    sources: SourceRange[];
+    pausesBefore: number[];
+    comments: (SourceRange & {
+        text: string;
+    })[];
+}
+export declare function parseAlgDocument(text: string): AlgDocument;
+export declare function parseAlg(text: string): Move[];
+export declare function formatAlg(moves: readonly Move[]): string;
+export declare function invert(moves: readonly Move[]): Move[];
+/** Merge adjacent turns of the same family (R R → R2, R R' → nothing), repeatedly. */
+export declare function simplify(moves: readonly Move[]): Move[];
+/** Mirror left↔right (the plane between L and R): R ↔ L', U → U', M and x unchanged, … */
+export declare function mirrorLR(moves: readonly Move[]): Move[];
+export type Metric = "htm" | "qtm" | "stm" | "etm";
+/**
+ * HTM: face/wide turn = 1, slice = 2 (two outer layers), rotation = 0.
+ * QTM: like HTM but half turns count 2. STM: slices count 1. ETM: every token 1.
+ */
+export declare function moveCount(moves: readonly Move[], metric?: Metric): number;

package/core/notation.js

@@ -0,0 +1,226 @@
+/**
+ * Algorithm notation: parse, format, invert, simplify, mirror, metrics.
+ *
+ * Accepted: face turns (R R' R2 R2' R3), wide turns in both spellings
+ * (r / Rw, r' / Rw'), slices M E S, rotations x y z, grouping with repetition
+ * `(R U R' U')3`, commutators `[A, B]` = A B A' B', conjugates `[A: B]` =
+ * A B A'. Typographic apostrophes (’ ′) are accepted, `//` starts a comment,
+ * `.` is a pause (one beat). parseAlg flattens everything to a Move[];
+ * parseAlgDocument also says where each move came from in the text.
+ */
+import { FAMILY, amountQuarters, formatMove, invertMove, moveKind, toAmount } from "./moves.js";
+export class NotationError extends Error {
+    position;
+    constructor(message, position) {
+        super(`${message} (at ${position})`);
+        this.position = position;
+    }
+}
+const FACE_LETTERS = "URFDLB";
+const WIDE_LETTERS = "urfdlb";
+const OTHER_LETTERS = "MESxyz";
+class Parser {
+    text;
+    pos = 0;
+    comments = [];
+    constructor(text) {
+        this.text = text;
+    }
+    parse() {
+        const items = this.sequence(null);
+        this.skipSpace();
+        if (this.pos < this.text.length)
+            throw new NotationError(`Unexpected "${this.text[this.pos]}"`, this.pos);
+        return items;
+    }
+    skipSpace() {
+        while (this.pos < this.text.length) {
+            const c = this.text[this.pos];
+            if (c === "/" && this.text[this.pos + 1] === "/") {
+                const start = this.pos;
+                while (this.pos < this.text.length && this.text[this.pos] !== "\n")
+                    this.pos++;
+                this.comments.push({ start, end: this.pos, text: this.text.slice(start + 2, this.pos).trim() });
+            }
+            else if (/\s/.test(c))
+                this.pos++;
+            else
+                break;
+        }
+    }
+    /** Items until `stop` (one of the given closing characters) or end of input. */
+    sequence(stop) {
+        const out = [];
+        for (;;) {
+            this.skipSpace();
+            const c = this.text[this.pos];
+            if (c === undefined || (stop !== null && stop.includes(c)))
+                return out;
+            if (c === "(") {
+                this.pos++;
+                const inner = this.sequence(")");
+                this.expect(")");
+                out.push(...repeat(inner, this.count()));
+            }
+            else if (c === "[") {
+                this.pos++;
+                const a = this.sequence(",:");
+                const sep = this.text[this.pos];
+                if (sep !== "," && sep !== ":")
+                    throw new NotationError('Expected "," or ":" in brackets', this.pos);
+                this.pos++;
+                const b = this.sequence("]");
+                this.expect("]");
+                const group = sep === "," ? [...a, ...b, ...invertItems(a), ...invertItems(b)] : [...a, ...b, ...invertItems(a)];
+                out.push(...repeat(group, this.count()));
+            }
+            else if (c === ".") {
+                // A pause (one beat, as in cubing.js).
+                out.push({ pause: true, start: this.pos, end: this.pos + 1 });
+                this.pos++;
+            }
+            else {
+                const start = this.pos;
+                const m = this.move();
+                if (m)
+                    out.push({ move: m, start, end: this.pos }); // null = a full turn (R4), which does nothing
+            }
+        }
+    }
+    expect(c) {
+        this.skipSpace();
+        if (this.text[this.pos] !== c)
+            throw new NotationError(`Expected "${c}"`, this.pos);
+        this.pos++;
+    }
+    count() {
+        const m = /^\d+/.exec(this.text.slice(this.pos));
+        if (!m)
+            return 1;
+        this.pos += m[0].length;
+        return Number(m[0]);
+    }
+    move() {
+        const start = this.pos;
+        const c = this.text[this.pos];
+        let family;
+        if (FACE_LETTERS.includes(c)) {
+            this.pos++;
+            if (this.text[this.pos] === "w") {
+                this.pos++;
+                family = c.toLowerCase();
+            }
+            else
+                family = c;
+        }
+        else if (WIDE_LETTERS.includes(c) || OTHER_LETTERS.includes(c)) {
+            this.pos++;
+            family = c;
+        }
+        else {
+            throw new NotationError(`Unknown move "${c}"`, start);
+        }
+        let quarters = this.count();
+        if (/['’′]/.test(this.text[this.pos] ?? "")) {
+            this.pos++;
+            quarters = -quarters;
+        }
+        const amount = toAmount(quarters);
+        if (amount === null)
+            return null;
+        // Keep the way it's written when the amount alone would lose it (R2', R3, R3').
+        const plain = amount === -1 ? -1 : amount;
+        return quarters === plain ? { family, amount } : { family, amount, written: quarters };
+    }
+}
+function repeat(items, n) {
+    const out = [];
+    for (let i = 0; i < n; i++)
+        out.push(...items);
+    return out;
+}
+/** Inverse keeping each move's source (commutators / conjugates point back at what was written). */
+function invertItems(items) {
+    return [...items].reverse().map((it) => ("move" in it ? { ...it, move: invertMove(it.move) } : it));
+}
+export function parseAlgDocument(text) {
+    const parser = new Parser(text);
+    const items = parser.parse();
+    const moves = [], sources = [], pausesBefore = [];
+    let beats = 0;
+    for (const it of items) {
+        if ("pause" in it)
+            beats++;
+        else {
+            moves.push(it.move);
+            sources.push({ start: it.start, end: it.end });
+            pausesBefore.push(beats);
+            beats = 0;
+        }
+    }
+    return { moves, sources, pausesBefore, comments: parser.comments };
+}
+export function parseAlg(text) {
+    return parseAlgDocument(text).moves;
+}
+export function formatAlg(moves) {
+    return moves.map(formatMove).join(" ");
+}
+export function invert(moves) {
+    return [...moves].reverse().map(invertMove);
+}
+/** Merge adjacent turns of the same family (R R → R2, R R' → nothing), repeatedly. */
+export function simplify(moves) {
+    const out = [];
+    for (const m of moves) {
+        const last = out[out.length - 1];
+        if (last && last.family === m.family) {
+            out.pop();
+            const merged = toAmount(amountQuarters(last.amount) + amountQuarters(m.amount));
+            if (merged !== null)
+                out.push({ family: m.family, amount: merged });
+        }
+        else
+            out.push(m);
+    }
+    return out;
+}
+const LAYER_MIRROR = { R: "L", L: "R", r: "l", l: "r" };
+/** Mirror left↔right (the plane between L and R): R ↔ L', U → U', M and x unchanged, … */
+export function mirrorLR(moves) {
+    return moves.map((m) => {
+        const def = FAMILY[m.family];
+        if (def.axis === 0) {
+            const family = LAYER_MIRROR[m.family] ?? m.family;
+            const flip = FAMILY[family].q !== def.q;
+            return { family, amount: (flip && m.amount !== 2 ? -m.amount : m.amount) };
+        }
+        return invertMove(m);
+    });
+}
+/**
+ * HTM: face/wide turn = 1, slice = 2 (two outer layers), rotation = 0.
+ * QTM: like HTM but half turns count 2. STM: slices count 1. ETM: every token 1.
+ */
+export function moveCount(moves, metric = "htm") {
+    let n = 0;
+    for (const m of moves) {
+        const kind = moveKind(m);
+        const half = m.amount === 2 ? 2 : 1;
+        switch (metric) {
+            case "etm":
+                n += 1;
+                break;
+            case "stm":
+                n += kind === "rotation" ? 0 : 1;
+                break;
+            case "htm":
+                n += kind === "rotation" ? 0 : kind === "slice" ? 2 : 1;
+                break;
+            case "qtm":
+                n += kind === "rotation" ? 0 : (kind === "slice" ? 2 : 1) * half;
+                break;
+        }
+    }
+    return n;
+}

package/core/physical.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What a smart cube actually sees. A Bluetooth cube reports only turns of its
+ * six faces, measured against its own centres: no rotations, no slices, no
+ * wide turns. An algorithm written with them is, physically, face turns plus
+ * a change in how the cube is held:
+ *
+ *   r   = L  + x        (the two turning layers = the opposite face the other way, plus a rotation)
+ *   M   = R L' + x'
+ *   r U = L F           (after r the cube is held x: the U you turn is the physical F)
+ *
+ * `toFaceTurns` converts an algorithm to the face turns a smart cube would
+ * report; `OrientationTracker` does it move by move and always knows how the
+ * cube is held — where each centre is after an algorithm with M slices or
+ * rotations (Roux LSE, rotations between F2L pairs…).
+ *
+ * Orientation is a Frame (see frames.ts): canonical = the algorithm's view
+ * (U = up in your hands), physical = the cube's own centres.
+ */
+import { type Frame } from "./frames.js";
+import { type Axis, type Face } from "./geometry.js";
+import { type Move } from "./moves.js";
+/**
+ * One move in the holder's view → the face turns (in the holder's view) and
+ * the rotation of the whole cube it implies. A move turning the middle layer
+ * is the same as rotating the cube that way and turning the other layers back.
+ */
+export declare function decompose(move: Move): {
+    turns: Move[];
+    rotation: {
+        axis: Axis;
+        quarters: number;
+    } | null;
+};
+/**
+ * Follows an algorithm move by move: which physical face each turn is, and how
+ * the cube is held afterwards. Feed it the moves of what you ask the solver to
+ * do; compare `push` results with what the smart cube reports.
+ */
+export declare class OrientationTracker {
+    private m;
+    constructor(start?: Frame);
+    /** How the cube is held: `frame.face.U` is the physical face (centre) now on top, etc. */
+    get frame(): Frame;
+    /** Physical face (by its centre) in each position of the holder's view. */
+    get centers(): Record<Face, Face>;
+    /** The physical face turns this move is — what a smart cube would report. */
+    push(move: Move | string): Move[];
+}
+/** An algorithm as the face turns a smart cube reports, and how the cube is held at the end. */
+export declare function toFaceTurns(alg: readonly Move[] | string, start?: Frame): {
+    moves: Move[];
+    frame: Frame;
+};

package/core/physical.js

@@ -0,0 +1,99 @@
+/**
+ * What a smart cube actually sees. A Bluetooth cube reports only turns of its
+ * six faces, measured against its own centres: no rotations, no slices, no
+ * wide turns. An algorithm written with them is, physically, face turns plus
+ * a change in how the cube is held:
+ *
+ *   r   = L  + x        (the two turning layers = the opposite face the other way, plus a rotation)
+ *   M   = R L' + x'
+ *   r U = L F           (after r the cube is held x: the U you turn is the physical F)
+ *
+ * `toFaceTurns` converts an algorithm to the face turns a smart cube would
+ * report; `OrientationTracker` does it move by move and always knows how the
+ * cube is held — where each centre is after an algorithm with M slices or
+ * rotations (Roux LSE, rotations between F2L pairs…).
+ *
+ * Orientation is a Frame (see frames.ts): canonical = the algorithm's view
+ * (U = up in your hands), physical = the cube's own centres.
+ */
+import { FRAMES, IDENTITY_FRAME } from "./frames.js";
+import { FACE_NORMAL, apply, faceOfNormal, multiply, rotationMatrix } from "./geometry.js";
+import { FAMILY, toAmount } from "./moves.js";
+import { parseAlg } from "./notation.js";
+const FACE_ON_AXIS = {
+    0: { 1: "R", [-1]: "L" },
+    1: { 1: "U", [-1]: "D" },
+    2: { 1: "F", [-1]: "B" },
+};
+const key = (m) => m.flat().map((v) => (v === 0 ? 0 : v)).join(","); // no -0
+const byMatrix = new Map(FRAMES.map((f) => [key(f.matrix), f]));
+const frameOf = (m) => byMatrix.get(key(m));
+const transpose = (m) => [
+    [m[0][0], m[1][0], m[2][0]],
+    [m[0][1], m[1][1], m[2][1]],
+    [m[0][2], m[1][2], m[2][2]],
+];
+/** Signed quarter turns (CCW about +axis) of a move. */
+const quartersOf = (m) => FAMILY[m.family].q * (m.amount === -1 ? -1 : m.amount === 2 ? 2 : 1);
+/** A face turn of `quarters` CCW about +axis on the layer at `layer` (±1), as a Move of that face. */
+function faceTurn(axis, layer, quarters) {
+    const face = FACE_ON_AXIS[axis][layer];
+    const amount = toAmount(quarters * FAMILY[face].q); // q is ±1, so dividing = multiplying
+    return amount === null ? null : { family: face, amount };
+}
+/**
+ * One move in the holder's view → the face turns (in the holder's view) and
+ * the rotation of the whole cube it implies. A move turning the middle layer
+ * is the same as rotating the cube that way and turning the other layers back.
+ */
+export function decompose(move) {
+    const def = FAMILY[move.family];
+    const q = quartersOf(move);
+    if (!def.layers.includes(0)) {
+        return { turns: def.layers.map((l) => faceTurn(def.axis, l, q)).filter((m) => m !== null), rotation: null };
+    }
+    const others = [-1, 1].filter((l) => !def.layers.includes(l));
+    return { turns: others.map((l) => faceTurn(def.axis, l, -q)).filter((m) => m !== null), rotation: { axis: def.axis, quarters: q } };
+}
+/**
+ * Follows an algorithm move by move: which physical face each turn is, and how
+ * the cube is held afterwards. Feed it the moves of what you ask the solver to
+ * do; compare `push` results with what the smart cube reports.
+ */
+export class OrientationTracker {
+    m;
+    constructor(start = IDENTITY_FRAME) {
+        this.m = start.matrix;
+    }
+    /** How the cube is held: `frame.face.U` is the physical face (centre) now on top, etc. */
+    get frame() {
+        return frameOf(this.m);
+    }
+    /** Physical face (by its centre) in each position of the holder's view. */
+    get centers() {
+        return this.frame.face;
+    }
+    /** The physical face turns this move is — what a smart cube would report. */
+    push(move) {
+        const moves = typeof move === "string" ? parseAlg(move) : [move];
+        const out = [];
+        for (const mv of moves) {
+            const { turns, rotation } = decompose(mv);
+            for (const t of turns) {
+                // Holder-view face → the physical face in that position (same turning direction: rotations are proper).
+                const physical = faceOfNormal(apply(this.m, FACE_NORMAL[t.family]));
+                out.push({ family: physical, amount: t.amount });
+            }
+            // Turning the cube by R (holder's view) moves the body: body = M · R⁻¹ · view.
+            if (rotation)
+                this.m = multiply(this.m, transpose(rotationMatrix(rotation.axis, rotation.quarters)));
+        }
+        return out;
+    }
+}
+/** An algorithm as the face turns a smart cube reports, and how the cube is held at the end. */
+export function toFaceTurns(alg, start = IDENTITY_FRAME) {
+    const t = new OrientationTracker(start);
+    const moves = (typeof alg === "string" ? parseAlg(alg) : alg).flatMap((m) => t.push(m));
+    return { moves, frame: t.frame };
+}