@hyperframes/studio 0.8.93 → 0.8.95

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

@@ -0,0 +1,157 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Timeline } from "./Timeline";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
+import { usePlayerStore } from "../store/playerStore";
+import { CLIP_Y, RULER_H, TRACK_H, TRACKS_BOTTOM_PAD, TRACKS_TOP_PAD } from "./timelineLayout";
+import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import type { TimelineProps } from "./TimelineTypes";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+installTimelineMountEnv();
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+async function mountCanvas(trackPadding?: TimelineProps["trackPadding"]) {
+  usePlayerStore.setState({
+    duration: 10,
+    currentTime: 0,
+    timelineReady: true,
+    gsapAnimations: new Map(),
+    elements: [{ id: "card", label: "Card", tag: "div", start: 0, duration: 4, track: 0 }],
+  });
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  await act(async () => root.render(<Timeline trackPadding={trackPadding} />));
+  const canvas = Array.from(host.querySelectorAll<HTMLElement>("div.relative")).find(
+    (el) => el.style.height && el.style.width,
+  );
+  const height = canvas?.style.height;
+  const firstRowTop = host.querySelector<HTMLElement>('[data-timeline-row="0"]')?.style.top;
+  act(() => root.unmount());
+  return { height, firstRowTop };
+}
+
+describe("Timeline trackPadding", () => {
+  it("keeps Studio's pads by default", async () => {
+    expect(await mountCanvas()).toEqual({
+      height: `${RULER_H + TRACKS_TOP_PAD + TRACK_H + TRACKS_BOTTOM_PAD}px`,
+      firstRowTop: `${RULER_H + TRACKS_TOP_PAD}px`,
+    });
+  });
+
+  it("places the first row and sizes the canvas from the host's pads", async () => {
+    expect(await mountCanvas({ top: 0, bottom: TRACK_H })).toEqual({
+      height: `${RULER_H + 2 * TRACK_H}px`,
+      firstRowTop: `${RULER_H}px`,
+    });
+  });
+
+  // With no top pad, y = 96 is the middle of row 1; any reader still on the default pad sees row 0.
+  const ROW1_MID = RULER_H + TRACK_H + TRACK_H / 2;
+  const hostPads = { top: 0, bottom: TRACK_H };
+
+  async function mountThreeTracks(props: TimelineProps = {}) {
+    usePlayerStore.setState({
+      duration: 10,
+      currentTime: 0,
+      timelineReady: true,
+      gsapAnimations: new Map(),
+      selectedElementId: null,
+      selectedElementIds: new Set(),
+      elements: [0, 1, 2].map((track) => ({
+        id: `c${track}`,
+        key: `c${track}`,
+        domId: `c${track}`,
+        tag: "div",
+        start: 0,
+        duration: 2,
+        track,
+      })),
+    });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    await act(async () => root.render(<Timeline trackPadding={hostPads} {...props} />));
+    const viewport = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]")!;
+    return { host, root, viewport };
+  }
+
+  const top = (el: Element | null | undefined) => (el as HTMLElement | null)?.style.top;
+
+  it("draws the gap strip, drop preview and insert line, and drops, on the host's rows", async () => {
+    const onAssetDrop = vi.fn();
+    const { host, root, viewport } = await mountThreeTracks({ onAssetDrop });
+    act(() => usePlayerStore.getState().setSelectedElementId("c1"));
+    expect(top(host.querySelector('[style*="--timeline-accent-faint"]'))).toBe(
+      `${RULER_H + TRACK_H + CLIP_Y}px`,
+    );
+
+    const drag = (type: string, clientY: number) => {
+      const event = new Event(type, { bubbles: true, cancelable: true });
+      Object.defineProperties(event, {
+        clientX: { value: 400 },
+        clientY: { value: clientY },
+        dataTransfer: {
+          value: {
+            types: [TIMELINE_ASSET_MIME],
+            files: [],
+            dropEffect: "none",
+            getData: (mime: string) => (mime === TIMELINE_ASSET_MIME ? '{"path":"a.png"}' : ""),
+          },
+        },
+      });
+      act(() => void viewport.dispatchEvent(event));
+    };
+    drag("dragover", ROW1_MID);
+    expect(top(host.querySelector('[data-testid="timeline-drop-preview"]'))).toBe(
+      `${RULER_H + TRACK_H + CLIP_Y}px`,
+    );
+    drag("dragover", RULER_H / 2);
+    expect(top(host.querySelector('[data-testid="timeline-insert-line"]'))).toBe(
+      `${RULER_H - 0.5}px`,
+    );
+    drag("drop", ROW1_MID);
+    expect(onAssetDrop).toHaveBeenCalledWith("a.png", expect.objectContaining({ track: 1 }));
+    act(() => root.unmount());
+  });
+
+  it("drags a clip onto the host's rows and opens a new track in the bottom pad", async () => {
+    const { host, root } = await mountThreeTracks({
+      onMoveElement: vi.fn(),
+      onResizeElement: vi.fn(),
+    });
+    const pointer = (target: EventTarget, type: string, clientY: number) =>
+      act(
+        () =>
+          void target.dispatchEvent(
+            new PointerEvent(type, {
+              bubbles: true,
+              button: 0,
+              pointerId: 1,
+              clientX: 400,
+              clientY,
+            }),
+          ),
+      );
+    const clip = host.querySelector('[data-clip][data-el-id="c0"]')!;
+    pointer(clip, "pointerdown", RULER_H + TRACK_H / 2);
+    pointer(window, "pointermove", ROW1_MID);
+    const ghost = Array.from(
+      host.querySelectorAll<HTMLElement>(".absolute.pointer-events-none"),
+    ).find((el) => el.style.zIndex === "30" && !el.dataset.testid);
+    expect(top(ghost)).toBe(`${RULER_H + TRACK_H + CLIP_Y}px`);
+    pointer(window, "pointermove", RULER_H + 3 * TRACK_H + TRACK_H / 2);
+    expect(top(host.querySelector('[data-testid="timeline-insert-line"]'))).toBe(
+      `${RULER_H + 3 * TRACK_H - 0.5}px`,
+    );
+    act(() => root.unmount());
+  });
+});

package/src/player/components/TimelineCanvas.tsx

@@ -2,16 +2,7 @@ import { memo } from "react";
 import { TimelineRulerPart } from "./TimelineRulerPart";
 import { PlayheadIndicator } from "./PlayheadIndicator";
 import { TimelinePlayheadLayer } from "./TimelinePlayheadLayer";
-import {
-  RULER_H,
-  CLIP_Y,
-  TRACKS_TOP_PAD,
-  TRACKS_BOTTOM_PAD,
-  TRACK_H,
-  PLAYHEAD_HEAD_W,
-  getTimelineRowTop,
-  getTimelineRowHeight,
-} from "./timelineLayout";
+import { RULER_H, CLIP_Y, TRACK_H, PLAYHEAD_HEAD_W, getTimelineRowHeight } from "./timelineLayout";
 import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { TimelineLanes } from "./TimelineLanes";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
@@ -33,6 +24,13 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
   const dropRowIndex = dropTrackIndex < 0 ? displayTrackOrder.length : dropTrackIndex;
   const insertLineRow =
     (draggedClip?.started ? draggedClip.insertRow : null) ?? props.dropPreview?.insertRow ?? null;
+  const ghostLaneActive =
+    (insertLineRow ?? -1) >= props.trackOrder.length ||
+    (props.dropPreview?.insertRow == null && props.dropPreview != null && dropTrackIndex < 0);
+  // A host bottom pad shorter than a track leaves no lane to draw.
+  const showGhostLane = props.rowGeometry.padding.bottom >= TRACK_H;
+  // Past the last committed track: a drag's new bottom-track preview row is the lane itself.
+  const ghostLaneRow = props.rowGeometry.getRowIndex(props.trackOrder.at(-1) ?? Number.NaN) + 1;
   const draggedRowHeight = getTimelineRowHeight(draggedRowIndex, props.rowHeights);
   // A clip bar in an EXPANDED row still renders at TRACK_H (the property lanes
   // occupy the rest of the row — see TimelineLanes' clipHeight), so the drag
@@ -49,8 +47,11 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
       <TimelineRulerPart />
 
       {/* Breathing room between the sticky ruler and the first track lane — the
-          top half of the CapCut-style padding (see TRACKS_TOP_PAD). */}
-      <div aria-hidden="true" style={{ height: props.rowsVirtualized ? 0 : TRACKS_TOP_PAD }} />
+          top half of the CapCut-style padding (see TimelineRowGeometry.padding). */}
+      <div
+        aria-hidden="true"
+        style={{ height: props.rowsVirtualized ? 0 : props.rowGeometry.padding.top }}
+      />
 
       <TimelineLanes
         {...props}
@@ -67,10 +68,34 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         onRazorSplitAll={props.onRazorSplitAll}
       />
 
-      {/* Breathing room below the last track lane (~1.5 track heights) — a real
+      {/* Breathing room below the last track lane (one track by default) — a real
           scrollable surface, so a clip can be dragged into the void to create a
-          new bottom track comfortably (see TRACKS_BOTTOM_PAD / getTimelineCanvasHeight). */}
-      <div aria-hidden="true" style={{ height: props.rowsVirtualized ? 0 : TRACKS_BOTTOM_PAD }} />
+          new bottom track (see TimelineRowGeometry.padding / canvasHeight). */}
+      <div
+        aria-hidden="true"
+        style={{ height: props.rowsVirtualized ? 0 : props.rowGeometry.padding.bottom }}
+      />
+
+      {showGhostLane && (
+        <div
+          aria-hidden="true"
+          data-testid="timeline-ghost-lane"
+          data-active={ghostLaneActive || undefined}
+          className={`pointer-events-none absolute flex items-center justify-center rounded-lg border border-dashed text-[11px] transition-colors duration-150 ${
+            ghostLaneActive
+              ? "border-studio-accent/60 bg-studio-accent/6 text-studio-accent"
+              : "border-neutral-700/50 text-neutral-500"
+          }`}
+          style={{
+            top: props.rowGeometry.getRowTop(ghostLaneRow) + CLIP_Y,
+            left: props.contentOrigin,
+            width: props.trackContentWidth,
+            height: TRACK_H - CLIP_Y * 2,
+          }}
+        >
+          {props.acceptsMediaDrop && "Drop media here"}
+        </div>
+      )}
 
       {/* Gap strips — loud dashed fill for the gap(s) a hovered "Close gap(s)"
           menu row would collapse; a quiet tint for every gap on the selected
@@ -91,7 +116,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
             key={`gap-${strip.kind}-${strip.track}-${gap.start}`}
             className="pointer-events-none absolute"
             style={{
-              top: getTimelineRowTop(rowIndex, props.rowHeights) + CLIP_Y,
+              top: props.rowGeometry.getRowTop(rowIndex) + CLIP_Y,
               left: props.contentOrigin + gap.start * props.pps,
               width: Math.max((gap.end - gap.start) * props.pps, 2),
               height: TRACK_H - CLIP_Y * 2,
@@ -109,7 +134,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         <div
           className="absolute pointer-events-none"
           style={{
-            top: getTimelineRowTop(draggedRowIndex, props.rowHeights) + CLIP_Y,
+            top: props.rowGeometry.getRowTop(draggedRowIndex) + CLIP_Y,
             left: props.contentOrigin + draggedClip.previewStart * props.pps,
             width: Math.max(draggedClip.element.duration * props.pps, 4),
             height: draggedClipHeight,
@@ -129,7 +154,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           data-testid="timeline-drop-preview"
           className="absolute pointer-events-none"
           style={{
-            top: getTimelineRowTop(dropRowIndex, props.rowHeights) + CLIP_Y,
+            top: props.rowGeometry.getRowTop(dropRowIndex) + CLIP_Y,
             left: props.contentOrigin + props.dropPreview.start * props.pps,
             width: DROP_PREVIEW_SECONDS * props.pps,
             height: TRACK_H - CLIP_Y * 2,
@@ -148,7 +173,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           data-testid="timeline-insert-line"
           className="absolute pointer-events-none"
           style={{
-            top: getTimelineRowTop(insertLineRow, props.rowHeights) - 0.5,
+            top: props.rowGeometry.getRowTop(insertLineRow) - 0.5,
             left: props.contentOrigin,
             width: props.trackContentWidth,
             height: 1,

package/src/player/components/TimelineProvider.tsx

@@ -51,6 +51,7 @@ export type TimelineCanvasState = Omit<
   playheadRef: React.RefObject<HTMLDivElement | null>;
   laneGapStrips: TimelineLaneGapStrips[];
   dropPreview: TimelineDropPlacement | null;
+  acceptsMediaDrop: boolean;
   setRangeSelection: (value: TimelineRangeSelection | null) => void;
   setResizingClip: (value: ResizingClipState | null) => void;
   setDraggedClip: (value: TimelineLaneBaseProps["draggedClip"]) => void;

package/src/player/components/TimelineTypes.ts

@@ -3,6 +3,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineTrackPadding } from "./timelineLayout";
 import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineStackingSyncProps } from "./useTimelineStackingSync";
 
@@ -35,4 +36,5 @@ export interface TimelineProps
   theme?: Partial<TimelineTheme>;
   showAudioEffects?: boolean;
   showKeyframes?: boolean;
+  trackPadding?: TimelineTrackPadding;
 }

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

@@ -12,6 +12,8 @@ import { configureTimelineTestViewport } from "./timelineTestViewport";
 
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+const ROW0_MID_Y = getTimelineRowTop(0) + TRACK_H / 2;
+
 interface DropTransfer {
   types: string[];
   files: File[];
@@ -124,7 +126,7 @@ describe("useTimelineAssetDrop", () => {
     const parent = document.createElement("div");
     const child = document.createElement("div");
     parent.append(child);
-    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, 100)));
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, ROW0_MID_Y)));
     act(() =>
       view.api.handleAssetDragLeave({
         relatedTarget: child,
@@ -160,8 +162,8 @@ describe("useTimelineAssetDrop", () => {
     const transfer = assetTransfer(JSON.stringify({ path: "/media/hero.mp4" }));
 
     act(() => {
-      view.api.handleAssetDragOver(dragEvent(transfer, 80, 100));
-      view.api.handleAssetDrop(dragEvent(transfer, 80, 100));
+      view.api.handleAssetDragOver(dragEvent(transfer, 80, ROW0_MID_Y));
+      view.api.handleAssetDrop(dragEvent(transfer, 80, ROW0_MID_Y));
     });
 
     // pps=40, clientX=80 -> 2s, far from the 50s playhead: proves start tracks
@@ -175,12 +177,12 @@ describe("useTimelineAssetDrop", () => {
     const view = renderHarness(onAssetDrop, 1);
     const transfer = assetTransfer("not-json");
 
-    act(() => view.api.handleAssetDragOver(dragEvent(transfer, 400, 100)));
+    act(() => view.api.handleAssetDragOver(dragEvent(transfer, 400, ROW0_MID_Y)));
     expect(view.api.isDragOver).toBe(true);
     view.rerender(2);
     expect(view.api.isDragOver).toBe(false);
 
-    act(() => view.api.handleAssetDrop(dragEvent(transfer, 400, 100)));
+    act(() => view.api.handleAssetDrop(dragEvent(transfer, 400, ROW0_MID_Y)));
     expect(onAssetDrop).not.toHaveBeenCalled();
     act(() => view.root.unmount());
   });
@@ -202,8 +204,8 @@ describe("useTimelineAssetDrop", () => {
     };
 
     act(() => {
-      view.api.handleAssetDragOver(dragEvent(transfer, 400, 100));
-      view.api.handleAssetDrop(dragEvent(transfer, 400, 100));
+      view.api.handleAssetDragOver(dragEvent(transfer, 400, ROW0_MID_Y));
+      view.api.handleAssetDrop(dragEvent(transfer, 400, ROW0_MID_Y));
     });
 
     expect(onAssetDrop).not.toHaveBeenCalled();
@@ -214,7 +216,7 @@ describe("useTimelineAssetDrop", () => {
 
   it("clears an escaped drag after StrictMode effect replay", () => {
     const view = renderHarness(vi.fn(), 1, { strict: true });
-    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, 100)));
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, ROW0_MID_Y)));
     expect(view.api.isDragOver).toBe(true);
 
     act(() => window.dispatchEvent(new Event("dragend")));
@@ -227,11 +229,11 @@ describe("useTimelineAssetDrop", () => {
     const view = renderHarness(onAssetDrop);
     const payload = JSON.stringify({ path: "assets/a.png" });
 
-    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer(payload), 400, 100)));
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer(payload), 400, ROW0_MID_Y)));
     const preview = view.api.dropPreview;
     expect(preview).toEqual({ start: 10, track: 0 });
 
-    act(() => view.api.handleAssetDrop(dragEvent(assetTransfer(payload), 400, 100)));
+    act(() => view.api.handleAssetDrop(dragEvent(assetTransfer(payload), 400, ROW0_MID_Y)));
     expect(onAssetDrop).toHaveBeenCalledExactlyOnceWith("assets/a.png", preview);
     expect(view.api.dropPreview).toBeNull();
     act(() => view.root.unmount());
@@ -239,8 +241,8 @@ describe("useTimelineAssetDrop", () => {
 
   it("moves the preview with the pointer and drops it when the drag leaves", () => {
     const view = renderHarness(vi.fn());
-    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, 100)));
-    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 800, 100)));
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, ROW0_MID_Y)));
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 800, ROW0_MID_Y)));
     expect(view.api.dropPreview?.start).toBe(20);
 
     act(() =>

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

@@ -19,6 +19,7 @@ import {
   getTimelineBeatEntries,
 } from "./timelineLayout";
 import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import { resolveInsertRow } from "./timelineCollision";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 
 describe("horizontal timeline window", () => {
@@ -124,27 +125,27 @@ describe("variable timeline row geometry", () => {
 
 describe("collapsed timeline row geometry characterization", () => {
   it.each([
-    [0, 74],
-    [1, 122],
-    [4, 266],
+    [0, 32],
+    [1, 80],
+    [4, 224],
   ])("keeps row %i at content y=%i", (row, expectedTop) => {
     expect(getTimelineRowTop(row)).toBe(expectedTop);
   });
 
   it.each([
-    [74, 0],
-    [86, 0.25],
-    [146, 1.5],
-    [290, 4.5],
+    [32, 0],
+    [44, 0.25],
+    [104, 1.5],
+    [248, 4.5],
   ])("maps content y=%i to fractional row %f", (contentY, expectedRow) => {
     expect(getTimelineRowFromY(contentY)).toBe(expectedRow);
   });
 
   it.each([
-    [0, 146],
-    [1, 194],
-    [3, 290],
-    [5, 386],
+    [0, 80],
+    [1, 128],
+    [3, 224],
+    [5, 320],
   ])("keeps the %i-track canvas height at %i", (trackCount, expectedHeight) => {
     expect(getTimelineCanvasHeight(baseRows(trackCount))).toBe(expectedHeight);
   });
@@ -247,6 +248,81 @@ describe("track-area breathing pad y-math", () => {
   });
 });
 
+describe("host track padding", () => {
+  const geometry = createTimelineRowGeometry([0, 1, 2], baseRows(3), { top: 0, bottom: TRACK_H });
+  // Row 1 with no top pad, but still row 0 if any reader keeps the default pad.
+  const yInRow1 = RULER_H + TRACK_H + 10;
+
+  it("moves the first row up and sizes the canvas from the host pads", () => {
+    expect(geometry.getRowTop(0)).toBe(RULER_H);
+    expect(getTimelineRowTop(1, geometry.rowHeights)).toBe(RULER_H + TRACK_H);
+    expect(getTimelineCanvasHeight(geometry.rowHeights)).toBe(RULER_H + 4 * TRACK_H);
+  });
+
+  it("maps a drag pointer y to the row under it", () => {
+    expect(Math.floor(geometry.getRowFromY(yInRow1))).toBe(1);
+    expect(Math.floor(getTimelineRowFromY(yInRow1, geometry.rowHeights))).toBe(1);
+  });
+
+  it("drops onto the row under the pointer, and a new track in the bottom pad", () => {
+    const drop = {
+      rectLeft: 0,
+      rectTop: 0,
+      scrollLeft: 0,
+      scrollTop: 0,
+      contentOrigin: GUTTER,
+      pixelsPerSecond: 100,
+      rowHeights: geometry.rowHeights,
+      trackOrder: [0, 1, 2],
+    };
+    expect(resolveTimelineAssetDrop(drop, GUTTER, yInRow1).track).toBe(1);
+    const inBottomPad = RULER_H + 3 * TRACK_H + TRACK_H / 2;
+    expect(resolveTimelineAssetDrop(drop, GUTTER, inBottomPad).track).toBe(3);
+  });
+
+  it("clamps a negative pad to 0 and replaces a non-finite one with the default", () => {
+    const odd = createTimelineRowGeometry([0], baseRows(1), { top: -20, bottom: Number.NaN });
+    expect(odd.padding).toEqual({ top: 0, bottom: TRACKS_BOTTOM_PAD });
+    expect(odd.getRowTop(0)).toBe(RULER_H);
+    expect(odd.canvasHeight).toBe(RULER_H + TRACK_H + TRACKS_BOTTOM_PAD);
+    const infinite = createTimelineRowGeometry([0], baseRows(1), { top: Infinity });
+    expect(infinite.padding.top).toBe(TRACKS_TOP_PAD);
+  });
+
+  it("keeps the default pads when a host passes none", () => {
+    const defaults = createTimelineRowGeometry([0], baseRows(1));
+    expect(defaults.padding).toEqual({ top: TRACKS_TOP_PAD, bottom: TRACKS_BOTTOM_PAD });
+  });
+});
+
+describe("default track pads", () => {
+  const rows = [TRACK_H, TRACK_H, TRACK_H];
+  const lastLaneBottom = RULER_H + 8 + 3 * TRACK_H;
+
+  it("sits the first row 8px under the ruler and leaves one track below the last", () => {
+    expect(getTimelineRowTop(0)).toBe(RULER_H + 8);
+    expect(getTimelineCanvasHeight(rows)).toBe(lastLaneBottom + TRACK_H);
+  });
+
+  it("opens a new track from anywhere in the bottom lane", () => {
+    const drop = {
+      rectLeft: 0,
+      rectTop: 0,
+      scrollLeft: 0,
+      scrollTop: 0,
+      contentOrigin: GUTTER,
+      pixelsPerSecond: 100,
+      rowHeights: rows,
+      trackOrder: [0, 1, 2],
+    };
+    for (const y of [lastLaneBottom, getTimelineCanvasHeight(rows) - 1]) {
+      expect(resolveTimelineAssetDrop(drop, GUTTER, y).track).toBe(3);
+      expect(resolveInsertRow(getTimelineRowFromY(y, rows), rows.length)).toBe(3);
+    }
+    expect(resolveTimelineAssetDrop(drop, GUTTER, lastLaneBottom - 1).track).toBe(2);
+  });
+});
+
 describe("getTimelineScrubTime", () => {
   const at = (clientX: number, duration = 10) =>
     getTimelineScrubTime({

package/src/player/components/timelineLayout.ts

@@ -55,17 +55,20 @@ export function getTimelineLaneTop(laneIndex: number): number {
   return TRACK_H + Math.max(0, Math.trunc(laneIndex)) * LANE_H;
 }
 /**
- * Breathing room INSIDE the scroll area (CapCut-style), threaded through every
- * track-row y computation via {@link getTimelineRowTop} — never inline a magic
- * offset; a track row's top is always ruler + top pad + cumulative row heights.
+ * Default breathing room INSIDE the scroll area (CapCut-style). A host overrides
+ * it per Timeline; rows always read TimelineRowGeometry.padding, never these.
  *
- * - TRACKS_TOP_PAD: empty space between the (sticky) ruler and the first track
- *   (~half a track height) so the first clip isn't jammed under the ruler.
- * - TRACKS_BOTTOM_PAD: empty space below the last track (~1.5 track heights),
- *   enough to comfortably drag a clip into the void to create a new bottom lane.
+ * - TRACKS_TOP_PAD: empty space between the (sticky) ruler and the first track,
+ *   just enough that the first clip isn't jammed under the ruler.
+ * - TRACKS_BOTTOM_PAD: one empty track below the last, drawn as a ghost lane;
+ *   dropping a clip or file there creates a new bottom track.
  */
-export const TRACKS_TOP_PAD = 50;
-export const TRACKS_BOTTOM_PAD = Math.round(TRACK_H * 1.5);
+export const TRACKS_TOP_PAD = 8;
+export const TRACKS_BOTTOM_PAD = TRACK_H;
+export interface TimelineTrackPadding {
+  top?: number;
+  bottom?: number;
+}
 /**
  * Breathing room LEFT of t=0 (CapCut-style), inside the scroll content — the
  * horizontal sibling of TRACKS_TOP_PAD: empty lane surface between the sticky
@@ -115,12 +118,17 @@ function validRowHeight(height: number | undefined): number {
   return height;
 }
 
+function validPad(pad: number | undefined, fallback: number): number {
+  return pad !== undefined && Number.isFinite(pad) ? Math.max(0, pad) : fallback;
+}
+
 export interface TimelineRowGeometry {
   readonly rowKeys: readonly number[];
   readonly rowHeights: readonly number[];
   /** Cumulative row boundaries, including the final bottom boundary. */
   readonly rowOffsets: readonly number[];
   readonly rowsHeight: number;
+  readonly padding: Readonly<Required<TimelineTrackPadding>>;
   readonly canvasHeight: number;
   getRowIndex(rowKey: number): number;
   getRowHeight(row: number): number;
@@ -141,7 +149,10 @@ const EMPTY_ROW_HEIGHTS: readonly number[] = Object.freeze([]);
 export function createTimelineRowGeometry(
   rowKeys: readonly number[],
   rowHeights: readonly number[],
+  padding: TimelineTrackPadding = {},
 ): TimelineRowGeometry {
+  const topPad = validPad(padding.top, TRACKS_TOP_PAD);
+  const bottomPad = validPad(padding.bottom, TRACKS_BOTTOM_PAD);
   const heights = Object.freeze(rowHeights.map(validRowHeight));
   const keys = Object.freeze(
     heights.map((_, row) => {
@@ -165,7 +176,7 @@ export function createTimelineRowGeometry(
     return (offsets[wholeRow] ?? 0) + (row - wholeRow) * getRowHeight(wholeRow);
   };
   const getRowFromY = (contentY: number) => {
-    const y = contentY - RULER_H - TRACKS_TOP_PAD;
+    const y = contentY - RULER_H - topPad;
     if (heights.length === 0) return y / TRACK_H;
     if (y < 0) return y / getRowHeight(0);
     const rowsHeight = offsets[heights.length] ?? 0;
@@ -188,10 +199,11 @@ export function createTimelineRowGeometry(
     rowHeights: heights,
     rowOffsets: offsets,
     rowsHeight: offsets.at(-1) ?? 0,
-    canvasHeight: RULER_H + TRACKS_TOP_PAD + (offsets.at(-1) ?? 0) + TRACKS_BOTTOM_PAD,
+    padding: Object.freeze({ top: topPad, bottom: bottomPad }),
+    canvasHeight: RULER_H + topPad + (offsets.at(-1) ?? 0) + bottomPad,
     getRowIndex: (rowKey) => rowIndexByKey.get(rowKey) ?? -1,
     getRowHeight,
-    getRowTop: (row) => RULER_H + TRACKS_TOP_PAD + getRowOffset(row),
+    getRowTop: (row) => RULER_H + topPad + getRowOffset(row),
     getRowFromY,
     getRowPositionFromY: (contentY) => {
       const rowFloat = getRowFromY(contentY);
@@ -204,7 +216,7 @@ export function createTimelineRowGeometry(
   return frozenGeometry;
 }
 
-/** Compatibility accessor; repeated calls for one height-array reuse one snapshot. */
+/** Compatibility accessor: a geometry's own rowHeights resolves back to it, pads included. */
 export function getTimelineRowGeometry(rowHeights: readonly number[]): TimelineRowGeometry {
   const cached = rowGeometryCache.get(rowHeights);
   if (cached) return cached;
@@ -228,10 +240,6 @@ export function getTimelineRowHeight(
   return validRowHeight(rowHeights[row]);
 }
 
-function getTimelineRowOffset(row: number, rowHeights: readonly number[]): number {
-  return getTimelineRowGeometry(rowHeights).getRowTop(row) - RULER_H - TRACKS_TOP_PAD;
-}
-
 /**
  * The y (content-space) of the top edge of track ROW index `row` (0 = first
  * displayed lane). The single source of truth for row->y: the ruler height plus
@@ -243,7 +251,7 @@ export function getTimelineRowTop(
   row: number,
   rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
 ): number {
-  return RULER_H + TRACKS_TOP_PAD + getTimelineRowOffset(row, rowHeights);
+  return getTimelineRowGeometry(rowHeights).getRowTop(row);
 }
 
 /**
@@ -484,9 +492,8 @@ export function getTimelinePlaybackFollowScrollLeft(input: {
 }
 
 export function getTimelineCanvasHeight(rowHeights: readonly number[]): number {
-  // RULER_H + top pad + lanes + bottom pad. The old TIMELINE_SCROLL_BUFFER is
-  // subsumed by TRACKS_BOTTOM_PAD (which is larger), so the drag-into-void space
-  // below the last lane is real scrollable surface, not a hidden buffer.
+  // RULER_H + top pad + lanes + bottom pad, read from the geometry's padding.
+  // The drag-into-void space below the last lane is real scrollable surface.
   return getTimelineRowGeometry(rowHeights).canvasHeight;
 }
 

package/src/player/components/useTimelineProviderState.tsx

@@ -65,7 +65,8 @@ export function useTimelineProviderState({
   theme: themeOverrides,
   showAudioEffects = true,
   showKeyframes = true,
-  sessionEpoch = 0,
+  trackPadding,
+  sessionEpoch: sessionEpochProp,
   previewIframeRef,
   onZIndexReorder,
 }: TimelineProps = {}): TimelineContextValue {
@@ -107,6 +108,7 @@ export function useTimelineProviderState({
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
   const timelineSessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
+  const sessionEpoch = sessionEpochProp ?? timelineSessionEpoch;
   const setFocusedEaseSegment = usePlayerStore((s) => s.setFocusedEaseSegment);
   const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
   const playheadRef = useRef<HTMLDivElement>(null);
@@ -143,6 +145,7 @@ export function useTimelineProviderState({
     gsapAnimations,
     selectedElementId,
     selectedElementIds,
+    trackPadding,
   );
   const timelineElementsRef = useRef(timelineElements);
   timelineElementsRef.current = timelineElements; // oxlint-disable-line react/refs -- event handlers read the latest elements
@@ -431,6 +434,7 @@ export function useTimelineProviderState({
     marqueeRect,
     laneGapStrips,
     dropPreview: assetDrop.dropPreview,
+    acceptsMediaDrop: !!(onFileDrop || onAssetDrop),
     theme,
     showAudioEffects,
     displayTrackOrder: displayLayout.displayTrackOrder,