yt2ai/docs/DEVELOPER.md

YT2AI Developer Guide

Development Setup

Prerequisites

• Node.js 16+ - For build tools and testing
• npm 7+ - Package management
• Android device with Chrome 90+ - For testing
• Text editor with JavaScript support (VS Code recommended)

Initial Setup

# Clone repository
git clone https://github.com/yt2ai/yt2ai-bookmarklet.git
cd yt2ai-bookmarklet

# Install dependencies
npm install

# Verify setup
npm run verify

Development Workflow

1. Code Development

# Start file watching for continuous builds
npm run build:watch

# Run tests in watch mode
npm run test:watch

# Check code quality
npm run lint
npm run format:check

2. Testing Cycle

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Build development version
npm run build:dev

# Test manually on device using dist/bookmarklet-debug.js

3. Production Build

# Full verification pipeline
npm run verify

# Production build
npm run build

# Verify output in dist/bookmarklet.min.js

Project Architecture

Directory Structure

yt2ai-bookmarklet/
├── src/
│   ├── bookmarklet.js          # Main entry point (all code currently here)
│   ├── core/                   # Future: Core functionality modules
│   ├── ui/                     # Future: UI components
│   └── utils/                  # Future: Utility modules
├── build/
│   ├── webpack.config.js       # Build configuration
│   └── README.md              # Build system docs
├── tests/
│   ├── unit/core/             # Unit tests
│   ├── integration/           # Integration tests
│   ├── manual/                # Manual test protocols
│   └── setup.js               # Jest configuration
├── docs/                      # Documentation
├── dist/                      # Build outputs
└── .github/workflows/         # CI/CD configuration

Current Implementation

All functionality is currently implemented in src/bookmarklet.js as a single file. This monolithic approach is intentional for the bookmarklet format, but the architecture supports future modularization.

Code Architecture

Main Components

Environment Detection

const environment = {
    isDevelopment: boolean,    // Debug mode detection
    isMobile: boolean,         // Mobile device detection
    isAndroid: boolean,        // Android specific detection
    isChrome: boolean          // Chrome browser detection
};

YouTube Context Validation

function validateYouTubeContext() {
    // Validates hostname and extracts video ID
    // Supports: youtube.com/watch, youtu.be, shorts, embed
    // Returns: { videoId, url }
}

Mobile Overlay System

class MobileOverlay {
    // Mobile-optimized modal dialogs
    // Features: 44px touch targets, responsive design
    // Types: loading, error, success, info
}

Error Handling Framework

class BookmarkletError extends Error {
    // Enhanced error with context and recovery info
    // Types: network, api, parsing, captcha, validation
    // Severity: low, medium, high, critical
}

State Management

const stateManager = {
    // Module pattern for state management
    // Tracks: initialization, processing, video context
    // No persistence - stateless operation
}

Coding Standards

JavaScript Guidelines

Universal Rules

1. Always use const by default, let when reassignment needed

   const videoId = extractVideoId(url);  // ✅ Preferred
   let retryCount = 0;                   // ✅ When reassignment needed
   var oldStyle = 'avoid';               // ❌ Avoid var
   

2. Prefix all CSS classes with yt2ai-

   element.className = 'yt2ai-overlay yt2ai-loading';  // ✅ Correct
   element.className = 'overlay loading';               // ❌ Conflicts possible
   

3. Use z-index: 999999 or higher for overlays

   const styles = `
     .yt2ai-overlay {
       z-index: 999999;  /* ✅ Above YouTube's interface */
     }
   `;
   

4. Handle all async operations with try/catch

   // ✅ Proper error handling
   try {
     const result = await apiCall();
     return result;
   } catch (error) {
     errorReporter.report(error, 'api-call');
     throw new BookmarkletError('API call failed', 'network', true);
   }
   

Mobile-Specific Rules

1. All touch targets must be minimum 44px

   const styles = `
     .yt2ai-close-btn {
       min-width: 44px;   /* ✅ WCAG AA compliance */
       min-height: 44px;
     }
   `;
   

2. Use touchend events, not click for mobile optimization

   const eventType = environment.isMobile ? 'touchend' : 'click';
   button.addEventListener(eventType, handler);
   

3. Always prevent body scroll when showing modals

   show() {
     document.body.appendChild(this.element);
     document.body.style.overflow = 'hidden';  // ✅ Prevent scroll
   }
   

Bookmarklet-Specific Rules

1. Never rely on external dependencies in production

   // ✅ Self-contained
   const helper = (function() {
     // All code inline
   })();
   
   // ❌ External dependency
   import { helper } from 'external-lib';
   

2. Always namespace global variables with __YT2AI_

   window.__YT2AI_INITIALIZED__ = true;     // ✅ Namespaced
   window.__YT2AI_VERSION__ = '1.0.0';      // ✅ Namespaced
   window.initialized = true;                // ❌ Generic name
   

3. Always validate YouTube context before execution

   function initialize() {
     if (!window.location.hostname.includes('youtube.com')) {
       throw new BookmarkletError('YouTube page required');
     }
   }
   

Testing Guidelines

Unit Testing

Test Structure (Arrange-Act-Assert)

test('should extract video ID from YouTube URL', () => {
  // Arrange
  const testUrl = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
  
  // Act
  const videoId = extractVideoId(testUrl);
  
  // Assert
  expect(videoId).toBe('dQw4w9WgXcQ');
});

Mobile Environment Mocking

const mockMobileEnvironment = () => {
  Object.defineProperty(navigator, 'userAgent', {
    value: 'Mozilla/5.0 (Linux; Android 10; SM-G975F) Chrome/91.0'
  });
  Object.defineProperty(window, 'innerWidth', { value: 375 });
};

YouTube Context Mocking

const mockYouTubeUrl = (videoId = 'dQw4w9WgXcQ') => {
  Object.defineProperty(window, 'location', {
    value: {
      href: `https://www.youtube.com/watch?v=${videoId}`,
      hostname: 'youtube.com'
    }
  });
};

Integration Testing

• Test real YouTube URLs with various formats
• Verify API integration with external services
• Test mobile device compatibility

Manual Testing Protocol

1. Device Testing:

   • Test on actual Android devices
   • Various Chrome versions (90+)
   • Different screen sizes and orientations

2. Scenario Testing:

   • Different video types (regular, shorts, embedded)
   • Various network conditions (3G, 4G, WiFi)
   • Error scenarios (no subtitles, API down, CAPTCHA)

Mobile Development

Responsive Design Principles

// Mobile-first CSS approach
const mobileStyles = `
  .yt2ai-component {
    /* Mobile base styles */
    font-size: 14px;
    padding: 12px;
  }
  
  @media (min-width: 768px) {
    .yt2ai-component {
      /* Desktop enhancements */
      font-size: 16px;
      padding: 16px;
    }
  }
`;

Touch Optimization

// Touch-friendly event handling
const handleTouch = (e) => {
  e.preventDefault();  // Prevent scroll bounce
  e.stopPropagation(); // Prevent event bubbling
};

element.addEventListener('touchend', handleTouch, { passive: false });

Mobile Network Handling

// Adaptive timeouts for mobile networks
const timeout = environment.isMobile ? 30000 : 15000;
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);

Build System

Webpack Configuration

The build system transforms modular development code into single-file bookmarklet distribution:

// webpack.config.js highlights
module.exports = {
  entry: 'src/bookmarklet.js',
  output: {
    path: 'dist/',
    filename: isProduction ? '[name].min.js' : '[name].debug.js'
  },
  plugins: [
    new BookmarkletPlugin(),  // Wraps in javascript:(function(){...})()
    new InlineCSSPlugin()     // Inlines all CSS
  ]
};

Custom Build Plugins

BookmarkletPlugin

• Wraps output in javascript:(function(){code})() format
• Creates both prefixed and readable versions
• Handles IIFE execution context properly

InlineCSSPlugin

• Ensures no separate CSS files
• All styles embedded as JavaScript template literals
• Maintains mobile-optimized CSS structure

Build Outputs

dist/
├── bookmarklet.min.js           # Production (8.7KB) - ready for distribution
├── bookmarklet-readable.js      # Production readable version
├── bookmarklet-debug.js         # Development (13.6KB) - with debugging
└── bookmarklet-debug-readable.js # Development readable version

Error Handling

Error Classification System

const ErrorTypes = {
  NETWORK: 'network',      // Connection issues
  API: 'api',             // External service errors
  PARSING: 'parsing',     // Data processing errors
  CAPTCHA: 'captcha',     // Human verification required
  VALIDATION: 'validation', // Input validation failures
  UNKNOWN: 'unknown'      // Unclassified errors
};

const ErrorSeverity = {
  LOW: 'low',             // Recoverable, minimal impact
  MEDIUM: 'medium',       // May affect functionality
  HIGH: 'high',           // Significant impact
  CRITICAL: 'critical'    // System-breaking
};

Error Reporting Pattern

try {
  stateManager.advanceToStep('subtitle-extraction');
  const result = await apiService.extractSubtitles(videoId);
  stateManager.completeStep('subtitle-extraction');
  return result.data;
} catch (error) {
  const bookmarkletError = new BookmarkletError(
    error.message,
    ErrorTypes.API,
    true, // recoverable
    ErrorSeverity.MEDIUM
  );
  
  stateManager.failStep('subtitle-extraction', bookmarkletError);
  errorReporter.report(bookmarkletError, 'subtitle-extraction');
  throw bookmarkletError;
}

Performance Optimization

Memory Management

// Always cleanup resources
function cleanup() {
  // Remove DOM elements
  document.querySelectorAll('.yt2ai-overlay').forEach(el => el.remove());
  
  // Clear event listeners (handled by element removal)
  
  // Reset global state
  stateManager.reset();
  
  // Clear initialization flag
  window.__YT2AI_INITIALIZED__ = false;
}

Network Optimization

// Adaptive timeout based on device and connection
const getTimeout = () => {
  const base = environment.isMobile ? 30000 : 15000;
  const connection = navigator.connection;
  
  if (connection && connection.effectiveType === 'slow-2g') {
    return base * 2;
  }
  
  return base;
};

Bundle Size Optimization

• Tree shaking: Webpack eliminates unused code
• Minification: Terser with mobile-optimized settings
• No polyfills: Target modern Chrome 90+ features
• Inline everything: No external resources

Debugging

Development Mode

Add ?debug=true to any YouTube URL:

https://www.youtube.com/watch?v=VIDEO_ID&debug=true

This enables:

• Detailed console logging
• Performance monitoring
• Error stack traces
• Memory usage tracking
• Network request logging

Debug Utilities

// Available in development mode
window.__YT2AI__ = {
  initialize,           // Manual initialization
  cleanup,             // Manual cleanup
  stateManager,        // State inspection
  environment,         // Environment info
  logger,              // Logging controls
  MobileOverlay        // UI testing
};

Console Logging Levels

const logger = {
  debug: environment.isDevelopment ? console.log : () => {},
  info: console.info.bind(console, '[YT2AI:INFO]'),
  warn: console.warn.bind(console, '[YT2AI:WARN]'),
  error: console.error.bind(console, '[YT2AI:ERROR]')
};

Deployment

Release Process

1. Version bump in package.json
2. Full verification with npm run verify
3. Create GitHub release with build artifacts
4. Update documentation for any breaking changes
5. Test on actual devices before public announcement

CI/CD Pipeline

GitHub Actions automatically:

• Runs tests on Node.js 16, 18, 20
• Builds production version
• Validates bundle size (<10KB limit)
• Checks bookmarklet format (javascript: prefix)
• Creates releases for main branch pushes
• Security scanning with CodeQL

Distribution

• GitHub Releases: Primary distribution channel
• Documentation site: Installation guides and tutorials
• QR codes: Mobile-friendly installation method

Common Issues

Build Issues

1. "Cannot resolve module" - Check import paths and file existence
2. "Bundle too large" - Review imports and webpack config
3. "Babel transformation failed" - Check target browser compatibility

Runtime Issues

1. "Bookmarklet not working" - Verify javascript: prefix installation
2. "YouTube not detected" - Check URL format and hostname validation
3. "Network timeout" - Review mobile network handling and retry logic

Testing Issues

1. "Jest environment errors" - Check jsdom setup and mocks
2. "Mobile tests failing" - Verify environment mocking
3. "Async test timeouts" - Increase Jest timeout for slow operations

Contributing

Code Review Checklist

• Mobile compatibility tested on actual devices
• Error handling comprehensive with proper types
• Performance impact measured and within limits
• Test coverage maintained at 80%+ for new code
• Documentation updated for user-facing changes
• Build size impact acceptable (<10KB limit)

Pull Request Process

1. Create feature branch from main
2. Implement changes following coding standards
3. Add/update tests maintaining coverage
4. Update documentation for any user-facing changes
5. Test on mobile devices - Android Chrome priority
6. Submit PR with detailed description

Development Tips

• Test early and often on real mobile devices
• Keep bundle size in mind - every byte matters for mobile
• Prioritize error handling - mobile networks are unreliable
• Think mobile-first - desktop is secondary consideration
• Document edge cases - mobile browsers have unique behaviors

---

For questions or clarification, please open a GitHub issue or discussion.