Narrow UIManager surface by exposing log and overlay subviews

Expose GameLogView as ui.log and OverlayView as ui.overlay,
eliminating 15 thin pass-through methods from UIManager.
Callers now use ui.log.logText() and ui.overlay.showToast()
directly. Screen-mode and HUD methods remain on UIManager
since they orchestrate multiple subviews.

Author: rgilks

docs/BACKLOG.md

@@ -95,25 +95,6 @@ behavior for the covered flow.
 `src/client/game/session-controller.ts`,
 `src/client/main.ts`
 
-### Narrow the `UIManager` surface
-
-Reduce pass-through verbosity in `UIManager` so it remains a
-coordinator, not a large forwarding facade.
-
-`UIManager` currently owns the right boundaries, but it still
-contains many thin methods that simply relay calls into
-subviews. The next step is to group or collapse those
-operations around clearer screen/view-model boundaries rather
-than one-method-per-button/per-label style forwarding.
-
-Definition of done: `UIManager` exposes a smaller, more
-coherent API grouped around screen mode and major UI domains,
-with no regression in ownership clarity or testability.
-
-**Files:** `src/client/ui/ui.ts`,
-`src/client/main.ts`,
-affected UI subviews and tests
-
 ### Reduce repetitive UI collection rendering
 
 Introduce a clearer pattern for list-like UI rendering where

src/client/game/command-router.test.ts

@@ -152,8 +152,8 @@ const createDeps = (overrides?: {
   };
   const showAttackButton = vi.fn<CommandRouterDeps['ui']['showAttackButton']>();
   const showFireButton = vi.fn<CommandRouterDeps['ui']['showFireButton']>();
-  const showToast = vi.fn<CommandRouterDeps['ui']['showToast']>();
-  const toggleLog = vi.fn<CommandRouterDeps['ui']['toggleLog']>();
+  const showToast = vi.fn<CommandRouterDeps['ui']['overlay']['showToast']>();
+  const toggleLog = vi.fn<CommandRouterDeps['ui']['log']['toggle']>();
   const updateHUD = vi.fn<() => void>();
   const renderer = {
     centerOnHex: vi.fn<(position: { q: number; r: number }) => void>(),
@@ -196,8 +196,8 @@ const createDeps = (overrides?: {
     ui: {
       showAttackButton,
       showFireButton,
-      showToast,
-      toggleLog,
+      overlay: { showToast },
+      log: { toggle: toggleLog },
     },
     renderer,
     getCanvasCenter: () => ({ x: 400, y: 300 }),
@@ -256,7 +256,7 @@ describe('game-command-router', () => {
 
     expect(deps.ctx.planningState.queuedAttacks).toHaveLength(1);
     expect(ui.showFireButton).toHaveBeenCalledWith(true, 1);
-    expect(ui.showToast).toHaveBeenCalledWith(
+    expect(ui.overlay.showToast).toHaveBeenCalledWith(
       'Undid last attack (1 queued)',
       'info',
     );
@@ -318,7 +318,10 @@ describe('game-command-router', () => {
     expect(deps.ctx.planningState.selectedShipId).toBe('ship-1');
     expect(deps.ctx.planningState.lastSelectedHex).toBe('0,0');
     expect(renderer.centerOnHex).toHaveBeenCalledWith({ q: 0, r: 0 });
-    expect(ui.showToast).toHaveBeenCalledWith('Selected: Packet', 'info');
+    expect(ui.overlay.showToast).toHaveBeenCalledWith(
+      'Selected: Packet',
+      'info',
+    );
     expect(updateHUD).toHaveBeenCalledTimes(1);
   });
 

src/client/game/command-router.ts

@@ -52,8 +52,10 @@ interface CommandRouterContext {
 interface CommandRouterUI {
   showAttackButton: (visible: boolean) => void;
   showFireButton: (visible: boolean, count: number) => void;
-  showToast: (message: string, type: 'error' | 'info' | 'success') => void;
-  toggleLog: () => void;
+  overlay: {
+    showToast: (message: string, type: 'error' | 'info' | 'success') => void;
+  };
+  log: { toggle: () => void };
 }
 
 interface CommandRouterRenderer {
@@ -95,7 +97,7 @@ const undoQueuedAttack = (deps: CommandRouterDeps): void => {
   const count = popQueuedAttack(deps.ctx.planningState);
 
   deps.ui.showFireButton(count > 0, count);
-  deps.ui.showToast(
+  deps.ui.overlay.showToast(
     count > 0 ? `Undid last attack (${count} queued)` : 'Attack queue cleared',
     'info',
   );
@@ -149,7 +151,7 @@ const selectShip = (
 
     if (myAlive && myAlive.length > 1) {
       const name = SHIP_STATS[ship.type]?.name ?? ship.type;
-      deps.ui.showToast(`Selected: ${name}`, 'info');
+      deps.ui.overlay.showToast(`Selected: ${name}`, 'info');
     }
   } else {
     setSelectedShipId(deps.ctx.planningState, shipId);
@@ -257,7 +259,7 @@ export const dispatchGameCommand = (
       return;
     }
     case 'toggleLog':
-      deps.ui.toggleLog();
+      deps.ui.log.toggle();
       return;
     case 'toggleHelp':
       deps.toggleHelp();

src/client/game/integration.test.ts

@@ -112,14 +112,18 @@ const createDeps = (
       clearTrails: track('renderer.clearTrails'),
     },
     ui: {
-      showToast: track('ui.showToast'),
-      logText: track('ui.logText'),
-      setChatEnabled: track('ui.setChatEnabled'),
-      hideReconnecting: track('ui.hideReconnecting'),
       setPlayerId: track('ui.setPlayerId'),
-      clearLog: track('ui.clearLog'),
-      showRematchPending: track('ui.showRematchPending'),
-      showGameOver: track('ui.showGameOver'),
+      log: {
+        logText: track('ui.log.logText'),
+        setChatEnabled: track('ui.log.setChatEnabled'),
+        clear: track('ui.log.clear'),
+      },
+      overlay: {
+        showToast: track('ui.overlay.showToast'),
+        hideReconnecting: track('ui.overlay.hideReconnecting'),
+        showRematchPending: track('ui.overlay.showRematchPending'),
+        showGameOver: track('ui.overlay.showGameOver'),
+      },
       updateLatency: track('ui.updateLatency'),
     },
     calls,
@@ -159,8 +163,10 @@ describe('client integration: connection flow', () => {
     });
 
     expect(deps.ctx.reconnectAttempts).toBe(0);
-    expect(deps.calls['ui.hideReconnecting']).toHaveLength(1);
-    expect(deps.calls['ui.showToast']).toEqual([['Reconnected!', 'success']]);
+    expect(deps.calls['ui.overlay.hideReconnecting']).toHaveLength(1);
+    expect(deps.calls['ui.overlay.showToast']).toEqual([
+      ['Reconnected!', 'success'],
+    ]);
     // No state transition when already playing
     expect(deps.calls.setState).toBeUndefined();
   });
@@ -177,8 +183,8 @@ describe('client integration: connection flow', () => {
     expect(deps.calls.resetTurnTelemetry).toHaveLength(1);
     expect(deps.calls.applyGameState).toEqual([[state]]);
     expect(deps.calls['renderer.clearTrails']).toHaveLength(1);
-    expect(deps.calls['ui.clearLog']).toHaveLength(1);
-    expect(deps.calls['ui.setChatEnabled']).toEqual([[true]]);
+    expect(deps.calls['ui.log.clear']).toHaveLength(1);
+    expect(deps.calls['ui.log.setChatEnabled']).toEqual([[true]]);
     expect(deps.calls.logScenarioBriefing).toHaveLength(1);
     expect(deps.calls.setState).toEqual([['playing_astrogation']]);
   });
@@ -408,7 +414,7 @@ describe('client integration: chat and errors', () => {
       text: 'hello',
     });
 
-    expect(deps.calls['ui.logText']).toEqual([['You: hello', 'log-chat']]);
+    expect(deps.calls['ui.log.logText']).toEqual([['You: hello', 'log-chat']]);
   });
 
   it('opponent chat message logs with "Opponent" label', () => {
@@ -421,7 +427,7 @@ describe('client integration: chat and errors', () => {
       text: 'gg',
     });
 
-    expect(deps.calls['ui.logText']).toEqual([
+    expect(deps.calls['ui.log.logText']).toEqual([
       ['Opponent: gg', 'log-chat-opponent'],
     ]);
   });
@@ -434,7 +440,9 @@ describe('client integration: chat and errors', () => {
       message: 'Invalid action',
     });
 
-    expect(deps.calls['ui.showToast']).toEqual([['Invalid action', 'error']]);
+    expect(deps.calls['ui.overlay.showToast']).toEqual([
+      ['Invalid action', 'error'],
+    ]);
   });
 
   it('rematch pending shows UI', () => {
@@ -444,7 +452,7 @@ describe('client integration: chat and errors', () => {
       type: 'rematchPending',
     } as S2C);
 
-    expect(deps.calls['ui.showRematchPending']).toHaveLength(1);
+    expect(deps.calls['ui.overlay.showRematchPending']).toHaveLength(1);
   });
 });
 

src/client/game/message-handler.ts

@@ -41,14 +41,18 @@ export interface MessageHandlerDeps {
     clearTrails: () => void;
   };
   ui: {
-    showToast: (message: string, type: 'error' | 'info' | 'success') => void;
-    logText: (text: string, cssClass?: string) => void;
-    setChatEnabled: (enabled: boolean) => void;
-    hideReconnecting: () => void;
     setPlayerId: (id: number) => void;
-    clearLog: () => void;
-    showRematchPending: () => void;
-    showGameOver: (won: boolean, reason: string) => void;
+    log: {
+      logText: (text: string, cssClass?: string) => void;
+      setChatEnabled: (enabled: boolean) => void;
+      clear: () => void;
+    };
+    overlay: {
+      showToast: (message: string, type: 'error' | 'info' | 'success') => void;
+      hideReconnecting: () => void;
+      showRematchPending: () => void;
+      showGameOver: (won: boolean, reason: string) => void;
+    };
     updateLatency: (ms: number) => void;
   };
 }
@@ -68,8 +72,8 @@ export const handleServerMessage = (
       applyWelcomeSession(deps.ctx, plan.playerId, plan.code);
       deps.storePlayerToken(plan.code, plan.playerToken);
       if (plan.showReconnectToast) {
-        deps.ui.hideReconnecting();
-        deps.ui.showToast('Reconnected!', 'success');
+        deps.ui.overlay.hideReconnecting();
+        deps.ui.overlay.showToast('Reconnected!', 'success');
       }
       deps.renderer.setPlayerId(plan.playerId);
       deps.ui.setPlayerId(plan.playerId);
@@ -85,8 +89,8 @@ export const handleServerMessage = (
       deps.resetTurnTelemetry();
       deps.applyGameState(deps.deserializeState(plan.state));
       deps.renderer.clearTrails();
-      deps.ui.clearLog();
-      deps.ui.setChatEnabled(true);
+      deps.ui.log.clear();
+      deps.ui.log.setChatEnabled(true);
       deps.logScenarioBriefing();
       deps.setState(plan.nextState);
       break;
@@ -123,16 +127,16 @@ export const handleServerMessage = (
       deps.showGameOverOutcome(plan.won, plan.reason);
       break;
     case 'rematchPending':
-      deps.ui.showRematchPending();
+      deps.ui.overlay.showRematchPending();
       break;
     case 'error':
       console.error('Server error:', plan.message);
-      deps.ui.showToast(plan.message, 'error');
+      deps.ui.overlay.showToast(plan.message, 'error');
       break;
     case 'chat': {
       const isOwn = plan.playerId === deps.ctx.playerId;
       const label = isOwn ? 'You' : 'Opponent';
-      deps.ui.logText(
+      deps.ui.log.logText(
         `${label}: ${plan.text}`,
         isOwn ? 'log-chat' : 'log-chat-opponent',
       );

src/client/game/presentation.ts

@@ -41,23 +41,31 @@ export interface PresentationDeps {
     showLandingEffect: (hex: HexCoord) => void;
   };
   ui: {
-    logMovementEvents: (events: MovementEvent[], ships: Ship[]) => void;
-    logCombatResults: (results: CombatResult[], ships: Ship[]) => void;
-    showToast: (message: string, type: 'error' | 'info' | 'success') => void;
-    logText: (text: string, cssClass?: string) => void;
-    logLanding: (shipName: string, bodyName: string) => void;
-    showGameOver: (won: boolean, reason: string, stats?: GameOverStats) => void;
+    log: {
+      logMovementEvents: (events: MovementEvent[], ships: Ship[]) => void;
+      logCombatResults: (results: CombatResult[], ships: Ship[]) => void;
+      logText: (text: string, cssClass?: string) => void;
+      logLanding: (shipName: string, bodyName: string) => void;
+    };
+    overlay: {
+      showToast: (message: string, type: 'error' | 'info' | 'success') => void;
+      showGameOver: (
+        won: boolean,
+        reason: string,
+        stats?: GameOverStats,
+      ) => void;
+    };
   };
 }
 
 const logLandings = (deps: PresentationDeps, movements: ShipMovement[]) => {
   const gameState = deps.getGameState();
   if (!gameState) return;
   for (const entry of deriveLandingLogEntries(gameState, movements)) {
-    deps.ui.logLanding(entry.shipName, entry.bodyName);
+    deps.ui.log.logLanding(entry.shipName, entry.bodyName);
     deps.renderer.showLandingEffect(entry.destination);
     if (entry.resupplyText) {
-      deps.ui.logText(entry.resupplyText);
+      deps.ui.log.logText(entry.resupplyText);
     }
   }
 };
@@ -75,7 +83,7 @@ export const presentMovementResult = (
   playThrust();
   if (events.length > 0) {
     deps.renderer.showMovementEvents(events);
-    deps.ui.logMovementEvents(events, state.ships);
+    deps.ui.log.logMovementEvents(events, state.ships);
     if (
       events.some(
         (event) => event.damageType === 'eliminated' || event.type === 'crash',
@@ -97,7 +105,7 @@ export const presentCombatResults = (
 ) => {
   deps.applyGameState(state);
   deps.renderer.showCombatResults(results, previousState);
-  deps.ui.logCombatResults(results, state.ships);
+  deps.ui.log.logCombatResults(results, state.ships);
   for (const [i, result] of results.entries()) {
     const target =
       result.targetType === 'ship'
@@ -119,7 +127,7 @@ export const presentCombatResults = (
           ? 'info'
           : 'info';
     setTimeout(
-      () => deps.ui.showToast(`${targetName}: ${outcome}`, toastType),
+      () => deps.ui.overlay.showToast(`${targetName}: ${outcome}`, toastType),
       i * 400,
     );
   }
@@ -141,13 +149,13 @@ export const showGameOverOutcome = (
   const gameState = deps.getGameState();
   const playerId = deps.getPlayerId();
   const plan = deriveGameOverPlan(gameState, playerId, won, reason);
-  deps.ui.logText(plan.logText, plan.logClass);
+  deps.ui.log.logText(plan.logText, plan.logClass);
   const loserShips =
     gameState?.ships.filter((ship: Ship) =>
       plan.loserShipIds.includes(ship.id),
     ) ?? [];
   if (loserShips.length === 0) {
-    deps.ui.showGameOver(won, reason, plan.stats);
+    deps.ui.overlay.showGameOver(won, reason, plan.stats);
     if (plan.resultSound === 'victory') {
       playVictory();
     } else {
@@ -158,7 +166,7 @@ export const showGameOverOutcome = (
   playExplosion();
   const animDuration = deps.renderer.triggerGameOverExplosions(loserShips);
   setTimeout(() => {
-    deps.ui.showGameOver(won, reason, plan.stats);
+    deps.ui.overlay.showGameOver(won, reason, plan.stats);
     if (plan.resultSound === 'victory') {
       playVictory();
     } else {