---
description: High-level technical standards, file structure, and testing requirements for the Aether Shards project.
globs: src/*.js, test/*.js**
---

# **General Project Standards**

## **Tech Stack**

- **Engine:** Three.js \+ Vanilla JavaScript (ES Modules).
- **UI:** LitElement (Web Components).
- **State:** Custom State Managers (Singletons).
- **Persistence:** IndexedDB (via Persistence.js).
- **Testing:** @web/test-runner \+ @esm-bundle/chai \+ sinon.

## **File Structure**

- src/core/: The main loop, state management, and input handling.
- src/grid/: Voxel data structures and rendering logic.
- src/units/: Entity classes (Explorer, Enemy).
- src/managers/: Logic controllers (UnitManager, MissionManager).
- src/systems/: Gameplay logic (TurnSystem, EffectProcessor, AI).
- src/generation/: Procedural algorithms.
- src/ui/: LitElement components.
- assets/data/: JSON definitions (Classes, Items, Missions).

## **Testing Mandate (TDD)**

1. **Test First:** All logic must have a corresponding test suite in test/.
2. **Conditions of Acceptance (CoA):** Every feature must define CoAs, and tests must explicitely verify them.
3. **Headless WebGL:** Tests involving Three.js/WebGL must handle headless contexts (SwiftShader) gracefully or use mocks.
4. **No Global Side Effects:** Tests must clean up DOM elements and Three.js resources (dispose()) after execution.

## **Coding Style**

- Use ES6 Modules (import/export).
- Prefer const over let. No var.
- Use JSDoc for all public methods and complex algorithms.
- **No Circular Dependencies:** Managers should not import GameLoop. GameLoop acts as the orchestrator.