From 8ecdd023222586c11528976b0af6bd4358d1d58a Mon Sep 17 00:00:00 2001
From: "robb.fladry" <robb@fladrycreative.com>
Date: Sun, 19 Jul 2026 21:04:10 -0400
Subject: [PATCH 1/2] feat(phase-1): WebGL2 compositor engine replaces
 CSS-filter pipeline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New portable engine module (client/src/engine/ — no React/store/DOM deps
beyond the canvas): three-pass pipeline of deck mix (A/B textures with
crossfade + geometry transform), an FX über-shader (grade, glitch,
chromatic aberration, pixelate, sharpen/blur, noise, vignette, scanlines —
identity at defaults), and a ping-pong feedback pass adding Trails/Warp,
the temporal effects CSS filters could never do.

Player now renders through the compositor canvas; the hidden <video> is
the texture source. CSS filter/transform strings and the three effect
overlay divs are gone. Audio-reactive mode feeds FFT levels into shader
uniforms instead of rewriting style.filter. Trails/Warp sliders added to
the effects panel; dev builds expose __store for console-driven testing.

Verified live: 60 fps with glitch+chroma+trails+scanlines stacked, clean
identity passthrough at defaults.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 client/src/components/Player.tsx            | 123 ++----
 client/src/components/VideoEffectsPanel.tsx |  32 ++
 client/src/engine/compositor.ts             | 455 ++++++++++++++++++++
 client/src/engine/gl.ts                     |  90 ++++
 client/src/engine/params.ts                 |  82 ++++
 client/src/lib/store.ts                     |   4 +
 client/src/lib/types.ts                     |   2 +
 client/src/main.tsx                         |   7 +
 8 files changed, 702 insertions(+), 93 deletions(-)
 create mode 100644 client/src/engine/compositor.ts
 create mode 100644 client/src/engine/gl.ts
 create mode 100644 client/src/engine/params.ts

diff --git a/client/src/components/Player.tsx b/client/src/components/Player.tsx
index 1f4bcdb..a05137e 100644
--- a/client/src/components/Player.tsx
+++ b/client/src/components/Player.tsx
@@ -3,6 +3,7 @@ import { useAdaptiveColors } from '@/hooks/use-adaptive-colors';
 import { Button } from '@/components/ui/button';
 import { Slider } from '@/components/ui/slider';
 import { useStore } from '@/lib/store';
+import { Compositor } from '@/engine/compositor';
 import { Play, Pause, SkipBack, SkipForward, Volume2, Maximize, Minimize, Scissors } from 'lucide-react';
 import { PopOutPlayer } from '@/components/PopOutPlayer';
 import { videoPreloader } from '@/lib/video-preloader';
@@ -13,6 +14,7 @@ import { TextOverlay } from '@/components/TextOverlay';
 export function Player() {
   const videoRef = useRef<HTMLVideoElement>(null);
   const canvasRef = useRef<HTMLCanvasElement>(null);
+  const compositorRef = useRef<Compositor | null>(null);
   const playerContainerRef = useRef<HTMLDivElement>(null);
   const audioContextRef = useRef<AudioContext | null>(null);
   const sourceNodeRef = useRef<MediaElementAudioSourceNode | null>(null);
@@ -425,11 +427,7 @@ export function Player() {
           const midNorm = mid / 255;
           const trebleNorm = treble / 255;
           
-          // Apply reactive effects (this could be enhanced further)
-          if (videoRef.current) {
-            const reactiveFilter = `brightness(${1 + bassNorm * 0.3}) saturate(${1 + midNorm * 0.5}) hue-rotate(${trebleNorm * 30}deg)`;
-            videoRef.current.style.filter = reactiveFilter;
-          }
+          compositorRef.current?.setAudioLevels({ bass: bassNorm, mid: midNorm, treble: trebleNorm }, true);
 
           animationFrame = requestAnimationFrame(draw);
         };
@@ -448,9 +446,30 @@ export function Player() {
       if (animationFrame) {
         cancelAnimationFrame(animationFrame);
       }
+      compositorRef.current?.setAudioLevels({ bass: 0, mid: 0, treble: 0 }, false);
     };
   }, [isAudioReactive, isPlaying]);
 
+  // --- WebGL engine lifecycle: canvas + video exist only while a video is
+  // loaded, so (re)create the compositor whenever that flips.
+  useEffect(() => {
+    if (!canvasRef.current || !videoRef.current) return;
+    const compositor = new Compositor(canvasRef.current);
+    compositor.setVideoA(videoRef.current);
+    compositor.setParams({ ...useStore.getState().videoEffects, gamma: useStore.getState().videoEffects.gamma / 100 });
+    compositor.start();
+    compositorRef.current = compositor;
+    return () => {
+      compositorRef.current = null;
+      compositor.destroy();
+    };
+  }, [!!currentVideo]);
+
+  // Drive engine parameters from the effects store
+  useEffect(() => {
+    compositorRef.current?.setParams({ ...videoEffects, gamma: videoEffects.gamma / 100 });
+  }, [videoEffects]);
+
   // Update audio effects when settings change
   useEffect(() => {
     if (!audioContextRef.current || !gainNodeRef.current) return;
@@ -702,32 +721,6 @@ export function Player() {
     return `${minutes}:${seconds.toString().padStart(2, '0')}`;
   };
 
-  // Generate CSS filter string from video effects
-  const generateFilterString = () => {
-    const filters = [
-      `brightness(${videoEffects.brightness}%)`,
-      `contrast(${videoEffects.contrast}%)`,
-      `saturate(${videoEffects.saturation}%)`,
-      `hue-rotate(${videoEffects.hue}deg)`,
-      `blur(${videoEffects.blur}px)`,
-      `opacity(${videoEffects.opacity}%)`,
-      `grayscale(${videoEffects.grayscale}%)`,
-      `invert(${videoEffects.invert}%)`,
-      `sepia(${videoEffects.sepia}%)`
-    ];
-    return filters.join(' ');
-  };
-
-  // Generate transform string from video effects
-  const generateTransformString = () => {
-    const transforms = [
-      `rotate(${videoEffects.rotate}deg)`,
-      `scaleX(${videoEffects.scaleX / 100})`,
-      `scaleY(${videoEffects.scaleY / 100})`
-    ];
-    return transforms.join(' ');
-  };
-
   const toggleFullscreen = async () => {
     if (!playerContainerRef.current) {
       console.warn('No player container reference for fullscreen');
@@ -914,78 +907,22 @@ export function Player() {
         }`}
         onDoubleClick={toggleFullscreen}
       >
+        {/* Hidden media source: the engine samples this element as a GPU
+            texture every frame. Kept in-DOM and sized so decode continues. */}
         <video
           ref={videoRef}
-          className="w-full h-full object-contain"
+          className="absolute inset-0 w-full h-full opacity-0 pointer-events-none"
           controls={false}
           preload="metadata"
           playsInline
-          style={{ 
-            display: isAudioReactive ? 'none' : 'block',
-            filter: generateFilterString(),
-            transform: generateTransformString(),
-            willChange: 'filter, transform',
-            maxHeight: '100%',
-            maxWidth: '100%'
-          }}
+          muted={false}
         />
+        {/* Program output: the WebGL compositor canvas */}
         <canvas
           ref={canvasRef}
-          width={640}
-          height={360}
-          className="w-full h-full object-contain"
-          style={{ 
-            display: isAudioReactive ? 'block' : 'none',
-            filter: generateFilterString(),
-            transform: generateTransformString()
-          }}
+          className="w-full h-full"
         />
         
-        {/* VJ Effects Overlays */}
-        {videoEffects.scanlines && (
-          <div 
-            className="absolute inset-0 opacity-30 pointer-events-none"
-            style={{
-              background: `repeating-linear-gradient(
-                0deg,
-                transparent,
-                transparent 2px,
-                rgba(0, 255, 0, 0.1) 2px,
-                rgba(0, 255, 0, 0.1) 4px
-              )`
-            }}
-          />
-        )}
-        
-        {videoEffects.glitchIntensity > 0 && (
-          <div 
-            className="absolute inset-0 pointer-events-none mix-blend-difference"
-            style={{
-              background: `linear-gradient(90deg, 
-                rgba(255, 0, 0, ${videoEffects.glitchIntensity / 400}) 0%, 
-                transparent 33%, 
-                rgba(0, 255, 0, ${videoEffects.glitchIntensity / 400}) 66%, 
-                transparent 100%
-              )`,
-              animation: videoEffects.glitchIntensity > 50 ? 'glitch 0.1s infinite' : 'none'
-            }}
-          />
-        )}
-        
-        {videoEffects.chromaticAberration > 0 && (
-          <div 
-            className="absolute inset-0 pointer-events-none"
-            style={{
-              mixBlendMode: 'screen',
-              background: `radial-gradient(circle, 
-                rgba(255, 0, 0, ${videoEffects.chromaticAberration / 300}) 0%, 
-                transparent 50%, 
-                rgba(0, 0, 255, ${videoEffects.chromaticAberration / 300}) 100%
-              )`
-            }}
-          />
-        )}
-        
         {/* Text Overlay */}
         <TextOverlay 
           textSettings={textOverlay}
diff --git a/client/src/components/VideoEffectsPanel.tsx b/client/src/components/VideoEffectsPanel.tsx
index 7f09ba1..2e59811 100644
--- a/client/src/components/VideoEffectsPanel.tsx
+++ b/client/src/components/VideoEffectsPanel.tsx
@@ -49,6 +49,8 @@ export function VideoEffectsPanel() {
       vignette: 0,
       sharpen: 0,
       noise: 0,
+      trails: 0,
+      warp: 0,
     });
   };
 
@@ -396,6 +398,36 @@ export function VideoEffectsPanel() {
               className="mt-1"
             />
           </div>
+
+          <div className="space-y-2">
+            <div className="flex justify-between items-center">
+              <Label className="text-xs font-medium">Trails</Label>
+              <span className="text-xs text-gray-500 bg-gray-100 px-2 py-0.5 rounded">{videoEffects.trails}%</span>
+            </div>
+            <Slider
+              value={[videoEffects.trails]}
+              onValueChange={([value]) => updateVideoEffect('trails', value)}
+              min={0}
+              max={100}
+              step={1}
+              className="mt-1"
+            />
+          </div>
+
+          <div className="space-y-2">
+            <div className="flex justify-between items-center">
+              <Label className="text-xs font-medium">Warp</Label>
+              <span className="text-xs text-gray-500 bg-gray-100 px-2 py-0.5 rounded">{videoEffects.warp}%</span>
+            </div>
+            <Slider
+              value={[videoEffects.warp]}
+              onValueChange={([value]) => updateVideoEffect('warp', value)}
+              min={0}
+              max={100}
+              step={1}
+              className="mt-1"
+            />
+          </div>
         </div>
 
         {/* Toggle Effects */}
diff --git a/client/src/engine/compositor.ts b/client/src/engine/compositor.ts
new file mode 100644
index 0000000..c5dfaf2
--- /dev/null
+++ b/client/src/engine/compositor.ts
@@ -0,0 +1,455 @@
+// The Static Buffet compositor: two video decks in, shader pipeline out.
+//
+// Pass 1 (MIX): deck textures sampled with contain-fit + geometry transform,
+//               A/B crossfade.
+// Pass 2 (FX):  single über-shader — pixelate, glitch, chromatic aberration,
+//               blur/sharpen, full color grade, noise, vignette, scanlines.
+//               Every stage is identity at its default parameter value.
+// Pass 3 (FEEDBACK): ping-pong trails/warp — the temporal pass CSS could
+//               never do — then blit to screen.
+//
+// Portable core: no React, no store, no DOM beyond the canvas (and the
+// HTMLVideoElements handed in as sources).
+
+import { createProgram, createQuad, createTarget, createVideoTexture, destroyTarget, QUAD_VS, type Target } from './gl';
+import { IDENTITY_PARAMS, type AudioLevels, type EngineParams } from './params';
+
+const MIX_FS = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 outColor;
+
+uniform sampler2D uTexA;
+uniform sampler2D uTexB;
+uniform float uCrossfade;      // 0 = A, 1 = B
+uniform vec2 uVideoSizeA;
+uniform vec2 uVideoSizeB;
+uniform vec2 uCanvasSize;
+uniform float uHasB;
+// geometry
+uniform float uRotate;         // radians
+uniform vec2 uScale;           // 1 = identity
+uniform vec2 uSkew;            // tan(radians)
+uniform vec2 uTranslate;       // fraction of frame
+
+vec2 containUv(vec2 uv, vec2 videoSize, vec2 canvasSize) {
+  float va = videoSize.x / max(videoSize.y, 1.0);
+  float ca = canvasSize.x / max(canvasSize.y, 1.0);
+  vec2 scale = va > ca ? vec2(1.0, ca / va) : vec2(va / ca, 1.0);
+  return (uv - 0.5) / scale + 0.5;
+}
+
+vec4 sampleDeck(sampler2D tex, vec2 videoSize, vec2 uv) {
+  // geometry: translate, then rotate/skew/scale around center
+  vec2 p = uv - 0.5 - uTranslate;
+  float c = cos(-uRotate), s = sin(-uRotate);
+  p = mat2(c, -s, s, c) * p;
+  p = vec2(p.x - uSkew.x * p.y, p.y - uSkew.y * p.x);
+  p /= max(uScale, vec2(0.001));
+  p += 0.5;
+  vec2 cuv = containUv(p, videoSize, uCanvasSize);
+  if (cuv.x < 0.0 || cuv.x > 1.0 || cuv.y < 0.0 || cuv.y > 1.0) return vec4(0.0, 0.0, 0.0, 1.0);
+  // video textures arrive Y-flipped relative to GL
+  return texture(tex, vec2(cuv.x, 1.0 - cuv.y));
+}
+
+void main() {
+  vec4 a = sampleDeck(uTexA, uVideoSizeA, vUv);
+  vec4 b = uHasB > 0.5 ? sampleDeck(uTexB, uVideoSizeB, vUv) : vec4(0.0, 0.0, 0.0, 1.0);
+  outColor = mix(a, b, uCrossfade * uHasB);
+}`;
+
+const FX_FS = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 outColor;
+
+uniform sampler2D uTex;
+uniform vec2 uResolution;
+uniform float uTime;
+uniform float uBeat;           // 0..1 audio energy (0 when reactive off)
+
+uniform float uBrightness;     // 1 = identity
+uniform float uContrast;       // 1 = identity
+uniform float uSaturation;     // 1 = identity
+uniform float uHue;            // radians
+uniform float uGamma;          // 1 = identity
+uniform float uExposure;       // 0 = identity
+uniform float uTemperature;    // -1..1
+uniform float uTint;           // -1..1
+uniform float uGrayscale;      // 0..1
+uniform float uInvert;         // 0..1
+uniform float uSepia;          // 0..1
+uniform float uOpacity;        // 0..1
+uniform float uBlur;           // 0 = identity (uv radius)
+uniform float uSharpen;        // 0..1
+uniform float uPixelate;       // 0 = identity (block count factor)
+uniform float uGlitch;         // 0..1
+uniform float uChroma;         // 0..1
+uniform float uScanlines;      // 0 or 1
+uniform float uNoise;          // 0..1
+uniform float uVignette;       // 0..1
+
+float hash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+}
+
+vec3 sampleBase(vec2 uv) {
+  if (uBlur <= 0.0001) return texture(uTex, uv).rgb;
+  vec2 px = uBlur / uResolution;
+  vec3 acc = vec3(0.0);
+  for (int x = -1; x <= 1; x++)
+    for (int y = -1; y <= 1; y++)
+      acc += texture(uTex, uv + vec2(float(x), float(y)) * px).rgb;
+  return acc / 9.0;
+}
+
+void main() {
+  vec2 uv = vUv;
+
+  // Pixelate
+  if (uPixelate > 0.001) {
+    float blocks = mix(240.0, 8.0, clamp(uPixelate, 0.0, 1.0));
+    vec2 grid = vec2(blocks * uResolution.x / uResolution.y, blocks);
+    uv = (floor(uv * grid) + 0.5) / grid;
+  }
+
+  // Glitch: horizontal slice displacement, time-driven
+  if (uGlitch > 0.001) {
+    float slice = floor(uv.y * 24.0);
+    float jump = hash(vec2(slice, floor(uTime * 12.0)));
+    float amt = step(1.0 - uGlitch * 0.6, jump) * (jump - 0.5) * 0.2 * (1.0 + uBeat);
+    uv.x = fract(uv.x + amt * uGlitch);
+  }
+
+  // Chromatic aberration + base sample
+  vec3 col;
+  if (uChroma > 0.001) {
+    vec2 dir = (uv - 0.5) * uChroma * 0.04 * (1.0 + uBeat * 0.5);
+    col = vec3(sampleBase(uv + dir).r, sampleBase(uv).g, sampleBase(uv - dir).b);
+  } else {
+    col = sampleBase(uv);
+  }
+
+  // Sharpen (unsharp mask)
+  if (uSharpen > 0.001) {
+    vec2 px = 1.0 / uResolution;
+    vec3 blurN = (texture(uTex, uv + vec2(px.x, 0.0)).rgb + texture(uTex, uv - vec2(px.x, 0.0)).rgb +
+                  texture(uTex, uv + vec2(0.0, px.y)).rgb + texture(uTex, uv - vec2(0.0, px.y)).rgb) * 0.25;
+    col += (col - blurN) * uSharpen * 2.0;
+  }
+
+  // Grade: exposure -> temperature/tint -> brightness/contrast -> saturation/hue
+  col *= exp2(uExposure);
+  col.r *= 1.0 + uTemperature * 0.3;
+  col.b *= 1.0 - uTemperature * 0.3;
+  col.g *= 1.0 + uTint * 0.25;
+  col *= uBrightness;
+  col = (col - 0.5) * uContrast + 0.5;
+  col = pow(max(col, 0.0), vec3(1.0 / max(uGamma, 0.01)));
+
+  float luma = dot(col, vec3(0.299, 0.587, 0.114));
+  col = mix(vec3(luma), col, uSaturation);
+
+  if (abs(uHue) > 0.001) {
+    float c = cos(uHue), s = sin(uHue);
+    mat3 hueM = mat3(
+      0.299 + 0.701 * c + 0.168 * s, 0.587 - 0.587 * c + 0.330 * s, 0.114 - 0.114 * c - 0.497 * s,
+      0.299 - 0.299 * c - 0.328 * s, 0.587 + 0.413 * c + 0.035 * s, 0.114 - 0.114 * c + 0.292 * s,
+      0.299 - 0.300 * c + 1.250 * s, 0.587 - 0.588 * c - 1.050 * s, 0.114 + 0.886 * c - 0.203 * s);
+    col = col * hueM;
+  }
+
+  col = mix(col, vec3(luma), uGrayscale);
+  col = mix(col, 1.0 - col, uInvert);
+  vec3 sep = vec3(
+    dot(col, vec3(0.393, 0.769, 0.189)),
+    dot(col, vec3(0.349, 0.686, 0.168)),
+    dot(col, vec3(0.272, 0.534, 0.131)));
+  col = mix(col, sep, uSepia);
+
+  // Noise
+  if (uNoise > 0.001) {
+    col += (hash(vUv * uResolution + fract(uTime) * 1000.0) - 0.5) * uNoise * 0.5;
+  }
+
+  // Vignette
+  if (uVignette > 0.001) {
+    float d = distance(vUv, vec2(0.5));
+    col *= 1.0 - smoothstep(0.35, 0.85, d) * uVignette;
+  }
+
+  // Scanlines
+  if (uScanlines > 0.5) {
+    float line = sin(vUv.y * uResolution.y * 3.14159) * 0.5 + 0.5;
+    col *= mix(0.82, 1.0, line);
+  }
+
+  outColor = vec4(clamp(col, 0.0, 1.0), 1.0) * uOpacity;
+}`;
+
+const FEEDBACK_FS = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 outColor;
+
+uniform sampler2D uCurrent;
+uniform sampler2D uPrevious;
+uniform float uTrails;   // 0..1 persistence
+uniform float uWarp;     // 0..1 zoom/rotate drift
+uniform float uTime;
+
+void main() {
+  vec4 cur = texture(uCurrent, vUv);
+  if (uTrails <= 0.001) { outColor = cur; return; }
+
+  // Warp the history: slight zoom + rotation drift around center
+  vec2 p = vUv - 0.5;
+  float zoom = 1.0 - uWarp * 0.012;
+  float ang = uWarp * 0.01 * sin(uTime * 0.4);
+  float c = cos(ang), s = sin(ang);
+  p = mat2(c, -s, s, c) * p * zoom;
+  vec4 prev = texture(uPrevious, p + 0.5);
+
+  // Decayed max blend: bright trails that die out
+  float keep = 0.55 + uTrails * 0.43;
+  outColor = max(cur, prev * keep);
+}`;
+
+const BLIT_FS = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 outColor;
+uniform sampler2D uTex;
+void main() { outColor = texture(uTex, vUv); }`;
+
+interface Deck {
+  video: HTMLVideoElement | null;
+  texture: WebGLTexture;
+  width: number;
+  height: number;
+}
+
+export class Compositor {
+  private gl: WebGL2RenderingContext;
+  private canvas: HTMLCanvasElement;
+  private quad: WebGLVertexArrayObject;
+  private progMix: WebGLProgram;
+  private progFx: WebGLProgram;
+  private progFeedback: WebGLProgram;
+  private progBlit: WebGLProgram;
+  private targets: Target[] = [];
+  private feedback: [Target, Target] | null = null;
+  private feedbackIndex = 0;
+  private deckA: Deck;
+  private deckB: Deck;
+  private params: EngineParams = { ...IDENTITY_PARAMS };
+  private crossfade = 0;
+  private audio: AudioLevels = { bass: 0, mid: 0, treble: 0 };
+  private audioReactive = false;
+  private raf = 0;
+  private startTime = performance.now();
+  private running = false;
+  private uniformCache = new Map<WebGLProgram, Map<string, WebGLUniformLocation | null>>();
+
+  // Rolling frame-time stats for the host's FPS meter
+  frameCount = 0;
+  lastFrameMs = 0;
+
+  constructor(canvas: HTMLCanvasElement) {
+    this.canvas = canvas;
+    const gl = canvas.getContext('webgl2', {
+      alpha: false,
+      antialias: false,
+      preserveDrawingBuffer: false,
+      powerPreference: 'high-performance',
+    });
+    if (!gl) throw new Error('WebGL2 is not available');
+    this.gl = gl;
+    this.quad = createQuad(gl);
+    this.progMix = createProgram(gl, QUAD_VS, MIX_FS);
+    this.progFx = createProgram(gl, QUAD_VS, FX_FS);
+    this.progFeedback = createProgram(gl, QUAD_VS, FEEDBACK_FS);
+    this.progBlit = createProgram(gl, QUAD_VS, BLIT_FS);
+    this.deckA = { video: null, texture: createVideoTexture(gl), width: 1, height: 1 };
+    this.deckB = { video: null, texture: createVideoTexture(gl), width: 1, height: 1 };
+  }
+
+  setVideoA(video: HTMLVideoElement | null) { this.deckA.video = video; }
+  setVideoB(video: HTMLVideoElement | null) { this.deckB.video = video; }
+  setCrossfade(v: number) { this.crossfade = Math.min(1, Math.max(0, v)); }
+  setParams(p: Partial<EngineParams>) { this.params = { ...this.params, ...p }; }
+  setAudioLevels(levels: AudioLevels, reactive: boolean) {
+    this.audio = levels;
+    this.audioReactive = reactive;
+  }
+
+  start() {
+    if (this.running) return;
+    this.running = true;
+    const loop = () => {
+      if (!this.running) return;
+      const t0 = performance.now();
+      this.renderFrame();
+      this.lastFrameMs = performance.now() - t0;
+      this.frameCount++;
+      this.raf = requestAnimationFrame(loop);
+    };
+    this.raf = requestAnimationFrame(loop);
+  }
+
+  stop() {
+    this.running = false;
+    cancelAnimationFrame(this.raf);
+  }
+
+  destroy() {
+    this.stop();
+    const gl = this.gl;
+    for (const t of this.targets) destroyTarget(gl, t);
+    if (this.feedback) { destroyTarget(gl, this.feedback[0]); destroyTarget(gl, this.feedback[1]); }
+    gl.deleteTexture(this.deckA.texture);
+    gl.deleteTexture(this.deckB.texture);
+    gl.deleteProgram(this.progMix);
+    gl.deleteProgram(this.progFx);
+    gl.deleteProgram(this.progFeedback);
+    gl.deleteProgram(this.progBlit);
+  }
+
+  private u(prog: WebGLProgram, name: string): WebGLUniformLocation | null {
+    let cache = this.uniformCache.get(prog);
+    if (!cache) { cache = new Map(); this.uniformCache.set(prog, cache); }
+    if (!cache.has(name)) cache.set(name, this.gl.getUniformLocation(prog, name));
+    return cache.get(name)!;
+  }
+
+  private uploadDeck(deck: Deck) {
+    const gl = this.gl;
+    const v = deck.video;
+    if (!v || v.readyState < 2 || v.videoWidth === 0) return;
+    gl.bindTexture(gl.TEXTURE_2D, deck.texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, v);
+    deck.width = v.videoWidth;
+    deck.height = v.videoHeight;
+  }
+
+  private ensureTargets(w: number, h: number) {
+    const gl = this.gl;
+    if (this.targets.length && this.targets[0].width === w && this.targets[0].height === h) return;
+    for (const t of this.targets) destroyTarget(gl, t);
+    if (this.feedback) { destroyTarget(gl, this.feedback[0]); destroyTarget(gl, this.feedback[1]); }
+    this.targets = [createTarget(gl, w, h), createTarget(gl, w, h)];
+    this.feedback = [createTarget(gl, w, h), createTarget(gl, w, h)];
+    // clear feedback history
+    for (const t of this.feedback) {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, t.fbo);
+      gl.clearColor(0, 0, 0, 1);
+      gl.clear(gl.COLOR_BUFFER_BIT);
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  private renderFrame() {
+    const gl = this.gl;
+    const canvas = this.canvas;
+
+    // Size canvas to display size (device-pixel aware, capped for perf)
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    const w = Math.max(2, Math.floor(canvas.clientWidth * dpr));
+    const h = Math.max(2, Math.floor(canvas.clientHeight * dpr));
+    if (canvas.width !== w || canvas.height !== h) {
+      canvas.width = w;
+      canvas.height = h;
+    }
+    this.ensureTargets(w, h);
+
+    this.uploadDeck(this.deckA);
+    this.uploadDeck(this.deckB);
+
+    const p = this.params;
+    const time = (performance.now() - this.startTime) / 1000;
+    const beat = this.audioReactive ? Math.min(1, this.audio.bass * 0.7 + this.audio.mid * 0.3) : 0;
+    const [t0, t1] = this.targets;
+
+    gl.bindVertexArray(this.quad);
+    gl.viewport(0, 0, w, h);
+
+    // --- Pass 1: MIX -> t0
+    gl.bindFramebuffer(gl.FRAMEBUFFER, t0.fbo);
+    gl.useProgram(this.progMix);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.deckA.texture);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, this.deckB.texture);
+    gl.uniform1i(this.u(this.progMix, 'uTexA'), 0);
+    gl.uniform1i(this.u(this.progMix, 'uTexB'), 1);
+    gl.uniform1f(this.u(this.progMix, 'uCrossfade'), this.crossfade);
+    gl.uniform2f(this.u(this.progMix, 'uVideoSizeA'), this.deckA.width, this.deckA.height);
+    gl.uniform2f(this.u(this.progMix, 'uVideoSizeB'), this.deckB.width, this.deckB.height);
+    gl.uniform2f(this.u(this.progMix, 'uCanvasSize'), w, h);
+    gl.uniform1f(this.u(this.progMix, 'uHasB'), this.deckB.video ? 1 : 0);
+    gl.uniform1f(this.u(this.progMix, 'uRotate'), (p.rotate * Math.PI) / 180);
+    gl.uniform2f(this.u(this.progMix, 'uScale'), p.scaleX / 100, p.scaleY / 100);
+    gl.uniform2f(this.u(this.progMix, 'uSkew'),
+      Math.tan(((p.skewX || 0) * Math.PI) / 180), Math.tan(((p.skewY || 0) * Math.PI) / 180));
+    gl.uniform2f(this.u(this.progMix, 'uTranslate'), (p.translateX || 0) / 100, -(p.translateY || 0) / 100);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    // --- Pass 2: FX t0 -> t1
+    gl.bindFramebuffer(gl.FRAMEBUFFER, t1.fbo);
+    gl.useProgram(this.progFx);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, t0.tex);
+    gl.uniform1i(this.u(this.progFx, 'uTex'), 0);
+    gl.uniform2f(this.u(this.progFx, 'uResolution'), w, h);
+    gl.uniform1f(this.u(this.progFx, 'uTime'), time);
+    gl.uniform1f(this.u(this.progFx, 'uBeat'), beat);
+    gl.uniform1f(this.u(this.progFx, 'uBrightness'), (p.brightness / 100) * (1 + beat * 0.3));
+    gl.uniform1f(this.u(this.progFx, 'uContrast'), p.contrast / 100);
+    gl.uniform1f(this.u(this.progFx, 'uSaturation'), (p.saturation / 100) * (1 + (this.audioReactive ? this.audio.mid * 0.5 : 0)));
+    gl.uniform1f(this.u(this.progFx, 'uHue'), ((p.hue + (this.audioReactive ? this.audio.treble * 30 : 0)) * Math.PI) / 180);
+    gl.uniform1f(this.u(this.progFx, 'uGamma'), p.gamma);
+    gl.uniform1f(this.u(this.progFx, 'uExposure'), p.exposure);
+    gl.uniform1f(this.u(this.progFx, 'uTemperature'), p.temperature / 100);
+    gl.uniform1f(this.u(this.progFx, 'uTint'), p.tint / 100);
+    gl.uniform1f(this.u(this.progFx, 'uGrayscale'), p.grayscale / 100);
+    gl.uniform1f(this.u(this.progFx, 'uInvert'), p.invert / 100);
+    gl.uniform1f(this.u(this.progFx, 'uSepia'), p.sepia / 100);
+    gl.uniform1f(this.u(this.progFx, 'uOpacity'), p.opacity / 100);
+    gl.uniform1f(this.u(this.progFx, 'uBlur'), p.blur);
+    gl.uniform1f(this.u(this.progFx, 'uSharpen'), p.sharpen / 100);
+    gl.uniform1f(this.u(this.progFx, 'uPixelate'), p.pixelate / 100);
+    gl.uniform1f(this.u(this.progFx, 'uGlitch'), p.glitchIntensity / 100);
+    gl.uniform1f(this.u(this.progFx, 'uChroma'), p.chromaticAberration / 100);
+    gl.uniform1f(this.u(this.progFx, 'uScanlines'), p.scanlines ? 1 : 0);
+    gl.uniform1f(this.u(this.progFx, 'uNoise'), p.noise / 100);
+    gl.uniform1f(this.u(this.progFx, 'uVignette'), p.vignette / 100);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    // --- Pass 3: FEEDBACK t1 + history -> feedback[i], then blit to screen
+    const fb = this.feedback!;
+    const write = fb[this.feedbackIndex];
+    const read = fb[1 - this.feedbackIndex];
+    gl.bindFramebuffer(gl.FRAMEBUFFER, write.fbo);
+    gl.useProgram(this.progFeedback);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, t1.tex);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, read.tex);
+    gl.uniform1i(this.u(this.progFeedback, 'uCurrent'), 0);
+    gl.uniform1i(this.u(this.progFeedback, 'uPrevious'), 1);
+    gl.uniform1f(this.u(this.progFeedback, 'uTrails'), p.trails / 100);
+    gl.uniform1f(this.u(this.progFeedback, 'uWarp'), p.warp / 100);
+    gl.uniform1f(this.u(this.progFeedback, 'uTime'), time);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.useProgram(this.progBlit);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, write.tex);
+    gl.uniform1i(this.u(this.progBlit, 'uTex'), 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    this.feedbackIndex = 1 - this.feedbackIndex;
+  }
+}
diff --git a/client/src/engine/gl.ts b/client/src/engine/gl.ts
new file mode 100644
index 0000000..62f219c
--- /dev/null
+++ b/client/src/engine/gl.ts
@@ -0,0 +1,90 @@
+// Minimal WebGL2 helpers for the compositor. No DOM assumptions beyond
+// the canvas handed to the Compositor.
+
+export function compileShader(gl: WebGL2RenderingContext, type: number, src: string): WebGLShader {
+  const shader = gl.createShader(type)!;
+  gl.shaderSource(shader, src);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader);
+    gl.deleteShader(shader);
+    throw new Error(`Shader compile failed: ${log}\n---\n${src}`);
+  }
+  return shader;
+}
+
+export function createProgram(gl: WebGL2RenderingContext, vsSrc: string, fsSrc: string): WebGLProgram {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vsSrc);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fsSrc);
+  const prog = gl.createProgram()!;
+  gl.attachShader(prog, vs);
+  gl.attachShader(prog, fs);
+  gl.linkProgram(prog);
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
+    const log = gl.getProgramInfoLog(prog);
+    gl.deleteProgram(prog);
+    throw new Error(`Program link failed: ${log}`);
+  }
+  return prog;
+}
+
+export interface Target {
+  fbo: WebGLFramebuffer;
+  tex: WebGLTexture;
+  width: number;
+  height: number;
+}
+
+export function createTarget(gl: WebGL2RenderingContext, width: number, height: number): Target {
+  const tex = gl.createTexture()!;
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  const fbo = gl.createFramebuffer()!;
+  gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+  gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, tex, 0);
+  gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  return { fbo, tex, width, height };
+}
+
+export function destroyTarget(gl: WebGL2RenderingContext, t: Target) {
+  gl.deleteFramebuffer(t.fbo);
+  gl.deleteTexture(t.tex);
+}
+
+export function createVideoTexture(gl: WebGL2RenderingContext): WebGLTexture {
+  const tex = gl.createTexture()!;
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  // 1x1 black placeholder until the first video frame arrives
+  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([0, 0, 0, 255]));
+  return tex;
+}
+
+export const QUAD_VS = `#version 300 es
+layout(location = 0) in vec2 aPos;
+out vec2 vUv;
+void main() {
+  vUv = aPos * 0.5 + 0.5;
+  gl_Position = vec4(aPos, 0.0, 1.0);
+}`;
+
+export function createQuad(gl: WebGL2RenderingContext): WebGLVertexArrayObject {
+  const vao = gl.createVertexArray()!;
+  gl.bindVertexArray(vao);
+  const buf = gl.createBuffer()!;
+  gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+  gl.enableVertexAttribArray(0);
+  gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+  gl.bindVertexArray(null);
+  return vao;
+}
diff --git a/client/src/engine/params.ts b/client/src/engine/params.ts
new file mode 100644
index 0000000..547ae05
--- /dev/null
+++ b/client/src/engine/params.ts
@@ -0,0 +1,82 @@
+// Engine parameter surface. Deliberately mirrors the store's VideoEffects
+// shape (CSS-era percentages/degrees) so existing panels drive the GPU
+// pipeline unchanged; the compositor normalizes internally.
+
+export interface EngineParams {
+  // Color grade
+  brightness: number;   // 100 = identity (%)
+  contrast: number;     // 100 = identity (%)
+  saturation: number;   // 100 = identity (%)
+  hue: number;          // degrees
+  gamma: number;        // 1 = identity
+  exposure: number;     // 0 = identity (stops)
+  temperature: number;  // 0 = identity (-100..100)
+  tint: number;         // 0 = identity (-100..100)
+  grayscale: number;    // 0..100
+  invert: number;       // 0..100
+  sepia: number;        // 0..100
+  opacity: number;      // 0..100
+
+  // Spatial / stylize
+  blur: number;                // px-ish, 0 = identity
+  sharpen: number;             // 0..100
+  pixelate: number;            // 0 = identity, grows blockier
+  glitchIntensity: number;     // 0..100
+  chromaticAberration: number; // 0..100
+  scanlines: boolean;
+  noise: number;               // 0..100
+  vignette: number;            // 0..100
+
+  // Geometry
+  rotate: number;     // degrees
+  scaleX: number;     // 100 = identity (%)
+  scaleY: number;     // 100 = identity (%)
+  skewX: number;      // degrees
+  skewY: number;      // degrees
+  translateX: number; // % of frame
+  translateY: number; // % of frame
+
+  // Temporal (new in the GPU engine — impossible with CSS filters)
+  trails: number;     // 0..100 feedback persistence
+  warp: number;       // 0..100 feedback zoom/rotate drift
+}
+
+export const IDENTITY_PARAMS: EngineParams = {
+  brightness: 100,
+  contrast: 100,
+  saturation: 100,
+  hue: 0,
+  gamma: 1,
+  exposure: 0,
+  temperature: 0,
+  tint: 0,
+  grayscale: 0,
+  invert: 0,
+  sepia: 0,
+  opacity: 100,
+  blur: 0,
+  sharpen: 0,
+  pixelate: 0,
+  glitchIntensity: 0,
+  chromaticAberration: 0,
+  scanlines: false,
+  noise: 0,
+  vignette: 0,
+  rotate: 0,
+  scaleX: 100,
+  scaleY: 100,
+  skewX: 0,
+  skewY: 0,
+  translateX: 0,
+  translateY: 0,
+  trails: 0,
+  warp: 0,
+};
+
+/** Audio analysis levels the host feeds in; the engine maps them to
+ *  subtle grade modulation when audio-reactive mode is on. */
+export interface AudioLevels {
+  bass: number;   // 0..1
+  mid: number;    // 0..1
+  treble: number; // 0..1
+}
diff --git a/client/src/lib/store.ts b/client/src/lib/store.ts
index b59227f..35f580c 100644
--- a/client/src/lib/store.ts
+++ b/client/src/lib/store.ts
@@ -120,6 +120,8 @@ export const useStore = create<AppStore>((set, get) => ({
     vignette: 0,
     sharpen: 0,
     noise: 0,
+    trails: 0,
+    warp: 0,
   },
   audioEffects: {
     gain: 100,
@@ -292,6 +294,8 @@ export const useStore = create<AppStore>((set, get) => ({
       vignette: 0,
       sharpen: 0,
       noise: 0,
+      trails: 0,
+      warp: 0,
       skewX: 0,
       skewY: 0,
       translateX: 0,
diff --git a/client/src/lib/types.ts b/client/src/lib/types.ts
index 41fdade..36a07a2 100644
--- a/client/src/lib/types.ts
+++ b/client/src/lib/types.ts
@@ -66,6 +66,8 @@ export interface VideoEffects {
   vignette: number;
   sharpen: number;
   noise: number;
+  trails: number;
+  warp: number;
   // Geometry effects
   skewX?: number;
   skewY?: number;
diff --git a/client/src/main.tsx b/client/src/main.tsx
index 696e0d2..1ca6a64 100644
--- a/client/src/main.tsx
+++ b/client/src/main.tsx
@@ -2,4 +2,11 @@ import { createRoot } from "react-dom/client";
 import App from "./App";
 import "./index.css";
 
+// Dev-only handle for driving state from the console / automated tests
+if (import.meta.env.DEV) {
+  import('./lib/store').then(({ useStore }) => {
+    (window as any).__store = useStore;
+  });
+}
+
 createRoot(document.getElementById("root")!).render(<App />);

From 57b8cf815174f1bd9d83369d7c25dbdcf45d5dd7 Mon Sep 17 00:00:00 2001
From: "robb.fladry" <robb@fladrycreative.com>
Date: Sun, 19 Jul 2026 21:09:35 -0400
Subject: [PATCH 2/2] feat(phase-1): real GPU crossfades between queue clips
 via deck B
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New engine/deck-transition module: clip advances arm the hidden transition
deck, the compositor mixes A->B on the GPU with an eased audio ramp, then
the program deck silently reloads the incoming clip, aligns to deck B's
clock, and the mix snaps home invisibly — so every Player control keeps
operating on deck A. Per-clip crossfade=true gets a 1.5s mix; even 'hard'
cuts get a 0.35s micro-mix, ending the load-gap flash entirely. Falls back
to a direct load on any media error and cancels cleanly on rapid advances.

Verified live: mid-fade frame shows both clips blending; handback leaves
deck A owning the clip at program volume with deck B released; no console
errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 client/src/components/Player.tsx     |  55 ++++++++++-
 client/src/engine/deck-transition.ts | 135 +++++++++++++++++++++++++++
 2 files changed, 188 insertions(+), 2 deletions(-)
 create mode 100644 client/src/engine/deck-transition.ts

diff --git a/client/src/components/Player.tsx b/client/src/components/Player.tsx
index a05137e..4fc7405 100644
--- a/client/src/components/Player.tsx
+++ b/client/src/components/Player.tsx
@@ -4,6 +4,7 @@ import { Button } from '@/components/ui/button';
 import { Slider } from '@/components/ui/slider';
 import { useStore } from '@/lib/store';
 import { Compositor } from '@/engine/compositor';
+import { runCrossfade, parseTimecode, type TransitionHandle } from '@/engine/deck-transition';
 import { Play, Pause, SkipBack, SkipForward, Volume2, Maximize, Minimize, Scissors } from 'lucide-react';
 import { PopOutPlayer } from '@/components/PopOutPlayer';
 import { videoPreloader } from '@/lib/video-preloader';
@@ -15,6 +16,8 @@ export function Player() {
   const videoRef = useRef<HTMLVideoElement>(null);
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const compositorRef = useRef<Compositor | null>(null);
+  const deckBRef = useRef<HTMLVideoElement>(null);
+  const transitionRef = useRef<TransitionHandle | null>(null);
   const playerContainerRef = useRef<HTMLDivElement>(null);
   const audioContextRef = useRef<AudioContext | null>(null);
   const sourceNodeRef = useRef<MediaElementAudioSourceNode | null>(null);
@@ -77,6 +80,7 @@ export function Player() {
       });
       
       const video = videoRef.current;
+      let isCrossfading = false;
       setIsVideoLoading(true);
       setVideoLoadError(false);
       
@@ -96,6 +100,39 @@ export function Player() {
           setVideoLoadError(true);
           setIsVideoLoading(false);
         }
+      } else if (
+        // GPU crossfade path: only when a previous clip is actually on air
+        (isCrossfading = Boolean(
+          lastLoadedVideoKey !== null &&
+          !video.paused &&
+          video.src &&
+          compositorRef.current &&
+          deckBRef.current
+        ))
+      ) {
+        transitionRef.current?.cancel();
+        const fadeDuration = currentVideo.crossfade ? 1.5 : 0.35;
+        console.log(`🎚️ Crossfading to next clip over ${fadeDuration}s`);
+        transitionRef.current = runCrossfade({
+          deckA: video,
+          deckB: deckBRef.current!,
+          url: currentVideo.videoUrl,
+          startAt: parseTimecode(currentVideo.trimIn),
+          duration: fadeDuration,
+          volume: volume[0] / 100,
+          setCrossfade: (v) => compositorRef.current?.setCrossfade(v),
+          onDone: () => {
+            transitionRef.current = null;
+            setIsVideoLoading(false);
+            setIsPlaying(true);
+          },
+          onError: (err) => {
+            transitionRef.current = null;
+            console.warn('Crossfade fell back to hard cut:', err);
+            setIsVideoLoading(false);
+          },
+        });
+        setIsVideoLoading(false);
       } else {
         // Normal video file handling
         // Check if we have a preloaded video
@@ -218,8 +255,11 @@ export function Player() {
       video.addEventListener('abort', handleAbort);
       video.addEventListener('emptied', handleEmptied);
       
-      // Load the video
-      video.load();
+      // Load the video (skip during a crossfade — deck A must keep playing
+      // the outgoing clip until the transition hands the new one back)
+      if (!isCrossfading) {
+        video.load();
+      }
       
       // Mark this video as loaded
       setLastLoadedVideoKey(currentVideoKey);
@@ -456,10 +496,13 @@ export function Player() {
     if (!canvasRef.current || !videoRef.current) return;
     const compositor = new Compositor(canvasRef.current);
     compositor.setVideoA(videoRef.current);
+    if (deckBRef.current) compositor.setVideoB(deckBRef.current);
     compositor.setParams({ ...useStore.getState().videoEffects, gamma: useStore.getState().videoEffects.gamma / 100 });
     compositor.start();
     compositorRef.current = compositor;
     return () => {
+      transitionRef.current?.cancel();
+      transitionRef.current = null;
       compositorRef.current = null;
       compositor.destroy();
     };
@@ -917,6 +960,14 @@ export function Player() {
           playsInline
           muted={false}
         />
+        {/* Transition deck: hidden video the crossfade engine mixes in */}
+        <video
+          ref={deckBRef}
+          className="absolute inset-0 w-full h-full opacity-0 pointer-events-none"
+          controls={false}
+          preload="auto"
+          playsInline
+        />
         {/* Program output: the WebGL compositor canvas */}
         <canvas
           ref={canvasRef}
diff --git a/client/src/engine/deck-transition.ts b/client/src/engine/deck-transition.ts
new file mode 100644
index 0000000..c60674f
--- /dev/null
+++ b/client/src/engine/deck-transition.ts
@@ -0,0 +1,135 @@
+// Deck-to-deck crossfade: the new clip spins up on the hidden transition
+// deck (B), the compositor mixes A→B on the GPU, then deck A silently
+// re-loads the new clip, aligns to B's clock, and the mix snaps back to A.
+// The program deck (A) therefore always ends up owning the current clip,
+// so every existing Player control keeps working unchanged.
+
+export interface CrossfadeOptions {
+  deckA: HTMLVideoElement;
+  deckB: HTMLVideoElement;
+  url: string;
+  startAt: number;          // seconds into the new clip
+  duration: number;         // fade length in seconds
+  volume: number;           // 0..1 program volume
+  setCrossfade: (v: number) => void;
+  onDone: () => void;
+  onError: (err: unknown) => void;
+}
+
+export interface TransitionHandle {
+  cancel: () => void;
+}
+
+function waitForEvent(el: HTMLVideoElement, event: string, timeoutMs: number, signal: { cancelled: boolean }): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`Timed out waiting for ${event}`));
+    }, timeoutMs);
+    const onEvent = () => { cleanup(); resolve(); };
+    const onErr = () => { cleanup(); reject(new Error(`Media error while waiting for ${event}`)); };
+    const cleanup = () => {
+      clearTimeout(timer);
+      el.removeEventListener(event, onEvent);
+      el.removeEventListener('error', onErr);
+    };
+    if (signal.cancelled) { cleanup(); reject(new Error('cancelled')); return; }
+    el.addEventListener(event, onEvent, { once: true });
+    el.addEventListener('error', onErr, { once: true });
+  });
+}
+
+export function runCrossfade(opts: CrossfadeOptions): TransitionHandle {
+  const signal = { cancelled: false };
+  const { deckA, deckB, url, startAt, duration, volume, setCrossfade } = opts;
+
+  (async () => {
+    // 1. Arm deck B with the incoming clip
+    deckB.crossOrigin = 'anonymous';
+    deckB.preload = 'auto';
+    deckB.muted = false;
+    deckB.volume = 0;
+    deckB.src = url;
+    deckB.load();
+    await waitForEvent(deckB, 'canplay', 10000, signal);
+    if (signal.cancelled) return;
+    if (startAt > 0.05) {
+      deckB.currentTime = startAt;
+      await waitForEvent(deckB, 'seeked', 5000, signal);
+      if (signal.cancelled) return;
+    }
+    await deckB.play();
+    if (signal.cancelled) return;
+
+    // 2. Animate the GPU mix A -> B (with an audio ramp to match)
+    await new Promise<void>((resolve) => {
+      const t0 = performance.now();
+      const tick = () => {
+        if (signal.cancelled) { resolve(); return; }
+        const t = Math.min(1, (performance.now() - t0) / (duration * 1000));
+        // smoothstep for an eased mix
+        const s = t * t * (3 - 2 * t);
+        setCrossfade(s);
+        deckB.volume = s * volume;
+        deckA.volume = (1 - s) * volume;
+        if (t < 1) requestAnimationFrame(tick);
+        else resolve();
+      };
+      requestAnimationFrame(tick);
+    });
+    if (signal.cancelled) return;
+
+    // 3. Hand the clip back to the program deck: load the same URL on A,
+    //    align to B's clock, then snap the mix home. Both decks show the
+    //    same content at the same time, so the snap is invisible.
+    deckA.muted = true;
+    deckA.src = url;
+    deckA.load();
+    await waitForEvent(deckA, 'canplay', 10000, signal);
+    if (signal.cancelled) return;
+    deckA.currentTime = deckB.currentTime + 0.05;
+    await waitForEvent(deckA, 'seeked', 5000, signal);
+    if (signal.cancelled) return;
+    await deckA.play();
+    if (signal.cancelled) return;
+
+    setCrossfade(0);
+    deckA.muted = false;
+    deckA.volume = volume;
+    deckB.pause();
+    deckB.removeAttribute('src');
+    deckB.load();
+    opts.onDone();
+  })().catch((err) => {
+    if (signal.cancelled) return;
+    // Fallback: hard-load the clip on the program deck so playback never dies
+    setCrossfade(0);
+    deckB.pause();
+    deckA.muted = false;
+    deckA.volume = volume;
+    if (!deckA.src.includes(url)) {
+      deckA.src = url;
+      deckA.load();
+      deckA.play().catch(() => {});
+    }
+    opts.onError(err);
+  });
+
+  return {
+    cancel: () => {
+      signal.cancelled = true;
+      setCrossfade(0);
+      deckB.pause();
+    },
+  };
+}
+
+/** Parse "MM:SS" / "HH:MM:SS" / plain seconds into seconds. */
+export function parseTimecode(tc: string | undefined): number {
+  if (!tc) return 0;
+  const parts = tc.split(':').map(Number);
+  if (parts.some(isNaN)) return 0;
+  if (parts.length === 3) return parts[0] * 3600 + parts[1] * 60 + parts[2];
+  if (parts.length === 2) return parts[0] * 60 + parts[1];
+  return parts[0] || 0;
+}