Add scene transitions, music mixing, captions, and interactivity to V2 player

[NextMonthLab]

Summary

This PR significantly enhances the V2 player with cinematic scene transitions, background music with audio ducking, styled caption rendering, and interactive character chat overlays. The player now supports smooth crossfade and fade-to-black transitions between scenes, manages audio mixing for music and narration, and displays captions with customizable styling from the manifest.

Key Changes

Scene Transitions

• Implemented scene transition detection and animation system with support for crossfade, fade-to-black, and cut styles
• Added imperative DOM manipulation with getBoundingClientRect() reflow forcing to ensure CSS transitions animate correctly
• Maintains outgoing scene during transition phase and overlays incoming scene with proper z-index layering
• Transition durations and styles are read from the manifest

Audio Mixing & Music

• Integrated useAudioMixer hook to manage background music and narration playback
• Added music connection on user gesture (respects Chrome autoplay policy)
• Implemented audio ducking: music volume reduces when narration plays, restores when narration ends
• Music pauses/resumes with playback state (playing/paused)
• Added hidden <audio> element for background music with loop support

Caption Rendering

• Created new CaptionOverlay component with responsive, token-based styling
• Captions now use caption engine presets (typography, colors, backgrounds) from manifest settings
• Supports configurable positioning (top, middle, bottom) and font size scaling
• Uses responsive clamp() CSS for font sizing instead of fixed pixels

Interactivity

• Added support for interactive character chat nodes that appear after specific scenes
• Character nodes display with gradient overlay and character information from manifest
• Implemented dismissNode() callback to close interactivity overlay and advance to next scene
• Integrated InteractivityNode component with character list and chat functionality

SceneRenderer Updates

• Added callbacks for narration start/end to trigger audio ducking
• Added connectNarration callback to wire narration audio to the mixer
• Passes captionSettings to CaptionOverlay for styled caption rendering
• Narration ducking fires on audio play event and ended event

useScenePlayback Hook

• Extended to track activeNodeId and provide dismissNode callback
• onSceneComplete now checks for interactivity nodes before advancing
• If a node exists for the current scene, it displays instead of auto-advancing

Notable Implementation Details

• Transition animation uses useRef to track previous/outgoing scene indices and manage timeout cleanup
• CSS transitions are driven imperatively via getBoundingClientRect() to force browser reflow between setting initial and target opacity values
• Audio mixer initialization is deferred until user gesture to comply with browser autoplay policies
• Caption styling is computed from manifest presets with responsive sizing via CSS clamp()

https://claude.ai/code/session_011izHphSuXPrgDCtVZW8a2J