# Introduction

I would like you to take this empty project and create a fun, colorful, and psychologically addictive game based on the 1979 game 'Asteroids' that runs 100% in a web browser using JavaScript.  You will plan, implement, test, and commit the initial game according to the following spec.  After that is complete, you will brainstorm ten new exciting addictive features for the game, after which you will plan, implement, test, and commit (in sequence) the ten new features. 

# Initial game specification

## Features specification

Graphics: B&W vectors (lines/polygons), black bg. All elements vector (text, objects).

Audio: Web Audio API monophonic synth (thrust, fire, saucer, explosions).

Objects: ship, asteroids, shots, UFO.

Controls:
- Left/Right: rotate
- Up: thrust
- Space: fire
- 'c': coin
- '1': start
- 'h': Hyperspace

Ship: triangular, no auto-slowdown, wraps screen.

Ship Thrust/Flame: vector flame on thrust, prominent, increases in size as thrust is held (to a limit).

Asteroids: 3 sizes, split on hit (large→2 med→2 small), wrap screen.

Shots:
- Range : Should be able to hit a target across the screen
- Number : 10 shots active at once (configurable)

Collisions: approximate (ship/bullets/asteroids/UFOs).

Lives: 3, icons top-left under score.

Explosions: particles (objects), disassembly (ship).

HUD: score (top-left), high score (top-center), lives (under score).

UFO:
- Large: slow, horizontal, random fire, 200pts
- Small: fast, erratic, aimed fire, 1000pts
- Bullets hit asteroids
- Destroyed by asteroids/player bullets
- DO NOT spawn UFOs more than once every 30 seconds

Modes:
- Attract: asteroids drift, "INSERT COIN 'C'" + "PRESS '1'" messages
- Game: play until game over

Game Screen:
- Playfield should be the size of the window when the game starts up.
- Outline the playfield to make the extent visible to the player
- Does not resize if window is resized.

Implementation: Canvas 2D, minimal efficient code, complete working files, 100% in browser JavaScript, no back end, test and run using `python3 -m http.server 8100` to serve to browser on port 8100.

Additional artifacts:
- Create README.md for the project.  Include directions for running tests from the command line.


## Project Specification

**Directory and file layout**
index.html
js/
├── main.js                          ← Tiny entry point: imports everything and starts the game
├── core/
│   ├── Game.js                      ← Main Game class, state, etc.
│   ├── GameLoop.js
│   └── Constants.js
├── entities/                        ← All game objects (Player.js, Enemy.js, Bullet.js, Powerup.js, etc.)
├── systems/                         ← RenderingSystem.js, PhysicsSystem.js, CollisionSystem.js, etc.
├── managers/                        ← InputManager.js, AudioManager.js, UIManager.js, etc.
└── utils/                           ← math.js, helpers.js, etc.
assets/                              ← images, sounds, sprites, fonts, etc. (create placeholder files if needed)

**STRICT RULES**
- Use ONLY native ES6 JavaScript modules (`import` / `export`). No bundlers, no frameworks, no build tools.
- The game must run 100% in the browser by simply opening `index.html`.
- The user should be able to run the game using `python3 -m http.server 8100`.
- `index.html` MUST load the game with: `<script type="module" src="js/main.js"></script>`.
- Keep every file small, focused, and single-responsibility. Split logic logically across the folders above.
- All import paths must be correct relative paths so the game works immediately.
- This structure is mandatory for clean, maintainable code and to allow future AI agents to edit individual components without seeing the entire codebase.

**DESIGN PRINCIPLES**
- Apply SOLID principles strictly: Ensure single responsibility (SRP), prioritize extension over modification (OCP), maintain subclass substitutability (LSP), use granular interfaces (ISP), and depend on abstractions/interfaces rather than concrete implementations (DIP). Adhere to SOLID for architecture (especially SRP and DIP) and DRY for logic.
- Maintain a KISS/YAGNI mindset: solve the current requirement with the simplest viable code. Avoid speculative features and prefer small, reusable abstractions over complex, monolithic ones.
- Follow the principle of least surprise: design in a way that other developers would reasonably expect, minimizing hidden side effects and ensuring clear, intuitive interfaces.
- If possible, design and code using a test driven development (TDD) paradigm.

## Testing Specification
- provide code testing according to best practices.
- provide guards against over testing or useless testing.
- provide guards against LLM testing "cheats".
- You have access to the images the game renders in the browser window via `Playwright` and `run_playwright_code`. Because this is a graphical game, the DOM tree and accessibility tags will not tell you if an element is rendered correctly. You must rely strictly on visual inspection of the screenshots provided to you to gauge game rendering correctness.  Example: use `Playwright` to take a screenshot and verify that any game element is oriented on screen as it should be, and to verify that the physics coordinates match the screen coordinates.
- You should probably make use of "testing" game modes, modes that are accessible by button presses (Example 'g' to toggle the graphics testing screen, or 's' to enable a mode where you can single step through a game 'tick' to take several screen captures in succession), for you to verify and correct various visual aspects of the game.

## Committing the initial game
- After implementation and testing of the initial game, commit files to git with an appropriate and succinct one line commit message.

# Follow-on Features
Once the initial game is implemented and tested, I would like you to explore adding color and new features to the game.  Feel free to use web based research to look into what makes a game fun and addictive, and provide value to the game player.  I want to keep the game single player, but I want to add more excitement, varied gameplay, lots of bold color, and 'pizazz' to the game. I also want to explore adding progression mechanics to the game, to keep the player interested.
Most of all, I want to add features that are addictive to the player, to keep them wanting to re-play the game. I’d be interested in addictive features that have their roots in human psychology and research on addictive features and games.

The emphasis should be on pizazz and addictive features.

For the follow-on features, you will need to brainstorm ten new features that, when, added to our game, would add excitement, varied gameplay, color, 'pizazz', fun, player value, and addictiveness to the game.  Then, for each new feature, plan, implement, test, and commit the feature.