Restore utility helpers, DOM helpers, and update docs

Recover src/shared/util.ts (16 functional collection helpers),
src/client/dom.ts (declarative DOM helpers), and their tests from
git history after accidental deletion during folder reorganization.

Update CODING_STANDARDS.md with functional style guidance and DOM
helper recommendations. Add utility adoption as top P2 priority
in BACKLOG.md. Align doc cross-references with new folder structure.

Author: rgilks

docs/ARCHITECTURE.md

@@ -8,7 +8,7 @@ Delta-V employs a full-stack TypeScript architecture built around a **shared pur
 
 ### Key Technologies
 - **Language**: TypeScript (strict mode) across the entire stack.
-- **Frontend**: HTML5 Canvas 2D API for rendering (`client/renderer.ts`), raw DOM/Events for UI and Input. No heavy frameworks (React/Vue/etc.) are used, ensuring maximum performance for the game loop.
+- **Frontend**: HTML5 Canvas 2D API for rendering (`client/renderer/renderer.ts`), raw DOM/Events for UI and Input. No heavy frameworks (React/Vue/etc.) are used, ensuring maximum performance for the game loop.
 - **Backend**: Cloudflare Workers for HTTP routing and Cloudflare Durable Objects for authoritative game state and WebSocket management.
 - **Build & Tools**: `esbuild` for lightning-fast client bundling, `wrangler` for local testing and deployment, and `vitest` for unit testing.
 
@@ -21,7 +21,7 @@ The architecture is divided into three distinct layers: Shared Logic, Server, an
 ### A. Shared Game Engine (`shared/`)
 This is the heart of the project. The decision to keep all game rules in a shared folder makes the system incredibly robust and completely unit-testable.
 
-- **`game-engine.ts`**: A pure functional state machine. It takes the current `GameState` and player actions (e.g., astrogation orders, combat declarations) and returns a new `GameState` along with events (movements, combat results). **Crucially, it has no side effects (no DOM manipulation, no network calls, no storage access).**
+- **`engine/game-engine.ts`**: A pure functional state machine. It takes the current `GameState` and player actions (e.g., astrogation orders, combat declarations) and returns a new `GameState` along with events (movements, combat results). **Crucially, it has no side effects (no DOM manipulation, no network calls, no storage access).**
 - **`movement.ts`**: Contains the complex vector math, gravity well logic, and collision detection. Moving a ship is resolved strictly on an axial hex grid (using `hex.ts`).
 - **`combat.ts`**: Evaluates line-of-sight, calculates combat odds based on velocity/range modifiers, and resolves damage.
 - **`types.ts`**: The single source of truth for all data structures (`GameState`, `Ship`, `CombatResult`, network message payloads). This ensures the client and server never fall out of sync.
@@ -30,7 +30,7 @@ This is the heart of the project. The decision to keep all game rules in a share
 The backend leverages Cloudflare's edge network.
 
 - **`index.ts`**: The standard Worker entry point. It creates tokenized game rooms, generates collision-checked 5-character codes, and forwards valid WebSocket requests.
-- **`game-do.ts` (Durable Object)**: Each game instance is backed by a single Durable Object. This ensures that all WebSocket connections for a specific game hit the same exact machine in Cloudflare's network, preventing race conditions.
+- **`game-do/game-do.ts` (Durable Object)**: Each game instance is backed by a single Durable Object. This ensures that all WebSocket connections for a specific game hit the same exact machine in Cloudflare's network, preventing race conditions.
   - Acts as the authoritative session and transport layer around `game-engine.ts`.
   - Handles WebSocket lifecycle (connections, reconnects, inactivity timeouts, turn timeouts).
   - Validates inputs before dispatch, passes them to the pure engine, stores the resulting state using the Durable Object `ctx.storage`, and broadcasts updates to connected clients.
@@ -40,10 +40,10 @@ The backend leverages Cloudflare's edge network.
 The frontend is responsible for rendering the pure hex-grid state into a smooth, continuous graphical experience.
 
 - **`main.ts`**: The client-side controller. Manages WebSocket connections, local-AI execution, phase transitions, and orchestrates the Renderer, Input, and UI.
-- **`renderer.ts`**: A highly optimized Canvas 2D renderer. It separates logical hex coordinates from pixel coordinates. It features smooth camera interpolation, persistent trails, and movement/combat animations that occur *between* turn phases.
+- **`renderer/renderer.ts`**: A highly optimized Canvas 2D renderer. It separates logical hex coordinates from pixel coordinates. It features smooth camera interpolation, persistent trails, and movement/combat animations that occur *between* turn phases.
 - **`input.ts`**: Manages the complex state of user interaction (selecting burn vectors, queuing attacks, choosing targets) before finalizing and sending them to the server.
-- **`game-client-*.ts` / `renderer-*.ts` helper modules**: Pure client-side helpers for combat selection, input planning, minimap geometry, phase derivation, formatting, and tooltip/view-model logic. These keep the large coordinators testable without introducing a client framework.
-- **`ui.ts` / `audio.ts`**: Handles the HTML overlay (menus, HUD) and Web Audio API interactions.
+- **`game/` / `renderer/` / `ui/` subfolders**: Pure client-side helpers for combat selection, input planning, minimap geometry, phase derivation, formatting, and tooltip/view-model logic. These keep the large coordinators testable without introducing a client framework.
+- **`ui/ui.ts`** / **`audio.ts`**: Handles the HTML overlay (menus, HUD) and Web Audio API interactions.
 - **Visual Polish**: Employs a premium design system with glassmorphism tokens (backdrop-filters), tactile micro-animations (recoil, scaling glows), and pulsing orbital effects for high-end UX.
 
 ### D. Progressive Web App (`static/sw.js`, `static/site.webmanifest`)
@@ -71,16 +71,16 @@ Delta-V is a fully installable PWA. A lightweight hand-written service worker pr
 The next architectural gains are mostly about keeping the current design readable, not replacing it:
 
 ### A. Shared Engine
-- **Split `game-engine.ts` by phase when it becomes painful to navigate**: The engine remains a strong fit for pure functions and plain data. If the file continues to grow, phase-oriented modules are the natural next split.
+- **Engine is now decomposed by phase** (`engine/game-engine.ts`, `engine/combat.ts`, `engine/ordnance.ts`, `engine/victory.ts`, `engine/util.ts`): The engine remains a strong fit for pure functions and plain data.
 - **Avoid premature ECS migration**: The current rules engine has a small, stable entity set and turn-based processing. An ECS would likely make the rules harder to follow before it creates meaningful flexibility.
 - **Prefer a lightweight event log over full event sourcing**: Replays, reconnect catch-up, and spectator mode would benefit from an append-only turn log, but snapshots should remain the source of truth.
 
 ### B. Client
 - **Continue extracting pure helpers from `main.ts`**: Phase derivation, HUD view models, and local/remote result application should keep moving out of the main controller so browser orchestration stays thin.
-- **Split `renderer.ts` by render pass only when needed**: The renderer is large enough to justify future decomposition, but the right split is by visual responsibility, not by introducing a generic rendering framework.
+- **Renderer is now decomposed by visual responsibility** (`renderer/renderer.ts` plus `combat.ts`, `entities.ts`, `vectors.ts`, `effects.ts`, etc.): Further splits should follow the same pattern of visual responsibility.
 - **Add browser-side tests around input/UI/orchestration**: Shared rules are already well covered. The bigger refactor risk now sits in client coordination code.
 
 ### C. Server / Operations
-- **Keep refactoring `game-do.ts` by concern**: Session/auth handling, engine-result publishing, and timeout management should stay separate so features like spectators or replay catch-up can be added without bloating one class.
+- **`game-do/` is now split by concern** (`game-do.ts`, `messages.ts`, `session.ts`, `turns.ts`): Features like spectators or replay catch-up can be added without bloating one class.
 - **Public lobby hardening remains future work**: Longer opaque identifiers, rate limiting, and optional identity/account binding matter more than swapping validation libraries.
 - **Persistence beyond active rooms is still optional**: Durable Object storage is a good fit for live matches; D1 or another store only becomes necessary once match history or player progression matters.

docs/BACKLOG.md

@@ -11,25 +11,117 @@ No open P0 items currently.
 ### Continue mobile HUD/layout polish
 The HUD now measures its live top/bottom offsets instead of relying on fixed `rem` guesses, and the mobile top bar/action cluster have been tightened. There is still follow-up work to validate real-device behavior and finish any remaining overlap or clipping issues on very small screens.
 
-**Files:** `static/style.css`, `src/client/ui.ts`, `src/client/renderer.ts`
+**Files:** `static/style.css`, `src/client/ui/ui.ts`, `src/client/renderer/renderer.ts`
 
 ## P2 — Code Quality
 
-### Shrink main.ts further (1,286 lines)
-`main.ts` is the only coordinator still over 1,000 lines. Its methods are mostly 5-20 line glue between extracted helpers — no single block is large enough for easy extraction. Consider whether a second-level split (e.g., separating local-game orchestration from network orchestration) is worthwhile.
+### 20. Adopt utility helpers across the codebase
+`src/shared/util.ts` provides functional collection helpers (`sumBy`, `minBy`, `maxBy`, `filterMap`, `compact`, `count`, `partition`, `indexBy`, `groupBy`, `cond`, etc.) and `src/client/dom.ts` provides declarative DOM helpers (`el`, `show`/`hide`/`visible`, `byId`). These are tested and documented in CODING_STANDARDS.md but not yet widely used. Sweep the codebase to replace manual reduce/loop/filter patterns with the util helpers, and replace verbose createElement/addEventListener chains with the DOM helpers.
 
-**Files:** `src/client/main.ts`
+**Benefit:** Reduces boilerplate, makes intent clearer, and establishes consistent patterns across the codebase.
+
+**Files:** All files under `src/shared/` and `src/client/` — look for manual `reduce`, `for` loops building accumulators, `.filter().length`, `.map().filter(x => x != null)`, `document.createElement` chains, and `getElementById` with non-null assertions.
+
+### 2a. Pull PlanningState out of the Renderer
+`PlanningState` lives on the `Renderer` but is mutated by `InputHandler`, `main.ts`, and read by renderer sub-modules. Move ownership to `GameClient`. The renderer and input handler receive it as a read reference. Mutations go through existing helpers like `createClearedCombatPlan`.
+
+**Benefit:** Eliminates the tightest coupling in the codebase — three systems reaching into the same mutable bag. Enables snapshotting for debugging/undo.
+
+**Files:** `src/client/main.ts`, `src/client/renderer/renderer.ts`, `src/client/input.ts`
+
+**Details:** See REFACTORING.md Priority 1.
+
+### 2b. Transport adapter for local vs network play
+9 `if (this.isLocalGame)` branches in `main.ts` duplicate logic. Define a `GameTransport` interface with `WebSocketTransport` and `LocalTransport` implementations.
+
+**Benefit:** Eliminates all `isLocalGame` branching. Opens the door for replay playback and test harness transports.
+
+**Files:** `src/client/main.ts`, new `src/client/game/transport.ts`
+
+**Details:** See REFACTORING.md Priority 2.
+
+### 2c. Command dispatch
+Unify ~30 action-handler methods into a single `dispatch(cmd: GameCommand)` bottleneck. The existing `KeyboardAction` discriminated union maps almost directly to `GameCommand`.
+
+**Benefit:** One place for logging, guard conditions, and input routing. Keyboard, UI, and input handler all produce the same command type.
+
+**Files:** `src/client/main.ts`, `src/client/game/keyboard.ts`
+
+**Details:** See REFACTORING.md Priority 3.
+
+### 2d. Typed UI event bus
+Replace `UIManager`'s ~15 nullable callback properties with a single typed `UIEvent` union and emitter. Events feed into the dispatch function from 2c.
+
+**Benefit:** Makes the relationship between UI events and game actions visible and greppable.
+
+**Files:** `src/client/ui/ui.ts`, `src/client/main.ts`
+
+**Details:** See REFACTORING.md Priority 5.
+
+### 2e. Async AI turn loop
+Replace the recursive callback chain in `processAIPhases` with an explicit async loop. Animation callbacks resolve promises instead of recursing.
+
+**Benefit:** AI turn becomes readable as a sequence, not a callback graph.
+
+**Files:** `src/client/main.ts`, `src/client/game/ai-flow.ts`
+
+**Details:** See REFACTORING.md Priority 7.
+
+### 2f. Serialisation codec
+Create `shared/codec.ts` with explicit serialise/deserialise functions for `GameState`. Add a round-trip test to catch new `Map`/`Set` fields.
+
+**Benefit:** Prevents a class of bugs when adding new collection fields to game state.
+
+**Files:** new `src/shared/codec.ts`
+
+**Details:** See REFACTORING.md Priority 8.
 
 ## P3 — Test Coverage
 
-### Improve branch coverage on decomposed engine modules
-`engine-combat.ts` (70.5% branches) has coverage gaps. Add tests for edge cases in combat phase validation.
+### 3a. Improve branch coverage on engine/combat.ts
+Currently 88.39% branches. Add tests for edge cases in combat phase validation (anti-nuke fire, split-fire edge cases, dreadnaught-when-disabled).
+
+**Files:** `src/shared/engine/combat.ts`, `src/shared/engine/combat.test.ts`
+
+### 3b. Improve AI test coverage
+`ai.ts` is at 62.66% statements, 58.61% branches, 54.05% functions. Significant gaps in ordnance AI, combat target selection, and fleet-building decisions.
+
+**Files:** `src/shared/ai.ts`, `src/shared/ai.test.ts`
+
+### 3c. Improve victory.ts branch coverage
+Currently 85.25% branches. Gaps around escape-edge detection, moral victory conditions, and checkpoint race completion.
+
+**Files:** `src/shared/engine/victory.ts`, `src/shared/engine/victory.test.ts`
+
+### 3d. Add movement.ts edge case tests
+Currently 77% branches. Gaps around weak gravity consecutive rules, off-map elimination, and takeoff mechanics.
+
+**Files:** `src/shared/movement.ts`, `src/shared/movement.test.ts`
+
+### 3e. Add protocol validation tests
+`server/protocol.ts` is at 46.77% branches. Add tests for malformed payloads, edge cases in fleet-ready validation, and ordnance launch validation.
+
+**Files:** `src/server/protocol.ts`, `src/server/protocol.test.ts`
+
+## Suggested Order of Work
+
+The P2 items build on each other. Suggested sequencing:
+1. **20** (Adopt utility helpers) — low-risk sweep that improves readability across the board
+2. **2a** (PlanningState) — removes the tightest coupling, minimal disruption
+2. **2b** (Transport) — eliminates isLocalGame branching, big main.ts shrink
+3. **2c** (Command dispatch) — unifies all input routing
+4. **2d** (UI event bus) — feeds naturally into 2c's dispatch
+5. **2e** (Async AI) — standalone, can be done anytime
+6. **2f** (Codec) — standalone, prevents future bugs
+
+P3 items are independent of each other and of P2. They can be interleaved freely.
 
 ## Done
 
-- ~~Decompose game-engine.ts~~ — Extracted into `engine-util.ts`, `engine-victory.ts`, `engine-ordnance.ts`, `engine-combat.ts` with backward-compatible re-exports (681 lines, down from 1957)
+- ~~Decompose game-engine.ts~~ — Extracted into `engine/util.ts`, `engine/victory.ts`, `engine/ordnance.ts`, `engine/combat.ts` with backward-compatible re-exports (681 lines, down from 1957)
 - ~~Add map-data.test.ts~~ — 23 tests covering map builder, body gravity, base placement, scenarios
 - ~~Add processEmplacement tests~~ — 10 tests covering emplacement validation and success paths
 - ~~Add constants validation tests~~ — 15 tests covering ship stats sanity, ordnance mass, combat/cost scaling
-- ~~Shrink renderer.ts~~ — Extracted `renderer-draw.ts`, `renderer-effects.ts`, `renderer-scene.ts`, `renderer-overlay.ts` (1,771 → 1,011 lines)
+- ~~Shrink renderer.ts~~ — Extracted `renderer/draw.ts`, `renderer/effects.ts`, `renderer/scene.ts`, `renderer/overlay.ts` (1,771 → 1,011 lines)
 - ~~Shrink ui.ts and input.ts~~ — Already under 1,000 lines (661 and 313 respectively)
+- ~~Reorganise into folders~~ — Flat prefixed filenames replaced with `game/`, `renderer/`, `ui/`, `engine/`, `game-do/` subfolders