@hyperframes/studio 0.8.94 → 0.8.96

package/src/components/editor/shiftDragAxisLock.test.tsx

@@ -0,0 +1,358 @@
+// @vitest-environment happy-dom
+import React, { act, createRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import type { GestureState, GroupGestureState } from "./domEditOverlayGestures";
+import { DomEditGroupChrome, DomEditSelectionChrome } from "./DomEditSelectionChrome";
+import { createManualOffsetDragMember } from "./manualOffsetDrag";
+import { resolveSnapAdjustment } from "./snapEngine";
+import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function gestureHarness(gesture: Partial<GestureState> | null, group: GroupGestureState | null) {
+  const opts = {
+    gestureRef: { current: gesture },
+    groupGestureRef: { current: group },
+    selectionRef: { current: null },
+    hoverSelectionRef: { current: null },
+    boxRef: { current: null },
+    blockedMoveRef: { current: null },
+    rafPausedRef: { current: false },
+    suppressNextBoxClickRef: { current: false },
+    snapGuidesRef: { current: null },
+    setOverlayRect: vi.fn(),
+    setGroupOverlayItems: vi.fn(),
+    onCanvasMouseDown: vi.fn(),
+    onCanvasPointerMoveRef: { current: vi.fn() },
+    onPathOffsetCommitRef: { current: vi.fn() },
+    onGroupPathOffsetCommitRef: { current: vi.fn() },
+  };
+  const handlers = createDomEditOverlayGestureHandlers(opts as never);
+  const pointer = (clientX: number, clientY: number, shiftKey: boolean) =>
+    ({ clientX, clientY, shiftKey, altKey: false }) as never;
+  return { opts, handlers, pointer };
+}
+
+function singleDrag() {
+  const element = document.createElement("div");
+  return gestureHarness(
+    {
+      kind: "drag",
+      mode: "path-offset",
+      selection: { element } as unknown as DomEditSelection,
+      startX: 100,
+      startY: 100,
+      originLeft: 10,
+      originTop: 20,
+      originWidth: 50,
+      originHeight: 40,
+      editScaleX: 1,
+      editScaleY: 1,
+      actualRotation: 0,
+    },
+    null,
+  );
+}
+
+const groupGesture = () =>
+  ({ startX: 100, startY: 100, originItems: [], members: [] }) as unknown as GroupGestureState;
+
+describe("shift+drag locks a move to the axis the pointer travels further on", () => {
+  it("keeps a mostly horizontal single drag on its row", () => {
+    const { opts, handlers, pointer } = singleDrag();
+    handlers.onPointerMove(pointer(130, 108, true));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 40, top: 20 }),
+    );
+  });
+
+  it("keeps a mostly vertical single drag on its column", () => {
+    const { opts, handlers, pointer } = singleDrag();
+    handlers.onPointerMove(pointer(95, 160, true));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 10, top: 80 }),
+    );
+  });
+
+  it("frees the drag on the next move once shift is released, and locks again when pressed", () => {
+    const { opts, handlers, pointer } = singleDrag();
+    handlers.onPointerMove(pointer(130, 108, false));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 40, top: 28 }),
+    );
+    handlers.onPointerMove(pointer(140, 110, true));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 50, top: 20 }),
+    );
+  });
+
+  it("locks a group drag the same way", () => {
+    const group = groupGesture();
+    const { handlers, pointer } = gestureHarness(null, group);
+    handlers.onPointerMove(pointer(130, 108, true));
+    expect([group.lastSnappedDx, group.lastSnappedDy]).toEqual([30, 0]);
+  });
+
+  it("snaps a locked drag only along its free axis", () => {
+    const target = {
+      id: "t",
+      left: 0,
+      top: 203,
+      right: 400,
+      bottom: 303,
+      centerX: 200,
+      centerY: 253,
+    };
+    const snap = (lockedAxis?: "x" | "y") =>
+      resolveSnapAdjustment({
+        movingRect: { left: 0, top: 0, width: 50, height: 200 },
+        proposedDx: 97,
+        proposedDy: 0,
+        targets: [target],
+        threshold: 6,
+        disabled: false,
+        lockedAxis,
+      } as never);
+    expect(snap().dy).toBe(3);
+    const locked = snap("y");
+    expect(locked.dy).toBe(0);
+    expect(locked.guides.every((guide) => guide.axis === "x")).toBe(true);
+  });
+});
+
+describe("shift+click on a selected box still toggles the element under the pointer", () => {
+  it.each([
+    ["group", () => gestureHarness(null, groupGesture())],
+    ["single", () => singleMemberDrag()],
+  ])(
+    "hands a %s shift press that never travelled to the canvas as an additive click",
+    (_, make) => {
+      const { opts, handlers, pointer } = make();
+      handlers.onPointerUp(pointer(101, 100, true));
+      expect(opts.onCanvasMouseDown).toHaveBeenCalledWith(
+        expect.objectContaining({ shiftKey: true }),
+        expect.objectContaining({ preferClipAncestor: false }),
+      );
+      expect(opts.suppressNextBoxClickRef.current).toBe(true);
+    },
+  );
+
+  it("leaves a plain press on the group box alone", () => {
+    const { opts, handlers, pointer } = gestureHarness(null, groupGesture());
+    handlers.onPointerUp(pointer(101, 100, false));
+    expect(opts.onCanvasMouseDown).not.toHaveBeenCalled();
+  });
+});
+
+describe("a shift press on a selected box starts the drag", () => {
+  const rect = { left: 10, top: 10, width: 200, height: 100, editScaleX: 1, editScaleY: 1 };
+  const gestures = () => ({
+    startGesture: vi.fn(),
+    startGroupDrag: vi.fn(),
+    startBlockedMove: vi.fn(),
+  });
+  const shiftPress = (el: Element) =>
+    act(() => {
+      el.dispatchEvent(
+        new PointerEvent("pointerdown", {
+          bubbles: true,
+          cancelable: true,
+          shiftKey: true,
+          pointerId: 1,
+        }),
+      );
+    });
+
+  function mount(node: (spies: ReturnType<typeof gestures>) => React.ReactNode) {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const spies = gestures();
+    act(() => root.render(node(spies)));
+    const box = host.querySelector<HTMLElement>('[data-dom-edit-selection-box="true"]')!;
+    return { spies, box, unmount: () => act(() => root.unmount()) };
+  }
+
+  const single = (canMove: boolean) =>
+    mount((spies) => (
+      <DomEditSelectionChrome
+        selection={
+          {
+            element: document.createElement("div"),
+            capabilities: { canApplyManualOffset: canMove },
+          } as unknown as DomEditSelection
+        }
+        overlayRect={rect}
+        allowCanvasMovement
+        allowBodyDrag
+        boxRef={createRef()}
+        boxChromeClass=""
+        boxClipPath={undefined}
+        selectionKey="box"
+        groupSelectionCount={0}
+        gestures={spies as never}
+        onBoxMouseDown={vi.fn()}
+        onBoxClick={vi.fn()}
+      />
+    ));
+
+  const group = (groupCanMove: boolean) =>
+    mount((spies) => (
+      <DomEditGroupChrome
+        groupOverlayItems={[]}
+        groupBounds={rect}
+        allowCanvasMovement
+        allowBodyDrag
+        groupCanMove={groupCanMove}
+        gestures={spies as never}
+        onBoxMouseDown={vi.fn()}
+        onBoxClick={vi.fn()}
+      />
+    ));
+
+  it("drags a single selection", () => {
+    const { spies, box, unmount } = single(true);
+    shiftPress(box);
+    expect(spies.startGesture).toHaveBeenCalledWith("drag", expect.anything());
+    unmount();
+  });
+
+  it("drags a group selection", () => {
+    const { spies, box, unmount } = group(true);
+    shiftPress(box);
+    expect(spies.startGroupDrag).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it("leaves a shift press on a box that cannot move to the multi-select toggle", () => {
+    const one = single(false);
+    shiftPress(one.box);
+    expect(one.spies.startBlockedMove).not.toHaveBeenCalled();
+    one.unmount();
+    const many = group(false);
+    shiftPress(many.box);
+    expect(many.spies.startGroupDrag).not.toHaveBeenCalled();
+    many.unmount();
+  });
+});
+
+type GsapStub = {
+  set: (el: Element, vars: object) => void;
+  getProperty: (el: Element, p: string) => number;
+};
+
+function previewGsap(): GsapStub {
+  const win = window as unknown as { gsap?: GsapStub };
+  if (win.gsap) return win.gsap;
+  const positions = new WeakMap<Element, Record<string, number>>();
+  win.gsap = {
+    set: (el, vars) => positions.set(el, { ...positions.get(el), ...vars }),
+    getProperty: (el, prop) => positions.get(el)?.[prop] ?? 0,
+  };
+  return win.gsap;
+}
+
+function draggableMember(key: string) {
+  const gsap = previewGsap();
+  const element = document.createElement("div");
+  document.body.append(element);
+  gsap.set(element, { x: 10, y: -10 });
+  const selection = {
+    element,
+    capabilities: { canApplyManualOffset: true },
+  } as unknown as DomEditSelection;
+  const result = createManualOffsetDragMember({
+    key,
+    selection,
+    element,
+    rect: { left: 0, top: 0, width: 50, height: 40, editScaleX: 1, editScaleY: 1 },
+  } as never);
+  if (!result.ok) throw new Error(result.reason);
+  const at = () => [gsap.getProperty(element, "x"), gsap.getProperty(element, "y")];
+  return { member: result.member, selection, at };
+}
+
+function singleMemberDrag() {
+  const { member, selection, at } = draggableMember("single");
+  const harness = gestureHarness(
+    {
+      kind: "drag",
+      mode: "path-offset",
+      selection,
+      startX: 100,
+      startY: 100,
+      originLeft: 0,
+      originTop: 0,
+      originWidth: 50,
+      originHeight: 40,
+      editScaleX: 1,
+      editScaleY: 1,
+      actualRotation: 0,
+      pathOffsetMember: member,
+      initialPathOffset: member.initialPathOffset,
+      manualEditDragToken: member.gestureToken,
+    },
+    null,
+  );
+  return { ...harness, at };
+}
+
+function groupMemberDrag() {
+  const a = draggableMember("a");
+  const b = draggableMember("b");
+  const group = { startX: 100, startY: 100, originItems: [], members: [a.member, b.member] };
+  const harness = gestureHarness(null, group as unknown as GroupGestureState);
+  return { ...harness, at: () => [a.at(), b.at()] };
+}
+
+afterEach(() => {
+  delete (window as unknown as { gsap?: GsapStub }).gsap;
+});
+
+describe("a press that stays under the drag threshold puts the preview back where it started", () => {
+  it.each([true, false])("single, shift %s", (shift) => {
+    const { handlers, pointer, at } = singleMemberDrag();
+    handlers.onPointerMove(pointer(102, 100, shift));
+    expect(at()).toEqual([12, -10]);
+    handlers.onPointerUp(pointer(102, 100, shift));
+    expect(at()).toEqual([10, -10]);
+  });
+
+  it.each([true, false])("group, shift %s", (shift) => {
+    const { handlers, pointer, at } = groupMemberDrag();
+    handlers.onPointerMove(pointer(102, 100, shift));
+    handlers.onPointerUp(pointer(102, 100, shift));
+    expect(at()).toEqual([
+      [10, -10],
+      [10, -10],
+    ]);
+  });
+});
+
+describe("a drag that travelled is not a click, even when it ends near its start", () => {
+  it.each([
+    ["single", singleMemberDrag, "onPathOffsetCommitRef"],
+    ["group", groupMemberDrag, "onGroupPathOffsetCommitRef"],
+  ] as const)("commits a %s shift drag instead of toggling", (_, make, commit) => {
+    const { opts, handlers, pointer } = make();
+    handlers.onPointerMove(pointer(180, 100, true));
+    handlers.onPointerMove(pointer(101, 100, true));
+    handlers.onPointerUp(pointer(101, 100, true));
+    expect(opts.onCanvasMouseDown).not.toHaveBeenCalled();
+    expect(opts[commit].current).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("a cancelled drag puts the preview back where it started", () => {
+  it("returns a single drag that travelled to its start and saves nothing", () => {
+    const { opts, handlers, pointer, at } = singleMemberDrag();
+    handlers.onPointerMove(pointer(140, 100, false));
+    expect(at()).toEqual([50, -10]);
+    handlers.clearPointerState({ current: null });
+    expect(at()).toEqual([10, -10]);
+    expect(opts.gestureRef.current).toBeNull();
+    expect(opts.onPathOffsetCommitRef.current).not.toHaveBeenCalled();
+  });
+});

package/src/components/editor/snapEngine.ts

@@ -379,6 +379,7 @@ export function resolveSnapAdjustment(input: {
   disabled: boolean;
   /** Set when the gesture has not travelled far enough for snapping yet. */
   disabledForTravel?: boolean;
+  lockedAxis?: "x" | "y";
 }): SnapResult {
   if (input.disabled || input.disabledForTravel || input.threshold <= 0) {
     return DISABLED_RESULT(input.proposedDx, input.proposedDy);
@@ -407,8 +408,8 @@ export function resolveSnapAdjustment(input: {
     input.threshold,
   );
 
-  const bestX = pickBest(xCandidates);
-  const bestY = pickBest(yCandidates);
+  const bestX = input.lockedAxis === "x" ? null : pickBest(xCandidates);
+  const bestY = input.lockedAxis === "y" ? null : pickBest(yCandidates);
   const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
   const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);
 

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -12,7 +12,6 @@ import {
   applyRotationDraftViaGsap,
   endManualOffsetDragMembers,
   restoreManualOffsetDragMembers,
-  resumeGsapTimelines,
 } from "./manualOffsetDrag";
 import {
   applyStudioBoxSize,
@@ -40,6 +39,7 @@ import {
   type UseDomEditOverlayGesturesOptions,
   ROTATED_SNAP_BYPASS_DEGREES,
   hasDomEditRotationChanged,
+  lockDragToDominantAxis,
   resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
 import { resolveCenterResizeSize } from "./domEditResizeLocal";
@@ -61,6 +61,13 @@ import { logDrag, logDragSettle, readDragPositions } from "../../utils/dragDebug
 import { createGroupDragMover } from "./groupDragMove";
 import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
 
+function isTap(g: { startX: number; startY: number; travelled?: boolean }, e: React.PointerEvent) {
+  return (
+    !g.travelled &&
+    Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < BLOCKED_MOVE_THRESHOLD_PX
+  );
+}
+
 function logGestureCommitFailure(message: string, error: unknown): void {
   if (error instanceof DomEditSaveQueueOpenError) return;
   console.error(message, error);
@@ -136,11 +143,13 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (groupG) {
+      if (!isTap(groupG, e)) groupG.travelled = true;
       moveGroupDrag(groupG, e);
       return;
     }
 
     if (!g || !sel) return;
+    if (!isTap(g, e)) g.travelled = true;
     let dx = e.clientX - g.startX;
     let dy = e.clientY - g.startY;
 
@@ -164,6 +173,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (g.kind === "drag") {
+      const lock = lockDragToDominantAxis(dx, dy, e.shiftKey);
+      dx = lock.dx;
+      dy = lock.dy;
       const sc = g.snapContext;
       // Bypass edge-snapping for rotated elements — the snap targets and the
       // snapped rect are axis-aligned, so snapping a rotated box's AABB shifts it
@@ -196,6 +208,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           gridEdges: sc.gridEdges ?? undefined,
           threshold: SNAP_THRESHOLD_PX,
           disabled: e.altKey,
+          lockedAxis: lock.lockedAxis,
         });
         dx = snap.dx;
         dy = snap.dy;
@@ -302,8 +315,14 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       // ordinary click — which lands between the members, resolves to nothing,
       // and deselects the group the drag just moved.
       opts.suppressNextBoxClickRef.current = true;
-      if (Math.hypot(rawDx, rawDy) < BLOCKED_MOVE_THRESHOLD_PX) {
+      if (isTap(groupG, e)) {
         restoreGroupPathOffsets(groupG);
+        if (e.shiftKey) {
+          opts.onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
+            preferClipAncestor: false,
+            hoverSelection: opts.hoverSelectionRef.current,
+          });
+        }
         return;
       }
       const dx = groupG.lastSnappedDx ?? rawDx;
@@ -360,10 +379,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     opts.rafPausedRef.current = false;
     const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
 
-    if (g.kind === "drag" && movedDistance < BLOCKED_MOVE_THRESHOLD_PX) {
-      restoreStudioPathOffset(sel.element, g.initialPathOffset);
-      endStudioManualEditGesture(sel.element, g.manualEditDragToken);
-      resumeGsapTimelines(sel.element);
+    if (g.kind === "drag" && isTap(g, e)) {
+      if (g.pathOffsetMember) restoreManualOffsetDragMembers([g.pathOffsetMember]);
       if (box) {
         box.style.left = `${g.originLeft}px`;
         box.style.top = `${g.originTop}px`;
@@ -525,9 +542,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     const g = opts.gestureRef.current;
     const sel = g?.selection ?? selectionRef.current;
     if (g?.mode === "path-offset" && sel) {
-      restoreStudioPathOffset(sel.element, g.initialPathOffset);
-      endStudioManualEditGesture(sel.element, g.manualEditDragToken);
-      resumeGsapTimelines(sel.element);
+      if (g.pathOffsetMember) restoreManualOffsetDragMembers([g.pathOffsetMember]);
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "box-size" && sel) {

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

@@ -0,0 +1,126 @@
+// @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, TRACK_H, getTimelineRowTop } 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 = "";
+});
+
+const GHOST_MID = getTimelineRowTop(3) + TRACK_H / 2;
+const ROW1_MID = getTimelineRowTop(1) + TRACK_H / 2;
+
+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 {...props} />));
+  const ghost = () => host.querySelector<HTMLElement>('[data-testid="timeline-ghost-lane"]');
+  return { host, root, ghost };
+}
+
+describe("Timeline ghost lane", () => {
+  it("draws one empty track below the last with a drop hint", async () => {
+    const { root, ghost } = await mountThreeTracks({ onAssetDrop: vi.fn() });
+    expect(ghost()?.textContent).toBe("Drop media here");
+    expect(ghost()?.getAttribute("aria-hidden")).toBe("true");
+    expect(ghost()?.style.top).toBe(`${getTimelineRowTop(3) + CLIP_Y}px`);
+    expect(ghost()?.dataset.active).toBeUndefined();
+    act(() => root.unmount());
+  });
+
+  it("drops the hint without a drop handler and the lane without a bottom pad", async () => {
+    const readOnly = await mountThreeTracks();
+    expect(readOnly.ghost()?.textContent).toBe("");
+    act(() => readOnly.root.unmount());
+    const unpadded = await mountThreeTracks({ trackPadding: { bottom: 0 } });
+    expect(unpadded.ghost()).toBeNull();
+    act(() => unpadded.root.unmount());
+  });
+
+  it("lights up under a file dragged into it and opens a new track on drop", async () => {
+    const onAssetDrop = vi.fn();
+    const { host, root, ghost } = await mountThreeTracks({ onAssetDrop });
+    const viewport = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]")!;
+    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(ghost()?.dataset.active).toBeUndefined();
+    drag("dragover", GHOST_MID);
+    expect(ghost()?.dataset.active).toBe("true");
+    drag("drop", GHOST_MID);
+    expect(onAssetDrop).toHaveBeenCalledWith("a.png", expect.objectContaining({ track: 3 }));
+    act(() => root.unmount());
+  });
+
+  it.each([0, 2])("lights up under clip c%i dragged into it", async (track) => {
+    const { host, root, ghost } = 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 clipMid = getTimelineRowTop(track) + TRACK_H / 2;
+    pointer(host.querySelector(`[data-clip][data-el-id="c${track}"]`)!, "pointerdown", clipMid);
+    pointer(window, "pointermove", ROW1_MID);
+    expect(ghost()?.dataset.active).toBeUndefined();
+    pointer(window, "pointermove", GHOST_MID);
+    expect(ghost()?.dataset.active).toBe("true");
+    // Dragging the last track's clip adds a preview row; the lane must stay under the pointer.
+    expect(ghost()?.style.top).toBe(`${getTimelineRowTop(3) + CLIP_Y}px`);
+    act(() => root.unmount());
+  });
+});

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

@@ -108,4 +108,11 @@ describe("Timeline ruler origin", () => {
     expect(origin).toBe("80px");
     expect(published).toBe("80");
   });
+
+  it("seeks on a press when the host omits sessionEpoch after a session began", async () => {
+    usePlayerStore.getState().beginTimelineSession("host-project");
+    expect(usePlayerStore.getState().timelineSessionEpoch).toBeGreaterThan(0);
+    const { time, tickTime } = await seekOnFirstTick({}, false);
+    expect(time).toBeCloseTo(tickTime, 1);
+  });
 });

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

@@ -35,6 +35,7 @@ import {
   getTimelineDisplayContentWidth,
   getTimelineFitPps,
   getTimelineLaneTop,
+  getTimelineRowTop,
   createTimelineRowGeometry,
 } from "./timelineLayout";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
@@ -1292,9 +1293,8 @@ describe("resolveTimelineAssetDrop", () => {
           trackOrder: [0, 3, 7],
         },
         432, // rectLeft(100) + GUTTER(32) + 3s*100pps  (contentOrigin = GUTTER)
-        // clientY: rectTop(200) + RULER_H(24) + TRACKS_TOP_PAD(72) + TRACK_H(48)
-        // + TRACK_H/2(24) = 368 → row 1 → track 3.
-        368,
+        // clientY: rectTop(200) + the middle of row 1 → track 3.
+        200 + getTimelineRowTop(1) + TRACK_H / 2,
       ),
     ).toEqual({ start: 3, track: 3 });
   });

package/src/player/components/TimelineCanvas.tsx

@@ -24,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
@@ -61,14 +68,35 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
         onRazorSplitAll={props.onRazorSplitAll}
       />
 
-      {/* Breathing room below the last track lane (1.5 tracks by default) — 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 TimelineRowGeometry.padding / canvasHeight). */}
+          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
           clip's lane. Geometry mirrors the drop placeholder (row top + clip