# Unspooled UI/UX Rebuild Constitution

Received 2026-06-03. This is the master specification for all Unspooled Android TV development going forward.

## Authorized Reference Sources

The following repositories are intentionally available for analysis and reuse:

| Source | Path | Purpose |
|--------|------|---------|
| DebridStream (FudgeTV) | `/home/rurouni/Repos to copy/fudge_tv_compose_library-master` | Navigation stability, TV Material patterns, settings |
| NuvioTV | `/home/rurouni/projects/NuvioTV` | Metadata depth, focus persistence, expanded cards, trailers |
| Lumera | `/home/rurouni/projects/Lumera` | Visual design, motion, sidebar, glass effects |
| Wholphin | `/home/rurouni/Repos to copy/Wholphin-main` | Reference |
| HTML Reference UI | `/home/rurouni/I want this ui/` | Target visual appearance — UI must be identical |

**Rule:** If a component already works correctly in one of these projects: audit it → understand it → reuse it → refactor it → improve it. Do NOT reinvent.

## Non-Negotiable Rules

1. **Focus correctness > visuals.** A beautiful UI with broken focus is a failed implementation.
2. **Only one zone owns focus at a time.** Never allow overlapping ownership.
3. **No implicit focus movement.** Every screen must define UP/DOWN/LEFT/RIGHT/BACK explicitly.
4. **Settings: true two-column architecture.** Never navigate to separate screens for sub-settings.
5. **Reference repos are for copying.** Do not license-audit; copy freely and improve.

## Phase Status (verified 2026-06-03)

### Phase 0 — Complete Application Audit [TODO]
Generate UI_AUDIT.md covering: Home, Search, Movies, TV, Anime, Details, Player, Settings, Addons, Downloads, Profile, Authentication, Onboarding, Debrid, Trakt. Identify focus traps, dead ends, invisible focus, missing restoration, sidebar conflicts, navigation bugs, crashes, visual issues.

### Phase 1 — Global Focus Graph Architecture [PARTIAL]
TvFocusZone has 8 zones: Sidebar, Content, SettingsCategory, SettingsDetail, SourceList, PlayerControls, ModalDialog, PlayerVideo.
**Missing from constitution spec:** SEARCH_INPUT, SEARCH_RESULTS, DETAILS_ACTIONS.

### Phase 2 — Focus Graph Topology [PARTIAL]
FocusLinks + focusProperties active on key screens (Search, Details, Player). Not all screens have explicit directional wiring verified.

### Phase 3 — Sidebar Rebuild [PARTIAL]
GlassSidebar + UnifiedChromeScaffold active. Needs: Lumera glass effects, visual polish, 72-80dp collapsed / 220-260dp expanded verification, profile avatar, accent bar, gradient mask, status indicators.

### Phase 4 — Home Screen Rebuild [DONE]
UnspooledHomeScreen with MVI, HomeScreenFocusState, catalog focus persistence, row focus persistence, velocity-aware settled focus, adaptive halos, directional expansion.

### Phase 5 — Card System [DONE]
PremiumContentCard + PremiumContentCardDisplay + FocusedMediaCard. Poster mode, expanded mode, hero mode. Adaptive glow, palette-based focus color. Stable focus IDs.

### Phase 6 — Settings Rebuild [NEEDS WORK]
Two-column exists but uses separate nav routes for sub-settings. Constitution requires "Never navigate to separate screens" — all sub-settings should render inline in the right pane.

### Phase 7 — Search Rebuild [DONE]
Focus zones SEARCH_INPUT + SEARCH_RESULTS. Keyboard→genres→results chain with grid-aware FocusLinks.

### Phase 8 — Details Page Rebuild [DONE]
Initial focus: Play/Resume/Sources. Source list as focus zone. Background actions disabled. Back restores originating catalog card.

### Phase 9 — Player Rebuild [DONE]
Nuvio-style PlayerOverlayScaffold with per-item FocusRequester graphs (45 in SelectionPanels, 26 in SourceSidePanel). Return-focus restoration. Auto-fallback flow.

### Phase 10 — Audio Feedback System [NOT WIRED]
SoundPoolManager + FocusAudioFeedback defined. **0 consumers.** Must wire to: focus move, sidebar open/close, dialog open/close, success, error. Respect system volume, disableable, low latency.

### Phase 11 — Responsive Design [NOT STARTED]
Must support: 720p, 1080p, 1440p, 4K. Google TV, Fire TV, Shield, Chromecast. No clipping, no cut-off text, no oversized layouts.

### Phase 12 — Performance [NOT STARTED]
Target: 60 FPS. Baseline Profiles, Macrobenchmark, JankStats. No jank, no focus lag, no frame drops, no trailer stutter, no sidebar lag.

### Phase 13 — Accessibility [PARTIAL]
TvAccessibility.kt foundation exists (79 contentDescription hits in codebase). Needs: large text, reduced motion, high contrast, colorblind support, screen reader traversal verification.

### Phase 14 — Validation [NOT DONE]
Entire app navigable with remote. No focus traps, no invisible focus, no random jumps, no dead ends. Sidebar/Player/Settings all behave correctly. Focus restoration works. Performance targets achieved.

## Constitution Source
Original document saved as `doc_ef12f6255901_message.txt` in Hermes cache.