meta: burndown of remaining fastled-wasm work

[zackees]

Context

One list for burning down all remaining open work in this repo. Each item has a checked status and an order. Items with an existing issue link to it. Items without one are described inline with enough detail to act on, and don't get separate child issues.

Status was verified against main at 4ebcabd on 2026-09-17. Several open issues turned out to be already implemented and only need confirming and closing.

Burndown

Work top to bottom. Tick an item when its PR merges or when its issue closes with evidence.

Tier 0: close what is already done (verify, then close)

• chore: remove obsolete Python shim runtime dependencies #245 remove obsolete Python shim runtime dependencies — closed 2026-09-17, verified on 4ebcabd
  • Verified on main: pyproject.toml no longer declares typeguard or zcmds_win32, and the implementation comment says it shipped in Rebase FastLED infrastructure onto kernal-api #242 (merged 2026-09-15).
  • Closing step: confirm the dependency-boundary test covers it, then close with a link to Rebase FastLED infrastructure onto kernal-api #242.
• fix: Emscripten config retains staging paths after catalog installation #246 Emscripten config retains staging paths — closed 2026-09-17, verified on 4ebcabd incl. a real cold compile
  • Verified on main: archive::write_emscripten_config_at writes config for the final location while staged, and the health check in install.rs (~L1005) rewrites configs of older managed installs. Both shipped in Rebase FastLED infrastructure onto kernal-api #242.
  • Closing step: run the real compiler health check plus a Blink compile once, then close.
• migration: real WASM viewer fails OffscreenCanvas WebGL2 compatibility in Linux smoke #247 Linux smoke OffscreenCanvas WebGL2 compatibility
  • What landed: the forced AllowWebGLInWorkers was reverted upstream (fix(webview): stop forcing WebGL on OffscreenCanvas in WebKitGTK views zackees/kernal-api#272, on release/0.1.3, included in the current v0.1.11 pin). The main-thread render fallback is in bootstrap.ts and the worker.
  • Still to verify: one real Linux fastled <sketch> --test --test-screenshot render, plus Safari. Then close.
  • Blocked by Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250, measured 2026-09-17: that render exits 125 (viewer did not render a canvas) even for a sketch that sets a screen map in setup(), because the layout arrives after the worker's single read. The WebGL2 behaviour itself is now correct: webgl2:false on OffscreenCanvas falls back to contextType: "main_thread" without error. Evidence in Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250.

Tier 1: user-visible bugs

• Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250 Viewer shows an empty canvas for sketches with no setScreenMap() in setup() (e.g. Blink)
  • Still open on main: fastled_background_worker.ts reads getScreenMapData() once (~L647-659) and never polls again.
  • Wider than the title says (measured 2026-09-17): sketches that do call setScreenMap() in setup() hit it too, so the documented workaround is not reliable. The trigger is ordering. Evidence and a RED -> GREEN command in Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250.
  • Blocks migration: real WASM viewer fails OffscreenCanvas WebGL2 compatibility in Linux smoke #247's closing render, so it is the critical path for Tier 0 as well.
  • Fix: here, and mirrored in FastLED's copy of the frontend, per the issue.

Tier 2: CI coverage and CI cost

• Intel macOS Rust tests in a Linux-hosted guest (untracked; left over from Run macOS viewer rendering in a docker-mac-x64 guest on a Linux runner #251 scope item 3a)
  • Why it's still possible: ci(macos-x64): measure WebKit in a docker-mac-x64 guest; keep the hosted render lane #261 proved a docker-mac-x64 guest cannot render (no GPU, no WebGL), but the x86_64-apple-darwin nextest archive does not need a GPU.
  • Prior art: zackees/kernal-api macos-x64-tests.yml plus ci/macos-x64/{build-archive.sh,stage-guest-share.sh,recovery-guest.sh,verify-guest-results.py}, which runs the archive in a Recovery guest with a Mach-O cargo-nextest staged through the share directory.
  • Guest constraints measured in ci(macos-x64): measure WebKit in a docker-mac-x64 guest; keep the hosted render lane #261:
    • /var/root is read-only (set HOME under /tmp);
    • no python3;
    • /tmp is a 4.9 GB tmpfs;
    • an empty 68 GB disk is attached for anything larger;
    • network works.
  • Cadence: nightly plus workflow_dispatch. Boot plus probe alone took 391-579 s.
  • Acceptance:
    • the archive runs in the guest and the job fails on a test failure (the guest itself never exits non-zero, so verify collected results);
    • RED -> GREEN by temporarily breaking one test.
• setup-soldr soldr-cook fails on every Linux build job (untracked)
  • Symptom: the Linux unit-test run on main (35193809098) shows failed to run custom build command for glib-sys v0.18.1 / gobject-sys v0.18.0, then cook: failed with exit 101 ... continuing without cooked deps. _terminal-test.yml shows the same.
  • Cause: setup-soldr cooks dependencies inside its own step, before the later "Install system dependencies (Linux)" step installs libgtk-3-dev / libwebkit2gtk-4.1-dev, so pkg-config finds no GLib. The prebuilt-dependency cache is never produced, and every run compiles those dependencies cold.
  • Fix: install the apt packages before zackees/setup-soldr in _unit-test.yml, _terminal-test.yml and the other _*.yml files that cook on Linux.
  • Acceptance:
    • the cook step logs success on Linux;
    • a second run shows a warm-cache hit;
    • record the before/after wall time of the Linux unit-test job.
• Python files under ci/ are unlinted (untracked)
  • Symptom: bash lint runs ruff, black, isort and pyright over src tests only. ruff check ci reports 13 errors on main: 6 SIM102, 4 ISC004, 1 PIE810, 1 EXE001, 1 RUF100 (in ci/hooks/tool_guard.py and ci/lint_python/keyboard_interrupt_checker.py).
  • Why it matters: ci/ now holds real test code (safari_smoke.py, safari_terminal_smoke.py) that CI executes.
  • Fix: fix the 13 findings, then add ci to the ruff/black/isort/pyright invocations in lint.
  • Acceptance: bash lint covers ci/ and passes; reverting one fix makes lint fail.

Tier 3: developer experience

• bash lint cannot complete on hosts without rustup (untracked)
  • Symptom: the dylint stage requires cargo-dylint 6.0.3 and a rustup binary (to pin nightly-2026-03-26), and exits before the Python stages run. On a NixOS host, no Python lint runs locally.
  • Fix: run the Python stages independently of the dylint stage, or skip dylint with a loud warning locally (never in CI) when its prerequisites are missing.
  • Acceptance:
    • on a host without cargo-dylint, bash lint still runs every other stage and exits non-zero with an explicit "dylint not run" message;
    • in CI, a missing dylint still fails.

Tier 4: features and project direction

• feat(terminal): launch an agent in the browser terminal and preserve its session #254 launch an agent in the browser terminal and preserve its session
  • Feature (P2) with phases already defined in the issue.
  • Depends on nothing above, but should land after the terminal CI from test(terminal): run the browser terminal suite in CI, on real Safari, and close the Windows slot leak #259/ci(terminal): run the browser terminal suite on Linux, Windows and real Safari #260 so its RED -> GREEN runs in CI.
• Migrate fastled-wasm to fastled/cli #56 migrate fastled-wasm to fastled/cli
  • Organizational move with unresolved open questions (archive vs. deprecate, CLI shape, PyPI rename).
  • Needs an owner decision before any code work, so it goes last.

Acceptance criteria

1. Every checkbox above is ticked. Each existing issue is closed with a linked PR or verification evidence. Each untracked item has a merged PR meeting its own acceptance line.
2. Every bug or behavior change lands with RED -> GREEN evidence: a focused failing test or run first, then the fix. Tier 0 closures cite the verifying run instead.
3. bash test passes, and every CI workflow is green on the final merge.
4. No item is closed by weakening a check: no skipped browser checks, no lowered readiness gates, no JSPI flags (Safari remains a required target).

Decisions

• Order. Tier 0 first because it is nearly free and shrinks the board. Then user-visible bugs, then CI that protects future work, then developer experience, then features and project moves.
• No child issues for untracked items. They are small enough to describe inline, and each carries its own acceptance line. Open a child issue only if one grows beyond a single PR.
• migration: real WASM viewer fails OffscreenCanvas WebGL2 compatibility in Linux smoke #247 goes in Tier 0 rather than Tier 1. Its fixes are on main; what remains is a verification render, blocked only by Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250's Blink behavior when Blink is used as the sketch.
• The Intel guest test lane is nightly, not per PR. It is based on the 391-579 s boot-plus-probe measured in ci(macos-x64): measure WebKit in a docker-mac-x64 guest; keep the hosted render lane #261, matching kernal-api's cadence for the same guest.
• Migrate fastled-wasm to fastled/cli #56 goes last. It needs an ownership decision rather than implementation.
• Items considered and left out:
  • A Windows ConPTY bounded write: measured unnecessary in test(terminal): run the browser terminal suite in CI, on real Safari, and close the Windows slot leak #259/ci(terminal): run the browser terminal suite on Linux, Windows and real Safari #260, closed fix(pty): bound ConPTY writes on Windows zackees/kernal-api#296.
  • Real-GPU macOS rendering on Linux runners: measured impossible in Run macOS viewer rendering in a docker-mac-x64 guest on a Linux runner #251/ci(macos-x64): measure WebKit in a docker-mac-x64 guest; keep the hosted render lane #261.

Open questions

• migration: real WASM viewer fails OffscreenCanvas WebGL2 compatibility in Linux smoke #247 closing render: can a sketch that sets a screen map stand in for Blink? Answered 2026-09-17: no. A screen-mapped sketch fails the same way, so Viewer shows an empty canvas for sketches that set no screen map in setup() (e.g. Blink) #250 must land first.
• dylint on NixOS: should lint provide a Nix path for cargo-dylint and a nightly toolchain, instead of only a skip-with-warning?

Related issues

#245, #246, #247, #250, #254, #56. Closed context: #251/#261 (guest findings), #259/#260 (terminal CI).