mtg-online-drafter/docs/development/devlog/2025-12-14-224500_image_caching.md

Image Caching Implementation

Objective

Implement a robust image caching system that downloads card images to the server when creating a draft room, ensuring all players can see images reliably via local serving.

Changes

1. Backend - Image Service (src/server/services/CardService.ts):

   • Created CardService class.
   • Implements cacheImages which downloads images from external URLs to src/server/public/cards.
   • Uses a concurrency limit (5) to avoid rate limiting.
   • Checks for existence before downloading to avoid redundant work.

2. Backend - Server Setup (src/server/index.ts):

   • Enabled static file serving for /cards endpoint mapping to src/server/public/cards.
   • Added POST /api/cards/cache endpoint that accepts a list of cards and triggers cache logic.
   • Increased JSON body limit to 50mb to handle large set payloads.

3. Frontend - Lobby Manager (LobbyManager.tsx):

   • Updated handleCreateRoom workflow.
   • Pre-Creation: Extracts all unique cards from generated packs.
   • Cache Request: Sends list to /api/cards/cache.
   • Transformation: Updates local pack data to point image property to the local server URL (/cards/{scryfallId}.jpg) instead of remote Scryfall URL.
   • This ensures that when create_room is emitted, the room state on the server (and thus all connected clients) contains valid local URLs.

4. Fixes:

   • Addressed GameRoom.tsx crash by replacing require with dynamic imports (or static if preloaded) and fixing clipboard access.
   • Fixed TS imports in server index.

Status

• Image Caching: Functional. Creating a room now triggers a download process on the terminal.
• Local Serving: Cards should now load instantly from the server for all peers.

How to Verify

1. Generate packs in Draft Management.
2. Create a Room. Watch server logs for "Cached image: ..." messages.
3. Join room.
4. Start Draft. Images should appear.