Custom Raspberry Pi Media Box Development "PI-TV"

Project Goal:
Build a custom Raspberry Pi media box that functions exactly like a Fire TV / smart TV interface, but dedicated to quick-launching streaming websites and services. The system must feel polished, responsive, and fully TV-native. It runs on a Raspberry Pi 5 (recommended) connected to a TV via HDMI, controlled primarily with the TV remote via HDMI-CEC, and managed remotely via a phone web app.

Core Requirements: (detailed in sections 1-6 below)

1. Boot & Power Behavior
- The Pi should boot automatically when the TV is turned on (using HDMI-CEC power sync or HDMI signal detection).
- Boots directly into a full-screen custom home launcher (no desktop environment visible).
- Restores the last-used resolution and settings on boot. First boot defaults safely to 1080p.

2. Home Screen Layout (Fire TV / Smart TV style)
- Customizable wallpaper (upload via phone web app; supports multiple images, presets, or dynamic options).
- Top bar: Prominent search bar (for quickly finding channels/apps), Settings gear icon (top-right).
- Grid of channel tiles ("apps") displayed as large square/rectangular tiles with: Custom label/name + Icon/image (auto-fetch favicon/og:image/site logo with fallback placeholder).
- Support for **genres/categories** (Movies, TV Shows, Sports, Favorites, News, etc.). Tiles grouped/filtered by genre; users can create custom genres.
- Smooth D-pad + select navigation via TV remote (CEC). Highlighted tile enlarges with animations.
- TV Remote Home button always returns to this home screen. Search filters channels in real-time (including genre support).

3. Launching Websites
- Every channel launches its URL in **LibreWolf** (Firefox-based with strong built-in ad/tracker blocking) in true fullscreen/kiosk mode (no chrome, address bar, tabs, or toolbars).
- Pre-configure Vimium (or Vimium C) extension for excellent keyboard/D-pad navigation on all sites, including YouTube.
- TV remote Back button acts as browser "back". Smooth transitions to/from launcher.

**4. Phone Web App (Admin/Management Interface)**
- Responsive React dashboard served by the Pi (accessible via local IP or mDNS `pi-tv.local`).
- Features: Add/edit/delete/re-order channels (URL + label + one or more genres), upload custom icons, create/manage genres, wallpaper management, VPN domain exceptions (checkbox "Disconnect VPN for this domain", default = always on), and sync other settings.
- Secure with password or local-network only.

5. Settings Menu (Mimic Fire TV style and flow)
Tabbed/sidebar navigation with TV remote. Logical order:
- Network: Wi-Fi scan/connect (on-screen keyboard), Ethernet status, VPN (status, toggle, Mullvad/ProtonVPN WireGuard support, server/region, auto-connect + kill-switch, per-domain rules).
- Channels: Add/remove/edit with genre assignment.
- Display / Picture Settings: Resolution (with countdown confirm dialog — no confirm reverts to previous safe setting), advanced controls (brightness, contrast, R/G/B, gamma, saturation, aspect ratio, refresh rate), presets (Movie, Game, Theater, Night, etc.), live preview, first-boot 1080p safe default.
- Wallpaper, Volume & Audio, Accessibility, System (reboot/shutdown/updates/backup).

6. Additional Polish & Features
- Full HDMI-CEC: power sync + intuitive navigation everywhere (including inside LibreWolf via Vimium).
- VPN always-on by default (privacy-first) with smart configurable exceptions.
- Dark theme, TV-optimized fonts/sizes, smooth animations, on-screen keyboard, quiet 24/7 operation, automatic updates, logging/troubleshooting.

Recommended Architecture & Stack
- OS: Raspberry Pi OS Lite (Debian Bookworm) on Pi 5.
- Launcher: Local web app (React) served by Node.js/Express, running fullscreen via kiosk shell (X11 + xinit/openbox recommended for tooling).
- Browser: LibreWolf in dedicated profile with --kiosk + Vimium preinstalled; wrapper script for isolation and return-to-launcher on exit.
- Backend: Express + SQLite for channels, genres, settings, icons/wallpapers (/var/lib/pi-tv). WebSocket for live updates to launcher.
- CEC: libCEC / cec-client daemon + service to map keys to xdotool / uinput / launcher API.
- VPN: WireGuard (Mullvad/Proton) with per-domain exceptions (PAC + proxy or network namespaces).
- Autostart: systemd units with watchdog. On-screen keyboard: onboard or matchbox.
- Persistence & security: SQLite + JSON assets, local-only or password-protected management UI.

MVP Scope
1. Boot to kiosk web launcher (1080p safe).
2. React home screen with D-pad nav, tiles, search, genres.
3. Phone web UI + API to manage channels/genres (SQLite).
4. LibreWolf kiosk launch with Vimium + back mapping.
5. Basic CEC for Home/Back/D-pad.
6. Persistent settings + safe resolution confirm.
7. Global VPN toggle.

Implementation Roadmap (Phases)
- Phase A (Foundation): Pi setup, systemd kiosk boot, basic React launcher + LibreWolf wrapper.
- **Phase B (Remote Management)**: Express API + SQLite, phone React dashboard, WebSocket sync.
- Phase C (CEC & Input): Full remote mapping, on-screen keyboard, focus/animations.
- Phase D (VPN): WireGuard auto-connect + per-domain exceptions (detail tradeoffs: IP routes, PAC/proxy, or namespaces).
- Phase E (Polish): Full settings menu (including display confirm dialog, presets), wallpaper, themes, system features.
- Phase F (Hardening): Security, updates, backups, testing.

Critical Technical Notes
- Kiosk: Use X11 for easier OSK and xdotool.
- Icon fetching: Server-side scrape for og:image/favicon, cache locally.
- Resolution safety: Apply change → confirm overlay → xrandr/tvservice revert on timeout.
- CEC: Map Home to launcher, Back to browser back (Alt+Left).
- VPN exceptions: Implement chosen option with scripts.
- Security: Firewall, local-only or hashed password.

Deliverables
Produce the complete project step by step:
1) High-level design + MVP roadmap (components, data model, UX flows, testing checklist).
2) Implementation plan with concrete commands/configs (systemd units, kiosk startup, LibreWolf wrapper, CEC mapping, OSK setup).
3) Node/React + Express + SQLite repo scaffold (APIs, web UI skeleton, launcher UI) with local dev setup.
4) Full working proof-of-concept: scripts/configs to boot to kiosk, auto-start LibreWolf with Vimium, CEC, + phone web UI (create repo files).
5) Deep dive on VPN per-domain behavior (tradeoffs + step-by-step for 3 options with example scripts).

Start with deliverable 1 and proceed through the phases. Use X11. Target Mullvad and Proton for VPN examples. Use password-protected phone UI. Prioritize stability, TV-remote feel, and clean code. Produce files, scripts, and clear instructions I can follow on the Pi. Show More