# VideoPlayer Refactoring Plan

## Overview

The VideoPlayer is already reasonably well-organized with a `providers/` subfolder. This refactoring focuses on incremental improvements rather than major restructuring.

**Total: 2,024 lines across 10 files**

## Current Structure (Before)

```
VideoPlayer/
├── index.ts (68 lines)                 # Public exports
├── types.ts (369 lines)                # All types + helper functions ⚠️
├── VideoPlayer.tsx (202 lines)         # Main orchestrator
├── VideoPlayerContext.tsx (125 lines)  # Streaming context
├── VideoControls.tsx (139 lines)       # Vidstack controls
├── VideoErrorFallback.tsx (174 lines)  # Error UI
├── README.md
└── providers/
    ├── index.ts (8 lines)
    ├── VidstackProvider.tsx (332 lines) # YouTube/Vimeo/HLS/DASH
    ├── NativeProvider.tsx (206 lines)   # HTML5 <video>
    └── StreamProvider.tsx (401 lines)   # HTTP Range + Blob ⚠️
```

**Issues Identified:**
1. `types.ts` (369 lines) - Contains types AND helper functions
2. `StreamProvider.tsx` (401 lines) - Largest file, multiple concerns
3. Position caching logic duplicated in VidstackProvider & StreamProvider
4. No dedicated hooks/ folder

## Target Structure (After)

```
VideoPlayer/
├── index.ts                    # Public API
├── README.md
├── types/
│   ├── index.ts                # Re-exports all types
│   ├── sources.ts              # Source type definitions
│   ├── player.ts               # Player props and config types
│   └── provider.ts             # Provider-specific types
├── hooks/
│   ├── index.ts
│   └── useVideoPositionCache.ts  # Extracted caching logic
├── utils/
│   ├── index.ts
│   ├── resolvers.ts            # resolvePlayerMode, resolveFileSource
│   └── stream.ts               # Stream URL generation helpers
├── components/
│   ├── index.ts
│   ├── VideoPlayer.tsx         # Main component
│   ├── VideoControls.tsx       # Vidstack controls
│   └── VideoErrorFallback.tsx  # Error UI
├── context/
│   ├── index.ts
│   └── VideoPlayerContext.tsx
└── providers/
    ├── index.ts
    ├── VidstackProvider.tsx
    ├── NativeProvider.tsx
    └── StreamProvider.tsx
```

## Benefits

1. **DRY Principle** - Extract duplicated position caching logic
2. **Separation of Concerns** - Types split by domain
3. **Consistent Structure** - Matches AudioPlayer/ImageViewer patterns
4. **Maintainability** - Easier to find and modify specific functionality
5. **Testability** - Hooks and utils can be unit tested

## Execution Phases

| Phase | Description | Files |
|-------|-------------|-------|
| 1 | Create folder structure | types/, hooks/, utils/, components/, context/ |
| 2 | Split types | sources.ts, player.ts, provider.ts |
| 3 | Extract utils | resolvers.ts, stream.ts |
| 4 | Extract hooks | useVideoPositionCache.ts |
| 5 | Move components | VideoPlayer.tsx, VideoControls.tsx, VideoErrorFallback.tsx |
| 6 | Move context | VideoPlayerContext.tsx |
| 7 | Update exports | index.ts |
| 8 | Cleanup and verify | Delete old files, run pnpm check |

## Risk Assessment

- **Low Risk**: Incremental changes, no logic modifications
- **Testing**: Run `pnpm check` after each phase
- **Providers**: Already well-organized, minimal changes needed
