# Project: FreeExile 30 Dark Fantasy Map Styles & Graphics Overhaul

## Architecture
- **Data & Specification Layer**:
  - `data/map_styles.db`: Relational SQLite database with tables `map_styles` (30 records), `map_style_tiles`, `map_style_props`.
  - `server/world/map_style_types.py`: Immutable dataclasses (`MapStyleDefinition`, `MapStyleTileMapping`, `MapStylePropDefinition`).
  - `server/world/map_style_schema.py`: SQLite DDL schema, WAL mode, foreign key enforcement.
  - `server/world/map_style_service.py`: Service interface for querying styles, tiles, and props.
  - `server/world/map_style_catalog.py`: Python canonical catalog of 30 styles with legacy alias mappings.
  - `client/webapp/js/data/map_style_catalog.js`: ES Module catalog for client-side rendering and UI.
- **Asset Pipeline Layer**:
  - `client/webapp/assets/map/styles/<style_id>/`: Structured directory for all 30 biomes.
  - Each style contains: `floor.png`, `wall.png`, `path.png`, `liquid.png`, `props.png` / decal sprites, and tangent-space normal maps `*_normal.png` ($B > 128$).
- **Client Rendering & Memory Engine**:
  - `client/webapp/js/engine/biome_texture_manager.js`: Texture loader, `CanvasPattern` cache, lazy loading of active biome (< 500 KB RAM), graceful procedural fallback.
  - `client/webapp/js/engine/tile_map_renderer.js`: Nướng (bake) chunk 16x16 với texture ảnh thật, 2.5D elevation extrusion, deterministic coordinate hash decals, SAT Diamond culling, LRU 8 slots OffscreenCanvas (RAM <= 16.5 MB, 60-120 FPS).
  - `client/webapp/js/engine/tile_grid_loader.js`: Auto-sync hook on binary map reception.
  - `client/webapp/index.html` & `simulator_bar`: Biome selector dropdown & `?biome=` query param hook.
- **Server Biome Pipeline & Procedural Engine**:
  - `server/world/map_biome_catalog.py`: 30 biomes registered with `biome_code` 1-30.
  - `server/world/map_binary_serializer.py`: Binary header byte 3 (uint8) maps codes 1-30.
  - `server/world/wilderness_map_generator.py`: Zone-to-biome canonical mapping.
  - `tools/serve_webapp.py`: `/api/map` endpoint supports `?biome=` parameter.

## Feature Inventory
| # | Feature | Description | Milestone | Status |
|---|---------|-------------|-----------|--------|
| 1 | 30 Map Styles Specification | 30 distinct Dark Fantasy Cổ Võ Hoang Vực biomes across 6 themes | M1 | DONE |
| 2 | SQLite Map Styles Database | `data/map_styles.db` with tables `map_styles`, `map_style_tiles`, `map_style_props` | M1 | DONE |
| 3 | Server Map Style Catalogs & Service | `map_style_types.py`, `map_style_schema.py`, `map_style_service.py`, `map_style_catalog.py` | M1 | DONE |
| 4 | Client Map Style Catalog | `client/webapp/js/data/map_style_catalog.js` synchronized with database | M1 | DONE |
| 5 | Legacy Biome Alias Mapping | 100% backward compatibility for codes 1-5 with legacy tests | M1 | DONE |
| 6 | 30 Biomes Texture Asset Suite | 30 complete style folders in `client/webapp/assets/map/styles/` (Floor, Wall, Path, Liquid, Props) | M2 | DONE |
| 7 | Tangent-Space Normal Maps | Normal maps with $B > 128$ for lighting shaders | M2 | DONE |
| 8 | Client BiomeTextureManager | Texture pattern caching, lazy active biome loading, graceful procedural fallback | M3 | DONE |
| 9 | Upgraded TileMapRenderer | OffscreenCanvas chunk 16x16 baking with real textures, 2.5D extrusion, hash decals | M3 | DONE |
| 10 | TileGridLoader & Biome Switching | Auto-reinit renderer on zone change, debug dropdown & `?biome=` query param | M3 | DONE |
| 11 | Server Biome Pipeline Expansion | `map_biome_catalog.py` & `map_binary_serializer.py` support codes 1-30 | M3 | DONE |
| 12 | Zone Canonical Biome Mapping | `wilderness_map_generator.py` maps canonical zones to rich biomes | M3 | DONE |
| 13 | WebApp API Biome Query Param | `tools/serve_webapp.py` accepts `?biome=` in `/api/map` | M3 | DONE |
| 14 | Unit & Regression Test Fixes | Update `test_war_fog_and_procedural_map.py` line 50 for 30 biomes | M3 | DONE |
| 15 | E2E Testing Suite (Tiers 1-4) | Database integrity, catalog parity, 100% asset checks, 30 biomes procgen tests | E2E-Track | DONE |
| 16 | Real Browser DevTools Visual Audit | Chrome DevTools visual verification of textures, 60-120 FPS, RAM <= 16.5 MB, screenshots | M4 | DONE |
| 17 | Code & Document Hygiene Gate | Zero Hard Cap violations in `python tools/lint/check_code_and_doc_hygiene.py --strict` | M4 | DONE |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| M1 | R&D & Specification: Database & Catalogs | `data/map_styles.db`, `map_style_*.py`, `map_style_catalog.js` | none | DONE |
| M2 | Design & Asset Pipeline: 30 Styles Assets | `client/webapp/assets/map/styles/` (30 sets of textures & normal maps) | M1 | DONE |
| M3 | Engine & Pipeline: TileMapRenderer & Server | `BiomeTextureManager.js`, `TileMapRenderer.js`, `tile_grid_loader.js`, `map_biome_catalog.py`, `map_binary_serializer.py`, `wilderness_map_generator.py`, `serve_webapp.py` | M1, M2 | DONE |
| E2E | E2E Testing Track | `tests/unit/test_map_styles_db.py`, `test_map_styles_catalog_sync.py`, `test_map_style_assets_integrity.py`, `test_30_biomes_generation_e2e.py` | M1 | DONE |
| M4 | Final Milestone: QA Gate & Browser Visual Audit | Full test suite execution (399 tests pass), Chrome DevTools visual audit with screenshots, hygiene audit | M3, E2E | DONE |

Gate Verdict: **PASS**