Terminal Rework Plan
The current simulated terminal in the web app is honest (disclaimer button) but
doesn’t help students actually compile or run C. TERMINAL_PLAN.md in the
llc-course repo documents the full analysis. Summary here.
The problem
- Terminal responds only to pre-scripted commands with canned output
- Students on a real machine should use their own terminal, but that’s a friction point
- The course would be meaningfully better if it could run real code
Option B — WebAssembly Compiler
Embed a WASM-compiled C toolchain (TinyCC ~200 KB or Emscripten ~2–5 MB). Compiles and runs C entirely in the browser, no install required.
Covers: Modules 1–4 (anything that only needs stdio.h / stdlib.h)
Breaks down at: file I/O, sockets, processes, signals, threads (Modules 5–10)
| Install required | None |
| Device support | All (mobile, Chromebook) |
| Output fidelity | Emulated (TinyCC dialect) |
| Real gcc errors | No |
| Bundle size impact | +2–5 MB |
| Extensible | No |
Option C — Local Companion Process
A native helper binary (~5 MB, no deps) the student installs once. Runs a local
HTTP server on localhost:27183. The browser sends C source, the helper compiles
with the student’s real gcc, and streams stdout/stderr back via WebSocket.
Browser-to-localhost is a validated pattern (Jupyter, VS Code local server, Tauri, Figma desktop fonts). Browsers explicitly allow it even from HTTPS pages.
Covers: All 10 modules including the Game Boy emulator capstone
Breaks down at: mobile, Chromebook, locked-down school machines
| Install required | One binary + gcc |
| Device support | PC/Mac/Linux only |
| Output fidelity | Real gcc, real OS |
| Real gcc errors | Yes |
| Bundle size impact | None |
| Extensible | Yes (Valgrind, ASan, test diffs) |
Recommendation — Hybrid, phased
Phase 1 (WASM): Embed TinyCC-WASM for Modules 1–4. Zero friction, real (if limited) compilation for students who haven’t set up a dev environment.
Phase 2 (Companion): Build the native companion binary. Gate the real-run
feature in Modules 5–10 behind companion detection. Show a one-time install
prompt when the student reaches Module 5. Students who already have gcc
(the intended audience) will find setup straightforward.
Phase 3 (Companion extensions): Valgrind/ASan integration, expected-output diffing, automated lesson checks. Becomes the foundation for the “home lab” experience described in meta-project-status.
Open questions
- Windows support — bundle MinGW-w64, require WSL2, or just document WSL2? WSL2 is least friction but adds setup steps.
- Security model — timeout per run (~5s), max output size cap, temp dir isolation, no outbound network from compiled binary. Needs a threat-model pass.
- TinyCC vs Emscripten — TinyCC: tiny (~200 KB), fast to compile, C99 only, limited diagnostics. Emscripten: full C11/C17, better warnings, much larger bundle. Decision depends on how much warning quality matters for early modules.
- Streaming UX — companion output should stream line by line. The existing
terminal line-type system (
out,err,warn,success,comment) maps cleanly; just needs a WebSocket reader on the frontend.