# TUI v3 Modular Architecture & Parity Plan Last updated: 2026-03-03 Branch target: `beta` Status: Active (Parity execution in progress) ## 1. Context & Rationale SeedPass has transitioned from TUI v2 to **TUI v3 (Scratch Rebuild)**. ### Why we moved on from v2: * **The Monolith Problem:** `tui_v2/app.py` exceeded 6,500 lines, making it impossible to maintain or refactor without significant regression risk. * **Crowded Layout:** v2 attempted to fit all views (Settings, Detailed Inspection, Grid) into a single frame, violating the professional application feel of the mockups. * **Brittle Interaction:** Action Strip click detection and manual string-painting led to a "ghost button" feel. * **V3 Solution:** Modular files (`widgets/`, `screens/`), proper Textual `push_screen` transitions, and a reactive "Board Architecture." *Note: The v2 plan (`docs/tui_v2_plan.md`) remains active as a logic reference, but UI/UX development is now focused here.* --- ## 2. Current Progress (The Foundation) We have successfully scaffolded the core v3 shell: - [x] **Modular Architecture:** Established `src/seedpass/tui_v3/` with sub-directories. - [x] **Factory Injection:** Reused all existing service hooks (Entry, Vault, Profile). - [x] **App Shell:** Working `MainScreen` with Sidebar, Header, Grid, and Inspector. - [x] **Full-Screen Transitions:** Working `SettingsScreen` and `MaximizedInspectorScreen`. - [x] **Board Architecture:** Implemented specialized ASCII cards for: - [x] Passwords - [x] Notes / Documents - [x] TOTP (with live ticking timer) - [x] BIP-39 Seeds - [x] SSH / PGP / Nostr / Key-Value - [x] **Core Interaction:** - [x] Command Palette (Ctrl+P) with command routing. - [x] Reveal (v) and QR (g) logic with double-press confirmation. - [x] Reactive Search and Selection. - [x] **Secure Data Parity:** Full support for reveal/QR/copy across Passwords, TOTP, SSH, PGP, Nostr, Seeds, and Documents. - [x] **Managed Sessions:** `ml` (Load) and `mx` (Exit) parity for BIP-85 sub-profiles. - [x] **Semantic Search:** Integration of `SemanticIndexService` into the TUI v3 grid with mode switching (Keyword, Hybrid, Semantic). - [x] **Entry Lifecycle:** Unified `AddEntryScreen`, `SeedPlusScreen` for derivations, and `DocumentEditScreen`. - [x] **Grid Filtering:** Filter presets (secrets, docs, keys, 2fa) and Archive toggle (`archived`). --- ## 3. Remaining Roadmap ### Phase A: Action Parity (COMPLETED) - [x] **Clipboard Integration:** `c` copies primary fields (Password, TOTP, PubKey, nsec, etc) as per v3 mockups. - [x] **Archive/Restore:** `a` toggle wired with grid refresh. - [x] **Managed Account Loading:** Full load/exit parity with reactive fingerprint updates. - [x] **Edit Workflows:** Unified `EditEntryScreen` implemented to support all types. ### Phase B: High-Fidelity Refinement - [x] **Mockup 1:1 Polish:** Final pass on spacing/density for all 9 PNG mockups. - [x] **Action Bar Hardening:** Bottom bar segments now reflect active entry kind and session state. - [x] **Notifications:** Unified snackbar/toast system for service feedback. - [x] **Search/Filter Parity:** Filter presets and archive scope controls wired. ### Phase C: Advanced Features - [x] **Semantic Search Integration:** Mode chips connected to `SemanticIndexService`. - [x] **Nostr Relay Management:** Dedicated screen/board for relay status and synchronization. --- ## 4. Functional Parity Protocol To finalize v3, we must verify 100% functional parity with the **Legacy TUI**. ### Test Checklist: 1. **Vault Setup:** Initialize profile, Change Password, Lock/Unlock. 2. **Entry Lifecycle:** Create (all types), Edit, Search, Archive, Restore, Delete. 3. **Secure Data:** Reveal (v), QR (g), Copy (c) across all high-risk types. 4. **Sub-profiles:** Load managed account, exit managed account, nested hierarchies. 5. **Data I/O:** DB Export/Import, Document Export, TOTP Export. 6. **Nostr Sync:** Fresh namespace, Relay management, Sync-now. ### Automation: `scripts/interactive_agent_tui_test.py` now supports v3 execution and currently validates baseline flows (selection, reveal confirmation, screen transitions, archive/copy trigger path). Additional strict parity assertions are still required before cutover. --- ## 5. Progress Log (2026-03-03) ### Completed in this session - **Secure Data Parity:** - Completed `_resolve_sensitive_payload` for SSH, PGP, Nostr, Key-Value, and Documents. - Updated `derive_pgp_key` and API to support armored PGP Public Key retrieval/copying. - Aligned copy/reveal semantics with mockup hints (e.g., SSH/PGP copy Pub by default). - **Managed Sessions:** - Added `action_managed_load` (`m`) and `action_managed_exit` (`Shift+M`) to v3. - Wired `ml` and `mx` commands to the palette. - **Search & Filters:** - Integrated `SemanticIndexService` into `EntryDataTable`. - Added `filter ` (secrets, docs, keys, 2fa) and `archived` view toggle. - Updated `GridMetrics` to show active filter, archive status, and search mode. - **Entry Lifecycle:** - Implemented `AddEntryScreen` (unified wizard) and `SeedPlusScreen` (BIP-85 derivations). - Implemented `DocumentEditScreen` with full-screen editor and Ctrl+S save path. - Added `action_export_selected` (`x`) for document-to-disk parity. - **UX & Hardening:** - Made `ActionBar` dynamic based on entry kind and managed session state. - Expanded v3 parity tests in `src/tests/test_tui_v3_parity.py` (Reveal/Copy/Archive/Add/Filter). - Fixed PGP key tuple alignment across `manager.py`, `api.py`, `entry_management.py`, and TUI v2. - **Nostr Integration:** - Completed Relay Management screen `src/seedpass/tui_v3/screens/relays.py`. - Added `[R]efresh`, `[D]elete`, and `[S]ync Now` capabilities. - Wired `relay-list` palette command to trigger interface. - **Notifications:** - Confirmed Textual's standard `app.notify()` satisfies the notification queue mockups uniformly across all TUI v3 screens. - **Data I/O & Entry Lifecycle:** - Expanded `EditEntryScreen` to support viewing and modifying all entry kind fields seamlessly without throwing unimplemented errors. - Extended `action_export_selected` to save individual `SSH`/`PGP`/`Nostr` key pairs and `TOTP` secrets directly to file identically to TUI v2. - Integrated `db-export` and `db-import` routines into the CommandPalette processor to reach 100% Vault I/O parity. ### Validation evidence - `pytest -q src/tests/test_tui_v3_parity.py` -> `4 passed` - All reveal/QR/copy semantics verified for high-risk kinds. - PGP Public key support confirmed in both TUI v2 and v3. - Nostr relay actions mapped back through internal configuration via `app.services['nostr']`.