Skip to content

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

38.0 KB
Raw Blame
import { spawnSync } from "node:child_process";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { AxcutAsset, AxcutDocument } from "../../src/lib/ai-edition/schema";
import { axcutSchemaVersion } from "../../src/lib/ai-edition/schema";
import {
	DEFAULT_EDITOR_SETTINGS,
	getEditorSettings,
	patchEditorSettings,
} from "../../src/lib/ai-edition/store/editorSettings";
import {
	factoryStylePresetAppearance,
	stylePresetAppearanceFromSettings,
} from "../../src/lib/ai-edition/stylePresetsEditor";
import { registerMediaLinks } from "../media/mediaLinksRegistry";
import {
	DocumentNotFoundError,
	DocumentService,
	isProcessAlive,
	ProjectFileError,
	ProjectOpenInEditorError,
} from "./document-service";

async function makeTempDir(): Promise<string> {
	const base = await fs.mkdtemp(path.join(os.tmpdir(), "openscreen-ai-edition-"));
	return base;
}

describe("DocumentService", () => {
	let tempDir: string;
	let mediaDir: string;
	let service: DocumentService;

	beforeEach(async () => {
		tempDir = await makeTempDir();
		mediaDir = await makeTempDir();
		service = new DocumentService(tempDir, mediaDir);
	});

	afterEach(async () => {
		await fs.rm(tempDir, { recursive: true, force: true });
		await fs.rm(mediaDir, { recursive: true, force: true });
	});

	describe("createProject", () => {
		it("creates a v8 doc with the given title and writes it to disk", async () => {
			const doc = await service.createProject("Demo Project");
			expect(doc.schemaVersion).toBe(9);
			expect(doc.project.title).toBe("Demo Project");
			expect(doc.project.id).toMatch(/^proj_/);
			expect(doc.assets).toEqual([]);

			const filePath = path.join(tempDir, `${doc.project.id}.openscreen`);
			const raw = await fs.readFile(filePath, "utf8");
			expect(JSON.parse(raw)).toMatchObject({
				schemaVersion: axcutSchemaVersion,
				project: { title: "Demo Project" },
			});
		});

		it("falls back to 'Untitled Project' for empty titles", async () => {
			const doc = await service.createProject("   ");
			expect(doc.project.title).toBe("Untitled Project");
		});

		describe("the look a new project starts from", () => {
			const PRESET = {
				...factoryStylePresetAppearance(),
				aspectRatio: "9:16" as const,
				padding: 7,
				wallpaper: "#112233",
			};

			/** Saves a project whose look (and footage state) was edited, at a given time. */
			async function editedProject(padding: number, updatedAt: string): Promise<void> {
				const created = await service.createProject(`P${padding}`);
				const edited = patchEditorSettings(created, {
					padding,
					aspectRatio: "1:1",
					cropRegion: { x: 0.2, y: 0.2, width: 0.5, height: 0.5 },
					audioGainDb: 4,
				});
				// saveProject stamps "now"; write the chosen instant straight to disk instead.
				const filePath = path.join(tempDir, `${created.project.id}.openscreen`);
				await fs.writeFile(
					filePath,
					JSON.stringify({ ...edited, project: { ...edited.project, updatedAt } }),
				);
			}

			it("starts from the factory look when there is nothing to inherit", async () => {
				const doc = await service.createProject("First");
				expect(doc.legacyEditor).toBeNull();
			});

			it("takes the most recently edited project's look, never its format or footage", async () => {
				await editedProject(11, "2026-01-01T00:00:00.000Z");
				await editedProject(22, "2026-03-01T00:00:00.000Z");
				await editedProject(33, "2026-02-01T00:00:00.000Z");
				const settings = getEditorSettings(await service.createProject("Next"));
				expect(settings.padding).toBe(22);
				expect(settings.aspectRatio).toBe(DEFAULT_EDITOR_SETTINGS.aspectRatio);
				expect(settings.cropRegion).toEqual(DEFAULT_EDITOR_SETTINGS.cropRegion);
				expect(settings.audioGainDb).toBe(0);
			});

			it("prefers the preset marked for new projects, format left out", async () => {
				await editedProject(22, "2026-03-01T00:00:00.000Z");
				const withPreset = new DocumentService(tempDir, mediaDir, undefined, async () => PRESET);
				const settings = getEditorSettings(await withPreset.createProject("Next"));
				expect(stylePresetAppearanceFromSettings(settings)).toEqual({
					...PRESET,
					aspectRatio: DEFAULT_EDITOR_SETTINGS.aspectRatio,
				});
			});

			it("falls back to the last project when the marked preset is gone or unreadable", async () => {
				await editedProject(22, "2026-03-01T00:00:00.000Z");
				vi.spyOn(console, "warn").mockImplementation(() => undefined);
				for (const provider of [
					async () => null,
					async () => {
						throw new Error("disk gone");
					},
				]) {
					const next = new DocumentService(tempDir, mediaDir, undefined, provider);
					expect(getEditorSettings(await next.createProject("Next")).padding).toBe(22);
				}
			});
		});
	});

	describe("getProject", () => {
		it("returns the doc by id", async () => {
			const created = await service.createProject("Round trip");
			const fetched = await service.getProject(created.project.id);
			expect(fetched.project.id).toBe(created.project.id);
		});

		it("throws DocumentNotFoundError for missing projects", async () => {
			await expect(service.getProject("proj_does-not-exist")).rejects.toBeInstanceOf(
				DocumentNotFoundError,
			);
		});

		it("rejects project ids with path-traversal characters", async () => {
			await expect(service.getProject("../etc/passwd")).rejects.toBeInstanceOf(ProjectFileError);
			await expect(service.getProject("proj/with/slash")).rejects.toBeInstanceOf(ProjectFileError);
		});

		// Issue #348 — recording with no camera AND no microphone is the default for
		// anyone capturing a screen demo, and the failure lands at REOPEN, where the
		// recording exists on disk but the user cannot get to it. The recorder writes
		// no audio stream at all in that configuration (confirmed with ffprobe on real
		// captures) and `cameraTrack: null`, so this is the exact on-disk shape.
		describe("camera-less, microphone-less recordings", () => {
			// Windows path separators on purpose: the reporter is on Windows 11 and
			// `path.join` gives us the host's, so this stays honest on all three.
			async function writeCamlessProject(originalPath: string, sizeBytes?: number) {
				const doc = await service.createProject("Screen demo, no cam no mic");
				const asset: AxcutAsset = {
					id: "asset_camless",
					kind: "video",
					label: path.basename(originalPath),
					originalPath,
					sizeBytes,
					// No `audio` (the probe never populates it) and no camera link.
					cameraTrack: null,
					transcriptionFailure: {
						kind: "no-audio",
						message: "No audio track found in this video.",
					},
				};
				await service.saveProject({
					...doc,
					assets: [asset],
					project: { ...doc.project, primaryAssetId: asset.id },
				});
				return doc.project.id;
			}

			it("reopens, and stays listed", async () => {
				const screenPath = path.join(mediaDir, "screen-demo.mp4");
				await fs.writeFile(screenPath, "screen bytes", "utf8");
				const projectId = await writeCamlessProject(screenPath);

				const reopened = await service.getProject(projectId);
				expect(reopened.assets[0]?.cameraTrack).toBeNull();
				expect(reopened.assets[0]?.originalPath).toBe(screenPath);
				// A document that throws here is dropped by listProjects' skip-on-error
				// catch, which presents to the user as "my project vanished" rather than
				// as an error — so the absence of a throw is not enough to assert.
				const summaries = await service.listProjects();
				expect(summaries.map((s) => s.id)).toContain(projectId);
				// Re-decided on every open, so it must survive the round trip or the
				// whole recording is re-extracted for transcription each time.
				expect(reopened.assets[0]?.transcriptionFailure?.kind).toBe("no-audio");
			});

			it("does not hand the relinker's webcam to an asset that never had one", async () => {
				// The relink only runs when something is actually broken, so move the
				// screen file — and register a link that DOES carry a webcam, which is
				// the shape that produced #265 (screen recording used as the webcam).
				const screenBytes = "screen bytes";
				const screenPath = path.join(mediaDir, "moved-screen-demo.mp4");
				const webcamPath = path.join(mediaDir, "moved-screen-demo-webcam.mp4");
				await fs.writeFile(screenPath, screenBytes, "utf8");
				await fs.writeFile(webcamPath, "webcam bytes", "utf8");
				await registerMediaLinks(mediaDir, screenPath, { webcamVideoPath: webcamPath });

				const projectId = await writeCamlessProject(
					path.join(mediaDir, "gone", "moved-screen-demo.mp4"),
					Buffer.byteLength(screenBytes),
				);

				const reopened = await service.getProject(projectId);
				expect(reopened.assets[0]?.originalPath).toBe(screenPath);
				expect(reopened.assets[0]?.cameraTrack).toBeNull();
			});
		});

		// Issue #212 — a project authored on another machine opens with every asset
		// pointing at a path that does not exist here. The relink runs on this read,
		// not on import, so a document already saved broken still recovers.
		describe("relinking moved media", () => {
			const stalePath = "C:\\Users\\demo\\recording-42.mp4";
			const staleWebcamPath = "C:\\Users\\demo\\recording-42-webcam.mp4";
			const screenBytes = "screen bytes";
			let screenPath: string;
			let webcamPath: string;
			let logged: string[];

			beforeEach(async () => {
				screenPath = path.join(mediaDir, "recording-42.mp4");
				webcamPath = path.join(mediaDir, "recording-42-webcam.mp4");
				await fs.writeFile(screenPath, screenBytes, "utf8");
				await fs.writeFile(webcamPath, "webcam bytes", "utf8");
				await registerMediaLinks(mediaDir, screenPath, { webcamVideoPath: webcamPath });
				logged = [];
				const record = (...args: unknown[]) => {
					logged.push(args.join(" "));
				};
				vi.spyOn(console, "log").mockImplementation(record);
				vi.spyOn(console, "warn").mockImplementation(record);
			});

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

			async function writeStaleProject(sizeBytes: number | undefined): Promise<string> {
				const doc = await service.createProject("Moved media");
				const asset: AxcutAsset = {
					id: "asset_moved",
					kind: "video",
					label: "recording-42.mp4",
					originalPath: stalePath,
					sizeBytes,
					cameraTrack: { sourcePath: staleWebcamPath, startMs: 0, offsetMs: 0, visible: true },
				};
				await service.saveProject({
					...doc,
					assets: [asset],
					project: { ...doc.project, primaryAssetId: asset.id },
				});
				return doc.project.id;
			}

			it("repoints screen and webcam paths at the registry's copies", async () => {
				const projectId = await writeStaleProject(Buffer.byteLength(screenBytes));
				const loaded = await service.getProject(projectId);
				expect(loaded.assets[0]?.originalPath).toBe(screenPath);
				expect(loaded.assets[0]?.cameraTrack?.sourcePath).toBe(webcamPath);
				// The renderer saves what it is handed, so a rewrite must be traceable.
				expect(logged.join("\n")).toContain(screenPath);
			});

			it("leaves the paths alone when the document recorded no file size", async () => {
				// Every v1.7-migrated document is in this state: only addAsset records a
				// size. Matching on the basename alone would hand this project a
				// different recording — and that recording's webcam — without a word.
				const projectId = await writeStaleProject(undefined);
				const loaded = await service.getProject(projectId);
				expect(loaded.assets[0]?.originalPath).toBe(stalePath);
				expect(loaded.assets[0]?.cameraTrack?.sourcePath).toBe(staleWebcamPath);
				expect(logged.join("\n")).toContain(stalePath);
			});
		});
	});

	describe("listProjects", () => {
		it("returns summaries sorted by updatedAt desc", async () => {
			const a = await service.createProject("A");
			await new Promise((r) => setTimeout(r, 5));
			const b = await service.createProject("B");
			const summaries = await service.listProjects();
			expect(summaries.map((s) => s.id)).toEqual([b.project.id, a.project.id]);
			expect(summaries[0]?.title).toBe("B");
		});

		it("skips files that fail to parse rather than throwing", async () => {
			const a = await service.createProject("OK");
			await fs.writeFile(path.join(tempDir, "garbage.openscreen"), "not json", "utf8");
			const summaries = await service.listProjects();
			expect(summaries.map((s) => s.id)).toEqual([a.project.id]);
		});

		it("migrates a legacy .axcut project to .openscreen on access", async () => {
			// A project written by an older build: same document bytes, `.axcut` name.
			const created = await service.createProject("Legacy");
			const openscreenPath = path.join(tempDir, `${created.project.id}.openscreen`);
			const axcutPath = path.join(tempDir, `${created.project.id}.axcut`);
			await fs.rename(openscreenPath, axcutPath);

			// A fresh service (new process) must still surface and load it, renaming
			// the file across in the process.
			const fresh = new DocumentService(tempDir, mediaDir);
			const summaries = await fresh.listProjects();
			expect(summaries.map((s) => s.id)).toEqual([created.project.id]);
			await expect(fresh.getProject(created.project.id)).resolves.toMatchObject({
				project: { id: created.project.id, title: "Legacy" },
			});
			await expect(fs.access(axcutPath)).rejects.toBeTruthy();
			await expect(fs.access(openscreenPath)).resolves.toBeUndefined();
		});
	});

	describe("onProjectRead", () => {
		it("announces every document it hands out, after the relink", async () => {
			// The read allow-list lives in the main process and is in memory: a picker's
			// approval is gone by the next launch. This callback is how a project reopened
			// tomorrow can still read the media it declares — and it must fire with the
			// RELINKED paths, since those are the ones the renderer will ask for.
			const seen: string[][] = [];
			const service = new DocumentService(tempDir, mediaDir, (doc) =>
				seen.push(doc.assets.map((a) => a.originalPath)),
			);
			const created = await service.createProject("P");
			const withAsset = await service.addAsset(created.project.id, {
				path: path.join(mediaDir, "take.mp4"),
				label: "take.mp4",
			});
			seen.length = 0;
			await service.getProject(created.project.id);
			expect(seen).toEqual([withAsset.assets.map((a) => a.originalPath)]);
		});

		it("is optional, so a service built without it loads as it always did", async () => {
			const created = await service.createProject("P");
			await expect(service.getProject(created.project.id)).resolves.toMatchObject({
				project: { id: created.project.id },
			});
		});
	});

	describe("addAsset", () => {
		it("appends a video asset and sets primaryAssetId on the first add", async () => {
			const doc = await service.createProject("P");
			const updated = await service.addAsset(doc.project.id, {
				path: "/tmp/screen.mp4",
				label: "Screen",
			});
			expect(updated.assets).toHaveLength(1);
			const asset = updated.assets[0];
			expect(asset?.kind).toBe("video");
			expect(asset?.originalPath).toBe("/tmp/screen.mp4");
			expect(asset?.label).toBe("Screen");
			expect(updated.project.primaryAssetId).toBe(asset?.id);
		});

		it("resolves relative paths against the cwd", async () => {
			const doc = await service.createProject("P");
			const updated = await service.addAsset(doc.project.id, { path: "recording.webm" });
			expect(path.isAbsolute(updated.assets[0]?.originalPath ?? "")).toBe(true);
		});

		it("rejects unsupported video extensions", async () => {
			const doc = await service.createProject("P");
			await expect(
				service.addAsset(doc.project.id, { path: "/tmp/audio.mp3" }),
			).rejects.toBeInstanceOf(ProjectFileError);
		});

		it("preserves primaryAssetId when adding a second asset", async () => {
			const doc = await service.createProject("P");
			const first = await service.addAsset(doc.project.id, { path: "/tmp/a.mp4" });
			const after = await service.addAsset(doc.project.id, { path: "/tmp/b.mp4" });
			expect(after.project.primaryAssetId).toBe(first.project.primaryAssetId);
			expect(after.assets).toHaveLength(2);
		});

		// Issue #350 — external audio import (voiceover / BGM / SFX).
		it("appends an audio asset without claiming the primary slot", async () => {
			const doc = await service.createProject("P");
			const updated = await service.addAsset(doc.project.id, {
				path: "/tmp/voiceover.mp3",
				kind: "audio",
			});
			expect(updated.assets).toHaveLength(1);
			expect(updated.assets[0]?.kind).toBe("audio");
			// An audio-only file must never become the project's primary asset, even
			// when it is the first file added to an otherwise-empty project.
			expect(updated.project.primaryAssetId).toBeUndefined();
		});

		it("keeps the existing video primary when an audio track is added", async () => {
			const doc = await service.createProject("P");
			const withVideo = await service.addAsset(doc.project.id, { path: "/tmp/screen.mp4" });
			const primary = withVideo.project.primaryAssetId;
			const withAudio = await service.addAsset(doc.project.id, {
				path: "/tmp/bgm.wav",
				kind: "audio",
			});
			expect(withAudio.project.primaryAssetId).toBe(primary);
			expect(withAudio.assets).toHaveLength(2);
		});

		it("rejects unsupported audio extensions", async () => {
			const doc = await service.createProject("P");
			await expect(
				service.addAsset(doc.project.id, { path: "/tmp/clip.mp4", kind: "audio" }),
			).rejects.toBeInstanceOf(ProjectFileError);
		});

		it("accepts a recorded .webm take as audio", async () => {
			// MediaRecorder writes a voiceover as webm/opus — the same extension a
			// screen recording uses. The caller has already declared the kind here,
			// so this gate must take it; only the import PICKER, which has nothing
			// but the extension to go on, still refuses .webm as audio.
			const doc = await service.createProject("P");
			const next = await service.addAsset(doc.project.id, {
				path: "/tmp/voiceover-2026.webm",
				kind: "audio",
			});
			expect(next.assets.at(-1)).toMatchObject({ kind: "audio" });
			// ...and it must not have claimed the primary (video-only) slot.
			expect(next.project.primaryAssetId).toBeUndefined();
		});

		it("accepts a video extension under the default kind but not as audio", async () => {
			const doc = await service.createProject("P");
			// The same extension routing works in reverse: an .mp3 is fine as audio
			// but rejected as video (covered above), and an .mp4 is the opposite.
			await expect(
				service.addAsset(doc.project.id, { path: "/tmp/a.mp3", kind: "audio" }),
			).resolves.toBeDefined();
		});
	});

	describe("removeAsset", () => {
		it("removes the asset and cascades clips, trims, and clip modifiers", async () => {
			const doc = await service.createProject("P");
			const withAsset = await service.addAsset(doc.project.id, { path: "/tmp/a.mp4" });
			const assetId = withAsset.assets[0]?.id ?? "";
			expect(assetId).toBeTruthy();

			// Manually add a clip + trimRange so we can verify cascade
			const docWithTimeline = await service.saveProject({
				...withAsset,
				timeline: {
					...withAsset.timeline,
					clips: [
						{
							id: "clip_1",
							assetId,
							sourceStartSec: 0,
							timelineStartSec: 0,
							timelineEndSec: 1,
							wordRefs: [],
							origin: "system",
							reason: "",
						},
					],
					trimRanges: [
						{
							id: "trim_1",
							assetId,
							startSec: 0,
							endSec: 1,
							origin: "user",
							reason: "",
						},
					],
				},
				zoomRanges: [
					{
						id: "zoom_1",
						clipId: "clip_1",
						sourceStartSec: 0,
						sourceEndSec: 1,
						startMs: 0,
						endMs: 1000,
						depth: 3,
						focus: { cx: 0.5, cy: 0.5 },
					},
				],
				legacyEditor: {
					speedRegions: [
						{
							id: "speed_1",
							clipId: "clip_1",
							sourceStartSec: 0,
							sourceEndSec: 1,
							startMs: 0,
							endMs: 1000,
							speed: 2,
						},
					],
				},
			});

			const after = await service.removeAsset(docWithTimeline.project.id, assetId);
			expect(after.assets).toHaveLength(0);
			expect(after.timeline.clips).toHaveLength(0);
			expect(after.timeline.trimRanges).toHaveLength(0);
			expect(after.zoomRanges).toHaveLength(0);
			expect((after.legacyEditor as { speedRegions: unknown[] }).speedRegions).toHaveLength(0);
			expect(after.project.primaryAssetId).toBeUndefined();
		});

		it("reassigns primaryAssetId when removing the primary", async () => {
			const doc = await service.createProject("P");
			const a = await service.addAsset(doc.project.id, { path: "/tmp/a.mp4" });
			const b = await service.addAsset(doc.project.id, { path: "/tmp/b.mp4" });
			const primaryId = a.project.primaryAssetId;
			expect(primaryId).toBeTruthy();
			const after = await service.removeAsset(doc.project.id, primaryId ?? "");
			expect(after.project.primaryAssetId).toBe(b.assets[1]?.id);
		});

		// Issue #350 — an audio overlay can never be primary.
		it("passes primary to the next VIDEO asset, never to an audio asset", async () => {
			const doc = await service.createProject("P");
			const video = await service.addAsset(doc.project.id, { path: "/tmp/screen.mp4" });
			await service.addAsset(doc.project.id, { path: "/tmp/music.mp3", kind: "audio" });
			const primaryId = video.project.primaryAssetId;
			expect(primaryId).toBeTruthy();
			// Removing the only video leaves just the audio asset; primary must clear,
			// not fall to the audio one.
			const after = await service.removeAsset(doc.project.id, primaryId ?? "");
			expect(after.project.primaryAssetId).toBeUndefined();
			expect(after.assets).toHaveLength(1);
			expect(after.assets[0]?.kind).toBe("audio");
		});

		it("drops audioTracks that referenced a removed audio asset", async () => {
			const doc = await service.createProject("P");
			await service.addAsset(doc.project.id, { path: "/tmp/screen.mp4" });
			const withAudio = await service.addAsset(doc.project.id, {
				path: "/tmp/music.mp3",
				kind: "audio",
			});
			const audioId = withAudio.assets.find((a) => a.kind === "audio")?.id ?? "";
			expect(audioId).toBeTruthy();
			const withTrack = await service.saveProject({
				...withAudio,
				audioTracks: [
					{
						id: "trk_1",
						assetId: audioId,
						kind: "music",
						startMs: 0,
						endMs: 10_000,
						durationSec: 10,
						offsetMs: 0,
						gainDb: 0,
						loop: false,
						fadeInMs: 0,
						fadeOutMs: 0,
						muted: false,
						label: "music",
						origin: "user",
					},
				],
			});
			expect(withTrack.audioTracks).toHaveLength(1);
			const after = await service.removeAsset(doc.project.id, audioId);
			expect(after.audioTracks).toEqual([]);
			expect(after.assets.some((a) => a.id === audioId)).toBe(false);
		});

		it("resequences other assets and rederives their anchored regions", async () => {
			const created = await service.createProject("P");
			const withA = await service.addAsset(created.project.id, { path: "/tmp/a.mp4" });
			const withB = await service.addAsset(created.project.id, { path: "/tmp/b.mp4" });
			// Four clips that differ only in id / asset / four numbers.
			const clip = (
				id: string,
				assetId: string,
				[sourceStartSec, sourceEndSec]: [number, number],
				[timelineStartSec, timelineEndSec]: [number, number],
			) => ({
				id,
				assetId,
				sourceStartSec,
				sourceEndSec,
				timelineStartSec,
				timelineEndSec,
				wordRefs: [],
				origin: "user" as const,
				reason: "test",
			});
			const assetA = withA.assets[0]?.id ?? "";
			const assetB = withB.assets[1]?.id ?? "";
			expect(assetA).toBeTruthy();
			expect(assetB).toBeTruthy();

			await service.saveProject({
				...withB,
				timeline: {
					...withB.timeline,
					clips: [
						clip("a_1", assetA, [0, 2], [0, 2]),
						clip("b_1", assetB, [10, 14], [2, 6]),
						clip("a_2", assetA, [2, 3], [6, 7]),
						clip("b_2", assetB, [20, 22], [7, 9]),
					],
				},
				zoomRanges: [
					{
						id: "zoom_b_2",
						clipId: "b_2",
						sourceStartSec: 20.5,
						sourceEndSec: 21.5,
						startMs: 7500,
						endMs: 8500,
						depth: 3,
						focus: { cx: 0.5, cy: 0.5 },
					},
					// Bare `clipId`, no source range: not an anchor, so removing the asset that owns
					// `a_2` must NOT take it. This is what routes #249's fix through `removeAsset`
					// -- the fully-anchored zoom above survives either way, so on its own it pins
					// nothing about the predicate.
					{
						id: "zoom_partial_a_2",
						clipId: "a_2",
						startMs: 6000,
						endMs: 7000,
						depth: 3,
						focus: { cx: 0.5, cy: 0.5 },
					},
				],
			});

			const after = await service.removeAsset(created.project.id, assetA);

			expect(after.timeline.clips).toMatchObject([
				{ id: "b_1", timelineStartSec: 0, timelineEndSec: 4 },
				{ id: "b_2", timelineStartSec: 4, timelineEndSec: 6 },
			]);
			expect(after.zoomRanges).toEqual([
				expect.objectContaining({ id: "zoom_b_2", startMs: 4500, endMs: 5500 }),
				// Survives, and keeps its raw ms untouched -- now past the end of a 6s timeline.
				// That is the documented trade-off in `removeClip`: unreachable beats deleted.
				expect.objectContaining({ id: "zoom_partial_a_2", startMs: 6000, endMs: 7000 }),
			]);
		});

		it("throws when removing a missing asset", async () => {
			const doc = await service.createProject("P");
			await expect(service.removeAsset(doc.project.id, "asset_x")).rejects.toBeInstanceOf(
				ProjectFileError,
			);
		});
	});

	describe("deleteProject", () => {
		it("removes the project file", async () => {
			const doc = await service.createProject("Bye");
			await service.deleteProject(doc.project.id);
			await expect(service.getProject(doc.project.id)).rejects.toBeInstanceOf(
				DocumentNotFoundError,
			);
		});

		it("is a no-op when the file doesn't exist", async () => {
			await expect(service.deleteProject("proj_never-existed")).resolves.toBeUndefined();
		});
	});

	// These reproduce a bug that destroyed two real project files: fs.writeFile
	// truncates and writes from offset 0, so two concurrent saves of one project
	// spliced together — a short document over a long one's head, the long one's
	// tail surviving past its end. The file parsed as JSON up to the splice and
	// then died, taking the user's edits with it.
	describe("concurrent saves", () => {
		/** A document whose serialised length is driven by `annotations`. */
		const withBulk = (doc: AxcutDocument, count: number): AxcutDocument => ({
			...doc,
			annotations: Array.from({ length: count }, (_, i) => ({
				id: `ann_${i}`,
				startMs: i,
				endMs: i + 1,
				type: "text" as const,
				content: `annotation ${i} ${"x".repeat(200)}`,
				position: { x: 10, y: 10 },
				size: { width: 20, height: 10 },
				style: {
					color: "#ffffff",
					backgroundColor: "transparent",
					fontSize: 32,
					fontFamily: "Inter",
					fontWeight: "bold" as const,
					fontStyle: "normal" as const,
					textDecoration: "none" as const,
					textAlign: "center" as const,
				},
				zIndex: i,
			})),
		});

		// Repeated, because the race is a coin flip: measured on the pre-fix code,
		// one long/short race spliced the file ~5 times out of 10. A single attempt
		// passed against the very bug it was written for. 12 rounds miss it once in
		// ~4000 runs; the loop is the test, not decoration.
		//
		// Explicit timeout: 12 rounds of real create + fsync + rename take ~1.7s on
		// an idle machine but blow vitest's 5s default when the full suite runs its
		// files in parallel — observed failing there and passing alone. 30s is the
		// "this actually hung" threshold, not the expected runtime.
		it("leaves valid JSON when a long and a short save race", async () => {
			for (let round = 0; round < 12; round++) {
				const doc = await service.createProject(`Race ${round}`);
				const file = path.join(tempDir, `${doc.project.id}.openscreen`);

				// Unawaited on purpose: this is the exact shape of the real failure —
				// two saves of one project in flight at once.
				await Promise.all([
					service.saveProject(withBulk(doc, 400)),
					service.saveProject(withBulk(doc, 1)),
				]);

				const raw = await fs.readFile(file, "utf8");
				// The destroyed projects died exactly here, at the splice point: the
				// short document's bytes, then the long one's tail past its end.
				const parsed = JSON.parse(raw);
				// Whichever save landed last must be on disk WHOLE — never a mix.
				expect([1, 400]).toContain(parsed.annotations.length);
				expect(raw.trimEnd().endsWith("}")).toBe(true);
			}
		}, 30_000);

		it("applies racing saves in call order, last one winning", async () => {
			const doc = await service.createProject("Order");
			await Promise.all([
				service.saveProject(withBulk(doc, 300)),
				service.saveProject(withBulk(doc, 5)),
				service.saveProject(withBulk(doc, 120)),
			]);
			const onDisk = await service.getProject(doc.project.id);
			expect(onDisk.annotations).toHaveLength(120);
		});

		// 20 real temp-file+rename round trips, serialized through the save queue.
		// That is genuinely more than 5s of disk when the rest of the suite is
		// running in parallel, so it gets its own timeout rather than flaking.
		it("survives many interleaved saves of one project", { timeout: 20_000 }, async () => {
			const doc = await service.createProject("Storm");
			// Sizes deliberately alternate long/short: equal-length writes overwrite
			// each other cleanly and would prove nothing.
			await Promise.all(
				Array.from({ length: 20 }, (_, i) => service.saveProject(withBulk(doc, i % 2 ? 300 : 2))),
			);
			const onDisk = await service.getProject(doc.project.id);
			expect(onDisk.annotations).toHaveLength(300);
		});

		it("keeps the previous document when a save fails mid-write", async () => {
			const doc = await service.createProject("Durable");
			await service.saveProject(withBulk(doc, 3));

			// Fail the write itself, not the validation before it: a full disk or an
			// EIO lands here, where the old pipeline had already truncated the file.
			const open = vi.spyOn(fs, "open").mockRejectedValueOnce(new Error("ENOSPC: disk full"));
			await expect(service.saveProject(withBulk(doc, 99))).rejects.toThrow(ProjectFileError);
			open.mockRestore();

			// The point of temp+rename: the good document is still there, intact.
			const after = await service.getProject(doc.project.id);
			expect(after.annotations).toHaveLength(3);
		});

		it("does not leave temp files behind", async () => {
			const doc = await service.createProject("Tidy");
			await Promise.all([
				service.saveProject(withBulk(doc, 50)),
				service.saveProject(withBulk(doc, 2)),
			]);
			const entries = await fs.readdir(tempDir);
			expect(entries.filter((name) => name.includes(".tmp-"))).toEqual([]);
		});

		it("a failed save does not block later saves of the same project", async () => {
			const doc = await service.createProject("Recover");
			// The queue chains one save onto the last. If it chained on success only,
			// this rejection would strand every save behind it for the session.
			const open = vi.spyOn(fs, "open").mockRejectedValueOnce(new Error("EIO"));

			const failing = service.saveProject(withBulk(doc, 2));
			const following = service.saveProject(withBulk(doc, 7));
			await expect(failing).rejects.toThrow(ProjectFileError);
			await expect(following).resolves.toBeTruthy();
			open.mockRestore();

			expect((await service.getProject(doc.project.id)).annotations).toHaveLength(7);
		});

		it("makes a read wait for a read asked for before it", async () => {
			const doc = await service.createProject("Reads in order");
			const order: string[] = [];
			await Promise.all([
				service.getProject(doc.project.id).then(() => order.push("first")),
				service.getProject(doc.project.id).then(() => order.push("second")),
			]);
			expect(order).toEqual(["first", "second"]);
		});

		it("makes a read wait for a save already queued", async () => {
			const doc = await service.createProject("Read after write");
			const saving = service.saveProject({ ...doc, project: { ...doc.project, title: "Saved" } });
			expect((await service.getProject(doc.project.id)).project.title).toBe("Saved");
			await saving;
		});
	});

	// The MCP server saves projects the editor does not hold. If the editor opens one
	// between that read and that save, it loads the file without the save and its own
	// next save drops it without a word.
	describe("saveProjectIfUnchanged", () => {
		const renamed = (doc: AxcutDocument, title: string): AxcutDocument => ({
			...doc,
			project: { ...doc.project, title },
		});

		it("saves when nothing touched the project since the read", async () => {
			const created = await service.createProject("Untouched");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			const saved = await service.saveProjectIfUnchanged(renamed(document, "Edited"), version);
			expect(saved?.project.title).toBe("Edited");
			expect((await service.getProject(created.project.id)).project.title).toBe("Edited");
		});

		it("writes nothing when the project was read since, as the editor opening it does", async () => {
			const created = await service.createProject("Opened");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			await service.getProject(created.project.id);
			expect(await service.saveProjectIfUnchanged(renamed(document, "Edited"), version)).toBeNull();
			expect((await service.getProject(created.project.id)).project.title).toBe("Opened");
		});

		it("writes nothing when a read arrives while it is queued, and that read sees the file as it is", async () => {
			const created = await service.createProject("Racing");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			// Unawaited: the editor's open lands while the save waits for its turn.
			const saving = service.saveProjectIfUnchanged(renamed(document, "Edited"), version);
			const opened = await service.getProject(created.project.id);
			expect(await saving).toBeNull();
			expect(opened.project.title).toBe("Racing");
		});

		it("writes nothing when the project was saved since", async () => {
			const created = await service.createProject("Saved");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			await service.saveProject(renamed(document, "Elsewhere"));
			expect(await service.saveProjectIfUnchanged(renamed(document, "Edited"), version)).toBeNull();
			expect((await service.getProject(created.project.id)).project.title).toBe("Elsewhere");
		});

		it("writes nothing when the file changed outside the app, updatedAt and all", async () => {
			const created = await service.createProject("External");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			const file = path.join(tempDir, `${created.project.id}.openscreen`);
			await fs.writeFile(file, JSON.stringify(renamed(document, "Synced")), "utf8");
			expect(await service.saveProjectIfUnchanged(renamed(document, "Edited"), version)).toBeNull();
			expect((await service.getProject(created.project.id)).project.title).toBe("Synced");
		});

		it("writes nothing over a project deleted since", async () => {
			const created = await service.createProject("Deleted");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			await service.deleteProject(created.project.id);
			expect(await service.saveProjectIfUnchanged(renamed(document, "Edited"), version)).toBeNull();
			await expect(service.getProject(created.project.id)).rejects.toThrow(DocumentNotFoundError);
		});

		it("writes nothing over a project another process's editor holds (#1138)", async () => {
			const created = await service.createProject("Held");
			const { document, version } = await service.getProjectForUpdate(created.project.id);
			// The app, on the same folder, opens it after the read: only its marker says so.
			new DocumentService(tempDir, mediaDir).markOpenInEditor(created.project.id);
			await expect(
				service.saveProjectIfUnchanged(renamed(document, "Edited"), version),
			).rejects.toThrow(ProjectOpenInEditorError);
			expect((await service.getProject(created.project.id)).project.title).toBe("Held");
		});
	});

	describe("the project open in an editor", () => {
		const marker = () => path.join(tempDir, ".open-in-editor.json");
		/** A pid that was just alive and is not any more. */
		const deadPid = () => spawnSync(process.execPath, ["-e", ""]).pid;

		it("is none until an editor says so", async () => {
			expect(await service.projectOpenInEditor()).toBeNull();
		});

		it("is what an editor in any process sharing the folder last said, until it lets go", async () => {
			const app = new DocumentService(tempDir, mediaDir);
			app.markOpenInEditor("proj_a");
			expect(await service.projectOpenInEditor()).toBe("proj_a");
			app.markOpenInEditor("proj_b");
			expect(await service.projectOpenInEditor()).toBe("proj_b");
			app.markOpenInEditor(null);
			expect(await service.projectOpenInEditor()).toBeNull();
		});

		it("ignores the marker of a process that is gone, as after a crash", async () => {
			await fs.writeFile(marker(), JSON.stringify({ pid: deadPid(), projectId: "proj_a" }));
			expect(await service.projectOpenInEditor()).toBeNull();
		});

		it("ignores a marker it cannot read", async () => {
			await fs.writeFile(marker(), "{not json");
			expect(await service.projectOpenInEditor()).toBeNull();
			await fs.writeFile(marker(), JSON.stringify({ projectId: "proj_a" }));
			expect(await service.projectOpenInEditor()).toBeNull();
		});

		it("never shows up as a project", async () => {
			await service.createProject("Listed");
			service.markOpenInEditor("proj_a");
			expect((await service.listProjects()).map((p) => p.title)).toEqual(["Listed"]);
		});
	});

	describe("isProcessAlive", () => {
		it("tells a running process from one that exited", () => {
			expect(isProcessAlive(process.pid)).toBe(true);
			expect(isProcessAlive(spawnSync(process.execPath, ["-e", ""]).pid)).toBe(false);
		});
	});

	describe("storedProjectId", () => {
		it("names the project a file in the projects folder is the own file of", () => {
			expect(service.storedProjectId(path.join(tempDir, "proj_a.openscreen"))).toBe("proj_a");
			expect(service.storedProjectId(path.join(tempDir, "proj_a.axcut"))).toBe("proj_a");
		});

		it("names nothing for a file anywhere else", () => {
			expect(service.storedProjectId(path.join(mediaDir, "proj_a.openscreen"))).toBeUndefined();
			expect(
				service.storedProjectId(path.join(tempDir, "sub", "proj_a.openscreen")),
			).toBeUndefined();
			expect(service.storedProjectId(path.join(tempDir, "proj_a.json"))).toBeUndefined();
		});
	});
});