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. The archived terminal-plan docs in llc-course/plans/archive/2026-04/ document the original analysis and decision path. 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.

Decision — 2026-04-12

Build the companion process (Option C) first. WASM deferred.

Full rationale in TERMINAL_DECISION.md. Key points:

• The course prerequisite is “you have gcc installed” — WASM solves a problem that doesn’t exist for the target audience.
• WASM only covers Modules 1–4; the companion covers all 10. Shipping the incomplete solution and iterating creates confusion at Module 5.
• TinyCC vs. Emscripten is a genuine blocker: TinyCC is C99-only; the course uses C11 features. Emscripten adds 2–5 MB. Neither is a clean choice.
• The companion has compounding value: Valgrind integration, output diffing, and lesson test hooks can layer on top. WASM cannot support any of those.

Companion implementation decisions:

• Language: Go (single static binary, trivial cross-compilation)
• Protocol: WebSocket at ws://localhost:27183/run; ping at /ping
• Security: 5s timeout, 64 KB output cap, temp dir isolation per run
• Windows: WSL2 documented as supported path for v1

Companion onboarding — shipped 2026-04-13

CompanionSetup.jsx is live. When a student reaches Module 5 with no companion running, a modal auto-opens once per session (sessionStorage gate). Two tabs: guided companion install (with live detection) and manual gcc setup. “set up C environment →” button always available in the terminal bar for M5+.

Open questions (remaining backlog)

1. Windows path v2 — bundle MinGW-w64 or stick with WSL2-only?
2. Install UX — GitHub releases or hosted on course domain? Resolved: GitHub releases, surfaced via CompanionSetup modal.
3. Auto-update — check for new versions automatically?
4. WASM (Phase 1) — still deferred; TinyCC/C99 vs Emscripten/bundle-size tradeoff unresolved.