Repository Guidelines
Project Structure & Module Organization
Keep authored code under src/, grouped by feature: shared easing functions in src/lib/, React (or vanilla JS) scenes in src/scenes/, and helpers in src/utils/. Visual assets (sprites, HDRIs, LUTs) live in assets/. Tests mirror the tree inside tests/ so tests/scenes/wave.spec.ts verifies src/scenes/wave.ts. Treat docs/ as the home for design references and timing charts.
Build, Test, and Development Commands
Run npm install once to sync package versions. Use npm run dev for hot-reload authoring, npm run build for production bundles, and npm run preview to sanity-check the built artifacts. npm run lint enforces style, while npm run test -- --watch keeps the Jest/Vitest loop active during animation tweaks.
Coding Style & Naming Conventions
Stick to TypeScript with strict mode enabled, 2-space indentation, and dangling commas in multiline literals. Components and systems use PascalCase (RippleField), hooks and utilities use camelCase (useSpringChain). Name animation clips and exported constants with suffixes like *Motion or *Timeline to clarify intent. Always run npm run lint or let the pre-commit hook autoformat via ESLint + Prettier.
Testing Guidelines
Write unit tests with Vitest/Jest, one describe block per behavior and one expectation per scenario. Snapshot tests belong to tests/scenes/__snapshots__ and must be regenerated via npm run test -- --updateSnapshot. Aim for >85% branch coverage on core physics/easing modules; integration tests for rendering artifacts can be lower but must assert key frame markers.
Commit & Pull Request Guidelines
Follow Conventional Commits (feat: add bezier stitching, fix: clamp delta time). Keep commits focused and <300 lines where possible. PRs need a concise summary, linked issue or task ID, before/after GIF or FPS capture, and a checklist confirming npm run lint + npm run test passed. Request review from the module owner listed in docs/ownership.md once CI is green.
Security & Configuration Tips
Keep API keys and service tokens in .env.local, never in source; use env.example to document required values. If you touch shader compilation or WASM modules, run npm run verify:webgl (provided script) to ensure browsers accept the updated binaries. Review Dependabot alerts weekly so animation playback stays fast and safe.