Repository navigation
Description
Context
The instant-launch feature (#148, shipped via #149) does not work at all in the real product. Observed behavior on fastled <sketch> with no prior build artifacts:
- The viewer window opens and shows a bare
Not Foundpage. - The compile proceeds normally in the terminal; the viewer window never shows the loading page and never streams compile output.
- When the compile finishes successfully (
index.htmlnow on disk), the viewer still showsNot Foundand stays that way for the remaining life of the app. - Ctrl+C, run again: artifacts exist, the viewer renders the sketch immediately and works normally — masking the bug on every subsequent run.
All of the instant-launch UX built in #148/#149 (loading page, SSE log streaming, elapsed timer, auto-reload on success, stay-on-error) lives in the embedded HTTP server (crates/fastled-cli/src/server.rs — LOADING_PAGE, /build-stream, /build-status.json) — and the viewer never talks to that server. It is dead code in the shipped flow. The 18 server::tests and the Playwright stress test from #149 all exercise the HTTP surface directly, which is why they pass while the feature is broken end-to-end.
Root cause
The Tauri viewer is pointed at the artifact directory, not at the HTTP server URL:
commands.rs::compile_and_servestarts the HTTP server (with the SSE broadcast channel), then launches the viewer withviewer::launch_tauri_viewer(&output_dir)— the directory, nothttp://{addr}(crates/fastled-cli/src/commands.rs:83).- That spawns
fastled --internal-viewer <output_dir>(crates/fastled-cli/src/viewer.rs:165-181,:216-234). tauri_viewer.rs::runregisters a customfastled://URI scheme that serves raw files straight off disk from that directory and navigates the webview tofastled://localhost/index.html(crates/fastled-cli/src/tauri_viewer.rs:15-63,:72).- On a fresh sketch
index.htmldoes not exist yet, so the protocol handler returns a static 404 bodyNot Found(tauri_viewer.rs:54-60). That page has no JavaScript: no SSE subscription, no/build-status.jsonpolling, no reload. The webview never navigates again, so the window is permanently stuck — even after the build succeeds andindex.htmlappears.
Both halves of the report follow from one wiring bug: the webview lives in the fastled:// protocol universe, while every piece of instant-launch machinery (loading page, SSE, status flips, success transition via location.reload()) lives in the http://127.0.0.1:<port> universe.
E2E confirmation (real binary, full pipeline)
Performed on Windows 10, repo at 3fa9737, release binary target/x86_64-pc-windows-msvc/release/fastled.exe (self-relocates to ~/.fastled/run/fastled-v2.0.10-...):
- Created a pristine sketch dir containing only
Blink.ino(nofastled_js/, no.build/— forces a full cold compile; required, see repro below). fastled <sketch>→ terminal printsServing at http://127.0.0.1:58481, cold compile runs 38.43s.- During compile:
GET http://127.0.0.1:58481/returns HTTP 200 with the loading page (Compiling...,EventSource,/build-stream) — the HTTP side of feat: instant launch — open web view immediately, stream compile, switch to sketch when ready #148 works.- Process tree shows the viewer child spawned as
fastled.exe --internal-viewer C:\...\Blink\fastled_js— a directory path, no URL. - Window screenshot (PrintWindow): viewer titled "FastLED Viewer" renders only the text
Not Found.
- After compile success (
Build finished in 38.43s (strategy: cold),fastled_js/index.htmlpresent on disk): window screenshot still showsNot Found. No transition, ever. - Kill the app, re-run with artifacts present: viewer renders the FastLED sketch UI immediately. Matches the reported "works the second time" behavior exactly.
Reproduction (must force a full recompile)
The bug only manifests when index.html is absent at viewer-launch time. Because artifacts persist, the second run always works — sanitize state first:
rm -rf <sketch>/fastled_js <sketch>/.build # force full recompile; or use a fresh dir with only the .ino
fastled <sketch>Expected (per #148): viewer opens onto a live build view, streams the compile log, switches to the sketch when the build finishes.
Actual: viewer shows Not Found for the whole session; only the terminal shows progress; restart required.
Note: deleting only fastled_js/ (keeping .build/) still reproduces the permanently-stuck window — even a 1.2s incremental rebuild leaves the viewer on Not Found forever, because nothing ever re-navigates the webview.
Proposed fix
Point the webview at the already-running HTTP server instead of the fastled:// directory protocol:
- Thread the server URL from
compile_and_serveinto the viewer launch: e.g. spawnfastled --internal-viewer-url http://127.0.0.1:<port>/(keep or migrate--internal-viewer <dir>for the--serve-dirflow). Launch sites:crates/fastled-cli/src/commands.rs:83(compile flow) and:381(serve-dir flow). - In
tauri_viewer.rs::run, usetauri::WebviewUrl::External(url)instead ofWebviewUrl::CustomProtocol("fastled://localhost/index.html"). - This makes the whole feat: instant launch — open web view immediately, stream compile, switch to sketch when ready #148 contract work for free, because the HTTP server already implements it: loading page when
index.htmlis missing, SSE log streaming via/build-stream,location.reload()into the sketch onstatus: success, stay-on-error UX, correct COOP/COEP headers (same-origin/credentialless), plus the DWARF source endpoints (/dwarfsource,/sketchsource/...) which the custom protocol also cannot serve. - The
fastled://custom protocol handler then has no remaining consumer in this flow and can likely be deleted (or, if some packaging path needs serverless viewing, it must at minimum serve the loading page instead of a static 404).
Acceptance criteria
- E2E from a sanitized state (
fastled_js/and.build/deleted, full cold compile): the viewer window shows the live build view (status header + streaming log lines) within ~1s of launch — notNot Found. - When the cold compile succeeds, the viewer transitions to the running sketch automatically — no Ctrl+C/restart, no manual reload.
- When the compile fails, the viewer stays on the build view with the error log visible (per feat: instant launch — open web view immediately, stream compile, switch to sketch when ready #148 criterion 5), and a subsequent successful rebuild transitions forward.
- The viewer process is spawned with the HTTP server URL (verifiable via process command line); the webview origin is
http://127.0.0.1:<port>, notfastled://. -
--serve-dirwith viewer still works (pre-built dir renders). - A test guards the wiring (e.g. asserting the spawned viewer args contain the server URL), since all existing tests exercise the HTTP surface only and missed this.
- DWARF source fetch (
/dwarfsource) works from inside the viewer after a--debugbuild (it cannot work overfastled://today).
Decisions
- Priority: P1 — flagship UX feature from feat: instant launch — open web view immediately, stream compile, switch to sketch when ready #148 is fully non-functional on first run for every user; severity HIGH (user-facing bug, silent failure).
- Fix shape: reuse the HTTP server as the single serving path rather than teaching the
fastled://protocol to serve the loading page + SSE — the server already implements the whole contract; duplicating it would just re-create drift. - Repro instructions mandate deleting
fastled_js/+.build/because persisted artifacts mask the bug on second run (confirmed e2e: second run renders fine). - Follow-up (out of scope): once on the real sketch page, watcher-triggered rebuilds also have no reload channel into the viewer; worth a separate issue if the sketch page doesn't already subscribe to
/build-stream.
Related issues
- feat: instant launch — open web view immediately, stream compile, switch to sketch when ready #148 — instant launch feature spec (this is the defect in its implementation)
- feat: instant launch — explicit failure UX in the loading page #149 — PR that added the failure UX to the loading page (HTTP-side only; never reachable from the viewer)
Activity
release: v2.0.11 with viewer fix #157 and viewer URL regression gate
release: v2.0.11 with viewer fix #157 and viewer URL regression gate (#…
zackees commentedon Jun 12, 2026
Fixed and shipped. The viewer wiring fix landed in #157 (viewer now points at the HTTP server via WebviewUrl::External), #166 fixed the packaging staleness that kept shipping pre-fix binaries from 'pip install .', and #161 added the fail-loud http(s) URL guard + regression tests so this can't silently regress. v2.0.11 is now published on PyPI; verified the released wheel's bundled fastled.exe no longer contains the fastled://localhost protocol target and includes the current server endpoints.