feat(v0.2): UI modes wiring + auto-theme + error catalog + /search + /palette

[SimpleLittleDev]

Summary

Stacked on top of #4. Closes out the remaining v0.2 phases — Phase 7 (display modes), Phase 8 (long-output protection), Phase 9 (search + palette), Phase 10 (error catalog). All 184 tests pass; lint, typecheck, and build are clean.

Phase 7 — Display modes + auto-theme

• src/tui/DebugPanel.tsx — bordered panel showing FSM state, terminal caps, MCP server count, and a flags row. Mounts only when uiMode === "debug", so production sessions stay clean.
• src/app.tsx:
  • compact and focus hide the welcome banner.
  • focus also hides the StatusBar, the LogoAnimator, and the bottom command-count hint — pure chat + prompt for serious coding sessions.
  • debug adds the <DebugPanel> above the logo with FSM / caps / MCP counts / browser engine kind / transcript length.
  • noanim already wired through stable flags and now propagates to PromptV2 too.
• Auto theme selection — when config.theme is still the stock default, pickThemeForCaps() upgrades to nocolor (when NO_COLOR / dumb terminal) or termux (when running on Android) based on TerminalCapabilities. Explicit /theme choices are honored unchanged.

Phase 8 — Long output protection

• src/lib/transcriptVirtual.ts:
  • virtualize<T>(items, { maxRender, keepRecent }) returns { visible, dropped } for future render-time virtualization.
  • clipLines(text, maxLines, marker?) clips a long string to N lines with a configurable trailer like … 412 more lines (use /show last).
• src/app.tsx — every tool-call result now goes through clipLines(result.output, 200) before reaching the chat bubble. Stops a 50k-line stack trace from blowing up the TUI; the full text is still in the chat history for /save / future inspection.

Phase 9 — Search + palette

• src/commands/search.ts — /search <query> (aliases find, history-search) reads ~/.fastcode/history JSONL directly, fuzzy-matches on substring, and renders the 10 most recent hits with timestamps and one-line previews. Works even on a fresh restart before the live history ref has anything.
• src/commands/palette.ts — /palette (aliases commands, cmds) groups every visible command into 5 buckets (Session, Editing, Provider, Sandbox + MCP, Misc) and lists each with its aliases and description. Textual fallback for a future Ctrl+P overlay.

Phase 10 — Error catalog

• src/lib/errorCatalog.ts — small classifier matching common error shapes:
  • FS: FS_NOT_FOUND (ENOENT), FS_DENIED (EACCES)
  • Net: NET_TIMEOUT (ETIMEDOUT/timeout), NET_DNS (ENOTFOUND/getaddrinfo), PIPE_BROKEN (EPIPE)
  • Sandbox: SANDBOX_DENIED (anything with SANDBOX_* prefix)
  • MCP: MCP_TRANSPORT (json-rpc / mcp keywords)
  • Provider/auth: AUTH_FAILED (401/403), RATE_LIMITED (429), PROVIDER_5XX
  • Generic: ABORTED, UNKNOWN fallback
    Each entry returns { code, title, detail, hint? }. formatFriendlyError() renders to markdown for the chat layer.
• src/app.tsx — both tool failures and chat-loop exceptions now flow through explainError() so the user sees a labelled error block (e.g. **Network timeout** (NET_TIMEOUT)\n\n_Couldn't reach api.openai.com within the timeout. Check connectivity and retry._) instead of a raw Error: ... line.

Tests added (19 new, 184 total)

• test/transcriptVirtual.test.ts (5) — virtualize cap behavior, clipLines defaults and custom marker.
• test/errorCatalog.test.ts (10) — every classifier branch + formatFriendlyError shape.
• test/searchCommand.test.ts (4) — /search and /palette are reachable by name + alias and produce expected output shape.

npm run check (test + typecheck + lint + build) passes locally.

Review & Testing Checklist for Human

• Mode switching: /mode focus, /mode compact, /mode debug, /mode noanim, then /mode normal. Confirm each visibly changes the UI (banner / status / logo / debug panel) and that re-running normal restores everything.
• Auto-theme: launch with NO_COLOR=1 and verify the chat renders in nocolor automatically without manually running /theme nocolor. Then on Termux, verify the termux theme kicks in.
• /search: send a few prompts, restart, and run /search <substring>. Confirm matches surface from the persisted file (not just in-memory).
• /palette: confirm every visible command appears in exactly one bucket, with its aliases listed.
• Long output clipping: trigger a tool that emits more than 200 lines and confirm the bubble shows the head + a … N more lines trailer instead of overflowing.
• Error catalog: run a tool against a non-existent file or unreachable host and confirm the failure block is rendered with a friendly title + hint, not a stack trace.

Notes

• Stacked on top of feat(v0.2): PromptV2 + chat redesign + theme variants + headless browser #4. Base is main, so this PR's diff also includes the phase 1 + 2 + 5b + 6 commits for convenience. We can split / rebase once feat(v0.2): living TUI + MCP + sandbox v2 + browser tool #3 and feat(v0.2): PromptV2 + chat redesign + theme variants + headless browser #4 land.
• /palette and index.ts form a circular import at the module-graph level, but the cycle resolves at runtime because COMMANDS is only read inside the command's run() function. ESM live bindings do the right thing here.
• The full transcript is still kept in React state — clipLines only trims at render time. If long sessions grow uncomfortably, a future PR can render a virtual slice via virtualize() and replace <Static> with a managed scroll buffer.

Link to Devin session: https://app.devin.ai/sessions/0e73b43883c04a17b651ca6aa7dc1a5e
Requested by: @SimpleLittleDev

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[SimpleLittleDev]

v0.2 end-to-end TUI test — 5 passed, 2 real defects found

Tested all three v0.2 PRs (#3 + #4 + #5) live in xterm by driving the TUI via simulated keystrokes. Full report with screenshots: see attached test-report.md in the Devin session.

Lead — escalations first

🔴 DEFECT 1 — PromptV2 paste-burst corrupts multiline input
xterm bracketed-paste delivers \r (CR) as line separator, but PromptV2 splits buffer on \n only (src/tui/PromptV2.tsx:50). Pasting "line1\nline2" resulted in user echo bubble paste-line-Be-A (CR overwrite) and history JSONL stored literal \r. Suggested fix: normalize CR/CRLF/LF in the paste-burst branch.

// src/tui/PromptV2.tsx:~94
if (input && input.length > 1 && !key.ctrl && !key.meta) {
  insertText(input.replace(/\r\n?|\u2028|\u2029/g, "\n"));
  return;
}

🔴 DEFECT 2 — React duplicate-key warning on transcript pushes
Encountered two children with the same key, '16' (then '18', '4') logged repeatedly. Likely idRef.current += 1 race in a StrictMode double-render. Should use a stable counter inside the setTranscript updater.

⚠️ MISLEADING — placeholder says "Shift+Enter for newline" but xterm/most terminals don't forward shift modifier with Return. Either document the workaround (paste / Ctrl+J) or update placeholder.

ℹ️ DEAD CODE — /search empty-history branch: app.tsx:391 pushes prompt to history before slash dispatch, so by the time /search runs, the file always exists. The "No prompt history yet." branch in src/commands/search.ts is unreachable.

Test results

Tests verified live in TUI (click to collapse)

• ✅ /palette — lists commands grouped into Session / Editing / Provider / Sandbox+MCP buckets (Misc empty by design)
• ✅ /mode debug — DebugPanel mounts with state/label/terminal/flags/mcpServers/browserEngine/transcript rows
• ✅ /mode focus — banner + StatusBar + LogoAnimator + bottom hint all hidden
• ✅ /mode normal — StatusBar + LogoAnimator restored (banner intentionally stays hidden when transcript exceeds startup length)
• ✅ /theme cyber — prompt arrow + status dot recolored cyan-bright; user bubble magenta-bright
• ✅ /theme nocolor — all UI in plain white; cyan/magenta accents disappear
• 🐛 PromptV2 multiline + history recall — partial: Up arrow recall works; multiline via Shift+Enter blocked by xterm; multiline via paste corrupts buffer (DEFECT 1)
• ✅ /search palette — found 2 matches with timestamps from persisted JSONL
• 🟡 /search empty-history fallback — untested: dead code path under normal flow
• ✅ NO_COLOR=1 boot — auto-theme switches to nocolor; banner monochrome white; LogoAnimator uses ASCII tier > < > <
• ✅ Idle logo animation — captured both frames ◆◇◆◇◆◇ and ◇◆◇◆◇◆ at the 800ms cycle
• 🟡 Logo animation in thinking/executing/error/success/waiting states — untested visually: requires a live LLM call. Unit tests (test/logoAnimator.test.ts, test/stateMachine.test.ts) confirm FSM→frames mapping covers all 6 states.

Out of scope

• Real LLM round-trip (no API key)
• MCP server live connection (covered by test/mcpClient.test.ts)
• Headless browser (opt-in; covered by test/headlessEngine.test.ts)

Devin session: https://app.devin.ai/sessions/0e73b43883c04a17b651ca6aa7dc1a5e