Initial project setup

Add project structure with package.json, source code, tests, documentation, and GitHub workflows.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/prd.md

@@ -0,0 +1,401 @@
+# YouTube Subtitle Extraction & AI Summarization Bookmarklet Product Requirements Document (PRD)
+
+## Goals and Background Context
+
+### Goals
+Based on your Project Brief, here are the key desired outcomes the PRD will deliver:
+
+• Enable rapid pre-evaluation of YouTube educational content in 2-3 minutes instead of 10-20 minutes of uncertain viewing
+• Reduce time spent on irrelevant videos by 60% through AI-powered structured summaries  
+• Achieve 85% technical success rate for subtitle extraction and processing
+• Deliver consistent mobile-first experience for Android Chrome users with Claude.ai subscriptions
+• Establish foundation for 100+ active users within 3 months through organic distribution
+
+### Background Context
+
+The YouTube Subtitle Extraction & AI Summarization Bookmarklet addresses a critical efficiency problem for mobile educational content consumers. Android Chrome users currently waste 60-80% of their video exploration time discovering that educational YouTube content doesn't match their needs or comprehension level, only after investing 10-20 minutes of viewing time.
+
+This solution leverages existing infrastructure (Claude.ai subscriptions + downloadyoutubesubtitles.com API) to create a seamless one-click workflow that extracts auto-generated subtitles and processes them into structured summaries (Overview, Essential Points, Value Proposition, Beginner Summary). The bookmarklet approach eliminates adoption friction while providing immediate value to users who already have the necessary AI processing capabilities through their Claude.ai subscriptions.
+
+### Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-09-05 | v1.0 | Initial PRD creation from comprehensive Project Brief | John (PM) |
+
+## Requirements
+
+### Functional Requirements
+
+**FR1:** The bookmarklet must automatically extract YouTube video ID from the current page URL when activated
+
+**FR2:** The system must integrate with downloadyoutubesubtitles.com API to retrieve auto-generated English subtitles for the detected video
+
+**FR3:** The bookmarklet must handle CAPTCHA intervention gracefully, providing clear user guidance when manual verification is required
+
+**FR4:** The system must automatically open Claude.ai in a new tab with a prepared chat session for subtitle processing
+
+**FR5:** The bookmarklet must copy formatted subtitle text to clipboard as fallback when RPA automation is unavailable
+
+**FR6:** The system must provide structured error messages for videos without auto-generated subtitles or API unavailability
+
+**FR7:** The bookmarklet must format subtitle text specifically for Claude.ai processing to generate Overview, Essential Points, Value Proposition, and Beginner Summary sections
+
+**FR8:** The system must complete the entire subtitle extraction process within 60 seconds under normal conditions
+
+### Non-Functional Requirements
+
+**NFR1:** The bookmarklet must achieve 85% technical success rate for subtitle extraction without errors
+
+**NFR2:** The system must work exclusively on Android Chrome browser (version 90+) without requiring installations or permissions
+
+**NFR3:** The bookmarklet code must be vanilla JavaScript (ES6+) with no external dependencies for maximum compatibility
+
+**NFR4:** The system must operate statelessly with no data storage or user tracking for privacy by design
+
+**NFR5:** The solution must function with zero budget requirements, using only free external APIs and services
+
+**NFR6:** The bookmarklet must handle cross-origin resource sharing constraints while maintaining functionality
+
+**NFR7:** The system must process subtitle text efficiently to avoid Claude.ai context limitations for videos up to standard length
+
+**NFR8:** The user interface must provide clear feedback for all operations with mobile-optimized error messaging
+
+## User Interface Design Goals
+
+### Overall UX Vision
+A frictionless, one-click experience that feels like a natural extension of YouTube browsing. The interface should be invisible during success - users click the bookmarklet and receive results without intermediate screens or complex interactions. When intervention is needed (CAPTCHA, errors), provide clear, mobile-optimized guidance that maintains the lightweight feel.
+
+### Key Interaction Paradigms
+- **Single-Click Activation:** Primary interaction is bookmarklet click while viewing YouTube video
+- **Progressive Disclosure:** Show minimal UI during processing, expand only when user input required  
+- **Graceful Degradation:** Automatic fallback to clipboard copy when RPA automation unavailable
+- **Context Preservation:** Maintain YouTube viewing context while processing occurs in background/new tabs
+
+### Core Screens and Views
+- **YouTube Integration Layer:** Overlay or toast notifications on YouTube pages for status/errors
+- **Processing Feedback Screen:** Mobile-optimized loading states and progress indicators
+- **CAPTCHA Intervention Screen:** Clear instructions for manual verification when required
+- **Error Recovery Screen:** User-friendly error messages with actionable next steps
+- **Claude.ai Handoff Screen:** Seamless transition to Claude.ai with pre-populated content
+
+### Accessibility: WCAG AA
+Ensure mobile screen reader compatibility, sufficient color contrast for outdoor mobile viewing, and keyboard navigation support for users with motor difficulties on mobile devices.
+
+### Branding
+Minimal, clean aesthetic that complements both YouTube's interface and Claude.ai's design language. Use system fonts and native mobile UI patterns to feel integrated rather than intrusive. No custom branding needed - focus on functional clarity over visual identity.
+
+### Target Device and Platforms: Mobile Only
+Specifically optimized for Android Chrome mobile browsing experience, including touch-first interactions, portrait orientation optimization, and mobile network considerations for API calls.
+
+## Technical Assumptions
+
+### Repository Structure: Monorepo
+Single GitHub repository containing the bookmarklet source, development tools, documentation, and distribution files. This approach minimizes complexity for a single-file JavaScript solution while providing proper version control and issue tracking.
+
+### Service Architecture
+**Client-Side Only with External API Dependencies:** Pure bookmarklet architecture running entirely in browser JavaScript with no custom backend. Integrates with two external services: downloadyoutubesubtitles.com API for subtitle extraction and Claude.ai web interface for AI processing. This serverless approach eliminates hosting costs and maintenance overhead.
+
+### Testing Requirements
+**Unit + Integration Testing:** JavaScript unit tests for core functions (URL parsing, API formatting, error handling) plus integration tests with real YouTube URLs and API endpoints. Manual testing protocols for cross-device compatibility and CAPTCHA scenarios. No automated E2E testing due to external API dependencies and CAPTCHA requirements.
+
+### Additional Technical Assumptions and Requests
+
+**Language and Framework Choices:**
+- **Vanilla JavaScript ES6+** for maximum mobile browser compatibility without build dependencies
+- **No frameworks or libraries** to maintain bookmarklet simplicity and avoid CSP restrictions
+- **GitHub Pages** for documentation hosting and bookmarklet distribution
+
+**API Integration Strategy:**
+- **downloadyoutubesubtitles.com REST API** as primary subtitle source with JSON response handling
+- **CORS handling** through API proxy or direct requests based on service configuration
+- **Rate limiting consideration** to avoid API blocking (implement client-side throttling if needed)
+
+**Browser Compatibility Requirements:**
+- **Android Chrome 90+** as primary target with ES6+ feature detection
+- **Clipboard API support** for fallback functionality with permission handling
+- **Cross-origin policy compliance** within bookmarklet security constraints
+
+**Development and Deployment Pipeline:**
+- **Source code version** for development with comments and debugging
+- **Minified production version** for actual bookmarklet distribution
+- **Automated minification** through GitHub Actions for consistent builds
+- **Version tagging** aligned with semantic versioning for user updates
+
+## Epic List
+
+**Epic 1: Foundation & Core Extraction**
+Establish project infrastructure, YouTube video ID detection, and basic subtitle extraction via external API with comprehensive error handling for missing subtitles and API failures.
+
+**Epic 2: Claude.ai Integration & Processing**
+Implement automated Claude.ai tab opening, clipboard functionality for subtitle transfer, and structured prompt formatting to generate the four required summary sections (Overview, Essential Points, Value Proposition, Beginner Summary).
+
+**Epic 3: Mobile UX Enhancement & Reliability**
+Add mobile-optimized loading states, progress feedback, CAPTCHA handling guidance, and comprehensive error recovery to create a production-ready user experience for Android Chrome.
+
+**Epic 4: RPA Automation & Advanced Features**
+Implement automated form filling and submission in Claude.ai interface, eliminating manual paste requirements and delivering the complete seamless workflow envisioned in Phase 2.
+
+## Epic 1: Foundation & Core Extraction
+
+**Epic Goal:** Establish the foundational project infrastructure and core YouTube subtitle extraction capability, proving the technical feasibility of the bookmarklet approach while delivering a basic working version that can extract and display subtitle text for any YouTube video with auto-generated captions.
+
+### Story 1.1: Project Setup and Bookmarklet Infrastructure
+
+As a developer,
+I want to establish the project repository structure and basic bookmarklet framework,
+so that I have a solid foundation for implementing the YouTube subtitle extraction features.
+
+#### Acceptance Criteria
+1. GitHub repository is created with proper folder structure (src/, docs/, dist/)
+2. Basic bookmarklet template loads and executes without errors on YouTube pages
+3. Development version includes comprehensive logging and debugging capabilities
+4. Production minification process is established and documented
+5. README contains installation and development setup instructions
+6. Version control workflow is established with semantic versioning
+
+### Story 1.2: YouTube Video ID Detection and Extraction
+
+As a mobile user browsing YouTube educational content,
+I want the bookmarklet to automatically detect which video I'm currently viewing,
+so that it can extract the correct video's subtitle information without manual input.
+
+#### Acceptance Criteria
+1. Bookmarklet correctly extracts video ID from standard YouTube URLs (youtube.com/watch?v=...)
+2. System handles mobile YouTube URL formats (m.youtube.com variations)
+3. Video ID extraction works for embedded players and playlist contexts
+4. Clear error message displayed when video ID cannot be determined
+5. Extracted video ID is validated for proper YouTube format (11-character alphanumeric)
+6. Function handles edge cases like shortened URLs and redirect scenarios
+
+### Story 1.3: External Subtitle API Integration
+
+As a user wanting to preview YouTube video content,
+I want the system to automatically retrieve the video's auto-generated subtitles,
+so that I have the raw text content needed for AI summarization.
+
+#### Acceptance Criteria
+1. Integration with downloadyoutubesubtitles.com API successfully retrieves subtitle data
+2. System specifically requests English auto-generated subtitles when available
+3. API response is properly parsed and formatted for downstream processing
+4. Comprehensive error handling for API unavailability or rate limiting
+5. Timeout handling prevents indefinite waiting for API responses
+6. Subtitle text is cleaned and formatted for optimal Claude.ai processing
+
+### Story 1.4: Error Handling and User Feedback System
+
+As a mobile user encountering various video scenarios,
+I want clear, actionable feedback when the subtitle extraction cannot proceed,
+so that I understand what went wrong and what options I have.
+
+#### Acceptance Criteria
+1. Specific error messages for videos without auto-generated subtitles
+2. Clear feedback when external API is temporarily unavailable
+3. User-friendly guidance for CAPTCHA intervention requirements
+4. Mobile-optimized error display that doesn't disrupt YouTube viewing
+5. Error messages include suggested next steps or alternative actions
+6. All error scenarios are logged for debugging and improvement
+7. Graceful fallback behavior maintains YouTube page functionality
+
+## Epic 2: Claude.ai Integration & Processing
+
+**Epic Goal:** Complete the core user workflow by implementing Claude.ai integration and structured prompt formatting, enabling users to seamlessly transfer extracted YouTube subtitles to their Claude.ai subscription for AI-powered summarization in the four required sections (Overview, Essential Points, Value Proposition, Beginner Summary).
+
+### Story 2.1: Claude.ai Tab Management and Session Initialization
+
+As a user with a Claude.ai subscription wanting to process YouTube subtitles,
+I want the bookmarklet to automatically open Claude.ai in a new tab with a fresh chat session,
+so that I can immediately begin the subtitle analysis without manual navigation.
+
+#### Acceptance Criteria
+1. New Claude.ai tab opens automatically when subtitle extraction completes successfully
+2. Tab opens to a fresh chat session (not an existing conversation)
+3. Claude.ai tab focus behavior is optimized for mobile browsing (doesn't disrupt current YouTube tab)
+4. System handles Claude.ai authentication states gracefully (logged in vs logged out)
+5. Tab opening works consistently across different mobile Chrome versions
+6. Proper error handling if Claude.ai is inaccessible or blocked
+
+### Story 2.2: Structured Prompt Formatting for AI Summarization
+
+As a user needing consistent, actionable video summaries,
+I want the subtitle text formatted with specific instructions for Claude.ai,
+so that I receive structured analysis in exactly the four sections I need for decision-making.
+
+#### Acceptance Criteria
+1. Prompt template generates clear instructions for Overview, Essential Points, Value Proposition, and Beginner Summary sections
+2. Subtitle text is properly formatted and escaped for Claude.ai input requirements
+3. Prompt includes context about the YouTube video source and intended use case
+4. Character limits and token considerations are handled for very long subtitle content
+5. Prompt template can be easily modified for future customization needs
+6. Generated prompt is optimized for mobile Claude.ai interface display
+
+### Story 2.3: Clipboard Integration and Fallback Functionality
+
+As a mobile user who may encounter automation limitations,
+I want the formatted prompt and subtitle text automatically copied to my clipboard,
+so that I can manually paste into Claude.ai if needed while maintaining the structured format.
+
+#### Acceptance Criteria
+1. Complete formatted prompt is automatically copied to clipboard when processing completes
+2. Clipboard copy happens seamlessly without requiring user permission prompts
+3. Copied content is properly formatted for direct paste into Claude.ai text area
+4. Visual confirmation shows user that content has been copied successfully
+5. Clipboard functionality works reliably across Android Chrome versions
+6. Fallback gracefully handles scenarios where clipboard access is denied
+7. Content remains available in clipboard for reasonable duration
+
+### Story 2.4: End-to-End Workflow Integration
+
+As a mobile YouTube user wanting efficient content evaluation,
+I want the complete bookmarklet workflow to execute smoothly from activation to Claude.ai readiness,
+so that I can evaluate any educational video within the promised 2-3 minute timeframe.
+
+#### Acceptance Criteria
+1. Complete workflow (video detection → subtitle extraction → Claude.ai opening → clipboard copy) executes within 60 seconds under normal conditions
+2. Progress indicators show user the current processing stage throughout the workflow
+3. Each workflow step includes appropriate error recovery and user guidance
+4. Success confirmation clearly indicates when the user can proceed with Claude.ai analysis
+5. Mobile-optimized user experience maintains smooth performance throughout
+6. Workflow state is properly managed to prevent duplicate executions
+7. Complete integration test validates end-to-end functionality with real YouTube videos
+
+## Epic 3: Mobile UX Enhancement & Reliability
+
+**Epic Goal:** Transform the functional MVP into a production-ready mobile experience by implementing comprehensive user feedback, mobile-optimized interfaces, and robust error recovery mechanisms that ensure reliable operation for real-world Android Chrome users consuming educational YouTube content.
+
+### Story 3.1: Mobile-Optimized Loading States and Progress Feedback
+
+As a mobile user activating the bookmarklet on YouTube,
+I want clear visual feedback about the processing progress and current status,
+so that I understand what's happening and can wait appropriately during the subtitle extraction and Claude.ai preparation.
+
+#### Acceptance Criteria
+1. Loading overlay displays immediately upon bookmarklet activation with mobile-friendly design
+2. Progress indicators show distinct stages: Video Detection → Subtitle Extraction → Claude.ai Preparation → Complete
+3. Visual feedback adapts to different mobile screen sizes and orientations
+4. Loading states include estimated time remaining based on typical processing duration
+5. Progress display doesn't interfere with underlying YouTube video playback or navigation
+6. Loading animation and text are optimized for mobile data connections and performance
+7. Clear visual confirmation when processing completes successfully
+
+### Story 3.2: CAPTCHA Handling and User Guidance System
+
+As a user encountering CAPTCHA requirements from the subtitle API,
+I want clear, actionable instructions for completing the verification,
+so that I can resolve the issue quickly and continue with my video analysis workflow.
+
+#### Acceptance Criteria
+1. CAPTCHA detection triggers specific mobile-optimized guidance modal
+2. Instructions include step-by-step process for completing CAPTCHA verification
+3. System provides direct link to the CAPTCHA page with proper mobile formatting
+4. Retry mechanism allows user to continue processing after CAPTCHA completion
+5. CAPTCHA guidance includes expected timeframe and troubleshooting tips
+6. Mobile interface ensures CAPTCHA resolution doesn't lose YouTube context
+7. Fallback instructions provided if CAPTCHA cannot be resolved immediately
+
+### Story 3.3: Comprehensive Error Recovery and User Support
+
+As a mobile user experiencing various failure scenarios,
+I want helpful error messages and recovery options,
+so that I can either resolve issues myself or understand my alternatives when the bookmarklet cannot complete successfully.
+
+#### Acceptance Criteria
+1. Specific error messages for each failure type: no subtitles, API unavailable, network issues, video access restrictions
+2. Each error message includes suggested next steps or alternative approaches
+3. Error recovery options appropriate for mobile context (retry, manual alternatives, contact information)
+4. Error state preservation allows users to understand what was attempted and what failed
+5. Mobile-optimized error display that maintains readability and doesn't break YouTube functionality
+6. Option to copy error details for troubleshooting or support purposes
+7. Graceful degradation ensures YouTube page remains functional after any error
+
+### Story 3.4: Performance Optimization and Mobile Responsiveness
+
+As a mobile user with varying network conditions and device capabilities,
+I want the bookmarklet to perform efficiently across different Android Chrome configurations,
+so that I can use the tool reliably regardless of my mobile connection quality or device performance.
+
+#### Acceptance Criteria
+1. Bookmarklet code is optimized for mobile JavaScript execution with minimal memory footprint
+2. Network requests include appropriate timeouts and retry logic for mobile connections
+3. UI elements scale properly across different mobile screen densities and sizes
+4. Processing adapts to network quality with progressive timeout strategies
+5. Mobile battery impact is minimized through efficient code execution
+6. Touch interactions are optimized for mobile gesture patterns
+7. Performance monitoring and optimization ensure consistent operation across Android Chrome versions
+8. Subtitle processing handles large text efficiently without mobile browser crashes
+
+## Epic 4: RPA Automation & Advanced Features
+
+**Epic Goal:** Eliminate manual intervention by implementing RPA automation for Claude.ai interaction, transforming the workflow from "extract and copy" to true one-click automation that delivers complete YouTube video summaries without requiring users to manually paste content or interact with Claude.ai directly.
+
+### Story 4.1: Claude.ai DOM Analysis and Interface Detection
+
+As a developer implementing RPA automation,
+I want to programmatically understand Claude.ai's web interface structure,
+so that I can reliably identify and interact with the chat input elements across different page states and potential interface updates.
+
+#### Acceptance Criteria
+1. JavaScript functions detect Claude.ai page load states and readiness for input
+2. DOM selectors reliably identify chat input textarea across different Claude.ai interface versions
+3. System detects and handles different Claude.ai authentication and session states
+4. Interface change detection provides warnings when DOM structure appears to have changed
+5. Fallback identification methods work when primary selectors fail
+6. Mobile-specific Claude.ai interface elements are properly identified and targeted
+7. Analysis includes handling for dynamic loading and single-page application behavior
+
+### Story 4.2: Automated Form Filling and Content Injection
+
+As a user wanting seamless automation,
+I want the bookmarklet to automatically populate the Claude.ai chat input with my formatted subtitle content,
+so that I don't need to manually paste or type anything in the Claude.ai interface.
+
+#### Acceptance Criteria
+1. Formatted prompt and subtitle content is programmatically inserted into Claude.ai chat input
+2. Text insertion handles large content blocks without truncation or formatting loss
+3. System respects Claude.ai input limits and provides appropriate chunking if needed
+4. Content injection works reliably across mobile Chrome and different Claude.ai interface states
+5. Automated input includes proper text formatting and maintains structured prompt template
+6. Input validation ensures content was properly inserted before proceeding to submission
+7. Graceful fallback to clipboard copy when automated filling fails
+
+### Story 4.3: Automated Submission and Response Handling
+
+As a user expecting complete automation,
+I want the system to automatically submit my request to Claude.ai and monitor for the response,
+so that I receive my structured video summary without any manual interaction after bookmarklet activation.
+
+#### Acceptance Criteria
+1. Submit button is automatically triggered after content insertion with appropriate timing
+2. System monitors Claude.ai response generation and completion status
+3. Response text is captured and formatted for optimal mobile viewing
+4. Automation handles Claude.ai processing time variations and potential delays
+5. Error detection identifies when Claude.ai request fails or times out
+6. Response capture includes all four required summary sections (Overview, Essential Points, Value Proposition, Beginner Summary)
+7. Final results are presented in mobile-optimized format separate from Claude.ai interface
+
+### Story 4.4: End-to-End Automation Integration and Fallback Management
+
+As a mobile user expecting reliable one-click operation,
+I want the complete RPA workflow to operate seamlessly while providing clear fallbacks when automation encounters issues,
+so that I always receive my video analysis regardless of technical limitations.
+
+#### Acceptance Criteria
+1. Complete automation workflow executes within 3 minutes from bookmarklet activation to final summary display
+2. Fallback cascade gracefully degrades from full automation → semi-automation → manual clipboard approach
+3. User feedback clearly indicates current automation level and any required manual steps
+4. Automation success rate meets or exceeds 70% target with appropriate error recovery
+5. Manual fallback maintains all formatting and functionality when automation fails
+6. End-to-end testing validates complete workflow across different mobile scenarios
+7. Performance monitoring tracks automation success rates and failure patterns for optimization
+8. Final implementation delivers true one-click experience for successful automation scenarios
+
+## Checklist Results Report
+
+*[This section will be populated after executing the pm-checklist validation]*
+
+## Next Steps
+
+### UX Expert Prompt
+*[This section will contain the prompt for the UX Expert to initiate architecture mode using this PRD as input]*
+
+### Architect Prompt  
+*[This section will contain the prompt for the Architect to initiate create architecture mode using this PRD as input]*