react-rubiks-cube 0.1.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "react-rubiks-cube",
+  "version": "0.1.0",
+  "description": "A beautiful, self-solving 3D Rubik's Cube React component — auto scramble/solve loop, drag-to-turn interaction, and a fully themeable palette. Built on react-three-fiber.",
+  "type": "module",
+  "license": "MIT",
+  "author": "chahe-dridi",
+  "homepage": "https://github.com/chahe-dridi/cubex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chahe-dridi/cubex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chahe-dridi/cubex/issues"
+  },
+  "keywords": [
+    "react",
+    "rubiks-cube",
+    "rubik",
+    "cube",
+    "three",
+    "three-js",
+    "react-three-fiber",
+    "3d",
+    "animation",
+    "hero",
+    "component"
+  ],
+  "main": "./dist/cubex.umd.cjs",
+  "module": "./dist/cubex.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/cubex.js",
+      "require": "./dist/cubex.umd.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview --outDir example-dist",
+    "prepare": "vite build"
+  },
+  "peerDependencies": {
+    "@react-three/drei": ">=9.0.0",
+    "@react-three/fiber": ">=8.0.0",
+    "framer-motion": ">=10.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "three": ">=0.150.0"
+  },
+  "devDependencies": {
+    "@react-three/drei": "^9.122.0",
+    "@react-three/fiber": "^8.18.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "framer-motion": "^11.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "three": "^0.186.1",
+    "vite": "^5.3.4"
+  }
+}

package/src/AutoCubeScene.jsx

@@ -0,0 +1,190 @@
+import { useRef } from 'react'
+import { useFrame } from '@react-three/fiber'
+import * as THREE from 'three'
+import { Cubelet, smoother, useCubePositions } from './primitives.jsx'
+
+// ── Move helpers ──────────────────────────────────────────
+const AXES = ['x', 'y', 'z']
+const randDir = () => (Math.random() < 0.5 ? 1 : -1)
+
+// One random legal move, avoiding an immediate inverse of the last move (which
+// would read like an undo). Mostly quarter turns, occasionally a half turn.
+function randMove(last) {
+  for (let i = 0; i < 8; i++) {
+    const axis = AXES[(Math.random() * 3) | 0]
+    const layer = [-1, 0, 1][(Math.random() * 3) | 0]
+    const dir = randDir()
+    const quarter = Math.random() < 0.82 ? 1 : 2
+    if (last && last.axis === axis && last.layer === layer && last.dir === -dir && last.quarter === quarter) continue
+    return { axis, layer, dir, quarter }
+  }
+  return { axis: 'y', layer: 1, dir: 1, quarter: 1 }
+}
+
+// Cubelets in the given layer of the given axis (null layer = all cubelets).
+function layerChildren(children, axis, layer) {
+  if (layer === null) return children
+  return children.filter(c => {
+    const v = c.position[axis]
+    return layer === 0 ? Math.abs(v) < 0.5 : layer > 0 ? v > 0.5 : v < -0.5
+  })
+}
+
+// Reusable quaternions — never re-allocated per frame.
+const _dq = new THREE.Quaternion()
+const _pq1 = new THREE.Quaternion()
+const _pq2 = new THREE.Quaternion()
+const _pq3 = new THREE.Quaternion()
+
+// Three fixed precession axes, chosen incommensurate so the whole-cube tumble
+// never visibly repeats within a practical viewing window.
+const PREC1 = new THREE.Vector3(0.58, 0.77, -0.27).normalize()
+const PREC2 = new THREE.Vector3(-0.41, 0.35, 0.84).normalize()
+const PREC3 = new THREE.Vector3(0.22, -0.62, 0.75).normalize()
+
+// Build one scramble "step":
+//   • ~16% a 360° double-spin flourish (identity → not recorded)
+//   • ~38% two parallel layers of the SAME axis turning together
+//   • else a single quarter/half turn
+// `record` is what must be reversed later to solve (null for the flourish).
+function buildScrambleStep(prev) {
+  const roll = Math.random()
+  if (roll < 0.16) {
+    const move = { axis: AXES[(Math.random() * 3) | 0], layer: [-1, 0, 1][(Math.random() * 3) | 0], dir: randDir(), quarter: 4 }
+    return { moves: [move], record: null }
+  }
+  if (roll < 0.54) {
+    const axis = AXES[(Math.random() * 3) | 0]
+    const ls = [-1, 0, 1]
+    const i1 = (Math.random() * 3) | 0
+    let i2 = (Math.random() * 3) | 0
+    while (i2 === i1) i2 = (Math.random() * 3) | 0
+    const moves = [i1, i2].map(i => ({ axis, layer: ls[i], dir: randDir(), quarter: Math.random() < 0.25 ? 2 : 1 }))
+    return { moves, record: moves }
+  }
+  const move = randMove(prev)
+  return { moves: [move], record: [move] }
+}
+
+// Re-parent a layer's cubelets onto a rotation pivot and arm its tween. Each
+// slice gets its own duration so two concurrent turns finish at different times.
+function startSlot(slot, rotEl, cube, move) {
+  layerChildren(cube.children.slice(), move.axis, move.layer).forEach(c => rotEl.attach(c))
+  slot.ref = rotEl
+  slot.axis = move.axis
+  slot.target = (Math.PI / 2) * move.dir * move.quarter
+  slot.elapsed = 0
+  slot.duration = 0.42 * move.quarter + 0.16 + Math.random() * 0.3
+  slot.active = true
+}
+
+// ══════════════════════════════════════════════════════════
+// Auto-playing cube: whole-cube tumble + scramble→solve loop.
+// Renders inside a parent <Canvas>. `scrollRef` is an optional ref holding a
+// 0..1 scroll progress used to tilt the cube.
+// ══════════════════════════════════════════════════════════
+export function AutoCubeScene({ palette, scrollRef, scale = 0.72, tumble = true, autoplay = true }) {
+  const tiltRef = useRef() // outermost: scroll tilt only
+  const pivotRef = useRef() // whole-cube tumble + bob + scale
+  const cubeRef = useRef() // holds the 27 cubelets at integer grid positions
+  const rotRefA = useRef() // rotation pivot for slice A
+  const rotRefB = useRef() // rotation pivot for slice B (concurrent turns)
+
+  const spinDir = useRef(new THREE.Vector3(0.3, 0.88, 0.36).normalize())
+  const slots = useRef([
+    { active: false, ref: null, axis: 'y', target: 0, elapsed: 0, duration: 0 },
+    { active: false, ref: null, axis: 'y', target: 0, elapsed: 0, duration: 0 },
+  ])
+  // Player state machine: scramble a handful of moves, then solve back, forever.
+  const P = useRef({ phase: 'scramble', history: [], remaining: 7, idle: 1.0, prevMove: null })
+
+  const positions = useCubePositions()
+
+  useFrame((state, delta) => {
+    if (!pivotRef.current || !tiltRef.current || !cubeRef.current || !rotRefA.current || !rotRefB.current) return
+    const t = state.clock.elapsedTime
+    const cube = cubeRef.current
+    const m = P.current
+    const S = slots.current
+
+    // ── Whole-cube tumble on the PARENT pivot (cancels out of slice maths) ──
+    if (tumble) {
+      _pq1.setFromAxisAngle(PREC1, 0.2 * delta)
+      _pq2.setFromAxisAngle(PREC2, 0.125 * delta)
+      _pq3.setFromAxisAngle(PREC3, 0.075 * delta)
+      spinDir.current.applyQuaternion(_pq1).applyQuaternion(_pq2).applyQuaternion(_pq3).normalize()
+
+      const swell = Math.sin(t * 0.11) * 0.5 + Math.sin(t * 0.047 + 1.3) * 0.3 + Math.sin(t * 0.19 + 0.6) * 0.18
+      const speed = 0.72 + swell * 0.34
+      _dq.setFromAxisAngle(spinDir.current, speed * delta)
+      pivotRef.current.quaternion.premultiply(_dq)
+      pivotRef.current.position.y = Math.sin(t * 0.6) * 0.09
+    }
+
+    // ── Scroll tilt on the outer wrapper ──
+    if (scrollRef) {
+      const sp = scrollRef.current || 0
+      const tiltK = 1 - Math.pow(0.05, delta)
+      tiltRef.current.rotation.x = THREE.MathUtils.lerp(tiltRef.current.rotation.x, sp * -0.36, tiltK)
+    }
+
+    // ── Auto slice player: scramble → solve loop, 1 or 2 turns at a time ──
+    const busy = S[0].active || S[1].active
+    if (autoplay && !busy) {
+      m.idle -= delta
+      if (m.idle <= 0) {
+        let moves
+        if (m.phase === 'scramble') {
+          const step = buildScrambleStep(m.prevMove)
+          moves = step.moves
+          if (step.record) m.history.push(step.record)
+          if (m.history.length >= m.remaining) m.phase = 'solve'
+        } else {
+          const step = m.history.pop()
+          moves = step.map(mm => ({ axis: mm.axis, layer: mm.layer, dir: -mm.dir, quarter: mm.quarter }))
+        }
+        m.prevMove = moves[moves.length - 1]
+        startSlot(S[0], rotRefA.current, cube, moves[0])
+        if (moves[1]) startSlot(S[1], rotRefB.current, cube, moves[1])
+      }
+    }
+
+    // Advance each active slot independently (desynced finish).
+    for (const s of S) {
+      if (!s.active) continue
+      s.elapsed = Math.min(s.elapsed + delta, s.duration)
+      s.ref.rotation[s.axis] = s.target * smoother(s.elapsed / s.duration)
+      if (s.elapsed >= s.duration) {
+        s.ref.rotation[s.axis] = s.target
+        s.ref.children.slice().forEach(c => cube.attach(c))
+        s.ref.rotation.set(0, 0, 0)
+        s.active = false
+      }
+    }
+
+    // Step just completed → schedule the next.
+    if (busy && !S[0].active && !S[1].active) {
+      if (m.phase === 'solve' && m.history.length === 0) {
+        m.phase = 'scramble'
+        m.remaining = 7 + ((Math.random() * 6) | 0)
+        m.idle = 1.8 + Math.random() * 1.5 // linger on the solved cube
+      } else {
+        m.idle = 0.12 + Math.random() * 0.4 // brief pause between turns
+      }
+    }
+  })
+
+  return (
+    <group ref={tiltRef}>
+      <group ref={pivotRef} scale={[scale, scale, scale]}>
+        <group ref={cubeRef}>
+          {positions.map(([x, y, z]) => (
+            <Cubelet key={`${x + 1}${y + 1}${z + 1}`} px={x} py={y} pz={z} palette={palette} />
+          ))}
+        </group>
+        <group ref={rotRefA} />
+        <group ref={rotRefB} />
+      </group>
+    </group>
+  )
+}

package/src/CubeOverlay.jsx

@@ -0,0 +1,211 @@
+import { useState, useRef, useCallback } from 'react'
+import { createPortal } from 'react-dom'
+import { Canvas } from '@react-three/fiber'
+import { OrbitControls } from '@react-three/drei'
+import { AnimatePresence, motion } from 'framer-motion'
+import { Lights } from './primitives.jsx'
+import { InteractiveCubeScene, MOVE_GROUPS } from './InteractiveCubeScene.jsx'
+
+// Small reusable move button with a hover colour accent.
+function MoveBtn({ label, accent, onClick }) {
+  const [hov, setHov] = useState(false)
+  const isPrime = label.includes("'")
+  return (
+    <motion.button
+      whileTap={{ scale: 0.9 }}
+      onClick={onClick}
+      onMouseEnter={() => setHov(true)}
+      onMouseLeave={() => setHov(false)}
+      style={{
+        flex: 1,
+        border: `1px solid ${hov ? accent : 'rgba(255,255,255,0.08)'}`,
+        background: hov ? `${accent}22` : 'rgba(255,255,255,0.03)',
+        color: hov ? '#fff' : 'rgba(240,235,226,0.65)',
+        borderRadius: 6,
+        padding: '5px 0',
+        fontSize: 11,
+        fontWeight: 700,
+        cursor: 'pointer',
+        fontFamily: "'DM Mono', monospace",
+        transition: 'all 0.12s',
+        textAlign: 'center',
+        letterSpacing: isPrime ? '-0.02em' : '0.04em',
+      }}
+    >
+      {label}
+    </motion.button>
+  )
+}
+
+// ══════════════════════════════════════════════════════════
+// Fullscreen interactive overlay: a large drag-to-turn cube plus a control
+// panel of Rubik's-notation buttons. Rendered into document.body via a portal.
+// ══════════════════════════════════════════════════════════
+export function CubeOverlay({ onClose, palette, accent = '#E05C28', cameraPosition = [5, 4, 5], fov = 34 }) {
+  const [mode, setMode] = useState('orbit')
+  const modeRef = useRef('orbit')
+  const queueRef = useRef([])
+
+  const changeMode = useCallback(m => {
+    modeRef.current = m
+    setMode(m)
+  }, [])
+  const pushMove = useCallback(move => queueRef.current.push(move), [])
+
+  return createPortal(
+    <AnimatePresence>
+      <motion.div
+        key="cube-overlay"
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        exit={{ opacity: 0 }}
+        transition={{ duration: 0.2 }}
+        style={{
+          position: 'fixed',
+          inset: 0,
+          zIndex: 9999,
+          background: 'rgba(7, 6, 5, 0.65)',
+          backdropFilter: 'blur(20px)',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          gap: 28,
+          fontFamily: 'system-ui, sans-serif',
+        }}
+        onClick={e => {
+          if (e.target === e.currentTarget) onClose()
+        }}
+      >
+        <button
+          onClick={onClose}
+          aria-label="Close"
+          style={{
+            position: 'absolute',
+            top: 20,
+            right: 22,
+            background: 'rgba(255,255,255,0.04)',
+            border: '1px solid rgba(255,255,255,0.09)',
+            color: 'rgba(255,255,255,0.35)',
+            borderRadius: 9,
+            width: 36,
+            height: 36,
+            fontSize: 18,
+            cursor: 'pointer',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            transition: 'all 0.15s',
+          }}
+        >
+          ×
+        </button>
+
+        {/* 3-D canvas */}
+        <motion.div
+          initial={{ scale: 0.6, opacity: 0 }}
+          animate={{ scale: 1, opacity: 1 }}
+          exit={{ scale: 0.6, opacity: 0 }}
+          transition={{ type: 'spring', damping: 20, stiffness: 180 }}
+          style={{
+            width: 'min(460px, 78vw)',
+            height: 'min(460px, 78vw)',
+            flexShrink: 0,
+            borderRadius: 20,
+            cursor: mode === 'move' ? 'crosshair' : 'grab',
+            overflow: 'hidden',
+          }}
+        >
+          <Canvas flat camera={{ position: cameraPosition, fov }} gl={{ antialias: true, alpha: true }} style={{ background: 'transparent' }}>
+            <Lights ambient={0.4} />
+            <InteractiveCubeScene palette={palette} queueRef={queueRef} modeRef={modeRef} />
+            <OrbitControls enabled={mode === 'orbit'} autoRotate={false} enablePan={false} enableZoom={false} dampingFactor={0.08} enableDamping rotateSpeed={0.65} />
+          </Canvas>
+        </motion.div>
+
+        {/* Control panel */}
+        <motion.div
+          initial={{ x: 44, opacity: 0 }}
+          animate={{ x: 0, opacity: 1 }}
+          exit={{ x: 44, opacity: 0 }}
+          transition={{ type: 'spring', damping: 22, stiffness: 180, delay: 0.06 }}
+          style={{
+            width: 196,
+            background: 'rgba(255,255,255,0.025)',
+            border: '1px solid rgba(255,255,255,0.07)',
+            borderRadius: 16,
+            overflow: 'hidden',
+            flexShrink: 0,
+          }}
+        >
+          <div style={{ padding: '14px 14px 10px', borderBottom: '1px solid rgba(255,255,255,0.05)' }}>
+            <p style={{ fontSize: 9, fontWeight: 700, letterSpacing: '0.22em', textTransform: 'uppercase', color: 'rgba(255,255,255,0.22)', marginBottom: 10 }}>Controls</p>
+            <div style={{ display: 'flex', background: 'rgba(0,0,0,0.35)', borderRadius: 9, padding: 3, gap: 2 }}>
+              {[
+                { id: 'orbit', icon: '⟳', label: 'Orbit' },
+                { id: 'move', icon: '✦', label: 'Move' },
+              ].map(({ id, icon, label }) => (
+                <button
+                  key={id}
+                  onClick={() => changeMode(id)}
+                  style={{
+                    flex: 1,
+                    border: 'none',
+                    borderRadius: 7,
+                    padding: '6px 0',
+                    fontSize: 10.5,
+                    fontWeight: 700,
+                    cursor: 'pointer',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    gap: 4,
+                    transition: 'all 0.15s',
+                    background: mode === id ? accent : 'transparent',
+                    color: mode === id ? '#fff' : 'rgba(255,255,255,0.35)',
+                  }}
+                >
+                  <span style={{ fontSize: 11 }}>{icon}</span>
+                  {label}
+                </button>
+              ))}
+            </div>
+            <p style={{ marginTop: 8, fontSize: 9.5, lineHeight: 1.45, color: 'rgba(255,255,255,0.2)' }}>
+              {mode === 'orbit' ? 'Drag to orbit · buttons to move' : 'Swipe a face to rotate · or use buttons'}
+            </p>
+          </div>
+
+          {MOVE_GROUPS.map(({ id, label, accent: groupAccent, pairs }, gi) => (
+            <div key={id} style={{ borderBottom: gi < MOVE_GROUPS.length - 1 ? '1px solid rgba(255,255,255,0.045)' : 'none', padding: '8px 10px 9px' }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 5, marginBottom: 6 }}>
+                <span style={{ width: 5, height: 5, borderRadius: '50%', background: groupAccent, flexShrink: 0, opacity: 0.85 }} />
+                <span style={{ fontSize: 9, fontWeight: 700, letterSpacing: '0.16em', textTransform: 'uppercase', color: 'rgba(255,255,255,0.2)' }}>{label}</span>
+              </div>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
+                {pairs.map(([cw, ccw], pi) => (
+                  <div key={pi} style={{ display: 'flex', gap: 3 }}>
+                    {[cw, ccw].map(({ n, axis, layer, dir }) => (
+                      <MoveBtn key={n} label={n} accent={groupAccent} onClick={() => pushMove({ axis, layer, dir })} />
+                    ))}
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+
+          <div style={{ padding: '8px 14px 12px', borderTop: '1px solid rgba(255,255,255,0.04)' }}>
+            <p style={{ fontSize: 9, color: 'rgba(255,255,255,0.15)', lineHeight: 1.5, letterSpacing: '0.04em' }}>
+              Notation: prime (′) = counter-clockwise
+              <br />
+              U=Up D=Down R=Right L=Left
+              <br />
+              F=Front B=Back M=Mid E=Eq S=Std
+              <br />
+              x/y/z = whole-cube rotation
+            </p>
+          </div>
+        </motion.div>
+      </motion.div>
+    </AnimatePresence>,
+    document.body,
+  )
+}

package/src/InteractiveCubeScene.jsx

@@ -0,0 +1,196 @@
+import { useRef, useCallback } from 'react'
+import { useFrame, useThree } from '@react-three/fiber'
+import * as THREE from 'three'
+import { Cubelet, smoother, useCubePositions } from './primitives.jsx'
+
+// Which cubelet layer a given axis value sits in.
+function layerOf(v) {
+  return v > 0.5 ? 1 : v < -0.5 ? -1 : 0
+}
+
+// Map (faceNormal, cubelet position, screen drag delta) → { axis, layer, dir }.
+// Picks whichever in-face rotation axis best matches the drag direction on
+// screen, then the layer that cubelet belongs to.
+function computeSlideMove(faceNormal, cubeletPos, dragDx, dragDy, camera) {
+  const axes = ['x', 'y', 'z']
+  const faceAxis = axes.reduce((best, ax) => (Math.abs(faceNormal[ax]) > Math.abs(faceNormal[best]) ? ax : best), 'x')
+
+  const candidates = axes.filter(a => a !== faceAxis)
+  const len = Math.sqrt(dragDx * dragDx + dragDy * dragDy)
+  if (len < 1) return null
+
+  const results = candidates.map(rotAxis => {
+    const A = new THREE.Vector3(rotAxis === 'x' ? 1 : 0, rotAxis === 'y' ? 1 : 0, rotAxis === 'z' ? 1 : 0)
+    const tangent = new THREE.Vector3().crossVectors(A, faceNormal.clone().normalize())
+    const camT = tangent.clone().applyMatrix4(camera.matrixWorldInverse).normalize()
+    const dot = (camT.x * dragDx + -camT.y * dragDy) / len
+    return { rotAxis, dot }
+  })
+
+  const winner = results.reduce((a, b) => (Math.abs(a.dot) > Math.abs(b.dot) ? a : b))
+  const layer = layerOf(cubeletPos[winner.rotAxis])
+  return { axis: winner.rotAxis, layer, dir: winner.dot > 0 ? 1 : -1 }
+}
+
+// ══════════════════════════════════════════════════════════
+// Interactive cube: drag a face to turn a slice, or feed moves through a
+// queue ref (from external buttons). Auto-solves back to the start after
+// `autoReturnAfter` seconds of idle. Renders inside a parent <Canvas>.
+// ══════════════════════════════════════════════════════════
+export function InteractiveCubeScene({ palette, queueRef, modeRef, autoReturnAfter = 4, idleSpin = 0.28 }) {
+  const orbitRef = useRef() // outer wrapper; only the idle auto-spin touches this
+  const cubeRef = useRef()
+  const rotRef = useRef()
+  const anim = useRef({ active: false, axis: 'y', start: 0, target: 0, elapsed: 0, duration: 0.3 })
+  const dragRef = useRef(null)
+  const spinAngle = useRef(0)
+  const history = useRef([]) // moves applied so far (for auto-return)
+  const idleTimer = useRef(0)
+  const isReturning = useRef(false)
+  const { camera } = useThree()
+
+  const positions = useCubePositions()
+
+  useFrame((_, delta) => {
+    const a = anim.current
+    const cube = cubeRef.current
+    const rot = rotRef.current
+    if (!cube || !rot) return
+
+    // Dequeue next move.
+    if (!a.active && queueRef.current.length > 0) {
+      const move = queueRef.current.shift()
+      const { axis, layer, dir } = move
+      if (!isReturning.current) {
+        history.current.push(move)
+        idleTimer.current = 0
+      }
+      const all = cube.children.slice()
+      const toRot =
+        layer === null
+          ? all
+          : all.filter(c => {
+              const v = c.position[axis]
+              return layer === 0 ? Math.abs(v) < 0.5 : layer > 0 ? v > 0.5 : v < -0.5
+            })
+      toRot.forEach(c => rot.attach(c))
+      anim.current = { active: true, axis, start: 0, target: (Math.PI / 2) * dir, elapsed: 0, duration: 0.42 }
+    }
+
+    // Tween the active move — smootherstep for a silky, jerk-free turn.
+    if (a.active) {
+      a.elapsed = Math.min(a.elapsed + delta, a.duration)
+      const ease = smoother(a.elapsed / a.duration)
+      rot.rotation[a.axis] = a.start + (a.target - a.start) * ease
+      if (a.elapsed >= a.duration) {
+        rot.rotation[a.axis] = a.target
+        rot.children.slice().forEach(c => cube.attach(c))
+        rot.rotation.set(0, 0, 0)
+        a.active = false
+        if (isReturning.current && queueRef.current.length === 0) {
+          isReturning.current = false
+          history.current = []
+        }
+      }
+    }
+
+    // Auto-return: after idle with scramble history, reverse every move.
+    if (autoReturnAfter > 0 && !a.active && queueRef.current.length === 0 && history.current.length > 0 && !isReturning.current) {
+      idleTimer.current += delta
+      if (idleTimer.current >= autoReturnAfter) {
+        isReturning.current = true
+        idleTimer.current = 0
+        const reversed = history.current
+          .slice()
+          .reverse()
+          .map(m => ({ ...m, dir: -m.dir }))
+        queueRef.current.push(...reversed)
+      }
+    }
+
+    // Idle auto-spin — on the OUTER wrapper only, never on cubeRef.
+    if (idleSpin > 0 && !a.active && queueRef.current.length === 0 && orbitRef.current) {
+      spinAngle.current += delta * idleSpin
+      orbitRef.current.rotation.y = spinAngle.current
+    }
+  })
+
+  const onPointerDown = useCallback(
+    e => {
+      if (modeRef && modeRef.current !== 'move') return
+      e.stopPropagation()
+      const normalWorld = e.face.normal.clone().transformDirection(e.object.matrixWorld)
+      dragRef.current = { startX: e.clientX, startY: e.clientY, normalWorld, cubeletPos: e.object.position.clone() }
+    },
+    [modeRef],
+  )
+
+  const onPointerUp = useCallback(
+    e => {
+      const drag = dragRef.current
+      if (!drag) return
+      dragRef.current = null
+      const dx = e.clientX - drag.startX
+      const dy = e.clientY - drag.startY
+      if (Math.sqrt(dx * dx + dy * dy) < 12) return
+      const move = computeSlideMove(drag.normalWorld, drag.cubeletPos, dx, dy, camera)
+      if (move) queueRef.current.push(move)
+    },
+    [camera, queueRef],
+  )
+
+  return (
+    <group ref={orbitRef}>
+      <group ref={cubeRef} onPointerDown={onPointerDown} onPointerUp={onPointerUp}>
+        {positions.map(([x, y, z]) => (
+          <Cubelet key={`${x + 1}${y + 1}${z + 1}`} px={x} py={y} pz={z} palette={palette} />
+        ))}
+      </group>
+      <group ref={rotRef} />
+    </group>
+  )
+}
+
+// Rubik's-notation move groups, exported so consumers can build their own UI.
+export const MOVE_GROUPS = [
+  {
+    id: 'y',
+    label: 'Y · Layer',
+    accent: '#f59e0b',
+    pairs: [
+      [{ n: 'U', axis: 'y', layer: 1, dir: -1 }, { n: "U'", axis: 'y', layer: 1, dir: 1 }],
+      [{ n: 'E', axis: 'y', layer: 0, dir: 1 }, { n: "E'", axis: 'y', layer: 0, dir: -1 }],
+      [{ n: 'D', axis: 'y', layer: -1, dir: 1 }, { n: "D'", axis: 'y', layer: -1, dir: -1 }],
+    ],
+  },
+  {
+    id: 'x',
+    label: 'X · Column',
+    accent: '#ef4444',
+    pairs: [
+      [{ n: 'R', axis: 'x', layer: 1, dir: -1 }, { n: "R'", axis: 'x', layer: 1, dir: 1 }],
+      [{ n: 'M', axis: 'x', layer: 0, dir: 1 }, { n: "M'", axis: 'x', layer: 0, dir: -1 }],
+      [{ n: 'L', axis: 'x', layer: -1, dir: 1 }, { n: "L'", axis: 'x', layer: -1, dir: -1 }],
+    ],
+  },
+  {
+    id: 'z',
+    label: 'Z · Depth',
+    accent: '#22c55e',
+    pairs: [
+      [{ n: 'F', axis: 'z', layer: 1, dir: -1 }, { n: "F'", axis: 'z', layer: 1, dir: 1 }],
+      [{ n: 'S', axis: 'z', layer: 0, dir: -1 }, { n: "S'", axis: 'z', layer: 0, dir: 1 }],
+      [{ n: 'B', axis: 'z', layer: -1, dir: 1 }, { n: "B'", axis: 'z', layer: -1, dir: -1 }],
+    ],
+  },
+  {
+    id: 'rot',
+    label: 'Rotate · Whole',
+    accent: '#a78bfa',
+    pairs: [
+      [{ n: 'x', axis: 'x', layer: null, dir: -1 }, { n: "x'", axis: 'x', layer: null, dir: 1 }],
+      [{ n: 'y', axis: 'y', layer: null, dir: -1 }, { n: "y'", axis: 'y', layer: null, dir: 1 }],
+      [{ n: 'z', axis: 'z', layer: null, dir: -1 }, { n: "z'", axis: 'z', layer: null, dir: 1 }],
+    ],
+  },
+]