@hyperframes/studio 0.8.49 → 0.8.51

package/src/player/components/timelineDragDrop.ts

@@ -4,8 +4,14 @@ import {
   parseTimelineCompositionPayload,
   TIMELINE_COMPOSITION_MIME,
 } from "../../utils/timelineCompositionDrop";
-import { resolveTimelineAssetDrop, type TimelineRowGeometry } from "./timelineLayout";
-import type { TimelineDropCallbacks } from "./timelineCallbacks";
+import {
+  getTimelineInsertBoundaryBand,
+  getTimelineRowPositionFromY,
+  resolveTimelineAssetDrop,
+  type TimelineRowGeometry,
+} from "./timelineLayout";
+import { resolveInsertRow } from "./timelineCollision";
+import type { TimelineDropCallbacks, TimelineDropPlacement } from "./timelineCallbacks";
 import {
   applyTimelineAutoScrollStep,
   resolveTimelineAutoScrollLoopAction,
@@ -20,8 +26,6 @@ interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   sessionEpoch: number;
 }
 
-type TimelinePlacement = { start: number; track: number };
-
 /**
  * Parse a JSON drag payload and, if it yields a value, forward it to the drop
  * callback. Malformed payloads are ignored. Shared by the asset + block paths so
@@ -30,8 +34,8 @@ type TimelinePlacement = { start: number; track: number };
 function applyJsonDropPayload(
   raw: string,
   pick: (parsed: Record<string, string | undefined>) => string | undefined,
-  apply: (value: string, placement: TimelinePlacement) => void,
-  placement: TimelinePlacement,
+  apply: (value: string, placement: TimelineDropPlacement) => void,
+  placement: TimelineDropPlacement,
 ): boolean {
   try {
     const value = pick(JSON.parse(raw) as Record<string, string | undefined>);
@@ -43,6 +47,40 @@ function applyJsonDropPayload(
   }
 }
 
+/** Only file and asset drops are written by the asset op that can open a track. */
+function canInsertTrackFor(types: readonly string[]): boolean {
+  return types.includes("Files") || types.includes(TIMELINE_ASSET_MIME);
+}
+
+/** The row boundary a pointer at `contentY` arms for a new track, or null over a lane's middle. */
+export function resolveDropInsertRow(
+  contentY: number,
+  rowHeights: readonly number[] | undefined,
+  trackCount: number,
+): number | null {
+  if (trackCount === 0) return null;
+  const { rowFloat, rowHeight } = getTimelineRowPositionFromY(contentY, rowHeights);
+  // Past the last lane the drop already appends a track (getDefaultDroppedTrack).
+  if (rowFloat >= trackCount) return null;
+  return resolveInsertRow(rowFloat, trackCount, getTimelineInsertBoundaryBand(rowHeight));
+}
+
+function placeDrop(
+  geometry: Parameters<typeof resolveTimelineAssetDrop>[0],
+  clientX: number,
+  clientY: number,
+  // Blocks and compositions are written by their own installers, which only take a track.
+  canInsertTrack: boolean,
+): TimelineDropPlacement {
+  const placement = resolveTimelineAssetDrop(geometry, clientX, clientY);
+  if (!canInsertTrack) return placement;
+  const contentY = clientY - geometry.rectTop + geometry.scrollTop;
+  const insertRow = resolveDropInsertRow(contentY, geometry.rowHeights, geometry.trackOrder.length);
+  return insertRow == null
+    ? placement
+    : { ...placement, insertRow, trackOrder: geometry.trackOrder };
+}
+
 function invokeDropCallback(callback: () => Promise<void> | void): void {
   try {
     void Promise.resolve(callback()).catch(() => undefined);
@@ -54,7 +92,7 @@ function invokeDropCallback(callback: () => Promise<void> | void): void {
 function applyFileDrop(
   transfer: DataTransfer,
   onFileDrop: TimelineDropCallbacks["onFileDrop"],
-  placement: TimelinePlacement,
+  placement: TimelineDropPlacement,
 ): boolean {
   if (!onFileDrop || transfer.files.length === 0) return false;
   invokeDropCallback(() => onFileDrop(Array.from(transfer.files), placement));
@@ -65,8 +103,8 @@ function applyTypedJsonDrop(
   transfer: DataTransfer,
   mime: string,
   field: "name" | "path",
-  apply: ((value: string, placement: TimelinePlacement) => Promise<void> | void) | undefined,
-  placement: TimelinePlacement,
+  apply: ((value: string, placement: TimelineDropPlacement) => Promise<void> | void) | undefined,
+  placement: TimelineDropPlacement,
 ): boolean {
   if (!apply || !Array.from(transfer.types).includes(mime)) return false;
   const payload = transfer.getData(mime);
@@ -98,6 +136,7 @@ export function useTimelineAssetDrop({
   sessionEpoch,
 }: UseTimelineAssetDropOptions) {
   const [isDragOver, setIsDragOver] = useState(false);
+  const [dropPreview, setDropPreview] = useState<TimelineDropPlacement | null>(null);
   const dragPointerRef = useRef<{ clientX: number; clientY: number; sessionEpoch: number } | null>(
     null,
   );
@@ -142,6 +181,29 @@ export function useTimelineAssetDrop({
     [scrollRef, sessionEpoch, stepAutoScroll],
   );
 
+  const resolveDropPlacement = useCallback(
+    (clientX: number, clientY: number, canInsertTrack: boolean): TimelineDropPlacement => {
+      const scroll = scrollRef.current;
+      const rect = scroll?.getBoundingClientRect();
+      return placeDrop(
+        {
+          rectLeft: rect?.left ?? 0,
+          rectTop: rect?.top ?? 0,
+          scrollLeft: scroll?.scrollLeft ?? 0,
+          scrollTop: scroll?.scrollTop ?? 0,
+          contentOrigin,
+          pixelsPerSecond: ppsRef.current,
+          rowHeights: rowGeometryRef.current.rowHeights,
+          trackOrder: trackOrderRef.current,
+        },
+        clientX,
+        clientY,
+        canInsertTrack,
+      );
+    },
+    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
+  );
+
   const handleAssetDragOver = useCallback(
     (e: React.DragEvent) => {
       const types = Array.from(e.dataTransfer.types);
@@ -154,15 +216,22 @@ export function useTimelineAssetDrop({
       e.dataTransfer.dropEffect = "copy";
       activeDropEpochRef.current = sessionEpoch;
       setIsDragOver(true);
+      const next = resolveDropPlacement(e.clientX, e.clientY, canInsertTrackFor(types));
+      setDropPreview((prev) =>
+        prev?.start === next.start && prev.track === next.track && prev.insertRow === next.insertRow
+          ? prev
+          : next,
+      );
       syncAutoScroll(e.clientX, e.clientY);
     },
-    [sessionEpoch, syncAutoScroll],
+    [resolveDropPlacement, sessionEpoch, syncAutoScroll],
   );
 
   const clearDropPreview = useCallback(() => {
     activeDropEpochRef.current = null;
     stopAutoScroll();
     setIsDragOver(false);
+    setDropPreview(null);
   }, [stopAutoScroll]);
 
   const handleAssetDragLeave = useCallback(
@@ -174,35 +243,14 @@ export function useTimelineAssetDrop({
     [clearDropPreview],
   );
 
-  const resolveDropPlacement = useCallback(
-    (clientX: number, clientY: number): TimelinePlacement => {
-      const scroll = scrollRef.current;
-      const rect = scroll?.getBoundingClientRect();
-      return resolveTimelineAssetDrop(
-        {
-          rectLeft: rect?.left ?? 0,
-          rectTop: rect?.top ?? 0,
-          scrollLeft: scroll?.scrollLeft ?? 0,
-          scrollTop: scroll?.scrollTop ?? 0,
-          contentOrigin,
-          pixelsPerSecond: ppsRef.current,
-          rowHeights: rowGeometryRef.current.rowHeights,
-          trackOrder: trackOrderRef.current,
-        },
-        clientX,
-        clientY,
-      );
-    },
-    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
-  );
-
   const handleAssetDrop = useCallback(
     (e: React.DragEvent) => {
       e.preventDefault();
       const canCommit = activeDropEpochRef.current === sessionEpoch;
       clearDropPreview();
       if (!canCommit) return;
-      const placement = resolveDropPlacement(e.clientX, e.clientY);
+      const types = Array.from(e.dataTransfer.types);
+      const placement = resolveDropPlacement(e.clientX, e.clientY, canInsertTrackFor(types));
 
       const compositionPayload = parseTimelineCompositionPayload(
         e.dataTransfer.getData(TIMELINE_COMPOSITION_MIME),
@@ -240,6 +288,7 @@ export function useTimelineAssetDrop({
 
   return {
     isDragOver,
+    dropPreview,
     handleAssetDragOver,
     handleAssetDragLeave,
     handleAssetDrop,

package/src/player/components/timelineEditCapabilities.ts

@@ -42,10 +42,9 @@ export function getTimelineEditCapabilities(input: {
   playbackStart?: number;
   playbackStartAttr?: "media-start" | "playback-start";
   sourceDuration?: number;
-  timingSource?: "authored" | "implicit";
   timelineLocked?: boolean;
 }): TimelineEditCapabilities {
-  if (input.timingSource === "implicit" || input.timelineLocked) {
+  if (input.timelineLocked) {
     return { canMove: false, canTrimStart: false, canTrimEnd: false };
   }
 

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

@@ -412,21 +412,6 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("keeps implicit layout layers selectable but not timeline-editable", () => {
-    expect(
-      getTimelineEditCapabilities({
-        duration: 8,
-        selector: ".scene-shell",
-        tag: "div",
-        timingSource: "implicit",
-      }),
-    ).toEqual({
-      canMove: false,
-      canTrimStart: false,
-      canTrimEnd: false,
-    });
-  });
-
   it("allows move and both trims for patchable media clips with offset support", () => {
     expect(
       getTimelineEditCapabilities({
@@ -496,7 +481,6 @@ describe("getTimelineEditCapabilities", () => {
         tag: "div",
         duration: 4,
         selector: "#hero-card",
-        timingSource: "authored",
       }),
     ).toEqual({
       canMove: true,

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

@@ -34,11 +34,9 @@ describe("buildTimelineGroupResizeMembers (legacy 36413da7f semantics)", () => {
     expect(buildTimelineGroupResizeMembers([a, locked], keys("a", "b"), "a", "end")).toBeNull();
   });
 
-  it("degrades when a member is implicitly timed or has no patch target", () => {
+  it("degrades when a member 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();
   });
 

package/src/player/components/timelineGroupEditing.ts

@@ -198,7 +198,6 @@ function canTrimEdge(element: TimelineElement, edge: TimelineGroupResizeEdge): b
     playbackStart: element.playbackStart,
     playbackStartAttr: element.playbackStartAttr,
     sourceDuration: element.sourceDuration,
-    timingSource: element.timingSource,
     timelineLocked: element.timelineLocked,
   });
   return edge === "start" ? caps.canTrimStart : caps.canTrimEnd;

package/src/player/components/timelineLaneProps.ts

@@ -8,6 +8,7 @@ import type { TrackVisualStyle } from "./timelineIcons";
 import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
 import type { TimelineClipIndex, TimelineTimeRange } from "../lib/timelineClipIndex";
 import type { TimelineRowGeometry } from "./timelineLayout";
+import type { TimelineSnapTarget } from "./timelineSnapping";
 import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
 import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -112,6 +113,8 @@ export interface TimelineLaneBaseProps {
 export interface TimelineLanesProps extends TimelineLaneBaseProps {
   /** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
   draggedElement: TimelineElement | null;
+  /** Live move or trim snap target, resolved once by TimelineCanvas. */
+  snapGuide: TimelineSnapTarget | null;
   multiDragPreview: MultiDragPreviewInput | null;
   onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
   onTogglePropertyGroupKeyframe: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];

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

@@ -4,6 +4,7 @@ import {
   collectTimelineSnapTargets,
   snapMoveToTargets,
   snapTimelineTime,
+  resolveSnapGuide,
 } from "./timelineSnapping";
 
 describe("collectTimelineSnapTargets", () => {
@@ -26,6 +27,18 @@ describe("collectTimelineSnapTargets", () => {
     expect(targets).toContainEqual({ time: 0.5, type: "beat" });
   });
 
+  it("omits the playhead when includePlayhead is false, for a trim", () => {
+    const targets = collectTimelineSnapTargets({
+      elements,
+      playheadTime: 7.25,
+      beatTimes: [0.5],
+      includePlayhead: false,
+    });
+    expect(targets.some((t) => t.type === "playhead")).toBe(false);
+    expect(targets).toContainEqual({ time: 2, type: "clip-edge" });
+    expect(targets).toContainEqual({ time: 0.5, type: "beat" });
+  });
+
   it("excludes the dragged element's own edges", () => {
     const targets = collectTimelineSnapTargets({
       elements,
@@ -132,3 +145,17 @@ describe("snapMoveToTargets", () => {
     expect(r.snapTime).toBeNull();
   });
 });
+
+describe("resolveSnapGuide", () => {
+  it("prefers a started move, falls back to a trim, and is null when neither snapped", () => {
+    const move = { started: true, snapTime: 2, snapType: "playhead" as const };
+    const trim = { snapTime: 5, snapType: "clip-edge" as const };
+    expect(resolveSnapGuide(move, trim)).toEqual({ time: 2, type: "playhead" });
+    expect(resolveSnapGuide({ ...move, started: false }, trim)).toEqual({
+      time: 5,
+      type: "clip-edge",
+    });
+    expect(resolveSnapGuide(null, { snapTime: null, snapType: null })).toBeNull();
+    expect(resolveSnapGuide(null, null)).toBeNull();
+  });
+});

package/src/player/components/timelineSnapping.ts

@@ -7,6 +7,16 @@ export interface TimelineSnapTarget {
   type: TimelineSnapType;
 }
 
+/** The guide the canvas draws: the live move's snap target, else the live trim's. */
+export function resolveSnapGuide(
+  moving: { started: boolean; snapTime: number | null; snapType: TimelineSnapType | null } | null,
+  trimming: { snapTime?: number | null; snapType?: TimelineSnapType | null } | null,
+): TimelineSnapTarget | null {
+  const source = moving?.started ? moving : trimming;
+  if (source?.snapTime == null || source.snapType == null) return null;
+  return { time: source.snapTime, type: source.snapType };
+}
+
 /** Pixel radius within which a time snaps to a target (matches historical beat snap). */
 export const TIMELINE_SNAP_PX = 8;
 
@@ -21,6 +31,8 @@ export function collectTimelineSnapTargets(input: {
   playheadTime: number | null;
   beatTimes: readonly number[];
   excludeElementKey?: string | null;
+  /** A trim excludes the playhead: the dragged edge drives it, so snapping to it is circular. */
+  includePlayhead?: boolean;
 }): TimelineSnapTarget[] {
   const byTime = new Map<number, TimelineSnapTarget>();
   const add = (time: number, type: TimelineSnapType) => {
@@ -38,7 +50,8 @@ export function collectTimelineSnapTargets(input: {
     add(el.start, "clip-edge");
     add(el.start + el.duration, "clip-edge");
   }
-  if (input.playheadTime != null) add(input.playheadTime, "playhead");
+  if (input.playheadTime != null && input.includePlayhead !== false)
+    add(input.playheadTime, "playhead");
 
   return Array.from(byTime.values()).sort((a, b) => a.time - b.time);
 }

package/src/player/components/timelineTrackDisplay.ts

@@ -3,7 +3,7 @@
  *
  * `TimelineElement.track` is a z-order SORT key, not a row number: an expanded
  * sub-composition child gets a synthesized fractional key (`host.track + n /
- * (siblings + 2)`, see `useExpandedTimelineElements`), so putting it in a string
+ * (siblings + 2)`, see `useTimelineRowElements`), so putting it in a string
  * announces "Hide track 0.16666666666666666". Every user-visible track number,
  * whether it is rendered by a component or baked into an undo-history label,
  * routes through here; the raw key stays in callbacks and lookups only.

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

@@ -2,7 +2,6 @@ import { describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
-import { buildExpandedElements } from "../hooks/useExpandedTimelineElements";
 import { normalizeToZones } from "./timelineZones";
 import { commitDraggedClipMove, type TimelineMoveEdit } from "./timelineClipDragCommit";
 import type { DraggedClipState } from "./useTimelineClipDrag";
@@ -113,56 +112,4 @@ describe("track persist pipeline (manifest → factory → lanes → drag commit
     const up = commitLaneChange(byId.get("g")!, 0, elements, [0, 1, 2]);
     expect(up[0].updates.track).toBe(3); // authored, NOT display lane 0
   });
-
-  it("an expanded sub-comp child's lane change persists the sibling's authored track from ITS file", () => {
-    // Host timeline: the sub-comp host plus a root clip, discovered through the
-    // factory and lane-normalized like the store does.
-    const hostManifest = [
-      manifestClip({
-        id: "scene",
-        kind: "composition",
-        tagName: "div",
-        track: 0,
-        start: 0,
-        duration: 10,
-        compositionId: "scene",
-        compositionSrc: "scene.html",
-      }),
-      manifestClip({ id: "root-clip", kind: "video", tagName: "video", track: 1, start: 0 }),
-    ];
-    // scene.html has SPARSE authored tracks 3 and 7.
-    const childClips = [
-      manifestClip({ id: "c3", track: 3, start: 1, duration: 2, parentCompositionId: "scene" }),
-      manifestClip({ id: "c7", track: 7, start: 4, duration: 2, parentCompositionId: "scene" }),
-    ];
-    const storeElements = normalizeToZones(fromManifest(hostManifest));
-    const parentMap = new Map([
-      ["c3", "scene"],
-      ["c7", "scene"],
-    ]);
-    const expanded = buildExpandedElements(
-      storeElements,
-      [...hostManifest, ...childClips],
-      parentMap,
-      "scene",
-      "scene",
-    );
-
-    // The children replaced the host row: synthetic display lanes, but the
-    // authored track (in scene.html's coordinate space) survived the expansion.
-    const c3 = expanded.find((e) => e.domId === "c3")!;
-    const c7 = expanded.find((e) => e.domId === "c7")!;
-    expect(c3).toMatchObject({ authoredTrack: 3, sourceFile: "scene.html" });
-    expect(c7).toMatchObject({ authoredTrack: 7, sourceFile: "scene.html" });
-    expect(c3.stackingContextId).toBe("root");
-    expect(c3.track).not.toBe(3); // display row is synthetic
-
-    // Drag c3 onto c7's display lane: the persist target is c3's OWN file, so
-    // the written track must be c7's authored 7 — not the display-lane integer.
-    const trackOrder = [...new Set(expanded.map((e) => e.track))].sort((a, b) => a - b);
-    const edits = commitLaneChange(c3, c7.track, expanded, trackOrder);
-    expect(edits).toHaveLength(1);
-    expect(edits[0].updates.track).toBe(7);
-    expect(edits[0].updates.track).not.toBe(c7.track);
-  });
 });

package/src/player/components/trackHeaderLabelRows.tsx

@@ -39,7 +39,7 @@ function PropertyGroupNavigation({
   // bigger box; focus-visible matches every other control in this header.
   const CHEVRON_BUTTON_CLASS =
     "relative h-5 w-3 border-0 bg-transparent p-0 text-white/55 hover:text-white disabled:text-white/15 " +
-    "focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] " +
+    "focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC] " +
     "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-['']";
   const seekTo = (keyframe: { percentage: number } | null) => {
@@ -154,7 +154,7 @@ export function PropertyGroupHeaderRow({
           aria-label={`${navigation.currentKeyframe ? "Remove" : "Add"} ${label} keyframe`}
           title={`${navigation.currentKeyframe ? "Remove" : "Add"} ${label} keyframe`}
           // h-6 w-6 = the 24x24 WCAG 2.2 minimum target; the ◆ glyph stays 11px.
-          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-[#3CE6AC] focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-[#3CE6AC] focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
           onClick={(event) => {
             // Same as the disclosure caret and the eye: a control in the label
             // column owns its click, it does not also hit the track row behind it.
@@ -262,7 +262,7 @@ export function AutomationLaneHeaderRow({
         aria-label={onReveal ? `Show ${label} in the effect rack` : undefined}
         title={onReveal ? `Show ${label} in the effect rack` : label}
         disabled={!onReveal}
-        className="flex min-w-0 flex-1 flex-col justify-center rounded border-0 bg-transparent p-0 text-left leading-tight enabled:hover:text-white focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+        className="flex min-w-0 flex-1 flex-col justify-center rounded-sm border-0 bg-transparent p-0 text-left leading-tight enabled:hover:text-white focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
         onPointerDown={(event) => event.stopPropagation()}
         onClick={(event) => {
           // The label column owns its click; it does not also fall through to
@@ -311,7 +311,7 @@ export function AutomationLaneHeaderRow({
           aria-label={`Remove ${label} automation`}
           title={`Remove ${label} automation`}
           // h-6 w-6 is the 24x24 WCAG 2.2 target; the glyph stays small.
-          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-white/35 hover:text-white focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
+          className="flex h-6 w-6 shrink-0 items-center justify-center border-0 bg-transparent p-0 text-[11px] text-white/35 hover:text-white focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
           onPointerDown={(event) => event.stopPropagation()}
           onClick={(event) => {
             // A control in the label column owns its click; it does not also hit

package/src/player/components/useTimelineClipContextMenu.ts

@@ -0,0 +1,32 @@
+import { useCallback } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { ClipContextMenuState } from "./TimelineOverlays";
+
+/** A clicked member of an active multi-selection keeps the whole group
+ *  selected, so the context menu it opens acts on all of it. */
+export function useClipContextMenu(
+  onSelectElement: ((element: TimelineElement | null) => void) | undefined,
+  dismissGapMenu: () => void,
+  setClipContextMenu: (state: ClipContextMenuState | null) => void,
+) {
+  const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
+  const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  return useCallback(
+    (e: React.MouseEvent, el: TimelineElement) => {
+      e.preventDefault();
+      const id = el.key ?? el.id;
+      if (!(selectedElementIds.size > 1 && selectedElementIds.has(id))) {
+        setSelectedElementId(id);
+        onSelectElement?.(el);
+      }
+      dismissGapMenu();
+      setClipContextMenu({
+        x: e.clientX,
+        y: e.clientY,
+        element: el,
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+      });
+    },
+    [selectedElementIds, setSelectedElementId, onSelectElement, dismissGapMenu, setClipContextMenu],
+  );
+}