feat: add architecture, nations, save/load, and terrain documentation

- Introduced architecture overview detailing high-level data flow and directory structure.
- Documented nation system including spawning pipeline, nation class, political map overlay, and configuration.
- Added save/load system documentation outlining save format, API, and IndexedDB schema.
- Detailed terrain generation pipeline stages including elevation, temperature, humidity, rivers, biomes, resources, and strategic points.
- Implemented NationPanel component for displaying nation details and TileInspector for tile information.

Author: CodeByBryant

README.md

@@ -22,11 +22,19 @@ Watch nations rise and fall in a living, breathing world of emergent geopolitics
 
 ### Procedural World Generation
 
-- **Massive maps** — 2 000 × 1 200 tile worlds rendered with chunked Canvas 2D
-- **Three noise layers** — elevation, temperature and humidity via seeded simplex noise + domain warping
+- **Massive maps** — 2 000 × 2 000 tile worlds with per-tile data (elevation, temperature, humidity, biome, river, resource, ownership)
+- **Web Worker pipeline** — entire terrain generation runs off the main thread with zero-copy `ArrayBuffer` transfers
 - **26 biomes** — from deep ocean and glaciers to tropical rainforests and volcanic peaks, with organic jittered boundaries
 - **Rivers** — Minecraft-style noise zero-crossing algorithm producing primary and secondary waterways with shore tapering
+- **8 resource types** — Timber, Stone, Iron, Gold, Fertile Soil, Fish, Fur & Game — derived from biome, ore noise, elevation and river proximity
 - **Strategic locations** — automatic detection of river crossings, mountain passes, straits and peninsulas scored 0–10
+- **Nation spawning** — 12 nations placed on habitable land with procedural names, colours, flags, governments and personality traits
+
+### Tile Data System
+
+- **Struct-of-arrays** — 8 typed-array layers (Float32Array / Uint8Array) instead of 4M JS objects
+- **WorldMap.at(x, y)** — ergonomic accessor returns a `TileInfo` snapshot with biome, resource, owner, river, shore adjacency
+- **Per-tile ownership** — Uint8Array layer tracking which nation owns each tile (255 = unclaimed)
 
 ### Rendering & Performance
 
@@ -36,15 +44,24 @@ Watch nations rise and fall in a living, breathing world of emergent geopolitics
 - **Spatial-hash tooltip grid** — O(1) strategic point lookups on hover
 - **`{ alpha: false }` canvas context** — lets the browser skip compositing
 
-### Five Overlay Modes
+### Seven Overlay Modes
+
+| Key | Mode        | Visualises                                |
+| --- | ----------- | ----------------------------------------- |
+| `E` | Elevation   | Height map (blue → green → brown → white) |
+| `T` | Temperature | Heat map (blue → red)                     |
+| `H` | Humidity    | Moisture map (tan → teal)                 |
+| `B` | Biome       | Full 26-biome colour palette (default)    |
+| `G` | Strategic   | Biome base + highlighted strategic points |
+| `R` | Resource    | Biome base + tinted resource deposits     |
+| `P` | Political   | Territory colours + nation borders        |
 
-| Key | Mode | Visualises |
-|-----|------|-----------|
-| `E` | Elevation | Height map (blue → green → brown → white) |
-| `T` | Temperature | Heat map (blue → red) |
-| `H` | Humidity | Moisture map (tan → teal) |
-| `B` | Biome | Full 26-biome colour palette (default) |
-| `S` | Strategic | Biome base + highlighted strategic points |
+### State Management & Persistence
+
+- **Zustand store** — single source of truth for phase routing, view mode, world data, nations
+- **Title screen** — seed input + "New World" button with phase-based routing
+- **Save / Load** — binary format in IndexedDB (~68 MB per 2000×2000 world)
+- **Tile inspector** — hover tooltip showing biome · river · resource · strategic · nation (toggle: `I`)
 
 ### Desktop & Web
 
@@ -98,55 +115,77 @@ npm run build:linux
 
 ## Controls
 
-| Input | Action |
-|-------|--------|
-| Click + drag | Pan the camera |
-| Scroll wheel | Zoom in / out |
-| `E` | Elevation overlay |
-| `T` | Temperature overlay |
-| `H` | Humidity overlay |
-| `B` | Biome overlay |
-| `S` | Strategic overlay |
+| Input        | Action                |
+| ------------ | --------------------- |
+| Click + drag | Pan the camera        |
+| Scroll wheel | Zoom in / out         |
+| `E`          | Elevation overlay     |
+| `T`          | Temperature overlay   |
+| `H`          | Humidity overlay      |
+| `B`          | Biome overlay         |
+| `G`          | Strategic overlay     |
+| `R`          | Resource overlay      |
+| `P`          | Political overlay     |
+| `I`          | Toggle tile inspector |
+| `S`          | Toggle toolbar        |
 
 ---
 
 ## Architecture
 
 ```
 sovereign/
-├── electron/              # Electron main + preload
+├── electron/                # Electron main + preload
 │   ├── main/
 │   └── preload/
 ├── src/
 │   ├── config/
-│   │   └── Config.ts      # Every tunable parameter in one place
+│   │   └── Config.ts        # Every tunable parameter in one place
 │   ├── core/
-│   │   ├── ai/            # (Phase 2+) AI decision systems
+│   │   ├── ai/              # (Phase 4+) AI decision systems
 │   │   ├── camera/
-│   │   │   └── Camera.ts  # Pan / zoom state
-│   │   ├── entities/      # (Phase 2+) Nations, units
+│   │   │   └── Camera.ts    # Pan / zoom state
+│   │   ├── entities/
+│   │   │   ├── Nation.ts          # Nation class (provinces, stats, personality)
+│   │   │   ├── NameGenerator.ts   # Procedural nation names
+│   │   │   ├── ColorGenerator.ts  # Golden-angle colour spacing
+│   │   │   └── FlagGenerator.ts   # Procedural flag patterns
 │   │   ├── rendering/
-│   │   │   └── Renderer.ts# Chunked Canvas 2D draw loop
+│   │   │   └── Renderer.ts  # Chunked Canvas 2D draw loop
 │   │   ├── simulation/
 │   │   │   └── Simulation.ts
+│   │   ├── state/
+│   │   │   ├── GameStore.ts      # Zustand global store
+│   │   │   └── persistence.ts    # IndexedDB save / load
+│   │   ├── systems/
+│   │   │   └── NationSpawner.ts  # Greedy spawn + territory claiming
 │   │   ├── terrain/
 │   │   │   ├── biomes.ts           # 26-biome classifier
 │   │   │   ├── rivers.ts           # Noise zero-crossing rivers
+│   │   │   ├── resources.ts        # 8 resource types generator
 │   │   │   ├── strategic.ts        # Strategic point detection
+│   │   │   ├── terrain.worker.ts   # Web Worker pipeline
 │   │   │   └── TerrainGenerator.ts # Orchestrates all layers
-│   │   ├── systems/       # (Phase 2+) ECS-style systems
 │   │   └── world/
-│   │       └── WorldMap.ts
-│   ├── styles/            # SCSS w/ tokens, mixins, components
-│   ├── types/             # Shared TypeScript interfaces
+│   │       └── WorldMap.ts   # Struct-of-arrays tile storage
+│   ├── styles/               # SCSS w/ tokens, mixins, components
+│   ├── types/
+│   │   ├── resources.ts      # ResourceType enum + metadata
+│   │   └── tile.ts           # TileInfo / TileData interfaces
 │   └── ui/
-│       ├── App.tsx         # Main React component + toolbar
-│       └── main.tsx        # Entry point
-├── public/                # Static assets
-├── docs/                  # Documentation
-├── electron-builder.yml   # Desktop packaging config
+│       ├── App.tsx           # Phase router
+│       ├── MapView.tsx       # Canvas + toolbar + tooltip + worker
+│       ├── TitleScreen.tsx   # Seed input + New World
+│       └── main.tsx          # Entry point
+├── public/                   # Static assets
+├── docs/                     # Documentation
+│   ├── architecture.md
+│   ├── terrain.md
+│   ├── nations.md
+│   └── save-load.md
+├── electron-builder.yml      # Desktop packaging config
 ├── electron.vite.config.ts
-└── vite.config.ts         # Web-only Vite config
+└── vite.config.ts            # Web-only Vite config
 ```
 
 ---
@@ -161,15 +200,21 @@ sovereign/
 - [x] Camera pan & zoom
 - [x] River generation (primary + secondary waterways)
 - [x] Strategic point detection (river crossings, mountain passes, straits, peninsulas)
-- [x] Five overlay modes with bottom toolbar
+- [x] Web Worker terrain pipeline with zero-copy transfers
 - [x] JSDoc documentation across all modules
 
-### Phase 2 — Nation Spawning (next)
+### Phase 2 — Foundation & Nation Spawning ✅
 
-- [ ] Nation entity system with unique traits
-- [ ] 5 × 5 starting territories
-- [ ] Political map overlay
-- [ ] Province selection & tooltips
+- [x] Struct-of-arrays tile data (WorldMap)
+- [x] 8 resource types derived from biome, ore noise, elevation & rivers
+- [x] Title screen with seed input
+- [x] Zustand state management + phase routing
+- [x] Save / Load via IndexedDB (binary format)
+- [x] Seven overlay modes (Elevation, Temperature, Humidity, Biome, Strategic, Resource, Political)
+- [x] Tile inspector tooltip
+- [x] Nation entity system with procedural names, colours, flags & personality
+- [x] Greedy spawn placement + 5 × 5 starting territories
+- [x] Political map overlay with territory colouring
 
 ### Phase 3 — Expansion & Borders
 
@@ -188,7 +233,7 @@ sovereign/
 - [ ] God Mode (intervention tools)
 - [ ] Historical timeline & statistics
 
-> See individual phase docs in `docs/` for details.
+> See individual phase docs in [`docs/`](docs/) for details.
 
 ---
 
@@ -223,4 +268,4 @@ Contributions are welcome! The project is in early development.
 
 Built with [Electron](https://www.electronjs.org/) · [React](https://react.dev/) · [TypeScript](https://www.typescriptlang.org/) · [simplex-noise](https://github.com/jwagner/simplex-noise.js)
 
-</div>
+</div>

docs/architecture.md

@@ -0,0 +1,154 @@
+# Architecture Overview
+
+> Last updated: February 2026 · v0.2.0
+
+Sovereign is a procedural geopolitical simulation built with **React 18 + TypeScript + Canvas 2D**, shipped as both an **Electron** desktop app and a **static web build** via Vite.
+
+---
+
+## High-Level Data Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  TitleScreen                                              │
+│  User picks seed → GameStore.setPhase('generating')       │
+└──────────────┬───────────────────────────────────────────┘
+               ▼
+┌──────────────────────────────────────────────────────────┐
+│  MapView (mounts)                                         │
+│  Spawns terrain Web Worker                                │
+│  ┌──────────────────────────────────────────────────────┐ │
+│  │  terrain.worker.ts (off main thread)                 │ │
+│  │  elevation → waterDist → temp → humidity → rivers    │ │
+│  │  → biomes → resources → strategic → ImageData maps   │ │
+│  │  Posts back transferable ArrayBuffers (zero-copy)     │ │
+│  └──────────────────────────────────────────────────────┘ │
+│  Main thread receives → builds WorldMap + chunks          │
+│  → spawnNations() → builds political overlay              │
+│  GameStore.setPhase('playing')                            │
+│                                                           │
+│  Render loop: Camera → frustum cull → draw chunks         │
+│  Tooltip: WorldMap.at(x,y) → TileInfo                     │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+src/
+├── config/
+│   └── Config.ts              # Central config (every tunable param)
+├── core/
+│   ├── ai/                    # (Phase 4+) AI decision systems
+│   ├── camera/
+│   │   └── Camera.ts          # Pan / zoom / screen↔world transforms
+│   ├── entities/
+│   │   ├── Nation.ts           # Nation class: provinces, stats, personality
+│   │   ├── NameGenerator.ts   # Procedural fantasy nation names
+│   │   ├── ColorGenerator.ts  # Golden-angle hue spacing for distinct colours
+│   │   └── FlagGenerator.ts   # 6-pattern procedural flag data
+│   ├── rendering/
+│   │   └── Renderer.ts        # Chunked ImageBitmap compositing + culling
+│   ├── simulation/
+│   │   └── Simulation.ts      # requestAnimationFrame throttle + FPS counter
+│   ├── state/
+│   │   ├── GameStore.ts       # Zustand store (single source of truth)
+│   │   └── persistence.ts     # Save/load via IndexedDB (binary format)
+│   ├── systems/
+│   │   └── NationSpawner.ts   # Spawn N nations on habitable land
+│   ├── terrain/
+│   │   ├── TerrainGenerator.ts# Elevation, temp, humidity field gen
+│   │   ├── biomes.ts          # 26-biome classifier + colour palette
+│   │   ├── rivers.ts          # Noise zero-crossing river system
+│   │   ├── resources.ts       # Resource layer (Timber→Fur) from biome/noise
+│   │   ├── strategic.ts       # Strategic point detection
+│   │   └── terrain.worker.ts  # Web Worker orchestrating the full pipeline
+│   └── world/
+│       └── WorldMap.ts        # Struct-of-arrays tile data store
+├── styles/                    # SCSS (tokens, mixins, components)
+├── types/
+│   ├── tile.ts                # TileInfo interface
+│   └── resources.ts           # ResourceType enum + RESOURCE_META
+└── ui/
+    ├── App.tsx                # Phase router (title → generating → playing)
+    ├── TitleScreen.tsx        # Seed input + New World button
+    ├── MapView.tsx            # Canvas + toolbar + tooltip inspector
+    └── main.tsx               # React entry point
+```
+
+---
+
+## Key Design Decisions
+
+### Struct-of-Arrays for Tile Data
+
+With 4 million tiles (2000 × 2000), storing each tile as a JS object would create massive GC pressure. Instead, each property is a flat typed array:
+
+```ts
+elevation: Float32Array // 4M × 4 bytes = 16 MB
+temperature: Float32Array // 16 MB
+humidity: Float32Array // 16 MB
+biomeIds: Uint8Array // 4 MB
+riverMask: Uint8Array // 4 MB
+resourceType: Uint8Array // 4 MB
+resourceDensity: Uint8Array // 4 MB
+ownership: Uint8Array // 4 MB
+// Total: ~68 MB
+```
+
+The `WorldMap.at(x, y)` method composes a `TileInfo` object on demand, so the ergonomic API exists without the memory overhead.
+
+### Web Worker for Generation
+
+All terrain generation (elevation, temperature, humidity, rivers, biomes, resources, strategic detection, and ImageData rendering) runs in a dedicated Web Worker. Results are posted back as **transferable** `ArrayBuffer`s — true zero-copy transfer, not structured clone.
+
+### Chunked Rendering
+
+The map is split into 64 × 64 tile chunks, each rasterised into an `ImageBitmap`. The renderer only draws chunks overlapping the camera viewport (frustum culling). View switching swaps cached bitmap sets into the same chunk layout without re-rasterising.
+
+### Zustand State Store
+
+A single zustand store (`GameStore`) holds all application state:
+
+- `phase`: drives routing (`'title'` → `'generating'` → `'playing'`)
+- `view`: which map overlay is active
+- `worldMap`: the WorldMap instance (tile data)
+- `nations`: spawned Nation instances
+- `seed`, `fps`, `inspectorEnabled`, etc.
+
+### Save/Load Format
+
+Binary blob stored in IndexedDB:
+
+```
+[4-byte header length (LE)] [JSON header] [binary payload]
+```
+
+The JSON header holds metadata (seed, dimensions, strategic points). The binary payload is the concatenated typed array buffers. This avoids Base64 overhead and handles 60+ MB save files efficiently.
+
+---
+
+## Module Dependency Graph
+
+```
+Config.ts ◄──────────── everything reads config
+    │
+    ▼
+TerrainGenerator.ts
+    │
+    ├──► biomes.ts
+    ├──► rivers.ts
+    ├──► resources.ts
+    ├──► strategic.ts
+    │
+    ▼
+terrain.worker.ts ──(postMessage)──► MapView.tsx
+                                        │
+                                        ├──► WorldMap.ts ◄── TileInfo / ResourceType
+                                        ├──► NationSpawner.ts ◄── Nation / NameGen / ColorGen / FlagGen
+                                        ├──► Renderer.ts ◄── Camera.ts
+                                        ├──► Simulation.ts
+                                        └──► GameStore.ts ◄── persistence.ts
+```