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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```javascript
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
```javascript
function validateYouTubeContext() {
    // Validates hostname and extracts video ID
    // Supports: youtube.com/watch, youtu.be, shorts, embed
    // Returns: { videoId, url }
}
```

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

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

#### State Management
```javascript
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**
   ```javascript
   const videoId = extractVideoId(url);  // ✅ Preferred
   let retryCount = 0;                   // ✅ When reassignment needed
   var oldStyle = 'avoid';               // ❌ Avoid var
   ```

2. **Prefix all CSS classes with `yt2ai-`**
   ```javascript
   element.className = 'yt2ai-overlay yt2ai-loading';  // ✅ Correct
   element.className = 'overlay loading';               // ❌ Conflicts possible
   ```

3. **Use `z-index: 999999` or higher for overlays**
   ```javascript
   const styles = `
     .yt2ai-overlay {
       z-index: 999999;  /* ✅ Above YouTube's interface */
     }
   `;
   ```

4. **Handle all async operations with try/catch**
   ```javascript
   // ✅ 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**
   ```javascript
   const styles = `
     .yt2ai-close-btn {
       min-width: 44px;   /* ✅ WCAG AA compliance */
       min-height: 44px;
     }
   `;
   ```

2. **Use `touchend` events, not `click` for mobile optimization**
   ```javascript
   const eventType = environment.isMobile ? 'touchend' : 'click';
   button.addEventListener(eventType, handler);
   ```

3. **Always prevent body scroll when showing modals**
   ```javascript
   show() {
     document.body.appendChild(this.element);
     document.body.style.overflow = 'hidden';  // ✅ Prevent scroll
   }
   ```

#### Bookmarklet-Specific Rules
1. **Never rely on external dependencies in production**
   ```javascript
   // ✅ Self-contained
   const helper = (function() {
     // All code inline
   })();
   
   // ❌ External dependency
   import { helper } from 'external-lib';
   ```

2. **Always namespace global variables with `__YT2AI_`**
   ```javascript
   window.__YT2AI_INITIALIZED__ = true;     // ✅ Namespaced
   window.__YT2AI_VERSION__ = '1.0.0';      // ✅ Namespaced
   window.initialized = true;                // ❌ Generic name
   ```

3. **Always validate YouTube context before execution**
   ```javascript
   function initialize() {
     if (!window.location.hostname.includes('youtube.com')) {
       throw new BookmarkletError('YouTube page required');
     }
   }
   ```

## Testing Guidelines

### Unit Testing

#### Test Structure (Arrange-Act-Assert)
```javascript
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
```javascript
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
```javascript
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
```javascript
// 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
```javascript
// 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
```javascript
// 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:

```javascript
// 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
```bash
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
```javascript
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
```javascript
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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
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.