From f1125eadddebfaa3612d124d5b27db3ff70d8079 Mon Sep 17 00:00:00 2001
From: smirk-dev <suryansh.mishra.sm6@gmail.com>
Date: Sun, 7 Jun 2026 09:59:45 +0530
Subject: [PATCH] feat: add canvas-based live preview for editor
 transformations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirror the source <video> onto a <canvas> via a single requestAnimationFrame
loop so crop/framing, rotation and brightness/contrast/saturation changes are
reflected instantly, without running a full FFmpeg export. The export pipeline
is untouched — the canvas is preview-only.

- src/lib/previewGeometry.ts: pure, unit-tested geometry/colour helpers that
  mirror buildVideoFilter (rotate -> fit/fill scale+pad/crop -> eq colour).
- src/hooks/useCanvasPreview.ts: rAF render loop; recipe read via ref (no
  per-change re-subscribe), container size cached via ResizeObserver (no layout
  thrash), DPR-aware buffer, ctx.filter for colour with CSS-filter fallback.
- src/components/VideoPreview.tsx: render the canvas as the live preview with a
  Live toggle and click/space play-pause; native <video> retained as the frame
  source. Grouped the overlay control buttons into flex rows.

Refs #653

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/components/VideoPreview.tsx           | 228 +++++++++++++++-------
 src/hooks/useCanvasPreview.ts             | 188 ++++++++++++++++++
 src/lib/__tests__/previewGeometry.test.ts |  88 +++++++++
 src/lib/previewGeometry.ts                |  99 ++++++++++
 4 files changed, 537 insertions(+), 66 deletions(-)
 create mode 100644 src/hooks/useCanvasPreview.ts
 create mode 100644 src/lib/__tests__/previewGeometry.test.ts
 create mode 100644 src/lib/previewGeometry.ts

diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index b985f5cf..e8b6e111 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -5,9 +5,10 @@ import { useEffect, useRef, useState, useCallback, RefObject } from "react";
 import { EditRecipe, TextOverlay, TimelineTrack, MultiTrackEditorState } from "@/lib/types";
 import { getPresetById } from "@/lib/presets";
 import { cn } from "@/lib/utils";
-import { Camera } from "lucide-react";
+import { Camera, Play } from "lucide-react";
 import ComparisonPreview from "./ComparisonPreview";
 import DraggableTextOverlays from "./DraggableTextOverlays";
+import { useCanvasPreview } from "@/hooks/useCanvasPreview";
 
 interface Props {
   file: File | null;
@@ -37,12 +38,25 @@ export default function VideoPreview({
   const [showOverlay, setShowOverlay] = useState(false);
   const [showComparison, setShowComparison] = useState(false);
   const [showGridOverlay, setShowGridOverlay] = useState(false);
+  const [livePreview, setLivePreview] = useState(true);
+  const [isPaused, setIsPaused] = useState(false);
   const [containerDimensions, setContainerDimensions] = useState({
     width: 0,
     height: 0,
   });
   const previewContainerRef = useRef<HTMLDivElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
   const onLoadedRef = useRef<(() => void) | null>(null);
+
+  // Canvas live preview: mirror the video frame with rotation/framing/colour
+  // applied so edits show instantly. Export stays FFmpeg-based (preview only).
+  useCanvasPreview({
+    videoRef,
+    canvasRef,
+    containerRef: previewContainerRef,
+    recipe,
+    enabled: livePreview,
+  });
   
   // Phase 1 MVP: Multi-track URL management
   const multiTrackUrlRefs = useRef<Record<string, string | null>>({});
@@ -167,6 +181,31 @@ export default function VideoPreview({
     videoRef.current.playbackRate = recipe.speed;
   }, [recipe, videoRef]);
 
+  // Track play/pause so the live-preview overlay can show a play affordance
+  // (the native <video> controls are hidden while the canvas preview is active).
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video) return;
+    const sync = () => setIsPaused(video.paused);
+    sync();
+    video.addEventListener("play", sync);
+    video.addEventListener("pause", sync);
+    return () => {
+      video.removeEventListener("play", sync);
+      video.removeEventListener("pause", sync);
+    };
+  }, [videoRef, file]);
+
+  const togglePlayback = useCallback(() => {
+    const video = videoRef.current;
+    if (!video) return;
+    if (video.paused) {
+      video.play().catch(() => {});
+    } else {
+      video.pause();
+    }
+  }, [videoRef]);
+
   /**
    * Track preview container dimensions for text overlay positioning.
    */
@@ -274,8 +313,15 @@ export default function VideoPreview({
         {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
         <video
           ref={videoRef}
-          controls
-          className={cn("w-full h-full object-contain transition-opacity duration-300", isLoading ? "opacity-0" : "opacity-100")}
+          controls={!(livePreview && !!recipe)}
+          className={cn(
+            "w-full h-full object-contain transition-opacity duration-300",
+            // While the canvas preview is active the raw <video> is the frame
+            // source only — keep it in the DOM/playing but visually hidden so we
+            // don't show the un-transformed frame underneath the canvas.
+            isLoading || (livePreview && recipe) ? "opacity-0" : "opacity-100",
+            livePreview && recipe && "pointer-events-none"
+          )}
           onLoadedData={() => setIsLoading(false)}
           playsInline
           muted={!recipe?.keepAudio}
@@ -283,6 +329,30 @@ export default function VideoPreview({
           <track kind="captions" />
         </video>
 
+        {/* Canvas live preview — mirrors the frame with rotation/framing/colour */}
+        {livePreview && !isLoading && recipe && (
+          <canvas
+            ref={canvasRef}
+            onClick={togglePlayback}
+            className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 cursor-pointer"
+            role="img"
+            aria-label="Live preview of crop, rotation and colour edits"
+          />
+        )}
+
+        {/* Play affordance when paused in live-preview mode */}
+        {livePreview && !isLoading && isPaused && (
+          <button
+            type="button"
+            onClick={togglePlayback}
+            className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 z-10 grid place-items-center w-14 h-14 rounded-full bg-black/55 text-white pointer-events-auto hover:bg-black/70 transition-colors"
+            aria-label="Play video"
+            title="Play"
+          >
+            <Play className="w-6 h-6 translate-x-[1px]" fill="currentColor" />
+          </button>
+        )}
+
         {/* Phase 1 MVP: Multi-track overlay rendering */}
         {multiTrackState && multiTrackVideoRefs && multiTrackState.timelineTracks.length > 1 && (
           <div className="absolute inset-0 pointer-events-none" role="region" aria-label="Multi-track overlay layers">
@@ -320,8 +390,9 @@ export default function VideoPreview({
           </div>
         )}
 
-        {/* Letterbox / Crop overlay */}
-        {overlay && (
+        {/* Letterbox / Crop overlay — redundant while the canvas preview already
+            renders the true framing, so only show it for the raw <video>. */}
+        {overlay && !livePreview && (
           <div className="absolute inset-0 pointer-events-none" aria-hidden="true">
             {overlay.mode === "fit" ? (
               // Letterbox: semi-transparent bars outside the content area
@@ -376,72 +447,97 @@ export default function VideoPreview({
           />
         )}
 
-        {/* Toggle button */}
-        {recipe && !isLoading && (
-          <button
-            type="button"
-            onClick={() => setShowOverlay((v) => !v)}
-            className={`absolute top-2 left-2 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-10 pointer-events-auto ${
-              showOverlay
-                ? "bg-[var(--accent)] text-white"
-                : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
-            }`}
-            aria-pressed={showOverlay}
-            aria-label={showOverlay ? "Hide framing overlay" : "Show framing overlay"}
-            title={showOverlay ? "Hide framing overlay" : "Show framing overlay"}
-          >
-            {showOverlay ? "Hide overlay" : "Show overlay"}
-          </button>
-        )}
-
-        {/* Grid overlay button */}
+        {/* Top-left controls */}
         {recipe && !isLoading && (
-          <button
-            type="button"
-            onClick={() => setShowGridOverlay((v) => !v)}
-            className={`absolute top-2 left-32 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-10 pointer-events-auto ${
-              showGridOverlay
-                ? "bg-[var(--accent)] text-white"
-                : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
-            }`}
-            aria-pressed={showGridOverlay}
-            aria-label={showGridOverlay ? "Hide grid overlay" : "Show grid overlay"}
-            title={showGridOverlay ? "Hide grid overlay" : "Show grid overlay"}
-          >
-            {showGridOverlay ? "Hide grid" : "Show grid"}
-          </button>
-        )}
+          <div className="absolute top-2 left-2 flex flex-wrap gap-2 z-10">
+            {/* Live preview toggle */}
+            <button
+              type="button"
+              onClick={() => setLivePreview((v) => !v)}
+              className={`px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors pointer-events-auto ${
+                livePreview
+                  ? "bg-[var(--accent)] text-white"
+                  : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
+              }`}
+              aria-pressed={livePreview}
+              aria-label={livePreview ? "Disable live preview" : "Enable live preview"}
+              title={
+                livePreview
+                  ? "Live preview on — edits render on the canvas instantly"
+                  : "Live preview off — showing the raw player"
+              }
+            >
+              {livePreview ? "Live: on" : "Live: off"}
+            </button>
+
+            {/* Framing overlay — only useful against the raw <video> */}
+            {!livePreview && (
+              <button
+                type="button"
+                onClick={() => setShowOverlay((v) => !v)}
+                className={`px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors pointer-events-auto ${
+                  showOverlay
+                    ? "bg-[var(--accent)] text-white"
+                    : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
+                }`}
+                aria-pressed={showOverlay}
+                aria-label={showOverlay ? "Hide framing overlay" : "Show framing overlay"}
+                title={showOverlay ? "Hide framing overlay" : "Show framing overlay"}
+              >
+                {showOverlay ? "Hide overlay" : "Show overlay"}
+              </button>
+            )}
 
-        {/* Compare button */}
-        {recipe && !isLoading && (
-          <button
-            type="button"
-            onClick={() => setShowComparison((v) => !v)}
-            className={`absolute top-2 right-32 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-10 pointer-events-auto ${
-              showComparison
-                ? "bg-[var(--accent)] text-white"
-                : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
-            }`}
-            aria-pressed={showComparison}
-            aria-label={showComparison ? "Hide comparison preview" : "Show comparison preview"}
-            title={showComparison ? "Hide comparison preview" : "Show comparison preview"}
-          >
-            Compare
-          </button>
+            {/* Grid overlay button */}
+            <button
+              type="button"
+              onClick={() => setShowGridOverlay((v) => !v)}
+              className={`px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors pointer-events-auto ${
+                showGridOverlay
+                  ? "bg-[var(--accent)] text-white"
+                  : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
+              }`}
+              aria-pressed={showGridOverlay}
+              aria-label={showGridOverlay ? "Hide grid overlay" : "Show grid overlay"}
+              title={showGridOverlay ? "Hide grid overlay" : "Show grid overlay"}
+            >
+              {showGridOverlay ? "Hide grid" : "Show grid"}
+            </button>
+          </div>
         )}
 
-        {/* Grab frame button */}
+        {/* Top-right controls */}
         {!isLoading && (
-          <button
-            type="button"
-            onClick={handleGrabFrame}
-            className="absolute top-2 right-2 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-10 pointer-events-auto bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)] flex items-center gap-1"
-            aria-label="Grab frame as PNG"
-            title="Download current frame as PNG"
-          >
-            <Camera className="w-3 h-3" />
-            Grab frame
-          </button>
+          <div className="absolute top-2 right-2 flex flex-wrap gap-2 z-10">
+            {recipe && (
+              <button
+                type="button"
+                onClick={() => setShowComparison((v) => !v)}
+                className={`px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors pointer-events-auto ${
+                  showComparison
+                    ? "bg-[var(--accent)] text-white"
+                    : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
+                }`}
+                aria-pressed={showComparison}
+                aria-label={showComparison ? "Hide comparison preview" : "Show comparison preview"}
+                title={showComparison ? "Hide comparison preview" : "Show comparison preview"}
+              >
+                Compare
+              </button>
+            )}
+
+            {/* Grab frame button */}
+            <button
+              type="button"
+              onClick={handleGrabFrame}
+              className="px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors pointer-events-auto bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)] flex items-center gap-1"
+              aria-label="Grab frame as PNG"
+              title="Download current frame as PNG"
+            >
+              <Camera className="w-3 h-3" />
+              Grab frame
+            </button>
+          </div>
         )}
       </div>
 
diff --git a/src/hooks/useCanvasPreview.ts b/src/hooks/useCanvasPreview.ts
new file mode 100644
index 00000000..a7877166
--- /dev/null
+++ b/src/hooks/useCanvasPreview.ts
@@ -0,0 +1,188 @@
+"use client";
+
+import { RefObject, useEffect, useRef } from "react";
+import { EditRecipe } from "@/lib/types";
+import { getPresetById } from "@/lib/presets";
+import {
+  colorFilterString,
+  fitContain,
+  frameScale,
+  rotatedSize,
+  rotationRadians,
+} from "@/lib/previewGeometry";
+
+interface Params {
+  /** Source `<video>` whose current frame is mirrored onto the canvas. */
+  videoRef: RefObject<HTMLVideoElement | null>;
+  /** Target `<canvas>` the preview is drawn into. */
+  canvasRef: RefObject<HTMLCanvasElement | null>;
+  /** Element used to measure the available preview area. */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Current edit recipe (crop/rotation/colour). */
+  recipe?: EditRecipe;
+  /** When false the loop is torn down and no frames are drawn. */
+  enabled: boolean;
+}
+
+function outputSize(recipe: EditRecipe): { width: number; height: number } | null {
+  if (recipe.preset === "custom") {
+    return { width: recipe.customWidth, height: recipe.customHeight };
+  }
+  const preset = getPresetById(recipe.preset);
+  return preset ? { width: preset.width, height: preset.height } : null;
+}
+
+/**
+ * Drives a single `requestAnimationFrame` loop that mirrors the source video
+ * onto a canvas, applying rotation, fit/fill framing and colour adjustments so
+ * the user sees crop/rotation/colour changes instantly — without an FFmpeg
+ * export. The export pipeline is untouched; this is preview-only.
+ *
+ * Performance notes:
+ * - One rAF loop per instance, started/stopped with `enabled`. No timers.
+ * - The recipe is read through a ref so slider changes never re-create the loop.
+ * - Container size is cached via `ResizeObserver`; layout is only read on resize,
+ *   not per frame, avoiding layout thrash.
+ * - Colour is applied through `ctx.filter` where supported (so letterbox bars
+ *   stay pure black, matching the export's padding) and falls back to a CSS
+ *   `filter` on the canvas element otherwise.
+ */
+export function useCanvasPreview({
+  videoRef,
+  canvasRef,
+  containerRef,
+  recipe,
+  enabled,
+}: Params) {
+  // Latest recipe accessed by the loop without resubscribing on every change.
+  const recipeRef = useRef(recipe);
+  recipeRef.current = recipe;
+
+  // Cached container measurement, refreshed only on resize.
+  const sizeRef = useRef({ width: 0, height: 0 });
+  // Cached `ctx.filter` support detection (null = not yet probed).
+  const supportsCtxFilterRef = useRef<boolean | null>(null);
+  // Last CSS filter written to the element, to skip redundant style writes.
+  const cssFilterRef = useRef<string>("none");
+
+  // Measure the container and keep it current across resizes.
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const measure = () => {
+      const rect = el.getBoundingClientRect();
+      sizeRef.current = { width: rect.width, height: rect.height };
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [containerRef]);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+
+    if (!enabled) {
+      // Drop any element-level filter we may have applied while active.
+      if (canvas && cssFilterRef.current !== "none") {
+        canvas.style.filter = "none";
+        cssFilterRef.current = "none";
+      }
+      return;
+    }
+
+    let raf = 0;
+
+    const render = () => {
+      raf = requestAnimationFrame(render);
+
+      const video = videoRef.current;
+      const canvasEl = canvasRef.current;
+      const currentRecipe = recipeRef.current;
+      if (!video || !canvasEl || !currentRecipe) return;
+      if (video.readyState < 2 || !video.videoWidth || !video.videoHeight) return;
+
+      const { width: cw, height: ch } = sizeRef.current;
+      if (cw <= 0 || ch <= 0) return;
+
+      const output = outputSize(currentRecipe);
+      if (!output || output.width <= 0 || output.height <= 0) return;
+
+      // Output frame (preset aspect ratio) letterboxed inside the container.
+      const display = fitContain(cw, ch, output.width, output.height);
+      if (display.width <= 0 || display.height <= 0) return;
+
+      const dpr = window.devicePixelRatio || 1;
+      const bufW = Math.max(1, Math.round(display.width * dpr));
+      const bufH = Math.max(1, Math.round(display.height * dpr));
+
+      if (canvasEl.width !== bufW || canvasEl.height !== bufH) {
+        canvasEl.width = bufW;
+        canvasEl.height = bufH;
+      }
+      const cssW = `${display.width}px`;
+      const cssH = `${display.height}px`;
+      if (canvasEl.style.width !== cssW) canvasEl.style.width = cssW;
+      if (canvasEl.style.height !== cssH) canvasEl.style.height = cssH;
+
+      const ctx = canvasEl.getContext("2d");
+      if (!ctx) return;
+
+      if (supportsCtxFilterRef.current === null) {
+        supportsCtxFilterRef.current = typeof ctx.filter === "string";
+      }
+
+      const filter = colorFilterString(
+        currentRecipe.brightness,
+        currentRecipe.contrast,
+        currentRecipe.saturation
+      );
+
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.filter = "none";
+      ctx.clearRect(0, 0, bufW, bufH);
+      // Black backdrop = letterbox pad (fit) / crop matte (fill), like the export.
+      ctx.fillStyle = "#000";
+      ctx.fillRect(0, 0, bufW, bufH);
+
+      // Apply colour to the video pixels only.
+      if (supportsCtxFilterRef.current) {
+        ctx.filter = filter;
+        if (cssFilterRef.current !== "none") {
+          canvasEl.style.filter = "none";
+          cssFilterRef.current = "none";
+        }
+      } else if (cssFilterRef.current !== filter) {
+        // Fallback: filter the whole element (also tints letterbox bars).
+        canvasEl.style.filter = filter;
+        cssFilterRef.current = filter;
+      }
+
+      const rotated = rotatedSize(
+        video.videoWidth,
+        video.videoHeight,
+        currentRecipe.rotate
+      );
+      const scale = frameScale(
+        rotated.width,
+        rotated.height,
+        bufW,
+        bufH,
+        currentRecipe.framing
+      );
+
+      ctx.translate(bufW / 2, bufH / 2);
+      if (currentRecipe.rotate !== 0) {
+        ctx.rotate(rotationRadians(currentRecipe.rotate));
+      }
+      const drawW = video.videoWidth * scale;
+      const drawH = video.videoHeight * scale;
+      // Draw the un-rotated frame centred; the canvas transform handles rotation
+      // and anything past the buffer edges is clipped automatically (fill crop).
+      ctx.drawImage(video, -drawW / 2, -drawH / 2, drawW, drawH);
+    };
+
+    raf = requestAnimationFrame(render);
+    return () => cancelAnimationFrame(raf);
+  }, [enabled, videoRef, canvasRef]);
+}
diff --git a/src/lib/__tests__/previewGeometry.test.ts b/src/lib/__tests__/previewGeometry.test.ts
new file mode 100644
index 00000000..562b0cd6
--- /dev/null
+++ b/src/lib/__tests__/previewGeometry.test.ts
@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import {
+  colorFilterString,
+  fitContain,
+  frameScale,
+  rotatedSize,
+  rotationRadians,
+} from "../previewGeometry";
+
+describe("rotatedSize", () => {
+  it("leaves dimensions unchanged for 0 and 180", () => {
+    expect(rotatedSize(1920, 1080, 0)).toEqual({ width: 1920, height: 1080 });
+    expect(rotatedSize(1920, 1080, 180)).toEqual({ width: 1920, height: 1080 });
+  });
+
+  it("swaps axes for 90 and 270", () => {
+    expect(rotatedSize(1920, 1080, 90)).toEqual({ width: 1080, height: 1920 });
+    expect(rotatedSize(1920, 1080, 270)).toEqual({ width: 1080, height: 1920 });
+  });
+});
+
+describe("rotationRadians", () => {
+  it("converts degrees to radians (clockwise)", () => {
+    expect(rotationRadians(0)).toBe(0);
+    expect(rotationRadians(90)).toBeCloseTo(Math.PI / 2);
+    expect(rotationRadians(180)).toBeCloseTo(Math.PI);
+    expect(rotationRadians(270)).toBeCloseTo((3 * Math.PI) / 2);
+  });
+});
+
+describe("fitContain", () => {
+  it("pillarboxes a wide target inside a square container (full width)", () => {
+    // 2:1 target in a 100x100 box → width 100, height 50.
+    expect(fitContain(100, 100, 2, 1)).toEqual({ width: 100, height: 50 });
+  });
+
+  it("letterboxes a tall target inside a wide container (full height)", () => {
+    // 1:2 target in a 160x90 box → height 90, width 45.
+    expect(fitContain(160, 90, 1, 2)).toEqual({ width: 45, height: 90 });
+  });
+
+  it("returns the container when aspect ratios match", () => {
+    expect(fitContain(160, 90, 16, 9)).toEqual({ width: 160, height: 90 });
+  });
+
+  it("guards against zero/negative inputs", () => {
+    expect(fitContain(0, 100, 16, 9)).toEqual({ width: 0, height: 0 });
+    expect(fitContain(100, 100, 0, 9)).toEqual({ width: 0, height: 0 });
+  });
+});
+
+describe("frameScale", () => {
+  it("fit shrinks to the smaller axis (letterbox)", () => {
+    // 200x100 source into 100x100 output → min(0.5, 1) = 0.5.
+    expect(frameScale(200, 100, 100, 100, "fit")).toBe(0.5);
+  });
+
+  it("fill grows to the larger axis (crop)", () => {
+    // 200x100 source into 100x100 output → max(0.5, 1) = 1.
+    expect(frameScale(200, 100, 100, 100, "fill")).toBe(1);
+  });
+
+  it("returns 0 for a degenerate source", () => {
+    expect(frameScale(0, 100, 100, 100, "fit")).toBe(0);
+  });
+});
+
+describe("colorFilterString", () => {
+  it("returns 'none' at default values", () => {
+    expect(colorFilterString(0, 1, 1)).toBe("none");
+  });
+
+  it("maps additive brightness to a CSS multiplier (1 + b)", () => {
+    expect(colorFilterString(0.5, 1, 1)).toBe("brightness(1.500)");
+    expect(colorFilterString(-0.5, 1, 1)).toBe("brightness(0.500)");
+  });
+
+  it("passes contrast and saturation through unchanged", () => {
+    expect(colorFilterString(0, 1.4, 1)).toBe("contrast(1.400)");
+    expect(colorFilterString(0, 1, 2)).toBe("saturate(2.000)");
+  });
+
+  it("combines all active channels in order", () => {
+    expect(colorFilterString(0.2, 1.3, 0.8)).toBe(
+      "brightness(1.200) contrast(1.300) saturate(0.800)"
+    );
+  });
+});
diff --git a/src/lib/previewGeometry.ts b/src/lib/previewGeometry.ts
new file mode 100644
index 00000000..e17af0b0
--- /dev/null
+++ b/src/lib/previewGeometry.ts
@@ -0,0 +1,99 @@
+/**
+ * Pure geometry + color helpers shared by the canvas live preview
+ * (`useCanvasPreview`). These mirror the transformations the FFmpeg export
+ * pipeline applies in `buildVideoFilter` — rotation (transpose) → fit/fill
+ * scale + pad/crop → eq colour — so the preview reflects the final output
+ * without running an export.
+ *
+ * Everything here is framework-agnostic and side-effect free so it can be
+ * unit tested in isolation.
+ */
+
+export type Rotation = 0 | 90 | 180 | 270;
+
+export type Framing = "fit" | "fill";
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * Source dimensions after applying a 90/270° rotation (which swaps the axes).
+ * 0/180° leave the dimensions unchanged.
+ */
+export function rotatedSize(width: number, height: number, rotate: Rotation): Size {
+  return rotate === 90 || rotate === 270
+    ? { width: height, height: width }
+    : { width, height };
+}
+
+/** Rotation in radians, clockwise — matches FFmpeg `transpose` orientation. */
+export function rotationRadians(rotate: Rotation): number {
+  return (rotate * Math.PI) / 180;
+}
+
+/**
+ * Largest rectangle with aspect ratio `arW:arH` that fits entirely inside a
+ * `containerW × containerH` box (CSS `object-fit: contain`). Used to letterbox
+ * the output frame — whose aspect ratio is the selected preset — inside the
+ * fixed 16:9 preview container.
+ */
+export function fitContain(
+  containerW: number,
+  containerH: number,
+  arW: number,
+  arH: number
+): Size {
+  if (arW <= 0 || arH <= 0 || containerW <= 0 || containerH <= 0) {
+    return { width: 0, height: 0 };
+  }
+  const targetAr = arW / arH;
+  const containerAr = containerW / containerH;
+  if (targetAr > containerAr) {
+    // Wider than the container → full width, pillarbox top/bottom.
+    return { width: containerW, height: containerW / targetAr };
+  }
+  // Taller than the container → full height, letterbox left/right.
+  return { width: containerH * targetAr, height: containerH };
+}
+
+/**
+ * Scale factor for drawing a `srcW × srcH` frame into an `outW × outH` output
+ * region. `fit` shrinks the frame so it is fully visible (letterbox bars);
+ * `fill` enlarges it so it covers the region (cropping the overflow). Mirrors
+ * FFmpeg's `force_original_aspect_ratio=decrease`+`pad` vs `increase`+`crop`.
+ */
+export function frameScale(
+  srcW: number,
+  srcH: number,
+  outW: number,
+  outH: number,
+  framing: Framing
+): number {
+  if (srcW <= 0 || srcH <= 0) return 0;
+  const sx = outW / srcW;
+  const sy = outH / srcH;
+  return framing === "fit" ? Math.min(sx, sy) : Math.max(sx, sy);
+}
+
+/**
+ * CSS/canvas `filter` string approximating FFmpeg's `eq` colour adjustments.
+ * Returns `"none"` when every channel is at its default so callers can skip
+ * compositing work.
+ *
+ * Mapping: FFmpeg `brightness` is additive in [-1, 1]; CSS `brightness()` is a
+ * multiplier centred on 1, so we map `b → 1 + b`. `contrast` and `saturation`
+ * are already multipliers centred on 1 in both systems and pass through 1:1.
+ */
+export function colorFilterString(
+  brightness: number,
+  contrast: number,
+  saturation: number
+): string {
+  const parts: string[] = [];
+  if (brightness !== 0) parts.push(`brightness(${(1 + brightness).toFixed(3)})`);
+  if (contrast !== 1) parts.push(`contrast(${contrast.toFixed(3)})`);
+  if (saturation !== 1) parts.push(`saturate(${saturation.toFixed(3)})`);
+  return parts.length > 0 ? parts.join(" ") : "none";
+}