# Repository Guidelines

## Project Structure & Modules
- `index.html` boots the canvas, HUD overlays, and pulls Matter.js plus all project scripts; open it directly or via a simple static server.
- `styles.css` holds layout, HUD, overlays, and popup styling.
- `src/main.js` runs the physics loop, spawning, scoring, and scene application; `src/ui.js` wires DOM/HUD controls and overlays.
- `src/scenes/*.js` defines scene presets (`id`, `name`, `config`, `createBodies(width, height)`); `src/scenes/index.js` registers them to `window.PhysilinksScenes`.
- `src/decomp-setup.js` configures `poly-decomp` for concave shapes; `src/storage.js` reads/writes per-scene highscores/records in `localStorage`.

## Build, Test, and Development Commands
- No build step. Serve or open locally: `python3 -m http.server 8000` then visit `http://localhost:8000`, or double-click `index.html`.
- Use a modern desktop/mobile browser; Matter.js is loaded via CDN.

## Coding Style & Naming Conventions
- JavaScript uses 2-space indentation, semicolons, and double quotes; keep functions/variables camelCase, constants UPPER_SNAKE_CASE.
- Scene files are kebab-cased (e.g., `scene-storm-grid.js`) and should export an `id` matching the filename. Keep configs minimal: gravity, spawn settings, palette, `link` options, and `createBodies`.
- Favor small helpers over inline duplication; attach shared globals to `window.Physilinks*` consistently.

## Testing Guidelines
- No automated tests yet; rely on manual playthroughs. Recommended pass: load each scene, start a chain, clear at least one valid link, verify score popup and HUD update, pause/resume, and confirm run-over detection triggers when the entry is blocked.
- Validate persistence: switch scenes and ensure highscores reload; refresh to confirm `localStorage` keys (`physilinks-highscore-<sceneId>`) remain honored.

## Commit & Pull Request Guidelines
- Follow the short, present-tense style from history (e.g., `Add Storm Grid Shift scene`, `Clamp square spawns for stack blocks`).
- Call out any new globals, storage keys, or DOM IDs/classes. Keep diffs focused and avoid unrelated formatting churn.