Feature/game framework improvements - #17

src/lib/games/snake/SnakeGame.ts (2)

180-182: Consider defensive handling for empty snake array.

getHead() accesses this.state.snake[0] directly. While the snake should never be empty during normal gameplay (initialized with 3 segments), accessing index 0 on an empty array returns undefined, which doesn't match the Position return type.

🛡️ Optional defensive check

     getHead(): Position {
+        if (this.state.snake.length === 0) {
+            return { x: 0, y: 0 }
+        }
         return this.state.snake[0]
     }

---

246-259: Type inconsistency when calling utility functions.

The generateFoodPosition and isOutOfBounds functions expect a GameConstants interface, but you're passing partial objects with only GRID_WIDTH and GRID_HEIGHT. This works at runtime but creates a type mismatch.

Consider creating a minimal interface or updating the utility functions to accept only the required fields.

src/lib/games/snake/SnakeGame.test.ts (1)

165-181: Consider adding tests for movement and collision scenarios.

The current test suite covers initialization, lifecycle, and callbacks well. However, tests for actual gameplay mechanics would strengthen coverage:

• Snake movement and food consumption
• Wall collision detection
• Self-collision detection
• Game over on timer expiration

These are important for ensuring game state transitions work correctly during gameplay. Based on learnings, tests should ensure proper game state transitions and score submissions.

Would you like me to generate additional test cases for movement and collision scenarios?

src/lib/games/snake/SnakeRenderer.ts (2)

174-182: Address static analysis warning for forEach callback.

The Biome linter flags that the callback should not return a value. While graphic.destroy() returns void (which is fine), the linter prefers explicit handling.

🔧 Proposed fix to satisfy linter

     private clearGameObjects(): void {
         if (this.gameObjectContainer) {
             this.gameObjectContainer.removeChildren()
         }

         // Destroy graphics objects
-        this.graphics.forEach(graphic => graphic.destroy())
+        for (const graphic of this.graphics) {
+            graphic.destroy()
+        }
         this.graphics = []
     }

---

30-47: Consider adding error handling for setup failures.

If super.setup() fails or getApp() returns null, the method exits silently without indication. Per coding guidelines, async operations should include error handling.

🛡️ Optional: Add logging for setup issues

     async setup(): Promise<void> {
         await super.setup()

         const app = this.getApp()
         if (!app) {
+            console.warn('SnakeRenderer: Failed to get PIXI app after setup')
             return
         }

src/lib/games/snake/initFramework.ts (2)

252-274: Consolidate duplicate handler functions.

resetHandler, restartHandler, and playAgainHandler have identical implementations. Consider consolidating into a single handler.

♻️ Proposed consolidation

-    const resetHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
-
-    const restartHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
-
-    const playAgainHandler = () => {
+    const resetHandler = () => {
         game.reset()
         const overlay = document.getElementById('game-over-overlay')
         if (overlay) {
             overlay.classList.add('hidden')
         }
     }
+
+    // Use same handler for all reset-like actions
+    const restartHandler = resetHandler
+    const playAgainHandler = resetHandler

---

132-142: Render loop runs continuously regardless of game state.

The render loop calls renderer.render(game.getState()) on every animation frame, even when the game is paused or not started. While the renderer's needsRedraw flag provides some optimization, consider adding a state check to reduce unnecessary work.

⚡ Optional optimization

     function renderLoop() {
         if (!renderRunning) {
             return
         }
-        renderer.render(game.getState())
+        const state = game.getState()
+        if (state.isActive || state.needsRedraw) {
+            renderer.render(state)
+        }
         renderFrameId = requestAnimationFrame(renderLoop)
     }

src/lib/games/bubble-shooter/init.ts (1)

150-157: Consider adding touch event support for mobile compatibility.

The canvas only registers mouse events. Per coding guidelines, games should implement proper touch and mouse event handling for mobile/desktop compatibility.

♻️ Proposed touch event additions

         // Canvas event listeners
         if (renderer.app && renderer.app.canvas) {
             renderer.app.canvas.addEventListener(
                 'mousemove',
                 canvasMouseMoveHandler
             )
             renderer.app.canvas.addEventListener('click', canvasClickHandler)
+            renderer.app.canvas.addEventListener(
+                'touchmove',
+                (e: TouchEvent) => {
+                    e.preventDefault()
+                    const touch = e.touches[0]
+                    const mouseEvent = new MouseEvent('mousemove', {
+                        clientX: touch.clientX,
+                        clientY: touch.clientY,
+                    })
+                    canvasMouseMoveHandler(mouseEvent)
+                }
+            )
+            renderer.app.canvas.addEventListener(
+                'touchend',
+                (e: TouchEvent) => {
+                    e.preventDefault()
+                    const touch = e.changedTouches[0]
+                    const mouseEvent = new MouseEvent('click', {
+                        clientX: touch.clientX,
+                        clientY: touch.clientY,
+                    })
+                    canvasClickHandler(mouseEvent)
+                }
+            )
         }

As per coding guidelines: "Implement proper touch and mouse event handling for mobile/desktop compatibility".

src/lib/games/shared/utils.ts (1)

187-192: Document deepClone limitations.

The JSON-based clone doesn't handle functions, undefined, Date, RegExp, circular references, or Symbol keys. Consider expanding the JSDoc to warn users.

📝 Proposed documentation enhancement

 /**
  * Deep clone an object (simple version using JSON)
+ * 
+ * Limitations: Does not handle functions, undefined, Date objects,
+ * RegExp, circular references, or Symbol keys.
  */
 export function deepClone<T>(obj: T): T {
     return JSON.parse(JSON.stringify(obj))
 }

src/lib/games/shared/utils.test.ts (1)

199-218: Consider using consistent fake timer setup pattern.

The throttle test manages fake timers inline while debounce uses beforeEach/afterEach. For consistency and to prevent timer leaks in case of test failures, consider using the same pattern.

♻️ Proposed refactor for consistency

 describe('throttle', () => {
+    beforeEach(() => {
+        vi.useFakeTimers()
+    })
+
+    afterEach(() => {
+        vi.useRealTimers()
+    })
+
     it('should throttle function calls', () => {
-        vi.useFakeTimers()
         const fn = vi.fn()
         const throttled = throttle(fn, 100)

         throttled()
         expect(fn).toHaveBeenCalledTimes(1)

         throttled()
         throttled()
         expect(fn).toHaveBeenCalledTimes(1)

         vi.advanceTimersByTime(100)
         throttled()
         expect(fn).toHaveBeenCalledTimes(2)
-
-        vi.useRealTimers()
     })
 })

src/lib/games/core/errors.ts (1)

32-46: Consider using GameErrorCodes constant for error codes.

The error code strings are hardcoded in each class and duplicated in the GameErrorCodes constant below. Using the constant would improve maintainability and prevent potential inconsistencies.

♻️ Suggested refactor

+import { GameErrorCodes } from './errors'
+
 export class GameInitializationError extends GameError {
     constructor(
         message: string,
         options?: {
             context?: Record<string, unknown>
             cause?: Error
         }
     ) {
-        super(message, 'GAME_INIT_ERROR', {
+        super(message, GameErrorCodes.GAME_INIT_ERROR, {
             ...options,
             recoverable: true,
         })
         this.name = 'GameInitializationError'
     }
 }

Apply the same pattern to other error classes (RenderError, DOMElementNotFoundError, etc.).

better-auth_migrations/2025-07-06-schema-consolidation.sql (1)

62-65: Consider a composite index for leaderboard queries.

If you frequently query top scores by game (e.g., WHERE game_id = ? ORDER BY score DESC, created_at DESC), a composite index can drastically reduce sort cost.

🔧 Example composite index

+CREATE INDEX IF NOT EXISTS "idx_game_scores_game_score_created"
+  ON "game_scores" ("game_id", "score" DESC, "created_at" DESC);

src/lib/games/evader/game.test.ts (2)

238-252: Add integration coverage for score submission/achievements and responsive canvas behavior.
This suite validates stats, but it doesn’t assert /api/scores submission, achievement thresholds/in‑game event payloads, or responsive/touch canvas behavior. Consider adding a higher‑level test (likely in init/renderer tests) to cover those flows.

Based on learnings: “Ensure proper game state transitions and score submissions in tests”, “Test achievement score thresholds and in-game event achievements”, and “Verify responsive behavior of game interfaces and canvas elements in tests”.

---

130-162: Make the coin/bomb spawn test deterministic.
The current test only verifies that any object spawns—the .some() check will always pass. To ensure both coin and bomb types can actually spawn, mock Math.random() with specific return values to force each type and verify the expected behavior.

♻️ Proposed refactor (deterministic spawn types)

-        it('should spawn either coins or bombs', () => {
+        it('should deterministically spawn coins and bombs', () => {
+            const randomSpy = vi.spyOn(Math, 'random')
+            randomSpy.mockReturnValueOnce(0.1) // coin
+            randomSpy.mockReturnValueOnce(0.99) // bomb
             game.startGame()
 
-            // Spawn multiple objects
-            vi.advanceTimersByTime(config.spawnInterval * 10 * 1000)
+            vi.advanceTimersByTime(config.spawnInterval * 2 * 1000)
 
             const calls = (
                 mockCallbacks.onObjectSpawn as ReturnType<typeof vi.fn>
             ).mock.calls
             const types = calls.map((call: [GameObject]) => call[0].type)
 
-            expect(types.some(t => t === 'coin' || t === 'bomb')).toBe(true)
+            expect(types).toEqual(['coin', 'bomb'])
+            randomSpy.mockRestore()
         })

src/lib/games/tetris/init.ts (2)

139-142: resetHandler and restartHandler are identical.

Both close over the same arguments and call resetGame(enhancedState, updateNextPieceDisplayFn). You could share a single handler reference to reduce duplication.

♻️ Suggested consolidation

-    const resetHandler = () =>
-        resetGame(enhancedState, updateNextPieceDisplayFn)
-    const restartHandler = () =>
-        resetGame(enhancedState, updateNextPieceDisplayFn)
+    const resetHandler = () =>
+        resetGame(enhancedState, updateNextPieceDisplayFn)
+    const restartHandler = resetHandler

---

23-28: Add window.tetrisGame debug object for consistency with memory-matrix.

Only the memory-matrix game currently exports a window debug object (window.memoryMatrixGame.getGame(), etc.) for development inspection. To align tetris with that pattern, expose a similar debug object in the game instance returned from initTetrisGame().

src/lib/server/db/client.ts (1)

7-15: Mixing process.env and import.meta.env in the same module.

isCi reads from process.env.CI (line 7) while dbUrl falls back to import.meta.env.TURSO_DATABASE_URL (line 11). In Astro's Vite-based build, process.env is only reliably available server-side at runtime, whereas import.meta.env is statically replaced at build time. This works for an SSR server module, but be aware that process.env.CI won't be available if this module is ever bundled for the client or processed by Vite's client transform.

src/lib/server/db/queries.ts (1)

113-126: Redundant try/catch — upsertUserStats already swallows all exceptions.

upsertUserStats (line 57-111) catches every error internally and returns false, so the catch block here is dead code. This is harmless but slightly misleading — readers may expect errors to propagate from upsertUserStats.

♻️ Simplified version (optional)

 export async function updateUserLevel(
     userId: string,
     newLevel: number
 ): Promise<boolean> {
-    try {
-        return await upsertUserStats(userId, { level: newLevel })
-    } catch (error) {
-        console.error('[updateUserLevel] Error:', sanitizeError(error))
-        return false
-    }
+    return upsertUserStats(userId, { level: newLevel })
 }

src/lib/services/challengeService.ts (1)

236-240: Duplicate JSDoc block.

Lines 236–240 contain two consecutive doc comments for checkAndUpdateStreak — one is a stale leftover.

♻️ Remove duplicate JSDoc

-/**
- * Check if all daily challenges are completed and update streak
- */
 /**
  * Check if all daily challenges are completed and update streak atomically
  */
 async function checkAndUpdateStreak(userId: string): Promise<void> {

src/lib/games/snake/SnakeRenderer.ts (1)

174-182: Satisfy Biome linter: avoid implicit return in forEach callback.

The arrow function graphic => graphic.destroy() implicitly returns the result of destroy(). Biome's useIterableCallbackReturn flags this for forEach.

Suggested fix

-        this.graphics.forEach(graphic => graphic.destroy())
+        this.graphics.forEach(graphic => { graphic.destroy() })

src/lib/games/snake/initFramework.ts (3)

141-154: Render loop duplicates rendering already done by onStateChange callback.

The onStateChange callback (line 66) already calls renderer.render(state) on every state change. This separate rAF loop renders the same state again before markRendered() clears needsRedraw. Consider removing renderer.render from the callback and relying solely on this loop, which already handles markRendered().

Suggested fix: remove render from callback

         onStateChange: state => {
-            renderer.render(state)
             updateUI(state as ReturnType<SnakeGame['getState']>)
             customCallbacks?.onStateChange?.(state)
         },

---

285-299: restartHandler and playAgainHandler are identical.

Both handlers call game.reset() and hide the overlay. Consider sharing a single handler function.

Suggested deduplication

-    const restartHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
-
-    const playAgainHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
+    const restartHandler = () => {
+        game.reset()
+        const overlay = document.getElementById('game-over-overlay')
+        if (overlay) {
+            overlay.classList.add('hidden')
+        }
+    }
+
+    const playAgainHandler = restartHandler

---

113-127: Unsafe casting of event data for achievement notifications.

The chain (event as { data: unknown }).data as { newAchievements?: ... } silently swallows structural mismatches. If the end event payload shape changes, this won't surface an error — it'll just skip notifications. Consider adding a lightweight guard instead of double-casting.

src/lib/games/core/ScoreManager.ts (1)

141-149: Non-OK responses are silently treated as failure.

When response.ok is false, the method returns { success: false } without logging the HTTP status or response body. This makes it hard to diagnose server-side issues (e.g., 401, 500).

Suggested improvement

             if (response.ok) {
                 const result = await response.json()
                 return {
                     success: true,
                     newAchievements: result.newAchievements,
                 }
             } else {
+                console.error(`[ScoreManager] Score save failed: ${response.status} ${response.statusText}`)
                 return { success: false }
             }

src/lib/games/snake/SnakeRenderer.ts (1)

200-219: responsive: false — confirm this is intentional for the Snake game.

The config hardcodes responsive: false, which means the canvas won't scale with the viewport. For a fixed-grid game this can be fine, but the coding guidelines call for handling responsive canvas sizing with proper scaling across devices. If this game will be played on mobile, you may need responsive scaling or at least viewport-aware cellSize computation.

src/lib/games/snake/initFramework.ts (4)

130-142: Fragile double type assertion on event payload.

The chain (event as { data: unknown }).data as { newAchievements?: ... } will silently produce undefined if the event shape ever changes. If the BaseGame.on('end', ...) callback has a defined signature, prefer typing the parameter directly. If not, consider adding a runtime guard before accessing .data.

---

281-295: restartHandler and playAgainHandler are identical — extract a shared helper.

Both handlers call game.reset() and hide the overlay. Consolidate into one function to reduce duplication.

Suggested refactor

-    const restartHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
-
-    const playAgainHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
+    const restartHandler = () => {
+        game.reset()
+        const overlay = document.getElementById('game-over-overlay')
+        if (overlay) {
+            overlay.classList.add('hidden')
+        }
+    }
+    const playAgainHandler = restartHandler

---

314-366: No touch/swipe controls for mobile.

The keyboard handler covers WASD and arrow keys, but there's no touch or swipe event handling. The coding guidelines require "proper touch and mouse event handling for mobile/desktop compatibility" and testing canvas functionality across devices. A swipe-to-direction handler would make the Snake game playable on touch devices.

As per coding guidelines: "Implement proper touch and mouse event handling for mobile/desktop compatibility" and "ensure mobile compatibility with touch/mouse event handling in games."

---

344-358: Pause toggle logic is duplicated with pauseHandler (lines 246-259).

The keyboard 'P' handler and the button click handler both implement the same pause/resume + button text update logic. Consider extracting a shared togglePause(game) helper to keep behavior in sync.

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/lib/server/db/client.ts (2)

7-12: Inconsistent env access: process.env vs import.meta.env.

Line 7 reads process.env.CI while line 12 reads import.meta.env.TURSO_DATABASE_URL. In Astro server-side code, import.meta.env includes all environment variables, so import.meta.env.CI would work here too. Consider using one accessor consistently for clarity.

Suggested change

-const isCi = process.env.CI === 'true' || process.env.CI === '1'
+const isCi = import.meta.env.CI === 'true' || import.meta.env.CI === '1'

---

7-16: CI fallback path is constructed but never verified to exist.

When running in CI with no TURSO_DATABASE_URL, the code falls back to db/db.sqlite relative to process.cwd(). If that file doesn't exist, the error will surface later (potentially as a cryptic libsql error) rather than at startup. A brief existence check or a clearer log message when using the fallback would improve debuggability.

src/lib/games/sudoku/game.test.ts (2)

117-188: Consider extracting a helper for finding given / non-given cells.

The nested loop pattern to locate a given or non-given cell is repeated five times across placeNumber and clearCell tests (lines 119–132, 147–160, 172–186, 200–210, 217–228). A small helper like findCell(state, predicate) would reduce duplication and improve readability.

♻️ Example helper extraction

// At the top of the describe block or in a local helper:
function findCell(
    state: GameState,
    predicate: (cell: GameState['grid']['cells'][number][number]) => boolean
): { row: number; col: number } | null {
    for (let r = 0; r < 9; r++) {
        for (let c = 0; c < 9; c++) {
            if (predicate(state.grid.cells[r][c])) {
                return { row: r, col: c }
            }
        }
    }
    return null
}

// Usage in tests:
const given = findCell(state, (cell) => cell.isGiven)
expect(given).not.toBeNull()
selectCell(state, given!.row, given!.col)

---

284-301: calculateScore tests rely on implementation-specific magic numbers.

Line 299 asserts score >= 150 for easy difficulty, which tightly couples this test to the internal scoring formula. If the scoring weights change, this test breaks without an obvious reason. Consider either importing/referencing the difficulty bonus constants or asserting a relative property (e.g., score > 0) to make the test more resilient.

Also, both easyState and hardState on line 293 are freshly initialized (unsolved) puzzles — the assertion that hardState.score > easyState.score only validates the difficulty multiplier, not actual gameplay scoring. A brief comment clarifying this intent would help future readers.

src/lib/games/bubble-shooter/init.ts (4)

22-24: Avoid any for the return type and stats parameter.

Promise<any> loses all type safety on the returned game instance. Consider defining an interface (e.g., BubbleShooterGameInstance) for the return value. Similarly, stats: any on the callback should use a concrete type.

♻️ Suggested typing

+interface BubbleShooterGameInstance {
+  restart: () => void;
+  getState: () => typeof enhancedState;
+  endGame: () => void;
+  cleanup: () => void;
+}
+
-export async function initBubbleShooterGame(callbacks?: {
-    onGameOver?: (finalScore: number, stats: any) => void
-}): Promise<any> {
+export async function initBubbleShooterGame(callbacks?: {
+    onGameOver?: (finalScore: number, stats: GameOverStats) => void
+}): Promise<BubbleShooterGameInstance> {

As per coding guidelines, "Use type annotations for function parameters in TypeScript" and "Implement proper game state management with TypeScript types."

---

136-168: Duplicate handler logic for resetBtn and restartBtn.

Lines 136-151 and 153-168 are identical. Extract a shared handler to reduce duplication.

♻️ Proposed refactor

+    const handleReset = () => {
+        const gameOverOverlay = document.getElementById('game-over-overlay')
+        if (gameOverOverlay) {
+            gameOverOverlay.classList.add('hidden')
+        }
+        resetGame(enhancedState, updateCurrentBubbleDisplayFn, updateNextBubbleDisplayFn)
+    }
+
-    resetBtn?.addEventListener('click', () => { /* ... */ }, { signal })
-    restartBtn?.addEventListener('click', () => { /* ... */ }, { signal })
+    resetBtn?.addEventListener('click', handleReset, { signal })
+    restartBtn?.addEventListener('click', handleReset, { signal })

---

214-248: Missing debug object export per coding guidelines.

The returned game instance doesn't expose a debug object on window. Other games expose window.<gameName>Game.getGame() for development inspection.

♻️ Suggested addition

Add after line 212, before the return:

if (import.meta.env.DEV) {
    (window as any).bubbleShooterGame = {
        getGame: () => enhancedState,
    }
}

As per coding guidelines: "Use game debug objects window.gameNameGame.getGame() for development inspection and debugging."

---

178-188: No touch event listeners for mobile compatibility.

Only mousemove and click are registered on the canvas. For mobile devices, consider also handling touchmove and touchstart/touchend (or using pointer events for unified handling).

As per coding guidelines: "Implement proper touch and mouse event handling for mobile/desktop compatibility" and "Test canvas functionality across devices (mobile/desktop) and ensure mobile compatibility."

src/lib/games/snake/SnakeRenderer.ts (1)

174-184: Consider object pooling for per-frame graphics allocation.

Every redraw creates new PIXI.Graphics objects for all snake segments and food, then destroys them on the next frame. For a snake game the object count is small so this is fine, but if you plan to extend this pattern to games with many more objects, a graphics pool would reduce GC pressure.

src/lib/games/snake/initFramework.ts (5)

130-143: Fragile event data casting.

The onGameEnd handler uses a chain of unsafe casts to extract newAchievements from the event. If the 'end' event emitted by BaseGame doesn't include a .data.newAchievements property, this silently does nothing (which is acceptable), but the double cast on line 132 ((event as { data: unknown }).data as { ... }) is brittle and would benefit from defensive narrowing.

Suggested safer narrowing

     const onGameEnd = (event: unknown) => {
-        const data = (event as { data: unknown }).data as {
-            newAchievements?: AchievementNotification[]
-        }
-        if (data?.newAchievements && data.newAchievements.length > 0) {
+        const eventObj = event as Record<string, unknown> | undefined
+        const data = eventObj?.data as Record<string, unknown> | undefined
+        const newAchievements = data?.newAchievements as AchievementNotification[] | undefined
+        if (newAchievements && newAchievements.length > 0) {
             if (
                 typeof window !== 'undefined' &&
                 typeof window.showAchievementAward === 'function'
             ) {
-                window.showAchievementAward(data.newAchievements)
+                window.showAchievementAward(newAchievements)
             }
         }
     }

---

155-171: Render loop runs unconditionally — even after game over.

The startRenderLoop kicks off a perpetual requestAnimationFrame cycle that never stops on its own. Even after game-over, it continues polling game.getState() every frame. While the needsRedraw check makes it a cheap no-op, this is unnecessary work. Consider stopping the loop when the game ends and restarting it on reset/start.

---

308-322: restartHandler and playAgainHandler are identical — extract a shared handler.

Both handlers call game.reset() and hide the overlay. This duplicated logic can be consolidated.

Suggested deduplication

-    const restartHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
-
-    const playAgainHandler = () => {
-        game.reset()
-        const overlay = document.getElementById('game-over-overlay')
-        if (overlay) {
-            overlay.classList.add('hidden')
-        }
-    }
+    const restartOrPlayAgainHandler = () => {
+        game.reset()
+        const overlay = document.getElementById('game-over-overlay')
+        if (overlay) {
+            overlay.classList.add('hidden')
+        }
+    }

     startBtn?.addEventListener('click', startHandler)
     endBtn?.addEventListener('click', endHandler)
     pauseBtn?.addEventListener('click', pauseHandler)
     resetBtn?.addEventListener('click', resetHandler)
-    restartBtn?.addEventListener('click', restartHandler)
-    playAgainBtn?.addEventListener('click', playAgainHandler)
+    restartBtn?.addEventListener('click', restartOrPlayAgainHandler)
+    playAgainBtn?.addEventListener('click', restartOrPlayAgainHandler)

Update the cleanup function similarly.

---

288-306: Unnecessary re-querying of DOM elements inside resetHandler.

startBtn and endBtn are already captured in the outer scope on lines 263–264. The inner declarations on lines 290–295 shadow them for no reason. Reuse the outer references.

Suggested fix

     const resetHandler = () => {
         game.reset()
-        const startBtn = document.getElementById(
-            'start-btn'
-        ) as HTMLButtonElement | null
-        const endBtn = document.getElementById(
-            'end-btn'
-        ) as HTMLButtonElement | null
         if (startBtn) {
             startBtn.style.display = 'inline-flex'
         }

---

55-69: Minor inconsistency: line 68 uses raw console.error instead of handleGameError.

The primary catch on line 56 correctly uses handleGameError, but the nested cleanup catch on line 68 falls back to console.error. For consistency, use handleGameError here too, though this is a low-severity nit since it's a last-resort cleanup path.