SeedPass/docs/tui_v3_plan.md

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:

• Modular Architecture: Established src/seedpass/tui_v3/ with sub-directories.
• Factory Injection: Reused all existing service hooks (Entry, Vault, Profile).
• App Shell: Working MainScreen with Sidebar, Header, Grid, and Inspector.
• Full-Screen Transitions: Working SettingsScreen and MaximizedInspectorScreen.
• Board Architecture: Implemented specialized ASCII cards for:
  • Passwords
  • Notes / Documents
  • TOTP (with live ticking timer)
  • BIP-39 Seeds
  • SSH / PGP / Nostr / Key-Value
• Core Interaction:
  • Command Palette (Ctrl+P) with command routing.
  • Reveal (v) and QR (g) logic with double-press confirmation.
  • Reactive Search and Selection.
  • Secure Data Parity: Full support for reveal/QR/copy across Passwords, TOTP, SSH, PGP, Nostr, Seeds, and Documents.
  • Managed Sessions: ml (Load) and mx (Exit) parity for BIP-85 sub-profiles.
  • Semantic Search: Integration of SemanticIndexService into the TUI v3 grid with mode switching (Keyword, Hybrid, Semantic).
  • Entry Lifecycle: Unified AddEntryScreen, SeedPlusScreen for derivations, and DocumentEditScreen.
  • Grid Filtering: Filter presets (secrets, docs, keys, 2fa) and Archive toggle (archived).

---

3. Remaining Roadmap

Phase A: Action Parity (COMPLETED)

• Clipboard Integration: c copies primary fields (Password, TOTP, PubKey, nsec, etc) as per v3 mockups.
• Archive/Restore: a toggle wired with grid refresh.
• Managed Account Loading: Full load/exit parity with reactive fingerprint updates.
• Edit Workflows: DocumentEditScreen implemented.

Phase B: High-Fidelity Refinement

• Mockup 1:1 Polish: Final pass on spacing/density for all 9 PNG mockups.
• Action Bar Hardening: Bottom bar segments now reflect active entry kind and session state.
• Notifications: Unified snackbar/toast system for service feedback.
• Search/Filter Parity: Filter presets and archive scope controls wired.

Phase C: Advanced Features

• Semantic Search Integration: Mode chips connected to SemanticIndexService.
• 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 <kind> (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.

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.