Skip to content

fix: instant launch broken — Tauri viewer loads fastled:// directory protocol, never the HTTP server, shows 'Not Found' forever #151

Closed

Description

@zackees

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:

  1. The viewer window opens and shows a bare Not Found page.
  2. The compile proceeds normally in the terminal; the viewer window never shows the loading page and never streams compile output.
  3. When the compile finishes successfully (index.html now on disk), the viewer still shows Not Found and stays that way for the remaining life of the app.
  4. 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_serve starts the HTTP server (with the SSE broadcast channel), then launches the viewer with viewer::launch_tauri_viewer(&output_dir) — the directory, not http://{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::run registers a custom fastled:// URI scheme that serves raw files straight off disk from that directory and navigates the webview to fastled://localhost/index.html (crates/fastled-cli/src/tauri_viewer.rs:15-63, :72).
  • On a fresh sketch index.html does not exist yet, so the protocol handler returns a static 404 body Not Found (tauri_viewer.rs:54-60). That page has no JavaScript: no SSE subscription, no /build-status.json polling, no reload. The webview never navigates again, so the window is permanently stuck — even after the build succeeds and index.html appears.

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-...):

  1. Created a pristine sketch dir containing only Blink.ino (no fastled_js/, no .build/ — forces a full cold compile; required, see repro below).
  2. fastled <sketch> → terminal prints Serving at http://127.0.0.1:58481, cold compile runs 38.43s.
  3. During compile:
  4. After compile success (Build finished in 38.43s (strategy: cold), fastled_js/index.html present on disk): window screenshot still shows Not Found. No transition, ever.
  5. 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:

  1. Thread the server URL from compile_and_serve into the viewer launch: e.g. spawn fastled --internal-viewer-url http://127.0.0.1:<port>/ (keep or migrate --internal-viewer <dir> for the --serve-dir flow). Launch sites: crates/fastled-cli/src/commands.rs:83 (compile flow) and :381 (serve-dir flow).
  2. In tauri_viewer.rs::run, use tauri::WebviewUrl::External(url) instead of WebviewUrl::CustomProtocol("fastled://localhost/index.html").
  3. 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.html is missing, SSE log streaming via /build-stream, location.reload() into the sketch on status: 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.
  4. 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 — not Not 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>, not fastled://.
  • --serve-dir with 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 --debug build (it cannot work over fastled:// 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

Activity

  1. added 2 commits that reference this issue on Jun 12, 2026
  2. zackees commented on Jun 12, 2026

    @zackees
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions