WebSocket server:
- WS auth via Better Auth session on upgrade request
- Router with discriminated union dispatch and two-layer error handling
- In-memory connections map with broadcastToLobby
- Lobby handlers: join, leave, start
- Game handlers: answer, resolve round, end game, game:ready for state sync
- Shared game state store (LobbyGameStore interface + InMemory impl)
- Timer map separate from store for Valkey-readiness
REST API:
- POST /api/v1/lobbies — create lobby + add host as first player
- POST /api/v1/lobbies/:code/join — atomic join with capacity/status checks
- getLobbyWithPlayers added to model for id-based lookup
Frontend:
- WsClient class with typed on/off, connect/disconnect, isConnected
- WsProvider owns connection lifecycle (connect/disconnect/isConnected state)
- WsConnector component triggers connection at multiplayer layout mount
- Lobby waiting room: live player list, copyable code, host Start button
- Game view: reuses QuestionCard, game:ready on mount, round results
- MultiplayerScoreScreen: sorted scores, winner highlight, tie handling
- Vite proxy: /ws and /api proxied to localhost:3000 for dev cookie fix
Tests:
- lobbyService.test.ts: create, join, retry, idempotency, full lobby
- auth.test.ts: 401 reject, upgrade success, 500 on error
- router.test.ts: dispatch all message types, error handling
- vitest.config.ts: exclude dist folder
Fixes:
- server.ts: server.listen() instead of app.listen() for WS support
- StrictMode removed from main.tsx (incompatible with WS lifecycle)
- getLobbyWithPlayers(id) added for handleLobbyStart lookup
- server.ts: switch from app.listen() to server.listen() so WebSocket
upgrade handler is on the same server as HTTP requests
- lobbyService: add host as first player on lobby creation
- ws-client: guard against reconnect when already connecting
- ws-provider: skip connect if already connected
- Add Play link to /play
- Add Multiplayer link to /multiplayer
- Remove About link (route kept, just not linked)
- Simplify signOut onClick to .then() chain
- lobby.$code.tsx: waiting room with live player list via lobby:state,
copyable lobby code, host Start Game button (disabled until 2+ players),
sends lobby:join on connect, lobby:leave on unmount
- game.$code.tsx: in-game view, sends game:ready on mount to get current
question, handles game:question/answer_result/finished messages,
reuses QuestionCard component, shows round results after each answer
- MultiplayerScoreScreen: final score screen sorted by score, highlights
winner(s) with crown, handles ties via winnerIds array, Play Again
navigates back to lobby, Leave goes to multiplayer landing
- GameRouteSearchSchema added to shared for typed lobbyId search param
without requiring Zod in apps/web
- connects WebSocket on mount, sends lobby:join after connection open
- registers handlers for lobby:state, game:question, error messages
- lobby:state updates player list in real time
- game:question navigates to game route (server re-sends via game:ready)
- displays lobby code as copyable button
- host sees Start Game button, disabled until 2+ players connected
- non-host sees waiting message
- cleanup sends lobby:leave and disconnects on unmount
- lobbyIdRef tracks lobby id for reliable cleanup before lobby state arrives
- WsGameReadySchema added to shared schemas and WsClientMessageSchema
- handleGameReady sends current game:question directly to requesting
client socket (not broadcast) — foundation for reconnection slice
- router dispatches game:ready to handleGameReady handler
- multiplayer.tsx: layout route wrapping all multiplayer children
with WsProvider, auth guard via beforeLoad
- multiplayer/index.tsx: create/join landing page
- POST /api/v1/lobbies to create, navigates to lobby waiting room
- POST /api/v1/lobbies/:code/join to join, normalizes code to
uppercase before sending
- loading states per action, error display, Enter key on join input
- imports Lobby type from @lila/shared (single source of truth)
- connect(apiUrl) derives wss:// from https:// automatically, returns
Promise<void> resolving on open, rejecting on error
- disconnect() closes connection, no-op if already closed
- isConnected() checks readyState === OPEN
- send(message) typed to WsClientMessage discriminated union
- on/off typed with Extract<WsServerMessage, { type: T }> for
precise callback narrowing per message type
- callbacks stored as Map<string, Set<fn>> supporting multiple
listeners per message type
- clearCallbacks() for explicit cleanup on provider unmount
- onError/onClose as separate lifecycle properties distinct
from message handlers
- Type response bodies in gameController.test.ts to fix no-unsafe-member-access
- Replace async methods with Promise.resolve() in InMemoryGameSessionStore
and InMemoryLobbyGameStore to satisfy require-await rule
- Add argsIgnorePattern and varsIgnorePattern to eslint config so
underscore-prefixed params are globally ignored
- Fix no-misused-promises in ws/index.ts, lobbyHandlers, gameHandlers,
__root.tsx, login.tsx and play.tsx by using void + .catch()
- Fix no-floating-promises on navigate calls in login.tsx
- Move API_URL outside Play component to fix useCallback dependency warning
- Type fetch response bodies in play.tsx to fix no-unsafe-assignment
- Add only-throw-error: off for route files (TanStack Router throw redirect)
- Remove unused WebSocket import from express.d.ts
- Fix unsafe return in connections.ts by typing empty Map constructor
- Exclude scripts/ folder from eslint
- Add targeted override for better-auth auth-client.ts (upstream typing issue)
- POST /api/v1/lobbies creates a lobby with a Crockford-Base32
6-char code, retrying on unique violation up to 5 times
- POST /api/v1/lobbies/:code/join validates lobby state then
calls the model's atomic addPlayer, idempotent for repeat
joins from the same user
- Routes require authentication via requireAuth
- Add Express Request type augmentation for req.session
- requireAuth now sets req.session after session validation,
so protected handlers can read the user without calling
getSession again
- Add ConflictError (409) alongside existing AppError subclasses
- Add docker-compose.prod.yml and Caddyfile for Caddy reverse proxy
- Add production stages to frontend Dockerfile (nginx for static files)
- Fix monorepo package exports for production builds (dist/src paths)
- Add CORS_ORIGIN env var for cross-origin config
- Add Better Auth baseURL, cookie domain, and trusted origins from env
- Use VITE_API_URL for API calls in auth-client and play route
- Add credentials: include for cross-origin fetch requests
- Remove unused users table from schema
- Update all package names from @glossa/* to @lila/*
- Update all imports, container names, volume names
- Update documentation references
- Recreate database with new credentials
- Add Better Auth config with Google + GitHub social providers
- Mount auth handler on /api/auth/* in Express
- Generate and migrate auth tables (user, session, account, verification)
- Deduplicate term_glosses data for tighter unique constraint
- Drop legacy users table
- Unit tests for createGameSession and evaluateAnswer (14 tests)
- Endpoint tests for POST /game/start and /game/answer via supertest (8 tests)
- Mock @glossa/db — no real database dependency
- Add GameSetup component with Duolingo-style button selectors for
language pair, POS, difficulty, and rounds
- Language swap: selecting the same language for source and target
automatically swaps them instead of allowing duplicates
- Add selection-before-submission flow: user clicks an option to
highlight it, then confirms with a Submit button to prevent misclicks
- Add selected state to OptionButton (purple ring highlight)
- Play Again on score screen returns to settings instead of
auto-restarting with the same configuration
- Remove hardcoded GAME_SETTINGS, game configuration is now user-driven
- Add Vite proxy for /api → localhost:3000 (no CORS needed in dev)
- Create /play route with hardcoded game settings (en→it, nouns, easy)
- Three-phase state machine: loading → playing → finished
- Show prompt, optional gloss, and 4 answer buttons per question
- Submit answers to /api/v1/game/answer, show correct/wrong feedback
- Manual Next button to advance after answering
- Score screen on completion
- Add selectedOptionId to AnswerResult schema (discovered during
frontend work that the result needs to be self-contained for
rendering feedback without separate client state)
Intentionally unstyled — component extraction and polish come next.
Complete the game answer flow:
- Add evaluateAnswer service function: looks up the session in the
GameSessionStore, compares the submitted optionId against the stored
correct answer, returns an AnswerResult.
- Add submitAnswer controller with safeParse validation and error
handling (session/question not found → 404).
- Add POST /api/v1/game/answer route.
- Fix createGameSession: was missing the answerKey tracking and the
gameSessionStore.create() call, so sessions were never persisted.
The full singleplayer game loop now works end-to-end:
POST /game/start → GameSession, POST /game/answer → AnswerResult.
The service now tracks the correct optionId for each question and
stores the answer key in the GameSessionStore after building the
session. The client response is unchanged — the store is invisible
to the outside.
- Build answerKey (questionId → correctOptionId) during question
assembly by finding the correct answer's position after shuffle
- Store the answer key via gameSessionStore.create() before returning
- Add excludeText parameter to getDistractors to prevent a distractor
from having identical text to the correct answer (different term,
same translation). Solved at the query level, not with post-filtering.
- Module-level InMemoryGameSessionStore singleton in the service
Add the session storage infrastructure for tracking correct answers
during a game. Designed for easy swap to Valkey in Phase 4.
- GameSessionStore interface with create/get/delete methods, all async
to match the eventual Valkey implementation
- InMemoryGameSessionStore backed by a Map
- GameSessionData holds only the answer key (questionId → correctOptionId)
- Also fix root build script to build packages in dependency order
Extend the game flow from raw term rows to a complete GameSession
matching the shared schema:
- Add getDistractors model query: fetches N same-POS, same-difficulty,
same-target-language terms excluding a given termId. Returns bare
strings since distractors only need their display text.
- Fix getGameTerms select clause to use the neutral field names
(sourceText, targetText, sourceGloss) that the type already declared.
- Rename gameService entry point to createGameSession; signature now
takes a GameRequest and returns a GameSession.
- Per question: fetch 3 distractors, combine with the correct answer,
shuffle (Fisher-Yates), assign optionIds 0-3 by post-shuffle index,
and assemble into a GameQuestion with a fresh UUID.
- Wrap the questions in a GameSession with its own UUID.
- Run per-question distractor fetches in parallel via Promise.all.
Known gap: the correct option is not yet remembered server-side, so
/game/answer cannot evaluate submissions. SessionStore lands next.
Add the shared schemas for the quiz request/response cycle, defining
the contract between the API and the frontend.
- Reorganise packages/shared: move schemas into a schemas/ subdirectory
grouped by domain. Delete the old flat schema.ts.
- Add AnswerOption, GameQuestion, GameSession, AnswerSubmission, and
AnswerResult alongside the existing GameRequest.
- optionId is an integer 0-3 (positional, shuffled at session-build
time so position carries no information).
- questionId and sessionId are UUIDs (globally unique, opaque, natural
keys for Valkey storage later).
- gloss is rather than optional, for a predictable
shape on the frontend.
- options array enforced to exactly 4 elements at the schema level.
