@hyperframes/studio 0.7.55 → 0.7.56

package/src/player/components/timelineEditCapabilities.ts

@@ -0,0 +1,52 @@
+export interface TimelineEditCapabilities {
+  canMove: boolean;
+  canTrimStart: boolean;
+  canTrimEnd: boolean;
+}
+
+function isDeterministicTimelineWindow(input: {
+  tag: string;
+  compositionSrc?: string;
+  playbackStartAttr?: "media-start" | "playback-start";
+  sourceDuration?: number;
+}): boolean {
+  if (input.compositionSrc || input.playbackStartAttr != null) return true;
+  if (
+    input.sourceDuration != null &&
+    Number.isFinite(input.sourceDuration) &&
+    input.sourceDuration > 0
+  ) {
+    return true;
+  }
+  return ["video", "audio", "img"].includes(input.tag.toLowerCase());
+}
+
+export function hasPatchableTimelineTarget(input: { domId?: string; selector?: string }): boolean {
+  return Boolean(input.domId || input.selector);
+}
+
+export function getTimelineEditCapabilities(input: {
+  tag: string;
+  duration: number;
+  domId?: string;
+  selector?: string;
+  compositionSrc?: string;
+  playbackStart?: number;
+  playbackStartAttr?: "media-start" | "playback-start";
+  sourceDuration?: number;
+  timingSource?: "authored" | "implicit";
+  timelineLocked?: boolean;
+}): TimelineEditCapabilities {
+  if (input.timingSource === "implicit" || input.timelineLocked) {
+    return { canMove: false, canTrimStart: false, canTrimEnd: false };
+  }
+
+  const canPatch = hasPatchableTimelineTarget(input);
+  const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
+  const hasDeterministicWindow = isDeterministicTimelineWindow(input);
+  return {
+    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
+    canTrimEnd: canPatch && hasFiniteDuration,
+    canTrimStart: canPatch && hasFiniteDuration,
+  };
+}

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

@@ -693,7 +693,7 @@ describe("buildTimelineAgentPrompt", () => {
       prompt: "Move the title later and lower the music",
     });
 
-    expect(text).toContain("Time range: 0:01 - 0:04");
+    expect(text).toContain("Time range: 00:01 - 00:04");
     expect(text).toContain("#title (div)");
     expect(text).toContain("#music (audio)");
     expect(text).toContain("Move the title later and lower the music");

package/src/player/components/timelineEditing.ts

@@ -4,6 +4,13 @@ import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrde
 import { resolveTimelineLayerStackingMove } from "./timelineLayerDrag";
 import { shouldShowTimelineLayerGroupHeader } from "./TimelineLayerGroupHeader";
 import type { TimelineStackingElement, TimelineStackingReorderIntent } from "./timelineStacking";
+import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
+
+export {
+  getTimelineEditCapabilities,
+  hasPatchableTimelineTarget,
+} from "./timelineEditCapabilities";
+export type { TimelineEditCapabilities } from "./timelineEditCapabilities";
 
 import {
   applyClipStartTrimDelta,
@@ -245,12 +252,6 @@ export interface TimelinePromptElement {
   track: number;
 }
 
-export interface TimelineEditCapabilities {
-  canMove: boolean;
-  canTrimStart: boolean;
-  canTrimEnd: boolean;
-}
-
 export type BlockedTimelineEditIntent = "move" | "resize-start" | "resize-end";
 
 export interface TimelineRangeSelection {
@@ -362,59 +363,6 @@ export function selectTimelineElementsInMarquee({
   return selected;
 }
 
-function isDeterministicTimelineWindow(input: {
-  tag: string;
-  compositionSrc?: string;
-  playbackStartAttr?: "media-start" | "playback-start";
-  sourceDuration?: number;
-}): boolean {
-  if (input.compositionSrc) return true;
-  if (input.playbackStartAttr != null) return true;
-  if (
-    input.sourceDuration != null &&
-    Number.isFinite(input.sourceDuration) &&
-    input.sourceDuration > 0
-  ) {
-    return true;
-  }
-  const normalizedTag = input.tag.toLowerCase();
-  return ["video", "audio", "img"].includes(normalizedTag);
-}
-
-export function hasPatchableTimelineTarget(input: { domId?: string; selector?: string }): boolean {
-  return Boolean(input.domId || input.selector);
-}
-
-export function getTimelineEditCapabilities(input: {
-  tag: string;
-  duration: number;
-  domId?: string;
-  selector?: string;
-  compositionSrc?: string;
-  playbackStart?: number;
-  playbackStartAttr?: "media-start" | "playback-start";
-  sourceDuration?: number;
-  timingSource?: "authored" | "implicit";
-  timelineLocked?: boolean;
-}): TimelineEditCapabilities {
-  if (input.timingSource === "implicit" || input.timelineLocked) {
-    return {
-      canMove: false,
-      canTrimStart: false,
-      canTrimEnd: false,
-    };
-  }
-
-  const canPatch = hasPatchableTimelineTarget(input);
-  const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
-  const hasDeterministicWindow = isDeterministicTimelineWindow(input);
-  return {
-    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
-    canTrimEnd: canPatch && hasFiniteDuration,
-    canTrimStart: canPatch && hasFiniteDuration,
-  };
-}
-
 export function resolveBlockedTimelineEditIntent(input: {
   width: number;
   offsetX: number;
@@ -525,3 +473,72 @@ export function buildTimelineElementAgentPrompt(element: {
 export function formatTimelineAttributeNumber(value: number): string {
   return Number(roundToCentiseconds(value).toFixed(2)).toString();
 }
+
+/**
+ * Apply one edge auto-scroll step: scroll `scroll` toward the edge zone the
+ * pointer is in, clamped to the scrollable range. Returns true when the
+ * container actually moved (the caller keeps its RAF running and re-runs its
+ * live preview), false when the pointer is outside the edge zones or the scroll
+ * is already clamped (the caller stops).
+ */
+export function applyTimelineAutoScrollStep(
+  scroll: HTMLElement,
+  clientX: number,
+  clientY: number,
+): boolean {
+  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  if (delta.x === 0 && delta.y === 0) return false;
+  const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+  const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.clientHeight);
+  const nextScrollLeft = Math.max(0, Math.min(maxScrollLeft, scroll.scrollLeft + delta.x));
+  const nextScrollTop = Math.max(0, Math.min(maxScrollTop, scroll.scrollTop + delta.y));
+  if (nextScrollLeft === scroll.scrollLeft && nextScrollTop === scroll.scrollTop) return false;
+  scroll.scrollLeft = nextScrollLeft;
+  scroll.scrollTop = nextScrollTop;
+  return true;
+}
+
+/**
+ * Decide whether an edge auto-scroll RAF loop should start, stop, or stay as-is
+ * for the current pointer: "start" when the pointer is in an edge zone and no
+ * loop is running, "stop" when it left the zones while a loop is running,
+ * "none" otherwise.
+ */
+export function resolveTimelineAutoScrollLoopAction(
+  scroll: HTMLElement | null,
+  clientX: number,
+  clientY: number,
+  rafActive: boolean,
+): "start" | "stop" | "none" {
+  if (!scroll) return "none";
+  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  if (delta.x === 0 && delta.y === 0) return rafActive ? "stop" : "none";
+  return rafActive ? "none" : "start";
+}
+
+/**
+ * Escape cancels an in-progress clip drag / resize / blocked-drag: no commit,
+ * no undo entry — the previews live only in the gesture state, so clearing it
+ * restores the pre-drag timeline. `suppressClick` arms the click suppressor
+ * only when the gesture actually started, so the click generated by the
+ * eventual pointerup can't reselect or split the clip.
+ */
+export function resolveTimelineDragEscape(input: TimelineDragEscapeInput): {
+  cancel: boolean;
+  suppressClick: boolean;
+} {
+  if (input.key !== "Escape" || (!input.drag && !input.resize && !input.blocked)) {
+    return { cancel: false, suppressClick: false };
+  }
+  return {
+    cancel: true,
+    suppressClick: Boolean(input.drag?.started || input.resize?.started || input.blocked?.started),
+  };
+}
+
+export interface TimelineDragEscapeInput {
+  key: string;
+  drag: { started: boolean } | null;
+  resize: { started: boolean } | null;
+  blocked: { started: boolean } | null;
+}

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  buildTimelineGroupResizeMembers,
+  resolveTimelineGroupResize,
+  resolveTimelineGroupResizeChanges,
+} from "./timelineGroupEditing";
+
+function el(id: string, over: Partial<TimelineElement> = {}): TimelineElement {
+  // domId gives a patchable target so getTimelineEditCapabilities().canTrim* is true.
+  return { id, key: id, tag: "video", start: 0, duration: 2, track: 0, domId: id, ...over };
+}
+
+function keys(...ids: string[]): ReadonlySet<string> {
+  return new Set(ids);
+}
+
+describe("buildTimelineGroupResizeMembers (legacy 36413da7f semantics)", () => {
+  it("returns null for a single-clip selection (no group forms)", () => {
+    const a = el("a");
+    expect(buildTimelineGroupResizeMembers([a], keys("a"), "a", "end")).toBeNull();
+    expect(buildTimelineGroupResizeMembers([a], new Set(), "a", "end")).toBeNull();
+  });
+
+  it("returns null when the grabbed clip is not part of the selection", () => {
+    const a = el("a");
+    const b = el("b");
+    expect(buildTimelineGroupResizeMembers([a, b], keys("a", "b"), "c", "end")).toBeNull();
+  });
+
+  it("degrades to single-clip (null) when ANY member is locked — locked clip never patched", () => {
+    const a = el("a");
+    const locked = el("b", { timelineLocked: true });
+    expect(buildTimelineGroupResizeMembers([a, locked], keys("a", "b"), "a", "end")).toBeNull();
+  });
+
+  it("degrades when a member is implicitly timed or has no patch target", () => {
+    const a = el("a");
+    const implicit = el("b", { timingSource: "implicit" });
+    const noTarget = el("c", { domId: undefined, selector: undefined });
+    expect(buildTimelineGroupResizeMembers([a, implicit], keys("a", "b"), "a", "end")).toBeNull();
+    expect(buildTimelineGroupResizeMembers([a, noTarget], keys("a", "c"), "a", "end")).toBeNull();
+  });
+
+  it("snapshots members and seeds start-edge media playbackStart to 0", () => {
+    const grabbed = el("a", { start: 2, duration: 2 });
+    const audio = el("b", { tag: "audio", start: 5, duration: 3 }); // playbackStart undefined
+    const members = buildTimelineGroupResizeMembers([grabbed, audio], keys("a", "b"), "a", "start");
+    expect(members).not.toBeNull();
+    expect(members!.map((m) => [m.key, m.start, m.duration, m.playbackStart])).toEqual([
+      ["a", 2, 2, 0], // start-edge media seeds playbackStart to 0
+      ["b", 5, 3, 0],
+    ]);
+  });
+
+  it("does not seed playbackStart on the END edge", () => {
+    const grabbed = el("a", { tag: "audio", start: 0, duration: 2 });
+    const b = el("b", { tag: "audio", start: 3, duration: 2 });
+    const members = buildTimelineGroupResizeMembers([grabbed, b], keys("a", "b"), "a", "end");
+    expect(members!.every((m) => m.playbackStart === undefined)).toBe(true);
+  });
+});
+
+describe("resolveTimelineGroupResizeChanges (rigid group patch set)", () => {
+  it("END edge: extends every member's duration by the shared delta", () => {
+    const members = buildTimelineGroupResizeMembers(
+      [el("a", { duration: 2 }), el("b", { duration: 3 })],
+      keys("a", "b"),
+      "a",
+      "end",
+    )!;
+    const changes = resolveTimelineGroupResizeChanges(members, "end", 0.5);
+    expect(changes.map((c) => [c.key, c.start, c.duration])).toEqual([
+      ["a", 0, 2.5],
+      ["b", 0, 3.5],
+    ]);
+  });
+
+  it("END edge: rigid — the most-constrained member clamps the whole group", () => {
+    // b (0.2s) can only shrink 0.1 before hitting min duration, so the group as a
+    // whole shrinks 0.1 even though the grabbed clip asked for -0.5.
+    const members = buildTimelineGroupResizeMembers(
+      [el("a", { duration: 2 }), el("b", { duration: 0.2 })],
+      keys("a", "b"),
+      "a",
+      "end",
+    )!;
+    const changes = resolveTimelineGroupResizeChanges(members, "end", -0.5);
+    expect(changes.map((c) => c.duration)).toEqual([1.9, 0.1]);
+  });
+
+  it("START edge: shifts start + duration together across the group", () => {
+    const members = buildTimelineGroupResizeMembers(
+      [
+        el("a", { tag: "text", start: 2, duration: 2 }),
+        el("b", { tag: "text", start: 5, duration: 3 }),
+      ],
+      keys("a", "b"),
+      "a",
+      "start",
+    )!;
+    const changes = resolveTimelineGroupResizeChanges(members, "start", -0.5);
+    expect(changes.map((c) => [c.key, c.start, c.duration])).toEqual([
+      ["a", 1.5, 2.5],
+      ["b", 4.5, 3.5],
+    ]);
+  });
+
+  it("produces exactly the resolveTimelineGroupResize output, keyed per member", () => {
+    const members = buildTimelineGroupResizeMembers(
+      [el("a", { duration: 2 }), el("b", { duration: 4 })],
+      keys("a", "b"),
+      "a",
+      "end",
+    )!;
+    const raw = resolveTimelineGroupResize(members, "end", 0.75);
+    const changes = resolveTimelineGroupResizeChanges(members, "end", 0.75);
+    expect(
+      changes.map((c) => ({
+        start: c.start,
+        duration: c.duration,
+        playbackStart: c.playbackStart,
+      })),
+    ).toEqual(raw.members);
+  });
+});

package/src/player/components/timelineGroupEditing.ts

@@ -1,4 +1,6 @@
 import { roundToCenti } from "../../utils/rounding";
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineEditCapabilities } from "./timelineEditCapabilities";
 
 const DEFAULT_TIMELINE_MIN_DURATION = 0.1;
 const ABSOLUTE_TIMELINE_MIN_DURATION = 0.05;
@@ -157,3 +159,134 @@ export function resolveTimelineGroupResize(
     }),
   };
 }
+
+/* ── Multi-select group resize wiring (restored from main 36413da7f) ───────── */
+
+/** A selected clip snapshot captured at group-resize gesture start. */
+export interface TimelineGroupResizeMember extends TimelineGroupTimingMember {
+  element: TimelineElement;
+  key: string;
+}
+
+/** Per-member timing patch produced by a group resize (grabbed clip included). */
+export interface TimelineGroupResizeChange {
+  element: TimelineElement;
+  key: string;
+  start: number;
+  duration: number;
+  playbackStart?: number;
+}
+
+function elementKey(element: TimelineElement): string {
+  return element.key ?? element.id;
+}
+
+function isMediaTimelineElement(element: TimelineElement): boolean {
+  const tag = element.tag.toLowerCase();
+  return tag === "audio" || tag === "video";
+}
+
+function canTrimEdge(element: TimelineElement, edge: TimelineGroupResizeEdge): boolean {
+  const caps = getTimelineEditCapabilities({
+    tag: element.tag,
+    duration: element.duration,
+    domId: element.domId,
+    selector: element.selector,
+    compositionSrc: element.compositionSrc,
+    playbackStart: element.playbackStart,
+    playbackStartAttr: element.playbackStartAttr,
+    sourceDuration: element.sourceDuration,
+    timingSource: element.timingSource,
+    timelineLocked: element.timelineLocked,
+  });
+  return edge === "start" ? caps.canTrimStart : caps.canTrimEnd;
+}
+
+/**
+ * Snapshot the members for a group resize, or `null` when the gesture must stay a
+ * single-clip resize. Legacy semantics (main 36413da7f): a group forms only when
+ * the grabbed clip is part of a multi-selection (> 1) AND EVERY selected member
+ * can take THIS edge's trim. It is all-or-nothing — if any member is locked or
+ * implicitly-timed the group does not form, so a locked member is never patched
+ * (the grabbed clip then resizes on its own). Start-edge media members seed
+ * `playbackStart` to 0 so the in-point trim math has a base, mirroring the legacy
+ * `resizeMember`.
+ */
+export function buildTimelineGroupResizeMembers(
+  elements: readonly TimelineElement[],
+  selectedKeys: ReadonlySet<string>,
+  grabbedKey: string,
+  edge: TimelineGroupResizeEdge,
+): TimelineGroupResizeMember[] | null {
+  if (selectedKeys.size <= 1 || !selectedKeys.has(grabbedKey)) return null;
+  const selected = elements.filter((element) => selectedKeys.has(elementKey(element)));
+  if (selected.length <= 1) return null;
+  if (!selected.every((element) => canTrimEdge(element, edge))) return null;
+  return selected.map((element) => ({
+    element,
+    key: elementKey(element),
+    start: element.start,
+    duration: element.duration,
+    playbackStart:
+      edge === "start" && isMediaTimelineElement(element)
+        ? (element.playbackStart ?? 0)
+        : element.playbackStart,
+    playbackRate: element.playbackRate,
+  }));
+}
+
+/**
+ * Resolve the per-member timing patches for a group resize from the grabbed
+ * clip's raw edge delta. Rigid group: one shared delta, clamped by the most
+ * constrained member (see resolveTimelineGroupResize), applied to every member.
+ */
+export function resolveTimelineGroupResizeChanges(
+  members: readonly TimelineGroupResizeMember[],
+  edge: TimelineGroupResizeEdge,
+  rawDelta: number,
+  minDuration = resolveTimelineMinDuration(),
+): TimelineGroupResizeChange[] {
+  const result = resolveTimelineGroupResize(members, edge, rawDelta, minDuration);
+  return result.members.map((member, index) => ({
+    element: members[index]!.element,
+    key: members[index]!.key,
+    start: member.start,
+    duration: member.duration,
+    playbackStart: member.playbackStart,
+  }));
+}
+
+/** In-flight multi-select group-resize gesture (owned by the drag hook). */
+export interface TimelineGroupResizeSession {
+  grabbedKey: string;
+  edge: TimelineGroupResizeEdge;
+  members: TimelineGroupResizeMember[];
+  changes: TimelineGroupResizeChange[];
+  hasChanged: boolean;
+}
+
+/**
+ * Fold the grabbed clip's single-clip preview into the group: derive the raw
+ * edge delta from it, resolve the rigid per-member changes onto the session
+ * (updating `changes` + `hasChanged`), and return the grabbed clip's own change
+ * so the caller can render it from the resize state.
+ */
+export function applyTimelineGroupResizePreview(
+  session: TimelineGroupResizeSession,
+  grabbedPreview: { previewStart: number; previewDuration: number },
+): TimelineGroupResizeChange | undefined {
+  const grabbed = session.members.find((m) => m.key === session.grabbedKey);
+  const rawDelta =
+    session.edge === "start"
+      ? grabbedPreview.previewStart - (grabbed?.start ?? grabbedPreview.previewStart)
+      : grabbedPreview.previewDuration - (grabbed?.duration ?? grabbedPreview.previewDuration);
+  const changes = resolveTimelineGroupResizeChanges(session.members, session.edge, rawDelta);
+  session.changes = changes;
+  session.hasChanged = changes.some(
+    (c, i) =>
+      c.start !== session.members[i]!.start ||
+      c.duration !== session.members[i]!.duration ||
+      c.playbackStart !== session.members[i]!.playbackStart,
+  );
+  return changes.find((c) => c.key === session.grabbedKey);
+}

package/src/player/components/timelineGroupResizeCommit.ts

@@ -0,0 +1,54 @@
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import type { TimelineGroupResizeSession } from "./timelineGroupEditing";
+import {
+  beginTimelineOptimisticGesture,
+  rollbackLatestTimelineOptimisticGesture,
+} from "./timelineOptimisticRevision";
+
+export function commitTimelineGroupResize(
+  session: TimelineGroupResizeSession,
+  updateElement: (key: string, updates: Partial<TimelineElement>) => void,
+  persist: TimelineEditCallbacks["onResizeElements"],
+): void {
+  if (!session.hasChanged) return;
+  const changes = session.changes;
+  const revision = beginTimelineOptimisticGesture(
+    updateElement,
+    changes.map((change) => change.key),
+  );
+  for (const change of changes) {
+    updateElement(change.key, {
+      start: change.start,
+      duration: change.duration,
+      playbackStart: change.playbackStart,
+    });
+  }
+  if (!persist) {
+    rollbackLatestTimelineOptimisticGesture(
+      updateElement,
+      revision,
+      session.members.map((member) => ({ key: member.key, updates: member })),
+    );
+    return;
+  }
+  const coalesceKey = `clip-group-resize:${changes.map((change) => change.key).join(":")}`;
+  Promise.resolve(
+    persist(
+      changes.map((change) => ({
+        element: change.element,
+        start: change.start,
+        duration: change.duration,
+        playbackStart: change.playbackStart,
+      })),
+      { coalesceKey },
+    ),
+  ).catch((error) => {
+    rollbackLatestTimelineOptimisticGesture(
+      updateElement,
+      revision,
+      session.members.map((member) => ({ key: member.key, updates: member })),
+    );
+    console.error("[Timeline] Failed to persist group clip resize", error);
+  });
+}

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

@@ -1,34 +1,106 @@
-import { describe, expect, it } from "vitest";
-import { computeTimelineBasisDuration, computeTimelineEffectiveDuration } from "./timelineLayout";
+import { describe, it, expect } from "vitest";
+import {
+  RULER_H,
+  TRACK_H,
+  TRACKS_TOP_PAD,
+  TRACKS_BOTTOM_PAD,
+  GUTTER,
+  getTimelineRowTop,
+  getTimelineRowFromY,
+  getTimelineCanvasHeight,
+  resolveTimelineAssetDrop,
+} from "./timelineLayout";
 
-describe("computeTimelineBasisDuration", () => {
-  it("uses the root duration when it exceeds every clip end", () => {
-    expect(computeTimelineBasisDuration(12, [4, 6, 9])).toBe(12);
-  });
+describe("track-area breathing pad y-math", () => {
+  describe("getTimelineRowTop", () => {
+    it("offsets the first lane below the ruler by the top pad", () => {
+      expect(getTimelineRowTop(0)).toBe(RULER_H + TRACKS_TOP_PAD);
+    });
 
-  it("grows to the furthest committed clip end past the root duration", () => {
-    expect(computeTimelineBasisDuration(12, [4, 18, 9])).toBe(18);
-  });
+    it("advances by one track height per row, keeping the pad", () => {
+      expect(getTimelineRowTop(1)).toBe(RULER_H + TRACKS_TOP_PAD + TRACK_H);
+      expect(getTimelineRowTop(3)).toBe(RULER_H + TRACKS_TOP_PAD + 3 * TRACK_H);
+    });
 
-  it("falls back to the root duration with no clips / non-finite ends", () => {
-    expect(computeTimelineBasisDuration(10, [])).toBe(10);
-    expect(computeTimelineBasisDuration(Number.NaN, [])).toBe(0);
+    it("is a strict positive shift from the pre-pad formula (pad is non-zero)", () => {
+      expect(TRACKS_TOP_PAD).toBeGreaterThan(0);
+      expect(getTimelineRowTop(2)).toBe(RULER_H + 2 * TRACK_H + TRACKS_TOP_PAD);
+    });
   });
-});
 
-describe("computeTimelineEffectiveDuration", () => {
-  it("returns the basis when there is no active preview", () => {
-    expect(computeTimelineEffectiveDuration(12, [null, null])).toBe(12);
+  describe("getTimelineRowFromY", () => {
+    it("is the exact inverse of getTimelineRowTop at lane boundaries", () => {
+      for (const row of [0, 1, 2, 7]) {
+        expect(getTimelineRowFromY(getTimelineRowTop(row))).toBeCloseTo(row, 10);
+      }
+    });
+
+    it("floors a y inside the top pad (above lane 0) to a negative fraction", () => {
+      // A drop in the pad between the ruler and lane 0 sits at row < 0, so a
+      // floor lands it on row -1 → getDefaultDroppedTrack floors to the top lane.
+      const yInPad = RULER_H + TRACKS_TOP_PAD / 2;
+      expect(getTimelineRowFromY(yInPad)).toBeLessThan(0);
+    });
+
+    it("maps a y in the middle of lane 1 into [1,2)", () => {
+      const yMidLane1 = getTimelineRowTop(1) + TRACK_H / 2;
+      const row = getTimelineRowFromY(yMidLane1);
+      expect(row).toBeGreaterThanOrEqual(1);
+      expect(row).toBeLessThan(2);
+    });
   });
 
-  it("extends to a drag/resize preview end beyond the basis", () => {
-    expect(computeTimelineEffectiveDuration(12, [20, null])).toBe(20);
-    expect(computeTimelineEffectiveDuration(12, [null, 16])).toBe(16);
+  describe("getTimelineCanvasHeight", () => {
+    it("reserves ruler + top pad + lanes + bottom pad", () => {
+      expect(getTimelineCanvasHeight(0)).toBe(RULER_H + TRACKS_TOP_PAD + TRACKS_BOTTOM_PAD);
+      expect(getTimelineCanvasHeight(3)).toBe(
+        RULER_H + TRACKS_TOP_PAD + 3 * TRACK_H + TRACKS_BOTTOM_PAD,
+      );
+    });
+
+    it("clamps a negative track count to zero lanes", () => {
+      expect(getTimelineCanvasHeight(-4)).toBe(RULER_H + TRACKS_TOP_PAD + TRACKS_BOTTOM_PAD);
+    });
+
+    it("leaves room below the last lane for a drag-into-void new track", () => {
+      // The gap below the final lane must be at least a full track height so a
+      // clip can be dropped there to create a new bottom track.
+      const oneLane = getTimelineCanvasHeight(1);
+      const lastLaneBottom = getTimelineRowTop(0) + TRACK_H;
+      expect(oneLane - lastLaneBottom).toBeGreaterThanOrEqual(TRACK_H);
+    });
   });
 
-  it("never shrinks below the basis for a preview inside the current length", () => {
-    // The invariant behind the jump fix: the basis (which drives zoom) is
-    // independent of the preview, and a smaller preview end can't reduce it.
-    expect(computeTimelineEffectiveDuration(12, [8])).toBe(12);
+  describe("resolveTimelineAssetDrop honours the top pad", () => {
+    const base = {
+      rectLeft: 0,
+      rectTop: 0,
+      scrollLeft: 0,
+      scrollTop: 0,
+      pixelsPerSecond: 100,
+      duration: 60,
+      trackHeight: TRACK_H,
+      trackOrder: [0, 1, 2],
+    };
+
+    it("drops onto lane 0 when the pointer is in the middle of the first lane", () => {
+      const clientY = getTimelineRowTop(0) + TRACK_H / 2;
+      const clientX = GUTTER + 100; // t = 1s
+      const { start, track } = resolveTimelineAssetDrop(base, clientX, clientY);
+      expect(track).toBe(0);
+      expect(start).toBe(1);
+    });
+
+    it("drops into the top pad → floors to the first lane (row < 0)", () => {
+      const clientY = RULER_H + TRACKS_TOP_PAD / 2; // inside the pad, above lane 0
+      const { track } = resolveTimelineAssetDrop(base, GUTTER, clientY);
+      expect(track).toBe(0);
+    });
+
+    it("drops below the last lane → appends a new track", () => {
+      const clientY = getTimelineRowTop(2) + TRACK_H + 4; // in the bottom pad
+      const { track } = resolveTimelineAssetDrop(base, GUTTER, clientY);
+      expect(track).toBe(3); // max(trackOrder)+1
+    });
   });
 });