chore(release): 4.7.0 [skip ci]

## [4.7.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.10...v4.7.0) (2025-10-18)

### Features

* **complement-race:** enable adaptive AI difficulty in arcade ([55010d2](55010d2bcd))

CHANGELOG.md

@@ -1,3 +1,150 @@
+## [4.7.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.10...v4.7.0) (2025-10-18)
+
+
+### Features
+
+* **complement-race:** enable adaptive AI difficulty in arcade ([55010d2](https://github.com/antialias/soroban-abacus-flashcards/commit/55010d2bcd953718d8fea428b1f7f613a193779c))
+
+## [4.6.10](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.9...v4.6.10) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** improve AI speech bubble positioning ([6e436db](https://github.com/antialias/soroban-abacus-flashcards/commit/6e436db5e709d944ebffed6936ea1f8e4bd2e19e))
+* **docker:** remove reference to deleted @soroban/client package ([2953ef8](https://github.com/antialias/soroban-abacus-flashcards/commit/2953ef8917f7b13f6eb562eb7d58d14179a718da))
+
+## [4.6.9](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.6.8...v4.6.9) (2025-10-18)
+
+
+### Bug Fixes
+
+* **complement-race:** add missing AI commentary cooldown updates ([357aa30](https://github.com/antialias/soroban-abacus-flashcards/commit/357aa30618f80d659ae515f94b7b9254bb458910))
+
+
+### Code Refactoring
+
+* remove dead Python bridge and unused packages ([22426f6](https://github.com/antialias/soroban-abacus-flashcards/commit/22426f677f9b127441377b95571f0066a0990d3f))
+
+## [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)
+
+
+### 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)
+
+
+### Bug Fixes
+
+* **complement-race:** show new passengers when route changes ([ec1c8ed](https://github.com/antialias/soroban-abacus-flashcards/commit/ec1c8ed263844f56477c1f709041339b42b48f4e))
+
+## [4.4.12](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.11...v4.4.12) (2025-10-17)
+
+
+### Bug Fixes
+
+* **complement-race:** track physical car indices to prevent boarding issues ([53bbae8](https://github.com/antialias/soroban-abacus-flashcards/commit/53bbae84af7317d5e12109db2054cc70ca5bea27))
+* **complement-race:** update passenger display when state changes ([5116364](https://github.com/antialias/soroban-abacus-flashcards/commit/511636400c19776b58c6bddf8f7c9cc398a05236))
+
+## [4.4.11](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.10...v4.4.11) (2025-10-17)
+
+
+### Code Refactoring
+
+* **logging:** replace per-frame debug logging with event-based logging ([fedb324](https://github.com/antialias/soroban-abacus-flashcards/commit/fedb32486ab5c6c619ebc03570b6c66529a1344e))
+
+## [4.4.10](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.9...v4.4.10) (2025-10-17)
+
+
+### Bug Fixes
+
+* **complement-race:** correct passenger boarding to use multiplayer fields ([7ed1b94](https://github.com/antialias/soroban-abacus-flashcards/commit/7ed1b94b8fa620cb4f64ba43e160ef511704f3ce))
+
+## [4.4.9](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.8...v4.4.9) (2025-10-17)
+
+
+### Bug Fixes
+
+* **complement-race:** reduce initial momentum from 50 to 10 to prevent train sailing past first station ([5f146b0](https://github.com/antialias/soroban-abacus-flashcards/commit/5f146b0daf74d54e1c7b9a57d3a2f37e73849ff2))
+
 ## [4.4.8](https://github.com/antialias/soroban-abacus-flashcards/compare/v4.4.7...v4.4.8) (2025-10-17)
 
 

Dockerfile

@@ -13,7 +13,6 @@ WORKDIR /app
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
 COPY apps/web/package.json ./apps/web/
 COPY packages/core/client/node/package.json ./packages/core/client/node/
-COPY packages/core/client/typescript/package.json ./packages/core/client/typescript/
 COPY packages/abacus-react/package.json ./packages/abacus-react/
 COPY packages/templates/package.json ./packages/templates/
 

apps/web/.claude/settings.local.json

@@ -92,7 +92,9 @@
       "Bash(ls:*)",
       "Bash(do if [ -f \"$file\" ])",
       "Bash(! echo \"$file\")",
-      "Bash(then sed -i '' \"s|from ''''../context/ComplementRaceContext''''|from ''''@/arcade-games/complement-race/Provider''''|g\" \"$file\" sed -i '' \"s|from ''''../../context/ComplementRaceContext''''|from ''''@/arcade-games/complement-race/Provider''''|g\" \"$file\" fi done)"
+      "Bash(then sed -i '' \"s|from ''''../context/ComplementRaceContext''''|from ''''@/arcade-games/complement-race/Provider''''|g\" \"$file\" sed -i '' \"s|from ''''../../context/ComplementRaceContext''''|from ''''@/arcade-games/complement-race/Provider''''|g\" \"$file\" fi done)",
+      "Bash(pnpm install)",
+      "Bash(pnpm exec turbo build --filter=@soroban/web)"
     ],
     "deny": [],
     "ask": []

apps/web/package.json

@@ -48,7 +48,6 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@react-spring/web": "^10.0.2",
     "@soroban/abacus-react": "workspace:*",
-    "@soroban/client": "workspace:*",
     "@soroban/core": "workspace:*",
     "@soroban/templates": "workspace:*",
     "@tanstack/react-form": "^0.19.0",

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

@@ -1,7 +1,7 @@
 'use client'
 
 import { memo } from 'react'
-import type { Passenger, Station } from '../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 
 interface PassengerCardProps {
   passenger: Passenger
@@ -17,24 +17,27 @@ export const PassengerCard = memo(function PassengerCard({
   if (!destinationStation || !originStation) return null
 
   // Vintage train station colors
-  const bgColor = passenger.isDelivered
+  // Arcade room multiplayer uses claimedBy/deliveredBy instead of isBoarded/isDelivered
+  const isBoarded = passenger.claimedBy !== null
+  const isDelivered = passenger.deliveredBy !== null
+
+  const bgColor = isDelivered
     ? '#1a3a1a' // Dark green for delivered
-    : !passenger.isBoarded
+    : !isBoarded
       ? '#2a2419' // Dark brown/sepia for waiting
       : passenger.isUrgent
         ? '#3a2419' // Dark red-brown for urgent
         : '#1a2a3a' // Dark blue for aboard
 
-  const accentColor = passenger.isDelivered
+  const accentColor = isDelivered
     ? '#4ade80' // Green
-    : !passenger.isBoarded
+    : !isBoarded
       ? '#d4af37' // Gold for waiting
       : passenger.isUrgent
         ? '#ff6b35' // Orange-red for urgent
         : '#60a5fa' // Blue for aboard
 
-  const borderColor =
-    passenger.isUrgent && passenger.isBoarded && !passenger.isDelivered ? '#ff6b35' : '#d4af37'
+  const borderColor = passenger.isUrgent && isBoarded && !isDelivered ? '#ff6b35' : '#d4af37'
 
   return (
     <div
@@ -46,13 +49,13 @@ export const PassengerCard = memo(function PassengerCard({
         minWidth: '220px',
         maxWidth: '280px',
         boxShadow:
-          passenger.isUrgent && !passenger.isDelivered && passenger.isBoarded
+          passenger.isUrgent && !isDelivered && isBoarded
             ? '0 0 16px rgba(255, 107, 53, 0.5)'
             : '0 4px 12px rgba(0, 0, 0, 0.4)',
         position: 'relative',
         fontFamily: '"Courier New", Courier, monospace',
         animation:
-          passenger.isUrgent && !passenger.isDelivered && passenger.isBoarded
+          passenger.isUrgent && !isDelivered && isBoarded
             ? 'urgentFlicker 1.5s ease-in-out infinite'
             : 'none',
         transition: 'all 0.3s ease',
@@ -79,7 +82,7 @@ export const PassengerCard = memo(function PassengerCard({
           }}
         >
           <div style={{ fontSize: '20px', lineHeight: '1' }}>
-            {passenger.isDelivered ? '✅' : passenger.avatar}
+            {isDelivered ? '✅' : passenger.avatar}
           </div>
           <div
             style={{
@@ -109,7 +112,7 @@ export const PassengerCard = memo(function PassengerCard({
             marginTop: '0',
           }}
         >
-          {passenger.isDelivered ? 'DLVRD' : passenger.isBoarded ? 'BOARD' : 'WAIT'}
+          {isDelivered ? 'DLVRD' : isBoarded ? 'BOARD' : 'WAIT'}
         </div>
       </div>
 
@@ -187,7 +190,7 @@ export const PassengerCard = memo(function PassengerCard({
       </div>
 
       {/* Points badge */}
-      {!passenger.isDelivered && (
+      {!isDelivered && (
         <div
           style={{
             position: 'absolute',
@@ -208,7 +211,7 @@ export const PassengerCard = memo(function PassengerCard({
       )}
 
       {/* Urgent indicator */}
-      {passenger.isUrgent && !passenger.isDelivered && passenger.isBoarded && (
+      {passenger.isUrgent && !isDelivered && isBoarded && (
         <div
           style={{
             position: 'absolute',

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
@@ -400,7 +401,11 @@ export function CircularTrack({ playerProgress, playerLap, aiRacers, aiLaps }: C
             {activeBubble && (
               <div
                 style={{
-                  transform: `rotate(${-aiPos.angle}deg)`, // Counter-rotate bubble
+                  position: 'absolute',
+                  bottom: '100%', // Position above the AI racer
+                  left: '50%',
+                  transform: `translate(-50%, -15px) rotate(${-aiPos.angle}deg)`, // Offset 15px above, counter-rotate bubble
+                  zIndex: 20, // Above player (10) and AI racers (5)
                 }}
               >
                 <SpeechBubble

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

@@ -1,7 +1,8 @@
 'use client'
 
 import { memo } from 'react'
-import type { ComplementQuestion, Passenger, Station } from '../../lib/gameTypes'
+import type { ComplementQuestion } from '../../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 import { AbacusTarget } from '../AbacusTarget'
 import { PassengerCard } from '../PassengerCard'
 import { PressureGauge } from '../PressureGauge'

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,20 @@ export function LinearTrack({
           >
             {racer.icon}
             {activeBubble && (
-              <SpeechBubble
-                message={activeBubble}
-                onHide={() => dispatch({ type: 'CLEAR_AI_COMMENT', racerId: racer.id })}
-              />
+              <div
+                style={{
+                  position: 'absolute',
+                  bottom: '100%', // Position above the AI racer
+                  left: '50%',
+                  transform: 'translate(-50%, -15px) scaleX(-1)', // Offset 15px above, counter-flip bubble
+                  zIndex: 20, // Above player (10) and AI racers (5)
+                }}
+              >
+                <SpeechBubble
+                  message={activeBubble}
+                  onHide={() => dispatch({ type: 'CLEAR_AI_COMMENT', racerId: racer.id })}
+                />
+              </div>
             )}
           </div>
         )

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

@@ -1,7 +1,7 @@
 'use client'
 
 import { memo } from 'react'
-import type { Passenger, Station } from '../../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 import type { Landmark } from '../../lib/landmarks'
 
 interface RailroadTrackPathProps {
@@ -100,18 +100,19 @@ export const RailroadTrackPath = memo(
         {stationPositions.map((pos, index) => {
           const station = stations[index]
           // Find passengers waiting at this station (exclude currently boarding)
+          // Arcade room multiplayer uses claimedBy/deliveredBy instead of isBoarded/isDelivered
           const waitingPassengers = passengers.filter(
             (p) =>
               p.originStationId === station?.id &&
-              !p.isBoarded &&
-              !p.isDelivered &&
+              p.claimedBy === null &&
+              p.deliveredBy === null &&
               !boardingAnimations.has(p.id)
           )
           // Find passengers delivered at this station (exclude currently disembarking)
           const deliveredPassengers = passengers.filter(
             (p) =>
               p.destinationStationId === station?.id &&
-              p.isDelivered &&
+              p.deliveredBy !== null &&
               !disembarkingAnimations.has(p.id)
           )
 

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

@@ -14,7 +14,6 @@ import type { ComplementQuestion } from '../../lib/gameTypes'
 import { useSteamJourney } from '../../hooks/useSteamJourney'
 import { useTrackManagement } from '../../hooks/useTrackManagement'
 import { useTrainTransforms } from '../../hooks/useTrainTransforms'
-import { calculateMaxConcurrentPassengers } from '../../lib/passengerGenerator'
 import { RailroadTrackGenerator } from '../../lib/RailroadTrackGenerator'
 import { getRouteTheme } from '../../lib/routeThemes'
 import { GameHUD } from './GameHUD'
@@ -94,9 +93,6 @@ export function SteamTrainJourney({
   currentInput,
 }: SteamTrainJourneyProps) {
   const { state } = useComplementRace()
-  console.log(
-    `🚂 Train: mom=${momentum} pos=${trainPosition} stations=${state.stations.length} passengers=${state.passengers.length}`
-  )
 
   const { getSkyGradient, getTimeOfDayPeriod } = useSteamJourney()
   const _skyGradient = getSkyGradient()
@@ -113,12 +109,9 @@ export function SteamTrainJourney({
   const pathRef = useRef<SVGPathElement>(null)
   const [trackGenerator] = useState(() => new RailroadTrackGenerator(800, 600))
 
-  // Calculate the number of train cars dynamically based on max concurrent passengers
-  const maxCars = useMemo(() => {
-    const maxPassengers = calculateMaxConcurrentPassengers(state.passengers, state.stations)
-    // Ensure at least 1 car, even if no passengers
-    return Math.max(1, maxPassengers)
-  }, [state.passengers, state.stations])
+  // Use server's authoritative maxConcurrentPassengers calculation
+  // This ensures visual display matches game logic and console logs
+  const maxCars = Math.max(1, state.maxConcurrentPassengers || 3)
 
   const carSpacing = 7 // Distance between cars (in % of track)
 
@@ -170,13 +163,14 @@ export function SteamTrainJourney({
   const routeTheme = getRouteTheme(state.currentRoute)
 
   // Memoize filtered passenger lists to avoid recalculating on every render
+  // Arcade room multiplayer uses claimedBy/deliveredBy instead of isBoarded/isDelivered
   const boardedPassengers = useMemo(
-    () => displayPassengers.filter((p) => p.isBoarded && !p.isDelivered),
+    () => displayPassengers.filter((p) => p.claimedBy !== null && p.deliveredBy === null),
     [displayPassengers]
   )
 
   const nonDeliveredPassengers = useMemo(
-    () => displayPassengers.filter((p) => !p.isDelivered),
+    () => displayPassengers.filter((p) => p.deliveredBy === null),
     [displayPassengers]
   )
 

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

@@ -2,7 +2,7 @@
 
 import { memo } from 'react'
 import type { BoardingAnimation, DisembarkingAnimation } from '../../hooks/usePassengerAnimations'
-import type { Passenger } from '../../lib/gameTypes'
+import type { Passenger } from '@/arcade-games/complement-race/types'
 
 interface TrainCarTransform {
   x: number

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

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/react'
 import { describe, expect, test, vi } from 'vitest'
-import type { Passenger, Station } from '../../../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 import { GameHUD } from '../GameHUD'
 
 // Mock child components
@@ -33,9 +33,11 @@ describe('GameHUD', () => {
     avatar: '👨',
     originStationId: 'station-1',
     destinationStationId: 'station-2',
-    isBoarded: false,
-    isDelivered: false,
     isUrgent: false,
+    claimedBy: null,
+    deliveredBy: null,
+    carIndex: null,
+    timestamp: Date.now(),
   }
 
   const defaultProps = {

apps/web/src/app/arcade/complement-race/hooks/__tests__/useTrackManagement.passenger-display.test.ts

@@ -1,6 +1,6 @@
 import { renderHook } from '@testing-library/react'
 import { beforeEach, describe, expect, test, vi } from 'vitest'
-import type { Passenger, Station } from '../../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 import type { RailroadTrackGenerator } from '../../lib/RailroadTrackGenerator'
 import { useTrackManagement } from '../useTrackManagement'
 
@@ -47,7 +47,7 @@ describe('useTrackManagement - Passenger Display', () => {
       { id: 'station3', name: 'Station 3', icon: '🏪', emoji: '🏪', position: 80 },
     ]
 
-    // Mock passengers - initial set
+    // Mock passengers - initial set (multiplayer format)
     mockPassengers = [
       {
         id: 'p1',
@@ -55,9 +55,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👩',
         originStationId: 'station1',
         destinationStationId: 'station2',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
       {
         id: 'p2',
@@ -65,9 +67,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👨',
         originStationId: 'station2',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -111,18 +115,18 @@ describe('useTrackManagement - Passenger Display', () => {
 
     // Initially 2 passengers
     expect(result.current.displayPassengers).toHaveLength(2)
-    expect(result.current.displayPassengers[0].isBoarded).toBe(false)
+    expect(result.current.displayPassengers[0].claimedBy).toBe(null)
 
     // Board first passenger
     const boardedPassengers = mockPassengers.map((p) =>
-      p.id === 'p1' ? { ...p, isBoarded: true } : p
+      p.id === 'p1' ? { ...p, claimedBy: 'player1', carIndex: 0 } : p
     )
 
     rerender({ passengers: boardedPassengers, position: 25 })
 
     // Should show updated passengers
     expect(result.current.displayPassengers).toHaveLength(2)
-    expect(result.current.displayPassengers[0].isBoarded).toBe(true)
+    expect(result.current.displayPassengers[0].claimedBy).toBe('player1')
   })
 
   test('passengers do NOT update during route transition (train moving)', () => {
@@ -153,9 +157,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👴',
         originStationId: 'station1',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -196,9 +202,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👴',
         originStationId: 'station1',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -239,9 +247,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👴',
         originStationId: 'station1',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -316,18 +326,18 @@ describe('useTrackManagement - Passenger Display', () => {
 
     // Initially 2 passengers, neither delivered
     expect(result.current.displayPassengers).toHaveLength(2)
-    expect(result.current.displayPassengers[0].isDelivered).toBe(false)
+    expect(result.current.displayPassengers[0].deliveredBy).toBe(null)
 
     // Deliver first passenger
     const deliveredPassengers = mockPassengers.map((p) =>
-      p.id === 'p1' ? { ...p, isBoarded: true, isDelivered: true } : p
+      p.id === 'p1' ? { ...p, claimedBy: 'player1', carIndex: 0, deliveredBy: 'player1' } : p
     )
 
     rerender({ passengers: deliveredPassengers, position: 55 })
 
     // Should show updated passengers immediately
     expect(result.current.displayPassengers).toHaveLength(2)
-    expect(result.current.displayPassengers[0].isDelivered).toBe(true)
+    expect(result.current.displayPassengers[0].deliveredBy).toBe('player1')
   })
 
   test('multiple rapid passenger updates during same route', () => {
@@ -350,25 +360,27 @@ describe('useTrackManagement - Passenger Display', () => {
     expect(result.current.displayPassengers).toHaveLength(2)
 
     // Board p1
-    let updated = mockPassengers.map((p) => (p.id === 'p1' ? { ...p, isBoarded: true } : p))
+    let updated = mockPassengers.map((p) =>
+      p.id === 'p1' ? { ...p, claimedBy: 'player1', carIndex: 0 } : p
+    )
     rerender({ passengers: updated, position: 26 })
-    expect(result.current.displayPassengers[0].isBoarded).toBe(true)
+    expect(result.current.displayPassengers[0].claimedBy).toBe('player1')
 
     // Board p2
-    updated = updated.map((p) => (p.id === 'p2' ? { ...p, isBoarded: true } : p))
+    updated = updated.map((p) => (p.id === 'p2' ? { ...p, claimedBy: 'player1', carIndex: 1 } : p))
     rerender({ passengers: updated, position: 52 })
-    expect(result.current.displayPassengers[1].isBoarded).toBe(true)
+    expect(result.current.displayPassengers[1].claimedBy).toBe('player1')
 
     // Deliver p1
-    updated = updated.map((p) => (p.id === 'p1' ? { ...p, isDelivered: true } : p))
+    updated = updated.map((p) => (p.id === 'p1' ? { ...p, deliveredBy: 'player1' } : p))
     rerender({ passengers: updated, position: 53 })
-    expect(result.current.displayPassengers[0].isDelivered).toBe(true)
+    expect(result.current.displayPassengers[0].deliveredBy).toBe('player1')
 
     // All updates should have been reflected
-    expect(result.current.displayPassengers[0].isBoarded).toBe(true)
-    expect(result.current.displayPassengers[0].isDelivered).toBe(true)
-    expect(result.current.displayPassengers[1].isBoarded).toBe(true)
-    expect(result.current.displayPassengers[1].isDelivered).toBe(false)
+    expect(result.current.displayPassengers[0].claimedBy).toBe('player1')
+    expect(result.current.displayPassengers[0].deliveredBy).toBe('player1')
+    expect(result.current.displayPassengers[1].claimedBy).toBe('player1')
+    expect(result.current.displayPassengers[1].deliveredBy).toBe(null)
   })
 
   test('EDGE CASE: new passengers at position 0 with old route', () => {
@@ -402,9 +414,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👴',
         originStationId: 'station1',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -445,9 +459,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👴',
         originStationId: 'station1',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -483,9 +499,11 @@ describe('useTrackManagement - Passenger Display', () => {
         avatar: '👴',
         originStationId: 'station1',
         destinationStationId: 'station3',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 

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

@@ -1,6 +1,6 @@
 import { renderHook } from '@testing-library/react'
 import { beforeEach, describe, expect, test, vi } from 'vitest'
-import type { Passenger, Station } from '../../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 import type { RailroadTrackGenerator } from '../../lib/RailroadTrackGenerator'
 import { useTrackManagement } from '../useTrackManagement'
 
@@ -60,9 +60,11 @@ describe('useTrackManagement', () => {
         avatar: '👨',
         originStationId: 'station-1',
         destinationStationId: 'station-2',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -155,6 +157,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 
@@ -174,6 +178,8 @@ describe('useTrackManagement', () => {
           pathRef: mockPathRef,
           stations: mockStations,
           passengers: mockPassengers,
+          maxCars: 3,
+          carSpacing: 7,
         }),
       {
         initialProps: { route: 1, position: 0 },
@@ -200,6 +206,8 @@ describe('useTrackManagement', () => {
           pathRef: mockPathRef,
           stations: mockStations,
           passengers: mockPassengers,
+          maxCars: 3,
+          carSpacing: 7,
         }),
       {
         initialProps: { route: 1, position: 0 },
@@ -227,6 +235,8 @@ describe('useTrackManagement', () => {
           pathRef: mockPathRef,
           stations: mockStations,
           passengers: mockPassengers,
+          maxCars: 3,
+          carSpacing: 7,
         }),
       {
         initialProps: { route: 1, position: -5 },
@@ -250,9 +260,11 @@ describe('useTrackManagement', () => {
         avatar: '👩',
         originStationId: 'station-1',
         destinationStationId: 'station-2',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -287,12 +299,15 @@ describe('useTrackManagement', () => {
     const newPassengers: Passenger[] = [
       {
         id: 'passenger-2',
+        name: 'Passenger 2',
         avatar: '👩',
         originStationId: 'station-1',
         destinationStationId: 'station-2',
-        isBoarded: false,
-        isDelivered: false,
         isUrgent: false,
+        claimedBy: null,
+        deliveredBy: null,
+        carIndex: null,
+        timestamp: Date.now(),
       },
     ]
 
@@ -328,7 +343,9 @@ describe('useTrackManagement', () => {
   })
 
   test('updates passengers immediately during same route', () => {
-    const updatedPassengers: Passenger[] = [{ ...mockPassengers[0], isBoarded: true }]
+    const updatedPassengers: Passenger[] = [
+      { ...mockPassengers[0], claimedBy: 'player1', carIndex: 0 },
+    ]
 
     const { result, rerender } = renderHook(
       ({ passengers, position }) =>
@@ -368,6 +385,8 @@ describe('useTrackManagement', () => {
         pathRef: mockPathRef,
         stations: mockStations,
         passengers: mockPassengers,
+        maxCars: 3,
+        carSpacing: 7,
       })
     )
 

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

@@ -1,6 +1,5 @@
 import { useEffect, useRef } from 'react'
 import { useComplementRace } from '@/arcade-games/complement-race/Provider'
-import { calculateMaxConcurrentPassengers, generatePassengers } from '../lib/passengerGenerator'
 import { useSoundEffects } from './useSoundEffects'
 
 /**
@@ -44,26 +43,44 @@ export function useSteamJourney() {
   const gameStartTimeRef = useRef<number>(0)
   const lastUpdateRef = useRef<number>(0)
   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 and generate initial passengers
+  // Initialize game start time
   useEffect(() => {
     if (state.isGameActive && state.style === 'sprint' && gameStartTimeRef.current === 0) {
       gameStartTimeRef.current = Date.now()
       lastUpdateRef.current = Date.now()
-
-      // Generate initial passengers if none exist
-      if (state.passengers.length === 0) {
-        const newPassengers = generatePassengers(state.stations)
-        dispatch({ type: 'GENERATE_PASSENGERS', passengers: newPassengers })
-
-        // Calculate and store exit threshold for this route
-        const CAR_SPACING = 7
-        const maxPassengers = calculateMaxConcurrentPassengers(newPassengers, state.stations)
-        const maxCars = Math.max(1, maxPassengers)
-        routeExitThresholdRef.current = 100 + maxCars * CAR_SPACING
-      }
     }
-  }, [state.isGameActive, state.style, state.stations, state.passengers.length, dispatch])
+  }, [state.isGameActive, state.style, state.stations, state.passengers])
+
+  // Calculate exit threshold when route changes or config updates
+  useEffect(() => {
+    if (state.passengers.length > 0 && state.stations.length > 0) {
+      const CAR_SPACING = 7
+      // Use server-calculated maxConcurrentPassengers
+      const maxCars = Math.max(1, state.maxConcurrentPassengers || 3)
+      routeExitThresholdRef.current = 100 + maxCars * CAR_SPACING
+    }
+  }, [state.currentRoute, state.passengers, state.stations, state.maxConcurrentPassengers])
+
+  // Clean up pendingBoardingRef when passengers are claimed/delivered or route changes
+  useEffect(() => {
+    // Remove passengers from pending set if they've been claimed or delivered
+    state.passengers.forEach((passenger) => {
+      if (passenger.claimedBy !== null || passenger.deliveredBy !== null) {
+        pendingBoardingRef.current.delete(passenger.id)
+      }
+    })
+  }, [state.passengers])
+
+  // Clear all pending boarding requests when route changes
+  useEffect(() => {
+    pendingBoardingRef.current.clear()
+    missedPassengersRef.current.clear()
+    previousTrainPositionRef.current = 0 // Reset previous position for new route
+  }, [state.currentRoute])
 
   // Momentum decay and position update loop
   useEffect(() => {
@@ -77,116 +94,48 @@ 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
       const CAR_SPACING = 7 // Must match SteamTrainJourney component
-      const maxPassengers = calculateMaxConcurrentPassengers(state.passengers, state.stations)
-      const maxCars = Math.max(1, maxPassengers)
-      const currentBoardedPassengers = state.passengers.filter((p) => p.isBoarded && !p.isDelivered)
+      // Use server-calculated maxConcurrentPassengers (updates per route based on passenger layout)
+      const maxCars = Math.max(1, state.maxConcurrentPassengers || 3)
 
-      // Debug logging flag - enable when debugging passenger boarding issues
-      // TO ENABLE: Change this to true, save, and the logs will appear in the browser console
-      // When you see passengers getting left behind, copy the entire console log and paste into Claude Code
-      const DEBUG_PASSENGER_BOARDING = false
-
-      if (DEBUG_PASSENGER_BOARDING) {
-        console.log('\n'.repeat(3))
-        console.log('='.repeat(80))
-        console.log('🚂 PASSENGER BOARDING DEBUG LOG')
-        console.log('='.repeat(80))
-        console.log('ISSUE: Passengers are getting left behind at stations')
-        console.log('PURPOSE: This log captures all state during boarding/delivery logic')
-        console.log('USAGE: Copy this entire log and paste into Claude Code for debugging')
-        console.log('='.repeat(80))
-        console.log('\n📊 CURRENT FRAME STATE:')
-        console.log(`  Train Position: ${trainPosition.toFixed(2)}`)
-        console.log(`  Speed: ${speed.toFixed(2)}% per second`)
-        console.log(`  Momentum: ${newMomentum.toFixed(2)}`)
-        console.log(`  Max Cars: ${maxCars}`)
-        console.log(`  Car Spacing: ${CAR_SPACING}`)
-        console.log(`  Distance Tolerance: 5`)
-
-        console.log('\n🚉 STATIONS:')
-        state.stations.forEach((station) => {
-          console.log(`  ${station.emoji} ${station.name} (ID: ${station.id})`)
-          console.log(`    Position: ${station.position}`)
-        })
-
-        console.log('\n👥 ALL PASSENGERS:')
-        state.passengers.forEach((p, idx) => {
-          const origin = state.stations.find((s) => s.id === p.originStationId)
-          const dest = state.stations.find((s) => s.id === p.destinationStationId)
-          console.log(`  [${idx}] ${p.name} (ID: ${p.id})`)
+      // Debug: Log train configuration at start (only once per route)
+      if (trainPosition < 1 && state.passengers.length > 0) {
+        const lastLoggedRoute = (window as any).__lastLoggedRoute || 0
+        if (lastLoggedRoute !== state.currentRoute) {
           console.log(
-            `    Status: ${p.isDelivered ? 'DELIVERED' : p.isBoarded ? 'BOARDED' : 'WAITING'}`
+            `\n🚆 ROUTE ${state.currentRoute} START - Train has ${maxCars} cars (server maxConcurrentPassengers: ${state.maxConcurrentPassengers}) for ${state.passengers.length} passengers`
           )
-          console.log(
-            `    Route: ${origin?.emoji} ${origin?.name} (pos ${origin?.position}) → ${dest?.emoji} ${dest?.name} (pos ${dest?.position})`
-          )
-          console.log(`    Urgent: ${p.isUrgent}`)
-        })
-
-        console.log('\n🚃 CAR POSITIONS:')
-        for (let i = 0; i < maxCars; i++) {
-          const carPos = Math.max(0, trainPosition - (i + 1) * CAR_SPACING)
-          console.log(`  Car ${i}: position ${carPos.toFixed(2)}`)
+          state.passengers.forEach((p) => {
+            const origin = state.stations.find((s) => s.id === p.originStationId)
+            const dest = state.stations.find((s) => s.id === p.destinationStationId)
+            console.log(
+              `  📍 ${p.name}: ${origin?.emoji} ${origin?.name} (${origin?.position}) → ${dest?.emoji} ${dest?.name} (${dest?.position}) ${p.isUrgent ? '⚡' : ''}`
+            )
+          })
+          console.log('') // Blank line for readability
+          ;(window as any).__lastLoggedRoute = state.currentRoute
         }
-
-        console.log('\n🔍 CURRENTLY BOARDED PASSENGERS:')
-        currentBoardedPassengers.forEach((p, carIndex) => {
-          const carPos = Math.max(0, trainPosition - (carIndex + 1) * CAR_SPACING)
-          const dest = state.stations.find((s) => s.id === p.destinationStationId)
-          const distToDest = Math.abs(carPos - (dest?.position || 0))
-          console.log(`  Car ${carIndex}: ${p.name}`)
-          console.log(`    Car position: ${carPos.toFixed(2)}`)
-          console.log(`    Destination: ${dest?.emoji} ${dest?.name} (pos ${dest?.position})`)
-          console.log(`    Distance to dest: ${distToDest.toFixed(2)}`)
-          console.log(`    Will deliver: ${distToDest < 5 ? 'YES' : 'NO'}`)
-        })
       }
+      const currentBoardedPassengers = state.passengers.filter(
+        (p) => p.claimedBy !== null && p.deliveredBy === null
+      )
 
       // FIRST: Identify which passengers will be delivered in this frame
       const passengersToDeliver = new Set<string>()
-      currentBoardedPassengers.forEach((passenger, carIndex) => {
-        if (!passenger || passenger.isDelivered) return
+      currentBoardedPassengers.forEach((passenger) => {
+        if (!passenger || passenger.deliveredBy !== null || passenger.carIndex === null) return
 
         const station = state.stations.find((s) => s.id === passenger.destinationStationId)
         if (!station) return
 
-        // Calculate this passenger's car position
-        const carPosition = Math.max(0, trainPosition - (carIndex + 1) * CAR_SPACING)
+        // Calculate this passenger's car position using PHYSICAL carIndex
+        const carPosition = Math.max(0, trainPosition - (passenger.carIndex + 1) * CAR_SPACING)
         const distance = Math.abs(carPosition - station.position)
 
         // If this car is at the destination station (within 5% tolerance), mark for delivery
@@ -195,159 +144,161 @@ export function useSteamJourney() {
         }
       })
 
-      // Build a map of which cars are occupied (excluding passengers being delivered this frame)
+      // Build a map of which cars are occupied (using PHYSICAL car index, not array index!)
+      // This is critical: passenger.carIndex stores the physical car (0-N) they're seated in
       const occupiedCars = new Map<number, (typeof currentBoardedPassengers)[0]>()
-      currentBoardedPassengers.forEach((passenger, arrayIndex) => {
+      currentBoardedPassengers.forEach((passenger) => {
         // Don't count a car as occupied if its passenger is being delivered this frame
-        if (!passengersToDeliver.has(passenger.id)) {
-          occupiedCars.set(arrayIndex, passenger)
+        if (!passengersToDeliver.has(passenger.id) && passenger.carIndex !== null) {
+          occupiedCars.set(passenger.carIndex, passenger) // Use physical carIndex, NOT array index!
         }
       })
 
-      if (DEBUG_PASSENGER_BOARDING) {
-        console.log('\n📦 PASSENGERS TO DELIVER THIS FRAME:')
-        if (passengersToDeliver.size === 0) {
-          console.log('  None')
-        } else {
-          passengersToDeliver.forEach((id) => {
-            const p = state.passengers.find((passenger) => passenger.id === id)
-            console.log(`  - ${p?.name} (ID: ${id})`)
-          })
-        }
-
-        console.log('\n🚗 OCCUPIED CARS (after excluding deliveries):')
-        if (occupiedCars.size === 0) {
-          console.log('  All cars are empty')
-        } else {
-          occupiedCars.forEach((passenger, carIndex) => {
-            console.log(`  Car ${carIndex}: ${passenger.name}`)
-          })
-        }
-
-        console.log('\n🔄 BOARDING ATTEMPTS:')
-      }
-
-      // Track which cars are assigned in THIS frame to prevent double-boarding
-      const carsAssignedThisFrame = new Set<number>()
-
-      // Find waiting passengers whose origin station has an empty car nearby
-      state.passengers.forEach((passenger) => {
-        if (passenger.isBoarded || passenger.isDelivered) return
-
-        const station = state.stations.find((s) => s.id === passenger.originStationId)
-        if (!station) return
-
-        if (DEBUG_PASSENGER_BOARDING) {
-          console.log(
-            `\n  Passenger: ${passenger.name} waiting at ${station.emoji} ${station.name} (pos ${station.position})`
-          )
-        }
-
-        // Check if any empty car is at this station
-        // Cars are at positions: trainPosition - 7, trainPosition - 14, etc.
-        let boarded = false
-        for (let carIndex = 0; carIndex < maxCars; carIndex++) {
-          const carPosition = Math.max(0, trainPosition - (carIndex + 1) * CAR_SPACING)
-          const distance = Math.abs(carPosition - station.position)
-
-          if (DEBUG_PASSENGER_BOARDING) {
-            const isOccupied = occupiedCars.has(carIndex)
-            const isAssigned = carsAssignedThisFrame.has(carIndex)
-            const inRange = distance < 5
-            const occupant = occupiedCars.get(carIndex)
-
-            console.log(`    Car ${carIndex} @ pos ${carPosition.toFixed(2)}:`)
-            console.log(`      Distance to station: ${distance.toFixed(2)}`)
-            console.log(`      In range (<5): ${inRange}`)
-            console.log(
-              `      Occupied: ${isOccupied}${isOccupied ? ` (by ${occupant?.name})` : ''}`
-            )
-            console.log(`      Assigned this frame: ${isAssigned}`)
-            console.log(`      Can board: ${!isOccupied && !isAssigned && inRange}`)
-          }
-
-          // Skip if this car already has a passenger OR was assigned this frame
-          if (occupiedCars.has(carIndex) || carsAssignedThisFrame.has(carIndex)) continue
-
-          const distance2 = Math.abs(carPosition - station.position)
-
-          // If car is at or near station (within 5% tolerance for fast trains), board this passenger
-          // Increased tolerance to ensure fast-moving trains don't miss passengers
-          if (distance2 < 5) {
-            if (DEBUG_PASSENGER_BOARDING) {
-              console.log(`    ✅ BOARDING ${passenger.name} onto Car ${carIndex}`)
-            }
-            dispatch({
-              type: 'BOARD_PASSENGER',
-              passengerId: passenger.id,
-            })
-            // Mark this car as assigned in this frame
-            carsAssignedThisFrame.add(carIndex)
-            boarded = true
-            return // Board this passenger and move on
-          }
-        }
-
-        if (DEBUG_PASSENGER_BOARDING && !boarded) {
-          console.log(`    ❌ ${passenger.name} NOT BOARDED - no suitable car found`)
-        }
-      })
-
-      if (DEBUG_PASSENGER_BOARDING) {
-        console.log('\n🎯 DELIVERY ATTEMPTS:')
-      }
-
-      // Check for deliverable passengers
-      // Passengers disembark when THEIR car reaches their destination
-      currentBoardedPassengers.forEach((passenger, carIndex) => {
-        if (!passenger || passenger.isDelivered) return
+      // PRIORITY 1: Process deliveries FIRST (dispatch DELIVER moves before BOARD moves)
+      // This ensures the server frees up cars before processing new boarding requests
+      currentBoardedPassengers.forEach((passenger) => {
+        if (!passenger || passenger.deliveredBy !== null || passenger.carIndex === null) return
 
         const station = state.stations.find((s) => s.id === passenger.destinationStationId)
         if (!station) return
 
-        // Calculate this passenger's car position
-        const carPosition = Math.max(0, trainPosition - (carIndex + 1) * CAR_SPACING)
+        // Calculate this passenger's car position using PHYSICAL carIndex
+        const carPosition = Math.max(0, trainPosition - (passenger.carIndex + 1) * CAR_SPACING)
         const distance = Math.abs(carPosition - station.position)
 
         // If this car is at the destination station (within 5% tolerance), deliver
         if (distance < 5) {
-          if (DEBUG_PASSENGER_BOARDING) {
-            console.log(
-              `  ✅ DELIVERING ${passenger.name} from Car ${carIndex} to ${station.emoji} ${station.name}`
-            )
-            console.log(
-              `    Car position: ${carPosition.toFixed(2)}, Station: ${station.position}, Distance: ${distance.toFixed(2)}`
-            )
-          }
           const points = passenger.isUrgent ? 20 : 10
+          console.log(
+            `🎯 DELIVERY: ${passenger.name} delivered from Car ${passenger.carIndex} to ${station.emoji} ${station.name} (+${points} pts) (trainPos=${trainPosition.toFixed(1)}, carPos=${carPosition.toFixed(1)}, stationPos=${station.position})`
+          )
           dispatch({
             type: 'DELIVER_PASSENGER',
             passengerId: passenger.id,
             points,
           })
-        } else if (DEBUG_PASSENGER_BOARDING) {
+        }
+      })
+
+      // Debug: Log car states periodically at stations
+      const isAtStation = state.stations.some((s) => Math.abs(trainPosition - s.position) < 3)
+      if (isAtStation && Math.floor(trainPosition) !== Math.floor(state.trainPosition)) {
+        const nearStation = state.stations.find((s) => Math.abs(trainPosition - s.position) < 3)
+        console.log(
+          `\n🚃 Train arriving at ${nearStation?.emoji} ${nearStation?.name} (trainPos=${trainPosition.toFixed(1)}) - ${maxCars} cars total:`
+        )
+        for (let i = 0; i < maxCars; i++) {
+          const carPos = Math.max(0, trainPosition - (i + 1) * CAR_SPACING)
+          const occupant = occupiedCars.get(i)
+          if (occupant) {
+            const dest = state.stations.find((s) => s.id === occupant.destinationStationId)
+            console.log(
+              `  Car ${i}: @ ${carPos.toFixed(1)}% - ${occupant.name} → ${dest?.emoji} ${dest?.name}`
+            )
+          } else {
+            console.log(`  Car ${i}: @ ${carPos.toFixed(1)}% - EMPTY`)
+          }
+        }
+      }
+
+      // Track which cars are assigned in THIS frame to prevent double-boarding
+      const carsAssignedThisFrame = new Set<number>()
+      // Track which passengers are assigned in THIS frame to prevent same passenger boarding multiple cars
+      const passengersAssignedThisFrame = new Set<string>()
+
+      // PRIORITY 2: Process boardings AFTER deliveries
+
+      // Find waiting passengers whose origin station has an empty car nearby
+      state.passengers.forEach((passenger) => {
+        // Skip if already claimed or delivered (optimistic update marks immediately)
+        if (passenger.claimedBy !== null || passenger.deliveredBy !== null) return
+
+        // Skip if already assigned in this frame OR has a pending boarding request from previous frames
+        if (
+          passengersAssignedThisFrame.has(passenger.id) ||
+          pendingBoardingRef.current.has(passenger.id)
+        )
+          return
+
+        const station = state.stations.find((s) => s.id === passenger.originStationId)
+        if (!station) return
+
+        // Don't allow boarding if locomotive has passed too far beyond this station
+        // Station stays open until the LAST car has passed (accounting for train length)
+        const STATION_CLOSURE_BUFFER = 10 // Extra buffer beyond the last car
+        const lastCarOffset = maxCars * CAR_SPACING // Distance from locomotive to last car
+        const stationClosureThreshold = lastCarOffset + STATION_CLOSURE_BUFFER
+
+        if (trainPosition > station.position + stationClosureThreshold) {
           console.log(
-            `  ⏳ ${passenger.name} in Car ${carIndex} heading to ${station.emoji} ${station.name}`
+            `❌ MISSED: ${passenger.name} at ${station.emoji} ${station.name} - train too far past (trainPos=${trainPosition.toFixed(1)}, station=${station.position}, threshold=${stationClosureThreshold})`
           )
+          return
+        }
+
+        // Check if any empty car is at this station
+        // Cars are at positions: trainPosition - 7, trainPosition - 14, etc.
+        let closestCarDistance = 999
+        let closestCarReason = ''
+
+        for (let carIndex = 0; carIndex < maxCars; carIndex++) {
+          const carPosition = Math.max(0, trainPosition - (carIndex + 1) * CAR_SPACING)
+          const distance = Math.abs(carPosition - station.position)
+
+          if (distance < closestCarDistance) {
+            closestCarDistance = distance
+            if (occupiedCars.has(carIndex)) {
+              const occupant = occupiedCars.get(carIndex)
+              closestCarReason = `Car ${carIndex} occupied by ${occupant?.name}`
+            } else if (carsAssignedThisFrame.has(carIndex)) {
+              closestCarReason = `Car ${carIndex} just assigned`
+            } else if (distance >= 5) {
+              closestCarReason = `Car ${carIndex} too far (dist=${distance.toFixed(1)})`
+            } else {
+              closestCarReason = 'available'
+            }
+          }
+
+          // Skip if this car already has a passenger OR was assigned this frame
+          if (occupiedCars.has(carIndex) || carsAssignedThisFrame.has(carIndex)) continue
+
+          // If car is at or near station (within 5% tolerance for fast trains), board this passenger
+          if (distance < 5) {
+            console.log(
+              `🚂 BOARDING: ${passenger.name} boarding Car ${carIndex} at ${station.emoji} ${station.name} (trainPos=${trainPosition.toFixed(1)}, carPos=${carPosition.toFixed(1)}, stationPos=${station.position})`
+            )
+
+            // Mark as pending BEFORE dispatch to prevent duplicate boarding attempts across frames
+            pendingBoardingRef.current.add(passenger.id)
+
+            dispatch({
+              type: 'BOARD_PASSENGER',
+              passengerId: passenger.id,
+              carIndex, // Pass physical car index to server
+            })
+            // Mark this car and passenger as assigned in this frame
+            carsAssignedThisFrame.add(carIndex)
+            passengersAssignedThisFrame.add(passenger.id)
+            return // Board this passenger and move on
+          }
+        }
+
+        // If we get here, passenger wasn't boarded - log why
+        if (closestCarDistance < 10) {
+          // Only log if train is somewhat near
           console.log(
-            `    Car position: ${carPosition.toFixed(2)}, Station: ${station.position}, Distance: ${distance.toFixed(2)}`
+            `⏸️  WAITING: ${passenger.name} at ${station.emoji} ${station.name} - ${closestCarReason} (trainPos=${trainPosition.toFixed(1)}, maxCars=${maxCars})`
           )
         }
       })
 
-      if (DEBUG_PASSENGER_BOARDING) {
-        console.log(`\n${'='.repeat(80)}`)
-        console.log('END OF DEBUG LOG')
-        console.log('='.repeat(80))
-      }
-
       // Check for route completion (entire train exits tunnel)
-      // Use stored threshold (stable for entire route)
       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)
@@ -357,52 +308,24 @@ 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,
           stations: state.stations,
         })
 
-        // Generate new passengers
-        const newPassengers = generatePassengers(state.stations)
-        dispatch({ type: 'GENERATE_PASSENGERS', passengers: newPassengers })
-
-        // Calculate and store new exit threshold for next route
-        const newMaxPassengers = calculateMaxConcurrentPassengers(newPassengers, state.stations)
-        const newMaxCars = Math.max(1, newMaxPassengers)
-        routeExitThresholdRef.current = 100 + newMaxCars * CAR_SPACING
+        // 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)
-  }, [
-    state.isGameActive,
-    state.style,
-    state.momentum,
-    state.trainPosition,
-    state.timeoutSetting,
-    state.passengers,
-    state.stations,
-    state.currentRoute,
-    dispatch,
-    playSound,
-  ])
-
-  // Auto-regenerate passengers when all are delivered
-  useEffect(() => {
-    if (!state.isGameActive || state.style !== 'sprint') return
-
-    // Check if all passengers are delivered
-    const allDelivered = state.passengers.length > 0 && state.passengers.every((p) => p.isDelivered)
-
-    if (allDelivered) {
-      // Generate new passengers after a short delay
-      setTimeout(() => {
-        const newPassengers = generatePassengers(state.stations)
-        dispatch({ type: 'GENERATE_PASSENGERS', passengers: newPassengers })
-      }, 1000)
-    }
-  }, [state.isGameActive, state.style, state.passengers, state.stations, dispatch])
+  }, [state.isGameActive, state.style, state.timeoutSetting, dispatch, playSound])
 
   // Add momentum on correct answer
   useEffect(() => {

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

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import type { Passenger, Station } from '../lib/gameTypes'
+import type { Passenger, Station } from '@/arcade-games/complement-race/types'
 import { generateLandmarks, type Landmark } from '../lib/landmarks'
 import type { RailroadTrackGenerator } from '../lib/RailroadTrackGenerator'
 
@@ -67,7 +67,7 @@ export function useTrackManagement({
 
   // Apply pending track when train resets to beginning
   useEffect(() => {
-    if (pendingTrackData && trainPosition < 0) {
+    if (pendingTrackData && trainPosition <= 0) {
       setTrackData(pendingTrackData)
       previousRouteRef.current = currentRoute
       setPendingTrackData(null)
@@ -77,22 +77,34 @@ export function useTrackManagement({
   // Manage passenger display during route transitions
   useEffect(() => {
     // Only switch to new passengers when:
-    // 1. Train has reset to start position (< 0) - track has changed, OR
-    // 2. Same route AND train is in middle of track (10-90%) - gameplay updates like boarding/delivering
-    const trainReset = trainPosition < 0
+    // 1. Train has reset to start position (<= 0) - track has changed, OR
+    // 2. Same route AND (in middle of track OR passengers have changed state)
+    const trainReset = trainPosition <= 0
     const sameRoute = currentRoute === displayRouteRef.current
     const inMiddleOfTrack = trainPosition >= 10 && trainPosition < 90 // Avoid start/end transition zones
 
+    // Detect if passenger states have changed (boarding or delivery)
+    // This allows updates even when train is past 90% threshold
+    const passengerStatesChanged =
+      sameRoute &&
+      passengers.some((p) => {
+        const oldPassenger = displayPassengers.find((dp) => dp.id === p.id)
+        return (
+          oldPassenger &&
+          (oldPassenger.claimedBy !== p.claimedBy || oldPassenger.deliveredBy !== p.deliveredBy)
+        )
+      })
+
     if (trainReset) {
       // Train reset - update to new route's passengers
       setDisplayPassengers(passengers)
       displayRouteRef.current = currentRoute
-    } else if (sameRoute && inMiddleOfTrack) {
-      // Same route and train in middle of track - update passengers for gameplay changes (boarding/delivery)
+    } else if (sameRoute && (inMiddleOfTrack || passengerStatesChanged)) {
+      // Same route and either in middle of track OR passenger states changed - update for gameplay
       setDisplayPassengers(passengers)
     }
     // Otherwise, keep displaying old passengers until train resets
-  }, [passengers, trainPosition, currentRoute])
+  }, [passengers, displayPassengers, trainPosition, currentRoute])
 
   // Generate ties and rails when path is ready
   useEffect(() => {

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

@@ -38,6 +38,7 @@ interface CompatibleGameState {
   style: string
   timeoutSetting: string
   complementDisplay: string
+  maxConcurrentPassengers: number
 
   // Current question (extracted from currentQuestions[localPlayerId])
   currentQuestion: any | null
@@ -102,7 +103,7 @@ interface ComplementRaceContextValue {
   lastError: string | null
   startGame: () => void
   submitAnswer: (answer: number, responseTime: number) => void
-  claimPassenger: (passengerId: string) => void
+  claimPassenger: (passengerId: string, carIndex: number) => void
   deliverPassenger: (passengerId: string) => void
   nextQuestion: () => void
   endGame: () => void
@@ -129,12 +130,71 @@ export function useComplementRace() {
 
 /**
  * Optimistic move application (client-side prediction)
- * For now, just return current state - server will validate and send back authoritative state
+ * Apply moves immediately on client for responsive UI, server will confirm or reject
  */
 function applyMoveOptimistically(state: ComplementRaceState, move: GameMove): ComplementRaceState {
-  // Simple optimistic updates can be added here later
-  // For now, rely on server validation
-  return state
+  const typedMove = move as ComplementRaceMove
+
+  switch (typedMove.type) {
+    case 'CLAIM_PASSENGER': {
+      // Optimistically mark passenger as claimed and assign to car
+      const passengerId = typedMove.data.passengerId
+      const carIndex = typedMove.data.carIndex
+      const updatedPassengers = state.passengers.map((p) =>
+        p.id === passengerId ? { ...p, claimedBy: typedMove.playerId, carIndex } : p
+      )
+
+      // Optimistically add to player's passenger list
+      const updatedPlayers = { ...state.players }
+      const player = updatedPlayers[typedMove.playerId]
+      if (player) {
+        updatedPlayers[typedMove.playerId] = {
+          ...player,
+          passengers: [...player.passengers, passengerId],
+        }
+      }
+
+      return {
+        ...state,
+        passengers: updatedPassengers,
+        players: updatedPlayers,
+      }
+    }
+
+    case 'DELIVER_PASSENGER': {
+      // Optimistically mark passenger as delivered and award points
+      const passengerId = typedMove.data.passengerId
+      const passenger = state.passengers.find((p) => p.id === passengerId)
+      if (!passenger) return state
+
+      const points = passenger.isUrgent ? 20 : 10
+      const updatedPassengers = state.passengers.map((p) =>
+        p.id === passengerId ? { ...p, deliveredBy: typedMove.playerId } : p
+      )
+
+      // Optimistically remove from player's passenger list and update score
+      const updatedPlayers = { ...state.players }
+      const player = updatedPlayers[typedMove.playerId]
+      if (player) {
+        updatedPlayers[typedMove.playerId] = {
+          ...player,
+          passengers: player.passengers.filter((id) => id !== passengerId),
+          deliveredPassengers: player.deliveredPassengers + 1,
+          score: player.score + points,
+        }
+      }
+
+      return {
+        ...state,
+        passengers: updatedPassengers,
+        players: updatedPlayers,
+      }
+    }
+
+    default:
+      // For other moves, rely on server validation
+      return state
+  }
 }
 
 /**
@@ -254,9 +314,22 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
   const lastLogRef = useState({ key: '', count: 0 })[0]
 
   // Client-side game state (NOT synced to server - purely visual/gameplay)
-  const [clientMomentum, setClientMomentum] = useState(50) // Start at 50
+  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)
 
@@ -300,6 +373,7 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
       style: multiplayerState.config.style,
       timeoutSetting: multiplayerState.config.timeoutSetting,
       complementDisplay: multiplayerState.config.complementDisplay,
+      maxConcurrentPassengers: multiplayerState.config.maxConcurrentPassengers,
 
       // Current question
       currentQuestion: localPlayerId
@@ -326,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
@@ -364,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(() => {
@@ -373,9 +450,9 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
         gameStartTimeRef.current = Date.now()
         lastUpdateRef.current = Date.now()
         // Reset client state for new game
-        setClientMomentum(50)
+        setClientMomentum(10) // Start with gentle push
         setClientPosition(0)
-        setClientPressure((50 / 100) * 150) // Initial pressure from starting momentum
+        setClientPressure((10 / 100) * 150) // Initial pressure from starting momentum
       }
     } else {
       // Reset when game ends
@@ -383,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
@@ -434,33 +548,16 @@ 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(50) // Reset to starting momentum
+      setClientMomentum(10) // Reset to starting momentum (gentle push)
     }
-  }, [multiplayerState.currentRoute, compatibleState.style])
+  }, [multiplayerState.currentRoute, compatibleState.style, multiplayerState.passengers.length])
 
-  // Debug logging: only log on answer submission or significant events
-  useEffect(() => {
-    if (compatibleState.style === 'sprint' && compatibleState.isGameActive) {
-      const key = `${compatibleState.correctAnswers}`
-
-      // Only log on new answers (not every frame)
-      if (lastLogRef.key !== key) {
-        console.log(
-          `🚂 Answer #${compatibleState.correctAnswers}: momentum=${compatibleState.momentum} pos=${Math.floor(compatibleState.trainPosition)} pressure=${compatibleState.pressure} streak=${compatibleState.streak}`
-        )
-        lastLogRef.key = key
-      }
-    }
-  }, [
-    compatibleState.correctAnswers,
-    compatibleState.momentum,
-    compatibleState.trainPosition,
-    compatibleState.pressure,
-    compatibleState.streak,
-    compatibleState.style,
-    compatibleState.isGameActive,
-  ])
+  // Keep lastLogRef for future debugging needs
+  // (removed debug logging)
 
   // Action creators
   const startGame = useCallback(() => {
@@ -506,7 +603,7 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
   )
 
   const claimPassenger = useCallback(
-    (passengerId: string) => {
+    (passengerId: string, carIndex: number) => {
       const currentPlayerId = activePlayers.find((id) => {
         const player = players.get(id)
         return player?.isLocal
@@ -518,7 +615,7 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
         type: 'CLAIM_PASSENGER',
         playerId: currentPlayerId,
         userId: viewerId || '',
-        data: { passengerId },
+        data: { passengerId, carIndex },
       } as ComplementRaceMove)
     },
     [activePlayers, players, viewerId, sendMove]
@@ -660,8 +757,8 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
           break
         case 'BOARD_PASSENGER':
         case 'CLAIM_PASSENGER':
-          if (action.passengerId !== undefined) {
-            claimPassenger(action.passengerId)
+          if (action.passengerId !== undefined && action.carIndex !== undefined) {
+            claimPassenger(action.passengerId, action.carIndex)
           }
           break
         case 'DELIVER_PASSENGER':
@@ -669,6 +766,18 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
             deliverPassenger(action.passengerId)
           }
           break
+        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] || '',
+              userId: viewerId || '',
+              data: { routeNumber: action.routeNumber },
+            } as ComplementRaceMove)
+          }
+          break
         // Local UI state actions
         case 'UPDATE_INPUT':
           setLocalUIState((prev) => ({ ...prev, currentInput: action.input || '' }))
@@ -691,6 +800,18 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
             newBubbles.set(action.racerId, action.message)
             return { ...prev, activeSpeechBubbles: newBubbles }
           })
+          // Update racer's lastComment time and cooldown to prevent spam
+          setClientAIRacers((prevRacers) =>
+            prevRacers.map((racer) =>
+              racer.id === action.racerId
+                ? {
+                    ...racer,
+                    lastComment: Date.now(),
+                    commentCooldown: Math.random() * 4000 + 2000, // 2-6 seconds
+                  }
+                : racer
+            )
+          )
           break
         }
         case 'CLEAR_AI_COMMENT': {
@@ -701,15 +822,55 @@ 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
+        }
+        case 'UPDATE_AI_SPEEDS': {
+          // Update client-side AI speeds (adaptive difficulty)
+          if (action.racers && Array.isArray(action.racers)) {
+            setClientAIRacers((prevRacers) =>
+              prevRacers.map((racer) => {
+                const update = action.racers.find(
+                  (r: { id: string; speed: number }) => r.id === racer.id
+                )
+                return update
+                  ? {
+                      ...racer,
+                      speed: update.speed,
+                    }
+                  : racer
+              })
+            )
+          }
+          break
+        }
+        case 'UPDATE_DIFFICULTY_TRACKER': {
+          // Update local difficulty tracker state
+          setLocalUIState((prev) => ({ ...prev, difficultyTracker: action.tracker }))
+          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':
-        case 'UPDATE_DIFFICULTY_TRACKER':
-        case 'UPDATE_AI_SPEEDS':
-        case 'GENERATE_PASSENGERS':
-        case 'START_NEW_ROUTE':
+        case 'GENERATE_PASSENGERS': // Passengers generated server-side when route starts
         case 'COMPLETE_ROUTE':
         case 'HIDE_ROUTE_CELEBRATION':
         case 'COMPLETE_LAP':
@@ -729,6 +890,9 @@ export function ComplementRaceProvider({ children }: { children: ReactNode }) {
       claimPassenger,
       deliverPassenger,
       multiplayerState.questionStartTime,
+      sendMove,
+      activePlayers,
+      viewerId,
     ]
   )
 

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

@@ -76,12 +76,6 @@ export class ComplementRaceValidator
   implements GameValidator<ComplementRaceState, ComplementRaceMove>
 {
   validateMove(state: ComplementRaceState, move: ComplementRaceMove): ValidationResult {
-    console.log('[ComplementRace] Validating move:', {
-      type: move.type,
-      playerId: move.playerId,
-      gamePhase: state.gamePhase,
-    })
-
     switch (move.type) {
       case 'START_GAME':
         return this.validateStartGame(state, move.data.activePlayers, move.data.playerMetadata)
@@ -104,7 +98,12 @@ export class ComplementRaceValidator
         return this.validateUpdateInput(state, move.playerId, move.data.input)
 
       case 'CLAIM_PASSENGER':
-        return this.validateClaimPassenger(state, move.playerId, move.data.passengerId)
+        return this.validateClaimPassenger(
+          state,
+          move.playerId,
+          move.data.passengerId,
+          move.data.carIndex
+        )
 
       case 'DELIVER_PASSENGER':
         return this.validateDeliverPassenger(state, move.playerId, move.data.passengerId)
@@ -190,8 +189,25 @@ export class ComplementRaceValidator
         ? this.generatePassengers(state.config.passengerCount, state.stations)
         : []
 
+    // Calculate maxConcurrentPassengers based on initial passenger layout (sprint mode only)
+    let updatedConfig = state.config
+    if (state.config.style === 'sprint' && passengers.length > 0) {
+      const maxConcurrentPassengers = Math.max(
+        1,
+        this.calculateMaxConcurrentPassengers(passengers, state.stations)
+      )
+      console.log(
+        `[Game Start] Calculated maxConcurrentPassengers: ${maxConcurrentPassengers} for ${passengers.length} passengers`
+      )
+      updatedConfig = {
+        ...state.config,
+        maxConcurrentPassengers,
+      }
+    }
+
     const newState: ComplementRaceState = {
       ...state,
+      config: updatedConfig,
       gamePhase: 'playing', // Go directly to playing (countdown can be added later)
       activePlayers,
       playerMetadata: playerMetadata as typeof state.playerMetadata,
@@ -202,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 }
@@ -387,7 +404,8 @@ export class ComplementRaceValidator
   private validateClaimPassenger(
     state: ComplementRaceState,
     playerId: string,
-    passengerId: string
+    passengerId: string,
+    carIndex: number
   ): ValidationResult {
     if (state.config.style !== 'sprint') {
       return { valid: false, error: 'Passengers only available in sprint mode' }
@@ -414,22 +432,27 @@ export class ComplementRaceValidator
       return { valid: false, error: 'Passenger already claimed' }
     }
 
-    // Check if player is at the origin station (within 5% tolerance)
-    const originStation = state.stations.find((s) => s.id === passenger.originStationId)
-    if (!originStation) {
-      return { valid: false, error: 'Origin station not found' }
+    // Sprint mode: Position is client-side, trust client's spatial checking
+    // (Client checks position in useSteamJourney before sending CLAIM move)
+    // Other modes: Validate position server-side
+    if (state.config.style !== 'sprint') {
+      const originStation = state.stations.find((s) => s.id === passenger.originStationId)
+      if (!originStation) {
+        return { valid: false, error: 'Origin station not found' }
+      }
+
+      const distance = Math.abs(player.position - originStation.position)
+      if (distance > 5) {
+        return { valid: false, error: 'Not at origin station' }
+      }
     }
 
-    const distance = Math.abs(player.position - originStation.position)
-    if (distance > 5) {
-      return { valid: false, error: 'Not at origin station' }
-    }
-
-    // Claim passenger
+    // Claim passenger and assign to physical car
     const updatedPassengers = [...state.passengers]
     updatedPassengers[passengerIndex] = {
       ...passenger,
       claimedBy: playerId,
+      carIndex, // Store which physical car (0-N) the passenger is seated in
     }
 
     const newState: ComplementRaceState = {
@@ -477,15 +500,19 @@ export class ComplementRaceValidator
       return { valid: false, error: 'Passenger already delivered' }
     }
 
-    // Check if player is at destination station (within 5% tolerance)
-    const destStation = state.stations.find((s) => s.id === passenger.destinationStationId)
-    if (!destStation) {
-      return { valid: false, error: 'Destination station not found' }
-    }
+    // Sprint mode: Position is client-side, trust client's spatial checking
+    // (Client checks position in useSteamJourney before sending DELIVER move)
+    // Other modes: Validate position server-side
+    if (state.config.style !== 'sprint') {
+      const destStation = state.stations.find((s) => s.id === passenger.destinationStationId)
+      if (!destStation) {
+        return { valid: false, error: 'Destination station not found' }
+      }
 
-    const distance = Math.abs(player.position - destStation.position)
-    if (distance > 5) {
-      return { valid: false, error: 'Not at destination station' }
+      const distance = Math.abs(player.position - destStation.position)
+      if (distance > 5) {
+        return { valid: false, error: 'Not at destination station' }
+      }
     }
 
     // Deliver passenger and award points
@@ -531,12 +558,26 @@ export class ComplementRaceValidator
     // Generate new passengers
     const newPassengers = this.generatePassengers(state.config.passengerCount, state.stations)
 
+    // Calculate maxConcurrentPassengers based on the new route's passenger layout
+    const maxConcurrentPassengers = Math.max(
+      1,
+      this.calculateMaxConcurrentPassengers(newPassengers, state.stations)
+    )
+
+    console.log(
+      `[Route ${routeNumber}] Calculated maxConcurrentPassengers: ${maxConcurrentPassengers} for ${newPassengers.length} passengers`
+    )
+
     const newState: ComplementRaceState = {
       ...state,
       currentRoute: routeNumber,
       routeStartTime: Date.now(),
       players: resetPlayers,
       passengers: newPassengers,
+      config: {
+        ...state.config,
+        maxConcurrentPassengers, // Update config with calculated value
+      },
     }
 
     return { valid: true, newState }
@@ -657,37 +698,126 @@ export class ComplementRaceValidator
 
   private generatePassengers(count: number, stations: Station[]): Passenger[] {
     const passengers: Passenger[] = []
+    const usedCombos = new Set<string>()
 
     for (let i = 0; i < count; i++) {
-      // Pick random origin and destination (must be different)
-      const originIndex = Math.floor(Math.random() * stations.length)
-      let destIndex = Math.floor(Math.random() * stations.length)
-      while (destIndex === originIndex) {
-        destIndex = Math.floor(Math.random() * stations.length)
+      let name: string
+      let avatar: string
+      let comboKey: string
+
+      // Keep trying until we get a unique name/avatar combo
+      do {
+        const nameIndex = Math.floor(Math.random() * PASSENGER_NAMES.length)
+        const avatarIndex = Math.floor(Math.random() * PASSENGER_AVATARS.length)
+        name = PASSENGER_NAMES[nameIndex]
+        avatar = PASSENGER_AVATARS[avatarIndex]
+        comboKey = `${name}-${avatar}`
+      } while (usedCombos.has(comboKey) && usedCombos.size < 100) // Prevent infinite loop
+
+      usedCombos.add(comboKey)
+
+      // Pick origin and destination stations
+      // KEY: Destination must be AHEAD of origin (higher position on track)
+      // This ensures passengers travel forward, creating better overlap
+      let originStation: Station
+      let destinationStation: Station
+
+      if (Math.random() < 0.4 || stations.length < 3) {
+        // 40% chance to start at depot (first station)
+        originStation = stations[0]
+        // Pick any station ahead as destination
+        const stationsAhead = stations.slice(1)
+        destinationStation = stationsAhead[Math.floor(Math.random() * stationsAhead.length)]
+      } else {
+        // Start at a random non-depot, non-final station
+        const nonDepotStations = stations.slice(1, -1) // Exclude depot and final station
+        originStation = nonDepotStations[Math.floor(Math.random() * nonDepotStations.length)]
+        // Pick a station ahead of origin (higher position)
+        const stationsAhead = stations.filter((s) => s.position > originStation.position)
+        destinationStation = stationsAhead[Math.floor(Math.random() * stationsAhead.length)]
       }
 
-      const nameIndex = Math.floor(Math.random() * PASSENGER_NAMES.length)
-      const avatarIndex = Math.floor(Math.random() * PASSENGER_AVATARS.length)
+      // 30% chance of urgent
+      const isUrgent = Math.random() < 0.3
 
-      passengers.push({
+      const passenger = {
         id: `p-${Date.now()}-${i}-${Math.random().toString(36).substr(2, 9)}`,
-        name: PASSENGER_NAMES[nameIndex],
-        avatar: PASSENGER_AVATARS[avatarIndex],
-        originStationId: stations[originIndex].id,
-        destinationStationId: stations[destIndex].id,
-        isUrgent: Math.random() < 0.3, // 30% chance of urgent
+        name,
+        avatar,
+        originStationId: originStation.id,
+        destinationStationId: destinationStation.id,
+        isUrgent,
         claimedBy: null,
         deliveredBy: null,
+        carIndex: null, // Not boarded yet
         timestamp: Date.now(),
-      })
+      }
+
+      passengers.push(passenger)
+
+      console.log(
+        `[Passenger ${i + 1}/${count}] ${name} waiting at ${originStation.emoji} ${originStation.name} (pos ${originStation.position}) → ${destinationStation.emoji} ${destinationStation.name} (pos ${destinationStation.position}) ${isUrgent ? '⚡ URGENT' : ''}`
+      )
     }
 
+    console.log(`[Generated ${passengers.length} passengers total]`)
     return passengers
   }
 
+  /**
+   * Calculate the maximum number of passengers that will be on the train
+   * concurrently at any given moment during the route
+   */
+  private calculateMaxConcurrentPassengers(passengers: Passenger[], stations: Station[]): number {
+    // Create events for boarding and delivery
+    interface StationEvent {
+      position: number
+      isBoarding: boolean // true = board, false = delivery
+    }
+
+    const events: StationEvent[] = []
+
+    for (const passenger of passengers) {
+      const originStation = stations.find((s) => s.id === passenger.originStationId)
+      const destStation = stations.find((s) => s.id === passenger.destinationStationId)
+
+      if (originStation && destStation) {
+        events.push({ position: originStation.position, isBoarding: true })
+        events.push({ position: destStation.position, isBoarding: false })
+      }
+    }
+
+    // Sort events by position, with deliveries before boardings at the same position
+    events.sort((a, b) => {
+      if (a.position !== b.position) return a.position - b.position
+      // At same position, deliveries happen before boarding
+      return a.isBoarding ? 1 : -1
+    })
+
+    // Track current passenger count and maximum
+    let currentCount = 0
+    let maxCount = 0
+
+    for (const event of events) {
+      if (event.isBoarding) {
+        currentCount++
+        maxCount = Math.max(maxCount, currentCount)
+      } else {
+        currentCount--
+      }
+    }
+
+    return maxCount
+  }
+
   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)) {
@@ -695,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
@@ -746,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/arcade-games/complement-race/types.ts

@@ -41,6 +41,7 @@ export interface Passenger {
   isUrgent: boolean // Urgent passengers worth 2x points
   claimedBy: string | null // playerId who picked up this passenger (null = unclaimed)
   deliveredBy: string | null // playerId who delivered (null = not delivered yet)
+  carIndex: number | null // Physical car index (0-N) where passenger is seated (null = not boarded)
   timestamp: number // When passenger spawned
 }
 
@@ -142,7 +143,7 @@ export type ComplementRaceMove = BaseGameMove &
     // Playing phase
     | { type: 'SUBMIT_ANSWER'; data: { answer: number; responseTime: number } }
     | { type: 'UPDATE_INPUT'; data: { input: string } } // Show "thinking" indicator
-    | { type: 'CLAIM_PASSENGER'; data: { passengerId: string } } // Sprint mode: pickup
+    | { type: 'CLAIM_PASSENGER'; data: { passengerId: string; carIndex: number } } // Sprint mode: pickup
     | { type: 'DELIVER_PASSENGER'; data: { passengerId: string } } // Sprint mode: delivery
 
     // Game flow

apps/web/src/hooks/useArcadeSession.ts

@@ -107,32 +107,28 @@ export function useArcadeSession<TState>(
     exitSession: socketExitSession,
   } = useArcadeSocket({
     onSessionState: (data) => {
-      console.log('[ArcadeSession] Syncing with server state')
       optimistic.syncWithServer(data.gameState as TState, data.version)
     },
 
     onMoveAccepted: (data) => {
-      console.log('[ArcadeSession] Move accepted by server')
       optimistic.handleMoveAccepted(data.gameState as TState, data.version, data.move)
     },
 
     onMoveRejected: (data) => {
-      console.log('[ArcadeSession] Move rejected by server:', data.error)
+      console.log(`[ArcadeSession] Move rejected: ${data.error}`)
       optimistic.handleMoveRejected(data.error, data.move)
     },
 
     onSessionEnded: () => {
-      console.log('[ArcadeSession] Session ended')
       optimistic.reset()
     },
 
     onNoActiveSession: () => {
-      console.log('[ArcadeSession] No active session found')
+      // Silent - normal state
     },
 
     onError: (data) => {
-      console.error('[ArcadeSession] Error:', data.error)
-      // Users can handle errors via the onMoveRejected callback
+      console.error(`[ArcadeSession] Error: ${data.error}`)
     },
   })
 

apps/web/src/hooks/useArcadeSocket.ts

@@ -62,22 +62,19 @@ export function useArcadeSocket(events: ArcadeSocketEvents = {}): UseArcadeSocke
     })
 
     socketInstance.on('session-state', (data) => {
-      console.log('[ArcadeSocket] Received session state', data)
       eventsRef.current.onSessionState?.(data)
     })
 
     socketInstance.on('no-active-session', () => {
-      console.log('[ArcadeSocket] No active session')
       eventsRef.current.onNoActiveSession?.()
     })
 
     socketInstance.on('move-accepted', (data) => {
-      console.log('[ArcadeSocket] Move accepted', data)
       eventsRef.current.onMoveAccepted?.(data)
     })
 
     socketInstance.on('move-rejected', (data) => {
-      console.log('[ArcadeSocket] Move rejected', data)
+      console.log(`[ArcadeSocket] Move rejected: ${data.error}`)
       eventsRef.current.onMoveRejected?.(data)
     })
 
@@ -124,12 +121,7 @@ export function useArcadeSocket(events: ArcadeSocketEvents = {}): UseArcadeSocke
         console.warn('[ArcadeSocket] Cannot send move - socket not connected')
         return
       }
-      const payload = { userId, move, roomId }
-      console.log(
-        '[ArcadeSocket] Sending game-move event with payload:',
-        JSON.stringify(payload, null, 2)
-      )
-      socket.emit('game-move', payload)
+      socket.emit('game-move', { userId, move, roomId })
     },
     [socket]
   )

apps/web/src/hooks/useRoomData.ts

@@ -451,7 +451,6 @@ export function useRoomData() {
       gameName: string | null
       gameConfig?: Record<string, unknown>
     }) => {
-      console.log('[useRoomData] Room game changed:', data)
       if (data.roomId === roomData?.id) {
         queryClient.setQueryData<RoomData | null>(roomKeys.current(), (prev) => {
           if (!prev) return null
@@ -683,18 +682,6 @@ async function updateGameConfigApi(params: {
   roomId: string
   gameConfig: Record<string, unknown>
 }): Promise<void> {
-  console.log(
-    '[updateGameConfigApi] Sending PATCH to server:',
-    JSON.stringify(
-      {
-        url: `/api/arcade/rooms/${params.roomId}/settings`,
-        gameConfig: params.gameConfig,
-      },
-      null,
-      2
-    )
-  )
-
   const response = await fetch(`/api/arcade/rooms/${params.roomId}/settings`, {
     method: 'PATCH',
     headers: { 'Content-Type': 'application/json' },
@@ -705,11 +692,8 @@ async function updateGameConfigApi(params: {
 
   if (!response.ok) {
     const errorData = await response.json()
-    console.error('[updateGameConfigApi] Server error:', JSON.stringify(errorData, null, 2))
     throw new Error(errorData.error || 'Failed to update game config')
   }
-
-  console.log('[updateGameConfigApi] Server responded OK')
 }
 
 /**
@@ -730,10 +714,6 @@ export function useUpdateGameConfig() {
           gameConfig: variables.gameConfig,
         }
       })
-      console.log(
-        '[useUpdateGameConfig] Updated cache with new gameConfig:',
-        JSON.stringify(variables.gameConfig, null, 2)
-      )
     },
   })
 }

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,

apps/web/src/lib/arcade/session-manager.ts

@@ -79,11 +79,6 @@ export async function createArcadeSession(
   // Check if session already exists for this room (roomId is PRIMARY KEY)
   const existingRoomSession = await getArcadeSessionByRoom(options.roomId)
   if (existingRoomSession) {
-    console.log('[Session Manager] Room session already exists, returning existing:', {
-      roomId: options.roomId,
-      sessionUserId: existingRoomSession.userId,
-      version: existingRoomSession.version,
-    })
     return existingRoomSession
   }
 
@@ -93,7 +88,6 @@ export async function createArcadeSession(
   })
 
   if (!user) {
-    console.log('[Session Manager] Creating new user with guestId:', options.userId)
     const [newUser] = await db
       .insert(schema.users)
       .values({
@@ -102,9 +96,6 @@ export async function createArcadeSession(
       })
       .returning()
     user = newUser
-    console.log('[Session Manager] Created user with id:', user.id)
-  } else {
-    console.log('[Session Manager] Found existing user with id:', user.id)
   }
 
   const newSession: schema.NewArcadeSession = {
@@ -121,12 +112,6 @@ export async function createArcadeSession(
     version: 1,
   }
 
-  console.log('[Session Manager] Creating new session:', {
-    roomId: options.roomId,
-    userId: user.id,
-    gameName: options.gameName,
-  })
-
   try {
     const [session] = await db.insert(schema.arcadeSessions).values(newSession).returning()
     return session
@@ -134,10 +119,6 @@ export async function createArcadeSession(
     // Handle PRIMARY KEY constraint violation (UNIQUE constraint on roomId)
     // This can happen if two users try to create a session for the same room simultaneously
     if (error instanceof Error && error.message.includes('UNIQUE constraint failed')) {
-      console.log(
-        '[Session Manager] Session already exists (race condition), fetching existing session for room:',
-        options.roomId
-      )
       const existingSession = await getArcadeSessionByRoom(options.roomId)
       if (existingSession) {
         return existingSession
@@ -180,7 +161,6 @@ export async function getArcadeSession(guestId: string): Promise<schema.ArcadeSe
   })
 
   if (!room) {
-    console.log('[Session Manager] Deleting session with non-existent room:', session.roomId)
     await deleteArcadeSessionByRoom(session.roomId)
     return undefined
   }
@@ -220,16 +200,6 @@ export async function applyGameMove(
   // Get the validator for this game
   const validator = getValidator(session.currentGame as GameName)
 
-  console.log('[SessionManager] About to validate move:', {
-    gameName: session.currentGame,
-    moveType: move.type,
-    playerId: move.playerId,
-    moveData: move.type === 'SET_CONFIG' ? (move as any).data : undefined,
-    gameStateCurrentPlayer: (session.gameState as any)?.currentPlayer,
-    gameStateActivePlayers: (session.gameState as any)?.activePlayers,
-    gameStatePhase: (session.gameState as any)?.gamePhase,
-  })
-
   // Fetch player ownership for authorization checks (room-based games)
   let playerOwnership: PlayerOwnershipMap | undefined
   let internalUserId: string | undefined
@@ -247,8 +217,6 @@ export async function applyGameMove(
 
       // Use centralized ownership utility
       playerOwnership = await buildPlayerOwnershipMap(session.roomId)
-      console.log('[SessionManager] Player ownership map:', playerOwnership)
-      console.log('[SessionManager] Internal userId for authorization:', internalUserId)
     } catch (error) {
       console.error('[SessionManager] Failed to fetch player ownership:', error)
     }
@@ -260,11 +228,6 @@ export async function applyGameMove(
     playerOwnership,
   })
 
-  console.log('[SessionManager] Validation result:', {
-    valid: validationResult.valid,
-    error: validationResult.error,
-  })
-
   if (!validationResult.valid) {
     return {
       success: false,
@@ -373,10 +336,6 @@ export async function updateSessionActivePlayers(
   // Only update if game is in setup phase (not started yet)
   const gameState = session.gameState as any
   if (gameState.gamePhase !== 'setup') {
-    console.log('[Session Manager] Cannot update activePlayers - game already started:', {
-      roomId,
-      gamePhase: gameState.gamePhase,
-    })
     return false
   }
 
@@ -397,12 +356,6 @@ export async function updateSessionActivePlayers(
     })
     .where(eq(schema.arcadeSessions.roomId, roomId))
 
-  console.log('[Session Manager] Updated session activePlayers:', {
-    roomId,
-    playerIds,
-    count: playerIds.length,
-  })
-
   return true
 }
 

apps/web/src/socket-server.ts

@@ -41,7 +41,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
   })
 
   io.on('connection', (socket) => {
-    console.log('🔌 Client connected:', socket.id)
     let currentUserId: string | null = null
 
     // Join arcade session room
@@ -50,12 +49,10 @@ export function initializeSocketServer(httpServer: HTTPServer) {
       async ({ userId, roomId }: { userId: string; roomId?: string }) => {
         currentUserId = userId
         socket.join(`arcade:${userId}`)
-        console.log(`👤 User ${userId} joined arcade room`)
 
         // If this session is part of a room, also join the game room for multi-user sync
         if (roomId) {
           socket.join(`game:${roomId}`)
-          console.log(`🎮 User ${userId} joined game room ${roomId}`)
         }
 
         // Send current session state if exists
@@ -68,19 +65,14 @@ export function initializeSocketServer(httpServer: HTTPServer) {
           // If no session exists for this room, create one in setup phase
           // This allows users to send SET_CONFIG moves before starting the game
           if (!session && roomId) {
-            console.log('[join-arcade-session] Creating initial session for room:', roomId)
-
             // Get the room to determine game type and config
             const room = await getRoomById(roomId)
             if (room) {
               // Fetch all active player IDs from room members (respects isActive flag)
               const roomPlayerIds = await getRoomPlayerIds(roomId)
-              console.log('[join-arcade-session] Room active players:', roomPlayerIds)
 
               // Get initial state from the correct validator based on game type
-              console.log('[join-arcade-session] Room game name:', room.gameName)
               const validator = getValidator(room.gameName as GameName)
-              console.log('[join-arcade-session] Got validator for:', room.gameName)
 
               // Get game-specific config from database (type-safe)
               const gameConfig = await getGameConfig(roomId, room.gameName as GameName)
@@ -94,23 +86,10 @@ export function initializeSocketServer(httpServer: HTTPServer) {
                 activePlayers: roomPlayerIds, // Include all room members' active players
                 roomId: room.id,
               })
-
-              console.log('[join-arcade-session] Created initial session:', {
-                roomId,
-                sessionId: session.userId,
-                gamePhase: (session.gameState as any).gamePhase,
-                activePlayersCount: roomPlayerIds.length,
-              })
             }
           }
 
           if (session) {
-            console.log('[join-arcade-session] Found session:', {
-              userId,
-              roomId,
-              version: session.version,
-              sessionUserId: session.userId,
-            })
             socket.emit('session-state', {
               gameState: session.gameState,
               currentGame: session.currentGame,
@@ -119,10 +98,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               version: session.version,
             })
           } else {
-            console.log('[join-arcade-session] No active session found for:', {
-              userId,
-              roomId,
-            })
             socket.emit('no-active-session')
           }
         } catch (error) {
@@ -134,15 +109,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
 
     // Handle game moves
     socket.on('game-move', async (data: { userId: string; move: GameMove; roomId?: string }) => {
-      console.log('🎮 Game move received:', {
-        userId: data.userId,
-        moveType: data.move.type,
-        playerId: data.move.playerId,
-        timestamp: data.move.timestamp,
-        roomId: data.roomId,
-        fullMove: JSON.stringify(data.move, null, 2),
-      })
-
       try {
         // Special handling for START_GAME - create session if it doesn't exist
         if (data.move.type === 'START_GAME') {
@@ -152,12 +118,9 @@ export function initializeSocketServer(httpServer: HTTPServer) {
             : await getArcadeSession(data.userId)
 
           if (!existingSession) {
-            console.log('🎯 Creating new session for START_GAME')
-
             // activePlayers must be provided in the START_GAME move data
             const activePlayers = (data.move.data as any)?.activePlayers
             if (!activePlayers || activePlayers.length === 0) {
-              console.error('❌ START_GAME move missing activePlayers')
               socket.emit('move-rejected', {
                 error: 'START_GAME requires at least one active player',
                 move: data.move,
@@ -186,7 +149,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
                 existingRoom.status !== 'finished'
               ) {
                 room = existingRoom
-                console.log('🏠 Using existing room:', room.code)
                 break
               }
             }
@@ -205,7 +167,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
                 },
                 ttlMinutes: 60,
               })
-              console.log('🏠 Created new room:', room.code)
             }
 
             // Now create the session linked to the room
@@ -218,8 +179,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               roomId: room.id,
             })
 
-            console.log('✅ Session created successfully with room association')
-
             // Notify all connected clients about the new session
             const newSession = await getArcadeSession(data.userId)
             if (newSession) {
@@ -230,7 +189,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
                 activePlayers: newSession.activePlayers,
                 version: newSession.version,
               })
-              console.log('📢 Emitted session-state to notify clients of new session')
             }
           }
         }
@@ -251,7 +209,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
           // If this is a room-based session, ALSO broadcast to all users in the room
           if (result.session.roomId) {
             io!.to(`game:${result.session.roomId}`).emit('move-accepted', moveAcceptedData)
-            console.log(`📢 Broadcasted move to game room ${result.session.roomId}`)
           }
 
           // Update activity timestamp
@@ -275,8 +232,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
 
     // Handle session exit
     socket.on('exit-arcade-session', async ({ userId }: { userId: string }) => {
-      console.log('🚪 User exiting arcade session:', userId)
-
       try {
         await deleteArcadeSession(userId)
         io!.to(`arcade:${userId}`).emit('session-ended')
@@ -298,8 +253,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
 
     // Room: Join
     socket.on('join-room', async ({ roomId, userId }: { roomId: string; userId: string }) => {
-      console.log(`🏠 User ${userId} joining room ${roomId}`)
-
       try {
         // Join the socket room
         socket.join(`room:${roomId}`)
@@ -323,10 +276,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
         const sessionUpdated = await updateSessionActivePlayers(roomId, roomPlayerIds)
 
         if (sessionUpdated) {
-          console.log(`🎮 Updated session activePlayers for room ${roomId}:`, {
-            playerCount: roomPlayerIds.length,
-          })
-
           // Broadcast updated session state to all users in the game room
           const updatedSession = await getArcadeSessionByRoom(roomId)
           if (updatedSession) {
@@ -337,7 +286,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               activePlayers: updatedSession.activePlayers,
               version: updatedSession.version,
             })
-            console.log(`📢 Broadcasted updated session state to game room ${roomId}`)
           }
         }
 
@@ -355,8 +303,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
           members,
           memberPlayers: memberPlayersObj,
         })
-
-        console.log(`✅ User ${userId} joined room ${roomId}`)
       } catch (error) {
         console.error('Error joining room:', error)
         socket.emit('room-error', { error: 'Failed to join room' })
@@ -365,11 +311,9 @@ export function initializeSocketServer(httpServer: HTTPServer) {
 
     // User Channel: Join (for moderation events)
     socket.on('join-user-channel', async ({ userId }: { userId: string }) => {
-      console.log(`👤 User ${userId} joining user-specific channel`)
       try {
         // Join user-specific channel for moderation notifications
         socket.join(`user:${userId}`)
-        console.log(`✅ User ${userId} joined user channel`)
       } catch (error) {
         console.error('Error joining user channel:', error)
       }
@@ -377,8 +321,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
 
     // Room: Leave
     socket.on('leave-room', async ({ roomId, userId }: { roomId: string; userId: string }) => {
-      console.log(`🚪 User ${userId} leaving room ${roomId}`)
-
       try {
         // Leave the socket room
         socket.leave(`room:${roomId}`)
@@ -403,8 +345,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
           members,
           memberPlayers: memberPlayersObj,
         })
-
-        console.log(`✅ User ${userId} left room ${roomId}`)
       } catch (error) {
         console.error('Error leaving room:', error)
       }
@@ -412,8 +352,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
 
     // Room: Players updated
     socket.on('players-updated', async ({ roomId, userId }: { roomId: string; userId: string }) => {
-      console.log(`🎯 Players updated for user ${userId} in room ${roomId}`)
-
       try {
         // Get updated player data
         const memberPlayers = await getRoomActivePlayers(roomId)
@@ -429,11 +367,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
         const sessionUpdated = await updateSessionActivePlayers(roomId, roomPlayerIds)
 
         if (sessionUpdated) {
-          console.log(`🎮 Updated session activePlayers after player toggle:`, {
-            roomId,
-            playerCount: roomPlayerIds.length,
-          })
-
           // Broadcast updated session state to all users in the game room
           const updatedSession = await getArcadeSessionByRoom(roomId)
           if (updatedSession) {
@@ -444,7 +377,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               activePlayers: updatedSession.activePlayers,
               version: updatedSession.version,
             })
-            console.log(`📢 Broadcasted updated session state to game room ${roomId}`)
           }
         }
 
@@ -453,8 +385,6 @@ export function initializeSocketServer(httpServer: HTTPServer) {
           roomId,
           memberPlayers: memberPlayersObj,
         })
-
-        console.log(`✅ Broadcasted player updates for room ${roomId}`)
       } catch (error) {
         console.error('Error updating room players:', error)
         socket.emit('room-error', { error: 'Failed to update players' })
@@ -462,16 +392,11 @@ export function initializeSocketServer(httpServer: HTTPServer) {
     })
 
     socket.on('disconnect', () => {
-      console.log('🔌 Client disconnected:', socket.id)
-      if (currentUserId) {
-        // Don't delete session on disconnect - it persists across devices
-        console.log(`👤 User ${currentUserId} disconnected but session persists`)
-      }
+      // Don't delete session on disconnect - it persists across devices
     })
   })
 
   // Store in globalThis to make accessible across module boundaries
   globalThis.__socketIO = io
-  console.log('✅ Socket.IO initialized on /api/socket')
   return io
 }

package.json

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

packages/core/client/browser/node_modules/.bin/tsc

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsc" "$@"
-fi

packages/core/client/browser/node_modules/.bin/tsserver

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsserver" "$@"
-fi

packages/core/client/browser/node_modules/.bin/vite

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules/vite/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules/vite/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules/vite/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules/vite/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../vite/bin/vite.js" "$@"
-else
-  exec node  "$basedir/../vite/bin/vite.js" "$@"
-fi

packages/core/client/browser/node_modules/@myriaddreamin/typst-ts-renderer

@@ -1 +0,0 @@
-../../../../../../node_modules/.pnpm/@myriaddreamin+typst-ts-renderer@0.6.0/node_modules/@myriaddreamin/typst-ts-renderer

packages/core/client/browser/node_modules/@myriaddreamin/typst-ts-web-compiler

@@ -1 +0,0 @@
-../../../../../../node_modules/.pnpm/@myriaddreamin+typst-ts-web-compiler@0.6.0/node_modules/@myriaddreamin/typst-ts-web-compiler

packages/core/client/browser/node_modules/vite

@@ -1 +0,0 @@
-../../../../../node_modules/.pnpm/vite@5.4.20_@types+node@20.19.19_terser@5.44.0/node_modules/vite

packages/core/client/browser/package.json

@@ -1,19 +0,0 @@
-{
-  "name": "soroban-flashcards-browser",
-  "version": "1.0.0",
-  "description": "Browser-based Soroban Flashcard Generator using Typst.ts",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "@myriaddreamin/typst-ts-web-compiler": "^0.6.0",
-    "@myriaddreamin/typst-ts-renderer": "^0.6.0"
-  },
-  "devDependencies": {
-    "vite": "^5.0.0",
-    "typescript": "^5.0.0"
-  }
-}

packages/core/client/node/dist/index.d.ts

@@ -2,12 +2,12 @@
  * Node.js TypeScript wrapper for Soroban Flashcard Generator
  * Calls Python functions via child_process
  */
-interface FlashcardConfig$1 {
+interface FlashcardConfig {
     range: string;
     step?: number;
     cardsPerPage?: number;
-    paperSize?: 'us-letter' | 'a4' | 'a3' | 'a5';
-    orientation?: 'portrait' | 'landscape';
+    paperSize?: "us-letter" | "a4" | "a3" | "a5";
+    orientation?: "portrait" | "landscape";
     margins?: {
         top?: string;
         bottom?: string;
@@ -24,12 +24,12 @@ interface FlashcardConfig$1 {
     columns?: string | number;
     showEmptyColumns?: boolean;
     hideInactiveBeads?: boolean;
-    beadShape?: 'diamond' | 'circle' | 'square';
-    colorScheme?: 'monochrome' | 'place-value' | 'heaven-earth' | 'alternating';
+    beadShape?: "diamond" | "circle" | "square";
+    colorScheme?: "monochrome" | "place-value" | "heaven-earth" | "alternating";
     coloredNumerals?: boolean;
     scaleFactor?: number;
 }
-declare class SorobanGenerator$1 {
+declare class SorobanGenerator {
     private pythonPath;
     private generatorPath;
     private projectRoot;
@@ -38,15 +38,15 @@ declare class SorobanGenerator$1 {
     /**
      * Generate flashcards and return PDF as Buffer
      */
-    generate(config: FlashcardConfig$1): Promise<Buffer>;
+    generate(config: FlashcardConfig): Promise<Buffer>;
     /**
      * Generate flashcards and save to file
      */
-    generateToFile(config: FlashcardConfig$1, outputPath: string): Promise<void>;
+    generateToFile(config: FlashcardConfig, outputPath: string): Promise<void>;
     /**
      * Generate flashcards and return as base64 string
      */
-    generateBase64(config: FlashcardConfig$1): Promise<string>;
+    generateBase64(config: FlashcardConfig): Promise<string>;
     private executePython;
     /**
      * Check if all dependencies are installed
@@ -59,65 +59,4 @@ declare class SorobanGenerator$1 {
 }
 declare function expressExample(): Promise<void>;
 
-/**
- * TypeScript wrapper using python-shell for clean function interface
- * No CLI arguments - just function calls with objects
- */
-interface FlashcardConfig {
-    range: string;
-    step?: number;
-    cardsPerPage?: number;
-    paperSize?: 'us-letter' | 'a4' | 'a3' | 'a5';
-    orientation?: 'portrait' | 'landscape';
-    margins?: {
-        top?: string;
-        bottom?: string;
-        left?: string;
-        right?: string;
-    };
-    gutter?: string;
-    shuffle?: boolean;
-    seed?: number;
-    showCutMarks?: boolean;
-    showRegistration?: boolean;
-    fontFamily?: string;
-    fontSize?: string;
-    columns?: string | number;
-    showEmptyColumns?: boolean;
-    hideInactiveBeads?: boolean;
-    beadShape?: 'diamond' | 'circle' | 'square';
-    colorScheme?: 'monochrome' | 'place-value' | 'heaven-earth' | 'alternating';
-    coloredNumerals?: boolean;
-    scaleFactor?: number;
-    format?: 'pdf' | 'svg';
-    mode?: 'single-card' | 'flashcards';
-    number?: number;
-}
-interface FlashcardResult {
-    pdf: string;
-    count: number;
-    numbers: number[];
-}
-declare class SorobanGenerator {
-    private pythonShell;
-    private projectRoot;
-    constructor(projectRoot?: string);
-    /**
-     * Initialize persistent Python process for better performance
-     */
-    initialize(): Promise<void>;
-    /**
-     * Generate flashcards - clean function interface
-     */
-    generate(config: FlashcardConfig): Promise<FlashcardResult>;
-    /**
-     * Generate and return as Buffer
-     */
-    generateBuffer(config: FlashcardConfig): Promise<Buffer>;
-    /**
-     * Clean up Python process
-     */
-    close(): Promise<void>;
-}
-
-export { FlashcardConfig as BridgeFlashcardConfig, FlashcardResult as BridgeFlashcardResult, FlashcardConfig$1 as FlashcardConfig, SorobanGenerator$1 as SorobanGenerator, SorobanGenerator as SorobanGeneratorBridge, SorobanGenerator$1 as default, expressExample };
+export { type FlashcardConfig, SorobanGenerator, SorobanGenerator as default, expressExample };

packages/core/client/node/dist/index.js

@@ -31,7 +31,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   SorobanGenerator: () => SorobanGenerator,
-  SorobanGeneratorBridge: () => SorobanGenerator2,
   default: () => SorobanGenerator,
   expressExample: () => expressExample
 });
@@ -194,96 +193,8 @@ var SorobanGenerator = class {
 async function expressExample() {
   const generator = new SorobanGenerator();
 }
-
-// src/soroban-generator-bridge.ts
-var import_python_shell = require("python-shell");
-var path2 = __toESM(require("path"));
-var SorobanGenerator2 = class {
-  pythonShell = null;
-  projectRoot;
-  constructor(projectRoot) {
-    this.projectRoot = projectRoot || path2.join(__dirname, "../../");
-  }
-  /**
-   * Initialize persistent Python process for better performance
-   */
-  async initialize() {
-    if (this.pythonShell)
-      return;
-    this.pythonShell = new import_python_shell.PythonShell(path2.join("src", "bridge.py"), {
-      mode: "json",
-      pythonPath: "python3",
-      pythonOptions: ["-u"],
-      // Unbuffered
-      scriptPath: this.projectRoot
-    });
-  }
-  /**
-   * Generate flashcards - clean function interface
-   */
-  async generate(config) {
-    if (!this.pythonShell) {
-      return new Promise((resolve, reject) => {
-        const shell = new import_python_shell.PythonShell(path2.join("src", "bridge.py"), {
-          mode: "json",
-          pythonPath: "python3",
-          scriptPath: this.projectRoot
-        });
-        shell.on("message", (message) => {
-          if (message.error) {
-            reject(new Error(message.error));
-          } else {
-            resolve(message);
-          }
-        });
-        shell.on("error", (err) => {
-          reject(err);
-        });
-        shell.send(config);
-        shell.end((err, code, signal) => {
-          if (err)
-            reject(err);
-        });
-      });
-    }
-    return new Promise((resolve, reject) => {
-      if (!this.pythonShell) {
-        reject(new Error("Not initialized"));
-        return;
-      }
-      const handler = (message) => {
-        if (message.error) {
-          reject(new Error(message.error));
-        } else {
-          resolve(message);
-        }
-        this.pythonShell?.removeListener("message", handler);
-      };
-      this.pythonShell.on("message", handler);
-      this.pythonShell.send(config);
-    });
-  }
-  /**
-   * Generate and return as Buffer
-   */
-  async generateBuffer(config) {
-    const result = await this.generate(config);
-    return Buffer.from(result.pdf, "base64");
-  }
-  /**
-   * Clean up Python process
-   */
-  async close() {
-    if (this.pythonShell) {
-      this.pythonShell.end(() => {
-      });
-      this.pythonShell = null;
-    }
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SorobanGenerator,
-  SorobanGeneratorBridge,
   expressExample
 });

packages/core/client/node/dist/index.mjs

@@ -155,96 +155,8 @@ var SorobanGenerator = class {
 async function expressExample() {
   const generator = new SorobanGenerator();
 }
-
-// src/soroban-generator-bridge.ts
-import { PythonShell } from "python-shell";
-import * as path2 from "path";
-var SorobanGenerator2 = class {
-  pythonShell = null;
-  projectRoot;
-  constructor(projectRoot) {
-    this.projectRoot = projectRoot || path2.join(__dirname, "../../");
-  }
-  /**
-   * Initialize persistent Python process for better performance
-   */
-  async initialize() {
-    if (this.pythonShell)
-      return;
-    this.pythonShell = new PythonShell(path2.join("src", "bridge.py"), {
-      mode: "json",
-      pythonPath: "python3",
-      pythonOptions: ["-u"],
-      // Unbuffered
-      scriptPath: this.projectRoot
-    });
-  }
-  /**
-   * Generate flashcards - clean function interface
-   */
-  async generate(config) {
-    if (!this.pythonShell) {
-      return new Promise((resolve, reject) => {
-        const shell = new PythonShell(path2.join("src", "bridge.py"), {
-          mode: "json",
-          pythonPath: "python3",
-          scriptPath: this.projectRoot
-        });
-        shell.on("message", (message) => {
-          if (message.error) {
-            reject(new Error(message.error));
-          } else {
-            resolve(message);
-          }
-        });
-        shell.on("error", (err) => {
-          reject(err);
-        });
-        shell.send(config);
-        shell.end((err, code, signal) => {
-          if (err)
-            reject(err);
-        });
-      });
-    }
-    return new Promise((resolve, reject) => {
-      if (!this.pythonShell) {
-        reject(new Error("Not initialized"));
-        return;
-      }
-      const handler = (message) => {
-        if (message.error) {
-          reject(new Error(message.error));
-        } else {
-          resolve(message);
-        }
-        this.pythonShell?.removeListener("message", handler);
-      };
-      this.pythonShell.on("message", handler);
-      this.pythonShell.send(config);
-    });
-  }
-  /**
-   * Generate and return as Buffer
-   */
-  async generateBuffer(config) {
-    const result = await this.generate(config);
-    return Buffer.from(result.pdf, "base64");
-  }
-  /**
-   * Clean up Python process
-   */
-  async close() {
-    if (this.pythonShell) {
-      this.pythonShell.end(() => {
-      });
-      this.pythonShell = null;
-    }
-  }
-};
 export {
   SorobanGenerator,
-  SorobanGenerator2 as SorobanGeneratorBridge,
   SorobanGenerator as default,
   expressExample
 };

packages/core/client/node/node_modules/.bin/esbuild

@@ -6,9 +6,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.19.12/node_modules/esbuild/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.19.12/node_modules/esbuild/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.19.12/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.19.12/node_modules/esbuild/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.19.12/node_modules/esbuild/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.19.12/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
-"$basedir/../../../../../../node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/bin/esbuild"   "$@"
+"$basedir/../../../../../../node_modules/.pnpm/esbuild@0.19.12/node_modules/esbuild/bin/esbuild"   "$@"
 exit $?

packages/core/client/node/node_modules/python-shell

@@ -1 +0,0 @@
-../../../../../node_modules/.pnpm/python-shell@5.0.0/node_modules/python-shell

packages/core/client/node/package.json

@@ -18,9 +18,6 @@
     "type-check": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
-  "dependencies": {
-    "python-shell": "^5.0.0"
-  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsup": "^7.0.0",

packages/core/client/node/src/index.ts

@@ -5,12 +5,5 @@
 
 export * from "./soroban-generator";
 
-// Export bridge generator with different name to avoid conflicts
-export {
-  SorobanGenerator as SorobanGeneratorBridge,
-  FlashcardConfig as BridgeFlashcardConfig,
-  FlashcardResult as BridgeFlashcardResult,
-} from "./soroban-generator-bridge";
-
 // Default export for convenience
 export { SorobanGenerator as default } from "./soroban-generator";

packages/core/client/node/src/soroban-generator-bridge.ts

@@ -1,190 +0,0 @@
-/**
- * TypeScript wrapper using python-shell for clean function interface
- * No CLI arguments - just function calls with objects
- */
-
-import { PythonShell } from "python-shell";
-import * as path from "path";
-
-export interface FlashcardConfig {
-  range: string;
-  step?: number;
-  cardsPerPage?: number;
-  paperSize?: "us-letter" | "a4" | "a3" | "a5";
-  orientation?: "portrait" | "landscape";
-  margins?: {
-    top?: string;
-    bottom?: string;
-    left?: string;
-    right?: string;
-  };
-  gutter?: string;
-  shuffle?: boolean;
-  seed?: number;
-  showCutMarks?: boolean;
-  showRegistration?: boolean;
-  fontFamily?: string;
-  fontSize?: string;
-  columns?: string | number;
-  showEmptyColumns?: boolean;
-  hideInactiveBeads?: boolean;
-  beadShape?: "diamond" | "circle" | "square";
-  colorScheme?: "monochrome" | "place-value" | "heaven-earth" | "alternating";
-  coloredNumerals?: boolean;
-  scaleFactor?: number;
-  format?: "pdf" | "svg";
-  mode?: "single-card" | "flashcards";
-  number?: number;
-}
-
-export interface FlashcardResult {
-  pdf: string; // base64 encoded PDF or SVG content (depending on format)
-  count: number;
-  numbers: number[];
-}
-
-export class SorobanGenerator {
-  private pythonShell: PythonShell | null = null;
-  private projectRoot: string;
-
-  constructor(projectRoot?: string) {
-    this.projectRoot = projectRoot || path.join(__dirname, "../../");
-  }
-
-  /**
-   * Initialize persistent Python process for better performance
-   */
-  async initialize(): Promise<void> {
-    if (this.pythonShell) return;
-
-    this.pythonShell = new PythonShell(path.join("src", "bridge.py"), {
-      mode: "json",
-      pythonPath: "python3",
-      pythonOptions: ["-u"], // Unbuffered
-      scriptPath: this.projectRoot,
-    });
-  }
-
-  /**
-   * Generate flashcards - clean function interface
-   */
-  async generate(config: FlashcardConfig): Promise<FlashcardResult> {
-    // One-shot mode if not initialized
-    if (!this.pythonShell) {
-      return new Promise((resolve, reject) => {
-        const shell = new PythonShell(path.join("src", "bridge.py"), {
-          mode: "json",
-          pythonPath: "python3",
-          scriptPath: this.projectRoot,
-        });
-
-        shell.on("message", (message: any) => {
-          if (message.error) {
-            reject(new Error(message.error));
-          } else {
-            resolve(message as FlashcardResult);
-          }
-        });
-
-        shell.on("error", (err: any) => {
-          reject(err);
-        });
-
-        shell.send(config);
-        shell.end((err: any, code: any, signal: any) => {
-          if (err) reject(err);
-        });
-      });
-    }
-
-    // Persistent mode
-    return new Promise((resolve, reject) => {
-      if (!this.pythonShell) {
-        reject(new Error("Not initialized"));
-        return;
-      }
-
-      const handler = (message: any) => {
-        if (message.error) {
-          reject(new Error(message.error));
-        } else {
-          resolve(message as FlashcardResult);
-        }
-        this.pythonShell?.removeListener("message", handler);
-      };
-
-      this.pythonShell.on("message", handler);
-      this.pythonShell.send(config);
-    });
-  }
-
-  /**
-   * Generate and return as Buffer
-   */
-  async generateBuffer(config: FlashcardConfig): Promise<Buffer> {
-    const result = await this.generate(config);
-    return Buffer.from(result.pdf, "base64");
-  }
-
-  /**
-   * Clean up Python process
-   */
-  async close(): Promise<void> {
-    if (this.pythonShell) {
-      this.pythonShell.end(() => {});
-      this.pythonShell = null;
-    }
-  }
-}
-
-// Example usage - just like calling a regular TypeScript function
-async function example() {
-  const generator = new SorobanGenerator();
-
-  // Just call it like a function!
-  const result = await generator.generate({
-    range: "0-99",
-    cardsPerPage: 6,
-    colorScheme: "place-value",
-    coloredNumerals: true,
-    showCutMarks: true,
-  });
-
-  // You get back a clean result object
-  console.log(`Generated ${result.count} flashcards`);
-
-  // Convert to Buffer if needed
-  const pdfBuffer = Buffer.from(result.pdf, "base64");
-
-  // Or use persistent mode for better performance
-  await generator.initialize();
-
-  // Now calls are faster
-  const result2 = await generator.generate({ range: "0-9" });
-  const result3 = await generator.generate({ range: "10-19" });
-
-  await generator.close();
-}
-
-// Express example - clean function calls
-export function expressRoute(app: any) {
-  const generator = new SorobanGenerator();
-
-  app.post("/api/flashcards", async (req: any, res: any) => {
-    try {
-      // Just pass the config object directly!
-      const result = await generator.generate(req.body);
-
-      // Send back JSON or PDF
-      if (req.query.format === "json") {
-        res.json(result);
-      } else {
-        const pdfBuffer = Buffer.from(result.pdf, "base64");
-        res.contentType("application/pdf");
-        res.send(pdfBuffer);
-      }
-    } catch (error) {
-      res.status(500).json({ error: (error as Error).message });
-    }
-  });
-}

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/dist/index.d.ts

@@ -1,58 +0,0 @@
-/**
- * TypeScript client for Soroban Flashcard Generator API
- */
-interface FlashcardConfig {
-    range: string;
-    step?: number;
-    cardsPerPage?: number;
-    paperSize?: 'us-letter' | 'a4' | 'a3' | 'a5';
-    orientation?: 'portrait' | 'landscape';
-    margins?: {
-        top?: string;
-        bottom?: string;
-        left?: string;
-        right?: string;
-    };
-    gutter?: string;
-    shuffle?: boolean;
-    seed?: number;
-    showCutMarks?: boolean;
-    showRegistration?: boolean;
-    fontFamily?: string;
-    fontSize?: string;
-    columns?: string | number;
-    showEmptyColumns?: boolean;
-    hideInactiveBeads?: boolean;
-    beadShape?: 'diamond' | 'circle' | 'square';
-    colorScheme?: 'monochrome' | 'place-value' | 'heaven-earth' | 'alternating';
-    coloredNumerals?: boolean;
-    scaleFactor?: number;
-}
-interface FlashcardResponse {
-    pdf: string;
-    count: number;
-    numbers: number[];
-}
-declare class SorobanFlashcardClient {
-    private apiUrl;
-    constructor(apiUrl?: string);
-    /**
-     * Generate flashcards and return as base64 PDF
-     */
-    generate(config: FlashcardConfig): Promise<FlashcardResponse>;
-    /**
-     * Generate flashcards and download as PDF file
-     */
-    generateAndDownload(config: FlashcardConfig, filename?: string): Promise<void>;
-    /**
-     * Generate flashcards and open in new tab
-     */
-    generateAndOpen(config: FlashcardConfig): Promise<void>;
-    /**
-     * Check API health
-     */
-    health(): Promise<boolean>;
-}
-declare function example(): Promise<void>;
-
-export { FlashcardConfig, FlashcardResponse, SorobanFlashcardClient, SorobanFlashcardClient as default, example };

packages/core/client/typescript/dist/index.js

@@ -1,148 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  SorobanFlashcardClient: () => SorobanFlashcardClient,
-  default: () => SorobanFlashcardClient,
-  example: () => example
-});
-module.exports = __toCommonJS(src_exports);
-
-// src/soroban-flashcards.ts
-var SorobanFlashcardClient = class {
-  apiUrl;
-  constructor(apiUrl = "http://localhost:8000") {
-    this.apiUrl = apiUrl;
-  }
-  /**
-   * Generate flashcards and return as base64 PDF
-   */
-  async generate(config) {
-    const response = await fetch(`${this.apiUrl}/generate`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        range: config.range,
-        step: config.step ?? 1,
-        cards_per_page: config.cardsPerPage ?? 6,
-        paper_size: config.paperSize ?? "us-letter",
-        orientation: config.orientation ?? "portrait",
-        margins: config.margins ?? {
-          top: "0.5in",
-          bottom: "0.5in",
-          left: "0.5in",
-          right: "0.5in"
-        },
-        gutter: config.gutter ?? "5mm",
-        shuffle: config.shuffle ?? false,
-        seed: config.seed,
-        show_cut_marks: config.showCutMarks ?? false,
-        show_registration: config.showRegistration ?? false,
-        font_family: config.fontFamily ?? "DejaVu Sans",
-        font_size: config.fontSize ?? "48pt",
-        columns: config.columns ?? "auto",
-        show_empty_columns: config.showEmptyColumns ?? false,
-        hide_inactive_beads: config.hideInactiveBeads ?? false,
-        bead_shape: config.beadShape ?? "diamond",
-        color_scheme: config.colorScheme ?? "monochrome",
-        colored_numerals: config.coloredNumerals ?? false,
-        scale_factor: config.scaleFactor ?? 0.9,
-        format: "base64"
-      })
-    });
-    if (!response.ok) {
-      const error = await response.json();
-      throw new Error(error.detail || "Failed to generate flashcards");
-    }
-    return response.json();
-  }
-  /**
-   * Generate flashcards and download as PDF file
-   */
-  async generateAndDownload(config, filename = "flashcards.pdf") {
-    const result = await this.generate(config);
-    const pdfBytes = atob(result.pdf);
-    const byteArray = new Uint8Array(pdfBytes.length);
-    for (let i = 0; i < pdfBytes.length; i++) {
-      byteArray[i] = pdfBytes.charCodeAt(i);
-    }
-    const blob = new Blob([byteArray], { type: "application/pdf" });
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = filename;
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
-    URL.revokeObjectURL(url);
-  }
-  /**
-   * Generate flashcards and open in new tab
-   */
-  async generateAndOpen(config) {
-    const result = await this.generate(config);
-    const pdfBytes = atob(result.pdf);
-    const byteArray = new Uint8Array(pdfBytes.length);
-    for (let i = 0; i < pdfBytes.length; i++) {
-      byteArray[i] = pdfBytes.charCodeAt(i);
-    }
-    const blob = new Blob([byteArray], { type: "application/pdf" });
-    const url = URL.createObjectURL(blob);
-    window.open(url, "_blank");
-  }
-  /**
-   * Check API health
-   */
-  async health() {
-    try {
-      const response = await fetch(`${this.apiUrl}/health`);
-      const data = await response.json();
-      return data.status === "healthy";
-    } catch {
-      return false;
-    }
-  }
-};
-async function example() {
-  const client = new SorobanFlashcardClient();
-  await client.generateAndDownload({
-    range: "0-99",
-    cardsPerPage: 6,
-    colorScheme: "place-value",
-    coloredNumerals: true,
-    showCutMarks: true
-  });
-  await client.generateAndDownload(
-    {
-      range: "0-100",
-      step: 5,
-      cardsPerPage: 6
-    },
-    "counting-by-5s.pdf"
-  );
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  SorobanFlashcardClient,
-  example
-});

packages/core/client/typescript/dist/index.mjs

@@ -1,120 +0,0 @@
-// src/soroban-flashcards.ts
-var SorobanFlashcardClient = class {
-  apiUrl;
-  constructor(apiUrl = "http://localhost:8000") {
-    this.apiUrl = apiUrl;
-  }
-  /**
-   * Generate flashcards and return as base64 PDF
-   */
-  async generate(config) {
-    const response = await fetch(`${this.apiUrl}/generate`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        range: config.range,
-        step: config.step ?? 1,
-        cards_per_page: config.cardsPerPage ?? 6,
-        paper_size: config.paperSize ?? "us-letter",
-        orientation: config.orientation ?? "portrait",
-        margins: config.margins ?? {
-          top: "0.5in",
-          bottom: "0.5in",
-          left: "0.5in",
-          right: "0.5in"
-        },
-        gutter: config.gutter ?? "5mm",
-        shuffle: config.shuffle ?? false,
-        seed: config.seed,
-        show_cut_marks: config.showCutMarks ?? false,
-        show_registration: config.showRegistration ?? false,
-        font_family: config.fontFamily ?? "DejaVu Sans",
-        font_size: config.fontSize ?? "48pt",
-        columns: config.columns ?? "auto",
-        show_empty_columns: config.showEmptyColumns ?? false,
-        hide_inactive_beads: config.hideInactiveBeads ?? false,
-        bead_shape: config.beadShape ?? "diamond",
-        color_scheme: config.colorScheme ?? "monochrome",
-        colored_numerals: config.coloredNumerals ?? false,
-        scale_factor: config.scaleFactor ?? 0.9,
-        format: "base64"
-      })
-    });
-    if (!response.ok) {
-      const error = await response.json();
-      throw new Error(error.detail || "Failed to generate flashcards");
-    }
-    return response.json();
-  }
-  /**
-   * Generate flashcards and download as PDF file
-   */
-  async generateAndDownload(config, filename = "flashcards.pdf") {
-    const result = await this.generate(config);
-    const pdfBytes = atob(result.pdf);
-    const byteArray = new Uint8Array(pdfBytes.length);
-    for (let i = 0; i < pdfBytes.length; i++) {
-      byteArray[i] = pdfBytes.charCodeAt(i);
-    }
-    const blob = new Blob([byteArray], { type: "application/pdf" });
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = filename;
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
-    URL.revokeObjectURL(url);
-  }
-  /**
-   * Generate flashcards and open in new tab
-   */
-  async generateAndOpen(config) {
-    const result = await this.generate(config);
-    const pdfBytes = atob(result.pdf);
-    const byteArray = new Uint8Array(pdfBytes.length);
-    for (let i = 0; i < pdfBytes.length; i++) {
-      byteArray[i] = pdfBytes.charCodeAt(i);
-    }
-    const blob = new Blob([byteArray], { type: "application/pdf" });
-    const url = URL.createObjectURL(blob);
-    window.open(url, "_blank");
-  }
-  /**
-   * Check API health
-   */
-  async health() {
-    try {
-      const response = await fetch(`${this.apiUrl}/health`);
-      const data = await response.json();
-      return data.status === "healthy";
-    } catch {
-      return false;
-    }
-  }
-};
-async function example() {
-  const client = new SorobanFlashcardClient();
-  await client.generateAndDownload({
-    range: "0-99",
-    cardsPerPage: 6,
-    colorScheme: "place-value",
-    coloredNumerals: true,
-    showCutMarks: true
-  });
-  await client.generateAndDownload(
-    {
-      range: "0-100",
-      step: 5,
-      cardsPerPage: 6
-    },
-    "counting-by-5s.pdf"
-  );
-}
-export {
-  SorobanFlashcardClient,
-  SorobanFlashcardClient as default,
-  example
-};

packages/core/client/typescript/node_modules/.bin/esbuild

@@ -1,14 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/esbuild@0.18.20/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-"$basedir/../../../../../../node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/bin/esbuild"   "$@"
-exit $?

packages/core/client/typescript/node_modules/.bin/tsc

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsc" "$@"
-fi

packages/core/client/typescript/node_modules/.bin/tsserver

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
-else
-  exec node  "$basedir/../typescript/bin/tsserver" "$@"
-fi

packages/core/client/typescript/node_modules/.bin/tsup

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/dist/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/dist/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../tsup/dist/cli-default.js" "$@"
-else
-  exec node  "$basedir/../tsup/dist/cli-default.js" "$@"
-fi

packages/core/client/typescript/node_modules/.bin/tsup-node

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/dist/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/dist/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../tsup/dist/cli-node.js" "$@"
-else
-  exec node  "$basedir/../tsup/dist/cli-node.js" "$@"
-fi

packages/core/client/typescript/node_modules/.bin/vitest

@@ -1,17 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vitest@1.6.1_@types+node@20.19.19_@vitest+ui@3.2.4_happy-dom@18.0.1_jsdom@27.0.0_postcss@8.5.6__terser@5.44.0/node_modules/vitest/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vitest@1.6.1_@types+node@20.19.19_@vitest+ui@3.2.4_happy-dom@18.0.1_jsdom@27.0.0_postcss@8.5.6__terser@5.44.0/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vitest@1.6.1_@types+node@20.19.19_@vitest+ui@3.2.4_happy-dom@18.0.1_jsdom@27.0.0_postcss@8.5.6__terser@5.44.0/node_modules/vitest/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/vitest@1.6.1_@types+node@20.19.19_@vitest+ui@3.2.4_happy-dom@18.0.1_jsdom@27.0.0_postcss@8.5.6__terser@5.44.0/node_modules:/Users/antialias/projects/soroban-abacus-flashcards/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
-else
-  exec node  "$basedir/../vitest/vitest.mjs" "$@"
-fi

packages/core/client/typescript/node_modules/tsup

@@ -1 +0,0 @@
-../../../../../node_modules/.pnpm/tsup@7.3.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup

packages/core/client/typescript/node_modules/vitest

@@ -1 +0,0 @@
-../../../../../node_modules/.pnpm/vitest@1.6.1_@types+node@20.19.19_@vitest+ui@3.2.4_happy-dom@18.0.1_jsdom@27.0.0_postcss@8.5.6__terser@5.44.0/node_modules/vitest

packages/core/client/typescript/package.json

@@ -1,37 +0,0 @@
-{
-  "name": "@soroban/client",
-  "version": "1.0.0",
-  "description": "TypeScript client for Soroban Flashcard Generator",
-  "main": "dist/index.js",
-  "module": "dist/index.esm.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.js",
-      "import": "./dist/index.esm.js"
-    }
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest",
-    "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
-  "keywords": [
-    "soroban",
-    "abacus",
-    "flashcards",
-    "education",
-    "math"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsup": "^7.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
-  }
-}

packages/core/client/typescript/src/index.ts

@@ -1,7 +0,0 @@
-/**
- * Soroban Flashcard Generator - TypeScript Client
- * Re-export main client functionality
- */
-
-export * from "./soroban-flashcards";
-export { SorobanFlashcardClient as default } from "./soroban-flashcards";

packages/core/client/typescript/src/soroban-flashcards.ts

@@ -1,176 +0,0 @@
-/**
- * TypeScript client for Soroban Flashcard Generator API
- */
-
-export interface FlashcardConfig {
-  range: string;
-  step?: number;
-  cardsPerPage?: number;
-  paperSize?: "us-letter" | "a4" | "a3" | "a5";
-  orientation?: "portrait" | "landscape";
-  margins?: {
-    top?: string;
-    bottom?: string;
-    left?: string;
-    right?: string;
-  };
-  gutter?: string;
-  shuffle?: boolean;
-  seed?: number;
-  showCutMarks?: boolean;
-  showRegistration?: boolean;
-  fontFamily?: string;
-  fontSize?: string;
-  columns?: string | number;
-  showEmptyColumns?: boolean;
-  hideInactiveBeads?: boolean;
-  beadShape?: "diamond" | "circle" | "square";
-  colorScheme?: "monochrome" | "place-value" | "heaven-earth" | "alternating";
-  coloredNumerals?: boolean;
-  scaleFactor?: number;
-}
-
-export interface FlashcardResponse {
-  pdf: string; // base64 encoded PDF
-  count: number;
-  numbers: number[];
-}
-
-export class SorobanFlashcardClient {
-  private apiUrl: string;
-
-  constructor(apiUrl: string = "http://localhost:8000") {
-    this.apiUrl = apiUrl;
-  }
-
-  /**
-   * Generate flashcards and return as base64 PDF
-   */
-  async generate(config: FlashcardConfig): Promise<FlashcardResponse> {
-    const response = await fetch(`${this.apiUrl}/generate`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        range: config.range,
-        step: config.step ?? 1,
-        cards_per_page: config.cardsPerPage ?? 6,
-        paper_size: config.paperSize ?? "us-letter",
-        orientation: config.orientation ?? "portrait",
-        margins: config.margins ?? {
-          top: "0.5in",
-          bottom: "0.5in",
-          left: "0.5in",
-          right: "0.5in",
-        },
-        gutter: config.gutter ?? "5mm",
-        shuffle: config.shuffle ?? false,
-        seed: config.seed,
-        show_cut_marks: config.showCutMarks ?? false,
-        show_registration: config.showRegistration ?? false,
-        font_family: config.fontFamily ?? "DejaVu Sans",
-        font_size: config.fontSize ?? "48pt",
-        columns: config.columns ?? "auto",
-        show_empty_columns: config.showEmptyColumns ?? false,
-        hide_inactive_beads: config.hideInactiveBeads ?? false,
-        bead_shape: config.beadShape ?? "diamond",
-        color_scheme: config.colorScheme ?? "monochrome",
-        colored_numerals: config.coloredNumerals ?? false,
-        scale_factor: config.scaleFactor ?? 0.9,
-        format: "base64",
-      }),
-    });
-
-    if (!response.ok) {
-      const error = await response.json();
-      throw new Error(error.detail || "Failed to generate flashcards");
-    }
-
-    return response.json();
-  }
-
-  /**
-   * Generate flashcards and download as PDF file
-   */
-  async generateAndDownload(
-    config: FlashcardConfig,
-    filename: string = "flashcards.pdf",
-  ): Promise<void> {
-    const result = await this.generate(config);
-
-    // Convert base64 to blob
-    const pdfBytes = atob(result.pdf);
-    const byteArray = new Uint8Array(pdfBytes.length);
-    for (let i = 0; i < pdfBytes.length; i++) {
-      byteArray[i] = pdfBytes.charCodeAt(i);
-    }
-    const blob = new Blob([byteArray], { type: "application/pdf" });
-
-    // Create download link
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = filename;
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
-    URL.revokeObjectURL(url);
-  }
-
-  /**
-   * Generate flashcards and open in new tab
-   */
-  async generateAndOpen(config: FlashcardConfig): Promise<void> {
-    const result = await this.generate(config);
-
-    // Convert base64 to blob
-    const pdfBytes = atob(result.pdf);
-    const byteArray = new Uint8Array(pdfBytes.length);
-    for (let i = 0; i < pdfBytes.length; i++) {
-      byteArray[i] = pdfBytes.charCodeAt(i);
-    }
-    const blob = new Blob([byteArray], { type: "application/pdf" });
-
-    // Open in new tab
-    const url = URL.createObjectURL(blob);
-    window.open(url, "_blank");
-  }
-
-  /**
-   * Check API health
-   */
-  async health(): Promise<boolean> {
-    try {
-      const response = await fetch(`${this.apiUrl}/health`);
-      const data = await response.json();
-      return data.status === "healthy";
-    } catch {
-      return false;
-    }
-  }
-}
-
-// Example usage function
-export async function example() {
-  const client = new SorobanFlashcardClient();
-
-  // Generate and download flashcards for 0-99 with place-value coloring
-  await client.generateAndDownload({
-    range: "0-99",
-    cardsPerPage: 6,
-    colorScheme: "place-value",
-    coloredNumerals: true,
-    showCutMarks: true,
-  });
-
-  // Generate counting by 5s
-  await client.generateAndDownload(
-    {
-      range: "0-100",
-      step: 5,
-      cardsPerPage: 6,
-    },
-    "counting-by-5s.pdf",
-  );
-}

packages/core/src/bridge.py

@@ -1,303 +0,0 @@
-#!/usr/bin/env python3
-"""
-Python bridge for Node.js integration
-Provides a clean function interface instead of CLI
-"""
-
-import json
-import sys
-import base64
-import tempfile
-import os
-import glob
-from pathlib import Path
-import subprocess
-
-# Import our existing functions
-from generate import parse_range, generate_typst_file, generate_single_card_typst
-
-def generate_flashcards_json(config_json):
-    """
-    Generate flashcards from JSON config
-    Returns base64 encoded PDF
-    """
-    config = json.loads(config_json)
-    
-    # Parse numbers
-    numbers = parse_range(
-        config.get('range', '0-9'),
-        config.get('step', 1)
-    )
-    
-    # Handle shuffle
-    if config.get('shuffle', False):
-        import random
-        if 'seed' in config:
-            random.seed(config['seed'])
-        random.shuffle(numbers)
-    
-    # Build Typst config
-    typst_config = {
-        'cards_per_page': config.get('cardsPerPage', 6),
-        'paper_size': config.get('paperSize', 'us-letter'),
-        'orientation': config.get('orientation', 'portrait'),
-        'margins': config.get('margins', {
-            'top': '0.5in',
-            'bottom': '0.5in',
-            'left': '0.5in',
-            'right': '0.5in'
-        }),
-        'gutter': config.get('gutter', '5mm'),
-        'show_cut_marks': config.get('showCutMarks', False),
-        'show_registration': config.get('showRegistration', False),
-        'font_family': config.get('fontFamily', 'DejaVu Sans'),
-        'font_size': config.get('fontSize', '48pt'),
-        'columns': config.get('columns', 'auto'),
-        'show_empty_columns': config.get('showEmptyColumns', False),
-        'hide_inactive_beads': config.get('hideInactiveBeads', False),
-        'bead_shape': config.get('beadShape', 'diamond'),
-        'color_scheme': config.get('colorScheme', 'monochrome'),
-        'colored_numerals': config.get('coloredNumerals', False),
-        'scale_factor': config.get('scaleFactor', 0.9),
-    }
-    
-    # Generate in core package directory to match main generator behavior
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmpdir_path = Path(tmpdir)
-
-        # Generate Typst file - same setup as main generate.py
-        core_package_root = Path(__file__).parent.parent  # packages/core directory
-
-        # Create temp files in core package root, not temp directory
-        temp_typst = core_package_root / f'temp_flashcards_{os.getpid()}.typ'
-        temp_pdf = core_package_root / f'temp_flashcards_{os.getpid()}.pdf'
-        
-        # Convert Python list to Typst array syntax (same as main generate.py)
-        if numbers:
-            numbers_str = '(' + ', '.join(str(n) for n in numbers) + ',)'
-        else:
-            numbers_str = '()'
-
-        # Create temp Typst with relative imports (works when run from core package root)
-        typst_content = f'''
-#import "templates/flashcards.typ": generate-flashcards
-
-#generate-flashcards(
-  {numbers_str},
-  cards-per-page: {typst_config['cards_per_page']},
-  paper-size: "{typst_config['paper_size']}",
-  orientation: "{typst_config['orientation']}",
-  margins: (
-    top: {typst_config['margins'].get('top', '0.5in')},
-    bottom: {typst_config['margins'].get('bottom', '0.5in')},
-    left: {typst_config['margins'].get('left', '0.5in')},
-    right: {typst_config['margins'].get('right', '0.5in')}
-  ),
-  gutter: {typst_config['gutter']},
-  show-cut-marks: {str(typst_config['show_cut_marks']).lower()},
-  show-registration: {str(typst_config['show_registration']).lower()},
-  font-family: "{typst_config['font_family']}",
-  font-size: {typst_config['font_size']},
-  columns: {typst_config['columns']},
-  show-empty-columns: {str(typst_config['show_empty_columns']).lower()},
-  hide-inactive-beads: {str(typst_config['hide_inactive_beads']).lower()},
-  bead-shape: "{typst_config['bead_shape']}",
-  color-scheme: "{typst_config['color_scheme']}",
-  colored-numerals: {str(typst_config['colored_numerals']).lower()},
-  scale-factor: {typst_config['scale_factor']}
-)
-'''
-        
-        with open(temp_typst, 'w') as f:
-            f.write(typst_content)
-        
-        # Get format preference
-        output_format = config.get('format', 'pdf').lower()
-        temp_svg = None
-
-        try:
-            if output_format == 'svg':
-                # Generate SVG using Typst with page template for multi-page support
-                temp_svg = core_package_root / f'temp_flashcards_{os.getpid()}_{{p}}.svg'
-                result = subprocess.run(
-                    ['typst', 'compile', str(temp_typst), str(temp_svg), '--format', 'svg'],
-                    capture_output=True,
-                    text=True,
-                    cwd=str(core_package_root)
-                )
-
-                if result.returncode != 0:
-                    return json.dumps({
-                        'error': f'Typst SVG compilation failed: {result.stderr}'
-                    })
-
-                # Read SVG content - find the first generated page
-                svg_pattern = core_package_root / f'temp_flashcards_{os.getpid()}_*.svg'
-                import glob
-                svg_files = glob.glob(str(svg_pattern))
-
-                if not svg_files:
-                    return json.dumps({
-                        'error': 'No SVG files were generated'
-                    })
-
-                # Read the first SVG file (page 1)
-                svg_file = Path(svg_files[0])
-                with open(svg_file, 'r', encoding='utf-8') as f:
-                    svg_content = f.read()
-
-                # Clean up all generated SVG files
-                for svg_path in svg_files:
-                    Path(svg_path).unlink()
-
-                result_data = {
-                    'pdf': svg_content,  # Keep field name for compatibility
-                    'count': len(numbers),
-                    'numbers': numbers[:100]
-                }
-            else:
-                # Generate PDF (default)
-                result = subprocess.run(
-                    ['typst', 'compile', str(temp_typst), str(temp_pdf)],
-                    capture_output=True,
-                    text=True,
-                    cwd=str(core_package_root)
-                )
-
-                if result.returncode != 0:
-                    return json.dumps({
-                        'error': f'Typst compilation failed: {result.stderr}'
-                    })
-
-                # Read and encode PDF
-                with open(temp_pdf, 'rb') as f:
-                    pdf_bytes = f.read()
-
-                result_data = {
-                    'pdf': base64.b64encode(pdf_bytes).decode('utf-8'),
-                    'count': len(numbers),
-                    'numbers': numbers[:100]  # Limit preview
-                }
-        finally:
-            # Clean up temp files
-            for temp_file in [temp_typst, temp_pdf, temp_svg if output_format == 'svg' else None]:
-                if temp_file and temp_file.exists():
-                    temp_file.unlink()
-
-        return json.dumps(result_data)
-
-def generate_single_card_json(config_json):
-    """
-    Generate a single card SVG from JSON config
-    Specifically for preview - always returns front side (abacus)
-    """
-    config = json.loads(config_json)
-
-    # Extract the single number
-    number = config.get('number')
-    if number is None:
-        return json.dumps({'error': 'Missing number parameter'})
-
-    # Build Typst config optimized for preview display
-    typst_config = {
-        'bead_shape': config.get('beadShape', 'diamond'),
-        'color_scheme': config.get('colorScheme', 'monochrome'),
-        'color_palette': config.get('colorPalette', 'default'),
-        'colored_numerals': config.get('coloredNumerals', False),
-        'hide_inactive_beads': config.get('hideInactiveBeads', False),
-        'show_empty_columns': config.get('showEmptyColumns', False),
-        'columns': config.get('columns', 'auto'),
-        'transparent': config.get('transparent', False),
-        'card_width': '120pt',    # Smaller card for larger abacus
-        'card_height': '160pt',   # Smaller card for larger abacus
-        'font_size': config.get('fontSize', '48pt'),
-        'font_family': config.get('fontFamily', 'DejaVu Sans'),
-        'scale_factor': config.get('scaleFactor', 4.0),  # Much larger scale for preview visibility
-    }
-
-    # Generate in core package directory
-    core_package_root = Path(__file__).parent.parent
-    temp_typst = core_package_root / f'temp_single_{number}_{os.getpid()}.typ'
-    temp_svg = core_package_root / f'temp_single_{number}_{os.getpid()}.svg'
-
-    try:
-        # Create single card content directly with correct template path
-        typst_content = f'''
-#import "templates/single-card.typ": generate-single-card
-
-#generate-single-card(
-  {number},
-  side: "front",
-  bead-shape: "{typst_config['bead_shape']}",
-  color-scheme: "{typst_config['color_scheme']}",
-  color-palette: "{typst_config['color_palette']}",
-  colored-numerals: {str(typst_config['colored_numerals']).lower()},
-  hide-inactive-beads: {str(typst_config['hide_inactive_beads']).lower()},
-  show-empty-columns: {str(typst_config['show_empty_columns']).lower()},
-  columns: {typst_config['columns']},
-  transparent: {str(typst_config['transparent']).lower()},
-  width: {typst_config['card_width']},
-  height: {typst_config['card_height']},
-  font-size: {typst_config['font_size']},
-  font-family: "{typst_config['font_family']}",
-  scale-factor: {typst_config['scale_factor']}
-)
-'''
-
-        with open(temp_typst, 'w') as f:
-            f.write(typst_content)
-
-        # Generate SVG
-        result = subprocess.run(
-            ['typst', 'compile', str(temp_typst), str(temp_svg), '--format', 'svg'],
-            capture_output=True,
-            text=True,
-            cwd=str(core_package_root)
-        )
-
-        if result.returncode != 0:
-            return json.dumps({
-                'error': f'Typst SVG compilation failed: {result.stderr}'
-            })
-
-        # Read SVG content
-        if not temp_svg.exists():
-            return json.dumps({
-                'error': 'SVG file was not generated'
-            })
-
-        with open(temp_svg, 'r', encoding='utf-8') as f:
-            svg_content = f.read()
-
-        return json.dumps({
-            'pdf': svg_content,  # Keep field name for compatibility
-            'count': 1,
-            'numbers': [number]
-        })
-
-    except Exception as e:
-        return json.dumps({'error': f'Single card generation failed: {str(e)}'})
-    finally:
-        # Clean up temp files
-        for temp_file in [temp_typst, temp_svg]:
-            if temp_file and temp_file.exists():
-                temp_file.unlink()
-
-if __name__ == '__main__':
-    # Read JSON from stdin, write JSON to stdout
-    # This allows clean function-like communication
-    for line in sys.stdin:
-        try:
-            config = json.loads(line.strip())
-
-            # Check if this is a single-card generation request
-            if config.get('mode') == 'single-card':
-                result = generate_single_card_json(line.strip())
-            else:
-                result = generate_flashcards_json(line.strip())
-
-            print(result)
-            sys.stdout.flush()
-        except Exception as e:
-            print(json.dumps({'error': str(e)}))
-            sys.stdout.flush()

pnpm-lock.yaml

@@ -119,9 +119,6 @@ importers:
       '@soroban/abacus-react':
         specifier: workspace:*
         version: link:../../packages/abacus-react
-      '@soroban/client':
-        specifier: workspace:*
-        version: link:../../packages/core/client/typescript
       '@soroban/core':
         specifier: workspace:*
         version: link:../../packages/core/client/node
@@ -380,42 +377,7 @@ importers:
         specifier: ^1.0.0
         version: 1.6.1(@types/node@20.19.19)(@vitest/ui@3.2.4)(happy-dom@18.0.1)(jsdom@27.0.0(postcss@8.5.6))(terser@5.44.0)
 
-  packages/core/client/browser:
-    dependencies:
-      '@myriaddreamin/typst-ts-renderer':
-        specifier: ^0.6.0
-        version: 0.6.0
-      '@myriaddreamin/typst-ts-web-compiler':
-        specifier: ^0.6.0
-        version: 0.6.0
-    devDependencies:
-      typescript:
-        specifier: ^5.0.0
-        version: 5.9.3
-      vite:
-        specifier: ^5.0.0
-        version: 5.4.20(@types/node@20.19.19)(terser@5.44.0)
-
   packages/core/client/node:
-    dependencies:
-      python-shell:
-        specifier: ^5.0.0
-        version: 5.0.0
-    devDependencies:
-      '@types/node':
-        specifier: ^20.0.0
-        version: 20.19.19
-      tsup:
-        specifier: ^7.0.0
-        version: 7.3.0(postcss@8.5.6)(typescript@5.9.3)
-      typescript:
-        specifier: ^5.0.0
-        version: 5.9.3
-      vitest:
-        specifier: ^1.0.0
-        version: 1.6.1(@types/node@20.19.19)(@vitest/ui@3.2.4)(happy-dom@18.0.1)(jsdom@27.0.0(postcss@8.5.6))(terser@5.44.0)
-
-  packages/core/client/typescript:
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1951,12 +1913,6 @@ packages:
       '@types/react': '>=16'
       react: '>=16'
 
-  '@myriaddreamin/typst-ts-renderer@0.6.0':
-    resolution: {integrity: sha512-56Mids4E5Ob6LeEeXDedvmsVnEWnLmc1qeUOeUSruL/zI3S9QXleF/c3Os1FXwJmLuCFbWTEIq8Quh2cXlnxKw==}
-
-  '@myriaddreamin/typst-ts-web-compiler@0.6.0':
-    resolution: {integrity: sha512-P/eIJ5RnfElj0NYzn5PI296t/IwWtgqUyyTMi5Jm5X3V5kZfskkH+LI7mSQe8tEyxwgCvxbxvFe5adinA3K8Gg==}
-
   '@napi-rs/wasm-runtime@0.2.12':
     resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
 
@@ -7767,10 +7723,6 @@ packages:
   python-bridge@1.1.0:
     resolution: {integrity: sha512-qjQ0QB8p9cn/XDeILQH0aP307hV58lrmv0Opjyub68Um7FHdF+ZXlTqyxNkKaXOFk2QSkScoPWwn7U9GGnrkeQ==}
 
-  python-shell@5.0.0:
-    resolution: {integrity: sha512-RUOOOjHLhgR1MIQrCtnEqz/HJ1RMZBIN+REnpSUrfft2bXqXy69fwJASVziWExfFXsR1bCY0TznnHooNsCo0/w==}
-    engines: {node: '>=0.10'}
-
   qs@6.13.0:
     resolution: {integrity: sha512-+38qI9SOr8tfZ4QmJNplMUxqjbe7LKvvZgWdExBOmd+egZTtjLB67Gu0HRX3u/XOq7UU2Nx6nsjvS16Z9uwfpg==}
     engines: {node: '>=0.6'}
@@ -10808,10 +10760,6 @@ snapshots:
       '@types/react': 18.3.26
       react: 18.3.1
 
-  '@myriaddreamin/typst-ts-renderer@0.6.0': {}
-
-  '@myriaddreamin/typst-ts-web-compiler@0.6.0': {}
-
   '@napi-rs/wasm-runtime@0.2.12':
     dependencies:
       '@emnapi/core': 1.5.0
@@ -17636,8 +17584,6 @@ snapshots:
     dependencies:
       bluebird: 3.7.2
 
-  python-shell@5.0.0: {}
-
   qs@6.13.0:
     dependencies:
       side-channel: 1.1.0