@wodzik/cubecore 0.1.0

package/react/index.js

@@ -0,0 +1,228 @@
+/**
+ * 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 { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, } from "react";
+import "../element/index.js"; // registers the elements (in the browser)
+/** Listen to element events from an effect; handlers may change every render. */
+function useEvents(ref, handlers) {
+    const latest = useRef(handlers);
+    latest.current = handlers;
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const names = Object.keys(latest.current);
+        const listeners = names.map((name) => {
+            const l = (e) => latest.current[name]?.(e.detail);
+            el.addEventListener(name, l);
+            return [name, l];
+        });
+        return () => listeners.forEach(([name, l]) => el.removeEventListener(name, l));
+    }, [ref]);
+}
+const flag = (on) => (on ? "" : undefined);
+export const CubePlayer = forwardRef(function CubePlayer(p, ref) {
+    const el = useRef(null);
+    useImperativeHandle(ref, () => el.current, []);
+    useEffect(() => {
+        if (el.current)
+            el.current.recording = p.recording ?? null;
+    }, [p.recording]);
+    useEffect(() => {
+        if (el.current)
+            el.current.method = p.method ?? null;
+    }, [p.method]);
+    useEffect(() => {
+        if (el.current && p.segments !== undefined)
+            el.current.segments = p.segments;
+    }, [p.segments]);
+    useEffect(() => {
+        if (el.current)
+            el.current.mask = p.mask ?? null;
+    }, [p.mask]);
+    useEffect(() => {
+        if (el.current && p.skin && typeof p.skin !== "string")
+            el.current.skin = p.skin;
+    }, [p.skin]);
+    useEffect(() => {
+        if (el.current && p.formatSegment)
+            el.current.formatSegment = p.formatSegment;
+    }, [p.formatSegment]);
+    useEffect(() => {
+        if (!el.current || !p.live)
+            return;
+        return el.current.attach(p.live, { autoSkin: p.autoSkin });
+    }, [p.live, p.autoSkin]);
+    useEvents(el, { timeupdate: p.onTimeUpdate, play: p.onPlay, pause: p.onPause, ended: p.onEnded, segmentchange: p.onSegmentChange, error: p.onError });
+    return createElement("cube-player", {
+        ref: el,
+        alg: p.alg,
+        setup: p.setup,
+        anchor: p.anchor,
+        tempo: p.tempo,
+        skin: typeof p.skin === "string" ? p.skin : undefined,
+        theme: p.theme,
+        visualization: p.visualization,
+        "back-view": p.backView,
+        controls: p.controls,
+        progress: flag(p.progress),
+        markers: flag(p.markers),
+        "segment-labels": flag(p.segmentLabels),
+        tooltips: p.tooltips === false ? "off" : undefined,
+        "max-pause": p.maxPause,
+        id: p.id,
+        className: p.className,
+        style: p.style,
+    }, p.children);
+});
+export const CubeScramble = forwardRef(function CubeScramble(p, ref) {
+    const el = useRef(null);
+    useImperativeHandle(ref, () => el.current, []);
+    useEffect(() => {
+        if (!el.current || !p.source)
+            return;
+        return el.current.attach(p.source);
+    }, [p.source]);
+    useEffect(() => {
+        if (el.current)
+            el.current.scramble = p.scramble;
+    }, [p.scramble]);
+    useEffect(() => {
+        if (el.current && p.messages)
+            el.current.messages = p.messages;
+    }, [p.messages]);
+    useEffect(() => {
+        if (el.current)
+            el.current.player = p.player?.current ?? null;
+    });
+    useEvents(el, { progress: p.onProgress, complete: p.onComplete, change: p.onChange });
+    return createElement("cube-scramble", { ref: el, editable: p.editable ? "" : undefined, arrows: p.arrows ? "" : undefined, "arrow-shape": p.arrowShape, id: p.id, className: p.className, style: p.style });
+});
+export const CubeAlgPractice = forwardRef(function CubeAlgPractice(p, ref) {
+    const el = useRef(null);
+    useImperativeHandle(ref, () => el.current, []);
+    useEffect(() => {
+        if (!el.current || !p.source)
+            return;
+        return el.current.attach(p.source);
+    }, [p.source]);
+    useEffect(() => {
+        if (el.current)
+            el.current.alg = p.alg;
+    }, [p.alg]);
+    useEffect(() => {
+        if (el.current && p.messages)
+            el.current.messages = p.messages;
+    }, [p.messages]);
+    useEffect(() => {
+        if (el.current)
+            el.current.player = p.player?.current ?? null;
+    });
+    useEvents(el, { progress: p.onProgress, mistake: p.onMistake, complete: p.onComplete });
+    return createElement("cube-alg-practice", {
+        ref: el,
+        reveal: p.reveal,
+        arrows: p.arrows ? "" : undefined,
+        "arrow-shape": p.arrowShape,
+        "hint-on-mistake": p.hintOnMistake === false ? "off" : undefined,
+        controls: p.controls,
+        headless: p.headless ? "" : undefined,
+        id: p.id,
+        className: p.className,
+        style: p.style,
+    }, p.children);
+});
+export const CubeBld = forwardRef(function CubeBld(p, ref) {
+    const el = useRef(null);
+    useImperativeHandle(ref, () => el.current, []);
+    useEffect(() => {
+        if (!el.current || !p.source)
+            return;
+        return el.current.attach(p.source);
+    }, [p.source]);
+    useEffect(() => {
+        if (el.current && p.messages)
+            el.current.messages = p.messages;
+    }, [p.messages]);
+    useEvents(el, { progress: p.onProgress, letter: p.onLetter, wrong: p.onWrong, complete: p.onComplete });
+    return createElement("cube-bld", { ref: el, scheme: p.scheme, rotation: p.rotation, reveal: p.reveal, headless: p.headless ? "" : undefined, id: p.id, className: p.className, style: p.style }, p.children);
+});
+export const CubeAlg = forwardRef(function CubeAlg(p, ref) {
+    const el = useRef(null);
+    useImperativeHandle(ref, () => el.current, []);
+    useEffect(() => {
+        if (el.current && p.player?.current)
+            el.current.attach(p.player.current);
+    });
+    return createElement("cube-alg", { ref: el, for: p.for, alg: p.alg, id: p.id, className: p.className, style: p.style });
+});
+/** A smart cube as React state: the session, its state after every move, battery, connection. */
+export function useSmartCube() {
+    const [session, setSession] = useState(null);
+    const [state, setState] = useState(null);
+    const [battery, setBattery] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!session)
+            return;
+        setState(session.state);
+        setBattery(session.battery);
+        const offs = [
+            session.on("state", (e) => setState(e.state)),
+            session.on("battery", (b) => setBattery(b)),
+            session.on("disconnect", () => setSession(null)),
+        ];
+        return () => offs.forEach((off) => off());
+    }, [session]);
+    useEffect(() => () => void session?.disconnect(), [session]);
+    const connect = useCallback(async () => {
+        setError(null);
+        try {
+            const { SmartCubeSession } = await import("../bluetooth/index.js");
+            setSession(await SmartCubeSession.connect({ enableAddressSearch: true }));
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        }
+    }, []);
+    const simulate = useCallback(async () => {
+        const { SimulatedCube, SmartCubeSession } = await import("../bluetooth/index.js");
+        setSession(new SmartCubeSession(new SimulatedCube()));
+    }, []);
+    const disconnect = useCallback(async () => {
+        await session?.disconnect();
+        setSession(null);
+    }, [session]);
+    return { session, state, battery, connected: !!session, error, connect, simulate, disconnect };
+}
+/** The solver worker for this component's lifetime (null until created, e.g. during SSR). */
+export function useSolverWorker(url) {
+    const [client, setClient] = useState(null);
+    useEffect(() => {
+        let c = null;
+        let cancelled = false;
+        import("../solve/index.js").then(({ createSolverWorker }) => {
+            if (cancelled)
+                return;
+            c = createSolverWorker(url);
+            setClient(c);
+        });
+        return () => {
+            cancelled = true;
+            c?.terminate();
+        };
+    }, [String(url ?? "")]);
+    return client;
+}

package/render/arrows.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Turn arrows in 3D: a ribbon with an arrowhead hovering just above the
+ * layer that is about to turn — centred on its row, flat side to the cube,
+ * rounding the cube's edges — the way the layer moves.
+ *
+ * One length for every arrow; two per layer on opposite sides, travelling
+ * round the layer the way they point (so one is always in view, and the
+ * motion shows the direction); as many heads as quarter turns (1–3).
+ * Shapes: "box" follows the faces at an even height, "circle" is an arc of
+ * a circle over them (clear of the corners).
+ *
+ * The direction is the one written (R2' the other way than R2).
+ *
+ * The path around a layer is the cube's square cross-section pushed out by
+ * HOVER (straight over the faces, round over the edges), measured in
+ * quarters t: t = k at the middle of side k (side 0 faces +e1, side 1 +e2…),
+ * t = k + 0.5 at the edge between sides k and k+1; increasing t is
+ * counter-clockwise about +axis — the same sense as TurnArrow.quarters.
+ */
+import { Group, Vector3 } from "three";
+import type { Axis, TurnArrow } from "../core/index.js";
+export interface ArrowStyle {
+    /** Arrow colour. Default a clear blue. */
+    color?: string;
+    /** 0..1. Default 0.95. */
+    opacity?: number;
+    /** Size factor (ribbon width, heads). Default 1. */
+    scale?: number;
+    /** "box": even height over the faces, round over the edges (default); "circle": an arc over them. */
+    shape?: ArrowShape;
+    /**
+     * How fast the arrows travel round the layer the way they point, in
+     * quarter turns per second (default 0.35); 0 keeps them still.
+     */
+    speed?: number;
+}
+/** Default travel speed of the arrows (quarter turns per second). */
+export declare const ARROW_SPEED = 0.35;
+export type ArrowShape = "box" | "circle";
+/** How far arrows reach from the centre (for fitting the camera). */
+export declare const ARROW_REACH: number;
+/** In-plane basis (e1, e2) with e1 × e2 = +axis. */
+export declare const PLANE: Record<Axis, [Vector3, Vector3, Vector3]>;
+/** Point of the path at `t` quarters, in plane coordinates (u along e1, v along e2). */
+export declare function pathPoint(t: number, shape?: ArrowShape): [number, number];
+/**
+ * Where an arrow goes for a viewer at `eye` (cube coordinates): over the
+ * best-seen side, leaning towards its better-seen neighbour.
+ */
+export declare function arrowCentre(arrow: TurnArrow, eye: Vector3): number;
+/** Tail → tip in quarters along the path (the same length for every turn). */
+export declare function arrowSpan(quarters: number, centre: number): {
+    from: number;
+    to: number;
+};
+/** A strip along the path: cross-sections [t, half width] from one end to the other. */
+export type Strip = [number, number][];
+/** One arrow as strips: the ribbon, then one per head (as many heads as quarter turns, up to 3). */
+export declare function arrowStrips(quarters: number, centre: number, scale?: number, shape?: ArrowShape): Strip[];
+/**
+ * Meshes for `arrows`: for each turning layer two arrows on opposite sides,
+ * the first at `centres[i]` (quarters along the path). Move them with
+ * `moveArrows`; dispose with `disposeArrows`.
+ */
+export declare function buildArrows(arrows: readonly TurnArrow[], centres: readonly number[], style?: ArrowStyle): Group;
+/** Slide every arrow `travel` quarters along its layer, the way it points (a travelling arrow shows the direction). */
+export declare function moveArrows(group: Group, travel: number): void;
+export declare function disposeArrows(group: Group): void;

package/render/arrows.js

@@ -0,0 +1,190 @@
+/**
+ * Turn arrows in 3D: a ribbon with an arrowhead hovering just above the
+ * layer that is about to turn — centred on its row, flat side to the cube,
+ * rounding the cube's edges — the way the layer moves.
+ *
+ * One length for every arrow; two per layer on opposite sides, travelling
+ * round the layer the way they point (so one is always in view, and the
+ * motion shows the direction); as many heads as quarter turns (1–3).
+ * Shapes: "box" follows the faces at an even height, "circle" is an arc of
+ * a circle over them (clear of the corners).
+ *
+ * The direction is the one written (R2' the other way than R2).
+ *
+ * The path around a layer is the cube's square cross-section pushed out by
+ * HOVER (straight over the faces, round over the edges), measured in
+ * quarters t: t = k at the middle of side k (side 0 faces +e1, side 1 +e2…),
+ * t = k + 0.5 at the edge between sides k and k+1; increasing t is
+ * counter-clockwise about +axis — the same sense as TurnArrow.quarters.
+ */
+import { BufferGeometry, Color, DoubleSide, Float32BufferAttribute, Group, Matrix4, Mesh, MeshBasicMaterial, Vector3 } from "three";
+/** Default travel speed of the arrows (quarter turns per second). */
+export const ARROW_SPEED = 0.35;
+const HALF = 1.5; // half the cube
+/** Height of the ribbon above the faces. */
+const HOVER = 0.3;
+const CORNER = (Math.PI / 2) * HOVER;
+const QUARTER = 2 * HALF + CORNER; // path length of one quarter
+const WIDTH = 0.34;
+const HEAD_WIDTH = 0.7;
+const HEAD_LENGTH = 0.5;
+/** Each further head this many head lengths behind the one before. */
+const HEAD_GAP = 0.9;
+/** Length of every arrow, in quarters of the way round. */
+const SPAN = 1.3;
+/** Arrows sit this far (quarters) from the best-seen face's middle towards the next face seen best. */
+const LEAN = 0.25;
+/** The circle clears the corners (1.5·√2 ≈ 2.12) by a little. */
+const CIRCLE = HALF * Math.SQRT2 + 0.2;
+const CIRCLE_QUARTER = (Math.PI / 2) * CIRCLE;
+/** How far arrows reach from the centre (for fitting the camera). */
+export const ARROW_REACH = Math.hypot(HALF * Math.SQRT2 + 0.3, 1 + HEAD_WIDTH / 2);
+/** In-plane basis (e1, e2) with e1 × e2 = +axis. */
+export const PLANE = {
+    0: [new Vector3(0, 1, 0), new Vector3(0, 0, 1), new Vector3(1, 0, 0)],
+    1: [new Vector3(0, 0, 1), new Vector3(1, 0, 0), new Vector3(0, 1, 0)],
+    2: [new Vector3(1, 0, 0), new Vector3(0, 1, 0), new Vector3(0, 0, 1)],
+};
+/** Point of the path at `t` quarters, in plane coordinates (u along e1, v along e2). */
+export function pathPoint(t, shape = "box") {
+    if (shape === "circle")
+        return [CIRCLE * Math.cos((t * Math.PI) / 2), CIRCLE * Math.sin((t * Math.PI) / 2)];
+    const k = Math.floor(t);
+    const s = (t - k) * QUARTER;
+    let u, v;
+    if (s < HALF)
+        [u, v] = [HALF + HOVER, s];
+    else if (s < HALF + CORNER) {
+        const a = (s - HALF) / HOVER;
+        [u, v] = [HALF + HOVER * Math.cos(a), HALF + HOVER * Math.sin(a)];
+    }
+    else
+        [u, v] = [HALF - (s - HALF - CORNER), HALF + HOVER];
+    for (let i = 0; i < ((k % 4) + 4) % 4; i++)
+        [u, v] = [-v, u]; // k quarter turns counter-clockwise
+    return [u, v];
+}
+/** Outward normal of side k of the layer (cube coordinates). */
+function sideNormal(axis, k) {
+    const [e1, e2] = PLANE[axis];
+    const q = ((k % 4) + 4) % 4;
+    return [e1, e2, e1.clone().negate(), e2.clone().negate()][q].clone();
+}
+/**
+ * Where an arrow goes for a viewer at `eye` (cube coordinates): over the
+ * best-seen side, leaning towards its better-seen neighbour.
+ */
+export function arrowCentre(arrow, eye) {
+    const seen = [0, 1, 2, 3].map((k) => sideNormal(arrow.axis, k).dot(eye));
+    const best = seen.indexOf(Math.max(...seen));
+    return best + (seen[(best + 1) % 4] >= seen[(best + 3) % 4] ? LEAN : -LEAN);
+}
+/** Tail → tip in quarters along the path (the same length for every turn). */
+export function arrowSpan(quarters, centre) {
+    const half = SPAN / 2;
+    return quarters > 0 ? { from: centre - half, to: centre + half } : { from: centre + half, to: centre - half };
+}
+/** One arrow as strips: the ribbon, then one per head (as many heads as quarter turns, up to 3). */
+export function arrowStrips(quarters, centre, scale = 1, shape = "box") {
+    const { from, to } = arrowSpan(quarters, centre);
+    const dir = Math.sign(to - from);
+    const heads = Math.min(3, Math.max(1, Math.abs(quarters)));
+    const hl = (HEAD_LENGTH * scale) / (shape === "circle" ? CIRCLE_QUARTER : QUARTER);
+    const strip = (t0, t1, w0, w1, n) => Array.from({ length: n + 1 }, (_, i) => [t0 + ((t1 - t0) * i) / n, w0 + ((w1 - w0) * i) / n]);
+    const end = to - dir * hl * (1 + HEAD_GAP * (heads - 1));
+    const strips = [strip(from, end, (WIDTH * scale) / 2, (WIDTH * scale) / 2, 64)];
+    for (let h = 0; h < heads; h++) {
+        const tip = to - dir * hl * HEAD_GAP * h;
+        strips.push(strip(tip - dir * hl, tip, (HEAD_WIDTH * scale) / 2, 0, 6));
+    }
+    return strips;
+}
+/** Vertex positions of strips around the layer (layer frame: axis = z, the row's middle at z = 0); width along the axis. */
+function positionsOf(strips, shape) {
+    const pos = [];
+    for (const strip of strips) {
+        for (const [t, half] of strip) {
+            const [u, v] = pathPoint(t, shape);
+            pos.push(u, v, half, u, v, -half);
+        }
+    }
+    return pos;
+}
+function wrap(strips, shape) {
+    const index = [];
+    let first = 0;
+    for (const strip of strips) {
+        for (let i = 0; i < strip.length - 1; i++) {
+            const k = first + 2 * i;
+            index.push(k, k + 1, k + 2, k + 1, k + 3, k + 2);
+        }
+        first += 2 * strip.length;
+    }
+    const g = new BufferGeometry();
+    g.setAttribute("position", new Float32BufferAttribute(positionsOf(strips, shape), 3));
+    g.setIndex(index);
+    g.computeBoundingSphere();
+    return g;
+}
+/**
+ * Meshes for `arrows`: for each turning layer two arrows on opposite sides,
+ * the first at `centres[i]` (quarters along the path). Move them with
+ * `moveArrows`; dispose with `disposeArrows`.
+ */
+export function buildArrows(arrows, centres, style = {}) {
+    const group = new Group();
+    const material = new MeshBasicMaterial({
+        color: new Color(style.color ?? "#2f8bff"),
+        transparent: true,
+        opacity: style.opacity ?? 0.95,
+        side: DoubleSide,
+        depthWrite: false,
+        toneMapped: false, // exactly the colour asked for
+    });
+    const shape = style.shape ?? "box";
+    const scale = style.scale ?? 1;
+    arrows.forEach((arrow, i) => {
+        const [e1, e2, n] = PLANE[arrow.axis];
+        for (const centre of [centres[i], centres[i] + 2]) {
+            for (const layer of arrow.layers) {
+                // Own geometry per mesh: each is moved along the path separately.
+                const mesh = new Mesh(wrap(arrowStrips(arrow.quarters, centre, scale, shape), shape), material);
+                mesh.matrixAutoUpdate = false;
+                mesh.matrix.copy(new Matrix4().makeBasis(e1, e2, n).setPosition(n.clone().multiplyScalar(layer)));
+                mesh.renderOrder = 3; // after the cube and its decals (2), so the see-through ribbon blends over both
+                mesh.userData.arrow = { quarters: arrow.quarters, centre, scale, shape };
+                mesh.frustumCulled = false; // it moves; its bounding sphere would go stale
+                group.add(mesh);
+            }
+        }
+    });
+    return group;
+}
+/** Slide every arrow `travel` quarters along its layer, the way it points (a travelling arrow shows the direction). */
+export function moveArrows(group, travel) {
+    for (const o of group.children) {
+        const m = o;
+        const d = m.userData.arrow;
+        if (!d)
+            continue;
+        const strips = arrowStrips(d.quarters, d.centre + Math.sign(d.quarters) * (travel % 4), d.scale, d.shape);
+        const attr = m.geometry.getAttribute("position");
+        attr.array.set(positionsOf(strips, d.shape));
+        attr.needsUpdate = true;
+    }
+}
+export function disposeArrows(group) {
+    const done = new Set();
+    group.traverse((o) => {
+        const m = o;
+        if (!m.isMesh)
+            return;
+        for (const r of [m.geometry, m.material]) {
+            if (done.has(r))
+                continue;
+            done.add(r);
+            r.dispose();
+        }
+    });
+    group.removeFromParent();
+}

package/render/build/attachments.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Attachments in 3D — decals and features (see @cubecore/skin
+ * attachments.ts) as three.js objects that ride on their STICKER.
+ *
+ * Tiles are built per position and only recoloured as the state changes, so
+ * each frame an attachment is re-parented onto the tile mesh where its
+ * sticker currently is, and turned by that sticker's in-plane turn (core
+ * `stickerTurn`: centre spins, piece orientation). Being a child of the tile
+ * it moves with layer animations and hides with the tile.
+ */
+import * as THREE from "three";
+import { type CenterSpins, type Mask, type State } from "../../core/index.js";
+import { type PieceKind, type Skin } from "../../skin/index.js";
+export interface Attachment {
+    /** Home facelet index of the sticker it belongs to. */
+    sticker: number;
+    /** Pivot in tile-local coordinates (z = 0 on the tile top); rotated by the sticker's turn. */
+    object: THREE.Group;
+    /** Hidden while the sticker isn't shown in full colour. */
+    onlyRegular: boolean;
+    /** Height of its tile's top (the tile thickness of its piece kind). */
+    lift: number;
+}
+export interface AttachmentSet {
+    items: Attachment[];
+    dispose(): void;
+}
+/** Build every decal and feature of `skin`, one object per selected sticker. `onLoad` fires as images arrive. */
+export declare function buildAttachments(skin: Skin, kit: {
+    sideOf(kind: PieceKind): number;
+    thicknessOf(kind: PieceKind): number;
+}, onLoad: () => void): AttachmentSet;
+/** Put each attachment on the tile where its sticker is now, turned with the sticker. */
+/** `surface`: one height for every tile (glTF models), or null for each tile's own thickness. */
+export declare function placeAttachments(set: AttachmentSet, state: State, spins: CenterSpins, tiles: readonly THREE.Object3D[], surface: number | null, mask: Mask | null): void;

package/render/build/attachments.js

@@ -0,0 +1,94 @@
+/**
+ * Attachments in 3D — decals and features (see @cubecore/skin
+ * attachments.ts) as three.js objects that ride on their STICKER.
+ *
+ * Tiles are built per position and only recoloured as the state changes, so
+ * each frame an attachment is re-parented onto the tile mesh where its
+ * sticker currently is, and turned by that sticker's in-plane turn (core
+ * `stickerTurn`: centre spins, piece orientation). Being a child of the tile
+ * it moves with layer animations and hides with the tile.
+ */
+import * as THREE from "three";
+import { maskStateAt, stickerTurn } from "../../core/index.js";
+import { featureDef, imageUrl, kindOfSticker, selectedStickers } from "../../skin/index.js";
+/** Build every decal and feature of `skin`, one object per selected sticker. `onLoad` fires as images arrive. */
+export function buildAttachments(skin, kit, onLoad) {
+    const items = [];
+    const textures = new Map();
+    const disposables = [];
+    const pivot = (sticker, onlyRegular) => {
+        const object = new THREE.Group();
+        items.push({ sticker, object, onlyRegular, lift: kit.thicknessOf(kindOfSticker(sticker)) });
+        return object;
+    };
+    // A sticker is always on the same kind of piece, so its tile size is known up front.
+    const planes = new Map();
+    for (const decal of skin.decals ?? []) {
+        const url = imageUrl(decal.image);
+        let texture = textures.get(url);
+        if (!texture) {
+            texture = new THREE.TextureLoader().load(url, onLoad);
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.anisotropy = 4;
+            textures.set(url, texture);
+        }
+        const multiply = decal.blend === "multiply";
+        const material = new THREE.MeshBasicMaterial({
+            map: texture,
+            transparent: true,
+            depthWrite: false,
+            blending: multiply ? THREE.MultiplyBlending : THREE.NormalBlending,
+            premultipliedAlpha: multiply,
+            toneMapped: false,
+        });
+        disposables.push(material);
+        const [ox, oy] = decal.offset ?? [0, 0];
+        for (const sticker of selectedStickers(decal.select)) {
+            const side = kit.sideOf(kindOfSticker(sticker));
+            const key = `${side * decal.size}`;
+            let plane = planes.get(key);
+            if (!plane) {
+                planes.set(key, (plane = new THREE.PlaneGeometry(side * decal.size, side * decal.size)));
+                disposables.push(plane);
+            }
+            const mesh = new THREE.Mesh(plane, material);
+            mesh.position.set((ox * side) / 2, (oy * side) / 2, 0.0015);
+            mesh.rotation.z = ((decal.rotate ?? 0) * Math.PI) / 2;
+            mesh.renderOrder = 2;
+            pivot(sticker, decal.onlyRegular ?? true).add(mesh);
+        }
+    }
+    for (const use of skin.features ?? []) {
+        const def = featureDef(use.type);
+        if (!def?.build3d)
+            continue; // unknown type or 2D-only: nothing to draw here
+        for (const sticker of selectedStickers(use.select)) {
+            const kind = kindOfSticker(sticker);
+            pivot(sticker, false).add(def.build3d({ three: THREE, side: kit.sideOf(kind), thickness: kit.thicknessOf(kind), params: use.params ?? {} }));
+        }
+    }
+    return {
+        items,
+        dispose() {
+            for (const t of textures.values())
+                t.dispose();
+            for (const d of disposables)
+                d.dispose();
+        },
+    };
+}
+/** Put each attachment on the tile where its sticker is now, turned with the sticker. */
+/** `surface`: one height for every tile (glTF models), or null for each tile's own thickness. */
+export function placeAttachments(set, state, spins, tiles, surface, mask) {
+    for (const a of set.items) {
+        const pos = state.indexOf(a.sticker);
+        const tile = tiles[pos];
+        if (!tile)
+            continue;
+        if (a.object.parent !== tile)
+            tile.add(a.object);
+        a.object.position.set(0, 0, surface ?? a.lift);
+        a.object.rotation.set(0, 0, (stickerTurn(state, a.sticker, spins) * Math.PI) / 2);
+        a.object.visible = !a.onlyRegular || !mask || maskStateAt(mask, state, pos) === "regular";
+    }
+}

package/render/build/models.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Loading piece models (glTF / GLB) once per URL. The renderer draws the
+ * built-in pieces until a model is ready, then rebuilds with it.
+ */
+import type { Object3D } from "three";
+/** The model at `url` if it has loaded (null while loading or after a failure). */
+export declare const readyModel: (url: string | undefined) => Object3D | null;
+/** Load (once) and resolve with the model's scene, or null on failure (logged). */
+export declare function loadModel(url: string): Promise<Object3D | null>;

package/render/build/models.js

@@ -0,0 +1,27 @@
+/**
+ * Loading piece models (glTF / GLB) once per URL. The renderer draws the
+ * built-in pieces until a model is ready, then rebuilds with it.
+ */
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+const pending = new Map();
+const ready = new Map();
+/** The model at `url` if it has loaded (null while loading or after a failure). */
+export const readyModel = (url) => (url ? (ready.get(url) ?? null) : null);
+/** Load (once) and resolve with the model's scene, or null on failure (logged). */
+export function loadModel(url) {
+    let p = pending.get(url);
+    if (!p) {
+        p = new GLTFLoader()
+            .loadAsync(url)
+            .then((gltf) => {
+            ready.set(url, gltf.scene);
+            return gltf.scene;
+        })
+            .catch((err) => {
+            console.warn(`cubecore: could not load piece model ${url}`, err);
+            return null;
+        });
+        pending.set(url, p);
+    }
+    return p;
+}