Align ordnance UI with shared rules

Author: rgilks

docs/ARCHITECTURE.md

@@ -23,6 +23,7 @@ client/          → State machine + Canvas renderer + DOM UI
 - **Transport abstraction.** `GameTransport` decouples the client from WebSocket vs local (AI) play. The client doesn't know or care where state comes from.
 - **Functional style throughout.** Pure derivation functions (`deriveHudViewModel`, `deriveKeyboardAction`, `deriveBurnChangePlan`), mandatory injectable RNG, `cond()` for branching.
 - **Scenario-driven.** `ScenarioRules` controls behaviour: ordnance types, base sharing, combat enabled, checkpoints, escape edges. New scenarios can vary gameplay without engine changes.
+- **Shared rule reuse across layers.** Client ordnance entry, HUD button visibility, and engine validation now all derive from the same shared ordnance-rule helpers, so restricted scenarios do not drift between UI and server authority.
 - **Hidden state filtering.** `filterStateForPlayer` hides fugitive identities in escape scenarios — the server never leaks information the client shouldn't have.
 
 ---
@@ -144,7 +145,7 @@ The frontend renders the pure hex-grid state into a smooth, continuous graphical
 - **`main.ts`**: The client-side coordinator. Manages WebSocket connections, local-AI execution, and phase transitions. Orchestrates the Renderer, Input, and UI through a centralized **`ClientContext`**. Commands are dispatched via `dispatchGameCommand()` in `game/command-router.ts`.
 - **`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, transport abstraction, connection management, input interpretation, view-model helpers, and presentation logic.
+- **`game/`**: Command routing, action handlers (astrogation/combat/ordnance), phase derivation, 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.

docs/CODING_STANDARDS.md

@@ -245,6 +245,8 @@ Client game modules use two patterns depending on purity (see [dependency inject
 
 When adding new side-effecting logic, prefer extending an existing `*Deps` interface over adding methods to `GameClient`. Keep pure derivation functions as direct-parameter exports — they don't need deps.
 
+When the client needs to decide whether an action is legal or should be shown/enabled, prefer reusing shared rule helpers from `src/shared/engine/` over duplicating lighter-weight UI heuristics. The ordnance HUD and ordnance-phase auto-selection follow this pattern: the client derives button visibility/disabled state and default selection from the same validation helpers the engine uses.
+
 ### Transport adapter
 
 Network vs. local game branching is handled by `GameTransport` (`src/client/game/transport.ts`), not by `if (isLocalGame)` checks in action handlers:

src/client/game/helpers.test.ts

@@ -246,6 +246,68 @@ describe('game client helpers', () => {
       canOverload: true,
       canEmplaceBase: true,
       fleetStatus: '⚔ 1v0 1M/1N',
+      launchMineState: {
+        visible: true,
+        disabled: false,
+        title: '',
+      },
+      launchTorpedoState: {
+        visible: true,
+        disabled: false,
+        title: '',
+      },
+      launchNukeState: {
+        visible: true,
+        disabled: false,
+        title: '',
+      },
+    });
+  });
+
+  it('hides disallowed ordnance buttons and disables illegal launches', () => {
+    const state = createState({
+      phase: 'ordnance',
+      scenarioRules: {
+        allowedOrdnanceTypes: ['nuke'],
+      },
+      ships: [
+        createShip({
+          id: 'p0s0',
+          type: 'corsair',
+          cargoUsed: 0,
+        }),
+        createShip({
+          id: 'p1s0',
+          type: 'corsair',
+          owner: 1,
+          destroyed: true,
+        }),
+      ],
+    });
+
+    const planning = {
+      selectedShipId: 'p0s0',
+      burns: new Map(),
+      overloads: new Map(),
+      weakGravityChoices: new Map(),
+    };
+
+    expect(deriveHudViewModel(state, 0, planning)).toMatchObject({
+      launchMineState: {
+        visible: false,
+        disabled: true,
+        title: '',
+      },
+      launchTorpedoState: {
+        visible: false,
+        disabled: true,
+        title: '',
+      },
+      launchNukeState: {
+        visible: true,
+        disabled: true,
+        title: 'Not enough cargo (need 20, have 10)',
+      },
     });
   });
 

src/client/game/helpers.ts

@@ -1,6 +1,15 @@
 import { SHIP_STATS } from '../../shared/constants';
+import {
+  getAllowedOrdnanceTypes,
+  validateOrdnanceLaunch,
+} from '../../shared/engine/util';
 import { hexVecLength } from '../../shared/hex';
-import type { AstrogationOrder, GameState, Ship } from '../../shared/types';
+import type {
+  AstrogationOrder,
+  GameState,
+  Ordnance,
+  Ship,
+} from '../../shared/types';
 import { count } from '../../shared/util';
 import type { PlanningState } from './planning';
 
@@ -34,6 +43,15 @@ export interface HudViewModel {
   multipleShipsAlive: boolean;
   speed: number;
   fuelToStop: number;
+  launchMineState: OrdnanceActionState;
+  launchTorpedoState: OrdnanceActionState;
+  launchNukeState: OrdnanceActionState;
+}
+
+export interface OrdnanceActionState {
+  visible: boolean;
+  disabled: boolean;
+  title: string;
 }
 
 type PlanningSnapshot = Pick<
@@ -182,6 +200,38 @@ export const deriveHudViewModel = (
   );
 
   const stats = selectedShip ? SHIP_STATS[selectedShip.type] : null;
+  const allowedOrdnanceTypes = getAllowedOrdnanceTypes(state);
+
+  const getOrdnanceActionState = (
+    ordnanceType: Ordnance['type'],
+  ): OrdnanceActionState => {
+    if (!allowedOrdnanceTypes.has(ordnanceType)) {
+      return {
+        visible: false,
+        disabled: true,
+        title: '',
+      };
+    }
+
+    if (!selectedShip) {
+      return {
+        visible: true,
+        disabled: true,
+        title: '',
+      };
+    }
+
+    const error = validateOrdnanceLaunch(state, selectedShip, ordnanceType);
+
+    return {
+      visible: true,
+      disabled: error !== null,
+      title:
+        error === 'Only warships and orbital bases can launch torpedoes'
+          ? 'Warships only'
+          : (error ?? ''),
+    };
+  };
 
   return {
     turn: state.turnNumber,
@@ -212,6 +262,9 @@ export const deriveHudViewModel = (
     multipleShipsAlive: myShips.filter((s) => !s.destroyed).length > 1,
     speed: selectedShip ? hexVecLength(selectedShip.velocity) : 0,
     fuelToStop: selectedShip ? hexVecLength(selectedShip.velocity) : 0,
+    launchMineState: getOrdnanceActionState('mine'),
+    launchTorpedoState: getOrdnanceActionState('torpedo'),
+    launchNukeState: getOrdnanceActionState('nuke'),
   };
 };
 

src/client/game/ordnance.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 import type { GameState, Ship } from '../../shared/types';
 import {
   getFirstLaunchableShipId,
+  getUnambiguousLaunchableShipId,
   resolveBaseEmplacementPlan,
   resolveOrdnanceLaunchPlan,
 } from './ordnance';
@@ -26,8 +27,11 @@ function createShip(overrides: Partial<Ship> = {}): Ship {
   };
 }
 
-function createState(ships: Ship[]): Pick<GameState, 'ships'> {
-  return { ships };
+function createState(
+  ships: Ship[],
+  scenarioRules: GameState['scenarioRules'] = {},
+): Pick<GameState, 'ships' | 'scenarioRules'> {
+  return { ships, scenarioRules };
 }
 
 function createPlanning(
@@ -60,6 +64,30 @@ describe('game-client-ordnance', () => {
     expect(getFirstLaunchableShipId(state, 1)).toBe('enemy');
   });
 
+  it('skips ships that cannot launch any allowed ordnance this turn', () => {
+    const state = createState(
+      [
+        createShip({
+          id: 'corsair',
+          type: 'corsair',
+        }),
+        createShip({
+          id: 'packet',
+          type: 'packet',
+        }),
+        createShip({
+          id: 'resupplied',
+          type: 'packet',
+          resuppliedThisTurn: true,
+        }),
+      ],
+      { allowedOrdnanceTypes: ['nuke'] },
+    );
+
+    expect(getFirstLaunchableShipId(state, 0)).toBe('packet');
+    expect(getUnambiguousLaunchableShipId(state, 0)).toBe('packet');
+  });
+
   it('builds a launch plan for torpedoes', () => {
     const state = createState([createShip({ type: 'frigate' })]);
     const planning = createPlanning({
@@ -106,6 +134,38 @@ describe('game-client-ordnance', () => {
       level: 'error',
     });
 
+    expect(
+      resolveOrdnanceLaunchPlan(
+        createState([createShip({ type: 'packet' })], {
+          allowedOrdnanceTypes: ['nuke'],
+        }),
+        createPlanning(),
+        'mine',
+      ),
+    ).toEqual({
+      ok: false,
+      message: 'This scenario does not allow mine launches',
+      level: 'error',
+    });
+
+    expect(
+      resolveOrdnanceLaunchPlan(
+        createState([
+          createShip({
+            type: 'packet',
+            resuppliedThisTurn: true,
+          }),
+        ]),
+        createPlanning(),
+        'nuke',
+      ),
+    ).toEqual({
+      ok: false,
+      message:
+        'Ships cannot launch ordnance during a turn in which they resupply',
+      level: 'error',
+    });
+
     expect(
       resolveOrdnanceLaunchPlan(
         createState([

src/client/game/ordnance.ts

@@ -1,7 +1,8 @@
 import { SHIP_STATS } from '../../shared/constants';
 import {
-  canLaunchOrdnance,
-  validateShipOrdnanceLaunch,
+  getAllowedOrdnanceTypes,
+  hasLaunchableOrdnanceCapacity,
+  validateOrdnanceLaunch,
 } from '../../shared/engine/util';
 import type {
   GameState,
@@ -11,7 +12,7 @@ import type {
 } from '../../shared/types';
 import type { PlanningState } from './planning';
 
-type OrdnanceState = Pick<GameState, 'ships'>;
+type OrdnanceState = Pick<GameState, 'ships' | 'scenarioRules'>;
 
 type OrdnancePlanning = Pick<
   PlanningState,
@@ -58,9 +59,14 @@ export const getFirstLaunchableShipId = (
   state: OrdnanceState,
   playerId: number,
 ): string | null => {
+  const allowedTypes = getAllowedOrdnanceTypes(state);
+
   return (
     state.ships.find(
-      (ship) => ship.owner === playerId && canLaunchOrdnance(ship),
+      (ship) =>
+        ship.owner === playerId &&
+        !ship.resuppliedThisTurn &&
+        hasLaunchableOrdnanceCapacity(ship, allowedTypes),
     )?.id ?? null
   );
 };
@@ -69,8 +75,12 @@ export const getUnambiguousLaunchableShipId = (
   state: OrdnanceState,
   playerId: number,
 ): string | null => {
+  const allowedTypes = getAllowedOrdnanceTypes(state);
   const launchable = state.ships.filter(
-    (ship) => ship.owner === playerId && canLaunchOrdnance(ship),
+    (ship) =>
+      ship.owner === playerId &&
+      !ship.resuppliedThisTurn &&
+      hasLaunchableOrdnanceCapacity(ship, allowedTypes),
   );
 
   return launchable.length === 1 ? launchable[0].id : null;
@@ -95,7 +105,7 @@ export const resolveOrdnanceLaunchPlan = (
     return { ok: false, message: null, level: 'error' };
   }
 
-  const error = validateShipOrdnanceLaunch(ship, ordnanceType);
+  const error = validateOrdnanceLaunch(state, ship, ordnanceType);
 
   if (error) {
     return { ok: false, message: error, level: 'error' };

src/client/game/phase-entry.test.ts

@@ -21,7 +21,10 @@ function createShip(overrides: Partial<Ship> = {}): Ship {
   };
 }
 
-function createState(ships: Ship[]): GameState {
+function createState(
+  ships: Ship[],
+  overrides: Partial<GameState> = {},
+): GameState {
   return {
     gameId: 'LOCAL',
     scenario: 'Bi-Planetary',
@@ -56,6 +59,7 @@ function createState(ships: Ship[]): GameState {
     ],
     winner: null,
     winReason: null,
+    ...overrides,
   };
 }
 
@@ -81,17 +85,41 @@ describe('game-client-phase-entry', () => {
   it('derives ordnance selection from the first launchable ship', () => {
     const plan = deriveClientStateEntryPlan(
       'playing_ordnance',
-      createState([
-        createShip({ id: 'empty', cargoUsed: 50 }),
-        createShip({ id: 'launchable' }),
-      ]),
+      createState(
+        [
+          createShip({
+            id: 'restricted',
+            type: 'corsair',
+          }),
+          createShip({ id: 'launchable', type: 'packet' }),
+        ],
+        { scenarioRules: { allowedOrdnanceTypes: ['nuke'] } },
+      ),
       0,
     );
 
     expect(plan.selectedShipId).toBe('launchable');
     expect(plan.tutorialPhase).toBe('ordnance');
   });
 
+  it('returns null ordnance selection when no ship can launch the allowed types', () => {
+    const plan = deriveClientStateEntryPlan(
+      'playing_ordnance',
+      createState(
+        [
+          createShip({
+            id: 'restricted',
+            type: 'corsair',
+          }),
+        ],
+        { scenarioRules: { allowedOrdnanceTypes: ['nuke'] } },
+      ),
+      0,
+    );
+
+    expect(plan.selectedShipId).toBeNull();
+  });
+
   it('returns null selectedShipId when multiple alive ships exist', () => {
     const plan = deriveClientStateEntryPlan(
       'playing_astrogation',