Repository navigation
Description
Problem / corrected requirement
The previous read-only design is rejected. The integrated terminal must be an interactive shell backed by a real PTY, with stdin, stdout/stderr, terminal resizing, and first-class clud ... use. Its initial working directory is the directory in which the app's fastled process was launched, not the served fastled_js directory and not an independently resolved sketch argument.
Investigation and architecture
commands.rsstarts the loopback Axum server for normal compile/watch,--test, and--serve.viewer.rslaunches the same native binary with--internal-viewer http://127.0.0.1:PORT. The shipped Tauri webview loads that HTTP origin. Existing frontend IPC uses HTTP and build SSE; no frontend Tauri terminal command exists.- The CLI HTTP server owns PTYs, consistently for the shipped viewer and browsers. Keep existing SSE for build logs; add a same-origin WebSocket for bidirectional terminal bytes and resize messages. No Tauri IPC fork.
portable-pty0.9.0 is already pinned in Cargo.lock through running-process. Add it as a direct exact-version dependency. Enable Axum's WebSocket feature, updating only necessary lockfile entries.- The referenced current_dir call is currently in project initialization on origin/main; it is not a launch-directory handoff to the server. Capture
std::env::current_dir()when the server starts, before any PTY exists, and store it independently of serve_dir. Normal serving does not change process cwd. Use CommandBuilder::cwd with that captured path for every shell.
PTY backend and IPC
- Add
terminal.rs: native PTY, inherited environment, interactive shell, byte-preserving output, ordered stdin and resize, bounded queues, shell exit/error reporting and child kill/reap on disconnect. Limit concurrent sessions and message sizes; validate nonzero/bounded terminal dimensions. /terminal/wsupgrades only with an Origin exactly equal to the bound loopback HTTP origin. Reject absent/null/foreign origins and DNS-rebinding host aliases. Existing permissive static-asset CORS must never grant terminal access.- Binary WebSocket frames carry raw PTY output (including split UTF-8); JSON client messages carry input and resize. Subscribe/read before consuming output so the initial prompt is retained. No output replay across disconnected sessions; hide/show keeps the same connection and bounded xterm scrollback. Explicit restart creates a fresh shell after exit/disconnect.
- Blocking PTY operations stay off async executor threads. Disconnect and server shutdown close the terminal and reap its shell.
PATH and clud
- On Unix choose the user's SHELL, with a documented system-shell fallback when unset; start it interactively with login startup files. Preserve the inherited environment and supplement PATH with the user's
~/.local/bin(uv tool entrypoints) and standard system paths for desktop/service launches. Set TERM=xterm-256color. - The viewer's desktop-launch PATH is not authoritative: the server initializes the PTY environment, and login startup files restore the user's normal configuration. On this machine
/home/niteris/.local/bin/cludis a symlink into~/.local/share/uv/tools/clud/bin/clud;.bash_profileexplicitly adds~/.local/bin. Verify resolution andclud --helpin the actual PTY, including a stripped parent PATH. Never hardcode this user's absolute home into production code. - Windows uses a native interactive command shell/ConPTY and inherited user PATH with the uv tool bin fallback. Document platform validation actually performed. User startup files remain user-controlled; errors must be visible, never replaced by a log viewer.
Frontend and layouts
- Add an always-visible Terminal button and a separate responsive terminal dialog: desktop wide/tall overlay; mobile fits viewport. Include Close, Copy selection/buffer, Restart and visible connection/error status. Fit on open and ResizeObserver updates; focus terminal on open, restore opener focus on close. Preserve normal Escape input to interactive programs; use explicit close controls.
- Keep
logging_setup.tsand<pre id="output">as the separate sketch/console log surface with its existing canvas-click access. Do not seed or inject console logs into a live shell: ANSI streams, prompts, and full-screen agent applications must remain coherent. Native console.error behavior is unchanged.
Exact files to touch
crates/fastled-cli/Cargo.toml,Cargo.lock: pinned PTY and WebSocket dependencies.crates/fastled-cli/src/{lib.rs,server.rs}and newterminal.rs: module, launch cwd capture, guarded HTTP upgrade and PTY lifecycle/protocol tests.src/fastled/frontend/{app.ts,index.html,index.css}and newterminal.ts: interactive terminal initialization and accessible controls/layout.src/fastled/frontend/vendor/xterm/: runtime assets, licenses, provenance and checksums.crates/fastled-cli/src/frontend.rs: bundle CSS with esbuild so local xterm CSS reaches dist.MANIFEST.in: package vendor licenses/provenance.- New
tests/frontend/test_terminal.py: browser fixture using real vendored xterm and the real server/PTY, without a WASM compile. - New
docs/interactive-terminal.md: protocol, shell environment, lifecycle and verification instructions/limitations.
Vendoring plan (no npm / node_modules)
Download published tarballs directly: @xterm/xterm 5.5.0 and @xterm/addon-fit 0.10.0. Store upstream lib/xterm.js and lib/addon-fit.js in vendor/xterm/build/ (matching the local vendor build-directory ignore exception), their maps, xterm CSS in css/, and both MIT licenses. Record upstream URLs, versions and SHA-256 checksums. Use only relative imports, like vendor/three. No CDN or package manager at build/runtime. Use default renderer and fit addon; no WebGL addon.
Test plan / acceptance criteria
- Record RED -> GREEN against a real missing terminal endpoint / behavior before implementation.
- Real PTY tests: launch cwd differs from served dir; stdin produces output; ANSI/UTF-8 bytes survive; resize reaches PTY; shell exit and disconnect cleanup; invalid dimensions and foreign/missing origins rejected; bounded queues/session limit.
- Verify a shell with stripped inherited PATH resolves a test uv-style tool; on this host verify real
command -v cludandclud --help, recording output without credentials. - Production esbuild JS/CSS bundling succeeds without npm. Browser checks use real xterm and real transport: type commands, ANSI output, hide/reopen continuity, fit/resize, restart, copy and separate logs. Chromium and WebKit where available; report native Safari availability honestly.
- Run
bash lintandbash test. No full WASM compilation needed because compiler/linker behavior is untouched. - Safari remains required: introduce no JSPI flags, WebAssembly.Suspending or WebAssembly.promising.
- Commit with Refs feat: add xterm.js terminal to CLI web app #240 on an origin/main-based isolated branch, push, create PR, merge only when CI is green. Preserve the unpushed kernal migration branch.
Non-goals
Read-only output-viewer replacement, remote/network shell hosting, multiple terminal tabs or durable session reconnection, shell installation or clud installation, compile-loading-page redesign, UI-manager refactor, Emscripten upgrades and pre-existing JSPI debt cleanup.
Implementation investigation follow-up
NixOS browser validation exposed that /usr/bin alone is insufficient when
inherited profile guards prevent reinitialization. Include existing
~/.nix-profile/bin and /run/current-system/sw/bin in the environment fallback.
Use bounded output acknowledgements and Unicode-safe paced paste chunks.
Blocking stdin must run separately from session supervision: the regression
opens four PTYs whose foreground program stops reading, sends 60,000 bytes,
disconnects, then verifies a fifth connection succeeds. Full implementation and
exact local validation commands are recorded in docs/interactive-terminal.md.
Activity
fix: gate Unix PTY test helper on Unix
feat: add interactive PTY terminal with launch cwd and clud access (#241
zackees commentedon Sep 13, 2026
Implemented and merged.
22ea04610e55a2a008b406d336c8c6fac3be0ca7, all 22 CI checks green.cludavailable (login-like PATH including~/.local/bin).@xterm/xterm5.5.0 and@xterm/addon-fit0.10.0 are vendored undersrc/fastled/frontend/vendor/xterm/with licenses and checksums — no npm, no node_modules. Transport is a same-origin WebSocket (/terminal/ws), origin-guarded.logging_setup.tsbehaviour is unchanged.Verified:
bash lint— passed.bash test— 259 Rust tests/doctests passed; Python 23 passed, one pre-existing skip.clud --help, a 120,400-byte paste, and blocked-input cleanup.Caveats, stated plainly: native Safari was not available (WebKit passed, and no JSPI was introduced, so the Safari compatibility invariant holds — but a real Safari smoke test has not been run), and no full local WASM compile was performed because compiler/linker behaviour is untouched.
Implementation notes and the full validation record are in
docs/interactive-terminal.md.Closing as complete.