Open source CapCut alternative.
TypeScript
feat(site): a spine resize carries the timeline with it [rebuild]
David Leed1640406627
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.tsindex 13d7ec86..3e1026b0 100644--- a/site/src/cut/components/Inspector.tools.ts+++ b/site/src/cut/components/Inspector.tools.ts@@ -213,7 +213,7 @@ export const INSPECTOR_TOOLS = [{name: "set_speed",description:- "Set a video clip's playback speed. Faster shortens the clip on the timeline; slower stretches it. Later titles and captions shift to stay in sync.",+ "Set a video clip's playback speed. Faster shortens the clip on the timeline; slower stretches it. Later clips, titles, captions, and soundtrack shift to stay in sync.",inputSchema: obj({ clipId: str("Video clip id"), speed: num("Playback rate (1 = normal, no upper limit)") }, ["clipId", "speed"]),},{diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.tsindex f7586554..cbc67480 100644--- a/site/src/cut/components/Timeline.tools.ts+++ b/site/src/cut/components/Timeline.tools.ts@@ -57,7 +57,7 @@ export const TIMELINE_TOOLS = [{name: "trim_clip",description:- "Set a video clip's trim points inside its source media (seconds). Changing `in` hides the leading part; `out` the trailing part.",+ "Set a video clip's trim points inside its source media (seconds). Changing `in` hides the leading part; `out` the trailing part. While track 0 is the only video track, a track-0 resize ripples: everything past the clip's tail — clips, titles, captions, soundtrack — rides the moved edge in both directions, and every existing gap keeps its width. With overlay video tracks present, growth pushes the track-0 run and a shrink leaves a gap.",inputSchema: obj({ clipId: str("Video clip id"), in: num("New in point (optional)"), out: num("New out point (optional)") }, ["clipId"]),},{@@ -125,7 +125,7 @@ export const TIMELINE_TOOLS = [{name: "delete_item",description:- "Delete a video clip (any track), soundtrack clip, or overlay element (title/shape/sticker) by id. While track 0 is the only video track, deleting a track-0 clip ripples: its footprint closes and everything after it — clips, titles, captions, soundtrack — slides left in sync; items wholly inside that span are removed with it, straddlers are trimmed. With overlay video tracks present the delete leaves its gap in place (remove_gap closes it). Deletes on other tracks remove just that item.",+ "Delete a video clip (any track), soundtrack clip, or overlay element (title/shape/sticker) by id. Only the listed item leaves the project — anything else laid over it survives at full length. While track 0 is the only video track, deleting a track-0 clip ripples: its footprint closes and everything after it — clips, titles, captions, soundtrack — slides left in sync, while items standing over the footprint fall back to where it started. With overlay video tracks present the delete leaves its gap in place (remove_gap closes it). Deletes on other tracks remove just that item.",inputSchema: obj({kind: { type: "string", enum: ["clip", "audio", "overlay"], description: "Item kind — 'clip' is any video clip, whatever track; 'overlay' is any title-lane element" },id: str("Item id"),diff --git a/site/src/cut/lib/laneTracks.ts b/site/src/cut/lib/laneTracks.tsindex 52e2086f..d1f25fcb 100644--- a/site/src/cut/lib/laneTracks.ts+++ b/site/src/cut/lib/laneTracks.ts@@ -30,7 +30,7 @@import type React from "react";import { refFromAsset, startPointerRefDrag } from "./assetRef";import { startDrag } from "./drag";-import { track0Clips, clipLen, getClipSpans, moveOverlayGroup, nextFreeStart, overlayLaneOrder, overlayLayers, projectDuration, useEditor } from "./store";+import { track0Clips, clipLen, getClipSpans, moveOverlayGroup, nextFreeStart, overlayLaneOrder, overlayLayers, projectDuration, reanchorTransitions, startTrimRipple, useEditor } from "./store";import { playheadAt } from "./playhead";import type {AudioClip,@@ -150,8 +150,7 @@ const clipAdapter: LaneAdapter<VideoClip> = {leftFloor: (c) => Math.max(0, c.start - c.in / speedOf(c)),maxLen: videoMaxLen,closesGap: true,- assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId),- onMoved: () => useEditor.getState().sortClips(),+ assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId), onMoved: () => useEditor.getState().sortClips(),};const audioAdapter: LaneAdapter<AudioClip> = {@@ -177,8 +176,7 @@ const audioAdapter: LaneAdapter<AudioClip> = {maxLen: (s, a) =>((s.assets.find((x) => x.id === a.assetId)?.duration ?? a.out) - a.in) / speedOf(a),lanePatch: (a, lane) => ({ id: a.id, patch: { lane: lane > 0 ? lane : undefined } }),- assetOf: (s, a) => s.assets.find((x) => x.id === a.assetId),-};+ assetOf: (s, a) => s.assets.find((x) => x.id === a.assetId),};const textAdapter: LaneAdapter<Overlay> = {minLen: 0.2,@@ -219,8 +217,7 @@ const overlayClipAdapter: LaneAdapter<VideoClip> = {leftFloor: (c) => Math.max(0, c.start - c.in / speedOf(c)),maxLen: videoMaxLen,closesGap: true,- assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId),-};+ assetOf: (s, c) => s.assets.find((x) => x.id === c.assetId),};const cueAdapter: LaneAdapter<SubtitleCue> = {minLen: 0.15,@@ -1150,6 +1147,34 @@ export function startLaneTrim(.raws(s).map((r) => ({ raw: r, view: ad.view(r) })).filter((x) => x.view.id !== id && x.view.lane === self.lane);+ // While track 0 is the only video track, a spine trim ripples: everything+ // past the clip's tail — clips, titles, captions, soundtrack — rides the+ // moved edge in both directions, every gap keeping its width. With overlay+ // video tracks present the engine is null (the delete gate) and the trim+ // keeps its own track's push rules.+ const ripple =+ kind === "clip"+ ? (startTrimRipple(s, id, self.start + self.len) as {+ move: (shift: number, clipPatches: Patch<LaneRaw>[]) => void;+ settle: (close?: { at: number; shift: number }) => void;+ } | null)+ : null;+ // The clip layout the gesture started from, so a trim with no ripple engine+ // behind it can still map the bars onto where it left the cuts.+ const clips0 = kind === "clip" ? s.clips : null;+ /** Close the gesture: the ripple settles the document when there is one,+ * and either way the transition bars re-seat onto the cuts the trim moved.+ * A dissolve follows its cut whether or not the project has overlay tracks. */+ const settle = (close?: { at: number; shift: number }) => {+ if (ripple) {+ ripple.settle(close);+ return;+ }+ if (!clips0) return;+ const st = useEditor.getState();+ if (st.transitions.length)+ useEditor.setState({ transitions: reanchorTransitions(clips0, st.clips, st.transitions) });+ };if (side === "l") {const start0 = self.start;@@ -1242,30 +1267,44 @@ export function startLaneTrim(const end = ad.revealLeftPatch? Math.max(start, floor) + len0 + (start0 - reveal): start0 + len0;- const delta = Math.max(0, end - nextStart);- if (delta !== lastDelta) {- patches.push(...followers.map((f) => ad.movePatch(f.raw, f.view.start + delta)));- lastDelta = delta;+ if (ripple) {+ ripple.move(end - (start0 + len0), patches);+ } else {+ const delta = Math.max(0, end - nextStart);+ if (delta !== lastDelta) {+ patches.push(...followers.map((f) => ad.movePatch(f.raw, f.view.start + delta)));+ lastDelta = delta;+ }+ ad.apply(patches);}- ad.apply(patches);},onUp: () => {ui.onSnap(null);releaseOvershoot();const cur = ad.raws(useEditor.getState()).find((r) => ad.view(r).id === id);const from = cur ? ad.view(cur).start : floor;- if (from >= floor - 1e-4) return; // settled within the room+ if (from >= floor - 1e-4) {+ // Settled within the room. A head trimmed to the right left its+ // trimmed footage as a gap; the ripple closes it, pulling the clip+ // and everything after back onto the footage that survives.+ settle(from > start0 + 1e-4 ? { at: start0, shift: start0 - from } : undefined);+ return;+ }// Elastic spring back to the floor. `finish` lands the floor exactly,// so an interrupting gesture settles rather than strands the trim.// The rubber engages only past the source floor, so the sprung patch// keeps the full reveal.const t0 = performance.now();- const finish = () => ad.apply([selfPatch(floor, srcFloor)]);+ const finish = () => {+ ad.apply([selfPatch(floor, srcFloor)]);+ settle();+ };const step = (now: number) => {const p = Math.min(1, (now - t0) / 240);const v = Math.max(0, from + (floor - from) * easeOutBack(p));ad.apply([selfPatch(p < 1 ? v : floor, srcFloor)]);snapBack = p < 1 ? { raf: requestAnimationFrame(step), finish } : null;+ if (p >= 1) settle();};snapBack = { raf: requestAnimationFrame(step), finish };},@@ -1306,33 +1345,48 @@ export function startLaneTrim(end = ceil + rubberBand((desired - ceil) * ui.pps, RUBBER_PX) / ui.pps;ui.onSnap(null);}- // Followers respond only to growth up to the ceiling, so the overshoot+ // Followers respond only to travel up to the ceiling, so the overshoot// gives visually without shoving the run — and springing back needs no// re-lay, just as packed leaders hold at the floor on the left edge.- const delta = Math.max(0, Math.min(end, ceil) - nextStart);- const run =- delta === lastDelta- ? []- : followers.map((f) => ad.movePatch(f.raw, f.view.start + delta));- lastDelta = delta;- ad.apply([ad.trimRightPatch(raw0, end), ...run]);+ if (ripple) {+ // The document rides the edge both ways, every gap keeping its width.+ ripple.move(Math.min(end, ceil) - end0, [ad.trimRightPatch(raw0, end)]);+ } else {+ const delta = Math.max(0, Math.min(end, ceil) - nextStart);+ const run =+ delta === lastDelta+ ? []+ : followers.map((f) => ad.movePatch(f.raw, f.view.start + delta));+ lastDelta = delta;+ ad.apply([ad.trimRightPatch(raw0, end), ...run]);+ }},onUp: () => {ui.onSnap(null);const cur = ad.raws(useEditor.getState()).find((r) => ad.view(r).id === id);- if (!cur) return;+ if (!cur) {+ settle();+ return;+ }const v = ad.view(cur);const from = v.start + v.len;- if (from <= ceil + 1e-4) return; // settled within the room+ if (from <= ceil + 1e-4) {+ settle();+ return; // settled within the room+ }// Elastic spring back to the ceiling. `finish` lands it exactly, so an// interrupting gesture settles rather than strands an over-ceiling trim.const t0 = performance.now();- const finish = () => ad.apply([ad.trimRightPatch(raw0, ceil)]);+ const finish = () => {+ ad.apply([ad.trimRightPatch(raw0, ceil)]);+ settle();+ };const step = (now: number) => {const p = Math.min(1, (now - t0) / 240);const e2 = from + (ceil - from) * easeOutBack(p);ad.apply([ad.trimRightPatch(raw0, p < 1 ? e2 : ceil)]);snapBack = p < 1 ? { raf: requestAnimationFrame(step), finish } : null;+ if (p >= 1) settle();};snapBack = { raf: requestAnimationFrame(step), finish };},diff --git a/site/src/cut/lib/store.test.ts b/site/src/cut/lib/store.test.tsindex 90d74c4c..675738dc 100644--- a/site/src/cut/lib/store.test.ts+++ b/site/src/cut/lib/store.test.ts@@ -1,6 +1,6 @@import { beforeEach, describe, expect, test } from "bun:test";import { groupRemap } from "@donkeycut/effects-kit";-import { adoptTransitionFields, clipLen, cutTranscribeSpec, deriveTransitionFields, docOverlays, getClipSpans, liftClipLooks, moveOverlayGroup, overlayLaneOrder, normalizeElementLanes, parkedTransitions, placeInRun, projectDuration, separateOverlaps, serializeDoc, useEditor } from "./store";+import { adoptTransitionFields, clipLen, cutTranscribeSpec, deriveTransitionFields, docOverlays, getClipSpans, liftClipLooks, moveOverlayGroup, overlayLaneOrder, normalizeElementLanes, parkedTransitions, placeInRun, projectDuration, separateOverlaps, serializeDoc, startTrimRipple, useEditor } from "./store";import { playheadAt, setPlayhead, setSkim } from "./playhead";import { emptySubtitles } from "./types";import type { AudioClip, MediaAsset, SubtitleCue, TextOverlay, VideoClip } from "./types";@@ -747,6 +747,96 @@ describe("delete ripple and gaps", () => {expect(s().overlays[0].start).toBeCloseTo(1);});+ test("a title on its own row survives the clip it was written over", () => {+ const a = vclip({ track: 0, start: 0, out: 2 });+ const b = vclip({ track: 0, start: 2, out: 2 });+ const t = title({ start: 2.5, end: 3.5, lane: 1 });+ useEditor.setState({+ clips: [a, b],+ overlays: [t],+ selection: { kind: "clip", id: b.id },+ });+ s().deleteSelection();+ // The clip goes; the title keeps its full second and falls back to where+ // the footage under it used to start.+ expect(s().overlays.map((o) => o.id)).toEqual([t.id]);+ expect(s().overlays[0].start).toBeCloseTo(2);+ expect(s().overlays[0].end).toBeCloseTo(3);+ });++ test("a soundtrack spanning the deleted clip keeps every second of it", () => {+ const a = vclip({ track: 0, start: 0, out: 2 });+ const b = vclip({ track: 0, start: 2, out: 2 });+ const c = vclip({ track: 0, start: 4, out: 2 });+ const bed = aclip({ start: 0, out: 6 });+ useEditor.setState({+ clips: [a, b, c],+ audioClips: [bed],+ selection: { kind: "clip", id: b.id },+ });+ s().deleteSelection();+ expect(s().audioClips.map((x) => x.id)).toEqual([bed.id]);+ expect(audioById(bed.id).start).toBeCloseTo(0);+ expect(clipLen(audioById(bed.id))).toBeCloseTo(6);+ expect(clipById(c.id).start).toBeCloseTo(2);+ });++ test("captions over the deleted footage stand, packed and in order", () => {+ const a = vclip({ track: 0, start: 0, out: 2 });+ const b = vclip({ track: 0, start: 2, out: 4 });+ const q1 = cue({ start: 2.5, end: 3, words: [{ t0: 2.5, t1: 3, w: "one" }] });+ const q2 = cue({ start: 3.5, end: 4 });+ useEditor.setState({+ clips: [a, b],+ subtitles: { ...emptySubtitles(), cues: [q1, q2] },+ selection: { kind: "clip", id: b.id },+ });+ s().deleteSelection();+ const cues = s().subtitles.cues;+ expect(cues.map((c) => c.id)).toEqual([q1.id, q2.id]);+ expect(cues[0].start).toBeCloseTo(2);+ expect(cues[0].end).toBeCloseTo(2.5);+ expect(cues[0].words![0].t0).toBeCloseTo(2);+ expect(cues[1].start).toBeCloseTo(2.5);+ expectLaneSound(cues);+ });++ test("two titles on one row pulled back by a ripple stay apart", () => {+ const a = vclip({ track: 0, start: 0, out: 2 });+ const b = vclip({ track: 0, start: 2, out: 4 });+ const t1 = title({ start: 2.5, end: 3 });+ const t2 = title({ start: 3.5, end: 4 });+ useEditor.setState({+ clips: [a, b],+ overlays: [t1, t2],+ selection: { kind: "clip", id: b.id },+ });+ s().deleteSelection();+ expect(s().overlays.map((o) => o.id)).toEqual([t1.id, t2.id]);+ expectLaneSound(s().overlays);+ expect(s().overlays.find((o) => o.id === t2.id)!.start).toBeCloseTo(2.5);+ });++ test("a grouped set crossing rows stays rigid through the ripple", () => {+ const a = vclip({ track: 0, start: 0, out: 2 });+ const b = vclip({ track: 0, start: 2, out: 6 });+ // Lane 0 is crowded right where the group wants to land, so its member+ // packs in behind the resident — and its peer on lane 1 comes along.+ const resident = title({ start: 2.2, end: 2.9 });+ const g1 = title({ start: 4, end: 5, groupId: "g" });+ const g2 = title({ start: 4, end: 5, lane: 1, groupId: "g" });+ useEditor.setState({+ clips: [a, b],+ overlays: [resident, g1, g2],+ selection: { kind: "clip", id: b.id },+ });+ s().deleteSelection();+ const byId = (id: string) => s().overlays.find((o) => o.id === id)!;+ expect(s().overlays.length).toBe(3);+ expect(byId(g1.id).start).toBeCloseTo(byId(g2.id).start);+ expectLaneSound(s().overlays.filter((o) => (o.lane ?? 0) === 0));+ });+test("delete with an overlay video track leaves the gap in place", () => {const a = vclip({ track: 0, start: 0, out: 2 });const b = vclip({ track: 0, start: 2, out: 2 });@@ -838,6 +928,123 @@ describe("delete ripple and gaps", () => {});});+describe("resize ripple", () => {+ test("shrinking a clip pulls everything after it along, gaps kept", () => {+ const a = vclip({ track: 0, start: 0, out: 4 });+ const b = vclip({ track: 0, start: 4, out: 2 });+ const t = title({ start: 4.5, end: 5.5 });+ const au = aclip({ start: 5, out: 1 });+ const q = cue({ start: 4.2, end: 4.8, words: [{ t0: 4.2, t1: 4.8, w: "hi" }] });+ useEditor.setState({+ clips: [a, b],+ overlays: [t],+ audioClips: [au],+ subtitles: { ...emptySubtitles(), cues: [q] },+ });+ s().setClipTrim(a.id, 0, 3);+ expect(clipById(b.id).start).toBeCloseTo(3);+ expect(s().overlays[0].start).toBeCloseTo(3.5);+ expect(audioById(au.id).start).toBeCloseTo(4);+ expect(s().subtitles.cues[0].start).toBeCloseTo(3.2);+ expect(s().subtitles.cues[0].words![0].t0).toBeCloseTo(3.2);+ });++ test("growing a clip pushes them right the same way", () => {+ const av = asset(8);+ const a = vclip({ track: 0, start: 0, out: 4, assetId: av.id });+ const b = vclip({ track: 0, start: 5, out: 2, assetId: av.id }); // a 1s gap before b+ const t = title({ start: 5, end: 6 });+ useEditor.setState({ assets: [av], clips: [a, b], overlays: [t] });+ s().setClipTrim(a.id, 0, 6);+ expect(clipById(b.id).start).toBeCloseTo(7); // its gap survives+ expect(s().overlays[0].start).toBeCloseTo(7);+ });++ test("growing into an abutting neighbor carries it along, never over it", () => {+ const av = asset(8);+ const a = vclip({ track: 0, start: 0, out: 4, assetId: av.id });+ const b = vclip({ track: 0, start: 4, out: 2, assetId: av.id }); // butted joint+ const t = title({ start: 4, end: 5 });+ useEditor.setState({ assets: [av], clips: [a, b], overlays: [t] });+ s().setClipTrim(a.id, 0, 6);+ expect(clipById(b.id).start).toBeCloseTo(6);+ expect(s().overlays[0].start).toBeCloseTo(6);+ expectLaneSound(videoLane(0));+ });++ test("the gesture's tail growth rides the abutting run too", () => {+ // The left handle's pinned reveal and the right handle's growth both feed+ // the engine a positive shift; the clip butted against the tail moves.+ const a = vclip({ track: 0, start: 0, out: 4 });+ const b = vclip({ track: 0, start: 4, out: 2 });+ useEditor.setState({ clips: [a, b] });+ const engine = startTrimRipple(s(), a.id, 4)!;+ engine.move(1, [{ id: a.id, patch: { out: 5 } }]);+ expect(clipById(b.id).start).toBeCloseTo(5);+ expectLaneSound(videoLane(0));+ engine.move(0, [{ id: a.id, patch: { out: 4 } }]);+ expect(clipById(b.id).start).toBeCloseTo(4);+ engine.settle();+ });++ test("an item standing over the shortened tail falls back to the new end", () => {+ const a = vclip({ track: 0, start: 0, out: 4 });+ const t = title({ start: 3, end: 5 });+ useEditor.setState({ clips: [a], overlays: [t] });+ s().setClipTrim(a.id, 0, 2);+ expect(s().overlays[0].start).toBeCloseTo(2);+ expect(s().overlays[0].end).toBeCloseTo(4);+ });++ test("with an overlay video track a shrink keeps its own-track rules", () => {+ const a = vclip({ track: 0, start: 0, out: 4 });+ const b = vclip({ track: 0, start: 4, out: 2 });+ const layer = vclip({ track: 1, start: 1, out: 2 });+ useEditor.setState({ clips: [a, b, layer] });+ s().setClipTrim(a.id, 0, 3);+ expect(clipById(b.id).start).toBeCloseTo(4); // the gap stays+ expect(clipById(layer.id).start).toBeCloseTo(1);+ });++ test("the trim gesture ripples live and a retreat flows everything back", () => {+ const a = vclip({ track: 0, start: 0, out: 4 });+ const b = vclip({ track: 0, start: 4, out: 2 });+ const t = title({ start: 4.5, end: 5 });+ useEditor.setState({ clips: [a, b], overlays: [t] });+ const engine = startTrimRipple(s(), a.id, 4)!;+ engine.move(-1, [{ id: a.id, patch: { out: 3 } }]);+ expect(clipById(a.id).out).toBeCloseTo(3);+ expect(clipById(b.id).start).toBeCloseTo(3);+ expect(s().overlays[0].start).toBeCloseTo(3.5);+ engine.move(0, [{ id: a.id, patch: { out: 4 } }]);+ expect(clipById(b.id).start).toBeCloseTo(4);+ expect(s().overlays[0].start).toBeCloseTo(4.5);+ engine.settle();+ });++ test("settling a head trim closes the footage it removed", () => {+ const a = vclip({ track: 0, start: 0, out: 4 });+ const b = vclip({ track: 0, start: 4, out: 2 });+ const t = title({ start: 5, end: 6 });+ useEditor.setState({ clips: [a, b], overlays: [t] });+ const engine = startTrimRipple(s(), a.id, 4)!;+ // The left handle dragged right by 1: head trimmed, gap opened before.+ engine.move(0, [{ id: a.id, patch: { start: 1, in: 1 } }]);+ engine.settle({ at: 0, shift: -1 });+ expect(clipById(a.id).start).toBeCloseTo(0);+ expect(clipById(a.id).in).toBeCloseTo(1);+ expect(clipById(b.id).start).toBeCloseTo(3);+ expect(s().overlays[0].start).toBeCloseTo(4);+ });++ test("with an overlay video track the gesture engine stays off", () => {+ const a = vclip({ track: 0, start: 0, out: 4 });+ const layer = vclip({ track: 1, start: 0, out: 2 });+ useEditor.setState({ clips: [a, layer] });+ expect(startTrimRipple(s(), a.id, 4)).toBe(null);+ });+});+describe("spine grounding", () => {test("deleting the last track-0 clip grounds the layers above it", () => {const spine = vclip({ track: 0, start: 0, out: 2 });diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.tsindex 0dc3582d..0aab81f9 100644--- a/site/src/cut/lib/store.ts+++ b/site/src/cut/lib/store.ts@@ -415,12 +415,14 @@ export interface EditorState {/** Place an effect element; a drop passes where it landed. */addEffect: (effect: EffectId, aim?: { at?: number; lane?: number }) => void;updateClip: (id: string, patch: Partial<VideoClip>) => void;- /** Set a clip's playback rate (0.25–4). A longer footprint pushes the- * following clips right by the overflow; a shorter one opens a gap. */+ /** Set a clip's playback rate (0.25–4). The footprint change carries the+ * timeline behind it the way a trim does (see resizeClipFootprint). */setClipSpeed: (id: string, speed: number) => void;- /** Set a clip's source trim points with the same run rules as a speed- * resize: a longer footprint pushes the following clips right, a shorter- * one opens a gap, and a live dissolve keeps its overlap. */+ /** Set a clip's source trim points. While track 0 is the only video track,+ * a track-0 resize ripples: everything past the clip's tail rides the moved+ * edge both directions, gaps keeping their width. Otherwise the run rules+ * stay on the clip's own track: growth pushes the following clips right, a+ * shrink opens a gap, and a live dissolve keeps its contact. */setClipTrim: (id: string, nextIn: number, nextOut: number) => void;/** Set the transition into the next clip (seconds; 0 clears it), optionally* changing its style; omitting the style keeps the current one. Upserts the@@ -548,6 +550,14 @@ export interface EditorState {updateAudiosTransient: (patches: { id: string; patch: Partial<AudioClip> }[]) => void;updateCuesTransient: (patches: { id: string; patch: Partial<SubtitleCue> }[]) => void;updateClipsTransient: (patches: { id: string; patch: Partial<VideoClip> }[]) => void;+ /** Patch every collection in one write — a trim gesture's ripple lands the+ * whole document per pointer move, so the frame renders once. */+ updateDocTransient: (patches: {+ clips?: { id: string; patch: Partial<VideoClip> }[];+ audioClips?: { id: string; patch: Partial<AudioClip> }[];+ overlays?: { id: string; patch: OverlayPatch }[];+ cues?: { id: string; patch: Partial<SubtitleCue> }[];+ }) => void;updateClipTransient: (id: string, patch: Partial<VideoClip>) => void;updateAudioTransient: (id: string, patch: Partial<AudioClip>) => void;/** Keep the clips array sorted by start (consumers read `clips[0]` as the@@ -635,14 +645,17 @@ export interface EditorState {* from the original recording, so the word highlighter would otherwise drift). */retimeCues: (entries: { id: string; start: number; end: number }[]) => void;sortCues: () => void;- /** Delete the current selection. While track 0 is the only video track and+ /** Delete the current selection — and only the selection: a clip delete+ * never takes a title, sticker, caption or soundtrack clip with it, whatever+ * footage they were laid over. While track 0 is the only video track and* some of its footage survives, a track-0 clip delete ripples: the footprint- * it occupied closes and everything after it — clips, titles, captions,- * soundtrack — slides left in sync (see exciseRange). With upper video- * layers present the slide would shear them against track 0, and with track- * 0 emptied there is nothing left for the close to keep contiguous, so both- * leave the gap and everything laid over the footage stands; closing it is- * `removeLaneGap`. Deletes on every other track remove just that item. */+ * it occupied closes and everything after it slides left in sync, while+ * anything standing over the hole falls back to where the footage started+ * (see rippleAt). With upper video layers present the slide would shear+ * them against track 0, and with track 0 emptied there is nothing left for+ * the close to keep contiguous, so both leave the gap and everything stands+ * where it was; closing it is `removeLaneGap`. Deletes on every other track+ * remove just that item. */deleteSelection: () => void;/** Close the empty span on `lane` containing `at` — a video track, an audio* track, or a title track. Only that row's later items slide left; every@@ -948,38 +961,61 @@ function pushOverlaysClearOf(ids: Set<string>) {}));}-/** Resize a clip's footprint to `newLen` (a trim or speed change), keeping its- * own track sound: a cut the clip transitions over stays a cut (the run- * follows the resize so the pair keeps its contact); otherwise a longer- * footprint pushes the run right by the overflow and a shorter one just opens- * a gap. Everything is scoped to the clip's track — resizing a track-0 clip- * never drags the composited layers (or vice versa), so each track's- * annotations keep the timing they were placed at. One undo step. */+/** Resize a clip's footprint to `newLen` (a trim or speed change) and carry+ * the timeline behind the moved tail. While track 0 is the only video track,+ * a track-0 resize ripples the whole document: everything past the tail —+ * clips, titles, captions, soundtrack — rides the edge in both directions and+ * every pre-existing gap keeps its width, so annotations stay on the footage+ * they were laid over. Layer clips, and a spine resize under overlay video+ * tracks (where the slide would shear the layers), keep the run rules scoped+ * to their own track: a cut the clip transitions over stays a cut, a longer+ * footprint pushes the run right by the overflow, and a shorter one opens a+ * gap. One undo step. */function resizeClipFootprint(clip: VideoClip, patch: Partial<VideoClip>, newLen: number) {useEditor.getState().pushHistory();const before = useEditor.getState().clips;- const next = useEditor- .getState()- .clips.filter((c) => c.id !== clip.id && c.track === clip.track && c.start >= clip.start)- .reduce<VideoClip | null>((m, c) => (!m || c.start < m.start ? c : m), null);- // Whether the pair makes the cut this clip's transition lives on, measured- // before the resize lands.- const keepContact = !!next && transitionOverlap(clip, next) > 1e-6;+ const end0 = clip.start + clipLen(clip);+ const newEnd = clip.start + newLen;useEditor.getState().updateClipTransient(clip.id, patch);- const nextStart = next?.start ?? Infinity;- const delta = keepContact- ? clip.start + newLen - nextStart- : Math.max(0, clip.start + newLen - nextStart);- if (Math.abs(delta) > 1e-6) {- useEditor.setState((st) => ({- clips: st.clips- .map((c) =>- c.id !== clip.id && c.track === clip.track && c.start >= clip.start- ? { ...c, start: Math.max(0, c.start + delta) }- : c- )- .sort((a, b) => a.start - b.start),- }));+ if (clip.track === 0 && !before.some((c) => c.track !== 0)) {+ // The spine resize ripples: everything past the clip's tail — clips,+ // titles, captions, soundtrack — rides the moved edge in both directions,+ // every pre-existing gap keeping its width (see rippleAt).+ useEditor.setState((st) => {+ const out = rippleAt(+ { clips: st.clips, audioClips: st.audioClips, overlays: st.overlays, cues: st.subtitles.cues },+ Math.min(end0, newEnd),+ newEnd - end0+ );+ return {+ clips: out.clips === st.clips ? st.clips : [...out.clips].sort((a, b) => a.start - b.start),+ audioClips: out.audioClips,+ overlays: out.overlays,+ ...(out.cues !== st.subtitles.cues ? { subtitles: { ...st.subtitles, cues: out.cues } } : {}),+ };+ });+ } else {+ // With upper video layers present the slide would shear them against the+ // footage they were composed over, so growth pushes the same-track run+ // and a shrink leaves the gap — except a live dissolve's partner, which+ // follows the edge to keep the cut it blends.+ const next = before+ .filter((c) => c.id !== clip.id && c.track === clip.track && c.start >= clip.start)+ .reduce<VideoClip | null>((m, c) => (!m || c.start < m.start ? c : m), null);+ const keepContact = !!next && transitionOverlap(clip, next) > 1e-6;+ const nextStart = next?.start ?? Infinity;+ const delta = keepContact ? newEnd - nextStart : Math.max(0, newEnd - nextStart);+ if (Math.abs(delta) > 1e-6) {+ useEditor.setState((st) => ({+ clips: st.clips+ .map((c) =>+ c.id !== clip.id && c.track === clip.track && c.start >= clip.start+ ? { ...c, start: Math.max(0, c.start + delta) }+ : c+ )+ .sort((a, b) => a.start - b.start),+ }));+ }}// The resized clip's own edge moved, and the run behind it with it, so the// bars playing those cuts follow.@@ -2933,6 +2969,43 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {};}),+ updateDocTransient: (patches) =>+ set((s) => {+ const out: Partial<EditorState> = {};+ if (patches.clips?.length) {+ const byId = new Map(patches.clips.map((p) => [p.id, p.patch]));+ out.clips = s.clips.map((c) => {+ const patch = byId.get(c.id);+ return patch ? { ...c, ...patch } : c;+ });+ }+ if (patches.audioClips?.length) {+ const byId = new Map(patches.audioClips.map((p) => [p.id, p.patch]));+ out.audioClips = s.audioClips.map((a) => {+ const patch = byId.get(a.id);+ return patch ? { ...a, ...patch } : a;+ });+ }+ if (patches.overlays?.length) {+ const byId = new Map(patches.overlays.map((p) => [p.id, p.patch]));+ out.overlays = s.overlays.map((o) => {+ const patch = byId.get(o.id);+ return patch ? { ...o, ...patch } : o;+ });+ }+ if (patches.cues?.length) {+ const byId = new Map(patches.cues.map((p) => [p.id, p.patch]));+ out.subtitles = {+ ...s.subtitles,+ cues: s.subtitles.cues.map((c) => {+ const patch = byId.get(c.id);+ return patch ? { ...c, ...patch } : c;+ }),+ };+ }+ return out;+ }),+sortClips: () =>set((s) => ({ clips: [...s.clips].sort((a, b) => a.start - b.start) })),@@ -3242,18 +3315,17 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {let cues = s.subtitles.cues.filter((c) => !cueIds.has(c.id));// Deleting a track-0 clip closes the hole it leaves: everything after// it — clips, titles, captions, soundtrack — slides left with the- // surviving footage, and anything living inside the hole annotated- // footage that is gone, so it goes too. Two conditions gate that- // ripple. Track 0 has to be the only video track, since with upper- // layers surviving the slide would shear them against the footage they- // were composed over. And some track-0 footage has to survive the- // delete: clearing the whole track leaves no hole to close, and closing- // it anyway would carry every title, card and caption in the project- // into the excision. Either way the delete leaves the gap and closing- // it is an explicit act (removeGap, via right-click on the empty- // space). Deletes on every other track are plain removals (already- // applied above). Holes close right-to-left so each one's coordinates- // stay valid while the ones before it are unprocessed.+ // surviving footage, and anything standing over the hole falls back to+ // where the footage started. Nothing but the picked clip leaves the+ // project. Two conditions gate that ripple. Track 0 has to be the only+ // video track, since with upper layers surviving the slide would shear+ // them against the footage they were composed over. And some track-0+ // footage has to survive the delete, since clearing the whole track+ // leaves no hole to close. Either way the delete leaves the gap and+ // closing it is an explicit act (removeGap, via right-click on the+ // empty space). Deletes on every other track are plain removals+ // (already applied above). Holes close right-to-left so each one's+ // coordinates stay valid while the ones before it are unprocessed.const rippling = clips.some((c) => c.track === 0) && !clips.some((c) => c.track !== 0);const holes = rippling? s.clips@@ -3270,10 +3342,10 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {// any gap that already existed after it survives.const delta = Math.min(clipLen(gone), next - gone.start);if (delta < 0.05) continue;- ({ clips, audioClips, overlays, cues } = exciseRange(+ ({ clips, audioClips, overlays, cues } = rippleAt({ clips, audioClips, overlays, cues },gone.start,- delta+ -delta));}clips = clips.sort((a, b) => a.start - b.start);@@ -5280,13 +5352,27 @@ export function laneGapAt(return null;}-/** Cut the timeline range [at, at + delta) out of the whole document — the- * ripple half of a track-0 delete. Items past the hole slide left by delta;- * items wholly inside it are removed; items straddling an edge keep the part- * that survives (a layer/soundtrack clip spanning the hole splits around it,- * excising those source seconds). Track-0 clips only shift: the hole is a- * deleted track-0 clip's own footprint, so no survivor there can straddle it. */-function exciseRange(+/** Items grouped by the row they live on, each row in play order. */+function byRow<T>(items: T[], row: (x: T) => number, startOf: (x: T) => number): Map<number, T[]> {+ const rows = new Map<number, T[]>();+ for (const item of items) {+ const list = rows.get(row(item));+ if (list) list.push(item);+ else rows.set(row(item), [item]);+ }+ for (const list of rows.values()) list.sort((a, b) => startOf(a) - startOf(b));+ return rows;+}++/** Slide everything on every row past `at` by `shift` seconds — how a track-0+ * delete or resize carries the rest of the document. A negative shift closes+ * the span [at, at - shift): items past it slide left in sync, an item+ * standing over it falls back to `at`, and each row packs so no item overruns+ * the one ahead of it. A positive shift opens that span, sliding items past+ * `at` right together. Either way every item survives whole — same media,+ * same length — pre-existing gaps keep their width, cue words ride along, and+ * a grouped set of elements moves as one. Items at or before `at` stand. */+export function rippleAt(doc: {clips: VideoClip[];audioClips: AudioClip[];@@ -5294,65 +5380,219 @@ function exciseRange(cues: SubtitleCue[];},at: number,- delta: number+ shift: number): typeof doc {+ if (Math.abs(shift) < 1e-9) return doc;const EPS = 0.001;- const end = at + delta;-- const cutClip = <T extends VideoClip | AudioClip>(c: T): T[] => {- const speed = c.speed && c.speed > 0 ? c.speed : 1;- const stop = c.start + clipLen(c);- if (stop <= at + EPS) return [c];- if (c.start >= end - EPS) return [{ ...c, start: c.start - delta }];- const pieces: T[] = [];- if (c.start < at) pieces.push({ ...c, out: c.in + (at - c.start) * speed });- if (stop > end) pieces.push({ ...c, id: pieces.length ? uid() : c.id, start: at, in: c.in + (end - c.start) * speed });- return pieces.filter((p) => (p.out - p.in) / speed >= MIN_LEN);+ /** The ripple's own pull on a time: past `at` it moves by the shift, and a+ * close never drags anything in front of where the closed span began. An+ * item sitting exactly on `at` — the clip abutting a growing tail — rides+ * an open and stands through a close (a close cannot move it anyway). */+ const pull =+ shift > 0+ ? (start: number) => (start < at - EPS ? start : start + shift)+ : (start: number) => (start <= at + EPS ? start : Math.max(at, start + shift));++ /** One kind of row re-laid: each item takes the ripple's pull, then gives+ * way to whatever the item ahead of it on its row needs. Returns each+ * item's move. */+ const slides = <T,>(+ items: T[],+ row: (x: T) => number,+ startOf: (x: T) => number,+ lenOf: (x: T) => number+ ): Map<T, number> => {+ const out = new Map<T, number>();+ for (const list of byRow(items, row, startOf).values()) {+ let cursor = -Infinity;+ for (const item of list) {+ const start = startOf(item);+ const landed = Math.max(pull(start), cursor);+ out.set(item, landed - start);+ cursor = landed + lenOf(item);+ }+ }+ return out;};- const cutText = (o: Overlay): Overlay[] => {- if (o.end <= at + EPS) return [o];- if (o.start >= end - EPS) return [{ ...o, start: o.start - delta, end: o.end - delta }];- const start = Math.min(o.start, at);- const stop = o.end > end ? o.end - delta : at;- return stop - start >= MIN_LEN ? [{ ...o, start, end: stop }] : [];+ /** Elements re-lay the same way, with a grouped set held rigid: the group+ * takes one move — the member with the least room pins the set — and a+ * member crowded on its own lane raises it for all of them until every+ * lane is clear. */+ const elementSlides = (overlays: Overlay[]): Map<Overlay, number> => {+ const unit = (o: Overlay) => o.groupId ?? o.id;+ const tighter = (a: number, b: number) => (Math.abs(a) < Math.abs(b) ? a : b);+ const moves = new Map<string, number>();+ for (const o of overlays) {+ const want = pull(o.start) - o.start;+ const cur = moves.get(unit(o));+ moves.set(unit(o), cur === undefined ? want : tighter(cur, want));+ }+ const lanes = byRow(overlays, (o) => o.lane ?? 0, (o) => o.start);+ for (let pass = 0; pass <= overlays.length; pass++) {+ let raised = false;+ for (const list of lanes.values()) {+ let cursor = -Infinity;+ for (const o of list) {+ if (o.start + moves.get(unit(o))! < cursor - 1e-9) {+ moves.set(unit(o), cursor - o.start);+ raised = true;+ }+ cursor = o.start + moves.get(unit(o))! + (o.end - o.start);+ }+ }+ if (!raised) break;+ }+ return new Map(overlays.map((o) => [o, moves.get(unit(o))!]));};- const cutCue = (c: SubtitleCue): SubtitleCue[] => {- if (c.end <= at + EPS) return [c];- if (c.start >= end - EPS) {- return [{- ...c,- start: c.start - delta,- end: c.end - delta,- words: c.words?.map((w) => ({ ...w, t0: w.t0 - delta, t1: w.t1 - delta })),- }];- }- const start = Math.min(c.start, at);- const stop = c.end > end ? c.end - delta : at;- if (stop - start < MIN_LEN) return [];- // Same convention as splitCue: a word sits left of a cut when it starts- // before it. Words swallowed by the hole go with it; later ones slide left- // and the text follows the surviving words.- const words = c.words- ?.filter((w) => w.t0 < at || w.t0 >= end)- .map((w) => (w.t0 >= end ? { ...w, t0: w.t0 - delta, t1: w.t1 - delta } : w));- return [{- ...c,- start,- end: stop,- words: words?.length ? words : undefined,- text: words?.length ? words.map((w) => w.w).join(" ") : c.text,- }];+ const clipBy = slides(doc.clips, (c) => c.track, (c) => c.start, clipLen);+ const audioBy = slides(doc.audioClips, (a) => a.lane ?? 0, (a) => a.start, clipLen);+ const textBy = elementSlides(doc.overlays);+ const cueBy = slides(doc.cues, (c) => c.lane ?? 0, (c) => c.start, (c) => c.end - c.start);+ const moved = <T,>(item: T, moves: Map<T, number>) => {+ const by = moves.get(item)!;+ return Math.abs(by) < 1e-6 ? 0 : by;};+ /** Same array back when nothing on it moved, so an untouched collection+ * keeps its identity (autosave tells an edit from a re-read by it). */+ const keep = <T,>(orig: T[], next: T[]) => (next.some((x, i) => x !== orig[i]) ? next : orig);return {- clips: doc.clips.flatMap((c) =>- c.track !== 0 ? cutClip(c) : c.start >= end - EPS ? [{ ...c, start: c.start - delta }] : [c]+ clips: keep(+ doc.clips,+ doc.clips.map((c) => {+ const by = moved(c, clipBy);+ return by ? { ...c, start: c.start + by } : c;+ })+ ),+ audioClips: keep(+ doc.audioClips,+ doc.audioClips.map((a) => {+ const by = moved(a, audioBy);+ return by ? { ...a, start: a.start + by } : a;+ })+ ),+ overlays: keep(+ doc.overlays,+ doc.overlays.map((o) => {+ const by = moved(o, textBy);+ return by ? { ...o, start: o.start + by, end: o.end + by } : o;+ })),- audioClips: doc.audioClips.flatMap(cutClip),- overlays: doc.overlays.flatMap(cutText),- cues: doc.cues.flatMap(cutCue),+ cues: keep(+ doc.cues,+ doc.cues.map((c) => {+ const by = moved(c, cueBy);+ if (!by) return c;+ return {+ ...c,+ start: c.start + by,+ end: c.end + by,+ words: c.words?.map((w) => ({ ...w, t0: w.t0 + by, t1: w.t1 + by })),+ };+ })+ ),+ };+}++/** The live ripple a trim-handle drag spreads while track 0 is the only video+ * track: created at grab, fed the clip's footprint-end travel each pointer+ * move, settled on release. Each move re-lays every other item from the+ * grab-time layout through `rippleAt` — so a retreating drag flows everything+ * back to where it stood — and lands the whole document in one write. Null+ * when an overlay video track is present: the slide would shear the layers+ * against the footage they were composed over, so those trims keep the run+ * rules on their own track (the delete gate). */+export function startTrimRipple(+ s: Pick<EditorState, "clips" | "audioClips" | "overlays" | "subtitles" | "transitions">,+ selfId: string,+ end0: number+): {+ /** Apply one pointer move: `shift` is the footprint end's travel from where+ * it stood at grab (negative = shorter), `clipPatches` the gesture's own+ * clip writes — the trim itself, plus any leaders it re-laid. */+ move: (shift: number, clipPatches: { id: string; patch: Partial<VideoClip> }[]) => void;+ /** Land the gesture. A left-handle trim that moved the head rightward+ * leaves its trimmed footage as a gap; `close` names where the head stood+ * and how far everything behind it slides back to swallow it. Then the+ * transition bars re-seat on the cuts the gesture moved. */+ settle: (close?: { at: number; shift: number }) => void;+} | null {+ if (s.clips.some((c) => c.track !== 0)) return null;+ const clips0 = s.clips;+ const doc0 = {+ clips: s.clips.filter((c) => c.id !== selfId),+ audioClips: s.audioClips,+ overlays: s.overlays,+ cues: s.subtitles.cues,+ };+ // Where each rider last landed, so a move patches only what it changes and+ // a retreat restores what an earlier move displaced.+ const placed = new Map<string, number>();+ for (const c of doc0.clips) placed.set(`c${c.id}`, c.start);+ for (const a of doc0.audioClips) placed.set(`a${a.id}`, a.start);+ for (const o of doc0.overlays) placed.set(`o${o.id}`, o.start);+ for (const q of doc0.cues) placed.set(`q${q.id}`, q.start);+ let dirty = false;+ return {+ move: (shift, clipPatches) => {+ dirty = true;+ // The trimmed clip rides along as its patch; `at` sits at the tail's+ // earlier position, so a shrink pulls nothing in front of the new tail+ // and growth carries everything past the old one.+ const out = rippleAt(doc0, Math.min(end0, end0 + shift), shift);+ const clips = [...clipPatches];+ const audioClips: { id: string; patch: Partial<AudioClip> }[] = [];+ const overlays: { id: string; patch: OverlayPatch }[] = [];+ const cues: { id: string; patch: Partial<SubtitleCue> }[] = [];+ for (const c of out.clips)+ if (placed.get(`c${c.id}`) !== c.start) {+ placed.set(`c${c.id}`, c.start);+ clips.push({ id: c.id, patch: { start: c.start } });+ }+ for (const a of out.audioClips)+ if (placed.get(`a${a.id}`) !== a.start) {+ placed.set(`a${a.id}`, a.start);+ audioClips.push({ id: a.id, patch: { start: a.start } });+ }+ for (const o of out.overlays)+ if (placed.get(`o${o.id}`) !== o.start) {+ placed.set(`o${o.id}`, o.start);+ overlays.push({ id: o.id, patch: { start: o.start, end: o.end } });+ }+ for (const q of out.cues)+ if (placed.get(`q${q.id}`) !== q.start) {+ placed.set(`q${q.id}`, q.start);+ cues.push({ id: q.id, patch: { start: q.start, end: q.end, words: q.words } });+ }+ useEditor.getState().updateDocTransient({ clips, audioClips, overlays, cues });+ },+ settle: (close) => {+ if (close && close.shift < -1e-6) {+ dirty = true;+ useEditor.setState((st) => {+ const out = rippleAt(+ { clips: st.clips, audioClips: st.audioClips, overlays: st.overlays, cues: st.subtitles.cues },+ close.at,+ close.shift+ );+ return {+ clips: out.clips,+ audioClips: out.audioClips,+ overlays: out.overlays,+ ...(out.cues !== st.subtitles.cues ? { subtitles: { ...st.subtitles, cues: out.cues } } : {}),+ };+ });+ }+ if (!dirty) return;+ const st = useEditor.getState();+ // One mapping from the grab layout to where the gesture left the cuts,+ // so every bar keeps playing the boundary it played.+ if (st.transitions.length)+ useEditor.setState({ transitions: reanchorTransitions(clips0, st.clips, st.transitions) });+ st.sortClips();+ },};}diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.tsindex 0d177322..5ac88d96 100644--- a/site/src/cut/server/ai/catalog.ts+++ b/site/src/cut/server/ai/catalog.ts@@ -84,13 +84,14 @@ 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.-- While track 0 is the only video track, deleting a track-0 clip ripples: the span it occupied closes, later items on every track slide left together, items wholly inside the span go with it, and straddlers are trimmed. A gap that already existed stays. With overlay video tracks present the delete leaves its gap (remove_gap closes it by sliding that track's later clips left). Deletes on other tracks remove just that item.+- A delete removes the item asked for and nothing else: a title, sticker, caption or soundtrack clip laid over a deleted clip is still there afterwards, at its full length. While track 0 is the only video track, deleting a track-0 clip ripples: the span it occupied closes, later items on every track slide left together, and anything standing over the span falls back to where the span started. A gap that already existed stays. With overlay video tracks present the delete leaves its gap (remove_gap closes it by sliding that track's later clips left). Deletes on other tracks remove just that item.- 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 — clips after it shift right, every other gap survives. Index-based inserts (freeze_frame, generated clips) open a slot the same way.- 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.- A clip's timeline length is (out-in)/speed; total duration runs to the last clip's end, gaps included. Transitions blend at cuts and never change layout or length.- trim_clip changes in/out inside the source media. in >= 0, out <= source duration, out-in >= 0.1.-- set_speed sets a clip's playback rate; it changes the clip's timeline length, and later titles/captions ripple to stay in sync.+- Resizes ripple the same way deletes do: while track 0 is the only video track, a track-0 trim or speed change slides everything past the clip's tail — clips, titles, captions, soundtrack — with the moved edge, in both directions, every existing gap keeping its width. With overlay video tracks present, growth pushes the track-0 run and a shrink leaves a gap.+- set_speed sets a clip's playback rate; it changes the clip's timeline length and carries the timeline behind it like a trim.- set_transition joins a clip into the next one (0–2s, ${TRANSITION_STYLE_IDS.length} styles); set_animation animates one clip's own entrance/exit — read the transitions-and-fades skill before styling cuts. Splitting or deleting clears the affected transition. A transition is a bar on its own row at an absolute time, so an edit can leave one lining up with nothing: every timeline mutation reports those as \`parkedTransitions\`, and clearing them (remove_transition) is part of finishing the edit. Grading a clip's picture is the color tools (set_color_preset, set_color_grade, set_color_curves, set_color_wheels, set_color_hsl — read the color-grading skill); a stylized post treatment (grain, VHS, halation…) is add_effect, dropped over the stretch of timeline it covers — as is a treatment on the sound (echo, reverb, telephone…).- split_at cuts the track-0 clip under that time into two clips at the exact frame. With a soundtrack or overlay clip selected it splits that instead.- The Media and Library panels take the same gestures: ⌘/⇧-click a tile, or sweep a rubber-band over the grid, and dragging any picked tile onto the timeline lays the whole set down one after another from the drop point.