Plotnchill

“Find your plot. Settle in.”

PlotnChill is a modern, responsive, frontend-only movie and TV show discovery and streaming interface built with React 19, TypeScript, and Vite. Browse TMDB’s vast catalog, manage your personal library locally, and watch available content through embedded Vidking playback.

Key Highlights & Architecture

1. Clean Client-Side Architecture

   • Built with React 19, TypeScript, and Vite.
   • Standard HTML5 Browser Routing (BrowserRouter) for clean URLs (/movie/:id, /watch/tv/:id/:season/:episode, etc.) with zero hash fragments (/#/).
   • Pure client-side state and persistence using versioned localStorage for Watchlist, Favorites, Watched markers, Playback History, and Custom Lists.
   • JSON Backup Import and Export with schema verification to migrate libraries across devices.

2. Refined Visual Identity & UX

   • High-contrast cinema dark theme (#0c0c0f, #14141c) with warm ivory typography (#f5f2eb), amber accents (#f59e0b), and subtle borders.
   • Elegant TV show season dropdown selector replacing awkward horizontal scrollbars.
   • Horizontal trailer carousel with 16:9 thumbnail cards and smooth hover interactions.
   • Styled player controls with subtle telemetry indicators and origin-verified player events.
   • Responsive across mobile, tablet, and widescreen desktop displays with touch-friendly controls and bottom navigation on mobile.

3. TMDB Integration & Build Configuration

   • Authoritative catalog, search, genres, credits, episode guides, and artwork fetched live from The Movie Database (TMDB).
   • Zero runtime credential surface: no API key prompts, banners, or token inputs shown to end users.
   • Production builds load the TMDB Read Access Token securely at build time via VITE_TMDB_TOKEN.
   • Real-time search supporting keywords as well as direct IMDb ID lookups (e.g., tt1375666).

4. Embedded Playback Engine

   • Seamless streaming powered by the Vidking player embed (vidking.net).
   • Automatic next-episode calculation and transition logic (respecting regular seasons vs. specials).
   • Secure origin-verified postMessage listener tracking real watch progress and playback state.
   • Configurable player preferences (accent colors, autoplay toggle, progress telemetry).

Application Routes

| Route | Page | Description | | :--- | :--- | :--- | | / | Home | Spotlight hero showcase, "Pick for Me" random decider, Recently Opened titles, Trending, Popular, Top Rated, and Airing collections. | | /movies | Browse Movies | Filterable movie catalog by genre, release year, language, minimum rating, and sort order. | | /tv | Browse TV Shows | Filterable TV series catalog by genre, air date, language, rating, and sort order. | | /search?q=... | Search | Instant debounced search for movies and TV shows, with recent search history and direct IMDb ID resolution. | | /movie/:id | Movie Details | Backdrop and poster artwork, synopsis, runtime, genres, top-billed cast, YouTube trailers & previews, and recommendations. | | /tv/:id | TV Details & Seasons | Series metadata, season dropdown selector, episode guide with air dates, runtimes, overviews, and specials segregation. | | /watch/movie/:id | Watch Movie | Responsive 16:9 player embed, reload controls, external stream links, and watch-progress tracking. | | /watch/tv/:id/:s/:e | Watch TV Episode | Player embed with external season and episode selectors, next/previous episode navigation, and "Up Next" preview banner. | | /library | My Library | Personal Watchlist, Favorites, Watched Movies & Episodes, History, and Custom Lists with JSON export/import. | | /settings | Settings | Player parameter customization (color theme, autoplay), language preference, motion accessibility, and local data reset. | | /about | About | Legal disclaimers, TMDB attribution notices, Vidking service information, and creator credits. |

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• npm (v9 or higher)

Installation

# Clone the repository
git clone https://github.com/your-username/plotnchill.git
cd "Agnific - PlotnChill"

# Install dependencies
npm install

Environment Configuration

Create a .env file in the project root (or copy .env.example):

cp .env.example .env

Add your TMDB API Read Access Token (v4 Bearer token) or API Key (v3):

VITE_TMDB_TOKEN=your_tmdb_bearer_token_here

Note: To obtain a TMDB token, register for a free account at themoviedb.org and create an API token under Account Settings → API.

Development Server

npm run dev

Open your browser to http://localhost:5173/.

Production Build & Preview

# Type check and build static production bundle
npm run build

# Preview production build locally
npm run preview

The compiled output is located in the dist/ directory, ready to deploy to any static host (e.g. Vercel, Netlify, Cloudflare Pages, GitHub Pages, or S3).

Automated Testing

npm run test

Runs Vitest unit tests covering:

• Embed URL Construction: Validates movie & TV streaming URL patterns and sanitized parameters.
• Episode Transitions: Validates episode advancement, season transitions, series finales, and specials isolation.
• Library Sanitization & Versioning: Tests JSON schema migration and local storage security.
• Player Telemetry: Validates postMessage origin security (https://www.vidking.net) and telemetry payload parsing.

Attributions & Credits

• The Movie Database (TMDB): This product uses the TMDB API but is not endorsed or certified by TMDB.
• Vidking: Video playback streaming powered by Vidking.
• Icons: UI iconography provided by Lucide React.
• Created by: Developed by Agnific.