# YouTube Creator: Build Scenes from Plan - User Flow & Safeguards

## User Flow

### Step-by-Step Process

1. **User clicks "Build Scenes from Plan" button**
   - **Location**: `ScenesStep` component (Step 2)
   - **Condition**: Button only shows when `scenes.length === 0`
   - **Handler**: `handleBuildScenes()` in `YouTubeCreator.tsx`

2. **Frontend Validation**
   - ✅ Checks if `videoPlan` exists (shows error if missing)
   - ✅ **NEW**: Checks if scenes already exist (prevents duplicate calls)
   - ✅ Sets loading state to prevent double-clicks
   - ✅ Shows preflight check via `OperationButton` (subscription validation)

3. **API Call**
   - **Endpoint**: `POST /api/youtube/scenes`
   - **Payload**: `{ video_plan: VideoPlan, custom_script?: string }`
   - **Client**: `youtubeApi.buildScenes(videoPlan)`

4. **Backend Processing** (`YouTubeSceneBuilderService.build_scenes_from_plan`)
   
   **Optimization Strategy (minimizes AI calls):**
   
   a. **Check for existing scenes** (0 AI calls)
      - If `video_plan.scenes` exists and `_scenes_included=True` → Reuse scenes
      - Logs: `♻️ Reusing X scenes from plan - skipping generation`
   
   b. **Custom script parsing** (0 AI calls)
      - If `custom_script` provided → Parse into scenes without AI
   
   c. **Shorts optimization** (0 AI calls if already in plan)
      - If `duration_type="shorts"` and `_scenes_included=True` → Use normalized scenes
      - Otherwise → Generate scenes normally (1 AI call)
   
   d. **Medium/Long videos** (1-3 AI calls)
      - Generate scenes: 1 AI call
      - Batch enhance prompts:
        - Shorts: Skip enhancement (0 calls)
        - Medium: 1 batch call for all scenes (1 call)
        - Long: 2 batch calls, split scenes (2 calls)
   
   **Total AI calls per video type:**
   - **Shorts** (with optimization): 0-1 calls (0 if included in plan, 1 if not)
   - **Medium**: 2 calls (1 generation + 1 batch enhancement)
   - **Long**: 3 calls (1 generation + 2 batch enhancements)
   - **Custom script**: 0-2 calls (0 parsing + 0-2 enhancements)

5. **Response Processing**
   - Normalizes scene data (adds `enabled: true` by default)
   - Updates state via `updateState({ scenes: updatedScenes })`
   - Shows success message
   - Navigates to Step 2 (Scenes review)

## Safeguards to Prevent Wasting AI Calls

### Frontend Safeguards

1. **Button Visibility**
   - Button only appears when `scenes.length === 0`
   - Prevents accidental clicks when scenes exist

2. **Duplicate Call Prevention** ✅ **NEW**
   ```typescript
   if (scenes.length > 0) {
     console.warn('[YouTubeCreator] Scenes already exist, skipping build');
     setError('Scenes have already been generated...');
     return;
   }
   ```

3. **Loading State**
   - Button disabled during `loading` state
   - Prevents multiple simultaneous calls

4. **Preflight Check**
   - `OperationButton` performs subscription validation before API call
   - Shows cost estimate and subscription limits
   - Prevents calls if limits exceeded (but allows click to show modal)

### Backend Safeguards

1. **Scene Reuse Detection** ✅ **ENHANCED**
   - Checks `video_plan.scenes` and `_scenes_included` flag
   - Reuses existing scenes (0 AI calls)
   - Logs reuse to track optimization success

2. **Shorts Optimization**
   - When plan is generated with `include_scenes=True` for shorts
   - Scenes are included in plan generation (1 combined call)
   - Scene builder reuses them instead of regenerating

3. **Batch Processing**
   - Visual prompt enhancement batched (1-2 calls instead of N calls)
   - Shorts skip enhancement entirely (saves 1 call)

4. **Error Handling**
   - Graceful fallbacks if batch enhancement fails
   - Uses original prompts instead of failing completely

## Testing Recommendations

### To Test Without Wasting AI Calls

1. **Use Shorts Duration**
   - Scenes included in plan generation (optimized)
   - Scene building reuses existing scenes (0 calls)

2. **Use Custom Script**
   - Parse custom script (0 AI calls)
   - Still needs enhancement for medium/long (1-2 calls)

3. **Test with Existing Scenes**
   - Frontend guard prevents duplicate calls
   - Backend detects and reuses existing scenes

4. **Monitor Logs**
   - Look for `♻️ Reusing X scenes` messages
   - Verify `0 AI calls` for optimized paths
   - Check scene count matches expectations

### Log Messages to Watch

- `♻️ Reusing X scenes from plan - skipping generation` ✅ **NEW**
- `Using scenes from optimized plan+scenes call` (shorts optimization)
- `Skipping prompt enhancement for shorts` (saves 1 call)
- `Batch enhancing X scenes in 1 AI call` (medium optimization)
- `Batch enhancing X scenes in 2 AI calls` (long optimization)

## API Call Summary

| Video Type | Scenario | AI Calls | Details |
|------------|----------|----------|---------|
| Shorts | Plan with scenes | 0 | Reuses scenes from plan |
| Shorts | Plan without scenes | 1 | Generates scenes only (no enhancement) |
| Medium | Normal flow | 2 | 1 generation + 1 batch enhancement |
| Long | Normal flow | 3 | 1 generation + 2 batch enhancements |
| Any | Custom script | 0-2 | 0 parsing + 0-2 enhancements |

## Code References

- **Frontend Handler**: `frontend/src/components/YouTubeCreator/YouTubeCreator.tsx:214`
- **API Endpoint**: `backend/api/youtube/router.py:295`
- **Scene Builder**: `backend/services/youtube/scene_builder.py:26`
- **Operation Helper**: `frontend/src/components/YouTubeCreator/utils/operationHelpers.ts:136`