Updated README and reformated all ts/tsx code.

Author: Faisal5546

README.md

@@ -1,84 +1,109 @@
 # Doodlebot Educational Platform
 
-A browser-based multiplayer game that teaches kids pathfinding and autonomous navigation algorithms through a virtual grid game.
+A browser-based multiplayer game that teaches kids pathfinding and autonomous-navigation
+algorithms through a virtual grid game. Built with **Vite + React + TypeScript** and synced
+in real time with **Firebase Realtime Database**.
+
+Live at **https://mitmedialab.github.io/doodlebot-controller/** (deployed from `main` via
+GitHub Pages).
 
 ## What it does
 
-Players join a shared room and each controls a bot on a 16×16 grid. They progress through a guided tutorial that introduces four movement algorithms in increasing sophistication:
+Two players join a shared room and each controls a bot on a 16×16 grid. Players drag bots,
+coins, and obstacles onto the board, assign their bot a **movement policy**, then start —
+all bots execute simultaneously and the player who collects the most coins wins the phase.
+
+The game runs as **three phases** that introduce planning strategies of increasing
+sophistication:
+
+| Phase | Movement policy available               | Notes                                                                                                           |
+| ----- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **1** | Goal-based planning (Manhattan) only    | The reflex baseline is forced; the utility option is hidden.                                                    |
+| **2** | Goal-based + Utility-based (Dijkstra)   | Utility-based is a **single-owner claim** — only one player may take it (labelled _unclaimed / yours / taken_). |
+| **3** | Goal-based + Utility-based, free choice | Any player may pick Utility-based; no claim.                                                                    |
+
+Each phase runs on a **60-second countdown** and ends when the timer expires _or_ all coins
+are collected. A results modal shows the per-player score and advances to the next phase
+(or finishes the game after phase 3).
+
+### Movement policies
+
+The grid model implements three distance strategies:
 
-1. **Random** — the bot picks a random valid move each turn
-2. **Euclidean distance** — the bot greedily moves toward the closest target
-3. **Manhattan distance** — same idea, different distance metric
-4. **Dijkstra** — full shortest-path that navigates around obstacles
+- **Reflex planning** (Euclidean) — the default fallback; greedy straight-line distance.
+- **Goal-based planning** (Manhattan) — greedy `|dx| + |dy|` distance.
+- **Utility-based planning** (Dijkstra) — true shortest path that routes around obstacles,
+  computed from a per-coin weighted graph. It carries a cosmetic memory/heat "cost" in the
+  resource panel.
 
-Each player assigns their bot a **policy** (collect coins, follow another bot, or run away from a bot) and a **movement type**, then watches all bots execute simultaneously. The player who collects the most items wins.
+Only Goal-based and Utility-based are offered as radio options in the UI; Reflex is the
+implicit fallback when a bot has no policy set.
 
 ## Themes
 
-Four visual themes change sprites and backgrounds: **None** (plain robots), **City** (cars, pizza), **School** (buses, bicycles), **Pacman** (ghosts, maze).
+Three visual themes change sprites and backgrounds: **None / Default** (plain robots),
+**City** (cars, pizza), and **School** (buses, bicycles). The room creator picks the theme;
+it is stored on the room and applied for both players.
 
 ## Getting started
 
-No installation or build step required. Serve the root directory with any static file server:
+This is a build-based app (Node + npm required).
 
 ```bash
-python3 -m http.server 8080
+npm install
+npm run dev        # local dev server (served under base /doodlebot-controller/)
+npm run build      # tsc + vite build → dist/
+npm run preview    # serve the production build locally
+npm run test:run   # run the vitest suite once
 ```
 
-Then open:
-
-```
-http://localhost:8080/virtual-board/doodlebotGame.html
-```
-
-Or open `virtual-board/doodlebotGame.html` directly in your browser. The app is also live at the GitHub Pages URL for this repo.
+Open the dev server URL, which lands on the splash page (`index.html`).
 
 ## Game flow
 
 ```
-doodlebotGame.html       splash screen
-  └─> rooms.html         create or join a multiplayer room
-      └─> tutorial1      watch: Random navigation
-          └─> game1      play: Random bots
-              └─> tutorial2  watch: Euclidean distance
-                  └─> game2  play: Euclidean bots
-                      └─> tutorial3  watch: Manhattan distance
-                          └─> game3  play: Manhattan bots + obstacles
-                              └─> tutorial4  watch: Dijkstra
-                                  └─> game4  play: Dijkstra bots
-                                      └─> tutorial5
-                                          └─> free play (choose theme)
+index.html      splash screen  →  "Play Game"
+  └─> rooms.html   create a room (share the ID) or join one, creator picks a theme
+        └─> game.html   both players auto-navigate here once the room has 2 players
+              └─> Phase 1  →  Phase 2  →  Phase 3  →  Finish
 ```
 
-The tutor (room creator) controls page progression. All players are automatically navigated together when the tutor advances.
+Room membership drives navigation: when a room reaches 2 players, `RealtimeUpdates`
+redirects everyone to `game.html?room=<id>&option=<theme>&mode=virtual`.
 
 ## Tech stack
 
-- **Vanilla HTML/CSS/JS** — no framework, no bundler
-- **Firebase Realtime Database + Auth** — multiplayer sync and anonymous player identity
-- **Bootstrap 5** — UI layout and modals
-- **interact.js** — drag-and-drop for placing bots, obstacles, and coins
+- **Vite + React 19 + TypeScript** — multi-page app (`index.html`, `rooms.html`, `game.html`),
+  each React page mounted into a single `#root`.
+- **Firebase Realtime Database + Auth** — multiplayer sync and anonymous player identity.
+- **Bootstrap 5** (CSS/markup only; modals are React-controlled, no Bootstrap JS).
+- **Vitest + Testing Library (jsdom)** — unit and DOM component tests.
 
 ## Project structure
 
 ```
-ralcant.github.io/
-├── virtual-board/        # All game HTML, JS, and CSS
-│   ├── grid.js           # Core grid state machine and movement algorithms
-│   ├── grid-graph.js     # Graph + Dijkstra implementation
-│   ├── game-assets.js    # Static asset and object-size data
-│   ├── game-setup.js     # Grid construction and Firebase callback bridge
-│   ├── bot-movement.js   # Bot start/stop movement lifecycle
-│   ├── grid-render.js    # DOM drawing functions
-│   ├── phase-manager.js  # Tutorial phase and countdown logic
-│   └── test-index.js     # Entry point: URL params, theme, event wiring
-├── assets/               # Sprites and backgrounds per theme
-├── firebase-handler.js   # Firebase bootstrap shim
-├── firebase-init.js      # Firebase app init and anonymous auth
-├── firebase-sync.js      # RealtimeUpdates class — all Realtime Database calls
-└── firebase-game-flow.js # Game flow helpers (phase transitions)
+doodlebot-controller/
+├── index.html / rooms.html / game.html   # multi-page entry points
+├── public/assets/                        # sprites & backgrounds (per theme)
+├── src/
+│   ├── main.ts / rooms.ts                # per-page entry scripts (mount React roots)
+│   ├── grid/                             # VirtualGrid model + graph/Dijkstra (no DOM)
+│   ├── firebase/                         # firebase-init (auth) + firebase-sync (RealtimeUpdates)
+│   ├── sync/                             # grid ↔ Firebase adapter
+│   ├── game/resource-model.ts            # cosmetic battery/CPU/memory sim (local, unsynced)
+│   ├── ui/                               # phase-manager, bot-movement, drag-drop, game-setup
+│   ├── ui/react/                         # GameApp, GameBoard, Sidebar, Controls, PhaseHud,
+│   │                                     #   Modals, ResourcePanel, Lobby, useGridSnapshot
+│   ├── events.ts                         # typed event bus (gameEvents)
+│   ├── types.ts                          # shared types + MOVEMENT_VALUES etc.
+│   └── __tests__/                        # vitest suites
+├── vite.config.ts                        # base: "/doodlebot-controller/"
+└── .github/workflows/deploy.yml          # build + deploy to GitHub Pages
 ```
 
+See [CLAUDE.md](CLAUDE.md) for architecture details (state separation, the event bus, the
+Firebase room schema, and the React island model).
+
 ## Browser requirements
 
-Any modern browser (Chrome, Firefox, Safari, Edge) works for virtual mode.
+Any modern browser (Chrome, Firefox, Safari, Edge).