Research: Bubble Tea stack versions and architecture patterns

[aksOps]

Question

Surface the facts the scaffold needs: latest stable pinned versions and licenses of bubbletea, bubbles, lipgloss, glamour, and teatest; recommended architecture for multi-pane apps (model composition vs single model); mouse support API and its terminal caveats; teatest patterns for coverage-gated projects; SQLite data_version PRAGMA polling for change detection across processes. Capture findings as a markdown file on a research branch.

Part of #80.

[aksOps]

Research complete. Findings in docs/research/bubbletea-stack.md on branch research/bubbletea-stack.

Key findings:

• Pin the v2 line, canonical paths moved to charm.land: charm.land/bubbletea/v2 v2.0.8, bubbles/v2 v2.1.1, lipgloss/v2 v2.0.6, glamour/v2 v2.0.1 (all MIT; whole stack went v2-stable 2026-02-24). teatest is github.com/charmbracelet/x/exp/teatest/v2, untagged — pin pseudo-version v2.0.0-20260816001655-68d539dca504, test-only. modernc.org/sqlite v1.56.0 (BSD-3, SQLite 3.53.3) — upgrade from v1.54.0, keep modernc.org/libc in lockstep.
• Architecture: single root model owning focus enum, layout, and message routing; one package per pane (gh-dash sub-models vs crush imperative components both work). Crush rules to adopt: no IO in Update, no state mutation in commands.
• Mouse: v2 is declarative — View.MouseMode = tea.MouseModeCellMotion; events are MouseClickMsg/ReleaseMsg/WheelMsg/MotionMsg; hit-test via View.OnMouse or bubblezone/v2. v1's WithMouseCellMotion option is gone.
• teatest: NewTestModel + Send/Type, WaitFor(WithCheckInterval/WithDuration), FinalOutput + RequireEqualOutput goldens (-update); fix color profile for CI. No evidence real TUIs hold 95% statement coverage — goldens for rendering, pure-Update table tests for logic.
• PRAGMA data_version: correct primitive for cross-process write detection — changes only for other connections' commits (own commits compensated in btree.c), works across processes and under WAL; poll on one pinned *sql.Conn (~1 Hz, cost is a read-txn open + wal-index header check), never hold read txns open on the watcher.

Note: /docs/ is in .gitignore; the file was force-added. Decide whether to un-ignore docs/research/ when merging.