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
parent
70f8030ae4
commit
2723fbf4be
4 changed files with 581 additions and 0 deletions
177
docs/phases.md
Normal file
177
docs/phases.md
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
# BTerminal v2 — Implementation Phases
|
||||
|
||||
See [task_plan.md](task_plan.md) for architecture decisions, error handling, and testing strategy.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Project Scaffolding [status: not_started] — MVP
|
||||
|
||||
- [ ] Create feature branch `v2-mission-control`
|
||||
- [ ] Initialize Tauri 2.x project with Svelte 5 frontend
|
||||
- [ ] Project structure (see below)
|
||||
- [ ] Basic Tauri window with Catppuccin Mocha CSS variables
|
||||
- [ ] Verify Tauri builds and launches on target system
|
||||
- [ ] Set up dev scripts (dev, build, lint)
|
||||
|
||||
### File Structure
|
||||
```
|
||||
bterminal-v2/
|
||||
src-tauri/
|
||||
src/
|
||||
main.rs # Tauri app entry
|
||||
pty.rs # PTY management (portable-pty, not plugin)
|
||||
sidecar.rs # Node.js sidecar lifecycle (spawn, restart, health)
|
||||
watcher.rs # File watcher for markdown viewer
|
||||
session.rs # Session persistence (SQLite via rusqlite)
|
||||
Cargo.toml
|
||||
src/
|
||||
App.svelte # Root layout
|
||||
lib/
|
||||
components/
|
||||
Layout/
|
||||
TilingGrid.svelte # Dynamic tiling manager
|
||||
PaneContainer.svelte # Individual pane wrapper
|
||||
PaneHeader.svelte # Pane title bar with controls
|
||||
Terminal/
|
||||
TerminalPane.svelte # xterm.js terminal pane
|
||||
Agent/
|
||||
AgentPane.svelte # SDK agent structured output
|
||||
AgentTree.svelte # Subagent tree visualization
|
||||
ToolCallCard.svelte # Individual tool call display
|
||||
Markdown/
|
||||
MarkdownPane.svelte # Live markdown file viewer
|
||||
Sidebar/
|
||||
SessionList.svelte # Session browser
|
||||
stores/
|
||||
sessions.ts # Session state ($state runes)
|
||||
agents.ts # Active agent tracking
|
||||
layout.ts # Pane layout state
|
||||
adapters/
|
||||
sdk-messages.ts # SDK message abstraction layer
|
||||
pty-bridge.ts # PTY IPC wrapper
|
||||
styles/
|
||||
catppuccin.css # Theme CSS variables
|
||||
app.css
|
||||
sidecar/
|
||||
agent-runner.ts # Node.js sidecar entry point
|
||||
package.json # Agent SDK dependency
|
||||
esbuild.config.ts # Bundle to single file
|
||||
package.json
|
||||
svelte.config.js
|
||||
vite.config.ts
|
||||
tauri.conf.json
|
||||
```
|
||||
|
||||
**Key change from v1:** Using portable-pty directly from Rust instead of tauri-plugin-pty (38-star community plugin). portable-pty is well-maintained (used by WezTerm). More work upfront, more reliable long-term.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Terminal Pane + Layout [status: not_started] — MVP
|
||||
|
||||
### Layout (responsive)
|
||||
|
||||
**32:9 (5120px) — full density:**
|
||||
```
|
||||
+--------+------------------------------------+--------+
|
||||
|Sidebar | 2-4 panes, CSS Grid, resizable | Right |
|
||||
| 260px | | 380px |
|
||||
+--------+------------------------------------+--------+
|
||||
```
|
||||
|
||||
**16:9 (1920px) — degraded but functional:**
|
||||
```
|
||||
+--------+-------------------------+
|
||||
|Sidebar | 1-2 panes | (right panel collapses to overlay)
|
||||
| 240px | |
|
||||
+--------+-------------------------+
|
||||
```
|
||||
|
||||
- [ ] CSS Grid layout with sidebar + main area + optional right panel
|
||||
- [ ] Responsive breakpoints (ultrawide / standard / narrow)
|
||||
- [ ] Pane resize via drag handles (use CSS `resize` or lightweight lib)
|
||||
- [ ] Layout presets: 1-col, 2-col, 3-col, 2x2, master+stack
|
||||
- [ ] Save/restore layout to SQLite
|
||||
- [ ] Keyboard: Ctrl+1-4 focus pane, Ctrl+Shift+arrows move
|
||||
|
||||
### Terminal
|
||||
- [ ] xterm.js with Canvas addon (explicit — no WebGL dependency)
|
||||
- [ ] Catppuccin Mocha theme for xterm.js
|
||||
- [ ] PTY spawn from Rust (portable-pty), stream to frontend via Tauri events
|
||||
- [ ] Terminal resize -> PTY resize
|
||||
- [ ] Copy/paste (Ctrl+Shift+C/V)
|
||||
- [ ] SSH session: spawn `ssh` command in PTY
|
||||
- [ ] Local shell: spawn user's $SHELL
|
||||
- [ ] Claude Code CLI: spawn `claude` in PTY (fallback mode)
|
||||
|
||||
**Milestone: After Phase 2, we have a working multi-pane terminal.** Usable as a daily driver even without agent features.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Agent SDK Integration [status: not_started] — MVP
|
||||
|
||||
- [ ] Node.js sidecar: thin wrapper around Agent SDK `query()`
|
||||
- [ ] Sidecar communication: Rust spawns Node.js, stdio NDJSON
|
||||
- [ ] Sidecar lifecycle: spawn on demand, detect crash, restart
|
||||
- [ ] SDK message adapter (abstraction layer)
|
||||
- [ ] Agent pane: renders structured messages
|
||||
- Text -> markdown rendered
|
||||
- Tool calls -> collapsible cards (tool name + input + output)
|
||||
- Subagent spawn -> tree node + optional new pane
|
||||
- Errors -> highlighted error card
|
||||
- Cost/tokens -> pane header metrics
|
||||
- [ ] Auto-scroll with scroll-lock on user scroll-up
|
||||
- [ ] Agent status indicator (running/thinking/waiting/done/error)
|
||||
- [ ] Start/stop/cancel agent from UI
|
||||
- [ ] Session resume (SDK `resume: sessionId`)
|
||||
|
||||
**Milestone: After Phase 3, we have the core differentiator.** SDK agents run in structured panes alongside raw terminals.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Session Management + Markdown Viewer [status: not_started] — MVP
|
||||
|
||||
### Sessions
|
||||
- [ ] SQLite persistence for sessions (rusqlite)
|
||||
- [ ] Session types: SSH, Claude CLI, Agent SDK, Local Shell
|
||||
- [ ] Session CRUD in sidebar
|
||||
- [ ] Session groups/folders
|
||||
- [ ] Remember last layout on restart
|
||||
|
||||
### Markdown Viewer
|
||||
- [ ] File watcher (notify crate) -> Tauri events -> frontend
|
||||
- [ ] Markdown rendering (marked.js or remark)
|
||||
- [ ] Syntax highlighting (Shiki)
|
||||
- [ ] Open from sidebar or from agent output file references
|
||||
- [ ] Debounce file watcher (200ms)
|
||||
|
||||
**Milestone: After Phase 4 = MVP ship.** Full session management, structured agent panes, terminal panes, markdown viewer.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Agent Tree + Polish [status: not_started] — Post-MVP
|
||||
|
||||
- [ ] Agent tree visualization (SVG, compact horizontal layout)
|
||||
- [ ] Click tree node -> focus agent pane
|
||||
- [ ] Aggregate cost per subtree
|
||||
- [ ] Global status bar (total cost, active agents, uptime)
|
||||
- [ ] Notification system (agent done, error)
|
||||
- [ ] Global keyboard shortcuts
|
||||
- [ ] Settings dialog
|
||||
- [ ] ctx integration (port from v1)
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Packaging + Distribution [status: not_started] — Post-MVP
|
||||
|
||||
- [ ] install.sh v2 (check Node.js, install Tauri runtime deps)
|
||||
- [ ] AppImage build (single file, works everywhere)
|
||||
- [ ] .deb package (Debian/Ubuntu)
|
||||
- [ ] GitHub Actions CI for building releases
|
||||
- [ ] Auto-update mechanism (Tauri updater)
|
||||
- [ ] Migrate bterminal.svg icon
|
||||
- [ ] README update
|
||||
|
||||
### System Requirements
|
||||
- Node.js 20+ (for Agent SDK sidecar)
|
||||
- WebKit2GTK 4.1+ (Tauri runtime)
|
||||
- Linux x86_64 (primary target)
|
||||
Loading…
Add table
Add a link
Reference in a new issue