timeline-svg/DEPENDS.md

# Dependencies - Timeline SVG Generator

This document lists all third-party libraries and tools used in the Timeline SVG Generator project.

## Runtime Dependencies

### Production Dependencies

#### PapaParse
- **Version**: 5.4.1
- **Source**: https://cdn.jsdelivr.net/npm/papaparse@5.4.1/papaparse.min.js
- **Purpose**: CSV parsing and processing
- **License**: MIT
- **Usage**: Loaded via CDN in index.html:6
- **Documentation**: https://www.papaparse.com/
- **Why chosen**: Robust CSV parser with header support, handles edge cases, small footprint

## Development Dependencies

### Testing Framework

#### Vitest
- **Version**: ^2.1.0
- **Purpose**: Modern test runner and framework
- **License**: MIT
- **Documentation**: https://vitest.dev/
- **Features**: Fast execution, ESM support, built-in coverage, watch mode

#### @vitest/ui
- **Version**: ^2.1.0
- **Purpose**: Browser-based test UI and visualization
- **License**: MIT
- **Usage**: `npm run test:ui`

#### @vitest/coverage-v8
- **Version**: ^2.1.0
- **Purpose**: Code coverage reporting using V8 engine
- **License**: MIT
- **Usage**: `npm run test:coverage`

#### jsdom
- **Version**: ^25.0.0
- **Purpose**: DOM environment simulation for Node.js testing
- **License**: MIT
- **Documentation**: https://github.com/jsdom/jsdom
- **Usage**: Enables testing of browser APIs and DOM manipulation

## System Requirements

### Node.js
- **Minimum Version**: 18.0.0
- **Recommended**: 20.0.0 or later
- **Purpose**: Development environment and package management

### NPM
- **Minimum Version**: 8.0.0
- **Purpose**: Package manager for development dependencies

## Browser Requirements (Production)

### Supported Browsers
- **Chrome**: 80+
- **Firefox**: 75+
- **Safari**: 13+
- **Edge**: 80+

### Required Browser Features
- ES6 Modules support
- Fetch API
- File API (for file uploads)
- SVG support
- CSS Grid and Flexbox

## External Services

### CDN Dependencies

#### jsDelivr
- **Purpose**: Content Delivery Network for PapaParse
- **URL**: https://cdn.jsdelivr.net/
- **Fallback**: None (project requires internet connection)
- **Alternative**: Could be replaced with local copy

## Font Dependencies

### Inter Font Family
- **Source**: System fonts (Inter, Arial, sans-serif fallback)
- **Usage**: Default UI typography in index.html:11
- **Purpose**: Modern, readable interface typography
- **Fallback**: Arial → sans-serif

## Development Tools (Optional)

### Recommended IDE Extensions
- **Vitest**: VS Code extension for integrated test running
- **JavaScript ES6**: Enhanced JavaScript support
- **Live Server**: Local development server

### Git
- **Purpose**: Version control
- **Required for**: Contributing to the project

## Security Considerations

### CDN Dependencies
- **Risk**: External dependency on jsDelivr
- **Mitigation**: Well-established CDN with high uptime
- **Alternative**: Local hosting of PapaParse possible

### No Backend Dependencies
- **Advantage**: Reduced attack surface
- **Note**: All processing happens client-side

## Dependency Management

### Installation
```bash
# Install all development dependencies
npm install

# Production use
# No installation needed - open index.html in browser
```

### Updates
```bash
# Check for outdated packages
npm outdated

# Update to latest compatible versions
npm update

# Update to latest major versions (breaking changes possible)
npm install package@latest
```

### Vulnerability Scanning
```bash
# Check for security vulnerabilities
npm audit

# Fix automatically fixable vulnerabilities
npm audit fix
```

## License Compatibility

All dependencies use MIT or MIT-compatible licenses:
- **PapaParse**: MIT License
- **Vitest**: MIT License
- **jsdom**: MIT License
- **@vitest/ui**: MIT License
- **@vitest/coverage-v8**: MIT License

## Dependency Decision Matrix

| Library | Alternatives Considered | Why Chosen |
|---------|------------------------|------------|
| PapaParse | CSV.js, custom parser | Mature, feature-rich, wide browser support |
| Vitest | Jest, Mocha | Modern, fast, ESM native, zero config |
| jsdom | happy-dom, playwright | Most mature DOM simulation, wide compatibility |

## Future Dependency Considerations

### Potential Additions
- **TypeScript**: For type safety (would require build step)
- **Playwright**: For E2E testing
- **ESLint**: For code quality
- **Prettier**: For code formatting

### Minimization Strategy
The project intentionally keeps dependencies minimal to:
- Reduce bundle size
- Minimize security surface
- Maintain browser compatibility
- Enable offline usage
- Simplify deployment

## Monitoring

### Dependency Health
- Monitor PapaParse for security updates
- Watch Vitest releases for test improvements
- Check browser compatibility quarterly

### Performance Impact
- PapaParse: ~45KB minified
- No runtime performance impact from dev dependencies
- Zero build step maintains fast development cycle