# Repository Guidelines

## Project Structure & Module Organization

HEX TRAILS is a dependency-free JavaScript hexagonal track puzzle. `index.html` and `style.css` define the responsive browser interface. Keep gameplay, solving, generation, validation, and difficulty scoring in `src/core.js`; coordinate conversion and curve sampling belong in `src/geometry.js`. `src/renderer.js` exposes engine-independent drawing commands plus the Canvas adapter. Browser controls and persistence live in `src/app.js`.

`levels/campaign.json` and generated `src/levels.js` contain the campaign. `tests/` holds Node tests, `scripts/` provides development utilities, and `docs/` explains design and portability. `cocos/HexTrailsBoard.ts` is the native engine adapter example.

## Build, Test, and Development Commands

Use Node.js 20 or newer. No dependency installation is required.

- `npm run dev`: serve the application at `http://localhost:4173`.
- `npm test`: run the Node built-in test suite.
- `npm run build`: create a static deployment in `dist/`.
- `npm run levels`: regenerate both campaign data files using deterministic seeds.

Open the application over HTTP because it uses ES modules. Do not commit `dist/` or `node_modules/`.

## Coding Style & Naming Conventions

Use ES modules, two-space indentation, camelCase functions, and PascalCase classes. No formatter or linter is configured. Follow surrounding conventions and avoid unrelated formatting changes. Keep DOM and storage APIs out of the model and geometry modules. Keep gameplay rendering portable: polygons, lines, circles, and PNG atlas sprites. Store generated art and prompts in `assets/`; source rectangles live in `src/sprites.js`. `src/path-math.js` shares geometry between rendering and swept collision detection.

## Testing Guidelines

Name tests `tests/*.test.js`. Cover rule changes with meaningful fixtures, particularly board rotation, swept collisions along curves, blockers, loops, undo, and malformed imports. Campaign changes must validate and solve completely. Test responsive gameplay and editor flows after interface changes. No coverage percentage is enforced.

## Commit & Pull Request Guidelines

No Git history was available when this project was created. Use focused, imperative commit subjects. Describe behavior changes, link relevant issues, and include test results and screenshots for visual changes. State native-engine verification limits explicitly.

## Agent-Specific Instructions

Before calling MCP tools, read `/Users/wukaibing/.grok-go/agents-guide.md` for version-specific GrokGo instructions.

### Level-production scope

The user has explicitly limited this work to level creation: board layouts, track connections, pieces, difficulty, and level ordering. Use the game's existing interface and interaction logic. Do not independently add controls, hide controls, change layouts or themes, or introduce teaching-specific interface behavior. Any future interface or interaction change requires an explicit user request. Preserve existing campaign numbering and saved progress when integrating level data.

### Design-system entry point

For user-requested design/UI work, start at [design/README.md](design/README.md) and [design/AGENTS.md](design/AGENTS.md), then read [design/shared.md](design/shared.md) and the selected `design/directions/<id>/design.md`. [design/manifest.json](design/manifest.json) lists all five stable IDs, canonical documents, previews, and generated tokens. Each design has five themes; design IDs are separate from theme IDs and campaign versions. Authored design.md files must not be overwritten by generators. This entry point does not expand the scope of level-only tasks.