# Idiot Box Planner — Prototype Context ## What This Is A visual prototype for **Idiot Box Planner**, a streaming subscription optimizer and watchlist manager. This is not production code — it is a reference prototype for developers who will rebuild it from scratch. The goal is to communicate intent, structure, and feel. **This spec is a living starting point.** Everything here represents the best thinking at the time the prototype was built. Once the prototype exists, all of it is open for revision — logic, views, algorithms, data structures. Treat this file as "what we decided going in," not "the final word." ## Core Idea The app answers two questions: 1. **What should I watch right now?** (filtered to what the user already pays for) 2. **What subscriptions should I keep, cancel, or switch to next month?** (based on the user's actual watchlist and a monthly budget cap) The financial optimization ("Rotate Churn") is the core value proposition — it treats every month as a blank slate and tells the user exactly which streaming services to keep, drop, subscribe to, or downgrade based on what they actually want to watch. ## Build Rules - **Plain HTML + CSS only** by default. No frameworks, no build tools. - **Vanilla JavaScript only when genuinely needed** — tab switching, show/hide, modals. Ask before adding anything beyond that. - **Realistic fake data** everywhere. No databases, no login, no backend calls. - All files live in this folder (`prototype planner/idiot box/`), one HTML file per view or a single multi-page HTML file if views are tightly linked. - When making a technical decision, explain what it means in plain English — not what it's called. ## Content Model How titles relate to each other. Five entity types, organized along two axes. ### Hierarchical axis (strict parent / child) `Franchise → Universe → Series → Title`. Each level is optional except Title. A title always has a Franchise (even if the "franchise" is just itself — a standalone film with no shared IP). - **Franchise** — the brand / IP. Examples: Marvel, Star Wars, Harry Potter, DC. Owns everything regardless of continuity. - **Universe** — a shared narrative continuity within a franchise. Examples: the MCU, Sony's Spider-Man Universe, the Skywalker Saga, the Wizarding World. **A franchise can contain multiple universes.** A title can belong to multiple universes (multi-membership — see below). - **Series** — an ordered sequence of titles. Examples: the Iron Man trilogy, the Fantastic Beasts trilogy, the original Skywalker trilogy. Usually lives inside a universe; can exist directly under a franchise when there's no shared continuity. **Series detail is folded into Universe detail** (or Franchise detail when seriesless-of-universe) — no dedicated Series page in the prototype. - **Title** — a single work. Either a Film or a Show. - **Show** — contains Seasons → Episodes. Structurally distinct from a film Series: a season is not a standalone work the way a sequel film is. ### Orthogonal axis (cross-cutting) - **Collection** — a curatorial / thematic grouping that crosses franchises and continuities. Examples: "Disney Animation Films," "A24 Catalog," "Studio Ghibli," "Best Picture Winners." **App-curated only — users use Lists for personal curation.** Collections reference titles directly and are not parent or child of anything in the hierarchy. ### Membership rules - **Multi-membership for universes is allowed.** Spider-Man crossover films legitimately belong to both the MCU and Sony's Spider-Man Universe. The UI lists all memberships rather than picking a "primary." - **One-off titles are not their own mini-universes.** A standalone Marvel film like the 2003 Hulk has Franchise = Marvel, Universe = none, Series = none. Loose nodes under a franchise are the norm, not the exception. - **Title detail (View 06)** shows Franchise / Universe / Series chips when each applies; chips disappear when the level is empty. ### Detail pages Each entity that warrants navigation gets its own detail page: - **Franchise detail (View 17)** — umbrella page listing all universes inside it, all series not in a universe, all one-off titles. Marvel is the reference example (most complex: MCU, Sony's Spider-Man Universe, Fox X-Men, Netflix Defenders-era, plus one-offs). - **Universe detail (View 16)** — the rich one. Phases or chronological tracks, watched / unwatched state, films and shows interleaved, multi-membership noted. MCU is the reference example. - **Show detail (View 18)** — distinct from film Title detail. Show → Seasons → Episodes, with per-season streaming availability (since shows commonly have seasons scattered across services). Loki is the reference example (TV show inside a universe). - **Collection detail (View 19)** — curated grid of titles, no narrative structure, no timeline. Disney Animation Films is the reference example. - **Title detail (View 06)** — film-specific. `06-title.html` is the single reference (Bill & Ted's Excellent Adventure: franchise + series, no universe). Membership chips/crumbs appear or disappear depending on which levels apply; orphan (franchise-only) and crossover (multi-universe) cases reuse the same layout — no separate variant files. ## Design Use the `wa-design` skill for all UI work. Do not invoke `frontend-design`. **The design system is locked.** See `NEXT.md` for the full spec and `mockups/01-home.html` for the reference implementation. Summary: Cinematic Utility aesthetic, flat obsidian dark default with light-mode support, peach (`#FFB59A`) as the single accent, Sora / Inter / JetBrains Mono type stack, horizontal rails (no grids, no sidebar), 16:9 backdrops for Continue Watching and 2:3 posters everywhere else. The Lineup (subscription manager, View 05) uses the **same** palette as the rest of the app — it differentiates through layout and component vocabulary (ledger rows, monospace numerics, status pills for Keep/Subscribe/Downgrade/Dump), not through a separate skin. Red is reserved for Dump/Cancel actions only. ## The 12 Views (Build Order TBD) ### View 01 — What To Watch (Landing / Home) The primary screen. Answers "what should I watch right now?" by filtering everything to the user's active subscriptions. Sections (top to bottom): - **Expiring Soon** — wishlist titles about to leave a platform the user pays for - **Wishlist Now Available** — high-priority wishlist titles currently streamable - **Recommended For You** — algorithm output, filtered to active subs only - **Other Lists** — titles from custom lists (e.g. "Family Movie Night") currently available Rules: - Every item shows a provider flag/icon (which service it's on) - Items marked "Completed" or "Hibernating" are completely hidden here --- ### View 02 — List Management (List of Lists) Central hub for managing multiple watchlists. - Directory of all lists with metadata (total items, unwatched count, who it's shared with) - Create / rename / delete lists - One default "Main Wishlist" that cannot be deleted - Sharing controls: invite collaborators, toggle Private vs. Shared - All active lists aggregate into a master watchlist that feeds the Subscription Optimizer --- ### View 03 — Single List View Detailed contents of one list. Key features: - Poster, title, year, streaming service badges - **Emphasis toggle** per title: "Must Watch" vs. "Nice to Watch" - Sort by: streaming service / theme / release date / added date - Filter by: currently available vs. requires new subscription - **In Progress section:** shows season/episode progress + "X episodes left" cancellation countdown - **Hibernation:** shows waiting for a new season — hidden in collapsed section, suppressed from home view - **Event/Seasonal resurfacing:** titles tagged for a date (recurring like "Christmas Movies" or one-time like a flight) stay hidden until that window opens - **Rewatch Cooldowns:** "All-Time Favorite" titles get a countdown timer (e.g. 2 years) before resurfacing - **Shared list watch states:** "Watched by Derek" vs. group-watched — partial checkmarks for individual vs. group completion --- ### View 04 — Search and Explore Content discovery engine. - Global search bar with immediate "Where to Watch" results (Stream / Rent / Buy) - Theme-based browsing: not just genres, but specific clusters (e.g. "Dystopian Cyberpunk" not just "Sci-Fi") - **Universe Mapping:** visual franchise timelines (MCU, Star Wars) with watched/unwatched highlights - **Add to List flow:** mimics a music app's "Add to Playlist" — prompts for Must Watch vs. Nice to Watch during the add - Optional: Trending section (global or among friends) --- ### View 05 — Subscription Manager ("The Brain") The core value proposition. Translates watchlist desires into a monthly financial plan. Sections: - **Budget input:** monthly cap in USD/CAD/GBP/EUR - **The Optimization Plan (Rotate Churn output):** - **Keep** — active services worth keeping - **Subscribe To** — inactive services with critical-mass Must Watch content - **Downgrade** — services where a cheaper ad-supported tier beats canceling entirely - **Dump** — active services the user has exhausted - **Actionable Links:** step-by-step cancel/downgrade/sign-up instructions with direct deep links to each platform's account management page - **Savings Tracker:** "Total Saved This Year" counter — calculates cost of paused services vs. what would have been spent Algorithm weights: priority tags, content expiration dates, episode counts left on in-progress shows, estimated runtime vs. days left in billing cycle. --- ### View 06 — Title Details Card (Modal / Page) Opens when tapping any poster from anywhere in the app. - Poster, title, year, genre tags, runtime/episode count, cast/crew, synopsis - Universe link if part of a franchise - "Where to Watch" clearly showing active sub (highlighted) vs. inactive (dimmed) - Primary actions: - Add to List (with Must Watch / Nice to Watch prompt) - Tag for Event/Date - Watch Now (deep link to native app, if on active sub) - Mark as Watched / Rate (4-Point Feedback) - Set Rewatch Cooldown - Mark as Completed / Hibernating --- ### View 07 — Profile & Integrations Personal ecosystem settings. - Region selector (determines which streaming library is queried) - Content filters / parental controls - Integration Hub: connect Trakt.tv, Plex, Jellyfin, Kodi (OAuth/API token) - Billing defaults: currency preference, default monthly budget cap --- ### View 08 — Social & Friends (The Network) Watch Together features. - Friend management (find, add, approve) - **Ad-Hoc Watch Party:** host selects friends in the room → app intersects everyone's watchlists + taste profiles + host's active subscriptions → outputs top 5 recommendations available right now - Optional Social Feed: public actions from friends (e.g. "Derek marked Dune Part Two as Must Watch") **No persistent Groups in v1.** Shared Lists cover collaborative curation; the Watch Party picker covers "who's here tonight." Revisit only if user testing shows people repeatedly picking the same roster — at which point Groups would ship as a saved shortcut, not a new primitive with its own taste profile. --- ### View 09 — Onboarding Fast, visual setup flow. Three discrete steps, each its own focused screen. - **Step 1 — The Wallet:** set monthly budget cap + select current streaming subscriptions from a logo grid - **Step 2 — Taste Seeding:** rapid-fire swipe/tap rating of ~20 "High-Footprint" titles (culturally massive, thematically distinct). Options: Loved It / Not For Me / Haven't Seen But Interested / Haven't Seen Don't Care - **Step 3 — Opt-In:** optional email or push notification setup for monthly Subscription Strategy alerts --- ### View 10 — Settings & Watch History The app's "backend configuration." - Watch History log: chronological, editable ratings, deletable entries - Notification preferences: in-app inbox + email/push toggles per alert type - Global settings: theme (Light / Dark / System), budget cap, integrations access - Privacy Policy & Support links --- ### View 11 — Marketing Site Single-page, high-impact landing page for prospective users. - Hero: financial savings headline ("Stop paying for Netflix when you're only watching Hulu."), "Start Saving" CTA - How It Works: 3-step visual loop (Build watchlist → Set budget → Get the monthly plan) - Privacy pitch: "We don't need your name. We don't even need your email." --- ### View 12 — Authentication & Privacy Low-friction, privacy-first account creation. Three paths: 1. **Username + Recovery Key** — no email required; app generates a 12-word recovery phrase on signup; unrecoverable if both username and key are lost 2. **Sign in with Apple** — supports "Hide My Email" (proxy email forwarding via Apple Relay); maximum privacy 3. **Sign in with Google** — real email collected; email is the absolute maximum PII the app ever stores Optional: users on path 1 can add an email later in Settings for notifications and password recovery fallback. --- ## Algorithms Full specs live in separate files — read those for implementation detail. The prototype uses static fake data for all algorithm output. - [algo-recommendation-engine.md](algo-recommendation-engine.md) — Content Recommendation Engine ("What to Watch"): hybrid thematic + collaborative scoring, 4-point feedback, recency decay, group veto formula, cold-start seeding, embeddings vs. explicit tags discussion - [algo-rotate-churn.md](algo-rotate-churn.md) — Subscription Optimization Engine ("Rotate Churn"): Zero-Based Budgeting, Platform Utility Score, knapsack allocation, bundle/tier/reseller handling, savings tracking, 5-step processing loop, guardrails --- **Tier 1:** Netflix, Hulu, Max, Amazon Prime Video, Disney+, Apple TV+, Peacock, Paramount+ **Tier 2:** AMC+, MGM+, Starz, Crunchyroll, HIDIVE, Shudder, Screambox, Acorn TV, Curiosity Stream, PBS Documentaries, PBS Kids **Free (FAST):** Tubi, The Roku Channel, Plex (ad-supported catalog) **Personal:** Plex (user's own server library) --- ## External APIs Referenced (for Prototype Fake Data Labels) - **TMDB** — metadata, relationships, popularity - **Watchmode / JustWatch / Streaming Availability API** — where titles stream + pricing - **Trakt.tv / Plex / Letterboxd** — watch history imports - **TheTVDB / TVmaze** — TV metadata and schedules - **Common Sense Media** — age ratings --- ## Key User Flows to Validate 1. **Search → Add → Subscription Impact:** User searches "The Bear," sees it's on Hulu (not active), marks Must Watch → Subscription Manager now recommends subscribing to Hulu. 2. **Monthly Rotate Churn Execution:** Notification → open Brain → see "Switch Max for Paramount+" recommendation → tap Confirm → get cancel/signup deep links → self-report "Did you do it?" 3. **Ad-Hoc Watch Party:** Host selects 2 friends → algorithm intersects watchlists + taste profiles + host's active subs → outputs top 5 streamable right now → all 3 mark it watched after.