@hyperframes/studio 0.8.48 → 0.8.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.48",
+  "version": "0.8.49",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.48",
-    "@hyperframes/parsers": "0.8.48",
-    "@hyperframes/player": "0.8.48",
-    "@hyperframes/studio-server": "0.8.48",
-    "@hyperframes/sdk": "0.8.48"
+    "@hyperframes/parsers": "0.8.49",
+    "@hyperframes/studio-server": "0.8.49",
+    "@hyperframes/player": "0.8.49",
+    "@hyperframes/sdk": "0.8.49",
+    "@hyperframes/core": "0.8.49"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.48"
+    "@hyperframes/producer": "0.8.49"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/useBlockHandlers.ts

@@ -6,6 +6,7 @@ import { useCallback, useMemo, useRef, useState } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { addBlockToProject } from "../utils/blockInstaller";
+import { selectAndRevealTimelineElement } from "../player/components/timelineDropReveal";
 import type { BlockParam } from "@hyperframes/core/registry";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
@@ -148,7 +149,9 @@ export function useBlockHandlers({
           previewIframe: previewIframeRef.current,
           currentTime: usePlayerStore.getState().currentTime,
         }),
-      );
+      ).then((result) => {
+        if (result) selectAndRevealTimelineElement(result.hostKey);
+      });
     },
     [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );
@@ -184,7 +187,9 @@ export function useBlockHandlers({
           previewIframe: previewIframeRef.current,
           currentTime: usePlayerStore.getState().currentTime,
         }),
-      );
+      ).then((result) => {
+        if (result) selectAndRevealTimelineElement(result.hostKey);
+      });
     },
     [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );

package/src/hooks/useTimelineAssetDropOps.test.tsx

@@ -4,12 +4,14 @@ import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
 import { mountReactHarness } from "./domSelectionTestHarness";
+import { usePlayerStore } from "../player/store/playerStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
   document.body.innerHTML = "";
   vi.unstubAllGlobals();
+  usePlayerStore.getState().reset();
 });
 
 type DropFn = ReturnType<typeof useTimelineAssetDropOps>["handleTimelineAssetDrop"];
@@ -69,4 +71,17 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     const [, written] = writeProjectFile.mock.calls[0] as [string, string];
     expect(written).toContain('data-duration="10"');
   });
+
+  it("selects and reveals the newly dropped clip", async () => {
+    const source =
+      '<main data-composition-id="scene" data-duration="10" data-width="1920" data-height="1080"></main>';
+    const writeProjectFile = vi.fn().mockResolvedValue(undefined);
+    const getDrop = renderDropHook(source, writeProjectFile);
+
+    await act(async () => {
+      await getDrop()("clip.mp4", { start: 1, track: 0 }, 2);
+    });
+
+    expect(usePlayerStore.getState().selectedElementId).toBe("index.html#clip");
+  });
 });

package/src/hooks/useTimelineAssetDropOps.ts

@@ -21,7 +21,8 @@ import { formatTimelineAttributeNumber } from "./timelineEditingHelpers";
 import { readFileContent } from "./timelineTimingSync";
 import { commitTimelineCompositionInsertion } from "../utils/timelineCompositionInsert";
 import { extendRootDurationInSource } from "../utils/rootDuration";
-import { usePlayerStore } from "../player";
+import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
+import { selectAndRevealTimelineElement } from "../player/components/timelineDropReveal";
 
 interface UseTimelineAssetDropOpsOptions {
   projectIdRef: MutableRefObject<string | null>;
@@ -121,6 +122,7 @@ export function useTimelineAssetDropOps({
           recordEdit,
         });
 
+        selectAndRevealTimelineElement(deriveTimelineStoreKeyForDomId(newId, targetPath));
         forceReloadSdkSession?.();
         reloadPreview();
       } catch (error) {
@@ -194,7 +196,7 @@ export function useTimelineAssetDropOps({
           writeFile: writeProjectFile,
           recordEdit,
           observeVersion: observeProjectFileVersion,
-          selectHost: (key) => usePlayerStore.getState().setSelectedElementId(key),
+          selectHost: selectAndRevealTimelineElement,
           resync: forceReloadSdkSession,
           refresh: reloadPreview,
         });

package/src/hooks/useTimelineSelectionPreviewSync.test.tsx

@@ -175,7 +175,70 @@ describe("useTimelineSelectionPreviewSync", () => {
     harness.cleanup();
   });
 
-  it("warns once while retrying a timeline selection after preview refreshes", async () => {
+  it("does not clear the selection when the selected clip is not in timelineElements yet", async () => {
+    // A freshly-dropped clip is selected before the reload that adds it to
+    // timelineElements has completed. Bailing quietly here (like the
+    // DOM-node-not-ready case above) lets the later effect run, once the
+    // element exists, apply the selection instead of wiping it.
+    const { timelineElements } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async () => null);
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: "clip-3",
+      selectedElementIds: new Set(["clip-3"]),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound,
+    });
+
+    // Still within the retry grace window: quiet, not yet a warning.
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
+    expect(applyDomSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("does not shrink a pasted or duplicated group's selection when only some members have appeared yet", async () => {
+    // Paste/duplicate of a group selects every new id up front; one member
+    // (clip-1) is already in timelineElements, the other (a fresh paste/dup
+    // target, "clip-3") is not yet. Applying only the resolved member would
+    // silently drop the rest of the group from the store.
+    const { firstSelection, timelineElements, selectionById } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) => {
+      return selectionById.get(element.id) ?? firstSelection;
+    });
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: "clip-1",
+      selectedElementIds: new Set(["clip-1", "clip-3"]),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound,
+    });
+
+    // Still within the retry grace window: quiet, not yet a warning.
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
+    expect(applyDomSelection).not.toHaveBeenCalled();
+    expect(applyMarqueeSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("stays quiet through retries and resolves once the preview refreshes", async () => {
     const { secondSelection, timelineElements } = makeSyncFixture();
     const applyDomSelection = vi.fn();
     const applyMarqueeSelection = vi.fn();
@@ -199,7 +262,7 @@ describe("useTimelineSelectionPreviewSync", () => {
       onSelectionNotFound,
     });
 
-    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
     expect(applyDomSelection).not.toHaveBeenCalled();
 
     await harness.rerender({
@@ -214,7 +277,7 @@ describe("useTimelineSelectionPreviewSync", () => {
       onSelectionNotFound,
     });
 
-    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
 
     previewReady = true;
     await harness.rerender({
@@ -230,6 +293,155 @@ describe("useTimelineSelectionPreviewSync", () => {
     });
 
     expect(applyDomSelection).toHaveBeenCalledWith(secondSelection);
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("degrades to the resolvable subset once a group member never resolves", async () => {
+    // clip-2 is a permanent hold-out (deleted out of band, a stale id, or
+    // anything else that will never build a selection). Retrying forever
+    // would leave the whole group's selection stuck; after a few attempts,
+    // apply the members that did resolve instead.
+    const { firstSelection, timelineElements } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) =>
+      element.id === "clip-1" ? firstSelection : null,
+    );
+    const selectedElementIds = new Set(["clip-1", "clip-2"]);
+    const harness = renderHarness();
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      await harness.rerender({
+        selectedElementId: "clip-1",
+        selectedElementIds,
+        timelineElements: [...timelineElements],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+        buildDomSelectionForTimelineElement,
+        applyDomSelection,
+        applyMarqueeSelection,
+        onSelectionNotFound,
+      });
+    }
+
+    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+    expect(applyDomSelection).toHaveBeenCalledWith(firstSelection);
+    expect(applyMarqueeSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("gives a fresh retry budget after deselecting a permanently-unresolvable selection", async () => {
+    // Same permanent hold-out as the test above, but the user deselects and
+    // reselects the exact same group afterward. Without resetting the retry
+    // budget on deselect, reselecting the same key resumes an already-
+    // exhausted count and degrades on the very first attempt with no warning.
+    const { firstSelection, timelineElements } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) =>
+      element.id === "clip-1" ? firstSelection : null,
+    );
+    const selectedElementIds = new Set(["clip-1", "clip-2"]);
+    const harness = renderHarness();
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      await harness.rerender({
+        selectedElementId: "clip-1",
+        selectedElementIds,
+        timelineElements: [...timelineElements],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+        buildDomSelectionForTimelineElement,
+        applyDomSelection,
+        applyMarqueeSelection,
+        onSelectionNotFound,
+      });
+    }
+    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+
+    await harness.rerender({
+      selectedElementId: null,
+      selectedElementIds: new Set(),
+      timelineElements: [...timelineElements],
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound,
+    });
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      await harness.rerender({
+        selectedElementId: "clip-1",
+        selectedElementIds,
+        timelineElements: [...timelineElements],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+        buildDomSelectionForTimelineElement,
+        applyDomSelection,
+        applyMarqueeSelection,
+        onSelectionNotFound,
+      });
+    }
+
+    expect(onSelectionNotFound).toHaveBeenCalledTimes(2);
+    harness.cleanup();
+  });
+
+  it("resolves every member of a large selection concurrently, not one network round trip at a time", async () => {
+    const elementCount = 30;
+    const timelineElements: TimelineElement[] = Array.from({ length: elementCount }, (_, i) => ({
+      id: `clip-${i}`,
+      domId: `clip-${i}`,
+      tag: "div",
+      start: i,
+      duration: 1,
+      track: i % 4,
+    }));
+    const selectionById = new Map(
+      timelineElements.map((el) => {
+        const domEl = document.createElement("div");
+        domEl.id = el.id;
+        return [el.id, makeSelection(el.id, domEl)];
+      }),
+    );
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) => {
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      // Stands in for the network round trip: yields once so every member's
+      // call has a chance to start before any of them finish.
+      await Promise.resolve();
+      inFlight -= 1;
+      return selectionById.get(element.id) ?? null;
+    });
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: timelineElements[0].id,
+      selectedElementIds: new Set(timelineElements.map((el) => el.id)),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound: vi.fn(),
+    });
+
+    expect(buildDomSelectionForTimelineElement).toHaveBeenCalledTimes(elementCount);
+    // A sequential loop never has more than one call in flight at once; this
+    // asserts every member's probe started before any of them resolved.
+    expect(maxInFlight).toBe(elementCount);
+    expect(applyMarqueeSelection).toHaveBeenCalledOnce();
+    expect(applyMarqueeSelection.mock.calls[0]?.[0]).toHaveLength(elementCount);
     harness.cleanup();
   });
 });

package/src/hooks/useTimelineSelectionPreviewSync.ts

@@ -3,6 +3,7 @@ import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { resolveTimelineIdForSelection } from "../utils/studioHelpers";
 import { logSelect } from "../utils/selectDebug";
+import { recordRetryAttempt, type RetryBudgetState } from "../utils/retryBudget";
 
 interface UseTimelineSelectionPreviewSyncParams {
   selectedElementId: string | null;
@@ -27,6 +28,12 @@ interface UseTimelineSelectionPreviewSyncParams {
   onSelectionNotFound: () => void;
 }
 
+// A member still resolving (a just-dropped/pasted/duplicated clip, or a preview
+// still reloading) heals within a few retries. One that never will (deleted out
+// of band, a stale id) would otherwise bail forever; past this cap, apply
+// whatever did resolve instead of leaving the group selection stuck.
+const MAX_UNRESOLVED_SYNC_RETRIES = 3;
+
 function orderSelectedIds(ids: Set<string>, anchor: string | null): string[] {
   const ordered = [...ids];
   if (!anchor || !ids.has(anchor)) return ordered;
@@ -63,6 +70,36 @@ function anchorIsOutsideSelection(anchor: string | null, selectedIds: string[]):
   return anchor !== null && !selectedIds.includes(anchor);
 }
 
+async function resolveSelectionsForIds(
+  ids: string[],
+  timelineElements: TimelineElement[],
+  buildDomSelectionForTimelineElement: UseTimelineSelectionPreviewSyncParams["buildDomSelectionForTimelineElement"],
+): Promise<DomEditSelection[]> {
+  // Each element's resolution fires its own network probe; a selection of N
+  // members used to pay N sequential round trips here instead of one.
+  const elements = ids
+    .map((id) => timelineElements.find((item) => (item.key ?? item.id) === id))
+    .filter((element): element is TimelineElement => Boolean(element));
+  const resolved = await Promise.all(
+    elements.map((element) => buildDomSelectionForTimelineElement(element)),
+  );
+  return resolved.filter((selection): selection is DomEditSelection => Boolean(selection));
+}
+
+function applyResolvedSelections(
+  selections: DomEditSelection[],
+  applyDomSelection: UseTimelineSelectionPreviewSyncParams["applyDomSelection"],
+  applyMarqueeSelection: UseTimelineSelectionPreviewSyncParams["applyMarqueeSelection"],
+): void {
+  if (selections.length === 0) {
+    applyDomSelection(null, { revealPanel: false });
+  } else if (selections.length === 1) {
+    applyDomSelection(selections[0]);
+  } else {
+    applyMarqueeSelection(selections, false);
+  }
+}
+
 export function useTimelineSelectionPreviewSync({
   selectedElementId,
   selectedElementIds,
@@ -84,6 +121,7 @@ export function useTimelineSelectionPreviewSync({
   const domEditGroupSelectionsRef = useRef(domEditGroupSelections);
   const lastSyncedSelectedKeyRef = useRef("");
   const missingSelectionKeyRef = useRef("");
+  const unresolvedAttemptsRef = useRef<RetryBudgetState<string>>({ id: "", count: 0 });
   domEditSelectionRef.current = domEditSelection;
   domEditGroupSelectionsRef.current = domEditGroupSelections;
 
@@ -109,6 +147,10 @@ export function useTimelineSelectionPreviewSync({
 
     if (selectedIds.length === 0) {
       missingSelectionKeyRef.current = "";
+      // A deselect is the one unambiguous "new attempt" signal: without it, reselecting the
+      // same permanently-unresolvable id later picks up an already-exhausted retry budget
+      // and skips straight to the degraded fallback instead of getting a fresh grace window.
+      unresolvedAttemptsRef.current = { id: "", count: 0 };
       // The timeline holds nothing, so the canvas is about to hold nothing either.
       // This is the path that silently drops a selection the user can still see.
       logSelect("timeline-empty", {
@@ -134,46 +176,35 @@ export function useTimelineSelectionPreviewSync({
       onSelectionNotFound();
     };
     const syncSelection = async () => {
-      const selections: DomEditSelection[] = [];
-      let resolvableCount = 0;
-      for (const id of selectedIds) {
-        const element = timelineElements.find((item) => (item.key ?? item.id) === id);
-        if (!element) continue;
-        resolvableCount += 1;
-        const selection = await buildDomSelectionForTimelineElement(element);
-        if (selection) selections.push(selection);
-      }
+      const selections = await resolveSelectionsForIds(
+        selectedIds,
+        timelineElements,
+        buildDomSelectionForTimelineElement,
+      );
       if (cancelled) return;
-      // The store is the source of truth: applying a partial set would write that
-      // shrunk set back and silently drop the members whose DOM node was not ready.
-      // Bail instead; a later effect run (on timelineElements/DOM change) applies the
-      // full set once every resolvable member has a live node.
-      if (selections.length < resolvableCount) {
-        warnSelectionMissingOnce();
-        // Bailing keeps whatever the canvas already held, and Delete acts on the
-        // canvas first — so an anchor pointing OUTSIDE this selection is an
-        // element the user is no longer looking at, and deleting it is the
-        // damage. Only that goes: a member still resolving has no anchor of its
-        // own here and is left for the later run. Quietly, because announcing
-        // the clear would deselect the clip that was just picked.
-        if (anchorIsOutsideSelection(currentAnchor, selectedIds)) {
-          applyDomSelection(null, { revealPanel: false, announce: false });
+      if (selections.length < selectedIds.length) {
+        if (recordRetryAttempt(unresolvedAttemptsRef, selectedKey, MAX_UNRESOLVED_SYNC_RETRIES)) {
+          // Still within the retry grace window: stay quiet (warn only once
+          // exhausted, below). Delete acts on the canvas first, so only an
+          // anchor OUTSIDE this selection is cleared here, quietly.
+          if (anchorIsOutsideSelection(currentAnchor, selectedIds)) {
+            applyDomSelection(null, { revealPanel: false, announce: false });
+          }
+          return;
         }
-        return;
+        // Budget exhausted: warn once (missingSelectionKeyRef dedupes further
+        // reruns of this same still-unresolved key) and apply whatever did resolve.
+        warnSelectionMissingOnce();
+      } else {
+        unresolvedAttemptsRef.current = { id: "", count: 0 };
+        missingSelectionKeyRef.current = "";
       }
-      missingSelectionKeyRef.current = "";
       logSelect("timeline-sync", {
         wanted: selectedIds.length,
         had: currentIds.length,
         resolved: selections.length,
       });
-      if (selections.length === 0) {
-        applyDomSelection(null, { revealPanel: false });
-      } else if (selections.length === 1) {
-        applyDomSelection(selections[0]);
-      } else {
-        applyMarqueeSelection(selections, false);
-      }
+      applyResolvedSelections(selections, applyDomSelection, applyMarqueeSelection);
     };
 
     void syncSelection();

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

@@ -1223,6 +1223,120 @@ describe("commitDraggedClipMove", () => {
       expect(onStackingPatches).not.toHaveBeenCalled();
     });
   });
+
+  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.
+      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);
+    });
+
+    it("a plain lane change onto the empty main track snaps its committed start to 0", () => {
+      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);
+    });
+
+    it("a top-gutter insert that pushes the old track-0 clip down snaps to the new track 0", () => {
+      const oldMain = el("old", 0, 0, 3);
+      const dragged = el("v1", 2, 0, 5);
+      const { onMoveElements } = runClipMove(
+        drag(dragged, { previewStart: 8, previewTrack: 2, insertRow: 0 }),
+        { elements: [oldMain, dragged], trackOrder: [0, 2] },
+      );
+      const map = editMap(onMoveElements.mock.calls[0][0]);
+      expect(map.old.track).toBe(1);
+      expect(map.v1).toEqual({ start: 0, track: 0 });
+    });
+
+    it("an expanded child dragged with its host commits the HOST at 0", () => {
+      for (const [hostStart, childStart] of [
+        [30, 32],
+        [20, 22],
+      ]) {
+        const host = el("host", 1, hostStart, 10);
+        const child: TimelineElement = {
+          ...el("child", 2, childStart, 4),
+          expandedHostKey: "host",
+          expandedParentStart: hostStart,
+        };
+        const { onMoveElements } = runClipMove(
+          drag(child, { previewStart: childStart, previewTrack: 0 }),
+          {
+            elements: [host, child],
+            trackOrder: [0, 1, 2],
+            selectedKeys: new Set(["host", "child"]),
+          },
+        );
+        expect(editMap(onMoveElements.mock.calls[0][0]).host).toEqual({ start: 0, track: 0 });
+      }
+    });
+
+    it("a multi-selection top-gutter insert does NOT snap (siblings key off the unsnapped start)", () => {
+      const dragged = el("v1", 1, 0, 5);
+      const sibling = el("v2", 1, 10, 5);
+      const elements = [dragged, sibling];
+      const { onMoveElements } = runClipMove(
+        drag(dragged, { previewStart: 8, previewTrack: 1, insertRow: 0 }),
+        { 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
+    });
+  });
 });
 
 describe("commitZMirrorLaneMove", () => {