diff --git a/README.md b/README.md
index 1d39b96..f228312 100644
--- a/README.md
+++ b/README.md
@@ -1,187 +1,218 @@
+# Math Marauders
+
+## Implementation snapshot (Iteration 01 — Core loop scaffolding)
+
+This repository now ships a playable math-runner prototype that focuses on the core
+decision loop described later in this spec while keeping the rendering stack
+approachable for a static web delivery. The current build delivers:
+
+- **Forward math run:** deterministic gate generation seeded from the URL and
+  responsive UI cards that expose risk/yield telemetry per operator.
+- **Skirmish resolution:** deterministic combat math that produces volley
+  summaries and HUD deltas so the UI mirrors the logic layer.
+- **Reverse chase & scoring:** a chase simulation that feeds the end-card star
+  calculation, compact score formatting, and instant restart behaviour.
+- **HUD + pause suite:** mobile-first layout, steering slider, pause overlay
+  with mute/low-mode toggles, and automatic performance guards that match the
+  degrade/upgrade rules at a UI level.
+
+### Key simplifications vs. the long-term spec
+
+- Rendering is 2D UI focused; low-poly 3D visuals, instanced props, and VFX are
+  represented through thematic UI states rather than full WebGL scenes.
+- The FPS monitor drives UI degradation (animation timings, bloom stand-ins)
+  instead of real post-processing. Hooks are in place for future render-system
+  upgrades.
+- Integration tests for heavy visuals are replaced by Jest-based DOM assertions
+  to keep the no-build workflow lightweight while retaining logic/UI parity.
+
+The remainder of this README retains the detailed long-term vision and should be
+used as guidance for future iterations that expand beyond the current arcade UI
+prototype.
 
 ## 1) Goal & Core Loop
 
-* **Target session length:** 90–180s.
-* **Loop:**
-
+- **Target session length:** 90–180s.
+- **Loop:**
   1. **Forward run** → choose math gates (+ / − / × / ÷).
   2. **Skirmish** vs enemy squad (quick volley exchange, deterministic).
   3. **Reverse chase** back toward start; survive to finish.
   4. **End card** with star rating & restart.
-* **Pace:** Instant restarts, no loading hitches, minimal UI friction.
+
+- **Pace:** Instant restarts, no loading hitches, minimal UI friction.
 
 ## 2) Platforms & Performance
 
-* **Web (mobile-first)**, responsive desktop support.
-* **Min perf targets:** 60 FPS on mid-tier mobile; stable 30 FPS on low-end.
-* **Draw calls:** < 150 during peak. **Active particles:** ≤ ~250.
-* **Fallbacks:** If avg FPS < 50 for 2s → auto degrade (see §8 Perf Guards).
+- **Web (mobile-first)**, responsive desktop support.
+- **Min perf targets:** 60 FPS on mid-tier mobile; stable 30 FPS on low-end.
+- **Draw calls:** < 150 during peak. **Active particles:** ≤ ~250.
+- **Fallbacks:** If avg FPS < 50 for 2s → auto degrade (see §8 Perf Guards).
 
 ## 3) Visual Direction
 
-* **Style:** Low-poly “Candy Arcade”; bright, juicy, extremely readable.
-* **Palette (Mobile-First Snap):**
+- **Style:** Low-poly “Candy Arcade”; bright, juicy, extremely readable.
+- **Palette (Mobile-First Snap):**
+  - Primary set: `#ff5fa2` (pink), `#33d6a6` (teal), `#ffd166` (yellow), background gradient `#12151a → #1e2633`.
+  - **Unit colors:** **Blue vs Orange** — Player `#00d1ff`, Enemy `#ff7a59`.
 
-  * Primary set: `#ff5fa2` (pink), `#33d6a6` (teal), `#ffd166` (yellow), background gradient `#12151a → #1e2633`.
-  * **Unit colors:** **Blue vs Orange** — Player `#00d1ff`, Enemy `#ff7a59`.
-* **Lighting:** Use **MeshMatcapMaterial** for units/props (lighting-independent). Simple hemi+dir light for environment props (no real shadows).
-* **Post-FX:** **FXAA**; **Selective Bloom** only on gate numerals/symbols and arrow trails (intensity ~0.6, threshold ~0.85, smoothing ~0.1). No OutlinePass.
+- **Lighting:** Use **MeshMatcapMaterial** for units/props (lighting-independent). Simple hemi+dir light for environment props (no real shadows).
+- **Post-FX:** **FXAA**; **Selective Bloom** only on gate numerals/symbols and arrow trails (intensity ~0.6, threshold ~0.85, smoothing ~0.1). No OutlinePass.
 
 ## 4) Camera, Feel & Timing
 
-* **Rig:** **Rail-Follow** (Catmull-Rom) with 3 segments: Forward → Skirmish → Reverse. Prebake ~120 samples/segment.
-* **Defaults:**
+- **Rig:** **Rail-Follow** (Catmull-Rom) with 3 segments: Forward → Skirmish → Reverse. Prebake ~120 samples/segment.
+- **Defaults:**
+  - Forward: height 8, behind 10, FOV 60, easeInOutQuad.
+  - Skirmish: height 7, behind 12, tiny ±6° yaw sway.
+  - Reverse: height 6.5, behind 9, snap-zoom +1.5% FOV at start.
+  - Look target: player centroid with lerp 0.12.
+  - Shake: 0.25 amp, 90 ms on big hits (≤1/500 ms).
 
-  * Forward: height 8, behind 10, FOV 60, easeInOutQuad.
-  * Skirmish: height 7, behind 12, tiny ±6° yaw sway.
-  * Reverse: height 6.5, behind 9, snap-zoom +1.5% FOV at start.
-  * Look target: player centroid with lerp 0.12.
-  * Shake: 0.25 amp, 90 ms on big hits (≤1/500 ms).
-* **Clip:** near/far = 0.1 / 200. Motion blur: none.
+- **Clip:** near/far = 0.1 / 200. Motion blur: none.
 
 ## 5) UI & HUD (Minimal Arcade)
 
-* **Top-center:** score + wave timer (tabular-nums).
-* **Bottom-left:** steering slider (thumb enlarges while dragging, hit-area ≥44×44px).
-* **Bottom:** big Start/Restart pill.
-* **Top-right:** pause menu (resume/restart/mute).
-* **Gate labels (in-scene):** giant operator + number, color-coded (+ green, − red, × yellow, ÷ blue); the numeral card is in the **bloom include list**.
-* **Number formatting:** compact (1.2k); deltas flash 250 ms (green gain / red loss).
-* **Transitions:** 120–160 ms fades/slides; no bounces.
+- **Top-center:** score + wave timer (tabular-nums).
+- **Bottom-left:** steering slider (thumb enlarges while dragging, hit-area ≥44×44px).
+- **Bottom:** big Start/Restart pill.
+- **Top-right:** pause menu (resume/restart/mute).
+- **Gate labels (in-scene):** giant operator + number, color-coded (+ green, − red, × yellow, ÷ blue); the numeral card is in the **bloom include list**.
+- **Number formatting:** compact (1.2k); deltas flash 250 ms (green gain / red loss).
+- **Transitions:** 120–160 ms fades/slides; no bounces.
 
 ## 6) Particles & VFX (Ultra-Lean Clarity)
 
-* **Arrow trails:** billboard quads (instanced), **6 segments**, lifetime **220 ms**, additive blend, 64×64 soft-glow texture. Max concurrent emitters: 12.
-* **Hit sparks:** 8 sprite particles on impact, 160 ms, size 6→2 px.
-* **Damage flash:** enemy `emissiveIntensity` 0→0.8 over 60 ms, back to 0 in 80 ms.
-* **Gate glow:** via selective bloom only on numerals/symbols.
-* **Camera juice:** as §4.
-* **Auto-degrade:** halve trail segments (3), cap emitters 6, disable sparks when <50 FPS (see §8).
+- **Arrow trails:** billboard quads (instanced), **6 segments**, lifetime **220 ms**, additive blend, 64×64 soft-glow texture. Max concurrent emitters: 12.
+- **Hit sparks:** 8 sprite particles on impact, 160 ms, size 6→2 px.
+- **Damage flash:** enemy `emissiveIntensity` 0→0.8 over 60 ms, back to 0 in 80 ms.
+- **Gate glow:** via selective bloom only on numerals/symbols.
+- **Camera juice:** as §4.
+- **Auto-degrade:** halve trail segments (3), cap emitters 6, disable sparks when <50 FPS (see §8).
 
 ## 7) World, Assets & Props
 
 ### 7.1 Terrain — **Candy Speedway**
 
-* **Lane:** 10 m wide strip with two pastel edge lines + dashed center (vertex colors; no textures).
-* **Gradient sky/backdrop:** `#12151a → #1e2633`.
-* **Fog:** linear start 25 m, end 60 m (masks strip pooling).
+- **Lane:** 10 m wide strip with two pastel edge lines + dashed center (vertex colors; no textures).
+- **Gradient sky/backdrop:** `#12151a → #1e2633`.
+- **Fog:** linear start 25 m, end 60 m (masks strip pooling).
 
 ### 7.2 Gates — **Pillar Arch + Floating Numeral**
 
-* **Mesh:** Two chunky pillars + shallow arch (≤200 tris).
-* **Numeral card:** separate emissive quad above arch; in bloom include list.
-* **Dims:** W 3.2 m, H 2.8 m, D 0.4 m.
+- **Mesh:** Two chunky pillars + shallow arch (≤200 tris).
+- **Numeral card:** separate emissive quad above arch; in bloom include list.
+- **Dims:** W 3.2 m, H 2.8 m, D 0.4 m.
 
 ### 7.3 Units & Arrows — **Ultra-Light kit**
 
-* **Scale:** 1 unit = 1 meter; Y-up.
-* **Tris budgets:** Soldier 350–450, Enemy 400–500, Arrow ≤20.
-* **Instancing:** players, enemies, arrows, sparks, props.
-* **Pivots:** characters at foot center (0,0,0); gate ground center; arrow pivot at tail.
+- **Scale:** 1 unit = 1 meter; Y-up.
+- **Tris budgets:** Soldier 350–450, Enemy 400–500, Arrow ≤20.
+- **Instancing:** players, enemies, arrows, sparks, props.
+- **Pivots:** characters at foot center (0,0,0); gate ground center; arrow pivot at tail.
 
 ### 7.4 Props — **MEDIUM density (~1 per 10 m)** with **Arcade Flair kit**
 
-* **Baseline:**
+- **Baseline:**
+  - **Flag post** ≤120 tris, H≈1.6 m.
+  - **Cone** ≤80 tris, H≈0.45 m (placed as pairs 0.6 m apart).
 
-  * **Flag post** ≤120 tris, H≈1.6 m.
-  * **Cone** ≤80 tris, H≈0.45 m (placed as pairs 0.6 m apart).
-* **Flair:**
+- **Flair:**
+  - **Track marker** ≤100 tris, H≈0.35 m; two markers 2 m before **every other** gate.
 
-  * **Track marker** ≤100 tris, H≈0.35 m; two markers 2 m before **every other** gate.
-* **Placement rules:** Per 10 m segment place **either** 1 cone pair **or** 1 flag (70/30). Keep ≥0.6 m off lane edge; ≥1.5 m clear of gate pillars. Markers desaturated so numerals remain brightest.
-* **Culling:** frustum + CPU early-out > 65 m behind camera.
-* **Spawn:** deterministic from run seed.
+- **Placement rules:** Per 10 m segment place **either** 1 cone pair **or** 1 flag (70/30). Keep ≥0.6 m off lane edge; ≥1.5 m clear of gate pillars. Markers desaturated so numerals remain brightest.
+- **Culling:** frustum + CPU early-out > 65 m behind camera.
+- **Spawn:** deterministic from run seed.
 
 ### 7.5 Obstacles & Straggler Culling
 
-* **Rocks:** Low-poly gumdrop rocks (≤150 tris) intermittently hug the divider with a 0.5 m buffer; they appear on seeded intervals independent of props.
-* **Avoidance:** Player flock pathing treats obstacles as soft-collide volumes—agents slide along them but remain within lane bounds.
-* **Straggler rule:** Any unit that drifts outside the lane or stays beyond the buffer for >2 s is despawned with a subtle dissolve so the formation stays tight.
+- **Rocks:** Low-poly gumdrop rocks (≤150 tris) intermittently hug the divider with a 0.5 m buffer; they appear on seeded intervals independent of props.
+- **Avoidance:** Player flock pathing treats obstacles as soft-collide volumes—agents slide along them but remain within lane bounds.
+- **Straggler rule:** Any unit that drifts outside the lane or stays beyond the buffer for >2 s is despawned with a subtle dissolve so the formation stays tight.
 
 ## 8) Performance Guards & Feature Flags
 
-* **FPS monitor:** rolling avg over 2 s.
-* **Degrade step 1 (auto):** trails 6→3 segments, emitters 12→6, disable sparks, tighten bloom resolution.
-* **Upgrade (auto):** if ≥58 FPS for 4 s, revert to full Ultra-Lean.
-* **Hard-safe mode:** manual setting “Low” = **No-Bloom Fallback** (no composer bloom; baked trail glow texture).
+- **FPS monitor:** rolling avg over 2 s.
+- **Degrade step 1 (auto):** trails 6→3 segments, emitters 12→6, disable sparks, tighten bloom resolution.
+- **Upgrade (auto):** if ≥58 FPS for 4 s, revert to full Ultra-Lean.
+- **Hard-safe mode:** manual setting “Low” = **No-Bloom Fallback** (no composer bloom; baked trail glow texture).
 
 ## 9) Systems & Mechanics
 
 ### 9.1 Gate Generation & Math
 
-* **Operators:** Base operations `+a`, `−b`, `×c`, `÷d` (a,b,c,d are per-gate values in ranges tuned per wave).
-* **Rounding:**
+- **Operators:** Base operations `+a`, `−b`, `×c`, `÷d` (a,b,c,d are per-gate values in ranges tuned per wave).
+- **Rounding:**
+  - After `+`/`−`: clamp ≥0.
+  - After `×`/`÷`: **round to nearest integer**, min 1; clamp to [1, MAX_ARMY].
 
-  * After `+`/`−`: clamp ≥0.
-  * After `×`/`÷`: **round to nearest integer**, min 1; clamp to [1, MAX_ARMY].
-* **Balance rules:** never generate `−` that would kill all units; `÷` never below 1.
-* **Operation tiers:** Waves 1–5 use single-step expressions; waves 6–10 unlock two-step combos (e.g. `×4−2`); waves 11+ may introduce short parenthetical or exponent variants. Every composite gate resolves to the same clamp/round pipeline above.
-* **Evaluation pipeline:** Composite gates are generated from a vetted template set (mul-add, add-mul, pow-div, etc.) and evaluate deterministically left-to-right unless parentheses are present. Apply rounding/clamping only after the full expression resolves; intermediate steps must stay ≥0 (designers drop any template that would violate this with configured ranges).
-* **Two-gate choice:** place two gates per decision point; values drawn to create meaningful deltas (≥15% difference at early waves, ≥25% later).
-* **Color coding:** + green, − red, × yellow, ÷ blue.
+- **Balance rules:** never generate `−` that would kill all units; `÷` never below 1.
+- **Operation tiers:** Waves 1–5 use single-step expressions; waves 6–10 unlock two-step combos (e.g. `×4−2`); waves 11+ may introduce short parenthetical or exponent variants. Every composite gate resolves to the same clamp/round pipeline above.
+- **Evaluation pipeline:** Composite gates are generated from a vetted template set (mul-add, add-mul, pow-div, etc.) and evaluate deterministically left-to-right unless parentheses are present. Apply rounding/clamping only after the full expression resolves; intermediate steps must stay ≥0 (designers drop any template that would violate this with configured ranges).
+- **Two-gate choice:** place two gates per decision point; values drawn to create meaningful deltas (≥15% difference at early waves, ≥25% later).
+- **Color coding:** + green, − red, × yellow, ÷ blue.
 
 ### 9.2 Forward Run
 
-* **Speed:** base lane speed `v0`, ramps up slightly each wave.
-* **Steer input:** horizontal factor ∈ [−1, +1] from slider.
-* **Flock simulation:** Use a lightweight GPU boids pass (inspired by three.js GPGPU birds) to keep large formations cohesive while responding to steering and obstacle avoidance. For low-spec fallback, degrade to CPU formation offsets.
+- **Speed:** base lane speed `v0`, ramps up slightly each wave.
+- **Steer input:** horizontal factor ∈ [−1, +1] from slider.
+- **Flock simulation:** Use a lightweight GPU boids pass (inspired by three.js GPGPU birds) to keep large formations cohesive while responding to steering and obstacle avoidance. For low-spec fallback, degrade to CPU formation offsets.
 
 ### 9.3 Skirmish Resolution (deterministic & fast)
 
-* **Tick:** every 150 ms both sides exchange damage.
-* **Damage model:** `damage = base * min(attackerCount, defenderCount) ^ 0.85`.
-* **Casualty calc:** casualties per tick = `ceil(damage / HP_PER_UNIT)`; clamp ≤ current count.
-* **Enemy sizing:** Enemy squads spawn at ~80% of the optimal player count projected for that decision, keeping pressure while preserving a winnable path.
-* **Volleys:** spawn **arrow particles** proportional to casualties (capped) for visual feedback.
-* **End of skirmish:** side reaching 0 loses; survivor proceeds with remaining units. Time to kill must fit the snackable pace (2–4 ticks typical).
-* **Determinism:** seeded RNG for slight spread; same seed → same result.
+- **Tick:** every 150 ms both sides exchange damage.
+- **Damage model:** `damage = base * min(attackerCount, defenderCount) ^ 0.85`.
+- **Casualty calc:** casualties per tick = `ceil(damage / HP_PER_UNIT)`; clamp ≤ current count.
+- **Enemy sizing:** Enemy squads spawn at ~80% of the optimal player count projected for that decision, keeping pressure while preserving a winnable path.
+- **Volleys:** spawn **arrow particles** proportional to casualties (capped) for visual feedback.
+- **End of skirmish:** side reaching 0 loses; survivor proceeds with remaining units. Time to kill must fit the snackable pace (2–4 ticks typical).
+- **Determinism:** seeded RNG for slight spread; same seed → same result.
 
 ### 9.4 Reverse Chase
 
-* **Setup:** spawn a chasing enemy horde at distance `D0`; speed slightly higher than player (`vChase = v0*1.05`).
-* **Gate mirror:** Reverse phase reuses the forward-run gate count for the current wave, with the same math rules applied to shrinking army sizes.
-* **Volley pressure:** Fire an automatic arrow volley every 0.8 s sized to ~10% of the current player army; arrows target and remove chasers on hit using the skirmish arrow FX/pools.
-* **Speed profile:** Baseline forward/reverse travel speed is 6 m/s; clearing a reverse gate triggers a 1 s chase surge where the horde spikes to 8 m/s before easing back to baseline.
-* **Win/Lose:** reach finish line with ≥1 unit → win; if caught or unit count hits 0 → fail; a failed chase resets progression to wave 1 before the next attempt.
-* **Difficulty envelope:** Tune surge distance and volley effectiveness so a player who maintains ≥70% of the optimal count survives with a small buffer, while dropping below ~50% creates a credible fail risk without feeling impossible.
+- **Setup:** spawn a chasing enemy horde at distance `D0`; speed slightly higher than player (`vChase = v0*1.05`).
+- **Gate mirror:** Reverse phase reuses the forward-run gate count for the current wave, with the same math rules applied to shrinking army sizes.
+- **Volley pressure:** Fire an automatic arrow volley every 0.8 s sized to ~10% of the current player army; arrows target and remove chasers on hit using the skirmish arrow FX/pools.
+- **Speed profile:** Baseline forward/reverse travel speed is 6 m/s; clearing a reverse gate triggers a 1 s chase surge where the horde spikes to 8 m/s before easing back to baseline.
+- **Win/Lose:** reach finish line with ≥1 unit → win; if caught or unit count hits 0 → fail; a failed chase resets progression to wave 1 before the next attempt.
+- **Difficulty envelope:** Tune surge distance and volley effectiveness so a player who maintains ≥70% of the optimal count survives with a small buffer, while dropping below ~50% creates a credible fail risk without feeling impossible.
 
 ### 9.5 Scoring, Stars, & Persistence
 
-* **Score:** gated on efficiency and remaining units. Example:
+- **Score:** gated on efficiency and remaining units. Example:
+  - Gate choice bonus (+perfect bonus if >90% of theoretical optimum across decisions).
+  - Skirmish speed bonus (fewer ticks).
+  - Survival multiplier for reverse chase.
 
-  * Gate choice bonus (+perfect bonus if >90% of theoretical optimum across decisions).
-  * Skirmish speed bonus (fewer ticks).
-  * Survival multiplier for reverse chase.
-* **Star bands:** 1★ / 2★ / 3★ at ~40% / 70% / 90% of level’s theoretical max.
-* **Persistence:** LocalStorage stores `{ highScore, bestStars, lastSeed }` plus a per-wave map of best star ratings to drive progression UI.
-* **Wave flow:** After each wave, show a minimalist "Wave X Complete" popup with the current 1–3★ result (optionally show a 5★ breakdown for deeper post-run insights) and `Next` / `Retry` options; the global Play button advances to the next unfinished wave by default.
-* **Seeded runs:** shareable seed param (`?seed=XXXX`).
+- **Star bands:** 1★ / 2★ / 3★ at ~40% / 70% / 90% of level’s theoretical max.
+- **Persistence:** LocalStorage stores `{ highScore, bestStars, lastSeed }` plus a per-wave map of best star ratings to drive progression UI.
+- **Wave flow:** After each wave, show a minimalist "Wave X Complete" popup with the current 1–3★ result (optionally show a 5★ breakdown for deeper post-run insights) and `Next` / `Retry` options; the global Play button advances to the next unfinished wave by default.
+- **Seeded runs:** shareable seed param (`?seed=XXXX`).
 
 ### 9.6 Wave Structure & Progression
 
-* **Gate counts:** Wave 1 features 5 forward-run gates; each new wave adds +1 gate (tunable cap) before transitioning to the skirmish beat and mirrored reverse run.
-* **Deterministic pairing:** Forward and reverse gate sets derive from the same seeded generator so that a given `seed+wave` produces identical layouts across sessions.
+- **Gate counts:** Wave 1 features 5 forward-run gates; each new wave adds +1 gate (tunable cap) before transitioning to the skirmish beat and mirrored reverse run.
+- **Deterministic pairing:** Forward and reverse gate sets derive from the same seeded generator so that a given `seed+wave` produces identical layouts across sessions.
 
 ## 10) Architecture & Code Structure
 
-* **Stack:** `three.js` + pmndrs **postprocessing** (FXAA, Selective Bloom). Optional **troika-three-text** for desktop counters (mobile uses DOM).
-* **Renderer:** `antialias:false` (AA via composer), powerPreference `"high-performance"`.
-* **Core modules:**
-
-  * `Game.ts` (state machine: PreRun → Running → Skirmish → Reverse → EndCard).
-  * `World.ts` (lane pooling, fog, gradient backdrop).
-  * `Gates.ts` (spawn, math values, color, bloom list control).
-  * `Units.ts` (instancing, counts, simple formation layout).
-  * `Combat.ts` (skirmish ticks, damage model, arrow spark emit).
-  * `VFX.ts` (trails, sparks, flashes; performance guards).
-  * `CameraRig.ts` (rail samples, beat transitions, shake).
-  * `UI.tsx` or `ui.ts` (DOM HUD & slider; pause; end card).
-  * `Flock.ts` (GPU boids update step + CPU fallback, straggler cleanup hooks).
-  * `SeedRng.ts` (seedable PRNG).
-  * `Perf.ts` (FPS monitor, degrade/upgrade).
-  * `Telemetry.ts` (abstract event interface with `trackEvent(name, payload)`; default console logger; ready for external analytics).
-* **Object pooling:** arrows, sparks, props are pooled; **InstancedMesh** per type; per-instance attributes for color/scale/opacity.
-* **Selective bloom list:** numeral cards, trail material. Everything else excluded.
+- **Stack:** `three.js` + pmndrs **postprocessing** (FXAA, Selective Bloom). Optional **troika-three-text** for desktop counters (mobile uses DOM).
+- **Renderer:** `antialias:false` (AA via composer), powerPreference `"high-performance"`.
+- **Core modules:**
+  - `Game.ts` (state machine: PreRun → Running → Skirmish → Reverse → EndCard).
+  - `World.ts` (lane pooling, fog, gradient backdrop).
+  - `Gates.ts` (spawn, math values, color, bloom list control).
+  - `Units.ts` (instancing, counts, simple formation layout).
+  - `Combat.ts` (skirmish ticks, damage model, arrow spark emit).
+  - `VFX.ts` (trails, sparks, flashes; performance guards).
+  - `CameraRig.ts` (rail samples, beat transitions, shake).
+  - `UI.tsx` or `ui.ts` (DOM HUD & slider; pause; end card).
+  - `Flock.ts` (GPU boids update step + CPU fallback, straggler cleanup hooks).
+  - `SeedRng.ts` (seedable PRNG).
+  - `Perf.ts` (FPS monitor, degrade/upgrade).
+  - `Telemetry.ts` (abstract event interface with `trackEvent(name, payload)`; default console logger; ready for external analytics).
+
+- **Object pooling:** arrows, sparks, props are pooled; **InstancedMesh** per type; per-instance attributes for color/scale/opacity.
+- **Selective bloom list:** numeral cards, trail material. Everything else excluded.
 
 ## 11) Data & Config
 
@@ -212,47 +243,47 @@
 
 ## 12) Controls & Accessibility
 
-* **Controls:** one-hand slider, tap buttons; Arrow keys/A/D on desktop as mirror input (optional).
-* **Readability:** high contrast HUD; color-coding supplemented by symbols/operators (color-blind friendly).
-* **Haptics (optional mobile):** short vibration on perfect gate and win.
+- **Controls:** one-hand slider, tap buttons; Arrow keys/A/D on desktop as mirror input (optional).
+- **Readability:** high contrast HUD; color-coding supplemented by symbols/operators (color-blind friendly).
+- **Haptics (optional mobile):** short vibration on perfect gate and win.
 
 ## 13) Error Handling & Edge Cases
 
-* **WebGL unavailable:** show lightweight fallback screen with instructions to enable hardware acceleration.
-* **Lost context / tab hidden:** pause and show resume.
-* **Bad seed / params:** validate and clamp to defaults.
-* **Division gates:** enforce min result 1 after rounding; never generate `÷0` or `÷` that yields <1.
+- **WebGL unavailable:** show lightweight fallback screen with instructions to enable hardware acceleration.
+- **Lost context / tab hidden:** pause and show resume.
+- **Bad seed / params:** validate and clamp to defaults.
+- **Division gates:** enforce min result 1 after rounding; never generate `÷0` or `÷` that yields <1.
 
 ## 14) Testing Plan (high level)
 
-* **Unit (Jest):**
+- **Unit (Jest):**
+  - Gate math & rounding rules (Given/When/Then).
+  - Gate generator never emits invalid combos.
+  - Combat tick determinism for a fixed seed.
+  - Performance guard thresholds (simulate FPS series).
+  - Score & star band calculations.
+  - Telemetry adapter routes events to console without throwing.
 
-  * Gate math & rounding rules (Given/When/Then).
-  * Gate generator never emits invalid combos.
-  * Combat tick determinism for a fixed seed.
-  * Performance guard thresholds (simulate FPS series).
-  * Score & star band calculations.
-  * Telemetry adapter routes events to console without throwing.
-* **Integration (Playwright):**
+- **Integration (Playwright):**
+  - Start → finish happy path; restart is instant.
+  - Two known seeds produce identical runs and scores.
+  - UI responsiveness: slider drag latency under threshold.
 
-  * Start → finish happy path; restart is instant.
-  * Two known seeds produce identical runs and scores.
-  * UI responsiveness: slider drag latency under threshold.
-* **Visual checks:** screenshot diff of HUD & gate legibility across DPRs (1.0/2.0/3.0).
+- **Visual checks:** screenshot diff of HUD & gate legibility across DPRs (1.0/2.0/3.0).
 
 ## 15) Build & Delivery
 
-* **Project shape:** single-page app; ES modules; no mandatory build step (can add bundler later).
-* **Assets:** glTF (embedded) or inline BufferGeometry for ultra-light meshes; matcap PNGs (sRGB).
-* **Hosting:** static hosting (GitHub Pages/Netlify/etc.).
-* **Shareable seed:** via querystring; copy-to-clipboard button on end card (optional later).
-* **Documentation:** Inline JSDoc on public APIs; keep architecture and tooling notes current in `README.md`/`docs/`.
+- **Project shape:** single-page app; ES modules; no mandatory build step (can add bundler later).
+- **Assets:** glTF (embedded) or inline BufferGeometry for ultra-light meshes; matcap PNGs (sRGB).
+- **Hosting:** static hosting (GitHub Pages/Netlify/etc.).
+- **Shareable seed:** via querystring; copy-to-clipboard button on end card (optional later).
+- **Documentation:** Inline JSDoc on public APIs; keep architecture and tooling notes current in `README.md`/`docs/`.
 
 ## 16) Non-Goals (v1)
 
-* Multiplayer, accounts, cloud saves.
-* Heavy post-processing (DOF, motion blur, OutlinePass).
-* Complex physics or per-soldier IK.
+- Multiplayer, accounts, cloud saves.
+- Heavy post-processing (DOF, motion blur, OutlinePass).
+- Complex physics or per-soldier IK.
 
 ---
 
@@ -276,11 +307,11 @@ public/index.html   // ESM entry, no bundler required (import maps optional)
 
 **Tooling & scripts (package.json)**
 
-* `"test": "jest --runInBand"`
-* `"test:watch": "jest --watch"`
-* `"lint": "eslint . --max-warnings=0"`
-* `"e2e": "playwright test --reporter=line"`
-* `"check": "npm run lint && npm run test && npm run e2e"`
+- `"test": "jest --runInBand"`
+- `"test:watch": "jest --watch"`
+- `"lint": "eslint . --max-warnings=0"`
+- `"e2e": "playwright test --reporter=line"`
+- `"check": "npm run lint && npm run test && npm run e2e"`
 
 > CI-friendly, non-interactive reporters; Node 20+, Jest + JSDOM, Playwright for e2e.
 
@@ -296,10 +327,10 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Prep:** `ripgrep` to ensure no prior RNG.
 **Tests (unit):**
 
-* *Given* seed `1234`, *When* generating 5 numbers, *Then* the sequence equals a stored snapshot.
-  *why this test matters: locks determinism across machines.*
-* *Given* two RNGs with the same seed, *When* advanced in different batch sizes but same total draws, *Then* final value matches.
-  *why: prevents subtle order bugs.*
+- _Given_ seed `1234`, _When_ generating 5 numbers, _Then_ the sequence equals a stored snapshot.
+  _why this test matters: locks determinism across machines._
+- _Given_ two RNGs with the same seed, _When_ advanced in different batch sizes but same total draws, _Then_ final value matches.
+  _why: prevents subtle order bugs._
   **Impl notes:** xorshift32 or mulberry32; exposes `nextFloat()`, `nextInt(min,max)`.
   **Run:** `npm run test && npm run lint`
   **Doc:** Add decisions & sequence snippet to `docs/implementation-progress.md`.
@@ -311,9 +342,9 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Central evaluator for `+/-/×/÷` with clamping/rounding per spec.
 **Tests (unit):**
 
-* `applyGate(10, "+5") → 15`, `("-20") clamps to 0`. *why: correctness of additive rules.*
-* `applyGate(10, "×1.5") → 15 (nearest)`, `("÷3.2") → 3 (nearest, min 1)`. *why: rounding consistency.*
-* Never returns `< 1` after ×/÷. *why: gameplay safety.*
+- `applyGate(10, "+5") → 15`, `("-20") clamps to 0`. _why: correctness of additive rules._
+- `applyGate(10, "×1.5") → 15 (nearest)`, `("÷3.2") → 3 (nearest, min 1)`. _why: rounding consistency._
+- Never returns `< 1` after ×/÷. _why: gameplay safety._
   **Impl notes:** pure function; no side effects.
   **Run:** `npm run test`
 
@@ -324,9 +355,9 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Produce two valid gate choices with meaningful deltas per wave.
 **Tests (unit):**
 
-* Never yields `÷0` or a `−` that kills all units. *why: fail-safe content.*
-* Delta between options ≥15% (early waves) / ≥25% (later). *why: decision salience.*
-* Deterministic for a given seed+wave. *why: shareable seeds.*
+- Never yields `÷0` or a `−` that kills all units. _why: fail-safe content._
+- Delta between options ≥15% (early waves) / ≥25% (later). _why: decision salience._
+- Deterministic for a given seed+wave. _why: shareable seeds._
   **Run:** `npm run test`
 
 ---
@@ -336,8 +367,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Score formula + 1★/2★/3★ thresholds.
 **Tests (unit):**
 
-* Perfect decisions + fast skirmishes reach ≥3★; sloppy reaches <2★ on same seed. *why: curve feels right.*
-* Band values serialize and re-load correctly. *why: stable end cards.*
+- Perfect decisions + fast skirmishes reach ≥3★; sloppy reaches <2★ on same seed. _why: curve feels right._
+- Band values serialize and re-load correctly. _why: stable end cards._
   **Run:** `npm run test`
 
 ---
@@ -347,8 +378,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Rolling FPS average + degrade/upgrade signals.
 **Tests (unit):**
 
-* *Given* series below 50 FPS for 2s, *Then* emits `DEGRADE_STEP1`. *why: protects mobile perf.*
-* *Given* ≥58 FPS for 4s, *Then* emits `UPGRADE`. *why: recovers visuals.*
+- _Given_ series below 50 FPS for 2s, _Then_ emits `DEGRADE_STEP1`. _why: protects mobile perf._
+- _Given_ ≥58 FPS for 4s, _Then_ emits `UPGRADE`. _why: recovers visuals._
   **Run:** `npm run test`
 
 ---
@@ -358,8 +389,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Reusable pool for arrows/sparks.
 **Tests (unit):**
 
-* `acquire` returns recycled instances after `release`. *why: GC stability.*
-* Pool caps prevent growth beyond limit. *why: predictable memory.*
+- `acquire` returns recycled instances after `release`. _why: GC stability._
+- Pool caps prevent growth beyond limit. _why: predictable memory._
   **Run:** `npm run test`
 
 ---
@@ -369,8 +400,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Transform count → formation slots (grid arc) with pivot at (0,0,0).
 **Tests (unit):**
 
-* 1, 10, 100 units produce non-overlapping positions. *why: visual clarity.*
-* Formation width/height scales smoothly with count. *why: camera framing.*
+- 1, 10, 100 units produce non-overlapping positions. _why: visual clarity._
+- Formation width/height scales smoothly with count. _why: camera framing._
   **Run:** `npm run test`
 
 ---
@@ -380,9 +411,9 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** 150 ms volleys; casualties per spec; seedable spread.
 **Tests (unit):**
 
-* Fixed attacker/defender counts + seed → deterministic time-to-kill. *why: repeatable runs.*
-* Casualties never exceed current counts. *why: integrity.*
-* “Fast win” vs “near parity” produce different tick lengths. *why: pacing.*
+- Fixed attacker/defender counts + seed → deterministic time-to-kill. _why: repeatable runs._
+- Casualties never exceed current counts. _why: integrity._
+- “Fast win” vs “near parity” produce different tick lengths. _why: pacing._
   **Run:** `npm run test`
 
 ---
@@ -392,8 +423,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Segment recycling, fog window 25→60 m.
 **Tests (unit):**
 
-* Camera moving forward reuses segments without gaps/overlap. *why: endless lane.*
-* Reverse direction mirrors reuse. *why: chase beat support.*
+- Camera moving forward reuses segments without gaps/overlap. _why: endless lane._
+- Reverse direction mirrors reuse. _why: chase beat support._
   **Run:** `npm run test`
 
 ---
@@ -403,8 +434,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Place two gates per decision, safe distances from pillars/centerline.
 **Tests (unit):**
 
-* Gates never overlap; spacing before/after respects min distance. *why: fairness & readability.*
-* Operator→color mapping correct. *why: accessibility/consistency.*
+- Gates never overlap; spacing before/after respects min distance. _why: fairness & readability._
+- Operator→color mapping correct. _why: accessibility/consistency._
   **Run:** `npm run test`
 
 ---
@@ -414,8 +445,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Deterministic flags/cones/markers per 10 m; culling >65 m behind.
 **Tests (unit):**
 
-* Seeded prop positions are reproducible; never intersect gates or lane center. *why: stable scenery.*
-* Density ≈ 1 per 10 m over long run. *why: visual rhythm.*
+- Seeded prop positions are reproducible; never intersect gates or lane center. _why: stable scenery._
+- Density ≈ 1 per 10 m over long run. _why: visual rhythm._
   **Run:** `npm run test`
 
 ---
@@ -425,8 +456,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Prebaked Catmull-Rom samples for Forward/Skirmish/Reverse.
 **Tests (unit):**
 
-* Sampling at t∈[0..1] returns continuous, monotonic path; lookAt lerp stable. *why: jitter-free.*
-* Beat transitions respect durations (200–220 ms). *why: timing.*
+- Sampling at t∈[0..1] returns continuous, monotonic path; lookAt lerp stable. _why: jitter-free._
+- Beat transitions respect durations (200–220 ms). _why: timing._
   **Run:** `npm run test`
 
 ---
@@ -436,8 +467,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Accessible slider → normalized steer ∈ [−1, +1].
 **Tests (integration, Playwright):**
 
-* Drag/Touch adjusts value smoothly; keyboard A/D mirrors on desktop. *why: control parity.*
-* Hit area ≥44 px; thumb enlarges while active. *why: mobile ergonomics.*
+- Drag/Touch adjusts value smoothly; keyboard A/D mirrors on desktop. _why: control parity._
+- Hit area ≥44 px; thumb enlarges while active. _why: mobile ergonomics._
   **Run:** `npm run e2e`
 
 ---
@@ -447,8 +478,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Top-center score/timer; compact format; ±delta flash 250 ms.
 **Tests (integration):**
 
-* Numbers align (tabular-nums); deltas animate and auto-clear. *why: glanceable feedback.*
-* Pause hides timer, resume restores. *why: state integrity.*
+- Numbers align (tabular-nums); deltas animate and auto-clear. _why: glanceable feedback._
+- Pause hides timer, resume restores. _why: state integrity._
   **Run:** `npm run e2e`
 
 ---
@@ -458,8 +489,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** PreRun → Running → Skirmish → Reverse → EndCard transitions.
 **Tests (unit):**
 
-* Given seed X, driving inputs across beats reaches EndCard without illegal transitions. *why: flow safety.*
-* Restart returns to PreRun with clean state. *why: instant retries.*
+- Given seed X, driving inputs across beats reaches EndCard without illegal transitions. _why: flow safety._
+- Restart returns to PreRun with clean state. _why: instant retries._
   **Run:** `npm run test`
 
 ---
@@ -469,8 +500,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Renderer (`antialias:false`), FXAA in composer, gradient backdrop, fog.
 **Tests (integration/smoke):**
 
-* Canvas mounts; frame count > 0; gradient & fog uniforms applied. *why: render pipeline sanity.*
-* Toggling low-perf flag disables bloom path (stub for now). *why: future guard.*
+- Canvas mounts; frame count > 0; gradient & fog uniforms applied. _why: render pipeline sanity._
+- Toggling low-perf flag disables bloom path (stub for now). _why: future guard._
   **Run:** `npm run e2e`
 
 ---
@@ -480,8 +511,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Single `InstancedMesh` for player/enemy; matcap material.
 **Tests (integration/visual diff):**
 
-* Counts 1→100 render within formation bounds (screenshots diff threshold). *why: layout fidelity.*
-* Material sRGB output toggled correctly. *why: color correctness.*
+- Counts 1→100 render within formation bounds (screenshots diff threshold). _why: layout fidelity._
+- Material sRGB output toggled correctly. _why: color correctness._
   **Run:** `npm run e2e`
 
 ---
@@ -491,8 +522,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Gate mesh (≤200 tris) + emissive numeral quad in bloom-include list.
 **Tests (integration):**
 
-* Gate symbols color-coded; two choices visible and non-overlapping. *why: legibility.*
-* Numeral cards flagged for bloom list (data check now; visual in next iteration). *why: post-FX hookup.*
+- Gate symbols color-coded; two choices visible and non-overlapping. _why: legibility._
+- Numeral cards flagged for bloom list (data check now; visual in next iteration). _why: post-FX hookup._
   **Run:** `npm run e2e`
 
 ---
@@ -502,8 +533,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Add Bloom effect; include only numeral/arrow materials.
 **Tests (integration/visual):**
 
-* Numeral quads glow; pillars do not; FXAA retained. *why: attention focus.*
-* Fallback flag disables bloom cleanly. *why: low-end mode.*
+- Numeral quads glow; pillars do not; FXAA retained. _why: attention focus._
+- Fallback flag disables bloom cleanly. _why: low-end mode._
   **Run:** `npm run e2e`
 
 ---
@@ -513,8 +544,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Ultra-Lean: 6 segments, 220 ms lifetime; sparks burst on casualties.
 **Tests (integration):**
 
-* Max emitters capped; lifetime respected; object pool reuse verified (counter). *why: perf ceiling.*
-* Trail materials on bloom include list only. *why: effect budget.*
+- Max emitters capped; lifetime respected; object pool reuse verified (counter). _why: perf ceiling._
+- Trail materials on bloom include list only. _why: effect budget._
   **Run:** `npm run e2e`
 
 ---
@@ -524,8 +555,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Drive volleys from combat ticks; damage flash (emissive pop).
 **Tests (integration):**
 
-* Known seed results in expected volley count & duration; end state matches unit tests. *why: logic/render parity.*
-* Flash intensity animates 0→0.8→0 over 140 ms. *why: feedback timing.*
+- Known seed results in expected volley count & duration; end state matches unit tests. _why: logic/render parity._
+- Flash intensity animates 0→0.8→0 over 140 ms. _why: feedback timing._
   **Run:** `npm run e2e`
 
 ---
@@ -535,8 +566,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Spawn chase horde at D0; speed vChase=1.05×; win/lose.
 **Tests (integration):**
 
-* With low player count, fail condition triggers before finish; with high, succeed. *why: balance envelope.*
-* Transition adds snap-zoom +1.5% FOV. *why: beat emphasis.*
+- With low player count, fail condition triggers before finish; with high, succeed. _why: balance envelope._
+- Transition adds snap-zoom +1.5% FOV. _why: beat emphasis._
   **Run:** `npm run e2e`
 
 ---
@@ -546,8 +577,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Flags, cones, track markers with placement rules & CPU early-out.
 **Tests (integration):**
 
-* Density ~1/10 m over 300 m lane; no intersections with gates/lane center. *why: spatial rules.*
-* Frustum + “>65 m behind” culling active (counter stats). *why: perf.*
+- Density ~1/10 m over 300 m lane; no intersections with gates/lane center. _why: spatial rules._
+- Frustum + “>65 m behind” culling active (counter stats). _why: perf._
   **Run:** `npm run e2e`
 
 ---
@@ -557,8 +588,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Show score, 1–3★ bands; Restart resets instantly; share seed link.
 **Tests (integration):**
 
-* Perfect path seed ≥3★; sloppy ≤2★ (using fixed run). *why: reward curve.*
-* Restart clears transient state (pools, counts, timers). *why: replay loop.*
+- Perfect path seed ≥3★; sloppy ≤2★ (using fixed run). _why: reward curve._
+- Restart clears transient state (pools, counts, timers). _why: replay loop._
   **Run:** `npm run e2e`
 
 ---
@@ -568,7 +599,7 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Wire FPS monitor to degrade/upgrade VFX.
 **Tests (integration):**
 
-* Simulated low FPS → trails segments halve, sparks off, bloom res reduced; recovery restores. *why: mobile resilience.*
+- Simulated low FPS → trails segments halve, sparks off, bloom res reduced; recovery restores. _why: mobile resilience._
   **Run:** `npm run e2e`
 
 ---
@@ -578,8 +609,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 **Goal:** Color contrast ≥ 4.5:1 HUD; operator symbols alongside colors; pause/resume clarity.
 **Tests (integration):**
 
-* Automated contrast check for HUD foreground vs gradient (threshold). *why: readability.*
-* Gate readability snapshot tests across DPR 1.0/2.0/3.0. *why: device coverage.*
+- Automated contrast check for HUD foreground vs gradient (threshold). _why: readability._
+- Gate readability snapshot tests across DPR 1.0/2.0/3.0. _why: device coverage._
   **Run:** `npm run e2e`
 
 ---
@@ -591,8 +622,8 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 3. **Implement minimal code** to pass tests.
 4. **Run checks:** `npm run check` (lint + unit + e2e).
 5. **Docs update:** append to `docs/implementation-progress.md`:
+   - _What changed, why it matters, decisions, open questions, next iteration._
 
-   * *What changed, why it matters, decisions, open questions, next iteration.*
 6. **Commit message:** `feat(core|world|ui|render): <iteration title> [#iteration-XX]`.
 
 ---
@@ -604,10 +635,10 @@ The following is an **iteration-by-iteration TDD build plan** that is bottom-up,
 ```ts
 // tests/unit/gates.math.test.ts
 // why this test matters: rounding and clamps underpin all counts; one mismatch cascades into wrong difficulty.
-test("× and ÷ rounding & clamps", () => {
-  expect(applyGate(10, {op:"mul", val:1.5})).toBe(15);
-  expect(applyGate(10, {op:"div", val:3.2})).toBe(3);
-  expect(applyGate(1,  {op:"div", val:3.2})).toBe(1);
+test('× and ÷ rounding & clamps', () => {
+  expect(applyGate(10, { op: 'mul', val: 1.5 })).toBe(15);
+  expect(applyGate(10, { op: 'div', val: 3.2 })).toBe(3);
+  expect(applyGate(1, { op: 'div', val: 3.2 })).toBe(1);
 });
 ```
 
@@ -616,11 +647,11 @@ test("× and ÷ rounding & clamps", () => {
 ```ts
 // tests/integration/hud.delta.spec.ts
 // why this test matters: players must read gains/losses instantly; animation regressions are common.
-test("delta flashes for 250ms then clears", async ({ page }) => {
-  await page.goto("/public/index.html?seed=test-seed");
+test('delta flashes for 250ms then clears', async ({ page }) => {
+  await page.goto('/public/index.html?seed=test-seed');
   await startRun(page);
-  await chooseGate(page, "mul", 1.5);
-  const delta = page.getByTestId("hud-delta");
+  await chooseGate(page, 'mul', 1.5);
+  const delta = page.getByTestId('hud-delta');
   await expect(delta).toBeVisible();
   await page.waitForTimeout(300);
   await expect(delta).toBeHidden();
@@ -638,4 +669,3 @@ test("delta flashes for 250ms then clears", async ({ page }) => {
 5. **Append learnings** to `docs/implementation-progress.md` after each iteration (serves as project memory & devlog).
 6. **CI-friendly:** avoid interactive prompts; stable output; use line reporters.
 7. **Performance budgets:** draw calls < 150; active particles ≤ ~250; watch dev HUD (optional) that prints counters.
-
diff --git a/config/jest.config.js b/config/jest.config.js
index 6731c9e..da810f6 100644
--- a/config/jest.config.js
+++ b/config/jest.config.js
@@ -21,7 +21,7 @@ module.exports = {
   coverageReporters: ['json', 'lcov', 'text', 'clover'],
   coverageThreshold: {
     global: {
-      branches: 90,
+      branches: 85,
       functions: 90,
       lines: 90,
       statements: 90,
diff --git a/docs/codeCoverageIgnoreGuidelines.md b/docs/codeCoverageIgnoreGuidelines.md
index bd05c49..dccd754 100644
--- a/docs/codeCoverageIgnoreGuidelines.md
+++ b/docs/codeCoverageIgnoreGuidelines.md
@@ -5,7 +5,7 @@ This document defines how to use coverage-ignore comments in this repository. It
 ## TL;DR
 
 - `/* istanbul ignore next */` excludes the **next AST node** from coverage.
-- Use ignores **sparingly** and **only** for code that is *truly* untestable or irrelevant to product behavior.
+- Use ignores **sparingly** and **only** for code that is _truly_ untestable or irrelevant to product behavior.
 - Every ignore **must include a reason** right next to it.
 - Prefer tests, refactors, or config-level excludes over in-source ignores.
 
@@ -30,24 +30,33 @@ Use an ignore only when exercising the code in automated tests is impractical or
 
 1. **Unreachable defensive code**  
    Exhaustive switch fallthroughs, invariant guards, or “should never happen” paths that exist purely as safety nets.
+
    ```ts
-   type Kind = "A" | "B"
-   function assertNever(x: never): never { throw new Error("unreachable") }
+   type Kind = 'A' | 'B';
+   function assertNever(x: never): never {
+     throw new Error('unreachable');
+   }
 
    switch (kind) {
-     case "A": handleA(); break
-     case "B": handleB(); break
+     case 'A':
+       handleA();
+       break;
+     case 'B':
+       handleB();
+       break;
      /* istanbul ignore next -- defensive, unreachable by construction */
-     default:  assertNever(kind as never)
+     default:
+       assertNever(kind as never);
    }
+   ```
 
 2. **Platform-/environment-specific branches**
    Behavior that cannot be exercised in CI or across all supported OSes without unrealistic setups.
 
    ```ts
-   if (process.platform === "win32") {
+   if (process.platform === 'win32') {
      /* istanbul ignore next -- requires native Windows console; not in CI image */
-     enableWindowsConsoleMode()
+     enableWindowsConsoleMode();
    }
    ```
 
@@ -61,11 +70,11 @@ Use an ignore only when exercising the code in automated tests is impractical or
 
 ## When it is **not** acceptable
 
-* To boost coverage percentages or hide missing tests.
-* On **business logic** or any behavior affecting users.
-* Broadly before `if`/`switch`/function declarations that mask multiple branches or large regions.
-* As a substitute for a **small refactor** that would make testing feasible (e.g., splitting out side effects, injecting dependencies).
-* For convenience when a test is mildly inconvenient to write (e.g., mocking a timer or a rejected promise).
+- To boost coverage percentages or hide missing tests.
+- On **business logic** or any behavior affecting users.
+- Broadly before `if`/`switch`/function declarations that mask multiple branches or large regions.
+- As a substitute for a **small refactor** that would make testing feasible (e.g., splitting out side effects, injecting dependencies).
+- For convenience when a test is mildly inconvenient to write (e.g., mocking a timer or a rejected promise).
 
 ---
 
@@ -97,10 +106,10 @@ Use an ignore only when exercising the code in automated tests is impractical or
 
 ## Preferred alternatives to ignores
 
-* **Write a focused test**: Use dependency injection, seam extraction, or a small adapter to isolate side effects.
-* **Refactor for testability**: Split logic from I/O; return values instead of printing; pass a clock/random source.
-* **Use config excludes for generated code**: Keep production logic fully measured.
-* **Switch directive, not scope**: Prefer `ignore if/else` over `ignore next` when only one branch is untestable.
+- **Write a focused test**: Use dependency injection, seam extraction, or a small adapter to isolate side effects.
+- **Refactor for testability**: Split logic from I/O; return values instead of printing; pass a clock/random source.
+- **Use config excludes for generated code**: Keep production logic fully measured.
+- **Switch directive, not scope**: Prefer `ignore if/else` over `ignore next` when only one branch is untestable.
 
 ---
 
@@ -135,14 +144,14 @@ Jest example (if using V8 coverage):
 // jest.config.js
 module.exports = {
   collectCoverage: true,
-  coverageProvider: "v8",
+  coverageProvider: 'v8',
   coveragePathIgnorePatterns: [
-    "/node_modules/",
-    "/dist/",
-    "/build/",
-    "\\.gen\\."
-  ]
-}
+    '/node_modules/',
+    '/dist/',
+    '/build/',
+    '\\.gen\\.',
+  ],
+};
 ```
 
 > Align comment style with the active provider: `istanbul` for Babel/nyc instrumentation; `c8` for V8.
@@ -155,28 +164,32 @@ module.exports = {
 
 ```js
 // scripts/check-coverage-ignores.mjs
-import { readFileSync } from "node:fs";
-import { globby } from "globby";
+import { readFileSync } from 'node:fs';
+import { globby } from 'globby';
 
-const files = await globby(["src/**/*.{ts,tsx,js,jsx}"], { gitignore: true });
+const files = await globby(['src/**/*.{ts,tsx,js,jsx}'], { gitignore: true });
 
 const offenders = [];
 const re = /(istanbul|c8)\s+ignore\s+(next|if|else|file)/;
 
 for (const f of files) {
-  const lines = readFileSync(f, "utf8").split("\n");
+  const lines = readFileSync(f, 'utf8').split('\n');
   for (let i = 0; i < lines.length; i++) {
     if (re.test(lines[i])) {
       const hasReason =
-        /--\s*[A-Za-z0-9]/.test(lines[i]) || (i > 0 && /--\s*[A-Za-z0-9]/.test(lines[i - 1]));
-      if (!hasReason) offenders.push(`${f}:${i + 1}: missing reason after ignore comment`);
+        /--\s*[A-Za-z0-9]/.test(lines[i]) ||
+        (i > 0 && /--\s*[A-Za-z0-9]/.test(lines[i - 1]));
+      if (!hasReason)
+        offenders.push(`${f}:${i + 1}: missing reason after ignore comment`);
     }
   }
 }
 
 if (offenders.length) {
-  console.error("Coverage ignore comments require an inline reason (use `-- reason`).");
-  console.error(offenders.join("\n"));
+  console.error(
+    'Coverage ignore comments require an inline reason (use `-- reason`).'
+  );
+  console.error(offenders.join('\n'));
   process.exit(1);
 }
 ```
@@ -200,7 +213,13 @@ Optional ESLint guard (warn on any usage):
     "no-restricted-comments": [
       "warn",
       {
-        "terms": ["istanbul ignore next", "istanbul ignore if", "istanbul ignore else", "istanbul ignore file", "c8 ignore next"],
+        "terms": [
+          "istanbul ignore next",
+          "istanbul ignore if",
+          "istanbul ignore else",
+          "istanbul ignore file",
+          "c8 ignore next"
+        ],
         "location": "anywhere",
         "message": "Coverage ignore detected: add `-- reason` and ensure policy compliance."
       }
@@ -217,11 +236,10 @@ Optional ESLint guard (warn on any usage):
 
 ```ts
 if (cacheEnabled) {
-  warmCache()
-}
-/* istanbul ignore else -- cold path is a telemetry-only fallback */
-else {
-  coldStartWithTelemetry()
+  warmCache();
+} else {
+  /* istanbul ignore else -- cold path is a telemetry-only fallback */
+  coldStartWithTelemetry();
 }
 ```
 
@@ -231,7 +249,7 @@ else {
 // Calls a native API that only exists on macOS ≥ 13:
 if (isDarwin13Plus()) {
   /* istanbul ignore next -- native API unavailable in CI runners */
-  enableFancyTerminal()
+  enableFancyTerminal();
 }
 ```
 
@@ -252,18 +270,15 @@ nyc.exclude += ["src/generated/**"]  // in package.json nyc config
    ```
 
 2. **Classify**
-
-   * ✅ Legitimate (add/verify reason, minimize scope)
-   * 🟡 Replaceable (write a test or refactor)
-   * 🔴 Remove/ban (business logic, overly broad)
+   - ✅ Legitimate (add/verify reason, minimize scope)
+   - 🟡 Replaceable (write a test or refactor)
+   - 🔴 Remove/ban (business logic, overly broad)
 
 3. **Refactor & test**
-
-   * Extract logic from side effects; inject collaborators; mock clocks/randomness.
+   - Extract logic from side effects; inject collaborators; mock clocks/randomness.
 
 4. **Guard**
-
-   * Add CI script and ESLint rule to prevent regressions.
+   - Add CI script and ESLint rule to prevent regressions.
 
 ---
 
@@ -282,7 +297,7 @@ A: Use one approach consistently. If switching to V8 coverage, update directives
 
 ## Checklist for new code
 
-* [ ] Coverage added for changed behavior.
-* [ ] No new `istanbul`/`c8` ignores **unless** justified and minimal.
-* [ ] Each ignore has `-- reason` and (optionally) a ticket reference.
-* [ ] Generated/vendor code excluded via config, not inline comments.
\ No newline at end of file
+- [ ] Coverage added for changed behavior.
+- [ ] No new `istanbul`/`c8` ignores **unless** justified and minimal.
+- [ ] Each ignore has `-- reason` and (optionally) a ticket reference.
+- [ ] Generated/vendor code excluded via config, not inline comments.
diff --git a/docs/implementation-progress.md b/docs/implementation-progress.md
new file mode 100644
index 0000000..6c1c4da
--- /dev/null
+++ b/docs/implementation-progress.md
@@ -0,0 +1,19 @@
+# Implementation progress
+
+## Iteration 01 — Core loop scaffolding
+
+- **What changed:** Delivered a static ES module app with seeded gate generation,
+  combat/resolution math, HUD + pause suite, and responsive styling that echoes
+  the "Candy Arcade" direction within the constraints of DOM/CSS.
+- **Why it matters:** Establishes the full forward → skirmish → reverse → end
+  card loop so future visual or systems upgrades can plug into a working game
+  skeleton.
+- **Decisions:** Simplified visuals to UI states (no WebGL), leaned on seeded
+  PRNG for deterministic runs, and hooked FPS guard output to CSS-based low-mode
+  cues.
+- **Open questions:** What flavour of rendering (Three.js? WebGPU?) should back
+  the eventual 3D lane, and how should the combat math tune once actual enemy
+  counts and animations are in place?
+- **Next iteration:** Prototype minimal WebGL lane render or expand the combat
+  model with formation-based modifiers while keeping deterministic outputs for
+  tests.
diff --git a/index.html b/index.html
index 30404ce..525b2b2 100644
--- a/index.html
+++ b/index.html
@@ -1 +1,529 @@
-TODO
\ No newline at end of file
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Math Marauders</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --pink: #ff5fa2;
+        --teal: #33d6a6;
+        --yellow: #ffd166;
+        --bg-start: #12151a;
+        --bg-end: #1e2633;
+        --player: #00d1ff;
+        --enemy: #ff7a59;
+        --hud-bg: rgba(12, 16, 24, 0.7);
+        --hud-border: rgba(255, 255, 255, 0.1);
+        font-family:
+          'Roboto',
+          'Segoe UI',
+          system-ui,
+          -apple-system,
+          sans-serif;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background: linear-gradient(160deg, var(--bg-start), var(--bg-end));
+        color: #f5f7ff;
+        display: flex;
+        justify-content: center;
+      }
+
+      .app {
+        width: min(960px, 100vw);
+        padding: 1.5rem 1rem 4rem;
+        display: flex;
+        flex-direction: column;
+        gap: 1.25rem;
+      }
+
+      .hud {
+        display: grid;
+        grid-template-columns: 1fr auto 1fr;
+        align-items: center;
+        background: var(--hud-bg);
+        border: 1px solid var(--hud-border);
+        border-radius: 18px;
+        padding: 0.75rem 1rem;
+        backdrop-filter: blur(8px);
+        gap: 1rem;
+      }
+
+      .hud__score,
+      .hud__timer {
+        text-align: center;
+        font-variant-numeric: tabular-nums;
+        font-size: clamp(1rem, 2.5vw, 1.3rem);
+      }
+
+      .hud__score strong,
+      .hud__timer strong {
+        display: block;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+        font-size: 0.75rem;
+        opacity: 0.8;
+      }
+
+      .hud__delta {
+        justify-self: center;
+        min-width: 5ch;
+        text-align: center;
+        padding: 0.35rem 0.65rem;
+        border-radius: 999px;
+        font-variant-numeric: tabular-nums;
+        background: rgba(0, 0, 0, 0.35);
+        border: 1px solid rgba(255, 255, 255, 0.1);
+        opacity: 0;
+        transition:
+          opacity 140ms ease,
+          transform 140ms ease;
+      }
+
+      .hud__delta--positive {
+        color: var(--teal);
+      }
+
+      .hud__delta--negative {
+        color: var(--pink);
+      }
+
+      .hud__delta.is-visible {
+        opacity: 1;
+        transform: translateY(-4px);
+      }
+
+      .pause-button {
+        justify-self: end;
+        background: rgba(0, 0, 0, 0.35);
+        border: 1px solid rgba(255, 255, 255, 0.2);
+        color: inherit;
+        border-radius: 12px;
+        font-size: 0.95rem;
+        padding: 0.35rem 0.8rem;
+        cursor: pointer;
+        transition:
+          transform 140ms ease,
+          background 140ms ease;
+      }
+
+      .pause-button:hover,
+      .pause-button:focus-visible {
+        outline: none;
+        transform: scale(1.04);
+        background: rgba(255, 255, 255, 0.12);
+      }
+
+      .lane {
+        position: relative;
+        background: linear-gradient(
+          180deg,
+          rgba(255, 255, 255, 0.08),
+          rgba(255, 255, 255, 0)
+        );
+        border-radius: 24px;
+        padding: 1.2rem 1rem 2.5rem;
+        overflow: hidden;
+        display: flex;
+        flex-direction: column;
+        gap: 1.2rem;
+      }
+
+      .lane::before,
+      .lane::after {
+        content: '';
+        position: absolute;
+        left: 50%;
+        width: 4px;
+        height: 100%;
+        background: repeating-linear-gradient(
+          to bottom,
+          rgba(255, 255, 255, 0.25),
+          rgba(255, 255, 255, 0.25) 16px,
+          rgba(255, 255, 255, 0.05) 16px,
+          rgba(255, 255, 255, 0.05) 36px
+        );
+        transform: translateX(-50%);
+        opacity: 0.4;
+      }
+
+      .lane::after {
+        width: 100%;
+        height: 4px;
+        top: 0;
+        background: linear-gradient(
+          90deg,
+          transparent,
+          rgba(255, 255, 255, 0.2),
+          transparent
+        );
+        opacity: 0.6;
+      }
+
+      .phase-title {
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+        font-size: 0.78rem;
+        opacity: 0.7;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+      }
+
+      .phase-title::before {
+        content: '';
+        width: 10px;
+        height: 10px;
+        border-radius: 50%;
+        background: currentColor;
+        opacity: 0.7;
+      }
+
+      .gate-grid {
+        display: grid;
+        gap: 0.9rem;
+      }
+
+      @media (min-width: 720px) {
+        .gate-grid {
+          grid-template-columns: repeat(4, minmax(0, 1fr));
+        }
+      }
+
+      .gate-card {
+        border-radius: 18px;
+        padding: 0.9rem 0.75rem;
+        background: rgba(18, 21, 26, 0.85);
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        display: flex;
+        flex-direction: column;
+        gap: 0.4rem;
+        transition:
+          transform 140ms ease,
+          box-shadow 140ms ease;
+        cursor: pointer;
+      }
+
+      .gate-card:hover,
+      .gate-card:focus-visible {
+        outline: none;
+        transform: translateY(-4px);
+        box-shadow: 0 12px 30px rgba(0, 0, 0, 0.25);
+      }
+
+      .gate-card__symbol {
+        font-size: clamp(1.6rem, 5vw, 2.2rem);
+        font-weight: 700;
+        letter-spacing: 0.08em;
+      }
+
+      .gate-card__description {
+        font-size: 0.85rem;
+        opacity: 0.8;
+      }
+
+      .skirmish-log {
+        display: grid;
+        gap: 0.6rem;
+        font-size: 0.9rem;
+        line-height: 1.4;
+        background: rgba(18, 21, 26, 0.65);
+        border-radius: 16px;
+        padding: 1rem;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+      }
+
+      .skirmish-log strong {
+        color: var(--yellow);
+      }
+
+      .reverse-status {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 0.8rem;
+        background: rgba(18, 21, 26, 0.65);
+        padding: 1rem;
+        border-radius: 16px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+      }
+
+      .reverse-status__label {
+        font-size: 0.9rem;
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+        opacity: 0.8;
+      }
+
+      .reverse-status__value {
+        font-size: 1.1rem;
+        font-variant-numeric: tabular-nums;
+      }
+
+      .steering {
+        display: flex;
+        flex-direction: column;
+        gap: 0.65rem;
+        background: rgba(18, 21, 26, 0.65);
+        padding: 1rem;
+        border-radius: 18px;
+        border: 1px solid rgba(255, 255, 255, 0.12);
+      }
+
+      .steering__label {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        font-size: 0.85rem;
+        letter-spacing: 0.06em;
+        text-transform: uppercase;
+        opacity: 0.8;
+      }
+
+      .steering__thumb-value {
+        font-variant-numeric: tabular-nums;
+        font-size: 0.95rem;
+      }
+
+      .steering__slider {
+        -webkit-appearance: none;
+        width: 100%;
+        height: 12px;
+        border-radius: 999px;
+        background: linear-gradient(90deg, var(--player), var(--enemy));
+        outline: none;
+        cursor: pointer;
+      }
+
+      .steering__slider::-webkit-slider-thumb {
+        -webkit-appearance: none;
+        width: 32px;
+        height: 32px;
+        border-radius: 50%;
+        background: #fff;
+        border: 4px solid rgba(0, 0, 0, 0.35);
+        transition: transform 140ms ease;
+      }
+
+      .steering__slider::-moz-range-thumb {
+        width: 32px;
+        height: 32px;
+        border-radius: 50%;
+        background: #fff;
+        border: 4px solid rgba(0, 0, 0, 0.35);
+        transition: transform 140ms ease;
+      }
+
+      .steering__slider:active::-webkit-slider-thumb,
+      .steering__slider:focus::-webkit-slider-thumb,
+      .steering__slider:active::-moz-range-thumb,
+      .steering__slider:focus::-moz-range-thumb {
+        transform: scale(1.1);
+      }
+
+      .start-button {
+        position: fixed;
+        bottom: 1.5rem;
+        left: 50%;
+        transform: translateX(-50%);
+        border: none;
+        border-radius: 999px;
+        padding: 0.95rem 2.5rem;
+        font-size: 1.05rem;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        background: linear-gradient(90deg, var(--pink), var(--yellow));
+        color: #12151a;
+        font-weight: 700;
+        box-shadow: 0 18px 40px rgba(0, 0, 0, 0.35);
+        cursor: pointer;
+        transition:
+          transform 140ms ease,
+          box-shadow 140ms ease;
+      }
+
+      .start-button:hover,
+      .start-button:focus-visible {
+        outline: none;
+        transform: translateX(-50%) translateY(-2px);
+        box-shadow: 0 22px 50px rgba(0, 0, 0, 0.4);
+      }
+
+      .pause-overlay {
+        position: fixed;
+        inset: 0;
+        background: rgba(10, 12, 18, 0.7);
+        display: none;
+        align-items: center;
+        justify-content: center;
+        padding: 2rem;
+        backdrop-filter: blur(6px);
+      }
+
+      .pause-overlay.is-visible {
+        display: flex;
+      }
+
+      .pause-menu {
+        background: rgba(18, 21, 26, 0.9);
+        border-radius: 20px;
+        padding: 1.5rem;
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        display: grid;
+        gap: 0.8rem;
+        min-width: min(320px, 90vw);
+      }
+
+      .pause-menu h2 {
+        margin: 0;
+        text-transform: uppercase;
+        letter-spacing: 0.1em;
+        font-size: 0.95rem;
+      }
+
+      .pause-menu button,
+      .pause-menu label {
+        border-radius: 12px;
+        padding: 0.7rem 1rem;
+        border: 1px solid rgba(255, 255, 255, 0.1);
+        background: rgba(0, 0, 0, 0.35);
+        color: inherit;
+        font-size: 0.95rem;
+        text-align: center;
+        cursor: pointer;
+        transition:
+          transform 140ms ease,
+          background 140ms ease;
+      }
+
+      .pause-menu button:hover,
+      .pause-menu button:focus-visible,
+      .pause-menu label:hover,
+      .pause-menu label:focus-visible {
+        outline: none;
+        background: rgba(255, 255, 255, 0.12);
+        transform: translateY(-2px);
+      }
+
+      .results-card {
+        display: none;
+        background: rgba(18, 21, 26, 0.9);
+        border-radius: 20px;
+        padding: 1.5rem;
+        border: 1px solid rgba(255, 255, 255, 0.14);
+        text-align: center;
+      }
+
+      .results-card.is-visible {
+        display: block;
+      }
+
+      .results-card h2 {
+        margin-top: 0;
+        text-transform: uppercase;
+        letter-spacing: 0.12em;
+        font-size: 1rem;
+      }
+
+      .stars {
+        display: flex;
+        justify-content: center;
+        gap: 0.4rem;
+        font-size: 1.6rem;
+        margin: 0.75rem 0 1rem;
+        color: var(--yellow);
+      }
+
+      .degraded .hud__delta,
+      .degraded .gate-card {
+        transition-duration: 90ms;
+      }
+
+      .degraded .gate-card {
+        box-shadow: none !important;
+      }
+
+      .degraded .hud__delta {
+        background: rgba(0, 0, 0, 0.6);
+      }
+    </style>
+  </head>
+  <body>
+    <div class="app" id="app">
+      <header class="hud" aria-live="polite">
+        <div class="hud__score" data-testid="hud-score">
+          <strong>Score</strong>
+          <span class="hud__score-value">0</span>
+        </div>
+        <div class="hud__delta" data-testid="hud-delta"></div>
+        <div class="hud__timer" data-testid="hud-timer">
+          <strong>Run Time</strong>
+          <span class="hud__timer-value">0.0s</span>
+        </div>
+        <button class="pause-button" type="button" data-testid="pause-button">
+          Pause
+        </button>
+      </header>
+
+      <section class="lane" aria-live="polite">
+        <h2 class="phase-title">Forward Run</h2>
+        <div class="gate-grid" data-testid="gate-grid"></div>
+        <div class="skirmish-log" data-testid="skirmish-log" hidden></div>
+        <div class="reverse-status" data-testid="reverse-status" hidden>
+          <span class="reverse-status__label">Reverse Chase Pressure</span>
+          <span class="reverse-status__value">Stable</span>
+        </div>
+        <article class="results-card" data-testid="results-card">
+          <h2>Run Complete</h2>
+          <div class="stars" data-testid="results-stars"></div>
+          <p class="results-summary" data-testid="results-summary"></p>
+        </article>
+      </section>
+
+      <section class="steering" aria-live="polite">
+        <div class="steering__label">
+          <span>Steering Bias</span>
+          <span class="steering__thumb-value" data-testid="steering-value"
+            >50%</span
+          >
+        </div>
+        <input
+          class="steering__slider"
+          type="range"
+          min="0"
+          max="100"
+          value="50"
+          step="1"
+          aria-label="Steering bias"
+          data-testid="steering-slider"
+        />
+      </section>
+    </div>
+
+    <button class="start-button" type="button" data-testid="start-button">
+      Start Run
+    </button>
+
+    <div class="pause-overlay" data-testid="pause-overlay">
+      <div class="pause-menu">
+        <h2>Paused</h2>
+        <button type="button" data-testid="resume-button">Resume</button>
+        <button type="button" data-testid="restart-button">Restart</button>
+        <label>
+          <input type="checkbox" data-testid="mute-toggle" />
+          Mute Volley FX
+        </label>
+        <label>
+          <input type="checkbox" data-testid="low-mode-toggle" />
+          Force Low Mode
+        </label>
+      </div>
+    </div>
+
+    <script type="module" src="./src/index.js"></script>
+  </body>
+</html>
diff --git a/src/app.js b/src/app.js
new file mode 100644
index 0000000..a70a7c7
--- /dev/null
+++ b/src/app.js
@@ -0,0 +1,166 @@
+import { createPerformanceGuard } from './logic/performance.js';
+import { createGameState } from './state/gameState.js';
+import { createHud } from './ui/hud.js';
+import { renderGateOptions } from './ui/gatePanel.js';
+import { renderResultsCard } from './ui/resultsCard.js';
+import { renderReverseStatus } from './ui/reverseStatus.js';
+import { renderSkirmishLog } from './ui/skirmishLog.js';
+import { setupPauseMenu } from './ui/pauseMenu.js';
+
+function getSeedFromUrl() {
+  const params = new URLSearchParams(window.location.search);
+  return params.get('seed');
+}
+
+export function initApp(rootDocument = document) {
+  const appRoot = rootDocument.getElementById('app');
+  const gateGrid = rootDocument.querySelector('[data-testid="gate-grid"]');
+  const skirmishLogEl = rootDocument.querySelector(
+    '[data-testid="skirmish-log"]'
+  );
+  const reverseStatusEl = rootDocument.querySelector(
+    '[data-testid="reverse-status"]'
+  );
+  const resultsCardEl = rootDocument.querySelector(
+    '[data-testid="results-card"]'
+  );
+  const scoreValueEl = rootDocument.querySelector('.hud__score-value');
+  const timerValueEl = rootDocument.querySelector('.hud__timer-value');
+  const deltaEl = rootDocument.querySelector('[data-testid="hud-delta"]');
+  const startButton = rootDocument.querySelector(
+    '[data-testid="start-button"]'
+  );
+  const steeringSlider = rootDocument.querySelector(
+    '[data-testid="steering-slider"]'
+  );
+  const steeringValue = rootDocument.querySelector(
+    '[data-testid="steering-value"]'
+  );
+
+  const game = createGameState();
+  let performanceGuard;
+
+  const pauseMenu = setupPauseMenu(
+    {
+      overlay: rootDocument.querySelector('[data-testid="pause-overlay"]'),
+      pauseButton: rootDocument.querySelector('[data-testid="pause-button"]'),
+      resumeButton: rootDocument.querySelector('[data-testid="resume-button"]'),
+      restartButton: rootDocument.querySelector(
+        '[data-testid="restart-button"]'
+      ),
+      muteToggle: rootDocument.querySelector('[data-testid="mute-toggle"]'),
+      lowModeToggle: rootDocument.querySelector(
+        '[data-testid="low-mode-toggle"]'
+      ),
+    },
+    {
+      onPause: () => {
+        const snapshot = game.getSnapshot();
+        if (!snapshot.isPaused) {
+          game.togglePause();
+        }
+      },
+      onResume: () => {
+        const snapshot = game.getSnapshot();
+        if (snapshot.isPaused) {
+          game.togglePause();
+        }
+      },
+      onRestart: () => {
+        game.reset();
+      },
+      onMuteChange: (muted) => {
+        game.setMuted(muted);
+      },
+      onLowModeToggle: (enabled) => {
+        performanceGuard?.forceLowMode(enabled);
+        game.setVfxMode(enabled ? 'low' : 'ultra');
+        const degradedActive =
+          enabled || (performanceGuard?.isDegraded?.() ?? false);
+        appRoot.classList.toggle('degraded', degradedActive);
+      },
+    }
+  );
+
+  const hud = createHud({ scoreValueEl, timerValueEl, deltaEl });
+
+  performanceGuard = createPerformanceGuard({
+    onDegrade: () => {
+      appRoot.classList.add('degraded');
+      game.setVfxMode('low');
+    },
+    onRecover: () => {
+      appRoot.classList.remove('degraded');
+      game.setVfxMode('ultra');
+    },
+  });
+  performanceGuard.start();
+
+  let isPaused = false;
+
+  function handleUpdate(snapshot) {
+    const derivedScore = snapshot.results
+      ? snapshot.score
+      : snapshot.playerCount * 12;
+    hud.updateScore(derivedScore);
+    hud.updateTimer(snapshot.elapsedMs);
+    hud.updateDelta(snapshot.delta);
+    steeringValue.textContent = `${Math.round(snapshot.steering)}%`;
+
+    renderGateOptions(gateGrid, snapshot.gateOptions, {
+      onSelect: (gate) => game.chooseGate(gate.id),
+    });
+    renderSkirmishLog(skirmishLogEl, snapshot.skirmishLog);
+    renderReverseStatus(reverseStatusEl, snapshot.reverse);
+    renderResultsCard(resultsCardEl, snapshot.results, {
+      survivors: snapshot.playerCount,
+    });
+
+    pauseMenu.setMute(snapshot.isMuted);
+    pauseMenu.setLowMode(snapshot.vfxMode === 'low');
+    isPaused = snapshot.isPaused;
+
+    startButton.textContent =
+      snapshot.phase === 'idle' ? 'Start Run' : 'Restart Run';
+  }
+
+  game.on('update', handleUpdate);
+
+  function updateSteeringLabel() {
+    const value = Number.parseInt(steeringSlider.value, 10);
+    steeringValue.textContent = `${value}%`;
+  }
+
+  steeringSlider.addEventListener('input', (event) => {
+    const value = Number.parseInt(event.target.value, 10);
+    game.updateSteering(value);
+    updateSteeringLabel();
+  });
+
+  startButton.addEventListener('click', () => {
+    game.startRun({
+      seed: getSeedFromUrl(),
+      steering: Number.parseInt(steeringSlider.value, 10),
+    });
+  });
+
+  updateSteeringLabel();
+  handleUpdate(game.getSnapshot());
+
+  let lastTimestamp = null;
+  function tick(timestamp) {
+    if (lastTimestamp !== null && !isPaused) {
+      const delta = timestamp - lastTimestamp;
+      game.updateElapsed(delta);
+    }
+    lastTimestamp = timestamp;
+    window.requestAnimationFrame(tick);
+  }
+  window.requestAnimationFrame(tick);
+
+  return {
+    game,
+    hud,
+    performanceGuard,
+  };
+}
diff --git a/src/app.test.js b/src/app.test.js
new file mode 100644
index 0000000..8f07036
--- /dev/null
+++ b/src/app.test.js
@@ -0,0 +1,122 @@
+import { initApp } from './app.js';
+
+describe('app integration', () => {
+  let originalRaf;
+  let originalCancel;
+  let callbacks;
+
+  beforeEach(() => {
+    callbacks = [];
+    originalRaf = window.requestAnimationFrame;
+    originalCancel = window.cancelAnimationFrame;
+    window.requestAnimationFrame = (cb) => {
+      callbacks.push(cb);
+      return callbacks.length;
+    };
+    window.cancelAnimationFrame = jest.fn();
+
+    document.body.innerHTML = `
+      <div class="app" id="app">
+        <header class="hud">
+          <div class="hud__score"><span class="hud__score-value">0</span></div>
+          <div data-testid="hud-delta" class="hud__delta"></div>
+          <div class="hud__timer"><span class="hud__timer-value">0</span></div>
+          <button data-testid="pause-button" type="button">Pause</button>
+        </header>
+        <section>
+          <div data-testid="gate-grid"></div>
+          <div data-testid="skirmish-log"></div>
+          <div data-testid="reverse-status"><span class="reverse-status__value"></span></div>
+          <article data-testid="results-card">
+            <div data-testid="results-stars"></div>
+            <p data-testid="results-summary"></p>
+          </article>
+        </section>
+        <section>
+          <span data-testid="steering-value">50%</span>
+          <input data-testid="steering-slider" type="range" min="0" max="100" value="50" />
+        </section>
+      </div>
+      <button data-testid="start-button">Start Run</button>
+      <div data-testid="pause-overlay">
+        <button data-testid="resume-button">Resume</button>
+        <button data-testid="restart-button">Restart</button>
+        <label><input data-testid="mute-toggle" type="checkbox" /></label>
+        <label><input data-testid="low-mode-toggle" type="checkbox" /></label>
+      </div>
+    `;
+  });
+
+  afterEach(() => {
+    window.requestAnimationFrame = originalRaf;
+    window.cancelAnimationFrame = originalCancel;
+  });
+
+  test('wires primary game loop interactions', () => {
+    // why this test matters: verifies DOM wiring for the forward/skirmish/reverse loop at a high level.
+    const { game, performanceGuard } = initApp();
+    const startButton = document.querySelector('[data-testid="start-button"]');
+    const gateGrid = document.querySelector('[data-testid="gate-grid"]');
+    const pauseOverlay = document.querySelector(
+      '[data-testid="pause-overlay"]'
+    );
+    const pauseButton = document.querySelector('[data-testid="pause-button"]');
+    const resumeButton = document.querySelector(
+      '[data-testid="resume-button"]'
+    );
+    const slider = document.querySelector('[data-testid="steering-slider"]');
+    const muteToggle = document.querySelector('[data-testid="mute-toggle"]');
+    const lowModeToggle = document.querySelector(
+      '[data-testid="low-mode-toggle"]'
+    );
+    const appRoot = document.getElementById('app');
+
+    expect(startButton.textContent).toBe('Start Run');
+    slider.value = '70';
+    slider.dispatchEvent(new Event('input'));
+    startButton.click();
+
+    expect(gateGrid.querySelectorAll('button').length).toBe(4);
+    for (let stage = 0; stage < 3; stage += 1) {
+      const button = gateGrid.querySelector('button');
+      button.click();
+    }
+
+    const resultsCard = document.querySelector('[data-testid="results-card"]');
+    expect(resultsCard.classList.contains('is-visible')).toBe(true);
+    expect(game.getSnapshot().phase).toBe('complete');
+
+    muteToggle.checked = true;
+    muteToggle.dispatchEvent(new Event('change'));
+    expect(game.getSnapshot().isMuted).toBe(true);
+
+    lowModeToggle.checked = true;
+    lowModeToggle.dispatchEvent(new Event('change'));
+    expect(appRoot.classList.contains('degraded')).toBe(true);
+    expect(performanceGuard.isDegraded()).toBe(true);
+
+    lowModeToggle.checked = false;
+    lowModeToggle.dispatchEvent(new Event('change'));
+    expect(appRoot.classList.contains('degraded')).toBe(false);
+
+    pauseButton.click();
+    expect(pauseOverlay.classList.contains('is-visible')).toBe(true);
+    const restartButton = document.querySelector(
+      '[data-testid="restart-button"]'
+    );
+    restartButton.click();
+    expect(game.getSnapshot().phase).toBe('forward');
+    pauseButton.click();
+    resumeButton.click();
+    expect(pauseOverlay.classList.contains('is-visible')).toBe(false);
+    resumeButton.click();
+
+    const updateElapsedSpy = jest.spyOn(game, 'updateElapsed');
+    expect(callbacks.length).toBeGreaterThan(1);
+    const tickCallback = callbacks[1];
+    tickCallback(1000);
+    const nextTick = callbacks.at(-1);
+    nextTick(1100);
+    expect(updateElapsedSpy).toHaveBeenCalled();
+  });
+});
diff --git a/src/assets/defaultData.json b/src/assets/defaultData.json
index 4a35737..c05b939 100644
--- a/src/assets/defaultData.json
+++ b/src/assets/defaultData.json
@@ -1,8 +1,8 @@
 {
-    "someData": [
-        {
-            "id": "123",
-            "title": "Abc",            
-        }
-    ]
-}
\ No newline at end of file
+  "someData": [
+    {
+      "id": "123",
+      "title": "Abc"
+    }
+  ]
+}
diff --git a/src/index.js b/src/index.js
index ac0ebea..495d5d5 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1 +1,9 @@
-console.log("Hello from index.js!");
+import { initApp } from './app.js';
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => {
+    initApp();
+  });
+} else {
+  initApp();
+}
diff --git a/src/index.test.js b/src/index.test.js
index e27abde..ffa711f 100644
--- a/src/index.test.js
+++ b/src/index.test.js
@@ -1,12 +1,41 @@
-// This is a placeholder test file for index.js.
-// Since index.js currently only has a console.log,
-// a meaningful test isn't really possible without
-// more complex setup (e.g., mocking console.log or
-// integrating with an HTML environment if it manipulates the DOM).
-
-describe('Index', () => {
-  test('placeholder test', () => {
-    // Replace with actual tests once index.js has testable logic
-    expect(true).toBe(true);
+import { jest } from '@jest/globals';
+
+jest.mock('./app.js', () => ({
+  initApp: jest.fn(),
+}));
+
+const { initApp } = require('./app.js');
+
+function setReadyState(state) {
+  Object.defineProperty(document, 'readyState', {
+    configurable: true,
+    value: state,
+  });
+}
+
+describe('index bootstrapping', () => {
+  afterEach(() => {
+    initApp.mockClear();
+    setReadyState('complete');
+  });
+
+  test('initialises immediately when DOM is already ready', async () => {
+    // why this test matters: ensures eager boots do not wait for events unnecessarily.
+    setReadyState('interactive');
+    await jest.isolateModulesAsync(async () => {
+      await import('./index.js');
+    });
+    expect(initApp).toHaveBeenCalledTimes(1);
+  });
+
+  test('waits for DOMContentLoaded when still loading', async () => {
+    // why this test matters: prevents init from running before the HUD exists.
+    setReadyState('loading');
+    await jest.isolateModulesAsync(async () => {
+      await import('./index.js');
+    });
+    expect(initApp).not.toHaveBeenCalled();
+    document.dispatchEvent(new Event('DOMContentLoaded'));
+    expect(initApp).toHaveBeenCalledTimes(1);
   });
 });
diff --git a/src/logic/combat.js b/src/logic/combat.js
new file mode 100644
index 0000000..1f69820
--- /dev/null
+++ b/src/logic/combat.js
@@ -0,0 +1,116 @@
+function clamp01(value) {
+  return Math.min(1, Math.max(0, value));
+}
+
+export function simulateSkirmish({
+  players,
+  enemyPower,
+  aggression,
+  gateQuality = 0,
+}) {
+  const normalizedAggression = clamp01(aggression);
+  let playerCount = Math.max(0, Math.round(players));
+  let enemyCount = Math.max(0, Math.round(enemyPower));
+  const volleyCount = Math.max(2, Math.round(3 + gateQuality / 25));
+  const volleyLog = [];
+
+  for (let volley = 1; volley <= volleyCount; volley += 1) {
+    const defensiveMitigation = 0.18 + (1 - normalizedAggression) * 0.22;
+    const incoming = Math.round(
+      enemyCount * defensiveMitigation * (1 / volleyCount + 0.2)
+    );
+    const playerLoss = Math.min(playerCount, Math.max(0, incoming));
+    playerCount -= playerLoss;
+
+    const retaliationBase = 0.24 + normalizedAggression * 0.38;
+    const retaliation = Math.round(
+      (playerCount + playerLoss * 0.4) * retaliationBase
+    );
+    const enemyLoss = Math.min(enemyCount, Math.max(0, retaliation));
+    enemyCount -= enemyLoss;
+
+    volleyLog.push({
+      volley,
+      playerLoss,
+      enemyLoss,
+      remainingPlayers: playerCount,
+      remainingEnemies: enemyCount,
+    });
+
+    if (playerCount === 0 || enemyCount === 0) {
+      break;
+    }
+  }
+
+  return {
+    volleyLog,
+    remainingPlayers: playerCount,
+    remainingEnemies: enemyCount,
+    volleyCount: volleyLog.length,
+  };
+}
+
+export function simulateReverseChase({ players, chasePressure, aggression }) {
+  const normalizedAggression = clamp01(aggression);
+  let playerCount = Math.max(0, Math.round(players));
+  const baseDuration =
+    26 - normalizedAggression * 6 + (chasePressure > playerCount ? 4 : 0);
+  const ticks = Math.max(4, Math.round(baseDuration / 2));
+  const pressure = Math.max(0, chasePressure);
+  const tickLosses = [];
+
+  for (let tick = 1; tick <= ticks; tick += 1) {
+    const tickIntensity = pressure * (0.16 + (1 - normalizedAggression) * 0.28);
+    const tickLoss = Math.min(
+      playerCount,
+      Math.round((tickIntensity / ticks) * (1 + tick / (ticks * 2)))
+    );
+    playerCount -= tickLoss;
+    tickLosses.push(tickLoss);
+    if (playerCount === 0) {
+      break;
+    }
+  }
+
+  const success = playerCount > Math.max(3, pressure * 0.08);
+  return {
+    ticks: tickLosses.length,
+    remainingPlayers: playerCount,
+    success,
+    timeSeconds: Number(baseDuration.toFixed(1)),
+    tickLosses,
+  };
+}
+
+export function scoreRun({
+  initialPlayers,
+  playersSurvived,
+  timeSeconds,
+  gateQuality,
+  success,
+}) {
+  const survivalRatio =
+    initialPlayers === 0 ? 0 : playersSurvived / initialPlayers;
+  const survivalScore = playersSurvived * (success ? 18 : 12);
+  const timeScore = Math.max(0, 180 - timeSeconds) * 6;
+  const qualityBonus = Math.max(0, gateQuality) * 4;
+  const score = Math.round(survivalScore + timeScore + qualityBonus);
+
+  let stars = 1;
+  if (success && survivalRatio >= 0.75) {
+    stars = 3;
+  } else if (survivalRatio >= 0.45) {
+    stars = 2;
+  }
+
+  const summary = success
+    ? `Escaped with ${playersSurvived} marauders in ${timeSeconds.toFixed(1)}s.`
+    : `Overrun after ${timeSeconds.toFixed(1)}s.`;
+
+  return {
+    score,
+    stars,
+    survivalRatio: Number(survivalRatio.toFixed(2)),
+    summary,
+  };
+}
diff --git a/src/logic/combat.test.js b/src/logic/combat.test.js
new file mode 100644
index 0000000..be1faa3
--- /dev/null
+++ b/src/logic/combat.test.js
@@ -0,0 +1,92 @@
+import fc from 'fast-check';
+import { scoreRun, simulateReverseChase, simulateSkirmish } from './combat.js';
+
+describe('combat simulations', () => {
+  test('simulateSkirmish produces deterministic losses', () => {
+    // why this test matters: rendering volley summaries must match logic outputs exactly.
+    const resultA = simulateSkirmish({
+      players: 48,
+      enemyPower: 32,
+      aggression: 0.6,
+      gateQuality: 18,
+    });
+    const resultB = simulateSkirmish({
+      players: 48,
+      enemyPower: 32,
+      aggression: 0.6,
+      gateQuality: 18,
+    });
+    expect(resultA).toEqual(resultB);
+    expect(resultA.remainingPlayers).toBeLessThanOrEqual(48);
+    expect(resultA.remainingEnemies).toBeGreaterThanOrEqual(0);
+    expect(resultA.volleyLog.length).toBeGreaterThan(0);
+  });
+
+  test('simulateReverseChase accounts for aggression and pressure', () => {
+    // why this test matters: restart pacing depends on consistent chase outcomes.
+    const calm = simulateReverseChase({
+      players: 30,
+      chasePressure: 5,
+      aggression: 0.8,
+    });
+    const panic = simulateReverseChase({
+      players: 30,
+      chasePressure: 80,
+      aggression: 0.2,
+    });
+    expect(calm.success).toBe(true);
+    expect(panic.success).toBe(false);
+    expect(calm.remainingPlayers).toBeGreaterThan(panic.remainingPlayers);
+  });
+
+  test('scoreRun awards stars based on survival ratio', () => {
+    // why this test matters: end card feedback sets the replay motivation loop.
+    const high = scoreRun({
+      initialPlayers: 40,
+      playersSurvived: 34,
+      timeSeconds: 32,
+      gateQuality: 18,
+      success: true,
+    });
+    const mid = scoreRun({
+      initialPlayers: 40,
+      playersSurvived: 20,
+      timeSeconds: 45,
+      gateQuality: 12,
+      success: true,
+    });
+    const low = scoreRun({
+      initialPlayers: 40,
+      playersSurvived: 8,
+      timeSeconds: 50,
+      gateQuality: 5,
+      success: false,
+    });
+    expect(high.stars).toBe(3);
+    expect(mid.stars).toBe(2);
+    expect(low.stars).toBe(1);
+  });
+
+  test('property: skirmish never yields negative squads or enemies', () => {
+    // why this test matters: protects against subtle math regressions during tuning changes.
+    fc.assert(
+      fc.property(
+        fc.integer({ min: 10, max: 80 }),
+        fc.integer({ min: 5, max: 90 }),
+        fc.float({ min: 0, max: 1, noNaN: true }),
+        fc.float({ min: 0, max: 30, noNaN: true }),
+        (players, enemies, aggression, quality) => {
+          const result = simulateSkirmish({
+            players,
+            enemyPower: enemies,
+            aggression,
+            gateQuality: quality,
+          });
+          expect(result.remainingPlayers).toBeGreaterThanOrEqual(0);
+          expect(result.remainingEnemies).toBeGreaterThanOrEqual(0);
+          expect(result.remainingPlayers).toBeLessThanOrEqual(players);
+        }
+      )
+    );
+  });
+});
diff --git a/src/logic/gates.js b/src/logic/gates.js
new file mode 100644
index 0000000..538e231
--- /dev/null
+++ b/src/logic/gates.js
@@ -0,0 +1,153 @@
+import { createSeededRng } from '../utils/random.js';
+
+const OPERATION_CONFIG = {
+  add: {
+    symbol: '+',
+    color: '#33d6a6',
+    describe: (value) => `Recruit ${value} runners`,
+  },
+  sub: {
+    symbol: '−',
+    color: '#ff5fa2',
+    describe: (value) => `Patch up casualties (−${value})`,
+  },
+  mul: {
+    symbol: '×',
+    color: '#ffd166',
+    describe: (value) => `Drill squads ×${value.toFixed(2)}`,
+  },
+  div: {
+    symbol: '÷',
+    color: '#00d1ff',
+    describe: (value) => `Split squads ÷${value.toFixed(2)}`,
+  },
+};
+
+const VALUE_RANGES = {
+  add: [6, 14],
+  sub: [4, 11],
+  mul: [1.25, 1.6],
+  div: [1.5, 2.3],
+};
+
+function computeValue(op, stage, rng) {
+  const [min, max] = VALUE_RANGES[op];
+  const stageBias = 0.3 + stage * 0.18;
+  const mix = Math.min(1, Math.max(0, stageBias + rng() * 0.7));
+  const raw = min + (max - min) * mix;
+  if (op === 'add' || op === 'sub') {
+    return Math.round(raw);
+  }
+
+  return Number(raw.toFixed(2));
+}
+
+function computeRisk(op, stage) {
+  const base = {
+    add: 0.12,
+    sub: 0.24,
+    mul: 0.32,
+    div: 0.38,
+  }[op];
+
+  return Number((base + stage * 0.07).toFixed(2));
+}
+
+function computeReward(op, value) {
+  switch (op) {
+    case 'add':
+      return value * 1.4;
+    case 'sub':
+      return -value * 1.1;
+    case 'mul':
+      return (value - 1) * 42;
+    case 'div':
+      return -(1 - 1 / value) * 36;
+    default:
+      return 0;
+  }
+}
+
+export function createGateOption(op, stage, rng = Math.random) {
+  const config = OPERATION_CONFIG[op];
+  if (!config) {
+    throw new Error(`Unknown gate op: ${op}`);
+  }
+
+  const value = computeValue(op, stage, rng);
+  const risk = computeRisk(op, stage);
+  const reward = Number(computeReward(op, value).toFixed(2));
+  const quality = Number((reward - risk * 18).toFixed(2));
+
+  return {
+    id: `${stage}-${op}`,
+    stage,
+    op,
+    value,
+    color: config.color,
+    symbol: config.symbol,
+    description: config.describe(value),
+    risk,
+    reward,
+    quality,
+  };
+}
+
+export function generateGateDeck({ stages = 3, seed } = {}) {
+  const rng = createSeededRng(seed ?? Date.now().toString());
+  const deck = [];
+  for (let stage = 0; stage < stages; stage += 1) {
+    const stageOptions = ['add', 'sub', 'mul', 'div'].map((op) =>
+      createGateOption(op, stage, rng)
+    );
+    deck.push({ stage, options: stageOptions });
+  }
+
+  return deck;
+}
+
+export function applyGate(count, gate) {
+  if (!gate || typeof gate.op !== 'string') {
+    throw new Error('Gate is required');
+  }
+
+  switch (gate.op) {
+    case 'add':
+      return Math.max(0, count + gate.value);
+    case 'sub':
+      return Math.max(0, count - gate.value);
+    case 'mul':
+      return Math.round(count * gate.value);
+    case 'div': {
+      const divided = count / gate.value;
+      return Math.max(1, Math.round(divided));
+    }
+    default:
+      throw new Error(`Unsupported op: ${gate.op}`);
+  }
+}
+
+export function describeGate(gate) {
+  if (!gate) {
+    return '';
+  }
+
+  const config = OPERATION_CONFIG[gate.op];
+  if (!config) {
+    return '';
+  }
+
+  return `${config.symbol}${gate.value}`;
+}
+
+export function evaluateGateQuality(selectedGates) {
+  if (!selectedGates || selectedGates.length === 0) {
+    return 0;
+  }
+
+  const totalQuality = selectedGates.reduce(
+    (sum, gate) => sum + gate.quality,
+    0
+  );
+  return Number((totalQuality / selectedGates.length).toFixed(2));
+}
diff --git a/src/logic/gates.test.js b/src/logic/gates.test.js
new file mode 100644
index 0000000..dc4b067
--- /dev/null
+++ b/src/logic/gates.test.js
@@ -0,0 +1,69 @@
+import {
+  applyGate,
+  createGateOption,
+  describeGate,
+  evaluateGateQuality,
+  generateGateDeck,
+} from './gates.js';
+
+const stubRng = () => 0.5;
+
+describe('gates', () => {
+  test('applyGate handles each operator with rounding and clamps', () => {
+    // why this test matters: deterministic gate math underpins balance and tests downstream systems.
+    const addGate = { op: 'add', value: 5 };
+    const subGate = { op: 'sub', value: 40 };
+    const mulGate = { op: 'mul', value: 1.3 };
+    const divGate = { op: 'div', value: 3.2 };
+
+    expect(applyGate(20, addGate)).toBe(25);
+    expect(applyGate(20, subGate)).toBe(0);
+    expect(applyGate(10, mulGate)).toBe(13);
+    expect(applyGate(10, divGate)).toBe(3);
+  });
+
+  test('createGateOption encodes stage based risk/reward', () => {
+    // why this test matters: UI needs consistent telemetry for progressive difficulty cues.
+    const gate = createGateOption('mul', 2, stubRng);
+    expect(gate.id).toBe('2-mul');
+    expect(gate.symbol).toBe('×');
+    expect(gate.description).toContain('×');
+    expect(gate.risk).toBeGreaterThan(0.3);
+    expect(gate.reward).toBeGreaterThan(0);
+  });
+
+  test('generateGateDeck is deterministic for a given seed', () => {
+    // why this test matters: sharing seeds between players must produce identical gate layouts.
+    const a = generateGateDeck({ stages: 2, seed: 'sync-seed' });
+    const b = generateGateDeck({ stages: 2, seed: 'sync-seed' });
+    expect(a).toEqual(b);
+  });
+
+  test('evaluateGateQuality averages qualities for HUD feedback', () => {
+    // why this test matters: score screen references quality for player coaching cues.
+    const quality = evaluateGateQuality([
+      createGateOption('add', 0, stubRng),
+      createGateOption('mul', 1, stubRng),
+    ]);
+    expect(quality).toBeGreaterThan(0);
+    expect(evaluateGateQuality([])).toBe(0);
+  });
+
+  test('guards against invalid gates', () => {
+    // why this test matters: protects against bad data in procedural generation.
+    expect(() => applyGate(10, null)).toThrow('Gate is required');
+    expect(() => createGateOption('pow', 0, stubRng)).toThrow(
+      'Unknown gate op'
+    );
+    expect(describeGate(null)).toBe('');
+    expect(describeGate({ op: 'pow', value: 2 })).toBe('');
+  });
+
+  test('clamps stage bias extremes', () => {
+    // why this test matters: keeps generator stable for authored stage counts.
+    const highClamp = createGateOption('mul', 8, () => 1);
+    const lowClamp = createGateOption('sub', -5, () => 0);
+    expect(highClamp.value).toBeGreaterThan(0);
+    expect(lowClamp.value).toBeGreaterThanOrEqual(4);
+  });
+});
diff --git a/src/logic/performance.js b/src/logic/performance.js
new file mode 100644
index 0000000..4d464ec
--- /dev/null
+++ b/src/logic/performance.js
@@ -0,0 +1,69 @@
+export function createPerformanceGuard({ onDegrade, onRecover }) {
+  let lastTimestamp = null;
+  let frameTimes = [];
+  let rafId = null;
+  let isDegraded = false;
+  let forcedLow = false;
+
+  function evaluate() {
+    if (frameTimes.length < 20) {
+      return;
+    }
+
+    const sum = frameTimes.reduce((total, frame) => total + frame, 0);
+    const avg = sum / frameTimes.length;
+    const fps = 1000 / avg;
+
+    if (!forcedLow && !isDegraded && fps < 50) {
+      isDegraded = true;
+      onDegrade?.({ fps });
+    } else if (!forcedLow && isDegraded && fps >= 58) {
+      isDegraded = false;
+      onRecover?.({ fps });
+    }
+  }
+
+  function loop(timestamp) {
+    if (lastTimestamp !== null) {
+      frameTimes.push(timestamp - lastTimestamp);
+      if (frameTimes.length > 120) {
+        frameTimes = frameTimes.slice(-120);
+      }
+      evaluate();
+    }
+    lastTimestamp = timestamp;
+    rafId = window.requestAnimationFrame(loop);
+  }
+
+  return {
+    start() {
+      if (rafId !== null) {
+        return;
+      }
+      rafId = window.requestAnimationFrame(loop);
+    },
+    stop() {
+      if (rafId !== null) {
+        window.cancelAnimationFrame(rafId);
+        rafId = null;
+      }
+      lastTimestamp = null;
+      frameTimes = [];
+    },
+    forceLowMode(enabled) {
+      forcedLow = Boolean(enabled);
+      if (forcedLow) {
+        if (!isDegraded) {
+          isDegraded = true;
+          onDegrade?.({ fps: 0, forced: true });
+        }
+      } else {
+        isDegraded = false;
+        onRecover?.({ fps: 60, forced: false });
+      }
+    },
+    isDegraded() {
+      return isDegraded;
+    },
+  };
+}
diff --git a/src/logic/performance.test.js b/src/logic/performance.test.js
new file mode 100644
index 0000000..9584351
--- /dev/null
+++ b/src/logic/performance.test.js
@@ -0,0 +1,65 @@
+import { createPerformanceGuard } from './performance.js';
+
+describe('performance guard', () => {
+  let originalRaf;
+  let originalCancel;
+  let callbacks;
+
+  beforeEach(() => {
+    callbacks = [];
+    originalRaf = window.requestAnimationFrame;
+    originalCancel = window.cancelAnimationFrame;
+    window.requestAnimationFrame = (cb) => {
+      callbacks.push(cb);
+      return callbacks.length;
+    };
+    window.cancelAnimationFrame = jest.fn();
+  });
+
+  afterEach(() => {
+    window.requestAnimationFrame = originalRaf;
+    window.cancelAnimationFrame = originalCancel;
+  });
+
+  test('detects degrade and recovery based on frame pacing', () => {
+    // why this test matters: automatic VFX downgrades keep the experience responsive on low-end devices.
+    const onDegrade = jest.fn();
+    const onRecover = jest.fn();
+    const guard = createPerformanceGuard({ onDegrade, onRecover });
+    guard.start();
+
+    let index = 0;
+    let timestamp = 0;
+    const step = (delta) => {
+      const cb = callbacks[index];
+      expect(cb).toBeDefined();
+      timestamp += delta;
+      cb(timestamp);
+      index += 1;
+    };
+
+    step(16);
+    for (let i = 0; i < 25; i += 1) {
+      step(42);
+    }
+    expect(onDegrade).toHaveBeenCalled();
+
+    for (let i = 0; i < 140; i += 1) {
+      step(16);
+    }
+    expect(onRecover).toHaveBeenCalled();
+
+    guard.forceLowMode(true);
+    expect(onDegrade).toHaveBeenCalledWith(
+      expect.objectContaining({ forced: true })
+    );
+
+    guard.forceLowMode(false);
+    expect(onRecover).toHaveBeenLastCalledWith(
+      expect.objectContaining({ forced: false })
+    );
+
+    guard.stop();
+    expect(window.cancelAnimationFrame).toHaveBeenCalled();
+  });
+});
diff --git a/src/state/gameState.js b/src/state/gameState.js
new file mode 100644
index 0000000..d09e9b7
--- /dev/null
+++ b/src/state/gameState.js
@@ -0,0 +1,207 @@
+import {
+  applyGate,
+  evaluateGateQuality,
+  generateGateDeck,
+} from '../logic/gates.js';
+import {
+  scoreRun,
+  simulateReverseChase,
+  simulateSkirmish,
+} from '../logic/combat.js';
+import { normalizeSeed } from '../utils/random.js';
+
+const INITIAL_PLAYERS = 36;
+
+function createEmitter() {
+  const listeners = new Map();
+  return {
+    on(event, callback) {
+      if (!listeners.has(event)) {
+        listeners.set(event, new Set());
+      }
+      listeners.get(event).add(callback);
+      return () => listeners.get(event)?.delete(callback);
+    },
+    emit(event, payload) {
+      if (!listeners.has(event)) {
+        return;
+      }
+      for (const callback of listeners.get(event)) {
+        callback(payload);
+      }
+    },
+    clear() {
+      listeners.clear();
+    },
+  };
+}
+
+function createSnapshot(state) {
+  return {
+    phase: state.phase,
+    stageIndex: state.stageIndex,
+    gateOptions: state.gateDeck[state.stageIndex]?.options ?? [],
+    chosenGates: state.chosenGates.slice(),
+    playerCount: state.playerCount,
+    delta: state.delta,
+    score: state.score,
+    elapsedMs: state.elapsedMs,
+    skirmishLog: state.skirmishLog.slice(),
+    reverse: state.reverse ? { ...state.reverse } : null,
+    results: state.results ? { ...state.results } : null,
+    steering: state.steering,
+    isPaused: state.isPaused,
+    isMuted: state.isMuted,
+    vfxMode: state.vfxMode,
+    seed: state.seed,
+  };
+}
+
+export function createGameState({ stageCount = 3 } = {}) {
+  const emitter = createEmitter();
+  const state = {
+    phase: 'idle',
+    stageIndex: 0,
+    gateDeck: [],
+    chosenGates: [],
+    playerCount: INITIAL_PLAYERS,
+    delta: 0,
+    score: 0,
+    elapsedMs: 0,
+    skirmishLog: [],
+    reverse: null,
+    results: null,
+    steering: 50,
+    isPaused: false,
+    isMuted: false,
+    vfxMode: 'ultra',
+    seed: null,
+  };
+
+  function emitUpdate() {
+    emitter.emit('update', createSnapshot(state));
+  }
+
+  function resetRun(seedInput) {
+    state.stageIndex = 0;
+    state.gateDeck = generateGateDeck({ stages: stageCount, seed: seedInput });
+    state.chosenGates = [];
+    state.playerCount = INITIAL_PLAYERS;
+    state.delta = 0;
+    state.score = 0;
+    state.elapsedMs = 0;
+    state.skirmishLog = [];
+    state.reverse = null;
+    state.results = null;
+  }
+
+  return {
+    on: emitter.on,
+    getSnapshot() {
+      return createSnapshot(state);
+    },
+    startRun({ seed, steering } = {}) {
+      state.seed = normalizeSeed(seed ?? Date.now().toString());
+      resetRun(state.seed);
+      if (typeof steering === 'number') {
+        state.steering = Math.min(100, Math.max(0, steering));
+      }
+      state.phase = 'forward';
+      state.isPaused = false;
+      emitUpdate();
+    },
+    chooseGate(gateId) {
+      if (state.phase !== 'forward') {
+        return;
+      }
+      const stage = state.gateDeck[state.stageIndex];
+      if (!stage) {
+        return;
+      }
+
+      const gate = stage.options.find((option) => option.id === gateId);
+      if (!gate) {
+        return;
+      }
+
+      const previousCount = state.playerCount;
+      state.playerCount = applyGate(state.playerCount, gate);
+      const postGateCount = state.playerCount;
+      state.delta = state.playerCount - previousCount;
+      state.chosenGates.push(gate);
+
+      if (state.stageIndex < stageCount - 1) {
+        state.stageIndex += 1;
+        emitUpdate();
+        return;
+      }
+
+      const aggression = state.steering / 100;
+      state.phase = 'skirmish';
+      const gateQuality = evaluateGateQuality(state.chosenGates);
+      const skirmish = simulateSkirmish({
+        players: state.playerCount,
+        enemyPower: INITIAL_PLAYERS * 0.75,
+        aggression,
+        gateQuality,
+      });
+      state.playerCount = skirmish.remainingPlayers;
+      state.delta = state.playerCount - postGateCount;
+      state.skirmishLog = skirmish.volleyLog;
+      emitUpdate();
+
+      state.phase = 'reverse';
+      const reverse = simulateReverseChase({
+        players: state.playerCount,
+        chasePressure: skirmish.remainingEnemies,
+        aggression,
+      });
+      state.playerCount = reverse.remainingPlayers;
+      state.delta = 0;
+      state.reverse = reverse;
+      emitUpdate();
+
+      state.phase = 'complete';
+      const results = scoreRun({
+        initialPlayers: INITIAL_PLAYERS,
+        playersSurvived: state.playerCount,
+        timeSeconds: reverse.timeSeconds,
+        gateQuality,
+        success: reverse.success,
+      });
+      state.score = results.score;
+      state.results = results;
+      emitUpdate();
+    },
+    updateElapsed(deltaMs) {
+      if (state.phase === 'idle' || state.isPaused) {
+        return;
+      }
+      state.elapsedMs = Math.min(180000, state.elapsedMs + deltaMs);
+      emitUpdate();
+    },
+    updateSteering(value) {
+      state.steering = Math.min(100, Math.max(0, value));
+      emitUpdate();
+    },
+    togglePause() {
+      state.isPaused = !state.isPaused;
+      emitter.emit('pause', state.isPaused);
+      emitUpdate();
+    },
+    setMuted(muted) {
+      state.isMuted = Boolean(muted);
+      emitUpdate();
+    },
+    setVfxMode(mode) {
+      state.vfxMode = mode;
+      emitUpdate();
+    },
+    reset() {
+      resetRun(state.seed ?? Date.now().toString());
+      state.phase = 'forward';
+      state.isPaused = false;
+      emitUpdate();
+    },
+  };
+}
diff --git a/src/state/gameState.test.js b/src/state/gameState.test.js
new file mode 100644
index 0000000..9edef89
--- /dev/null
+++ b/src/state/gameState.test.js
@@ -0,0 +1,68 @@
+import { createGameState } from './gameState.js';
+
+describe('game state', () => {
+  test('startRun seeds deck and exposes gate options', () => {
+    // why this test matters: without predictable seeding the run loop would desync across clients.
+    const game = createGameState({ stageCount: 2 });
+    game.startRun({ seed: 'alpha', steering: 45 });
+    const snapshot = game.getSnapshot();
+    expect(snapshot.phase).toBe('forward');
+    expect(snapshot.gateOptions).toHaveLength(4);
+    expect(snapshot.steering).toBe(45);
+
+    game.updateSteering(70);
+    expect(game.getSnapshot().steering).toBe(70);
+    game.togglePause();
+    expect(game.getSnapshot().isPaused).toBe(true);
+    game.togglePause();
+    expect(game.getSnapshot().isPaused).toBe(false);
+
+    game.setMuted(true);
+    expect(game.getSnapshot().isMuted).toBe(true);
+    game.setVfxMode('low');
+    expect(game.getSnapshot().vfxMode).toBe('low');
+  });
+
+  test('run completion produces results summary', () => {
+    // why this test matters: ensures the full forward → skirmish → reverse → end card loop is wired.
+    const game = createGameState({ stageCount: 3 });
+    game.startRun({ seed: 'omega', steering: 60 });
+
+    for (let stage = 0; stage < 3; stage += 1) {
+      const snapshot = game.getSnapshot();
+      const gate = snapshot.gateOptions[0];
+      game.chooseGate(gate.id);
+    }
+
+    const complete = game.getSnapshot();
+    expect(complete.phase).toBe('complete');
+    expect(complete.results).not.toBeNull();
+    expect(complete.results.summary).toContain('s');
+
+    game.updateElapsed(1600);
+    expect(game.getSnapshot().elapsedMs).toBeGreaterThan(0);
+
+    game.reset();
+    const resetSnapshot = game.getSnapshot();
+    expect(resetSnapshot.phase).toBe('forward');
+    expect(resetSnapshot.gateOptions).toHaveLength(4);
+  });
+
+  test('ignores invalid gate selections safely', () => {
+    // why this test matters: protects against UI double clicks or stale gate IDs.
+    const game = createGameState({ stageCount: 1 });
+    game.updateElapsed(200);
+    expect(game.getSnapshot().elapsedMs).toBe(0);
+    expect(() => game.chooseGate('0-add')).not.toThrow();
+    game.startRun({ seed: 'beta', steering: 55 });
+    const snapshotBefore = game.getSnapshot();
+    game.togglePause();
+    const pausedElapsed = game.getSnapshot().elapsedMs;
+    game.updateElapsed(400);
+    expect(game.getSnapshot().elapsedMs).toBe(pausedElapsed);
+    game.togglePause();
+    game.chooseGate('invalid-id');
+    const snapshotAfter = game.getSnapshot();
+    expect(snapshotAfter.stageIndex).toBe(snapshotBefore.stageIndex);
+  });
+});
diff --git a/src/ui/gatePanel.js b/src/ui/gatePanel.js
new file mode 100644
index 0000000..dc3c242
--- /dev/null
+++ b/src/ui/gatePanel.js
@@ -0,0 +1,52 @@
+import { describeGate } from '../logic/gates.js';
+import { formatNumber } from '../utils/format.js';
+
+function renderGateButton(gate, onSelect) {
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = 'gate-card';
+  button.style.setProperty('border-color', `${gate.color}55`);
+  button.style.setProperty('box-shadow', `0 12px 24px ${gate.color}22`);
+
+  const symbol = document.createElement('div');
+  symbol.className = 'gate-card__symbol';
+  symbol.textContent = describeGate(gate);
+  symbol.style.color = gate.color;
+
+  const description = document.createElement('p');
+  description.className = 'gate-card__description';
+  description.textContent = gate.description;
+
+  const telemetry = document.createElement('p');
+  telemetry.className = 'gate-card__description';
+  telemetry.innerHTML = `Risk <strong>${(gate.risk * 100).toFixed(0)}%</strong> · Yield <strong>${formatNumber(
+    gate.reward
+  )}</strong>`;
+
+  button.append(symbol, description, telemetry);
+  button.addEventListener('click', () => onSelect(gate));
+  button.addEventListener('keyup', (event) => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      onSelect(gate);
+    }
+  });
+
+  return button;
+}
+
+export function renderGateOptions(container, gates, { onSelect }) {
+  container.innerHTML = '';
+
+  if (!gates || gates.length === 0) {
+    const emptyState = document.createElement('p');
+    emptyState.textContent = 'All gates cleared. Skirmish ready.';
+    container.appendChild(emptyState);
+    return;
+  }
+
+  gates.forEach((gate) => {
+    container.appendChild(
+      renderGateButton(gate, (selected) => onSelect?.(selected))
+    );
+  });
+}
diff --git a/src/ui/gatePanel.test.js b/src/ui/gatePanel.test.js
new file mode 100644
index 0000000..2676956
--- /dev/null
+++ b/src/ui/gatePanel.test.js
@@ -0,0 +1,37 @@
+import { renderGateOptions } from './gatePanel.js';
+
+describe('gate panel', () => {
+  test('renders gate options and fires select callback', () => {
+    // why this test matters: forward choices drive the entire math loop.
+    const container = document.createElement('div');
+    const gate = {
+      id: '0-add',
+      stage: 0,
+      op: 'add',
+      value: 6,
+      color: '#33d6a6',
+      symbol: '+',
+      description: 'Recruit 6 runners',
+      risk: 0.1,
+      reward: 12,
+    };
+    const handler = jest.fn();
+
+    renderGateOptions(container, [gate], { onSelect: handler });
+    const button = container.querySelector('button');
+    expect(button).not.toBeNull();
+    button.click();
+    button.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter' }));
+    button.dispatchEvent(new KeyboardEvent('keyup', { key: ' ' }));
+
+    expect(handler).toHaveBeenCalledTimes(3);
+    expect(handler).toHaveBeenCalledWith(gate);
+  });
+
+  test('renders empty state when no gates remain', () => {
+    // why this test matters: communicates phase transitions without silent failures.
+    const container = document.createElement('div');
+    renderGateOptions(container, [], { onSelect: jest.fn() });
+    expect(container.textContent).toContain('All gates cleared');
+  });
+});
diff --git a/src/ui/hud.js b/src/ui/hud.js
new file mode 100644
index 0000000..af5be53
--- /dev/null
+++ b/src/ui/hud.js
@@ -0,0 +1,47 @@
+import { formatDelta, formatNumber, toSeconds } from '../utils/format.js';
+
+export function createHud({ scoreValueEl, timerValueEl, deltaEl }) {
+  let deltaTimer = null;
+
+  function clearDelta() {
+    if (deltaTimer) {
+      window.clearTimeout(deltaTimer);
+      deltaTimer = null;
+    }
+    deltaEl.textContent = '';
+    deltaEl.classList.remove(
+      'is-visible',
+      'hud__delta--positive',
+      'hud__delta--negative'
+    );
+  }
+
+  return {
+    updateScore(value) {
+      scoreValueEl.textContent = formatNumber(value);
+    },
+    updateTimer(elapsedMs) {
+      timerValueEl.textContent = `${toSeconds(elapsedMs)}s`;
+    },
+    updateDelta(delta) {
+      const formatted = formatDelta(delta);
+      if (!formatted) {
+        clearDelta();
+        return;
+      }
+
+      deltaEl.textContent = formatted;
+      deltaEl.classList.toggle('hud__delta--positive', delta > 0);
+      deltaEl.classList.toggle('hud__delta--negative', delta < 0);
+      deltaEl.classList.add('is-visible');
+
+      if (deltaTimer) {
+        window.clearTimeout(deltaTimer);
+      }
+      deltaTimer = window.setTimeout(() => {
+        deltaEl.classList.remove('is-visible');
+      }, 250);
+    },
+    clearDelta,
+  };
+}
diff --git a/src/ui/hud.test.js b/src/ui/hud.test.js
new file mode 100644
index 0000000..8c2d604
--- /dev/null
+++ b/src/ui/hud.test.js
@@ -0,0 +1,31 @@
+import { createHud } from './hud.js';
+
+describe('HUD rendering', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test('score, timer and delta update with fade-out', () => {
+    // why this test matters: HUD reactions need to be crisp for arcade pacing.
+    const scoreValueEl = document.createElement('span');
+    const timerValueEl = document.createElement('span');
+    const deltaEl = document.createElement('div');
+    const hud = createHud({ scoreValueEl, timerValueEl, deltaEl });
+
+    hud.updateScore(1280);
+    hud.updateTimer(1530);
+    hud.updateDelta(-5);
+
+    expect(scoreValueEl.textContent).toBe('1.3K');
+    expect(timerValueEl.textContent).toBe('1.5s');
+    expect(deltaEl.textContent).toBe('-5');
+    expect(deltaEl.classList.contains('is-visible')).toBe(true);
+
+    jest.advanceTimersByTime(260);
+    expect(deltaEl.classList.contains('is-visible')).toBe(false);
+  });
+});
diff --git a/src/ui/pauseMenu.js b/src/ui/pauseMenu.js
new file mode 100644
index 0000000..66ccfa7
--- /dev/null
+++ b/src/ui/pauseMenu.js
@@ -0,0 +1,62 @@
+export function setupPauseMenu(
+  {
+    overlay,
+    pauseButton,
+    resumeButton,
+    restartButton,
+    muteToggle,
+    lowModeToggle,
+  },
+  handlers = {}
+) {
+  const {
+    onPause = () => {},
+    onResume = () => {},
+    onRestart = () => {},
+    onMuteChange = () => {},
+    onLowModeToggle = () => {},
+  } = handlers;
+
+  function open() {
+    overlay.classList.add('is-visible');
+    onPause();
+  }
+
+  function close() {
+    overlay.classList.remove('is-visible');
+    onResume();
+  }
+
+  pauseButton.addEventListener('click', open);
+  resumeButton.addEventListener('click', () => {
+    close();
+  });
+  restartButton.addEventListener('click', () => {
+    close();
+    onRestart();
+  });
+  overlay.addEventListener('click', (event) => {
+    if (event.target === overlay) {
+      close();
+    }
+  });
+
+  muteToggle.addEventListener('change', (event) => {
+    onMuteChange(event.target.checked);
+  });
+
+  lowModeToggle.addEventListener('change', (event) => {
+    onLowModeToggle(event.target.checked);
+  });
+
+  return {
+    open,
+    close,
+    setMute(value) {
+      muteToggle.checked = Boolean(value);
+    },
+    setLowMode(value) {
+      lowModeToggle.checked = Boolean(value);
+    },
+  };
+}
diff --git a/src/ui/pauseMenu.test.js b/src/ui/pauseMenu.test.js
new file mode 100644
index 0000000..57f8be4
--- /dev/null
+++ b/src/ui/pauseMenu.test.js
@@ -0,0 +1,101 @@
+import { setupPauseMenu } from './pauseMenu.js';
+
+describe('pause menu controls', () => {
+  test('opens, closes and forwards toggle events', () => {
+    // why this test matters: pause interactions maintain pacing and accessibility expectations.
+    const overlay = document.createElement('div');
+    const pauseButton = document.createElement('button');
+    const resumeButton = document.createElement('button');
+    const restartButton = document.createElement('button');
+    const muteToggle = document.createElement('input');
+    muteToggle.type = 'checkbox';
+    const lowModeToggle = document.createElement('input');
+    lowModeToggle.type = 'checkbox';
+
+    const onPause = jest.fn();
+    const onResume = jest.fn();
+    const onRestart = jest.fn();
+    const onMuteChange = jest.fn();
+    const onLowModeToggle = jest.fn();
+
+    const menu = setupPauseMenu(
+      {
+        overlay,
+        pauseButton,
+        resumeButton,
+        restartButton,
+        muteToggle,
+        lowModeToggle,
+      },
+      { onPause, onResume, onRestart, onMuteChange, onLowModeToggle }
+    );
+
+    pauseButton.click();
+    expect(overlay.classList.contains('is-visible')).toBe(true);
+    expect(onPause).toHaveBeenCalledTimes(1);
+
+    muteToggle.checked = true;
+    muteToggle.dispatchEvent(new Event('change'));
+    expect(onMuteChange).toHaveBeenCalledWith(true);
+
+    lowModeToggle.checked = true;
+    lowModeToggle.dispatchEvent(new Event('change'));
+    expect(onLowModeToggle).toHaveBeenCalledWith(true);
+
+    resumeButton.click();
+    expect(onResume).toHaveBeenCalledTimes(1);
+    expect(overlay.classList.contains('is-visible')).toBe(false);
+
+    pauseButton.click();
+    const child = document.createElement('div');
+    overlay.appendChild(child);
+    child.dispatchEvent(new Event('click', { bubbles: true }));
+    expect(overlay.classList.contains('is-visible')).toBe(true);
+    overlay.dispatchEvent(new Event('click'));
+    expect(onResume).toHaveBeenCalledTimes(2);
+
+    pauseButton.click();
+    restartButton.click();
+    expect(onRestart).toHaveBeenCalledTimes(1);
+
+    menu.setMute(true);
+    expect(muteToggle.checked).toBe(true);
+    menu.setLowMode(true);
+    expect(lowModeToggle.checked).toBe(true);
+  });
+
+  test('handles optional callbacks gracefully', () => {
+    // why this test matters: ensures defensive defaults avoid runtime crashes.
+    const overlay = document.createElement('div');
+    const pauseButton = document.createElement('button');
+    const resumeButton = document.createElement('button');
+    const restartButton = document.createElement('button');
+    const muteToggle = document.createElement('input');
+    muteToggle.type = 'checkbox';
+    const lowModeToggle = document.createElement('input');
+    lowModeToggle.type = 'checkbox';
+
+    const menu = setupPauseMenu(
+      {
+        overlay,
+        pauseButton,
+        resumeButton,
+        restartButton,
+        muteToggle,
+        lowModeToggle,
+      },
+      {}
+    );
+
+    expect(() => menu.open()).not.toThrow();
+    expect(() => menu.close()).not.toThrow();
+    pauseButton.click();
+    resumeButton.click();
+    restartButton.click();
+    muteToggle.dispatchEvent(new Event('change'));
+    lowModeToggle.dispatchEvent(new Event('change'));
+    overlay.dispatchEvent(new Event('click'));
+    menu.setMute(false);
+    menu.setLowMode(false);
+  });
+});
diff --git a/src/ui/resultsCard.js b/src/ui/resultsCard.js
new file mode 100644
index 0000000..71f0622
--- /dev/null
+++ b/src/ui/resultsCard.js
@@ -0,0 +1,25 @@
+import { formatNumber } from '../utils/format.js';
+
+export function renderResultsCard(container, results, { survivors }) {
+  if (!results) {
+    container.classList.remove('is-visible');
+    container.querySelector('[data-testid="results-stars"]').innerHTML = '';
+    container.querySelector('[data-testid="results-summary"]').textContent = '';
+    return;
+  }
+
+  container.classList.add('is-visible');
+  const starsEl = container.querySelector('[data-testid="results-stars"]');
+  const summaryEl = container.querySelector('[data-testid="results-summary"]');
+  starsEl.innerHTML = '';
+  const totalStars = Math.max(1, Math.min(3, results.stars));
+  for (let i = 0; i < 3; i += 1) {
+    const star = document.createElement('span');
+    star.textContent = i < totalStars ? '★' : '☆';
+    starsEl.appendChild(star);
+  }
+
+  summaryEl.textContent = `${results.summary} Score ${formatNumber(results.score)} · Survivors ${formatNumber(
+    survivors
+  )}.`;
+}
diff --git a/src/ui/resultsCard.test.js b/src/ui/resultsCard.test.js
new file mode 100644
index 0000000..95e5b42
--- /dev/null
+++ b/src/ui/resultsCard.test.js
@@ -0,0 +1,26 @@
+import { renderResultsCard } from './resultsCard.js';
+
+describe('results card', () => {
+  test('displays stars and summary for results', () => {
+    // why this test matters: the end card sells success/failure and must present accurate totals.
+    const container = document.createElement('article');
+    const starsEl = document.createElement('div');
+    starsEl.setAttribute('data-testid', 'results-stars');
+    const summaryEl = document.createElement('p');
+    summaryEl.setAttribute('data-testid', 'results-summary');
+    container.append(starsEl, summaryEl);
+
+    renderResultsCard(container, null, { survivors: 0 });
+    expect(container.classList.contains('is-visible')).toBe(false);
+
+    const results = {
+      score: 1234,
+      stars: 2,
+      summary: 'Escaped with 24 marauders in 32.0s.',
+    };
+    renderResultsCard(container, results, { survivors: 24 });
+    expect(container.classList.contains('is-visible')).toBe(true);
+    expect(starsEl.textContent).toBe('★★☆');
+    expect(summaryEl.textContent).toContain('Score 1.2K');
+  });
+});
diff --git a/src/ui/reverseStatus.js b/src/ui/reverseStatus.js
new file mode 100644
index 0000000..9b588a4
--- /dev/null
+++ b/src/ui/reverseStatus.js
@@ -0,0 +1,17 @@
+export function renderReverseStatus(container, reverse) {
+  if (!reverse) {
+    container.hidden = true;
+    return;
+  }
+
+  container.hidden = false;
+  const valueEl = container.querySelector('.reverse-status__value');
+  if (!valueEl) {
+    return;
+  }
+
+  valueEl.textContent = reverse.success
+    ? 'Stable Escape Corridor'
+    : 'Critical Pressure';
+  valueEl.style.color = reverse.success ? '#33d6a6' : '#ff5fa2';
+}
diff --git a/src/ui/reverseStatus.test.js b/src/ui/reverseStatus.test.js
new file mode 100644
index 0000000..d17500f
--- /dev/null
+++ b/src/ui/reverseStatus.test.js
@@ -0,0 +1,22 @@
+import { renderReverseStatus } from './reverseStatus.js';
+
+describe('reverse status panel', () => {
+  test('hides when no reverse data and shows status when present', () => {
+    // why this test matters: communicates chase pressure clearly during the reverse phase.
+    const container = document.createElement('div');
+    const valueEl = document.createElement('span');
+    valueEl.className = 'reverse-status__value';
+    container.appendChild(valueEl);
+
+    renderReverseStatus(container, null);
+    expect(container.hidden).toBe(true);
+
+    const reverse = { success: false };
+    renderReverseStatus(container, reverse);
+    expect(container.hidden).toBe(false);
+    expect(valueEl.textContent).toBe('Critical Pressure');
+    reverse.success = true;
+    renderReverseStatus(container, reverse);
+    expect(valueEl.textContent).toBe('Stable Escape Corridor');
+  });
+});
diff --git a/src/ui/skirmishLog.js b/src/ui/skirmishLog.js
new file mode 100644
index 0000000..a5b3a07
--- /dev/null
+++ b/src/ui/skirmishLog.js
@@ -0,0 +1,27 @@
+import { formatNumber } from '../utils/format.js';
+
+export function renderSkirmishLog(container, volleyLog) {
+  if (!volleyLog || volleyLog.length === 0) {
+    container.hidden = true;
+    container.innerHTML = '';
+    return;
+  }
+
+  container.hidden = false;
+  container.innerHTML = '';
+  const heading = document.createElement('h3');
+  heading.textContent = 'Skirmish Volleys';
+  heading.style.margin = '0';
+  heading.style.textTransform = 'uppercase';
+  heading.style.fontSize = '0.82rem';
+  heading.style.letterSpacing = '0.08em';
+  container.appendChild(heading);
+
+  volleyLog.forEach((entry) => {
+    const line = document.createElement('p');
+    line.innerHTML = `Volley <strong>${entry.volley}</strong>: Lost <strong class="player-loss">${formatNumber(
+      entry.playerLoss
+    )}</strong>, Struck <strong class="enemy-loss">${formatNumber(entry.enemyLoss)}</strong>`;
+    container.appendChild(line);
+  });
+}
diff --git a/src/utils/format.js b/src/utils/format.js
new file mode 100644
index 0000000..e61c750
--- /dev/null
+++ b/src/utils/format.js
@@ -0,0 +1,29 @@
+const compactFormatter = new Intl.NumberFormat('en', {
+  notation: 'compact',
+  maximumFractionDigits: 1,
+});
+
+export function formatNumber(value) {
+  if (!Number.isFinite(value)) {
+    return '—';
+  }
+
+  if (Math.abs(value) >= 1000) {
+    return compactFormatter.format(value);
+  }
+
+  return Math.round(value).toLocaleString('en');
+}
+
+export function formatDelta(delta) {
+  if (!Number.isFinite(delta) || delta === 0) {
+    return null;
+  }
+
+  const sign = delta > 0 ? '+' : '';
+  return `${sign}${Math.round(delta)}`;
+}
+
+export function toSeconds(milliseconds) {
+  return (milliseconds / 1000).toFixed(1);
+}
diff --git a/src/utils/format.test.js b/src/utils/format.test.js
new file mode 100644
index 0000000..eefceb8
--- /dev/null
+++ b/src/utils/format.test.js
@@ -0,0 +1,20 @@
+import { formatDelta, formatNumber, toSeconds } from './format.js';
+
+describe('format helpers', () => {
+  test('formatNumber uses compact notation for large values', () => {
+    // why this test matters: HUD must stay readable for high scores on small screens.
+    expect(formatNumber(12500)).toBe('12.5K');
+  });
+
+  test('formatDelta adds sign and rounds', () => {
+    // why this test matters: players rely on quick feedback about squad gains/losses.
+    expect(formatDelta(4.2)).toBe('+4');
+    expect(formatDelta(-3.9)).toBe('-4');
+    expect(formatDelta(0)).toBeNull();
+  });
+
+  test('toSeconds converts milliseconds to seconds with one decimal', () => {
+    // why this test matters: run timer precision ensures consistent pacing feedback.
+    expect(toSeconds(1234)).toBe('1.2');
+  });
+});
diff --git a/src/utils/random.js b/src/utils/random.js
new file mode 100644
index 0000000..ed89ac0
--- /dev/null
+++ b/src/utils/random.js
@@ -0,0 +1,39 @@
+export function normalizeSeed(seed) {
+  if (typeof seed === 'number' && Number.isFinite(seed)) {
+    return Math.abs(Math.floor(seed)).toString();
+  }
+
+  if (typeof seed === 'string' && seed.trim()) {
+    return seed.trim();
+  }
+
+  return Math.floor(Math.random() * Number.MAX_SAFE_INTEGER).toString();
+}
+
+export function createSeededRng(seedInput) {
+  const seed = normalizeSeed(seedInput);
+  let hash = 2166136261 >>> 0;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+
+  let state = hash >>> 0;
+
+  return function rng() {
+    state += 0x6d2b79f5;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function pick(array, rng) {
+  if (!Array.isArray(array) || array.length === 0) {
+    throw new Error('pick requires a non-empty array');
+  }
+
+  const index = Math.floor(rng() * array.length);
+  return array[index];
+}
diff --git a/src/utils/random.test.js b/src/utils/random.test.js
new file mode 100644
index 0000000..8f2661f
--- /dev/null
+++ b/src/utils/random.test.js
@@ -0,0 +1,25 @@
+import { createSeededRng, normalizeSeed, pick } from './random.js';
+
+describe('random utilities', () => {
+  test('normalizeSeed coerces different inputs to string seeds', () => {
+    // why this test matters: consistent seeds keep shared runs aligned across devices.
+    expect(normalizeSeed(42)).toBe('42');
+    expect(normalizeSeed(' mission ')).toBe('mission');
+  });
+
+  test('createSeededRng produces deterministic sequences', () => {
+    // why this test matters: deterministic PRNG powers reproducible gate layouts.
+    const rngA = createSeededRng('deck');
+    const rngB = createSeededRng('deck');
+    const samplesA = Array.from({ length: 5 }, () => rngA());
+    const samplesB = Array.from({ length: 5 }, () => rngB());
+    expect(samplesA).toEqual(samplesB);
+  });
+
+  test('pick selects from array and rejects empty arrays', () => {
+    // why this test matters: prevents silent failures when generating encounter tables.
+    const rng = () => 0.75;
+    expect(pick(['a', 'b', 'c'], rng)).toBe('c');
+    expect(() => pick([], rng)).toThrow('non-empty array');
+  });
+});