Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
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();
});
});
});