chore(release): 4.6.2 [skip ci]

## [4.6.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.1...v4.6.2) (2025-10-18)

### Bug Fixes

* **build:** resolve Docker build failures preventing deployment ([7801dbb](7801dbb25f))

CHANGELOG.md

@@ -1,3 +1,45 @@
+## [4.6.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.1...v4.6.2) (2025-10-18)
+
+
+### Bug Fixes
+
+* **build:** resolve Docker build failures preventing deployment ([7801dbb](https://github.com/antialias/soroban-abacus-flashcards/commit/7801dbb25fb0a33429c70f11294264f7238ce7a4))
+
+## [4.6.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.0...v4.6.1) (2025-10-18)
+
+
+### Code Refactoring
+
+* **complement-race:** move AI opponents from server-side to client-side ([09e21fa](https://github.com/antialias/soroban-abacus-flashcards/commit/09e21fa4934c634d0ce46381ef7e40238fc134c3))
+
+## [4.6.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.5.0...v4.6.0) (2025-10-18)
+
+
+### Features
+
+* **complement-race:** restore AI opponents in practice and survival modes ([325e07d](https://github.com/antialias/soroban-abacus-flashcards/commit/325e07de5929169aa333ef16f7bca5b41eeb1622))
+
+## [4.5.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.15...v4.5.0) (2025-10-18)
+
+
+### Features
+
+* **complement-race:** add infinite win condition for Steam Sprint mode ([d8fdfee](https://github.com/antialias/soroban-abacus-flashcards/commit/d8fdfeef74a5d3bb9684254af1c9d64d264b46ad))
+
+## [4.4.15](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.14...v4.4.15) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** track previous position to detect route threshold crossing ([a6c20aa](https://github.com/antialias/soroban-abacus-flashcards/commit/a6c20aab3b245d9893808d188d16a35ab80cfca9))
+
+## [4.4.14](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.13...v4.4.14) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** remove dual game loop conflict preventing route progression ([84d42e2](https://github.com/antialias/soroban-abacus-flashcards/commit/84d42e22ac0cdd25e87e45dc698029ad7ed78559))
+
 ## [4.4.13](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.12...v4.4.13) (2025-10-17)
 
 

apps/web/src/app/arcade/complement-race/hooks/useSteamJourney.ts

@@ -45,6 +45,7 @@ export function useSteamJourney() {
   const routeExitThresholdRef = useRef<number>(107) // Default for 1 car: 100 + 7
   const missedPassengersRef = useRef<Set<string>>(new Set()) // Track which passengers have been logged as missed
   const pendingBoardingRef = useRef<Set<string>>(new Set()) // Track passengers with pending boarding requests across frames
+  const previousTrainPositionRef = useRef<number>(0) // Track previous position to detect threshold crossings
 
   // Initialize game start time
   useEffect(() => {
@@ -78,6 +79,7 @@ export function useSteamJourney() {
   useEffect(() => {
     pendingBoardingRef.current.clear()
     missedPassengersRef.current.clear()
+    previousTrainPositionRef.current = 0 // Reset previous position for new route
   }, [state.currentRoute])
 
   // Momentum decay and position update loop
@@ -92,37 +94,9 @@ export function useSteamJourney() {
 
       // Steam Sprint is infinite - no time limit
 
-      // Get decay rate based on timeout setting (skill level)
-      const decayRate =
-        MOMENTUM_DECAY_RATES[state.timeoutSetting as keyof typeof MOMENTUM_DECAY_RATES] ||
-        MOMENTUM_DECAY_RATES.normal
-
-      // Calculate momentum decay for this frame
-      const momentumLoss = (decayRate * deltaTime) / 1000
-
-      // Update momentum (don't go below 0)
-      const newMomentum = Math.max(0, state.momentum - momentumLoss)
-
-      // Calculate speed from momentum (% per second)
-      const speed = newMomentum * SPEED_MULTIPLIER
-
-      // Update train position (accumulate, never go backward)
-      // Allow position to go past 100% so entire train (including cars) can exit tunnel
-      const positionDelta = (speed * deltaTime) / 1000
-      const trainPosition = state.trainPosition + positionDelta
-
-      // Calculate pressure (0-150 PSI) - based on momentum as percentage of max
-      const maxMomentum = 100 // Theoretical max momentum
-      const pressure = Math.min(150, (newMomentum / maxMomentum) * 150)
-
-      // Update state
-      dispatch({
-        type: 'UPDATE_STEAM_JOURNEY',
-        momentum: newMomentum,
-        trainPosition,
-        pressure,
-        elapsedTime: elapsed,
-      })
+      // Train position, momentum, and pressure are all managed by the Provider's game loop
+      // This hook only reads those values and handles game logic (boarding, delivery, route completion)
+      const trainPosition = state.trainPosition
 
       // Check for passengers that should board
       // Passengers board when an EMPTY car reaches their station
@@ -320,10 +294,11 @@ export function useSteamJourney() {
 
       // Check for route completion (entire train exits tunnel)
       const ENTIRE_TRAIN_EXIT_THRESHOLD = routeExitThresholdRef.current
+      const previousPosition = previousTrainPositionRef.current
 
       if (
         trainPosition >= ENTIRE_TRAIN_EXIT_THRESHOLD &&
-        state.trainPosition < ENTIRE_TRAIN_EXIT_THRESHOLD
+        previousPosition < ENTIRE_TRAIN_EXIT_THRESHOLD
       ) {
         // Play celebration whistle
         playSound('train_whistle', 0.6)
@@ -333,6 +308,9 @@ export function useSteamJourney() {
 
         // Auto-advance to next route
         const nextRoute = state.currentRoute + 1
+        console.log(
+          `🏁 ROUTE COMPLETE: Train crossed exit threshold (${trainPosition.toFixed(1)} >= ${ENTIRE_TRAIN_EXIT_THRESHOLD}). Advancing to Route ${nextRoute}`
+        )
         dispatch({
           type: 'START_NEW_ROUTE',
           routeNumber: nextRoute,
@@ -341,6 +319,9 @@ export function useSteamJourney() {
 
         // Note: New passengers will be generated by the server when it handles START_NEW_ROUTE
       }
+
+      // Update previous position for next frame
+      previousTrainPositionRef.current = trainPosition
     }, UPDATE_INTERVAL)
 
     return () => clearInterval(interval)

apps/web/src/app/arcade/complement-race/page.tsx

@@ -2,7 +2,7 @@
 
 import { PageWithNav } from '@/components/PageWithNav'
 import { ComplementRaceGame } from './components/ComplementRaceGame'
-import { ComplementRaceProvider } from './context/ComplementRaceContext'
+import { ComplementRaceProvider } from '@/arcade-games/complement-race/Provider'
 
 export default function ComplementRacePage() {
   return (

apps/web/src/app/arcade/complement-race/practice/page.tsx

@@ -2,7 +2,7 @@
 
 import { PageWithNav } from '@/components/PageWithNav'
 import { ComplementRaceGame } from '../components/ComplementRaceGame'
-import { ComplementRaceProvider } from '../context/ComplementRaceContext'
+import { ComplementRaceProvider } from '@/arcade-games/complement-race/Provider'
 
 export default function PracticeModePage() {
   return (

apps/web/src/app/arcade/complement-race/sprint/page.tsx

@@ -2,7 +2,7 @@
 
 import { PageWithNav } from '@/components/PageWithNav'
 import { ComplementRaceGame } from '../components/ComplementRaceGame'
-import { ComplementRaceProvider } from '../context/ComplementRaceContext'
+import { ComplementRaceProvider } from '@/arcade-games/complement-race/Provider'
 
 export default function SprintModePage() {
   return (

apps/web/src/app/arcade/complement-race/survival/page.tsx

@@ -2,7 +2,7 @@
 
 import { PageWithNav } from '@/components/PageWithNav'
 import { ComplementRaceGame } from '../components/ComplementRaceGame'
-import { ComplementRaceProvider } from '../context/ComplementRaceContext'
+import { ComplementRaceProvider } from '@/arcade-games/complement-race/Provider'
 
 export default function SurvivalModePage() {
   return (

apps/web/src/app/games/complement-race/components/RaceTrack/__tests__/GameHUD.test.tsx

@@ -29,6 +29,7 @@ describe('GameHUD', () => {
 
   const mockPassenger: Passenger = {
     id: 'passenger-1',
+    name: 'Test Passenger',
     avatar: '👨',
     originStationId: 'station-1',
     destinationStationId: 'station-2',

apps/web/src/app/games/complement-race/hooks/__tests__/usePassengerAnimations.test.ts

@@ -44,6 +44,7 @@ describe('usePassengerAnimations', () => {
     // Create mock passengers
     mockPassenger1 = {
       id: 'passenger-1',
+      name: 'Passenger 1',
       avatar: '👨',
       originStationId: 'station-1',
       destinationStationId: 'station-2',
@@ -54,6 +55,7 @@ describe('usePassengerAnimations', () => {
 
     mockPassenger2 = {
       id: 'passenger-2',
+      name: 'Passenger 2',
       avatar: '👩',
       originStationId: 'station-1',
       destinationStationId: 'station-2',

apps/web/src/app/games/complement-race/hooks/__tests__/useTrackManagement.test.ts

@@ -52,6 +52,7 @@ describe('useTrackManagement', () => {
     mockPassengers = [
       {
         id: 'passenger-1',
+        name: 'Test Passenger',
         avatar: '👨',
         originStationId: 'station-1',
         destinationStationId: 'station-2',
@@ -73,6 +74,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 
@@ -90,6 +93,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 
@@ -107,6 +112,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 
@@ -123,6 +130,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 
@@ -142,6 +151,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 
@@ -161,6 +172,8 @@ describe('useTrackManagement', () => {
           pathRef: mockPathRef,
           stations: mockStations,
           passengers: mockPassengers,
+          maxCars: 3,
+          carSpacing: 7,
         }),
       {
         initialProps: { route: 1, position: 0 },
@@ -187,6 +200,8 @@ describe('useTrackManagement', () => {
           pathRef: mockPathRef,
           stations: mockStations,
           passengers: mockPassengers,
+          maxCars: 3,
+          carSpacing: 7,
         }),
       {
         initialProps: { route: 1, position: 0 },
@@ -214,6 +229,8 @@ describe('useTrackManagement', () => {
           pathRef: mockPathRef,
           stations: mockStations,
           passengers: mockPassengers,
+          maxCars: 3,
+          carSpacing: 7,
         }),
       {
         initialProps: { route: 1, position: -5 },
@@ -233,6 +250,7 @@ describe('useTrackManagement', () => {
     const newPassengers: Passenger[] = [
       {
         id: 'passenger-2',
+        name: 'New Passenger',
         avatar: '👩',
         originStationId: 'station-1',
         destinationStationId: 'station-2',
@@ -273,6 +291,7 @@ describe('useTrackManagement', () => {
     const newPassengers: Passenger[] = [
       {
         id: 'passenger-2',
+        name: 'New Passenger',
         avatar: '👩',
         originStationId: 'station-1',
         destinationStationId: 'station-2',
@@ -354,6 +373,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 

apps/web/src/arcade-games/complement-race/Provider.tsx

@@ -317,6 +317,19 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
   const [clientMomentum, setClientMomentum] = useState(10) // Start at 10 for gentle push
   const [clientPosition, setClientPosition] = useState(0)
   const [clientPressure, setClientPressure] = useState(0)
+  const [clientAIRacers, setClientAIRacers] = useState<
+    Array<{
+      id: string
+      name: string
+      position: number
+      speed: number
+      personality: 'competitive' | 'analytical'
+      icon: string
+      lastComment: number
+      commentCooldown: number
+      previousPosition: number
+    }>
+  >([])
   const lastUpdateRef = useRef(Date.now())
   const gameStartTimeRef = useRef(0)
 
@@ -388,17 +401,7 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
       raceGoal: multiplayerState.config.raceGoal,
       timeLimit: multiplayerState.config.timeLimit ?? null,
       speedMultiplier: 1.0,
-      aiRacers: multiplayerState.aiOpponents.map((ai) => ({
-        id: ai.id,
-        name: ai.name,
-        position: ai.position,
-        speed: ai.speed,
-        personality: ai.personality,
-        icon: ai.personality === 'competitive' ? '🏃‍♂️' : '🏃',
-        lastComment: ai.lastCommentTime,
-        commentCooldown: 0,
-        previousPosition: ai.position,
-      })),
+      aiRacers: clientAIRacers, // Use client-side AI state
 
       // Sprint mode specific (all client-side for smooth movement)
       momentum: clientMomentum, // Client-only state with continuous decay
@@ -425,7 +428,15 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
       adaptiveFeedback: localUIState.adaptiveFeedback,
       difficultyTracker: localUIState.difficultyTracker,
     }
-  }, [multiplayerState, localPlayerId, localUIState, clientPosition, clientPressure])
+  }, [
+    multiplayerState,
+    localPlayerId,
+    localUIState,
+    clientPosition,
+    clientPressure,
+    clientMomentum,
+    clientAIRacers,
+  ])
 
   // Initialize game start time when game becomes active
   useEffect(() => {
@@ -444,6 +455,41 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
     }
   }, [compatibleState.isGameActive, compatibleState.style])
 
+  // Initialize AI racers when game starts
+  useEffect(() => {
+    if (compatibleState.isGameActive && multiplayerState.config.enableAI) {
+      const count = multiplayerState.config.aiOpponentCount
+      if (count > 0 && clientAIRacers.length === 0) {
+        const aiNames = ['Robo-Racer', 'Calculator', 'Speed Demon', 'Brain Bot']
+        const personalities: Array<'competitive' | 'analytical'> = ['competitive', 'analytical']
+
+        const newAI = []
+        for (let i = 0; i < Math.min(count, aiNames.length); i++) {
+          newAI.push({
+            id: `ai-${i}`,
+            name: aiNames[i],
+            personality: personalities[i % personalities.length] as 'competitive' | 'analytical',
+            position: 0,
+            speed: 0.8 + Math.random() * 0.4, // Speed multiplier 0.8-1.2
+            icon: personalities[i % personalities.length] === 'competitive' ? '🏃‍♂️' : '🏃',
+            lastComment: 0,
+            commentCooldown: 0,
+            previousPosition: 0,
+          })
+        }
+        setClientAIRacers(newAI)
+      }
+    } else if (!compatibleState.isGameActive) {
+      // Clear AI when game ends
+      setClientAIRacers([])
+    }
+  }, [
+    compatibleState.isGameActive,
+    multiplayerState.config.enableAI,
+    multiplayerState.config.aiOpponentCount,
+    clientAIRacers.length,
+  ])
+
   // Main client-side game loop: momentum decay and position calculation
   useEffect(() => {
     if (!compatibleState.isGameActive || compatibleState.style !== 'sprint') return
@@ -495,10 +541,13 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
     const currentRoute = multiplayerState.currentRoute
     // When route changes, reset position and give starting momentum
     if (currentRoute > 1 && compatibleState.style === 'sprint') {
+      console.log(
+        `[Provider] Route changed to ${currentRoute}, resetting position. Passengers: ${multiplayerState.passengers.length}`
+      )
       setClientPosition(0)
       setClientMomentum(10) // Reset to starting momentum (gentle push)
     }
-  }, [multiplayerState.currentRoute, compatibleState.style])
+  }, [multiplayerState.currentRoute, compatibleState.style, multiplayerState.passengers.length])
 
   // Keep lastLogRef for future debugging needs
   // (removed debug logging)
@@ -713,6 +762,7 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
         case 'START_NEW_ROUTE':
           // Send route progression to server
           if (action.routeNumber !== undefined) {
+            console.log(`[Provider] Dispatching START_NEW_ROUTE for route ${action.routeNumber}`)
             sendMove({
               type: 'START_NEW_ROUTE',
               playerId: activePlayers[0] || '',
@@ -753,8 +803,27 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
           })
           break
         }
+        case 'UPDATE_AI_POSITIONS': {
+          // Update client-side AI positions
+          if (action.positions && Array.isArray(action.positions)) {
+            setClientAIRacers((prevRacers) =>
+              prevRacers.map((racer) => {
+                const update = action.positions.find(
+                  (p: { id: string; position: number }) => p.id === racer.id
+                )
+                return update
+                  ? {
+                      ...racer,
+                      previousPosition: racer.position,
+                      position: update.position,
+                    }
+                  : racer
+              })
+            )
+          }
+          break
+        }
         // Other local actions that don't affect UI (can be ignored for now)
-        case 'UPDATE_AI_POSITIONS':
         case 'UPDATE_MOMENTUM':
         case 'UPDATE_TRAIN_POSITION':
         case 'UPDATE_STEAM_JOURNEY':

apps/web/src/arcade-games/complement-race/Validator.ts

@@ -218,6 +218,7 @@ export class ComplementRaceValidator
       routeStartTime: state.config.style === 'sprint' ? Date.now() : null,
       raceStartTime: Date.now(), // Race starts immediately
       gameStartTime: Date.now(),
+      aiOpponents: [], // AI handled client-side
     }
 
     return { valid: true, newState }
@@ -812,6 +813,11 @@ export class ComplementRaceValidator
   private checkWinCondition(state: ComplementRaceState): string | null {
     const { config, players } = state
 
+    // Infinite mode: Never end the game
+    if (config.winCondition === 'infinite') {
+      return null
+    }
+
     // Practice mode: First to reach goal
     if (config.style === 'practice') {
       for (const [playerId, player] of Object.entries(players)) {
@@ -819,6 +825,7 @@ export class ComplementRaceValidator
           return playerId
         }
       }
+      // AI wins handled client-side via useAIRacers hook
     }
 
     // Sprint mode: Check route-based, score-based, or time-based win conditions
@@ -870,12 +877,15 @@ export class ComplementRaceValidator
         // Find player with highest position (most laps)
         let maxPosition = 0
         let winner: string | null = null
+
         for (const [playerId, player] of Object.entries(players)) {
           if (player.position > maxPosition) {
             maxPosition = player.position
             winner = playerId
           }
         }
+        // AI wins handled client-side via useAIRacers hook
+
         return winner
       }
     }

apps/web/src/arcade-games/complement-race/index.tsx

@@ -41,7 +41,7 @@ const defaultConfig: ComplementRaceConfig = {
   passengerCount: 6,
   maxConcurrentPassengers: 3,
   raceGoal: 20,
-  winCondition: 'route-based',
+  winCondition: 'infinite', // Sprint mode is infinite by default (Steam Sprint)
   routeCount: 3,
   targetScore: 100,
   timeLimit: 300,

apps/web/src/lib/arcade/game-configs.ts

@@ -89,7 +89,7 @@ export interface ComplementRaceGameConfig {
   raceGoal: number // questions to win practice mode (default 20)
 
   // Win Conditions
-  winCondition: 'route-based' | 'score-based' | 'time-based'
+  winCondition: 'route-based' | 'score-based' | 'time-based' | 'infinite'
   targetScore?: number // for score-based (e.g., 100)
   timeLimit?: number // for time-based (e.g., 300 seconds)
   routeCount?: number // for route-based (e.g., 3 routes)
@@ -171,7 +171,7 @@ export const DEFAULT_COMPLEMENT_RACE_CONFIG: ComplementRaceGameConfig = {
   raceGoal: 20,
 
   // Win conditions
-  winCondition: 'route-based',
+  winCondition: 'infinite', // Sprint mode is infinite by default (Steam Sprint)
   routeCount: 3,
   targetScore: 100,
   timeLimit: 300,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "soroban-monorepo",
-  "version": "4.4.13",
+  "version": "4.6.2",
   "private": true,
   "description": "Beautiful Soroban Flashcard Generator - Monorepo",
   "workspaces": [

packages/core/client/node/package.json

@@ -22,6 +22,7 @@
     "python-shell": "^5.0.0"
   },
   "devDependencies": {
+    "@types/minimatch": "^6.0.0",
     "@types/node": "^20.0.0",
     "tsup": "^7.0.0",
     "typescript": "^5.0.0",

packages/core/client/node/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

packages/core/client/typescript/package.json

@@ -29,6 +29,7 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
+    "@types/minimatch": "^6.0.0",
     "@types/node": "^20.0.0",
     "tsup": "^7.0.0",
     "typescript": "^5.0.0",

packages/core/client/typescript/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

pnpm-lock.yaml

@@ -402,6 +402,9 @@ importers:
         specifier: ^5.0.0
         version: 5.0.0
     devDependencies:
+      '@types/minimatch':
+        specifier: ^6.0.0
+        version: 6.0.0
       '@types/node':
         specifier: ^20.0.0
         version: 20.19.19
@@ -417,6 +420,9 @@ importers:
 
   packages/core/client/typescript:
     devDependencies:
+      '@types/minimatch':
+        specifier: ^6.0.0
+        version: 6.0.0
       '@types/node':
         specifier: ^20.0.0
         version: 20.19.19