Cubify is a 3×3 cube rendering library for CFOP apps. Delegates permutation state and move application to cubing.js, then owns the rendering layer — typed theme system, stickering API for CFOP case visualisation, and React wrappers that expose cube state as a first-class value.
This repo is an npm workspace publishing two packages to GitHub Packages:
| Package | Description |
|---|---|
@andyjudson/cubify |
Core cube library — state, rendering, animation, export |
@andyjudson/cubify-react |
React wrappers — <CubePlayer>, <CubeState>, <CubeMoveTape>, <CubePlayerControls> |
# .npmrc (add to your project)
@andyjudson:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}
# Install
npm install @andyjudson/cubify three cubing
npm install @andyjudson/cubify-react react react-dom react-icons # if using ReactGitHub Packages requires auth even for public packages. Use a GitHub PAT with read:packages scope locally; in CI use GITHUB_TOKEN.
See specs/cubify.md for full setup, usage examples, local dev workflow, and architecture reference.
| Module | Description |
|---|---|
CubeState |
cubing.js KPattern wrapper — applyMove/applyAlg, toFaceArray(), isSolved(), invertAlg() |
CubeScramble |
Scramble generator — CubeScramble.random(length?) sync; CubeScramble.wca() async WCA random-state via twips WASM |
CubeSolver |
Kociemba 2-phase solver — new CubeSolver() → solve(state), cancel(), dispose(); runs in a web worker |
AlgParser |
WCA notation parser (face turns, wide moves, slice moves, rotations) |
CubeStickering |
CFOP orbit-string masking; MASK_PRESETS (15 presets); chars -/I/D/O/S/P |
CubeTheme |
Theme system — THEME_PRESETS (default/rubiks/speed-dark/speed-light), DEFAULT_THEME |
CubeRenderer2D |
Top-down 2D renderer — toSVG(), canvas update(), setTheme() |
CubeRenderer3D |
Three.js 3D renderer — animateMove(), setSpeed(), applyStickering(), snapshotAt() |
CubePlayer |
Animation engine — loadAlg(), play/pause/jumpTo/reset, events (move, complete, reset) |
CubeExporter |
toPNG(alg, { style: '2d'|'3d' }) — transparent PNG export |
npm install # install workspace deps
npm test # Vitest suite (237 pass, 10 skip)
npm run dev # Vite dev server → cubify-harness/index.html
npm run build --workspace=packages/cubify # tsc build → packages/cubify/dist/
npm run build --workspace=packages/cubify-react # tsc build → packages/cubify-react/dist/bash scripts/version-bump.sh 1.1.0 # bumps both packages, commits, tags
git push && git push --tags # triggers publish.yml CI → GitHub PackagesInteractive browser dev environment — algorithm selector, play/step controls, export buttons.
| File | Description |
|---|---|
cubify-harness/index.html |
Interactive harness UI |
packages/cubify/test/ |
Vitest suite — 237 tests, no headed browser |
cubify-harness/verify-perms.mjs |
18-test permutation cross-check against cubing.js ground truth |
Node.js CLI for on-demand cube image generation. Used as the /cubify Claude Code skill.
node cubify-scripts/cubify.mjs "R U R' U R U2 R'"
node cubify-scripts/cubify.mjs --case oll_sune --masked --2d
node cubify-scripts/cubify.mjs --file algs-cfop-oll.json --masked --2dRequires headful Chromium (WebGL blocked in headless on macOS):
cd cubify-scripts && npx playwright install chromium
ln -s /path/to/cfop/cfop-app/public/data cubify-scripts/data| Doc | Content |
|---|---|
specs/cubify.md |
Quickstart, usage examples, local dev workflow, architecture |
specs/cubing-js-architecture.md |
Cubing.js KPuzzle/KPattern data model |
specs/cube-mapping-lessons.md |
Hard-won implementation gotchas |
specs/cube-physical-rules.md |
Physical cube geometry, CFOP conventions |
- cubing.js (Lucas Garron) — KPuzzle/KPattern permutation state model, WCA alg parsing, move application, and the 3×3 puzzle definition that cubify builds its rendering layer on top of
- Three.js — 3D rendering
- Playwright (cubify-scripts only) — headful Chromium screenshot capture
MIT License — see LICENSE for details.
Status: Features 022–033 complete • 034 in progress