Adopt utility and DOM helpers across the codebase

Replace manual patterns with shared helpers:
- sumBy/minBy/count replace reduce/filter chains in ai, combat, helpers
- clamp replaces Math.max(min, Math.min(max, v)) in combat, camera, main
- parseHexKey replaces inline key.split(',').map(Number) in combat, victory, ai
- randomChoice replaces manual array indexing in game-engine
- pickBy replaces Object.fromEntries(Object.entries().filter()) in session
- byId replaces document.getElementById()! across all client code
- show/hide/visible replace manual style.display toggling in ui, main, tutorial
- el replaces createElement+className+textContent for simple elements

Author: rgilks

src/client/game/combat.ts

@@ -1,6 +1,7 @@
 import { canAttack, getCombatStrength, hasLineOfSight, hasLineOfSightToTarget } from '../../shared/combat';
 import { type HexCoord, hexEqual } from '../../shared/hex';
 import type { CombatAttack, GameState, SolarSystemMap } from '../../shared/types';
+import { clamp } from '../../shared/util';
 import type { PlanningState } from '../renderer/renderer';
 
 type CombatPlanningSnapshot = Pick<
@@ -101,7 +102,7 @@ export const hasSplitFireOptions = (state: GameState, playerId: number, queuedAt
 
 const clampAttackStrength = (maxStrength: number, requestedStrength: number | null): number | null => {
   if (maxStrength <= 0) return null;
-  return Math.max(1, Math.min(maxStrength, requestedStrength ?? maxStrength));
+  return clamp(requestedStrength ?? maxStrength, 1, maxStrength);
 };
 
 export const getCombatAttackerIdAtHex = (state: GameState, playerId: number, clickHex: HexCoord): string | null => {

src/client/game/helpers.ts

@@ -1,5 +1,6 @@
 import { SHIP_STATS } from '../../shared/constants';
 import type { AstrogationOrder, GameState, Ship } from '../../shared/types';
+import { count } from '../../shared/util';
 import type { PlanningState } from '../renderer/renderer';
 
 export interface GameOverStats {
@@ -59,8 +60,8 @@ const getObjective = (state: GameState, playerId: number): string => {
 const getFleetStatus = (state: GameState, playerId: number): string => {
   const myShips = state.ships.filter((ship) => ship.owner === playerId);
   const enemyShips = state.ships.filter((ship) => ship.owner !== playerId);
-  const myAlive = myShips.filter((ship) => !ship.destroyed).length;
-  const enemyAlive = enemyShips.filter((ship) => !ship.destroyed).length;
+  const myAlive = count(myShips, (ship) => !ship.destroyed);
+  const enemyAlive = count(enemyShips, (ship) => !ship.destroyed);
   const statusParts: string[] = [];
   if (myShips.length > 1 || enemyShips.length > 1) {
     statusParts.push(`⚔ ${myAlive}v${enemyAlive}`);
@@ -72,9 +73,9 @@ const getFleetStatus = (state: GameState, playerId: number): string => {
   }
 
   const ordnanceParts: string[] = [];
-  const mines = activeOrdnance.filter((ordnance) => ordnance.type === 'mine').length;
-  const torpedoes = activeOrdnance.filter((ordnance) => ordnance.type === 'torpedo').length;
-  const nukes = activeOrdnance.filter((ordnance) => ordnance.type === 'nuke').length;
+  const mines = count(activeOrdnance, (ordnance) => ordnance.type === 'mine');
+  const torpedoes = count(activeOrdnance, (ordnance) => ordnance.type === 'torpedo');
+  const nukes = count(activeOrdnance, (ordnance) => ordnance.type === 'nuke');
   if (mines > 0) ordnanceParts.push(`${mines}M`);
   if (torpedoes > 0) ordnanceParts.push(`${torpedoes}T`);
   if (nukes > 0) ordnanceParts.push(`${nukes}N`);
@@ -130,9 +131,9 @@ export const getGameOverStats = (state: GameState, playerId: number): GameOverSt
   const enemyShips = state.ships.filter((ship) => ship.owner !== playerId);
   return {
     turns: state.turnNumber,
-    myShipsAlive: myShips.filter((ship) => !ship.destroyed).length,
+    myShipsAlive: count(myShips, (ship) => !ship.destroyed),
     myShipsTotal: myShips.length,
-    enemyShipsAlive: enemyShips.filter((ship) => !ship.destroyed).length,
+    enemyShipsAlive: count(enemyShips, (ship) => !ship.destroyed),
     enemyShipsTotal: enemyShips.length,
   };
 };

src/client/game/session.ts

@@ -1,3 +1,5 @@
+import { pickBy } from '../../shared/util';
+
 export interface TokenStoreEntry {
   playerToken?: string;
   inviteToken?: string;
@@ -29,7 +31,7 @@ export const loadTokenStore = (storage: Pick<StorageLike, 'getItem'>, key = TOKE
 };
 
 export const pruneExpiredTokens = (store: TokenStore, now: number, ttlMs = TOKEN_TTL_MS): TokenStore => {
-  return Object.fromEntries(Object.entries(store).filter(([, entry]) => now - entry.ts <= ttlMs));
+  return pickBy(store, (entry) => now - entry.ts <= ttlMs) as TokenStore;
 };
 
 export const saveTokenStore = (

src/client/main.ts

@@ -18,6 +18,7 @@ import type {
   S2C,
   ShipMovement,
 } from '../shared/types';
+import { clamp } from '../shared/util';
 import {
   initAudio,
   isMuted,
@@ -32,6 +33,7 @@ import {
   playWarning,
   setMuted,
 } from './audio';
+import { byId, hide, show } from './dom';
 import { deriveAIActionPlan } from './game/ai-flow';
 import { deriveScenarioBriefingEntries } from './game/briefing';
 import { deriveBurnChangePlan } from './game/burn';
@@ -111,12 +113,12 @@ class GameClient {
   private timerWarningPlayed = false;
 
   constructor() {
-    this.canvas = document.getElementById('gameCanvas') as HTMLCanvasElement;
+    this.canvas = byId<HTMLCanvasElement>('gameCanvas');
     this.renderer = new Renderer(this.canvas);
     this.input = new InputHandler(this.canvas, this.renderer.camera, this.renderer.planningState);
     this.ui = new UIManager();
     this.tutorial = new Tutorial();
-    this.tooltipEl = document.getElementById('shipTooltip')!;
+    this.tooltipEl = byId('shipTooltip');
 
     this.renderer.setMap(this.map);
     this.input.setMap(this.map);
@@ -170,11 +172,11 @@ class GameClient {
     });
 
     // Help overlay
-    document.getElementById('helpCloseBtn')!.addEventListener('click', () => this.toggleHelp());
-    document.getElementById('helpBtn')!.addEventListener('click', () => this.toggleHelp());
+    byId('helpCloseBtn').addEventListener('click', () => this.toggleHelp());
+    byId('helpBtn').addEventListener('click', () => this.toggleHelp());
 
     // Sound toggle
-    const soundBtn = document.getElementById('soundBtn')!;
+    const soundBtn = byId('soundBtn');
     this.updateSoundButton();
     soundBtn.addEventListener('click', () => {
       setMuted(!isMuted());
@@ -184,7 +186,7 @@ class GameClient {
     // Ship hover tooltip
     this.canvas.addEventListener('mousemove', (e) => this.updateTooltip(e.clientX, e.clientY));
     this.canvas.addEventListener('mouseleave', () => {
-      this.tooltipEl.style.display = 'none';
+      hide(this.tooltipEl);
     });
 
     // Start render loop and audio
@@ -211,7 +213,7 @@ class GameClient {
   private setState(newState: ClientState) {
     this.state = newState;
     // Hide tooltip on state changes
-    this.tooltipEl.style.display = 'none';
+    hide(this.tooltipEl);
 
     const entryPlan = deriveClientStateEntryPlan(newState, this.gameState, this.playerId);
     const screenPlan = deriveClientScreenPlan(
@@ -837,7 +839,7 @@ class GameClient {
     if (maxStrength <= 0) return;
 
     const current = this.renderer.planningState.combatAttackStrength ?? maxStrength;
-    this.renderer.planningState.combatAttackStrength = Math.max(1, Math.min(maxStrength, current + delta));
+    this.renderer.planningState.combatAttackStrength = clamp(current + delta, 1, maxStrength);
   }
 
   private resetCombatStrengthToMax() {
@@ -1255,12 +1257,12 @@ class GameClient {
     const ship = getTooltipShip(gameState, this.state, this.playerId, hoverHex);
 
     if (!ship || !gameState) {
-      this.tooltipEl.style.display = 'none';
+      hide(this.tooltipEl);
       return;
     }
 
     this.tooltipEl.innerHTML = buildShipTooltipHtml(gameState, ship, this.playerId, this.map);
-    this.tooltipEl.style.display = 'block';
+    show(this.tooltipEl, 'block');
     // Position tooltip offset from cursor
     this.tooltipEl.style.left = `${screenX + 12}px`;
     this.tooltipEl.style.top = `${screenY - 10}px`;

src/client/renderer/camera.ts

@@ -1,5 +1,6 @@
 import { CAMERA_LERP_SPEED } from '../../shared/constants';
 import type { PixelCoord } from '../../shared/hex';
+import { clamp } from '../../shared/util';
 
 export class Camera {
   x = 0;
@@ -54,7 +55,7 @@ export class Camera {
   }
 
   zoomAt(sx: number, sy: number, factor: number) {
-    const newZoom = Math.max(this.minZoom, Math.min(this.maxZoom, this.targetZoom * factor));
+    const newZoom = clamp(this.targetZoom * factor, this.minZoom, this.maxZoom);
     const worldX = (sx - this.canvasW / 2) / this.targetZoom + this.targetX;
     const worldY = (sy - this.canvasH / 2) / this.targetZoom + this.targetY;
     this.targetZoom = newZoom;

src/client/renderer/combat.ts

@@ -12,6 +12,7 @@ import {
 } from '../../shared/combat';
 import type { HexCoord } from '../../shared/hex';
 import type { CombatAttack, CombatResult, GameState, Ordnance, Ship, SolarSystemMap } from '../../shared/types';
+import { clamp } from '../../shared/util';
 
 export interface CombatOverlayPlanningState {
   combatTargetId: string | null;
@@ -167,7 +168,7 @@ const formatPreviewLabel = (
     const shipTarget = target as Ship;
     const maxAttackStrength = getCombatStrength(attackers);
     const attackStrength =
-      maxAttackStrength > 0 ? Math.max(1, Math.min(maxAttackStrength, requestedStrength ?? maxAttackStrength)) : 0;
+      maxAttackStrength > 0 ? clamp(requestedStrength ?? maxAttackStrength, 1, maxAttackStrength) : 0;
     const defendStrength = getCombatStrength([shipTarget]);
     const odds = computeOdds(attackStrength, defendStrength);
     rangeMod = computeGroupRangeMod(attackers, shipTarget);

src/client/tutorial.ts

@@ -5,6 +5,8 @@
  * Tutorial state is persisted in localStorage so it only shows once.
  */
 
+import { byId, hide, show } from './dom';
+
 const STORAGE_KEY = 'deltav_tutorial_done';
 
 interface TutorialStep {
@@ -63,18 +65,18 @@ export class Tutorial {
   private activeStepId: string | null = null;
 
   constructor() {
-    this.tipEl = document.getElementById('tutorialTip')!;
-    this.textEl = document.getElementById('tutorialTipText')!;
-    this.progressEl = document.getElementById('tutorialProgress')!;
+    this.tipEl = byId('tutorialTip');
+    this.textEl = byId('tutorialTipText');
+    this.progressEl = byId('tutorialProgress');
 
     // Check if tutorial already completed
     if (localStorage.getItem(STORAGE_KEY) === '1') {
       this.completed = true;
     }
 
     // Wire buttons
-    document.getElementById('tutorialNextBtn')!.addEventListener('click', () => this.advance());
-    document.getElementById('tutorialSkipBtn')!.addEventListener('click', () => this.skip());
+    byId('tutorialNextBtn').addEventListener('click', () => this.advance());
+    byId('tutorialSkipBtn').addEventListener('click', () => this.skip());
   }
 
   /** Check if tutorial is active (not completed) */
@@ -103,14 +105,14 @@ export class Tutorial {
 
   /** Hide the tutorial tip */
   hideTip() {
-    this.tipEl.style.display = 'none';
+    hide(this.tipEl);
     this.activeStepId = null;
   }
 
   private showStep(step: TutorialStep) {
     this.activeStepId = step.id;
     this.textEl.textContent = step.text;
-    this.tipEl.style.display = 'block';
+    show(this.tipEl, 'block');
     // Re-trigger animation
     this.tipEl.style.animation = 'none';
     void this.tipEl.offsetHeight; // force reflow

src/client/ui/fleet.ts

@@ -1,5 +1,6 @@
 import { SHIP_STATS } from '../../shared/constants';
 import type { FleetPurchase } from '../../shared/types';
+import { sumBy } from '../../shared/util';
 
 export interface FleetShopItemView {
   shipType: string;
@@ -28,7 +29,7 @@ export const getFleetShopTypes = () => {
 };
 
 export const getFleetCartCost = (cart: FleetPurchase[]): number => {
-  return cart.reduce((total, purchase) => total + (SHIP_STATS[purchase.shipType]?.cost ?? 0), 0);
+  return sumBy(cart, (purchase) => SHIP_STATS[purchase.shipType]?.cost ?? 0);
 };
 
 export const canAddFleetShip = (cart: FleetPurchase[], totalCredits: number, shipType: string): boolean => {