GPU Engine

src/engine/
  WebGPUEngine.ts           # Thin facade orchestrating all subsystems
  WebCodecsPlayer.ts        # Full WebCodecs decoding (MP4Box demux + VideoDecoder)
  WebCodecsExportMode.ts    # Sequential export frame decoding
  ParallelDecodeManager.ts  # Parallel multi-clip decoding for export
  featureFlags.ts           # Runtime feature toggles
  webCodecsTypes.ts         # Shared MP4Box/sample types
  index.ts                  # Public exports
  core/
    WebGPUContext.ts         # GPU adapter/device/canvas management + device loss recovery
    RenderTargetManager.ts   # Ping-pong buffers, independent preview buffers, effect temp textures
    types.ts                 # Layer, BlendMode, EngineStats, LayerRenderData, blend mode map
  render/
    RenderLoop.ts            # RAF loop with idle detection, frame rate limiting, watchdog
    RenderDispatcher.ts      # Orchestrates per-frame render: collect -> composite -> output
    Compositor.ts            # Ping-pong compositing with inline + complex effects
    LayerCollector.ts        # Imports textures from video/image/text/nested sources
    NestedCompRenderer.ts    # Pre-renders nested compositions to offscreen textures
    layerEffectStack.ts      # Splits effects into inline vs. complex via splitLayerEffects()
  pipeline/
    CompositorPipeline.ts    # GPU pipelines for standard + external composite + copy shaders
    OutputPipeline.ts        # Final output to canvas with optional transparency grid
    SlicePipeline.ts         # Corner-pin warped slices with 16x16 subdivision
  texture/
    TextureManager.ts        # Image/canvas/video/ImageBitmap texture creation and caching
    MaskTextureManager.ts    # Per-layer mask textures with white fallback
    ScrubbingCache.ts        # LRU frame cache for scrubbing, last-frame cache, RAM Preview
  managers/
    CacheManager.ts          # Owns ScrubbingCache lifecycle + video time tracking
    ExportCanvasManager.ts   # OffscreenCanvas for zero-copy VideoFrame export
    OutputWindowManager.ts   # External popup windows for multi-display output
  video/
    VideoFrameManager.ts     # requestVideoFrameCallback tracking for frame readiness
  stats/
    PerformanceStats.ts      # FPS, timing, frame drop tracking with ring buffer
  analysis/
    OpticalFlowAnalyzer.ts   # GPU Lucas-Kanade optical flow (compute shaders)
    ScopeRenderer.ts         # Delegates to waveform/histogram/vectorscope
    HistogramScope.ts        # GPU-accelerated histogram (compute + render)
    WaveformScope.ts         # GPU-accelerated waveform with phosphor glow
    VectorscopeScope.ts      # GPU-accelerated vectorscope (BT.709 CbCr)
  audio/
    AudioMixer.ts            # Multi-track mixing with mute/solo
    AudioEncoder.ts          # WebCodecs AAC/Opus encoding
    AudioExportPipeline.ts   # Orchestrates complete audio export
  export/
    FrameExporter.ts         # Frame-by-frame export orchestrator
    VideoEncoderWrapper.ts   # WebCodecs VideoEncoder + mp4/webm muxers

WebGPUEngine (Facade)
  Core:
  ├── WebGPUContext             # GPU adapter, device, canvas configuration
  ├── RenderTargetManager       # Ping-pong + independent + effect temp textures
  ├── PerformanceStats          # FPS, timing, drops

  Render:
  ├── RenderLoop                # RAF with idle detection + watchdog
  ├── RenderDispatcher          # Orchestrates per-frame render
  ├── LayerCollector            # Texture import from all source types
  ├── Compositor                # Ping-pong compositing + effects
  └── NestedCompRenderer        # Offscreen nested composition rendering

  Pipelines:
  ├── CompositorPipeline        # Standard + external composite GPU pipelines
  ├── EffectsPipeline           # Per-effect GPU pipelines (30+ effects)
  ├── OutputPipeline            # Final output with transparency grid
  └── SlicePipeline             # Corner-pin warped slice output

  Textures:
  ├── TextureManager            # Image/canvas/video/bitmap textures
  ├── MaskTextureManager        # Per-layer mask textures
  └── VideoFrameManager         # RVFC frame readiness tracking

  Managers:
  ├── CacheManager              # ScrubbingCache + video time tracking
  ├── ExportCanvasManager       # Zero-copy export via OffscreenCanvas
  └── OutputWindowManager       # External popup windows

// Initialization parameters
- GPU adapter: powerPreference configurable ('high-performance' | 'low-power')
- Device: requiredLimits: { maxTextureDimension2D: 4096 }
- Canvas: preferred format via navigator.gpu.getPreferredCanvasFormat()
- Alpha mode: 'opaque' for preview canvases, 'premultiplied' for export
- Sampler: linear filtering, clamp-to-edge
- Device loss recovery: 100ms delay before re-initialization (up to 3 attempts)

Device Lost → notify callbacks → clean GPU resources → wait 100ms →
  → re-initialize (up to 3 attempts) → recreate all resources →
  → reconfigure canvases → restart render loop → notify restored

Clear Ping → transparent

Layer 1 → Read Ping, Write Pong (composite)
Layer 2 → Read Pong, Write Ping (composite)
Layer 3 → Read Ping, Write Pong (composite)
...
Final → Output Pipeline → Canvas(es)

// CompositorPipeline uniform layout
[0]  opacity: f32
[1]  blendMode: u32              // 0-36 (37 blend modes)
[2]  positionX: f32
[3]  positionY: f32
[4]  scaleX: f32
[5]  scaleY: f32
[6]  rotationZ: f32              // radians
[7]  sourceAspect: f32
[8]  outputAspect: f32
[9]  time: f32                   // for dissolve effects
[10] hasMask: u32                // 0 or 1
[11] maskInvert: u32             // 0 or 1
[12] rotationX: f32              // radians
[13] rotationY: f32              // radians
[14] perspectiveDistance: f32    // default 2.0
[15] maskFeather: f32            // blur radius in pixels
[16] maskFeatherQuality: u32     // 0=low, 1=med, 2=high
[17] positionZ: f32              // depth position
[18] inlineBrightness: f32       // 0 = no change
[19] inlineContrast: f32         // 1 = no change
[20] inlineSaturation: f32       // 1 = no change
[21] inlineInvert: u32           // 0 or 1

interface MotionResult {
  total: number;       // Overall motion 0-1
  global: number;      // Camera/scene motion 0-1
  local: number;       // Object motion 0-1
  isSceneCut: boolean; // True if likely a scene cut
}

flags = {
  useRenderGraph: false,           // Render Graph executor (stubs — not ready)
  useDecoderPool: false,           // Shared decoder pool (not wired yet)
  useFullWebCodecsPlayback: false, // Preview uses HTML video by default;
                                   // WebCodecs is used for export and full-mode only
}

// Toggle in browser console
window.__ENGINE_FLAGS__.useFullWebCodecsPlayback = true

// Check GPU status
chrome://gpu

// Debug commands
window.__ENGINE_FLAGS__                                          // view/toggle feature flags
Logger.enable('WebGPU,Compositor,RenderLoop')                    // enable engine logging
Logger.enable('LayerCollector,TextureManager')                   // debug texture import