@hyperframes/studio 0.8.90 → 0.8.92

package/src/hooks/useTimelineEditing.ts

@@ -1,7 +1,7 @@
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
-import type { TimelineElement } from "../player";
-import { usePlayerStore } from "../player";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { toAuthoredStart, toCompositionTime } from "../player/store/timelineElement";
 import { useRazorSplit } from "./useRazorSplit";
 import { selectSplittableElements } from "../utils/timelineElementSplit";
 import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
@@ -187,12 +187,11 @@ export function useTimelineEditing({
         // other move — early-returning on !startChanged alone silently dropped
         // the file write, so the lane snapped back on reload.
         const trackChanged = updates.track !== element.track;
-
+        const authoredStart = toAuthoredStart(element, updates.start);
         if (startChanged || trackChanged) {
           const liveAttrs: Array<[string, string]> = [];
-          if (startChanged) {
-            liveAttrs.push(["data-start", formatTimelineAttributeNumber(updates.start)]);
-          }
+          if (startChanged)
+            liveAttrs.push(["data-start", formatTimelineAttributeNumber(authoredStart)]);
           if (trackChanged) {
             liveAttrs.push(["data-track-index", formatTimelineAttributeNumber(updates.track)]);
           }
@@ -224,7 +223,7 @@ export function useTimelineEditing({
           return buildTimelineMoveTimingPatch(
             original,
             target,
-            updates.start,
+            authoredStart,
             element.duration,
             track,
           );
@@ -258,7 +257,7 @@ export function useTimelineEditing({
               return sdkTimingPersist(
                 element.hfId,
                 targetPath,
-                { start: updates.start },
+                { start: authoredStart },
                 sdkSession,
                 {
                   editHistory: { recordEdit },
@@ -309,8 +308,9 @@ export function useTimelineEditing({
       element: TimelineElement,
       updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
     ) => {
+      const authoredStart = toAuthoredStart(element, updates.start);
       const liveAttrs: Array<[string, string]> = [
-        ["data-start", formatTimelineAttributeNumber(updates.start)],
+        ["data-start", formatTimelineAttributeNumber(authoredStart)],
         ["data-duration", formatTimelineAttributeNumber(updates.duration)],
       ];
       if (updates.playbackStart != null) {
@@ -350,8 +350,8 @@ export function useTimelineEditing({
           writeProjectFile,
           edit: {
             kind: "scale",
-            from: { start: element.start, duration: element.duration },
-            to: { start: updates.start, duration: updates.duration },
+            from: { start: toCompositionTime(element, element.start), duration: element.duration },
+            to: { start: toCompositionTime(element, updates.start), duration: updates.duration },
           },
         }).finally(() => invalidateGsapCache?.());
       const resizeFallback = () =>
@@ -363,7 +363,7 @@ export function useTimelineEditing({
           ? sdkTimingPersist(
               element.hfId,
               targetPath,
-              { start: updates.start, duration: updates.duration },
+              { start: authoredStart, duration: updates.duration },
               sdkSession,
               {
                 editHistory: { recordEdit },

package/src/hooks/useTimelineGroupEditing.ts

@@ -3,6 +3,7 @@
 import { useCallback, type MutableRefObject, type RefObject } from "react";
 import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
+import { toAuthoredStart, toCompositionTime } from "../player/store/timelineElement";
 import {
   cutoverCommittedOrThrow,
   sdkTimingBatchPersist,
@@ -244,7 +245,10 @@ export function useTimelineGroupEditing({
       if (changes.length === 0) return Promise.resolve();
       for (const change of changes) {
         const attrs: Array<[string, string]> = [
-          ["data-start", formatTimelineAttributeNumber(change.start)],
+          [
+            "data-start",
+            formatTimelineAttributeNumber(toAuthoredStart(change.element, change.start)),
+          ],
         ];
         if (change.track != null) {
           attrs.push(["data-track-index", formatTimelineAttributeNumber(change.track)]);
@@ -287,7 +291,9 @@ export function useTimelineGroupEditing({
         await options?.beforeTiming;
         const handledBySdk = await trySdkBatchPersist({
           changes,
-          sdkChanges: toSdkTimingChanges(changes, (change) => ({ start: change.start })),
+          sdkChanges: toSdkTimingChanges(changes, (change) => ({
+            start: toAuthoredStart(change.element, change.start),
+          })),
           eligible: changes.every((change) => change.track == null),
           needsExtension,
           label,
@@ -304,7 +310,7 @@ export function useTimelineGroupEditing({
                 buildTimelineMoveTimingPatch(
                   original,
                   target,
-                  change.start,
+                  toAuthoredStart(change.element, change.start),
                   change.element.duration,
                   change.track,
                 ),
@@ -375,7 +381,10 @@ export function useTimelineGroupEditing({
       if (changes.length === 0) return Promise.resolve();
       for (const change of changes) {
         const liveAttrs: Array<[string, string]> = [
-          ["data-start", formatTimelineAttributeNumber(change.start)],
+          [
+            "data-start",
+            formatTimelineAttributeNumber(toAuthoredStart(change.element, change.start)),
+          ],
           ["data-duration", formatTimelineAttributeNumber(change.duration)],
         ];
         if (change.playbackStart != null) {
@@ -402,7 +411,7 @@ export function useTimelineGroupEditing({
         const handledBySdk = await trySdkBatchPersist({
           changes,
           sdkChanges: toSdkTimingChanges(changes, (change) => ({
-            start: change.start,
+            start: toAuthoredStart(change.element, change.start),
             duration: change.duration,
           })),
           eligible: changes.every((change) => !resizeHasPlaybackStartAdjustment(change)),
@@ -453,9 +462,9 @@ export function useTimelineGroupEditing({
                 projectId,
                 changePath,
                 domId,
-                change.element.start,
+                toCompositionTime(change.element, change.element.start),
                 change.element.duration,
-                change.start,
+                toCompositionTime(change.element, change.start),
                 change.duration,
               );
             },

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

@@ -0,0 +1,111 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { Timeline } from "./Timeline";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
+import { usePlayerStore } from "../store/playerStore";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+installTimelineMountEnv();
+
+beforeAll(() => {
+  HTMLElement.prototype.setPointerCapture = vi.fn();
+  HTMLElement.prototype.releasePointerCapture = vi.fn();
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+const KEYFRAMED = new Map([
+  [
+    "card",
+    [
+      {
+        id: "card-position",
+        targetSelector: "#card",
+        method: "to" as const,
+        position: 0,
+        duration: 2,
+        properties: {},
+        propertyGroup: "position" as const,
+        keyframes: {
+          format: "percentage" as const,
+          keyframes: [
+            { percentage: 0, properties: { x: 0 } },
+            { percentage: 50, properties: { x: 100 } },
+          ],
+        },
+      },
+    ],
+  ],
+]);
+
+/** Presses the ruler exactly on the first drawn tick after 0 and returns its time and the seek. */
+async function seekOnFirstTick(
+  props: { showKeyframes?: boolean },
+  keyframesLate: boolean,
+  animations: typeof KEYFRAMED | Map<string, never[]> = KEYFRAMED,
+) {
+  usePlayerStore.setState({
+    duration: 10,
+    currentTime: 0,
+    timelineReady: true,
+    elements: [{ id: "card", label: "Hero card", tag: "div", start: 0, duration: 10, track: 0 }],
+    gsapAnimations: keyframesLate ? new Map() : animations,
+  });
+  const onSeek = vi.fn();
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  await act(async () => root.render(<Timeline {...props} onSeek={onSeek} />));
+  if (keyframesLate) await act(async () => usePlayerStore.setState({ gsapAnimations: animations }));
+
+  const viewport = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]")!;
+  viewport.getBoundingClientRect = () =>
+    ({ left: 0, top: 0, right: 900, bottom: 400, width: 900, height: 400 }) as DOMRect;
+  const label = host.querySelector<HTMLElement>('[data-timeline-grid-cell="major"] span')!;
+  const band = label.parentElement!.parentElement!;
+  const tick = band.querySelectorAll<HTMLElement>('[data-timeline-grid-cell="major"]')[1]!;
+  const [, mm, ss] = /(\d+):(\d+)/.exec(tick.textContent ?? "")!;
+  const tickTime = Number(mm) * 60 + Number(ss);
+  // The ruler's corner block is as wide as the origin the ruler draws 0 s at.
+  const origin = (band.previousElementSibling as HTMLElement).style.width;
+  const clientX = parseFloat(origin) + parseFloat(tick.style.left) + 0.5;
+  const at = { bubbles: true, clientX, clientY: 4, button: 0, pointerId: 1 };
+  await act(async () => tick.dispatchEvent(new PointerEvent("pointerdown", at)));
+  await act(async () => tick.dispatchEvent(new PointerEvent("pointerup", at)));
+  act(() => root.unmount());
+  return {
+    time: onSeek.mock.calls.at(-1)?.[0] as number | undefined,
+    tickTime,
+    origin,
+    published: viewport.getAttribute("data-timeline-content-origin"),
+  };
+}
+
+describe("Timeline ruler origin", () => {
+  it.each([
+    ["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, expected) => {
+      const { time, tickTime, origin, published } = await seekOnFirstTick(props, late);
+      expect(origin).toBe(`${expected}px`);
+      expect(published).toBe(String(expected));
+      expect(time).toBeCloseTo(tickTime, 1);
+    },
+  );
+
+  it("publishes the narrow origin when no clip needs the label column", async () => {
+    const { origin, published } = await seekOnFirstTick({}, false, new Map());
+    expect(origin).toBe("80px");
+    expect(published).toBe("80");
+  });
+});

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/TimelinePropertyLanes.test.tsx

@@ -189,7 +189,7 @@ describe("TimelinePropertyLanes", () => {
   // host-absolute start while its tweens are parsed from its own file and are
   // local to it. clipTimingStart is what brings the two into one frame.
   it("keeps an expanded sub-comp child's lane percentages inside the clip", () => {
-    const child = { start: 16.5, duration: 2, expandedParentStart: 16 };
+    const child = { start: 16.5, duration: 2, parentCompositionStart: 16 };
     const local = animation("pill-tween", "position", [
       { percentage: 0, properties: { x: 0 } },
       { percentage: 100, properties: { x: 100 } },

package/src/player/components/TimelineProvider.tsx

@@ -127,6 +127,7 @@ export interface TimelineViewportProps {
   ref: RefCallback<HTMLDivElement>;
   "data-timeline-scroll-viewport": boolean;
   "data-timeline-auto-scroll-left-inset": number;
+  "data-timeline-content-origin": number;
   tabIndex: number;
   className: string;
   onScroll: (event: UIEvent<HTMLDivElement>) => void;

package/src/player/components/TimelineTrackHeader.test.tsx

@@ -209,7 +209,7 @@ describe("TimelineTrackHeader", () => {
       start: 16.5,
       duration: 2,
       track: 0,
-      expandedParentStart: 16,
+      parentCompositionStart: 16,
       sourceFile: "scene.html",
     };
     const local: GsapAnimation = {

package/src/player/components/TimelineTypes.ts

@@ -15,7 +15,7 @@ export interface TimelineProps
   extends TimelineDropCallbacks, TimelineEditOverrides, TimelineStackingSyncProps {
   /** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
   sessionEpoch?: number;
-  onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
+  onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;
   onDrillDown?: (element: TimelineElement) => void;
   /** Picture only: takes no pointer input. Interactive content goes in renderClipOverlay. */
   renderClipContent?: (

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

@@ -315,7 +315,6 @@ describe("commitDraggedClipMove", () => {
     const child = {
       ...el("scene.html#title", 0.25, 12, 2),
       sourceFile: "scene.html",
-      expandedParentStart: 10,
       expandedHostKey: "host",
     };
     const { updateElement, onMoveElement, onMoveElements } = runClipMove(
@@ -338,7 +337,6 @@ describe("commitDraggedClipMove", () => {
     const child = {
       ...el("scene.html#title", 0.25, 12, 2),
       sourceFile: "scene.html",
-      expandedParentStart: 10,
       expandedHostKey: "host",
     };
     const { onMoveElement, onMoveElements } = runClipMove(
@@ -360,7 +358,6 @@ describe("commitDraggedClipMove", () => {
     const child = {
       ...el("scene.html#title", 0.25, 12, 2),
       sourceFile: "scene.html",
-      expandedParentStart: 10,
       expandedHostKey: "host",
     };
     const { onMoveElement, onMoveElements } = runClipMove(
@@ -382,7 +379,6 @@ describe("commitDraggedClipMove", () => {
     const child = {
       ...el("scene.html#title", 0.25, 12, 2),
       sourceFile: "scene.html",
-      expandedParentStart: 10,
       expandedHostKey: "host",
     };
     const { onMoveElement, onMoveElements } = runClipMove(
@@ -406,7 +402,6 @@ describe("commitDraggedClipMove", () => {
     const child = {
       ...el("scene.html#title", 0.25, 12, 2),
       sourceFile: "scene.html",
-      expandedParentStart: 10,
       expandedHostKey: "host",
     };
     const { onMoveElement, onMoveElements } = runClipMove(
@@ -1192,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 });
-    });
-
-    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);
+      expect(expectAtomicMoveMap(spies).v1).toEqual({ start: 8, track: 0 });
     });
 
-    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(
@@ -1267,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],
@@ -1279,7 +1227,6 @@ describe("commitDraggedClipMove", () => {
         const child: TimelineElement = {
           ...el("child", 2, childStart, 4),
           expandedHostKey: "host",
-          expandedParentStart: hostStart,
         };
         const { onMoveElements } = runClipMove(
           drag(child, { previewStart: childStart, previewTrack: 0 }),
@@ -1289,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];
@@ -1302,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);
     });
   });
 });
@@ -1399,12 +1349,10 @@ describe("commitZMirrorLaneMove", () => {
     const child1 = {
       ...el("child-1", 0.25, 0, 5),
       sourceFile: "scene.html",
-      expandedParentStart: 0,
     };
     const child2 = {
       ...el("child-2", 0.5, 0, 5),
       sourceFile: "scene.html",
-      expandedParentStart: 0,
     };
     const b = { ...el("b", 1, 0, 5), sourceFile: "index.html" };
     const t = { ...el("t", 2, 0, 5), sourceFile: "index.html" };
@@ -1516,6 +1464,24 @@ describe("commitZMirrorLaneMove", () => {
   });
 });
 
+describe("persistMoveEdits: a nested row dropped before its host", () => {
+  it("lands at the host's start in the store and in the persist", async () => {
+    const logo = { ...el("logo", 0, 5, 5, "div"), parentCompositionStart: 2 };
+    const updateElement = vi.fn();
+    const onMoveElements = vi.fn(async (_edits: TimelineMoveEdit[]) => {});
+    await persistMoveEdits([{ element: logo, updates: { start: 1, track: 0 } }], {
+      elements: [logo],
+      trackOrder: [0],
+      updateElement,
+      onMoveElements,
+    });
+    expect(updateElement).toHaveBeenCalledWith("logo", { start: 2, track: 0 });
+    expect(onMoveElements.mock.calls[0]?.[0]).toEqual([
+      { element: logo, updates: { start: 2, track: 0 } },
+    ]);
+  });
+});
+
 describe("persistMoveEdits convergence", () => {
   it("reasserts a saved lane after a stale runtime sync", async () => {
     const clip = { ...el("headline", 2, 0.5, 4.9), authoredTrack: 2 };

package/src/player/components/timelineClipDragCommit.ts

@@ -1,10 +1,11 @@
 import type { TimelineElement } from "../store/playerStore";
+import { clampToHostStart } from "../store/timelineElement";
 import type { DraggedClipState } from "./useTimelineClipDrag";
 // Type-only: erased at runtime, so the timelineZMirror → timelineClipDragCommit
 // 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,
@@ -18,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 {
@@ -62,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;
   /**
@@ -107,6 +109,10 @@ export function persistMoveEdits(
   coalesceMs?: number,
 ): Promise<boolean> {
   if (edits.length === 0) return Promise.resolve(true);
+  edits = edits.map((e) => {
+    const start = clampToHostStart(e.element, e.updates.start);
+    return start === e.updates.start ? e : { ...e, updates: { ...e.updates, start } };
+  });
   const { updateElement, onMoveElement, onMoveElements } = deps;
   if (!onMoveElements) {
     console.warn(
@@ -186,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 });
@@ -231,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);
@@ -274,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.