Skip to content

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

39.3 KB
Raw Blame
import { describe, expect, it } from "vitest";
import { migrateRawDocumentToCurrent } from "../document/migrate";
import {
	annotationRegionSchema,
	assetSchema,
	audioTrackSchema,
	axcutSchemaVersion,
	clipSchema,
	createAudioTrack,
	createEmptyDocument,
	documentSchema,
	ensureDocument,
	legacyEditorSchema,
	parseDocumentFile,
	rangeSchema,
	shaderEffectRangeSchema,
	shaderEffectSchema,
	timelineSchema,
	trimRangeSchema,
	upgradeV7DocumentToV8,
	zoomRegionSchema,
} from "./index";

describe("axcut-schema v9", () => {
	it("uses schema version 9", () => {
		expect(axcutSchemaVersion).toBe(9);
	});

	it("rejects unknown schema versions", () => {
		expect(() =>
			documentSchema.parse({
				...createEmptyDocument({ projectId: "p", title: "t" }),
				schemaVersion: 2,
			}),
		).toThrow();
	});

	it("createEmptyDocument returns a valid v9 doc with empty collections", () => {
		const doc = createEmptyDocument({ projectId: "proj_1", title: "Demo" });
		expect(doc.schemaVersion).toBe(9);
		expect(doc.assets).toEqual([]);
		expect(doc.timeline.clips).toEqual([]);
		expect(doc.timeline.trimRanges).toEqual([]);
		expect(doc.timeline.speedRanges).toEqual([]);
		expect(doc.timeline.muteRanges).toEqual([]);
		expect(doc.timeline.captionRanges).toEqual([]);
		expect(doc.annotations).toEqual([]);
		expect(doc.zoomRanges).toEqual([]);
		expect(doc.audioTracks).toEqual([]);
		expect(doc.transcripts).toEqual([]);
		expect(doc.legacyEditor).toBeNull();
	});

	it("ensureDocument rejects garbage", () => {
		expect(() => ensureDocument({ schemaVersion: 3, project: "not-an-object" })).toThrow();
	});

	it("accepts a clip with sourceEndSec undefined (asset duration unknown at migration time)", () => {
		const clip = clipSchema.parse({
			id: "clip_1",
			assetId: "asset_1",
			sourceStartSec: 0,
			timelineStartSec: 0,
			timelineEndSec: 0,
			origin: "system",
		});
		expect(clip.sourceEndSec).toBeUndefined();
	});

	it("rejects negative clip times", () => {
		expect(() =>
			clipSchema.parse({
				id: "clip_1",
				assetId: "asset_1",
				sourceStartSec: -1,
				timelineStartSec: 0,
				timelineEndSec: 0,
				origin: "system",
			}),
		).toThrow();
	});

	it("assetSchema accepts kind 'video' and 'audio', defaulting to 'video'", () => {
		// Widened from a literal when external-audio import landed (issue #350).
		const video = assetSchema.parse({ id: "a1", label: "x", originalPath: "/x.mp4" });
		expect(video.kind).toBe("video");
		const audio = assetSchema.parse({
			id: "a2",
			kind: "audio",
			label: "bgm",
			originalPath: "/bgm.mp3",
		});
		expect(audio.kind).toBe("audio");
	});

	it("assetSchema rejects an unknown kind", () => {
		expect(() =>
			assetSchema.parse({ id: "a1", kind: "image", label: "x", originalPath: "/x.png" }),
		).toThrow();
	});

	it("trimRangeSchema carries assetId and origin", () => {
		const skip = trimRangeSchema.parse({
			id: "trim_1",
			assetId: "asset_1",
			startSec: 1.5,
			endSec: 3.0,
			origin: "user",
		});
		expect(skip.assetId).toBe("asset_1");
		expect(skip.origin).toBe("user");
	});

	it("rangeSchema has no required fields beyond startSec/endSec", () => {
		const r = rangeSchema.parse({ startSec: 0, endSec: 1 });
		expect(r.reason).toBe("");
	});

	it("timelineSchema defaults trimRanges to []", () => {
		const t = timelineSchema.parse({});
		expect(t.trimRanges).toEqual([]);
		expect(t.muteRanges).toEqual([]);
		expect(t.captionRanges).toEqual([]);
	});

	it("timelineSchema migrates legacy skipRanges → trimRanges", () => {
		// Documents persisted before the skip→trim rename carry `skipRanges`.
		const t = timelineSchema.parse({
			skipRanges: [
				{ id: "skip_1", assetId: "a", startSec: 3, endSec: 5, reason: "", origin: "user" },
			],
		});
		expect(t.trimRanges).toEqual([
			{ id: "skip_1", assetId: "a", startSec: 3, endSec: 5, reason: "", origin: "user" },
		]);
	});

	it("annotationRegionSchema accepts OpenScreen-shape regions", () => {
		const region = annotationRegionSchema.parse({
			id: "ann_1",
			startMs: 0,
			endMs: 1500,
			type: "text",
			content: "hello",
			position: { x: 4, y: 86 },
			size: { width: 92, height: 12 },
			style: {
				color: "#ffffff",
				backgroundColor: "transparent",
				fontSize: 24,
				fontFamily: "Inter",
				fontWeight: "bold",
				fontStyle: "normal",
				textDecoration: "none",
				textAlign: "center",
			},
			zIndex: 1,
		});
		expect(region.type).toBe("text");
		expect(region.annotationSource).toBeUndefined();
	});

	it("keeps the remembered background colour through a save-path parse", () => {
		// Le chemin d'enregistrement valide le document dans le processus principal, et zod jette
		// tout champ non déclaré : une mémoire que l'interface écrit mais que le schéma ignore
		// disparaît au premier enregistrement — silencieusement, ce qui est le pire cas.
		const region = annotationRegionSchema.parse({
			id: "ann_1",
			startMs: 0,
			endMs: 1500,
			type: "text",
			content: "hello",
			position: { x: 4, y: 86 },
			size: { width: 92, height: 12 },
			style: {
				color: "#ffffff",
				backgroundColor: "transparent",
				lastBackgroundColor: "#3b82f6",
				fontSize: 24,
			},
			zIndex: 1,
		});
		expect(region.style.lastBackgroundColor).toBe("#3b82f6");
	});

	it("reads a text size into its bound instead of refusing the project", () => {
		const sizeOf = (fontSize: number) =>
			annotationRegionSchema.parse({
				id: "ann_1",
				startMs: 0,
				endMs: 1500,
				type: "text",
				content: "hello",
				position: { x: 4, y: 86 },
				size: { width: 92, height: 12 },
				style: { fontSize },
				zIndex: 1,
			}).style.fontSize;
		// 0 is what an emptied size field used to store: it opens as the smallest text.
		expect([sizeOf(0), sizeOf(24), sizeOf(500)]).toEqual([8, 24, 200]);
	});

	it("opens an arrow drawn against the frame's edge, whose box starts before it", () => {
		const at = (type: "figure" | "text", x: number) => () =>
			annotationRegionSchema.parse({
				id: "ann_1",
				startMs: 0,
				endMs: 1500,
				type,
				position: { x, y: -5 },
				size: { width: 30, height: 53 },
				style: {},
				zIndex: 1,
			});
		// A right arrow with a 6 px stroke, dragged to the left edge (`arrowBox`).
		expect(at("figure", -17)().position).toEqual({ x: -17, y: -5 });
		expect(at("text", -17)).toThrow("position must be at least 0");
	});

	it("zoomRegionSchema rejects unknown depths", () => {
		expect(() =>
			zoomRegionSchema.parse({
				id: "z_1",
				startMs: 0,
				endMs: 1000,
				depth: 7,
				focus: { cx: 0.5, cy: 0.5 },
			}),
		).toThrow();
	});

	it("zoomRegionSchema accepts depth 1..6", () => {
		for (const d of [1, 2, 3, 4, 5, 6] as const) {
			const z = zoomRegionSchema.parse({
				id: `z_${d}`,
				startMs: 0,
				endMs: 1000,
				depth: d,
				focus: { cx: 0.5, cy: 0.5 },
			});
			expect(z.depth).toBe(d);
		}
	});

	it("legacyEditorSchema accepts arbitrary passthrough keys", () => {
		const legacy = legacyEditorSchema.parse({
			wallpaper: "/wallpapers/wallpaper1.jpg",
			autoZoomEnabled: true,
			someFutureField: "preserved",
		});
		expect(legacy?.someFutureField).toBe("preserved");
	});

	it("documentSchema defaults missing v3 envelopes on a v3 document", () => {
		// After the migration hoist, a v3 doc must run through
		// `migrateRawDocumentToCurrent` first; this models the new load-time
		// contract: the schema parse is a pure v8 validation step.
		expect(() =>
			documentSchema.parse(
				migrateRawDocumentToCurrent({
					schemaVersion: 3,
					project: {
						id: "p",
						title: "t",
						createdAt: new Date().toISOString(),
						updatedAt: new Date().toISOString(),
					},
					assets: [],
					transcript: null,
					timeline: {},
					agent: {},
					preview: {},
					export: {},
					history: {},
				}),
			),
		).not.toThrow();
	});

	it("assetSchema defaults cameraTrack to null", () => {
		const asset = assetSchema.parse({
			id: "asset_1",
			kind: "video",
			label: "x",
			originalPath: "/x.mp4",
		});
		expect(asset.cameraTrack).toBeNull();
	});

	describe("v3 -> v4 cameraTrack migration", () => {
		function v3Doc(overrides: Record<string, unknown> = {}) {
			return {
				schemaVersion: 3,
				project: {
					id: "p",
					title: "t",
					createdAt: new Date().toISOString(),
					updatedAt: new Date().toISOString(),
				},
				assets: [
					{ id: "asset_1", kind: "video", label: "a1", originalPath: "/a1.mp4" },
					{ id: "asset_2", kind: "video", label: "a2", originalPath: "/a2.mp4" },
				],
				cameraTrack: { sourcePath: "/cam.mp4", startMs: 0, offsetMs: 0, visible: true },
				...overrides,
			};
		}

		it("relocates a legacy top-level cameraTrack onto the primaryAssetId asset", () => {
			// After the migration hoist, v3 input runs through the load-time
			// upgrader before the pure v8 schema parse.
			const doc = documentSchema.parse(
				migrateRawDocumentToCurrent(
					v3Doc({ project: { ...v3Doc().project, primaryAssetId: "asset_2" } }),
				),
			);
			expect(doc.schemaVersion).toBe(9);
			expect((doc as Record<string, unknown>).cameraTrack).toBeUndefined();
			expect(doc.assets.find((a) => a.id === "asset_1")?.cameraTrack).toBeNull();
			expect(doc.assets.find((a) => a.id === "asset_2")?.cameraTrack?.sourcePath).toBe("/cam.mp4");
		});

		it("falls back to the first asset when there is no primaryAssetId", () => {
			const doc = documentSchema.parse(migrateRawDocumentToCurrent(v3Doc()));
			expect(doc.assets[0].cameraTrack?.sourcePath).toBe("/cam.mp4");
			expect(doc.assets[1].cameraTrack).toBeNull();
		});

		it("is a no-op when the v3 document has no legacy cameraTrack", () => {
			const doc = documentSchema.parse(migrateRawDocumentToCurrent(v3Doc({ cameraTrack: null })));
			expect(doc.schemaVersion).toBe(9);
			for (const asset of doc.assets) {
				expect(asset.cameraTrack).toBeNull();
			}
		});

		it("rejects schemaVersion 2 (the load-time helper only upgrades v3/v4)", () => {
			// The pre-hoist schema auto-upgraded v3 inside its `z.preprocess`;
			// the post-hoist schema is a pure v8 validator, and the helper
			// only handles v3/v4. v2 still requires the separate
			// `migrateProjectDataToAxcutDocument` pure function.
			expect(() => documentSchema.parse(v3Doc({ schemaVersion: 2 }))).toThrow();
		});
	});

	describe("range ordering validation", () => {
		it("rangeSchema rejects endSec < startSec", () => {
			expect(() => rangeSchema.parse({ startSec: 10, endSec: 5 })).toThrow();
			expect(rangeSchema.parse({ startSec: 5, endSec: 10 })).toBeTruthy();
			expect(rangeSchema.parse({ startSec: 5, endSec: 5 })).toBeTruthy();
		});

		it("trimRangeSchema rejects endSec < startSec", () => {
			expect(() =>
				trimRangeSchema.parse({
					id: "s1",
					assetId: "a1",
					startSec: 10,
					endSec: 5,
					origin: "user",
				}),
			).toThrow();
		});

		it("clipSchema rejects timelineEndSec < timelineStartSec or sourceEndSec < sourceStartSec", () => {
			const validBase = {
				id: "c1",
				assetId: "a1",
				sourceStartSec: 0,
				sourceEndSec: 10,
				timelineStartSec: 0,
				timelineEndSec: 10,
				origin: "user" as const,
			};
			expect(() => clipSchema.parse({ ...validBase, timelineEndSec: -1 })).toThrow();
			expect(() => clipSchema.parse({ ...validBase, sourceEndSec: -1 })).toThrow();
			expect(() =>
				clipSchema.parse({ ...validBase, sourceStartSec: 10, sourceEndSec: 5 }),
			).toThrow();
			expect(() =>
				clipSchema.parse({ ...validBase, timelineStartSec: 10, timelineEndSec: 5 }),
			).toThrow();
		});

		it("zoomRegionSchema rejects endMs < startMs", () => {
			expect(() =>
				zoomRegionSchema.parse({
					id: "z1",
					startMs: 100,
					endMs: 50,
					depth: 1,
					focus: { cx: 0.5, cy: 0.5 },
				}),
			).toThrow();
		});

		it("annotationRegionSchema rejects endMs < startMs", () => {
			expect(() =>
				annotationRegionSchema.parse({
					id: "a1",
					startMs: 100,
					endMs: 50,
					type: "text",
					position: { x: 10, y: 10 },
					size: { width: 100, height: 100 },
					style: {
						fontFamily: "Inter",
						fontSize: 14,
						color: "#ffffff",
						backgroundColor: "#000000",
					},
					zIndex: 1,
					figureData: {},
					blurData: {},
				}),
			).toThrow();
		});
	});
});

// --- v4 -> v5 clip-anchoring migration (round-trip) --------------------------
// Uses goodtest's real layout: clip A [asset_f] src[0,25.557313] raw[0,25.557313],
// clip B [asset_e] src[0,8.149313] raw[25.557313,33.706626], and its straddling
// speed region [8149,28575]ms. See technical-documentation/architecture/timeline-model.md

describe("v4 -> v5 clip-anchored modifier migration", () => {
	const CLIP_A_END = 25.557313;
	const CLIP_B_END = 33.706626;

	function makeV4Doc(overrides: Record<string, unknown> = {}) {
		const createdAt = "2024-01-01T00:00:00.000Z";
		return {
			schemaVersion: 4,
			project: { id: "p1", title: "goodtest-like", createdAt, updatedAt: createdAt },
			assets: [
				{ id: "asset_f", kind: "video", label: "A", originalPath: "/a.mp4", cameraTrack: null },
				{ id: "asset_e", kind: "video", label: "B", originalPath: "/b.mp4", cameraTrack: null },
			],
			timeline: {
				clips: [
					{
						id: "clip_a",
						assetId: "asset_f",
						sourceStartSec: 0,
						sourceEndSec: CLIP_A_END,
						timelineStartSec: 0,
						timelineEndSec: CLIP_A_END,
						origin: "user",
					},
					{
						id: "clip_b",
						assetId: "asset_e",
						sourceStartSec: 0,
						sourceEndSec: 8.149313,
						timelineStartSec: CLIP_A_END,
						timelineEndSec: CLIP_B_END,
						origin: "user",
					},
				],
			},
			...overrides,
		};
	}

	it("bumps the version and anchors a zoom wholly inside one clip", () => {
		// After the migration hoist, v4 input runs through the load-time
		// upgrader before the pure v8 schema parse.
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent(
				makeV4Doc({
					zoomRanges: [
						{ id: "z1", startMs: 2000, endMs: 5000, depth: 3, focus: { cx: 0.5, cy: 0.5 } },
					],
				}),
			),
		);
		expect(doc.schemaVersion).toBe(9);
		expect(doc.zoomRanges).toHaveLength(1);
		const z = doc.zoomRanges[0];
		expect(z).toMatchObject({ id: "z1", clipId: "clip_a", depth: 3 });
		expect(z.sourceStartSec).toBeCloseTo(2, 5);
		expect(z.sourceEndSec).toBeCloseTo(5, 5);
		// derived ms cache stays consistent with the anchor
		expect(z.startMs).toBe(2000);
		expect(z.endMs).toBe(5000);
	});

	it("splits a straddling speed region into two fragments that still read as one pill", () => {
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent(
				makeV4Doc({
					legacyEditor: { speedRegions: [{ id: "s1", startMs: 8149, endMs: 28575, speed: 3 }] },
				}),
			),
		);
		const speeds = (doc.legacyEditor as Record<string, unknown>).speedRegions as Array<
			Record<string, unknown>
		>;
		expect(speeds).toHaveLength(2);
		// No shared marker is stored: equal properties + adjacency is what re-merges them.
		expect(speeds.every((s) => s.speed === 3)).toBe(true);
		expect(speeds.map((s) => s.clipId)).toEqual(["clip_a", "clip_b"]);
		expect(speeds[0].sourceStartSec).toBeCloseTo(8.149, 5);
		expect(speeds[1].sourceStartSec).toBeCloseTo(0, 5);
		// The two derived ms spans are contiguous and together cover the original.
		expect(speeds[0].startMs).toBe(8149);
		expect(speeds[1].endMs).toBe(28575);
		expect(speeds[0].endMs).toBe(speeds[1].startMs);
	});

	it("never drops a region it cannot anchor (unknown clip duration → passes through)", () => {
		// A v2-imported project before its duration is probed: zero-extent clip.
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent({
				schemaVersion: 4,
				project: {
					id: "p2",
					title: "unprobed",
					createdAt: "2024-01-01T00:00:00.000Z",
					updatedAt: "2024-01-01T00:00:00.000Z",
				},
				assets: [{ id: "a", kind: "video", label: "A", originalPath: "/a.mp4", cameraTrack: null }],
				timeline: {
					clips: [
						{
							id: "c1",
							assetId: "a",
							sourceStartSec: 0,
							timelineStartSec: 0,
							timelineEndSec: 0,
							origin: "user",
						},
					],
				},
				zoomRanges: [
					{ id: "z1", startMs: 1000, endMs: 2000, depth: 3, focus: { cx: 0.5, cy: 0.5 } },
				],
			}),
		);
		expect(doc.zoomRanges).toHaveLength(1);
		expect(doc.zoomRanges[0]).toMatchObject({ id: "z1", startMs: 1000, endMs: 2000 });
		expect(doc.zoomRanges[0].clipId).toBeUndefined();
	});

	it("is idempotent — re-parsing an already-v8 document changes nothing", () => {
		// First call: v4 input → load-time upgrade → v7.
		const once = documentSchema.parse(
			migrateRawDocumentToCurrent(
				makeV4Doc({
					zoomRanges: [
						{ id: "z1", startMs: 2000, endMs: 5000, depth: 3, focus: { cx: 0.5, cy: 0.5 } },
					],
				}),
			),
		);
		// Second call: already-current input, no upgrade needed; the parse is now a
		// pure v8 validation step.
		const twice = documentSchema.parse(once);
		expect(twice).toEqual(once);
	});
});

// --- v5 -> v6 native AspectRatio migration -----------------------------------
// `"native"` used to be a runtime-only sentinel that resolved to the timeline's largest
// clip. v6 makes that resolution permanent by baking the concrete `"W:H"` token into the
// document. After this upgrader runs, no document ever contains `"native"` again — the
// union arm in `AspectRatio` is dropped, and the runtime bridge in
// `lib/ai-edition/document/outputFormat` is no longer needed.

describe("v5 -> v6 native AspectRatio migration", () => {
	function makeV5Doc(overrides: Record<string, unknown> = {}) {
		const createdAt = "2024-01-01T00:00:00.000Z";
		return {
			schemaVersion: 5,
			project: { id: "p1", title: "v5-aspect", createdAt, updatedAt: createdAt },
			assets: [
				{ id: "asset_f", kind: "video", label: "A", originalPath: "/a.mp4", cameraTrack: null },
			],
			timeline: {
				clips: [
					{
						id: "clip_a",
						assetId: "asset_f",
						sourceStartSec: 0,
						sourceEndSec: 30,
						timelineStartSec: 0,
						timelineEndSec: 30,
						origin: "user",
					},
				],
			},
			...overrides,
		};
	}

	it("rewrites legacy aspectRatio === 'native' to the largest clip's concrete token", () => {
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent(
				makeV5Doc({
					legacyEditor: { aspectRatio: "native" },
					assets: [
						{
							id: "asset_f",
							kind: "video",
							label: "A",
							originalPath: "/a.mp4",
							cameraTrack: null,
							video: { width: 1920, height: 1080 },
						},
					],
				}),
			),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("16:9");
	});

	it("picks the largest clip when the timeline is mixed-shape", () => {
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent({
				schemaVersion: 5,
				project: {
					id: "p1",
					title: "mixed",
					createdAt: "2024-01-01T00:00:00.000Z",
					updatedAt: "2024-01-01T00:00:00.000Z",
				},
				assets: [
					{
						id: "asset_f",
						kind: "video",
						label: "A",
						originalPath: "/a.mp4",
						cameraTrack: null,
						video: { width: 1920, height: 1080 },
					},
					{
						id: "asset_g",
						kind: "video",
						label: "B",
						originalPath: "/b.mp4",
						cameraTrack: null,
						video: { width: 2160, height: 3840 },
					},
				],
				timeline: {
					clips: [
						{
							id: "clip_a",
							assetId: "asset_f",
							sourceStartSec: 0,
							sourceEndSec: 10,
							timelineStartSec: 0,
							timelineEndSec: 10,
							origin: "user",
						},
						{
							id: "clip_b",
							assetId: "asset_g",
							sourceStartSec: 0,
							sourceEndSec: 10,
							timelineStartSec: 10,
							timelineEndSec: 20,
							origin: "user",
						},
					],
				},
				legacyEditor: { aspectRatio: "native" },
			}),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("9:16");
	});

	it("leaves 'native' alone when the timeline has no clips with known dimensions", () => {
		// Deliberately NOT a 16:9 fallback: an empty/unprobed timeline gives no basis
		// for a concrete token, and guessing one persists a wrong frame. See the v1.7
		// import case below.
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent(makeV5Doc({ legacyEditor: { aspectRatio: "native" } })),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("native");
	});

	it("passes through a concrete aspectRatio unchanged", () => {
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent(makeV5Doc({ legacyEditor: { aspectRatio: "4:5" } })),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("4:5");
	});

	it("passes through a legacyEditor without aspectRatio, which v8 then pins to 16:9", () => {
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent(makeV5Doc({ legacyEditor: { someOtherField: "preserved" } })),
		);
		expect(doc.schemaVersion).toBe(9);
		const legacy = doc.legacyEditor as Record<string, unknown>;
		expect(legacy.someOtherField).toBe("preserved");
		expect(legacy.aspectRatio).toBe("16:9");
	});

	it("passes through a v5 doc with no legacyEditor at all, which v8 then pins to 16:9", () => {
		const v5 = makeV5Doc();
		const doc = documentSchema.parse(migrateRawDocumentToCurrent(v5));
		expect(doc.schemaVersion).toBe(9);
		expect(doc.legacyEditor).toEqual({ aspectRatio: "16:9" });
	});

	it("is idempotent — re-parsing an already-v8 document changes nothing", () => {
		const once = documentSchema.parse(
			migrateRawDocumentToCurrent(makeV5Doc({ legacyEditor: { aspectRatio: "16:9" } })),
		);
		const twice = documentSchema.parse(once);
		expect(twice).toEqual(once);
	});

	it("keeps 'native' when the source dimensions are not known yet (v1.7 import)", () => {
		// The v1.7 -> v1.8 path: `{version:2, media, editor}` carries only file paths,
		// so `migrateProjectDataToAxcutDocument` produces assets with no `video` block.
		// Baking here would stamp a hardcoded 16:9 and persist it — permanently
		// reframing every portrait v1.7 project saved with "Native". Leave the
		// sentinel; it resolves dynamically at runtime and converts on a later load,
		// once useTimeline's probe has written `asset.video` back.
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent({
				schemaVersion: 5,
				project: {
					id: "p1",
					title: "from v1.7",
					createdAt: "2024-01-01T00:00:00.000Z",
					updatedAt: "2024-01-01T00:00:00.000Z",
				},
				assets: [
					{
						id: "asset_u",
						kind: "video",
						label: "A",
						originalPath: "/a.mp4",
						cameraTrack: null,
						// no `video` — exactly what the v2 import produces
					},
				],
				timeline: {
					clips: [
						{
							id: "clip_a",
							assetId: "asset_u",
							sourceStartSec: 0,
							sourceEndSec: 10,
							timelineStartSec: 0,
							timelineEndSec: 10,
							origin: "user",
						},
					],
				},
				legacyEditor: { aspectRatio: "native" },
			}),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("native");
	});

	it("converts 'native' once the probe has persisted dimensions", () => {
		// Second load of the same project, after useTimeline probed a PORTRAIT source.
		// This is the case that must not become 16:9.
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent({
				schemaVersion: 5,
				project: {
					id: "p1",
					title: "from v1.7, probed",
					createdAt: "2024-01-01T00:00:00.000Z",
					updatedAt: "2024-01-01T00:00:00.000Z",
				},
				assets: [
					{
						id: "asset_u",
						kind: "video",
						label: "A",
						originalPath: "/a.mp4",
						cameraTrack: null,
						video: { width: 1080, height: 1920 },
					},
				],
				timeline: {
					clips: [
						{
							id: "clip_a",
							assetId: "asset_u",
							sourceStartSec: 0,
							sourceEndSec: 10,
							timelineStartSec: 0,
							timelineEndSec: 10,
							origin: "user",
						},
					],
				},
				legacyEditor: { aspectRatio: "native" },
			}),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("9:16");
	});

	it("bakes the CROPPED dimensions, not the raw ones", () => {
		// "native" resolved to the cropped clip at runtime. A 3840x2160 asset cropped
		// to its left half is effectively 1920x2160 → 8:9. Reading the raw dims would
		// wrongly yield 16:9 and silently reframe the project.
		const doc = documentSchema.parse(
			migrateRawDocumentToCurrent({
				schemaVersion: 5,
				project: {
					id: "p1",
					title: "cropped",
					createdAt: "2024-01-01T00:00:00.000Z",
					updatedAt: "2024-01-01T00:00:00.000Z",
				},
				assets: [
					{
						id: "asset_c",
						kind: "video",
						label: "A",
						originalPath: "/a.mp4",
						cameraTrack: null,
						video: { width: 3840, height: 2160 },
					},
				],
				timeline: {
					clips: [
						{
							id: "clip_a",
							assetId: "asset_c",
							sourceStartSec: 0,
							sourceEndSec: 10,
							timelineStartSec: 0,
							timelineEndSec: 10,
							origin: "user",
							cropRegion: { x: 0, y: 0, width: 0.5, height: 1 },
						},
					],
				},
				legacyEditor: { aspectRatio: "native" },
			}),
		);
		expect(doc.schemaVersion).toBe(9);
		expect((doc.legacyEditor as Record<string, unknown>).aspectRatio).toBe("8:9");
	});
});

// --- v6 -> v7 trim clip-anchor migration -------------------------------------
// A v6 trim names only an asset, so on two clips over the same media it is ambiguous:
// the transcript pane showed it twice, the ruler drew it on the first clip, and playback
// cut it from both. The upgrade ventilates each stored trim into one anchored row per
// clip it covers — a faithful restatement of what the document already rendered, but now
// separately addressable so the user can delete the copy they did not mean.
describe("v6 -> v7 trim clip-anchor migration", () => {
	const v6Doc = (
		clips: Array<Record<string, unknown>>,
		trimRanges: Array<Record<string, unknown>>,
	) => ({
		schemaVersion: 6,
		project: {
			id: "p",
			title: "t",
			createdAt: "2026-01-01T00:00:00.000Z",
			updatedAt: "2026-01-01T00:00:00.000Z",
			primaryAssetId: "asset_1",
		},
		assets: [
			{
				id: "asset_1",
				kind: "video",
				label: "rec.mp4",
				originalPath: "/rec.mp4",
				durationSec: 12,
				cameraTrack: null,
			},
		],
		timeline: { clips, trimRanges },
	});

	const twoSharedClips = [
		{
			id: "clip_1",
			assetId: "asset_1",
			sourceStartSec: 0,
			sourceEndSec: 12,
			timelineStartSec: 0,
			timelineEndSec: 12,
			origin: "user",
		},
		{
			id: "clip_2",
			assetId: "asset_1",
			sourceStartSec: 0,
			sourceEndSec: 12,
			timelineStartSec: 12,
			timelineEndSec: 24,
			origin: "user",
		},
	];

	const trimsOf = (raw: unknown) =>
		((raw as Record<string, unknown>).timeline as Record<string, unknown>).trimRanges as Array<
			Record<string, unknown>
		>;

	it("anchors a trim to the single clip that covers it", () => {
		const out = migrateRawDocumentToCurrent(
			v6Doc(
				[twoSharedClips[0]],
				[{ id: "t1", assetId: "asset_1", startSec: 3, endSec: 5, origin: "user", reason: "" }],
			),
		);
		expect((out as Record<string, unknown>).schemaVersion).toBe(9);
		expect(trimsOf(out)).toEqual([
			{
				id: "t1",
				assetId: "asset_1",
				clipId: "clip_1",
				startSec: 3,
				endSec: 5,
				origin: "user",
				reason: "",
			},
		]);
	});

	it("ventilates into one row per covering clip, preserving what the document rendered", () => {
		const out = migrateRawDocumentToCurrent(
			v6Doc(twoSharedClips, [
				{ id: "t1", assetId: "asset_1", startSec: 3, endSec: 5, origin: "user", reason: "" },
			]),
		);
		const trims = trimsOf(out);
		expect(trims).toHaveLength(2);
		// The first row keeps the original id, so anything already holding it still resolves.
		expect(trims[0]).toMatchObject({ id: "t1", clipId: "clip_1", startSec: 3, endSec: 5 });
		expect(trims[1]).toMatchObject({ clipId: "clip_2", startSec: 3, endSec: 5 });
		expect(trims[1].id).not.toBe("t1");
	});

	it("clamps each row to its own clip's source window", () => {
		const out = migrateRawDocumentToCurrent(
			v6Doc(
				[
					{ ...twoSharedClips[0], sourceStartSec: 0, sourceEndSec: 6 },
					{ ...twoSharedClips[1], sourceStartSec: 6, sourceEndSec: 12 },
				],
				[{ id: "t1", assetId: "asset_1", startSec: 4, endSec: 9, origin: "user", reason: "" }],
			),
		);
		expect(trimsOf(out).map((t) => [t.clipId, t.startSec, t.endSec])).toEqual([
			["clip_1", 4, 6],
			["clip_2", 6, 9],
		]);
	});

	it("keeps a trim that covers no clip rather than dropping user data", () => {
		// `replaceTimeline` mints exactly these: the complement of the kept intervals, which
		// lies outside every clip by construction.
		const out = migrateRawDocumentToCurrent(
			v6Doc(
				[{ ...twoSharedClips[0], sourceStartSec: 0, sourceEndSec: 3 }],
				[{ id: "t1", assetId: "asset_1", startSec: 8, endSec: 9, origin: "user", reason: "" }],
			),
		);
		expect(trimsOf(out)).toEqual([
			{ id: "t1", assetId: "asset_1", startSec: 8, endSec: 9, origin: "user", reason: "" },
		]);
	});

	it("leaves an unprobed clip's trims un-anchored (no real window to clamp against)", () => {
		const out = migrateRawDocumentToCurrent(
			v6Doc(
				[{ ...twoSharedClips[0], sourceStartSec: 0, sourceEndSec: undefined }],
				[{ id: "t1", assetId: "asset_1", startSec: 3, endSec: 5, origin: "user", reason: "" }],
			),
		);
		expect(trimsOf(out)[0].clipId).toBeUndefined();
	});

	it("is idempotent — an already-anchored trim is left alone", () => {
		const once = migrateRawDocumentToCurrent(
			v6Doc(twoSharedClips, [
				{ id: "t1", assetId: "asset_1", startSec: 3, endSec: 5, origin: "user", reason: "" },
			]),
		);
		expect(migrateRawDocumentToCurrent(once)).toEqual(once);
	});

	it("survives a malformed clip entry instead of failing the whole project load", () => {
		const out = migrateRawDocumentToCurrent(
			v6Doc(
				[null as unknown as Record<string, unknown>, twoSharedClips[1]],
				[{ id: "t1", assetId: "asset_1", startSec: 3, endSec: 5, origin: "user", reason: "" }],
			),
		);
		expect(trimsOf(out)).toEqual([
			{
				id: "t1",
				assetId: "asset_1",
				clipId: "clip_2",
				startSec: 3,
				endSec: 5,
				origin: "user",
				reason: "",
			},
		]);
	});
});

describe("audio tracks (issue #350)", () => {
	it("applies defaults for kind, gain, offset, fades and label", () => {
		const track = audioTrackSchema.parse({
			id: "audio_1",
			assetId: "asset_1",
			durationSec: 42,
			startMs: 0,
			endMs: 42_000,
		});
		expect(track.kind).toBe("music");
		expect(track.offsetMs).toBe(0);
		expect(track.gainDb).toBe(0);
		expect(track.loop).toBe(false);
		expect(track.fadeInMs).toBe(0);
		expect(track.fadeOutMs).toBe(0);
		expect(track.muted).toBe(false);
		expect(track.label).toBe("");
		// Unanchored until a caller places it — same contract as every other
		// clip-anchored region kind.
		expect(track.clipId).toBeUndefined();
	});

	it("rejects a span whose end precedes its start", () => {
		expect(() =>
			audioTrackSchema.parse({
				id: "audio_1",
				assetId: "asset_1",
				durationSec: 10,
				startMs: 5000,
				endMs: 2000,
			}),
		).toThrow();
	});

	it("rejects a negative head", () => {
		expect(() =>
			audioTrackSchema.parse({
				id: "audio_1",
				assetId: "asset_1",
				durationSec: 10,
				startMs: -1,
				endMs: 1000,
			}),
		).toThrow();
	});

	it("createAudioTrack builds a schema-valid track with a prefixed id", () => {
		const track = createAudioTrack({
			assetId: "asset_1",
			durationSec: 12.5,
			timelineStartSec: 3,
			label: "voiceover.mp3",
		});
		expect(track.id).toMatch(/^audio_/);
		expect(track.assetId).toBe("asset_1");
		expect(track.durationSec).toBe(12.5);
		// The span runs from the head for the source duration by default.
		expect(track.startMs).toBe(3000);
		expect(track.endMs).toBe(15_500);
		expect(track.label).toBe("voiceover.mp3");
		// The factory output must itself round-trip through the schema.
		expect(() => audioTrackSchema.parse(track)).not.toThrow();
	});

	it("createAudioTrack takes a shorter span than the source when asked", () => {
		// A voiceover recorded over a 4s tail of the timeline should not lay a
		// 30s pill down just because its file is 30s long.
		const track = createAudioTrack({
			assetId: "asset_1",
			durationSec: 30,
			kind: "voiceover",
			timelineStartSec: 2,
			spanSec: 4,
		});
		expect(track.kind).toBe("voiceover");
		expect(track.startMs).toBe(2000);
		expect(track.endMs).toBe(6000);
	});

	it("createAudioTrack still gives a grabbable span to a zero-duration source", () => {
		const track = createAudioTrack({ assetId: "asset_1", durationSec: 0 });
		expect(track.endMs).toBeGreaterThan(track.startMs);
	});

	it("lays a new music bed down under the voice, eased in and out", () => {
		// Imported music at 0 dB with hard edges is what buried the narration; a new bed
		// starts at -18 dB with one-second ramps.
		const bed = createAudioTrack({ assetId: "asset_1", durationSec: 60 });
		expect(bed.kind).toBe("music");
		expect([bed.gainDb, bed.fadeInMs, bed.fadeOutMs]).toEqual([-18, 1000, 1000]);
		// A voiceover is voice: the export levels it, so it starts flat.
		const take = createAudioTrack({ assetId: "asset_1", durationSec: 5, kind: "voiceover" });
		expect([take.gainDb, take.fadeInMs, take.fadeOutMs]).toEqual([0, 0, 0]);
	});

	it("leaves a stored bed at the level its author set", () => {
		// The new defaults are for NEW tracks. A track saved before them, even one that
		// omits the fields, parses exactly as it did.
		const {
			gainDb: _gain,
			fadeInMs: _in,
			fadeOutMs: _out,
			...stored
		} = createAudioTrack({
			assetId: "asset_1",
			durationSec: 60,
		});
		expect(audioTrackSchema.parse(stored)).toMatchObject({ gainDb: 0, fadeInMs: 0, fadeOutMs: 0 });
		expect(audioTrackSchema.parse({ ...stored, gainDb: -3 }).gainDb).toBe(-3);
	});

	it("defaults audioTracks to [] when a stored document omits the key", () => {
		// A document written before issue #350 has no `audioTracks`; the defaulted
		// array must fill in so older files load unchanged (no schemaVersion bump).
		const { audioTracks: _drop, ...withoutAudio } = createEmptyDocument({
			projectId: "p",
			title: "t",
		});
		expect("audioTracks" in withoutAudio).toBe(false);
		const parsed = documentSchema.parse(withoutAudio);
		expect(parsed.audioTracks).toEqual([]);
	});

	it("round-trips a document carrying an audio track", () => {
		const track = createAudioTrack({ assetId: "asset_1", durationSec: 8 });
		const doc = {
			...createEmptyDocument({ projectId: "p", title: "t" }),
			audioTracks: [track],
		};
		const parsed = documentSchema.parse(doc);
		expect(parsed.audioTracks).toEqual([track]);
	});
});

// --- v7 -> v8 : Auto becomes the default ratio ---------------------------------

describe("v7 -> v8 default ratio pin", () => {
	const v7Doc = (legacyEditor: Record<string, unknown> | null) => ({
		...createEmptyDocument({ projectId: "p", title: "t" }),
		schemaVersion: 7,
		legacyEditor,
	});
	const ratioOf = (raw: unknown) =>
		((raw as Record<string, unknown>).legacyEditor as Record<string, unknown>).aspectRatio;

	it("pins 16:9 on a document that never chose a ratio, so it keeps its frame", () => {
		expect(ratioOf(upgradeV7DocumentToV8(v7Doc(null)))).toBe("16:9");
		const out = upgradeV7DocumentToV8(v7Doc({ padding: 20 })) as Record<string, unknown>;
		expect(out.schemaVersion).toBe(8);
		expect(out.legacyEditor).toEqual({ padding: 20, aspectRatio: "16:9" });
	});

	it("keeps a ratio the document already states", () => {
		for (const aspectRatio of ["9:16", "683:384", "auto", "native"]) {
			expect(ratioOf(upgradeV7DocumentToV8(v7Doc({ aspectRatio })))).toBe(aspectRatio);
		}
	});

	it("leaves a current document alone, so a new project keeps reading the Auto default", () => {
		const fresh = createEmptyDocument({ projectId: "p", title: "t" });
		expect(upgradeV7DocumentToV8(fresh)).toBe(fresh);
		expect(fresh.legacyEditor).toBeNull();
	});
});

describe("zoom click impact lifted to the cursor setting", () => {
	const doc = (zoomRanges: unknown[], legacyEditor: Record<string, unknown> | null = null) => ({
		...createEmptyDocument({ projectId: "p", title: "t" }),
		zoomRanges,
		legacyEditor,
	});
	const zoom = (extra: Record<string, unknown> = {}) => ({
		id: "z",
		startMs: 0,
		endMs: 1000,
		depth: 3,
		focus: { cx: 0.5, cy: 0.5 },
		rotationPreset: "left",
		...extra,
	});
	const load = (raw: unknown) => documentSchema.parse(migrateRawDocumentToCurrent(raw));

	it("turns the cursor setting on when any zoom had it, and drops the zoom's key", () => {
		const out = load(doc([zoom(), zoom({ id: "y", clickImpact: true })], { padding: 20 }));
		expect(out.legacyEditor).toEqual({ padding: 20, cursorClickImpact: true });
		expect(out.zoomRanges.every((z) => !("clickImpact" in z))).toBe(true);
	});

	it("keeps a cursor setting the document already states", () => {
		const out = load(doc([zoom({ clickImpact: true })], { cursorClickImpact: false }));
		expect(out.legacyEditor).toEqual({ cursorClickImpact: false });
	});

	it("leaves a document without it untouched", () => {
		const raw = doc([zoom()]);
		expect(migrateRawDocumentToCurrent(raw)).toBe(raw);
	});
});

// --- follow-cursor -> orbit : the orbit camera gains a manual mode ---------------------------

describe("follow-cursor zooms read as orbits under auto focus", () => {
	const zoom = (extra: Record<string, unknown>) => ({
		id: "z",
		startMs: 0,
		endMs: 1000,
		depth: 3,
		focus: { cx: 0.2, cy: 0.7 },
		...extra,
	});
	const docWith = (zoomRanges: unknown[]) => ({
		...createEmptyDocument({ projectId: "p", title: "t" }),
		zoomRanges,
	});

	it("keeps them following the cursor, whatever focus mode they stored", () => {
		const doc = parseDocumentFile(
			docWith([
				zoom({ id: "manual", rotationPreset: "follow-cursor", focusMode: "manual" }),
				zoom({ id: "unset", rotationPreset: "follow-cursor" }),
				zoom({ id: "left", rotationPreset: "left" }),
			]),
		);
		expect(doc.zoomRanges.map((z) => [z.id, z.rotationPreset, z.focusMode])).toEqual([
			["manual", "orbit", "auto"],
			["unset", "orbit", "auto"],
			["left", "left", undefined],
		]);
	});

	it("leaves an orbit set to manual alone, so a second load changes nothing", () => {
		const manualOrbit = docWith([zoom({ rotationPreset: "orbit", focusMode: "manual" })]);
		expect(migrateRawDocumentToCurrent(manualOrbit)).toBe(manualOrbit);
	});
});

describe("shader effects (docs/shader-effects.md)", () => {
	const effect = {
		id: "fx",
		name: "Dim",
		contract: 1,
		code: "fn effect(uv: vec2<f32>) -> vec4<f32> { return frame(uv); }",
		params: [{ type: "number", name: "level", default: 1, min: 0, max: 2 }],
	};

	it("fills the defaults of a definition and of a region", () => {
		expect(shaderEffectSchema.parse(effect)).toMatchObject({
			description: "",
			origin: "agent",
			params: [{ name: "level", label: "" }],
		});
		expect(
			shaderEffectRangeSchema.parse({ id: "r", startMs: 0, endMs: 1000, effectId: "fx" }),
		).toMatchObject({ values: {}, target: "image" });
	});

	it("refuses a parameter declared twice, or a default out of its bounds", () => {
		const twice = { ...effect, params: [effect.params[0], effect.params[0]] };
		expect(shaderEffectSchema.safeParse(twice).success).toBe(false);
		const outside = { ...effect, params: [{ ...effect.params[0], default: 3 }] };
		expect(shaderEffectSchema.safeParse(outside).success).toBe(false);
	});

	// A newer build may write a contract this one does not know: the document must still open,
	// and the compositor leaves those regions undrawn.
	it("loads a contract version it does not know", () => {
		expect(shaderEffectSchema.safeParse({ ...effect, contract: 2 }).success).toBe(true);
	});

	it("keeps a document without effects free of both keys", () => {
		const doc = createEmptyDocument({ title: "t", projectId: "p" });
		const parsed = documentSchema.parse(doc);
		expect("shaderEffects" in parsed).toBe(false);
		expect("shaderEffectRanges" in parsed).toBe(false);
	});
});