Load Space map assets from runtime URLs

README.md

@@ -178,6 +178,14 @@ Set values in `.env` (copy from `.env.local` first).
 | `SIM_GEMINI_MODEL` | `gemini-3.1-flash-lite` | Gemini model used by the simulation |
 | `SIM_CREATIVITY` | `1.0` | Creativity dial for plans/dialogue |
 | `SIM_WELLBEING_VARIABILITY` | `0.75` | Non-LLM variability in wellbeing updates |
+| `MAP_IMAGE_URL` | `""` | Public HTTPS URL for the daytime map displayed in the browser |
+| `MAP_NIGHT_IMAGE_URL` | `""` | Public HTTPS URL for the night-map overlay displayed in the browser |
+| `PATH_IMAGE_URL` | `""` | Public HTTPS URL for the walkable-path PNG used by the backend |
+
+For a Hugging Face Space that keeps images in GitHub, add these as **Variables**
+(not Secrets) in **Settings → Variables and secrets**. Use GitHub raw-content
+URLs, for example `https://raw.githubusercontent.com/OWNER/REPO/main/assets/map.png`.
+Set all three URLs; `PATH_IMAGE_URL` is required for backend route calculation.
 
 ## Project Structure
 
@@ -210,4 +218,4 @@ requirements.txt     # Python dependencies
 1. Fork and create a feature branch.
 2. Keep changes focused and documented.
 3. Validate local run paths before opening a PR.
-4. Include a clear summary of behavior changes and test notes.
+4. Include a clear summary of behavior changes and test notes.

backend/Odin.py

@@ -962,6 +962,20 @@ def get_entrypoints():
         return json.load(f)
 
 
+@app.get("/api/assets")
+def get_asset_urls():
+    """Return public map URLs configured on the running Space.
+
+    Hugging Face Space variables are runtime environment variables, while the
+    Vite bundle is built earlier. The browser reads this endpoint so changing
+    a Space variable does not require committing image files to the Space.
+    """
+    return {
+        "map_image_url": os.environ.get("MAP_IMAGE_URL", "").strip(),
+        "night_image_url": os.environ.get("MAP_NIGHT_IMAGE_URL", "").strip(),
+    }
+
+
 # Serve React production build (dist/) if it exists, else fallback to frontend/
 import mimetypes
 # On Windows, the registry often maps .js to text/plain, which makes browsers

backend/pathfinder.py

@@ -6,7 +6,10 @@ BFS shortest_path(), stats(), and is_walkable() helpers.
 
 import os
 import threading
+from io import BytesIO
 from collections import deque
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
 from PIL import Image
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -31,10 +34,24 @@ def _load():
             os.path.join(ROOT, "frontend", "path.png"),
             os.path.join(ROOT, "frontend", "dist", "path.png"),
         ]
+        path_file = next((p for p in candidates if os.path.exists(p)), None)
+        path_url = os.environ.get("PATH_IMAGE_URL", "").strip()
         try:
-            if path_file is None:
-                raise FileNotFoundError("path.png not found in frontend/public, frontend, or frontend/dist")
-            with Image.open(path_file) as image:
+            if path_file:
+                image_source = path_file
+            else:
+                if not path_url:
+                    raise FileNotFoundError("path.png not found and PATH_IMAGE_URL is not configured")
+                if urlparse(path_url).scheme != "https":
+                    raise ValueError("PATH_IMAGE_URL must be an https URL")
+                request = Request(path_url, headers={"User-Agent": "Valhalla/1.0"})
+                with urlopen(request, timeout=20) as response:
+                    image_bytes = response.read(20 * 1024 * 1024 + 1)
+                if len(image_bytes) > 20 * 1024 * 1024:
+                    raise ValueError("PATH_IMAGE_URL exceeds the 20 MB download limit")
+                image_source = BytesIO(image_bytes)
+
+            with Image.open(image_source) as image:
                 rgb = image.convert("RGB")
                 _W, _H = rgb.size
                 pix = rgb.load()

frontend/src/components/SimCanvas.jsx

@@ -26,32 +26,46 @@ export default function SimCanvas({ snapshot, focusedId, onFocus }) {
 
   useEffect(() => { focusRef.current = focusedId; }, [focusedId]);
 
-  // Load map images with candidate path fallbacks
+  // Read URLs from the backend so Hugging Face Space variables work at runtime.
   useEffect(() => {
-    const tryLoadImage = (filename, onLoaded) => {
+    let disposed = false;
+    const tryLoadImage = (urls, filename, onLoaded) => {
       const baseUrl = import.meta.env?.BASE_URL || "/";
       const cleanBase = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
-      const candidates = [
-        filename,
-        `./${filename}`,
-        `/${filename}`,
-        `${cleanBase}${filename}`
-      ];
+      const candidates = [...urls, filename, `./${filename}`, `/${filename}`, `${cleanBase}${filename}`];
       let idx = 0;
       const loadNext = () => {
         if (idx >= candidates.length) return;
         const img = new Image();
         const src = candidates[idx++];
-        img.onload = () => onLoaded(img);
+        img.onload = () => { if (!disposed) onLoaded(img); };
         img.onerror = () => loadNext();
         img.src = src;
       };
       loadNext();
     };
 
-    tryLoadImage("map.png", (img) => { mapImgRef.current = img; });
-    tryLoadImage("map_night.png", (img) => { nightImgRef.current = img; });
-    startLoop();
+    async function loadMaps() {
+      let assets = {};
+      try {
+        const response = await fetch(`${import.meta.env.BASE_URL}api/assets`);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        assets = await response.json();
+      } catch (error) {
+        console.warn("Could not read remote map configuration; using local assets.", error);
+      }
+      if (disposed) return;
+      tryLoadImage(assets.map_image_url ? [assets.map_image_url] : [], "map.png", (img) => {
+        mapImgRef.current = img;
+      });
+      tryLoadImage(assets.night_image_url ? [assets.night_image_url] : [], "map_night.png", (img) => {
+        nightImgRef.current = img;
+      });
+      startLoop();
+    }
+
+    loadMaps();
+    return () => { disposed = true; };
   }, []);
 
   // Update targets from snapshot