@wodzik/cubecore 0.1.0

package/render/build/tiles.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tile and piece geometry for a skin — everything the renderer needs to
+ * build one cubie, as cached three.js geometries. Pure construction, no
+ * scene state: swap this module (or wrap it) to give a skin different solids.
+ *
+ * Per facelet POSITION, a tile's shape only depends on its piece kind and
+ * where it sits (corner / edge / centre, which way the centre is), so tiles
+ * are built per position and cached per distinct shape. Anything that must
+ * follow a particular STICKER (logos, holes, charging ports) is an
+ * attachment — see attachments.ts.
+ */
+import { BufferGeometry } from "three";
+import { type PieceKind, type Skin } from "../../skin/index.js";
+import { type TileSolid } from "../tile.js";
+export interface TileKit {
+    /** Tile side (cubie units) — the usual one; `sideOf` per piece kind. */
+    side: number;
+    /** Height of a tile's top above the cubie face — the usual one; `thicknessOf` per piece kind. */
+    thickness: number;
+    sideOf(kind: PieceKind): number;
+    thicknessOf(kind: PieceKind): number;
+    /** Distance from a cubie's centre to the plane its tiles sit on. */
+    faceOffset: number;
+    /** The cubie body (a rounded box, or the small core when pieces are shaped). */
+    body: BufferGeometry;
+    /** A centre cubie's body: smaller when the centre cap is domed, so it stays under the cap's lowered corners. */
+    centerBody: BufferGeometry;
+    /**
+     * Shaped pieces: the mechanism in the middle of the cube (a dark ball round
+     * the one cell with no cubie), so gaps never show through to the far side.
+     * Null otherwise.
+     */
+    mechanism: BufferGeometry | null;
+    /** The tile at facelet position `fi`, in its face's local frame (x = a, y = b, z = outward). */
+    tile(fi: number): BufferGeometry;
+    /** The sticker lying on the tile at `fi` (`stickers.overlay`), in the tile's frame, or null. */
+    overlay(fi: number): BufferGeometry | null;
+    /** With `overlay.pedestal`: the flat print on top of the (black) sticker pedestal at `fi`, or null. */
+    overlayCap(fi: number): BufferGeometry | null;
+    /** The piece's plastic under that tile (`skin.pieces`), or null. */
+    skirt(fi: number): BufferGeometry | null;
+    /** The flat floating "back" sticker for position `fi`. */
+    hint(fi: number): BufferGeometry;
+    dispose(): void;
+}
+export declare function tileKit(skin: Skin): TileKit;
+/** three.js geometry of a swept solid (see tile.ts): sides plus a triangulated flat top, if any. */
+export declare function solidToGeometry(solid: TileSolid): BufferGeometry;

package/render/build/tiles.js

@@ -0,0 +1,194 @@
+/**
+ * Tile and piece geometry for a skin — everything the renderer needs to
+ * build one cubie, as cached three.js geometries. Pure construction, no
+ * scene state: swap this module (or wrap it) to give a skin different solids.
+ *
+ * Per facelet POSITION, a tile's shape only depends on its piece kind and
+ * where it sits (corner / edge / centre, which way the centre is), so tiles
+ * are built per position and cached per distinct shape. Anything that must
+ * follow a particular STICKER (logos, holes, charging ports) is an
+ * attachment — see attachments.ts.
+ */
+import { BufferGeometry, Float32BufferAttribute, Shape, ShapeGeometry, ShapeUtils, SphereGeometry, Vector2 } from "three";
+import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";
+import { SVGLoader } from "three/examples/jsm/loaders/SVGLoader.js";
+import { overlayOutline, reachEdge, roundedOutline, stickerLayout, stickerlessOutline, tileSize, tileThickness } from "../../skin/index.js";
+import { applyDome, cornerRound, densify, planeCut, skirtSolid, tileSolid } from "../tile.js";
+/** Default radius of the mechanism ball (cubie units). */
+const MECHANISM = 1.15;
+export function tileKit(skin) {
+    const size = skin.cubieSize;
+    const inset = skin.bodyInset ?? 0;
+    const side = skin.stickers.size * size;
+    const thickness = skin.stickers.thickness ?? 0;
+    const sideOf = (kind) => tileSize(skin, kind) * size;
+    const thicknessOf = (kind) => tileThickness(skin, kind);
+    const faceOffset = size / 2 + 0.002;
+    const edge = faceOffset;
+    const shape = skin.stickers.shape ?? {
+        corner: { inner: skin.stickers.radius, outer: skin.stickers.radius },
+        edge: { inner: skin.stickers.radius, outer: skin.stickers.radius },
+        center: skin.stickers.radius,
+    };
+    // With shaped pieces the box is only the hidden core; the visible plastic is the skirts under the tiles.
+    const bodySize = skin.pieces ? skin.pieces.core * size : size - 2 * inset;
+    const box = (s) => new RoundedBoxGeometry(s, s, s, 3, Math.min(skin.cubieRadius * size, s / 2));
+    const body = box(bodySize);
+    const dome = skin.stickers.kinds?.center?.dome;
+    // The core's top must stay under the dome's lowest point (its corners, `drop` below the face).
+    const centerBody = skin.pieces && dome ? box(Math.min(bodySize, size - 2 * (dome.drop + inset + 0.01))) : body;
+    // A ball: the same from every side, so layers turn round it; only its dark surface shows deep in the gaps.
+    const mechanism = skin.pieces ? new SphereGeometry(skin.pieces.mechanism ?? MECHANISM, 48, 32) : null;
+    // Corner-cutting relief: the tile corner(s) next to the face centre (corner pieces; edges if asked).
+    const reliefAt = (layout, s) => {
+        const relief = skin.pieces?.relief;
+        if (!relief)
+            return [];
+        const h = s / 2, su = -Math.sign(layout.u), sv = -Math.sign(layout.v);
+        if (layout.kind === "corner")
+            return [[su * h, sv * h]];
+        if (layout.kind === "edge" && relief.edges)
+            return layout.u ? [[su * h, h], [su * h, -h]] : [[h, sv * h], [-h, sv * h]];
+        return [];
+    };
+    // Cube corners rounder than the edges: a ball at each corner (in a corner tile's frame).
+    const roundCorner = (solid, layout) => {
+        const R = skin.stickers.cornerRound;
+        if (!R || layout.kind !== "corner")
+            return solid;
+        const top = thicknessOf("corner");
+        return cornerRound(solid, [layout.u * (edge - R), layout.v * (edge - R), top - R], [layout.u, layout.v, 1], R);
+    };
+    const outlineFor = (fi) => {
+        const layout = stickerLayout(fi, shape);
+        const path = skin.stickers.paths?.[layout.kind];
+        const fill = skin.stickers.fillOuter === true;
+        const s = sideOf(layout.kind), t = thicknessOf(layout.kind);
+        const outline = path
+            ? fill
+                ? reachEdge(pathOutline(path, s, layout.pathQuarters), layout, s / 2, edge)
+                : pathOutline(path, s, layout.pathQuarters)
+            : fill
+                ? stickerlessOutline(layout, s, edge)
+                : roundedOutline(s, layout.radii);
+        const mitre = fill ? { u: layout.u, v: layout.v, edge, ramp: Math.max(t * 4, 0.03) } : null;
+        const key = (path ? `p|${layout.kind}|${layout.pathQuarters}` : `r|${layout.radii.join(",")}`) + `${fill ? `|${layout.u},${layout.v}` : ""}|${s}|${t}`;
+        return { outline, mitre, key, layout, thickness: t, side: s };
+    };
+    const cache = new Map();
+    const cached = (key, make) => {
+        let g = cache.get(key);
+        if (!g)
+            cache.set(key, (g = make()));
+        return g;
+    };
+    return {
+        side,
+        thickness,
+        sideOf,
+        // Where things on a sticker sit: on the tile, or on the sticker lying on it.
+        thicknessOf: (kind) => thicknessOf(kind) + (skin.stickers.overlay?.thickness ?? 0),
+        faceOffset,
+        body,
+        centerBody,
+        mechanism,
+        tile(fi) {
+            const { outline, mitre, key, thickness: t, layout, side: s } = outlineFor(fi);
+            const relief = skin.pieces?.relief;
+            const at = relief?.tile !== undefined ? reliefAt(layout, s) : [];
+            const undercut = relief && at.length ? { at, r: relief.start ?? 0, z: relief.tile } : undefined;
+            const kind = skin.stickers.kinds?.[layout.kind];
+            const bevel = Math.min(kind?.bevel ?? skin.stickers.bevel ?? 0, t);
+            const dome = kind?.dome;
+            // A domed tile reaches deeper, so its lowered corners stay above its bottom.
+            const sink = inset + 0.002 + (dome ? dome.drop : 0);
+            return cached(`tile|${key}|${bevel}|${dome ? `${dome.flat},${dome.drop}` : ""}|${undercut ? "uc" : ""}`, () => t > 0
+                ? solidToGeometry(((solid) => roundCorner(dome ? applyDome(solid, dome, sink) : solid, layout))(tileSolid(dome || undercut || (skin.stickers.cornerRound && layout.kind === "corner") ? densify(outline, undercut ? 192 : 128) : outline, { thickness: t, bevel, segments: 4, sink, edgeRadius: skin.stickers.edgeRadius ?? 0, undercut }, mitre)))
+                : new ShapeGeometry(new Shape(outline.map(([x, y]) => new Vector2(x, y)))));
+        },
+        overlay(fi) {
+            const ov = skin.stickers.overlay;
+            if (!ov)
+                return null;
+            const { layout } = outlineFor(fi);
+            const base = thicknessOf(layout.kind);
+            return cached(`overlay|${fi}`, () => {
+                const g = solidToGeometry(tileSolid(overlayOutline(fi, ov), { thickness: ov.thickness, bevel: Math.min(ov.bevel ?? 0.004, ov.thickness), segments: 2, sink: 0.002 }, null));
+                g.translate(0, 0, base);
+                return g;
+            });
+        },
+        overlayCap(fi) {
+            const ov = skin.stickers.overlay;
+            if (!ov?.pedestal)
+                return null;
+            const { layout } = outlineFor(fi);
+            const z = thicknessOf(layout.kind) + ov.thickness + 0.0008;
+            return cached(`cap|${fi}`, () => {
+                const pts = overlayOutline(fi, ov, 8, Math.min(ov.bevel ?? 0.004, ov.thickness));
+                const g = new ShapeGeometry(new Shape(pts.map(([x, y]) => new Vector2(x, y))));
+                g.translate(0, 0, z);
+                return g;
+            });
+        },
+        skirt(fi) {
+            const pieces = skin.pieces;
+            if (!pieces)
+                return null;
+            const { outline, mitre, key, layout, side: s } = outlineFor(fi);
+            // Solid pieces: through the whole cubie. The walls lean in, so where two meet inside the
+            // piece the one from the nearer tile is outermost — the colours split on the diagonals.
+            const depth = pieces.fill === "solid" ? size : pieces.depth;
+            const at = reliefAt(layout, s);
+            const relief = pieces.relief && at.length ? { at, ...pieces.relief } : undefined;
+            // The inside is cut flat, square to the piece's direction from the cube's centre and touching the mechanism
+            // ball: a corner's inner point becomes a small triangle, an edge's inner edge a flat strip, a centre's back flat.
+            // (In this tile's frame the cube's centre is one step in along the face normal and −u / −v across.)
+            const ball = pieces.mechanism ?? MECHANISM;
+            const centre = [-layout.u, -layout.v, -1 - faceOffset];
+            const len = Math.hypot(layout.u, layout.v, 1);
+            const dir = [layout.u / len, layout.v / len, 1 / len];
+            return cached(`skirt|${key}|${depth}`, () => solidToGeometry(roundCorner(planeCut(skirtSolid(densify(outline, 192), { top: inset + 0.002, depth, taper: pieces.taper, wall: pieces.wall, relief, steps: 32 }, mitre), centre, dir, ball), layout)));
+        },
+        hint(fi) {
+            const { layout, side: s } = outlineFor(fi);
+            return cached(`hint|${layout.radii.join(",")}|${s}`, () => new ShapeGeometry(new Shape(roundedOutline(s * 0.92, layout.radii).map(([x, y]) => new Vector2(x, y)))));
+        },
+        dispose() {
+            body.dispose();
+            for (const g of cache.values())
+                g.dispose();
+            cache.clear();
+        },
+    };
+}
+/** three.js geometry of a swept solid (see tile.ts): sides plus a triangulated flat top, if any. */
+export function solidToGeometry(solid) {
+    const cap = solid.topRing.length ? ShapeUtils.triangulateShape(solid.topRing.map(([x, y]) => new Vector2(x, y)), []) : [];
+    const index = [...solid.sides];
+    for (const [a, b, c] of cap)
+        index.push(solid.topStart + a, solid.topStart + b, solid.topStart + c);
+    const g = new BufferGeometry();
+    g.setAttribute("position", new Float32BufferAttribute(solid.positions, 3));
+    g.setAttribute("normal", new Float32BufferAttribute(solid.normals, 3));
+    g.setIndex(index);
+    g.computeBoundingSphere();
+    return g;
+}
+/** Outline of a custom SVG path (0..1 box, y down) scaled to `side`, rotated by `quarters` CCW, centred. */
+function pathOutline(d, side, quarters) {
+    const data = new SVGLoader().parse(`<svg xmlns="http://www.w3.org/2000/svg"><path d="${d}"/></svg>`);
+    const shape = SVGLoader.createShapes(data.paths[0])[0];
+    if (!shape)
+        throw new Error("Sticker path has no closed shape");
+    const pts = shape.getPoints(8).map((p) => [(p.x - 0.5) * side, (0.5 - p.y) * side]);
+    const c = Math.cos((quarters * Math.PI) / 2), s = Math.sin((quarters * Math.PI) / 2);
+    const rotated = pts.map(([x, y]) => [Math.round((x * c - y * s) * 1e6) / 1e6, Math.round((x * s + y * c) * 1e6) / 1e6]);
+    // Keep the outline counter-clockwise (y flip reversed SVG's winding).
+    let area = 0;
+    for (let i = 0; i < rotated.length; i++) {
+        const [x1, y1] = rotated[i], [x2, y2] = rotated[(i + 1) % rotated.length];
+        area += x1 * y2 - x2 * y1;
+    }
+    return area < 0 ? rotated.reverse() : rotated;
+}

package/render/gltf.d.ts

@@ -0,0 +1,10 @@
+/**
+ * glTF templates of a skin's pieces — the built-in geometry written out in
+ * the piece-model convention (pieceModels.ts), as a starting point for model
+ * authors (open in Blender, reshape, export as GLB) and as ready-made
+ * models. Materials: `body` and `sticker-U` / `sticker-F` / `sticker-R`.
+ */
+import type { Skin } from "../skin/index.js";
+import { type ModelKind } from "./pieceModels.js";
+/** The skin's corner, edge and centre as .gltf documents (JSON strings) in the piece-model convention. */
+export declare function pieceTemplates(skin: Skin): Record<ModelKind, string>;

package/render/gltf.js

@@ -0,0 +1,106 @@
+/**
+ * glTF templates of a skin's pieces — the built-in geometry written out in
+ * the piece-model convention (pieceModels.ts), as a starting point for model
+ * authors (open in Blender, reshape, export as GLB) and as ready-made
+ * models. Materials: `body` and `sticker-U` / `sticker-F` / `sticker-R`.
+ */
+import { Matrix4, Vector3 } from "three";
+import { FACELETS, FACE_BASIS, faceletAt, FACE_NORMAL } from "../core/index.js";
+import { tileKit } from "./build/tiles.js";
+import { CANONICAL } from "./pieceModels.js";
+function toBase64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+const hexToLinear = (hex) => {
+    const c = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+    return c.map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+};
+/** A minimal glTF 2.0 document (embedded buffer) with one node per part. */
+function writeGltf(parts, materials) {
+    const chunks = [];
+    let offset = 0;
+    const bufferViews = [];
+    const accessors = [];
+    const push = (data, target) => {
+        const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        const pad = (4 - (offset % 4)) % 4;
+        if (pad) {
+            chunks.push(new Uint8Array(pad));
+            offset += pad;
+        }
+        bufferViews.push({ buffer: 0, byteOffset: offset, byteLength: bytes.length, target });
+        chunks.push(bytes);
+        offset += bytes.length;
+        return bufferViews.length - 1;
+    };
+    const materialNames = Object.keys(materials);
+    const meshes = parts.map((p) => {
+        const pos = p.geometry.getAttribute("position").array;
+        const nor = p.geometry.getAttribute("normal").array;
+        const index = p.geometry.getIndex()?.array ?? Uint32Array.from({ length: pos.length / 3 }, (_, i) => i);
+        const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        for (let i = 0; i < pos.length; i += 3)
+            for (let k = 0; k < 3; k++) {
+                min[k] = Math.min(min[k], pos[i + k]);
+                max[k] = Math.max(max[k], pos[i + k]);
+            }
+        const count = pos.length / 3;
+        accessors.push({ bufferView: push(Float32Array.from(pos), 34962), componentType: 5126, count, type: "VEC3", min, max });
+        const posAcc = accessors.length - 1;
+        accessors.push({ bufferView: push(Float32Array.from(nor), 34962), componentType: 5126, count, type: "VEC3" });
+        const norAcc = accessors.length - 1;
+        accessors.push({ bufferView: push(Uint32Array.from(index), 34963), componentType: 5125, count: index.length, type: "SCALAR" });
+        return { primitives: [{ attributes: { POSITION: posAcc, NORMAL: norAcc }, indices: accessors.length - 1, material: materialNames.indexOf(p.material) }] };
+    });
+    const buffer = new Uint8Array(offset);
+    let at = 0;
+    for (const c of chunks) {
+        buffer.set(c, at);
+        at += c.length;
+    }
+    return JSON.stringify({
+        asset: { version: "2.0", generator: "cubecore piece templates" },
+        scene: 0,
+        scenes: [{ nodes: parts.map((_, i) => i) }],
+        nodes: parts.map((p, i) => ({ mesh: i, matrix: p.matrix.elements.map((v) => Math.round(v * 1e6) / 1e6 + 0) })),
+        meshes,
+        materials: materialNames.map((name) => ({
+            name,
+            pbrMetallicRoughness: { baseColorFactor: [...hexToLinear(materials[name].color), 1], metallicFactor: 0, roughnessFactor: materials[name].roughness },
+        })),
+        accessors,
+        bufferViews,
+        buffers: [{ byteLength: buffer.length, uri: `data:application/octet-stream;base64,${toBase64(buffer)}` }],
+    });
+}
+/** The skin's corner, edge and centre as .gltf documents (JSON strings) in the piece-model convention. */
+export function pieceTemplates(skin) {
+    const kit = tileKit(skin);
+    const roughness = skin.stickers.roughness ?? 0.4;
+    const colors = skin.stickers.colors;
+    const out = {};
+    for (const kind of ["corner", "edge", "center"]) {
+        const { pos, faces } = CANONICAL[kind];
+        const parts = [{ geometry: kit.body, matrix: new Matrix4(), material: "body" }];
+        for (const face of faces) {
+            const fi = faceletAt(pos, FACE_NORMAL[face]);
+            const f = FACELETS[fi];
+            const { a, b, n } = FACE_BASIS[f.face];
+            const m = new Matrix4().makeBasis(new Vector3(...a), new Vector3(...b), new Vector3(...n));
+            m.setPosition(new Vector3(...f.pos).sub(new Vector3(...pos)).addScaledVector(new Vector3(...n), kit.faceOffset));
+            parts.push({ geometry: kit.tile(fi), matrix: m, material: `sticker-${face}` });
+            const skirt = kit.skirt(fi);
+            if (skirt)
+                parts.push({ geometry: skirt, matrix: m.clone(), material: "body" });
+        }
+        const mats = { body: { color: skin.body, roughness: 0.85 } };
+        for (const face of faces)
+            mats[`sticker-${face}`] = { color: colors["URFDLB".indexOf(face)], roughness };
+        out[kind] = writeGltf(parts, mats);
+    }
+    kit.dispose();
+    return out;
+}

package/render/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./layers.js";
+export * from "../skin/index.js";
+export * from "./renderer.js";
+export * from "./pictures.js";
+export * from "./arrows.js";
+export * from "./viewports.js";
+export * from "./tile.js";
+export * from "./build/tiles.js";
+export * from "./build/attachments.js";
+export * from "./pieceModels.js";
+export * from "./gltf.js";
+export * from "./build/models.js";

package/render/index.js

@@ -0,0 +1,12 @@
+export * from "./layers.js";
+export * from "../skin/index.js";
+export * from "./renderer.js";
+export * from "./pictures.js";
+export * from "./arrows.js";
+export * from "./viewports.js";
+export * from "./tile.js";
+export * from "./build/tiles.js";
+export * from "./build/attachments.js";
+export * from "./pieceModels.js";
+export * from "./gltf.js";
+export * from "./build/models.js";

package/render/layers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure geometry for animation (no three.js): which cubies a move turns, about
+ * which axis, and by what angle. Shared by the renderer and its tests.
+ *
+ * Animation model: while move m animates from state S, the renderer shows S's
+ * colours with m's layer rotated by `progress × angle`; at progress 1 it
+ * switches to S·m with nothing rotated. The two pictures coincide, so there is
+ * no pop — and the scene never has to track which physical cubie is where.
+ */
+import { type Move, type Vec3 } from "../core/index.js";
+export interface LayerTurn {
+    /** 0 = x, 1 = y, 2 = z. */
+    axis: 0 | 1 | 2;
+    /** Radians, counter-clockwise about +axis (right-hand rule). */
+    angle: number;
+    /** Does this move turn the cubie at `pos`? */
+    turns(pos: Vec3): boolean;
+}
+export declare function layerTurn(move: Move): LayerTurn;
+/** Default animation length for a move, scaled by how far it turns (half turns take longer). */
+export declare function defaultDuration(move: Move, quarterMs?: number): number;

package/render/layers.js

@@ -0,0 +1,24 @@
+/**
+ * Pure geometry for animation (no three.js): which cubies a move turns, about
+ * which axis, and by what angle. Shared by the renderer and its tests.
+ *
+ * Animation model: while move m animates from state S, the renderer shows S's
+ * colours with m's layer rotated by `progress × angle`; at progress 1 it
+ * switches to S·m with nothing rotated. The two pictures coincide, so there is
+ * no pop — and the scene never has to track which physical cubie is where.
+ */
+import { FAMILY, amountQuarters } from "../core/index.js";
+export function layerTurn(move) {
+    const def = FAMILY[move.family];
+    // A family's clockwise turn is `def.q` CCW quarters about +axis; the amount multiplies it.
+    const quarters = def.q * (move.amount === -1 ? -1 : move.amount === 2 ? 2 : 1);
+    return {
+        axis: def.axis,
+        angle: (quarters * Math.PI) / 2,
+        turns: (pos) => def.layers.includes(pos[def.axis]),
+    };
+}
+/** Default animation length for a move, scaled by how far it turns (half turns take longer). */
+export function defaultDuration(move, quarterMs = 120) {
+    return amountQuarters(move.amount) === 2 ? quarterMs * 1.5 : quarterMs;
+}

package/render/pictures.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Still pictures of cubes from ONE WebGL renderer — for pages with many
+ * cubes (a list of cases). Browsers keep only ~16 WebGL contexts, so a live
+ * renderer per cube stops working past that; here a single hidden renderer
+ * draws each picture in turn (the same 3D look, perspective and camera) and
+ * hands back an image URL, cached by `key`.
+ *
+ *   const pictures = sharedPictures();
+ *   img.src = pictures.draw({ state, mask, skin, camera: { latitude: 20, longitude: 25 } }, key);
+ */
+import type { Mask, State } from "../core/index.js";
+import { type Skin, type Theme } from "../skin/index.js";
+import { type CameraOptions } from "./renderer.js";
+export interface PictureOptions {
+    state: State;
+    mask?: Mask | null;
+    skin?: Skin;
+    theme?: Theme;
+    camera?: Partial<CameraOptions>;
+    /** Turn the whole cube (e.g. as held: white down) — see CubeRenderer.setOrientation. */
+    orientation?: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    } | null;
+}
+export declare class CubePictures {
+    private readonly size;
+    private readonly maxCached;
+    private host;
+    private renderer;
+    private skin;
+    private theme;
+    private readonly cache;
+    /** `size`: picture side in CSS px (drawn at the device pixel ratio, up to 2×). */
+    constructor(size?: number, maxCached?: number);
+    /** An image URL of the cube (a PNG data URL); same `key` → the cached one. */
+    draw(options: PictureOptions, key?: string): string;
+    /** Forget cached pictures (e.g. after the look changed). */
+    clear(): void;
+    dispose(): void;
+    private ensure;
+}
+/** The page's shared picture renderer (one WebGL context for all of them). */
+export declare function sharedPictures(): CubePictures;

package/render/pictures.js

@@ -0,0 +1,80 @@
+/**
+ * Still pictures of cubes from ONE WebGL renderer — for pages with many
+ * cubes (a list of cases). Browsers keep only ~16 WebGL contexts, so a live
+ * renderer per cube stops working past that; here a single hidden renderer
+ * draws each picture in turn (the same 3D look, perspective and camera) and
+ * hands back an image URL, cached by `key`.
+ *
+ *   const pictures = sharedPictures();
+ *   img.src = pictures.draw({ state, mask, skin, camera: { latitude: 20, longitude: 25 } }, key);
+ */
+import { SKINS } from "../skin/index.js";
+import { CubeRenderer } from "./renderer.js";
+export class CubePictures {
+    size;
+    maxCached;
+    host = null;
+    renderer = null;
+    skin = null;
+    theme = null;
+    cache = new Map();
+    /** `size`: picture side in CSS px (drawn at the device pixel ratio, up to 2×). */
+    constructor(size = 240, maxCached = 500) {
+        this.size = size;
+        this.maxCached = maxCached;
+    }
+    /** An image URL of the cube (a PNG data URL); same `key` → the cached one. */
+    draw(options, key) {
+        if (key !== undefined) {
+            const hit = this.cache.get(key);
+            if (hit)
+                return hit;
+        }
+        const r = this.ensure();
+        const skin = options.skin ?? SKINS.default;
+        if (skin !== this.skin)
+            r.setSkin((this.skin = skin));
+        const theme = options.theme ?? "dark";
+        if (theme !== this.theme)
+            r.setTheme((this.theme = theme));
+        r.setCamera({ latitude: 30, longitude: 35, ...options.camera });
+        r.setOrientation(options.orientation ?? null);
+        r.setMask(options.mask ?? null);
+        r.setState(options.state);
+        const url = r.snapshot();
+        if (key !== undefined) {
+            if (this.cache.size >= this.maxCached)
+                this.cache.delete(this.cache.keys().next().value);
+            this.cache.set(key, url);
+        }
+        return url;
+    }
+    /** Forget cached pictures (e.g. after the look changed). */
+    clear() {
+        this.cache.clear();
+    }
+    dispose() {
+        this.renderer?.dispose();
+        this.host?.remove();
+        this.renderer = null;
+        this.host = null;
+        this.cache.clear();
+    }
+    ensure() {
+        if (this.renderer)
+            return this.renderer;
+        const host = document.createElement("div");
+        host.setAttribute("aria-hidden", "true");
+        host.style.cssText = `position:fixed;left:-10000px;top:0;width:${this.size}px;height:${this.size}px;pointer-events:none;`;
+        document.body.append(host);
+        this.host = host;
+        this.renderer = new CubeRenderer(host, { dragToRotate: false });
+        return this.renderer;
+    }
+}
+let shared = null;
+/** The page's shared picture renderer (one WebGL context for all of them). */
+export function sharedPictures() {
+    shared ??= new CubePictures();
+    return shared;
+}

package/render/pieceModels.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Piece models — pure maths for placing one model per piece kind on all 26
+ * cubies (no three.js here; the renderer and the glTF exporter use it).
+ *
+ * Convention for model authors (glTF / GLB, 1 unit = one cubie, centred on
+ * the cubie's centre, Y up, Z towards the viewer — same axes as cubecore):
+ *
+ *   corner  modelled as the UFR corner: at +x +y +z, stickers on U, F and R
+ *   edge    modelled as the UF edge:    at  0 +y +z, stickers on U and F
+ *   center  modelled as the U centre:   at  0 +y  0, sticker on U
+ *
+ * Meshes whose material is named `sticker-U`, `sticker-F`, `sticker-R` are
+ * the coloured parts (recoloured by state and mask); everything else — the
+ * `body`, screws, logos you bake in — is drawn as authored. The renderer
+ * rotates each model onto every position of its kind and maps its sticker
+ * materials to the facelets there.
+ */
+import { type Cubie, type Face, type Mat3, type Vec3 } from "../core/index.js";
+export type ModelKind = "corner" | "edge" | "center";
+/** Where each kind's model is authored, and which of its faces carry stickers. */
+export declare const CANONICAL: Record<ModelKind, {
+    pos: Vec3;
+    faces: readonly Face[];
+}>;
+export interface PiecePlacement {
+    cubie: Cubie;
+    kind: ModelKind;
+    /** Rotation taking the canonical piece onto this cubie (rows; canonical → cube coordinates). */
+    rotation: Mat3;
+    /** Model sticker face (canonical letter) → facelet index at this cubie. */
+    stickers: Partial<Record<Face, number>>;
+}
+/** How the model of `cubie`'s kind sits on it. */
+export declare function placePiece(cubie: Cubie): PiecePlacement;
+/** Placements of all 26 cubies. */
+export declare const PLACEMENTS: readonly PiecePlacement[];
+/** `sticker-U` → "U"; anything else → null. */
+export declare function stickerFaceOf(materialName: string | undefined): Face | null;

package/render/pieceModels.js

@@ -0,0 +1,43 @@
+/**
+ * Piece models — pure maths for placing one model per piece kind on all 26
+ * cubies (no three.js here; the renderer and the glTF exporter use it).
+ *
+ * Convention for model authors (glTF / GLB, 1 unit = one cubie, centred on
+ * the cubie's centre, Y up, Z towards the viewer — same axes as cubecore):
+ *
+ *   corner  modelled as the UFR corner: at +x +y +z, stickers on U, F and R
+ *   edge    modelled as the UF edge:    at  0 +y +z, stickers on U and F
+ *   center  modelled as the U centre:   at  0 +y  0, sticker on U
+ *
+ * Meshes whose material is named `sticker-U`, `sticker-F`, `sticker-R` are
+ * the coloured parts (recoloured by state and mask); everything else — the
+ * `body`, screws, logos you bake in — is drawn as authored. The renderer
+ * rotates each model onto every position of its kind and maps its sticker
+ * materials to the facelets there.
+ */
+import { CUBIES, FACE_NORMAL, FRAMES, apply, faceletAt } from "../core/index.js";
+/** Where each kind's model is authored, and which of its faces carry stickers. */
+export const CANONICAL = {
+    corner: { pos: [1, 1, 1], faces: ["U", "F", "R"] },
+    edge: { pos: [0, 1, 1], faces: ["U", "F"] },
+    center: { pos: [0, 1, 0], faces: ["U"] },
+};
+const same = (a, b) => a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+/** How the model of `cubie`'s kind sits on it. */
+export function placePiece(cubie) {
+    const kind = cubie.kind;
+    const canon = CANONICAL[kind];
+    // The first of the 24 cube rotations that brings the canonical piece here (identity first).
+    const frame = FRAMES.find((f) => same(apply(f.matrix, canon.pos), cubie.pos));
+    const stickers = {};
+    for (const face of canon.faces)
+        stickers[face] = faceletAt(cubie.pos, apply(frame.matrix, FACE_NORMAL[face]));
+    return { cubie, kind, rotation: frame.matrix, stickers };
+}
+/** Placements of all 26 cubies. */
+export const PLACEMENTS = CUBIES.map(placePiece);
+/** `sticker-U` → "U"; anything else → null. */
+export function stickerFaceOf(materialName) {
+    const m = /^sticker-([URFDLB])$/i.exec(materialName ?? "");
+    return m ? m[1].toUpperCase() : null;
+}