docs: add v2 architecture planning and research findings

Architecture decision: Tauri 2.x + Svelte 5 + Claude Agent SDK (Node.js sidecar).
Includes research on Agent SDK streaming, xterm.js performance, WebKit2GTK
limitations, and adversarial review corrections (two-tier observation, Svelte 5
over Solid.js, SDK abstraction layer). Six implementation phases defined,
MVP = Phases 1-4.
This commit is contained in:
Hibryda 2026-03-05 22:49:00 +01:00
parent 70f8030ae4
commit 2723fbf4be
4 changed files with 581 additions and 0 deletions

37
docs/progress.md Normal file
View file

@ -0,0 +1,37 @@
# BTerminal v2 — Progress Log
## Session: 2026-03-05
### Research Phase (complete)
- [x] Analyzed current BTerminal v1 codebase (2092 lines Python, GTK3+VTE)
- [x] Queried Memora — no existing BTerminal memories
- [x] Researched Claude Agent SDK — found structured streaming, subagent tracking, hooks
- [x] Researched Tauri + xterm.js ecosystem — found 4+ working projects
- [x] Researched terminal latency benchmarks — xterm.js acceptable for AI output
- [x] Researched 32:9 ultrawide layout patterns
- [x] Evaluated GTK4 vs Tauri vs pure Rust — Tauri wins for this use case
- [x] Created task_plan.md with 8 phases
- [x] Created findings.md with 7 research areas
### Technology Decision (complete)
- Decision: **Tauri 2.x + Solid.js + Claude Agent SDK + xterm.js**
- Rationale documented in task_plan.md Phase 0
### Adversarial Review (complete)
- [x] Spawned devil's advocate agent to attack the plan
- [x] Identified 5 fatal/critical issues:
1. Node.js sidecar requirement unacknowledged
2. SDK 0.2.x instability — need abstraction layer
3. Three-tier observation overengineered → simplified to two-tier
4. Solid.js ecosystem too small → switched to Svelte 5
5. Missing: packaging, error handling, testing, responsive design
- [x] Revised plan (Rev 2) incorporating all corrections
- [x] Added error handling strategy table
- [x] Added testing strategy table
- [x] Defined MVP boundary (Phases 1-4)
- [x] Added responsive layout requirement (1920px degraded mode)
### Next Steps
- [ ] Present plan to user for review and decision
- [ ] Create feature branch
- [ ] Begin Phase 1: Project scaffolding