Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

97.5 KB
Raw Blame
// @vitest-environment jsdom

import { act, renderHook, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { I18nProvider } from "@/contexts/I18nContext";
import { DEFAULT_TEXT_PLATE } from "../annotations/background";
import { layoutRuns } from "../document/layout";
import { type RegionKind, readSpeedRegions } from "../document/timeline";
import type { AxcutDocument } from "../schema";
import { axcutSchemaVersion, parseDocumentFile } from "../schema";
import { coalesceRegionsForRuler } from "../timeline/timelineMap";
import { useProjectStore } from "./projectStore";
import { clearHistory, redo, undo } from "./undo";
import { future, past } from "./undoStack";
import { useTimeline } from "./useTimeline";

/**
 * `useTimeline` reads the locale — `addAnnotation` seeds a new region with the
 * translated default text — so it needs the provider. One helper rather than a
 * wrapper argument on every call site.
 */
const renderTimeline = () => renderHook(() => useTimeline(), { wrapper: I18nProvider });

const probeVideoDurationMock = vi.hoisted(() => vi.fn());
const probeVideoDimensionsMock = vi.hoisted(() =>
	vi.fn().mockResolvedValue({ width: 1920, height: 1080 }),
);
const probeAudioDurationMock = vi.hoisted(() => vi.fn().mockResolvedValue(null));
const toastErrorMock = vi.hoisted(() => vi.fn());
// Real implementation unless a test forces an answer (the backfill's timeout branch).
const waitForDocumentSavesMock = vi.hoisted(() => vi.fn());

vi.mock("./projectStore", async (importOriginal) => {
	const actual = await importOriginal<typeof import("./projectStore")>();
	waitForDocumentSavesMock.mockImplementation(actual.waitForDocumentSaves);
	return { ...actual, waitForDocumentSaves: waitForDocumentSavesMock };
});

vi.mock("sonner", () => ({ toast: { error: toastErrorMock } }));

vi.mock("../timeline/duration", async (importOriginal) => {
	const actual = await importOriginal<typeof import("../timeline/duration")>();
	return {
		...actual,
		probeVideoDuration: probeVideoDurationMock,
		probeVideoDimensions: probeVideoDimensionsMock,
		probeAudioDuration: probeAudioDurationMock,
	};
});

const bridgeMocks = vi.hoisted(() => ({
	get: vi.fn(),
	create: vi.fn(),
	save: vi.fn(),
	addAsset: vi.fn(),
	removeAsset: vi.fn(),
	listProjects: vi.fn(),
}));

vi.mock("@/native/client", () => ({
	nativeBridgeClient: {
		aiEdition: {
			get: bridgeMocks.get,
			create: bridgeMocks.create,
			save: bridgeMocks.save,
			addAsset: bridgeMocks.addAsset,
			removeAsset: bridgeMocks.removeAsset,
			listProjects: bridgeMocks.listProjects,
		},
	},
}));

const sampleDoc: AxcutDocument = {
	// ponytail: the bridge contract after the migration hoist is the CURRENT version —
	// every load site (DocumentService, browserShim) runs `migrateRawDocumentToCurrent`
	// before returning, and the renderer's `parseDocument` is a pure current-version
	// validator. Test fixtures model the post-hoist contract, so they read the version
	// off `axcutSchemaVersion` instead of restating it.
	// Annotated `AxcutDocument` rather than left to inference: the document type
	// pins `schemaVersion` to the LITERAL 8 and `kind` to `"video"`, both of which
	// an unannotated object literal widens — and the annotation makes every
	// required field (`cameraTrack`) a compile error when it is missing instead of
	// a fixture that silently drifts from the schema.
	schemaVersion: axcutSchemaVersion,
	project: {
		id: "proj_test",
		title: "Test",
		createdAt: "2026-06-25T10:00:00.000Z",
		updatedAt: "2026-06-25T10:00:00.000Z",
		primaryAssetId: "asset_1",
	},
	assets: [
		{
			id: "asset_1",
			kind: "video",
			label: "screen.webm",
			originalPath: "/tmp/screen.webm",
			durationSec: 30,
			video: { codec: "unknown", width: 1920, height: 1080, fps: 0 },
			// No webcam was recorded alongside this screen capture.
			cameraTrack: null,
		},
	],
	transcript: null,
	transcripts: [],
	timeline: {
		clips: [
			{
				id: "clip_a",
				assetId: "asset_1",
				sourceStartSec: 0,
				sourceEndSec: 10,
				timelineStartSec: 0,
				timelineEndSec: 10,
				wordRefs: [],
				origin: "user",
				reason: "",
			},
		],
		gaps: [],
		trimRanges: [],
		muteRanges: [],
		speedRanges: [],
		captionRanges: [],
	},
	annotations: [],
	zoomRanges: [],
	audioTracks: [],
	legacyEditor: null,
};

describe("layout authoring history", () => {
	beforeEach(() => {
		useProjectStore.getState().clear();
		clearHistory();
		bridgeMocks.save.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: AxcutDocument) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({ projectId: "proj_test", document: sampleDoc, currentTimeSec: 5 });
	});
	afterEach(() => {
		useProjectStore.getState().clear();
		clearHistory();
	});
	it("records each partition edit once and restores it with undo/redo", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addLayoutChange("no-webcam");
		});
		expect(result.current.layoutSegments.map((r) => r.start)).toEqual([0, 5]);
		expect(past).toHaveLength(1);
		const id = result.current.layoutSegments[1].ids[0];
		await act(async () => {
			await result.current.moveLayoutBoundary(id, 8);
		});
		expect(result.current.layoutSegments[1].start).toBe(8);
		expect(past).toHaveLength(2);
		act(() => undo());
		expect(result.current.layoutSegments[1].start).toBe(5);
		act(() => redo());
		expect(result.current.layoutSegments[1].start).toBe(8);
		await act(async () => {
			await result.current.removeRegion("layout", id);
		});
		expect(result.current.layoutSegments).toHaveLength(1);
		expect(past).toHaveLength(3);
	});
	it("does not record a failed layout save or alter the document", async () => {
		bridgeMocks.save.mockResolvedValue({ success: false, error: "disk full" });
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addLayoutChange("no-webcam");
		});
		expect(useProjectStore.getState().document).toBe(sampleDoc);
		expect(past).toHaveLength(0);
	});
});

describe("useTimeline.insertClipAt background duration probe", () => {
	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		probeVideoDurationMock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: {
				...sampleDoc,
				assets: [
					...sampleDoc.assets,
					{
						id: "asset_2",
						kind: "video",
						label: "long.webm",
						originalPath: "/tmp/long.webm",
						durationSec: undefined,
						video: { codec: "unknown", width: 1920, height: 1080, fps: 0 },
						cameraTrack: null,
					},
				],
			},
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("only resizes the probed clip and leaves earlier clips' positions untouched", async () => {
		// clip_a already sits at 0..10 (a "short clip"). Insert a second clip
		// for asset_2 after it — insertClipAt has no cached duration for
		// asset_2, so it lands at the 60s placeholder, then the background
		// probe (mocked here to resolve to a much shorter real duration)
		// corrects it. Regression test for the bug where the probe used to
		// shift EVERY sibling clip (including ones before it) by the delta
		// between the real and placeholder duration, corrupting their
		// positions and producing visual overlap.
		probeVideoDurationMock.mockResolvedValue(5);
		const { result } = renderTimeline();

		await act(async () => {
			await result.current.insertClipAt("asset_2", 1);
		});

		const clips = useProjectStore.getState().document?.timeline.clips;
		expect(clips).toHaveLength(2);
		const clipA = clips?.find((c) => c.id === "clip_a");
		const inserted = clips?.find((c) => c.assetId === "asset_2");
		expect(clipA).toMatchObject({ timelineStartSec: 0, timelineEndSec: 10 });
		expect(inserted).toMatchObject({
			sourceEndSec: 5,
			timelineStartSec: 10,
			timelineEndSec: 15,
		});
	});
});

describe("useTimeline.moveClip / duplicateClip (delegates to document/timeline.ts)", () => {
	const twoClipDoc: AxcutDocument = {
		...sampleDoc,
		timeline: {
			...sampleDoc.timeline,
			clips: [
				sampleDoc.timeline.clips[0],
				{
					id: "clip_b",
					assetId: "asset_1",
					// Does not continue where clip_a stops, on purpose: two clips of one recording
					// whose media timecodes meet are one clip, so a fixture like that would
					// collapse under any structural edit.
					sourceStartSec: 15,
					sourceEndSec: 25,
					timelineStartSec: 10,
					timelineEndSec: 20,
					wordRefs: [],
					origin: "user" as const,
					reason: "",
				},
			],
		},
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: twoClipDoc,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("moveClip reorders clips and persists the resequenced timeline", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.moveClip("clip_a", 1);
		});
		const clips = useProjectStore.getState().document?.timeline.clips;
		expect(clips?.map((c) => c.id)).toEqual(["clip_b", "clip_a"]);
		expect(clips?.[0]).toMatchObject({ timelineStartSec: 0, timelineEndSec: 10 });
		expect(clips?.[1]).toMatchObject({ timelineStartSec: 10, timelineEndSec: 20 });
	});

	it("moveClip no-ops for an unknown clip id", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.moveClip("clip_missing", 0);
		});
		expect(bridgeMocks.save).not.toHaveBeenCalled();
	});

	it("duplicateClip inserts a copy right after the original and selects it", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.duplicateClip("clip_a");
		});
		const clips = useProjectStore.getState().document?.timeline.clips;
		expect(clips).toHaveLength(3);
		expect(clips?.[0].id).toBe("clip_a");
		expect(clips?.[2].id).toBe("clip_b");
		const copyId = clips?.[1].id;
		expect(copyId).toBeTruthy();
		expect(copyId).not.toBe("clip_a");
		expect(result.current.clipSelection).toBe(copyId);
	});

	it("duplicateClip no-ops for an unknown clip id", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.duplicateClip("clip_missing");
		});
		expect(bridgeMocks.save).not.toHaveBeenCalled();
	});
});

describe("useTimeline backfills missing source dimensions on load", () => {
	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		probeVideoDimensionsMock.mockReset();
		probeVideoDimensionsMock.mockResolvedValue({ width: 1920, height: 1080 });
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	// The reported bug: a project saved with a duration but no probed `video` dims (nothing
	// re-probes it on open) drops that clip from everything reading asset.video — the ratio
	// picker's ORIGINAL list, the output resolution, the export badges.
	it("probes a used asset that has a duration but no video dims, and persists them", async () => {
		useProjectStore.setState({
			projectId: "proj_test",
			document: {
				...sampleDoc,
				assets: [{ ...sampleDoc.assets[0], video: undefined }],
			},
			revision: 1,
			status: "ready",
			error: null,
		});
		renderTimeline();
		await waitFor(() => expect(bridgeMocks.save).toHaveBeenCalledTimes(1));
		expect(probeVideoDimensionsMock).toHaveBeenCalledTimes(1);
		const saved = useProjectStore.getState().document?.assets.find((a) => a.id === "asset_1");
		expect(saved?.video).toMatchObject({ width: 1920, height: 1080 });
	});

	// A fresh recording: the document is rewritten (duration, camera link, auto-zoom) while
	// the probe is still out. That re-render used to cancel the probe's write for good.
	it("still persists probed dims when the document changes while the probe is running", async () => {
		let resolveProbe!: (dims: { width: number; height: number }) => void;
		probeVideoDimensionsMock.mockReturnValue(
			new Promise((resolve) => {
				resolveProbe = resolve;
			}),
		);
		const unprobed = { ...sampleDoc, assets: [{ ...sampleDoc.assets[0], video: undefined }] };
		useProjectStore.setState({
			projectId: "proj_test",
			document: unprobed,
			revision: 1,
			status: "ready",
			error: null,
		});
		renderTimeline();
		await waitFor(() => expect(probeVideoDimensionsMock).toHaveBeenCalledTimes(1));
		act(() => {
			useProjectStore.setState({ document: { ...unprobed, zoomRanges: [] }, revision: 2 });
		});
		await act(async () => {
			resolveProbe({ width: 1080, height: 1920 });
		});
		await waitFor(() => expect(bridgeMocks.save).toHaveBeenCalledTimes(1));
		const saved = useProjectStore.getState().document?.assets.find((a) => a.id === "asset_1");
		expect(saved?.video).toMatchObject({ width: 1080, height: 1920 });
	});

	// The fresh-recording auto-zooms are saved while the probe is out. The store only takes
	// them once that save returns, so a backfill built on the store before then erased them.
	it("keeps a save that is still in flight when the probe resolves", async () => {
		let resolveProbe!: (dims: { width: number; height: number }) => void;
		probeVideoDimensionsMock.mockReturnValue(
			new Promise((resolve) => {
				resolveProbe = resolve;
			}),
		);
		const unprobed = { ...sampleDoc, assets: [{ ...sampleDoc.assets[0], video: undefined }] };
		useProjectStore.setState({
			projectId: "proj_test",
			document: unprobed,
			revision: 1,
			status: "ready",
			error: null,
		});
		renderTimeline();
		await waitFor(() => expect(probeVideoDimensionsMock).toHaveBeenCalledTimes(1));

		let releaseZoomSave!: () => void;
		const zoomSaveGate = new Promise<void>((resolve) => {
			releaseZoomSave = resolve;
		});
		bridgeMocks.save.mockImplementationOnce(async (doc: typeof sampleDoc) => {
			await zoomSaveGate;
			return { success: true, document: doc };
		});
		const zoomed = {
			...unprobed,
			zoomRanges: [
				{ id: "zoom_1", startMs: 0, endMs: 1000, depth: 3, focus: { cx: 0.5, cy: 0.5 } },
			],
		} as AxcutDocument;
		let zoomSave!: Promise<boolean>;
		act(() => {
			zoomSave = useProjectStore.getState().saveDocument(zoomed, { history: true });
		});
		await act(async () => {
			resolveProbe({ width: 1080, height: 1920 });
			await new Promise((r) => setTimeout(r, 0));
		});
		await act(async () => {
			releaseZoomSave();
			await zoomSave;
		});

		await waitFor(() => expect(bridgeMocks.save).toHaveBeenCalledTimes(2));
		await waitFor(() => {
			const doc = useProjectStore.getState().document;
			expect(doc?.zoomRanges).toHaveLength(1);
			expect(doc?.assets.find((a) => a.id === "asset_1")?.video).toMatchObject({
				width: 1080,
				height: 1920,
			});
		});
	});

	// A wait that times out says nothing about what landed, so the backfill writes nothing.
	// It must not leave the asset marked attempted either, or no later run ever probes it.
	it("probes again on the next document change after the save wait timed out", async () => {
		waitForDocumentSavesMock.mockResolvedValueOnce("timeout");
		const unprobed = { ...sampleDoc, assets: [{ ...sampleDoc.assets[0], video: undefined }] };
		useProjectStore.setState({
			projectId: "proj_test",
			document: unprobed,
			revision: 1,
			status: "ready",
			error: null,
		});
		renderTimeline();
		await waitFor(() => expect(waitForDocumentSavesMock).toHaveBeenCalledTimes(1));
		await act(async () => {
			await new Promise((r) => setTimeout(r, 0));
		});
		expect(bridgeMocks.save).not.toHaveBeenCalled();

		act(() => {
			useProjectStore.setState({ document: { ...unprobed, zoomRanges: [] }, revision: 2 });
		});
		await waitFor(() => expect(bridgeMocks.save).toHaveBeenCalledTimes(1));
		expect(probeVideoDimensionsMock).toHaveBeenCalledTimes(2);
		const saved = useProjectStore.getState().document?.assets.find((a) => a.id === "asset_1");
		expect(saved?.video).toMatchObject({ width: 1920, height: 1080 });
	});

	it("leaves an asset that already has video dims untouched", async () => {
		useProjectStore.setState({
			projectId: "proj_test",
			document: sampleDoc, // asset_1 already carries 1920x1080
			revision: 1,
			status: "ready",
			error: null,
		});
		renderTimeline();
		// Give any stray effect a chance to fire before asserting it didn't.
		await act(async () => {
			await new Promise((r) => setTimeout(r, 0));
		});
		expect(probeVideoDimensionsMock).not.toHaveBeenCalled();
		expect(bridgeMocks.save).not.toHaveBeenCalled();
	});

	it("does not re-probe a used asset with no reachable file more than once", async () => {
		probeVideoDimensionsMock.mockResolvedValue(null); // probe fails (unreadable file)
		useProjectStore.setState({
			projectId: "proj_test",
			document: {
				...sampleDoc,
				assets: [{ ...sampleDoc.assets[0], video: undefined }],
			},
			revision: 1,
			status: "ready",
			error: null,
		});
		const { rerender } = renderTimeline();
		await act(async () => {
			await new Promise((r) => setTimeout(r, 0));
		});
		rerender();
		await act(async () => {
			await new Promise((r) => setTimeout(r, 0));
		});
		// Attempted once; the failure is remembered so a document change doesn't spin it again.
		expect(probeVideoDimensionsMock).toHaveBeenCalledTimes(1);
		expect(bridgeMocks.save).not.toHaveBeenCalled();
	});
});

describe("useTimeline.applyClipEdit (Edit-clip modal)", () => {
	const anchoredZoom = (id: string, s: number, e: number) => ({
		id,
		startMs: s * 1000,
		endMs: e * 1000,
		clipId: "clip_a",
		sourceStartSec: s,
		sourceEndSec: e,
		depth: 3 as const,
		focus: { cx: 0.5, cy: 0.5 },
	});

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: {
				...sampleDoc,
				zoomRanges: [anchoredZoom("z_keep", 2, 3), anchoredZoom("z_drop", 6, 8)],
			},
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("shrinks the clip's timeline width to match the narrowed source window", async () => {
		const { result } = renderTimeline();
		// Trim the 10s clip down to its first 4s of source.
		await act(async () => {
			await result.current.applyClipEdit("clip_a", 0, 4);
		});
		const clip = useProjectStore.getState().document?.timeline.clips[0];
		expect(clip).toMatchObject({ sourceStartSec: 0, sourceEndSec: 4 });
		// The width followed the edit instead of keeping its stale 10s extent.
		expect(clip?.timelineStartSec).toBe(0);
		expect(clip?.timelineEndSec).toBe(4);
	});

	it("drops a pill sitting over the truncated tail and keeps the one that survives", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.applyClipEdit("clip_a", 0, 4);
		});
		const zooms = useProjectStore.getState().document?.zoomRanges ?? [];
		// z_keep (source 2-3) stays; z_drop (source 6-8) is entirely past the new 4s end.
		expect(zooms.map((z) => z.id)).toEqual(["z_keep"]);
		expect(zooms[0]).toMatchObject({
			sourceStartSec: 2,
			sourceEndSec: 3,
			startMs: 2000,
			endMs: 3000,
		});
	});

	it("shortens a pill that straddles the new clip end to the surviving overlap", async () => {
		useProjectStore.setState({
			document: {
				...sampleDoc,
				zoomRanges: [anchoredZoom("z_edge", 3, 7)],
			},
		});
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.applyClipEdit("clip_a", 0, 5);
		});
		const zooms = useProjectStore.getState().document?.zoomRanges ?? [];
		expect(zooms).toHaveLength(1);
		// 3-7 clamped to the [0,5] window → 3-5.
		expect(zooms[0]).toMatchObject({
			sourceStartSec: 3,
			sourceEndSec: 5,
			startMs: 3000,
			endMs: 5000,
		});
	});

	// #355. Apply used to fire `updateClipSourceRange` and `updateClipCrop` as two
	// concurrent saves, each built from the same pre-Apply document — so the second
	// write clobbered the first and one of the two edits vanished with no error and no
	// toast. Which one survived depended on IPC timing, which is why it read as "the app
	// randomly forgets my crop".
	it("keeps BOTH the source range and the crop when Apply changes them together", async () => {
		const { result } = renderTimeline();
		const crop = { x: 0.1, y: 0.2, width: 0.5, height: 0.5 };
		await act(async () => {
			await result.current.applyClipEdit("clip_a", 0, 4, crop);
		});
		const clip = useProjectStore.getState().document?.timeline.clips[0];
		expect(clip).toMatchObject({ sourceStartSec: 0, sourceEndSec: 4, cropRegion: crop });
		// The width still followed the range edit — the crop is applied to the
		// RESEQUENCED clips, not to a stale copy of them.
		expect(clip?.timelineEndSec).toBe(4);
		// One user action, one document, one write: two saves is the race itself.
		expect(bridgeMocks.save).toHaveBeenCalledTimes(1);
	});

	it("clears the crop on an explicit null and leaves it alone on undefined", async () => {
		useProjectStore.setState({
			document: {
				...sampleDoc,
				timeline: {
					...sampleDoc.timeline,
					clips: [
						{ ...sampleDoc.timeline.clips[0], cropRegion: { x: 0, y: 0, width: 0.5, height: 1 } },
					],
				},
			},
		});
		const { result } = renderTimeline();
		// `undefined` is the modal's "crop section untouched" — the stored region stays.
		await act(async () => {
			await result.current.applyClipEdit("clip_a", 0, 6);
		});
		expect(useProjectStore.getState().document?.timeline.clips[0].cropRegion).toEqual({
			x: 0,
			y: 0,
			width: 0.5,
			height: 1,
		});
		// `null` is "reset to no crop", stored as an absent field rather than the
		// identity region.
		await act(async () => {
			await result.current.applyClipEdit("clip_a", 0, 6, null);
		});
		expect(useProjectStore.getState().document?.timeline.clips[0].cropRegion).toBeUndefined();
	});
});

// #353. The toolbar button and the `C` shortcut both used to write a region on a
// project with no webcam: it persists into `legacyEditor.cameraFullscreenRegions`,
// renders nothing in the preview (PreviewCanvas short-circuits on a missing
// `webcamRect`) and nothing in the export, forever, with no feedback. The gate lives
// in the shared mutation so both entry points — and any future one — are covered.
describe("useTimeline.addCameraFullscreen (camera gate)", () => {
	const cameraAsset = {
		...sampleDoc.assets[0],
		cameraTrack: {
			sourcePath: "/tmp/camera.webm",
			startMs: 0,
			offsetMs: 0,
			visible: true,
			// Dimensions filled in so the hook's backfill probe has nothing to do — an
			// unprobed camera would fire its own `saveDocument` alongside this test's.
			width: 1280,
			height: 720,
		},
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: sampleDoc,
			currentTimeSec: 1,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("writes nothing when no clip on the timeline has a camera", async () => {
		// sampleDoc's only asset carries `cameraTrack: null`.
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addCameraFullscreen();
		});
		expect(bridgeMocks.save).not.toHaveBeenCalled();
		expect(useProjectStore.getState().document?.legacyEditor).toBeNull();
		expect(result.current.cameraFullscreenRegions).toEqual([]);
	});

	it("still writes a region when a clip's asset carries a camera", async () => {
		useProjectStore.setState({ document: { ...sampleDoc, assets: [cameraAsset] } });
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addCameraFullscreen();
		});
		const regions =
			useProjectStore
				.getState()
				.document?.layoutRegions?.filter((r) => r.preset === "camera-only") ?? [];
		expect(regions).toHaveLength(1);
		// 2s at the playhead (currentTimeSec = 1), the shared default.
		expect(regions[0]).toMatchObject({ startMs: 1000, endMs: 3000 });
	});
});

describe("useTimeline shader effects (the Effects lane and its inspector)", () => {
	const effect = {
		id: "fx_1",
		name: "Dim",
		description: "",
		contract: 1,
		code: "fn effect(uv: vec2<f32>) -> vec4<f32> { return frame(uv) * params.level; }",
		params: [
			{ type: "number" as const, name: "level", label: "Level", default: 1, min: 0, max: 2 },
		],
		origin: "agent" as const,
	};
	const range = (id: string, startMs: number, endMs: number) => ({
		id,
		startMs,
		endMs,
		clipId: "clip_a",
		sourceStartSec: startMs / 1000,
		sourceEndSec: endMs / 1000,
		effectId: "fx_1",
		values: {},
		target: "image" as const,
	});
	const effectDoc: AxcutDocument = {
		...sampleDoc,
		shaderEffects: [effect],
		// Another value on the second, so it stays a pill of its own beside the first.
		shaderEffectRanges: [
			range("fxr_1", 1000, 3000),
			{ ...range("fxr_2", 5000, 7000), values: { level: 0.5 } },
		],
	};
	const ranges = () => useProjectStore.getState().document?.shaderEffectRanges ?? [];

	beforeEach(() => {
		useProjectStore.getState().clear();
		clearHistory();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: effectDoc,
			currentTimeSec: 1,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("moves an effect up to its neighbour, never over it: one effect at a time", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateShaderEffectSpan("fxr_1", 2000, 6000);
		});
		const [moved, wall] = coalesceRegionsForRuler(ranges());
		expect(moved.end).toBeLessThanOrEqual(5);
		expect([wall.start, wall.end]).toEqual([5, 7]);
	});

	it("re-tunes a value live, then saves it as one undo step; retargets in one write", async () => {
		const { result } = renderTimeline();
		const before = past.length;
		act(() => {
			result.current.updateShaderEffectLive("fxr_1", { values: { level: 1.5 } });
			result.current.updateShaderEffectLive("fxr_1", { values: { level: 0.5 } });
		});
		await act(async () => {
			await result.current.commitShaderEffectChange();
		});
		expect(ranges().find((r) => r.id === "fxr_1")?.values).toEqual({ level: 0.5 });
		expect(past.length).toBe(before + 1);
		await act(async () => {
			await result.current.updateShaderEffect("fxr_1", { target: "text", values: { level: 1 } });
		});
		// Back at its default, the value is not stored.
		expect(ranges().find((r) => r.id === "fxr_1")).toMatchObject({ target: "text", values: {} });
		await act(async () => {
			await undo();
			await undo();
		});
		expect(ranges().find((r) => r.id === "fxr_1")).toMatchObject({ target: "image", values: {} });
	});

	it("deletes effects in a batch, and their definition with the last", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.removeRegions([
				{ kind: "shaderEffect", id: "fxr_1" },
				{ kind: "shaderEffect", id: "fxr_2" },
			]);
		});
		const doc = useProjectStore.getState().document;
		expect(doc?.shaderEffectRanges).toEqual([]);
		expect(doc?.shaderEffects).toEqual([]);
	});
});

describe("useTimeline.addAnnotation", () => {
	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: sampleDoc,
			currentTimeSec: 1,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("creates a text annotation carrying the localised default text", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		const annotations = useProjectStore.getState().document?.annotations ?? [];
		expect(annotations).toHaveLength(1);
		// Real text, not an empty field. An empty annotation renders nothing at
		// all, so adding one used to change nothing on the canvas; the
		// inspector's placeholder is CSS ghost text that never reaches `content`
		// and therefore never reached the compositor. DEFAULT_LOCALE is `en`.
		expect(annotations[0]).toMatchObject({ type: "text", content: "Hello" });
		// Still auto-selected, so its inspector opens ready to be typed over.
		expect(result.current.selection).toEqual({
			kind: "annotation",
			id: (annotations[0] as { id: string }).id,
		});
	});

	it("centres the new text box and puts it on a dark plate that reads on any page", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		const [annotation] = useProjectStore.getState().document?.annotations ?? [];
		const { position, size } = annotation as {
			position: { x: number; y: number };
			size: { width: number; height: number };
		};
		expect([position.x + size.width / 2, position.y + size.height / 2]).toEqual([50, 50]);
		expect(annotation.style.backgroundColor).toBe(DEFAULT_TEXT_PLATE);
	});

	it("adds above the highest saved layer even after other annotations were deleted", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		const doc = useProjectStore.getState().document as AxcutDocument;
		act(() => {
			useProjectStore.setState({
				document: {
					...doc,
					annotations: [{ ...doc.annotations[0], zIndex: 12 }],
				},
			});
		});
		await act(async () => {
			await result.current.addAnnotation();
		});
		expect(useProjectStore.getState().document?.annotations.map((a) => a.zIndex)).toEqual([12, 13]);
	});

	it("moves above an overlapping annotation on an occupied track", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		await act(async () => {
			await result.current.addAnnotation();
		});
		const before = useProjectStore.getState().document as AxcutDocument;
		const [low, high] = before.annotations;
		await act(async () => {
			await result.current.updateAnnotationSpan(low.id, 1500, 3500, { row: 0, direction: "up" });
		});
		const after = useProjectStore.getState().document as AxcutDocument;
		expect(after.annotations.find((a) => a.id === high.id)).toMatchObject({ ...high, zIndex: 0 });
		expect(after.annotations.find((a) => a.id === low.id)?.zIndex).toBe(1);
	});

	it("preserves saved compositing tie order on a horizontal move into an identical annotation", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		const doc = useProjectStore.getState().document as AxcutDocument;
		const original = doc.annotations[0];
		act(() => {
			useProjectStore.setState({
				document: {
					...doc,
					annotations: [
						original,
						{
							...original,
							id: "second",
							startMs: 5000,
							endMs: 7000,
							sourceStartSec: 5,
							sourceEndSec: 7,
						},
					],
				},
			});
		});
		await act(async () => {
			await result.current.updateAnnotationSpan("second", 2000, 4000);
		});
		const after = useProjectStore.getState().document as AxcutDocument;
		expect(after.annotations.find((a) => a.id === original.id)).toEqual(original);
		expect(after.annotations.find((a) => a.id === "second")).toMatchObject({
			zIndex: original.zIndex,
			startMs: 2000,
			endMs: 4000,
		});
	});

	it("moves down below an overlapping annotation with the same saved layer", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		const doc = useProjectStore.getState().document as AxcutDocument;
		const back = doc.annotations[0];
		act(() => {
			useProjectStore.setState({
				document: { ...doc, annotations: [back, { ...back, id: "front" }] },
			});
		});
		await act(async () => {
			await result.current.updateAnnotationSpan("front", 2000, 4000, { row: 1, direction: "down" });
		});
		const annotations = useProjectStore.getState().document?.annotations ?? [];
		expect(annotations.find((a) => a.id === "front")?.zIndex).toBe(0);
		expect(annotations.find((a) => a.id === back.id)?.zIndex).toBe(1);
	});

	it("saves an overlapping span and bottom-layer move together and supports undo, redo and reload", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.addAnnotation();
		});
		await act(async () => {
			await result.current.addAnnotation();
		});
		const doc = useProjectStore.getState().document as AxcutDocument;
		act(() => {
			useProjectStore.setState({
				document: {
					...doc,
					annotations: doc.annotations.map((a, i) => ({ ...a, zIndex: i })),
				},
			});
		});
		const before = useProjectStore.getState().document as AxcutDocument;
		clearHistory();
		bridgeMocks.save.mockClear();
		const id = before.annotations[1].id;
		await act(async () => {
			await result.current.updateAnnotationSpan(id, 2000, 4000, { row: 1, direction: "down" });
		});
		const after = useProjectStore.getState().document as AxcutDocument;
		expect(bridgeMocks.save).toHaveBeenCalledTimes(1);
		expect(after.annotations.find((a) => a.id === id)).toMatchObject({
			startMs: 2000,
			endMs: 4000,
			zIndex: 0,
		});
		expect(after.annotations.find((a) => a.id !== id)?.zIndex).toBe(1);
		expect(parseDocumentFile(JSON.parse(JSON.stringify(after))).annotations).toEqual(
			after.annotations,
		);
		await act(async () => {
			await undo();
		});
		expect(useProjectStore.getState().document?.annotations).toEqual(before.annotations);
		await act(async () => {
			await redo();
		});
		expect(useProjectStore.getState().document?.annotations).toEqual(after.annotations);
	});
});

// The Clear timeline button. Every edit region on every clip, one write; the content stays.
describe("useTimeline.clearTimeline", () => {
	type Timeline = ReturnType<typeof useTimeline>;
	type EditKind = Exclude<RegionKind, "audio" | "cameraFullscreen">;

	// A Record rather than a list: a new region kind fails to compile here until this suite
	// decides whether "Clear timeline" takes it. Each adder goes through the real hook, so
	// every region is schema-valid by construction.
	const addOf: Record<EditKind, (tl: Timeline) => Promise<unknown>> = {
		zoom: (tl) => tl.addZoom(),
		trim: (tl) => tl.addTrim(),
		annotation: (tl) => tl.addAnnotation(),
		speed: (tl) => tl.addSpeed(),
		layout: (tl) => tl.addLayoutChange("no-webcam", 2),
		// The editor has no effect lane: agents add effects, so this one is written as they do.
		shaderEffect: async () => {
			const doc = useProjectStore.getState().document as AxcutDocument;
			const clip = doc.timeline.clips[0];
			await useProjectStore.getState().saveDocument(
				{
					...doc,
					shaderEffects: [
						{
							id: "fx_1",
							name: "Pass-through",
							description: "",
							contract: 1,
							code: "fn effect(uv: vec2<f32>) -> vec4<f32> { return frame(uv); }",
							params: [],
							origin: "agent",
						},
					],
					shaderEffectRanges: [
						{
							id: "fxr_1",
							startMs: 0,
							endMs: 1000,
							clipId: clip.id,
							sourceStartSec: clip.sourceStartSec,
							sourceEndSec: clip.sourceStartSec + 1,
							effectId: "fx_1",
							values: {},
							target: "image",
						},
					],
				},
				{ history: true },
			);
		},
	};
	const editKinds = Object.keys(addOf) as EditKind[];

	const regionCounts = (doc: AxcutDocument | null | undefined): Record<EditKind, number> => {
		return {
			zoom: doc?.zoomRanges.length ?? 0,
			trim: doc?.timeline.trimRanges.length ?? 0,
			annotation: doc?.annotations.length ?? 0,
			speed: doc ? readSpeedRegions(doc).length : 0,
			layout: doc ? Math.max(0, layoutRuns(doc).length - 1) : 0,
			shaderEffect: doc?.shaderEffectRanges?.length ?? 0,
		};
	};
	const noRegions: Record<EditKind, number> = {
		zoom: 0,
		trim: 0,
		annotation: 0,
		speed: 0,
		layout: 0,
		shaderEffect: 0,
	};

	// A project holding everything that is NOT an edit: two clips, a webcam, an imported
	// audio track, a transcript, captions, a pause, and settings in the legacy envelope.
	const clipA = sampleDoc.timeline.clips[0];
	const contentDoc: AxcutDocument = {
		...sampleDoc,
		assets: [
			{
				...sampleDoc.assets[0],
				// Dimensions filled in so the hook's backfill probe has nothing to do.
				cameraTrack: {
					sourcePath: "/tmp/camera.webm",
					startMs: 0,
					offsetMs: 0,
					visible: true,
					width: 1280,
					height: 720,
				},
			},
			{
				id: "audio_1",
				kind: "audio",
				label: "vo.mp3",
				originalPath: "/tmp/vo.mp3",
				durationSec: 30,
				cameraTrack: null,
			},
		],
		transcripts: [{ assetId: "asset_1", language: "en", segments: [], words: [] }],
		timeline: {
			...sampleDoc.timeline,
			clips: [
				clipA,
				{
					...clipA,
					id: "clip_b",
					sourceStartSec: 10,
					sourceEndSec: 20,
					timelineStartSec: 10,
					timelineEndSec: 20,
				},
			],
			muteRanges: [{ startSec: 3, endSec: 4, reason: "pause" }],
			captionRanges: [{ startSec: 1, endSec: 2, reason: "caption" }],
		},
		audioTracks: [
			{
				id: "trk_1",
				assetId: "audio_1",
				kind: "voiceover",
				startMs: 0,
				endMs: 5000,
				durationSec: 30,
				offsetMs: 0,
				gainDb: 0,
				loop: false,
				fadeInMs: 0,
				fadeOutMs: 0,
				muted: false,
				label: "vo.mp3",
				origin: "user",
			},
		],
		legacyEditor: { aspectRatio: "16:9" },
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: contentDoc,
			currentTimeSec: 1,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	const addEveryKind = async (result: { current: Timeline }) => {
		for (const kind of editKinds) {
			await act(async () => {
				await addOf[kind](result.current);
			});
		}
	};

	it.each(editKinds)("clears a timeline holding only a %s region", async (kind) => {
		const { result } = renderTimeline();
		await act(async () => {
			await addOf[kind](result.current);
		});
		expect(regionCounts(useProjectStore.getState().document)).toEqual({
			...noRegions,
			[kind]: 1,
		});
		// What the button's visibility reads: the stored regions, the same ones it clears.
		expect(result.current.hasEditRegions).toBe(true);

		await act(async () => {
			await result.current.clearTimeline();
		});
		expect(regionCounts(useProjectStore.getState().document)).toEqual(noRegions);
		expect(result.current.hasEditRegions).toBe(false);
	});

	// A trim whose carrying clip is gone is stored but not drawn: `coalescedTrimGroups` drops
	// it from the lane, and loading accepts it (no schema rule ties `clipId` to a clip). The
	// button follows the STORED regions, or it would hide while the action still had one to clear.
	it("counts and clears a stored trim whose clip no longer exists, though no pill shows it", async () => {
		const orphanDoc: AxcutDocument = {
			...contentDoc,
			timeline: {
				...contentDoc.timeline,
				trimRanges: [
					{
						id: "trim_orphan",
						assetId: "asset_1",
						clipId: "clip_gone",
						startSec: 1,
						endSec: 3,
						reason: "",
						origin: "user",
					},
				],
			},
		};
		// Loading keeps it: the schema does not tie a trim's `clipId` to an existing clip.
		expect(parseDocumentFile(orphanDoc).timeline.trimRanges).toHaveLength(1);
		useProjectStore.setState({ document: orphanDoc });
		const { result } = renderTimeline();
		expect(result.current.hasEditRegions).toBe(true);

		await act(async () => {
			await result.current.clearTimeline();
		});
		expect(useProjectStore.getState().document?.timeline.trimRanges).toEqual([]);
		expect(result.current.hasEditRegions).toBe(false);
	});

	it("clears every region kind at once and keeps clips, media, audio, captions and transcript", async () => {
		const { result } = renderTimeline();
		await addEveryKind(result);
		const before = useProjectStore.getState().document;
		expect(regionCounts(before)).toEqual({
			zoom: 1,
			trim: 1,
			annotation: 1,
			speed: 1,
			layout: 1,
			shaderEffect: 1,
		});

		await act(async () => {
			await result.current.clearTimeline();
		});
		const after = useProjectStore.getState().document;
		expect(regionCounts(after)).toEqual(noRegions);
		expect(after?.timeline.clips).toEqual(before?.timeline.clips);
		expect(after?.timeline.clips).toHaveLength(2);
		expect(after?.assets).toEqual(before?.assets);
		expect(after?.audioTracks).toEqual(before?.audioTracks);
		expect(after?.audioTracks).toHaveLength(1);
		expect(after?.transcripts).toEqual(before?.transcripts);
		expect(after?.timeline.captionRanges).toEqual(before?.timeline.captionRanges);
		expect(after?.timeline.muteRanges).toEqual(before?.timeline.muteRanges);
		expect((after?.legacyEditor as { aspectRatio?: string }).aspectRatio).toBe("16:9");
	});

	it("is one undo step: a single Ctrl+Z restores every region, redo clears them again", async () => {
		const { result } = renderTimeline();
		await addEveryKind(result);
		const before = useProjectStore.getState().document;
		const stepsBefore = past.length;

		await act(async () => {
			await result.current.clearTimeline();
		});
		expect(past).toHaveLength(stepsBefore + 1);

		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document).toEqual(before);
		expect(regionCounts(useProjectStore.getState().document)).toEqual({
			zoom: 1,
			trim: 1,
			annotation: 1,
			speed: 1,
			layout: 1,
			shaderEffect: 1,
		});

		act(() => {
			expect(redo()).toBe(true);
		});
		expect(regionCounts(useProjectStore.getState().document)).toEqual(noRegions);
	});

	it("lets go of a selection that pointed at a region it just removed", async () => {
		const { result } = renderTimeline();
		// A fresh annotation is auto-selected.
		await act(async () => {
			await result.current.addAnnotation();
		});
		expect(result.current.selection?.kind).toBe("annotation");

		await act(async () => {
			await result.current.clearTimeline();
		});
		expect(result.current.selection).toBeNull();
		expect(result.current.multiSelection).toEqual([]);
	});

	it("writes nothing when the timeline holds no edit region, whatever else it holds", async () => {
		const { result } = renderTimeline();
		// Audio track, captions and clips are all there, and none of them is an edit.
		expect(result.current.hasEditRegions).toBe(false);
		await act(async () => {
			await result.current.clearTimeline();
		});
		expect(bridgeMocks.save).not.toHaveBeenCalled();
		expect(past).toHaveLength(0);
	});
});

describe("useTimeline zoom modifiers (rotation + focus mode)", () => {
	const docWithZoom: AxcutDocument = {
		...sampleDoc,
		zoomRanges: [
			{
				id: "zoom_a",
				startMs: 1000,
				endMs: 3000,
				depth: 3,
				focus: { cx: 0.5, cy: 0.5 },
				focusMode: "manual",
				// v5 clip anchor: clip_a draws source 0..10 at timeline 0..10, so the
				// 1000..3000ms ruler span is source 1..3 of that clip. `startMs`/`endMs`
				// stay as the derived cache. (The fixture used to carry a
				// `clipStartOffsetMs` that exists in no schema and no reader.)
				clipId: "clip_a",
				sourceStartSec: 1,
				sourceEndSec: 3,
			},
		],
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: docWithZoom,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("sets a 3D rotation preset on the region", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateZoomRotation("zoom_a", "left");
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			id: "zoom_a",
			rotationPreset: "left",
		});
	});

	it("clears the preset back to a flat frame", async () => {
		// "None" in the UI is the ABSENCE of a preset, not a fourth one: the schema field is
		// optional and the native side treats anything unrecognised as zero rotation.
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateZoomRotation("zoom_a", "left");
		});
		await act(async () => {
			await result.current.updateZoomRotation("zoom_a", undefined);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0].rotationPreset).toBeUndefined();
	});

	it("switches focus mode without disturbing the rotation preset", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateZoomRotation("zoom_a", "left");
		});
		await act(async () => {
			await result.current.updateZoomFocusMode("zoom_a", "auto");
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			rotationPreset: "left",
			focusMode: "auto",
		});
	});

	it("stores a moving camera in the same field as the fixed angles", async () => {
		// One control, one field: a moving camera replaces a fixed angle instead of stacking on it.
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateZoomRotation("zoom_a", "left");
		});
		await act(async () => {
			await result.current.updateZoomRotation("zoom_a", "orbit");
		});
		const zoom = useProjectStore.getState().document?.zoomRanges[0];
		expect(zoom?.rotationPreset).toBe("orbit");
		expect(zoom).not.toHaveProperty("cameraMotion");
	});

	it("updates hideCursor on a zoom region", async () => {
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateZoomHideCursor("zoom_a", true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0].hideCursor).toBe(true);

		await act(async () => {
			await result.current.updateZoomHideCursor("zoom_a", false);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0].hideCursor).toBeUndefined();
	});

	it("rolls a live focus edit back when its commit cannot be saved", async () => {
		bridgeMocks.save.mockResolvedValueOnce({ success: false, error: "project file locked" });
		const { result } = renderTimeline();

		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
		expect(useProjectStore.getState().document?.zoomRanges[0]?.focus).toEqual({
			cx: 0.8,
			cy: 0.2,
		});

		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(useProjectStore.getState().document?.zoomRanges[0]?.focus).toEqual({
			cx: 0.5,
			cy: 0.5,
		});
		// Still dirty, deliberately. The rollback target is the document this drag
		// started from, not the last SAVED one, so claiming "clean" would let the window
		// close on unsaved work without a prompt.
		expect(useProjectStore.getState().dirty).toBe(true);
		// The live edit advanced revision once; restoring a different document
		// advances it again so async work cannot mistake the rollback for the
		// optimistic document it replaced.
		expect(useProjectStore.getState().revision).toBe(3);
		expect(toastErrorMock).toHaveBeenCalledWith("Failed to save project", {
			description: "project file locked",
		});
	});

	it("does not restore another project's document after the project changed", async () => {
		// A drag does not always end in a commit: `ZoomFocusOverlay` unmounts the instant
		// `focusMode` flips to "auto", so `endDrag` never runs and the snapshot outlives
		// the project. Restoring it into the NEXT project put project A's document in
		// project B, and the following successful save wrote A over B on disk.
		const { result, rerender } = renderTimeline();

		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));

		const otherProjectDoc: AxcutDocument = {
			...docWithZoom,
			project: { ...docWithZoom.project, id: "proj_other", title: "Other" },
		};
		act(() => {
			useProjectStore.setState({ projectId: "proj_other", document: otherProjectDoc });
		});
		rerender();

		bridgeMocks.save.mockResolvedValueOnce({ success: false, error: "project file locked" });
		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(useProjectStore.getState().document?.project.id).toBe("proj_other");
	});
});

describe("useTimeline edits one region of a merged pill (#1017)", () => {
	// One 4–13 s pill of two regions with the same properties: `zoom_x` on clip A, and
	// `zoom_p` drawn across the A|B junction, stored as one fragment per clip.
	const zoom = (id: string, clipId: string, startSec: number, endSec: number) => ({
		id,
		startMs: startSec * 1000,
		endMs: endSec * 1000,
		depth: 3 as const,
		focus: { cx: 0.5, cy: 0.5 },
		clipId,
		// Both clips play the source at its own timeline position.
		sourceStartSec: startSec,
		sourceEndSec: endSec,
	});
	const clipA = sampleDoc.timeline.clips[0];
	const docWithMergedPill: AxcutDocument = {
		...sampleDoc,
		timeline: {
			...sampleDoc.timeline,
			clips: [
				clipA,
				{
					...clipA,
					id: "clip_b",
					sourceStartSec: 10,
					sourceEndSec: 20,
					timelineStartSec: 10,
					timelineEndSec: 20,
				},
			],
		},
		zoomRanges: [
			zoom("zoom_x", "clip_a", 4, 7),
			zoom("zoom_p", "clip_a", 7, 10),
			zoom("zoom_p_b", "clip_b", 10, 13),
		],
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: docWithMergedPill,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	it("changes the region picked and its fragments, not its look-alike, and the pill splits", async () => {
		expect(coalesceRegionsForRuler(docWithMergedPill.zoomRanges)).toHaveLength(1);
		const { result } = renderTimeline();
		await act(async () => {
			await result.current.updateZoomDepth("zoom_p_b", 2);
		});
		const zooms = useProjectStore.getState().document?.zoomRanges ?? [];
		expect(zooms.map((z) => [z.id, z.depth])).toEqual([
			["zoom_x", 3],
			["zoom_p", 2],
			["zoom_p_b", 2],
		]);
		expect(coalesceRegionsForRuler(zooms).map((p) => p.ids)).toEqual([
			["zoom_x"],
			["zoom_p", "zoom_p_b"],
		]);
	});
});

// Regression guard for the playhead-stutter fix. `currentTimeSec` is rewritten on
// every animation frame during playback, and `useTimeline()` is called by the editor
// shell — so subscribing to the playhead here re-rendered the entire editor (timeline,
// clips, waveforms, inspector) 60×/s, which is exactly what made the playhead itself
// stutter. The hook must read the playhead imperatively: zero re-renders per tick, but
// still the LIVE value at the moment an action fires.
describe("useTimeline is not re-rendered by playhead ticks", () => {
	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: sampleDoc,
			revision: 1,
			status: "ready",
			error: null,
			currentTimeSec: 0,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("does not re-render across a second of 60 Hz playhead writes", () => {
		let renders = 0;
		renderHook(
			() => {
				renders++;
				return useTimeline();
			},
			{ wrapper: I18nProvider },
		);
		const baseline = renders;

		// One act() per write: a single batched act() would collapse all 60 into one
		// React pass and hide the very thing this asserts.
		for (let i = 1; i <= 60; i++) {
			act(() => {
				useProjectStore.getState().setCurrentTime(i / 60);
			});
		}

		expect(renders - baseline).toBe(0);
		expect(useProjectStore.getState().currentTimeSec).toBeCloseTo(1);
	});

	it("still anchors a new region at the live playhead", async () => {
		const { result } = renderTimeline();
		act(() => {
			useProjectStore.getState().setCurrentTime(4.2);
		});
		await act(async () => {
			await result.current.addZoom();
		});
		expect(useProjectStore.getState().document?.zoomRanges.at(-1)).toMatchObject({
			startMs: 4200,
			endMs: 6200,
			// Framing what the pointer does, not the middle of the screen.
			focusMode: "auto",
		});
	});

	// Pasting a copied trim is exactly this call: a trim carries no properties, so
	// all a copy holds is its length, and paste recreates one that long at the
	// playhead. Same primitive the toolbar's cut button uses.
	it("creates a trim of the requested length", async () => {
		const { result } = renderTimeline();
		act(() => {
			useProjectStore.getState().setCurrentTime(3);
		});
		await act(async () => {
			await result.current.addTrim(1.25);
		});
		const trim = useProjectStore.getState().document?.timeline.trimRanges.at(-1);
		expect((trim?.endSec ?? 0) - (trim?.startSec ?? 0)).toBeCloseTo(1.25, 6);
	});

	// The timeline's toolbar passes a duration worth a fixed number of pixels at
	// the current zoom; every other entry point keeps the 2 s above.
	it("honours a caller-supplied duration", async () => {
		const { result } = renderTimeline();
		act(() => {
			useProjectStore.getState().setCurrentTime(4.2);
		});
		await act(async () => {
			await result.current.addZoom(0.4);
		});
		expect(useProjectStore.getState().document?.zoomRanges.at(-1)).toMatchObject({
			startMs: 4200,
			endMs: 4600,
		});
	});
});

describe("useTimeline selection", () => {
	// A pill and a clip are one selection, not two. While both could be set at
	// once, copy/paste keyed off "is a clip selected?" and so acted on the clip
	// whatever the user had actually clicked.
	it("lets a clip and a pill cancel each other", () => {
		const { result } = renderTimeline();

		act(() => result.current.selectClip("clip_1"));
		expect(result.current.clipSelection).toBe("clip_1");

		act(() => result.current.selectRegion("zoom", "z1"));
		expect(result.current.selection).toMatchObject({ kind: "zoom", id: "z1" });
		expect(result.current.clipSelection).toBeNull();

		act(() => result.current.selectClip("clip_2"));
		expect(result.current.clipSelection).toBe("clip_2");
		expect(result.current.selection).toBeNull();
		expect(result.current.multiSelection).toEqual([]);

		act(() => result.current.clearSelection());
		expect(result.current.selection).toBeNull();
		expect(result.current.clipSelection).toBeNull();
	});
});

describe("useTimeline save failures", () => {
	afterEach(() => {
		vi.clearAllMocks();
	});

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		toastErrorMock.mockReset();
		bridgeMocks.save.mockResolvedValue({ success: false, error: "disk full" });
		useProjectStore.setState({
			projectId: "proj_test",
			document: sampleDoc,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	it("surfaces a rejected mutation without applying it or leaking the rejection", async () => {
		const { result } = renderTimeline();

		await act(async () => {
			await expect(result.current.removeClip("clip_a")).resolves.toBeUndefined();
		});

		expect(toastErrorMock).toHaveBeenCalledWith("Failed to save project", {
			description: "disk full",
		});
		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(1);
		expect(useProjectStore.getState().document?.timeline.clips[0]?.id).toBe("clip_a");
	});

	it("reports 0 zooms added when the bulk write fails", async () => {
		// The count is what the Auto-enhance caller shows in its success toast, so a
		// failed write returning `suggestions.length` produced "Added 3 automatic zooms"
		// stacked on "Failed to save project", with no zoom anywhere. The caller guards
		// on this 0 (`V4Timeline` runAutoZooms).
		const { result } = renderTimeline();

		let added: number | undefined;
		await act(async () => {
			added = await result.current.addZoomsBulk([
				{ span: { start: 1000, end: 2000 }, focus: { cx: 0.5, cy: 0.5 }, depth: 3 },
			]);
		});

		expect(added).toBe(0);
		expect(useProjectStore.getState().document?.zoomRanges).toHaveLength(0);
	});
});

describe("useTimeline undo history", () => {
	// `addAsset` (electron/ai-edition/document-service.ts) never writes `durationSec`,
	// so EVERY freshly imported asset lands at the 60s placeholder and fires the
	// background probe. Anything the probe records is therefore on the undo stack of
	// every single drop, which is what makes these two the common case and not an
	// edge one.
	const unprobed = {
		id: "asset_3",
		kind: "video" as const,
		label: "fresh-import.mp4",
		originalPath: "/tmp/fresh-import.mp4",
		durationSec: undefined,
		// No `video` either: that is what `addAsset` produces, and it is what makes
		// `probeAndCorrectClip` save even once the clip it came for is gone.
		cameraTrack: null,
	};

	const docWithZoom: AxcutDocument = {
		...sampleDoc,
		zoomRanges: [
			{
				id: "zoom_a",
				startMs: 1000,
				endMs: 3000,
				depth: 3,
				focus: { cx: 0.5, cy: 0.5 },
				focusMode: "manual",
				clipId: "clip_a",
				sourceStartSec: 1,
				sourceEndSec: 3,
			},
		],
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		clearHistory();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		probeVideoDurationMock.mockReset();
		probeVideoDimensionsMock.mockResolvedValue({ width: 1920, height: 1080 });
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	function seed(document: AxcutDocument) {
		useProjectStore.setState({
			projectId: "proj_test",
			document,
			revision: 1,
			status: "ready",
			error: null,
		});
	}

	it("keeps the background duration probe off the undo stack", async () => {
		// Without `{ history: false }` on `probeAndCorrectClip`'s save, dropping a clip
		// left `past` = [beforeDrop, dropWithPlaceholderClip]: the first Ctrl+Z snapped
		// the clip back to a 60s placeholder instead of removing it.
		seed({ ...sampleDoc, assets: [...sampleDoc.assets, unprobed] });
		probeVideoDurationMock.mockResolvedValue(5);
		const { result } = renderTimeline();

		await act(async () => {
			await result.current.insertClipAt("asset_3", 1);
		});
		await waitFor(() => {
			const inserted = useProjectStore
				.getState()
				.document?.timeline.clips.find((c) => c.assetId === "asset_3");
			expect(inserted?.sourceEndSec).toBe(5);
		});

		// One step for the drop the user made, none for the probe that corrected it.
		expect(past).toHaveLength(1);
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(1);
	});

	it("does not let a probe landing after an undo destroy the redo", async () => {
		// The probe is detached from the drop, so it can resolve at any point — including
		// after the user has already pressed Ctrl+Z. A recording save there ran
		// `pushHistory`, which clears `future` on its way past: redo was gone, wiped by a
		// write the user never made and never saw.
		seed({ ...sampleDoc, assets: [...sampleDoc.assets, unprobed] });
		let landProbe!: (durationSec: number) => void;
		probeVideoDurationMock.mockReturnValue(
			new Promise<number>((resolvePromise) => {
				landProbe = resolvePromise;
			}),
		);
		const { result } = renderTimeline();

		await act(async () => {
			await result.current.insertClipAt("asset_3", 1);
		});
		expect(past).toHaveLength(1);

		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(1);
		expect(future).toHaveLength(1);

		await act(async () => {
			landProbe(5);
			// The clip is gone, so only the dimensions half of the probe still has
			// anything to write — and that is exactly the write that used to be recorded.
			await new Promise((resolveTick) => setTimeout(resolveTick, 0));
		});

		expect(past).toHaveLength(0);
		expect(future).toHaveLength(1);
		act(() => {
			expect(redo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.timeline.clips).toHaveLength(2);
	});

	// Holds the first document save until the test releases it; every later one lands at once.
	const gateFirstSave = () => {
		const gate: { release?: () => void } = {};
		let calls = 0;
		bridgeMocks.save.mockImplementation(async (doc: AxcutDocument) => {
			calls += 1;
			if (calls === 1) {
				await new Promise<void>((resolve) => {
					gate.release = resolve;
				});
			}
			return { success: true, document: doc };
		});
		return gate;
	};

	it("lands rapid zoom-level steps in order, one undo step each", async () => {
		seed(docWithZoom);
		const gate = gateFirstSave();
		const { result } = renderTimeline();

		const p4 = result.current.updateZoomDepth("zoom_a", 4);
		const p5 = result.current.updateZoomDepth("zoom_a", 5);
		await waitFor(() => expect(gate.release).toEqual(expect.any(Function)));
		await act(async () => {
			gate.release?.();
			await Promise.all([p4, p5]);
		});

		expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(5);
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(4);
	});

	// A custom scale overrides the depth, so a preset that left it in place would change a
	// field the render never reads.
	it("clamps a custom zoom level to the renderer's range, and a preset clears it", async () => {
		seed(docWithZoom);
		const { result } = renderTimeline();

		await act(async () => {
			await result.current.updateZoomCustomScale("zoom_a", 9);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]?.customScale).toBe(5);

		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 4);
		});
		const zoom = useProjectStore.getState().document?.zoomRanges[0];
		expect(zoom?.depth).toBe(4);
		expect(zoom?.customScale).toBeUndefined();
	});

	it("keeps a pending zoom level when the 3D tilt is changed before it lands", async () => {
		seed(docWithZoom);
		const gate = gateFirstSave();
		const { result } = renderTimeline();

		const pDepth = result.current.updateZoomDepth("zoom_a", 4);
		const pRotation = result.current.updateZoomRotation("zoom_a", "left");
		await waitFor(() => expect(gate.release).toEqual(expect.any(Function)));
		await act(async () => {
			gate.release?.();
			await Promise.all([pDepth, pRotation]);
		});

		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			depth: 4,
			rotationPreset: "left",
		});
	});

	// A resize built its save from the render's document, outside the zoom chain: whichever of
	// the two saves landed last put the other's field back.
	it("keeps a pending zoom level when the pill is resized before it lands", async () => {
		seed(docWithZoom);
		const gate = gateFirstSave();
		const { result } = renderTimeline();

		const pDepth = result.current.updateZoomDepth("zoom_a", 4);
		const pSpan = result.current.updateZoomSpan("zoom_a", 1500, 3500);
		await waitFor(() => expect(gate.release).toEqual(expect.any(Function)));
		await act(async () => {
			gate.release?.();
			await Promise.all([pDepth, pSpan]);
		});

		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			depth: 4,
			startMs: 1500,
			endMs: 3500,
		});
	});

	// The inspector's "Reset focus point" is a live write and its commit in one click, next to
	// the level buttons. The level landing first also takes the live focus off screen, so the
	// commit has to put it back on top rather than save what it finds.
	it("keeps a pending zoom level when a focus is committed before it lands", async () => {
		seed(docWithZoom);
		const gate = gateFirstSave();
		const { result } = renderTimeline();

		const pDepth = result.current.updateZoomDepth("zoom_a", 4);
		await waitFor(() => expect(gate.release).toEqual(expect.any(Function)));
		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
		const pCommit = result.current.commitZoomFocus();
		await act(async () => {
			gate.release?.();
			await Promise.all([pDepth, pCommit]);
		});

		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			depth: 4,
			focus: { cx: 0.8, cy: 0.2 },
		});
		// One undo step each, the focus first.
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			depth: 4,
			focus: { cx: 0.5, cy: 0.5 },
		});
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(3);
	});

	// The commit's focus is put back only over a write of its own epoch. A drag abandoned
	// (`ZoomFocusOverlay` unmounts when the focus mode flips to auto) and then undone must stay
	// undone when a bare commit (`endDrag` with nothing in front of it) comes later.
	it("does not put an abandoned drag's focus back after an undo", async () => {
		seed(docWithZoom);
		const { result } = renderTimeline();

		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 4);
		});
		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(future).toHaveLength(1);

		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(useProjectStore.getState().document?.zoomRanges[0]?.focus).toEqual({
			cx: 0.5,
			cy: 0.5,
		});
		expect(future).toHaveLength(1);
	});

	// A zoom write that runs while a focus drag is on screen saves the dragged focus too, so the
	// commit finds nothing left to record. That write's undo step has to reach back to before
	// the drag, or no Ctrl+Z could ever bring the old focus back.
	it("undoes a focus drag with the zoom write that saved it", async () => {
		seed(docWithZoom);
		const { result } = renderTimeline();

		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 4);
		});
		await act(async () => {
			await result.current.commitZoomFocus();
		});

		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			depth: 3,
			focus: { cx: 0.5, cy: 0.5 },
		});
	});

	// Rebase-review finding (queued zoom writes vs. document replacement): a zoom write
	// queued behind a still-pending one starts AFTER an undo has restored the document,
	// and must not apply its stale patch to the replacement. The in-flight write itself
	// is dropped by `saveDocument`'s epoch check; the queued one is the hole.
	it("drops a queued zoom write that starts after an undo replaces the document", async () => {
		seed(docWithZoom);
		const { result } = renderTimeline();
		// One settled write so the undo has a recorded state to restore.
		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 4);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(4);

		const gate = gateFirstSave();
		const pRotation = result.current.updateZoomRotation("zoom_a", "left");
		const pCursor = result.current.updateZoomHideCursor("zoom_a", true);
		await waitFor(() => expect(gate.release).toEqual(expect.any(Function)));
		let undid = false;
		act(() => {
			undid = undo();
		});
		expect(undid).toBe(true);
		expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(3);

		await act(async () => {
			gate.release?.();
			await Promise.allSettled([pRotation, pCursor]);
		});

		// The undo's result stands; neither queued write landed on the restored document.
		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({ depth: 3 });
		expect(useProjectStore.getState().document?.zoomRanges[0]?.rotationPreset).toBeUndefined();
		expect(useProjectStore.getState().document?.zoomRanges[0]?.hideCursor).toBeUndefined();
	});

	// Same finding through the project-switch path: `loadProject` replaces projectId and
	// document without superseding the queue, and project B deliberately contains the same
	// region id, so a stale patch must not escape detection by id coincidence.
	it("drops queued zoom writes when a project switch replaces the document", async () => {
		seed(docWithZoom);
		const { result } = renderTimeline();
		const projectB: AxcutDocument = {
			...docWithZoom,
			project: { ...docWithZoom.project, id: "proj_b", title: "Project B" },
			zoomRanges: [{ ...docWithZoom.zoomRanges[0]!, depth: 2 }],
		};

		const gate = gateFirstSave();
		const pRotation = result.current.updateZoomRotation("zoom_a", "left");
		const pCursor = result.current.updateZoomHideCursor("zoom_a", true);
		await waitFor(() => expect(gate.release).toEqual(expect.any(Function)));
		bridgeMocks.get.mockResolvedValue({ success: true, document: projectB });
		await act(async () => {
			await useProjectStore.getState().loadProject("proj_b");
		});
		expect(useProjectStore.getState().projectId).toBe("proj_b");

		await act(async () => {
			gate.release?.();
			await Promise.allSettled([pRotation, pCursor]);
		});

		// Project B's own zoom_a is untouched by the stale project-A queue.
		expect(useProjectStore.getState().document?.zoomRanges[0]).toMatchObject({
			id: "zoom_a",
			depth: 2,
		});
		expect(useProjectStore.getState().document?.zoomRanges[0]?.rotationPreset).toBeUndefined();
		expect(useProjectStore.getState().document?.zoomRanges[0]?.hideCursor).toBeUndefined();
	});

	// Rebase-review finding (stalled save blocks the zoom queue): while one zoom save's
	// answer is unknown (bridge never settles), later zoom-pane writes must not queue
	// behind it forever — they are refused until the unknown save settles, then work
	// again. The refusal is the safe half: the unknown save may still land, so racing
	// it would recreate the stale-document overwrite this chain exists to prevent.
	it("refuses zoom writes while a save is unknown and recovers when it settles", async () => {
		seed(docWithZoom);
		vi.useFakeTimers();
		try {
			let hungDoc: AxcutDocument | undefined;
			let releaseHungSave: (result: { success: boolean; document: AxcutDocument }) => void;
			bridgeMocks.save.mockImplementation((doc: AxcutDocument) => {
				hungDoc = doc;
				return new Promise((resolve) => {
					releaseHungSave = (result) => {
						// Settle this one call only; later saves answer immediately.
						bridgeMocks.save.mockImplementation(async (next: AxcutDocument) => ({
							success: true,
							document: next,
						}));
						resolve(result);
					};
				});
			});
			const { result } = renderTimeline();

			let depthOk: boolean | undefined;
			act(() => {
				void result.current.updateZoomDepth("zoom_a", 4).then((ok) => {
					depthOk = ok;
				});
			});
			// Deadline passes with the bridge still silent: the write's result is unknown,
			// reported to the caller as not-taken, and the document is left alone.
			await act(async () => {
				await vi.advanceTimersByTimeAsync(10_000);
			});
			expect(depthOk).toBe(false);
			expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(3);

			// A later zoom write is refused while that save is still unknown.
			let rotationOk: boolean | undefined;
			await act(async () => {
				rotationOk = await result.current.updateZoomRotation("zoom_a", "left");
			});
			expect(rotationOk).toBe(false);
			expect(useProjectStore.getState().document?.zoomRanges[0]?.rotationPreset).toBeUndefined();

			// The unknown save settles late — it may land — and the refusal clears.
			await act(async () => {
				releaseHungSave({ success: true, document: hungDoc! });
				for (let i = 0; i < 20; i++) await Promise.resolve();
			});
			await act(async () => {
				await result.current.updateZoomDepth("zoom_a", 5);
			});
			expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(5);
		} finally {
			vi.useRealTimers();
		}
	});

	// A focus commit out of time leaves the zoom chain, but its save can still fail. The drag
	// must come off screen then, as for any failed commit, or a later save persists it.
	it("rolls a focus drag back when its commit fails after the deadline", async () => {
		seed(docWithZoom);
		vi.useFakeTimers();
		try {
			let failHungSave: () => void;
			bridgeMocks.save.mockImplementation(
				() =>
					new Promise((resolve) => {
						failHungSave = () => resolve({ success: false, error: "disk full" });
					}),
			);
			const { result } = renderTimeline();

			act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
			act(() => {
				void result.current.commitZoomFocus();
			});
			// No answer by the deadline: the save may still land, so the drag stays.
			await act(async () => {
				await vi.advanceTimersByTimeAsync(10_000);
			});
			expect(useProjectStore.getState().document?.zoomRanges[0]?.focus).toEqual({
				cx: 0.8,
				cy: 0.2,
			});

			await act(async () => {
				failHungSave();
				for (let i = 0; i < 20; i++) await Promise.resolve();
			});
			expect(useProjectStore.getState().document?.zoomRanges[0]?.focus).toEqual({
				cx: 0.5,
				cy: 0.5,
			});
		} finally {
			vi.useRealTimers();
		}
	});

	// Rebase-review follow-up (unknown save × replacement): the refusal must not outlive
	// its reason. Once an undo bumps the epoch, the stuck save can no longer install
	// anything (`saveDocument` drops it), so it must stop blocking zoom writes — even if
	// the bridge never answers. A project switch does NOT bump the epoch, so there the
	// stuck save can still land and the refusal correctly stays.
	it("stops refusing zoom writes once a replacement makes the unknown save unable to land", async () => {
		seed(docWithZoom);
		vi.useFakeTimers();
		try {
			let hungDoc: AxcutDocument | undefined;
			let releaseHungSave: (result: { success: boolean; document: AxcutDocument }) => void = () => {
				// replaced once the hung save registers
			};
			let saveCalls = 0;
			bridgeMocks.save.mockImplementation((doc: AxcutDocument) => {
				saveCalls += 1;
				if (saveCalls === 2) {
					// The write whose answer never comes; the test never releases it until
					// the very end, and then only to prove the epoch guard drops it.
					hungDoc = doc;
					return new Promise((resolve) => {
						releaseHungSave = resolve;
					});
				}
				return Promise.resolve({ success: true, document: doc });
			});
			const { result } = renderTimeline();

			// One settled write so the undo has a recorded state to restore.
			await act(async () => {
				await result.current.updateZoomDepth("zoom_a", 4);
			});
			expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(4);

			let depthOk: boolean | undefined;
			act(() => {
				void result.current.updateZoomDepth("zoom_a", 5).then((ok) => {
					depthOk = ok;
				});
			});
			await act(async () => {
				await vi.advanceTimersByTimeAsync(10_000);
			});
			expect(depthOk).toBe(false);

			// The undo replaces the document; the stuck save can no longer install it.
			let undid = false;
			act(() => {
				undid = undo();
			});
			expect(undid).toBe(true);

			// Zoom writes must work again on the restored document.
			await act(async () => {
				const ok = await result.current.updateZoomDepth("zoom_a", 5);
				expect(ok).toBe(true);
			});
			expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(5);

			// When the stuck save finally settles, the epoch guard drops it — the restored
			// (and since re-edited) document stands.
			await act(async () => {
				releaseHungSave({ success: true, document: hungDoc! });
				for (let i = 0; i < 20; i++) await Promise.resolve();
			});
			expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(5);
		} finally {
			vi.useRealTimers();
		}
	});

	it("resolves a zoom-level write with whether the save took effect", async () => {
		seed(docWithZoom);
		const { result } = renderTimeline();
		bridgeMocks.save.mockResolvedValueOnce({ success: false, error: "read-only" });

		let ok: boolean | undefined;
		await act(async () => {
			ok = await result.current.updateZoomDepth("zoom_a", 4);
		});

		expect(ok).toBe(false);
		expect(useProjectStore.getState().document?.zoomRanges[0]?.depth).toBe(3);
	});

	it("leaves no undo step behind a focus drag whose commit failed", async () => {
		// The drag used to push its pre-drag document from the FIRST `setDocument`. When
		// the commit then failed, `commitZoomFocus` restored that same document through
		// `setState` — which cannot pop the entry. `past` was left holding a snapshot
		// identical to what was on screen (a Ctrl+Z that visibly does nothing) and
		// `future` had already been wiped by the push.
		seed(docWithZoom);
		const { result } = renderTimeline();

		// An edit and an undo, so there is a redo entry to lose.
		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 5);
		});
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(past).toHaveLength(0);
		expect(future).toHaveLength(1);

		const beforeDrag = useProjectStore.getState().document;
		bridgeMocks.save.mockResolvedValue({ success: false, error: "disk full" });
		act(() => {
			result.current.updateZoomFocusLive("zoom_a", { cx: 0.2, cy: 0.3 });
			result.current.updateZoomFocusLive("zoom_a", { cx: 0.25, cy: 0.35 });
		});
		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(useProjectStore.getState().document).toBe(beforeDrag);
		expect(past).toHaveLength(0);
		expect(future).toHaveLength(1);
		act(() => {
			expect(redo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0].depth).toBe(5);
	});

	it("records one undo step for a whole focus drag once it commits", async () => {
		// The other half of the same change: moving the record to the commit must not
		// lose it. Sixty pointermoves, one Ctrl+Z, back to where the drag started.
		seed(docWithZoom);
		const { result } = renderTimeline();

		act(() => {
			for (let i = 0; i < 60; i++) {
				result.current.updateZoomFocusLive("zoom_a", { cx: 0.2 + i / 1000, cy: 0.3 });
			}
		});
		expect(past).toHaveLength(0);

		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(past).toHaveLength(1);
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.zoomRanges[0].focus).toEqual({
			cx: 0.5,
			cy: 0.5,
		});
	});
});

// What a drag's snapshot is allowed to still be holding once the drag is over.
//
// `zoomFocusRollbackRef` / `annotationRollbackRef` hold the document a drag started
// from, kept until the commit that records it. A drag does not always reach a commit,
// and both commits are reachable without one: the inspector's annotation `<textarea>`
// writes live on every keystroke and commits `onBlur`, so closing the panel unmounts the
// focused node before blur can fire (the region's own delete button is an `onClick`, which
// runs after blur, so that route does not reach here) -- and `SliderCell` wires
// mouseup/touchend/keyup straight to `onCommit` with no `onChange` in front, so a bare
// click on a stroke-width thumb reaches `commitAnnotationChange()` carrying that
// leftover. `NewEditorShell` builds ONE `useTimeline()` and hands it to the inspector,
// so the abandonable live write and the bare commit share an instance.
describe("useTimeline drag snapshots", () => {
	const docWithRegions: AxcutDocument = {
		...sampleDoc,
		zoomRanges: [
			{
				id: "zoom_a",
				startMs: 1000,
				endMs: 3000,
				depth: 3,
				focus: { cx: 0.5, cy: 0.5 },
				focusMode: "manual",
				clipId: "clip_a",
				sourceStartSec: 1,
				sourceEndSec: 3,
			},
		],
		annotations: [
			{
				id: "ann_a",
				startMs: 1000,
				endMs: 3000,
				clipId: "clip_a",
				sourceStartSec: 1,
				sourceEndSec: 3,
				type: "text",
				content: "before",
				textContent: "",
				position: { x: 50, y: 50 },
				size: { width: 30, height: 20 },
				style: {
					color: "#ffffff",
					backgroundColor: "transparent",
					fontSize: 32,
					fontFamily: "Inter",
					fontWeight: "bold",
					fontStyle: "normal",
					textDecoration: "none",
					textAlign: "center",
					textAnimation: "none",
				},
				zIndex: 1,
			},
		],
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		clearHistory();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		probeVideoDimensionsMock.mockResolvedValue({ width: 1920, height: 1080 });
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: docWithRegions,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	afterEach(() => {
		clearHistory();
		vi.clearAllMocks();
	});

	/** Two recording edits between the abandoned live write and the bare commit, so the
	 *  stale snapshot is one the stack has already buried. */
	async function twoZoomDepthEdits(result: { current: ReturnType<typeof useTimeline> }) {
		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 4);
		});
		await act(async () => {
			await result.current.updateZoomDepth("zoom_a", 5);
		});
	}

	it("does not hand a bare annotation commit a base the edits since have buried", async () => {
		const { result } = renderTimeline();

		// The keystrokes that never reach their `onBlur`.
		act(() => result.current.updateAnnotationLive("ann_a", { content: "typed" }));
		await twoZoomDepthEdits(result);
		expect(past).toHaveLength(2);

		// The bare click on a slider thumb.
		await act(async () => {
			await result.current.commitAnnotationChange();
		});

		// Same project, so nothing is cleared -- the cost is that one Ctrl+Z jumps over
		// BOTH zoom edits and lands on the document the abandoned typing started from.
		expect(past).toHaveLength(2);
		act(() => {
			expect(undo()).toBe(true);
		});
		const doc = useProjectStore.getState().document;
		expect(doc?.zoomRanges[0].depth).toBe(4);
		expect(doc?.annotations[0].content).toBe("typed");
	});

	it("does not restore a buried document when a bare annotation commit fails", async () => {
		// The worse half: `rollback` is used as a DOCUMENT here, not only as a
		// `historyBase`, so a failed bare commit wrote the stale snapshot back into the
		// store and both zoom edits were silently gone.
		const { result } = renderTimeline();

		act(() => result.current.updateAnnotationLive("ann_a", { content: "typed" }));
		await twoZoomDepthEdits(result);

		const onScreen = useProjectStore.getState().document;
		bridgeMocks.save.mockResolvedValueOnce({ success: false, error: "disk full" });
		await act(async () => {
			await result.current.commitAnnotationChange();
		});

		expect(useProjectStore.getState().document).toBe(onScreen);
		expect(onScreen?.zoomRanges[0].depth).toBe(5);
		expect(onScreen?.annotations[0].content).toBe("typed");
	});

	it("does not hand a bare focus commit a base the edits since have buried", async () => {
		// `ZoomFocusOverlay.handlePointerDown` sets `draggingRef` BEFORE its live write,
		// and that write returns early on a zero-size overlay rect -- so `endDrag` fires
		// `commitZoomFocus()` with nothing in front of it.
		const { result } = renderTimeline();

		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
		await twoZoomDepthEdits(result);
		expect(past).toHaveLength(2);

		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(past).toHaveLength(2);
		act(() => {
			expect(undo()).toBe(true);
		});
		const doc = useProjectStore.getState().document;
		expect(doc?.zoomRanges[0].depth).toBe(4);
		expect(doc?.zoomRanges[0].focus).toEqual({ cx: 0.8, cy: 0.2 });
	});

	it("does not restore a buried document when a bare focus commit fails", async () => {
		const { result } = renderTimeline();

		act(() => result.current.updateZoomFocusLive("zoom_a", { cx: 0.8, cy: 0.2 }));
		await twoZoomDepthEdits(result);

		const onScreen = useProjectStore.getState().document;
		bridgeMocks.save.mockResolvedValueOnce({ success: false, error: "disk full" });
		await act(async () => {
			await result.current.commitZoomFocus();
		});

		expect(useProjectStore.getState().document).toBe(onScreen);
		expect(onScreen?.zoomRanges[0].depth).toBe(5);
	});

	it("still records the pre-drag document when an annotation drag reaches its commit", async () => {
		// The guard must not cost the feature it guards: a drag that ends the way a drag
		// normally ends is still ONE undo step, back to before it.
		const { result } = renderTimeline();

		act(() => result.current.updateAnnotationLive("ann_a", { content: "ty" }));
		act(() => result.current.updateAnnotationLive("ann_a", { content: "typed" }));
		await act(async () => {
			await result.current.commitAnnotationChange();
		});

		expect(past).toHaveLength(1);
		act(() => {
			expect(undo()).toBe(true);
		});
		expect(useProjectStore.getState().document?.annotations[0].content).toBe("before");
	});
});

// Issue #350 — imported audio tracks. The hook wraps the pure ops in
// document/audioTracks.ts (unit-tested separately); these cover the wiring:
// asset lookup, playhead placement, the save, and undo.
describe("useTimeline audio tracks", () => {
	const audioDoc: AxcutDocument = {
		...sampleDoc,
		assets: [
			...sampleDoc.assets,
			{
				id: "audio_1",
				kind: "audio",
				label: "voiceover.mp3",
				originalPath: "/tmp/vo.mp3",
				durationSec: 30,
				cameraTrack: null,
			},
		],
	};

	beforeEach(() => {
		useProjectStore.getState().clear();
		clearHistory();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		probeAudioDurationMock.mockReset();
		probeAudioDurationMock.mockResolvedValue(null);
		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
			success: true,
			document: doc,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: audioDoc,
			revision: 1,
			status: "ready",
			error: null,
			currentTimeSec: 4,
		});
	});

	afterEach(() => {
		vi.clearAllMocks();
	});

	it("addAudioTrack places a track for the asset at the playhead and returns its id", async () => {
		const { result } = renderTimeline();
		let id: string | null = null;
		await act(async () => {
			id = await result.current.addAudioTrack("audio_1");
		});
		const tracks = useProjectStore.getState().document?.audioTracks ?? [];
		expect(tracks).toHaveLength(1);
		expect(id).toBe(tracks[0]?.id);
		expect(tracks[0]).toMatchObject({
			assetId: "audio_1",
			durationSec: 30,
			// Head at the playhead (4s), span the source's own length.
			startMs: 4000,
			label: "voiceover.mp3",
		});
	});

	it("addAudioTrack refuses a non-audio (or unknown) asset", async () => {
		const { result } = renderTimeline();
		let videoId: string | null = "x";
		let missingId: string | null = "x";
		await act(async () => {
			videoId = await result.current.addAudioTrack("asset_1"); // a video asset
			missingId = await result.current.addAudioTrack("nope");
		});
		expect(videoId).toBeNull();
		expect(missingId).toBeNull();
		expect(useProjectStore.getState().document?.audioTracks).toEqual([]);
	});

	it("place / gain update the track and each is one undo step", async () => {
		const { result } = renderTimeline();
		let id = "";
		await act(async () => {
			id = (await result.current.addAudioTrack("audio_1", 2)) ?? "";
		});
		// A lane drag commits the whole span in one write and re-ventilates it.
		await act(async () => {
			await result.current.placeAudioTrack(id, { startMs: 3000, endMs: 8000 });
		});
		await act(async () => {
			await result.current.setAudioTrackGain(id, -6);
		});

		const track = useProjectStore.getState().document?.audioTracks[0];
		expect(track).toMatchObject({
			startMs: 3000,
			endMs: 8000,
			gainDb: -6,
		});

		// Three writes (add + place + gain) → the gain edit undoes first.
		act(() => {
			expect(undo()).toBe(true);
		});
		// Back to the level a new music bed is placed at.
		expect(useProjectStore.getState().document?.audioTracks[0]?.gainDb).toBe(-18);
	});

	it("clamps a track to the content under it, like every other anchored region", async () => {
		// The sample timeline is one 0..10s clip. A track dragged past the end has
		// nothing to anchor to out there — and the exported programme stops at the
		// last clip regardless — so the span is cut at the content, not stored
		// hanging off the end where it could never play.
		const { result } = renderTimeline();
		let id = "";
		await act(async () => {
			id = (await result.current.addAudioTrack("audio_1", 2)) ?? "";
		});
		await act(async () => {
			await result.current.placeAudioTrack(id, { startMs: 9000, endMs: 16_000 });
		});
		const track = useProjectStore.getState().document?.audioTracks[0];
		expect(track).toMatchObject({ startMs: 9000, endMs: 10_000 });
	});

	it("turning loop on fills the rest of the programme, in one undo step", async () => {
		// Looping only means anything when the span exceeds the source, so a toggle
		// that changed nothing else did nothing at all. The sample timeline is one
		// 0..10s clip and the asset is 30s, so the track is created 2..10 (clamped
		// to the content) and filling is a no-op — place it short first.
		const { result } = renderTimeline();
		let id = "";
		await act(async () => {
			id = (await result.current.addAudioTrack("audio_1", 2)) ?? "";
		});
		await act(async () => {
			await result.current.placeAudioTrack(id, { startMs: 2000, endMs: 4000 });
		});
		await act(async () => {
			await result.current.setAudioTrackLoop(id, true);
		});
		const tracks = useProjectStore.getState().document?.audioTracks ?? [];
		expect(tracks[0]).toMatchObject({ startMs: 2000, endMs: 10_000, loop: true });

		// One step: the flag and the fill undo together.
		act(() => {
			expect(undo()).toBe(true);
		});
		const back = useProjectStore.getState().document?.audioTracks[0];
		expect(back).toMatchObject({ endMs: 4000, loop: false });
	});

	it("turning loop off leaves the span alone", async () => {
		// Shrinking back would throw away a length the user may have set by hand.
		const { result } = renderTimeline();
		let id = "";
		await act(async () => {
			id = (await result.current.addAudioTrack("audio_1", 2)) ?? "";
		});
		await act(async () => {
			await result.current.setAudioTrackLoop(id, true);
		});
		const filled = useProjectStore.getState().document?.audioTracks[0]?.endMs;
		await act(async () => {
			await result.current.setAudioTrackLoop(id, false);
		});
		const track = useProjectStore.getState().document?.audioTracks[0];
		expect(track?.loop).toBe(false);
		expect(track?.endMs).toBe(filled);
	});

	it("removeAudioTrack deletes the track", async () => {
		const { result } = renderTimeline();
		let id = "";
		await act(async () => {
			id = (await result.current.addAudioTrack("audio_1")) ?? "";
		});
		await act(async () => {
			await result.current.removeAudioTrack(id);
		});
		expect(useProjectStore.getState().document?.audioTracks).toEqual([]);
	});

	// #350: the toolbar button and the `M` shortcut both call `tl.addAudio`, which opens
	// the OS file picker and hands the result to `importAudioAsset`. Spy on the store's
	// import so these assert the wiring (picker → import), not the import itself.
	it("addAudio imports the picked file, and is a no-op when the picker is cancelled", async () => {
		const importSpy = vi.fn().mockResolvedValue(null);
		useProjectStore.setState({ importAudioAsset: importSpy });
		const pickerMock = vi.fn();
		Object.defineProperty(window, "electronAPI", {
			configurable: true,
			value: { openAudioFilePicker: pickerMock },
		});
		const { result } = renderTimeline();

		// Cancelled picker → nothing imported.
		pickerMock.mockResolvedValueOnce({ success: false });
		await act(async () => {
			await result.current.addAudio();
		});
		expect(importSpy).not.toHaveBeenCalled();

		// Picked a file → imported with its path and display name.
		pickerMock.mockResolvedValueOnce({ success: true, path: "/tmp/bgm.mp3", name: "bgm.mp3" });
		await act(async () => {
			await result.current.addAudio();
		});
		expect(importSpy).toHaveBeenCalledWith("/tmp/bgm.mp3", "bgm.mp3");
	});

	it("addAudio clears region/clip selections after a successful import", async () => {
		// importAudioAsset must resolve an asset for the success path to run.
		useProjectStore.setState({ importAudioAsset: vi.fn().mockResolvedValue({ id: "audio_1" }) });
		Object.defineProperty(window, "electronAPI", {
			configurable: true,
			value: {
				openAudioFilePicker: vi
					.fn()
					.mockResolvedValue({ success: true, path: "/tmp/bgm.mp3", name: "bgm.mp3" }),
			},
		});
		const { result } = renderTimeline();

		// A clip selected before the import (selectClip and selectRegion are mutually
		// exclusive, so a clip is enough to prove the import wipes the local selection)…
		act(() => result.current.selectClip("clip_1"));
		expect(result.current.clipSelection).toBe("clip_1");

		await act(async () => {
			await result.current.addAudio();
		});
		// …is gone after it (the imported track becomes the sole selection).
		expect(result.current.selection).toBeNull();
		expect(result.current.multiSelection).toEqual([]);
		expect(result.current.clipSelection).toBeNull();
	});

	it("addAudio toasts when the file picker itself rejects", async () => {
		toastErrorMock.mockClear();
		const importSpy = vi.fn();
		useProjectStore.setState({ importAudioAsset: importSpy });
		Object.defineProperty(window, "electronAPI", {
			configurable: true,
			value: { openAudioFilePicker: vi.fn().mockRejectedValueOnce(new Error("ipc down")) },
		});
		const { result } = renderTimeline();

		await act(async () => {
			await result.current.addAudio();
		});
		// A picker rejection reaches the localized toast, not an unhandled rejection, and never
		// attempts an import.
		expect(importSpy).not.toHaveBeenCalled();
		expect(toastErrorMock).toHaveBeenCalledTimes(1);
	});

	// #350 regression: a failed import-time probe leaves durationSec at 0, which
	// makes the playback window zero-length. The on-load backfill re-probes and
	// stamps the real duration onto the asset AND the track, so it can play again.
	it("backfills a missing audio duration on load", async () => {
		probeAudioDurationMock.mockResolvedValue(12.5);
		// Asset imported with an unknown duration (probe failed), and a track that
		// cached the resulting 0.
		useProjectStore.setState({
			projectId: "proj_test",
			document: {
				...sampleDoc,
				assets: [
					...sampleDoc.assets,
					{
						id: "audio_2",
						kind: "audio",
						label: "bgm.mp3",
						originalPath: "/tmp/bgm.mp3",
						cameraTrack: null,
					},
				],
				audioTracks: [
					{
						id: "trk_2",
						assetId: "audio_2",
						kind: "music" as const,
						startMs: 0,
						endMs: 1,
						durationSec: 0,
						offsetMs: 0,
						gainDb: 0,
						loop: false,
						fadeInMs: 0,
						fadeOutMs: 0,
						muted: false,
						label: "bgm.mp3",
						origin: "user" as const,
					},
				],
			},
			revision: 1,
			status: "ready",
			error: null,
		});
		renderTimeline();
		await waitFor(() => {
			const doc = useProjectStore.getState().document;
			expect(doc?.assets.find((a) => a.id === "audio_2")?.durationSec).toBe(12.5);
			expect(doc?.audioTracks[0]?.durationSec).toBe(12.5);
		});
		expect(probeAudioDurationMock).toHaveBeenCalledTimes(1);
	});
});

// The wand (`V4Timeline.runAutoZooms`) captures this callback, awaits a
// multi-second cursor-telemetry IPC, and only then calls it. Anything the user
// commits during that wait is in the store but not in the callback's render
// closure, so reading the closure writes back a snapshot that drops their edit.
// Its `add*` siblings compute and save in the same tick, which is why this one
// is the reachable case.
describe("useTimeline.addZoomsBulk reads the document at write time", () => {
	afterEach(() => {
		vi.clearAllMocks();
	});

	beforeEach(() => {
		useProjectStore.getState().clear();
		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
		toastErrorMock.mockReset();
		bridgeMocks.save.mockImplementation(async (document: AxcutDocument) => ({
			success: true,
			document,
		}));
		useProjectStore.setState({
			projectId: "proj_test",
			document: sampleDoc,
			revision: 1,
			status: "ready",
			error: null,
		});
	});

	it("does not write back the document from before the telemetry wait", async () => {
		const { result } = renderTimeline();
		// Captured the way the wand captures it: before the wait, not after.
		const addZoomsBulk = result.current.addZoomsBulk;

		// The user's edit lands while the wand is off fetching telemetry.
		const edited: AxcutDocument = {
			...sampleDoc,
			project: { ...sampleDoc.project, title: "Edited while the wand was busy" },
		};
		act(() => {
			useProjectStore.setState({ document: edited, revision: 2 });
		});

		let added: number | undefined;
		await act(async () => {
			added = await addZoomsBulk([
				{ span: { start: 1000, end: 2000 }, focus: { cx: 0.5, cy: 0.5 }, depth: 3 },
			]);
		});

		expect(added).toBe(1);
		const saved = bridgeMocks.save.mock.calls.at(-1)?.[0] as AxcutDocument;
		// The zoom was added, and the edit is still there.
		expect(saved.zoomRanges).toHaveLength(1);
		expect(saved.project.title).toBe("Edited while the wand was busy");
		expect(useProjectStore.getState().document?.project.title).toBe(
			"Edited while the wand was busy",
		);
	});

	// Reading the document fresh is what makes this reachable: the spans were built
	// from the OLD project's telemetry and its ruler, so writing them into whatever is
	// loaded now puts one project's zooms in another. `saveDocument`'s epoch check does
	// not cover it -- the write is issued after the switch, not across it.
	it("writes nothing when the project changed during the telemetry wait", async () => {
		const { result } = renderTimeline();
		const addZoomsBulk = result.current.addZoomsBulk;

		// The user switches projects while the wand is off fetching telemetry.
		act(() => {
			useProjectStore.setState({
				projectId: "proj_switched_to",
				document: sampleDoc,
				revision: 2,
			});
		});

		let added: number | undefined;
		await act(async () => {
			added = await addZoomsBulk([
				{ span: { start: 1000, end: 2000 }, focus: { cx: 0.5, cy: 0.5 }, depth: 3 },
			]);
		});

		expect(added).toBe(0);
		expect(bridgeMocks.save).not.toHaveBeenCalled();
	});
});