feat: youtube preview

specs/002-youtube-design-preview/plan.md

@@ -0,0 +1,92 @@
+# Implementation Plan: YouTube Design Preview Replica
+
+**Branch**: `002-youtube-design-preview` | **Date**: 2026-01-29 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/002-youtube-design-preview/spec.md`
+
+## Summary
+
+Enhance the existing thumbnail preview tool to achieve pixel-perfect visual accuracy with YouTube's current design across three view modes (Desktop, Mobile, Sidebar). The implementation focuses on extracting exact CSS values from YouTube, implementing local storage persistence, adding a manual theme toggle, and integrating Playwright MCP for automated visual regression testing with weekly reference screenshot updates.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.9.x (frontend + backend)
+**Primary Dependencies**: React 19.x, Tailwind CSS 4.x, shadcn/ui, Zustand, Playwright MCP
+**Storage**: Browser localStorage (preview persistence), file system (reference screenshots)
+**Testing**: Playwright visual comparison, Jest (unit tests)
+**Target Platform**: Web browsers (Chrome, Firefox, Safari), responsive mobile views
+**Project Type**: Monorepo (frontend + backend)
+**Performance Goals**: Preview render < 2 seconds, 98% visual match with YouTube
+**Constraints**: 5MB max thumbnail upload, JPG/PNG/WebP formats only
+**Scale/Scope**: Single-user local tool, no concurrent users
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| I. Tech Stack | PASS | React 19.x, TypeScript 5.x, Tailwind CSS 4.x, shadcn/ui, Zustand - all aligned |
+| II. Architecture | PASS | Feature code goes in existing frontend structure |
+| III. Styling | PASS | YouTube CSS variables already defined in index.css; extend with Tailwind utilities |
+| IV. Data Management | PASS | Zustand for preview state, localStorage for persistence (no backend changes needed) |
+| V. Development Practices | PASS | TypeScript strict mode, ESLint, existing patterns followed |
+
+**Gate Result**: PASS - All constitution principles satisfied.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-youtube-design-preview/
+├── plan.md              # This file
+├── research.md          # Phase 0: YouTube design extraction research
+├── data-model.md        # Phase 1: Data entities and storage schema
+├── quickstart.md        # Phase 1: Development setup guide
+├── contracts/           # Phase 1: API contracts (minimal - mostly frontend)
+└── tasks.md             # Phase 2: Implementation tasks (created by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+frontend/
+├── src/
+│   ├── components/
+│   │   ├── YouTubeVideoCard.tsx      # MODIFY: Enhance for pixel-perfect accuracy
+│   │   ├── PreviewModeSelector.tsx   # NEW: Desktop/Mobile/Sidebar switcher
+│   │   ├── ThemeToggle.tsx           # NEW: Light/dark mode toggle
+│   │   ├── ThumbnailUploader.tsx     # MODIFY: Add file validation (5MB, formats)
+│   │   └── ui/                       # shadcn/ui components (no changes)
+│   ├── hooks/
+│   │   └── useLocalStorage.ts        # NEW: Persist preview state
+│   ├── store/
+│   │   └── previewStore.ts           # MODIFY: Add persistence, theme state
+│   ├── types/
+│   │   └── index.ts                  # MODIFY: Add new type definitions
+│   ├── lib/
+│   │   └── youtube-styles.ts         # NEW: Extracted YouTube CSS constants
+│   └── index.css                     # MODIFY: Add precise YouTube CSS variables
+├── tests/
+│   └── visual/
+│       ├── desktop.spec.ts           # NEW: Playwright visual tests
+│       ├── mobile.spec.ts            # NEW: Playwright visual tests
+│       ├── sidebar.spec.ts           # NEW: Playwright visual tests
+│       └── reference/                # NEW: YouTube reference screenshots
+└── playwright.config.ts              # NEW: Playwright configuration
+
+scripts/
+└── capture-youtube-reference.ts      # NEW: Weekly reference screenshot capture
+```
+
+**Structure Decision**: Extending existing frontend structure. No backend changes required as persistence uses browser localStorage per clarification.
+
+## Complexity Tracking
+
+> No constitution violations to justify.
+
+| Aspect | Decision | Rationale |
+|--------|----------|-----------|
+| Storage | localStorage only | Per clarification - no server persistence needed |
+| Theme | Manual toggle | Per clarification - no system preference detection |
+| Reference updates | Automated weekly | Per clarification - Playwright captures from live YouTube |