# DISPATCH: Milestone M4 Implementation (Fog of War & Minimap HUD)

## Agent Identity
- Name: worker_m4_1
- Archetype: teamwork_preview_worker
- Working Directory: c:\Projects\FreeExile\.agents\teamwork\worker_m4_1
- Parent Conversation ID: 1cc48fc5-ce57-4f48-8964-24cab4bfcacc

## Authoritative User Request
MANDATORY: Read the user request at:
c:\Projects\FreeExile\.agents\teamwork\ORIGINAL_REQUEST.md (specifically section ## 2026-10-01T19:19:13Z - R4).

## Mandatory Integrity Warning
DO NOT CHEAT. All implementations must be genuine. DO NOT hardcode test results, create dummy/facade implementations, or circumvent the intended task. A teamwork_preview_auditor will independently verify your work. Integrity violations WILL be detected and your work WILL be rejected.

## Task Objective
Implement the complete Fog of War client-side engine, world canvas visual overlay with entity suppression, and dedicated 120x80 px Minimap HUD component.

## Blueprints and References
Consult and integrate the validated explorer deliverables:
1. `c:\Projects\FreeExile\.agents\teamwork\explorer_m4_1\handoff.md` and `proposed_war_fog.js`
2. `c:\Projects\FreeExile\.agents\teamwork\explorer_m4_2\handoff.md`, `proposed_war_fog_renderer.js`, and `war_fog_renderer.patch`
3. `c:\Projects\FreeExile\.agents\teamwork\explorer_m4_3\handoff.md`, `proposed_minimap_hud.js`, and `proposed_index_patch.diff`

## Specific Implementation Requirements
1. `client/webapp/js/ui/war_fog.js`:
   - Replace with the validated implementation from `explorer_m4_1/proposed_war_fog.js`.
   - 3-state fog matrix (`0=UNEXPLORED`, `1=EXPLORED_FOGGED`, `2=VISIBLE`).
   - Dynamic vision reveal within radius 8 tiles around player with zero-heap updates.
   - Compact bit-packed `localStorage` persistence keyed by `fe_fog_${zoneId}_${seed}` (< 2 KB for 120x90).
   - Maintain backward-compatible modal exports and handlers for `#modal-war-fog` to preserve existing UI tests.
   - Strictly <= 300 lines (Soft cap 350, Hard cap 500 lines).

2. `client/webapp/js/ui/war_fog_renderer.js`:
   - Replace with the validated implementation from `explorer_m4_2/proposed_war_fog_renderer.js`.
   - Dark shroud rendering: 0=UNEXPLORED (pitch black), 1=EXPLORED_FOGGED (semi-transparent shadow), 2=VISIBLE (clear).
   - Zero-heap 2-pass batch draw architecture with smooth horizon radial vignette.
   - Strictly <= 250 lines (Soft cap 350, Hard cap 500 lines).

3. Entity Suppression in Engine Files:
   - `client/webapp/js/engine/world_renderer.js`: Hide dynamic ground drops and loot beams outside VISIBLE tiles; only render Waypoints / Boss Gate rune if discovered (fogState >= 1). Wire `WarFogRenderer.render(ctx, camera, viewport)`. Keep file <= 480 lines (Hard cap 500 lines).
   - `client/webapp/js/engine/entity_renderer.js`: Suppress active monsters and NPCs on non-VISIBLE tiles (fogState !== 2). Suppress unrevealed props (fogState === 0). Keep file <= 450 lines (Hard cap 500 lines).
   - `client/webapp/js/engine/monster_system.js`: In `getBestCombatTarget`, ignore monsters whose tile is not VISIBLE (fogState !== 2). Keep file <= 490 lines (Hard cap 500 lines).

4. `client/webapp/js/ui/minimap_hud.js`:
   - Implement using the validated blueprint from `explorer_m4_3/proposed_minimap_hud.js`.
   - Dedicated 120x80 px canvas in top-right HUD.
   - Aspect-ratio preserving uniform scaling with centering offsets.
   - Dual-layer `baseCanvas` offscreen caching and 30 Hz mobile battery throttling. Freezes when `window.isGamePaused = true`.
   - Dynamic indicators: player blip with heading orientation line, waypoints, locked/unlocked Boss Gate, discovered POIs.
   - Strictly <= 280 lines (Soft cap 350, Hard cap 500 lines).

5. `client/webapp/index.html`:
   - Add `#minimap-container` in header and script import for `minimap_hud.js`.
   - Strictly <= 200 lines (Soft cap 200, Hard cap 400 lines).

6. Automated Unit Tests:
   - Create `tests/unit/test_fog_and_minimap.py` synthesizing test cases from `explorer_m4_1/proposed_test_war_fog.py` and `explorer_m4_3/proposed_test_fog_and_minimap.py`.
   - Strictly <= 300 lines.

## Verification Requirements
Run and verify all test suites:
- `pytest tests/unit/test_fog_and_minimap.py -v` (Must PASS all tests)
- `pytest tests/unit/test_tile_collision.py -v` (11/11 PASS)
- `pytest tests/unit/test_mobile_webapp_config.py -v` (Must PASS)
- `pytest tests/e2e/test_poe2_map_system_e2e.py -v` (81/81 PASS)
- `node tools/perf/map_render_benchmark.js` (Must PASS with 0 stationary re-bakes)
- `pytest tests/unit/ -q` (all unit tests must PASS with zero regressions)
- `python tools/lint/check_code_and_doc_hygiene.py --strict` (0 violations)

Report all test command results in your handoff report.