Terminal UI Architecture

The frontend is a single-pane terminal-style interface. No scrolling, no route changes — everything happens within one fixed viewport through screen transitions.

Layout Structure

┌─────────────────────────────────────┐
│  TerminalHeader (h-12, fixed)       │  ← Email, logout, theme toggle
├─────────────────────────────────────┤
│  FourSquares (h-auto)               │  ← QUOTES | SPEAKERS | DATA | AGENTS
│  ┌────────┐ ┌────────┐             │     Thread-scoped counts
│  │ QUOTES │ │SPEAKERS│             │
│  │  47    │ │   12   │             │
│  └────────┘ └────────┘             │
│  ┌────────┐ ┌────────┐             │
│  │  DATA  │ │ AGENTS │             │
│  │   8    │ │   2    │             │
│  └────────┘ └────────┘             │
├─────────────────────────────────────┤
│                                     │
│  Terminal Viewport (flex-1)         │  ← Dynamic content, NO SCROLL
│                                     │
│  Renders current screen:            │
│  boot → search-input → trace →     │
│  synthesis → detail screens         │
│                                     │
├─────────────────────────────────────┤
│  BitTextarea (search input)         │  ← Always visible, 2-4 lines
│  "What do Bitcoiners believe..."    │
└─────────────────────────────────────┘

Screen State Machine

All 17 Screens

#	Screen	Description
1	boot	8-bit Bitcoin animation + curated quote (2-3 sec)
2	search-input	Mode picker (Direct/Playbook) + recent searches
3	trace	Real-time pipeline visualization (EMBED → SCAN → SYNTH)
4	synthesis	Agent answer with clickable speakers, sources
5	quotes	Thread belief cards, paginated, simple filters
6	belief	Full quote + ontology tree + related
7	speakers	Thread speakers with tier badges
8	speaker	Profile + stats + top beliefs + connections
9	data	Session stats + accumulated totals
10	agents	2x2 agent cards (Direct, Playbook, Oracle, Jackal)
11	playbook	4-lens breakdown + synthesis
12	share	Thread published with shareable link
13	oracle	Oracle agent info (planned)
14	jackal	Jackal agent info (planned)
15	mcp	MCP infrastructure info
16	threads	Thread management list
17	top-threads	Popular community threads

State Management (Zustand)

Key Patterns:

• searchNonce — incrementing counter triggers new search (not the query string itself)
• screenHistory — stack enables goBack() without losing context
• squareCounts — always scoped to active thread, reset on thread switch
• URL sync — debounced 100ms, bidirectional with ?screen=, ?q=, ?thread=

Component Hierarchy

8-Bit Retro Design System

The UI uses 8bitcn/ui registry components with a retro arcade aesthetic:

Element	Style
Colors	Bitcoin orange (#F7931A), dark navy (#1a1a2e)
Fonts	Space Grotesk (sans), JetBrains Mono (mono), Press Start 2P (pixel)
Borders	Pixel-art borders on TerminalPanel
Badges	Tier system: Legendary (gold), Epic (teal), Rare (purple), Common (orange)
Animations	Boot sequence, pipeline stages, card fade-ins
Cards	8-bit Card component with glow effects

No-Scroll Constraint

The terminal viewport never scrolls. Content must fit:

.main-container {
  height: 100dvh;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.terminal-viewport {
  flex: 1;
  min-height: 0;      /* critical for flex children */
  overflow: hidden;    /* no scroll */
}

Content that exceeds viewport is handled by:

• Pagination — belief cards paginate, not scroll
• Truncation — long text gets ellipsis
• Compression — previous results compress on follow-up
• Screen transitions — drill down via screen change, not expansion