AI media harness for planning, generating, and editing locally
TypeScript
import { describe, expect, it } from "vitest";
import { parseProjectConfig, type TimelineClip, type TimelineTrack } from "./project";
import {
adjacentCut,
cutPoints,
formatTimecode,
parseTimecode,
pasteClip,
rulerLabel,
rulerScale,
scrollAfterZoom,
clipEndMs,
freeStart,
insertClip,
moveClip,
removeClip,
snapStart,
snapTargets,
snapTime,
sourceRoom,
trimClip,
} from "./timeline";
const clip = (id: string, startMs: number, durationMs: number, over: Partial<TimelineClip> = {}): TimelineClip => ({
id, assetId: `asset-${id}`, trackId: "v1", startMs, durationMs, sourceStartMs: 0,
label: id, color: null, status: "approved", ...over,
});
const track = (id: string, kind: "video" | "audio", clips: TimelineClip[], over: Partial<TimelineTrack> = {}): TimelineTrack => ({
id, kind, name: id, locked: false, muted: false, clips: clips.map((item) => ({ ...item, trackId: id })), ...over,
});
/* Two picture lanes and two sound lanes, which is what makes "to another track"
testable in both directions and "not onto that one" testable at all. */
const stage = () => [
track("v1", "video", [clip("a", 0, 4_000), clip("b", 6_000, 2_000)]),
track("v2", "video", []),
track("a1", "audio", [clip("music", 0, 10_000)]),
track("a2", "audio", []),
];
const lane = (tracks: TimelineTrack[], id: string) => tracks.find((item) => item.id === id)!;
const at = (tracks: TimelineTrack[], trackId: string, clipId: string) => lane(tracks, trackId).clips.find((item) => item.id === clipId);
/** Nothing any of these functions returns may put two clips over each other —
* the single invariant the whole module exists to keep. */
const noOverlaps = (tracks: TimelineTrack[]) =>
tracks.every((item) => [...item.clips].sort((a, b) => a.startMs - b.startMs)
.every((current, index, sorted) => index === 0 || sorted[index - 1].startMs + sorted[index - 1].durationMs <= current.startMs));
describe("snapping", () => {
it("offers the head of the timeline, the playhead, and both ends of every other clip", () => {
// 0 and the playhead, plus b (6s–8s) and the music (0–10s) — a's own edges
// are missing because a is the clip being dragged.
expect(snapTargets(stage(), { excludeClipId: "a", playheadMs: 5_500 }))
.toEqual([0, 5_500, 6_000, 8_000, 10_000]);
// The dragged clip is not a target for itself, or it could never move.
expect(snapTargets(stage(), { excludeClipId: "a" })).not.toContain(4_000);
});
it("takes the nearest target inside the tolerance and leaves everything else alone", () => {
const snap = { targets: [0, 6_000, 8_000], toleranceMs: 200 };
expect(snapTime(5_900, snap)).toBe(6_000);
expect(snapTime(6_250, snap)).toBe(6_250);
// A tolerance of zero is how the view says "I have not measured the lane
// yet". It must disable the magnet rather than snap everything to 0.
expect(snapTime(5_900, { targets: [0, 6_000], toleranceMs: 0 })).toBe(5_900);
});
it("lets the tail of a clip take the magnet, which is how a cut gets closed up", () => {
const snap = { targets: [6_000], toleranceMs: 200 };
// Head is 4s from anything; the tail is 100ms short of the next clip's head,
// so the clip lands flush and the gap disappears.
expect(snapStart(5_900 - 4_000, 4_000, snap)).toBe(2_000);
// Whichever end is closer wins: here it is the head.
expect(snapStart(5_950, 4_000, snap)).toBe(6_000);
});
});
describe("placing a clip where there is room", () => {
it("leaves a free position alone", () => {
expect(freeStart([clip("a", 0, 4_000)], 5_000, 1_000)).toBe(5_000);
});
it("butts up against whatever is in the way, on the nearer side", () => {
const neighbours = [clip("a", 2_000, 4_000)];
// Dropped over the head of the neighbour: lands flush in front of it.
expect(freeStart(neighbours, 2_300, 1_000)).toBe(1_000);
// Dropped over its tail: lands flush after it.
expect(freeStart(neighbours, 5_500, 1_000)).toBe(6_000);
// And a clip dropped where it already fits is not moved at all.
expect(freeStart(neighbours, 500, 1_000)).toBe(500);
});
it("finds a gap big enough and refuses when there is none", () => {
const crowd = [clip("a", 0, 4_000), clip("b", 5_000, 4_000)];
// The 1s gap takes a 1s clip exactly.
expect(freeStart(crowd, 4_400, 1_000)).toBe(4_000);
// A 2s clip does not fit in it, so it goes after the crowd rather than on
// top of anything.
expect(freeStart(crowd, 4_400, 2_000)).toBe(9_000);
// Nowhere at all: both edges of the crowd blocked by the timeline head is
// impossible, but a lane with no room to the left still answers honestly.
expect(freeStart([clip("a", 0, 4_000)], 0, 4_000)).toBe(4_000);
});
it("never lands a clip before the start of the timeline", () => {
expect(freeStart([], -5_000, 1_000)).toBe(0);
});
});
describe("moving a clip", () => {
it("moves it along its own lane", () => {
// b is 2s long and 4s–6s is empty, so this is a plain slide with no
// neighbour involved.
const next = moveClip(stage(), "b", "v1", 4_200)!;
expect(at(next, "v1", "b")!.startMs).toBe(4_200);
expect(noOverlaps(next)).toBe(true);
});
it("moves it to another lane of the same kind, and takes it off the old one", () => {
const next = moveClip(stage(), "a", "v2", 3_000)!;
expect(lane(next, "v1").clips.map((item) => item.id)).toEqual(["b"]);
expect(at(next, "v2", "a")).toMatchObject({ startMs: 3_000, trackId: "v2" });
// The clip's own record of which track it is on has to move with it, or the
// project says one thing and the lane it is drawn in says another.
expect(at(next, "v2", "a")!.trackId).toBe("v2");
});
it("moves sound between sound tracks", () => {
const next = moveClip(stage(), "music", "a2", 2_000)!;
expect(lane(next, "a1").clips).toHaveLength(0);
expect(at(next, "a2", "music")!.startMs).toBe(2_000);
});
it("refuses to mix picture and sound, or to touch a locked track", () => {
expect(moveClip(stage(), "music", "v2", 0)).toBeNull();
expect(moveClip(stage(), "a", "a2", 0)).toBeNull();
const lockedTarget = stage().map((item) => (item.id === "v2" ? { ...item, locked: true } : item));
expect(moveClip(lockedTarget, "a", "v2", 0)).toBeNull();
const lockedSource = stage().map((item) => (item.id === "v1" ? { ...item, locked: true } : item));
expect(moveClip(lockedSource, "a", "v2", 0)).toBeNull();
});
it("slides against a neighbour instead of covering it", () => {
// Dragged over the middle of b (6s–8s): it cannot land there, so it lands
// flush against the side the pointer was nearer to.
const next = moveClip(stage(), "a", "v1", 6_500)!;
expect(at(next, "v1", "a")!.startMs).toBe(8_000);
expect(noOverlaps(next)).toBe(true);
});
it("does not count the clip as its own neighbour when it moves within a lane", () => {
// Nudged 100ms right on a lane where the only other clip is far away. If
// the clip were still on the lane while being placed, it would block itself
// and jump the whole width of itself instead.
const next = moveClip(stage(), "a", "v1", 100)!;
expect(at(next, "v1", "a")!.startMs).toBe(100);
});
it("reports no move rather than an identical project", () => {
expect(moveClip(stage(), "a", "v1", 0)).toBeNull();
expect(moveClip(stage(), "nope", "v1", 0)).toBeNull();
expect(moveClip(stage(), "a", "no-such-track", 0)).toBeNull();
});
it("snaps to a neighbour while moving", () => {
const snap = { targets: snapTargets(stage(), { excludeClipId: "a" }), toleranceMs: 300 };
// 4.1s from the head means the tail lands 100ms short of b: close the gap.
const next = moveClip(stage(), "a", "v1", 2_100, snap)!;
expect(at(next, "v1", "a")!.startMs).toBe(2_000);
expect(clipEndMs(at(next, "v1", "a")!)).toBe(6_000);
});
});
describe("trimming a clip by its edges", () => {
const room = { headMs: 3_000, tailMs: 3_000 };
it("moves the head on the ruler and inside the file together", () => {
const tracks = [track("v1", "video", [clip("a", 4_000, 4_000, { sourceStartMs: 3_000 })])];
const next = trimClip(tracks, "a", "start", 5_000, { minClipMs: 40, room })!;
const trimmed = at(next, "v1", "a")!;
expect(trimmed.startMs).toBe(5_000);
expect(trimmed.durationMs).toBe(3_000);
// A second later on the ruler is a second later in the footage, or the
// trim would slide the picture under the cut.
expect(trimmed.sourceStartMs).toBe(4_000);
});
it("will not pull the head back past the footage the file has", () => {
const tracks = [track("v1", "video", [clip("a", 4_000, 4_000, { sourceStartMs: 1_000 })])];
// Only 1s of head is left in the file, so 4_000 - 1_000 is the floor.
const next = trimClip(tracks, "a", "start", 0, { minClipMs: 40, room: { headMs: 1_000, tailMs: 0 } })!;
expect(at(next, "v1", "a")).toMatchObject({ startMs: 3_000, durationMs: 5_000, sourceStartMs: 0 });
});
it("lets a still image be pulled open at either end, because it has no footage to run out of", () => {
const tracks = [track("v1", "video", [clip("still", 4_000, 2_000)])];
const unbounded = { headMs: null, tailMs: null };
expect(at(trimClip(tracks, "still", "start", 500, { minClipMs: 40, room: unbounded })!, "v1", "still"))
.toMatchObject({ startMs: 500, durationMs: 5_500, sourceStartMs: 0 });
expect(at(trimClip(tracks, "still", "end", 30_000, { minClipMs: 40, room: unbounded })!, "v1", "still"))
.toMatchObject({ startMs: 4_000, durationMs: 26_000 });
});
it("stops at the neighbour on that side rather than growing over it", () => {
const tracks = stage();
// a ends at 4s, b starts at 6s: the tail can reach 6s and no further.
const next = trimClip(tracks, "a", "end", 9_000, { minClipMs: 40, room: { headMs: 0, tailMs: 20_000 } })!;
expect(clipEndMs(at(next, "v1", "a")!)).toBe(6_000);
expect(noOverlaps(next)).toBe(true);
// And the head cannot be pulled back over the clip in front of it: b opens
// up into the 1s gap and stops dead on a's tail.
const crowded = [track("v1", "video", [clip("a", 0, 4_000), clip("b", 5_000, 4_000)])];
const pulled = trimClip(crowded, "b", "start", 1_000, { minClipMs: 40, room: { headMs: 9_000, tailMs: 0 } })!;
expect(at(pulled, "v1", "b")).toMatchObject({ startMs: 4_000, durationMs: 5_000 });
expect(noOverlaps(pulled)).toBe(true);
});
it("keeps at least one frame, from either end", () => {
const tracks = [track("v1", "video", [clip("a", 0, 4_000)])];
expect(at(trimClip(tracks, "a", "end", 0, { minClipMs: 42, room })!, "v1", "a")!.durationMs).toBe(42);
const fromHead = at(trimClip(tracks, "a", "start", 9_999, { minClipMs: 42, room })!, "v1", "a")!;
expect(fromHead.durationMs).toBe(42);
expect(fromHead.startMs).toBe(4_000 - 42);
});
it("will not run the tail past the end of the footage", () => {
const tracks = [track("v1", "video", [clip("a", 0, 4_000, { sourceStartMs: 2_000 })])];
// 10s file, starting 2s in, 4s used: 4s of tail left.
const measured = sourceRoom(tracks[0].clips[0], 10_000);
expect(measured).toEqual({ headMs: 2_000, tailMs: 4_000 });
expect(at(trimClip(tracks, "a", "end", 30_000, { minClipMs: 40, room: measured })!, "v1", "a")!.durationMs).toBe(8_000);
});
it("reports no trim rather than an identical project, and refuses a locked track", () => {
const tracks = [track("v1", "video", [clip("a", 0, 4_000)])];
expect(trimClip(tracks, "a", "end", 4_000, { minClipMs: 40, room })).toBeNull();
expect(trimClip(tracks, "a", "start", 0, { minClipMs: 40, room })).toBeNull();
const locked = [track("v1", "video", [clip("a", 0, 4_000)], { locked: true })];
expect(trimClip(locked, "a", "end", 6_000, { minClipMs: 40, room })).toBeNull();
});
it("snaps a trimmed edge to the clips around it", () => {
const tracks = stage();
const snap = { targets: snapTargets(tracks, { excludeClipId: "a" }), toleranceMs: 300 };
const next = trimClip(tracks, "a", "end", 5_800, { minClipMs: 40, room: { headMs: 0, tailMs: 20_000 }, snap })!;
expect(clipEndMs(at(next, "v1", "a")!)).toBe(6_000);
});
});
describe("removing and inserting", () => {
it("takes a clip off its track and leaves the rest alone", () => {
const next = removeClip(stage(), "a")!;
expect(lane(next, "v1").clips.map((item) => item.id)).toEqual(["b"]);
expect(lane(next, "a1").clips).toHaveLength(1);
});
it("refuses to remove from a locked track", () => {
const locked = stage().map((item) => (item.id === "v1" ? { ...item, locked: true } : item));
expect(removeClip(locked, "a")).toBeNull();
expect(removeClip(stage(), "not-a-clip")).toBeNull();
});
it("drops a new clip into the first place it fits", () => {
const fresh = clip("new", 0, 3_000);
const next = insertClip(stage(), "v1", fresh, 3_000)!;
// 3s over the top of a (0–4s): it butts up after it instead of covering it.
expect(at(next, "v1", "new")!.startMs).toBe(8_000);
expect(noOverlaps(next)).toBe(true);
expect(insertClip(stage().map((item) => (item.id === "v1" ? { ...item, locked: true } : item)), "v1", fresh, 0)).toBeNull();
});
});
describe("what comes out still parses as a project", () => {
it("survives the schema after a move, a trim and a delete", () => {
const base = parseProjectConfig({
schemaVersion: 1,
id: "11111111-1111-4111-8111-111111111111",
name: "Edits", createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z",
thumbnail: null,
settings: { aspectRatio: "16:9", resolution: "1080p", frameRate: 24, backgroundColor: "#10131a" },
brief: { prompt: "A film", status: "draft", targetDurationSeconds: 30, aspectRatio: "16:9", resolution: "1080p" },
assets: [], references: [], generationJobs: [],
timeline: { tracks: stage() },
exports: [],
});
const moved = moveClip(base.timeline.tracks, "a", "v2", 1_234)!;
const trimmed = trimClip(moved, "b", "start", 6_500, { minClipMs: 42, room: { headMs: 5_000, tailMs: 5_000 } })!;
const deleted = removeClip(trimmed, "music")!;
expect(parseProjectConfig({ ...base, timeline: { tracks: deleted } })).toBeTruthy();
expect(noOverlaps(deleted)).toBe(true);
});
});
describe("timecode at the project frame rate", () => {
it("prints HH:MM:SS:FF", () => {
expect(formatTimecode(4_900, 24)).toBe("00:00:04:21");
expect(formatTimecode(0, 30)).toBe("00:00:00:00");
expect(formatTimecode((1000 / 30) * 3, 30)).toBe("00:00:00:03");
expect(formatTimecode(3_723_500, 25)).toBe("01:02:03:12");
expect(formatTimecode(59_999, 60)).toBe("00:00:59:59");
});
it("reads back what it prints, and the shorter forms people type", () => {
expect(parseTimecode("00:00:04:21", 24)).toBe(4_875);
expect(formatTimecode(parseTimecode("00:00:04:21", 24)!, 24)).toBe("00:00:04:21");
expect(parseTimecode("01:30", 30)).toBe(90_000);
expect(parseTimecode("12.5", 30)).toBe(12_500);
expect(parseTimecode("00:02:15", 30)).toBe(2_500);
expect(parseTimecode("00:00:01:30", 30)).toBeNull();
expect(parseTimecode("soon", 30)).toBeNull();
});
});
describe("cuts", () => {
it("steps to the previous and next edit point on any track", () => {
const tracks = stage();
expect(cutPoints(tracks)).toEqual([0, 4_000, 6_000, 8_000, 10_000]);
expect(adjacentCut(tracks, 4_000, 1)).toBe(6_000);
expect(adjacentCut(tracks, 4_000, -1)).toBe(0);
expect(adjacentCut(tracks, 10_000, 1)).toBeNull();
expect(adjacentCut(tracks, 0, -1)).toBeNull();
});
});
describe("ruler density", () => {
it("labels frames when zoomed in and minutes when zoomed out", () => {
expect(rulerScale(2_400, 24)).toMatchObject({ frames: true, majorMs: 1000 / 24 });
expect(rulerScale(100, 30)).toMatchObject({ frames: false, majorMs: 1_000 });
expect(rulerScale(10, 30).majorMs).toBe(10_000);
expect(rulerScale(0.5, 30).majorMs).toBeGreaterThanOrEqual(120_000);
expect(rulerLabel(65_000, 30, false)).toBe("01:05");
expect(rulerLabel(3_725_000, 30, false)).toBe("1:02:05");
expect(rulerLabel(1_500, 30, true)).toBe("00:00:01:15");
});
it("keeps the moment under the pointer in place when zooming", () => {
// 100px/s, scrolled 500px, pointer 200px in: 7s is under the pointer, and
// at 200px/s that moment sits at 1400px, so the scroll becomes 1200.
expect(scrollAfterZoom(500, 200, 100, 200)).toBe(1_200);
expect(scrollAfterZoom(0, 50, 100, 50)).toBe(0);
});
});
describe("pasting a clip", () => {
it("lands a copy with a new id where the lane has room", () => {
const tracks = stage();
const next = pasteClip(tracks, tracks[0].clips[0], "v2", 1_000, "copy")!;
expect(next[1].clips).toMatchObject([{ id: "copy", trackId: "v2", startMs: 1_000, durationMs: 4_000 }]);
expect(pasteClip(tracks, tracks[0].clips[0], "v1", 1_000, "copy")![0].clips.map((item) => item.startMs)).toEqual([0, 6_000, 8_000]);
});
});