@hyperframes/studio 0.8.91 → 0.8.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.91",
+  "version": "0.8.93",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.91",
-    "@hyperframes/player": "0.8.91",
-    "@hyperframes/shader-transitions": "0.8.91",
-    "@hyperframes/sdk": "0.8.91",
-    "@hyperframes/studio-server": "0.8.91",
-    "@hyperframes/core": "0.8.91"
+    "@hyperframes/core": "0.8.93",
+    "@hyperframes/shader-transitions": "0.8.93",
+    "@hyperframes/studio-server": "0.8.93",
+    "@hyperframes/parsers": "0.8.93",
+    "@hyperframes/player": "0.8.93",
+    "@hyperframes/sdk": "0.8.93"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.91"
+    "@hyperframes/producer": "0.8.93"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/useTimelineAssetDropOps.test.tsx

@@ -6,6 +6,7 @@ import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { usePlayerStore } from "../player/store/playerStore";
 import type { TimelineElement } from "../player";
+import type { TimelineDropPlacement } from "../player/components/timelineCallbacks";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -140,6 +141,143 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     expect(written).toMatch(/<video id="clip"[^>]*data-track-index="1"/);
   });
 
+  // A clip shown on timeline row `row` and written on file track `track`.
+  const rowClip = (
+    id: string,
+    start: number,
+    duration: number,
+    shown: { tag?: string; row?: number; track?: number } = {},
+  ): TimelineElement => ({
+    id,
+    key: id,
+    tag: shown.tag ?? "div",
+    start,
+    duration,
+    track: shown.row ?? 0,
+    authoredTrack: shown.track ?? shown.row ?? 0,
+    hfId: `hf-${id}`,
+    domId: id,
+  });
+  const rowSource = (clips: TimelineElement[]) =>
+    [
+      '<main data-composition-id="scene" data-duration="10" data-width="1920" data-height="1080">',
+      ...clips.map(
+        (c) =>
+          `<${c.tag} data-hf-id="hf-${c.id}" id="${c.id}" data-start="${c.start}" data-duration="${c.duration}" data-track-index="${c.authoredTrack}"></${c.tag}>`,
+      ),
+      "</main>",
+    ].join("\n");
+  const writtenClip = (written: string, tag: string) =>
+    written.match(new RegExp(`<${tag} id="[^"]*"[^>]*>`))?.[0] ?? "";
+
+  it("lands an asset dropped on an occupied row at that row's nearest free time", async () => {
+    const subtitle = rowClip("subtitle", 0, 6);
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const getDrop = renderDropHook(rowSource([subtitle]), writeProjectFile, [subtitle]);
+
+    await act(async () => {
+      await getDrop()("clip.mp4", { start: 2, track: 0 }, 5);
+    });
+
+    const [, written] = writeProjectFile.mock.calls[0] as [string, string];
+    const clip = writtenClip(written, "video");
+    expect(clip).toContain('data-start="6"');
+    expect(clip).toContain('data-track-index="0"');
+    expect(written).toContain(
+      'id="subtitle" data-start="0" data-duration="6" data-track-index="0"',
+    );
+  });
+
+  // Drops two files (3 s images by default) onto `clips`; returns each written clip's start and track.
+  async function twoFileDrop(
+    clips: TimelineElement[],
+    placement: TimelineDropPlacement,
+    [names, tag] = [["one.png", "two.png"], "img"] as [string[], string],
+  ) {
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const uploadProjectFiles = vi.fn().mockResolvedValue(names);
+    const getDrop = renderDropHook(
+      rowSource(clips),
+      writeProjectFile,
+      clips,
+      undefined,
+      uploadProjectFiles,
+    );
+    const files = names.map((name) => new File([name], name));
+    await act(async () => {
+      await getDrop.file()(files, placement);
+    });
+    return writeProjectFile.mock.calls.map(([, written]) => {
+      const img = writtenClip(written as string, tag);
+      return [img.match(/data-start="([^"]*)"/)?.[1], img.match(/data-track-index="([^"]*)"/)?.[1]];
+    });
+  }
+
+  it("keeps a multi-file drop's clips off each other and off the row's clips", async () => {
+    const landed = await twoFileDrop([rowClip("a", 0, 4), rowClip("b", 8, 2)], {
+      start: 1,
+      track: 0,
+    });
+    // The first moves past a [0,4); the second is too long for [7,8) and goes after b.
+    expect(landed).toEqual([
+      ["4", "0"],
+      ["10", "0"],
+    ]);
+  });
+
+  it("puts a multi-file drop that opens a track back to back on that new track", async () => {
+    const landed = await twoFileDrop([rowClip("a", 0, 10)], {
+      start: 2,
+      track: 0,
+      insertRow: 0,
+      trackOrder: [0],
+    });
+    // Clip a moved down a row, so it no longer blocks the second file.
+    expect(landed).toEqual([
+      ["2", "0"],
+      ["5", "0"],
+    ]);
+  });
+
+  it("keeps a multi-file drop on the file track of the row it was dropped on", async () => {
+    const clips = [
+      rowClip("title", 0, 10, { track: 2 }),
+      rowClip("mid", 0, 1, { row: 1, track: 3 }),
+      rowClip("other", 0, 1, { row: 2, track: 5 }),
+    ];
+    // Row 0 is file track 2; the second file must not read that 2 back as row 2 (track 5).
+    expect(await twoFileDrop(clips, { start: 3, track: 0 })).toEqual([
+      ["10", "2"],
+      ["13", "2"],
+    ]);
+  });
+
+  it("reads a row's file track from every clip of the file, whether or not it names the file", async () => {
+    const unnamed = rowClip("unnamed", 0, 1, { row: 2, track: 0 });
+    const title = { ...rowClip("title", 0, 10), sourceFile: "index.html" };
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const getDrop = renderDropHook(rowSource([unnamed, title]), writeProjectFile, [unnamed, title]);
+    await act(async () => {
+      await getDrop()("pic.png", { start: 2, track: 0 }, 3);
+    });
+    const img = writtenClip(writeProjectFile.mock.calls[0][1] as string, "img");
+    expect(img).toContain('data-track-index="0"');
+    expect(img).toContain('data-start="10"');
+  });
+
+  it("keeps two audio files dropped on a visual row together, as a single one would go", async () => {
+    const clips = [
+      rowClip("title", 0, 10, { track: 1 }),
+      rowClip("music", 2, 3, { tag: "audio", row: 1, track: 0 }),
+    ];
+    const landed = await twoFileDrop(clips, { start: 12, track: 0 }, [["a.mp3", "b.mp3"], "audio"]);
+    // Audio length probing times out in this harness, so each file gets the 5 s default.
+    expect(landed).toEqual([
+      ["12", "0"],
+      ["17", "0"],
+    ]);
+  }, 30_000);
+
   it("refuses an asset drop before reading or writing when editing is blocked", async () => {
     const writeProjectFile = vi.fn().mockResolvedValue(undefined);
     const checkEditable = vi.fn(() => false);

package/src/hooks/useTimelineAssetDropOps.ts

@@ -30,14 +30,20 @@ import { extendRootDurationInSource } from "../utils/rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 import { selectAndRevealTimelineElement } from "../player/components/timelineDropReveal";
 
-/** The first uploaded file opens the new track (if asked); the rest land on the lane it landed on. */
+/** The first uploaded file opens the new track (if asked); each next one aims right after the previous. */
 function fileDropPlacement(
   index: number,
   next: { start: number; track: number },
   dropped: TimelineDropPlacement | undefined,
-  landedTrack: number | undefined,
+  previous: TimelineElement | undefined,
 ): TimelineDropPlacement {
-  return index === 0 ? { ...dropped, ...next } : { ...next, track: landedTrack ?? next.track };
+  if (index === 0) return { ...dropped, ...next };
+  return previous ? { start: previous.start + previous.duration, track: previous.track } : next;
+}
+
+interface DropGesture {
+  placed: TimelineElement[];
+  onNewTrack: boolean;
 }
 
 function timelineDropTarget(
@@ -90,7 +96,8 @@ export function useTimelineAssetDropOps({
       assetPath: string,
       placement: TimelineDropPlacement,
       durationOverride?: number,
-    ): Promise<number | undefined> => {
+      gesture: DropGesture = { placed: [], onNewTrack: false },
+    ): Promise<TimelineElement | undefined> => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
         return undefined;
@@ -121,28 +128,32 @@ export function useTimelineAssetDropOps({
         const resolvedAssetSrc = resolveTimelineAssetSrc(targetPath, assetPath);
 
         const resolvedTargetPath = targetPath || "index.html";
-        const relevantElements = timelineElements.filter(
-          (te) => (te.sourceFile || activeCompPath || "index.html") === resolvedTargetPath,
-        );
-        const newElementZIndex = Math.max(1, relevantElements.length + 1);
+        const fileElements = timelineElements
+          .filter((te) => (te.sourceFile || activeCompPath || "index.html") === resolvedTargetPath)
+          .map((te) => ({ ...te, sourceFile: resolvedTargetPath }));
+        const newElementZIndex = Math.max(1, fileElements.length + gesture.placed.length + 1);
+        const tag = kind === "image" ? "img" : kind;
 
         let newId = "";
         let track = 0;
+        let start = normalizedStart;
         const insertAsset = (originalContent: string) => {
           newId = buildTimelineAssetId(assetPath, collectHtmlIds(originalContent));
           const resolved = resolveDropTrack({
             source: originalContent,
-            // insertRow counts the rows the timeline shows, so plan against those.
-            elements: relevantElements,
+            // Rows and insertRow count the rows the timeline shows; a track this drop opened has no others.
+            elements: gesture.onNewTrack ? [] : fileElements,
+            placed: gesture.placed,
             placement,
             dropped: {
               id: newId,
-              tag: kind === "image" ? "img" : kind,
+              tag,
               start: normalizedStart,
               duration: normalizedDuration,
             },
           });
           track = resolved.track;
+          start = resolved.start;
           return extendRootDurationInSource(
             insertTimelineAssetIntoSource(
               resolved.source,
@@ -151,7 +162,7 @@ export function useTimelineAssetDropOps({
                 hfId: `hf-${generateId()}`,
                 assetPath: resolvedAssetSrc,
                 kind,
-                start: normalizedStart,
+                start,
                 duration: normalizedDuration,
                 track,
                 zIndex: newElementZIndex,
@@ -162,7 +173,7 @@ export function useTimelineAssetDropOps({
                 ),
               }),
             ),
-            normalizedStart + normalizedDuration,
+            start + normalizedDuration,
           );
         };
 
@@ -178,7 +189,15 @@ export function useTimelineAssetDropOps({
         selectAndRevealTimelineElement(deriveTimelineStoreKeyForDomId(newId, targetPath));
         forceReloadSdkSession?.();
         reloadPreview();
-        return track;
+        const lane = placement.insertRow == null ? placement.track : track;
+        return {
+          id: newId,
+          tag,
+          start,
+          duration: normalizedDuration,
+          track: lane,
+          authoredTrack: track,
+        };
       } catch (error) {
         const message =
           error instanceof Error ? error.message : "Failed to drop asset onto timeline";
@@ -234,15 +253,18 @@ export function useTimelineAssetDropOps({
         placement ?? { start: 0, track: 0 },
         durations,
       );
-      let landedTrack: number | undefined;
+      const gesture: DropGesture = { placed: [], onNewTrack: false };
       for (const [index, assetPath] of uploaded.entries()) {
         const next = placements[index] ?? placements[0];
-        const track = await dropAssetAt(
+        const clip = await dropAssetAt(
           assetPath,
-          fileDropPlacement(index, next, placement, landedTrack),
+          fileDropPlacement(index, next, placement, gesture.placed.at(-1)),
           durations[index],
+          gesture,
         );
-        if (index === 0) landedTrack = track;
+        if (!clip) continue;
+        gesture.placed.push(clip);
+        if (index === 0 && placement?.insertRow != null) gesture.onNewTrack = true;
       }
     },
     [

package/src/player/components/Timeline.rulerSeek.test.tsx

@@ -89,16 +89,16 @@ async function seekOnFirstTick(
 
 describe("Timeline ruler origin", () => {
   it.each([
-    ["keyframes shown", { showKeyframes: true }, false],
-    ["keyframes hidden", { showKeyframes: false }, false],
-    ["keyframes shown, arriving after mount", { showKeyframes: true }, true],
-    ["keyframes hidden, arriving after mount", { showKeyframes: false }, true],
+    ["keyframes shown", { showKeyframes: true }, false, 264],
+    ["keyframes hidden", { showKeyframes: false }, false, 80],
+    ["keyframes shown, arriving after mount", { showKeyframes: true }, true, 264],
+    ["keyframes hidden, arriving after mount", { showKeyframes: false }, true, 80],
   ])(
     "publishes where the ruler draws 0 s, and a press seeks by it (%s)",
-    async (_case, props, late) => {
+    async (_case, props, late, expected) => {
       const { time, tickTime, origin, published } = await seekOnFirstTick(props, late);
-      expect(origin).toBe("264px");
-      expect(published).toBe("264");
+      expect(origin).toBe(`${expected}px`);
+      expect(published).toBe(String(expected));
       expect(time).toBeCloseTo(tickTime, 1);
     },
   );

package/src/player/components/Timeline.showKeyframes.test.tsx

@@ -84,8 +84,34 @@ describe("Timeline showKeyframes", () => {
     expect((await mountKeyframed(false)).lanes).toBe(false);
   });
 
-  it("keeps each track's name in the header when keyframes are off", async () => {
+  it("opens the track-name column for a keyframed clip only while keyframes are shown", async () => {
     expect((await mountKeyframed()).named).toBe(true);
-    expect((await mountKeyframed(false)).named).toBe(true);
+    expect((await mountKeyframed(false)).named).toBe(false);
+  });
+
+  it("still opens the column for an audio group when keyframes are off", async () => {
+    usePlayerStore.setState({
+      duration: 10,
+      timelineReady: true,
+      gsapAnimations: new Map(),
+      elements: [
+        {
+          id: "vo",
+          label: "Voice",
+          tag: "audio",
+          start: 0,
+          duration: 4,
+          track: 0,
+          audioGroup: "g",
+        },
+      ],
+    });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () => root.render(<Timeline showKeyframes={false} />));
+    const corner = host.querySelector<HTMLElement>(".sticky.top-0.flex > div");
+    expect(corner?.style.width).toBe("264px");
+    act(() => root.unmount());
   });
 });

package/src/player/components/timelineClipDragCommit.test.ts

@@ -1187,73 +1187,26 @@ describe("commitDraggedClipMove", () => {
     });
   });
 
-  describe("magnetic main track on a track-insert", () => {
-    it("a top-gutter insert that renumbers to literal track 0 snaps its start to 0", () => {
-      // Sole visual clip sits on track 1 — the real main track (0) is genuinely
-      // empty. Dragging it into the top insert-gutter creates a new lane that
-      // normalizeToZones renumbers to literal 0, so the main-track rule must apply
-      // even though the preview never saw a literal-0 landing track.
+  describe("a clip landing on an empty main track keeps its released start", () => {
+    it("a top-gutter insert that renumbers to literal track 0 commits at the released start", () => {
       const elements = [el("v1", 1, 0, 5)];
       const { onMoveElements } = runClipMove(
         drag(elements[0], { previewStart: 8, previewTrack: 1, insertRow: 0 }),
         { elements, trackOrder: [1] },
       );
-      const map = editMap(onMoveElements.mock.calls[0][0]);
-      expect(map.v1).toEqual({ start: 0, track: 0 });
-    });
-
-    it("the z-sync candidate reflects the snapped start, not the raw previewStart", async () => {
-      // v1 snaps from previewStart 8 to 0 (see the test above). A foreign-file
-      // sibling at [2, 5) only overlaps the SNAPPED window [0, 5), never the
-      // raw [8, 13) — so a z-sync firing at all proves the candidate the
-      // stacking check reads from carries the snapped start.
-      const v1 = el("v1", 2, 0, 5);
-      const sibling = el("s", 1, 2, 3); // [2, 5) — same source file, same paint scope
-      const elements = [v1, sibling];
-      const onStackingPatches = vi.fn();
-      // v1 lands on lane 0, which paints above lane 1 (lower track paints higher),
-      // yet carries the lower z: a violation only while the two overlap in time.
-      commitDraggedClipMove(drag(v1, { previewStart: 8, previewTrack: 2, insertRow: 0 }), {
-        elements,
-        trackOrder: [1, 2],
-        updateElement: vi.fn(),
-        onMoveElement: vi.fn(),
-        onMoveElements: vi.fn(),
-        readZIndex: (element) => (element.key === "v1" ? 1 : 10),
-        onStackingPatches,
-      });
-      await flushMicrotasks();
-      expect(onStackingPatches).toHaveBeenCalledTimes(1);
+      expect(editMap(onMoveElements.mock.calls[0][0]).v1).toEqual({ start: 8, track: 0 });
     });
 
-    it("a plain lane change onto the empty main track snaps its committed start to 0", () => {
+    it("a plain lane change onto the empty main track commits at the released start", () => {
       const elements = [el("v1", 1, 0, 5)];
       const spies = runClipMove(drag(elements[0], { previewStart: 8, previewTrack: 0 }), {
         elements,
         trackOrder: [0, 1],
       });
-      expect(expectAtomicMoveMap(spies).v1).toEqual({ start: 0, track: 0 });
+      expect(expectAtomicMoveMap(spies).v1).toEqual({ start: 8, track: 0 });
     });
 
-    it("the z-sync candidate of a plain lane change carries the snapped start", async () => {
-      // The sibling [2, 5) overlaps v1 only at the snapped [0, 5), never at the raw [8, 13).
-      const v1 = el("v1", 2, 0, 5);
-      const sibling = el("s", 1, 2, 3);
-      const onStackingPatches = vi.fn();
-      commitDraggedClipMove(drag(v1, { previewStart: 8, previewTrack: 0 }), {
-        elements: [v1, sibling],
-        trackOrder: [0, 1, 2],
-        updateElement: vi.fn(),
-        onMoveElement: vi.fn(),
-        onMoveElements: vi.fn(),
-        readZIndex: (element) => (element.key === "v1" ? 1 : 10),
-        onStackingPatches,
-      });
-      await flushMicrotasks();
-      expect(onStackingPatches).toHaveBeenCalledTimes(1);
-    });
-
-    it("a top-gutter insert that pushes the old track-0 clip down snaps to the new track 0", () => {
+    it("a top-gutter insert that pushes the old track-0 clip down keeps the released start", () => {
       const oldMain = el("old", 0, 0, 3);
       const dragged = el("v1", 2, 0, 5);
       const { onMoveElements } = runClipMove(
@@ -1262,10 +1215,10 @@ describe("commitDraggedClipMove", () => {
       );
       const map = editMap(onMoveElements.mock.calls[0][0]);
       expect(map.old.track).toBe(1);
-      expect(map.v1).toEqual({ start: 0, track: 0 });
+      expect(map.v1).toEqual({ start: 8, track: 0 });
     });
 
-    it("an expanded child dragged with its host commits the HOST at 0", () => {
+    it("an expanded child dragged with its host onto the main track keeps the host's start", () => {
       for (const [hostStart, childStart] of [
         [30, 32],
         [20, 22],
@@ -1283,11 +1236,14 @@ describe("commitDraggedClipMove", () => {
             selectedKeys: new Set(["host", "child"]),
           },
         );
-        expect(editMap(onMoveElements.mock.calls[0][0]).host).toEqual({ start: 0, track: 0 });
+        expect(editMap(onMoveElements.mock.calls[0][0]).host).toEqual({
+          start: hostStart,
+          track: 0,
+        });
       }
     });
 
-    it("a multi-selection top-gutter insert does NOT snap (siblings key off the unsnapped start)", () => {
+    it("a multi-selection top-gutter insert keeps the grabbed clip's start", () => {
       const dragged = el("v1", 1, 0, 5);
       const sibling = el("v2", 1, 10, 5);
       const elements = [dragged, sibling];
@@ -1296,7 +1252,7 @@ describe("commitDraggedClipMove", () => {
         { elements, trackOrder: [1], selectedKeys: new Set(["v1", "v2"]) },
       );
       const map = editMap(onMoveElements.mock.calls[0][0]);
-      expect(map.v1.start).toBe(8); // unsnapped — multi-selection guard
+      expect(map.v1.start).toBe(8);
     });
   });
 });

package/src/player/components/timelineClipDragCommit.ts

@@ -5,7 +5,7 @@ import type { DraggedClipState } from "./useTimelineClipDrag";
 // value-import edge stays acyclic.
 import type { ZMirrorLaneMove } from "./timelineZMirror";
 import { classifyZone } from "./timelineZones";
-import { layoutAfterTrackInsert, resolveDragLandingStart } from "./timelineDragLanding";
+import { layoutAfterTrackInsert } from "./timelineDragLanding";
 import { computeStackingPatches, type StackingPatch } from "./timelineStackingSync";
 import {
   canMoveTimelineElement as canMoveElement,
@@ -19,6 +19,7 @@ import {
 import { runLaneZGesture } from "../../components/nle/zLaneGesture";
 import { refreshAfterDurableLaneMove } from "./timelineLaneMoveRefresh";
 import { authoredTrackForLane } from "./timelineAuthoredTrack";
+import { resolveGroupMovers } from "./timelineMultiDragPreview";
 
 type StartTrack = Pick<TimelineElement, "start" | "track">;
 export interface TimelineMoveEdit {
@@ -63,9 +64,9 @@ export interface DragCommitDeps {
    * the edited clip(s) get z-index patches so their canvas stacking matches lane
    * order (higher lane = on top) relative to time-overlapping clips — see
    * timelineStackingSync. Both deps must be supplied to engage; if either is
-   * absent the z-sync is skipped (pure time-moves and horizontal collision bumps
-   * never restack). `readZIndex` returns the clip's current z-index (from the
-   * live DOM inline style / computed; "auto" ⇒ 0).
+   * absent the z-sync is skipped (pure time-moves never restack). `readZIndex`
+   * returns the clip's current z-index (from the live DOM inline style / computed;
+   * "auto" ⇒ 0).
    */
   readZIndex?: (element: TimelineElement) => number;
   /**
@@ -191,41 +192,20 @@ function resolveMultiSelection(
   keys: ReadonlySet<string>;
   movedStart: (e: TimelineElement) => number;
 } | null {
-  const { elements, selectedKeys } = deps;
   const dragKey = keyOf(drag.element);
-  if (!selectedKeys || selectedKeys.size <= 1 || !selectedKeys.has(dragKey)) return null;
-  const keys = new Set(
-    [...selectedKeys].filter((k) => {
-      const el = elements.find((e) => keyOf(e) === k);
-      return el ? canMoveElement(el) : false;
-    }),
-  );
+  const movers = resolveGroupMovers(deps.elements, deps.selectedKeys, dragKey);
+  if (!movers) return null;
+  const keys = new Set(movers.map(keyOf));
   const delta = drag.previewStart - drag.element.start;
   const movedStart = (e: TimelineElement): number =>
     keyOf(e) === dragKey ? drag.previewStart : Math.max(0, round3(e.start + delta));
   return { keys, movedStart };
 }
 
-/**
- * Commit a finished clip drag.
- *
- * The lane model is CapCut-stable: a clip's display lane is its track, and editing
- * ONE clip must never re-lane or rewrite OTHER clips. Three outcomes:
- *
- * - **Pure time-move** (dragged clip keeps its lane, no insert): persist just the
- *   dragged clip's start (multi-selection shifts every selected clip in time).
- * - **Lane change / collision relocation** (the dragged clip's OWN lane changes,
- *   no new track): persist ONLY the dragged clip's start + lane. No other clip is
- *   touched. z is synced only when the gesture is a DELIBERATE vertical move
- *   (the pointer aimed at another lane) — a horizontal drag merely bumped to a
- *   free lane never restacks.
- * - **Track insert** (a new lane at a gap boundary): the dragged clip lands on
- *   the new lane and the clips at/below the insert are renumbered by +1 (the ONLY
- *   permitted multi-clip write) via a whole-set re-normalize; persisted atomically.
- */
+// A move writes the dragged clip's start (each moving clip's, in a group); a lane change also writes its lane and
+// re-lanes no other clip; only a new track renumbers the rows below it.
 // fallow-ignore-next-line complexity
-export function commitDraggedClipMove(rawDrag: DraggedClipState, deps: DragCommitDeps): void {
-  const drag = { ...rawDrag, previewStart: resolveDragLandingStart(rawDrag, deps) };
+export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDeps): void {
   const hostAlias = resolveExpandedHostAlias(drag, deps);
   if (hostAlias) {
     commitDraggedClipMove(hostAlias.drag, { ...deps, selectedKeys: hostAlias.selectedKeys });
@@ -236,11 +216,8 @@ export function commitDraggedClipMove(rawDrag: DraggedClipState, deps: DragCommi
   const dragKey = keyOf(drag.element);
   const isInsert = drag.insertRow != null;
   const laneChanged = drag.previewTrack !== drag.element.track;
-  // Deliberate VERTICAL gesture: the pointer aimed at a different lane, or at a
-  // gap boundary (insert). A plain HORIZONTAL drag whose target span is occupied
-  // gets the DRAGGED clip bumped to a free lane (previewTrack differs) while the
-  // pointer never left its lane (desiredTrack === element.track) — that is NOT a
-  // vertical move: it must neither rewrite other clips nor touch z.
+  // Deliberate VERTICAL gesture: the pointer aimed at a different lane, or at the
+  // empty space outside the rows (insert). Anything else never touches z.
   const aimTrack = drag.desiredTrack ?? drag.previewTrack;
   const isVertical = isInsert || aimTrack !== drag.element.track;
   const multi = resolveMultiSelection(drag, deps);
@@ -279,7 +256,7 @@ export function commitDraggedClipMove(rawDrag: DraggedClipState, deps: DragCommi
     return;
   }
 
-  // ── Lane change / collision relocation: persist ONLY the dragged clip ────────
+  // ── Lane change: persist ONLY the dragged clip ──────────────────────────────
   // CapCut invariant — one edit never re-lanes another clip. The dragged clip
   // takes its new lane (previewTrack); the rest of any selection shifts in time
   // only. Nothing else is written.