rubik/docs/code-standards.md

Code Standards

Language & Toolchain

• ES modules, modern JS (no TypeScript).
• Svelte 5 with runes ($state, $derived, $effect, $props, $bindable).
• Three.js for WebGL. Tween.js for animation.
• Vite as build tool. Dev: npm run dev. Prod: npm run build.

Naming

• Plain JS files: kebab-case with descriptive names (apply-move.js, pointer-gesture.js).
• Svelte components: PascalCase.svelte per ecosystem convention (CubeView.svelte).
• Functions and variables: camelCase. Constants: UPPER_SNAKE for module-level tuning knobs (DEAD_ZONE_PX, PIXELS_PER_QUARTER_TURN).

File Size

• Code files must stay under 200 lines of code.
• Refactor when a file exceeds the limit; split by concern (e.g., pointer-gesture.js + gesture-math.js).

Architecture Rules

• Core (src/lib/core/) is pure JS. No Svelte, no Three.js imports. Authoritative cube state, move algebra, parser, scrambler, solved check. Unit-testable from Node.
• Render (src/lib/render/) is the Three.js layer. Owns scene/camera/renderer, mesh construction, animation. May import from core/ but never the other way around.
• Controls (src/lib/controls/) handles user input. Imports from render/ and core/ as needed.
• Views (src/views/) are Svelte components. Each owns layout + Svelte state. May call into the other layers but never the inverse.
• The Three.js cube model and the JS cube state are kept in sync explicitly via applyMove + syncMeshes (or, post-animation, via pivot.attach baking).

Style

• Prefer composition over inheritance.
• Fail loudly during development (throw on unknown move tokens), fail gracefully at runtime.
• Comments: short, explain why, not what. File headers give a one-sentence purpose.

Git / Commits

• Conventional commits (feat:, fix:, refactor:, chore:).
• Never commit dotenv files, build artifacts, or secrets.
• Run npm run build before pushing to catch compile errors.

Testing Strategy

• Pure-JS smoke test at scripts/smoke-test-core.mjs covers the cube algebra.
• No automated UI tests yet (matches sokoban). Manual smoke test: scramble → undo until solved → confirm timer stops.