YouTube-AI-Navigator-Browser-Extension

📖 Table of Contents

• 🌟 Features
• 🛠️ Architecture
• 🤖 AI Agent Directives
• ⚙️ Installation & Usage
  • Development Setup
  • Building for Production
  • Loading the Extension
• 🧑‍💻 Development Standards
  • Principles
  • Scripts
• 🤝 Contributing
• 📄 License
• 🛡️ Security
• 🙏 Acknowledgments

🤖 AI AGENT DIRECTIVES: YouTube-AI-Navigator-Browser-Extension

This section provides critical directives for AI agents, ensuring consistent development, high-quality output, and adherence to the project's architectural vision.

1. PROJECT OVERVIEW

• Project Name: YouTube-AI-Navigator-Browser-Extension
• Primary Function: Apex-grade, privacy-first browser extension for real-time, AI-powered YouTube analysis.
• Core Technologies: WXT (Vite-powered web extension framework), TypeScript (Strict), Google Gemini API, Biome, Vitest, Playwright.

2. ARCHITECTURAL PRINCIPLES & PATTERNS

• Architectural Pattern: Feature-Sliced Design (FSD).
  • Layers: app, shared, entities, features, widgets, pages, processes.
  • Strict Dependency Rule: Dependencies flow downwards (e.g., features can depend on entities and shared, but shared cannot depend on features).
  • Purpose: Ensures strict separation of concerns, scalability, and maintainability crucial for complex browser extensions.
• Design Principles:
  • SOLID: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.
  • DRY (Don't Repeat Yourself): Abstract common logic, especially for API interactions and UI components.
  • YAGNI (You Ain't Gonna Need It): Implement only features that are explicitly required. Avoid over-engineering.
  • Privacy-First: All data handling and API interactions must prioritize user privacy. No telemetry without explicit consent. Local storage preference over remote where possible.
  • Performance: Optimize content script and background script execution for minimal browser impact. Debouncing, throttling, and efficient DOM manipulation are critical.

3. CORE TECHNOLOGY STACK

• Framework: WXT (Vite-powered Web Extension Framework).
  • Configuration: wxt.config.ts.
  • Entrypoints: src/entrypoints/ for background, content scripts, popups, and options pages.
• Language: TypeScript (Strict Mode).
  • Linting & Formatting: Biome. Enforce strict rules defined in biome.json.
  • Type Safety: All public interfaces and API interactions must have explicit types.
• AI Integration: Google Gemini API (gemini-pro).
  • Client: Utilize official Google Gemini SDKs or well-maintained community wrappers.
  • Error Handling: Implement robust retry mechanisms, rate-limit handling, and clear error messaging for all AI interactions.
  • Prompt Engineering: Store prompts versioned and externalized where possible, allowing for iterative refinement.
• State Management: Utilize native browser extension messaging (chrome.runtime.sendMessage) for communication between entrypoints. For complex local state, consider simple React Context or Pinia/Zustand if a UI framework is introduced for specific components.
• Styling (Optional but Recommended): TailwindCSS v4. Use for rapid UI development and maintainability.

4. DEVELOPMENT WORKFLOW & VERIFICATION

• Setup Commands: bash git clone https://github.com/chirag127/YouTube-AI-Navigator-Browser-Extension.git cd YouTube-AI-Navigator-Browser-Extension npm install # Use npm for WXT/TS projects
• Build & Run Commands:
  • Development: npm run dev (starts WXT dev server with HMR).
  • Production Build: npm run build (creates production-ready extension package).
  • Extension Loading: Load the dist folder as an unpacked extension in your browser.
• Linting & Formatting Commands:
  • Check: npm run lint (runs Biome check).
  • Fix: npm run format (runs Biome fix).
  • Pre-commit Hook: Ensure Biome checks are integrated via Git hooks (e.g., Husky) to maintain code quality.
• Testing Commands:
  • Unit/Integration Tests: npm run test (executes Vitest tests).
  • End-to-End Tests: npm run test:e2e (executes Playwright tests for extension interaction).
• Verification Protocols:
  • All new features MUST include corresponding unit and integration tests.
  • Critical user flows MUST be covered by E2E tests.
  • Code MUST pass all Biome linting and formatting checks before merge.
  • AI prompt changes MUST be tested against a diverse set of YouTube videos to ensure consistent, unbiased, and accurate output.
  • Privacy implications of any new data handling MUST be thoroughly reviewed.

⚙️ Installation & Usage

Development Setup

To get started with local development, follow these steps:

1. Clone the Repository: bash git clone https://github.com/chirag127/YouTube-AI-Navigator-Browser-Extension.git cd YouTube-AI-Navigator-Browser-Extension

2. Install Dependencies: This project uses npm for package management. bash npm install

3. Start Development Server: WXT provides a development server with Hot Module Replacement (HMR) for rapid iteration. bash npm run dev

Building for Production

To create a production-ready build of the extension:

bash npm run build

This command will generate the compiled extension files in the dist directory.

Loading the Extension

Once built, you can load the extension into your browser:

1. Open your browser's extension management page (e.g., chrome://extensions for Chrome, about:debugging#/runtime/this-firefox for Firefox).
2. Enable "Developer mode" (usually a toggle in the top right).
3. Click "Load unpacked" or "Load Temporary Add-on".
4. Navigate to the dist folder within your cloned repository and select it.

🧑‍💻 Development Standards

Principles

• SOLID: Adhere to the Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles.
• DRY (Don't Repeat Yourself): Avoid redundant code. Abstract common functionalities and components.
• YAGNI (You Ain't Gonna Need It): Implement only what is necessary, avoiding premature optimization or feature creep.
• Code Clarity: Write clean, readable, and well-commented code.
• Type Safety: Leverage TypeScript's strict mode to prevent common errors and enhance code maintainability.

Scripts

Here are the essential development scripts: