feat: single undo step for freeze frame

The handler fired four separate commands (asset add, split, move, insert),
producing four undo steps. It now builds one BatchCommand and executes it
once. The new ShiftSplitRemainderCommand resolves the split's right-side
elements lazily at execute() so it can be composed after the split in the
batch, and rebuilds the inner move on redo since a re-executed split
generates fresh element ids.

3 files changed, 236 insertions, 0 deletions

diff --git a/apps/web/src/commands/timeline/element/__tests__/shift-split-remainder.test.ts b/apps/web/src/commands/timeline/element/__tests__/shift-split-remainder.test.ts
new file mode 100644
index 00000000..36d742fe
--- /dev/null
+++ b/apps/web/src/commands/timeline/element/__tests__/shift-split-remainder.test.ts
@@ -0,0 +1,185 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { EditorCore } from "@/core";
+import {
+	BatchCommand,
+	InsertElementCommand,
+	ShiftSplitRemainderCommand,
+	SplitElementsCommand,
+} from "@/commands";
+import { buildDefaultScene } from "@/timeline/scenes";
+import { buildElementFromMedia, type VideoElement } from "@/timeline";
+import {
+	addMediaTime,
+	mediaTimeFromSeconds,
+	ZERO_MEDIA_TIME,
+} from "@/wasm";
+
+const SPLIT_TIME = mediaTimeFromSeconds({ seconds: 4 });
+const FREEZE_DURATION = mediaTimeFromSeconds({ seconds: 3 });
+const VIDEO_DURATION = mediaTimeFromSeconds({ seconds: 10 });
+
+function buildVideoElement(): VideoElement {
+	return {
+		id: "video-1",
+		type: "video",
+		name: "video-1",
+		startTime: ZERO_MEDIA_TIME,
+		duration: VIDEO_DURATION,
+		trimStart: ZERO_MEDIA_TIME,
+		trimEnd: ZERO_MEDIA_TIME,
+		mediaId: "media-video-1",
+		params: {
+			"transform.positionX": 0,
+			"transform.positionY": 0,
+			"transform.scaleX": 1,
+			"transform.scaleY": 1,
+			"transform.rotate": 0,
+			opacity: 1,
+		},
+	};
+}
+
+function seedSceneWithVideo(): { editor: EditorCore; trackId: string } {
+	const editor = EditorCore.getInstance();
+	const scene = buildDefaultScene({ name: "Main scene", isMain: true });
+	scene.tracks.main.elements = [buildVideoElement()];
+	editor.project.setActiveProject({
+		project: {
+			metadata: {
+				id: "project-1",
+				name: "Test project",
+				duration: VIDEO_DURATION,
+				createdAt: new Date("2026-01-01T00:00:00Z"),
+				updatedAt: new Date("2026-01-01T00:00:00Z"),
+			},
+			scenes: [scene],
+			currentSceneId: scene.id,
+			settings: {
+				fps: { numerator: 30, denominator: 1 },
+				canvasSize: { width: 1920, height: 1080 },
+				background: { type: "color", color: "#000000" },
+			},
+			version: 1,
+		},
+	});
+	editor.scenes.setScenes({ scenes: [scene], activeSceneId: scene.id });
+	return { editor, trackId: scene.tracks.main.id };
+}
+
+function buildFreezeBatch({ trackId }: { trackId: string }): BatchCommand {
+	const splitCommand = new SplitElementsCommand({
+		elements: [{ trackId, elementId: "video-1" }],
+		splitTime: SPLIT_TIME,
+	});
+	const shiftCommand = new ShiftSplitRemainderCommand({
+		split: splitCommand,
+		newStartTime: addMediaTime({ a: SPLIT_TIME, b: FREEZE_DURATION }),
+	});
+	const insertCommand = new InsertElementCommand({
+		element: buildElementFromMedia({
+			mediaId: "media-freeze-1",
+			mediaType: "image",
+			name: "Freeze frame",
+			duration: FREEZE_DURATION,
+			startTime: SPLIT_TIME,
+		}),
+		placement: { mode: "explicit", trackId },
+	});
+	return new BatchCommand([splitCommand, shiftCommand, insertCommand]);
+}
+
+describe("ShiftSplitRemainderCommand", () => {
+	beforeEach(() => {
+		EditorCore.reset();
+	});
+
+	test("splits, shifts the right side, and inserts into the gap", () => {
+		const { editor, trackId } = seedSceneWithVideo();
+
+		buildFreezeBatch({ trackId }).execute();
+
+		const elements = editor.scenes
+			.getActiveScene()
+			.tracks.main.elements.slice()
+			.sort((a, b) => (a.startTime > b.startTime ? 1 : -1));
+		expect(elements.map((element) => element.type)).toEqual([
+			"video",
+			"image",
+			"video",
+		]);
+
+		const [left, image, right] = elements;
+		expect(left.startTime).toBe(ZERO_MEDIA_TIME);
+		expect(left.duration).toBe(SPLIT_TIME);
+		expect(image.startTime).toBe(SPLIT_TIME);
+		expect(image.duration).toBe(FREEZE_DURATION);
+		expect(right.startTime).toBe(
+			addMediaTime({ a: SPLIT_TIME, b: FREEZE_DURATION }),
+		);
+		expect(right.duration).toBe(
+			addMediaTime({ a: VIDEO_DURATION, b: mediaTimeFromSeconds({ seconds: -4 }) }),
+		);
+	});
+
+	test("undo restores the original element as a single step", () => {
+		const { editor, trackId } = seedSceneWithVideo();
+		const batch = buildFreezeBatch({ trackId });
+
+		batch.execute();
+		batch.undo();
+
+		const elements = editor.scenes.getActiveScene().tracks.main.elements;
+		expect(elements).toHaveLength(1);
+		expect(elements[0].id).toBe("video-1");
+		expect(elements[0].startTime).toBe(ZERO_MEDIA_TIME);
+		expect(elements[0].duration).toBe(VIDEO_DURATION);
+	});
+
+	test("redo after undo re-applies the shift to the re-split elements", () => {
+		const { editor, trackId } = seedSceneWithVideo();
+		const batch = buildFreezeBatch({ trackId });
+
+		batch.execute();
+		batch.undo();
+		batch.redo();
+
+		const elements = editor.scenes
+			.getActiveScene()
+			.tracks.main.elements.slice()
+			.sort((a, b) => (a.startTime > b.startTime ? 1 : -1));
+		expect(elements.map((element) => element.type)).toEqual([
+			"video",
+			"image",
+			"video",
+		]);
+		// The re-executed split generates fresh right-side ids; the shift must
+		// still land on them.
+		const right = elements.at(-1);
+		expect(right?.type).toBe("video");
+		expect(right?.startTime).toBe(
+			addMediaTime({ a: SPLIT_TIME, b: FREEZE_DURATION }),
+		);
+	});
+
+	test("is a no-op when the split produces no right side", () => {
+		const { editor, trackId } = seedSceneWithVideo();
+
+		const splitCommand = new SplitElementsCommand({
+			elements: [{ trackId, elementId: "video-1" }],
+			splitTime: ZERO_MEDIA_TIME,
+		});
+		const shiftCommand = new ShiftSplitRemainderCommand({
+			split: splitCommand,
+			newStartTime: FREEZE_DURATION,
+		});
+		const batch = new BatchCommand([splitCommand, shiftCommand]);
+
+		expect(() => {
+			batch.execute();
+			batch.undo();
+		}).not.toThrow();
+		expect(
+			editor.scenes.getActiveScene().tracks.main.elements,
+		).toHaveLength(1);
+	});
+});
diff --git a/apps/web/src/commands/timeline/element/index.ts b/apps/web/src/commands/timeline/element/index.ts
index ff365801..cd6dc8f9 100644
--- a/apps/web/src/commands/timeline/element/index.ts
+++ b/apps/web/src/commands/timeline/element/index.ts
@@ -2,6 +2,7 @@ export { InsertElementCommand } from "./insert-element";
 export { DeleteElementsCommand } from "./delete-elements";
 export { DuplicateElementsCommand } from "./duplicate-elements";
 export { SplitElementsCommand } from "./split-elements";
+export { ShiftSplitRemainderCommand } from "./shift-split-remainder";
 export { UpdateElementsCommand } from "./update-elements";
 export { ToggleSourceAudioSeparationCommand } from "./toggle-source-audio-separation";
 export { MoveElementCommand } from "./move-elements";
diff --git a/apps/web/src/commands/timeline/element/shift-split-remainder.ts b/apps/web/src/commands/timeline/element/shift-split-remainder.ts
new file mode 100644
index 00000000..3799c8f9
--- /dev/null
+++ b/apps/web/src/commands/timeline/element/shift-split-remainder.ts
@@ -0,0 +1,50 @@
+import { Command, type CommandResult } from "@/commands/base-command";
+import type { MediaTime } from "@/wasm";
+import { MoveElementCommand } from "./move-elements";
+import type { SplitElementsCommand } from "./split-elements";
+
+/**
+ * Moves the right-side elements produced by a SplitElementsCommand to a new
+ * start time. Must run after the split inside a BatchCommand: the right-side
+ * element ids only exist once the split has executed. Rebuilds the inner move
+ * on every execute() so redo picks up the fresh ids a re-executed split
+ * generates.
+ */
+export class ShiftSplitRemainderCommand extends Command {
+	private inner: MoveElementCommand | null = null;
+
+	constructor({
+		split,
+		newStartTime,
+	}: {
+		split: SplitElementsCommand;
+		newStartTime: MediaTime;
+	}) {
+		super();
+		this.split = split;
+		this.newStartTime = newStartTime;
+	}
+
+	private readonly split: SplitElementsCommand;
+	private readonly newStartTime: MediaTime;
+
+	execute(): CommandResult | undefined {
+		const rightSideElements = this.split.getRightSideElements();
+		if (rightSideElements.length === 0) {
+			return undefined;
+		}
+		this.inner = new MoveElementCommand({
+			moves: rightSideElements.map((element) => ({
+				sourceTrackId: element.trackId,
+				targetTrackId: element.trackId,
+				elementId: element.elementId,
+				newStartTime: this.newStartTime,
+			})),
+		});
+		return this.inner.execute();
+	}
+
+	undo(): void {
+		this.inner?.undo();
+	}
+}