Repository Guidelines

Project Structure & Module Organization

client/: Vite + TypeScript web app.
- src/main.ts: connect flow, key commands, status/audio cues.
- src/audio, src/network, src/state, src/render, src/webrtc, src/input: feature modules.
- public/version.js: single source of truth for web version.
- public/sounds/: all client sound assets.
server/: Python signaling service.
- app/server.py: websocket lifecycle + packet routing.
- app/client.py: client connection model.
- app/item_service.py: item persistence + hydration.
- app/item_catalog.py: global item-type properties.
- app/models.py: packet/data schemas.
deploy/: Apache snippet + systemd unit examples.

Client dev: cd client && npm install && npm run dev -- --host 0.0.0.0 --port 5173
Client build: cd client && npm run build
Server run: cd server && cp config.example.toml config.toml && uv run python main.py --config config.toml
Server tests: cd server && uv run --extra dev pytest

TypeScript: strict typing, camelCase, small focused modules.
Python: PEP 8, 4 spaces, snake_case, typed Pydantic models.
Backward compatibility: not required during current development phase; prefer simpler clean-cut changes over compatibility shims/migrations unless the user asks otherwise.
Python docstrings: for server/app changes, include module docstring, class docstring, and docstrings for public functions/methods where behavior/contracts matter.
Shared logic first: when behavior is reused across modes/features, implement it in shared helpers/modules rather than duplicating branch-specific logic.
Keep protocol changes synced in client/src/network/protocol.ts and server/app/models.py.

Keep behavior docs in sync in the same change when features change.
Controls/keybindings changes: update docs/controls.md.
Item behavior/defaults/validation changes: update docs/item-types.md and docs/item-schema.md.
Runtime/protocol behavior changes: update docs/runtime-flow.md and/or docs/protocol-notes.md.

Bump client/public/version.js on every user-visible change using YYYY.MM.DD Rn.
Commit each completed logical change; include the version bump in that same commit when client behavior changes.
Docs-only changes do not require a version bump unless explicitly requested.
Do not duplicate version constants elsewhere in client code.
server/config.toml is deployment-local and must not be committed.
Production should use TLS (network.allow_insecure_ws = false).

Footer changelog content is sourced from client/public/changelog.json.
Do not add or edit changelog lines unless the user explicitly instructs to do so.