Skip to content

Open source CapCut alternative.

TypeScript

feat(site): add a timeline magnet [rebuild]

David Lea3c1c0ec1da4
diff --git a/site/src/clients/chatgpt/server/guidance.ts b/site/src/clients/chatgpt/server/guidance.ts
index 33487def..18f5b2b7 100644
--- a/site/src/clients/chatgpt/server/guidance.ts
+++ b/site/src/clients/chatgpt/server/guidance.ts
@@ -36,7 +36,7 @@ The card offers the timeline, preview and inspector. ChatGPT provides the conver
"timeline-editing": `# Timeline editing
Inspect the project before editing. Every track uses start times and allows gaps. add_clip places a project asset; add_overlay_video places footage on an upper track. add_clip with blocks lays out placeholders for footage the user will supply, and replace_item fills them while retaining the edit's timing.
trim_clip uses source seconds. split_at and place_clip use timeline seconds. For uniform forward playback, timeline time = clip.start + (source time - clip.in) / clip.speed. For reverse playback use clip.out - source time. For speed curves use the reported len and returned timing data.
-delete_item removes the item and its group, leaving a gap. remove_gap closes a gap on one row. place_clip places by time; move_clip reorders by index. Growth pushes overlapping neighbors on the same row; shrinking leaves a gap. Read returned ids and timing after each mutation.
+delete_item removes the item and its group, leaving a gap. remove_gap closes a gap on one row; with the magnet on (set_magnet), track 0 closes up on every edit. place_clip places by time; move_clip reorders by index. Growth pushes overlapping neighbors on the same row; shrinking leaves a gap. Read returned ids and timing after each mutation.
set_speed changes uniform speed or reverse playback; set_speed_curve adds a rate curve. detach_audio separates a clip's sound for independent editing. freeze_frame creates a still. set_framing adjusts fit, fill, zoom and pan; set_clip_keyframes animates a clip's transform.
Use select_items to find items from their recorded state and apply batch-capable tools with ids. Measure or watch first when the selection depends on media content. set_clip_hidden and track visibility tools preserve items while excluding them from playback and export.
Transitions sit at cuts and retain their positions as edits move footage. Inspect parkedTransitions after mutations and remove unused transitions. Read transitions-and-fades, color-grading or graphics for styling. Verify the changed span with capture_frame and listen_audio, and use undo or redo for the shared editor history.`,
diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.ts
index ff7b9f22..bb94b29c 100644
--- a/site/src/cut/components/Timeline.tools.ts
+++ b/site/src/cut/components/Timeline.tools.ts
@@ -250,6 +250,12 @@ export const TIMELINE_TOOLS = [
track: num("Video track the gap is on (default 0)"),
}, ["at"]),
},
+ {
+ name: "set_magnet",
+ description:
+ "Turn the project's magnet on or off. On, track 0 stays closed up: deleting, trimming or moving a clip there pulls everything after it left, and the clips on other tracks, the elements, captions and soundtrack move with the track-0 footage under their start, keeping their lengths (one over a closed gap lands on the join). Nothing can land below track 0 while it is on. Off, track 0 keeps its gaps, which play the background. Turning it on closes every gap at once. It is the user's setting: call it when they ask for the magnet, ripple editing, or a track 0 that never has gaps; remove_gap closes one gap. editor_state project.magnet reports it.",
+ inputSchema: obj({ on: bool("true turns the magnet on, false turns it off") }, ["on"]),
+ },
{
name: "add_overlay_video",
description:
diff --git a/site/src/cut/components/Timeline.tsx b/site/src/cut/components/Timeline.tsx
index eedeadc1..78b47b7e 100644
--- a/site/src/cut/components/Timeline.tsx
+++ b/site/src/cut/components/Timeline.tsx
@@ -3,13 +3,14 @@ import { TimelineActionButton } from "@/cut/components/TimelineActionButton";
import { TimelineGroupActions } from "@/cut/components/TimelineGroupActions";
import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, type ReactNode } from "react";
-import { ArrowDownToLine, AudioLines, Check, Clapperboard, Copy, Diamond, Download, EllipsisVertical, Eye, EyeOff, FolderOpen, FolderPlus, Fullscreen, Loader2, MoreHorizontal, PanelBottomClose, Pause, Play, Scissors, SkipBack, Sticker, Trash2, Type, Volume2, VolumeX } from "lucide-react";
+import { ArrowDownToLine, AudioLines, Check, Clapperboard, Copy, Diamond, Download, EllipsisVertical, Eye, EyeOff, FolderOpen, FolderPlus, Fullscreen, Loader2, Magnet, MoreHorizontal, PanelBottomClose, Pause, Play, Scissors, SkipBack, Sticker, Trash2, Type, Volume2, VolumeX } from "lucide-react";
import { EFFECT_CHIP_ICONS, effectIconKind, SHAPE_CHIP_ICONS, TRANSITION_ICONS } from "@/cut/components/entityIcons";
import { Button } from "@/components/ui/button";
import { GuidesMenu } from "@/cut/components/GuidesMenu";
import { EmptyTimelineNote, TimelinePicker } from "@/cut/components/TimelinePicker";
import {
DropdownMenu,
+ DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuSeparator,
@@ -826,7 +827,8 @@ export function Timeline() {
if (st.clips.length === 0) return TRACK_ZERO;
const rows = videoRows();
if (!rows.length) return TRACK_ZERO;
- const row = resolveRow(rows, clientY, heldRow.current, { top: true, bottom: true });
+ // With the magnet on, nothing opens below track 0.
+ const row = resolveRow(rows, clientY, heldRow.current, { top: true, bottom: !st.magnet });
heldRow.current = row;
if (row < 0)
return { kind: "insert", level: Math.max(0, ...overlayLayers(st.clips).map((c) => c.track)) + 1 };
@@ -3389,12 +3391,22 @@ function TimelineTools({
}) {
const splitEnabled = useSplitEnabled();
const readOnly = useEditor((s) => s.readOnly);
+ const magnet = useEditor((s) => s.magnet);
+ const toggleMagnet = useEditor((s) => s.toggleMagnet);
if (readOnly) return null;
return (
<>
<TimelineActionButton label="Text" tooltip="Text (T)" onClick={addText}><Type /></TimelineActionButton>
<SaveSelectionButton />
- {(splitEnabled || selectionCount > 0) && <div role="separator" aria-orientation="vertical" className="mx-1 h-4 w-px shrink-0 bg-border" />}
+ <div role="separator" aria-orientation="vertical" className="mx-1 h-4 w-px shrink-0 bg-border" />
+ <TimelineActionButton
+ label="Magnet"
+ tooltip={magnet ? "Magnet on: track 0 closes up" : "Magnet: close up track 0"}
+ pressed={magnet}
+ onClick={toggleMagnet}
+ >
+ <Magnet />
+ </TimelineActionButton>
{splitEnabled && (
<TimelineActionButton label="Split" tooltip="Split at pointer, or at playhead (⌘B or S)" onClick={split}><Scissors /></TimelineActionButton>
)}
@@ -3431,6 +3443,8 @@ function TimelineToolsMenu({
const splitEnabled = useSplitEnabled();
const save = useSaveSelection();
const readOnly = useEditor((s) => s.readOnly);
+ const magnet = useEditor((s) => s.magnet);
+ const toggleMagnet = useEditor((s) => s.toggleMagnet);
// Held open, because the zoom row is not a pick: dragging the slider has to
// leave the menu standing, while Fit beside it closes as any command would.
const [open, setOpen] = useState(false);
@@ -3451,7 +3465,12 @@ function TimelineToolsMenu({
{save.state === "done" ? "Saved" : "Save template"}
</DropdownMenuItem>
)}
- {(splitEnabled || (!readOnly && selectionCount > 0)) && <DropdownMenuSeparator />}
+ {!readOnly && <DropdownMenuSeparator />}
+ {!readOnly && (
+ <DropdownMenuCheckboxItem checked={magnet} onCheckedChange={toggleMagnet}>
+ <Magnet /> Magnet
+ </DropdownMenuCheckboxItem>
+ )}
{splitEnabled && <DropdownMenuItem onClick={split}><Scissors /> Split</DropdownMenuItem>}
{!readOnly && selectionCount > 0 && (
<DropdownMenuItem onClick={deleteSelection}>
diff --git a/site/src/cut/components/TimelineActionButton.tsx b/site/src/cut/components/TimelineActionButton.tsx
index 5ae87a54..155e06ef 100644
--- a/site/src/cut/components/TimelineActionButton.tsx
+++ b/site/src/cut/components/TimelineActionButton.tsx
@@ -2,6 +2,7 @@
import type { ReactNode } from "react";
import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
type Props = {
@@ -9,14 +10,28 @@ type Props = {
tooltip: string;
onClick: () => void;
disabled?: boolean;
+ /** A switch's state: set, the button reads as pressed. */
+ pressed?: boolean;
children: ReactNode;
};
-export function TimelineActionButton({ label, tooltip, onClick, disabled, children }: Props) {
+export function TimelineActionButton({ label, tooltip, onClick, disabled, pressed, children }: Props) {
return (
<TooltipProvider>
<Tooltip>
- <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label={label} disabled={disabled} onClick={onClick} />}>
+ <TooltipTrigger
+ render={
+ <Button
+ variant="ghost"
+ size="icon-sm"
+ aria-label={label}
+ aria-pressed={pressed}
+ disabled={disabled}
+ onClick={onClick}
+ className={cn(pressed && "bg-[#0a84ff]/12 text-[#0a84ff] hover:bg-[#0a84ff]/20 hover:text-[#0a84ff] dark:hover:bg-[#0a84ff]/20")}
+ />
+ }
+ >
{children}
</TooltipTrigger>
<TooltipContent>{tooltip}</TooltipContent>
diff --git a/site/src/cut/lib/aiContext.ts b/site/src/cut/lib/aiContext.ts
index 340c684c..d57531dc 100644
--- a/site/src/cut/lib/aiContext.ts
+++ b/site/src/cut/lib/aiContext.ts
@@ -403,6 +403,7 @@ export function describeDoc(doc: ProjectDoc, opts?: { fullCues?: boolean; chatId
aspect,
background: state.background,
colorSpace: state.colorSpace,
+ magnet: doc.magnet === true,
guides: sanitizeGuides(doc.guides),
guideLines: sanitizeGuideLines(doc.guideLines),
genvideo: doc.genvideo ?? undefined,
@@ -432,6 +433,7 @@ interface DescribedState {
aspect: Aspect;
background: string;
colorSpace: OutputSpace;
+ magnet: boolean;
guides: GuideId[];
guideLines: GuideLines;
genvideo?: VideoProject | null;
@@ -523,6 +525,8 @@ function describeState(
// The delivery's color space (set_project_color): sdr, or hlg / pq
// for an HDR export and an HDR preview where the display carries it.
colorSpace: s.colorSpace,
+ // The magnet (set_magnet): on, track 0 stays closed up.
+ magnet: s.magnet,
// Every guide preset's safe area for this frame, whether or not it
// shows, so placement can respect a platform's UI without a guide on:
// safeArea and keepOut are frame fractions (x, y, w, h).
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index 172e2b40..ccccdb8a 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -3629,6 +3629,16 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
return { closed: { track, ...gap }, ...tracksAfter() };
},
+ set_magnet: (s, input) => {
+ if (typeof input.on !== "boolean") {
+ throw new ToolError("on (true or false) is required.");
+ }
+ if (s.magnet !== input.on) {
+ s.toggleMagnet();
+ }
+ return { magnet: useEditor.getState().magnet, ...tracksAfter() };
+ },
+
add_title: (_s, input) => placeEach(input, "titles", checkTitle, placeTitle),
add_text_sequence: (s, input) => {
diff --git a/site/src/cut/lib/backend/browser/router.ts b/site/src/cut/lib/backend/browser/router.ts
index a66f363a..e15d0738 100644
--- a/site/src/cut/lib/backend/browser/router.ts
+++ b/site/src/cut/lib/backend/browser/router.ts
@@ -8,6 +8,7 @@
// shelf (./library.ts). Everything else is the driver's cloud proxy.
import { resolveParent, settleParents, subtreeOf } from "../../folderTree";
import { sanitizeGuideLines, sanitizeGuides } from "../../guides";
+import { OUTPUT_SPACES } from "@donkeycut/effects-kit";
import { isTimelineId, normalizeAspect, sanitizeTimelines, type ProjectDoc, type ProjectFolder } from "../../types";
import {
getBrowserExportJob,
@@ -100,6 +101,8 @@ async function putProject(req: Request, id: string): Promise<Response> {
guides: Array.isArray(body.guides) ? sanitizeGuides(body.guides) : existing.guides,
guideLines: body.guideLines !== undefined ? sanitizeGuideLines(body.guideLines) : existing.guideLines,
background: typeof body.background === "string" ? body.background : existing.background,
+ colorSpace: OUTPUT_SPACES.some((o) => o.id === body.colorSpace) ? body.colorSpace : existing.colorSpace,
+ magnet: typeof body.magnet === "boolean" ? body.magnet : existing.magnet,
subtitles:
body.subtitles && typeof body.subtitles === "object" ? body.subtitles : existing.subtitles,
ui: body.ui && typeof body.ui === "object" ? { ...existing.ui, ...body.ui } : existing.ui,
diff --git a/site/src/cut/lib/drag.ts b/site/src/cut/lib/drag.ts
index 98a4cfcf..5f4db3f6 100644
--- a/site/src/cut/lib/drag.ts
+++ b/site/src/cut/lib/drag.ts
@@ -119,9 +119,14 @@ export function startDrag(e: React.PointerEvent, opts: DragOpts) {
frame = 0;
flush();
pin?.remove();
- activeDrags--;
- dragListeners.forEach((fn) => fn());
- opts.onUp?.(ev.clientX - startX, ev.clientY - startY, moved);
+ // The drag ends after its release lands, so a listener settling on the
+ // drag's end (the store's magnet) sees the gesture's last write.
+ try {
+ opts.onUp?.(ev.clientX - startX, ev.clientY - startY, moved);
+ } finally {
+ activeDrags--;
+ dragListeners.forEach((fn) => fn());
+ }
};
window.addEventListener("pointermove", move);
window.addEventListener("pointerup", up);
diff --git a/site/src/cut/lib/laneTracks.ts b/site/src/cut/lib/laneTracks.ts
index aefeb21c..e7ce8671 100644
--- a/site/src/cut/lib/laneTracks.ts
+++ b/site/src/cut/lib/laneTracks.ts
@@ -683,7 +683,7 @@ function startGroupMove(
: [];
const edges = {
top: otherRows.some((r) => r < Math.max(...rowsHeld)),
- bottom: otherRows.some((r) => r > Math.min(...rowsHeld)),
+ bottom: otherRows.some((r) => r > Math.min(...rowsHeld)) && !(grabbed.kind === "video" && s.magnet),
};
const rowLo = vertical && edges.top ? -1 - homeRow : 0;
const rowHi = vertical && edges.bottom ? usedLanes.length - homeRow : 0;
@@ -940,11 +940,12 @@ export function startLaneMove(e: React.PointerEvent, kind: LaneKind, id: string,
// The edges this drag can open a new row past. From an outermost row an
// item alone there has nothing to open on its side: the row it left
// collapses behind it, so the fresh one renumbers straight back to the
- // picture already on screen. Single-lane kinds stay on their row.
+ // picture already on screen. Single-lane kinds stay on their row. With the
+ // magnet on, the video band opens nothing below track 0, its bottom row.
const alone = !rest.some((x) => x.view.lane === self.lane);
const edges = {
top: !(alone && ui.homeRow === 0),
- bottom: !(alone && ui.homeRow === usedLanes.length - 1),
+ bottom: !(alone && ui.homeRow === usedLanes.length - 1) && !(kind === "video" && s.magnet),
};
const targets = snapTargets(s, kind, id);
const tol = SNAP_PX / ui.pps;
diff --git a/site/src/cut/lib/magnet.test.ts b/site/src/cut/lib/magnet.test.ts
new file mode 100644
index 00000000..08fce898
--- /dev/null
+++ b/site/src/cut/lib/magnet.test.ts
@@ -0,0 +1,180 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type React from "react";
+import { closeTrack0, serializeDoc, useEditor } from "./store";
+import { runAiTool } from "./aiTools";
+import { startDrag } from "./drag";
+import { emptySubtitles } from "./types";
+import type { AudioClip, SubtitleCue, TextOverlay, VideoClip } from "./types";
+
+// The magnet keeps track 0 closed up, and everything timed against it rides
+// the footage under its start: same length, never stretched, never stacked.
+
+const vclip = (id: string, track: number, start: number, len: number): VideoClip => ({
+ id,
+ assetId: "x",
+ track,
+ start,
+ in: 0,
+ out: len,
+ muted: false,
+});
+const aclip = (id: string, start: number, len: number, lane = 0): AudioClip => ({ id, assetId: "x", start, in: 0, out: len, volume: 1, lane });
+const title = (id: string, start: number, end: number): TextOverlay => ({
+ id,
+ text: "T",
+ start,
+ end,
+ x: 0.5,
+ y: 0.5,
+ size: 88,
+ font: "sf",
+ weight: 700,
+ color: "#fff",
+ shadow: true,
+ plate: false,
+});
+const cue = (id: string, start: number, end: number): SubtitleCue => ({
+ id,
+ start,
+ end,
+ text: "hi",
+ words: [{ w: "hi", t0: start, t1: end }],
+});
+const doc = (o: Partial<Parameters<typeof closeTrack0>[0]>) => ({
+ clips: [],
+ transitions: [],
+ audioClips: [],
+ overlays: [],
+ cues: [],
+ ...o,
+});
+
+const s = () => useEditor.getState();
+const startOf = (id: string) => s().clips.find((c) => c.id === id)?.start;
+
+beforeEach(() => {
+ useEditor.setState({
+ clips: [],
+ transitions: [],
+ audioClips: [],
+ overlays: [],
+ assets: [],
+ subtitles: emptySubtitles(),
+ selection: null,
+ multiSelection: [],
+ magnet: false,
+ readOnly: false,
+ });
+});
+
+describe("closing up track 0", () => {
+ test("the gap shuts and every follower rides the footage under its start", () => {
+ // A 0–5, a 4s gap, C 9–15: C pulls back to 5.
+ const out = closeTrack0(
+ doc({
+ clips: [vclip("A", 0, 0, 5), vclip("C", 0, 9, 6), vclip("broll", 1, 2, 2), vclip("pip", 1, 10, 2)],
+ overlays: [title("over-c", 10, 12)],
+ audioClips: [aclip("music", 0, 20), aclip("in-gap", 7, 1, 1)],
+ cues: [cue("q", 11, 12)],
+ })
+ );
+ const at = (id: string) => out.clips.find((c) => c.id === id)!.start;
+ expect(at("C")).toBe(5);
+ expect(at("broll")).toBe(2);
+ expect(at("pip")).toBe(6);
+ expect(out.overlays[0]).toMatchObject({ start: 6, end: 8 });
+ expect(out.audioClips.map((a) => a.start)).toEqual([0, 5]);
+ expect(out.cues[0]).toMatchObject({ start: 7, end: 8, words: [{ w: "hi", t0: 7, t1: 8 }] });
+ });
+
+ test("a head gap closes to zero", () => {
+ const out = closeTrack0(doc({ clips: [vclip("A", 0, 3, 2)], overlays: [title("t", 1, 2)] }));
+ expect(out.clips[0].start).toBe(0);
+ expect(out.overlays[0]).toMatchObject({ start: 0, end: 1 });
+ });
+
+ test("a row the move crowds pushes its later item right", () => {
+ // over-a stays at 4–6; over-c lands on 5 and slides to 6.
+ const out = closeTrack0(
+ doc({
+ clips: [vclip("A", 0, 0, 5), vclip("C", 0, 9, 6)],
+ overlays: [title("over-a", 4, 6), title("over-c", 9, 10)],
+ })
+ );
+ expect(out.overlays.map((o) => [o.start, o.end])).toEqual([[4, 6], [6, 7]]);
+ });
+
+ test("a closed track 0 is the same document back", () => {
+ const d = doc({ clips: [vclip("A", 0, 0, 5), vclip("B", 0, 5, 2)] });
+ expect(closeTrack0(d)).toBe(d);
+ });
+});
+
+describe("the magnet in the editor", () => {
+ test("turning it on closes every gap, and one undo brings them back off", () => {
+ useEditor.setState({ clips: [vclip("A", 0, 0, 5), vclip("C", 0, 9, 6)] });
+ s().toggleMagnet();
+ expect(s().magnet).toBe(true);
+ expect(startOf("C")).toBe(5);
+ s().undo();
+ expect(s().magnet).toBe(false);
+ expect(startOf("C")).toBe(9);
+ });
+
+ test("deleting a track-0 clip pulls the rest left", () => {
+ useEditor.setState({ clips: [vclip("A", 0, 0, 5), vclip("B", 0, 5, 4), vclip("C", 0, 9, 6)], magnet: true });
+ s().select({ kind: "clip", id: "B" });
+ s().deleteSelection();
+ expect(startOf("C")).toBe(5);
+ });
+
+ test("off, track 0 keeps its gaps", () => {
+ useEditor.setState({ clips: [vclip("A", 0, 0, 5), vclip("C", 0, 9, 6)] });
+ expect(startOf("C")).toBe(9);
+ });
+
+ test("a drop aimed below track 0 inserts into it", () => {
+ useEditor.setState({
+ assets: [{ id: "x", fileName: "x.mp4", name: "x", type: "video", duration: 2, url: "" }],
+ clips: [vclip("A", 0, 0, 5)],
+ magnet: true,
+ });
+ s().addVideoFromAsset("x", { kind: "insert", level: 0 }, 1);
+ expect(s().clips.every((c) => c.track === 0)).toBe(true);
+ expect(startOf("A")).toBe(2);
+ });
+
+ test("a drag holds the close-up until release", () => {
+ const saved = new Map(["window", "document", "requestAnimationFrame", "cancelAnimationFrame"].map((key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)]));
+ try {
+ const events = new EventTarget();
+ Object.defineProperty(globalThis, "window", { configurable: true, value: events });
+ Object.defineProperty(globalThis, "document", { configurable: true, value: { activeElement: null } });
+ Object.defineProperty(globalThis, "requestAnimationFrame", { configurable: true, value: (cb: () => void) => (cb(), 0) });
+ Object.defineProperty(globalThis, "cancelAnimationFrame", { configurable: true, value: () => {} });
+ useEditor.setState({ clips: [vclip("A", 0, 0, 5), vclip("C", 0, 5, 6)], magnet: true });
+
+ // The gesture parts C away from A; the slot stays open under the pointer.
+ const down = { button: 0, clientX: 0, clientY: 0, currentTarget: {}, preventDefault() {}, stopPropagation() {} } as unknown as React.PointerEvent;
+ startDrag(down, { onMove: () => s().updateClipTransient("C", { start: 8 }) });
+ events.dispatchEvent(Object.assign(new Event("pointermove"), { clientX: 30, clientY: 0 }));
+ const held = startOf("C");
+ events.dispatchEvent(Object.assign(new Event("pointerup"), { clientX: 30, clientY: 0 }));
+ expect(held).toBe(8);
+ expect(startOf("C")).toBe(5);
+ } finally {
+ for (const [key, descriptor] of saved) {
+ if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+ else Reflect.deleteProperty(globalThis, key);
+ }
+ }
+ });
+
+ test("chat turns it on and editor_state carries it", async () => {
+ useEditor.setState({ clips: [vclip("A", 0, 0, 5), vclip("C", 0, 9, 6)] });
+ await runAiTool("set_magnet", { on: true });
+ expect(s().magnet).toBe(true);
+ expect(startOf("C")).toBe(5);
+ expect(serializeDoc(s()).magnet).toBe(true);
+ });
+});
diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.ts
index 77425d99..9b1864f0 100644
--- a/site/src/cut/lib/store.ts
+++ b/site/src/cut/lib/store.ts
@@ -98,12 +98,13 @@ import { engineTranscribeSamples, withEngineStt } from "./localStt";
import { laneCues, subtitleLaneCount, trackLocale } from "./subtitles";
import { cueEmphasis, mergeEmphasis, remapEmphasis, splitEmphasis, toggleEmphasis, withEmphasis } from "./captionEmphasis";
import { clipboardItemAssetIds, clipboardItemFor, listedAssetIds, type TimelineClipboardItem } from "./itemKinds";
-import { ANIM_STYLE_IDS, animStyleOfTransition, assetIsSilent, CLIP_MIN_SECONDS, clipPoseAt, DEFAULT_BACKGROUND, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isAudioTransition, fontAssetId, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, projectBackground, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, isTimelineId, sanitizeTimelines, timelineAspect, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionBarAt, transitionBarStart, transitionStyleOfAnim, type TransitionBoundaryKind } from "./types";
+import { ANIM_STYLE_IDS, animStyleOfTransition, assetIsSilent, CLIP_MIN_SECONDS, clipPoseAt, DEFAULT_BACKGROUND, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isAudioTransition, fontAssetId, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, projectBackground, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, isTimelineId, laneOf, sanitizeTimelines, timelineAspect, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionBarAt, transitionBarStart, transitionStyleOfAnim, type TransitionBoundaryKind } from "./types";
import { clampBand, clampFeather, takesBand, takesFeather } from "./transitionShape";
import { liftMoveTracks } from "./textMotion";
import { OWN_SOUND, soundRoom, soundSourceOf, soundWindow, SPLIT_EDIT_MAX_S } from "./soundSource";
import { CUT_SOUND } from "./soundSettings";
import { readTextStyle } from "./textStyle";
+import { isDragActive, subscribeDragActive } from "./drag";
import { loadUiState, saveUiState, type ProjectUiState } from "./uiState";
import { captureTimelineFrames } from "./visualFrames";
@@ -403,6 +404,9 @@ interface DocSnapshot {
/** The delivery's color space, set from the export dialog, the Color
* panel and the chat. */
colorSpace: OutputSpace;
+ /** The magnet: turning it on closes track 0 up, so undo turns it back off
+ * with the gaps it closed. */
+ magnet: boolean;
/** Each asset's beat grid. Beats are edited on the timeline like anything
* else — dragged, added, removed, cleared — but they live on the asset
* rather than in the doc arrays, so the checkpoint carries them separately
@@ -489,6 +493,9 @@ export interface EditorState {
/** The delivery's color space: SDR, or HDR in HLG or PQ. The export writes
* it and the preview shows it on an HDR display. */
colorSpace: OutputSpace;
+ /** The magnet: track 0 stays closed up (`closeTrack0`) and nothing lands
+ * below it. Off, track 0 keeps its gaps. */
+ magnet: boolean;
selection: Selection;
/** Everything selected, including `selection` (the primary that drives the
* inspector). Bulk actions — delete, copy — act on this whole set. */
@@ -591,6 +598,8 @@ export interface EditorState {
setBackground: (hex: string) => void;
/** Set the delivery's color space, with undo. */
setColorSpace: (space: OutputSpace) => void;
+ /** Turn the magnet on or off, with undo. */
+ toggleMagnet: () => void;
addAsset: (asset: MediaAsset) => void;
updateAsset: (id: string, patch: Partial<MediaAsset>) => void;
/** Rename a project file under the rule every Library shelf applies. */
@@ -1105,6 +1114,7 @@ let stepUndone = false;
interface SharedFields {
guideLines: GuideLines;
colorSpace: OutputSpace;
+ magnet: boolean;
beats: Map<string, AssetBeats | undefined>;
profiles: Map<string, SourceProfile | undefined>;
sounds: Map<string, SoundFrom | undefined>;
@@ -1113,9 +1123,10 @@ interface SharedFields {
* brings its history back. Session only, cleared when a project opens. */
const parkedHistory = new Map<TimelineId, { history: DocSnapshot[]; future: DocSnapshot[]; shared: SharedFields }>();
-const sharedFields = (s: Pick<EditorState, "guideLines" | "colorSpace" | "assets">): SharedFields => ({
+const sharedFields = (s: Pick<EditorState, "guideLines" | "colorSpace" | "magnet" | "assets">): SharedFields => ({
guideLines: s.guideLines,
colorSpace: s.colorSpace,
+ magnet: s.magnet,
beats: new Map(s.assets.map((a) => [a.id, a.beats])),
profiles: new Map(s.assets.map((a) => [a.id, a.colorProfile])),
sounds: new Map(s.assets.map((a) => [a.id, a.soundFrom])),
@@ -1133,6 +1144,7 @@ function rebaseShared(snaps: DocSnapshot[], then: SharedFields, now: SharedField
for (const snap of snaps) {
if (now.guideLines !== then.guideLines) snap.guideLines = { v: [...now.guideLines.v], h: [...now.guideLines.h] };
if (now.colorSpace !== then.colorSpace) snap.colorSpace = now.colorSpace;
+ if (now.magnet !== then.magnet) snap.magnet = now.magnet;
if (beats.size) snap.beats = snap.beats.map((b) => (beats.has(b.id) ? { id: b.id, grid: now.beats.get(b.id) } : b));
if (profiles.size)
snap.sourceColor = snap.sourceColor.map((c) =>
@@ -1561,6 +1573,7 @@ export const DOC_KEYS = [
"guideLines",
"background",
"colorSpace",
+ "magnet",
"publish",
"notes",
"subtitles",
@@ -1575,6 +1588,41 @@ const proxyOn = (a: { id: string; proxy?: unknown }) => !!a.proxy && !proxyOffHe
/** A held proxy is going to be dropped or replaced: links mint it again. */
export const releaseProxyHold = (id: string) => void proxyOffHere.delete(id);
+/**
+ * The magnet's part of a write: with it on, a write that touches the clips —
+ * or turns the magnet on — leaves track 0 closed up. A live drag holds off
+ * until release (the drag-end settle below), so the slot a move parts open
+ * stays open under the pointer. A read-only view shows the doc as stored.
+ */
+function closeUpWrite(prev: EditorState, next: Partial<EditorState>): Partial<EditorState> {
+ const magnet = next.magnet ?? prev.magnet;
+ if (!magnet || prev.readOnly || isDragActive() || !(next.clips || next.magnet)) {
+ return next;
+ }
+
+ const clips = next.clips ?? prev.clips;
+ const subtitles = next.subtitles ?? prev.subtitles;
+ const closed = closeTrack0({
+ clips,
+ transitions: next.transitions ?? prev.transitions,
+ audioClips: next.audioClips ?? prev.audioClips,
+ overlays: next.overlays ?? prev.overlays,
+ cues: subtitles.cues,
+ });
+ if (closed.clips === clips) {
+ return next;
+ }
+
+ return {
+ ...next,
+ clips: closed.clips,
+ transitions: closed.transitions,
+ audioClips: closed.audioClips,
+ overlays: closed.overlays,
+ subtitles: { ...subtitles, cues: closed.cues },
+ };
+}
+
/**
* The invariants every write to the store passes through, wherever it comes
* from: a read-only project takes no doc changes, the track stack stays
@@ -1594,6 +1642,7 @@ function normalizeWrite(prev: EditorState, incoming: Partial<EditorState>): Part
for (const k of DOC_KEYS) delete (next as Record<string, unknown>)[k];
}
if (next.clips) next = { ...next, clips: closeMicroGaps(groundTracks(next.clips)) };
+ next = closeUpWrite(prev, next);
if (next.clips || next.transitions) {
const clips = next.clips ?? prev.clips;
const derived = deriveTransitionFields(clips, next.transitions ?? prev.transitions);
@@ -1771,13 +1820,14 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
api.setState = set as typeof api.setState;
const snapshot = (): DocSnapshot => {
- const { clips, transitions, audioClips, overlays, subtitles, assets, guideLines, colorSpace } = get();
+ const { clips, transitions, audioClips, overlays, subtitles, assets, guideLines, colorSpace, magnet } = get();
return {
beats: assets.map((a) => ({ id: a.id, grid: a.beats })),
sourceColor: assets.map((a) => ({ id: a.id, profile: a.colorProfile })),
soundFrom: assets.map((a) => ({ id: a.id, from: a.soundFrom })),
guideLines: { v: [...guideLines.v], h: [...guideLines.h] },
colorSpace,
+ magnet,
// Render-owned clips are excluded — history captures the user's timeline,
// not the background run's placements (restoreDoc re-attaches the live ones).
clips: clips.filter((c) => !genClipIds.has(c.id)).map((c) => ({ ...c })),
@@ -2034,6 +2084,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
guideLines: EMPTY_GUIDE_LINES,
background: DEFAULT_BACKGROUND,
colorSpace: "sdr",
+ magnet: false,
selection: null,
multiSelection: [],
playing: false,
@@ -2089,6 +2140,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
guideLines: EMPTY_GUIDE_LINES,
background: DEFAULT_BACKGROUND,
colorSpace: "sdr",
+ magnet: false,
selection: null,
multiSelection: [],
selectedKey: null,
@@ -2427,6 +2479,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
guideLines: sanitizeGuideLines(doc.guideLines),
background: state.background,
colorSpace: state.colorSpace,
+ magnet: doc.magnet === true,
// View state lives in IndexedDB; doc.ui covers projects saved
// before the move.
pxPerSec: clampPps(ui.pxPerSec ?? doc.ui?.pxPerSec ?? 60),
@@ -2801,6 +2854,13 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
push();
set({ colorSpace: space });
},
+ toggleMagnet: () => {
+ if (get().readOnly) {
+ return;
+ }
+ push();
+ set({ magnet: !get().magnet });
+ },
addAsset: (asset) =>
set((s) => {
@@ -3995,9 +4055,13 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {
set({ ...next, clips: [...next.clips].sort((a, b) => a.start - b.start), subtitles: { ...s.subtitles, cues: next.subtitles.cues } });
},
- addVideoFromAsset: (assetId, place, start) => {
+ addVideoFromAsset: (assetId, aimed, start) => {
const asset = get().assets.find((a) => a.id === assetId);
if (!asset || (asset.type !== "video" && asset.type !== "image")) return;
+ // With the magnet on, nothing opens a row below track 0: a drop aimed
+ // under the stack inserts into track 0 at the pointer.
+ const place: VideoTrackPlacement =
+ get().magnet && aimed.kind === "insert" && aimed.level === 0 ? { kind: "track", track: 0 } : aimed;
const out = asset.type === "image" ? IMAGE_CLIP_SECONDS : asset.duration;
push();
const { track, start: at, shifts } = landOnPlacement(
@@ -5543,11 +5607,38 @@ useEditor.subscribe((s, prev) => {
s.subtitles !== prev.subtitles ||
s.guideLines !== prev.guideLines ||
s.colorSpace !== prev.colorSpace ||
+ s.magnet !== prev.magnet ||
(s.assets !== prev.assets && beatsEdited(prev.assets, s.assets))
)
docSeq++;
});
+// A drag's release settles the magnet: the gesture's writes held off while it
+// ran, and the last of them may write no clips at all (a move that parted its
+// neighbours and landed where it began), so the close-up runs here once.
+subscribeDragActive(() => {
+ if (isDragActive()) {
+ return;
+ }
+
+ const s = useEditor.getState();
+ if (!s.magnet || s.readOnly) {
+ return;
+ }
+
+ const closed = closeTrack0({ ...s, cues: s.subtitles.cues });
+ if (closed.clips === s.clips) {
+ return;
+ }
+ useEditor.setState({
+ clips: closed.clips,
+ transitions: closed.transitions,
+ audioClips: closed.audioClips,
+ overlays: closed.overlays,
+ subtitles: { ...s.subtitles, cues: closed.cues },
+ });
+});
+
/** Resolves once the cut is not playing. */
function untilStopped(): Promise<void> {
if (!useEditor.getState().playing) return Promise.resolve();
@@ -5710,6 +5801,7 @@ export function serializeDoc(s: {
guideLines: GuideLines;
background: string;
colorSpace: OutputSpace;
+ magnet: boolean;
publish: { caption: string; tags: string; soundTitle: string; handle: string };
notes: { text: string; publishedAt: string; links: string[] };
subtitles: SubtitlesBlock;
@@ -5737,6 +5829,7 @@ export function serializeDoc(s: {
guideLines: s.guideLines,
background: s.background,
colorSpace: s.colorSpace,
+ magnet: s.magnet,
subtitles: s.subtitles,
publish: { ...s.publish },
notes: { ...s.notes, links: [...s.notes.links] },
@@ -5778,6 +5871,7 @@ const DOC_FIELD_EDITED: {
guideLines: (s, last) => s.guideLines !== last.guideLines,
background: (s, last) => s.background !== last.background,
colorSpace: (s, last) => s.colorSpace !== last.colorSpace,
+ magnet: (s, last) => s.magnet !== (last.magnet === true),
publish: (s, last) =>
s.publish.caption !== last.publish?.caption ||
s.publish.tags !== last.publish?.tags ||
@@ -6209,6 +6303,125 @@ export function separateOverlaps<
};
}
+/** Push every item on a row right of the one before it, so a row the
+ * magnet pulled left never intersects itself. `lane` names the row. */
+function unstack<T extends { start: number }>(
+ items: T[],
+ lane: (x: T) => number,
+ len: (x: T) => number,
+ moveTo: (x: T, start: number) => T
+): T[] {
+ const ends = new Map<number, number>();
+ const placed = new Map<T, T>();
+ for (const x of [...items].sort((a, b) => a.start - b.start)) {
+ const end = ends.get(lane(x)) ?? -Infinity;
+ const y = x.start < end - 1e-6 ? moveTo(x, end) : x;
+ placed.set(x, y);
+ ends.set(lane(x), y.start + len(y));
+ }
+ return items.map((x) => placed.get(x)!);
+}
+
+/**
+ * The magnet's close-up: every gap on track 0 — at the head or between two
+ * clips — shuts, and everything timed against the picture comes along. A clip
+ * on another track, an element, a caption or a soundtrack clip moves by
+ * whatever the track-0 footage under its start moved and keeps its length;
+ * one over a gap lands on the join. Nothing is stretched. A row the move
+ * crowds pushes its later items right, so no row intersects, and transition
+ * bars re-anchor to the cuts they sat on. The same document back when track
+ * 0 has no gap.
+ *
+ * before t1 [broll] [pip]
+ * t0 [A 0–5 ] [C 9–15 ]
+ * after t1 [broll] [pip]
+ * t0 [A 0–5 ][C 5–11 ]
+ */
+export function closeTrack0<
+ T extends {
+ clips: VideoClip[];
+ transitions: TimelineTransition[];
+ audioClips: AudioClip[];
+ overlays: Overlay[];
+ cues: SubtitleCue[];
+ },
+>(doc: T): T {
+ const row = track0Clips(doc.clips).sort((a, b) => a.start - b.start);
+
+ // Each track-0 clip's packed start: one after another from 0.
+ let cursor = 0;
+ const steps = row.map((c) => {
+ const step = { from: c.start, to: cursor, len: clipLen(c) };
+ cursor += step.len;
+ return step;
+ });
+ if (steps.every((st) => Math.abs(st.from - st.to) <= 1e-6)) {
+ return doc;
+ }
+
+ // Where a time on the old timeline lands: inside a clip it rides that clip,
+ // inside a gap it lands on the join, past the end it rides the last clip.
+ const at = (t: number) => {
+ for (const st of steps) {
+ if (t < st.from) {
+ return st.to;
+ }
+ if (t < st.from + st.len) {
+ return st.to + (t - st.from);
+ }
+ }
+ const last = steps[steps.length - 1];
+ return last.to + last.len + (t - (last.from + last.len));
+ };
+
+ const packed = new Map(row.map((c, i) => [c.id, steps[i].to]));
+ const clips = unstack(
+ doc.clips.map((c) => ({ ...c, start: packed.get(c.id) ?? at(c.start) })),
+ (c) => (c.track === 0 ? -1 : c.track),
+ clipLen,
+ (c, start) => ({ ...c, start })
+ ).sort((a, b) => a.start - b.start);
+
+ const overlays = unstack(
+ doc.overlays.map((o) => {
+ const d = at(o.start) - o.start;
+ return { ...o, start: o.start + d, end: o.end + d };
+ }),
+ laneOf,
+ (o) => o.end - o.start,
+ (o, start) => ({ ...o, start, end: start + (o.end - o.start) })
+ );
+
+ const audioClips = unstack(
+ doc.audioClips.map((a) => ({ ...a, start: at(a.start) })),
+ laneOf,
+ clipLen,
+ (a, start) => ({ ...a, start })
+ );
+
+ const shiftCue = (c: SubtitleCue, d: number): SubtitleCue => ({
+ ...c,
+ start: c.start + d,
+ end: c.end + d,
+ words: c.words?.map((w) => ({ ...w, t0: w.t0 + d, t1: w.t1 + d })),
+ });
+ const cues = unstack(
+ doc.cues.map((c) => shiftCue(c, at(c.start) - c.start)),
+ laneOf,
+ (c) => c.end - c.start,
+ (c, start) => shiftCue(c, start - c.start)
+ );
+
+ return {
+ ...doc,
+ clips,
+ transitions: reanchorTransitions(doc.clips, clips, doc.transitions),
+ audioClips,
+ overlays,
+ cues,
+ };
+}
+
/**
* Spans for one track, cached until the document moves.
*
diff --git a/site/src/cut/lib/types.ts b/site/src/cut/lib/types.ts
index 692ba3ad..d820f0bb 100644
--- a/site/src/cut/lib/types.ts
+++ b/site/src/cut/lib/types.ts
@@ -1865,6 +1865,9 @@ export interface ProjectDoc {
/** The delivery's color space — what the export writes and, on an HDR
* display, what the preview shows. Absent = SDR. */
colorSpace?: OutputSpace;
+ /** The magnet: track 0 stays closed up and nothing lands below it.
+ * Absent = off. */
+ magnet?: boolean;
/** Auto-generated (then hand-edited) subtitles. */
subtitles?: SubtitlesBlock;
/** Legacy per-project view metadata — view state now lives in IndexedDB;
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index fb680094..720b0371 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -252,7 +252,7 @@ Times are in seconds on the shared timeline. The playhead is currentTime; a skim
"timeline-editing": `# Timeline editing
- Every track is free-positioned: items carry a start time, gaps are allowed, and a track-0 gap plays black (and silence). videoTrack entries in editor_state report gapBefore where one exists.
-- A delete removes the selected item and its explicit group. Other items keep their timing. The footprint becomes a gap; remove_gap closes it on one row.
+- A delete removes the selected item and its explicit group. Other items keep their timing. The footprint becomes a gap; remove_gap closes it on one row. With the magnet on (project.magnet, set_magnet), track 0 never keeps a gap: it closes up on every edit and everything over it rides along.
- Two ways to move a track-0 clip: place_clip sets its start (respects gaps, slides right if the spot is taken); move_clip reorders by index, opening a slot at the landing point. Moved and displaced clips carry their group members with relative timing preserved; occupied rows can move a group farther right. Index-based inserts (freeze_frame, generated clips) also open a slot.
- add_clip puts a project asset on the timeline the way a drag does: video/image onto track 0 (a \`start\`, an \`index\` insert, or appended at the end), audio onto the soundtrack.
- Overlay video: a video/image asset can sit on a track above track 0 (track 1, 2… — topmost wins). A full-frame overlay covers everything below it; give it a layout to share the frame — top/bottom/left/right halves for a split screen, pip for a floating corner box, or a custom region rect. add_overlay_video creates one from a media asset; update_overlay_video moves/trims/regions/mutes/hides it. The user makes them by dragging media above track 0; they drag the region in the preview.
diff --git a/site/src/cut/server/cloud/projects.ts b/site/src/cut/server/cloud/projects.ts
index 6ce6e805..c25f45c4 100644
--- a/site/src/cut/server/cloud/projects.ts
+++ b/site/src/cut/server/cloud/projects.ts
@@ -4,6 +4,7 @@ import { sanitizeGuideLines, sanitizeGuides } from "@/cut/lib/guides";
import { resolveParent, subtreeOf } from "@/cut/lib/folderTree";
import { timelineEnd } from "@/cut/lib/timelineEnd";
import { DOC_SEQ_HEADER, DOC_WRITER_HEADER, HTTP_CONFLICT } from "@/cut/lib/backend/types";
+import { OUTPUT_SPACES } from "@donkeycut/effects-kit";
import { isTimelineId, normalizeAspect, sanitizeTimelines, type ProjectDoc, type ProjectFolder, type ProjectSummary } from "@/cut/lib/types";
import type { Prisma } from "@/generated/prisma/client";
import { prisma } from "@/lib/prisma";
@@ -116,6 +117,8 @@ function mergeDoc(existing: ProjectDoc, body: Partial<ProjectDoc>): ProjectDoc {
guides: Array.isArray(body.guides) ? sanitizeGuides(body.guides) : existing.guides,
guideLines: body.guideLines !== undefined ? sanitizeGuideLines(body.guideLines) : existing.guideLines,
background: typeof body.background === "string" ? body.background : existing.background,
+ colorSpace: OUTPUT_SPACES.some((o) => o.id === body.colorSpace) ? body.colorSpace : existing.colorSpace,
+ magnet: typeof body.magnet === "boolean" ? body.magnet : existing.magnet,
subtitles:
body.subtitles && typeof body.subtitles === "object" ? body.subtitles : existing.subtitles,
ui: body.ui && typeof body.ui === "object" ? { ...existing.ui, ...body.ui } : existing.ui,
diff --git a/site/src/cut/server/http/projects.ts b/site/src/cut/server/http/projects.ts
index 6f435281..b51619ff 100644
--- a/site/src/cut/server/http/projects.ts
+++ b/site/src/cut/server/http/projects.ts
@@ -1,6 +1,7 @@
import { sanitizeGuideLines, sanitizeGuides } from "@/cut/lib/guides";
import { execFile } from "node:child_process";
import { compatCoverIn, compatProxyNameFor } from "@/cut/lib/proxyNames";
+import { OUTPUT_SPACES } from "@donkeycut/effects-kit";
import { isTimelineId, normalizeAspect, sanitizeTimelines, type ProjectDoc } from "@/cut/lib/types";
import { detectSilence, extractAudio, makeFreezeFrame, probeDims, probeDuration } from "../frames";
import {
@@ -144,6 +145,8 @@ export const projectsApi = {
guides: Array.isArray(body.guides) ? sanitizeGuides(body.guides) : existing.guides,
guideLines: body.guideLines !== undefined ? sanitizeGuideLines(body.guideLines) : existing.guideLines,
background: typeof body.background === "string" ? body.background : existing.background,
+ colorSpace: OUTPUT_SPACES.some((o) => o.id === body.colorSpace) ? body.colorSpace : existing.colorSpace,
+ magnet: typeof body.magnet === "boolean" ? body.magnet : existing.magnet,
subtitles:
body.subtitles && typeof body.subtitles === "object"
? body.subtitles