From d4e03363b320179df2003e8e70333159567eec02 Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 14:49:58 +0530
Subject: [PATCH 1/8] implemented : rotation preview and aspect ratio preview

---
 src/components/VideoPreview.tsx | 30 ++++++++++++------------------
 1 file changed, 12 insertions(+), 18 deletions(-)

diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index 7456ac89..b96c45c8 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -144,43 +144,35 @@ export default function VideoPreview({
     return () => window.removeEventListener("resize", updateDimensions);
   }, []);
 
-  const overlay = (() => {
-    if (!recipe || !showOverlay) return null;
+  const preset = recipe?.preset === "custom"
+    ? { width: recipe.customWidth, height: recipe.customHeight }
+    : recipe ? getPresetById(recipe.preset) : null;
 
-    const preset = recipe.preset === "custom"
-      ? { width: recipe.customWidth, height: recipe.customHeight }
-      : getPresetById(recipe.preset);
+  const targetRatio = preset ? preset.width / preset.height : 16 / 9;
 
-    if (!preset) return null;
+  const overlay = (() => {
+    if (!recipe || !showOverlay || !preset) return null;
 
-    // Preview container is 16:9
-    const containerW = 16;
-    const containerH = 9;
-    const containerRatio = containerW / containerH;   // 1.777…
+    // Use the dynamic target ratio instead of hardcoded 16:9
+    const containerRatio = targetRatio;
     const outputRatio = preset.width / preset.height;
 
     if (recipe.framing === "fit") {
-      // Letterbox: the output video fits entirely inside 16:9, padded with bars.
       if (outputRatio > containerRatio) {
-        // Wider output → pillarbox bars on top & bottom
         const contentH = (containerRatio / outputRatio) * 100;
         const barH = (100 - contentH) / 2;
         return { mode: "fit", barTop: `${barH}%`, barBottom: `${barH}%`, barLeft: "0", barRight: "0" };
       } else {
-        // Taller output → letterbox bars on left & right
         const contentW = (outputRatio / containerRatio) * 100;
         const barW = (100 - contentW) / 2;
         return { mode: "fit", barTop: "0", barBottom: "0", barLeft: `${barW}%`, barRight: `${barW}%` };
       }
     } else {
-      // Fill / crop: the output fills the entire 16:9 preview — show a box representing what survives the crop.
       if (outputRatio < containerRatio) {
-        // Output is taller → crops top & bottom
         const visibleH = (outputRatio / containerRatio) * 100;
         const cropH = (100 - visibleH) / 2;
         return { mode: "fill", barTop: `${cropH}%`, barBottom: `${cropH}%`, barLeft: "0", barRight: "0" };
       } else {
-        // Output is wider → crops left & right
         const visibleW = (containerRatio / outputRatio) * 100;
         const cropW = (100 - visibleW) / 2;
         return { mode: "fill", barTop: "0", barBottom: "0", barLeft: `${cropW}%`, barRight: `${cropW}%` };
@@ -218,7 +210,8 @@ export default function VideoPreview({
       <div
         ref={previewContainerRef}
         role="group"
-        className="relative w-full rounded-lg overflow-hidden bg-[var(--bg)] aspect-video focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)]"
+        className="relative w-full rounded-lg overflow-hidden bg-[var(--bg)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)] transition-all duration-300"
+        style={{ aspectRatio: targetRatio }}
         tabIndex={0}
         onKeyDown={handleKeyDown}
         aria-label="Video preview (press Space to play/pause)"
@@ -233,7 +226,8 @@ export default function VideoPreview({
         <video
           ref={videoRef}
           controls
-          className={cn("w-full h-full object-contain transition-opacity duration-300", isLoading ? "opacity-0" : "opacity-100")}
+          className={cn("w-full h-full object-contain transition-all duration-300", isLoading ? "opacity-0" : "opacity-100")}
+          style={{ transform: `rotate(${recipe?.rotate || 0}deg)` }}
           onLoadedData={() => setIsLoading(false)}
           playsInline
           muted={!recipe?.keepAudio}

From d0a565fc6a06ad263e6a8fa9e7c569bccc4d8952 Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 14:59:31 +0530
Subject: [PATCH 2/8] implemented : trim preview

---
 src/components/VideoPreview.tsx | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index b96c45c8..ff25ed12 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -144,6 +144,29 @@ export default function VideoPreview({
     return () => window.removeEventListener("resize", updateDimensions);
   }, []);
 
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !recipe) return;
+
+    const handleTimeUpdate = () => {
+      // If duration is not yet available, fallback to a safe large number to prevent immediate stops
+      const start = recipe.trimStart || 0;
+      const end = recipe.trimEnd !== null ? recipe.trimEnd : (video.duration || Infinity);
+
+      if (video.currentTime < start) {
+        video.currentTime = start;
+      } else if (video.currentTime >= end && end > 0) {
+        video.pause();
+        video.currentTime = start;
+      }
+    };
+
+    video.addEventListener("timeupdate", handleTimeUpdate);
+    return () => {
+      video.removeEventListener("timeupdate", handleTimeUpdate);
+    };
+  }, [recipe, videoRef]);
+
   const preset = recipe?.preset === "custom"
     ? { width: recipe.customWidth, height: recipe.customHeight }
     : recipe ? getPresetById(recipe.preset) : null;

From fe4b788d846f382fc68808b765de5fae7ca061c9 Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 17:28:58 +0530
Subject: [PATCH 3/8] rotation implimentational bug fixed

---
 src/components/VideoPreview.tsx | 150 +++++++++++++++++++++++++++-----
 src/hooks/useVideoEditor.ts     |  55 +++++++++---
 src/lib/ffmpeg.worker.ts        |   3 +
 3 files changed, 171 insertions(+), 37 deletions(-)

diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index ff25ed12..cd156ce3 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -5,7 +5,7 @@ import { useEffect, useRef, useState, useCallback, RefObject } from "react";
 import { EditRecipe, TextOverlay } from "@/lib/types";
 import { getPresetById } from "@/lib/presets";
 import { cn } from "@/lib/utils";
-import { Camera } from "lucide-react";
+import { Camera, Play, Pause, Volume2, VolumeX } from "lucide-react";
 import ComparisonPreview from "./ComparisonPreview";
 import DraggableTextOverlays from "./DraggableTextOverlays";
 
@@ -32,6 +32,30 @@ export default function VideoPreview({
   const [showOverlay, setShowOverlay] = useState(false);
   const [showComparison, setShowComparison] = useState(false);
   const [showGridOverlay, setShowGridOverlay] = useState(false);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [isMuted, setIsMuted] = useState(!recipe?.keepAudio);
+  
+  useEffect(() => {
+    setIsMuted(!recipe?.keepAudio);
+  }, [recipe?.keepAudio]);
+
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video) return;
+
+    const handlePlay = () => setIsPlaying(true);
+    const handlePause = () => setIsPlaying(false);
+
+    video.addEventListener("play", handlePlay);
+    video.addEventListener("pause", handlePause);
+
+    return () => {
+      video.removeEventListener("play", handlePlay);
+      video.removeEventListener("pause", handlePause);
+    };
+  }, [videoRef]);
+
   const [containerDimensions, setContainerDimensions] = useState({
     width: 0,
     height: 0,
@@ -159,6 +183,8 @@ export default function VideoPreview({
         video.pause();
         video.currentTime = start;
       }
+      
+      setCurrentTime(video.currentTime);
     };
 
     video.addEventListener("timeupdate", handleTimeUpdate);
@@ -171,14 +197,20 @@ export default function VideoPreview({
     ? { width: recipe.customWidth, height: recipe.customHeight }
     : recipe ? getPresetById(recipe.preset) : null;
 
-  const targetRatio = preset ? preset.width / preset.height : 16 / 9;
+  const isRotated = recipe?.rotate === 90 || recipe?.rotate === 270;
+  
+  const targetW = preset ? preset.width : 16;
+  const targetH = preset ? preset.height : 9;
+
+  const targetRatio = targetW / targetH;
 
   const overlay = (() => {
     if (!recipe || !showOverlay || !preset) return null;
 
-    // Use the dynamic target ratio instead of hardcoded 16:9
-    const containerRatio = targetRatio;
-    const outputRatio = preset.width / preset.height;
+    // Both containerRatio and outputRatio must use the same rotation-aware
+    // dimensions so the bar math stays consistent regardless of rotation.
+    const containerRatio = targetRatio;   // targetW / targetH, already swapped for 90°/270°
+    const outputRatio = targetW / targetH; // identical to containerRatio — bars are zero when output fits exactly
 
     if (recipe.framing === "fit") {
       if (outputRatio > containerRatio) {
@@ -233,7 +265,7 @@ export default function VideoPreview({
       <div
         ref={previewContainerRef}
         role="group"
-        className="relative w-full rounded-lg overflow-hidden bg-[var(--bg)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)] transition-all duration-300"
+        className="relative w-full rounded-lg overflow-hidden bg-[var(--bg)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)] transition-all duration-300 group"
         style={{ aspectRatio: targetRatio }}
         tabIndex={0}
         onKeyDown={handleKeyDown}
@@ -241,26 +273,96 @@ export default function VideoPreview({
       >
         {isLoading && (
           <div
-            className="absolute inset-0 animate-pulse bg-[var(--surface)] rounded-xl transition-opacity duration-300"
+            className="absolute inset-0 animate-pulse bg-[var(--surface)] rounded-xl transition-opacity duration-300 z-10"
             aria-label="Loading video preview"
           />
         )}
-        {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
-        <video
-          ref={videoRef}
-          controls
-          className={cn("w-full h-full object-contain transition-all duration-300", isLoading ? "opacity-0" : "opacity-100")}
-          style={{ transform: `rotate(${recipe?.rotate || 0}deg)` }}
-          onLoadedData={() => setIsLoading(false)}
-          playsInline
-          muted={!recipe?.keepAudio}
+        
+        {/* 1. ROTATED VIDEO LAYER */}
+        <div 
+          className="absolute top-1/2 left-1/2 flex items-center justify-center pointer-events-none z-0" 
+          style={{ 
+            width: isRotated ? (containerDimensions.height || '100%') : '100%',
+            height: isRotated ? (containerDimensions.width || '100%') : '100%',
+            transform: `translate(-50%, -50%) rotate(${recipe?.rotate || 0}deg)` 
+          }}
         >
-          <track kind="captions" />
-        </video>
+          {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
+          <video
+            ref={videoRef}
+            className={cn("w-full h-full object-contain transition-all duration-300", isLoading ? "opacity-0" : "opacity-100")}
+            onLoadedData={() => setIsLoading(false)}
+            playsInline
+            muted={isMuted}
+          >
+            <track kind="captions" />
+          </video>
+        </div>
+
+        {/* CLICK-TO-PLAY LAYER */}
+        <div 
+          className="absolute inset-0 z-10 cursor-pointer"
+          onClick={() => {
+            if (videoRef.current) {
+              if (videoRef.current.paused) videoRef.current.play();
+              else videoRef.current.pause();
+            }
+          }}
+          aria-label="Play/Pause Video"
+        />
+
+        {/* 2. FIXED UI LAYER */}
+        <div className={cn("absolute bottom-0 left-0 right-0 p-3 bg-gradient-to-t from-black/70 to-transparent flex items-center gap-3 z-40 transition-opacity duration-300", isPlaying ? "opacity-0 group-hover:opacity-100 focus-within:opacity-100" : "opacity-100")}>
+          <button 
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              if (videoRef.current) {
+                if (videoRef.current.paused) videoRef.current.play();
+                else videoRef.current.pause();
+              }
+            }}
+            className="text-white hover:text-[var(--accent)] transition-colors"
+            aria-label={isPlaying ? "Pause" : "Play"}
+          >
+            {isPlaying ? <Pause size={18} /> : <Play size={18} />}
+          </button>
+          
+          <input 
+            type="range"
+            min={0}
+            max={videoRef.current?.duration || 100}
+            step="0.01"
+            value={currentTime}
+            onChange={(e) => {
+              if (videoRef.current) {
+                videoRef.current.currentTime = Number(e.target.value);
+              }
+            }}
+            onPointerDown={(e) => e.stopPropagation()}
+            className="flex-1 accent-[var(--accent)] h-1 cursor-pointer"
+            aria-label="Timeline"
+          />
+          
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              if (videoRef.current) {
+                videoRef.current.muted = !videoRef.current.muted;
+                setIsMuted(videoRef.current.muted);
+              }
+            }}
+            className="text-white hover:text-[var(--accent)] transition-colors"
+            aria-label={isMuted ? "Unmute" : "Mute"}
+          >
+            {isMuted ? <VolumeX size={18} /> : <Volume2 size={18} />}
+          </button>
+        </div>
 
         {/* Letterbox / Crop overlay */}
         {overlay && (
-          <div className="absolute inset-0 pointer-events-none" aria-hidden="true">
+          <div className="absolute inset-0 pointer-events-none z-20" aria-hidden="true">
             {overlay.mode === "fit" ? (
               // Letterbox: semi-transparent bars outside the content area
               <>
@@ -292,7 +394,7 @@ export default function VideoPreview({
 
         {/* 3x3 Grid Overlay */}
         {showGridOverlay && (
-          <div className="absolute inset-0 pointer-events-none" aria-hidden="true">
+          <div className="absolute inset-0 pointer-events-none z-20" aria-hidden="true">
             {/* Vertical lines */}
             <div className="absolute top-0 bottom-0 left-1/3 border-l-2 border-dotted border-black" />
             <div className="absolute top-0 bottom-0 right-1/3 border-l-2 border-dotted border-black" />
@@ -319,7 +421,7 @@ export default function VideoPreview({
           <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 ${
+            className={`absolute top-2 left-2 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-40 pointer-events-auto ${
               showOverlay
                 ? "bg-[var(--accent)] text-white"
                 : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
@@ -337,7 +439,7 @@ export default function VideoPreview({
           <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 ${
+            className={`absolute top-2 left-32 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-40 pointer-events-auto ${
               showGridOverlay
                 ? "bg-[var(--accent)] text-white"
                 : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
@@ -355,7 +457,7 @@ export default function VideoPreview({
           <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 ${
+            className={`absolute top-2 right-32 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-40 pointer-events-auto ${
               showComparison
                 ? "bg-[var(--accent)] text-white"
                 : "bg-[var(--surface)] text-[var(--muted)] hover:bg-[var(--accent-muted)] hover:text-[var(--text)]"
@@ -373,7 +475,7 @@ export default function VideoPreview({
           <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"
+            className="absolute top-2 right-2 px-2 py-1 text-[10px] font-heading font-bold uppercase tracking-wider rounded transition-colors z-40 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"
           >
diff --git a/src/hooks/useVideoEditor.ts b/src/hooks/useVideoEditor.ts
index b3ea8283..80dc8e50 100644
--- a/src/hooks/useVideoEditor.ts
+++ b/src/hooks/useVideoEditor.ts
@@ -3,7 +3,7 @@
 import { useState, useCallback, useEffect, useRef, useMemo } from "react";
 import { EditRecipe, ExportResult, ExportStatus, MAX_FILE_SIZE, OverlayPosition, isValidRecipe } from "@/lib/types";
 import { DEFAULT_RECIPE, SPEED_STEPS } from "@/lib/constants";
-import { getPresetById } from "@/lib/presets";
+import { getPresetById, PRESETS } from "@/lib/presets";
 import { loadFFmpeg, exportVideo, terminateFFmpeg, FFmpegLoadError } from "@/lib/ffmpeg";
 import { suggestPreset } from "@/lib/presetSuggestion";
 import { validateDimensions, getDownscaledDimensions } from "@/utils/video-validation";
@@ -188,16 +188,41 @@ export function useVideoEditor() {
   const [overlaySize, setOverlaySize] = useState(150);
   const [overlayOpacity, setOverlayOpacity] = useState(100);
   const [currentTime, setCurrentTime] = useState(0);
- const updateRecipe = useCallback((patch: Partial<EditRecipe>) => {
-  setRecipe((prev) => {
-    const next = { ...prev, ...patch };
-    // GIF has no audio — force keepAudio off
-    if (next.format === "gif") {
-      next.keepAudio = false;
-    }
-    return next;
-  });
-}, []);
+  const updateRecipe = useCallback((patch: Partial<EditRecipe>) => {
+    setRecipe((prev) => {
+      let next = { ...prev, ...patch };
+
+      if (patch.rotate !== undefined && prev.rotate !== undefined) {
+        const rotDiff = Math.abs(patch.rotate - prev.rotate);
+        if (rotDiff === 90 || rotDiff === 270) {
+          if (prev.preset === "custom") {
+            next.customWidth = prev.customHeight;
+            next.customHeight = prev.customWidth;
+          } else {
+            const currentPreset = getPresetById(prev.preset);
+            if (currentPreset) {
+              const targetRatio = currentPreset.height / currentPreset.width;
+              // Find a preset with the flipped ratio (allow small float differences)
+              const matchingPreset = PRESETS.find(p => p.id !== "custom" && Math.abs(p.width / p.height - targetRatio) < 0.01);
+              if (matchingPreset) {
+                next.preset = matchingPreset.id;
+              } else {
+                next.preset = "custom";
+                next.customWidth = currentPreset.height;
+                next.customHeight = currentPreset.width;
+              }
+            }
+          }
+        }
+      }
+
+      // GIF has no audio — force keepAudio off
+      if (next.format === "gif") {
+        next.keepAudio = false;
+      }
+      return next;
+    });
+  }, []);
   const isValidValue = (key: keyof EditRecipe, val: any): boolean => {
     switch (key) {
       case "preset":
@@ -362,8 +387,11 @@ export function useVideoEditor() {
 
   const recommendedPreset = useMemo(() => {
     if (!videoMetadata) return null;
-    return getPresetById(suggestPreset(videoMetadata.width, videoMetadata.height)) ?? null;
-  }, [videoMetadata]);
+    const isRotated = recipe.rotate === 90 || recipe.rotate === 270;
+    const w = isRotated ? videoMetadata.height : videoMetadata.width;
+    const h = isRotated ? videoMetadata.width : videoMetadata.height;
+    return getPresetById(suggestPreset(w, h)) ?? null;
+  }, [videoMetadata, recipe.rotate]);
 
   const handleFileSelect = useCallback(async (selectedFile: File) => {
     setResult(null);
@@ -437,6 +465,7 @@ export function useVideoEditor() {
           ...prev,
           trimStart: 0,
           trimEnd: null,
+          rotate: 0,
           ...(shouldApplySuggestion ? { preset: suggestedPreset } : {}),
         };
       });
diff --git a/src/lib/ffmpeg.worker.ts b/src/lib/ffmpeg.worker.ts
index f72ef583..9eddf9ca 100644
--- a/src/lib/ffmpeg.worker.ts
+++ b/src/lib/ffmpeg.worker.ts
@@ -399,6 +399,9 @@ async function runExport(request: ExportRequest): Promise<ResultPayload> {
   targetW = Math.round(targetW / 2) * 2;
   targetH = Math.round(targetH / 2) * 2;
 
+  // Target canvas dimensions are defined entirely by the preset.
+  // We do not swap them based on rotation, because the preset determines the final output aspect ratio.
+
   const ext = request.file.name.split(".").pop() ?? "mp4";
   const inputName = `input_${sessionId}.${ext}`;
 

From 1aab4914c678c1a0e429cecea89c871ac5ce7142 Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 17:34:46 +0530
Subject: [PATCH 4/8] Fix vertical aspect ratio preview overflowing outside the
 preview window

---
 src/components/VideoPreview.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index cd156ce3..04edaefa 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -265,8 +265,8 @@ export default function VideoPreview({
       <div
         ref={previewContainerRef}
         role="group"
-        className="relative w-full rounded-lg overflow-hidden bg-[var(--bg)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)] transition-all duration-300 group"
-        style={{ aspectRatio: targetRatio }}
+        className="relative w-full mx-auto rounded-lg overflow-hidden bg-[var(--bg)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)] transition-all duration-300 group"
+        style={{ aspectRatio: targetRatio, maxWidth: `calc(65vh * ${targetRatio})` }}
         tabIndex={0}
         onKeyDown={handleKeyDown}
         aria-label="Video preview (press Space to play/pause)"

From 7b7474b6b370ac577bf2380f21f166aed7783735 Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 17:55:55 +0530
Subject: [PATCH 5/8] fix: prevent unintended text preview movement

---
 src/components/DraggableTextOverlays.tsx |  2 +-
 src/components/VideoPreview.tsx          | 24 +++++++++++-------------
 2 files changed, 12 insertions(+), 14 deletions(-)

diff --git a/src/components/DraggableTextOverlays.tsx b/src/components/DraggableTextOverlays.tsx
index d6a088aa..c6be44ba 100644
--- a/src/components/DraggableTextOverlays.tsx
+++ b/src/components/DraggableTextOverlays.tsx
@@ -216,7 +216,7 @@ export default function DraggableTextOverlays({
   return (
     <div
       ref={containerRef}
-      className="absolute inset-0 pointer-events-none"
+      className="absolute inset-0 pointer-events-none z-30"
       style={{ width: containerWidth, height: containerHeight }}
     >
       {textOverlays.map((overlay) => {
diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index 04edaefa..34dc06f4 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -149,23 +149,21 @@ export default function VideoPreview({
     videoRef.current.playbackRate = recipe.speed;
   }, [recipe, videoRef]);
 
-  /**
-   * Track preview container dimensions for text overlay positioning.
-   */
   useEffect(() => {
-    const updateDimensions = () => {
-      if (previewContainerRef.current) {
-        const rect = previewContainerRef.current.getBoundingClientRect();
+    const el = previewContainerRef.current;
+    if (!el) return;
+    
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
         setContainerDimensions({
-          width: rect.width,
-          height: rect.height,
+          width: entry.contentRect.width,
+          height: entry.contentRect.height,
         });
       }
-    };
-
-    updateDimensions();
-    window.addEventListener("resize", updateDimensions);
-    return () => window.removeEventListener("resize", updateDimensions);
+    });
+    
+    observer.observe(el);
+    return () => observer.disconnect();
   }, []);
 
   useEffect(() => {

From 9009d745c63c4af1cd1b934bbd3369c5c2a2dd0a Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 18:21:12 +0530
Subject: [PATCH 6/8] implement image overlay preview

---
 src/components/VideoEditor.tsx  |  4 ++++
 src/components/VideoPreview.tsx | 42 ++++++++++++++++++++++++++++++++-
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/src/components/VideoEditor.tsx b/src/components/VideoEditor.tsx
index 411ca8e7..15e2d70d 100644
--- a/src/components/VideoEditor.tsx
+++ b/src/components/VideoEditor.tsx
@@ -443,6 +443,10 @@ return () => {
                     selectedTextId={selectedTextId}
                     onSelectText={setSelectedTextId}
                     onUpdateText={handleUpdateTextOverlay}
+                    overlayFile={overlayFile}
+                    overlayPosition={overlayPosition}
+                    overlaySize={overlaySize}
+                    overlayOpacity={overlayOpacity}
                   />
 
                   <div className="mt-3">
diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index 34dc06f4..20fe0022 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -2,7 +2,7 @@
 "use client";
 
 import { useEffect, useRef, useState, useCallback, RefObject } from "react";
-import { EditRecipe, TextOverlay } from "@/lib/types";
+import { EditRecipe, TextOverlay, OverlayPosition } from "@/lib/types";
 import { getPresetById } from "@/lib/presets";
 import { cn } from "@/lib/utils";
 import { Camera, Play, Pause, Volume2, VolumeX } from "lucide-react";
@@ -16,6 +16,10 @@ interface Props {
   selectedTextId?: string | null;
   onSelectText?: (id: string | null) => void;
   onUpdateText?: (id: string, updates: Partial<TextOverlay>) => void;
+  overlayFile?: File | null;
+  overlayPosition?: OverlayPosition;
+  overlaySize?: number;
+  overlayOpacity?: number;
 }
 
 export default function VideoPreview({
@@ -25,6 +29,10 @@ export default function VideoPreview({
   selectedTextId = null,
   onSelectText,
   onUpdateText,
+  overlayFile,
+  overlayPosition = "bottom-right",
+  overlaySize = 150,
+  overlayOpacity = 100,
 }: Props) {
   const lastId = useRef(0);
   const urlRef = useRef<string | null>(null);
@@ -35,6 +43,17 @@ export default function VideoPreview({
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentTime, setCurrentTime] = useState(0);
   const [isMuted, setIsMuted] = useState(!recipe?.keepAudio);
+  const [overlayUrl, setOverlayUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!overlayFile) {
+      setOverlayUrl(null);
+      return;
+    }
+    const url = URL.createObjectURL(overlayFile);
+    setOverlayUrl(url);
+    return () => URL.revokeObjectURL(url);
+  }, [overlayFile]);
   
   useEffect(() => {
     setIsMuted(!recipe?.keepAudio);
@@ -201,6 +220,10 @@ export default function VideoPreview({
   const targetH = preset ? preset.height : 9;
 
   const targetRatio = targetW / targetH;
+  
+  const scale = containerDimensions.width > 0 ? containerDimensions.width / targetW : 1;
+  const previewOverlaySize = overlaySize * scale;
+  const previewPadding = 20 * scale;
 
   const overlay = (() => {
     if (!recipe || !showOverlay || !preset) return null;
@@ -402,6 +425,23 @@ export default function VideoPreview({
           </div>
         )}
 
+        {/* IMAGE OVERLAY LAYER */}
+        {overlayUrl && containerDimensions.width > 0 && (
+          <img
+            src={overlayUrl}
+            alt="Overlay"
+            className="absolute pointer-events-none z-30"
+            style={{
+              width: previewOverlaySize,
+              opacity: overlayOpacity / 100,
+              ...(overlayPosition === "top-left" ? { top: previewPadding, left: previewPadding } : {}),
+              ...(overlayPosition === "top-right" ? { top: previewPadding, right: previewPadding } : {}),
+              ...(overlayPosition === "bottom-left" ? { bottom: previewPadding, left: previewPadding } : {}),
+              ...(overlayPosition === "bottom-right" ? { bottom: previewPadding, right: previewPadding } : {}),
+            }}
+          />
+        )}
+
         {/* Draggable Text Overlays */}
         {recipe && !isLoading && containerDimensions.width > 0 && (
           <DraggableTextOverlays

From b25b5fcbea0be7565e238ad79b5f7c5d69663bdc Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 18:38:32 +0530
Subject: [PATCH 7/8] implemented preiview for Adjustments( Brightness,
 Contrast, Saturation )

---
 src/components/VideoPreview.tsx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/components/VideoPreview.tsx b/src/components/VideoPreview.tsx
index 20fe0022..74ae075a 100644
--- a/src/components/VideoPreview.tsx
+++ b/src/components/VideoPreview.tsx
@@ -1,7 +1,7 @@
 /* eslint-disable jsx-a11y/no-static-element-interactions, jsx-a11y/no-noninteractive-tabindex, jsx-a11y/no-noninteractive-element-interactions */
 "use client";
 
-import { useEffect, useRef, useState, useCallback, RefObject } from "react";
+import { useEffect, useRef, useState, useCallback, useMemo, RefObject } from "react";
 import { EditRecipe, TextOverlay, OverlayPosition } from "@/lib/types";
 import { getPresetById } from "@/lib/presets";
 import { cn } from "@/lib/utils";
@@ -44,6 +44,13 @@ export default function VideoPreview({
   const [currentTime, setCurrentTime] = useState(0);
   const [isMuted, setIsMuted] = useState(!recipe?.keepAudio);
   const [overlayUrl, setOverlayUrl] = useState<string | null>(null);
+  const adjustmentFilter = useMemo(() => {
+    const brightness = 1 + (recipe?.brightness ?? 0);
+    const contrast = recipe?.contrast ?? 1;
+    const saturation = recipe?.saturation ?? 1;
+
+    return `brightness(${brightness}) contrast(${contrast}) saturate(${saturation})`;
+  }, [recipe?.brightness, recipe?.contrast, recipe?.saturation]);
 
   useEffect(() => {
     if (!overlayFile) {
@@ -312,6 +319,7 @@ export default function VideoPreview({
           <video
             ref={videoRef}
             className={cn("w-full h-full object-contain transition-all duration-300", isLoading ? "opacity-0" : "opacity-100")}
+            style={{ filter: adjustmentFilter }}
             onLoadedData={() => setIsLoading(false)}
             playsInline
             muted={isMuted}

From 16031e9da68edf02e9d41e9f244d9c1ca55c0c64 Mon Sep 17 00:00:00 2001
From: jayesh durge <179298187+jayesh-durge@users.noreply.github.com>
Date: Wed, 3 Jun 2026 18:45:34 +0530
Subject: [PATCH 8/8] updated ARCHITECTURE.md for the implementation of preview
 architecture

---
 docs/ARCHITECTURE.md | 497 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 367 insertions(+), 130 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7dd8e230..225b3202 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,26 +1,18 @@
 # Reframe Architecture
 
-This document provides detailed technical information about Reframe's architecture, design choices, and implementation details.
+This document is the source of truth for Reframe's app architecture, state flow, preview behavior, and export pipeline.
 
 ---
 
-## Table of Contents
+## Overview
 
-- [How It Works](#how-it-works)
-- [Architecture Diagram](#architecture-diagram)
-- [Key Files](#key-files)
-- [Tech Stack](#tech-stack)
-- [Video Processing Pipeline](#video-processing-pipeline)
-- [Design Choices](#design-choices)
+Reframe is a client-side video editor built with Next.js and React. Users upload a local video, adjust an `EditRecipe`, preview changes in the browser, and export the final result with FFmpeg running in a Web Worker. Videos are processed locally on the user's device; no media is uploaded to a server.
 
----
-
-## How It Works
+The app has three primary layers:
 
-1. **Load Video** → User selects a file → App detects resolution and duration
-2. **Build Recipe** → User adjusts presets, framing, trim, speed → Creates `EditRecipe`
-3. **Export** → Click Export → FFmpeg WASM loads from CDN (~30 MB, cached after first use) → Filtergraph runs locally → File downloads
-4. **Done** → Your edited video is ready. Nothing was uploaded anywhere.
+- **UI layer:** React components for layout, preview, controls, overlays, export status, and download results.
+- **State layer:** `useVideoEditor` owns the active file, edit recipe, metadata, persistence, and export state.
+- **Processing layer:** `ffmpeg.ts` and `ffmpeg.worker.ts` translate the recipe into FFmpeg arguments and run the export in browser-side WebAssembly.
 
 ---
 
@@ -28,177 +20,422 @@ This document provides detailed technical information about Reframe's architectu
 
 ```mermaid
 graph TD
-    A["UI Layer · Next.js Components"] --> B["VideoEditor · FileUpload · PresetSelector · FramingControl · TrimControl"]
-    A --> C["AudioSpeedControl · RotateControl · ExportSettings"]
-    B --> D["useVideoEditor Hook · State Management"]
-    C --> D
-    D --> E["ffmpeg.ts · Lazy-loads WASM, builds filter chains"]
-    E --> F["FFmpeg.wasm · Single-threaded core via CDN · ~30MB"]
-    F --> G["Video Pipeline: trim → rotate → scale/crop → speed"]
-    G --> I["Output: MP4 or WebM · Blob URL → Download"]
+    User["User"] --> UI["UI Layer: Next.js + React Components"]
+    UI --> Editor["VideoEditor"]
+    Editor --> Hook["useVideoEditor: State + Orchestration"]
+    Editor --> Preview["VideoPreview: Browser Preview"]
+    Editor --> Controls["Controls: Preset, Trim, Rotate, Text, Audio, Adjustments, Export"]
+    Controls --> Hook
+    Hook --> Recipe["EditRecipe"]
+    Recipe --> Preview
+    Hook --> FFmpegFacade["ffmpeg.ts: Main Thread Facade"]
+    FFmpegFacade --> Worker["ffmpeg.worker.ts: Web Worker"]
+    Worker --> Wasm["FFmpeg.wasm"]
+    Wasm --> Result["ExportResult: Blob URL + Download"]
+    Result --> Editor
 ```
 
 ---
 
 ## Key Files
 
-| File                             | Purpose                                                  |
-| -------------------------------- | -------------------------------------------------------- |
-| `src/components/VideoEditor.tsx` | Root component; layout, state orchestration              |
-| `src/hooks/useVideoEditor.ts`    | State management (file, recipe, export status)           |
-| `src/lib/ffmpeg.ts`              | FFmpeg wrapper; lazy-loads WASM, builds filter chains    |
-| `src/lib/presets.ts`             | 11 preset definitions (9:16, 16:9, 4:5, etc.)            |
-| `src/lib/types.ts`               | TypeScript types for EditRecipe, ExportResult, etc.      |
-| `src/components/*.tsx`           | Individual control panels (Trim, Rotate, Speed, Quality) |
+| File | Responsibility |
+| --- | --- |
+| `src/components/VideoEditor.tsx` | Main editor view, layout orchestration, passes state into preview and controls. |
+| `src/components/VideoPreview.tsx` | Renders the HTML video element, browser-side previews, playback controls, visual overlays, and comparison preview. |
+| `src/hooks/useVideoEditor.ts` | Owns domain state, file validation, recipe updates, persistence, export status, and export orchestration. |
+| `src/lib/types.ts` | Shared TypeScript contracts including `EditRecipe`, `ExportResult`, overlay options, and validation helpers. |
+| `src/lib/constants.ts` | Default recipe values and shared option constants. |
+| `src/lib/ffmpeg.ts` | Main-thread FFmpeg facade, worker lifecycle, request serialization, result handling, and filter builders used by tests. |
+| `src/lib/ffmpeg.worker.ts` | Worker-side FFmpeg load, MEMFS staging, argument construction, execution, cleanup, and progress reporting. |
+| `src/lib/presets.ts` | Output preset definitions and target dimensions. |
+| `src/lib/text-overlay.ts` | FFmpeg text overlay filter generation. |
 
 ---
 
-## Tech Stack
+## Component Hierarchy
+
+`VideoEditor` is the main composition root. It renders:
+
+- `ExportOverlay`
+- `OnboardingTour`
+- `FileUpload`
+- `VideoPreview`
+- `ThumbnailStrip`
+- `PresetSelector`
+- `FramingControl`
+- `TrimControl`
+- `RotateControl`
+- `TextControls`
+- `AudioSpeedControl`
+- brightness, contrast, and saturation controls
+- `FormatSelector`
+- `ExportSettings`
+- `ImageOverlay`
+- `DownloadResult`
+- `KeyboardShortcutsPanel`
+
+`VideoPreview` contains the actual `<video>` element and preview-only layers:
+
+- playback controls
+- framing/crop guide overlay
+- grid overlay
+- image overlay preview
+- draggable text overlays
+- optional comparison preview
+
+---
+
+## State Ownership
+
+The central source of truth is the `recipe` object owned by `useVideoEditor`.
+
+`useVideoEditor` owns:
+
+- uploaded `file`
+- video metadata and `duration`
+- `recipe`
+- export state: `status`, `progress`, `result`, `error`
+- media refs and seek helpers
+- overlay files and overlay options
+- persistence to `localStorage`
+- URL search parameter synchronization
+
+`VideoEditor` owns local UI-only state:
 
-| Layer                | Tech                                   |
-| -------------------- | -------------------------------------- |
-| **Framework**        | Next.js 15 (App Router, static export) |
-| **Language**         | TypeScript 5                           |
-| **Styling**          | Tailwind CSS v3                        |
-| **Icons**            | Lucide React                           |
-| **Animations**       | Lottie Web                             |
-| **Video Processing** | FFmpeg.wasm (single-threaded)          |
-| **Fonts**            | Bebas Neue · Syne · DM Sans            |
+- opened/closed sections
+- selected text overlay ID
+- copy-to-clipboard feedback
+- scroll behavior after export
+
+`VideoPreview` owns preview-only state:
+
+- loading state
+- play/pause state
+- current preview time
+- mute display state
+- framing overlay toggle
+- grid overlay toggle
+- comparison preview toggle
+- measured preview container dimensions
+- generated object URL for the image overlay preview
 
 ---
 
-## Video Processing Pipeline
+## EditRecipe Model
+
+The `EditRecipe` is the declarative edit description used by both preview and export.
+
+Important fields include:
+
+| Field | Meaning |
+| --- | --- |
+| `preset` | Selected output preset ID. |
+| `customWidth`, `customHeight` | Custom output dimensions when `preset === "custom"`. |
+| `framing` | `"fit"` for letterboxing/pillarboxing or `"fill"` for crop-to-fill. |
+| `trimStart`, `trimEnd` | Trim range in seconds; `trimEnd === null` means through the source end. |
+| `rotate` | Rotation in degrees: `0`, `90`, `180`, or `270`. |
+| `keepAudio` | Whether original audio is included. |
+| `normalizeAudio` | Whether loudness normalization is applied during export. |
+| `speed` | Playback speed multiplier. |
+| `quality` | Export CRF value. |
+| `format` | Output format: `mp4`, `webm`, `mkv`, or `gif`. |
+| `brightness` | FFmpeg `eq` brightness value, range `-1..1`, neutral `0`. |
+| `contrast` | FFmpeg `eq` contrast value, range `0..2`, neutral `1`. |
+| `saturation` | FFmpeg `eq` saturation value, range `0..3`, neutral `1`. |
+| `textOverlays` | Text overlays rendered in preview and exported with FFmpeg drawtext filters. |
 
-Reframe uses FFmpeg.wasm to process videos entirely in the browser. The processing pipeline follows these steps:
+---
 
-1. **Video Input** — User-selected video file is loaded into memory
-2. **Trim** — If trim times are specified, the video is trimmed using FFmpeg's `trim` filter
-3. **Rotate** — Video is rotated using FFmpeg's `transpose` filter (0°, 90°, 180°, 270°)
-4. **Scale/Crop** — Video is resized based on the selected preset and framing mode:
-   - **Fit mode**: Video is scaled to fit within the target dimensions with letterboxing/pillarboxing
-   - **Fill mode**: Video is scaled to fill the target dimensions and cropped
-5. **Speed Adjustment** — Playback speed is adjusted using `setpts` (video) and `atempo` (audio) filters
-6. **Audio Processing** — Audio is either kept (with speed adjustment) or removed based on user preference
-7. **Encoding** — Final video is encoded to MP4 (H.264) or WebM (VP9) format
-8. **Download** — Processed video is made available as a Blob URL for download
+## State Flow
+
+State flows in one direction:
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Control as Control Component
+    participant Editor as VideoEditor
+    participant Hook as useVideoEditor
+    participant Preview as VideoPreview
+    participant Storage as LocalStorage and URL
+
+    User->>Control: Changes a setting
+    Control->>Editor: onChange/updateRecipe patch
+    Editor->>Hook: updateRecipe(partialRecipe)
+    Hook->>Hook: Merge patch into recipe
+    Hook-->>Storage: Persist recipe
+    Hook-->>Editor: Re-render with updated recipe
+    Editor-->>Preview: Pass updated recipe
+    Preview-->>User: Update browser preview
+```
+
+Controls never mutate recipe fields directly. They call `updateRecipe`, and the resulting recipe is passed back down through props.
 
 ---
 
-## Design Choices
+## Browser Preview Architecture
+
+Preview rendering is intentionally browser-side and does not invoke FFmpeg.
+
+Preview constraints:
+
+- No backend rendering.
+- No temporary video generation.
+- No FFmpeg execution for preview.
+- No canvas rendering for simple adjustments.
+- The original `URL.createObjectURL(file)` video stream remains the preview source.
+- Export behavior stays controlled by the same recipe and FFmpeg pipeline.
+
+### Real-Time Color Adjustment Preview
+
+Brightness, contrast, and saturation are previewed with one consolidated CSS filter chain applied to the existing `<video>` element in `VideoPreview`.
+
+```tsx
+const adjustmentFilter = `
+  brightness(${1 + recipe.brightness})
+  contrast(${recipe.contrast})
+  saturate(${recipe.saturation})
+`;
+```
+
+The mapping exists because the stored values are FFmpeg-oriented:
+
+- FFmpeg brightness neutral is `0`; CSS brightness neutral is `1`, so preview uses `1 + recipe.brightness`.
+- Contrast maps directly because both use `1` as neutral.
+- Saturation maps directly because both use `1` as neutral.
+
+This keeps the data flow simple:
+
+```text
+Adjustment Control
+-> updateRecipe
+-> EditRecipe
+-> VideoPreview
+-> CSS filter on existing video element
+```
+
+The filter is applied as a style update only. The video element is not remounted or reloaded.
+
+### Rotation Preview
+
+Rotation is previewed with CSS transforms in `VideoPreview`. For `90` and `270` degrees, the preview uses a rotated wrapper so the video remains centered and bounded inside the target aspect ratio.
+
+### Aspect Ratio and Framing Preview
+
+The preview container uses the target preset dimensions to compute its aspect ratio. Framing guides help communicate the difference between:
+
+- **Fit:** scale down to fit target dimensions and fill unused space with bars.
+- **Fill:** scale up to cover target dimensions and crop the overflow.
 
-### Why FFmpeg.wasm?
+### Trim Preview
 
-- **Client-side processing** — No server infrastructure needed, complete privacy
-- **Industry-standard** — FFmpeg is the gold standard for video processing
-- **Feature-rich** — Supports all common video operations (trim, rotate, scale, speed, etc.)
-- **Browser compatibility** — Works in all modern browsers via WebAssembly
+`VideoPreview` listens to video time updates and keeps playback inside `trimStart` and `trimEnd`. If playback reaches the trim end, it returns to the trim start and pauses.
 
-### Why Next.js Static Export?
+### Overlay Preview
 
-- **Zero backend** — Entire app is static HTML/CSS/JS
-- **Fast deployment** — Can be hosted on any static file server
-- **Offline-capable** — Works offline after initial load (with service worker)
-- **SEO-friendly** — Static pages are easily crawlable
+Text and image overlays are rendered as DOM layers above the video. Their preview coordinates are scaled to the responsive preview dimensions, while export uses FFmpeg filters against the final output dimensions.
 
-### Why Single-threaded FFmpeg?
+---
+
+## Export Pipeline
+
+Export is separate from preview and is the only time FFmpeg is used.
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Editor as VideoEditor
+    participant Hook as useVideoEditor
+    participant Facade as ffmpeg.ts
+    participant Worker as ffmpeg.worker.ts
+    participant Core as FFmpeg.wasm
+    participant Result as DownloadResult
+
+    User->>Editor: Click Export
+    Editor->>Hook: handleExport()
+    Hook->>Hook: Validate recipe and set loading state
+    Hook->>Facade: loadFFmpeg()
+    Facade->>Worker: postMessage load
+    Worker->>Core: Load FFmpeg core
+    Worker-->>Facade: ready
+    Hook->>Facade: exportVideo(file, recipe, options)
+    Facade->>Worker: postMessage export payload
+    Worker->>Worker: Stage files in MEMFS
+    Worker->>Worker: Build FFmpeg args
+    Worker->>Core: ffmpeg.exec(args)
+    Core-->>Worker: Encoded output file
+    Worker-->>Facade: ArrayBuffer result
+    Facade-->>Hook: ExportResult with Blob URL
+    Hook-->>Result: Render download UI
+```
+
+### Export Steps
 
-- **Broader compatibility** — Multi-threaded WASM requires SharedArrayBuffer, which has strict CORS requirements
-- **Simpler deployment** — No need for special HTTP headers (COOP/COEP)
-- **Good enough performance** — For typical video editing tasks, single-threaded performance is acceptable
+1. `VideoEditor` calls `handleExport` from `useVideoEditor`.
+2. `handleExport` validates the current recipe and sets export UI state.
+3. `loadFFmpeg` initializes the FFmpeg Web Worker and loads the Wasm core.
+4. `exportVideo` serializes the video, optional music, and optional image overlay into transferable `ArrayBuffer` payloads.
+5. `ffmpeg.worker.ts` writes inputs into FFmpeg MEMFS.
+6. Worker-side argument builders translate the recipe into FFmpeg command arguments.
+7. FFmpeg runs inside the worker and reports progress.
+8. The worker reads the output file from MEMFS and sends it back to the main thread.
+9. The main thread wraps the output as a `Blob`, creates a Blob URL, and shows `DownloadResult`.
 
-### State Management
+### Video Filter Order
 
-Reframe uses a custom React hook (`useVideoEditor`) for state management instead of external libraries like Redux or Zustand:
+The export video filter chain is built from the recipe. Conceptually, it applies:
 
-- **Simplicity** — No additional dependencies
-- **Type safety** — Full TypeScript support
-- **Sufficient for scope** — App state is relatively simple and doesn't require complex state management
+1. trim
+2. stabilization, when enabled
+3. rotation
+4. scale and pad/crop based on preset and framing
+5. timestamp normalization when needed
+6. speed adjustment
+7. denoise, when enabled
+8. brightness, contrast, saturation via FFmpeg `eq`
+9. text overlays
 
-### Component Architecture
+Color adjustments are exported with:
 
-Components are organized by feature:
+```text
+eq=brightness={recipe.brightness}:contrast={recipe.contrast}:saturation={recipe.saturation}
+```
 
-- **Atomic components** — Small, reusable components (LottiePlayer, buttons)
-- **Feature components** — Components for specific features (TrimControl, RotateControl)
-- **Layout components** — High-level layout and orchestration (VideoEditor)
+### Audio Filter Order
 
-This structure makes it easy to:
-- Find and modify specific features
-- Add new features without affecting existing code
-- Test components in isolation
+Audio processing includes:
+
+- optional trim via `atrim`
+- timestamp reset via `asetpts`
+- speed changes via one or more `atempo` filters
+- optional loudness normalization via `loudnorm`
+- optional background music mixing
 
 ---
 
-## Browser Support
+## Processing and Threading
+
+FFmpeg work is performed in `ffmpeg.worker.ts`, not on the main UI thread. The main thread facade in `ffmpeg.ts` is responsible for:
 
-| Browser       | Support    | Notes                   |
-| ------------- | ---------- | ----------------------- |
-| Chrome 90+    | ✅ Full    | Recommended             |
-| Firefox 89+   | ✅ Full    |                         |
-| Safari 15+    | ✅ Full    |                         |
-| Edge 90+      | ✅ Full    |                         |
-| Mobile Chrome | ✅ Full    |                         |
-| Mobile Safari | ⚠️ Partial | Large files may be slow |
+- creating and terminating the worker
+- resolving readiness and export promises
+- forwarding progress callbacks
+- serializing files into transferable buffers
+- converting final output buffers into Blob URLs
 
-### Browser Requirements
+The worker is responsible for:
 
-- **WebAssembly support** — Required for FFmpeg.wasm
-- **File API** — For reading user-selected video files
-- **Blob URLs** — For downloading processed videos
-- **Modern JavaScript** — ES2017+ features
+- loading FFmpeg
+- writing files to MEMFS
+- building command arguments
+- running `ffmpeg.exec`
+- reading output files
+- cleaning temporary files
+- posting progress, result, error, and cancellation messages
+
+---
+
+## Tech Stack
+
+| Layer | Tech |
+| --- | --- |
+| Framework | Next.js 15 App Router |
+| Language | TypeScript |
+| UI | React |
+| Styling | Tailwind CSS |
+| Icons | Lucide React |
+| Video Processing | FFmpeg.wasm |
+| Execution Isolation | Web Worker |
+
+---
+
+## Design Choices
+
+### Client-Side Processing
+
+All media operations run locally in the browser. This preserves privacy, removes server costs, and allows static deployment.
+
+### Recipe-Driven Editing
+
+The `EditRecipe` is the shared contract between controls, preview, persistence, URL sharing, and export. This avoids duplicate state and keeps preview synchronized with export settings.
+
+### CSS/DOM Preview, FFmpeg Export
+
+Preview uses browser primitives for immediate visual feedback. Export uses FFmpeg for the actual encoded output. This avoids expensive temporary encodes while sliders are changing.
+
+### Worker-Based FFmpeg
+
+FFmpeg runs in a worker to keep the UI responsive. Main-thread React rendering, playback controls, and progress UI remain interactive during export.
+
+### Single Central Hook
+
+`useVideoEditor` acts as the editor facade. It keeps the feature surface understandable without introducing Redux/Zustand for a state model that is still compact enough for a custom hook.
 
 ---
 
 ## Performance Considerations
 
-### Memory Usage
+Preview performance:
+
+- CSS filters and transforms are generally GPU-accelerated.
+- Updating filter style while dragging sliders avoids video reloads and remounts.
+- Multiple overlays and filters can increase compositing cost on low-end devices.
+- Canvas/WebGL preview should be reserved for future complex effects, not simple adjustment sliders.
 
-- Video files are loaded entirely into memory
-- FFmpeg.wasm requires additional memory for processing
-- Large videos (>500 MB) may cause performance issues on low-memory devices
+Export performance:
 
-### Processing Speed
+- Video files are loaded into memory.
+- FFmpeg.wasm also requires working memory during processing.
+- Large or high-resolution files can be slow or memory-heavy.
+- FFmpeg is lazy-loaded only when export starts.
+- Browser/CDN caching reduces repeat load time.
 
-Processing speed depends on:
-- Video resolution and duration
-- Selected quality settings (CRF value)
-- Device CPU performance
-- Browser implementation
+---
 
-Typical processing times:
-- 1080p, 30s video: ~30-60 seconds
-- 4K, 30s video: ~2-5 minutes
+## Browser Requirements
 
-### Optimization Strategies
+Reframe depends on:
 
-- **Lazy loading** — FFmpeg.wasm is only loaded when user clicks Export
-- **CDN caching** — FFmpeg core files are cached by the browser after first load
-- **Efficient filters** — Filter chains are optimized to minimize processing steps
-- **Quality presets** — CRF slider allows users to balance quality vs. processing time
+- WebAssembly
+- Web Workers
+- File API
+- Blob URLs
+- modern JavaScript and CSS features such as `aspect-ratio`, transforms, and filters
+
+Large files may be constrained by device memory, especially on mobile browsers.
+
+---
+
+## Current Boundaries and Known Limitations
+
+- Preview color filters approximate FFmpeg `eq`; they are not guaranteed to be mathematically identical.
+- Stabilization and denoise remain export-only because native CSS cannot preview those effects accurately.
+- Browser-rendered text can differ slightly from FFmpeg `drawtext` output because font rendering engines differ.
+- Responsive overlay positioning must be mapped carefully to final video pixel coordinates.
+- FFmpeg export is memory-intensive because source and output media are staged in browser memory.
 
 ---
 
 ## Future Architecture Improvements
 
-Potential improvements for future versions:
+Possible future improvements:
 
-1. **Multi-threaded FFmpeg** — Faster processing with SharedArrayBuffer (requires COOP/COEP headers)
-2. **Web Workers** — Offload processing to background thread to keep UI responsive
-3. **Streaming processing** — Process video in chunks to reduce memory usage
-4. **GPU acceleration** — Use WebGPU for faster video processing (when browser support improves)
-5. **Service Worker** — Enable full offline functionality with caching
-6. **IndexedDB storage** — Store processed videos locally for later download
+1. More accurate preview pipelines for advanced effects using WebGL/WebGPU.
+2. Better custom trim timeline controls.
+3. Multi-threaded FFmpeg if deployment can support the required COOP/COEP headers.
+4. Chunked or streaming processing to reduce memory pressure.
+5. IndexedDB-backed drafts and cached exports.
+6. Stronger visual parity tests for overlay placement and text rendering.
 
 ---
 
-## Contributing to Architecture
-
-When contributing architecture changes:
+## Contribution Guidelines for Architecture Changes
 
-1. **Maintain privacy** — All processing must remain client-side
-2. **Keep it simple** — Avoid over-engineering; prefer simple solutions
-3. **Document decisions** — Update this file when making architectural changes
-4. **Consider performance** — Test with large videos on low-end devices
-5. **Ensure compatibility** — Test in all supported browsers
+When changing core architecture:
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for general contribution guidelines.
+1. Keep media processing local to the user's device.
+2. Keep `EditRecipe` as the single source of truth for editor settings.
+3. Do not invoke FFmpeg for live preview interactions.
+4. Keep preview changes lightweight enough for smooth playback.
+5. Update this document when changing state flow, preview behavior, or export behavior.