fix(viewer): recover screen maps created after setup() (#screenmap-250) (#264)

Sketches that never call setScreenMap() in setup() rendered an empty
canvas. The background worker read getScreenMapData() exactly once,
right after extern_setup() returned, but FastLED creates its default
layouts lazily on the first exported frame
(jsFillInMissingScreenMaps), so that single read came back without a
layout for the strip and the renderer had nothing to draw.

- Add modules/core/screenmap_sync.ts with pure helpers that match a
  frame entry's strip_id against the cached screenMaps dictionary.
- Share one fetchScreenMapsFromWasm()/applyScreenMaps() pair between
  the post-setup read and a new refreshScreenMapsIfIncomplete(), which
  runs after extractFrameData() and before the frame is posted or
  drawn, capped at 5 re-fetches per strip.
- Merge rather than replace the cache, so layouts delivered by the
  push-based screenmap_update path survive a partial late re-read, and
  only mark the cache dirty when a strip is actually recovered.
- Add tests/fixtures/wasm_no_screenmap plus a wheel-smoke render check
  that greps the viewer log for the recovery marker, and widen the
  _build.yml log upload glob to pick up the second viewer log.

Refs #250

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: zackees

.github/workflows/_build.yml

@@ -138,7 +138,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: wheel-smoke-log-${{ inputs.runs-on }}-${{ inputs.rust-target || 'native' }}
-          path: ${{ runner.temp }}/fastled-wheel-smoke/artifacts/viewer.log
+          path: ${{ runner.temp }}/fastled-wheel-smoke/artifacts/*.log
           if-no-files-found: warn
 
       - name: Upload wheel

ci/smoke_installed_wheel.sh

@@ -10,7 +10,7 @@ set -euo pipefail
 
 SMOKE_ROOT="$RUNNER_TEMP/fastled-wheel-smoke"
 rm -rf "$SMOKE_ROOT"
-mkdir -p "$SMOKE_ROOT/home" "$SMOKE_ROOT/sketch/data" "$SMOKE_ROOT/artifacts" "$SMOKE_ROOT/asset-origin"
+mkdir -p "$SMOKE_ROOT/home" "$SMOKE_ROOT/sketch/data" "$SMOKE_ROOT/artifacts" "$SMOKE_ROOT/asset-origin" "$SMOKE_ROOT/no-screenmap"
 uv venv "$SMOKE_ROOT/venv" --python "$UV_PYTHON"
 uv pip install --python "$SMOKE_ROOT/venv/bin/python" dist/*.whl
 test -x "$SMOKE_ROOT/venv/bin/uv"
@@ -92,6 +92,39 @@ if width <= 0 or height <= 0:
     raise SystemExit(f"viewer screenshot has invalid dimensions: {width}x{height}")
 PY
 
+# Regression check for issue #250: a sketch with no setScreenMap() call in
+# setup() used to render an empty canvas, because the worker only read
+# getScreenMapData() once, immediately after extern_setup() returned, before
+# FastLED had lazily created its default layout on the first exported frame.
+# The worker now re-reads layouts after a frame and logs the recovery marker
+# below when it picks up the late screen map.
+cp -R "$GITHUB_WORKSPACE/tests/fixtures/wasm_no_screenmap/." "$SMOKE_ROOT/no-screenmap/"
+env -i \
+  HOME="$SMOKE_ROOT/home" \
+  PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
+  "$SMOKE_ROOT/venv/bin/fastled" "$SMOKE_ROOT/no-screenmap" \
+    --check \
+    --test-wait-secs=2 \
+    --test-timeout-secs=240 \
+    --test-ready-timeout-secs=45 \
+    --test-screenshot="$SMOKE_ROOT/artifacts/no-screenmap.png" \
+    --test-log="$SMOKE_ROOT/artifacts/viewer-no-screenmap.log"
+grep -F "[fastled] late screenmap recovered" "$SMOKE_ROOT/artifacts/viewer-no-screenmap.log"
+"$SMOKE_ROOT/venv/bin/python" - "$SMOKE_ROOT/artifacts/no-screenmap.png" <<'PY'
+from pathlib import Path
+import sys
+
+image = Path(sys.argv[1]).read_bytes()
+if image[:8] != b"\x89PNG\r\n\x1a\n":
+    raise SystemExit("viewer screenshot is not a PNG")
+if image[12:16] != b"IHDR" or len(image) < 24:
+    raise SystemExit("viewer screenshot is missing its IHDR header")
+width = int.from_bytes(image[16:20], "big")
+height = int.from_bytes(image[20:24], "big")
+if width <= 0 or height <= 0:
+    raise SystemExit(f"viewer screenshot has invalid dimensions: {width}x{height}")
+PY
+
 if [ "${FASTLED_SAFARI_SMOKE:-0}" = "1" ]; then
   # The viewer run above left the compiled sketch in sketch/fastled_js; the
   # asset origin is still serving, so Safari loads the same program.

src/fastled/frontend/modules/core/fastled_background_worker.ts

@@ -24,6 +24,8 @@
 
 /* global postMessage, self, performance, requestAnimationFrame, cancelAnimationFrame */
 
+import { findStripsMissingLayout } from './screenmap_sync.ts';
+
 // CRITICAL FIX: Workers don't support import maps, but Three.js jsm files use bare "three" imports.
 // Solution: Use local vendor files with patched relative imports to three.module.js
 
@@ -99,6 +101,8 @@ async function loadThreeJSModules() {
  * @property {number} frameCaptureInterval - Milliseconds between frame captures
  * @property {number} lastFrameCaptureTime - Timestamp of last frame capture
  * @property {Object} screenMaps - Dictionary of screenmaps (stripId → screenmap, push-based from C++)
+ * @property {Object} screenMapRefreshAttempts - Late screenmap re-fetch counters per strip id
+ * @property {boolean} screenMapRecoveryReported - Whether the late-recovery notice was already emitted
  */
 
 /**
@@ -142,6 +146,13 @@ const workerState = {
   screenMapsDirty: false, // screenMaps changed and the main thread has not been told yet (main-thread rendering)
   renderOnMainThread: false, // frames are posted to the main thread instead of drawn on an OffscreenCanvas
 
+  // Late screenmap recovery (#250): FastLED fills in default layouts lazily on
+  // the first exported frame (jsFillInMissingScreenMaps), which happens after
+  // the single post-setup getScreenMapData() read in handleStart(). Strips seen
+  // in frame data without a layout are re-fetched for a few frames.
+  screenMapRefreshAttempts: {}, // stripId (string) -> late re-fetches performed for that strip
+  screenMapRecoveryReported: false, // stdout notice emitted once per session
+
   // Audio sample queue - samples buffered here from onmessage, flushed to WASM at frame start
   audioSampleQueue: [],
   audioSampleBufferedOnce: false,
@@ -159,6 +170,9 @@ const performanceMonitor = {
 
 };
 
+/** Maximum late getScreenMapData() re-fetches attempted per strip (#250). */
+const MAX_SCREENMAP_REFRESH_ATTEMPTS = 5;
+
 /**
  * Debug logging in worker context
  * @param {string} level - Log level (LOG, ERROR, TRACE)
@@ -608,6 +622,68 @@ async function initializeGraphicsManager() {
   }
 }
 
+/**
+ * Reads the current screenmap dictionary out of the WASM module.
+ * Shared by the post-setup read in handleStart() and the late refresh in
+ * refreshScreenMapsIfIncomplete() (#250).
+ * @returns {Object|null} Parsed screenmap dictionary, or null when unavailable
+ */
+function fetchScreenMapsFromWasm() {
+  const Module = workerState.fastledModule;
+  if (!Module || !Module.cwrap) {
+    return null;
+  }
+
+  // Bind WASM functions if not already bound (same binding set as extractFrameData)
+  if (!workerState.wasmFunctions) {
+    workerState.wasmFunctions = {
+      getFrameData: Module.cwrap('getFrameData', 'number', ['number']),
+      getScreenMapData: Module.cwrap('getScreenMapData', 'number', ['number']),
+      getStripPixelData: Module.cwrap('getStripPixelData', 'number', ['number', 'number']),
+      freeFrameData: Module.cwrap('freeFrameData', null, ['number'])
+    };
+  }
+
+  const screenMapSizePtr = Module._malloc(4);
+  try {
+    const screenMapDataPtr = workerState.wasmFunctions.getScreenMapData(screenMapSizePtr);
+    if (!screenMapDataPtr) {
+      return null;
+    }
+    try {
+      const screenMapSize = Module.getValue(screenMapSizePtr, 'i32');
+      const screenMapJson = Module.UTF8ToString(screenMapDataPtr, screenMapSize);
+      return JSON.parse(screenMapJson);
+    } finally {
+      workerState.wasmFunctions.freeFrameData(screenMapDataPtr);
+    }
+  } catch (error) {
+    workerLog('ERROR', 'BACKGROUND_WORKER', 'Failed to read screenmap data from WASM', error);
+    return null;
+  } finally {
+    Module._free(screenMapSizePtr);
+  }
+}
+
+/**
+ * Caches a screenmap dictionary and pushes it to the graphics manager.
+ * @param {Object} screenMapData - Dictionary stripId -> screenmap
+ * @param {string} reason - Why the update happened (logging only)
+ */
+function applyScreenMaps(screenMapData, reason) {
+  workerState.screenMaps = screenMapData;
+  workerState.screenMapsDirty = true;
+  if (workerState.graphicsManager && workerState.graphicsManager.updateScreenMap) {
+    workerState.graphicsManager.updateScreenMap(screenMapData);
+    workerLog('LOG', 'BACKGROUND_WORKER', 'ScreenMaps sent to graphics manager', {
+      reason,
+      screenMapCount: Object.keys(screenMapData || {}).length
+    });
+  } else {
+    workerLog('WARN', 'BACKGROUND_WORKER', 'Graphics manager not ready, screenMaps cached for initialization', { reason });
+  }
+}
+
 /**
  * Handles animation start request
  * @param {Object} _payload - Start parameters (unused)
@@ -639,47 +715,16 @@ async function handleStart(_payload) {
     workerState.externFunctions.externSetup();
     workerLog('LOG', 'BACKGROUND_WORKER', 'FastLED setup completed');
 
-    // Poll for screenmap data after setup (C++ setup() has registered screenmaps)
-    // EM_JS push mechanism has linking issues, so we use polling instead
+    // Read the screenmaps registered by C++ setup(). Layouts FastLED creates
+    // lazily on the first exported frame are picked up later by
+    // refreshScreenMapsIfIncomplete() (#250).
     try {
-      const Module = workerState.fastledModule;
-
-      // Bind getScreenMapData if not already bound
-      if (!workerState.wasmFunctions) {
-        workerState.wasmFunctions = {
-          getFrameData: Module.cwrap('getFrameData', 'number', ['number']),
-          getScreenMapData: Module.cwrap('getScreenMapData', 'number', ['number']),
-          getStripPixelData: Module.cwrap('getStripPixelData', 'number', ['number', 'number']),
-          freeFrameData: Module.cwrap('freeFrameData', null, ['number'])
-        };
-      }
-
-      // Fetch screenmap data from C++
-      const screenMapSizePtr = Module._malloc(4);
-      const screenMapDataPtr = workerState.wasmFunctions.getScreenMapData(screenMapSizePtr);
-
-      if (screenMapDataPtr !== 0) {
-        const screenMapSize = Module.getValue(screenMapSizePtr, 'i32');
-        const screenMapJson = Module.UTF8ToString(screenMapDataPtr, screenMapSize);
-        const screenMapData = JSON.parse(screenMapJson);
-
-        // Update worker state and notify graphics manager
-        workerState.screenMaps = screenMapData;
-        workerState.screenMapsDirty = true;
-        if (workerState.graphicsManager && workerState.graphicsManager.updateScreenMap) {
-          workerState.graphicsManager.updateScreenMap(screenMapData);
-          workerLog('LOG', 'BACKGROUND_WORKER', 'ScreenMaps fetched and sent to graphics manager', {
-            screenMapCount: Object.keys(screenMapData).length
-          });
-        }
-
-        // Free the allocated memory
-        workerState.wasmFunctions.freeFrameData(screenMapDataPtr);
+      const screenMapData = fetchScreenMapsFromWasm();
+      if (screenMapData) {
+        applyScreenMaps(screenMapData, 'post-setup');
       } else {
         workerLog('WARN', 'BACKGROUND_WORKER', 'No screenmap data available after setup');
       }
-
-      Module._free(screenMapSizePtr);
     } catch (error) {
       workerLog('ERROR', 'BACKGROUND_WORKER', 'Failed to fetch screenmap data', error);
       // Non-fatal - continue with animation
@@ -977,6 +1022,89 @@ function handleScreenMapUpdate(payload) {
   }
 }
 
+/**
+ * Picks up layouts that FastLED creates after setup() (#250).
+ *
+ * FastLED fills in default screenmaps lazily when a frame is exported
+ * (jsFillInMissingScreenMaps in FastLED's src/platforms/wasm/js_bindings.cpp.hpp),
+ * which is after handleStart()'s single post-setup read. Without this, a sketch
+ * that never calls setScreenMap() (stock Blink) renders an empty canvas.
+ *
+ * Only fetches while a strip in the current frame still has no layout, and gives
+ * up on a strip after MAX_SCREENMAP_REFRESH_ATTEMPTS fetches so a genuinely
+ * layout-less strip cannot cost a JSON parse every frame. The push-based
+ * screenmap_update path (handleScreenMapUpdate) is unaffected.
+ *
+ * NOTE: this worker is mirrored in FastLED at
+ * src/platforms/wasm/compiler/modules/core/fastled_background_worker.ts; that
+ * copy needs the same change (out of scope for this repo).
+ *
+ * @param {Array} frameData - Strip data from extractFrameData()
+ * @returns {boolean} True when a refresh fetch was performed
+ */
+function refreshScreenMapsIfIncomplete(frameData) {
+  if (!Array.isArray(frameData) || frameData.length === 0) {
+    return false;
+  }
+
+  const missing = findStripsMissingLayout(frameData, workerState.screenMaps);
+  if (missing.length === 0) {
+    return false; // every strip already has a layout - nothing to do
+  }
+
+  const attempts = workerState.screenMapRefreshAttempts;
+  const retryable = missing.filter((stripId) => (attempts[stripId] || 0) < MAX_SCREENMAP_REFRESH_ATTEMPTS);
+  if (retryable.length === 0) {
+    return false; // already retried these strips; stop polling
+  }
+  for (const stripId of retryable) {
+    attempts[stripId] = (attempts[stripId] || 0) + 1;
+  }
+
+  const screenMapData = fetchScreenMapsFromWasm();
+  if (!screenMapData || typeof screenMapData !== 'object') {
+    return false;
+  }
+
+  // Merge rather than replace: layouts pushed earlier through the
+  // screenmap_update path must survive a late re-read that happens to return
+  // fewer entries (or an empty dictionary).
+  const merged = Object.assign({}, workerState.screenMaps, screenMapData);
+  const stillMissing = findStripsMissingLayout(frameData, merged);
+  const recovered = missing.filter((stripId) => !stillMissing.includes(stripId));
+  if (recovered.length === 0) {
+    // Nothing new arrived; leave the cache (and its dirty flag) untouched so we
+    // do not re-push identical layouts to the graphics manager every frame.
+    if (stillMissing.length > 0) {
+      workerLog('WARN', 'BACKGROUND_WORKER', 'Strips still have no layout after screenmap refresh', {
+        strips: stillMissing
+      });
+    }
+    return true;
+  }
+
+  applyScreenMaps(merged, 'late-screenmap-refresh');
+
+  if (!workerState.screenMapRecoveryReported) {
+    workerState.screenMapRecoveryReported = true;
+    workerLog('LOG', 'BACKGROUND_WORKER', 'Late screenMaps recovered after first frame', {
+      strips: recovered,
+      frameNumber: workerState.frameCount
+    });
+    // Surface it on the viewer's stdout log so `--test` runs can assert it.
+    postMessage({
+      type: 'stdout',
+      payload: { text: `[fastled] late screenmap recovered for strips ${recovered.join(',')}` }
+    });
+  }
+  if (stillMissing.length > 0) {
+    workerLog('WARN', 'BACKGROUND_WORKER', 'Strips still have no layout after screenmap refresh', {
+      strips: stillMissing
+    });
+  }
+  return true;
+}
+
 /**
  * Handles audio samples from main thread and pushes them to C++ WASM ring buffer.
  * AudioManager runs on the main thread (needs window/document), but Module.ccall()
@@ -1133,6 +1261,11 @@ async function executeFrameLoop(currentTime) {
     const frameData = extractFrameData();
 
     if (frameData) {
+      // Layouts FastLED creates lazily on the first exported frame (#250) only
+      // become visible after getFrameData(); pick them up before rendering so
+      // the dirty screenmaps ride along with this frame.
+      refreshScreenMapsIfIncomplete(frameData);
+
       if (workerState.renderOnMainThread) {
         // No OffscreenCanvas here: hand the frame to the main thread to draw
         postFrameToMainThread(frameData);