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/scenes/scene-template.js is a reference-only template documenting all supported scene config options; it is not loaded by default.
src/decomp-setup.js configures poly-decomp for concave shapes; src/storage.js reads/writes per-scene highscores/records in localStorage.

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.

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.

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.

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.