aether-shards/.cursor/rules/RULE.md

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

# **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.
Add HubScreen and MissionBoard components for campaign management Introduce the HubScreen as the main interface for managing resources, units, and mission selection, integrating with the GameStateManager for dynamic data binding. Implement the MissionBoard component to display and select available missions, enhancing user interaction with mission details and selection logic. Update the GameStateManager to handle transitions between game states, ensuring a seamless experience for players. Add tests for HubScreen and MissionBoard to validate functionality and integration with the overall game architecture. 2025-12-31 18:49:26 +00:00			`---`
			`description: High-level technical standards, file structure, and testing requirements for the Aether Shards project.`
			`globs: src/.js, test/.js**`
Implement Marketplace system and enhance game state management - Introduce the Marketplace system, managed by MarketManager, to facilitate buying and selling items, enhancing player engagement and resource management. - Update GameStateManager to integrate the new MarketManager, ensuring seamless data handling and persistence for market transactions. - Add specifications for the Marketplace UI, detailing layout, functionality, and conditions of acceptance to ensure a robust user experience. - Refactor existing components to support the new marketplace features, including dynamic inventory updates and currency management. - Enhance testing coverage for the MarketManager and MarketplaceScreen to validate functionality and integration within the game architecture. 2025-12-31 21:52:59 +00:00			`alwaysApply: true`
Add HubScreen and MissionBoard components for campaign management Introduce the HubScreen as the main interface for managing resources, units, and mission selection, integrating with the GameStateManager for dynamic data binding. Implement the MissionBoard component to display and select available missions, enhancing user interaction with mission details and selection logic. Update the GameStateManager to handle transitions between game states, ensuring a seamless experience for players. Add tests for HubScreen and MissionBoard to validate functionality and integration with the overall game architecture. 2025-12-31 18:49:26 +00:00			`---`

			`# 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.`