@wodzik/cubecore 0.1.0

package/core/cubies.js

@@ -0,0 +1,169 @@
+/**
+ * The cube as pieces: corner / edge permutation and orientation in the
+ * standard (Kociemba) numbering, plus how the centres are turned (a Frame).
+ * The compact state codec and the two-phase solver work on this; everything
+ * else in cubecore uses the 54-sticker State.
+ *
+ * Corners URF UFL ULB UBR DFR DLF DBL DRB, edges UR UF UL UB DR DF DL DB FR FL
+ * BL BR. Corner twist counts how far the U/D sticker is turned from the U/D
+ * position (0..2, clockwise); an edge is flipped (1) when its first sticker —
+ * the U/D one, or F/B for the middle-layer edges — isn't in the first place.
+ */
+import { FRAMES, view } from "./frames.js";
+/** Facelets of each corner position, U/D sticker first, then clockwise. */
+export const CORNER_FACELETS = [
+    [8, 9, 20], [6, 18, 38], [0, 36, 47], [2, 45, 11],
+    [29, 26, 15], [27, 44, 24], [33, 53, 42], [35, 17, 51],
+];
+/** Facelets of each edge position, the reference sticker first. */
+export const EDGE_FACELETS = [
+    [5, 10], [7, 19], [3, 37], [1, 46], [32, 16], [28, 25],
+    [30, 43], [34, 52], [23, 12], [21, 41], [50, 39], [48, 14],
+];
+const centresHome = (s) => [0, 1, 2, 3, 4, 5].every((f) => s[f * 9 + 4] === f * 9 + 4);
+/** Pieces of a state, or null if it isn't made of real pieces. */
+export function toCubies(state) {
+    const frame = FRAMES.find((f) => centresHome(view(state, f)));
+    if (!frame)
+        return null;
+    const s = view(state, frame);
+    const cp = [], co = [], ep = [], eo = [];
+    for (const pos of CORNER_FACELETS) {
+        const st = pos.map((f) => s[f]);
+        const j = CORNER_FACELETS.findIndex((home) => home.includes(st[0]));
+        if (j < 0)
+            return null;
+        const home = CORNER_FACELETS[j];
+        const k = st.indexOf(home[0]);
+        if (k < 0 || st[(k + 1) % 3] !== home[1] || st[(k + 2) % 3] !== home[2])
+            return null;
+        cp.push(j);
+        co.push(k);
+    }
+    for (const pos of EDGE_FACELETS) {
+        const st = pos.map((f) => s[f]);
+        const j = EDGE_FACELETS.findIndex((home) => home.includes(st[0]));
+        if (j < 0)
+            return null;
+        const home = EDGE_FACELETS[j];
+        const flip = st[0] === home[0] ? 0 : 1;
+        if (st[1 - flip] !== home[1])
+            return null;
+        ep.push(j);
+        eo.push(flip);
+    }
+    if (new Set(cp).size !== 8 || new Set(ep).size !== 12)
+        return null;
+    return { frame, cp, co, ep, eo };
+}
+export function fromCubies(c) {
+    const s = new Uint8Array(54);
+    for (let f = 0; f < 6; f++)
+        s[f * 9 + 4] = f * 9 + 4;
+    CORNER_FACELETS.forEach((pos, i) => {
+        for (let n = 0; n < 3; n++)
+            s[pos[(n + c.co[i]) % 3]] = CORNER_FACELETS[c.cp[i]][n];
+    });
+    EDGE_FACELETS.forEach((pos, i) => {
+        for (let n = 0; n < 2; n++)
+            s[pos[(n + c.eo[i]) % 2]] = EDGE_FACELETS[c.ep[i]][n];
+    });
+    // `s` is the state seen with centres at home; put it back into the cube's own positions.
+    const state = new Uint8Array(54);
+    for (let i = 0; i < 54; i++)
+        state[c.frame.map[i]] = s[i];
+    return state;
+}
+/** Parity of a permutation (0 even, 1 odd). */
+export function parity(p) {
+    let odd = 0;
+    for (let i = 0; i < p.length; i++)
+        for (let j = i + 1; j < p.length; j++)
+            if (p[i] > p[j])
+                odd ^= 1;
+    return odd;
+}
+/** Reachable by turning (not a reassembled cube): twist sum ≡ 0 mod 3, flips even, equal parities. */
+export function isSolvable(c) {
+    return c.co.reduce((a, b) => a + b, 0) % 3 === 0 && c.eo.reduce((a, b) => a + b, 0) % 2 === 0 && parity(c.cp) === parity(c.ep);
+}
+// ─── ranks (for coordinates and the codec) ───
+/** Lehmer rank of a permutation of 0..n-1: 0 .. n!-1. */
+export function permRank(p) {
+    let r = 0;
+    const n = p.length;
+    for (let i = 0; i < n; i++) {
+        let smaller = 0;
+        for (let j = i + 1; j < n; j++)
+            if (p[j] < p[i])
+                smaller++;
+        r = r * (n - i) + smaller;
+    }
+    return r;
+}
+export function permUnrank(rank, n) {
+    const digits = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+        digits[i] = rank % (n - i);
+        rank = Math.floor(rank / (n - i));
+    }
+    const pool = Array.from({ length: n }, (_, i) => i);
+    return digits.map((d) => pool.splice(d, 1)[0]);
+}
+// ─── facelet strings ───
+const FACE_LETTERS = "URFDLB";
+/**
+ * A state from a 54-letter facelet string (Kociemba order U1…U9 R1… F1… D1…
+ * L1… B1…, each letter the face whose colour is there) — what smart cubes
+ * report and many tools exchange. Colours are read against the centres, so
+ * any letters work as long as each centre has its own. Null if the string
+ * isn't a reachable cube.
+ */
+export function stateFromFacelets(text) {
+    if (text.length !== 54)
+        return null;
+    const centreOf = new Map();
+    for (let f = 0; f < 6; f++)
+        centreOf.set(text[f * 9 + 4], f);
+    if (centreOf.size !== 6)
+        return null;
+    const colour = (i) => centreOf.get(text[i]);
+    const cls = (facelet) => Math.floor(facelet / 9); // home colour class of a facelet
+    const cp = [], co = [], ep = [], eo = [];
+    for (const pos of CORNER_FACELETS) {
+        const cols = pos.map(colour);
+        let found = false;
+        for (let j = 0; j < 8 && !found; j++) {
+            const home = CORNER_FACELETS[j].map(cls);
+            for (let k = 0; k < 3; k++) {
+                if (cols[k] === home[0] && cols[(k + 1) % 3] === home[1] && cols[(k + 2) % 3] === home[2]) {
+                    cp.push(j);
+                    co.push(k);
+                    found = true;
+                    break;
+                }
+            }
+        }
+        if (!found)
+            return null;
+    }
+    for (const pos of EDGE_FACELETS) {
+        const cols = pos.map(colour);
+        const j = EDGE_FACELETS.findIndex((home) => {
+            const h = home.map(cls);
+            return (cols[0] === h[0] && cols[1] === h[1]) || (cols[0] === h[1] && cols[1] === h[0]);
+        });
+        if (j < 0)
+            return null;
+        ep.push(j);
+        eo.push(cols[0] === cls(EDGE_FACELETS[j][0]) ? 0 : 1);
+    }
+    const c = { frame: FRAMES[0], cp, co, ep, eo };
+    if (new Set(cp).size !== 8 || new Set(ep).size !== 12 || !isSolvable(c))
+        return null;
+    return fromCubies(c);
+}
+/** The 54-letter facelet string of a state (each letter = the colour class's home face). */
+export function faceletsOf(state) {
+    return Array.from(state, (sticker) => FACE_LETTERS[Math.floor(sticker / 9)]).join("");
+}

package/core/frames.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Frames — the 24 ways to hold a cube — and "views": a state re-indexed so
+ * that a chosen frame looks like the canonical orientation.
+ *
+ * Every method check in cubecore is written once, for the canonical frame
+ * (e.g. "the cross is on D, the Roux first block is on L"). To be colour and
+ * orientation neutral, the checks run on `view(state, frame)` for each frame:
+ * a frame whose view passes tells you WHERE the cross / block actually is.
+ * Colours are never compared to fixed values — only to each other and to
+ * centres — so any colour scheme works.
+ */
+import { type Face, type Mat3 } from "./geometry.js";
+import type { State } from "./state.js";
+import type { Move } from "./moves.js";
+export interface Frame {
+    /** Stable id 0..23 (0 = identity). */
+    id: number;
+    /** Physical face that plays the canonical `face` in this frame. */
+    face: Record<Face, Face>;
+    /** view[i] = state[map[i]] — canonical facelet i ↔ physical facelet map[i]. */
+    map: Uint8Array;
+    matrix: Mat3;
+}
+export declare const FRAMES: readonly Frame[];
+export declare const IDENTITY_FRAME: Frame;
+/** The state as seen from `frame` — canonical checks can run on it directly. */
+export declare function view(state: State, frame: Frame): State;
+/**
+ * The state as if the cube were held in `frame`, with sticker identities
+ * renamed to match — so a solved cube is the identity again, and anything
+ * that reads pieces (toCubies, solvers, codecs) sees the frame's D as D.
+ * `view` keeps the physical sticker names; use it for colour checks.
+ */
+export declare function reframe(state: State, frame: Frame): State;
+/** Inverse of `reframe`: a state described in `frame` back in the cube's own positions and names. */
+export declare function unreframe(state: State, frame: Frame): State;
+/** Short human label, e.g. "D-bottom, F-front" style: canonical D and F mapped to physical faces. */
+export declare function frameLabel(frame: Frame): string;
+/** Frames whose canonical `face` sits on the physical face `physical`. */
+export declare function framesWith(face: Face, physical: Face): Frame[];
+/**
+ * The frame that holds physical face `bottom` down (and `front` towards you,
+ * if given): e.g. `frameFor("U")` looks at a cube whose cross was built on U
+ * as if it were on D, so canonical masks / checks apply.
+ */
+export declare function frameFor(bottom: Face, front?: Face): Frame;
+/**
+ * Colour neutral: the frame with the face whose centre shows colour class
+ * `bottomColor` down (and `frontColor` in front). Colour classes are home
+ * faces (0..5 = U R F D L B, or the letters): with the western scheme
+ * `frameForColors(state, "D")` = yellow down, whatever the scheme's colours.
+ * Uses the centres of `state`, so it works after rotations and slices.
+ */
+export declare function frameForColors(state: State, bottomColor: Face | number, frontColor?: Face | number): Frame;
+/**
+ * The same physical motion described from another orientation: a move written
+ * for the canonical frame, performed on a cube held as `frame`. E.g. with the
+ * frame that puts canonical D on physical F, "R U R'" (cross on D) becomes the
+ * moves that do the same thing to a cross on F.
+ */
+export declare function transformMoves(moves: readonly Move[], frame: Frame): Move[];

package/core/frames.js

@@ -0,0 +1,126 @@
+/**
+ * Frames — the 24 ways to hold a cube — and "views": a state re-indexed so
+ * that a chosen frame looks like the canonical orientation.
+ *
+ * Every method check in cubecore is written once, for the canonical frame
+ * (e.g. "the cross is on D, the Roux first block is on L"). To be colour and
+ * orientation neutral, the checks run on `view(state, frame)` for each frame:
+ * a frame whose view passes tells you WHERE the cross / block actually is.
+ * Colours are never compared to fixed values — only to each other and to
+ * centres — so any colour scheme works.
+ */
+import { FACELETS, FACELET_COUNT, FACES, IDENTITY, apply, faceOfNormal, faceletAt, multiply, rotationMatrix, FACE_NORMAL } from "./geometry.js";
+function buildFrames() {
+    const matrices = [IDENTITY];
+    const seen = new Set([IDENTITY.flat().join(",")]);
+    for (let i = 0; i < matrices.length; i++) {
+        for (const axis of [0, 1, 2]) {
+            const m = multiply(rotationMatrix(axis, 1), matrices[i]);
+            const k = m.flat().join(",");
+            if (!seen.has(k)) {
+                seen.add(k);
+                matrices.push(m);
+            }
+        }
+    }
+    return matrices.map((matrix, id) => {
+        const map = new Uint8Array(FACELET_COUNT);
+        for (const f of FACELETS)
+            map[f.index] = faceletAt(apply(matrix, f.pos), apply(matrix, f.normal));
+        const face = Object.fromEntries(FACES.map((fc) => [fc, faceOfNormal(apply(matrix, FACE_NORMAL[fc]))]));
+        return { id, face, map, matrix };
+    });
+}
+export const FRAMES = buildFrames();
+export const IDENTITY_FRAME = FRAMES[0];
+/** The state as seen from `frame` — canonical checks can run on it directly. */
+export function view(state, frame) {
+    const out = new Uint8Array(FACELET_COUNT);
+    for (let i = 0; i < FACELET_COUNT; i++)
+        out[i] = state[frame.map[i]];
+    return out;
+}
+/**
+ * The state as if the cube were held in `frame`, with sticker identities
+ * renamed to match — so a solved cube is the identity again, and anything
+ * that reads pieces (toCubies, solvers, codecs) sees the frame's D as D.
+ * `view` keeps the physical sticker names; use it for colour checks.
+ */
+export function reframe(state, frame) {
+    if (frame === IDENTITY_FRAME)
+        return new Uint8Array(state);
+    const rename = new Uint8Array(FACELET_COUNT);
+    for (let c = 0; c < FACELET_COUNT; c++)
+        rename[frame.map[c]] = c;
+    const out = new Uint8Array(FACELET_COUNT);
+    for (let i = 0; i < FACELET_COUNT; i++)
+        out[i] = rename[state[frame.map[i]]];
+    return out;
+}
+/** Inverse of `reframe`: a state described in `frame` back in the cube's own positions and names. */
+export function unreframe(state, frame) {
+    if (frame === IDENTITY_FRAME)
+        return new Uint8Array(state);
+    const out = new Uint8Array(FACELET_COUNT);
+    for (let i = 0; i < FACELET_COUNT; i++)
+        out[frame.map[i]] = frame.map[state[i]];
+    return out;
+}
+/** Short human label, e.g. "D-bottom, F-front" style: canonical D and F mapped to physical faces. */
+export function frameLabel(frame) {
+    return `${frame.face.D}${frame.face.F}`;
+}
+/** Frames whose canonical `face` sits on the physical face `physical`. */
+export function framesWith(face, physical) {
+    return FRAMES.filter((f) => f.face[face] === physical);
+}
+/**
+ * The frame that holds physical face `bottom` down (and `front` towards you,
+ * if given): e.g. `frameFor("U")` looks at a cube whose cross was built on U
+ * as if it were on D, so canonical masks / checks apply.
+ */
+export function frameFor(bottom, front) {
+    const f = FRAMES.find((fr) => fr.face.D === bottom && (!front || fr.face.F === front));
+    if (!f)
+        throw new Error(`No frame with ${bottom} down and ${front} in front`);
+    return f;
+}
+/**
+ * Colour neutral: the frame with the face whose centre shows colour class
+ * `bottomColor` down (and `frontColor` in front). Colour classes are home
+ * faces (0..5 = U R F D L B, or the letters): with the western scheme
+ * `frameForColors(state, "D")` = yellow down, whatever the scheme's colours.
+ * Uses the centres of `state`, so it works after rotations and slices.
+ */
+export function frameForColors(state, bottomColor, frontColor) {
+    const cls = (c) => (typeof c === "number" ? c : FACES.indexOf(c));
+    const faceWith = (c) => FACES.find((f) => Math.floor(state[FACES.indexOf(f) * 9 + 4] / 9) === c);
+    return frameFor(faceWith(cls(bottomColor)), frontColor === undefined ? undefined : faceWith(cls(frontColor)));
+}
+// ─── Re-expressing moves in another frame ───
+const FACE_FAMILY = { U: "U", R: "R", F: "F", D: "D", L: "L", B: "B" };
+const WIDE_FAMILY = { U: "u", R: "r", F: "f", D: "d", L: "l", B: "b" };
+/** Slice / rotation named by the face it turns like, plus whether that's inverted. */
+const SLICE_BY_FACE = { L: ["M", false], R: ["M", true], D: ["E", false], U: ["E", true], F: ["S", false], B: ["S", true] };
+const ROTATION_BY_FACE = { R: ["x", false], L: ["x", true], U: ["y", false], D: ["y", true], F: ["z", false], B: ["z", true] };
+const FACE_OF_FAMILY = { U: "U", R: "R", F: "F", D: "D", L: "L", B: "B", u: "U", r: "R", f: "F", d: "D", l: "L", b: "B" };
+const FOLLOWS = { M: "L", E: "D", S: "F", x: "R", y: "U", z: "F" };
+const inv = (a) => (a === 2 ? 2 : -a);
+/**
+ * The same physical motion described from another orientation: a move written
+ * for the canonical frame, performed on a cube held as `frame`. E.g. with the
+ * frame that puts canonical D on physical F, "R U R'" (cross on D) becomes the
+ * moves that do the same thing to a cross on F.
+ */
+export function transformMoves(moves, frame) {
+    return moves.map((m) => {
+        const face = FACE_OF_FAMILY[m.family];
+        if (face) {
+            const target = frame.face[face];
+            return { family: (m.family === m.family.toUpperCase() ? FACE_FAMILY : WIDE_FAMILY)[target], amount: m.amount };
+        }
+        const follows = FOLLOWS[m.family];
+        const [family, flipped] = (m.family === "x" || m.family === "y" || m.family === "z" ? ROTATION_BY_FACE : SLICE_BY_FACE)[frame.face[follows]];
+        return { family, amount: flipped ? inv(m.amount) : m.amount };
+    });
+}

package/core/geometry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Cube geometry — facelet positions in 3D, computed once. Every move, frame
+ * and block definition is derived from these positions instead of hand-typed
+ * permutation tables, so the tables can't contain typos.
+ *
+ * Coordinates: x → right, y → up, z → towards the viewer (front).
+ * Faces are ordered U R F D L B (Kociemba order); facelet index =
+ * face * 9 + row * 3 + col, rows/cols as seen when looking straight at the
+ * face in the usual net (U with F below it, D with F above it, the four side
+ * faces with U on top).
+ */
+export type Face = "U" | "R" | "F" | "D" | "L" | "B";
+export declare const FACES: readonly Face[];
+export type Vec3 = readonly [number, number, number];
+export declare const FACE_NORMAL: Record<Face, Vec3>;
+/**
+ * Tangent axes per face, as seen when looking straight at the face in the
+ * usual net: a = right, b = up, a × b = n (outward normal).
+ */
+export declare const FACE_BASIS: Record<Face, {
+    a: Vec3;
+    b: Vec3;
+    n: Vec3;
+}>;
+export interface Facelet {
+    index: number;
+    face: Face;
+    /** Position of the cubie this sticker is on. */
+    pos: Vec3;
+    /** Outward normal (the direction the sticker faces). */
+    normal: Vec3;
+}
+export declare const FACELETS: readonly Facelet[];
+export declare const FACELET_COUNT = 54;
+/** Facelet index at a cubie position facing `normal`, or -1. */
+export declare function faceletAt(pos: Vec3, normal: Vec3): number;
+/** Index of the centre facelet of a face. */
+export declare const centerOf: (face: Face) => number;
+export declare function faceOfNormal(n: Vec3): Face;
+export type Axis = 0 | 1 | 2;
+/** Rotate by `q` counter-clockwise quarter turns (any integer) about +axis. */
+export declare function rotate(v: Vec3, axis: Axis, q: number): Vec3;
+/** 3×3 integer matrix (rows) — used for cube orientations (frames). */
+export type Mat3 = readonly [Vec3, Vec3, Vec3];
+export declare const IDENTITY: Mat3;
+export declare function apply(m: Mat3, v: Vec3): Vec3;
+export declare function rotationMatrix(axis: Axis, q: number): Mat3;
+export declare function multiply(a: Mat3, b: Mat3): Mat3;
+export type CubieKind = "corner" | "edge" | "center";
+export interface Cubie {
+    pos: Vec3;
+    kind: CubieKind;
+    /** Facelet indices on this cubie. */
+    facelets: number[];
+}
+export declare const CUBIES: readonly Cubie[];
+/** The cubie a facelet position belongs to. */
+export declare const CUBIE_OF_FACELET: readonly Cubie[];

package/core/geometry.js

@@ -0,0 +1,132 @@
+/**
+ * Cube geometry — facelet positions in 3D, computed once. Every move, frame
+ * and block definition is derived from these positions instead of hand-typed
+ * permutation tables, so the tables can't contain typos.
+ *
+ * Coordinates: x → right, y → up, z → towards the viewer (front).
+ * Faces are ordered U R F D L B (Kociemba order); facelet index =
+ * face * 9 + row * 3 + col, rows/cols as seen when looking straight at the
+ * face in the usual net (U with F below it, D with F above it, the four side
+ * faces with U on top).
+ */
+export const FACES = ["U", "R", "F", "D", "L", "B"];
+export const FACE_NORMAL = {
+    U: [0, 1, 0],
+    R: [1, 0, 0],
+    F: [0, 0, 1],
+    D: [0, -1, 0],
+    L: [-1, 0, 0],
+    B: [0, 0, -1],
+};
+/**
+ * Tangent axes per face, as seen when looking straight at the face in the
+ * usual net: a = right, b = up, a × b = n (outward normal).
+ */
+export const FACE_BASIS = {
+    U: { a: [1, 0, 0], b: [0, 0, -1], n: [0, 1, 0] },
+    D: { a: [1, 0, 0], b: [0, 0, 1], n: [0, -1, 0] },
+    F: { a: [1, 0, 0], b: [0, 1, 0], n: [0, 0, 1] },
+    B: { a: [-1, 0, 0], b: [0, 1, 0], n: [0, 0, -1] },
+    R: { a: [0, 0, -1], b: [0, 1, 0], n: [1, 0, 0] },
+    L: { a: [0, 0, 1], b: [0, 1, 0], n: [-1, 0, 0] },
+};
+/** Cubie position of facelet (row, col) on `face`. */
+function faceletPosition(face, row, col) {
+    switch (face) {
+        case "U":
+            return [col - 1, 1, row - 1];
+        case "R":
+            return [1, 1 - row, 1 - col];
+        case "F":
+            return [col - 1, 1 - row, 1];
+        case "D":
+            return [col - 1, -1, 1 - row];
+        case "L":
+            return [-1, 1 - row, col - 1];
+        case "B":
+            return [1 - col, 1 - row, -1];
+    }
+}
+export const FACELETS = FACES.flatMap((face, f) => Array.from({ length: 9 }, (_, i) => ({
+    index: f * 9 + i,
+    face,
+    pos: faceletPosition(face, Math.floor(i / 3), i % 3),
+    normal: FACE_NORMAL[face],
+})));
+export const FACELET_COUNT = 54;
+const key = (pos, normal) => `${pos.join(",")}|${normal.join(",")}`;
+const BY_POS_NORMAL = new Map(FACELETS.map((f) => [key(f.pos, f.normal), f.index]));
+/** Facelet index at a cubie position facing `normal`, or -1. */
+export function faceletAt(pos, normal) {
+    return BY_POS_NORMAL.get(key(pos, normal)) ?? -1;
+}
+/** Index of the centre facelet of a face. */
+export const centerOf = (face) => FACES.indexOf(face) * 9 + 4;
+export function faceOfNormal(n) {
+    return FACES.find((f) => FACE_NORMAL[f].every((c, i) => c === n[i]));
+}
+/** One counter-clockwise quarter turn about the +axis (right-hand rule). */
+function quarter(v, axis) {
+    const [x, y, z] = v;
+    switch (axis) {
+        case 0:
+            return [x, -z, y];
+        case 1:
+            return [z, y, -x];
+        case 2:
+            return [-y, x, z];
+    }
+}
+/** Rotate by `q` counter-clockwise quarter turns (any integer) about +axis. */
+export function rotate(v, axis, q) {
+    let out = v;
+    for (let i = 0; i < ((q % 4) + 4) % 4; i++)
+        out = quarter(out, axis);
+    return out;
+}
+export const IDENTITY = [
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+];
+export function apply(m, v) {
+    return [
+        m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+        m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+        m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+    ];
+}
+export function rotationMatrix(axis, q) {
+    const cols = [rotate([1, 0, 0], axis, q), rotate([0, 1, 0], axis, q), rotate([0, 0, 1], axis, q)];
+    return [
+        [cols[0][0], cols[1][0], cols[2][0]],
+        [cols[0][1], cols[1][1], cols[2][1]],
+        [cols[0][2], cols[1][2], cols[2][2]],
+    ];
+}
+export function multiply(a, b) {
+    const row = (i) => [0, 1, 2].map((j) => a[i][0] * b[0][j] + a[i][1] * b[1][j] + a[i][2] * b[2][j]);
+    return [row(0), row(1), row(2)];
+}
+export const CUBIES = (() => {
+    const map = new Map();
+    for (const f of FACELETS) {
+        const k = f.pos.join(",");
+        let c = map.get(k);
+        if (!c) {
+            const nonZero = f.pos.filter((v) => v !== 0).length;
+            c = { pos: f.pos, kind: nonZero === 3 ? "corner" : nonZero === 2 ? "edge" : "center", facelets: [] };
+            map.set(k, c);
+        }
+        c.facelets.push(f.index);
+    }
+    return [...map.values()];
+})();
+/** The cubie a facelet position belongs to. */
+export const CUBIE_OF_FACELET = (() => {
+    const out = [];
+    for (const c of CUBIES)
+        for (const f of c.facelets)
+            out[f] = c;
+    return out;
+})();

package/core/index.d.ts

@@ -0,0 +1,19 @@
+export * from "./geometry.js";
+export * from "./moves.js";
+export * from "./notation.js";
+export * from "./state.js";
+export * from "./frames.js";
+export * as checks from "./checks.js";
+export * from "./method.js";
+export * from "./tracker.js";
+export * from "./masks.js";
+export * from "./centers.js";
+export * from "./physical.js";
+export * from "./stream.js";
+export * from "./bytes.js";
+export * from "./cubies.js";
+export * from "./stateCodec.js";
+export * from "./sequence.js";
+export * from "./practice.js";
+export * from "./arrows.js";
+export * from "./stages.js";

package/core/index.js

@@ -0,0 +1,19 @@
+export * from "./geometry.js";
+export * from "./moves.js";
+export * from "./notation.js";
+export * from "./state.js";
+export * from "./frames.js";
+export * as checks from "./checks.js";
+export * from "./method.js";
+export * from "./tracker.js";
+export * from "./masks.js";
+export * from "./centers.js";
+export * from "./physical.js";
+export * from "./stream.js";
+export * from "./bytes.js";
+export * from "./cubies.js";
+export * from "./stateCodec.js";
+export * from "./sequence.js";
+export * from "./practice.js";
+export * from "./arrows.js";
+export * from "./stages.js";

package/core/masks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Masks — which stickers matter. A mask gives each STICKER (by its home
+ * facelet, i.e. piece identity) a display state, so it follows the pieces as
+ * they move: masking "the cross edges" keeps highlighting them wherever they
+ * are, which is what a "watch these pieces" view needs.
+ *
+ * Masks are defined for the canonical frame (cross on D, last layer on U, Roux
+ * blocks on L/R) and mapped to any frame, so they are colour neutral too:
+ * `buildMask(CFOP_MASKS.oll, frame)` masks the last layer of a cube solved
+ * with the cross on any face.
+ */
+import { type Cubie, type Facelet } from "./geometry.js";
+import { type Frame } from "./frames.js";
+import type { State } from "./state.js";
+/**
+ * regular: full colour · dim: darkened colour (context) · ignored: grey (not
+ * relevant) · oriented: one "this sticker matters for orientation" colour ·
+ * invisible: not drawn.
+ */
+export type MaskState = "regular" | "dim" | "ignored" | "oriented" | "invisible";
+export declare const MASK_STATES: readonly MaskState[];
+/** Per home facelet (piece identity) → index into MASK_STATES. */
+export type Mask = Uint8Array;
+/** Rule over the CANONICAL home facelet and its cubie. */
+export type MaskRule = (facelet: Facelet, cubie: Cubie) => MaskState;
+export declare function buildMask(rule: MaskRule, frame?: Frame): Mask;
+export declare const fullMask: () => Mask;
+/** Display state of whatever sticker currently sits at facelet position `position`. */
+export declare function maskStateAt(mask: Mask, state: State, position: number): MaskState;
+export type MaskPreset = "full" | "first-layer" | "ll" | "centers" | "void";
+export declare const MASK_PRESETS: MaskPreset[];
+export declare function presetMask(preset: MaskPreset, frame?: Frame): Mask;

package/core/masks.js

@@ -0,0 +1,39 @@
+/**
+ * Masks — which stickers matter. A mask gives each STICKER (by its home
+ * facelet, i.e. piece identity) a display state, so it follows the pieces as
+ * they move: masking "the cross edges" keeps highlighting them wherever they
+ * are, which is what a "watch these pieces" view needs.
+ *
+ * Masks are defined for the canonical frame (cross on D, last layer on U, Roux
+ * blocks on L/R) and mapped to any frame, so they are colour neutral too:
+ * `buildMask(CFOP_MASKS.oll, frame)` masks the last layer of a cube solved
+ * with the cross on any face.
+ */
+import { CUBIE_OF_FACELET, FACELETS, FACELET_COUNT } from "./geometry.js";
+import { IDENTITY_FRAME } from "./frames.js";
+export const MASK_STATES = ["regular", "dim", "ignored", "oriented", "invisible"];
+const code = (s) => MASK_STATES.indexOf(s);
+export function buildMask(rule, frame = IDENTITY_FRAME) {
+    const mask = new Uint8Array(FACELET_COUNT);
+    for (const f of FACELETS)
+        mask[frame.map[f.index]] = code(rule(f, CUBIE_OF_FACELET[f.index]));
+    return mask;
+}
+export const fullMask = () => new Uint8Array(FACELET_COUNT); // all "regular" (code 0)
+/** Display state of whatever sticker currently sits at facelet position `position`. */
+export function maskStateAt(mask, state, position) {
+    return MASK_STATES[mask[state[position]]];
+}
+const RULES = {
+    full: () => "regular",
+    "first-layer": (f, c) => (c.kind === "center" || c.pos[1] === -1 ? "regular" : "ignored"),
+    ll: () => "regular",
+    /** Only the centres in colour — orientation practice, colour-neutral recognition. */
+    centers: (f, c) => (c.kind === "center" ? "regular" : "ignored"),
+    /** Void cube: no centres. */
+    void: (f, c) => (c.kind === "center" ? "invisible" : "regular"),
+};
+export const MASK_PRESETS = Object.keys(RULES);
+export function presetMask(preset, frame = IDENTITY_FRAME) {
+    return buildMask(RULES[preset], frame);
+}