Add scene gallery with GIF previews, incremental C++ preview generator, and desktop-scene capture script

[Copilot]

The frontend had no way to browse or preview scenes visually before adding them to a preset. This adds a GIF-based gallery view, a native C++ tool to generate preview GIFs incrementally, and a shell script for capturing previews of scenes that require the desktop application.

Backend

• New GET /scene_preview?name=<scene_name> endpoint — serves <exec_dir>/previews/<scene_name>.gif with path traversal protection
• /list_scenes now includes "has_preview": bool and "needs_desktop": bool per scene; needs_desktop reflects whether a scene requires the desktop app and therefore cannot be rendered headlessly

Frontend

• Scene Gallery page (/gallery) — responsive grid of all scenes; shows animated GIF preview or a "No preview" placeholder; search + "With preview" filter toggle; click any scene to add it directly to an existing preset
• AddScene dialog — now renders the preview GIF (or placeholder) inline when a scene type is selected
• Gallery nav item added to sidebar and mobile bottom nav

Preview Generator (src_preview_gen/main.cpp)

A native C++ tool (preview_gen) that renders each registered scene headlessly and encodes the output as an animated GIF:

• Creates a headless emulator matrix (no window shown) and renders each scene for N frames
• Uses GetPixel() on the FrameCanvas to capture rendered pixel data per frame
• Converts frames to palette-optimized animated GIFs via GraphicsMagick (Magick++)
• Automatically skips scenes where needs_desktop_app() == true — these cannot be rendered headlessly and must be captured with scripts/capture_desktop_preview.sh
• Adds --dump-manifest / --manifest-out mode: emits a JSON array of {name, plugin_name, plugin_path, needs_desktop} for all loaded scenes, used by the incremental CMake target
• Adds --scenes <csv> for explicit scene selection (complements the existing --scene)
• Per-scene crash isolation: each render is wrapped in try/catch; one broken scene never aborts the batch, and existing GIFs for failed scenes are preserved

Desktop-Scene Capture Script (scripts/capture_desktop_preview.sh)

For scenes that require the desktop application (VideoScene, AudioSpectrumScene, ShadertoyScene, etc.), a shell script captures previews from the running emulator window:

• Requires a running emulator + desktop app connected via WebSocket
• Uses xdotool to locate the emulator window and ffmpeg x11grab to record each scene
• Converts recordings to palette-optimised animated GIFs
• Auto-discovers desktop-dependent scenes via the /list_scenes API, or accepts --scenes <csv> to target specific scenes
• Options: --api-url, --output, --scenes, --duration, --fps, --window-title, --no-cleanup

CMake Integration

• plugins/CMakeLists.txt: each matrix plugin target is now appended to a global CMake property MATRIX_PLUGIN_TARGETS so preview targets express correct build-order dependencies on actual plugin .so files
• preview_gen target — builds the generator binary (emulator builds only, ENABLE_EMULATOR=ON)
• generate_scene_previews target — full rebuild of all non-desktop scenes; depends on preview_gen + MATRIX_PLUGIN_TARGETS; writes GIFs to <build_dir>/previews/
• generate_scene_previews_incremental target — fingerprints each scene by its plugin .so mtime+size plus preview settings; regenerates only changed or missing scenes; writes previews_manifest.json for subsequent runs
• GENERATE_SCENE_PREVIEWS option (default ON) — when ON, cmake --install copies the staged GIFs from <build_dir>/previews/ into <install_prefix>/previews/ via install(DIRECTORY) (no longer uses install(CODE) side effects); disable with -DGENERATE_SCENE_PREVIEWS=OFF
• cmake/scripts/incremental_preview.cmake — the CMake script driving the incremental logic: runs preview_gen --dump-manifest, compares fingerprints, and calls preview_gen --scenes <csv> for only the changed subset; falls back to full regen on CMake < 3.19
• Tunable cache variables: PREVIEW_FPS, PREVIEW_FRAMES, PREVIEW_WIDTH, PREVIEW_HEIGHT, PREVIEW_SCENES (manual scene override)
• scripts/build_upload.sh updated: syncs emulator_build/previews/ into the cross-compile install tree before rsync deploy; SKIP_PREVIEWS=1 opt-out for when the emulator build is unavailable

Full deploy workflow:

# 1. Generate/update previews on the host (emulator build)
cmake --build emulator_build --target generate_scene_previews_incremental

# 2. For desktop-dependent scenes (requires running emulator + desktop app)
./scripts/capture_desktop_preview.sh --api-url http://localhost:8080

# 3. Cross-compile and deploy (build_upload.sh syncs previews automatically)
./scripts/build_upload.sh

Original prompt

I want you to make the frontend user experience better. I want you to implement some kind of gallery / preview for the scenes, these previews should be shown with gifs, that the scenes in the plugins themselves should provide (so exposed via the matrix gif). Also I want you to create a simple script / extension to this for me to easily record that preview gifs for each scene, which places the produced gif properly into the right folder

The user has attached the following file paths as relevant context:

• .github/copilot-instructions.md

Created from VS Code.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[sshcrack]

instead of creating a script, actually implement that functionality in the led matrix application and (if possible) register it as a plugin. The rendering of the preview for scenes should be a cmake target, and also if the target install is used, they should be installed in the proper directory so the web frontend can receive them. Serve the gifs in an API endpoint and the web should then get them. Remove the actual script you just created

[sshcrack]

@copilot instead of creating a script, actually implement that functionality in the led matrix application and (if possible) register it as a plugin. The rendering of the preview for scenes should be a cmake target, and also if the target install is used, they should be installed in the proper directory so the web frontend can receive them. Serve the gifs in an API endpoint and the web should then get them. Remove the actual script you just created

Use the GetPixel method for canvases to achieve such a effect. Also make sure the emulator is started in headless mode, if the target for the rendering of the previews is hit. Add a option to disable the rendering on the install target

[Copilot]

@sshcrack The model claude-sonnet-4.6 is not available for your account. This can happen if the model was disabled by your organization's policy or if your Copilot plan doesn't include access to it.

You can try again without specifying a model (just @copilot) to use the default, or choose a different model from the model picker.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: efd8b971-f9bf-4b5c-b08c-6183ad2071ec

[sshcrack]

@copilot instead of creating a script, actually implement that functionality in the led matrix application and (if possible) register it as a plugin. The rendering of the preview for scenes should be a cmake target, and also if the target install is used, they should be installed in the proper directory so the web frontend can receive them. Serve the gifs in an API endpoint and the web should then get them. Remove the actual script you just created

Use the GetPixel method for canvases to achieve such a effect. Also make sure the emulator is started in headless mode, if the target for the rendering of the previews is hit. Add a option to disable the rendering on the install target

[Copilot]

@copilot instead of creating a script, actually implement that functionality in the led matrix application and (if possible) register it as a plugin. The rendering of the preview for scenes should be ...

Done in commit 4b100f3.

• scripts/record_scene_preview.sh removed
• src_preview_gen/main.cpp — C++ implementation using the headless emulator (EmulatorMatrix::Create with headless=true) and GetPixel() to capture rendered frames, then GraphicsMagick to write palette-optimized animated GIFs
• preview_gen CMake target — builds the generator; only available when ENABLE_EMULATOR=ON
• generate_scene_previews CMake target — runs preview_gen from the build tree and writes GIFs to <build_dir>/previews/
• Install step — cmake --install automatically runs preview_gen (controllable via -DGENERATE_SCENE_PREVIEWS=ON/OFF, default ON) and places GIFs in <install_prefix>/previews/; uses build-tree SOs to avoid CMake install-ordering issues with plugin subdirectories
• preview_gen binary is also installed to <install_prefix>/ so users can re-run it manually

[sshcrack]

@copilot

Plan: Incremental Scene Preview Build Pipeline

Use a host-side emulator preview pipeline as a first-class CMake workflow, then package generated previews into the cross-compile install tree for RPi deployment. Keep preview generation optional and incremental by tracking scene-to-plugin ownership and regenerating only scenes belonging to changed plugin shared libraries.

Steps

1. Phase 1: Baseline cleanup and target wiring
2. In root CMake, separate preview generation from install-time side effects by replacing install(CODE)-driven generation with explicit targets and installable artifacts that can be invoked intentionally; keep preview generation disabled/enabled with one option and default ON for emulator workflow. blocks steps 3-7
3. In plugins CMake registration flow, publish matrix plugin target names to parent scope (or a global CMake property) so preview targets can depend on actual plugin targets instead of opaque variables; verify current dependency wiring and remove undefined/misleading target lists. depends on 2
4. Add a dedicated cache/staging directory for generated previews in emulator build tree (for example emulator_build/previews) and install/copy from this staging area into install/previews. depends on 2
5. Phase 2: Scene ownership and incremental invalidation
6. Extend preview_gen with a metadata mode that outputs scene ownership manifest (scene name -> plugin name, plus plugin path/build identity) in JSON; reuse plugin metadata already available through BasicPlugin and loaded plugin records so ownership is computed from loaded plugins rather than heuristics. parallel with 7 after 3
7. Add CMake cache-state manifest handling (for example previews_manifest.json) that stores prior generation fingerprints per scene (plugin .so mtime/hash + preview settings like fps/frames/size + generator version). parallel with 6 after 4
8. Implement incremental selection logic in a CMake script step (or lightweight helper executable/script) that compares current ownership/fingerprints with previous manifest and produces a scene list requiring regeneration; unchanged scenes are skipped. depends on 6 and 7
9. Phase 3: Preview generation execution model
10. Add one full target for all previews and one incremental target that auto-selects changed scenes; both depend on preview_gen and matrix plugin targets, and both set PLUGIN_DIR and library search paths from build outputs (not install outputs). depends on 3 and 8
11. Add a manual override variable for explicit scene selection (comma-separated scene names) that bypasses auto-detection when provided; this supports targeted retries/debugging. depends on 10
12. Ensure generation failures are non-fatal for packaging by emitting warnings and preserving existing previews, matching your decision to continue cross-compile deploys with stale/missing previews when needed. depends on 10
13. Phase 4: Cross-compile packaging integration
14. In cross-compile workflow, add a packaging step that copies host-generated previews into build/install/previews before rsync/upload, without trying to run preview_gen in arm64 build. depends on 4 and 10
15. Update scripts/build_upload.sh workflow documentation/flow so expected order is: emulator preview incremental target -> cross-compile install -> rsync deploy; include opt-out switch to skip preview sync when desired. depends on 14
16. Keep runtime API contract unchanged: server reads get_exec_dir()/previews/SceneName.gif and list_scenes reports has_preview from file existence. No endpoint changes required. parallel with 14-15
17. Phase 5: Documentation and developer UX
18. Update README preview section with new commands for first-run full generation and subsequent incremental generation, including toggle flags and troubleshooting (missing PLUGIN_DIR, missing libs, scene crash behavior). depends on 10 and 15
19. Add CMake preset guidance (or optional extra preset) for emulator with previews ON/OFF and for fast iteration mode to avoid web rebuild when not needed. parallel with 18

Relevant files

• /home/xxx/Documents/cpp/led-matrix/CMakeLists.txt — replace install-time preview execution model with explicit build targets, staging/install rules, option toggles, and cross-workflow integration points.
• /home/xxx/Documents/cpp/led-matrix/plugins/CMakeLists.txt — expose plugin target inventory for reliable preview target dependencies.
• /home/xxx/Documents/cpp/led-matrix/src_preview_gen/main.cpp — add scene ownership manifest mode and stable fingerprint inputs.
• /home/xxx/Documents/cpp/led-matrix/shared/matrix/include/shared/matrix/plugin_loader/loader.h — optional API exposure if needed for scene->plugin mapping retrieval.
• /home/xxx/Documents/cpp/led-matrix/shared/matrix/src/shared/matrix/plugin_loader/loader.cpp — optional implementation support for ownership enumeration from loaded plugins.
• /home/xxx/Documents/cpp/led-matrix/scripts/build_upload.sh — integrate preview asset sync expectations into deploy path.
• /home/xxx/Documents/cpp/led-matrix/CMakePresets.json — optional preset additions/toggles for preview generation behavior.
• /home/xxx/Documents/cpp/led-matrix/README.md — document supported preview build/deploy workflows and flags.
• /home/xxx/Documents/cpp/led-matrix/src_matrix/server/scene_management.cpp — verify unchanged runtime lookup contract for preview serving.

Verification

1. First-run full generation: run emulator configure/build and full preview target, confirm GIF exists for each scene and metadata manifest is produced.
2. Incremental behavior: modify one plugin scene source, rebuild plugin + incremental preview target, confirm only associated scene GIFs are regenerated (timestamps changed only for impacted scenes).
3. Toggle behavior: run with preview generation OFF, confirm build/install succeeds and no new preview generation occurs.
4. Explicit override behavior: run with manual scene list override, confirm only specified scenes regenerate even if others changed.
5. Cross-compile packaging: run cross-compile install/deploy path, verify previews are present on RPi under runtime previews directory and /list_scenes has_preview reflects files.
6. Failure tolerance: force one scene generation failure, confirm process warns and continues, unchanged/stale previews remain deployable.

Decisions

• Generation location: host machine emulator pipeline is canonical source of preview assets.
• Incremental policy: regenerate by plugin change impact, mapped down to scene outputs.
• Cross-compile strictness: do not fail packaging when previews are missing; warn and continue.

Further Considerations

1. Fingerprint strategy recommendation: start with mtime+size for speed, optionally upgrade to content hash if false positives/negatives appear.
2. Scene crash isolation recommendation: run per-scene generation subprocesses for robustness so one broken scene does not abort the whole incremental run.
3. CI recommendation: optionally add a non-blocking preview freshness check job that reports stale previews without failing release builds.

[Copilot]

@sshcrack The model claude-sonnet-4.6 is not available for your account. This can happen if the model was disabled by your organization's policy or if your Copilot plan doesn't include access to it.

You can try again without specifying a model (just @copilot) to use the default, or choose a different model from the model picker.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 40dbb858-fd09-49c7-8e3f-5d8d2ab2c5e8

[sshcrack]

@copilot
@copilot

Plan: Incremental Scene Preview Build Pipeline

Use a host-side emulator preview pipeline as a first-class CMake workflow, then package generated previews into the cross-compile install tree for RPi deployment. Keep preview generation optional and incremental by tracking scene-to-plugin ownership and regenerating only scenes belonging to changed plugin shared libraries.

Steps

1. Phase 1: Baseline cleanup and target wiring
2. In root CMake, separate preview generation from install-time side effects by replacing install(CODE)-driven generation with explicit targets and installable artifacts that can be invoked intentionally; keep preview generation disabled/enabled with one option and default ON for emulator workflow. blocks steps 3-7
3. In plugins CMake registration flow, publish matrix plugin target names to parent scope (or a global CMake property) so preview targets can depend on actual plugin targets instead of opaque variables; verify current dependency wiring and remove undefined/misleading target lists. depends on 2
4. Add a dedicated cache/staging directory for generated previews in emulator build tree (for example emulator_build/previews) and install/copy from this staging area into install/previews. depends on 2
5. Phase 2: Scene ownership and incremental invalidation
6. Extend preview_gen with a metadata mode that outputs scene ownership manifest (scene name -> plugin name, plus plugin path/build identity) in JSON; reuse plugin metadata already available through BasicPlugin and loaded plugin records so ownership is computed from loaded plugins rather than heuristics. parallel with 7 after 3
7. Add CMake cache-state manifest handling (for example previews_manifest.json) that stores prior generation fingerprints per scene (plugin .so mtime/hash + preview settings like fps/frames/size + generator version). parallel with 6 after 4
8. Implement incremental selection logic in a CMake script step (or lightweight helper executable/script) that compares current ownership/fingerprints with previous manifest and produces a scene list requiring regeneration; unchanged scenes are skipped. depends on 6 and 7
9. Phase 3: Preview generation execution model
10. Add one full target for all previews and one incremental target that auto-selects changed scenes; both depend on preview_gen and matrix plugin targets, and both set PLUGIN_DIR and library search paths from build outputs (not install outputs). depends on 3 and 8
11. Add a manual override variable for explicit scene selection (comma-separated scene names) that bypasses auto-detection when provided; this supports targeted retries/debugging. depends on 10
12. Ensure generation failures are non-fatal for packaging by emitting warnings and preserving existing previews, matching your decision to continue cross-compile deploys with stale/missing previews when needed. depends on 10
13. Phase 4: Cross-compile packaging integration
14. In cross-compile workflow, add a packaging step that copies host-generated previews into build/install/previews before rsync/upload, without trying to run preview_gen in arm64 build. depends on 4 and 10
15. Update scripts/build_upload.sh workflow documentation/flow so expected order is: emulator preview incremental target -> cross-compile install -> rsync deploy; include opt-out switch to skip preview sync when desired. depends on 14
16. Keep runtime API contract unchanged: server reads get_exec_dir()/previews/SceneName.gif and list_scenes reports has_preview from file existence. No endpoint changes required. parallel with 14-15
17. Phase 5: Documentation and developer UX
18. Update README preview section with new commands for first-run full generation and subsequent incremental generation, including toggle flags and troubleshooting (missing PLUGIN_DIR, missing libs, scene crash behavior). depends on 10 and 15
19. Add CMake preset guidance (or optional extra preset) for emulator with previews ON/OFF and for fast iteration mode to avoid web rebuild when not needed. parallel with 18

Relevant files

• led-matrix/CMakeLists.txt — replace install-time preview execution model with explicit build targets, staging/install rules, option toggles, and cross-workflow integration points.
• led-matrix/plugins/CMakeLists.txt — expose plugin target inventory for reliable preview target dependencies.
• led-matrix/src_preview_gen/main.cpp — add scene ownership manifest mode and stable fingerprint inputs.
• led-matrix/shared/matrix/include/shared/matrix/plugin_loader/loader.h — optional API exposure if needed for scene->plugin mapping retrieval.
• led-matrix/shared/matrix/src/shared/matrix/plugin_loader/loader.cpp — optional implementation support for ownership enumeration from loaded plugins.
• led-matrix/scripts/build_upload.sh — integrate preview asset sync expectations into deploy path.
• led-matrix/CMakePresets.json — optional preset additions/toggles for preview generation behavior.
• led-matrix/README.md — document supported preview build/deploy workflows and flags.
• led-matrix/src_matrix/server/scene_management.cpp — verify unchanged runtime lookup contract for preview serving.

Verification

1. First-run full generation: run emulator configure/build and full preview target, confirm GIF exists for each scene and metadata manifest is produced.
2. Incremental behavior: modify one plugin scene source, rebuild plugin + incremental preview target, confirm only associated scene GIFs are regenerated (timestamps changed only for impacted scenes).
3. Toggle behavior: run with preview generation OFF, confirm build/install succeeds and no new preview generation occurs.
4. Explicit override behavior: run with manual scene list override, confirm only specified scenes regenerate even if others changed.
5. Cross-compile packaging: run cross-compile install/deploy path, verify previews are present on RPi under runtime previews directory and /list_scenes has_preview reflects files.
6. Failure tolerance: force one scene generation failure, confirm process warns and continues, unchanged/stale previews remain deployable.

Decisions

• Generation location: host machine emulator pipeline is canonical source of preview assets.
• Incremental policy: regenerate by plugin change impact, mapped down to scene outputs.
• Cross-compile strictness: do not fail packaging when previews are missing; warn and continue.

Further Considerations

1. Fingerprint strategy recommendation: start with mtime+size for speed, optionally upgrade to content hash if false positives/negatives appear.
2. Scene crash isolation recommendation: run per-scene generation subprocesses for robustness so one broken scene does not abort the whole incremental run.
3. CI recommendation: optionally add a non-blocking preview freshness check job that reports stale previews without failing release builds.

[Copilot]

@sshcrack The model claude-sonnet-4.6 is not available for your account. This can happen if the model was disabled by your organization's policy or if your Copilot plan doesn't include access to it.

You can try again without specifying a model (just @copilot) to use the default, or choose a different model from the model picker.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 645dee9d-e464-448e-b8f4-2d8022271f0d

[sshcrack]

@copilot

Plan: Incremental Scene Preview Build Pipeline

Use a host-side emulator preview pipeline as a first-class CMake workflow, then package generated previews into the cross-compile install tree for RPi deployment. Keep preview generation optional and incremental by tracking scene-to-plugin ownership and regenerating only scenes belonging to changed plugin shared libraries.

Steps

1. Phase 1: Baseline cleanup and target wiring
2. In root CMake, separate preview generation from install-time side effects by replacing install(CODE)-driven generation with explicit targets and installable artifacts that can be invoked intentionally; keep preview generation disabled/enabled with one option and default ON for emulator workflow. blocks steps 3-7
3. In plugins CMake registration flow, publish matrix plugin target names to parent scope (or a global CMake property) so preview targets can depend on actual plugin targets instead of opaque variables; verify current dependency wiring and remove undefined/misleading target lists. depends on 2
4. Add a dedicated cache/staging directory for generated previews in emulator build tree (for example emulator_build/previews) and install/copy from this staging area into install/previews. depends on 2
5. Phase 2: Scene ownership and incremental invalidation
6. Extend preview_gen with a metadata mode that outputs scene ownership manifest (scene name -> plugin name, plus plugin path/build identity) in JSON; reuse plugin metadata already available through BasicPlugin and loaded plugin records so ownership is computed from loaded plugins rather than heuristics. parallel with 7 after 3
7. Add CMake cache-state manifest handling (for example previews_manifest.json) that stores prior generation fingerprints per scene (plugin .so mtime/hash + preview settings like fps/frames/size + generator version). parallel with 6 after 4
8. Implement incremental selection logic in a CMake script step (or lightweight helper executable/script) that compares current ownership/fingerprints with previous manifest and produces a scene list requiring regeneration; unchanged scenes are skipped. depends on 6 and 7
9. Phase 3: Preview generation execution model
10. Add one full target for all previews and one incremental target that auto-selects changed scenes; both depend on preview_gen and matrix plugin targets, and both set PLUGIN_DIR and library search paths from build outputs (not install outputs). depends on 3 and 8
11. Add a manual override variable for explicit scene selection (comma-separated scene names) that bypasses auto-detection when provided; this supports targeted retries/debugging. depends on 10
12. Ensure generation failures are non-fatal for packaging by emitting warnings and preserving existing previews, matching your decision to continue cross-compile deploys with stale/missing previews when needed. depends on 10
13. Phase 4: Cross-compile packaging integration
14. In cross-compile workflow, add a packaging step that copies host-generated previews into build/install/previews before rsync/upload, without trying to run preview_gen in arm64 build. depends on 4 and 10
15. Update scripts/build_upload.sh workflow documentation/flow so expected order is: emulator preview incremental target -> cross-compile install -> rsync deploy; include opt-out switch to skip preview sync when desired. depends on 14
16. Keep runtime API contract unchanged: server reads get_exec_dir()/previews/SceneName.gif and list_scenes reports has_preview from file existence. No endpoint changes required. parallel with 14-15
17. Phase 5: Documentation and developer UX
18. Update README preview section with new commands for first-run full generation and subsequent incremental generation, including toggle flags and troubleshooting (missing PLUGIN_DIR, missing libs, scene crash behavior). depends on 10 and 15
19. Add CMake preset guidance (or optional extra preset) for emulator with previews ON/OFF and for fast iteration mode to avoid web rebuild when not needed. parallel with 18

Relevant files

• led-matrix/CMakeLists.txt — replace install-time preview execution model with explicit build targets, staging/install rules, option toggles, and cross-workflow integration points.
• led-matrix/plugins/CMakeLists.txt — expose plugin target inventory for reliable preview target dependencies.
• led-matrix/src_preview_gen/main.cpp — add scene ownership manifest mode and stable fingerprint inputs.
• led-matrix/shared/matrix/include/shared/matrix/plugin_loader/loader.h — optional API exposure if needed for scene->plugin mapping retrieval.
• led-matrix/shared/matrix/src/shared/matrix/plugin_loader/loader.cpp — optional implementation support for ownership enumeration from loaded plugins.
• led-matrix/scripts/build_upload.sh — integrate preview asset sync expectations into deploy path.
• led-matrix/CMakePresets.json — optional preset additions/toggles for preview generation behavior.
• led-matrix/README.md — document supported preview build/deploy workflows and flags.
• led-matrix/src_matrix/server/scene_management.cpp — verify unchanged runtime lookup contract for preview serving.

Verification

1. First-run full generation: run emulator configure/build and full preview target, confirm GIF exists for each scene and metadata manifest is produced.
2. Incremental behavior: modify one plugin scene source, rebuild plugin + incremental preview target, confirm only associated scene GIFs are regenerated (timestamps changed only for impacted scenes).
3. Toggle behavior: run with preview generation OFF, confirm build/install succeeds and no new preview generation occurs.
4. Explicit override behavior: run with manual scene list override, confirm only specified scenes regenerate even if others changed.
5. Cross-compile packaging: run cross-compile install/deploy path, verify previews are present on RPi under runtime previews directory and /list_scenes has_preview reflects files.
6. Failure tolerance: force one scene generation failure, confirm process warns and continues, unchanged/stale previews remain deployable.

Decisions

• Generation location: host machine emulator pipeline is canonical source of preview assets.
• Incremental policy: regenerate by plugin change impact, mapped down to scene outputs.
• Cross-compile strictness: do not fail packaging when previews are missing; warn and continue.

Further Considerations

1. Fingerprint strategy recommendation: start with mtime+size for speed, optionally upgrade to content hash if false positives/negatives appear.
2. Scene crash isolation recommendation: run per-scene generation subprocesses for robustness so one broken scene does not abort the whole incremental run.
3. CI recommendation: optionally add a non-blocking preview freshness check job that reports stale previews without failing release builds.