@wodzik/cubecore 0.1.0

package/image/svg.js

@@ -0,0 +1,215 @@
+/**
+ * Cube pictures as SVG strings — no DOM, no canvas: the same call works in a
+ * browser, a worker, or on a server (Node/Bun), and the output is a plain
+ * string you can cache, inline, serve or turn into PNG.
+ *
+ * Looks come from the same `Skin` as the 3D renderer (@cubecore/skin):
+ * colours, mask colours, tile shapes per piece kind, custom SVG tile outlines,
+ * stickerless tiles and the logo — one skin, one look in 3D and in pictures.
+ *
+ * Views:
+ *   "iso" — 3D-looking cube showing U, F and R (like a case card)
+ *   "top" — last-layer diagram: U face plus the side stickers of the top layer
+ *   "net" — unfolded cube (U on top, L F R B across, D below)
+ *
+ * Every tile is drawn in its face's own (a, b) coordinates and then mapped to
+ * the picture by an affine projection per view, so shapes, paths and logos
+ * work the same way in all three views.
+ */
+import { FACELETS, FACE_BASIS, IDENTITY_FRAME, apply, centerUp, colorAt, faceOfNormal, maskStateAt, solvedSpins, stickerTurn, view as frameView, } from "../core/index.js";
+import { SKINS, featureDef, imageUrl, kindOfSticker, roundedOutline, selectedStickers, stickerColor, stickerLayout, overlayOutline, stickerlessOutline, themed, tileSize, tileThickness, } from "../skin/index.js";
+const r3 = (n) => Math.round(n * 1000) / 1000;
+const add = (p, q, k = 1) => [p[0] + q[0] * k, p[1] + q[1] * k, p[2] + q[2] * k];
+const dot = (p, q) => p[0] * q[0] + p[1] * q[1] + p[2] * q[2];
+// ─── projections (affine, per face) ───
+const COS30 = Math.cos(Math.PI / 6);
+const isoProjection = (_face, p) => [(p[0] - p[2]) * COS30, (p[0] + p[2]) * 0.5 - p[1]];
+/** Faces of the net sit apart, so stickerless tiles of neighbouring faces don't run into each other. */
+const NET_GAP = 0.15;
+const NET_CELL = { U: [1, 0], L: [0, 1], F: [1, 1], R: [2, 1], B: [3, 1], D: [1, 2] };
+const NET_ORIGIN = Object.fromEntries(Object.entries(NET_CELL).map(([f, [c, r]]) => [f, [c * (3 + NET_GAP), r * (3 + NET_GAP)]]));
+const netProjection = (face, p) => {
+    const { a, b } = FACE_BASIS[face];
+    const [ox, oy] = NET_ORIGIN[face];
+    return [ox + 1.5 + dot(p, a), oy + 1.5 - dot(p, b)];
+};
+/**
+ * Side stickers of the top layer are squashed into strips of this depth
+ * around the U face, and spread out as they go down — in perspective, as
+ * seen from above (the strips are trapezoids, like the sides of a cube
+ * looked at from over its top).
+ */
+const STRIP = 0.35;
+const STRIP_GAP = 0.08;
+const topProjection = (face, p) => {
+    if (face === "U")
+        return [1.5 + p[0], 1.5 + p[2]];
+    const n = FACE_BASIS[face].n;
+    const out = STRIP_GAP + (1.5 - p[1]) * STRIP;
+    const spread = 1 + out / 1.5;
+    // Along the edge (the axis the face normal doesn't point along): spread out with the depth.
+    const x = n[0] !== 0 ? p[0] : p[0] * spread;
+    const z = n[2] !== 0 ? p[2] : p[2] * spread;
+    return [1.5 + x + n[0] * out, 1.5 + z + n[2] * out];
+};
+const E = STRIP + STRIP_GAP + 0.1;
+const VIEWS = {
+    iso: { project: isoProjection, shows: (f) => f.face === "U" || f.face === "F" || f.face === "R", fullFaces: ["U", "F", "R"], bodies: ["U", "F", "R"], box: [-3 * COS30 - 0.1, -3.1, 6 * COS30 + 0.2, 6.2] },
+    net: { project: netProjection, shows: () => true, fullFaces: ["U", "R", "F", "D", "L", "B"], bodies: ["U", "R", "F", "D", "L", "B"], box: [-0.1, -0.1, 12 + 3 * NET_GAP + 0.2, 9 + 2 * NET_GAP + 0.2] },
+    top: { project: topProjection, shows: (f) => f.face === "U" || (f.pos[1] === 1 && f.face !== "D"), fullFaces: ["U"], bodies: ["U"], box: [-E, -E, 3 + 2 * E, 3 + 2 * E] },
+};
+// ─── drawing helpers ───
+const polygon = (pts) => `M${pts.map((p) => `${r3(p[0])},${r3(p[1])}`).join("L")}Z`;
+/** Rounded polygon through `pts` (convex, in order) — the cubie body faces. */
+function roundedPolygon(pts, radius) {
+    const n = pts.length;
+    let d = "";
+    for (let i = 0; i < n; i++) {
+        const prev = pts[(i + n - 1) % n], cur = pts[i], next = pts[(i + 1) % n];
+        const toward = (a, b) => {
+            const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+            const k = Math.min(radius, len / 2) / len;
+            return [a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k];
+        };
+        const p1 = toward(cur, prev), p2 = toward(cur, next);
+        d += `${i === 0 ? "M" : "L"}${r3(p1[0])},${r3(p1[1])}Q${r3(cur[0])},${r3(cur[1])} ${r3(p2[0])},${r3(p2[1])}`;
+    }
+    return d + "Z";
+}
+/** 3D point of local tile coordinates (x along a, y along b) on facelet `f`. */
+function onFace(f, x, y) {
+    const { a, b } = FACE_BASIS[f.face];
+    return add(add(add(f.pos, f.normal, 0.5), a, x), b, y);
+}
+/**
+ * SVG `matrix(...)` mapping a unit box (0..1, y down — SVG convention) of side
+ * `side` onto facelet `f` in the picture: turned `spin` quarters about its
+ * own centre, moved by `offset` (tile-local, cubie units), then turned
+ * `quarters` CCW with the sticker.
+ */
+function boxTransform(f, side, quarters, project, offset = [0, 0], spin = 0, reach) {
+    const c = Math.cos((quarters * Math.PI) / 2), s = Math.sin((quarters * Math.PI) / 2);
+    const c2 = Math.cos((spin * Math.PI) / 2), s2 = Math.sin((spin * Math.PI) / 2);
+    const half = side / 2;
+    const at = (px, py) => {
+        // Box point → turned by its own `spin` → moved by `offset` (sticker frame) → turned with the sticker.
+        // `reach`: stickerless path tiles — the box's outer sides (left / top in the path convention) run out to the cube edge.
+        const bx = reach?.left ? -reach.edge + px * (reach.edge + half) : (px - 0.5) * side;
+        const by = reach?.top ? reach.edge - py * (reach.edge + half) : (0.5 - py) * side;
+        const lx = bx * c2 - by * s2 + offset[0], ly = bx * s2 + by * c2 + offset[1];
+        return project(f.face, onFace(f, lx * c - ly * s, lx * s + ly * c));
+    };
+    const o = at(0, 0), x = at(1, 0), y = at(0, 1);
+    return `matrix(${[x[0] - o[0], x[1] - o[1], y[0] - o[0], y[1] - o[1], o[0], o[1]].map((n) => r3(n)).join(" ")})`;
+}
+function tileShape(skin) {
+    const r = skin.stickers.radius;
+    return skin.stickers.shape ?? { corner: { inner: r, outer: r }, edge: { inner: r, outer: r }, center: r };
+}
+/** A physical centre's spin, re-expressed for the canonical face it plays in `frame`. */
+function spinInFrame(spins, state, centre, frame) {
+    const spin = spins[centre];
+    if (!frame || frame === IDENTITY_FRAME)
+        return spin;
+    const f = FACELETS[state.indexOf(centre * 9 + 4)];
+    const up = centerUp(f.face, spin);
+    // Canonical vectors map to physical ones by `frame.matrix`; go back with its transpose.
+    const m = frame.matrix;
+    const t = [
+        [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]],
+    ];
+    const face = faceOfNormal(apply(t, f.normal));
+    const canonicalUp = apply(t, up);
+    for (let k = 0; k < 4; k++)
+        if (centerUp(face, k).every((v, i) => v === canonicalUp[i]))
+            return k;
+    return 0;
+}
+const attr = (v) => v.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+// ─── render ───
+export function renderSvg(state, options = {}) {
+    const viewName = options.view ?? "iso";
+    const size = options.size ?? 160;
+    const skin = themed(options.skin ?? SKINS.default, options.theme ?? "dark");
+    const v = VIEWS[viewName];
+    const s = options.frame && options.frame !== IDENTITY_FRAME ? frameView(state, options.frame) : state;
+    const sideOf = (kind) => tileSize(skin, kind) * skin.cubieSize;
+    const shape = tileShape(skin);
+    let out = "";
+    if (skin.background)
+        out += `<rect x="${r3(v.box[0])}" y="${r3(v.box[1])}" width="${r3(v.box[2])}" height="${r3(v.box[3])}" fill="${skin.background}"/>`;
+    // Plastic: one rounded square per drawn face — unless the skin wants the gaps see-through in pictures.
+    const plastic = skin.pictureBody === undefined ? skin.body : skin.pictureBody;
+    for (const face of plastic === null ? [] : v.bodies) {
+        const f = FACELETS.find((x) => x.face === face && x.index % 9 === 4);
+        const corners = [[-1, -1], [1, -1], [1, 1], [-1, 1]].map(([u, w]) => v.project(face, onFace(f, u * 1.5, w * 1.5)));
+        out += `<path d="${roundedPolygon(corners, skin.cubieRadius * 1.2)}" fill="${plastic}"/>`;
+    }
+    for (const f of FACELETS) {
+        if (!v.shows(f))
+            continue;
+        const st = options.mask ? maskStateAt(options.mask, s, f.index) : "regular";
+        const fill = stickerColor(skin, colorAt(s, f.index), st);
+        if (!fill)
+            continue;
+        const layout = stickerLayout(f.index, shape);
+        const path = skin.stickers.paths?.[layout.kind];
+        const kindSide = sideOf(layout.kind);
+        // Stickers lying on the body (stickered cubes): the sticker's own outline on the plastic.
+        const overlay = skin.stickers.overlay;
+        if (overlay) {
+            out += `<path d="${polygon(overlayOutline(f.index, overlay, 6).map(([x, y]) => v.project(f.face, onFace(f, x, y))))}" fill="${fill}"/>`;
+            continue;
+        }
+        if (path) {
+            const reach = skin.stickers.fillOuter && layout.kind !== "center" ? { left: layout.kind === "corner", top: true, edge: 0.506 } : undefined;
+            out += `<path d="${attr(path)}" transform="${boxTransform(f, kindSide, layout.pathQuarters, v.project, [0, 0], 0, reach)}" fill="${fill}"/>`;
+            continue;
+        }
+        // Stickerless: outer sides reach the cube edge (a hair past it, so neighbouring faces overlap instead of leaving an anti-aliased seam).
+        const outline = skin.stickers.fillOuter ? stickerlessOutline(layout, kindSide, 0.506, 6) : roundedOutline(kindSide, layout.radii, 6);
+        out += `<path d="${polygon(outline.map(([x, y]) => v.project(f.face, onFace(f, x, y))))}" fill="${fill}"/>`;
+    }
+    // Decals and features ride on their sticker, turned with it — as in 3D.
+    const spins = options.spins ?? solvedSpins();
+    const turnOf = (sticker) => sticker % 9 === 4 ? spinInFrame(spins, state, Math.floor(sticker / 9), options.frame) : stickerTurn(s, sticker);
+    const placed = (sticker, regularOnly) => {
+        const pos = s.indexOf(sticker);
+        const f = FACELETS[pos];
+        if (!v.shows(f) || !v.fullFaces.includes(f.face))
+            return null; // not on squashed strips
+        const st = options.mask ? maskStateAt(options.mask, s, pos) : "regular";
+        if (st === "invisible" || (regularOnly && st !== "regular"))
+            return null;
+        return f;
+    };
+    for (const use of skin.features ?? []) {
+        const def = featureDef(use.type);
+        if (!def?.svg)
+            continue;
+        for (const sticker of selectedStickers(use.select)) {
+            const f = placed(sticker, false);
+            const kind = kindOfSticker(sticker);
+            const markup = def.svg({ side: sideOf(kind), thickness: tileThickness(skin, kind), params: use.params ?? {} });
+            if (f)
+                out += `<g transform="${boxTransform(f, sideOf(kind), turnOf(sticker), v.project)}">${markup}</g>`;
+        }
+    }
+    for (const decal of skin.decals ?? []) {
+        const blend = decal.blend === "multiply" ? ` style="mix-blend-mode:multiply"` : "";
+        for (const sticker of selectedStickers(decal.select)) {
+            const f = placed(sticker, decal.onlyRegular ?? true);
+            if (!f)
+                continue;
+            const side = sideOf(kindOfSticker(sticker));
+            const offset = [((decal.offset?.[0] ?? 0) * side) / 2, ((decal.offset?.[1] ?? 0) * side) / 2];
+            const t = boxTransform(f, side * decal.size, turnOf(sticker), v.project, offset, decal.rotate ?? 0);
+            out += `<image href="${attr(imageUrl(decal.image))}" width="1" height="1" preserveAspectRatio="xMidYMid meet" transform="${t}"${blend}/>`;
+        }
+    }
+    const [x, y, w, h] = v.box.map(r3);
+    const height = Math.round((size * h) / w);
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${x} ${y} ${w} ${h}" width="${size}" height="${height}">${out}</svg>`;
+}

package/lbl/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Beginner layer-by-layer: cross, four first-layer corners, four middle-layer
+ * edges, last layer orientation in two halves, then corner and edge
+ * permutation. Colour and orientation neutral like every cubecore method.
+ */
+import { type Frame, type Mask, type MaskRule, type Method } from "../core/index.js";
+export declare const LBL: Method;
+export type LblMask = "cross" | "first-layer" | "second-layer";
+export declare const LBL_MASKS: Record<LblMask, MaskRule>;
+export declare const lblMask: (name: LblMask, frame?: Frame) => Mask;

package/lbl/index.js

@@ -0,0 +1,31 @@
+/**
+ * Beginner layer-by-layer: cross, four first-layer corners, four middle-layer
+ * edges, last layer orientation in two halves, then corner and edge
+ * permutation. Colour and orientation neutral like every cubecore method.
+ */
+import { IDENTITY_FRAME, buildMask, checks as C, countedStages } from "../core/index.js";
+export const LBL = {
+    id: "lbl",
+    name: "Layer by layer",
+    stages: [
+        { id: "cross", label: "Cross", done: C.crossSolved },
+        ...countedStages("corner", "Corner", (s) => C.SLOTS.filter((x) => C.slotCornerSolved(s, x)), C.crossSolved),
+        ...countedStages("edge", "Edge", (s) => C.SLOTS.filter((x) => C.slotEdgeSolved(s, x)), C.firstLayerSolved),
+        {
+            id: "oll-1",
+            label: "Orient (1st half)",
+            done: (s) => C.f2lSolved(s) && (C.topCornersOriented(s) || C.topEdgesOriented(s)),
+            detail: (s) => (C.topEdgesOriented(s) ? "edges" : "corners"),
+        },
+        { id: "oll-2", label: "Orient (2nd half)", done: (s) => C.f2lSolved(s) && C.topOriented(s) },
+        { id: "pll-corners", label: "Permute corners", done: (s) => C.f2lSolved(s) && C.topOriented(s) && C.llCornersPermuted(s) },
+        { id: "pll", label: "Permute edges", done: C.solvedUpToAuf },
+        { id: "auf", label: "AUF", done: C.isSolved },
+    ],
+};
+export const LBL_MASKS = {
+    cross: (f, c) => (c.kind === "center" || (c.kind === "edge" && c.pos[1] === -1) ? "regular" : "ignored"),
+    "first-layer": (f, c) => (c.kind === "center" || c.pos[1] === -1 ? "regular" : "ignored"),
+    "second-layer": (f, c) => (c.kind === "center" || c.pos[1] === 0 ? "regular" : c.pos[1] === -1 ? "dim" : "ignored"),
+};
+export const lblMask = (name, frame = IDENTITY_FRAME) => buildMask(LBL_MASKS[name], frame);

package/methods/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * All methods together — for apps that let the user pick a method, or show
+ * every analysis side by side. Apps using a single method import its own
+ * package (@cubecore/cfop…) and skip the rest.
+ */
+import { type Frame, type Mask, type MaskRule, type Method } from "../core/index.js";
+import { CFOP } from "../cfop/index.js";
+import { LBL } from "../lbl/index.js";
+import { PETRUS } from "../petrus/index.js";
+import { ROUX } from "../roux/index.js";
+import { ZZ } from "../zz/index.js";
+export { CFOP, LBL, PETRUS, ROUX, ZZ };
+export declare const METHODS: readonly Method[];
+export declare const methodById: (id: string) => Method | undefined;
+/** Every method's masks, keyed "method:name" (e.g. "cfop:oll", "roux:cmll"). */
+export declare const METHOD_MASKS: Readonly<Record<string, MaskRule>>;
+/** All mask names: the generic presets ("full", "first-layer", "ll") and every "method:name". */
+export declare const MASK_NAMES: readonly string[];
+/** A mask by name from `MASK_NAMES`, for a cube held in `frame`. */
+export declare function maskByName(name: string, frame?: Frame): Mask;

package/methods/index.js

@@ -0,0 +1,33 @@
+/**
+ * All methods together — for apps that let the user pick a method, or show
+ * every analysis side by side. Apps using a single method import its own
+ * package (@cubecore/cfop…) and skip the rest.
+ */
+import { IDENTITY_FRAME, MASK_PRESETS, buildMask, presetMask } from "../core/index.js";
+import { CFOP, CFOP_MASKS } from "../cfop/index.js";
+import { LBL, LBL_MASKS } from "../lbl/index.js";
+import { PETRUS, PETRUS_MASKS } from "../petrus/index.js";
+import { ROUX, ROUX_MASKS } from "../roux/index.js";
+import { ZZ, ZZ_MASKS } from "../zz/index.js";
+export { CFOP, LBL, PETRUS, ROUX, ZZ };
+export const METHODS = [CFOP, LBL, ROUX, ZZ, PETRUS];
+export const methodById = (id) => METHODS.find((m) => m.id === id);
+/** Every method's masks, keyed "method:name" (e.g. "cfop:oll", "roux:cmll"). */
+export const METHOD_MASKS = Object.fromEntries([
+    ["cfop", CFOP_MASKS],
+    ["lbl", LBL_MASKS],
+    ["roux", ROUX_MASKS],
+    ["zz", ZZ_MASKS],
+    ["petrus", PETRUS_MASKS],
+].flatMap(([method, masks]) => Object.entries(masks).map(([name, rule]) => [`${method}:${name}`, rule])));
+/** All mask names: the generic presets ("full", "first-layer", "ll") and every "method:name". */
+export const MASK_NAMES = [...MASK_PRESETS, ...Object.keys(METHOD_MASKS)];
+/** A mask by name from `MASK_NAMES`, for a cube held in `frame`. */
+export function maskByName(name, frame = IDENTITY_FRAME) {
+    const rule = METHOD_MASKS[name];
+    if (rule)
+        return buildMask(rule, frame);
+    if (MASK_PRESETS.includes(name))
+        return presetMask(name, frame);
+    throw new Error(`Unknown mask "${name}"`);
+}

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@wodzik/cubecore",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0",
+  "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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wodzik/cubecore.git"
+  },
+  "homepage": "https://github.com/wodzik/cubecore#readme",
+  "bugs": "https://github.com/wodzik/cubecore/issues",
+  "keywords": [
+    "rubiks-cube",
+    "speedcubing",
+    "cube",
+    "smart-cube",
+    "bluetooth",
+    "solver",
+    "scramble",
+    "three",
+    "web-components",
+    "react",
+    "cfop",
+    "roux",
+    "zz"
+  ],
+  "type": "module",
+  "exports": {
+    "./skin": {
+      "types": "./skin/index.d.ts",
+      "import": "./skin/index.js"
+    },
+    "./methods": {
+      "types": "./methods/index.d.ts",
+      "import": "./methods/index.js"
+    },
+    "./solve": {
+      "types": "./solve/index.d.ts",
+      "import": "./solve/index.js"
+    },
+    "./core": {
+      "types": "./core/index.d.ts",
+      "import": "./core/index.js"
+    },
+    "./bld": {
+      "types": "./bld/index.d.ts",
+      "import": "./bld/index.js"
+    },
+    "./lbl": {
+      "types": "./lbl/index.d.ts",
+      "import": "./lbl/index.js"
+    },
+    "./element": {
+      "types": "./element/index.d.ts",
+      "import": "./element/index.js"
+    },
+    "./render": {
+      "types": "./render/index.d.ts",
+      "import": "./render/index.js"
+    },
+    "./image": {
+      "types": "./image/index.d.ts",
+      "import": "./image/index.js"
+    },
+    "./petrus": {
+      "types": "./petrus/index.d.ts",
+      "import": "./petrus/index.js"
+    },
+    "./zz": {
+      "types": "./zz/index.d.ts",
+      "import": "./zz/index.js"
+    },
+    "./bluetooth": {
+      "types": "./bluetooth/index.d.ts",
+      "import": "./bluetooth/index.js"
+    },
+    "./analyze": {
+      "types": "./analyze/index.d.ts",
+      "import": "./analyze/index.js"
+    },
+    "./cfop": {
+      "types": "./cfop/index.d.ts",
+      "import": "./cfop/index.js"
+    },
+    "./timeline": {
+      "types": "./timeline/index.d.ts",
+      "import": "./timeline/index.js"
+    },
+    "./react": {
+      "types": "./react/index.d.ts",
+      "import": "./react/index.js"
+    },
+    "./roux": {
+      "types": "./roux/index.d.ts",
+      "import": "./roux/index.js"
+    },
+    "./image/png-node": {
+      "types": "./image/png-node.d.ts",
+      "import": "./image/png-node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./element/index.js",
+    "./react/index.js"
+  ],
+  "dependencies": {
+    "aes-js": "^3.1.2",
+    "lz-string": "^1.5.0",
+    "rxjs": "^7.8.2",
+    "@types/web-bluetooth": "^0.0.21"
+  },
+  "peerDependencies": {
+    "three": ">=0.160",
+    "react": ">=18",
+    "@resvg/resvg-js": ">=2"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@resvg/resvg-js": {
+      "optional": true
+    }
+  }
+}

package/petrus/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Petrus — 2×2×2 block (canonical: at D-B-L), extended to 2×2×3 along the
+ * left-bottom, EO, F2L, last layer. Checks, method and masks; colour neutral.
+ */
+import { type Frame, type Mask, type MaskRule, type Method, type State } from "../core/index.js";
+export declare const block222Solved: (s: State) => boolean;
+export declare const block223Solved: (s: State) => boolean;
+export declare const PETRUS: Method;
+export type PetrusMask = "2x2x2" | "2x2x3";
+export declare const PETRUS_MASKS: Record<PetrusMask, MaskRule>;
+export declare const petrusMask: (name: PetrusMask, frame?: Frame) => Mask;

package/petrus/index.js

@@ -0,0 +1,27 @@
+/**
+ * Petrus — 2×2×2 block (canonical: at D-B-L), extended to 2×2×3 along the
+ * left-bottom, EO, F2L, last layer. Checks, method and masks; colour neutral.
+ */
+import { IDENTITY_FRAME, LAST_LAYER_STAGES, buildMask, checks as C } from "../core/index.js";
+const inBlock222 = (p) => p[0] <= 0 && p[1] <= 0 && p[2] <= 0;
+const inBlock223 = (p) => p[0] <= 0 && p[1] <= 0;
+const BLOCK_222 = C.cubiesWhere((p) => inBlock222(p) && p.some((v) => v !== 0));
+const BLOCK_223 = C.cubiesWhere((p) => inBlock223(p) && p.some((v) => v !== 0));
+export const block222Solved = (s) => C.allSolved(s, BLOCK_222);
+export const block223Solved = (s) => C.allSolved(s, BLOCK_223);
+export const PETRUS = {
+    id: "petrus",
+    name: "Petrus",
+    stages: [
+        { id: "2x2x2", label: "2×2×2 block", done: block222Solved },
+        { id: "2x2x3", label: "2×2×3 block", done: block223Solved },
+        { id: "eo", label: "EO", done: (s) => block223Solved(s) && C.edgesOrientedFB(s) },
+        { id: "f2l", label: "F2L", done: C.f2lSolved },
+        ...LAST_LAYER_STAGES,
+    ],
+};
+export const PETRUS_MASKS = {
+    "2x2x2": (f, c) => (c.kind === "center" || inBlock222(c.pos) ? "regular" : "ignored"),
+    "2x2x3": (f, c) => (c.kind === "center" || inBlock223(c.pos) ? "regular" : "ignored"),
+};
+export const petrusMask = (name, frame = IDENTITY_FRAME) => buildMask(PETRUS_MASKS[name], frame);

package/react/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * React bindings — thin wrappers around the cubecore elements plus hooks for
+ * a smart cube and the solver worker. No styling opinions: the elements'
+ * CSS variables and ::part() work as usual (className / style pass through).
+ *
+ *   <CubePlayer alg="R U R' U'" progress segmentLabels onEnded={…} ref={player} />
+ *   const cube = useSmartCube();   // cube.connect() / cube.simulate(); cube.state, cube.session
+ *   <CubePlayer live={cube.session} autoSkin />
+ *   <CubeScramble scramble={moves} source={cube.session} editable onComplete={start} />
+ *   <CubeAlgPractice alg="R U R' U R U2 R'" source={cube.session} reveal="done" onComplete={…} />
+ *
+ * Works with React 18 and 19: attributes are passed as attributes (booleans
+ * only when true), objects are set as properties from effects, events are
+ * listened to on the element.
+ */
+import { type CSSProperties, type ReactNode } from "react";
+import type { Mask, Method, Move, State } from "../core/index.js";
+import type { BldMessages, CubeBld as CubeBldElement, CubeAlg as CubeAlgElement, CubeAlgPractice as CubeAlgPracticeElement, CubePlayer as CubePlayerElement, CubeScramble as CubeScrambleElement, ArrowTarget, LiveSource, MoveSource, PracticeMessages, ScrambleMessages } from "../element/index.js";
+import type { SmartCubeSession } from "../bluetooth/index.js";
+import type { Skin } from "../skin/index.js";
+import type { SolverClient } from "../solve/index.js";
+import type { Recording, Segment } from "../timeline/index.js";
+import "../element/index.js";
+type Handler<T = void> = (detail: T) => void;
+export interface CubePlayerProps {
+    alg?: string;
+    setup?: string;
+    anchor?: "start" | "end";
+    tempo?: number;
+    skin?: Skin | string;
+    theme?: "light" | "dark" | "auto";
+    visualization?: "3d" | "net" | "top" | "iso";
+    backView?: "none" | "side-by-side" | "top-right";
+    controls?: "default" | "none";
+    progress?: boolean;
+    markers?: boolean;
+    segmentLabels?: boolean;
+    tooltips?: boolean;
+    maxPause?: number;
+    recording?: Recording | null;
+    method?: Method | null;
+    segments?: Segment[] | null;
+    mask?: Mask | null;
+    formatSegment?: (s: Segment) => string;
+    /** Follow a smart cube live (a SmartCubeSession). */
+    live?: LiveSource | null;
+    /** With `live`: use the cube's suggested skin. */
+    autoSkin?: boolean;
+    onTimeUpdate?: Handler<{
+        time: number;
+        duration: number;
+        applied: number;
+    }>;
+    onPlay?: Handler;
+    onPause?: Handler;
+    onEnded?: Handler;
+    onSegmentChange?: Handler<{
+        index: number;
+        segment: Segment;
+    }>;
+    onError?: Handler<{
+        message: string;
+    }>;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** e.g. your own controls with slot="controls". */
+    children?: ReactNode;
+}
+export declare const CubePlayer: import("react").ForwardRefExoticComponent<CubePlayerProps & import("react").RefAttributes<CubePlayerElement | null>>;
+export interface CubeScrambleProps {
+    scramble: string | readonly Move[];
+    /** Follow a smart cube (a SmartCubeSession). */
+    source?: MoveSource | null;
+    /** Arrows on a player's 3D cube for the next turn (with `player`). */
+    arrows?: boolean;
+    /** The <CubePlayer> ref the arrows go to. */
+    player?: {
+        current: ArrowTarget | null;
+    };
+    /** "box" (ribbon along the faces, default) or "circle" (an arc). Colours: --cc-arrow, --cc-arrow-undo, --cc-arrow-wrong-way. */
+    arrowShape?: "box" | "circle";
+    /** Show an input to paste or type your own scramble (fires onChange). */
+    editable?: boolean;
+    messages?: Partial<ScrambleMessages>;
+    onProgress?: Handler<unknown>;
+    onComplete?: Handler<unknown>;
+    onChange?: Handler<{
+        moves: Move[];
+        text: string;
+    }>;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare const CubeScramble: import("react").ForwardRefExoticComponent<CubeScrambleProps & import("react").RefAttributes<CubeScrambleElement | null>>;
+export interface CubeAlgPracticeProps {
+    alg: string | readonly Move[];
+    /** Follow a smart cube (a SmartCubeSession); tracking starts from its current state. */
+    source?: MoveSource | null;
+    /** Arrows on a player's 3D cube for the next turn (with `player`). */
+    arrows?: boolean;
+    /** The <CubePlayer> ref the arrows go to. */
+    player?: {
+        current: ArrowTarget | null;
+    };
+    /** "box" (ribbon along the faces, default) or "circle" (an arc). Colours: --cc-arrow, --cc-arrow-undo, --cc-arrow-wrong-way. */
+    arrowShape?: "box" | "circle";
+    /** "all" every move shown, "done" dots until done (default), "none" dots only. */
+    reveal?: "all" | "done" | "none";
+    /** Show the next move after a slip (default true). */
+    hintOnMistake?: boolean;
+    /** "none" hides the built-in Hint / Show / Restart buttons. */
+    controls?: "none";
+    /** Hide the whole built-in view (build your own from onProgress). */
+    headless?: boolean;
+    messages?: Partial<PracticeMessages>;
+    onProgress?: Handler<unknown>;
+    onMistake?: Handler<unknown>;
+    onComplete?: Handler<unknown>;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+export declare const CubeAlgPractice: import("react").ForwardRefExoticComponent<CubeAlgPracticeProps & import("react").RefAttributes<CubeAlgPracticeElement | null>>;
+export interface CubeBldProps {
+    /** Follow a smart cube: memo of it as it is now, then its execution letter by letter. */
+    source?: MoveSource | null;
+    /** "ruwix" (default) or "speffz". */
+    scheme?: "ruwix" | "speffz";
+    /** How the cube is held, as rotations (e.g. "x2 y'" = yellow top, orange front). */
+    rotation?: string;
+    /** Letters still to do: "all" shown (default), "done" hidden until done, "none" hidden. */
+    reveal?: "all" | "done" | "none";
+    headless?: boolean;
+    messages?: Partial<BldMessages>;
+    onProgress?: Handler<unknown>;
+    onLetter?: Handler<unknown>;
+    onWrong?: Handler<unknown>;
+    onComplete?: Handler<unknown>;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+export declare const CubeBld: import("react").ForwardRefExoticComponent<CubeBldProps & import("react").RefAttributes<CubeBldElement | null>>;
+export interface CubeAlgProps {
+    /** Id of a <cube-player>, or pass `player`. */
+    for?: string;
+    player?: {
+        current: CubePlayerElement | null;
+    };
+    alg?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare const CubeAlg: import("react").ForwardRefExoticComponent<CubeAlgProps & import("react").RefAttributes<CubeAlgElement | null>>;
+export interface SmartCube {
+    session: SmartCubeSession | null;
+    state: State | null;
+    battery: number | null;
+    connected: boolean;
+    error: string | null;
+    /** Ask the browser for a cube (call from a click). */
+    connect(): Promise<void>;
+    /** A simulated cube (same events) — for development without hardware. */
+    simulate(): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/** A smart cube as React state: the session, its state after every move, battery, connection. */
+export declare function useSmartCube(): SmartCube;
+/** The solver worker for this component's lifetime (null until created, e.g. during SSR). */
+export declare function useSolverWorker(url?: string | URL): SolverClient | null;
+export {};