@hyperframes/studio 0.8.47 → 0.8.49

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/index.ts

@@ -27,6 +27,16 @@ export { FileTree } from "./components/editor/FileTree";
 // App
 export { StudioApp } from "./App";
 
+// Ask-agent flow
+export { AskAgentModal } from "./components/AskAgentModal";
+export type { AskAgentModalProps } from "./components/AskAgentModal";
+export type { AgentModalAnchorPoint } from "./utils/studioHelpers";
+export {
+  buildPickerAgentPrompt,
+  buildPickerAgentContextPreview,
+} from "./components/editor/domEditingAgentPrompt";
+export type { AgentPromptElementInfo } from "./components/editor/domEditingAgentPrompt";
+
 // Hooks
 export { useElementPicker } from "./hooks/useElementPicker";
 export type { PickedElement } from "./hooks/useElementPicker";

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

@@ -166,7 +166,6 @@ describe("Timeline provider boundary", () => {
           scrollTop: 0,
           contentOrigin: GUTTER,
           pixelsPerSecond: 100,
-          duration: 60,
           trackOrder: [0],
         },
         1132,
@@ -282,7 +281,6 @@ describe("Timeline provider boundary", () => {
           scrollTop: 0,
           contentOrigin: LABEL_COL_W + GUTTER,
           pixelsPerSecond: 100,
-          duration: 60,
           trackOrder: [0],
         },
         100 + LABEL_COL_W + GUTTER + 1000,
@@ -1263,7 +1261,6 @@ describe("resolveTimelineAssetDrop", () => {
           scrollTop: 0,
           contentOrigin: GUTTER,
           pixelsPerSecond: 100,
-          duration: 10,
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },
@@ -1285,7 +1282,6 @@ describe("resolveTimelineAssetDrop", () => {
           scrollTop: 0,
           contentOrigin: GUTTER,
           pixelsPerSecond: 100,
-          duration: 10,
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },

package/src/player/components/Timeline.tsx

@@ -238,7 +238,6 @@ export const Timeline = memo(function Timeline({
   const assetDrop = useTimelineAssetDrop({
     scrollRef,
     ppsRef,
-    durationRef,
     trackOrderRef,
     rowGeometryRef,
     contentOrigin,

package/src/player/components/TimelineAutomationLaneSlot.tsx

@@ -13,7 +13,7 @@ import { TimelineAutomationLane } from "./TimelineAutomationLane";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { getTimelineLaneTop } from "./timelineLayout";
 import { groupAutomationLanes, isCarveLane } from "./automationLaneData";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isAudioOrVideoTimelineElement } from "../../utils/timelineInspector";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
 import type { UseAutomationLanesResult } from "./useAutomationLanes";
@@ -174,7 +174,9 @@ export function TimelineAutomationLaneSlot({
   currentTime,
   beatTimes,
 }: TimelineAutomationLaneSlotProps) {
-  const clips = elements.filter(isAudioTimelineElement);
+  // Broader than a raw-attribute check — a clip mid-edit (see the stale-
+  // selection test) has lanes in its live binding before the attribute commits.
+  const clips = elements.filter(isAudioOrVideoTimelineElement);
   const rowsByClip = new Map<string, ClipLaneRow[]>();
   groupAutomationLanes(clips).forEach((group, rowIndex) => {
     for (const entry of group.entries) {

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

@@ -1275,7 +1275,8 @@ describe("TimelineClipDiamonds", () => {
     expect(host.querySelectorAll("[data-keyframe-ease-segment]").length).toBe(2);
     const ease = host.querySelector<HTMLButtonElement>("[data-keyframe-ease-button]")!;
     expect(ease.getAttribute("aria-label")).toBe("Edit none easing after 10s");
-    expect(ease.classList.contains("opacity-0")).toBe(true);
+    expect(ease.getAttribute("title")).toBe("Edit none easing");
+    expect(ease.classList.contains("opacity-40")).toBe(true);
     act(() => ease.click());
     expect(onSelectSegment).toHaveBeenCalledOnce();
     expect(usePlayerStore.getState().requestedSeekTime).toBeNull();
@@ -1318,6 +1319,17 @@ describe("TimelineClipDiamonds", () => {
     act(() => root.unmount());
   });
 
+  it("keeps the ease button hover-only on a segment too narrow to show it at rest", () => {
+    // Same narrow clip as above: showing the button at rest here would sit on
+    // top of both diamonds instead of clear of them.
+    const { host, root } = renderSegmentLane(false, 40);
+    const ease = host.querySelector<HTMLButtonElement>("[data-keyframe-ease-button]");
+
+    expect(ease?.classList.contains("opacity-0")).toBe(true);
+    expect(ease?.classList.contains("opacity-40")).toBe(false);
+    act(() => root.unmount());
+  });
+
   it("hides the inline ease button on a segment with no source animation id", () => {
     // A runtime-scanned keyframe has no animationId, so there is no tween to
     // target; the segment ending on it must not render a (dead) ease button.

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { hasRoomForRestingEase } from "./TimelineDiamondConnectors";
+
+describe("hasRoomForRestingEase", () => {
+  it("is false just under the threshold", () => {
+    expect(hasRoomForRestingEase(23)).toBe(false);
+  });
+
+  it("is true exactly at the threshold", () => {
+    expect(hasRoomForRestingEase(24)).toBe(true);
+  });
+
+  it("is true well above the threshold", () => {
+    expect(hasRoomForRestingEase(78)).toBe(true);
+  });
+});

package/src/player/components/TimelineDiamondConnectors.tsx

@@ -13,6 +13,17 @@ export interface TimelineDiamondMarker {
   visualSize: number;
 }
 
+const EASE_BUTTON_PX = 16;
+const EASE_BUTTON_REST_GAP_PX = 4;
+
+/** Whether a segment is wide enough to show the ease button at rest (button
+ * box plus a clear gap each side) without overlapping either neighboring
+ * diamond. 24 coincides with roomForFullTarget's threshold below but is a
+ * separate constraint; don't assume changing one keeps the other in sync. */
+export function hasRoomForRestingEase(connectorWidth: number): boolean {
+  return connectorWidth >= EASE_BUTTON_PX + EASE_BUTTON_REST_GAP_PX * 2;
+}
+
 /**
  * The line between each pair of adjacent diamonds, plus the ease control that
  * sits at the segment's midpoint. Split out of TimelineClipDiamonds only to keep
@@ -96,6 +107,7 @@ export function TimelineDiamondConnectors({
                 // the hit test and steal their clicks at fit zoom. Grow the
                 // target only where the room exists.
                 roomForFullTarget={connectorWidth >= 24}
+                restingVisible={hasRoomForRestingEase(connectorWidth)}
                 onSelectSegment={onSelectSegment}
               />
             )}
@@ -133,6 +145,7 @@ function SegmentEaseControl({
   rovingTargetId,
   afterLabel,
   roomForFullTarget,
+  restingVisible,
   onSelectSegment,
 }: {
   left: number;
@@ -146,6 +159,9 @@ function SegmentEaseControl({
   /** Time label of the keyframe this segment starts at, for the accessible name. */
   afterLabel: string;
   roomForFullTarget: boolean;
+  /** Whether the segment is wide enough to show the button at rest; too
+   * narrow and it stays hover-only so it doesn't smear over the diamonds. */
+  restingVisible: boolean;
   onSelectSegment: (target: TimelineKeyframeTarget) => void;
 }) {
   // The ease button sits dead centre of its segment, which on a two-keyframe clip
@@ -187,7 +203,7 @@ function SegmentEaseControl({
         // for that overlay the button keeps its 16x16 hit area, which is WCAG's
         // target-spacing exception: the neighbouring diamonds are themselves the
         // reason it cannot grow, and stealing their clicks is the worse failure.
-        className={`absolute flex items-center justify-center rounded opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100 ${roomForFullTarget ? "before:absolute before:left-1/2 before:top-1/2 before:h-6 before:w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']" : ""}`}
+        className={`absolute flex items-center justify-center rounded ${restingVisible ? "opacity-40" : "opacity-0"} transition-opacity hover:opacity-100 group-hover:opacity-100 focus-visible:opacity-100 ${roomForFullTarget ? "before:absolute before:left-1/2 before:top-1/2 before:h-6 before:w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']" : ""}`}
         style={{
           left: "50%",
           top: "50%",

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

@@ -406,7 +406,7 @@ describe("TimelinePropertyLanes", () => {
     expect(laneDiamonds(host, "position")).toHaveLength(3);
     const buttons = laneEaseButtons(host, "position");
     expect(buttons).toHaveLength(2);
-    expect(buttons.every((button) => button.classList.contains("opacity-0"))).toBe(true);
+    expect(buttons.every((button) => button.classList.contains("opacity-40"))).toBe(true);
     expect(buttons.every((button) => button.classList.contains("group-hover:opacity-100"))).toBe(
       true,
     );

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

@@ -260,9 +260,17 @@ describe("groupAutomationLanes", () => {
     expect(groups.map((g) => g.entries.length)).toEqual([1, 1]);
   });
 
-  it("ignores clips that are not audio, the way the reserved height does", () => {
-    const video = el({ id: "titles", key: "titles", tag: "div", automation: lanesOf("volume") });
-    expect(groupAutomationLanes([video])).toEqual([]);
+  it("draws lanes for a video element, matching the reserved height", () => {
+    // A <video>'s volume can be automated from the property panel same as an
+    // audio clip's; gating this on `isAudioTimelineElement` alone hid every
+    // keyframe the panel wrote for a video clip.
+    const video = el({ id: "titles", key: "titles", tag: "video", automation: lanesOf("volume") });
+    expect(groupAutomationLanes([video]).map((g) => g.key)).toEqual(["Volume"]);
+  });
+
+  it("ignores a clip that is neither audio nor video, the way the reserved height does", () => {
+    const div = el({ id: "titles", key: "titles", tag: "div", automation: lanesOf("volume") });
+    expect(groupAutomationLanes([div])).toEqual([]);
   });
 
   it("skips a target that does not resolve against its clip's chain", () => {

package/src/player/components/automationLaneData.ts

@@ -22,7 +22,7 @@ import {
   type HfAutomationLane,
 } from "@hyperframes/core/audio-automation";
 import { parseAudioFxChain, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isAudioOrVideoTimelineElement } from "../../utils/timelineInspector";
 import type { TimelineElement } from "../store/playerStore";
 
 const EMPTY: HfAutomation = { version: 1, lanes: [] };
@@ -245,13 +245,14 @@ export interface AutomationLaneGroup {
  * spectrum, top down), so the first clip to carry a property fixes its row and
  * later clips only append properties nobody has shown yet.
  *
- * Non-audio elements contribute nothing, matching `automationLaneCountOf` — the
- * row's reserved height and its drawn lanes have to count the same clips.
+ * Gated on `isAudioOrVideoTimelineElement`, the same predicate `automationLaneCountOf`
+ * and `TimelineAutomationLaneSlot`'s clip filter use — the row's reserved height
+ * and its drawn lanes have to count the same clips.
  */
 export function groupAutomationLanes(elements: readonly TimelineElement[]): AutomationLaneGroup[] {
   const groups = new Map<string, AutomationLaneGroup>();
   for (const element of elements) {
-    if (!isAudioTimelineElement(element)) continue;
+    if (!isAudioOrVideoTimelineElement(element)) continue;
     const chain = elementFxChain(element);
     for (const lane of elementAutomationLanes(element)) {
       const key = laneGroupKey(lane.target, chain);

package/src/player/components/automationLaneGeometry.ts

@@ -23,6 +23,21 @@ import { getAudioFxDef, type HfAudioFxChain } from "@hyperframes/core/audio-fx";
 /** Points nearer than this in clip seconds are the same point, not two. */
 export const POINT_MERGE_SEC = 0.02;
 
+/** Insert or replace the point nearest `t` — the one merge/seed rule every
+ * hand-editing gesture on a lane uses (timeline double-click, panel control). */
+export function mergeInsertPoint(
+  points: readonly HfAutomationLane["points"][number][],
+  t: number,
+  v: number,
+): HfAutomationLane["points"] {
+  const kept = points.filter((p) => Math.abs(p.t - t) > POINT_MERGE_SEC);
+  // A lane's first point alone would be a constant, which is not what
+  // committing to an empty lane means: seed the far end at the same value so
+  // the envelope has somewhere to go.
+  const seeded = points.length === 0 && t > POINT_MERGE_SEC ? [{ t: 0, v }] : [];
+  return [...seeded, ...kept, { t, v }].sort((a, b) => a.t - b.t);
+}
+
 /**
  * Closest two breakpoints may sit in clip seconds while still being two points.
  *

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", () => {

package/src/player/components/timelineClipDragCommit.ts

@@ -3,7 +3,8 @@ 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, normalizeToZones } from "./timelineZones";
+import { classifyZone } from "./timelineZones";
+import { layoutAfterTrackInsert, resolveDragLandingStart } from "./timelineDragLanding";
 import { computeStackingPatches, type StackingPatch } from "./timelineStackingSync";
 import {
   canMoveTimelineElement as canMoveElement,
@@ -16,7 +17,7 @@ import {
 } from "./timelineOptimisticRevision";
 import { runLaneZGesture } from "../../components/nle/zLaneGesture";
 import { refreshAfterDurableLaneMove } from "./timelineLaneMoveRefresh";
-import { authoredTrackForLane, sameSourceFile } from "./timelineAuthoredTrack";
+import { authoredTrackForLane } from "./timelineAuthoredTrack";
 
 type StartTrack = Pick<TimelineElement, "start" | "track">;
 export interface TimelineMoveEdit {
@@ -172,19 +173,6 @@ export function persistMoveEdits(
   );
 }
 
-/**
- * A fractional track value for a NEW lane inserted at boundary `insertRow` in
- * `trackOrder` (0 = above the top, `length` = below the bottom). normalizeToZones
- * then compacts it to a distinct integer lane between its neighbours, and the
- * clips at/below the insert shift down by one — the sanctioned index-renumber.
- */
-function insertTrackValue(trackOrder: number[], insertRow: number): number {
-  if (trackOrder.length === 0) return 0;
-  if (insertRow <= 0) return trackOrder[0] - 0.5;
-  if (insertRow >= trackOrder.length) return trackOrder[trackOrder.length - 1] + 0.5;
-  return (trackOrder[insertRow - 1] + trackOrder[insertRow]) / 2;
-}
-
 /**
  * Build the time-shift resolver for a multi-selection drag: every member of the
  * selection moves by the dragged clip's delta (clamped ≥ 0); non-members are
@@ -231,7 +219,8 @@ function resolveMultiSelection(
  *   permitted multi-clip write) via a whole-set re-normalize; persisted atomically.
  */
 // fallow-ignore-next-line complexity
-export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDeps): void {
+export function commitDraggedClipMove(rawDrag: DraggedClipState, deps: DragCommitDeps): void {
+  const drag = { ...rawDrag, previewStart: resolveDragLandingStart(rawDrag, deps) };
   const hostAlias = resolveExpandedHostAlias(drag, deps);
   if (hostAlias) {
     commitDraggedClipMove(hostAlias.drag, { ...deps, selectedKeys: hostAlias.selectedKeys });
@@ -353,36 +342,11 @@ function buildTrackInsertEdits(
   } | null,
   deps: DragCommitDeps,
 ): { candidate: TimelineElement[]; edits: TimelineMoveEdit[] } | null {
-  const { elements, trackOrder } = deps;
+  const { elements } = deps;
   const editKey = keyOf(element);
-  // Expanded-child rows are synthetic host lanes, not source-file topology.
-  if (element.expandedParentStart != null) return null;
-  const targetTrack = insertTrackValue(trackOrder, insertRow);
-  const candidate = elements.map((e) => {
-    if (keyOf(e) === editKey) return { ...e, start: previewStart, track: targetTrack };
-    if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
-    return e;
-  });
-  // Foreign display rows and the opposite zone must not affect this topology.
-  const writableZone = classifyZone(element);
-  const writable = (src: TimelineElement): boolean =>
-    sameSourceFile(src, element) &&
-    classifyZone(src) === writableZone &&
-    src.expandedParentStart == null;
-  const topologyOrder = [...new Set(elements.filter(writable).map((e) => e.track))].sort(
-    (a, b) => a - b,
-  );
-  const topologyInsertRow = topologyOrder.filter((track) => track < targetTrack).length;
-  const topologyTargetTrack = insertTrackValue(topologyOrder, topologyInsertRow);
-  const normalized = normalizeToZones(
-    elements.filter(writable).map((e) => {
-      if (keyOf(e) === editKey) {
-        return { ...e, start: previewStart, track: topologyTargetTrack };
-      }
-      if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
-      return e;
-    }),
-  );
+  const layout = layoutAfterTrackInsert(element, previewStart, insertRow, multi, deps);
+  if (!layout) return null;
+  const { normalized, targetTrack, writable } = layout;
   const bySrc = new Map(elements.map((e) => [keyOf(e), e]));
   // A partial zone renumber creates collisions; refuse a shifted locked row.
   for (const norm of normalized) {
@@ -399,6 +363,11 @@ function buildTrackInsertEdits(
       return null;
     }
   }
+  const candidate = elements.map((e) => {
+    if (keyOf(e) === editKey) return { ...e, start: previewStart, track: targetTrack };
+    if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
+    return e;
+  });
   const edits: TimelineMoveEdit[] = [];
   if (multi) {
     for (const src of elements) {
@@ -415,10 +384,10 @@ function buildTrackInsertEdits(
   for (const norm of normalized) {
     const src = bySrc.get(keyOf(norm));
     if (!src || !canMoveElement(src)) continue;
-    const start =
-      keyOf(norm) === editKey || multi?.keys.has(keyOf(norm))
-        ? (multi?.movedStart(src) ?? previewStart)
-        : src.start;
+    const normKey = keyOf(norm);
+    let start = src.start;
+    if (normKey === editKey) start = previewStart;
+    else if (multi?.keys.has(normKey)) start = multi.movedStart(src);
     edits.push({ element: src, updates: { start, track: norm.track } });
   }
   return { candidate, edits };