rubiks-cube-3d 1.0.0

package/dist/rubiks-cube-3d.umd.cjs

@@ -0,0 +1,2 @@
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./core-CRe_v4Mo.cjs");let t=require("react"),n=require("react/jsx-runtime");var r=typeof window<`u`?t.useLayoutEffect:t.useEffect,i=[`size`,`colors`,`sticker`,`cubieGap`,`cubieRounding`,`antialias`,`shadow`,`maxPixelRatio`],a=(0,t.forwardRef)(function({className:a,style:o,width:s=`100%`,height:c,onReady:l,...u},d){let f=(0,t.useRef)(null),p=(0,t.useRef)(null),m=(0,t.useRef)(u);m.current=u,r(()=>{let t=f.current;if(!t)return;let n={onMove:(e,t)=>m.current.onMove?.(e,t),onScrambleStart:()=>m.current.onScrambleStart?.(),onScrambleEnd:()=>m.current.onScrambleEnd?.(),onSolved:()=>m.current.onSolved?.(),onStateChange:e=>m.current.onStateChange?.(e),onHoverChange:e=>m.current.onHoverChange?.(e)},r=new e.n(t,{...m.current,...n});return p.current=r,l?.(r),()=>{r.dispose(),p.current=null}},[(0,t.useMemo)(()=>JSON.stringify(i.map(e=>u[e]??null)),i.map(e=>JSON.stringify(u[e]??null)))]);let h=JSON.stringify({background:u.background,physics:u.physics,interaction:u.interaction,camera:u.camera,exposure:u.exposure,shadowOpacity:u.shadowOpacity,moveDuration:u.moveDuration,scrambleMoves:u.scrambleMoves});(0,t.useEffect)(()=>{let e=p.current;if(!e)return;let{background:t,physics:n,interaction:r,camera:i,exposure:a,shadowOpacity:o,moveDuration:s,scrambleMoves:c}=m.current;e.setOptions({background:t,physics:n,interaction:r,camera:i,exposure:a,shadowOpacity:o,moveDuration:s,scrambleMoves:c})},[h]),(0,t.useImperativeHandle)(d,()=>({get engine(){return p.current},scramble:e=>p.current?.scramble(e)??Promise.resolve(),move:(e,t)=>p.current?.move(e,t)??Promise.resolve(),turn:(e,t)=>p.current?.turn(e,t)??Promise.resolve(),reset:()=>p.current?.reset(),resetOrientation:()=>p.current?.resetOrientation(),isSolved:()=>p.current?.isSolved()??!0,get state(){return p.current?.state??`idle`},setHover:e=>p.current?.setHover(e),setIdle:e=>p.current?.setIdle(e)}),[]);let g={position:`relative`,width:s,height:c,aspectRatio:c===void 0?`1 / 1`:void 0,...o};return(0,n.jsx)(`div`,{ref:f,className:a,style:g})});exports.CubePhysics=e.m,exports.DEFAULT_CAMERA=e.r,exports.DEFAULT_COLORS=e.i,exports.DEFAULT_INTERACTION=e.a,exports.DEFAULT_OPTIONS=e.o,exports.DEFAULT_PHYSICS=e.s,exports.DEFAULT_STICKER=e.c,exports.RubiksCube=a,exports.default=a,exports.RubiksCubeEngine=e.n,exports.createRubiksCube=e.t,exports.layerCoordinates=e.u,exports.parseNotation=e.d,exports.randomScramble=e.f,exports.resolveOptions=e.l,exports.turnToNotation=e.p;
+//# sourceMappingURL=rubiks-cube-3d.umd.cjs.map

package/dist/rubiks-cube-3d.umd.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rubiks-cube-3d.umd.cjs","names":[],"sources":["../src/RubiksCube.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useEffect,\n  useImperativeHandle,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  type CSSProperties,\n} from 'react';\nimport { RubiksCubeEngine } from './core/RubiksCubeEngine';\nimport type { CubeState } from './core/RubiksCubeEngine';\nimport type { RubiksCubeOptions, Turn } from './core/types';\n\nexport interface RubiksCubeProps extends Partial<RubiksCubeOptions> {\n  className?: string;\n  style?: CSSProperties;\n  /** Width of the wrapper. Default '100%'. */\n  width?: number | string;\n  /** Height of the wrapper. Default: a square (aspect-ratio 1). */\n  height?: number | string;\n  /** Gets the engine instance as soon as it exists. */\n  onReady?: (engine: RubiksCubeEngine) => void;\n}\n\nexport interface RubiksCubeRef {\n  engine: RubiksCubeEngine | null;\n  scramble(moves?: number): Promise<void>;\n  move(notation: string, duration?: number): Promise<void>;\n  turn(turn: Turn, duration?: number): Promise<void>;\n  reset(): void;\n  resetOrientation(): void;\n  isSolved(): boolean;\n  readonly state: CubeState;\n  setHover(hovering: boolean): void;\n  setIdle(enabled: boolean): void;\n}\n\nconst useIsoLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;\n\n/** Props that require the cube to be rebuilt when they change. */\nconst STRUCTURAL_KEYS = ['size', 'colors', 'sticker', 'cubieGap', 'cubieRounding', 'antialias', 'shadow', 'maxPixelRatio'] as const;\n\n/**\n * React wrapper around the three.js/Matter.js engine.\n *\n *   <RubiksCube size={3} background=\"transparent\" physics={{ idleSpin: 0.4 }} />\n *\n * Structural props (size, colours, sticker shape, …) rebuild the cube; everything else is\n * updated live via `engine.setOptions`.\n */\nexport const RubiksCube = forwardRef<RubiksCubeRef, RubiksCubeProps>(function RubiksCube(\n  { className, style, width = '100%', height, onReady, ...options },\n  ref,\n) {\n  const containerRef = useRef<HTMLDivElement>(null);\n  const engineRef = useRef<RubiksCubeEngine | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  // A stable key for the props that force a rebuild.\n  const structuralKey = useMemo(\n    () => JSON.stringify(STRUCTURAL_KEYS.map((k) => options[k] ?? null)),\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    STRUCTURAL_KEYS.map((k) => JSON.stringify(options[k] ?? null)),\n  );\n\n  useIsoLayoutEffect(() => {\n    const el = containerRef.current;\n    if (!el) return;\n    // Callbacks are read through a ref so the latest closure is always used.\n    const callbackProxy: Partial<RubiksCubeOptions> = {\n      onMove: (t, n) => optionsRef.current.onMove?.(t, n),\n      onScrambleStart: () => optionsRef.current.onScrambleStart?.(),\n      onScrambleEnd: () => optionsRef.current.onScrambleEnd?.(),\n      onSolved: () => optionsRef.current.onSolved?.(),\n      onStateChange: (s) => optionsRef.current.onStateChange?.(s),\n      onHoverChange: (h) => optionsRef.current.onHoverChange?.(h),\n    };\n    const engine = new RubiksCubeEngine(el, { ...optionsRef.current, ...callbackProxy });\n    engineRef.current = engine;\n    onReady?.(engine);\n    return () => {\n      engine.dispose();\n      engineRef.current = null;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [structuralKey]);\n\n  // Live-updatable options.\n  const liveKey = JSON.stringify({\n    background: options.background,\n    physics: options.physics,\n    interaction: options.interaction,\n    camera: options.camera,\n    exposure: options.exposure,\n    shadowOpacity: options.shadowOpacity,\n    moveDuration: options.moveDuration,\n    scrambleMoves: options.scrambleMoves,\n  });\n  useEffect(() => {\n    const engine = engineRef.current;\n    if (!engine) return;\n    const { background, physics, interaction, camera, exposure, shadowOpacity, moveDuration, scrambleMoves } =\n      optionsRef.current;\n    engine.setOptions({ background, physics, interaction, camera, exposure, shadowOpacity, moveDuration, scrambleMoves });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [liveKey]);\n\n  useImperativeHandle(\n    ref,\n    () => ({\n      get engine() {\n        return engineRef.current;\n      },\n      scramble: (m) => engineRef.current?.scramble(m) ?? Promise.resolve(),\n      move: (n, d) => engineRef.current?.move(n, d) ?? Promise.resolve(),\n      turn: (t, d) => engineRef.current?.turn(t, d) ?? Promise.resolve(),\n      reset: () => engineRef.current?.reset(),\n      resetOrientation: () => engineRef.current?.resetOrientation(),\n      isSolved: () => engineRef.current?.isSolved() ?? true,\n      get state() {\n        return engineRef.current?.state ?? 'idle';\n      },\n      setHover: (h) => engineRef.current?.setHover(h),\n      setIdle: (i) => engineRef.current?.setIdle(i),\n    }),\n    [],\n  );\n\n  const wrapperStyle: CSSProperties = {\n    position: 'relative',\n    width,\n    height,\n    aspectRatio: height === undefined ? '1 / 1' : undefined,\n    ...style,\n  };\n\n  return <div ref={containerRef} className={className} style={wrapperStyle} />;\n});\n\nexport default RubiksCube;\n"],"mappings":"4LAqCA,IAAM,EAAqB,OAAO,OAAW,IAAc,EAAA,gBAAkB,EAAA,UAGvE,EAAkB,CAAC,OAAQ,SAAU,UAAW,WAAY,gBAAiB,YAAa,SAAU,eAAe,EAU5G,GAAA,EAAa,EAAA,WAAA,CAA2C,SACnE,CAAE,YAAW,QAAO,QAAQ,OAAQ,SAAQ,UAAS,GAAG,GACxD,EACA,CACA,IAAM,GAAA,EAAe,EAAA,OAAA,CAAuB,IAAI,EAC1C,GAAA,EAAY,EAAA,OAAA,CAAgC,IAAI,EAChD,GAAA,EAAa,EAAA,OAAA,CAAO,CAAO,EACjC,EAAW,QAAU,EASrB,MAAyB,CACvB,IAAM,EAAK,EAAa,QACxB,GAAI,CAAC,EAAI,OAET,IAAM,EAA4C,CAChD,QAAS,EAAG,IAAM,EAAW,QAAQ,SAAS,EAAG,CAAC,EAClD,oBAAuB,EAAW,QAAQ,kBAAkB,EAC5D,kBAAqB,EAAW,QAAQ,gBAAgB,EACxD,aAAgB,EAAW,QAAQ,WAAW,EAC9C,cAAgB,GAAM,EAAW,QAAQ,gBAAgB,CAAC,EAC1D,cAAgB,GAAM,EAAW,QAAQ,gBAAgB,CAAC,CAC5D,EACM,EAAS,IAAI,EAAA,EAAiB,EAAI,CAAE,GAAG,EAAW,QAAS,GAAG,CAAc,CAAC,EAGnF,MAFA,GAAU,QAAU,EACpB,IAAU,CAAM,MACH,CACX,EAAO,QAAQ,EACf,EAAU,QAAU,IACtB,CAEF,EAAG,EA1BG,EAAgB,EAAA,QAAA,KACd,KAAK,UAAU,EAAgB,IAAK,GAAM,EAAQ,IAAM,IAAI,CAAC,EAEnE,EAAgB,IAAK,GAAM,KAAK,UAAU,EAAQ,IAAM,IAAI,CAAC,CAuB3D,CAAa,CAAC,EAGlB,IAAM,EAAU,KAAK,UAAU,CAC7B,WAAY,EAAQ,WACpB,QAAS,EAAQ,QACjB,YAAa,EAAQ,YACrB,OAAQ,EAAQ,OAChB,SAAU,EAAQ,SAClB,cAAe,EAAQ,cACvB,aAAc,EAAQ,aACtB,cAAe,EAAQ,aACzB,CAAC,GACD,EAAA,EAAA,UAAA,KAAgB,CACd,IAAM,EAAS,EAAU,QACzB,GAAI,CAAC,EAAQ,OACb,GAAM,CAAE,aAAY,UAAS,cAAa,SAAQ,WAAU,gBAAe,eAAc,iBACvF,EAAW,QACb,EAAO,WAAW,CAAE,aAAY,UAAS,cAAa,SAAQ,WAAU,gBAAe,eAAc,eAAc,CAAC,CAEtH,EAAG,CAAC,CAAO,CAAC,GAEZ,EAAA,EAAA,oBAAA,CACE,OACO,CACL,IAAI,QAAS,CACX,OAAO,EAAU,OACnB,EACA,SAAW,GAAM,EAAU,SAAS,SAAS,CAAC,GAAK,QAAQ,QAAQ,EACnE,MAAO,EAAG,IAAM,EAAU,SAAS,KAAK,EAAG,CAAC,GAAK,QAAQ,QAAQ,EACjE,MAAO,EAAG,IAAM,EAAU,SAAS,KAAK,EAAG,CAAC,GAAK,QAAQ,QAAQ,EACjE,UAAa,EAAU,SAAS,MAAM,EACtC,qBAAwB,EAAU,SAAS,iBAAiB,EAC5D,aAAgB,EAAU,SAAS,SAAS,GAAK,GACjD,IAAI,OAAQ,CACV,OAAO,EAAU,SAAS,OAAS,MACrC,EACA,SAAW,GAAM,EAAU,SAAS,SAAS,CAAC,EAC9C,QAAU,GAAM,EAAU,SAAS,QAAQ,CAAC,CAC9C,GACA,CAAC,CACH,EAEA,IAAM,EAA8B,CAClC,SAAU,WACV,QACA,SACA,YAAa,IAAW,IAAA,GAAY,QAAU,IAAA,GAC9C,GAAG,CACL,EAEA,OAAO,EAAA,EAAA,IAAA,CAAC,MAAD,CAAK,IAAK,EAAyB,YAAW,MAAO,CAAe,CAAA,CAC7E,CAAC"}

package/dist/types/RubiksCube.d.ts

@@ -0,0 +1,36 @@
+import { type CSSProperties } from 'react';
+import { RubiksCubeEngine } from './core/RubiksCubeEngine';
+import type { CubeState } from './core/RubiksCubeEngine';
+import type { RubiksCubeOptions, Turn } from './core/types';
+export interface RubiksCubeProps extends Partial<RubiksCubeOptions> {
+    className?: string;
+    style?: CSSProperties;
+    /** Width of the wrapper. Default '100%'. */
+    width?: number | string;
+    /** Height of the wrapper. Default: a square (aspect-ratio 1). */
+    height?: number | string;
+    /** Gets the engine instance as soon as it exists. */
+    onReady?: (engine: RubiksCubeEngine) => void;
+}
+export interface RubiksCubeRef {
+    engine: RubiksCubeEngine | null;
+    scramble(moves?: number): Promise<void>;
+    move(notation: string, duration?: number): Promise<void>;
+    turn(turn: Turn, duration?: number): Promise<void>;
+    reset(): void;
+    resetOrientation(): void;
+    isSolved(): boolean;
+    readonly state: CubeState;
+    setHover(hovering: boolean): void;
+    setIdle(enabled: boolean): void;
+}
+/**
+ * React wrapper around the three.js/Matter.js engine.
+ *
+ *   <RubiksCube size={3} background="transparent" physics={{ idleSpin: 0.4 }} />
+ *
+ * Structural props (size, colours, sticker shape, …) rebuild the cube; everything else is
+ * updated live via `engine.setOptions`.
+ */
+export declare const RubiksCube: import("react").ForwardRefExoticComponent<RubiksCubeProps & import("react").RefAttributes<RubiksCubeRef>>;
+export default RubiksCube;

package/dist/types/core/RubiksCubeEngine.d.ts

@@ -0,0 +1,113 @@
+import { type ResolvedOptions, type RubiksCubeOptions, type Turn } from './types';
+export type CubeState = 'idle' | 'scrambling' | 'animating' | 'dragging' | 'snapping';
+export type CubeEvent = 'move' | 'scrambleStart' | 'scrambleEnd' | 'solved' | 'stateChange' | 'hoverChange';
+type Listener = (...args: unknown[]) => void;
+/**
+ * Framework-agnostic Rubik's cube renderer + mechanics. Mount it on any element:
+ *
+ *   const cube = new RubiksCubeEngine(document.querySelector('#cube'), { size: 3 });
+ *   cube.move("R U R' U'");
+ *   cube.dispose();
+ */
+export declare class RubiksCubeEngine {
+    readonly container: HTMLElement;
+    readonly canvas: HTMLCanvasElement;
+    options: ResolvedOptions;
+    private renderer;
+    private scene;
+    private camera;
+    private pmrem;
+    private envTexture;
+    private keyLight;
+    private shadowPlane?;
+    /** Floats, orbits and idle-spins. Everything cube-shaped lives inside. */
+    private cubeGroup;
+    private cubies;
+    private resources?;
+    private physics;
+    private raycaster;
+    private queue;
+    private active;
+    private drag;
+    private scrambleRemaining;
+    private scrambleResolve;
+    private hovering;
+    private idleEnabled;
+    private solved;
+    private timer;
+    private elapsed;
+    private rafId;
+    private disposed;
+    private resizeObserver?;
+    private touchLeaveTimer;
+    private listeners;
+    private mountTimer;
+    constructor(container: HTMLElement, options?: Partial<RubiksCubeOptions>);
+    get state(): CubeState;
+    get isHovering(): boolean;
+    isSolved(): boolean;
+    on(event: CubeEvent, listener: Listener): () => void;
+    off(event: CubeEvent, listener: Listener): void;
+    private emit;
+    /**
+     * Scramble with the physics flywheel: slow → fast → slow.
+     * Resolves when the last move has landed.
+     */
+    scramble(moves?: number): Promise<void>;
+    /** Apply moves in standard notation, e.g. `cube.move("R U R' U'")`. */
+    move(notation: string, duration?: number): Promise<void>;
+    /** Apply a single turn. `duration` 0 applies it instantly. */
+    turn(turn: Turn, duration?: number): Promise<void>;
+    /** Put every cubie back to the solved state immediately. */
+    reset(): void;
+    /** Programmatic hover (the same thing the mouse does). */
+    setHover(hovering: boolean): void;
+    /** Turn the idle float/spin on or off regardless of hover. */
+    setIdle(enabled: boolean): void;
+    /** Reset the cube's orientation (after orbiting / idle spinning). */
+    resetOrientation(): void;
+    /**
+     * Update options at runtime. Physics, interaction, background, exposure, shadow opacity and
+     * camera update in place; size/colours/sticker/geometry changes rebuild the cube (and reset it).
+     */
+    setOptions(partial: Partial<RubiksCubeOptions>): void;
+    /** Tear everything down and remove the canvas. */
+    dispose(): void;
+    private applyBackground;
+    private placeCamera;
+    private buildCube;
+    private disposeCubies;
+    private buildShadow;
+    private squareMode;
+    private resize;
+    private tick;
+    private updateIdle;
+    private applyIdleState;
+    private cubiesInLayers;
+    private beginTurn;
+    private setTurnAngle;
+    /** Detach cubies from the pivot, snap them to the grid, update logical state. */
+    private completeTurn;
+    /** Cancel the active turn without applying it (used by reset/rebuild). */
+    private abortActive;
+    private applyInstant;
+    private cancelQueue;
+    private finishScramble;
+    private updateTurn;
+    private updateSolved;
+    private computeSolved;
+    private bindPointerEvents;
+    private unbindPointerEvents;
+    private preventDefault;
+    private onPointerEnter;
+    private onPointerLeave;
+    private pointerNdc;
+    private pickCubie;
+    private toScreen;
+    private onPointerDown;
+    private onPointerMove;
+    /** Pick the rotation axis + layer from the grabbed face and the drag direction. */
+    private decideLayerDrag;
+    private onPointerUp;
+}
+export {};

package/dist/types/core/geometry.d.ts

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+import type { CubeColors, Face, ResolvedOptions } from './types';
+export declare const FACE_NORMALS: Record<Face, THREE.Vector3>;
+export interface StickerInfo {
+    face: Face;
+    /** Outward normal in the cubie's own (unrotated) frame. */
+    localNormal: THREE.Vector3;
+    mesh: THREE.Mesh;
+}
+export interface Cubie {
+    /** Group holding the plastic body and its stickers. Lives directly under the cube group. */
+    object: THREE.Group;
+    body: THREE.Mesh;
+    stickers: StickerInfo[];
+    /** Current logical grid position (integers for odd sizes, half-integers for even). */
+    grid: THREE.Vector3;
+    /** Grid position at solved state. */
+    home: THREE.Vector3;
+}
+/** Everything that has to be disposed when the cube is rebuilt. */
+export interface CubieResources {
+    geometries: THREE.BufferGeometry[];
+    materials: THREE.Material[];
+}
+export declare function makeBodyMaterial(colors: CubeColors): THREE.MeshPhysicalMaterial;
+export declare function makeStickerMaterial(color: string, roughness: number): THREE.MeshPhysicalMaterial;
+/**
+ * Build the `size³ − (size−2)³` visible cubies. Each cubie is a rounded black box
+ * with slightly raised, rounded, glossy stickers on its exposed faces.
+ */
+export declare function buildCubies(opts: ResolvedOptions): {
+    cubies: Cubie[];
+    resources: CubieResources;
+};
+/** Round a quaternion to the nearest of the 24 cube orientations (kills drift after a turn). */
+export declare function snapQuaternion(q: THREE.Quaternion): void;
+/** Snap a grid coordinate to the nearest half-integer (covers odd and even sizes). */
+export declare function snapGrid(v: THREE.Vector3): void;

package/dist/types/core/index.d.ts

@@ -0,0 +1,8 @@
+export { RubiksCubeEngine } from './RubiksCubeEngine';
+export type { CubeState, CubeEvent } from './RubiksCubeEngine';
+export { CubePhysics } from './physics';
+export { parseNotation, turnToNotation, randomScramble, layerCoordinates } from './notation';
+export { resolveOptions, DEFAULT_OPTIONS, DEFAULT_COLORS, DEFAULT_PHYSICS, DEFAULT_INTERACTION, DEFAULT_CAMERA, DEFAULT_STICKER, } from './types';
+export type { Axis, Face, Turn, CubeColors, PhysicsOptions, InteractionOptions, CameraOptions, StickerOptions, RubiksCubeOptions, ResolvedOptions, } from './types';
+export { createRubiksCube } from './mount';
+export type { RubiksCubeHandle } from './mount';

package/dist/types/core/mount.d.ts

@@ -0,0 +1,26 @@
+import { RubiksCubeEngine, type CubeEvent, type CubeState } from './RubiksCubeEngine';
+import type { RubiksCubeOptions, Turn } from './types';
+/** The small, stable surface most integrations need. The full engine is on `.engine`. */
+export interface RubiksCubeHandle {
+    engine: RubiksCubeEngine;
+    scramble(moves?: number): Promise<void>;
+    move(notation: string, duration?: number): Promise<void>;
+    turn(turn: Turn, duration?: number): Promise<void>;
+    reset(): void;
+    resetOrientation(): void;
+    isSolved(): boolean;
+    readonly state: CubeState;
+    setHover(hovering: boolean): void;
+    setIdle(enabled: boolean): void;
+    setOptions(options: Partial<RubiksCubeOptions>): void;
+    on(event: CubeEvent, listener: (...args: unknown[]) => void): () => void;
+    destroy(): void;
+}
+/**
+ * Mount a cube into any element (framework-free).
+ *
+ *   const cube = createRubiksCube(document.getElementById('cube'), { size: 3 });
+ *   cube.move("R U R' U'");
+ *   cube.destroy();
+ */
+export declare function createRubiksCube(container: HTMLElement | string, options?: Partial<RubiksCubeOptions>): RubiksCubeHandle;

package/dist/types/core/notation.d.ts

@@ -0,0 +1,7 @@
+import type { Turn } from './types';
+export declare function layerCoordinates(size: number): number[];
+export declare function parseNotation(notation: string, size: number): Turn[];
+/** Turn → notation string (inverse of parseNotation for common cases). */
+export declare function turnToNotation(turn: Turn, size: number): string;
+/** Random scramble: no two consecutive moves on the same axis+layer, no immediate undo. */
+export declare function randomScramble(size: number, moves: number, rng?: () => number): Turn[];

package/dist/types/core/physics.d.ts

@@ -0,0 +1,60 @@
+import type { PhysicsOptions } from './types';
+/**
+ * All the "feel" of the cube comes from a tiny Matter.js world with three bodies:
+ *
+ *  • flywheel  – a mass on a frictionless rail. While the scramble spins up we push it;
+ *                afterwards air friction bleeds the speed off. Its velocity IS the
+ *                angular speed of the current scramble turn, which is what produces the
+ *                slow → fast → slow envelope instead of a canned easing curve.
+ *  • floater   – a mass on a soft spring. The anchor moves between "resting" and
+ *                "lifted"; a small periodic force makes it bob. Its y is the cube's
+ *                hover offset.
+ *  • snapper   – a mass on a stiffer, under-damped spring. When you let go of a layer
+ *                mid-turn its position is the layer angle and the anchor is the nearest
+ *                90°, so layers settle with a real spring wobble.
+ */
+export declare class CubePhysics {
+    private readonly engine;
+    private readonly flywheel;
+    private readonly floater;
+    private readonly floatSpring;
+    private readonly snapper;
+    private readonly snapSpring;
+    private opts;
+    private accumulator;
+    private elapsed;
+    private spinningUp;
+    private bobbing;
+    private snapping;
+    constructor(opts: PhysicsOptions);
+    setOptions(opts: PhysicsOptions): void;
+    /** Reset the flywheel so the next scramble starts from the slow end. */
+    resetFlywheel(): void;
+    /** While true, the flywheel is pushed each step (the "getting faster" half of a scramble). */
+    setSpinningUp(on: boolean): void;
+    /** Current scramble turn speed in rad/s, clamped to [minSpeed, maxSpeed]. */
+    get scrambleSpeed(): number;
+    /** Raw flywheel velocity (for diagnostics / tuning). */
+    get flywheelVelocity(): number;
+    /**
+     * How many quarter turns the flywheel will still travel while coasting from its
+     * current speed down to `minSpeed` under air friction. The scramble uses this to
+     * decide when to stop pushing so the last move lands right at the slow end.
+     */
+    get quarterTurnsToCoast(): number;
+    /** Height (world units) the float spring pulls toward. */
+    setFloatTarget(y: number): void;
+    setBobbing(on: boolean): void;
+    /** Current vertical offset of the cube. */
+    get floatY(): number;
+    /** Start a spring snap from `angle` (with current angular velocity) toward `target`. */
+    beginSnap(angle: number, velocity: number, target: number): void;
+    endSnap(): void;
+    get snapAngle(): number;
+    get snapTarget(): number;
+    get snapSettled(): boolean;
+    /** Advance the world by `dtSeconds` using fixed 60 Hz sub-steps. */
+    step(dtSeconds: number): void;
+    private substep;
+    dispose(): void;
+}

package/dist/types/core/types.d.ts

@@ -0,0 +1,150 @@
+/** Axis of rotation in the cube's own coordinate frame. */
+export type Axis = 'x' | 'y' | 'z';
+/** Standard face names. U=up(+y) D=down(-y) F=front(+z) B=back(-z) L=left(-x) R=right(+x) */
+export type Face = 'U' | 'D' | 'F' | 'B' | 'L' | 'R';
+export interface CubeColors {
+    U: string;
+    D: string;
+    F: string;
+    B: string;
+    L: string;
+    R: string;
+    /** Plastic body colour. */
+    body: string;
+}
+/**
+ * A turn of one or more layers around one axis.
+ * `layers` are grid coordinates along `axis` (e.g. -1, 0, 1 on a 3x3; ±0.5 on a 2x2).
+ * A face move has one layer, a wide move two, a whole-cube rotation all of them.
+ */
+export interface Turn {
+    axis: Axis;
+    layers: number[];
+    /** Signed quarter turns. +1 = 90° counter-clockwise around the +axis (right-hand rule). */
+    quarterTurns: number;
+}
+export interface PhysicsOptions {
+    /**
+     * Force applied to the scramble "flywheel" while it spins up.
+     * Bigger = the scramble reaches top speed sooner. Default 0.00066.
+     */
+    scrambleForce: number;
+    /** Air friction on the flywheel (0..1). Controls how fast the scramble slows down. Default 0.013. */
+    scrambleFriction: number;
+    /** Top angular speed of a scramble turn, rad/s. Default 11. */
+    maxSpeed: number;
+    /** Minimum angular speed of a scramble turn, rad/s (the "slow" ends). Default 1.6. */
+    minSpeed: number;
+    /** How high the cube lifts while idle, in world units (a cubie is 1 unit). Default 0.22. */
+    floatLift: number;
+    /** Amplitude of the idle bobbing, world units. Default 0.09. */
+    floatAmplitude: number;
+    /** Bobbing frequency, Hz. Default 0.45. */
+    floatFrequency: number;
+    /** Stiffness (0..1) of the spring that carries the cube up/down between idle and hover. Default 0.004. */
+    floatStiffness: number;
+    /** Damping (0..1) of that spring. Default 0.03. */
+    floatDamping: number;
+    /** Idle spin speed around the vertical axis, rad/s. Default 0.25. */
+    idleSpin: number;
+    /** Extra idle tumble around the horizontal axis, rad/s. Default 0.06. */
+    idleTumble: number;
+    /** Stiffness (0..1) of the spring that snaps a dragged layer to the nearest 90°. Default 0.03. */
+    snapStiffness: number;
+    /** Damping (0..1) of the snap spring. Lower = more wobble. Default 0.07. */
+    snapDamping: number;
+}
+export interface InteractionOptions {
+    /** Master switch for pointer interaction. Default true. */
+    enabled: boolean;
+    /** Pixels of drag for one quarter turn of a layer. Default 110. */
+    dragPixelsPerQuarterTurn: number;
+    /** Allow dragging on empty space to orbit the whole cube. Default true. */
+    orbit: boolean;
+    /** Orbit sensitivity, radians per pixel. Default 0.008. */
+    orbitSensitivity: number;
+    /** Allow the user to interrupt a running scramble by grabbing the cube. Default false. */
+    interruptScramble: boolean;
+}
+export interface CameraOptions {
+    /** Distance from the cube centre, in cubie units. Default 3.5 * size. */
+    distance?: number;
+    /** Vertical field of view in degrees. Default 32. */
+    fov: number;
+    /** Camera elevation above the horizon, degrees. Default 31. */
+    pitch: number;
+    /** Camera rotation around the vertical axis, degrees. Default 38. */
+    yaw: number;
+}
+export interface StickerOptions {
+    /** Sticker width as a fraction of the cubie. Default 0.84. */
+    inset: number;
+    /** Corner radius as a fraction of the cubie. Default 0.09. */
+    cornerRadius: number;
+    /** Sticker relief height. Default 0.018. */
+    height: number;
+    /** Roughness of the sticker vinyl (0 = mirror). Default 0.28. */
+    roughness: number;
+}
+export interface RubiksCubeOptions {
+    /** Cubies per edge. 2..7 supported. Default 3. */
+    size: number;
+    /** Canvas background: 'transparent' (default), any CSS colour, or a CSS gradient/image. */
+    background: string;
+    colors: Partial<CubeColors>;
+    /** Scramble the cube as soon as it is mounted. Default true. */
+    scrambleOnMount: boolean;
+    /** Number of random moves in a scramble. Default 25. */
+    scrambleMoves: number;
+    /** Delay before the mount scramble starts, ms. Default 350. */
+    scrambleDelay: number;
+    /** Duration of a programmatic `move()` in ms. Default 260. */
+    moveDuration: number;
+    physics: Partial<PhysicsOptions>;
+    interaction: Partial<InteractionOptions>;
+    camera: Partial<CameraOptions>;
+    sticker: Partial<StickerOptions>;
+    /** Soft contact shadow underneath the cube. Default true. */
+    shadow: boolean;
+    /** Shadow opacity 0..1. Default 0.28. */
+    shadowOpacity: number;
+    /** Shadow map resolution (power of two). Lower it on weak GPUs. Default 2048. */
+    shadowMapSize: number;
+    /** Cubie corner rounding, as a fraction of a cubie. Default 0.1. */
+    cubieRounding: number;
+    /** Gap between cubies, as a fraction of a cubie. Default 0.035. */
+    cubieGap: number;
+    /** Cap on device pixel ratio. Default 2. */
+    maxPixelRatio: number;
+    antialias: boolean;
+    /** Overall brightness of the reflections/lighting. Default 1. */
+    exposure: number;
+    /** Start floating/spinning even before the first mouse-leave. Default true. */
+    idleOnMount: boolean;
+    /** Fired after every completed turn (user drag, scramble, or API). */
+    onMove?: (turn: Turn, notation: string) => void;
+    onScrambleStart?: () => void;
+    onScrambleEnd?: () => void;
+    /** Fired when the cube becomes solved after a turn. */
+    onSolved?: () => void;
+    /** Fired when the cube state changes; `solved` is the current state. */
+    onStateChange?: (solved: boolean) => void;
+    onHoverChange?: (hovering: boolean) => void;
+}
+export declare const DEFAULT_COLORS: CubeColors;
+export declare const DEFAULT_PHYSICS: PhysicsOptions;
+export declare const DEFAULT_INTERACTION: InteractionOptions;
+export declare const DEFAULT_CAMERA: CameraOptions;
+export declare const DEFAULT_STICKER: StickerOptions;
+export declare const DEFAULT_OPTIONS: RubiksCubeOptions;
+/** Fully resolved options with every default applied. */
+export interface ResolvedOptions extends Omit<RubiksCubeOptions, 'colors' | 'physics' | 'interaction' | 'camera' | 'sticker'> {
+    colors: CubeColors;
+    physics: PhysicsOptions;
+    interaction: InteractionOptions;
+    camera: CameraOptions;
+    sticker: StickerOptions;
+}
+/** Drop `undefined` values so they never override a default (React passes unset props as undefined). */
+export declare function compact<T extends object>(obj: T | undefined): Partial<T>;
+export declare function resolveOptions(user?: Partial<RubiksCubeOptions>): ResolvedOptions;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export { RubiksCube, default } from './RubiksCube';
+export type { RubiksCubeProps, RubiksCubeRef } from './RubiksCube';

package/dist/types/standalone.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Standalone build — no React, three.js and Matter.js bundled in.
+ *
+ *   <script src="https://unpkg.com/rubiks-cube-3d/dist/rubiks-cube-3d.standalone.js"></script>
+ *
+ *   // 1. declarative: any element with data-rubiks-cube is mounted automatically
+ *   <div data-rubiks-cube data-size="3" data-background="transparent"
+ *        data-options='{"physics":{"idleSpin":0.4}}' style="width:320px"></div>
+ *
+ *   // 2. imperative
+ *   const cube = RubiksCube3D.mount('#cube', { size: 4 });
+ *   cube.move("R U R' U'");
+ */
+import { createRubiksCube, type RubiksCubeHandle } from './core/mount';
+export * from './core';
+export { createRubiksCube as mount };
+/** Mount every `[data-rubiks-cube]` element that is not mounted yet. */
+export declare function autoMount(root?: ParentNode): RubiksCubeHandle[];
+/** Get the handle for an auto-mounted element. */
+export declare function get(el: Element): RubiksCubeHandle | undefined;

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "rubiks-cube-3d",
+  "version": "1.0.0",
+  "description": "A realistic, physics-driven, interactive 3D Rubik's cube built with three.js and Matter.js. Ships as a React component and as a standalone script for any website.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "rubiks",
+    "cube",
+    "three",
+    "threejs",
+    "matter-js",
+    "react",
+    "3d",
+    "physics",
+    "interactive"
+  ],
+  "main": "./dist/rubiks-cube-3d.umd.cjs",
+  "module": "./dist/rubiks-cube-3d.js",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "./dist/rubiks-cube-3d.standalone.js",
+  "jsdelivr": "./dist/rubiks-cube-3d.standalone.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/rubiks-cube-3d.js",
+      "require": "./dist/rubiks-cube-3d.umd.cjs"
+    },
+    "./core": {
+      "types": "./dist/types/core/index.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./standalone": "./dist/rubiks-cube-3d.standalone.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": [
+    "./dist/rubiks-cube-3d.standalone.js"
+  ],
+  "scripts": {
+    "dev": "vite --config vite.demo.config.ts",
+    "build": "npm run build:lib && npm run build:standalone && npm run build:types",
+    "build:lib": "BUILD_TARGET=lib vite build",
+    "build:standalone": "BUILD_TARGET=standalone vite build",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build:demo": "vite build --config vite.demo.config.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "matter-js": "^0.20.0",
+    "three": "^0.185.1"
+  },
+  "devDependencies": {
+    "@types/matter-js": "^0.20.2",
+    "@types/node": "^22.20.1",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@types/three": "^0.185.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.2.2"
+  }
+}