Sprite atlas: all art ships as one 354KB fetch

Each rendered plant was fetching 12 files (base + 11 masks) at 0.4-1.5s
per request on the free tier - a cold garden load fired ~250 requests.
Build now packs all 542 images into a data-URI atlas emitted as a
hashed immutable asset; the client resolves art from it with in-memory
memoization of images, masks, and in-flight loads. Falls back to
network paths if the atlas is missing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitignore

@@ -38,4 +38,7 @@ starter_profiles.json
 # Local dev game state (production state lives in the mounted HF Storage Bucket)
 /data/
 
+# Generated at build time by tools/build-sprite-atlas.mjs
+src/client/spriteAtlas.json
+
 

Dockerfile

@@ -5,6 +5,7 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci
 COPY vite.config.ts ./
+COPY tools ./tools
 COPY src ./src
 COPY public ./public
 RUN npm run build

package.json

@@ -5,7 +5,7 @@
   "license": "BSD-3-Clause",
   "type": "module",
   "scripts": {
-    "build": "vite build",
+    "build": "node tools/build-sprite-atlas.mjs && vite build",
     "dev": "tsx watch src/server/index.ts",
     "dev:client": "vite build --watch",
     "start": "tsx src/server/index.ts",

src/client/game.tsx

@@ -3,6 +3,7 @@ import './index.css';
 import { MatrixRainFxPanel, MatrixRainFxProvider } from './MatrixRainFx';
 
 import { bootTelegram, tgHeaders } from './telegram';
+import atlasUrl from './spriteAtlas.json?url';
 import { StrictMode, useEffect, useMemo, useRef, useState } from 'react';
 import type { CSSProperties } from 'react';
 import { createRoot } from 'react-dom/client';
@@ -472,29 +473,58 @@ function paletteKey(colors: Rgb[]): string {
   return colors.map((color) => color.join('-')).join('_');
 }
 
-function loadSpriteImage(src: string): Promise<HTMLImageElement> {
-  return new Promise((resolve, reject) => {
-    const image = new Image();
-    image.onload = () => resolve(image);
-    image.onerror = () => reject(new Error(`Could not load ${src}`));
-    image.src = src;
-  });
+// All art ships as one atlas of data URIs (built by tools/build-sprite-atlas.mjs)
+// so a garden render costs one cached fetch instead of ~12 requests per plant.
+let spriteAtlasPromise: Promise<Record<string, string>> | null = null;
+function loadSpriteAtlas(): Promise<Record<string, string>> {
+  spriteAtlasPromise ??= fetch(atlasUrl)
+    .then((response) => (response.ok ? (response.json() as Promise<Record<string, string>>) : {}))
+    .catch(() => ({}));
+  return spriteAtlasPromise;
 }
 
-async function loadMaskData(src: string, width: number, height: number): Promise<Uint8ClampedArray> {
-  const image = await loadSpriteImage(src);
-  const canvas = document.createElement('canvas');
-  canvas.width = width;
-  canvas.height = height;
-  const context = canvas.getContext('2d', { willReadFrequently: true });
-  if (!context) throw new Error('Mask canvas unavailable');
-  context.drawImage(image, 0, 0, width, height);
-  const pixels = context.getImageData(0, 0, width, height).data;
-  const mask = new Uint8ClampedArray(width * height);
-  for (let offset = 0, index = 0; offset < pixels.length; offset += 4, index += 1) {
-    mask[index] = pixels[offset] ?? 0;
-  }
-  return mask;
+const spriteImageCache = new Map<string, Promise<HTMLImageElement>>();
+function loadSpriteImage(src: string): Promise<HTMLImageElement> {
+  const cached = spriteImageCache.get(src);
+  if (cached) return cached;
+  const promise = (async () => {
+    const atlas = await loadSpriteAtlas();
+    const resolved = atlas[src] ?? src;
+    return await new Promise<HTMLImageElement>((resolve, reject) => {
+      const image = new Image();
+      image.onload = () => resolve(image);
+      image.onerror = () => reject(new Error(`Could not load ${src}`));
+      image.src = resolved;
+    });
+  })();
+  spriteImageCache.set(src, promise);
+  promise.catch(() => spriteImageCache.delete(src));
+  return promise;
+}
+
+const maskDataCache = new Map<string, Promise<Uint8ClampedArray>>();
+function loadMaskData(src: string, width: number, height: number): Promise<Uint8ClampedArray> {
+  const key = `${src}|${width}x${height}`;
+  const cached = maskDataCache.get(key);
+  if (cached) return cached;
+  const promise = (async () => {
+    const image = await loadSpriteImage(src);
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    if (!context) throw new Error('Mask canvas unavailable');
+    context.drawImage(image, 0, 0, width, height);
+    const pixels = context.getImageData(0, 0, width, height).data;
+    const mask = new Uint8ClampedArray(width * height);
+    for (let offset = 0, index = 0; offset < pixels.length; offset += 4, index += 1) {
+      mask[index] = pixels[offset] ?? 0;
+    }
+    return mask;
+  })();
+  maskDataCache.set(key, promise);
+  promise.catch(() => maskDataCache.delete(key));
+  return promise;
 }
 
 function strongestLayer(layers: Uint8ClampedArray[], pixel: number): [number, number] {

src/client/module.d.ts

@@ -1,3 +1,8 @@
+declare module '*.json?url' {
+  const url: string;
+  export default url;
+}
+
 declare module '*.png' {
   const content: string;
   export default content;

tools/build-sprite-atlas.mjs

@@ -0,0 +1,27 @@
+// Packs all sprite art and masks into one JSON atlas of data URIs, so the
+// client fetches a single cached file instead of ~540 tiny PNGs (12 requests
+// per rendered plant against a slow free-tier host).
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const roots = [
+  ['public/assets_px', '/assets_px'],
+  ['public/assets_masks', '/assets_masks'],
+];
+const atlas = {};
+
+function walk(dir, urlBase) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      walk(path, `${urlBase}/${name}`);
+    } else if (name.endsWith('.png')) {
+      atlas[`${urlBase}/${name}`] = `data:image/png;base64,${readFileSync(path).toString('base64')}`;
+    }
+  }
+}
+
+for (const [dir, base] of roots) walk(dir, base);
+const out = 'src/client/spriteAtlas.json';
+writeFileSync(out, JSON.stringify(atlas));
+console.log(`sprite atlas: ${Object.keys(atlas).length} images, ${(statSync(out).size / 1024).toFixed(0)} KB -> ${out}`);