pounce/UX_TERMINAL_UX_REPORT.md

# UX-Review: Pounce Terminal (Next.js User App)

Stand: 2025-12-19  
Scope: **alle Seiten unter** `frontend/src/app/terminal/*` (inkl. Subroute `intel/[tld]`) + globale Terminal-UX (Navigation, Feedback, Loading/Error, Mobile, Accessibility)  

---

## Executive Summary (was am meisten “zählt”)

Das Terminal wirkt visuell stark (klare Terminal-Ästhetik, konsistente Farbwelt, guter Einsatz von Stats/Badges). Die größten UX-Hebel liegen aktuell aber weniger im „Look“, sondern in **Konsistenz, Feedback-Loops und Bedienbarkeit**:

- **P0: Navigation/Chrome ist pro Seite dupliziert** (Mobile Header/Bottom Nav/Drawer) → Inkonsistenzen + Bugs (z.B. aktive Tabs/Routes falsch) + hoher Maintenance-Overhead.
- **P0: Keine globalen `loading.tsx` / `error.tsx`** im App Router → schlechte UX bei langsamen API-Calls und Edge-Fehlern.
- **P1: Mixed Feedback** (`alert/confirm`, Toast, inline) → mentaler Kontext-Switch + „unbranded“ Dialoge.
- **P1: Accessibility & Keyboard UX** (Focus Trap, ESC, ARIA-Rollen, Kontrast/Typografie bei 9–10px) → wirkt “pro”, aber ist für längere Sessions anstrengend.

---

## Quick Wins (1–2 Tage, hoher Impact)

- **Unify Terminal Shell**: Ein einziges Layout für Terminal (Sidebar + Topbar + Mobile Drawer + Bottom Nav) statt Copy/Paste pro Seite.
- **App Router Loading/Error**: `frontend/src/app/terminal/loading.tsx` + `frontend/src/app/terminal/error.tsx` (+ ggf. root-level) einführen.
- **Mobile Nav Active State fixen**: Aktive Route automatisch über `usePathname()` bestimmen (nicht hardcoded `active: true/false` Arrays).
- **Replace `alert/confirm`**: überall ein konsistentes Modal/Toast Pattern.
- **Modals**: ESC schließen, Fokus in Modal halten, `role="dialog"`, `aria-modal="true"`, initial focus auf primäres Feld/CTA.

---

## P0 / P1 / P2 – Priorisierte UX-Baustellen

### P0 – Blocker / deutliche UX-Schäden
- **Terminal Navigation/Chrome dupliziert**  
  Viele Seiten implementieren eigene Mobile Header/Bottom Nav/Drawer. Das führt zu:
  - inkonsistenten Labels (Radar/Hunt), unterschiedlichen Menüs, unterschiedlichen Drawer-Sections  
  - Bugs: aktive Navigation ist teils falsch oder gar nicht gesetzt (z.B. `/terminal/listing` hat mobileNavItems alle `active: false`)
  - fehlende Features in manchen Layouts (z.B. Notifications/Quick Search aus `components/TerminalLayout.tsx` werden in den meisten Terminal-Seiten nie genutzt)

- **Keine globalen Loading/Error States**  
  Es existieren keine `loading.tsx` / `error.tsx` im `app/` Tree. Bei langsamen Calls (Market Feed, TLD-Loads, WHOIS/Health) entsteht:
  - „Blank“/Springen zwischen States  
  - inkonsistente Loader-Stile pro Seite  
  - keine zentrale Recovery (Retry, Logging, Support CTA)

### P1 – hoher Impact, aber kein Blocker
- **Mixed Feedback & Confirmation UX**  
  Unterschiedliche Patterns je Seite: Toast (`Toast`), inline error blocks, aber auch `alert()` / `confirm()` (unbranded, nicht mobil-optimiert, blockierend).

- **Mobile IA/Navigation ist zu “kurz”**  
  Bottom Nav zeigt meist nur 4 Punkte (Hunt/Watch/Portfolio/Intel) → wichtige Module (Yield, Sniper, Inbox, For Sale, Settings) hängen hinter „Menu“, ohne klare Priorisierung oder Badges.

- **Intel lädt sehr viel Daten “am Client”**  
  `IntelPage` lädt bis zu 500 TLDs in einem Loop (100er chunks). UX-Probleme:
  - lange initiale Ladezeit
  - kein echtes Pagination/Search UX (Suche filtert lokal)
  - mobile wird schnell unübersichtlich

### P2 – polish / langfristige Qualität
- **Typografie & Kontrast**  
  Viele essenzielle Infos sind `text-white/30` oder `text-[9px]` → funktioniert “stylish”, aber wird bei langen Sessions anstrengend.
- **Keyboard-first**  
  Das Terminal-Feeling schreit nach Power-User Shortcuts (Cmd+K existiert, aber Search hat noch keine Results UX).

---

## Globale Empfehlungen (Terminal-weit)

### 1) Ein „Terminal Shell“ Layout (Single Source of Truth)
Ziel: **Sidebar + Topbar + Mobile Drawer + Mobile Bottom Nav** einmal bauen und Seiten nur noch Content rendern lassen.

Konkret:
- `frontend/src/app/terminal/layout.tsx` (auth guard) ist ok, aber **UI-Chrome sollte zusätzlich** in einem Layout/Wrapper passieren (z.B. `TerminalShellLayout`).
- `components/TerminalLayout.tsx` existiert bereits, wird aber primär nur auf `/terminal/welcome` genutzt.  
  Empfehlung: Entweder
  - **Option A**: `TerminalLayout` so erweitern, dass alle Terminal-Seiten ihn nutzen, oder
  - **Option B**: neue `TerminalShell` Komponente, die die wiederkehrenden Teile kapselt (Desktop+Mobile).

**Wichtig**: Mobile Bottom Nav muss aktive Route automatisch bestimmen (z.B. über `usePathname()`), sonst bleibt es fehleranfällig.

### 2) Konsistentes Feedback-System
Standardisieren:
- **Errors**: inline „ErrorCard“ mit Retry + „Details“ (expand), und optional „Contact support“ Link.
- **Confirms**: eigenes Confirm-Modal (nicht `confirm()`).
- **Success**: Toast.
- **Long-running**: progress + disable states + ggf. optimistic updates (macht ihr teils schon gut).

### 3) Modal Quality Bar (Accessibility + UX)
Alle Modals (Add/Verify/Thread/Wizards) sollten:
- ESC schließen
- Fokus im Modal halten (Focus Trap)
- `role="dialog"`, `aria-modal="true"`, `aria-labelledby`
- initial focus (erstes Input-Feld oder Primary CTA)
- „Close“ Button immer sichtbar
- bei kritischen Aktionen: klare irreversible Warnung + „Undo“ wo möglich

### 4) URL-State für Filter & Deep Links
Viele Seiten haben Filter/Sort/Search, aber Zustand ist oft nur in React State:
- Market: source/tld/price/hideSpam/search/page sollten in Query Params spiegeln (shareable links, back button korrekt).
- Intel: Filter und Search ebenfalls in URL.
- Inbox: ihr habt schon Query Param `inquiry` + `tab` → gutes Pattern, ausbauen.

### 5) “System Status” & Datenfrische
Für alle datengetriebenen Seiten ein einheitliches Muster:
- „Last updated“ + „Refresh“ (nicht überall gleich)
- bei Auto-refresh (Watchlist Tycoon): UI-Indikator „Auto-refresh active“ + letzte Hintergrund-Aktualisierung (sonst wirkt es „random“).

---

## Seitenreport (Terminal)

### `/terminal` (Redirect)
Ist aktuell ein Spinner + Redirect nach `/terminal/hunt`. UX ok, aber:
- **Verbesserung**: kurze Textzeile „Opening Terminal…“ (Barrierefreiheit, Kontext), plus “fallback link” falls Router hängt.

### `/terminal/welcome`
Starkes Upgrade-Confirmation Pattern (Feature Cards, Next Steps).  
UX-Fixes:
- Confetti nutzt `Math.random()` in render → kann bei Re-Renders „flackern“ / unruhig wirken.
- CTA Label “Go to Radar” führt nach `/terminal/hunt` (Terminologie konsistent halten: Hunt vs Radar).

### `/terminal/hunt`
Stärken:
- Tab UX (Search/Drops/Auctions/Trends/Forge) ist klar und fühlt sich wie ein “Workbench” an.

Probleme:
- Seite rendert eigene Sidebar + Mobile Drawer + Bottom Nav → **duplizierter Shell**.
- Mobile Bottom Nav hat „active“ hardcoded; ist hier ok, aber strukturell fragil.

Empfehlungen:
- Tabs als URL-State: `?tab=search|drops|...` (Deep link + Back button).
- Top-of-page: “What’s new / last updated” pro Tab (Drops/Auctions/Trends) um Datenfrische sichtbar zu machen.

### `/terminal/market`
Stärken:
- Gute Filter, Spam-Hide, Score Badges, Track/Analyze Actions.

Probleme:
- `searchQuery` wird sowohl server-seitig (API `keyword`) als auch client-seitig gefiltert → Doppel-Filter kann zu “WTF”-Momenten führen.
- Fehlerfall: bei API error wird `items=[]` gesetzt, aber **kein** Error UI (nur „No domains found“ → falsche Diagnose).
- Mobile Drawer/Bottom Nav duplicated.

Empfehlungen:
- Error UI unterscheiden: „0 Results“ vs „Load failed“.
- Filter in URL spiegeln.
- “Track” UX: wenn Domain schon getrackt ist und Remove passiert, muss UI klar „Removed from Watchlist“ anzeigen (Toast habt ihr), und optional Undo.

### `/terminal/intel`
Stärken:
- Tier Gating ist klar visualisiert (Locks, Upgrade CTA).
- Sort/Filter/Search UI ist solide.

Probleme:
- Große Client-Loads (bis 500 TLDs in 100er Schritten) → mobile/slow networks leiden.
- Duplicate nav/drawer.

Empfehlungen:
- Server-driven pagination: „Top 100 by popularity“ + search server-seitig, infinite scroll optional.
- “Renewal trap” als eigenes Filter/Badge prominent (weil es echte Entscheidung beeinflusst).

### `/terminal/intel/[tld]`
Stärken:
- Gute „Detail“-Informationsarchitektur (Chart + Domain Check + Registrar Tabelle).
- Lock Overlay für Scout ist gut.

Probleme:
- Domain Check Fehler wird nur `console.error`, kein UI-Feedback.
- Registrar-Link Fallback `'#'` (führt zu dead click) → besser: Button disabled + Tooltip „No registrar link available“.
- Duplicate nav/drawer.

Empfehlungen:
- Domain Check: inline error state + retry.
- Chart Tooltip: auf mobile fehlt Hover; optional Tap-to-inspect.

### `/terminal/watchlist`
Stärken:
- Sehr gutes Domain Operations UX (Alert toggle, Refresh, Health modal, Expiry tags).

Probleme:
- Mixed confirmations: `confirm('Drop target…')` ist unbranded und blockierend.
- Health-Autoload kann bei großen Listen viele Requests erzeugen; UX kann „unruhig“ werden (Loader überall).
- Duplicate nav/drawer.

Empfehlungen:
- Confirm Modal + optional Undo „Removed“.
- Health Cache: klarer Indikator „Health: cached at …“ vs „live check“.
- „Add domain“ Modal: Domain Normalisierung/Validation vor Submit (z.B. whitespace/protocol) + Inline errors.

### `/terminal/portfolio`
Stärken:
- Sehr umfangreich, aber erstaunlich gut strukturiert (Assets/Financials Tabs, CFO-Karten, KillList/BurnRate).
- DNS Verify Flow ist verständlich (2 Schritte, Copy Button).

Probleme:
- Auto Health checks (bis 20 Domains, delay 300ms) können initial lange dauern; ohne globalen “health loading” Kontext wirkt es wie “random spinners”.
- Viele Modals/Overlays, aber Fokus/ESC/ARIA nicht standardisiert.
- Duplicate nav/drawer (hier sogar unterschiedliche Drawer-Implementierungen).

Empfehlungen:
- Health prefetch optional machen (Toggle „Preload health on open“).
- “Financials” braucht klaren “data computed at” Stempel + “Refresh CFO” prominent.
- Vereinheitlichte Drawer/Bottom nav in Shell.

### `/terminal/listing` (For Sale)
Stärken:
- Wizard (Create Listing) ist ein gutes Pattern (Step 1–3).
- Leads Modal mit Thread UI ist sehr wertvoll (reale Workflows).

Probleme:
- Mobile Bottom Nav: `active` ist überall false → **Navigation Feedback kaputt**.
- Mixed feedback: `alert()` bei errors (publish/delete) → unbranded.
- Wizard Step 2: “DNS can take 1–5 minutes” ist ok, aber es fehlen “Where exactly to set TXT record?” Verweise/Links pro Registrar.

Empfehlungen:
- Active Nav fixen (global).
- Alerts/confirm ersetzen (Toast + Modal).
- Wizard: “Copy all fields” + “Open registrar docs” optional.
- Leads/Thread: auto-scroll to latest message + “unread” marker.

### `/terminal/inbox`
Stärken:
- Buying vs Selling Tabs; query-params unterstütztes Deep-Linking (gut!).
- Thread Pane Layout auf Desktop ist sinnvoll.

Probleme:
- Polling (15s messages, 30s threads) ohne sichtbaren „sync“ Indikator; kann „messages jumpen“ oder user verunsichern.
- Mobile Drawer ist sehr reduziert (Hunt/Watchlist/For Sale) → Missing core modules.

Empfehlungen:
- „Last synced“ + kleiner Spinner beim Poll refresh.
- Thread: “Sending…” state im Message Bubble optimistisch anzeigen.
- Mobile: Navigation vereinheitlichen (Shell).

### `/terminal/sniper`
Stärken:
- Übersicht mit Active/Matches/Sent Stats.
- Create/Edit Modal deckt viele Filter ab.

Probleme:
- Mixed feedback: `alert()` bei toggle/delete errors.
- Limit messaging: Scout maxAlerts=0, aber Settings-Plan Copy sagt “2 Sniper Alerts” → **Widerspruch** (führt zu Trust-Bruch).

Empfehlungen:
- Limits und Copy überall konsistent (Settings, Pricing, Backend).
- “Preview matches” wäre stark: pro Alert ein „Show matches“ (wenn Backend vorhanden).

### `/terminal/yield`
Stärken:
- Aktivierungsflow (Select Domain → DNS Setup → Verify) ist klar.
- Dashboard Tabelle liefert „operative“ KPIs.

Probleme:
- **Hardcoded IP** `46.235.147.194` im Frontend: UX/Trust & Ops-Risiko (kann sich ändern, Multi-env schwierig).
- Sehr viel `alert()/confirm()` für Verify/Delete → unbranded, keine Recovery UI.
- Tier-Gating Messaging: Modal Titel „Preview Yield Landing“ auch für Trader/Tycoon; das ist ok, aber sollte klarer sein.

Empfehlungen:
- IP & DNS instructions server/ENV-driven (z.B. `NEXT_PUBLIC_YIELD_SERVER_IP` + Backend liefert aktuelle DNS Targets).
- Verify/Delete: styled modal + inline results (verified/expected vs actual).
- “Landing Ready/Missing”: wenn missing, direkt CTA „Regenerate (Tycoon)“ mit Erklärung.

### `/terminal/settings`
Stärken:
- Gute Tabs (Profile/Alerts/Plans/Security), Plan Cards ordentlich.
- Referral/Invite ist sauber umgesetzt.

Probleme:
- Notification prefs werden nur in `localStorage` gespeichert → nicht cross-device, nicht auditierbar. (UX: „Saved“ wirkt, aber auf anderem Device weg.)
- “Email Verified” wird als immer verified angezeigt (UI Copy), unabhängig vom echten `user.is_verified` → UX/Trust Risiko.
- “Delete Account” Button ohne Flow (gefährlich).

Empfehlungen:
- Notification prefs in Backend persistieren (Endpoint z.B. `PUT /auth/notification-prefs` oder `PUT /users/me/preferences`).
- Security Tab: echten Status aus `user.is_verified` anzeigen + „Resend verification“ CTA falls false.
- Delete Account: confirm flow + export data + cooldown.

---

## Konsistenz-/Trust-Issues (wichtig für Conversion)

- **Plan Limits widersprüchlich**:  
  Beispiel: Sniper Limits in `/terminal/sniper` (scout: 0) vs Settings Plan Copy (Scout: “2 Sniper Alerts”). Das ist ein direkter Trust-Bruch.

- **Terminologie**: Radar vs Hunt; Terminal v1.0 in Drawer; “Go to Radar” aber Route `/terminal/hunt`.  
  Empfehlung: eine Terminologie festlegen (z.B. „Hunt“ überall) und konsequent.

---

## Messbare UX-KPIs (damit Improvements nachvollziehbar sind)

- **Time-to-first-useful-data** pro Seite (Market, Intel, Watchlist, Portfolio CFO)
- **Error rate** (API errors) pro Seite + Retry success rate
- **Completion rates**:
  - Listing Wizard Step 1→2→3
  - Yield Activation Step 1→2→3
  - DNS verification success time distribution
- **Engagement**:
  - Track/untrack from Market
  - Analyze opens per session
  - Inbox reply median time

---

## Konkrete nächste Schritte (Engineering Backlog Vorschlag)

### Phase 1 (P0): Shell + States
- Terminal Shell Layout bauen, alle Terminal-Seiten migrieren.
- `terminal/loading.tsx` + `terminal/error.tsx` einführen.
- Einheitliches Toast/Confirm/Modal Pattern.

### Phase 2 (P1): Data UX
- Market: echte Error UI + URL-state für Filter + klare Trennung API vs client filtering.
- Intel: server-driven pagination/search.
- Settings: Preferences persistieren + Security Status korrekt.

### Phase 3 (P2): Polish & Power-User
- Keyboard-first: Cmd+K Search mit echten Results + navigation.
- Accessibility sweep: Kontrast, Focus states, ARIA, reduced motion.