chore(release): 4.6.8 [skip ci]

## [4.6.8](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.7...v4.6.8) (2025-10-18)

### Bug Fixes

* **complement-race:** counter-flip AI speech bubbles to make text readable ([07d5607](07d5607218))

CHANGELOG.md

@@ -1,3 +1,59 @@
+## [4.6.8](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.7...v4.6.8) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** counter-flip AI speech bubbles to make text readable ([07d5607](https://github.com/antialias/soroban-abacus-flashcards/commit/07d5607218aee03e813eceff5d161a7838d66bcb))
+
+## [4.6.7](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.6...v4.6.7) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** use active local players pattern from navbar ([71cdc34](https://github.com/antialias/soroban-abacus-flashcards/commit/71cdc342c97ca53b5e7e4202d4d344199e8ddd98))
+
+## [4.6.6](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.5...v4.6.6) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** use local player emoji instead of first active player ([76eb051](https://github.com/antialias/soroban-abacus-flashcards/commit/76eb0517c202d1b9160b49dec0b99ff4972daff2))
+
+## [4.6.5](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.4...v4.6.5) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** flip player avatar to face right in practice mode ([fa6b3b6](https://github.com/antialias/soroban-abacus-flashcards/commit/fa6b3b69d5a4a7eb70f8c18fc8c122c54c4d504a))
+
+## [4.6.4](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.3...v4.6.4) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** flip AI racers to face right in practice mode ([ebfff1a](https://github.com/antialias/soroban-abacus-flashcards/commit/ebfff1a62fd104d531a8158345c8c012ec8a55d3))
+
+## [4.6.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.2...v4.6.3) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** balance AI speeds to match original implementation ([054f0c0](https://github.com/antialias/soroban-abacus-flashcards/commit/054f0c0d235dc2b0042a0f6af48840d23a4c5ff8))
+
+## [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)
 
 

apps/web/src/app/arcade/complement-race/components/RaceTrack/CircularTrack.tsx

@@ -17,15 +17,16 @@ interface CircularTrackProps {
 
 export function CircularTrack({ playerProgress, playerLap, aiRacers, aiLaps }: CircularTrackProps) {
   const { state, dispatch } = useComplementRace()
-  const { players } = useGameMode()
+  const { players, activePlayers } = useGameMode()
   const { profile: _profile } = useUserProfile()
   const { playSound } = useSoundEffects()
   const [celebrationCooldown, setCelebrationCooldown] = useState<Set<string>>(new Set())
 
-  // Get the first active player's emoji
-  const activePlayers = Array.from(players.values()).filter((p) => p.id)
-  const firstActivePlayer = activePlayers[0]
-  const playerEmoji = firstActivePlayer?.emoji ?? '👤'
+  // Get the current user's active local players (consistent with navbar pattern)
+  const activeLocalPlayers = Array.from(activePlayers)
+    .map((id) => players.get(id))
+    .filter((p): p is NonNullable<typeof p> => p !== undefined && p.isLocal !== false)
+  const playerEmoji = activeLocalPlayers[0]?.emoji ?? '👤'
   const [dimensions, setDimensions] = useState({ width: 600, height: 400 })
 
   // Update dimensions on mount and resize

apps/web/src/app/arcade/complement-race/components/RaceTrack/LinearTrack.tsx

@@ -20,13 +20,14 @@ export function LinearTrack({
   showFinishLine = true,
 }: LinearTrackProps) {
   const { state, dispatch } = useComplementRace()
-  const { players } = useGameMode()
+  const { players, activePlayers } = useGameMode()
   const { profile: _profile } = useUserProfile()
 
-  // Get the first active player's emoji
-  const activePlayers = Array.from(players.values()).filter((p) => p.id)
-  const firstActivePlayer = activePlayers[0]
-  const playerEmoji = firstActivePlayer?.emoji ?? '👤'
+  // Get the current user's active local players (consistent with navbar pattern)
+  const activeLocalPlayers = Array.from(activePlayers)
+    .map((id) => players.get(id))
+    .filter((p): p is NonNullable<typeof p> => p !== undefined && p.isLocal !== false)
+  const playerEmoji = activeLocalPlayers[0]?.emoji ?? '👤'
 
   // Position calculation: leftPercent = Math.min(98, (progress / raceGoal) * 96 + 2)
   // 2% minimum (start), 98% maximum (near finish), 96% range for race
@@ -110,7 +111,7 @@ export function LinearTrack({
           position: 'absolute',
           left: `${playerPosition}%`,
           top: '50%',
-          transform: 'translate(-50%, -50%)',
+          transform: 'translate(-50%, -50%) scaleX(-1)',
           fontSize: '32px',
           transition: 'left 0.3s ease-out',
           filter: 'drop-shadow(0 2px 4px rgba(0, 0, 0, 0.2))',
@@ -132,7 +133,7 @@ export function LinearTrack({
               position: 'absolute',
               left: `${aiPosition}%`,
               top: `${35 + index * 15}%`,
-              transform: 'translate(-50%, -50%)',
+              transform: 'translate(-50%, -50%) scaleX(-1)',
               fontSize: '28px',
               transition: 'left 0.2s linear',
               filter: 'drop-shadow(0 2px 4px rgba(0, 0, 0, 0.2))',
@@ -141,10 +142,16 @@ export function LinearTrack({
           >
             {racer.icon}
             {activeBubble && (
-              <SpeechBubble
-                message={activeBubble}
-                onHide={() => dispatch({ type: 'CLEAR_AI_COMMENT', racerId: racer.id })}
-              />
+              <div
+                style={{
+                  transform: 'scaleX(-1)', // Counter-flip bubble to make text readable
+                }}
+              >
+                <SpeechBubble
+                  message={activeBubble}
+                  onHide={() => dispatch({ type: 'CLEAR_AI_COMMENT', racerId: racer.id })}
+                />
+              </div>
             )}
           </div>
         )

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/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)
 
@@ -387,18 +400,13 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
       // Race mechanics
       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,
-      })),
+      speedMultiplier:
+        multiplayerState.config.style === 'practice'
+          ? 0.7
+          : multiplayerState.config.style === 'sprint'
+            ? 0.9
+            : 1.0, // Base speed multipliers by mode
+      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 +433,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 +460,43 @@ 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 = ['Swift AI', 'Math Bot', 'Speed Demon', 'Brain Bot']
+        const personalities: Array<'competitive' | 'analytical'> = ['competitive', 'analytical']
+
+        const newAI = []
+        for (let i = 0; i < Math.min(count, aiNames.length); i++) {
+          // Use original balanced speeds: 0.32 for Swift AI, 0.2 for Math Bot
+          const baseSpeed = i === 0 ? 0.32 : 0.2
+          newAI.push({
+            id: `ai-${i}`,
+            name: aiNames[i],
+            personality: personalities[i % personalities.length] as 'competitive' | 'analytical',
+            position: 0,
+            speed: baseSpeed, // Balanced speed from original single-player version
+            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
@@ -757,8 +810,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

@@ -205,12 +205,6 @@ export class ComplementRaceValidator
       }
     }
 
-    // Generate AI opponents if enabled
-    const aiOpponents =
-      state.config.enableAI && state.config.aiOpponentCount > 0
-        ? this.generateAIOpponents(state.config.aiOpponentCount)
-        : []
-
     const newState: ComplementRaceState = {
       ...state,
       config: updatedConfig,
@@ -224,7 +218,7 @@ export class ComplementRaceValidator
       routeStartTime: state.config.style === 'sprint' ? Date.now() : null,
       raceStartTime: Date.now(), // Race starts immediately
       gameStartTime: Date.now(),
-      aiOpponents,
+      aiOpponents: [], // AI handled client-side
     }
 
     return { valid: true, newState }
@@ -363,15 +357,6 @@ export class ComplementRaceValidator
       },
     }
 
-    // Update AI opponents (make them progress at their speed)
-    if (state.config.enableAI && state.aiOpponents.length > 0) {
-      newState.aiOpponents = this.updateAIOpponents(
-        state.aiOpponents,
-        state.config.style,
-        state.config.raceGoal
-      )
-    }
-
     // Check win conditions
     const winner = this.checkWinCondition(newState)
     if (winner) {
@@ -779,66 +764,6 @@ export class ComplementRaceValidator
     return passengers
   }
 
-  private generateAIOpponents(count: number): Array<{
-    id: string
-    name: string
-    personality: 'competitive' | 'analytical'
-    position: number
-    speed: number
-    lastComment: string | null
-    lastCommentTime: number
-  }> {
-    const aiNames = ['Robo-Racer', 'Calculator', 'Speed Demon', 'Brain Bot']
-    const personalities: Array<'competitive' | 'analytical'> = ['competitive', 'analytical']
-
-    const opponents = []
-    for (let i = 0; i < Math.min(count, aiNames.length); i++) {
-      opponents.push({
-        id: `ai-${i}`,
-        name: aiNames[i],
-        personality: personalities[i % personalities.length],
-        position: 0,
-        speed: 0.8 + Math.random() * 0.4, // Speed multiplier 0.8-1.2
-        lastComment: null,
-        lastCommentTime: 0,
-      })
-    }
-
-    return opponents
-  }
-
-  private updateAIOpponents(
-    opponents: Array<{
-      id: string
-      name: string
-      personality: 'competitive' | 'analytical'
-      position: number
-      speed: number
-      lastComment: string | null
-      lastCommentTime: number
-    }>,
-    gameStyle: 'practice' | 'sprint' | 'survival',
-    raceGoal: number
-  ) {
-    return opponents.map((opponent) => {
-      let newPosition = opponent.position
-
-      if (gameStyle === 'practice') {
-        // AI moves forward based on their speed (simulates answering questions)
-        newPosition = Math.min(100, opponent.position + (100 / raceGoal) * opponent.speed)
-      } else if (gameStyle === 'survival') {
-        // AI always moves forward
-        newPosition = opponent.position + 4 * opponent.speed
-      }
-      // Sprint mode: AI doesn't participate (train journey is single-player focused)
-
-      return {
-        ...opponent,
-        position: newPosition,
-      }
-    })
-  }
-
   /**
    * Calculate the maximum number of passengers that will be on the train
    * concurrently at any given moment during the route
@@ -895,18 +820,12 @@ export class ComplementRaceValidator
 
     // Practice mode: First to reach goal
     if (config.style === 'practice') {
-      // Check human players
       for (const [playerId, player] of Object.entries(players)) {
         if (player.correctAnswers >= config.raceGoal) {
           return playerId
         }
       }
-      // Check AI opponents
-      for (const ai of state.aiOpponents) {
-        if (ai.position >= 100) {
-          return ai.id
-        }
-      }
+      // AI wins handled client-side via useAIRacers hook
     }
 
     // Sprint mode: Check route-based, score-based, or time-based win conditions
@@ -955,25 +874,17 @@ export class ComplementRaceValidator
     if (config.style === 'survival' && config.timeLimit) {
       const elapsed = state.raceStartTime ? (Date.now() - state.raceStartTime) / 1000 : 0
       if (elapsed >= config.timeLimit) {
-        // Find player or AI with highest position (most laps)
+        // Find player with highest position (most laps)
         let maxPosition = 0
         let winner: string | null = null
 
-        // Check human players
         for (const [playerId, player] of Object.entries(players)) {
           if (player.position > maxPosition) {
             maxPosition = player.position
             winner = playerId
           }
         }
-
-        // Check AI opponents
-        for (const ai of state.aiOpponents) {
-          if (ai.position > maxPosition) {
-            maxPosition = ai.position
-            winner = ai.id
-          }
-        }
+        // AI wins handled client-side via useAIRacers hook
 
         return winner
       }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "soroban-monorepo",
-  "version": "4.6.0",
+  "version": "4.6.8",
   "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