From 3be195cc15f54bff333acaa3d296943d1f3d0104 Mon Sep 17 00:00:00 2001
From: xKeCo <kevcollazos@gmail.com>
Date: Wed, 1 Apr 2026 01:41:20 -0500
Subject: [PATCH 01/20] =?UTF-8?q?=E2=9C=A8=20feat:=20smooth=20auto-follow?=
 =?UTF-8?q?=20zoom=20with=20export=20parity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/components/video-editor/SettingsPanel.tsx | 41 ++++++++++++++
 src/components/video-editor/VideoEditor.tsx   | 24 ++++++++
 src/components/video-editor/VideoPlayback.tsx | 49 ++++++++++++++++-
 .../video-editor/projectPersistence.ts        |  1 +
 src/components/video-editor/types.ts          |  2 +
 .../video-editor/videoPlayback/constants.ts   |  2 +
 .../videoPlayback/cursorFollowUtils.ts        | 54 ++++++++++++++++++
 .../videoPlayback/overlayUtils.ts             |  2 +-
 .../videoPlayback/zoomRegionUtils.ts          | 55 +++++++++++++++----
 src/i18n/locales/en/settings.json             |  8 ++-
 src/i18n/locales/es/settings.json             |  8 ++-
 src/i18n/locales/zh-CN/settings.json          |  8 ++-
 src/lib/exporter/frameRenderer.ts             | 47 +++++++++++++++-
 src/lib/exporter/gifExporter.ts               |  2 +
 src/lib/exporter/videoExporter.ts             |  2 +
 15 files changed, 287 insertions(+), 18 deletions(-)
 create mode 100644 src/components/video-editor/videoPlayback/cursorFollowUtils.ts

diff --git a/src/components/video-editor/SettingsPanel.tsx b/src/components/video-editor/SettingsPanel.tsx
index f5afe35..bec50c2 100644
--- a/src/components/video-editor/SettingsPanel.tsx
+++ b/src/components/video-editor/SettingsPanel.tsx
@@ -92,6 +92,9 @@ interface SettingsPanelProps {
 	onWallpaperChange: (path: string) => void;
 	selectedZoomDepth?: ZoomDepth | null;
 	onZoomDepthChange?: (depth: ZoomDepth) => void;
+	selectedZoomFocusMode?: import("./types").ZoomFocusMode | null;
+	onZoomFocusModeChange?: (mode: import("./types").ZoomFocusMode) => void;
+	hasCursorTelemetry?: boolean;
 	selectedZoomId?: string | null;
 	onZoomDelete?: (id: string) => void;
 	selectedTrimId?: string | null;
@@ -161,6 +164,9 @@ export function SettingsPanel({
 	onWallpaperChange,
 	selectedZoomDepth,
 	onZoomDepthChange,
+	selectedZoomFocusMode,
+	onZoomFocusModeChange,
+	hasCursorTelemetry = false,
 	selectedZoomId,
 	onZoomDelete,
 	selectedTrimId,
@@ -500,6 +506,41 @@ export function SettingsPanel({
 					{!zoomEnabled && (
 						<p className="text-[10px] text-slate-500 mt-2 text-center">{t("zoom.selectRegion")}</p>
 					)}
+					{zoomEnabled && hasCursorTelemetry && (
+						<div className="mt-3">
+							<span className="text-sm font-medium text-slate-200 mb-2 block">
+								{t("zoom.focusMode.title")}
+							</span>
+							<div className="grid grid-cols-2 gap-1.5">
+								{(["manual", "auto"] as const).map((mode) => {
+									const isActive = selectedZoomFocusMode === mode;
+									return (
+										<Button
+											key={mode}
+											type="button"
+											onClick={() => onZoomFocusModeChange?.(mode)}
+											className={cn(
+												"h-auto w-full rounded-lg border px-2 py-2 text-center shadow-sm transition-all",
+												"duration-200 ease-out cursor-pointer",
+												isActive
+													? "border-[#34B27B] bg-[#34B27B] text-white shadow-[#34B27B]/20"
+													: "border-white/5 bg-white/5 text-slate-400 hover:bg-white/10 hover:border-white/10 hover:text-slate-200",
+											)}
+										>
+											<span className="text-xs font-semibold capitalize">
+												{t(`zoom.focusMode.${mode}`)}
+											</span>
+										</Button>
+									);
+								})}
+							</div>
+							{selectedZoomFocusMode === "auto" && (
+								<p className="text-[10px] text-slate-500 mt-1.5">
+									{t("zoom.focusMode.autoDescription")}
+								</p>
+							)}
+						</div>
+					)}
 					{zoomEnabled && (
 						<Button
 							onClick={handleDeleteClick}
diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index 304d10f..91b51e5 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -56,6 +56,7 @@ import {
 	type TrimRegion,
 	type ZoomDepth,
 	type ZoomFocus,
+	type ZoomFocusMode,
 	type ZoomRegion,
 } from "./types";
 import VideoPlayback, { VideoPlaybackRef } from "./VideoPlayback";
@@ -688,6 +689,18 @@ export default function VideoEditor() {
 		[selectedZoomId, pushState],
 	);
 
+	const handleZoomFocusModeChange = useCallback(
+		(focusMode: ZoomFocusMode) => {
+			if (!selectedZoomId) return;
+			pushState((prev) => ({
+				zoomRegions: prev.zoomRegions.map((region) =>
+					region.id === selectedZoomId ? { ...region, focusMode } : region,
+				),
+			}));
+		},
+		[selectedZoomId, pushState],
+	);
+
 	const handleZoomDelete = useCallback(
 		(id: string) => {
 			pushState((prev) => ({ zoomRegions: prev.zoomRegions.filter((r) => r.id !== id) }));
@@ -1093,6 +1106,7 @@ export default function VideoEditor() {
 						webcamPosition,
 						previewWidth,
 						previewHeight,
+						cursorTelemetry,
 						onProgress: (progress: ExportProgress) => {
 							setExportProgress(progress);
 						},
@@ -1224,6 +1238,7 @@ export default function VideoEditor() {
 						webcamPosition,
 						previewWidth,
 						previewHeight,
+						cursorTelemetry,
 						onProgress: (progress: ExportProgress) => {
 							setExportProgress(progress);
 						},
@@ -1292,6 +1307,7 @@ export default function VideoEditor() {
 			webcamPosition,
 			exportQuality,
 			handleExportSaved,
+			cursorTelemetry,
 		],
 	);
 
@@ -1502,6 +1518,7 @@ export default function VideoEditor() {
 											onSelectAnnotation={handleSelectAnnotation}
 											onAnnotationPositionChange={handleAnnotationPositionChange}
 											onAnnotationSizeChange={handleAnnotationSizeChange}
+											cursorTelemetry={cursorTelemetry}
 										/>
 									</div>
 								</div>
@@ -1584,6 +1601,13 @@ export default function VideoEditor() {
 							selectedZoomId ? zoomRegions.find((z) => z.id === selectedZoomId)?.depth : null
 						}
 						onZoomDepthChange={(depth) => selectedZoomId && handleZoomDepthChange(depth)}
+						selectedZoomFocusMode={
+							selectedZoomId
+								? (zoomRegions.find((z) => z.id === selectedZoomId)?.focusMode ?? "manual")
+								: null
+						}
+						onZoomFocusModeChange={(mode) => selectedZoomId && handleZoomFocusModeChange(mode)}
+						hasCursorTelemetry={cursorTelemetry.length > 0}
 						selectedZoomId={selectedZoomId}
 						onZoomDelete={handleZoomDelete}
 						selectedTrimId={selectedTrimId}
diff --git a/src/components/video-editor/VideoPlayback.tsx b/src/components/video-editor/VideoPlayback.tsx
index 71030bb..8c2d120 100644
--- a/src/components/video-editor/VideoPlayback.tsx
+++ b/src/components/video-editor/VideoPlayback.tsx
@@ -41,10 +41,13 @@ import {
 	type ZoomRegion,
 } from "./types";
 import {
+	AUTO_FOLLOW_DEADZONE,
+	AUTO_FOLLOW_SMOOTHING_FACTOR,
 	DEFAULT_FOCUS,
 	ZOOM_SCALE_DEADZONE,
 	ZOOM_TRANSLATION_DEADZONE_PX,
 } from "./videoPlayback/constants";
+import { smoothCursorFocus } from "./videoPlayback/cursorFollowUtils";
 import { clampFocusToStage as clampFocusToStageUtil } from "./videoPlayback/focusUtils";
 import { layoutVideoContent as layoutVideoContentUtil } from "./videoPlayback/layoutUtils";
 import { clamp01 } from "./videoPlayback/mathUtils";
@@ -93,6 +96,7 @@ interface VideoPlaybackProps {
 	onSelectAnnotation?: (id: string | null) => void;
 	onAnnotationPositionChange?: (id: string, position: { x: number; y: number }) => void;
 	onAnnotationSizeChange?: (id: string, size: { width: number; height: number }) => void;
+	cursorTelemetry?: import("./types").CursorTelemetryPoint[];
 }
 
 export interface VideoPlaybackRef {
@@ -141,6 +145,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			onSelectAnnotation,
 			onAnnotationPositionChange,
 			onAnnotationSizeChange,
+			cursorTelemetry = [],
 		},
 		ref,
 	) => {
@@ -160,6 +165,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 		const [webcamDimensions, setWebcamDimensions] = useState<Size | null>(null);
 		const currentTimeRef = useRef(0);
 		const zoomRegionsRef = useRef<ZoomRegion[]>([]);
+		const cursorTelemetryRef = useRef<import("./types").CursorTelemetryPoint[]>([]);
 		const selectedZoomIdRef = useRef<string | null>(null);
 		const animationStateRef = useRef({
 			scale: 1,
@@ -194,6 +200,8 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 		const onTimeUpdateRef = useRef(onTimeUpdate);
 		const onPlayStateChangeRef = useRef(onPlayStateChange);
 		const videoReadyRafRef = useRef<number | null>(null);
+		const smoothedAutoFocusRef = useRef<ZoomFocus | null>(null);
+		const prevTargetProgressRef = useRef(0);
 
 		const clampFocusToStage = useCallback((focus: ZoomFocus, depth: ZoomDepth) => {
 			return clampFocusToStageUtil(focus, depth, stageSizeRef.current);
@@ -379,6 +387,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			if (!regionId) return;
 			const region = zoomRegionsRef.current.find((r) => r.id === regionId);
 			if (!region) return;
+			if (region.focusMode === "auto") return;
 			onSelectZoom(region.id);
 			event.preventDefault();
 			isDraggingFocusRef.current = true;
@@ -462,6 +471,10 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			zoomRegionsRef.current = zoomRegions;
 		}, [zoomRegions]);
 
+		useEffect(() => {
+			cursorTelemetryRef.current = cursorTelemetry;
+		}, [cursorTelemetry]);
+
 		useEffect(() => {
 			selectedZoomIdRef.current = selectedZoomId;
 		}, [selectedZoomId]);
@@ -833,7 +846,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 				const { region, strength, blendedScale, transition } = findDominantRegion(
 					zoomRegionsRef.current,
 					currentTimeRef.current,
-					{ connectZooms: true },
+					{ connectZooms: true, cursorTelemetry: cursorTelemetryRef.current },
 				);
 
 				const defaultFocus = DEFAULT_FOCUS;
@@ -854,6 +867,40 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 					targetFocus = regionFocus;
 					targetProgress = strength;
 
+					// Apply deadzone + smoothing for auto-follow mode
+					if (region.focusMode === "auto" && !transition) {
+						const raw = targetFocus;
+						const isZoomingIn =
+							targetProgress < 0.999 && targetProgress >= prevTargetProgressRef.current;
+						if (targetProgress >= 0.999) {
+							// Full zoom: apply deadzone + smoothing for stable follow
+							const prev = smoothedAutoFocusRef.current ?? raw;
+							const dx = Math.abs(raw.cx - prev.cx);
+							const dy = Math.abs(raw.cy - prev.cy);
+							if (dx > AUTO_FOLLOW_DEADZONE || dy > AUTO_FOLLOW_DEADZONE) {
+								const smoothed = smoothCursorFocus(raw, prev, AUTO_FOLLOW_SMOOTHING_FACTOR);
+								smoothedAutoFocusRef.current = smoothed;
+								targetFocus = smoothed;
+							} else {
+								smoothedAutoFocusRef.current = prev;
+								targetFocus = prev;
+							}
+						} else if (isZoomingIn) {
+							// Zoom-in: track cursor directly so zoom always aims at current cursor
+							// position; keep ref in sync to avoid snap when full-zoom begins
+							smoothedAutoFocusRef.current = raw;
+						} else {
+							// Zoom-out: keep smoothing for continuity — avoids snap at zoom-out start
+							const prev = smoothedAutoFocusRef.current ?? raw;
+							const smoothed = smoothCursorFocus(raw, prev, AUTO_FOLLOW_SMOOTHING_FACTOR);
+							smoothedAutoFocusRef.current = smoothed;
+							targetFocus = smoothed;
+						}
+					} else if (region.focusMode !== "auto") {
+						smoothedAutoFocusRef.current = null;
+					}
+					prevTargetProgressRef.current = targetProgress;
+
 					// Handle connected zoom transitions (pan between adjacent zoom regions)
 					if (transition) {
 						const startTransform = computeZoomTransform({
diff --git a/src/components/video-editor/projectPersistence.ts b/src/components/video-editor/projectPersistence.ts
index 99f1bba..856b9d3 100644
--- a/src/components/video-editor/projectPersistence.ts
+++ b/src/components/video-editor/projectPersistence.ts
@@ -189,6 +189,7 @@ export function normalizeProjectEditor(editor: Partial<ProjectEditorState>): Pro
 							cx: clamp(isFiniteNumber(region.focus?.cx) ? region.focus.cx : 0.5, 0, 1),
 							cy: clamp(isFiniteNumber(region.focus?.cy) ? region.focus.cy : 0.5, 0, 1),
 						},
+						focusMode: region.focusMode === "auto" ? "auto" : "manual",
 					};
 				})
 		: [];
diff --git a/src/components/video-editor/types.ts b/src/components/video-editor/types.ts
index ce49f8e..552f2cc 100644
--- a/src/components/video-editor/types.ts
+++ b/src/components/video-editor/types.ts
@@ -1,6 +1,7 @@
 import type { WebcamLayoutPreset } from "@/lib/compositeLayout";
 
 export type ZoomDepth = 1 | 2 | 3 | 4 | 5 | 6;
+export type ZoomFocusMode = "manual" | "auto";
 export type { WebcamLayoutPreset };
 
 export const DEFAULT_WEBCAM_LAYOUT_PRESET: WebcamLayoutPreset = "picture-in-picture";
@@ -23,6 +24,7 @@ export interface ZoomRegion {
 	endMs: number;
 	depth: ZoomDepth;
 	focus: ZoomFocus;
+	focusMode?: ZoomFocusMode;
 }
 
 export interface CursorTelemetryPoint {
diff --git a/src/components/video-editor/videoPlayback/constants.ts b/src/components/video-editor/videoPlayback/constants.ts
index 83ff8d2..1c41cb7 100644
--- a/src/components/video-editor/videoPlayback/constants.ts
+++ b/src/components/video-editor/videoPlayback/constants.ts
@@ -8,3 +8,5 @@ export const VIEWPORT_SCALE = 0.8;
 export const SMOOTHING_FACTOR = 0.12;
 export const ZOOM_TRANSLATION_DEADZONE_PX = 1.25;
 export const ZOOM_SCALE_DEADZONE = 0.002;
+export const AUTO_FOLLOW_SMOOTHING_FACTOR = 0.05;
+export const AUTO_FOLLOW_DEADZONE = 0.06;
diff --git a/src/components/video-editor/videoPlayback/cursorFollowUtils.ts b/src/components/video-editor/videoPlayback/cursorFollowUtils.ts
new file mode 100644
index 0000000..9c92c25
--- /dev/null
+++ b/src/components/video-editor/videoPlayback/cursorFollowUtils.ts
@@ -0,0 +1,54 @@
+import type { CursorTelemetryPoint, ZoomFocus } from "../types";
+
+/**
+ * Binary-search the sorted telemetry array and linearly interpolate
+ * the cursor position at the given playback time.
+ */
+export function interpolateCursorAt(
+	telemetry: CursorTelemetryPoint[],
+	timeMs: number,
+): ZoomFocus | null {
+	if (telemetry.length === 0) return null;
+
+	if (timeMs <= telemetry[0].timeMs) {
+		return { cx: telemetry[0].cx, cy: telemetry[0].cy };
+	}
+
+	const last = telemetry[telemetry.length - 1];
+	if (timeMs >= last.timeMs) {
+		return { cx: last.cx, cy: last.cy };
+	}
+
+	let lo = 0;
+	let hi = telemetry.length - 1;
+
+	while (lo < hi - 1) {
+		const mid = (lo + hi) >>> 1;
+		if (telemetry[mid].timeMs <= timeMs) {
+			lo = mid;
+		} else {
+			hi = mid;
+		}
+	}
+
+	const before = telemetry[lo];
+	const after = telemetry[hi];
+	const span = after.timeMs - before.timeMs;
+	const t = span > 0 ? (timeMs - before.timeMs) / span : 0;
+
+	return {
+		cx: before.cx + (after.cx - before.cx) * t,
+		cy: before.cy + (after.cy - before.cy) * t,
+	};
+}
+
+/**
+ * Exponential smoothing to reduce jitter from high-frequency cursor data.
+ * Lower factor = smoother / more lag, higher = more responsive.
+ */
+export function smoothCursorFocus(raw: ZoomFocus, prev: ZoomFocus, factor: number): ZoomFocus {
+	return {
+		cx: prev.cx + (raw.cx - prev.cx) * factor,
+		cy: prev.cy + (raw.cy - prev.cy) * factor,
+	};
+}
diff --git a/src/components/video-editor/videoPlayback/overlayUtils.ts b/src/components/video-editor/videoPlayback/overlayUtils.ts
index b08ee7a..0426a23 100644
--- a/src/components/video-editor/videoPlayback/overlayUtils.ts
+++ b/src/components/video-editor/videoPlayback/overlayUtils.ts
@@ -14,7 +14,7 @@ interface OverlayUpdateParams {
 export function updateOverlayIndicator(params: OverlayUpdateParams) {
 	const { overlayEl, indicatorEl, region, focusOverride, videoSize, baseScale, isPlaying } = params;
 
-	if (!region) {
+	if (!region || region.focusMode === "auto") {
 		indicatorEl.style.display = "none";
 		overlayEl.style.pointerEvents = "none";
 		return;
diff --git a/src/components/video-editor/videoPlayback/zoomRegionUtils.ts b/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
index 3ceace8..3f8a132 100644
--- a/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
+++ b/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
@@ -1,6 +1,7 @@
-import type { ZoomFocus, ZoomRegion } from "../types";
+import type { CursorTelemetryPoint, ZoomFocus, ZoomRegion } from "../types";
 import { ZOOM_DEPTH_SCALES } from "../types";
 import { TRANSITION_WINDOW_MS, ZOOM_IN_TRANSITION_WINDOW_MS } from "./constants";
+import { interpolateCursorAt } from "./cursorFollowUtils";
 import { clampFocusToScale } from "./focusUtils";
 import { clamp01, cubicBezier, easeOutScreenStudio } from "./mathUtils";
 
@@ -10,6 +11,7 @@ const ZOOM_IN_OVERLAP_MS = 500;
 
 type DominantRegionOptions = {
 	connectZooms?: boolean;
+	cursorTelemetry?: CursorTelemetryPoint[];
 };
 
 type ConnectedRegionPair = {
@@ -64,8 +66,27 @@ function getLinearFocus(start: ZoomFocus, end: ZoomFocus, amount: number): ZoomF
 	};
 }
 
-function getResolvedFocus(region: ZoomRegion, zoomScale: number): ZoomFocus {
-	return clampFocusToScale(region.focus, zoomScale);
+function getResolvedFocus(
+	region: ZoomRegion,
+	zoomScale: number,
+	timeMs?: number,
+	cursorTelemetry?: CursorTelemetryPoint[],
+): ZoomFocus {
+	let focus = region.focus;
+
+	if (
+		region.focusMode === "auto" &&
+		cursorTelemetry &&
+		cursorTelemetry.length > 0 &&
+		timeMs !== undefined
+	) {
+		const cursorFocus = interpolateCursorAt(cursorTelemetry, timeMs);
+		if (cursorFocus) {
+			focus = cursorFocus;
+		}
+	}
+
+	return clampFocusToScale(focus, zoomScale);
 }
 
 function getConnectedRegionPairs(regions: ZoomRegion[]) {
@@ -96,6 +117,7 @@ function getActiveRegion(
 	regions: ZoomRegion[],
 	timeMs: number,
 	connectedPairs: ConnectedRegionPair[],
+	cursorTelemetry?: CursorTelemetryPoint[],
 ) {
 	const activeRegions = regions
 		.map((region) => {
@@ -130,21 +152,25 @@ function getActiveRegion(
 	return {
 		region: {
 			...activeRegion,
-			focus: getResolvedFocus(activeRegion, activeScale),
+			focus: getResolvedFocus(activeRegion, activeScale, timeMs, cursorTelemetry),
 		},
 		strength: activeRegions[0].strength,
 		blendedScale: null,
 	};
 }
 
-function getConnectedRegionHold(timeMs: number, connectedPairs: ConnectedRegionPair[]) {
+function getConnectedRegionHold(
+	timeMs: number,
+	connectedPairs: ConnectedRegionPair[],
+	cursorTelemetry?: CursorTelemetryPoint[],
+) {
 	for (const pair of connectedPairs) {
 		if (timeMs > pair.transitionEnd && timeMs < pair.nextRegion.startMs) {
 			const nextScale = ZOOM_DEPTH_SCALES[pair.nextRegion.depth];
 			return {
 				region: {
 					...pair.nextRegion,
-					focus: getResolvedFocus(pair.nextRegion, nextScale),
+					focus: getResolvedFocus(pair.nextRegion, nextScale, timeMs, cursorTelemetry),
 				},
 				strength: 1,
 				blendedScale: null,
@@ -155,7 +181,11 @@ function getConnectedRegionHold(timeMs: number, connectedPairs: ConnectedRegionP
 	return null;
 }
 
-function getConnectedRegionTransition(connectedPairs: ConnectedRegionPair[], timeMs: number) {
+function getConnectedRegionTransition(
+	connectedPairs: ConnectedRegionPair[],
+	timeMs: number,
+	cursorTelemetry?: CursorTelemetryPoint[],
+) {
 	for (const pair of connectedPairs) {
 		const { currentRegion, nextRegion, transitionStart, transitionEnd } = pair;
 
@@ -169,8 +199,8 @@ function getConnectedRegionTransition(connectedPairs: ConnectedRegionPair[], tim
 		const currentScale = ZOOM_DEPTH_SCALES[currentRegion.depth];
 		const nextScale = ZOOM_DEPTH_SCALES[nextRegion.depth];
 		const transitionScale = lerp(currentScale, nextScale, transitionProgress);
-		const currentFocus = getResolvedFocus(currentRegion, currentScale);
-		const nextFocus = getResolvedFocus(nextRegion, nextScale);
+		const currentFocus = getResolvedFocus(currentRegion, currentScale, timeMs, cursorTelemetry);
+		const nextFocus = getResolvedFocus(nextRegion, nextScale, timeMs, cursorTelemetry);
 		const transitionFocus = getLinearFocus(currentFocus, nextFocus, transitionProgress);
 
 		return {
@@ -204,20 +234,21 @@ export function findDominantRegion(
 	transition: ConnectedPanTransition | null;
 } {
 	const connectedPairs = options.connectZooms ? getConnectedRegionPairs(regions) : [];
+	const telemetry = options.cursorTelemetry;
 
 	if (options.connectZooms) {
-		const connectedTransition = getConnectedRegionTransition(connectedPairs, timeMs);
+		const connectedTransition = getConnectedRegionTransition(connectedPairs, timeMs, telemetry);
 		if (connectedTransition) {
 			return connectedTransition;
 		}
 
-		const connectedHold = getConnectedRegionHold(timeMs, connectedPairs);
+		const connectedHold = getConnectedRegionHold(timeMs, connectedPairs, telemetry);
 		if (connectedHold) {
 			return { ...connectedHold, transition: null };
 		}
 	}
 
-	const activeRegion = getActiveRegion(regions, timeMs, connectedPairs);
+	const activeRegion = getActiveRegion(regions, timeMs, connectedPairs, telemetry);
 	return activeRegion
 		? { ...activeRegion, transition: null }
 		: { region: null, strength: 0, blendedScale: null, transition: null };
diff --git a/src/i18n/locales/en/settings.json b/src/i18n/locales/en/settings.json
index 36b7462..2ba0e58 100644
--- a/src/i18n/locales/en/settings.json
+++ b/src/i18n/locales/en/settings.json
@@ -2,7 +2,13 @@
 	"zoom": {
 		"level": "Zoom Level",
 		"selectRegion": "Select a zoom region to adjust",
-		"deleteZoom": "Delete Zoom"
+		"deleteZoom": "Delete Zoom",
+		"focusMode": {
+			"title": "Focus Mode",
+			"manual": "Manual",
+			"auto": "Auto",
+			"autoDescription": "Camera follows the recorded cursor position"
+		}
 	},
 	"speed": {
 		"playbackSpeed": "Playback Speed",
diff --git a/src/i18n/locales/es/settings.json b/src/i18n/locales/es/settings.json
index 4674480..8e0607b 100644
--- a/src/i18n/locales/es/settings.json
+++ b/src/i18n/locales/es/settings.json
@@ -2,7 +2,13 @@
 	"zoom": {
 		"level": "Nivel de zoom",
 		"selectRegion": "Selecciona una región de zoom para ajustar",
-		"deleteZoom": "Eliminar zoom"
+		"deleteZoom": "Eliminar zoom",
+		"focusMode": {
+			"title": "Modo de enfoque",
+			"manual": "Manual",
+			"auto": "Auto",
+			"autoDescription": "La cámara sigue la posición del cursor grabado"
+		}
 	},
 	"speed": {
 		"playbackSpeed": "Velocidad de reproducción",
diff --git a/src/i18n/locales/zh-CN/settings.json b/src/i18n/locales/zh-CN/settings.json
index 41bf55b..9b62e4a 100644
--- a/src/i18n/locales/zh-CN/settings.json
+++ b/src/i18n/locales/zh-CN/settings.json
@@ -2,7 +2,13 @@
 	"zoom": {
 		"level": "缩放级别",
 		"selectRegion": "选择要调整的缩放区域",
-		"deleteZoom": "删除缩放"
+		"deleteZoom": "删除缩放",
+		"focusMode": {
+			"title": "对焦模式",
+			"manual": "手动",
+			"auto": "自动",
+			"autoDescription": "摄像头跟随录制时的光标位置"
+		}
 	},
 	"speed": {
 		"playbackSpeed": "播放速度",
diff --git a/src/lib/exporter/frameRenderer.ts b/src/lib/exporter/frameRenderer.ts
index 4a9b2bd..d08705d 100644
--- a/src/lib/exporter/frameRenderer.ts
+++ b/src/lib/exporter/frameRenderer.ts
@@ -18,10 +18,13 @@ import type {
 } from "@/components/video-editor/types";
 import { ZOOM_DEPTH_SCALES } from "@/components/video-editor/types";
 import {
+	AUTO_FOLLOW_DEADZONE,
+	AUTO_FOLLOW_SMOOTHING_FACTOR,
 	DEFAULT_FOCUS,
 	ZOOM_SCALE_DEADZONE,
 	ZOOM_TRANSLATION_DEADZONE_PX,
 } from "@/components/video-editor/videoPlayback/constants";
+import { smoothCursorFocus } from "@/components/video-editor/videoPlayback/cursorFollowUtils";
 import { clampFocusToStage as clampFocusToStageUtil } from "@/components/video-editor/videoPlayback/focusUtils";
 import { findDominantRegion } from "@/components/video-editor/videoPlayback/zoomRegionUtils";
 import {
@@ -66,6 +69,7 @@ interface FrameRenderConfig {
 	speedRegions?: SpeedRegion[];
 	previewWidth?: number;
 	previewHeight?: number;
+	cursorTelemetry?: import("@/components/video-editor/types").CursorTelemetryPoint[];
 }
 
 interface AnimationState {
@@ -107,6 +111,9 @@ export class FrameRenderer {
 	private layoutCache: LayoutCache | null = null;
 	private currentVideoTime = 0;
 	private motionBlurState: MotionBlurState = createMotionBlurState();
+	private smoothedAutoFocus: { cx: number; cy: number } | null = null;
+	private prevAnimationTimeMs: number | null = null;
+	private prevTargetProgress = 0;
 
 	constructor(config: FrameRenderConfig) {
 		this.config = config;
@@ -511,7 +518,7 @@ export class FrameRenderer {
 		const { region, strength, blendedScale, transition } = findDominantRegion(
 			this.config.zoomRegions,
 			timeMs,
-			{ connectZooms: true },
+			{ connectZooms: true, cursorTelemetry: this.config.cursorTelemetry },
 		);
 
 		const defaultFocus = DEFAULT_FOCUS;
@@ -527,6 +534,42 @@ export class FrameRenderer {
 			targetFocus = regionFocus;
 			targetProgress = strength;
 
+			// Apply deadzone + time-based smoothing for auto-follow mode
+			if (region.focusMode === "auto" && !transition) {
+				const raw = targetFocus;
+				const dtMs = this.prevAnimationTimeMs != null ? timeMs - this.prevAnimationTimeMs : 0;
+				const framesElapsed = dtMs > 0 ? dtMs / (1000 / 60) : 1;
+				const factor = 1 - Math.pow(1 - AUTO_FOLLOW_SMOOTHING_FACTOR, Math.max(1, framesElapsed));
+				const isZoomingIn = targetProgress < 0.999 && targetProgress >= this.prevTargetProgress;
+				if (targetProgress >= 0.999) {
+					// Full zoom: apply deadzone + smoothing for stable follow
+					const prev = this.smoothedAutoFocus ?? raw;
+					const dx = Math.abs(raw.cx - prev.cx);
+					const dy = Math.abs(raw.cy - prev.cy);
+					if (dx > AUTO_FOLLOW_DEADZONE || dy > AUTO_FOLLOW_DEADZONE) {
+						const smoothed = smoothCursorFocus(raw, prev, factor);
+						this.smoothedAutoFocus = smoothed;
+						targetFocus = smoothed;
+					} else {
+						this.smoothedAutoFocus = prev;
+						targetFocus = prev;
+					}
+				} else if (isZoomingIn) {
+					// Zoom-in: track cursor directly so zoom always aims at current cursor
+					// position; keep ref in sync to avoid snap when full-zoom begins
+					this.smoothedAutoFocus = raw;
+				} else {
+					// Zoom-out: keep smoothing for continuity — avoids snap at zoom-out start
+					const prev = this.smoothedAutoFocus ?? raw;
+					const smoothed = smoothCursorFocus(raw, prev, factor);
+					this.smoothedAutoFocus = smoothed;
+					targetFocus = smoothed;
+				}
+			} else if (region.focusMode !== "auto") {
+				this.smoothedAutoFocus = null;
+			}
+			this.prevTargetProgress = targetProgress;
+
 			if (transition) {
 				const startTransform = computeZoomTransform({
 					stageSize: this.layoutCache.stageSize,
@@ -602,6 +645,8 @@ export class FrameRenderer {
 		state.y = appliedY;
 		state.appliedScale = appliedScale;
 
+		this.prevAnimationTimeMs = timeMs;
+
 		return Math.max(
 			Math.abs(appliedScale - prevScale),
 			Math.abs(appliedX - prevX) / Math.max(1, this.layoutCache.stageSize.width),
diff --git a/src/lib/exporter/gifExporter.ts b/src/lib/exporter/gifExporter.ts
index 8aac0b5..eb9ed36 100644
--- a/src/lib/exporter/gifExporter.ts
+++ b/src/lib/exporter/gifExporter.ts
@@ -45,6 +45,7 @@ interface GifExporterConfig {
 	annotationRegions?: AnnotationRegion[];
 	previewWidth?: number;
 	previewHeight?: number;
+	cursorTelemetry?: import("@/components/video-editor/types").CursorTelemetryPoint[];
 	onProgress?: (progress: ExportProgress) => void;
 }
 
@@ -146,6 +147,7 @@ export class GifExporter {
 				speedRegions: this.config.speedRegions,
 				previewWidth: this.config.previewWidth,
 				previewHeight: this.config.previewHeight,
+				cursorTelemetry: this.config.cursorTelemetry,
 			});
 			await this.renderer.initialize();
 
diff --git a/src/lib/exporter/videoExporter.ts b/src/lib/exporter/videoExporter.ts
index 1b75a2e..7313f91 100644
--- a/src/lib/exporter/videoExporter.ts
+++ b/src/lib/exporter/videoExporter.ts
@@ -36,6 +36,7 @@ interface VideoExporterConfig extends ExportConfig {
 	annotationRegions?: AnnotationRegion[];
 	previewWidth?: number;
 	previewHeight?: number;
+	cursorTelemetry?: import("@/components/video-editor/types").CursorTelemetryPoint[];
 	onProgress?: (progress: ExportProgress) => void;
 }
 
@@ -139,6 +140,7 @@ export class VideoExporter {
 				speedRegions: this.config.speedRegions,
 				previewWidth: this.config.previewWidth,
 				previewHeight: this.config.previewHeight,
+				cursorTelemetry: this.config.cursorTelemetry,
 			});
 			this.renderer = renderer;
 			await renderer.initialize();

From 163b12d6fc131e5f1b9db742a044c22d439467ce Mon Sep 17 00:00:00 2001
From: xKeCo <kevcollazos@gmail.com>
Date: Wed, 1 Apr 2026 02:38:42 -0500
Subject: [PATCH 02/20] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20refactor?=
 =?UTF-8?q?=20zoom=20focus=20handling=20in=20video=20editor=20settings=20a?=
 =?UTF-8?q?nd=20playback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/components/video-editor/SettingsPanel.tsx   |  5 +++--
 .../videoPlayback/zoomRegionUtils.ts            | 17 +++++++++++++++--
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/src/components/video-editor/SettingsPanel.tsx b/src/components/video-editor/SettingsPanel.tsx
index bec50c2..bc7ebb0 100644
--- a/src/components/video-editor/SettingsPanel.tsx
+++ b/src/components/video-editor/SettingsPanel.tsx
@@ -52,6 +52,7 @@ import type {
 	PlaybackSpeed,
 	WebcamLayoutPreset,
 	ZoomDepth,
+	ZoomFocusMode,
 } from "./types";
 import { SPEED_OPTIONS } from "./types";
 
@@ -92,8 +93,8 @@ interface SettingsPanelProps {
 	onWallpaperChange: (path: string) => void;
 	selectedZoomDepth?: ZoomDepth | null;
 	onZoomDepthChange?: (depth: ZoomDepth) => void;
-	selectedZoomFocusMode?: import("./types").ZoomFocusMode | null;
-	onZoomFocusModeChange?: (mode: import("./types").ZoomFocusMode) => void;
+	selectedZoomFocusMode?: ZoomFocusMode | null;
+	onZoomFocusModeChange?: (mode: ZoomFocusMode) => void;
 	hasCursorTelemetry?: boolean;
 	selectedZoomId?: string | null;
 	onZoomDelete?: (id: string) => void;
diff --git a/src/components/video-editor/videoPlayback/zoomRegionUtils.ts b/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
index 3f8a132..8543907 100644
--- a/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
+++ b/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
@@ -199,8 +199,21 @@ function getConnectedRegionTransition(
 		const currentScale = ZOOM_DEPTH_SCALES[currentRegion.depth];
 		const nextScale = ZOOM_DEPTH_SCALES[nextRegion.depth];
 		const transitionScale = lerp(currentScale, nextScale, transitionProgress);
-		const currentFocus = getResolvedFocus(currentRegion, currentScale, timeMs, cursorTelemetry);
-		const nextFocus = getResolvedFocus(nextRegion, nextScale, timeMs, cursorTelemetry);
+		// Both regions share the same timeMs, so interpolate cursor once and reuse.
+		const sharedCursorFocus =
+			cursorTelemetry && cursorTelemetry.length > 0
+				? interpolateCursorAt(cursorTelemetry, timeMs)
+				: null;
+		const currentFocus = clampFocusToScale(
+			currentRegion.focusMode === "auto" && sharedCursorFocus
+				? sharedCursorFocus
+				: currentRegion.focus,
+			currentScale,
+		);
+		const nextFocus = clampFocusToScale(
+			nextRegion.focusMode === "auto" && sharedCursorFocus ? sharedCursorFocus : nextRegion.focus,
+			nextScale,
+		);
 		const transitionFocus = getLinearFocus(currentFocus, nextFocus, transitionProgress);
 
 		return {

From 5c6621293a9a70a79f06555f9c39def029304f1d Mon Sep 17 00:00:00 2001
From: xKeCo <kevcollazos@gmail.com>
Date: Wed, 1 Apr 2026 02:51:25 -0500
Subject: [PATCH 03/20] demo: add example project file for auto-follow zoom

Contains the zoom region configuration used in the PR demo video:
two auto-follow zoom regions and one manual zoom region.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 demo/auto-follow-zoom-example.openscreen | 65 ++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 demo/auto-follow-zoom-example.openscreen

diff --git a/demo/auto-follow-zoom-example.openscreen b/demo/auto-follow-zoom-example.openscreen
new file mode 100644
index 0000000..810eab7
--- /dev/null
+++ b/demo/auto-follow-zoom-example.openscreen
@@ -0,0 +1,65 @@
+{
+  "version": 2,
+  "media": {
+    "screenVideoPath": "/Users/kevincollazos/Library/Application Support/openscreen/recordings/recording-1775028565988.webm"
+  },
+  "editor": {
+    "wallpaper": "/wallpapers/wallpaper1.jpg",
+    "shadowIntensity": 0,
+    "showBlur": false,
+    "motionBlurAmount": 0.12,
+    "borderRadius": 11,
+    "padding": 50,
+    "cropRegion": {
+      "x": 0,
+      "y": 0,
+      "width": 1,
+      "height": 1
+    },
+    "zoomRegions": [
+      {
+        "id": "zoom-1",
+        "startMs": 3800,
+        "endMs": 13466,
+        "depth": 3,
+        "focus": {
+          "cx": 0.5,
+          "cy": 0.5
+        },
+        "focusMode": "auto"
+      },
+      {
+        "id": "zoom-2",
+        "startMs": 15489,
+        "endMs": 19229,
+        "depth": 3,
+        "focus": {
+          "cx": 0.5,
+          "cy": 0.5
+        },
+        "focusMode": "auto"
+      },
+      {
+        "id": "zoom-3",
+        "startMs": 21480,
+        "endMs": 22194,
+        "depth": 3,
+        "focus": {
+          "cx": 0.5,
+          "cy": 0.5
+        }
+      }
+    ],
+    "trimRegions": [],
+    "speedRegions": [],
+    "annotationRegions": [],
+    "aspectRatio": "16:9",
+    "webcamLayoutPreset": "picture-in-picture",
+    "webcamPosition": null,
+    "exportQuality": "source",
+    "exportFormat": "mp4",
+    "gifFrameRate": 15,
+    "gifLoop": true,
+    "gifSizePreset": "medium"
+  }
+}
\ No newline at end of file

From 05a87a8ab12fe71ee020b75335e46dea45eda69e Mon Sep 17 00:00:00 2001
From: xKeCo <kevcollazos@gmail.com>
Date: Wed, 1 Apr 2026 02:53:03 -0500
Subject: [PATCH 04/20] Revert "demo: add example project file for auto-follow
 zoom"

This reverts commit 5c6621293a9a70a79f06555f9c39def029304f1d.
---
 demo/auto-follow-zoom-example.openscreen | 65 ------------------------
 1 file changed, 65 deletions(-)
 delete mode 100644 demo/auto-follow-zoom-example.openscreen

diff --git a/demo/auto-follow-zoom-example.openscreen b/demo/auto-follow-zoom-example.openscreen
deleted file mode 100644
index 810eab7..0000000
--- a/demo/auto-follow-zoom-example.openscreen
+++ /dev/null
@@ -1,65 +0,0 @@
-{
-  "version": 2,
-  "media": {
-    "screenVideoPath": "/Users/kevincollazos/Library/Application Support/openscreen/recordings/recording-1775028565988.webm"
-  },
-  "editor": {
-    "wallpaper": "/wallpapers/wallpaper1.jpg",
-    "shadowIntensity": 0,
-    "showBlur": false,
-    "motionBlurAmount": 0.12,
-    "borderRadius": 11,
-    "padding": 50,
-    "cropRegion": {
-      "x": 0,
-      "y": 0,
-      "width": 1,
-      "height": 1
-    },
-    "zoomRegions": [
-      {
-        "id": "zoom-1",
-        "startMs": 3800,
-        "endMs": 13466,
-        "depth": 3,
-        "focus": {
-          "cx": 0.5,
-          "cy": 0.5
-        },
-        "focusMode": "auto"
-      },
-      {
-        "id": "zoom-2",
-        "startMs": 15489,
-        "endMs": 19229,
-        "depth": 3,
-        "focus": {
-          "cx": 0.5,
-          "cy": 0.5
-        },
-        "focusMode": "auto"
-      },
-      {
-        "id": "zoom-3",
-        "startMs": 21480,
-        "endMs": 22194,
-        "depth": 3,
-        "focus": {
-          "cx": 0.5,
-          "cy": 0.5
-        }
-      }
-    ],
-    "trimRegions": [],
-    "speedRegions": [],
-    "annotationRegions": [],
-    "aspectRatio": "16:9",
-    "webcamLayoutPreset": "picture-in-picture",
-    "webcamPosition": null,
-    "exportQuality": "source",
-    "exportFormat": "mp4",
-    "gifFrameRate": 15,
-    "gifLoop": true,
-    "gifSizePreset": "medium"
-  }
-}
\ No newline at end of file

From 914a3c7f7b7434ead4a02a9fb41edb7037b1fc90 Mon Sep 17 00:00:00 2001
From: Faga <faga@retize.com.br>
Date: Thu, 2 Apr 2026 11:55:21 -0300
Subject: [PATCH 05/20] fix: read raw pixels from canvas for VideoFrame to
 avoid silent failures on Linux

---
 src/lib/exporter/videoExporter.ts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/lib/exporter/videoExporter.ts b/src/lib/exporter/videoExporter.ts
index 1b75a2e..efdfcfb 100644
--- a/src/lib/exporter/videoExporter.ts
+++ b/src/lib/exporter/videoExporter.ts
@@ -230,8 +230,16 @@ export class VideoExporter {
 
 						const canvas = renderer.getCanvas();
 
-						// @ts-expect-error - colorSpace is available at runtime even if TS does not know it.
-						const exportFrame = new VideoFrame(canvas, {
+						// Read raw pixels from the canvas instead of passing
+						// the canvas directly to VideoFrame. On some Linux
+						// systems the GPU shared-image path (EGL/Ozone) fails
+						// silently, producing empty frames.
+						const canvasCtx = canvas.getContext("2d")!;
+						const imageData = canvasCtx.getImageData(0, 0, canvas.width, canvas.height);
+						const exportFrame = new VideoFrame(imageData.data.buffer, {
+							format: "RGBA",
+							codedWidth: canvas.width,
+							codedHeight: canvas.height,
 							timestamp,
 							duration: frameDuration,
 							colorSpace: {

From 9d0ccf3bde683630e53261db6dc80acb7cb775e0 Mon Sep 17 00:00:00 2001
From: Ivan <ivantgam@gmail.com>
Date: Fri, 3 Apr 2026 00:09:51 +0300
Subject: [PATCH 06/20] Add webcam mask shape support

---
 src/components/video-editor/SettingsPanel.tsx | 86 +++++++++++++++++++
 src/components/video-editor/VideoEditor.tsx   | 12 +++
 src/components/video-editor/VideoPlayback.tsx | 71 +++++++++------
 .../video-editor/projectPersistence.test.ts   |  9 ++
 .../video-editor/projectPersistence.ts        | 10 +++
 src/components/video-editor/types.ts          |  4 +
 .../video-editor/videoPlayback/layoutUtils.ts |  5 +-
 src/hooks/useEditorHistory.ts                 |  4 +
 src/i18n/locales/en/settings.json             |  3 +-
 src/i18n/locales/es/settings.json             |  3 +-
 src/i18n/locales/zh-CN/settings.json          |  3 +-
 src/lib/compositeLayout.test.ts               | 74 +++++++++++++---
 src/lib/compositeLayout.ts                    | 39 +++++++--
 src/lib/exporter/frameRenderer.ts             | 10 ++-
 src/lib/exporter/gifExporter.ts               |  2 +
 src/lib/exporter/videoExporter.ts             |  2 +
 src/lib/webcamMaskShapes.ts                   | 48 +++++++++++
 17 files changed, 330 insertions(+), 55 deletions(-)
 create mode 100644 src/lib/webcamMaskShapes.ts

diff --git a/src/components/video-editor/SettingsPanel.tsx b/src/components/video-editor/SettingsPanel.tsx
index f5afe35..50f2d9c 100644
--- a/src/components/video-editor/SettingsPanel.tsx
+++ b/src/components/video-editor/SettingsPanel.tsx
@@ -51,6 +51,7 @@ import type {
 	FigureData,
 	PlaybackSpeed,
 	WebcamLayoutPreset,
+	WebcamMaskShape,
 	ZoomDepth,
 } from "./types";
 import { SPEED_OPTIONS } from "./types";
@@ -143,6 +144,8 @@ interface SettingsPanelProps {
 	hasWebcam?: boolean;
 	webcamLayoutPreset?: WebcamLayoutPreset;
 	onWebcamLayoutPresetChange?: (preset: WebcamLayoutPreset) => void;
+	webcamMaskShape?: import("./types").WebcamMaskShape;
+	onWebcamMaskShapeChange?: (shape: import("./types").WebcamMaskShape) => void;
 }
 
 export default SettingsPanel;
@@ -211,6 +214,8 @@ export function SettingsPanel({
 	hasWebcam = false,
 	webcamLayoutPreset = "picture-in-picture",
 	onWebcamLayoutPresetChange,
+	webcamMaskShape = "rectangle",
+	onWebcamMaskShapeChange,
 }: SettingsPanelProps) {
 	const t = useScopedT("settings");
 	const [wallpaperPaths, setWallpaperPaths] = useState<string[]>([]);
@@ -623,6 +628,87 @@ export function SettingsPanel({
 										</SelectContent>
 									</Select>
 								</div>
+								{webcamLayoutPreset === "picture-in-picture" && (
+									<div className="mt-2 p-2 rounded-lg bg-white/5 border border-white/5">
+										<div className="text-[10px] font-medium text-slate-300 mb-1.5">
+											{t("layout.webcamShape")}
+										</div>
+										<div className="grid grid-cols-4 gap-1.5">
+											{(
+												[
+													{ value: "rectangle", label: "Rect" },
+													{ value: "circle", label: "Circle" },
+													{ value: "square", label: "Square" },
+													{ value: "rounded", label: "Rounded" },
+												] as Array<{ value: WebcamMaskShape; label: string }>
+											).map((shape) => (
+												<button
+													key={shape.value}
+													type="button"
+													onClick={() => onWebcamMaskShapeChange?.(shape.value)}
+													className={cn(
+														"h-10 rounded-lg border flex flex-col items-center justify-center gap-0.5 transition-all",
+														webcamMaskShape === shape.value
+															? "bg-[#34B27B] border-[#34B27B] text-white"
+															: "bg-white/5 border-white/10 hover:bg-white/10 hover:border-white/20 text-slate-400",
+													)}
+												>
+													<svg
+														width="16"
+														height="16"
+														viewBox="0 0 16 16"
+														fill="none"
+														xmlns="http://www.w3.org/2000/svg"
+													>
+														{shape.value === "rectangle" && (
+															<rect
+																x="1"
+																y="3"
+																width="14"
+																height="10"
+																rx="2"
+																stroke="currentColor"
+																strokeWidth="1.5"
+															/>
+														)}
+														{shape.value === "circle" && (
+															<circle
+																cx="8"
+																cy="8"
+																r="6.5"
+																stroke="currentColor"
+																strokeWidth="1.5"
+															/>
+														)}
+														{shape.value === "square" && (
+															<rect
+																x="2"
+																y="2"
+																width="12"
+																height="12"
+																rx="1"
+																stroke="currentColor"
+																strokeWidth="1.5"
+															/>
+														)}
+														{shape.value === "rounded" && (
+															<rect
+																x="1"
+																y="3"
+																width="14"
+																height="10"
+																rx="5"
+																stroke="currentColor"
+																strokeWidth="1.5"
+															/>
+														)}
+													</svg>
+													<span className="text-[8px] leading-none">{shape.label}</span>
+												</button>
+											))}
+										</div>
+									</div>
+								)}
 							</AccordionContent>
 						</AccordionItem>
 					)}
diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index 304d10f..469f892 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -84,6 +84,7 @@ export default function VideoEditor() {
 		padding,
 		aspectRatio,
 		webcamLayoutPreset,
+		webcamMaskShape,
 		webcamPosition,
 	} = editorState;
 
@@ -195,6 +196,7 @@ export default function VideoEditor() {
 				annotationRegions: normalizedEditor.annotationRegions,
 				aspectRatio: normalizedEditor.aspectRatio,
 				webcamLayoutPreset: normalizedEditor.webcamLayoutPreset,
+				webcamMaskShape: normalizedEditor.webcamMaskShape,
 				webcamPosition: normalizedEditor.webcamPosition,
 			});
 			setExportQuality(normalizedEditor.exportQuality);
@@ -264,6 +266,7 @@ export default function VideoEditor() {
 				annotationRegions,
 				aspectRatio,
 				webcamLayoutPreset,
+				webcamMaskShape,
 				webcamPosition,
 				exportQuality,
 				exportFormat,
@@ -287,6 +290,7 @@ export default function VideoEditor() {
 		annotationRegions,
 		aspectRatio,
 		webcamLayoutPreset,
+		webcamMaskShape,
 		webcamPosition,
 		exportQuality,
 		exportFormat,
@@ -380,6 +384,7 @@ export default function VideoEditor() {
 				annotationRegions,
 				aspectRatio,
 				webcamLayoutPreset,
+				webcamMaskShape,
 				webcamPosition,
 				exportQuality,
 				exportFormat,
@@ -434,6 +439,7 @@ export default function VideoEditor() {
 			annotationRegions,
 			aspectRatio,
 			webcamLayoutPreset,
+			webcamMaskShape,
 			webcamPosition,
 			exportQuality,
 			exportFormat,
@@ -1090,6 +1096,7 @@ export default function VideoEditor() {
 						cropRegion,
 						annotationRegions,
 						webcamLayoutPreset,
+						webcamMaskShape,
 						webcamPosition,
 						previewWidth,
 						previewHeight,
@@ -1221,6 +1228,7 @@ export default function VideoEditor() {
 						cropRegion,
 						annotationRegions,
 						webcamLayoutPreset,
+						webcamMaskShape,
 						webcamPosition,
 						previewWidth,
 						previewHeight,
@@ -1289,6 +1297,7 @@ export default function VideoEditor() {
 			isPlaying,
 			aspectRatio,
 			webcamLayoutPreset,
+			webcamMaskShape,
 			webcamPosition,
 			exportQuality,
 			handleExportSaved,
@@ -1473,6 +1482,7 @@ export default function VideoEditor() {
 											videoPath={videoPath || ""}
 											webcamVideoPath={webcamVideoPath || undefined}
 											webcamLayoutPreset={webcamLayoutPreset}
+											webcamMaskShape={webcamMaskShape}
 											webcamPosition={webcamPosition}
 											onWebcamPositionChange={(pos) => updateState({ webcamPosition: pos })}
 											onWebcamPositionDragEnd={commitState}
@@ -1613,6 +1623,8 @@ export default function VideoEditor() {
 								webcamPosition: preset === "vertical-stack" ? null : webcamPosition,
 							})
 						}
+						webcamMaskShape={webcamMaskShape}
+						onWebcamMaskShapeChange={(shape) => pushState({ webcamMaskShape: shape })}
 						videoElement={videoPlaybackRef.current?.video || null}
 						exportQuality={exportQuality}
 						onExportQualityChange={setExportQuality}
diff --git a/src/components/video-editor/VideoPlayback.tsx b/src/components/video-editor/VideoPlayback.tsx
index 71030bb..3bc4048 100644
--- a/src/components/video-editor/VideoPlayback.tsx
+++ b/src/components/video-editor/VideoPlayback.tsx
@@ -25,6 +25,7 @@ import {
 	type StyledRenderRect,
 	type WebcamLayoutPreset,
 } from "@/lib/compositeLayout";
+import { getCssClipPath } from "@/lib/webcamMaskShapes";
 import {
 	type AspectRatio,
 	formatAspectRatioForCSS,
@@ -63,6 +64,7 @@ interface VideoPlaybackProps {
 	videoPath: string;
 	webcamVideoPath?: string;
 	webcamLayoutPreset: WebcamLayoutPreset;
+	webcamMaskShape?: import("./types").WebcamMaskShape;
 	webcamPosition?: { cx: number; cy: number } | null;
 	onWebcamPositionChange?: (position: { cx: number; cy: number }) => void;
 	onWebcamPositionDragEnd?: () => void;
@@ -111,6 +113,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			videoPath,
 			webcamVideoPath,
 			webcamLayoutPreset,
+			webcamMaskShape,
 			webcamPosition,
 			onWebcamPositionChange,
 			onWebcamPositionDragEnd,
@@ -272,6 +275,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 				webcamDimensions,
 				webcamLayoutPreset,
 				webcamPosition,
+				webcamMaskShape,
 			});
 
 			if (result) {
@@ -302,6 +306,7 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			webcamDimensions,
 			webcamLayoutPreset,
 			webcamPosition,
+			webcamMaskShape,
 		]);
 
 		useEffect(() => {
@@ -1154,31 +1159,47 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 								: "none",
 					}}
 				/>
-				{webcamVideoPath && (
-					<video
-						ref={webcamVideoRef}
-						src={webcamVideoPath}
-						className={`absolute object-cover ${webcamLayoutPreset === "picture-in-picture" ? "cursor-grab active:cursor-grabbing" : "pointer-events-none"}`}
-						style={{
-							left: webcamLayout?.x ?? 0,
-							top: webcamLayout?.y ?? 0,
-							width: webcamLayout?.width ?? 0,
-							height: webcamLayout?.height ?? 0,
-							borderRadius: webcamLayout?.borderRadius ?? 0,
-							boxShadow: webcamCssBoxShadow,
-							zIndex: 20,
-							opacity: webcamLayout ? 1 : 0,
-							backgroundColor: "#000",
-						}}
-						onPointerDown={handleWebcamPointerDown}
-						onPointerMove={handleWebcamPointerMove}
-						onPointerUp={handleWebcamPointerUp}
-						onPointerLeave={handleWebcamPointerUp}
-						muted
-						preload="metadata"
-						playsInline
-					/>
-				)}
+				{webcamVideoPath &&
+					(() => {
+						const clipPath = getCssClipPath(webcamLayout?.maskShape ?? "rectangle");
+						const useClipPath = !!clipPath;
+						return (
+							<div
+								className="absolute"
+								style={{
+									left: webcamLayout?.x ?? 0,
+									top: webcamLayout?.y ?? 0,
+									width: webcamLayout?.width ?? 0,
+									height: webcamLayout?.height ?? 0,
+									zIndex: 20,
+									opacity: webcamLayout ? 1 : 0,
+									filter:
+										useClipPath && webcamCssBoxShadow !== "none"
+											? `drop-shadow(${webcamCssBoxShadow})`
+											: undefined,
+								}}
+							>
+								<video
+									ref={webcamVideoRef}
+									src={webcamVideoPath}
+									className={`w-full h-full object-cover ${webcamLayoutPreset === "picture-in-picture" ? "cursor-grab active:cursor-grabbing" : "pointer-events-none"}`}
+									style={{
+										borderRadius: useClipPath ? 0 : (webcamLayout?.borderRadius ?? 0),
+										clipPath: clipPath ?? undefined,
+										boxShadow: useClipPath ? "none" : webcamCssBoxShadow,
+										backgroundColor: "#000",
+									}}
+									onPointerDown={handleWebcamPointerDown}
+									onPointerMove={handleWebcamPointerMove}
+									onPointerUp={handleWebcamPointerUp}
+									onPointerLeave={handleWebcamPointerUp}
+									muted
+									preload="metadata"
+									playsInline
+								/>
+							</div>
+						);
+					})()}
 				{/* Only render overlay after PIXI and video are fully initialized */}
 				{pixiReady && videoReady && (
 					<div
diff --git a/src/components/video-editor/projectPersistence.test.ts b/src/components/video-editor/projectPersistence.test.ts
index 13ea358..3243aca 100644
--- a/src/components/video-editor/projectPersistence.test.ts
+++ b/src/components/video-editor/projectPersistence.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
 	createProjectData,
+	normalizeProjectEditor,
 	PROJECT_VERSION,
 	resolveProjectMedia,
 	validateProjectData,
@@ -40,6 +41,7 @@ describe("projectPersistence media compatibility", () => {
 				annotationRegions: [],
 				aspectRatio: "16:9",
 				webcamLayoutPreset: "picture-in-picture",
+				webcamMaskShape: "circle",
 				exportQuality: "good",
 				exportFormat: "mp4",
 				gifFrameRate: 15,
@@ -55,4 +57,11 @@ describe("projectPersistence media compatibility", () => {
 		});
 		expect(validateProjectData(project)).toBe(true);
 	});
+
+	it("normalizes webcam mask shape values safely", () => {
+		expect(normalizeProjectEditor({ webcamMaskShape: "rounded" }).webcamMaskShape).toBe("rounded");
+		expect(
+			normalizeProjectEditor({ webcamMaskShape: "not-a-real-shape" as never }).webcamMaskShape,
+		).toBe("rectangle");
+	});
 });
diff --git a/src/components/video-editor/projectPersistence.ts b/src/components/video-editor/projectPersistence.ts
index 99f1bba..177a48b 100644
--- a/src/components/video-editor/projectPersistence.ts
+++ b/src/components/video-editor/projectPersistence.ts
@@ -12,11 +12,13 @@ import {
 	DEFAULT_FIGURE_DATA,
 	DEFAULT_PLAYBACK_SPEED,
 	DEFAULT_WEBCAM_LAYOUT_PRESET,
+	DEFAULT_WEBCAM_MASK_SHAPE,
 	DEFAULT_WEBCAM_POSITION,
 	DEFAULT_ZOOM_DEPTH,
 	type SpeedRegion,
 	type TrimRegion,
 	type WebcamLayoutPreset,
+	type WebcamMaskShape,
 	type WebcamPosition,
 	type ZoomRegion,
 } from "./types";
@@ -44,6 +46,7 @@ export interface ProjectEditorState {
 	annotationRegions: AnnotationRegion[];
 	aspectRatio: AspectRatio;
 	webcamLayoutPreset: WebcamLayoutPreset;
+	webcamMaskShape: WebcamMaskShape;
 	webcamPosition: WebcamPosition | null;
 	exportQuality: ExportQuality;
 	exportFormat: ExportFormat;
@@ -352,6 +355,13 @@ export function normalizeProjectEditor(editor: Partial<ProjectEditorState>): Pro
 			editor.webcamLayoutPreset === "picture-in-picture"
 				? editor.webcamLayoutPreset
 				: DEFAULT_WEBCAM_LAYOUT_PRESET,
+		webcamMaskShape:
+			editor.webcamMaskShape === "rectangle" ||
+			editor.webcamMaskShape === "circle" ||
+			editor.webcamMaskShape === "square" ||
+			editor.webcamMaskShape === "rounded"
+				? editor.webcamMaskShape
+				: DEFAULT_WEBCAM_MASK_SHAPE,
 		webcamPosition:
 			editor.webcamPosition &&
 			typeof editor.webcamPosition === "object" &&
diff --git a/src/components/video-editor/types.ts b/src/components/video-editor/types.ts
index ce49f8e..6bdfdbd 100644
--- a/src/components/video-editor/types.ts
+++ b/src/components/video-editor/types.ts
@@ -5,6 +5,10 @@ export type { WebcamLayoutPreset };
 
 export const DEFAULT_WEBCAM_LAYOUT_PRESET: WebcamLayoutPreset = "picture-in-picture";
 
+export type WebcamMaskShape = "rectangle" | "circle" | "square" | "rounded";
+
+export const DEFAULT_WEBCAM_MASK_SHAPE: WebcamMaskShape = "rectangle";
+
 export interface WebcamPosition {
 	cx: number; // normalized horizontal center (0-1)
 	cy: number; // normalized vertical center (0-1)
diff --git a/src/components/video-editor/videoPlayback/layoutUtils.ts b/src/components/video-editor/videoPlayback/layoutUtils.ts
index 13d4631..2444c39 100644
--- a/src/components/video-editor/videoPlayback/layoutUtils.ts
+++ b/src/components/video-editor/videoPlayback/layoutUtils.ts
@@ -6,7 +6,7 @@ import {
 	type StyledRenderRect,
 	type WebcamLayoutPreset,
 } from "@/lib/compositeLayout";
-import type { CropRegion } from "../types";
+import type { CropRegion, WebcamMaskShape } from "../types";
 
 interface LayoutParams {
 	container: HTMLDivElement;
@@ -21,6 +21,7 @@ interface LayoutParams {
 	webcamDimensions?: Size | null;
 	webcamLayoutPreset?: WebcamLayoutPreset;
 	webcamPosition?: { cx: number; cy: number } | null;
+	webcamMaskShape?: WebcamMaskShape;
 }
 
 interface LayoutResult {
@@ -47,6 +48,7 @@ export function layoutVideoContent(params: LayoutParams): LayoutResult | null {
 		webcamDimensions,
 		webcamLayoutPreset,
 		webcamPosition,
+		webcamMaskShape,
 	} = params;
 
 	const videoWidth = lockedVideoDimensions?.width || videoElement.videoWidth;
@@ -94,6 +96,7 @@ export function layoutVideoContent(params: LayoutParams): LayoutResult | null {
 		webcamSize: webcamDimensions,
 		layoutPreset: webcamLayoutPreset,
 		webcamPosition,
+		webcamMaskShape,
 	});
 
 	if (!compositeLayout) {
diff --git a/src/hooks/useEditorHistory.ts b/src/hooks/useEditorHistory.ts
index ea155c8..d261c1f 100644
--- a/src/hooks/useEditorHistory.ts
+++ b/src/hooks/useEditorHistory.ts
@@ -5,12 +5,14 @@ import type {
 	SpeedRegion,
 	TrimRegion,
 	WebcamLayoutPreset,
+	WebcamMaskShape,
 	WebcamPosition,
 	ZoomRegion,
 } from "@/components/video-editor/types";
 import {
 	DEFAULT_CROP_REGION,
 	DEFAULT_WEBCAM_LAYOUT_PRESET,
+	DEFAULT_WEBCAM_MASK_SHAPE,
 	DEFAULT_WEBCAM_POSITION,
 } from "@/components/video-editor/types";
 import type { AspectRatio } from "@/utils/aspectRatioUtils";
@@ -31,6 +33,7 @@ export interface EditorState {
 	padding: number;
 	aspectRatio: AspectRatio;
 	webcamLayoutPreset: WebcamLayoutPreset;
+	webcamMaskShape: WebcamMaskShape;
 	webcamPosition: WebcamPosition | null;
 }
 
@@ -48,6 +51,7 @@ export const INITIAL_EDITOR_STATE: EditorState = {
 	padding: 50,
 	aspectRatio: "16:9",
 	webcamLayoutPreset: DEFAULT_WEBCAM_LAYOUT_PRESET,
+	webcamMaskShape: DEFAULT_WEBCAM_MASK_SHAPE,
 	webcamPosition: DEFAULT_WEBCAM_POSITION,
 };
 
diff --git a/src/i18n/locales/en/settings.json b/src/i18n/locales/en/settings.json
index 36b7462..24ce36b 100644
--- a/src/i18n/locales/en/settings.json
+++ b/src/i18n/locales/en/settings.json
@@ -17,7 +17,8 @@
 		"preset": "Preset",
 		"selectPreset": "Select preset",
 		"pictureInPicture": "Picture in Picture",
-		"verticalStack": "Vertical Stack"
+		"verticalStack": "Vertical Stack",
+		"webcamShape": "Camera Shape"
 	},
 	"effects": {
 		"title": "Video Effects",
diff --git a/src/i18n/locales/es/settings.json b/src/i18n/locales/es/settings.json
index 4674480..a3e2546 100644
--- a/src/i18n/locales/es/settings.json
+++ b/src/i18n/locales/es/settings.json
@@ -17,7 +17,8 @@
 		"preset": "Predefinido",
 		"selectPreset": "Seleccionar predefinido",
 		"pictureInPicture": "Imagen en imagen",
-		"verticalStack": "Apilado vertical"
+		"verticalStack": "Apilado vertical",
+		"webcamShape": "Forma de cámara"
 	},
 	"effects": {
 		"title": "Efectos de video",
diff --git a/src/i18n/locales/zh-CN/settings.json b/src/i18n/locales/zh-CN/settings.json
index 41bf55b..7344a98 100644
--- a/src/i18n/locales/zh-CN/settings.json
+++ b/src/i18n/locales/zh-CN/settings.json
@@ -17,7 +17,8 @@
 		"preset": "预设",
 		"selectPreset": "选择预设",
 		"pictureInPicture": "画中画",
-		"verticalStack": "垂直堆叠"
+		"verticalStack": "垂直堆叠",
+		"webcamShape": "摄像头形状"
 	},
 	"effects": {
 		"title": "视频效果",
diff --git a/src/lib/compositeLayout.test.ts b/src/lib/compositeLayout.test.ts
index 5dc5339..93ce2c5 100644
--- a/src/lib/compositeLayout.test.ts
+++ b/src/lib/compositeLayout.test.ts
@@ -33,7 +33,7 @@ describe("computeCompositeLayout", () => {
 		).toBeLessThanOrEqual(1920);
 	});
 
-	it("centers the combined screen and webcam stack in vertical stack mode", () => {
+	it("uses cover-style full-width stacking in vertical stack mode", () => {
 		const layout = computeCompositeLayout({
 			canvasSize: { width: 1920, height: 1080 },
 			maxContentSize: { width: 1536, height: 864 },
@@ -44,21 +44,22 @@ describe("computeCompositeLayout", () => {
 
 		expect(layout).not.toBeNull();
 		expect(layout?.screenRect).toEqual({
-			x: 576,
-			y: 108,
-			width: 768,
-			height: 432,
+			x: 0,
+			y: 0,
+			width: 1920,
+			height: 0,
 		});
 		expect(layout?.webcamRect).toEqual({
-			x: 576,
-			y: 540,
-			width: 768,
-			height: 432,
+			x: 0,
+			y: 0,
+			width: 1920,
+			height: 1080,
 			borderRadius: 0,
 		});
+		expect(layout?.screenCover).toBe(true);
 	});
 
-	it("keeps the screen centered and omits the webcam when dimensions are unavailable", () => {
+	it("fills the canvas with the screen when vertical stack has no webcam", () => {
 		const layout = computeCompositeLayout({
 			canvasSize: { width: 1920, height: 1080 },
 			maxContentSize: { width: 1536, height: 864 },
@@ -68,11 +69,56 @@ describe("computeCompositeLayout", () => {
 
 		expect(layout).not.toBeNull();
 		expect(layout?.screenRect).toEqual({
-			x: 192,
-			y: 108,
-			width: 1536,
-			height: 864,
+			x: 0,
+			y: 0,
+			width: 1920,
+			height: 1080,
 		});
 		expect(layout?.webcamRect).toBeNull();
+		expect(layout?.screenCover).toBe(true);
+	});
+
+	it("forces circular and square masks to use square dimensions", () => {
+		const circularLayout = computeCompositeLayout({
+			canvasSize: { width: 1920, height: 1080 },
+			screenSize: { width: 1920, height: 1080 },
+			webcamSize: { width: 1280, height: 720 },
+			webcamMaskShape: "circle",
+		});
+		const squareLayout = computeCompositeLayout({
+			canvasSize: { width: 1920, height: 1080 },
+			screenSize: { width: 1920, height: 1080 },
+			webcamSize: { width: 1280, height: 720 },
+			webcamMaskShape: "square",
+		});
+
+		expect(circularLayout?.webcamRect).not.toBeNull();
+		expect(squareLayout?.webcamRect).not.toBeNull();
+		expect(circularLayout?.webcamRect?.width).toBe(circularLayout?.webcamRect?.height);
+		expect(squareLayout?.webcamRect?.width).toBe(squareLayout?.webcamRect?.height);
+		expect(circularLayout?.webcamRect?.maskShape).toBe("circle");
+		expect(squareLayout?.webcamRect?.maskShape).toBe("square");
+	});
+
+	it("applies larger rounding for the rounded webcam mask", () => {
+		const roundedLayout = computeCompositeLayout({
+			canvasSize: { width: 1920, height: 1080 },
+			screenSize: { width: 1920, height: 1080 },
+			webcamSize: { width: 1280, height: 720 },
+			webcamMaskShape: "rounded",
+		});
+		const rectangleLayout = computeCompositeLayout({
+			canvasSize: { width: 1920, height: 1080 },
+			screenSize: { width: 1920, height: 1080 },
+			webcamSize: { width: 1280, height: 720 },
+			webcamMaskShape: "rectangle",
+		});
+
+		expect(roundedLayout?.webcamRect).not.toBeNull();
+		expect(rectangleLayout?.webcamRect).not.toBeNull();
+		expect(roundedLayout?.webcamRect?.borderRadius).toBeGreaterThan(
+			rectangleLayout?.webcamRect?.borderRadius ?? 0,
+		);
+		expect(roundedLayout?.webcamRect?.maskShape).toBe("rounded");
 	});
 });
diff --git a/src/lib/compositeLayout.ts b/src/lib/compositeLayout.ts
index 5feca50..a3c84e8 100644
--- a/src/lib/compositeLayout.ts
+++ b/src/lib/compositeLayout.ts
@@ -7,6 +7,7 @@ export interface RenderRect {
 
 export interface StyledRenderRect extends RenderRect {
 	borderRadius: number;
+	maskShape?: import("@/components/video-editor/types").WebcamMaskShape;
 }
 
 export interface Size {
@@ -125,6 +126,7 @@ export function computeCompositeLayout(params: {
 	webcamSize?: Size | null;
 	layoutPreset?: WebcamLayoutPreset;
 	webcamPosition?: { cx: number; cy: number } | null;
+	webcamMaskShape?: import("@/components/video-editor/types").WebcamMaskShape;
 }): WebcamCompositeLayout | null {
 	const {
 		canvasSize,
@@ -133,6 +135,7 @@ export function computeCompositeLayout(params: {
 		webcamSize,
 		layoutPreset = "picture-in-picture",
 		webcamPosition,
+		webcamMaskShape = "rectangle",
 	} = params;
 	const { width: canvasWidth, height: canvasHeight } = canvasSize;
 	const { width: screenWidth, height: screenHeight } = screenSize;
@@ -198,8 +201,15 @@ export function computeCompositeLayout(params: {
 	const maxWidth = Math.max(transform.minSize, canvasWidth * transform.maxStageFraction);
 	const maxHeight = Math.max(transform.minSize, canvasHeight * transform.maxStageFraction);
 	const scale = Math.min(maxWidth / webcamWidth, maxHeight / webcamHeight);
-	const width = Math.round(webcamWidth * scale);
-	const height = Math.round(webcamHeight * scale);
+	let width = Math.round(webcamWidth * scale);
+	let height = Math.round(webcamHeight * scale);
+
+	// Shape-specific dimension adjustments
+	if (webcamMaskShape === "circle" || webcamMaskShape === "square") {
+		const side = Math.min(width, height);
+		width = side;
+		height = side;
+	}
 
 	let webcamX: number;
 	let webcamY: number;
@@ -217,6 +227,22 @@ export function computeCompositeLayout(params: {
 		webcamY = Math.max(0, Math.round(canvasHeight - margin - height));
 	}
 
+	// Shape-specific border radius
+	let borderRadius: number;
+	if (webcamMaskShape === "rounded") {
+		borderRadius = Math.round(Math.min(width, height) * 0.3);
+	} else if (webcamMaskShape === "circle") {
+		borderRadius = Math.round(Math.min(width, height) / 2);
+	} else {
+		borderRadius = Math.min(
+			preset.borderRadius.max,
+			Math.max(
+				preset.borderRadius.min,
+				Math.round(Math.min(width, height) * preset.borderRadius.fraction),
+			),
+		);
+	}
+
 	return {
 		screenRect,
 		webcamRect: {
@@ -224,13 +250,8 @@ export function computeCompositeLayout(params: {
 			y: webcamY,
 			width,
 			height,
-			borderRadius: Math.min(
-				preset.borderRadius.max,
-				Math.max(
-					preset.borderRadius.min,
-					Math.round(Math.min(width, height) * preset.borderRadius.fraction),
-				),
-			),
+			borderRadius,
+			maskShape: webcamMaskShape,
 		},
 	};
 }
diff --git a/src/lib/exporter/frameRenderer.ts b/src/lib/exporter/frameRenderer.ts
index 4a9b2bd..f02d537 100644
--- a/src/lib/exporter/frameRenderer.ts
+++ b/src/lib/exporter/frameRenderer.ts
@@ -37,6 +37,7 @@ import {
 	type Size,
 	type StyledRenderRect,
 } from "@/lib/compositeLayout";
+import { drawCanvasClipPath } from "@/lib/webcamMaskShapes";
 import { renderAnnotations } from "./annotationRenderer";
 import {
 	getLinearGradientPoints,
@@ -61,6 +62,7 @@ interface FrameRenderConfig {
 	videoHeight: number;
 	webcamSize?: Size | null;
 	webcamLayoutPreset?: WebcamLayoutPreset;
+	webcamMaskShape?: import("@/components/video-editor/types").WebcamMaskShape;
 	webcamPosition?: { cx: number; cy: number } | null;
 	annotationRegions?: AnnotationRegion[];
 	speedRegions?: SpeedRegion[];
@@ -441,6 +443,7 @@ export class FrameRenderer {
 			webcamSize: webcamFrame ? this.config.webcamSize : null,
 			layoutPreset: this.config.webcamLayoutPreset,
 			webcamPosition: this.config.webcamPosition,
+			webcamMaskShape: this.config.webcamMaskShape,
 		});
 		if (!compositeLayout) return;
 
@@ -668,16 +671,17 @@ export class FrameRenderer {
 		const webcamRect = this.layoutCache?.webcamRect ?? null;
 		if (webcamFrame && webcamRect) {
 			const preset = getWebcamLayoutPresetDefinition(this.config.webcamLayoutPreset);
+			const shape = webcamRect.maskShape ?? this.config.webcamMaskShape ?? "rectangle";
 			ctx.save();
-			ctx.beginPath();
-			ctx.roundRect(
+			drawCanvasClipPath(
+				ctx,
 				webcamRect.x,
 				webcamRect.y,
 				webcamRect.width,
 				webcamRect.height,
+				shape,
 				webcamRect.borderRadius,
 			);
-			ctx.closePath();
 			if (preset.shadow) {
 				ctx.shadowColor = preset.shadow.color;
 				ctx.shadowBlur = preset.shadow.blur;
diff --git a/src/lib/exporter/gifExporter.ts b/src/lib/exporter/gifExporter.ts
index 8aac0b5..5ba278e 100644
--- a/src/lib/exporter/gifExporter.ts
+++ b/src/lib/exporter/gifExporter.ts
@@ -41,6 +41,7 @@ interface GifExporterConfig {
 	videoPadding?: number;
 	cropRegion: CropRegion;
 	webcamLayoutPreset?: WebcamLayoutPreset;
+	webcamMaskShape?: import("@/components/video-editor/types").WebcamMaskShape;
 	webcamPosition?: { cx: number; cy: number } | null;
 	annotationRegions?: AnnotationRegion[];
 	previewWidth?: number;
@@ -141,6 +142,7 @@ export class GifExporter {
 				videoHeight: videoInfo.height,
 				webcamSize: webcamInfo ? { width: webcamInfo.width, height: webcamInfo.height } : null,
 				webcamLayoutPreset: this.config.webcamLayoutPreset,
+				webcamMaskShape: this.config.webcamMaskShape,
 				webcamPosition: this.config.webcamPosition,
 				annotationRegions: this.config.annotationRegions,
 				speedRegions: this.config.speedRegions,
diff --git a/src/lib/exporter/videoExporter.ts b/src/lib/exporter/videoExporter.ts
index 1b75a2e..9481d2f 100644
--- a/src/lib/exporter/videoExporter.ts
+++ b/src/lib/exporter/videoExporter.ts
@@ -32,6 +32,7 @@ interface VideoExporterConfig extends ExportConfig {
 	videoPadding?: number;
 	cropRegion: CropRegion;
 	webcamLayoutPreset?: WebcamLayoutPreset;
+	webcamMaskShape?: import("@/components/video-editor/types").WebcamMaskShape;
 	webcamPosition?: { cx: number; cy: number } | null;
 	annotationRegions?: AnnotationRegion[];
 	previewWidth?: number;
@@ -134,6 +135,7 @@ export class VideoExporter {
 				videoHeight: videoInfo.height,
 				webcamSize: webcamInfo ? { width: webcamInfo.width, height: webcamInfo.height } : null,
 				webcamLayoutPreset: this.config.webcamLayoutPreset,
+				webcamMaskShape: this.config.webcamMaskShape,
 				webcamPosition: this.config.webcamPosition,
 				annotationRegions: this.config.annotationRegions,
 				speedRegions: this.config.speedRegions,
diff --git a/src/lib/webcamMaskShapes.ts b/src/lib/webcamMaskShapes.ts
new file mode 100644
index 0000000..f90e727
--- /dev/null
+++ b/src/lib/webcamMaskShapes.ts
@@ -0,0 +1,48 @@
+import type { WebcamMaskShape } from "@/components/video-editor/types";
+
+/**
+ * Returns a CSS clip-path value for the given shape, or null if borderRadius alone suffices.
+ */
+export function getCssClipPath(shape: WebcamMaskShape): string | null {
+	switch (shape) {
+		case "circle":
+			return "circle(50% at 50% 50%)";
+		case "rectangle":
+		case "rounded":
+		case "square":
+		default:
+			return null;
+	}
+}
+
+/**
+ * Draws a Canvas 2D clip path for the given webcam mask shape.
+ * Call ctx.beginPath() is handled internally; caller should call ctx.clip() after.
+ */
+export function drawCanvasClipPath(
+	ctx: CanvasRenderingContext2D,
+	x: number,
+	y: number,
+	w: number,
+	h: number,
+	shape: WebcamMaskShape,
+	borderRadius: number,
+): void {
+	ctx.beginPath();
+	switch (shape) {
+		case "circle": {
+			const cx = x + w / 2;
+			const cy = y + h / 2;
+			const r = Math.min(w, h) / 2;
+			ctx.arc(cx, cy, r, 0, Math.PI * 2);
+			break;
+		}
+		case "rectangle":
+		case "rounded":
+		case "square":
+		default:
+			ctx.roundRect(x, y, w, h, borderRadius);
+			break;
+	}
+	ctx.closePath();
+}

From 2b471783c084800acd67c37e8a74439c1db864a1 Mon Sep 17 00:00:00 2001
From: Adam <69064669+abres33@users.noreply.github.com>
Date: Fri, 3 Apr 2026 02:00:36 -0500
Subject: [PATCH 07/20] feat: add Cancel Recording button to HUD

---
 src/components/launch/LaunchWindow.tsx | 15 +++++++++++++++
 src/hooks/useScreenRecorder.ts         | 13 +++++++++++++
 src/i18n/locales/en/launch.json        |  1 +
 src/i18n/locales/es/launch.json        |  1 +
 src/i18n/locales/zh-CN/launch.json     |  1 +
 5 files changed, 31 insertions(+)

diff --git a/src/components/launch/LaunchWindow.tsx b/src/components/launch/LaunchWindow.tsx
index f1b66b8..d1185e8 100644
--- a/src/components/launch/LaunchWindow.tsx
+++ b/src/components/launch/LaunchWindow.tsx
@@ -5,6 +5,7 @@ import { FaRegStopCircle } from "react-icons/fa";
 import { FaFolderOpen } from "react-icons/fa6";
 import { FiMinus, FiX } from "react-icons/fi";
 import {
+	MdCancel,
 	MdMic,
 	MdMicOff,
 	MdMonitor,
@@ -43,6 +44,7 @@ const ICON_CONFIG = {
 	webcamOff: { icon: MdVideocamOff, size: ICON_SIZE },
 	stop: { icon: FaRegStopCircle, size: ICON_SIZE },
 	restart: { icon: MdRestartAlt, size: ICON_SIZE },
+	cancel: { icon: MdCancel, size: ICON_SIZE },
 	record: { icon: BsRecordCircle, size: ICON_SIZE },
 	videoFile: { icon: MdVideoFile, size: ICON_SIZE },
 	folder: { icon: FaFolderOpen, size: ICON_SIZE },
@@ -79,6 +81,7 @@ export function LaunchWindow() {
 		recording,
 		toggleRecording,
 		restartRecording,
+		cancelRecording,
 		microphoneEnabled,
 		setMicrophoneEnabled,
 		microphoneDeviceId,
@@ -477,6 +480,18 @@ export function LaunchWindow() {
 					</Tooltip>
 				)}
 
+				{/* Cancel recording */}
+				{recording && (
+					<Tooltip content={t("tooltips.cancelRecording")}>
+						<button
+							className={`${hudIconBtnClasses} ${styles.electronNoDrag}`}
+							onClick={cancelRecording}
+						>
+							{getIcon("cancel", "text-white/60")}
+						</button>
+					</Tooltip>
+				)}
+
 				{/* Open video file */}
 				<Tooltip content={t("tooltips.openVideoFile")}>
 					<button
diff --git a/src/hooks/useScreenRecorder.ts b/src/hooks/useScreenRecorder.ts
index 0c418c1..25adf6d 100644
--- a/src/hooks/useScreenRecorder.ts
+++ b/src/hooks/useScreenRecorder.ts
@@ -43,6 +43,7 @@ type UseScreenRecorderReturn = {
 	recording: boolean;
 	toggleRecording: () => void;
 	restartRecording: () => void;
+	cancelRecording: () => void;
 	microphoneEnabled: boolean;
 	setMicrophoneEnabled: (enabled: boolean) => void;
 	microphoneDeviceId: string | undefined;
@@ -601,10 +602,22 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 		}
 	};
 
+	const cancelRecording = () => {
+		const activeScreenRecorder = screenRecorder.current;
+		if (!activeScreenRecorder || activeScreenRecorder.recorder.state !== "recording") return;
+
+		const activeRecordingId = recordingId.current;
+		discardRecordingId.current = activeRecordingId;
+		allowAutoFinalize.current = false;
+
+		stopRecording.current();
+	};
+
 	return {
 		recording,
 		toggleRecording,
 		restartRecording,
+		cancelRecording,
 		microphoneEnabled,
 		setMicrophoneEnabled,
 		microphoneDeviceId,
diff --git a/src/i18n/locales/en/launch.json b/src/i18n/locales/en/launch.json
index 6e4a4ed..c1229cc 100644
--- a/src/i18n/locales/en/launch.json
+++ b/src/i18n/locales/en/launch.json
@@ -3,6 +3,7 @@
 		"hideHUD": "Hide HUD",
 		"closeApp": "Close App",
 		"restartRecording": "Restart recording",
+		"cancelRecording": "Cancel recording",
 		"openVideoFile": "Open video file",
 		"openProject": "Open project"
 	},
diff --git a/src/i18n/locales/es/launch.json b/src/i18n/locales/es/launch.json
index b25ec3d..f5be07c 100644
--- a/src/i18n/locales/es/launch.json
+++ b/src/i18n/locales/es/launch.json
@@ -3,6 +3,7 @@
 		"hideHUD": "Ocultar HUD",
 		"closeApp": "Cerrar aplicación",
 		"restartRecording": "Reiniciar grabación",
+		"cancelRecording": "Cancelar grabación",
 		"openVideoFile": "Abrir archivo de video",
 		"openProject": "Abrir proyecto"
 	},
diff --git a/src/i18n/locales/zh-CN/launch.json b/src/i18n/locales/zh-CN/launch.json
index 84fdcef..0c2b319 100644
--- a/src/i18n/locales/zh-CN/launch.json
+++ b/src/i18n/locales/zh-CN/launch.json
@@ -3,6 +3,7 @@
 		"hideHUD": "隐藏控制面板",
 		"closeApp": "关闭应用",
 		"restartRecording": "重新开始录制",
+		"cancelRecording": "取消录制",
 		"openVideoFile": "打开视频文件",
 		"openProject": "打开项目"
 	},

From d6933813bdcdd841fdbe038703fb9ef7e110134e Mon Sep 17 00:00:00 2001
From: Adam <69064669+abres33@users.noreply.github.com>
Date: Fri, 3 Apr 2026 02:25:29 -0500
Subject: [PATCH 08/20] fix: move try/catch outside evaluate() in gif-export
 E2E test

---
 tests/e2e/gif-export.spec.ts | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/tests/e2e/gif-export.spec.ts b/tests/e2e/gif-export.spec.ts
index a851546..c32d604 100644
--- a/tests/e2e/gif-export.spec.ts
+++ b/tests/e2e/gif-export.spec.ts
@@ -58,14 +58,15 @@ test("exports a GIF from a loaded video", async () => {
 			);
 		});
 
-		await hudWindow.evaluate((videoPath: string) => {
-			window.electronAPI.setCurrentVideoPath(videoPath);
-			try {
+		try {
+			await hudWindow.evaluate((videoPath: string) => {
+				window.electronAPI.setCurrentVideoPath(videoPath);
 				window.electronAPI.switchToEditor();
-			} catch {
-				// Expected: HUD window closes during this call, killing the context.
-			}
-		}, TEST_VIDEO);
+			}, TEST_VIDEO);
+		} catch {
+			// Expected: switchToEditor() closes the HUD window, which terminates
+			// the Playwright page context before evaluate() can resolve.
+		}
 
 		// ── 3. Switch to the editor window. This closes the HUD and opens
 		//       a new BrowserWindow with ?windowType=editor.

From 27853cc2c3069bad6d07ed60299e6d3cfd9a149a Mon Sep 17 00:00:00 2001
From: Adam <69064669+abres33@users.noreply.github.com>
Date: Fri, 3 Apr 2026 02:32:47 -0500
Subject: [PATCH 09/20] fix: await setCurrentVideoPath and narrow catch in
 gif-export E2E test

---
 tests/e2e/gif-export.spec.ts | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/tests/e2e/gif-export.spec.ts b/tests/e2e/gif-export.spec.ts
index c32d604..c3a0afb 100644
--- a/tests/e2e/gif-export.spec.ts
+++ b/tests/e2e/gif-export.spec.ts
@@ -59,13 +59,21 @@ test("exports a GIF from a loaded video", async () => {
 		});
 
 		try {
-			await hudWindow.evaluate((videoPath: string) => {
-				window.electronAPI.setCurrentVideoPath(videoPath);
+			await hudWindow.evaluate(async (videoPath: string) => {
+				await window.electronAPI.setCurrentVideoPath(videoPath);
 				window.electronAPI.switchToEditor();
 			}, TEST_VIDEO);
-		} catch {
+		} catch (error) {
 			// Expected: switchToEditor() closes the HUD window, which terminates
 			// the Playwright page context before evaluate() can resolve.
+			if (
+				!(
+					error instanceof Error &&
+					error.message.includes("Target page, context or browser has been closed")
+				)
+			) {
+				throw error;
+			}
 		}
 
 		// ── 3. Switch to the editor window. This closes the HUD and opens

From 11bad60eb2b073baebed02ce27d01e2d3a2c3345 Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 17:36:43 +0300
Subject: [PATCH 10/20] feat: add i18n labels for frame step shortcuts (en, es,
 zh-CN)

---
 src/i18n/locales/en/shortcuts.json    | 4 +++-
 src/i18n/locales/es/shortcuts.json    | 4 +++-
 src/i18n/locales/zh-CN/shortcuts.json | 4 +++-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/i18n/locales/en/shortcuts.json b/src/i18n/locales/en/shortcuts.json
index e943e61..790302c 100644
--- a/src/i18n/locales/en/shortcuts.json
+++ b/src/i18n/locales/en/shortcuts.json
@@ -29,6 +29,8 @@
 		"cycleAnnotationsBackward": "Cycle Annotations Backward",
 		"deleteSelectedAlt": "Delete Selected (alt)",
 		"panTimeline": "Pan Timeline",
-		"zoomTimeline": "Zoom Timeline"
+		"zoomTimeline": "Zoom Timeline",
+		"frameBack": "Frame Back",
+		"frameForward": "Frame Forward"
 	}
 }
diff --git a/src/i18n/locales/es/shortcuts.json b/src/i18n/locales/es/shortcuts.json
index ede18bf..a03420e 100644
--- a/src/i18n/locales/es/shortcuts.json
+++ b/src/i18n/locales/es/shortcuts.json
@@ -29,6 +29,8 @@
 		"cycleAnnotationsBackward": "Recorrer anotaciones hacia atrás",
 		"deleteSelectedAlt": "Eliminar seleccionado (alt)",
 		"panTimeline": "Desplazar línea de tiempo",
-		"zoomTimeline": "Zoom en línea de tiempo"
+		"zoomTimeline": "Zoom en línea de tiempo",
+		"frameBack": "Fotograma anterior",
+		"frameForward": "Fotograma siguiente"
 	}
 }
diff --git a/src/i18n/locales/zh-CN/shortcuts.json b/src/i18n/locales/zh-CN/shortcuts.json
index 5099b27..e2faa2f 100644
--- a/src/i18n/locales/zh-CN/shortcuts.json
+++ b/src/i18n/locales/zh-CN/shortcuts.json
@@ -29,6 +29,8 @@
 		"cycleAnnotationsBackward": "向后切换标注",
 		"deleteSelectedAlt": "删除所选（替代）",
 		"panTimeline": "平移时间轴",
-		"zoomTimeline": "缩放时间轴"
+		"zoomTimeline": "缩放时间轴",
+		"frameBack": "上一帧",
+		"frameForward": "下一帧"
 	}
 }

From b709d0d240cf6c41bb8ec5bf869bf7494f7617d3 Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 17:37:13 +0300
Subject: [PATCH 11/20] feat: add frame step entries to FIXED_SHORTCUTS display
 list

---
 src/lib/shortcuts.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/lib/shortcuts.ts b/src/lib/shortcuts.ts
index 69af499..1ca4975 100644
--- a/src/lib/shortcuts.ts
+++ b/src/lib/shortcuts.ts
@@ -49,6 +49,8 @@ export const FIXED_SHORTCUTS: FixedShortcut[] = [
 	},
 	{ label: "Pan Timeline", display: "Shift + Ctrl + Scroll", bindings: [] },
 	{ label: "Zoom Timeline", display: "Ctrl + Scroll", bindings: [] },
+	{ label: "Frame Back", display: "←", bindings: [{ key: "arrowleft" }] },
+	{ label: "Frame Forward", display: "→", bindings: [{ key: "arrowright" }] },
 ];
 
 export type ShortcutConflict =

From baa30a9d6ac5467505b96a7c2b1915098bf639cb Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 17:44:26 +0300
Subject: [PATCH 12/20] test: add unit tests for frame step time computation

---
 src/lib/__tests__/frameStepNavigation.test.ts | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 src/lib/__tests__/frameStepNavigation.test.ts

diff --git a/src/lib/__tests__/frameStepNavigation.test.ts b/src/lib/__tests__/frameStepNavigation.test.ts
new file mode 100644
index 0000000..99d62fe
--- /dev/null
+++ b/src/lib/__tests__/frameStepNavigation.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+
+const FRAME_DURATION_SEC = 1 / 60;
+
+function computeFrameStepTime(
+	currentTime: number,
+	duration: number,
+	direction: "forward" | "backward",
+): number {
+	const delta = direction === "forward" ? FRAME_DURATION_SEC : -FRAME_DURATION_SEC;
+	return Math.min(duration, Math.max(0, currentTime + delta));
+}
+
+describe("computeFrameStepTime", () => {
+	const duration = 10;
+
+	it("moves forward by one frame from the middle", () => {
+		const result = computeFrameStepTime(5, duration, "forward");
+		expect(result).toBeCloseTo(5 + FRAME_DURATION_SEC, 10);
+	});
+
+	it("moves backward by one frame from the middle", () => {
+		const result = computeFrameStepTime(5, duration, "backward");
+		expect(result).toBeCloseTo(5 - FRAME_DURATION_SEC, 10);
+	});
+
+	it("clamps to 0 when stepping backward at the beginning", () => {
+		const result = computeFrameStepTime(0, duration, "backward");
+		expect(result).toBe(0);
+	});
+
+	it("clamps to 0 when stepping backward near the beginning", () => {
+		const result = computeFrameStepTime(FRAME_DURATION_SEC / 2, duration, "backward");
+		expect(result).toBe(0);
+	});
+
+	it("clamps to duration when stepping forward at the end", () => {
+		const result = computeFrameStepTime(duration, duration, "forward");
+		expect(result).toBe(duration);
+	});
+
+	it("clamps to duration when stepping forward near the end", () => {
+		const result = computeFrameStepTime(duration - FRAME_DURATION_SEC / 2, duration, "forward");
+		expect(result).toBe(duration);
+	});
+
+	it("handles duration of 0 gracefully", () => {
+		expect(computeFrameStepTime(0, 0, "forward")).toBe(0);
+		expect(computeFrameStepTime(0, 0, "backward")).toBe(0);
+	});
+});

From e5430eed399d2abd9686788d0b88e833f5276a2a Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 17:50:53 +0300
Subject: [PATCH 13/20] feat: add arrow key frame-by-frame playhead navigation
 (#302)

---
 src/components/video-editor/VideoEditor.tsx   | 28 +++++++++++++++++++
 src/lib/__tests__/frameStepNavigation.test.ts | 11 +-------
 src/lib/frameStep.ts                          | 10 +++++++
 3 files changed, 39 insertions(+), 10 deletions(-)
 create mode 100644 src/lib/frameStep.ts

diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index 304d10f..9cd467a 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -20,6 +20,7 @@ import {
 	type GifSizePreset,
 	VideoExporter,
 } from "@/lib/exporter";
+import { computeFrameStepTime } from "@/lib/frameStep";
 import type { ProjectMedia } from "@/lib/recordingSession";
 import { matchesShortcut } from "@/lib/shortcuts";
 import {
@@ -98,6 +99,10 @@ export default function VideoEditor() {
 	const [isPlaying, setIsPlaying] = useState(false);
 	const [currentTime, setCurrentTime] = useState(0);
 	const [duration, setDuration] = useState(0);
+	const currentTimeRef = useRef(currentTime);
+	currentTimeRef.current = currentTime;
+	const durationRef = useRef(duration);
+	durationRef.current = duration;
 	const [cursorTelemetry, setCursorTelemetry] = useState<CursorTelemetryPoint[]>([]);
 	const [selectedZoomId, setSelectedZoomId] = useState<string | null>(null);
 	const [selectedTrimId, setSelectedTrimId] = useState<string | null>(null);
@@ -926,6 +931,29 @@ export default function VideoEditor() {
 				return;
 			}
 
+			// Frame-step navigation (arrow keys, no modifiers)
+			if (
+				(e.key === "ArrowLeft" || e.key === "ArrowRight") &&
+				!e.ctrlKey &&
+				!e.metaKey &&
+				!e.shiftKey &&
+				!e.altKey
+			) {
+				const target = e.target;
+				if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+					return;
+				}
+				e.preventDefault();
+				const direction = e.key === "ArrowLeft" ? "backward" : "forward";
+				const newTime = computeFrameStepTime(
+					currentTimeRef.current,
+					durationRef.current,
+					direction,
+				);
+				handleSeek(newTime);
+				return;
+			}
+
 			const isInput =
 				e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement;
 
diff --git a/src/lib/__tests__/frameStepNavigation.test.ts b/src/lib/__tests__/frameStepNavigation.test.ts
index 99d62fe..ab0393b 100644
--- a/src/lib/__tests__/frameStepNavigation.test.ts
+++ b/src/lib/__tests__/frameStepNavigation.test.ts
@@ -1,15 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-const FRAME_DURATION_SEC = 1 / 60;
-
-function computeFrameStepTime(
-	currentTime: number,
-	duration: number,
-	direction: "forward" | "backward",
-): number {
-	const delta = direction === "forward" ? FRAME_DURATION_SEC : -FRAME_DURATION_SEC;
-	return Math.min(duration, Math.max(0, currentTime + delta));
-}
+import { computeFrameStepTime, FRAME_DURATION_SEC } from "@/lib/frameStep";
 
 describe("computeFrameStepTime", () => {
 	const duration = 10;
diff --git a/src/lib/frameStep.ts b/src/lib/frameStep.ts
new file mode 100644
index 0000000..7eaaf6b
--- /dev/null
+++ b/src/lib/frameStep.ts
@@ -0,0 +1,10 @@
+export const FRAME_DURATION_SEC = 1 / 60;
+
+export function computeFrameStepTime(
+	currentTime: number,
+	duration: number,
+	direction: "forward" | "backward",
+): number {
+	const delta = direction === "forward" ? FRAME_DURATION_SEC : -FRAME_DURATION_SEC;
+	return Math.min(duration, Math.max(0, currentTime + delta));
+}

From 54df597160a130e82cbf9c43e4bc988c551fa5ba Mon Sep 17 00:00:00 2001
From: xKeCo <kevcollazos@gmail.com>
Date: Fri, 3 Apr 2026 12:26:07 -0500
Subject: [PATCH 14/20] =?UTF-8?q?=E2=9C=A8=20feat:=20enhance=20adaptive=20?=
 =?UTF-8?q?smoothing=20for=20auto-follow=20zoom=20in=20video=20playback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/components/video-editor/VideoPlayback.tsx | 46 +++++++++++------
 .../video-editor/videoPlayback/constants.ts   |  5 +-
 .../videoPlayback/cursorFollowUtils.ts        | 19 +++++++
 .../video-editor/videoPlayback/focusUtils.ts  | 29 ++++++++---
 .../videoPlayback/zoomRegionUtils.ts          | 31 +++++++++---
 src/lib/exporter/frameRenderer.ts             | 50 +++++++++++++------
 6 files changed, 133 insertions(+), 47 deletions(-)

diff --git a/src/components/video-editor/VideoPlayback.tsx b/src/components/video-editor/VideoPlayback.tsx
index 8c2d120..694c137 100644
--- a/src/components/video-editor/VideoPlayback.tsx
+++ b/src/components/video-editor/VideoPlayback.tsx
@@ -41,13 +41,14 @@ import {
 	type ZoomRegion,
 } from "./types";
 import {
-	AUTO_FOLLOW_DEADZONE,
+	AUTO_FOLLOW_RAMP_DISTANCE,
 	AUTO_FOLLOW_SMOOTHING_FACTOR,
+	AUTO_FOLLOW_SMOOTHING_FACTOR_MAX,
 	DEFAULT_FOCUS,
 	ZOOM_SCALE_DEADZONE,
 	ZOOM_TRANSLATION_DEADZONE_PX,
 } from "./videoPlayback/constants";
-import { smoothCursorFocus } from "./videoPlayback/cursorFollowUtils";
+import { adaptiveSmoothFactor, smoothCursorFocus } from "./videoPlayback/cursorFollowUtils";
 import { clampFocusToStage as clampFocusToStageUtil } from "./videoPlayback/focusUtils";
 import { layoutVideoContent as layoutVideoContentUtil } from "./videoPlayback/layoutUtils";
 import { clamp01 } from "./videoPlayback/mathUtils";
@@ -843,10 +844,16 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 			};
 
 			const ticker = () => {
+				const bm = baseMaskRef.current;
+				const ss = stageSizeRef.current;
+				const viewportRatio =
+					bm.width > 0 && bm.height > 0
+						? { widthRatio: ss.width / bm.width, heightRatio: ss.height / bm.height }
+						: undefined;
 				const { region, strength, blendedScale, transition } = findDominantRegion(
 					zoomRegionsRef.current,
 					currentTimeRef.current,
-					{ connectZooms: true, cursorTelemetry: cursorTelemetryRef.current },
+					{ connectZooms: true, cursorTelemetry: cursorTelemetryRef.current, viewportRatio },
 				);
 
 				const defaultFocus = DEFAULT_FOCUS;
@@ -867,24 +874,24 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 					targetFocus = regionFocus;
 					targetProgress = strength;
 
-					// Apply deadzone + smoothing for auto-follow mode
+					// Apply adaptive smoothing for auto-follow mode
 					if (region.focusMode === "auto" && !transition) {
 						const raw = targetFocus;
 						const isZoomingIn =
 							targetProgress < 0.999 && targetProgress >= prevTargetProgressRef.current;
 						if (targetProgress >= 0.999) {
-							// Full zoom: apply deadzone + smoothing for stable follow
+							// Full zoom: adaptive smoothing — moves faster when far, decelerates when close
 							const prev = smoothedAutoFocusRef.current ?? raw;
-							const dx = Math.abs(raw.cx - prev.cx);
-							const dy = Math.abs(raw.cy - prev.cy);
-							if (dx > AUTO_FOLLOW_DEADZONE || dy > AUTO_FOLLOW_DEADZONE) {
-								const smoothed = smoothCursorFocus(raw, prev, AUTO_FOLLOW_SMOOTHING_FACTOR);
-								smoothedAutoFocusRef.current = smoothed;
-								targetFocus = smoothed;
-							} else {
-								smoothedAutoFocusRef.current = prev;
-								targetFocus = prev;
-							}
+							const factor = adaptiveSmoothFactor(
+								raw,
+								prev,
+								AUTO_FOLLOW_SMOOTHING_FACTOR,
+								AUTO_FOLLOW_SMOOTHING_FACTOR_MAX,
+								AUTO_FOLLOW_RAMP_DISTANCE,
+							);
+							const smoothed = smoothCursorFocus(raw, prev, factor);
+							smoothedAutoFocusRef.current = smoothed;
+							targetFocus = smoothed;
 						} else if (isZoomingIn) {
 							// Zoom-in: track cursor directly so zoom always aims at current cursor
 							// position; keep ref in sync to avoid snap when full-zoom begins
@@ -892,7 +899,14 @@ const VideoPlayback = forwardRef<VideoPlaybackRef, VideoPlaybackProps>(
 						} else {
 							// Zoom-out: keep smoothing for continuity — avoids snap at zoom-out start
 							const prev = smoothedAutoFocusRef.current ?? raw;
-							const smoothed = smoothCursorFocus(raw, prev, AUTO_FOLLOW_SMOOTHING_FACTOR);
+							const factor = adaptiveSmoothFactor(
+								raw,
+								prev,
+								AUTO_FOLLOW_SMOOTHING_FACTOR,
+								AUTO_FOLLOW_SMOOTHING_FACTOR_MAX,
+								AUTO_FOLLOW_RAMP_DISTANCE,
+							);
+							const smoothed = smoothCursorFocus(raw, prev, factor);
 							smoothedAutoFocusRef.current = smoothed;
 							targetFocus = smoothed;
 						}
diff --git a/src/components/video-editor/videoPlayback/constants.ts b/src/components/video-editor/videoPlayback/constants.ts
index 1c41cb7..b5b4bd1 100644
--- a/src/components/video-editor/videoPlayback/constants.ts
+++ b/src/components/video-editor/videoPlayback/constants.ts
@@ -8,5 +8,6 @@ export const VIEWPORT_SCALE = 0.8;
 export const SMOOTHING_FACTOR = 0.12;
 export const ZOOM_TRANSLATION_DEADZONE_PX = 1.25;
 export const ZOOM_SCALE_DEADZONE = 0.002;
-export const AUTO_FOLLOW_SMOOTHING_FACTOR = 0.05;
-export const AUTO_FOLLOW_DEADZONE = 0.06;
+export const AUTO_FOLLOW_SMOOTHING_FACTOR = 0.1;
+export const AUTO_FOLLOW_SMOOTHING_FACTOR_MAX = 0.25;
+export const AUTO_FOLLOW_RAMP_DISTANCE = 0.15;
diff --git a/src/components/video-editor/videoPlayback/cursorFollowUtils.ts b/src/components/video-editor/videoPlayback/cursorFollowUtils.ts
index 9c92c25..14dad24 100644
--- a/src/components/video-editor/videoPlayback/cursorFollowUtils.ts
+++ b/src/components/video-editor/videoPlayback/cursorFollowUtils.ts
@@ -52,3 +52,22 @@ export function smoothCursorFocus(raw: ZoomFocus, prev: ZoomFocus, factor: numbe
 		cy: prev.cy + (raw.cy - prev.cy) * factor,
 	};
 }
+
+/**
+ * Compute an adaptive smoothing factor that scales with distance:
+ * far from target → faster (maxFactor), close → slower (minFactor).
+ * This replaces the hard deadzone with a natural deceleration curve.
+ */
+export function adaptiveSmoothFactor(
+	raw: ZoomFocus,
+	prev: ZoomFocus,
+	minFactor: number,
+	maxFactor: number,
+	rampDistance: number,
+): number {
+	const dx = raw.cx - prev.cx;
+	const dy = raw.cy - prev.cy;
+	const distance = Math.sqrt(dx * dx + dy * dy);
+	const t = Math.min(1, distance / rampDistance);
+	return minFactor + (maxFactor - minFactor) * t;
+}
diff --git a/src/components/video-editor/videoPlayback/focusUtils.ts b/src/components/video-editor/videoPlayback/focusUtils.ts
index 5a56f0e..f893935 100644
--- a/src/components/video-editor/videoPlayback/focusUtils.ts
+++ b/src/components/video-editor/videoPlayback/focusUtils.ts
@@ -39,9 +39,16 @@ function getFocusBounds(depth: ZoomDepth) {
 	return getFocusBoundsForScale(zoomScale);
 }
 
-function getFocusBoundsForScale(zoomScale: number) {
-	const marginX = 1 / (2 * zoomScale);
-	const marginY = 1 / (2 * zoomScale);
+interface ViewportRatio {
+	widthRatio: number;
+	heightRatio: number;
+}
+
+function getFocusBoundsForScale(zoomScale: number, viewportRatio?: ViewportRatio) {
+	const wr = viewportRatio?.widthRatio ?? 1;
+	const hr = viewportRatio?.heightRatio ?? 1;
+	const marginX = Math.min(0.5, wr / (2 * zoomScale));
+	const marginY = Math.min(0.5, hr / (2 * zoomScale));
 
 	return {
 		minX: marginX,
@@ -65,12 +72,16 @@ export function clampFocusToStage(
 	};
 }
 
-export function clampFocusToScale(focus: ZoomFocus, zoomScale: number): ZoomFocus {
+export function clampFocusToScale(
+	focus: ZoomFocus,
+	zoomScale: number,
+	viewportRatio?: ViewportRatio,
+): ZoomFocus {
 	const baseFocus = {
 		cx: clamp(focus.cx, 0, 1),
 		cy: clamp(focus.cy, 0, 1),
 	};
-	const bounds = getFocusBoundsForScale(zoomScale);
+	const bounds = getFocusBoundsForScale(zoomScale, viewportRatio);
 
 	return {
 		cx: clamp(baseFocus.cx, bounds.minX, bounds.maxX),
@@ -78,12 +89,16 @@ export function clampFocusToScale(focus: ZoomFocus, zoomScale: number): ZoomFocu
 	};
 }
 
-export function softenFocusToScale(focus: ZoomFocus, zoomScale: number): ZoomFocus {
+export function softenFocusToScale(
+	focus: ZoomFocus,
+	zoomScale: number,
+	viewportRatio?: ViewportRatio,
+): ZoomFocus {
 	const baseFocus = {
 		cx: clamp(focus.cx, 0, 1),
 		cy: clamp(focus.cy, 0, 1),
 	};
-	const bounds = getFocusBoundsForScale(zoomScale);
+	const bounds = getFocusBoundsForScale(zoomScale, viewportRatio);
 	const horizontalRange = bounds.maxX - bounds.minX;
 	const verticalRange = bounds.maxY - bounds.minY;
 	const horizontalSoftness = Math.min(0.12, horizontalRange * 0.35);
diff --git a/src/components/video-editor/videoPlayback/zoomRegionUtils.ts b/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
index 8543907..e5c16e1 100644
--- a/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
+++ b/src/components/video-editor/videoPlayback/zoomRegionUtils.ts
@@ -12,6 +12,7 @@ const ZOOM_IN_OVERLAP_MS = 500;
 type DominantRegionOptions = {
 	connectZooms?: boolean;
 	cursorTelemetry?: CursorTelemetryPoint[];
+	viewportRatio?: ViewportRatio;
 };
 
 type ConnectedRegionPair = {
@@ -66,11 +67,17 @@ function getLinearFocus(start: ZoomFocus, end: ZoomFocus, amount: number): ZoomF
 	};
 }
 
+interface ViewportRatio {
+	widthRatio: number;
+	heightRatio: number;
+}
+
 function getResolvedFocus(
 	region: ZoomRegion,
 	zoomScale: number,
 	timeMs?: number,
 	cursorTelemetry?: CursorTelemetryPoint[],
+	viewportRatio?: ViewportRatio,
 ): ZoomFocus {
 	let focus = region.focus;
 
@@ -86,7 +93,7 @@ function getResolvedFocus(
 		}
 	}
 
-	return clampFocusToScale(focus, zoomScale);
+	return clampFocusToScale(focus, zoomScale, viewportRatio);
 }
 
 function getConnectedRegionPairs(regions: ZoomRegion[]) {
@@ -118,6 +125,7 @@ function getActiveRegion(
 	timeMs: number,
 	connectedPairs: ConnectedRegionPair[],
 	cursorTelemetry?: CursorTelemetryPoint[],
+	viewportRatio?: ViewportRatio,
 ) {
 	const activeRegions = regions
 		.map((region) => {
@@ -152,7 +160,7 @@ function getActiveRegion(
 	return {
 		region: {
 			...activeRegion,
-			focus: getResolvedFocus(activeRegion, activeScale, timeMs, cursorTelemetry),
+			focus: getResolvedFocus(activeRegion, activeScale, timeMs, cursorTelemetry, viewportRatio),
 		},
 		strength: activeRegions[0].strength,
 		blendedScale: null,
@@ -163,6 +171,7 @@ function getConnectedRegionHold(
 	timeMs: number,
 	connectedPairs: ConnectedRegionPair[],
 	cursorTelemetry?: CursorTelemetryPoint[],
+	viewportRatio?: ViewportRatio,
 ) {
 	for (const pair of connectedPairs) {
 		if (timeMs > pair.transitionEnd && timeMs < pair.nextRegion.startMs) {
@@ -170,7 +179,13 @@ function getConnectedRegionHold(
 			return {
 				region: {
 					...pair.nextRegion,
-					focus: getResolvedFocus(pair.nextRegion, nextScale, timeMs, cursorTelemetry),
+					focus: getResolvedFocus(
+						pair.nextRegion,
+						nextScale,
+						timeMs,
+						cursorTelemetry,
+						viewportRatio,
+					),
 				},
 				strength: 1,
 				blendedScale: null,
@@ -185,6 +200,7 @@ function getConnectedRegionTransition(
 	connectedPairs: ConnectedRegionPair[],
 	timeMs: number,
 	cursorTelemetry?: CursorTelemetryPoint[],
+	viewportRatio?: ViewportRatio,
 ) {
 	for (const pair of connectedPairs) {
 		const { currentRegion, nextRegion, transitionStart, transitionEnd } = pair;
@@ -209,10 +225,12 @@ function getConnectedRegionTransition(
 				? sharedCursorFocus
 				: currentRegion.focus,
 			currentScale,
+			viewportRatio,
 		);
 		const nextFocus = clampFocusToScale(
 			nextRegion.focusMode === "auto" && sharedCursorFocus ? sharedCursorFocus : nextRegion.focus,
 			nextScale,
+			viewportRatio,
 		);
 		const transitionFocus = getLinearFocus(currentFocus, nextFocus, transitionProgress);
 
@@ -248,20 +266,21 @@ export function findDominantRegion(
 } {
 	const connectedPairs = options.connectZooms ? getConnectedRegionPairs(regions) : [];
 	const telemetry = options.cursorTelemetry;
+	const vr = options.viewportRatio;
 
 	if (options.connectZooms) {
-		const connectedTransition = getConnectedRegionTransition(connectedPairs, timeMs, telemetry);
+		const connectedTransition = getConnectedRegionTransition(connectedPairs, timeMs, telemetry, vr);
 		if (connectedTransition) {
 			return connectedTransition;
 		}
 
-		const connectedHold = getConnectedRegionHold(timeMs, connectedPairs, telemetry);
+		const connectedHold = getConnectedRegionHold(timeMs, connectedPairs, telemetry, vr);
 		if (connectedHold) {
 			return { ...connectedHold, transition: null };
 		}
 	}
 
-	const activeRegion = getActiveRegion(regions, timeMs, connectedPairs, telemetry);
+	const activeRegion = getActiveRegion(regions, timeMs, connectedPairs, telemetry, vr);
 	return activeRegion
 		? { ...activeRegion, transition: null }
 		: { region: null, strength: 0, blendedScale: null, transition: null };
diff --git a/src/lib/exporter/frameRenderer.ts b/src/lib/exporter/frameRenderer.ts
index d08705d..17986ec 100644
--- a/src/lib/exporter/frameRenderer.ts
+++ b/src/lib/exporter/frameRenderer.ts
@@ -18,13 +18,17 @@ import type {
 } from "@/components/video-editor/types";
 import { ZOOM_DEPTH_SCALES } from "@/components/video-editor/types";
 import {
-	AUTO_FOLLOW_DEADZONE,
+	AUTO_FOLLOW_RAMP_DISTANCE,
 	AUTO_FOLLOW_SMOOTHING_FACTOR,
+	AUTO_FOLLOW_SMOOTHING_FACTOR_MAX,
 	DEFAULT_FOCUS,
 	ZOOM_SCALE_DEADZONE,
 	ZOOM_TRANSLATION_DEADZONE_PX,
 } from "@/components/video-editor/videoPlayback/constants";
-import { smoothCursorFocus } from "@/components/video-editor/videoPlayback/cursorFollowUtils";
+import {
+	adaptiveSmoothFactor,
+	smoothCursorFocus,
+} from "@/components/video-editor/videoPlayback/cursorFollowUtils";
 import { clampFocusToStage as clampFocusToStageUtil } from "@/components/video-editor/videoPlayback/focusUtils";
 import { findDominantRegion } from "@/components/video-editor/videoPlayback/zoomRegionUtils";
 import {
@@ -515,10 +519,16 @@ export class FrameRenderer {
 	private updateAnimationState(timeMs: number): number {
 		if (!this.cameraContainer || !this.layoutCache) return 0;
 
+		const bmEx = this.layoutCache.maskRect;
+		const ssEx = this.layoutCache.stageSize;
+		const viewportRatio =
+			bmEx.width > 0 && bmEx.height > 0
+				? { widthRatio: ssEx.width / bmEx.width, heightRatio: ssEx.height / bmEx.height }
+				: undefined;
 		const { region, strength, blendedScale, transition } = findDominantRegion(
 			this.config.zoomRegions,
 			timeMs,
-			{ connectZooms: true, cursorTelemetry: this.config.cursorTelemetry },
+			{ connectZooms: true, cursorTelemetry: this.config.cursorTelemetry, viewportRatio },
 		);
 
 		const defaultFocus = DEFAULT_FOCUS;
@@ -534,26 +544,26 @@ export class FrameRenderer {
 			targetFocus = regionFocus;
 			targetProgress = strength;
 
-			// Apply deadzone + time-based smoothing for auto-follow mode
+			// Apply adaptive smoothing for auto-follow mode
 			if (region.focusMode === "auto" && !transition) {
 				const raw = targetFocus;
 				const dtMs = this.prevAnimationTimeMs != null ? timeMs - this.prevAnimationTimeMs : 0;
 				const framesElapsed = dtMs > 0 ? dtMs / (1000 / 60) : 1;
-				const factor = 1 - Math.pow(1 - AUTO_FOLLOW_SMOOTHING_FACTOR, Math.max(1, framesElapsed));
 				const isZoomingIn = targetProgress < 0.999 && targetProgress >= this.prevTargetProgress;
 				if (targetProgress >= 0.999) {
-					// Full zoom: apply deadzone + smoothing for stable follow
+					// Full zoom: adaptive smoothing — moves faster when far, decelerates when close
 					const prev = this.smoothedAutoFocus ?? raw;
-					const dx = Math.abs(raw.cx - prev.cx);
-					const dy = Math.abs(raw.cy - prev.cy);
-					if (dx > AUTO_FOLLOW_DEADZONE || dy > AUTO_FOLLOW_DEADZONE) {
-						const smoothed = smoothCursorFocus(raw, prev, factor);
-						this.smoothedAutoFocus = smoothed;
-						targetFocus = smoothed;
-					} else {
-						this.smoothedAutoFocus = prev;
-						targetFocus = prev;
-					}
+					const baseFactor = adaptiveSmoothFactor(
+						raw,
+						prev,
+						AUTO_FOLLOW_SMOOTHING_FACTOR,
+						AUTO_FOLLOW_SMOOTHING_FACTOR_MAX,
+						AUTO_FOLLOW_RAMP_DISTANCE,
+					);
+					const factor = 1 - Math.pow(1 - baseFactor, Math.max(1, framesElapsed));
+					const smoothed = smoothCursorFocus(raw, prev, factor);
+					this.smoothedAutoFocus = smoothed;
+					targetFocus = smoothed;
 				} else if (isZoomingIn) {
 					// Zoom-in: track cursor directly so zoom always aims at current cursor
 					// position; keep ref in sync to avoid snap when full-zoom begins
@@ -561,6 +571,14 @@ export class FrameRenderer {
 				} else {
 					// Zoom-out: keep smoothing for continuity — avoids snap at zoom-out start
 					const prev = this.smoothedAutoFocus ?? raw;
+					const baseFactor = adaptiveSmoothFactor(
+						raw,
+						prev,
+						AUTO_FOLLOW_SMOOTHING_FACTOR,
+						AUTO_FOLLOW_SMOOTHING_FACTOR_MAX,
+						AUTO_FOLLOW_RAMP_DISTANCE,
+					);
+					const factor = 1 - Math.pow(1 - baseFactor, Math.max(1, framesElapsed));
 					const smoothed = smoothCursorFocus(raw, prev, factor);
 					this.smoothedAutoFocus = smoothed;
 					targetFocus = smoothed;

From cd0f2ab3185037f8443a6a4bfb1998800e12a540 Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 22:06:45 +0300
Subject: [PATCH 15/20] fix: expand arrow key guard for form controls and wire
 i18n for fixed shortcuts

- Add HTMLSelectElement and contentEditable to the arrow key input guard
  to prevent intercepting native keyboard behavior on form controls
- Add i18nKey field to FixedShortcut interface and wire up i18n lookups
  in ShortcutsConfigDialog and KeyboardShortcutsHelp so fixed shortcut
  labels are properly localized
---
 .../video-editor/KeyboardShortcutsHelp.tsx    |  6 ++--
 .../video-editor/ShortcutsConfigDialog.tsx    |  8 +++--
 src/components/video-editor/VideoEditor.tsx   |  7 ++++-
 src/lib/shortcuts.ts                          | 31 +++++++++++++++----
 4 files changed, 40 insertions(+), 12 deletions(-)

diff --git a/src/components/video-editor/KeyboardShortcutsHelp.tsx b/src/components/video-editor/KeyboardShortcutsHelp.tsx
index 5287365..b90b377 100644
--- a/src/components/video-editor/KeyboardShortcutsHelp.tsx
+++ b/src/components/video-editor/KeyboardShortcutsHelp.tsx
@@ -37,8 +37,10 @@ export function KeyboardShortcutsHelp() {
 
 					<div className="pt-1 border-t border-white/5 mt-1 space-y-1.5">
 						{FIXED_SHORTCUTS.map((fixed) => (
-							<div key={fixed.label} className="flex items-center justify-between">
-								<span className="text-slate-400">{fixed.label}</span>
+							<div key={fixed.i18nKey} className="flex items-center justify-between">
+								<span className="text-slate-400">
+									{t(`fixedActions.${fixed.i18nKey}`, { defaultValue: fixed.label })}
+								</span>
 								<kbd className="px-1 py-0.5 bg-white/5 border border-white/10 rounded text-[#34B27B] font-mono">
 									{isMac
 										? fixed.display
diff --git a/src/components/video-editor/ShortcutsConfigDialog.tsx b/src/components/video-editor/ShortcutsConfigDialog.tsx
index 775cb8c..faa7513 100644
--- a/src/components/video-editor/ShortcutsConfigDialog.tsx
+++ b/src/components/video-editor/ShortcutsConfigDialog.tsx
@@ -197,12 +197,14 @@ export function ShortcutsConfigDialog() {
 					<p className="text-[10px] text-slate-500 mb-2 uppercase tracking-wide font-semibold">
 						{t("fixed")}
 					</p>
-					{FIXED_SHORTCUTS.map(({ label, display }) => (
+					{FIXED_SHORTCUTS.map(({ i18nKey, label, display }) => (
 						<div
-							key={label}
+							key={i18nKey}
 							className="flex items-center justify-between py-1.5 px-1 border-b border-white/5 last:border-0"
 						>
-							<span className="text-sm text-slate-400">{label}</span>
+							<span className="text-sm text-slate-400">
+								{t(`fixedActions.${i18nKey}`, { defaultValue: label })}
+							</span>
 							<kbd className="px-2 py-1 bg-white/5 border border-white/10 rounded text-xs font-mono text-slate-400 min-w-[90px] text-center">
 								{display}
 							</kbd>
diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index 9cd467a..3efd9ce 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -940,7 +940,12 @@ export default function VideoEditor() {
 				!e.altKey
 			) {
 				const target = e.target;
-				if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+				if (
+					target instanceof HTMLInputElement ||
+					target instanceof HTMLTextAreaElement ||
+					target instanceof HTMLSelectElement ||
+					(target instanceof HTMLElement && target.isContentEditable)
+				) {
 					return;
 				}
 				e.preventDefault();
diff --git a/src/lib/shortcuts.ts b/src/lib/shortcuts.ts
index 1ca4975..00b96b6 100644
--- a/src/lib/shortcuts.ts
+++ b/src/lib/shortcuts.ts
@@ -21,14 +21,16 @@ export interface ShortcutBinding {
 export type ShortcutsConfig = Record<ShortcutAction, ShortcutBinding>;
 
 export interface FixedShortcut {
+	i18nKey: string;
 	label: string;
 	display: string;
 	bindings: ShortcutBinding[];
 }
 
 export const FIXED_SHORTCUTS: FixedShortcut[] = [
-	{ label: "Undo", display: "Ctrl + Z", bindings: [{ key: "z", ctrl: true }] },
+	{ i18nKey: "undo", label: "Undo", display: "Ctrl + Z", bindings: [{ key: "z", ctrl: true }] },
 	{
+		i18nKey: "redo",
 		label: "Redo",
 		display: "Ctrl + Shift + Z / Ctrl + Y",
 		bindings: [
@@ -36,21 +38,38 @@ export const FIXED_SHORTCUTS: FixedShortcut[] = [
 			{ key: "y", ctrl: true },
 		],
 	},
-	{ label: "Cycle Annotations Forward", display: "Tab", bindings: [{ key: "tab" }] },
 	{
+		i18nKey: "cycleAnnotationsForward",
+		label: "Cycle Annotations Forward",
+		display: "Tab",
+		bindings: [{ key: "tab" }],
+	},
+	{
+		i18nKey: "cycleAnnotationsBackward",
 		label: "Cycle Annotations Backward",
 		display: "Shift + Tab",
 		bindings: [{ key: "tab", shift: true }],
 	},
 	{
+		i18nKey: "deleteSelectedAlt",
 		label: "Delete Selected (alt)",
 		display: "Del / ⌫",
 		bindings: [{ key: "delete" }, { key: "backspace" }],
 	},
-	{ label: "Pan Timeline", display: "Shift + Ctrl + Scroll", bindings: [] },
-	{ label: "Zoom Timeline", display: "Ctrl + Scroll", bindings: [] },
-	{ label: "Frame Back", display: "←", bindings: [{ key: "arrowleft" }] },
-	{ label: "Frame Forward", display: "→", bindings: [{ key: "arrowright" }] },
+	{
+		i18nKey: "panTimeline",
+		label: "Pan Timeline",
+		display: "Shift + Ctrl + Scroll",
+		bindings: [],
+	},
+	{ i18nKey: "zoomTimeline", label: "Zoom Timeline", display: "Ctrl + Scroll", bindings: [] },
+	{ i18nKey: "frameBack", label: "Frame Back", display: "←", bindings: [{ key: "arrowleft" }] },
+	{
+		i18nKey: "frameForward",
+		label: "Frame Forward",
+		display: "→",
+		bindings: [{ key: "arrowright" }],
+	},
 ];
 
 export type ShortcutConflict =

From 3bfcd8576b43dcb5395d109feb135724cb6ca478 Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 22:44:25 +0300
Subject: [PATCH 16/20] fix: read live video.currentTime for rapid frame steps
 and add JSDoc

- Read currentTime directly from the video element instead of the React
  ref so rapid arrow key presses each advance by exactly one frame
- Add JSDoc docstrings to frameStep.ts exports
---
 src/components/video-editor/VideoEditor.tsx | 10 +++++++---
 src/lib/frameStep.ts                        |  5 +++++
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index 3efd9ce..e83f5b0 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -949,13 +949,17 @@ export default function VideoEditor() {
 					return;
 				}
 				e.preventDefault();
+				const video = videoPlaybackRef.current?.video;
+				if (!video) {
+					return;
+				}
 				const direction = e.key === "ArrowLeft" ? "backward" : "forward";
 				const newTime = computeFrameStepTime(
-					currentTimeRef.current,
-					durationRef.current,
+					video.currentTime,
+					Number.isFinite(video.duration) ? video.duration : durationRef.current,
 					direction,
 				);
-				handleSeek(newTime);
+				video.currentTime = newTime;
 				return;
 			}
 
diff --git a/src/lib/frameStep.ts b/src/lib/frameStep.ts
index 7eaaf6b..dc42d78 100644
--- a/src/lib/frameStep.ts
+++ b/src/lib/frameStep.ts
@@ -1,5 +1,10 @@
+/** Duration of a single frame in seconds at 60 FPS (~16.67ms). */
 export const FRAME_DURATION_SEC = 1 / 60;
 
+/**
+ * Compute the new playhead time after stepping one frame forward or backward.
+ * The result is clamped to the range [0, duration].
+ */
 export function computeFrameStepTime(
 	currentTime: number,
 	duration: number,

From 97c9a73578ce547356593f03e258ce1595415549 Mon Sep 17 00:00:00 2001
From: theaiagent <h.aykut.cosgun@bozok.edu.tr>
Date: Fri, 3 Apr 2026 23:02:12 +0300
Subject: [PATCH 17/20] fix: skip frame-step on ARIA widgets that own arrow
 keys

Expand the arrow key guard to also skip elements with
role="separator" (PanelResizeHandle), role="slider", and
role="spinbutton" so keyboard panel resizing is not intercepted.
---
 src/components/video-editor/VideoEditor.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/components/video-editor/VideoEditor.tsx b/src/components/video-editor/VideoEditor.tsx
index e83f5b0..e3a30cf 100644
--- a/src/components/video-editor/VideoEditor.tsx
+++ b/src/components/video-editor/VideoEditor.tsx
@@ -944,7 +944,9 @@ export default function VideoEditor() {
 					target instanceof HTMLInputElement ||
 					target instanceof HTMLTextAreaElement ||
 					target instanceof HTMLSelectElement ||
-					(target instanceof HTMLElement && target.isContentEditable)
+					(target instanceof HTMLElement &&
+						(target.isContentEditable ||
+							target.closest('[role="separator"], [role="slider"], [role="spinbutton"]')))
 				) {
 					return;
 				}

From 7e298d3bbfe3f9cfeb236febc6adee91346057be Mon Sep 17 00:00:00 2001
From: Trevin Chow <trevin@trevinchow.com>
Date: Fri, 3 Apr 2026 20:14:20 -0700
Subject: [PATCH 18/20] feat: embed AppImage update information for delta
 updates

Add a top-level publish config in electron-builder.json5 pointing to
GitHub Releases. This embeds the update information URL in the AppImage
header, enabling tools like AppImageUpdate, AppImageLauncher, and
AppManager to perform delta updates instead of full re-downloads.

Also update the Linux build workflow to upload the generated .zsync file
alongside the .AppImage artifact.

Fixes #219
---
 .github/workflows/build.yml |  5 +++--
 electron-builder.json5      | 17 +++++++++--------
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 790884e..4cc446f 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -94,6 +94,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: linux-installer
-          path: release/**/*.AppImage
+          path: |
+            release/**/*.AppImage
+            release/**/*.zsync
           retention-days: 30
-
diff --git a/electron-builder.json5 b/electron-builder.json5
index a8f1dc1..40fce0a 100644
--- a/electron-builder.json5
+++ b/electron-builder.json5
@@ -20,14 +20,15 @@
     "!CONTRIBUTING.md",
     "!LICENSE"
   ],
-  "extraResources": [
-    {
-      "from": "public/wallpapers",
-      "to": "assets/wallpapers"
-    }
-  ],
-
-  "mac": {
+  "extraResources": [
+    {
+      "from": "public/wallpapers",
+      "to": "assets/wallpapers"
+    }
+  ],
+  "publish": [{"provider": "github"}],
+
+  "mac": {
     "hardenedRuntime": false,
     "target": [
       {

From bd604cb658081b46714a9739bb2ec8bc8c033f86 Mon Sep 17 00:00:00 2001
From: Marc Diaz <marcgabe15@gmail.com>
Date: Sat, 4 Apr 2026 20:43:41 -0400
Subject: [PATCH 19/20] add discord to readme

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 0e9ed4d..4cb61c3 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,10 @@
   <a href="https://deepwiki.com/siddharthvaddem/openscreen">
     <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" />
   </a>
+  &nbsp;
+  <a href="https://discord.gg/pHAUbcqNd">
+    <img src="https://img.shields.io/discord/pHAUbcqNd?logo=discord&label=Discord&color=5865F2" alt="Join Discord" />
+  </a>
 </p>
 
 # <p align="center">OpenScreen</p>

From 66f9172a35699037cd400852cc8685b18b25306d Mon Sep 17 00:00:00 2001
From: Marc Diaz <marcgabe15@gmail.com>
Date: Sat, 4 Apr 2026 20:52:14 -0400
Subject: [PATCH 20/20] feat: add discord to readme

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4cb61c3..53d5479 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
     <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" />
   </a>
   &nbsp;
-  <a href="https://discord.gg/pHAUbcqNd">
+  <a href="https://discord.gg/yAQQhRaEeg">
     <img src="https://img.shields.io/discord/pHAUbcqNd?logo=discord&label=Discord&color=5865F2" alt="Join Discord" />
   </a>
 </p>