Add Phase 1 React + Three.js 3D floor plan viewer (#15) (#16)

Implements Phase 1 of the frontend redesign tracked in #15: a
Tiled-JSON parser and a full 3D Three.js floor plan viewer with
Kenney furniture models, extruded walls, textured floors, and
interactive camera controls.

New package: environment/react_frontend
  React 18 + Vite + TypeScript + Three.js (@react-three/fiber + drei)

Parser (src/parser/)
  Pure pipeline that reads the legacy Tiled JSON maps and the three
  special-block CSV lookup tables (arena, game-object, spawning) and
  emits a strongly-typed MapLayout:
  - Zone extraction via iterative 4-way flood fill on the Arena Layer,
    producing one ZoneRegion per contiguous component with a clockwise
    perimeter polygon, bounding box, and centroid.
  - Equipment extraction from the Object Interaction Layer.
  - Spawning-slot extraction from the Spawning Blocks layer.
  - Wall compression into perimeter-only axis-aligned segments (only
    edges bordering a non-wall tile are emitted — no interior grid
    artefacts inside solid wall blocks).
  - Collision mask as a boolean[y][x] grid.
  - loadMapLayout(): browser-side fetch helper that drives the parser.

Three.js 3D renderer (src/components/ThreeFloorPlan.tsx)
  Full 3D scene built with @react-three/fiber:
  - Zone floors: PlaneGeometry per zone region, textured with raster
    PNGs (wood planks for the waiting room, polished concrete for
    clinical areas) and colour-tinted per zone category so rooms stay
    visually distinguishable.
  - Walls: BoxGeometry extruded along every wall segment with 2.5-unit
    height, white MeshStandardMaterial, real shadow casting.
  - Furniture: 7 Kenney Furniture Kit 2.0 (CC0) GLTF models loaded
    via useGLTF — bedSingle, chairCushion, loungeChair, computerScreen,
    table, desk, chairDesk — placed at each equipment tile position,
    casting and receiving shadows.
  - Lighting: DirectionalLight (2048 px shadow map, warm colour) plus
    soft AmbientLight fill, positioned for consistent top-left
    illumination.
  - Camera: OrbitControls — drag to orbit, scroll to zoom, right-drag
    to pan, with clamped polar angle and distance limits.
  - Navigation overlay: Google Maps-style HTML buttons (zoom +/−,
    rotate left/right, reset camera) positioned top-right of the
    canvas, wired to programmatic camera control via exposed
    OrbitControls ref.
  - Ground plane: large dark surface surrounding the building.

Viewer page (src/MapViewer.tsx)
  - Sidebar with map catalogue (Small ED Layout 30×20, Foothills ED
    Layout 122×123) plus display toggles (zone labels, spawning slots).
  - Live parsed-count panel (zones, equipment, spawning, walls, map
    dimensions).
  - URL query-string state so a map selection survives reloads.

Assets
  - 7 Kenney GLTF furniture models in public/models/ (~110 KB total,
    CC0 licence, kenney.nl).
  - 5 Kenney isometric sprite PNGs in src/assets/furniture/ (CC0,
    used as reference / future 2D fallback).
  - 2 floor texture PNGs in src/assets/textures/ (wood + polished
    concrete, generated at build time via scripts/generate-assets.mjs).
  - Asset catalogue (src/assets/index.ts) maps each ZoneId to its
    texture URL for the Three.js TextureLoader.

Tests
  - 42 vitest unit tests across CSV decoders, loadMapLayout (with
    mocked fetch), and parseTiledJSON. Fixture-pinned counts for both
    seed maps: small_ed_layout (8 zones, 42 equipment, 18 spawning,
    38 wall segments) and foothills_ed_layout (26 zones, 219
    equipment, 70 spawning, 774 wall segments).
  - 6 Playwright e2e tests: 3D view rendering, map switching, URL
    persistence, display toggles, and navigation control visibility.
  - CAPTURE_SCREENSHOTS=1 gated spec produces visual spot-check PNGs
    for both maps.

Tooling & CI
  - run_map_viewer.sh: single-command launcher at the repo root
    (dev / build / preview / test / test:e2e / generate-assets).
  - New test-react-frontend GitHub Actions job: typecheck, lint,
    vitest, production build, Playwright install + e2e, with
    Playwright report upload on failure.
  - ESLint flat config, strict tsc, vitest coverage wiring.
  - scripts/generate-assets.mjs: Playwright-based build-time PNG
    generator for floor textures (deterministic Mulberry32 PRNG,
    value noise, fBm mottle, directional lighting, pixel noise).
  - scripts/dump-parser.mjs: CLI utility to print parser output.

Documentation
  - environment/react_frontend/README.md: architecture, Three.js
    scene hierarchy, model mapping table, commands, how to add maps.
  - Root README.md and CLAUDE.md link to the new viewer.

The legacy Django/Phaser frontend under environment/frontend_server/
is untouched and remains the active runtime for the simulator. The
React frontend reads its map data directly from the same Tiled assets,
so any change to the legacy asset tree shows up in the 3D viewer
immediately — there is no copy step.

Author: stedrew

.github/workflows/ci.yml

@@ -47,3 +47,48 @@ jobs:
         env:
           DJANGO_SETTINGS_MODULE: frontend_server.settings.base
           PYTHONPATH: reverie/backend_server:environment/frontend_server:analysis
+
+  test-react-frontend:
+    name: React Frontend (Phase 1)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: environment/react_frontend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: environment/react_frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Unit tests (vitest)
+        run: npm test
+
+      - name: Build production bundle
+        run: npm run build
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: End-to-end tests (Playwright)
+        run: npm run test:e2e
+
+      - name: Upload Playwright report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: environment/react_frontend/playwright-report/
+          retention-days: 7

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install MkDocs and theme
+        run: pip install mkdocs-material
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

CLAUDE.md

@@ -122,6 +122,28 @@ Outputs: `analysis/patient_time_metrics.csv` and `analysis/ctas_daily_metrics.cs
 
 ## Architecture
 
+### Phase 1 React Floor Plan Viewer (Issue #15)
+
+A new bird's-eye renderer is being built under `environment/react_frontend/`
+using **React + Vite + TypeScript + Three.js**. Phase 1 (the Tiled JSON
+parser, zone/equipment/wall layers, and a static floor plan canvas) ships
+with its own unit + e2e test suites and a single-command launcher:
+
+```bash
+./run_map_viewer.sh           # install deps + start dev server (http://127.0.0.1:5173)
+./run_map_viewer.sh test      # vitest unit tests (parser invariants)
+./run_map_viewer.sh test:e2e  # Playwright e2e tests (viewer interactions)
+```
+
+The React frontend reads its map data directly from
+`environment/frontend_server/static_dirs/assets/the_ed/`, so any change to
+the legacy Phaser asset tree shows up in the new renderer immediately —
+there is no copy step.
+
+The legacy Django/Phaser frontend in `environment/frontend_server/` remains
+the active runtime; the React frontend lives alongside it as a successor
+under construction.
+
 ### Component Layout
 
 ```
@@ -156,6 +178,16 @@ analysis/
 
 data/
   baseline/, surge/         # Pre-computed reference metrics CSVs
+
+environment/react_frontend/ # Phase 1 React + Three.js floor plan viewer
+  src/parser/               # parseTiledJSON pipeline (issue #15 1.1)
+  src/components/           # ThreeFloorPlan (Three.js 3D renderer)
+  src/theme/                # Colour palette
+  src/data/maps.ts          # Catalogue of available Tiled fixtures
+  src/MapViewer.tsx         # Top-level page (sidebar + canvas)
+  tests/unit/               # vitest parser tests (50)
+  tests/e2e/                # Playwright viewer tests (6)
+  README.md                 # Phase 1 architecture and usage
 ```
 
 ### Simulation State Storage

README.md

@@ -70,6 +70,20 @@ Open [http://localhost:8000/](http://localhost:8000/) to confirm the frontend is
 
 > For interactive mode, custom configuration, or local development, see the sections below.
 
+### Phase 1 Floor Plan Viewer
+
+A new React + Three.js 3D renderer is being built under
+[`environment/react_frontend/`](environment/react_frontend/) (tracking
+[Issue #15](https://github.com/denoslab/EDSim/issues/15)). To preview just
+the floor plan layout from a Tiled map without running the simulation:
+
+```bash
+./run_map_viewer.sh             # opens http://127.0.0.1:5173
+```
+
+See [`environment/react_frontend/README.md`](environment/react_frontend/README.md)
+for the parser architecture, validation criteria, and how to add a new map.
+
 ## Architecture Overview
 
 EDSim consists of three main components:

docs/architecture/floor-plan-viewer.md

@@ -0,0 +1,41 @@
+# 3D Floor Plan Viewer
+
+The Phase 1 floor plan viewer lives under `environment/react_frontend/` and provides an interactive 3D rendering of the ED layout.
+
+## Technology stack
+
+| Layer | Technology |
+|---|---|
+| Build tool | Vite 5 |
+| Language | TypeScript 5 (strict mode) |
+| UI framework | React 18 |
+| 3D renderer | Three.js via `@react-three/fiber` + `@react-three/drei` |
+| Unit tests | Vitest |
+| E2E tests | Playwright (Chromium) |
+| Linting | ESLint 9 (flat config) |
+
+## Scene hierarchy
+
+`ThreeFloorPlan` renders the following hierarchy inside a `<Canvas>`:
+
+1. **GroundPlane** — large dark surface surrounding the building.
+2. **ZoneFloor** (×N) — one `PlaneGeometry` per zone region, textured with the raster PNG (wood or concrete) and tinted with the zone colour.
+3. **Walls** — `BoxGeometry` per wall segment, extruded to 2.5 units height, white `MeshStandardMaterial`, shadow casting enabled.
+4. **Furniture** (×N) — Kenney `.glb` models loaded via `useGLTF`, placed at each equipment tile position, casting and receiving shadows.
+5. **Lighting** — `DirectionalLight` (2048 px shadow map) + warm `AmbientLight` fill.
+6. **OrbitControls** — drag/scroll/right-drag camera interaction.
+7. **NavControls** — HTML overlay with zoom/rotate/reset buttons.
+
+## Data flow
+
+```
+Tiled JSON + CSV files
+        ↓
+   parseTiledJSON()  →  MapLayout
+        ↓
+   ThreeFloorPlan    →  Three.js scene
+        ↓
+   Browser WebGL canvas
+```
+
+The parser is a pure function with no side effects — it takes the raw Tiled data and emits a strongly-typed `MapLayout` object. The renderer consumes `MapLayout` and builds the 3D scene. This separation means the parser can be tested in isolation (42 vitest tests) and the renderer can be swapped without touching any parsing logic.

docs/architecture/overview.md

@@ -0,0 +1,49 @@
+# Architecture Overview
+
+EDSim consists of three main components and an analysis pipeline.
+
+## Component layout
+
+```
+reverie/backend_server/          # Simulation engine
+  reverie.py                     # ReverieServer — main simulation loop
+  maze.py                        # Tile-based map and spatial state
+  persona/                       # Agent classes and cognitive modules
+    persona_types/               # Doctor, BedsideNurse, TriageNurse, Patient
+    cognitive_modules/           # perceive, plan, reflect, converse, execute
+    memory_structures/           # Scratch (short-term), AssociativeMemory (long-term)
+    prompt_template/             # LLM prompt templates per role
+
+environment/frontend_server/     # Legacy Django + Phaser frontend
+  translator/views.py            # API endpoints
+  storage/                       # Simulation state folders
+  static_dirs/assets/the_ed/     # Tiled JSON maps and CSV block definitions
+
+environment/react_frontend/      # Phase 1 React + Three.js 3D viewer
+  src/parser/                    # Tiled JSON parser pipeline
+  src/components/                # ThreeFloorPlan (3D scene)
+  src/assets/                    # Textures and furniture sprites
+  public/models/                 # Kenney GLTF furniture models
+
+analysis/                        # Post-simulation metrics
+  compute_metrics.py             # Patient throughput, wait times
+```
+
+## Data flow
+
+1. The **simulation engine** reads its initial state from a seed folder under `environment/frontend_server/storage/`.
+2. Each simulation step runs the cognitive loop (perceive → retrieve → plan → execute → converse → reflect).
+3. Step output is written as JSON files under the simulation's `environment/` and `personas/` directories.
+4. The **legacy frontend** reads those JSON files and renders them via Phaser on a Tiled map.
+5. The **3D Floor Plan Viewer** parses the same Tiled JSON map files and renders the static floor plan in Three.js — it does not yet consume live simulation output (that's Phase 2).
+
+## Simulation state
+
+All simulation state lives under `environment/frontend_server/storage/<sim_name>/`:
+
+| Path | Contents |
+|---|---|
+| `reverie/meta.json` | Simulation parameters |
+| `reverie/maze_status.json` | Bed count overrides |
+| `environment/` | Per-step movement and environment JSON |
+| `personas/<name>/` | Agent memory (scratch, associative memory) |

docs/architecture/simulation-engine.md

@@ -0,0 +1,40 @@
+# Simulation Engine
+
+The simulation engine lives under `reverie/backend_server/` and drives the agent-based ED simulation.
+
+## Per-step cognitive loop
+
+Each step in `ReverieServer`:
+
+1. **Perceive** — agents observe nearby agents, objects, and events within `vision_r` tiles.
+2. **Retrieve** — relevant memories are fetched from associative memory using embedding similarity + recency weighting.
+3. **Plan** — the LLM generates or revises the agent's schedule and immediate next action.
+4. **Execute** — the planned action updates tile position and object state.
+5. **Converse** — agents in proximity may initiate LLM-driven conversations.
+6. **Reflect** — periodically synthesises memories into higher-level insights.
+
+## Agent types
+
+| Role | Behaviour | Spawn zone |
+|---|---|---|
+| **Doctor** | Assesses patients, orders diagnostic tests, discharges | Major injuries |
+| **Bedside Nurse** | Transfers patients between rooms, performs tests | Minor injuries |
+| **Triage Nurse** | Assigns CTAS score and injury zone to incoming patients | Triage |
+| **Patient** | Arrives with symptoms, interacts with staff | ED entrance |
+
+## LLM integration
+
+`gpt_structure.py` reads `openai_config.json` at import time and constructs the OpenAI/Azure client. All LLM calls go through `run_gpt_prompt.py`, which selects the appropriate prompt template from `persona/prompt_template/ED/`. Transient API errors (429, 500–503) are retried with exponential backoff.
+
+## Configuration (`meta.json`)
+
+Key parameters in `<sim_folder>/reverie/meta.json`:
+
+| Key | Description |
+|---|---|
+| `sec_per_step` | Simulation seconds per step |
+| `patient_rate_modifier` | Scales patient arrival rate |
+| `{role}_starting_amount` | Number of agents per role at start |
+| `patient_walkout_probability` | Probability a waiting patient leaves |
+| `testing_time` / `testing_result_time` | Diagnostic test durations (minutes) |
+| `priority_factor` | CTAS score prioritisation weight |

docs/development/adding-maps.md

@@ -0,0 +1,73 @@
+# Adding New Maps
+
+The 3D viewer supports any Tiled JSON map that follows the EDSim layer convention. Adding a new map is a four-step process with no code changes required.
+
+## Steps
+
+### 1. Create the Tiled JSON
+
+Use the [Tiled](https://www.mapeditor.org/) map editor. The map must contain these named layers:
+
+| Layer name | Purpose |
+|---|---|
+| `Arena Layer` | Zone classification (tile IDs from `arena_blocks.csv`) |
+| `Object Interaction Layer` | Equipment placement (tile IDs from `game_object_blocks.csv`) |
+| `Spawning Blocks` | Agent spawn points (tile IDs from `spawning_location_blocks.csv`) |
+| `Walls` | Wall tiles (any non-zero tile = wall) |
+| `Collisions` | Collision mask (any non-zero tile = blocked) |
+
+Save the map as a JSON file.
+
+### 2. Place the file
+
+Drop the JSON file into:
+
+```
+environment/frontend_server/static_dirs/assets/the_ed/visuals/
+```
+
+### 3. Update CSV lookup tables (if needed)
+
+If the new map introduces tile GIDs not already in the existing CSV files, add them to the corresponding file under:
+
+```
+environment/frontend_server/static_dirs/assets/the_ed/matrix/special_blocks/
+```
+
+| CSV file | Format |
+|---|---|
+| `arena_blocks.csv` | `<tileId>, ed map, emergency department, <zone label>` |
+| `game_object_blocks.csv` | `<tileId>, ed map, <all>, <object label>` |
+| `spawning_location_blocks.csv` | `<tileId>, ed map, emergency department, <zone label>, <slot label>` |
+
+### 4. Register in the map catalogue
+
+Add a new entry to `environment/react_frontend/src/data/maps.ts`:
+
+```typescript
+{
+  id: 'my_new_map',
+  displayName: 'My New Map',
+  description: '50 × 40 custom layout.',
+  load: {
+    mapId: 'my_new_map',
+    tiledJsonUrl: myNewMapJsonUrl,  // import via ?url
+    arenaBlocksUrl,
+    gameObjectBlocksUrl,
+    spawningBlocksUrl
+  }
+}
+```
+
+The sidebar picks up the new entry automatically on the next dev server restart.
+
+## Validation
+
+After adding a map, verify the parser output:
+
+```bash
+cd environment/react_frontend
+npx tsx scripts/dump-parser.mjs
+```
+
+This prints zone counts, equipment counts, and wall segment counts for every registered map. Cross-check these against the Tiled editor to confirm the parser decoded the map correctly.