feat(editor): add frame-by-frame stepping and timeline navigation sho…

src/components/video-editor/KeyboardShortcutsHelp.tsx

@@ -1,8 +1,8 @@
 import { Kbd } from "@heroui/react";
-import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
-import { Button } from "@/components/ui/button";
-import { Gear as Settings2, Question as HelpCircle } from "@/components/ui/icons";
 import { useEffect, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Question as HelpCircle, Gear as Settings2 } from "@/components/ui/icons";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
 import { useScopedT } from "@/contexts/I18nContext";
 import { useShortcuts } from "@/contexts/ShortcutsContext";
 import { formatBinding, SHORTCUT_ACTIONS, SHORTCUT_LABELS } from "@/lib/shortcuts";
@@ -75,6 +75,24 @@ export function KeyboardShortcutsHelp() {
 							</span>
 							<Kbd>{t("keyboardShortcuts.tab")}</Kbd>
 						</div>
+						<div className="flex items-center justify-between mt-1.5">
+							<span className="text-muted-foreground">
+								{t("keyboardShortcuts.stepFrame")}
+							</span>
+							<Kbd>, / . / ← / →</Kbd>
+						</div>
+						<div className="flex items-center justify-between mt-1.5">
+							<span className="text-muted-foreground">
+								{t("keyboardShortcuts.stepSecond")}
+							</span>
+							<Kbd>{isMac ? "⇧" : "Shift"} + ← / →</Kbd>
+						</div>
+						<div className="flex items-center justify-between mt-1.5">
+							<span className="text-muted-foreground">
+								{t("keyboardShortcuts.jumpKeyframe")}
+							</span>
+							<Kbd>{isMac ? "⌥" : "Alt"} + ← / →</Kbd>
+						</div>
 					</div>
 				</div>
 			</PopoverContent>

src/components/video-editor/hooks/useEditorGlobalInteractions.test.ts

@@ -118,3 +118,112 @@ describe("editor playback shortcut", () => {
 		expect(playback.pause).toHaveBeenCalledOnce();
 	});
 });
+
+describe("editor frame-by-frame and timeline stepping shortcuts", () => {
+	function setupStepping() {
+		vi.stubGlobal("HTMLInputElement", Input);
+		vi.stubGlobal("HTMLTextAreaElement", Textarea);
+		vi.stubGlobal("HTMLSelectElement", Select);
+		const handlers = new Map<string, (event: KeyboardEvent) => void>();
+		vi.stubGlobal("window", {
+			addEventListener: (name: string, handler: (event: KeyboardEvent) => void) =>
+				handlers.set(name, handler),
+			removeEventListener: vi.fn(),
+		});
+		const stepFrameBackward = vi.fn();
+		const stepFrameForward = vi.fn();
+		const stepTimeSeconds = vi.fn();
+		const handlePreviewSkipBack = vi.fn();
+		const handlePreviewSkipForward = vi.fn();
+
+		useEditorGlobalInteractions({
+			timeline: {},
+			videoPlaybackRef: { current: { video: {}, isPlaying: false, pause: vi.fn() } },
+			shortcuts: DEFAULT_SHORTCUTS,
+			isMac: true,
+			startPlayback: vi.fn(),
+			handleUndo: vi.fn(),
+			handleRedo: vi.fn(),
+			stepFrameBackward,
+			stepFrameForward,
+			stepTimeSeconds,
+			handlePreviewSkipBack,
+			handlePreviewSkipForward,
+		} as unknown as Parameters<typeof useEditorGlobalInteractions>[0]);
+
+		const send = (type = "keydown", options: Record<string, unknown> = {}) => {
+			const event = {
+				key: "",
+				code: "",
+				target: new Element(),
+				metaKey: false,
+				ctrlKey: false,
+				shiftKey: false,
+				altKey: false,
+				repeat: false,
+				preventDefault: vi.fn(),
+				stopImmediatePropagation: vi.fn(),
+				...options,
+			};
+			handlers.get(type)!(event as unknown as KeyboardEvent);
+			return event;
+		};
+
+		return {
+			send,
+			stepFrameBackward,
+			stepFrameForward,
+			stepTimeSeconds,
+			handlePreviewSkipBack,
+			handlePreviewSkipForward,
+		};
+	}
+
+	it("steps 1 frame backward with comma or ArrowLeft", () => {
+		const { send, stepFrameBackward } = setupStepping();
+		const e1 = send("keydown", { key: "," });
+		expect(e1.preventDefault).toHaveBeenCalled();
+		expect(stepFrameBackward).toHaveBeenCalledTimes(1);
+
+		const e2 = send("keydown", { key: "ArrowLeft" });
+		expect(e2.preventDefault).toHaveBeenCalled();
+		expect(stepFrameBackward).toHaveBeenCalledTimes(2);
+	});
+
+	it("steps 1 frame forward with period or ArrowRight", () => {
+		const { send, stepFrameForward } = setupStepping();
+		const e1 = send("keydown", { key: "." });
+		expect(e1.preventDefault).toHaveBeenCalled();
+		expect(stepFrameForward).toHaveBeenCalledTimes(1);
+
+		const e2 = send("keydown", { key: "ArrowRight" });
+		expect(e2.preventDefault).toHaveBeenCalled();
+		expect(stepFrameForward).toHaveBeenCalledTimes(2);
+	});
+
+	it("steps 1 second with Shift + Arrow keys", () => {
+		const { send, stepTimeSeconds } = setupStepping();
+		send("keydown", { key: "ArrowLeft", shiftKey: true });
+		expect(stepTimeSeconds).toHaveBeenCalledWith(-1);
+
+		send("keydown", { key: "ArrowRight", shiftKey: true });
+		expect(stepTimeSeconds).toHaveBeenCalledWith(1);
+	});
+
+	it("skips to keyframes with Alt + Arrow keys", () => {
+		const { send, handlePreviewSkipBack, handlePreviewSkipForward } = setupStepping();
+		send("keydown", { key: "ArrowLeft", altKey: true });
+		expect(handlePreviewSkipBack).toHaveBeenCalled();
+
+		send("keydown", { key: "ArrowRight", altKey: true });
+		expect(handlePreviewSkipForward).toHaveBeenCalled();
+	});
+
+	it("does not step frames when typing in input or textarea", () => {
+		const { send, stepFrameForward, stepFrameBackward } = setupStepping();
+		send("keydown", { key: ".", target: new Input() });
+		send("keydown", { key: "ArrowLeft", target: new Textarea() });
+		expect(stepFrameForward).not.toHaveBeenCalled();
+		expect(stepFrameBackward).not.toHaveBeenCalled();
+	});
+});

src/components/video-editor/hooks/useEditorGlobalInteractions.ts

@@ -12,6 +12,11 @@ type Input = {
 	handleUndo: () => void;
 	handleRedo: () => void;
 	startPlayback: () => void;
+	stepFrameBackward?: () => void;
+	stepFrameForward?: () => void;
+	stepTimeSeconds?: (seconds: number) => void;
+	handlePreviewSkipBack?: () => void;
+	handlePreviewSkipForward?: () => void;
 };
 
 export function useEditorGlobalInteractions({
@@ -22,6 +27,11 @@ export function useEditorGlobalInteractions({
 	handleUndo,
 	handleRedo,
 	startPlayback,
+	stepFrameBackward,
+	stepFrameForward,
+	stepTimeSeconds,
+	handlePreviewSkipBack,
+	handlePreviewSkipForward,
 }: Input) {
 	const heldPlaybackKey = useRef<string | null>(null);
 
@@ -72,6 +82,48 @@ export function useEditorGlobalInteractions({
 				}
 				return;
 			}
+
+			if (!editable) {
+				if (event.altKey && !event.ctrlKey && !event.metaKey) {
+					if (event.key === "ArrowLeft" && handlePreviewSkipBack) {
+						event.preventDefault();
+						handlePreviewSkipBack();
+						return;
+					}
+					if (event.key === "ArrowRight" && handlePreviewSkipForward) {
+						event.preventDefault();
+						handlePreviewSkipForward();
+						return;
+					}
+				}
+
+				if (event.shiftKey && !event.ctrlKey && !event.metaKey && !event.altKey) {
+					if (event.key === "ArrowLeft" && stepTimeSeconds) {
+						event.preventDefault();
+						stepTimeSeconds(-1);
+						return;
+					}
+					if (event.key === "ArrowRight" && stepTimeSeconds) {
+						event.preventDefault();
+						stepTimeSeconds(1);
+						return;
+					}
+				}
+
+				if (!event.shiftKey && !event.ctrlKey && !event.metaKey && !event.altKey) {
+					if ((event.key === "," || event.key === "ArrowLeft") && stepFrameBackward) {
+						event.preventDefault();
+						stepFrameBackward();
+						return;
+					}
+					if ((event.key === "." || event.key === "ArrowRight") && stepFrameForward) {
+						event.preventDefault();
+						stepFrameForward();
+						return;
+					}
+				}
+			}
+
 			if (!matchesShortcut(event, shortcuts.playPause, isMac) || editable) return;
 			consumePlaybackKey(event);
 			if (event.repeat) return;
@@ -89,7 +141,19 @@ export function useEditorGlobalInteractions({
 			window.removeEventListener("keyup", handleKeyUp, { capture: true });
 			window.removeEventListener("blur", releasePlaybackKey);
 		};
-	}, [shortcuts, isMac, handleUndo, handleRedo, startPlayback, videoPlaybackRef]);
+	}, [
+		shortcuts,
+		isMac,
+		handleUndo,
+		handleRedo,
+		startPlayback,
+		videoPlaybackRef,
+		stepFrameBackward,
+		stepFrameForward,
+		stepTimeSeconds,
+		handlePreviewSkipBack,
+		handlePreviewSkipForward,
+	]);
 
 	useEffect(() => {
 		if (

src/components/video-editor/hooks/useEditorPlaybackControls.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from "vitest";
+import { useEditorPlaybackControls } from "./useEditorPlaybackControls";
+
+vi.mock("react", () => ({
+	useCallback: (callback: unknown) => callback,
+	useEffect: (effect: () => void) => effect(),
+	useRef: (current: unknown) => ({ current }),
+}));
+
+describe("useEditorPlaybackControls frame stepping", () => {
+	function setup(timelinePlayheadTime = 5.0, timelineDuration = 10.0) {
+		const video = {};
+		const playback = {
+			video,
+			isPlaying: false,
+			pause: vi.fn(() => {
+				playback.isPlaying = false;
+			}),
+			play: vi.fn().mockResolvedValue(undefined),
+			seekTimeline: vi.fn(),
+		};
+		const videoPlaybackRef = { current: playback };
+		const timelineRef = {
+			current: {
+				keyframes: [
+					{ id: "k1", time: 2000 },
+					{ id: "k2", time: 8000 },
+				],
+			},
+		};
+		const playSourceAudioPreview = vi.fn();
+
+		const controls = useEditorPlaybackControls({
+			videoPlaybackRef: videoPlaybackRef as unknown as Parameters<
+				typeof useEditorPlaybackControls
+			>[0]["videoPlaybackRef"],
+			timelineRef: timelineRef as unknown as Parameters<
+				typeof useEditorPlaybackControls
+			>[0]["timelineRef"],
+			playSourceAudioPreview,
+			timelinePlayheadTime,
+			timelineDuration,
+		});
+
+		return { controls, playback, videoPlaybackRef, timelineRef };
+	}
+
+	it("steps forward by 1 frame (1/60s) and pauses active playback", () => {
+		const { controls, playback } = setup(2.0, 10.0);
+		playback.isPlaying = true;
+
+		controls.stepFrameForward();
+
+		expect(playback.pause).toHaveBeenCalled();
+		expect(playback.seekTimeline).toHaveBeenCalledWith(expect.closeTo(2.0 + 1 / 60, 5));
+	});
+
+	it("steps backward by 1 frame (1/60s) and pauses active playback", () => {
+		const { controls, playback } = setup(2.0, 10.0);
+		playback.isPlaying = true;
+
+		controls.stepFrameBackward();
+
+		expect(playback.pause).toHaveBeenCalled();
+		expect(playback.seekTimeline).toHaveBeenCalledWith(expect.closeTo(2.0 - 1 / 60, 5));
+	});
+
+	it("supports custom fps (e.g. 30fps) for frame stepping", () => {
+		const { controls: c1, playback: p1 } = setup(2.0, 10.0);
+		c1.stepFrameForward(30);
+		expect(p1.seekTimeline).toHaveBeenCalledWith(expect.closeTo(2.0 + 1 / 30, 5));
+
+		const { controls: c2, playback: p2 } = setup(2.0, 10.0);
+		c2.stepFrameBackward(30);
+		expect(p2.seekTimeline).toHaveBeenCalledWith(expect.closeTo(2.0 - 1 / 30, 5));
+	});
+
+	it("clamps frame stepping at 0 when stepping backward near start", () => {
+		const { controls, playback } = setup(0.005, 10.0);
+
+		controls.stepFrameBackward();
+
+		expect(playback.seekTimeline).toHaveBeenCalledWith(0);
+	});
+
+	it("clamps frame stepping at duration when stepping forward near end", () => {
+		const { controls, playback } = setup(9.995, 10.0);
+
+		controls.stepFrameForward();
+
+		expect(playback.seekTimeline).toHaveBeenCalledWith(10.0);
+	});
+
+	it("steps time by custom seconds (e.g. +1s and -1s)", () => {
+		const { controls: c1, playback: p1 } = setup(5.0, 10.0);
+		c1.stepTimeSeconds(1);
+		expect(p1.seekTimeline).toHaveBeenCalledWith(6.0);
+
+		const { controls: c2, playback: p2 } = setup(5.0, 10.0);
+		c2.stepTimeSeconds(-2.5);
+		expect(p2.seekTimeline).toHaveBeenCalledWith(2.5);
+	});
+
+	it("accumulates rapid repeated frame steps correctly across keydowns", () => {
+		const { controls, playback } = setup(1.0, 10.0);
+
+		controls.stepFrameForward(60);
+		expect(playback.seekTimeline).toHaveBeenLastCalledWith(expect.closeTo(1.0 + 1 / 60, 5));
+
+		controls.stepFrameForward(60);
+		expect(playback.seekTimeline).toHaveBeenLastCalledWith(expect.closeTo(1.0 + 2 / 60, 5));
+
+		controls.stepFrameForward(60);
+		expect(playback.seekTimeline).toHaveBeenLastCalledWith(expect.closeTo(1.0 + 3 / 60, 5));
+	});
+});