# Studio Clip Regions - Modular Architecture

This directory contains the modular refactor of the clip regions rendering system, replacing the original 2172-line `makeStudioClipRegions.ts` with a clean, maintainable architecture.

## Structure

```
studioClipRegions/
├── makeStudioClipRegionsV2.ts        # Main entry point (~130 lines)
├── makeClipRegionsForClip.ts         # Per-clip orchestrator (~70 lines)
├── types.ts                          # Core type definitions
├── utils.ts                          # Shared utilities
├── buildClipContext.ts               # Clip context builder
├── buildDraggedClipsMap.ts           # Dragged clips map builder
├── getClipGeometry.ts                # Geometry calculations
├── getClipRenderingState.ts          # Rendering state detection
├── getTrackMutedState.ts             # Track mute state logic
├── shouldDarkenClip.ts               # Shared darkening logic (used by waveforms too!)
└── regions/
    ├── makeBackgroundRegion.ts       # Colored clip backgrounds
    ├── makeDebugRegions.ts           # Debug markers & timing info
    ├── makeFadeRegions.ts            # Fade in/out handles
    ├── makeSnapVisualizationRegions.ts # Snap alignment indicators
    ├── makeTakeLaneOverlayRegion.ts  # Unarranged take overlays
    ├── makeTitleRegions.ts           # Title display & interaction
    └── makeTrimRegions.ts            # Edge drag/resize regions
```

## Features

### All 13 Region Types Implemented
1. Background rendering
2. Snap visualization (drag feedback)
3. Take lane overlays
4. Debug markers
5. Title hover target
6. Title interaction (drag, double-click)
7. Title display (text rendering)
8. Left edge drag (title bar)
9. Right edge drag (title bar)
10. Left waveform edge (magnet mode)
11. Right waveform edge (magnet mode)
12. Fade in handle
13. Fade out handle

### Supported Modes
- ✅ Magnet mode (maintain clip adjacency)
- ✅ Classic mode (stretch/trim neighbors)
- ✅ One-track mode
- ✅ Lyrics replacement mode
- ✅ Preview mode
- ✅ Debug mode

### Visual States
- ✅ Normal clips
- ✅ Lifted (dragging) clips
- ✅ Ghost clips (unlifted copies)
- ✅ Preview clips
- ✅ Uploading clips
- ✅ Muted clips
- ✅ Take lanes with unarranged content

## Key Benefits

### 1. Maintainability
- **Focused modules**: Each region type in its own file
- **Clear responsibilities**: Easy to find and modify specific behavior
- **No monolithic files**: Largest file is ~1000 lines (trim regions)

### 2. Reusability
- **`shouldDarkenClip()`**: Used by both clip regions AND waveform rendering
- **State detection functions**: Can be used by other rendering systems
- **Type safety**: Common types ensure consistency

### 3. Readability
- **Main file**: 130 lines (was 2172 lines - **94% reduction**)
- **Clear flow**: Easy to understand high-level logic
- **Self-documenting**: Function names explain intent

### 4. Bug Fixes
- Fixed waveform shading sync issue (ghost clips during edge drag)
- Consistent darkening logic across all visual systems

## Usage

The module is automatically used by `StudioTimeline.tsx` and `StudioLayoutV1.tsx`:

```typescript
import makeStudioClipRegions from './canvasRegions/studioClipRegions/makeStudioClipRegionsV2';

const { 
  aboveSelection,
  belowSelection,
  belowSelectionLifted,
  belowGridLifted,
  belowGrid,
  previewClipRegions 
} = makeStudioClipRegions(studioContext);
```

## Architecture Pattern

This refactor demonstrates a clean pattern for breaking down complex rendering logic:

1. **Main entry point**: High-level orchestration only
2. **Per-item processor**: Delegates to specialized modules
3. **Specialized modules**: Focused, single-responsibility functions
4. **Shared utilities**: Reusable across systems

This pattern can be applied to other complex region builders in the codebase.