Extract client game state store helper

Author: rgilks

docs/ARCHITECTURE.md

@@ -147,10 +147,10 @@ The frontend renders the pure hex-grid state into a smooth, continuous graphical
 
 #### Key Design Patterns
 
-- **`main.ts`**: The client-side coordinator. Manages WebSocket connections, local-AI execution, and top-level composition. It now delegates command dispatch to `game/command-router.ts`, client state-entry side effects to `game/state-transition.ts`, and session lifecycle flows to `game/session-controller.ts` instead of keeping those blocks inline.
+- **`main.ts`**: The client-side coordinator. Manages WebSocket connections, local-AI execution, and top-level composition. It now delegates command dispatch to `game/command-router.ts`, game-state application to `game/game-state-store.ts`, client state-entry side effects to `game/state-transition.ts`, and session lifecycle flows to `game/session-controller.ts` instead of keeping those blocks inline.
 - **`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 user interaction (panning, zooming, clicking). It translates raw browser events into `InputEvent` objects. Pure `interpretInput()` then maps these to `GameCommand[]`, ensuring the input layer never directly mutates the application state.
-- **`game/`**: Command routing, action handlers (astrogation/combat/ordnance), phase derivation, transition helpers, session helpers, transport abstraction, connection management, input interpretation, view-model helpers, and presentation logic. Ordnance-phase auto-selection and HUD legality are derived from shared engine rules instead of client-only cargo heuristics.
+- **`game/`**: Command routing, action handlers (astrogation/combat/ordnance), phase derivation, game-state helpers, transition helpers, session helpers, transport abstraction, connection management, input interpretation, view-model helpers, and presentation logic. Ordnance-phase auto-selection and HUD legality are derived from shared engine rules instead of client-only cargo heuristics.
 - **`renderer/`**: Canvas drawing layers (scene, entities, vectors, effects, overlays), camera, minimap, and animation management.
 - **`ui/`**: Screen visibility, HUD view building, button bindings, game log, fleet building, ship list, formatters, and layout metrics.
 - **`ui/ui.ts`** / **`audio.ts`**: Handles the HTML overlay (menus, HUD) and Web Audio API interactions.
@@ -205,6 +205,7 @@ main.ts (GameClient)
   ├→ input.ts (parse mouse/keyboard → InputEvent)
   ├→ ui/ui.ts (manage screens, accept UIEvent)
   ├→ game/command-router.ts (GameCommand → state mutation or network)
+  ├→ game/game-state-store.ts (apply authoritative game state + renderer sync)
   ├→ game/session-controller.ts (create/join/local-start/exit session lifecycle)
   ├→ game/state-transition.ts (client-state entry effects and screen changes)
   ├→ game/network.ts, game/messages.ts (handle S2C)

docs/BACKLOG.md

@@ -22,6 +22,10 @@ project review without rewriting working systems.
   create/join/local-start/exit session flows, by moving the rest
   of session-level `ClientContext` mutation behind explicit
   helpers instead of leaving it in `main.ts`.
+- Keep building on `game/game-state-store.ts`, which now owns
+  authoritative client-side `GameState` replacement, renderer
+  sync, and selection cleanup, so state application stops being
+  open-coded in `main.ts`.
 - Keep `GameClient` as the bootstrap/wiring shell for renderer,
   connection, and UI composition.
 - Target outcome: `main.ts` becomes orchestration glue instead of

src/client/game/game-state-store.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import { createGame } from '../../shared/engine/game-engine';
+import {
+  buildSolarSystemMap,
+  findBaseHex,
+  SCENARIOS,
+} from '../../shared/map-data';
+import type { GameState } from '../../shared/types';
+import {
+  type ApplyClientGameStateDeps,
+  applyClientGameState,
+} from './game-state-store';
+
+const createState = (overrides: Partial<GameState> = {}): GameState => ({
+  ...createGame(SCENARIOS.duel, buildSolarSystemMap(), 'STORE1', findBaseHex),
+  ...overrides,
+});
+
+const createDeps = (
+  selectedShipId: string | null = null,
+): ApplyClientGameStateDeps & {
+  rendererCalls: GameState[];
+} => {
+  const rendererCalls: GameState[] = [];
+
+  return {
+    ctx: {
+      gameState: null,
+      planningState: {
+        selectedShipId,
+      },
+    },
+    renderer: {
+      setGameState: (state) => {
+        rendererCalls.push(state);
+      },
+    },
+    rendererCalls,
+  };
+};
+
+describe('applyClientGameState', () => {
+  it('stores the game state and updates the renderer', () => {
+    const state = createState();
+    const deps = createDeps();
+
+    applyClientGameState(deps, state);
+
+    expect(deps.ctx.gameState).toBe(state);
+    expect(deps.rendererCalls).toEqual([state]);
+  });
+
+  it('keeps the selected ship when it still exists and is alive', () => {
+    const state = createState();
+    const selectedShipId = state.ships[0]?.id ?? null;
+    const deps = createDeps(selectedShipId);
+
+    applyClientGameState(deps, state);
+
+    expect(deps.ctx.planningState.selectedShipId).toBe(selectedShipId);
+  });
+
+  it('clears the selected ship when it no longer exists', () => {
+    const state = createState();
+    const deps = createDeps('missing-ship');
+
+    applyClientGameState(deps, state);
+
+    expect(deps.ctx.planningState.selectedShipId).toBeNull();
+  });
+
+  it('clears the selected ship when it was destroyed', () => {
+    const state = createState({
+      ships: createState().ships.map((ship, index) =>
+        index === 0 ? { ...ship, destroyed: true } : ship,
+      ),
+    });
+    const destroyedShipId = state.ships[0]?.id ?? null;
+    const deps = createDeps(destroyedShipId);
+
+    applyClientGameState(deps, state);
+
+    expect(deps.ctx.planningState.selectedShipId).toBeNull();
+  });
+});

src/client/game/game-state-store.ts

@@ -0,0 +1,37 @@
+import type { GameState } from '../../shared/types';
+
+interface PlanningStateLike {
+  selectedShipId: string | null;
+}
+
+interface GameStateStoreContext {
+  gameState: GameState | null;
+  planningState: PlanningStateLike;
+}
+
+interface GameStateStoreRenderer {
+  setGameState: (state: GameState) => void;
+}
+
+export interface ApplyClientGameStateDeps {
+  ctx: GameStateStoreContext;
+  renderer: GameStateStoreRenderer;
+}
+
+export const applyClientGameState = (
+  deps: ApplyClientGameStateDeps,
+  state: GameState,
+): void => {
+  deps.ctx.gameState = state;
+  deps.renderer.setGameState(state);
+
+  const selectedId = deps.ctx.planningState.selectedShipId;
+  if (!selectedId) {
+    return;
+  }
+
+  const selectedShip = state.ships.find((ship) => ship.id === selectedId);
+  if (!selectedShip || selectedShip.destroyed) {
+    deps.ctx.planningState.selectedShipId = null;
+  }
+};

src/client/main.ts

@@ -54,6 +54,7 @@ import {
   createConnectionManager,
 } from './game/connection';
 import { resolveLocalFleetReady } from './game/fleet';
+import { applyClientGameState } from './game/game-state-store';
 import { deriveHudViewModel } from './game/helpers';
 import { getTooltipShip } from './game/hover';
 import { type InputEvent, interpretInput } from './game/input-events';
@@ -535,16 +536,13 @@ class GameClient {
     this.connection.send(msg);
   }
   private applyGameState(state: GameState) {
-    this.ctx.gameState = state;
-    this.renderer.setGameState(state);
-    // Clear selection if the selected ship was destroyed
-    const selectedId = this.ctx.planningState.selectedShipId;
-    if (selectedId) {
-      const ship = state.ships.find((s) => s.id === selectedId);
-      if (!ship || ship.destroyed) {
-        this.ctx.planningState.selectedShipId = null;
-      }
-    }
+    applyClientGameState(
+      {
+        ctx: this.ctx,
+        renderer: this.renderer,
+      },
+      state,
+    );
   }
   private presentMovementResult(
     state: GameState,