@hyperframes/studio 0.7.75 → 0.7.77

package/src/player/components/TimelineTrackHeader.tsx

@@ -0,0 +1,363 @@
+import { Eye, EyeSlash } from "@phosphor-icons/react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { Music } from "../../icons/SystemIcons";
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
+import { LayerDisclosureRow } from "./LayerDisclosureRow";
+import { TrackClipCount } from "./TrackClipCount";
+import { LABEL_COL_W, LANE_H, getTimelineLaneTop } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+import {
+  resolveLaneHeaderState,
+  type KeyframeNavigationState,
+  type TimelinePropertyLane,
+} from "./trackHeaderLaneState";
+import { valueReadout } from "./trackHeaderLaneValues";
+
+interface TimelineTrackHeaderProps {
+  trackNumber: number;
+  trackLabel: string;
+  contentOrigin: number;
+  /** The track's active keyframe clip (selected, else primary) — the one whose
+   *  disclosure + property rows this header shows, whether expanded or not. */
+  keyframeClip: TimelineElement | null;
+  /** Clips on this track, so the header can say how many the row holds. */
+  clipCount: number;
+  isExpanded: boolean;
+  animations: readonly GsapAnimation[];
+  currentTime: number;
+  isTrackHidden: boolean;
+  isAudioTrack: boolean;
+  theme: TimelineTheme;
+  onToggleClipExpanded: () => void;
+  onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+  onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  onSeek?: (time: number) => void;
+}
+
+function VisibilityButton({
+  hidden,
+  trackNumber,
+  visible,
+  onToggle,
+}: {
+  hidden: boolean;
+  trackNumber: number;
+  visible: boolean;
+  onToggle: TimelineEditCallbacks["onToggleTrackHidden"];
+}) {
+  if (!visible) return <span aria-hidden="true" className="h-6 w-6 shrink-0" />;
+  const label = hidden ? `Show track ${trackNumber}` : `Hide track ${trackNumber}`;
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+        hidden ? "text-[#3CE6AC] hover:text-white" : "text-white/35 hover:text-white/75"
+      }`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onClick={(event) => {
+        event.stopPropagation();
+        void onToggle?.(trackNumber, !hidden);
+      }}
+    >
+      {hidden ? (
+        <EyeSlash size={14} weight="bold" aria-hidden="true" />
+      ) : (
+        <Eye size={14} weight="bold" aria-hidden="true" />
+      )}
+    </button>
+  );
+}
+
+// The header a track gets when it has no keyframe clip to disclose: label, clip
+// count, eye. Not deprecated — it is the live path for every track without lanes.
+function PlainTrackHeader({
+  trackNumber,
+  trackLabel,
+  clipCount,
+  showTrackLabel,
+  isTrackHidden,
+  isAudioTrack,
+  onToggleTrackHidden,
+}: Pick<
+  TimelineTrackHeaderProps,
+  | "trackNumber"
+  | "trackLabel"
+  | "clipCount"
+  | "isTrackHidden"
+  | "isAudioTrack"
+  | "onToggleTrackHidden"
+> & { showTrackLabel: boolean }) {
+  return (
+    <>
+      {isAudioTrack && (
+        <Music size={12} weight="fill" aria-hidden="true" className="text-white/35" />
+      )}
+      {showTrackLabel && (
+        <span className="min-w-0 flex-1 truncate text-[11px]" title={trackLabel}>
+          {trackLabel}
+        </span>
+      )}
+      {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
+      <VisibilityButton
+        hidden={isTrackHidden}
+        trackNumber={trackNumber}
+        visible
+        onToggle={onToggleTrackHidden}
+      />
+    </>
+  );
+}
+
+// Figma layout: prev-keyframe ‹, the add/remove toggle (children), next ›.
+function PropertyGroupNavigation({
+  navigation,
+  label,
+  expandedElement,
+  onSeek,
+  children,
+}: {
+  navigation: KeyframeNavigationState;
+  label: string;
+  expandedElement: TimelineElement;
+  onSeek?: (time: number) => void;
+  children: React.ReactNode;
+}) {
+  // The 12x20px glyph is all the lane row has room for, so the WCAG 24x24
+  // target is met with a centered transparent ::before overlay instead of a
+  // 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] " +
+    "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) => {
+    if (keyframe) {
+      onSeek?.(expandedElement.start + (keyframe.percentage / 100) * expandedElement.duration);
+    }
+  };
+  return (
+    <span className="flex shrink-0 items-center gap-0.5">
+      <button
+        type="button"
+        aria-label={`Previous ${label} keyframe`}
+        disabled={!navigation.prevKeyframe}
+        className={CHEVRON_BUTTON_CLASS}
+        onClick={(event) => {
+          event.stopPropagation();
+          seekTo(navigation.prevKeyframe);
+        }}
+      >
+        ‹
+      </button>
+      {children}
+      <button
+        type="button"
+        aria-label={`Next ${label} keyframe`}
+        disabled={!navigation.nextKeyframe}
+        className={CHEVRON_BUTTON_CLASS}
+        onClick={(event) => {
+          event.stopPropagation();
+          seekTo(navigation.nextKeyframe);
+        }}
+      >
+        ›
+      </button>
+    </span>
+  );
+}
+
+function PropertyGroupHeaderRow({
+  lane,
+  laneIndex,
+  isLastLane,
+  expandedElement,
+  currentTime,
+  clipPercentage,
+  gutterBackground,
+  columnWidth,
+  onTogglePropertyGroupKeyframe,
+  onSeek,
+}: {
+  lane: TimelinePropertyLane;
+  laneIndex: number;
+  isLastLane: boolean;
+  expandedElement: TimelineElement;
+  currentTime: number;
+  clipPercentage: number;
+  gutterBackground: string;
+  columnWidth: number;
+  onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  onSeek?: (time: number) => void;
+}) {
+  const { navigation, values, label, toggleTarget } = resolveLaneHeaderState(
+    lane,
+    currentTime,
+    clipPercentage,
+  );
+
+  return (
+    <div
+      data-property-group={lane.group}
+      data-timeline-lane-top={getTimelineLaneTop(laneIndex)}
+      className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-white/65"
+      style={{
+        top: getTimelineLaneTop(laneIndex),
+        // The header column narrows to contentOrigin whenever that is under
+        // LABEL_COL_W; a lane row pinned to LABEL_COL_W then hangs its value
+        // readout over the canvas, on top of the clips it is labelling.
+        width: columnWidth,
+        height: LANE_H,
+        background: gutterBackground,
+      }}
+    >
+      {/* Tree connector: vertical spine (top-half on the last lane) + branch tick. */}
+      <span className="relative h-full w-3 shrink-0" aria-hidden="true">
+        <span
+          className="absolute left-1.5 top-0 w-px bg-white/15"
+          style={{ height: isLastLane ? "50%" : "100%" }}
+        />
+        <span className="absolute left-1.5 top-1/2 h-px w-1.5 bg-white/15" />
+      </span>
+      <span className="w-[46px] shrink-0 truncate text-white" title={label}>
+        {label}
+      </span>
+      <PropertyGroupNavigation
+        navigation={navigation}
+        label={label}
+        expandedElement={expandedElement}
+        onSeek={onSeek}
+      >
+        <button
+          type="button"
+          aria-pressed={!!navigation.currentKeyframe}
+          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]"
+          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.
+            event.stopPropagation();
+            if (toggleTarget) {
+              void onTogglePropertyGroupKeyframe?.(expandedElement, toggleTarget);
+            }
+          }}
+        >
+          {navigation.currentKeyframe ? "◆" : "◇"}
+        </button>
+      </PropertyGroupNavigation>
+      <span
+        className="min-w-0 flex-1 truncate text-right tabular-nums text-white/45"
+        title={valueReadout(lane.group, values)}
+      >
+        {valueReadout(lane.group, values)}
+      </span>
+    </div>
+  );
+}
+
+export function TimelineTrackHeader({
+  trackNumber,
+  trackLabel,
+  contentOrigin,
+  keyframeClip,
+  clipCount,
+  isExpanded,
+  animations,
+  currentTime,
+  isTrackHidden,
+  isAudioTrack,
+  theme,
+  onToggleClipExpanded,
+  onToggleTrackHidden,
+  onTogglePropertyGroupKeyframe,
+  onSeek,
+}: TimelineTrackHeaderProps) {
+  const clipPercentage = keyframeClip
+    ? ((currentTime - keyframeClip.start) / keyframeClip.duration) * 100
+    : 0;
+  const lanes = keyframeClip
+    ? getTimelinePropertyLanes(animations, keyframeClip.start, keyframeClip.duration)
+    : [];
+  // Label mode = keyframe view; the label column stays LABEL_COL_W (Timeline.tsx
+  // owns the gutter past it, so a 0% diamond isn't clipped by this panel).
+  const showTrackLabel = contentOrigin >= LABEL_COL_W;
+  const isKeyframeLayer = !!keyframeClip && lanes.length > 0;
+  const lanesId = `timeline-lanes-track-${trackNumber}`;
+
+  return (
+    <div
+      className={`sticky left-0 z-[12] shrink-0 ${
+        !isKeyframeLayer
+          ? showTrackLabel
+            ? "flex items-center gap-1 px-1.5 text-white/55"
+            : "flex flex-col items-center justify-center gap-0.5"
+          : ""
+      }`}
+      style={{
+        width: showTrackLabel ? LABEL_COL_W : contentOrigin,
+        background: theme.gutterBackground,
+        borderRight: `1px solid ${theme.gutterBorder}`,
+      }}
+    >
+      {!keyframeClip || lanes.length === 0 ? (
+        <PlainTrackHeader
+          trackNumber={trackNumber}
+          trackLabel={trackLabel}
+          clipCount={clipCount}
+          showTrackLabel={showTrackLabel}
+          isTrackHidden={isTrackHidden}
+          isAudioTrack={isAudioTrack}
+          onToggleTrackHidden={onToggleTrackHidden}
+        />
+      ) : (
+        <>
+          <LayerDisclosureRow
+            keyframeClip={keyframeClip}
+            clipCount={clipCount}
+            isExpanded={isExpanded}
+            gutterBackground={theme.gutterBackground}
+            columnWidth={showTrackLabel ? LABEL_COL_W : contentOrigin}
+            lanesId={lanesId}
+            onToggleClipExpanded={onToggleClipExpanded}
+          >
+            {/* The eye belongs to the LAYER, so it lives on the always-mounted
+                layer row exactly like a plain track's. Hanging it off a lane row
+                (hover-gated, and only while expanded) left a keyframed track with
+                no way to be hidden at all by keyboard, and put the control on a
+                row it does not act on. */}
+            <VisibilityButton
+              hidden={isTrackHidden}
+              trackNumber={trackNumber}
+              visible
+              onToggle={onToggleTrackHidden}
+            />
+          </LayerDisclosureRow>
+          {/* Always mounted so the caret's aria-controls resolves in both states. */}
+          <div id={lanesId}>
+            {isExpanded &&
+              lanes.map((lane, laneIndex) => (
+                <PropertyGroupHeaderRow
+                  key={lane.group}
+                  lane={lane}
+                  laneIndex={laneIndex}
+                  isLastLane={laneIndex === lanes.length - 1}
+                  expandedElement={keyframeClip}
+                  currentTime={currentTime}
+                  clipPercentage={clipPercentage}
+                  gutterBackground={theme.gutterBackground}
+                  columnWidth={showTrackLabel ? LABEL_COL_W : contentOrigin}
+                  onTogglePropertyGroupKeyframe={onTogglePropertyGroupKeyframe}
+                  onSeek={onSeek}
+                />
+              ))}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

package/src/player/components/TrackClipCount.tsx

@@ -0,0 +1,17 @@
+/**
+ * How many clips the track holds, shown next to the track's identity so a
+ * multi-clip track reads as one at a glance. A single-clip track shows nothing:
+ * the clip bar already says "one", and the header stays low-density.
+ */
+export function TrackClipCount({ clipCount }: { clipCount: number }) {
+  if (clipCount < 2) return null;
+  return (
+    <span
+      aria-label={`${clipCount} clips`}
+      title={`${clipCount} clips`}
+      className="shrink-0 rounded-full bg-white/10 px-1 text-[9px] leading-[14px] tabular-nums text-white/55"
+    >
+      {clipCount}
+    </span>
+  );
+}

package/src/player/components/timelineCallbacks.ts

@@ -3,6 +3,16 @@
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineMoveOperation } from "../../hooks/timelineMoveAdapter";
 import type { BlockedTimelineEditIntent } from "./timelineEditing";
+import type { PropertyGroupName } from "@hyperframes/core/gsap-parser";
+import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
+
+export interface TimelinePropertyGroupKeyframeToggle {
+  animationId: string;
+  propertyGroup: PropertyGroupName;
+  tweenPercentage: number;
+  properties: Record<string, number | string>;
+  remove: boolean;
+}
 
 /**
  * Shared callback signatures for timeline editing operations.
@@ -62,14 +72,19 @@ export interface TimelineEditCallbacks {
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
-  onDeleteKeyframe?: (elementId: string, percentage: number) => void;
-  onDeleteAllKeyframes?: (elementId: string) => void;
-  onChangeKeyframeEase?: (elementId: string, percentage: number, ease: string) => void;
-  onMoveKeyframeToPlayhead?: (elementId: string, percentage: number) => void;
+  onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
+  onDeleteAllKeyframes?: (element: TimelineElement) => void;
+  onMoveKeyframeToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;
+  /** Drag-to-retime: `keyframe` identifies the dragged keyframe (its percentage
+   *  is clip-relative), `toClipPercentage` is the neighbour-clamped drop. */
   onMoveKeyframe?: (
     elementId: string,
-    fromClipPercentage: number,
+    keyframe: TimelineKeyframeTarget,
     toClipPercentage: number,
-  ) => void;
+  ) => Promise<boolean>;
   onToggleKeyframeAtPlayhead?: (element: TimelineElement) => void;
+  onTogglePropertyGroupKeyframe?: (
+    element: TimelineElement,
+    target: TimelinePropertyGroupKeyframeToggle,
+  ) => Promise<void> | void;
 }

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

@@ -6,7 +6,7 @@ import {
   type DragPreviewContext,
 } from "./timelineClipDragPreview";
 import type { DraggedClipState } from "./timelineClipDragTypes";
-import { RULER_H, TRACKS_TOP_PAD, TRACK_H } from "./timelineLayout";
+import { LANE_H, RULER_H, TRACKS_TOP_PAD, TRACK_H } from "./timelineLayout";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Regression bed for the live-reproduced BUG 1: a PLAIN HORIZONTAL drag of a clip
@@ -55,13 +55,17 @@ function fakeScroll(): HTMLDivElement {
   } as unknown as HTMLDivElement;
 }
 
-function ctx(): DragPreviewContext {
+function ctx(
+  rowHeights?: readonly number[],
+  elements: TimelineElement[] = fixtureElements,
+): DragPreviewContext {
   return {
     scroll: fakeScroll(),
     pps: PPS,
     duration: 44.5,
     trackOrder: [0, 1, 2],
-    elements: fixtureElements,
+    elements,
+    rowHeights,
     selectedKeys: new Set<string>(),
     buildSnapTargets: () => [],
     audioTracks: new Set<number>(),
@@ -145,6 +149,49 @@ describe("computeDragPreview — plain horizontal drag never arms a phantom inse
     const next = computeDragPreview(drag, originClientX, yForRow(-0.6), ctx());
     expect(next.insertRow).toBe(0); // a new TOP track will be created on drop
   });
+
+  it("keeps a horizontal drag in the body of an expanded row out of insert mode", () => {
+    const rowHeights = [TRACK_H + 2 * LANE_H, TRACK_H, TRACK_H];
+    const clientY = RULER_H + TRACKS_TOP_PAD + rowHeights[0] - 8;
+    const { drag, clientX } = horizontalDrag(moodboard, 0.5, 2);
+    const next = computeDragPreview(
+      { ...drag, originClientY: clientY, pointerClientY: clientY },
+      clientX,
+      clientY,
+      ctx(rowHeights),
+    );
+    expect(next.insertRow).toBeNull();
+    expect(next.previewTrack).toBe(0);
+  });
+
+  it("uses the expanded row midpoint when choosing the side for an automatic insert", () => {
+    const rowHeights = [TRACK_H + 2 * LANE_H, TRACK_H];
+    const dragged = clip("dragged", 0, 0, 1, 3);
+    const occupied = [dragged, clip("block-0", 0, 0, 1, 2), clip("block-1", 1, 0, 1, 1)];
+    const clientY = RULER_H + TRACKS_TOP_PAD + 30;
+    const drag: DraggedClipState = {
+      element: dragged,
+      originClientX: 0,
+      originClientY: clientY,
+      originScrollLeft: 0,
+      originScrollTop: 0,
+      pointerClientX: 0,
+      pointerClientY: clientY,
+      pointerOffsetX: 0,
+      pointerOffsetY: 0,
+      previewStart: 0,
+      previewTrack: 0,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: true,
+    };
+    const next = computeDragPreview(drag, 0, clientY, {
+      ...ctx(rowHeights, occupied),
+      trackOrder: [0, 1],
+    });
+    expect(next.insertRow).toBe(0);
+  });
 });
 
 describe("computeResizePreview — composition source continuity", () => {

package/src/player/components/timelineClipDragPreview.ts

@@ -1,6 +1,11 @@
 import { resolveTimelineMove, resolveTimelineResize } from "./timelineEditing";
 import type { TimelineElement } from "../store/playerStore";
-import { TRACK_H, getTimelineRowFromY, INSERT_BOUNDARY_BAND } from "./timelineLayout";
+import {
+  getTimelineInsertBoundaryBand,
+  getTimelineRowFromY,
+  getTimelineRowHeight,
+  getTimelineRowPositionFromY,
+} from "./timelineLayout";
 import { isMusicTrack, isAudioTimelineElement } from "../../utils/timelineInspector";
 import {
   TIMELINE_SNAP_PX,
@@ -27,6 +32,7 @@ export interface DragPreviewContext {
   pps: number;
   duration: number;
   trackOrder: number[];
+  rowHeights?: readonly number[];
   elements: TimelineElement[];
   selectedKeys: ReadonlySet<string>;
   buildSnapTargets: BuildSnapTargets;
@@ -81,20 +87,26 @@ function resolveDropPlacement(
   desiredTrack: number,
   ctx: DragPreviewContext,
 ): { track: number; insertRow: number | null } {
-  const { scroll, trackOrder, elements } = ctx;
+  const { scroll, trackOrder, rowHeights, elements } = ctx;
   // rowFloat = the pointer's position in track-heights from the top lane; a
   // near-boundary hover requests a deliberate new-track insert. Uses the
   // shared row→y inverse so the top breathing pad is subtracted consistently.
-  const rowFloat = scroll
-    ? getTimelineRowFromY(clientY - scroll.getBoundingClientRect().top + scroll.scrollTop)
-    : 0;
-  // Geometry-exact band (the clip inset) so an insert only arms in the visible
-  // gutter BETWEEN clip bodies — dragging over a clip body is a lane move, never a
-  // phantom insert (the plain-horizontal-drag misfire). See INSERT_BOUNDARY_BAND.
-  const rawInsertRow = resolveInsertRow(rowFloat, trackOrder.length, INSERT_BOUNDARY_BAND);
+  const rowPosition = scroll
+    ? getTimelineRowPositionFromY(
+        clientY - scroll.getBoundingClientRect().top + scroll.scrollTop,
+        rowHeights,
+      )
+    : { rowFloat: 0, row: 0, fraction: 0, rowHeight: getTimelineRowHeight(0, rowHeights) };
+  // Geometry-exact band (the clip inset divided by this row's actual height) so
+  // an insert only arms in the visible gutter between clip bodies.
+  const rawInsertRow = resolveInsertRow(
+    rowPosition.rowFloat,
+    trackOrder.length,
+    getTimelineInsertBoundaryBand(rowPosition.rowHeight),
+  );
   // Pointer sub-row half: when a drop must auto-create a track (aimed span
   // occupied, no free lane), open it on the side the pointer is nearer.
-  const preferInsertAbove = rowFloat - Math.floor(rowFloat) < 0.5;
+  const preferInsertAbove = rowPosition.fraction < 0.5;
   const audioTracks =
     ctx.audioTracks ?? new Set(elements.filter(isAudioTimelineElement).map((e) => e.track));
   return resolveZoneDropPlacement({
@@ -120,24 +132,30 @@ export function computeDragPreview(
 ): DraggedClipState {
   const { scroll, pps, duration, trackOrder, elements, selectedKeys, buildSnapTargets } = ctx;
   const dragMaxStart = resolveDragMaxStart(scroll, pps, duration);
+  const scrollTop = scroll?.scrollTop ?? drag.originScrollTop;
+  const scrollRectTop = scroll?.getBoundingClientRect().top ?? 0;
+  const originRow = getTimelineRowFromY(
+    drag.originClientY - scrollRectTop + drag.originScrollTop,
+    ctx.rowHeights,
+  );
+  const currentRow = getTimelineRowFromY(clientY - scrollRectTop + scrollTop, ctx.rowHeights);
+  // resolveTimelineMove's vertical axis is row indices, which is why the pointer
+  // and scroll pixels are folded into originRow/currentRow above.
   const nextMove = resolveTimelineMove(
     {
       start: drag.element.start,
       track: drag.element.track,
       duration: drag.element.duration,
       originClientX: drag.originClientX,
-      originClientY: drag.originClientY,
+      originRow,
       originScrollLeft: drag.originScrollLeft,
-      originScrollTop: drag.originScrollTop,
       currentScrollLeft: scroll?.scrollLeft ?? drag.originScrollLeft,
-      currentScrollTop: scroll?.scrollTop ?? drag.originScrollTop,
       pixelsPerSecond: pps,
-      trackHeight: TRACK_H,
       maxStart: dragMaxStart,
       trackOrder,
     },
     clientX,
-    clientY,
+    currentRow,
   );
   // The music track defines the beats, so it must not snap to them —
   // but it still snaps to the playhead and other clip edges.

package/src/player/components/timelineCollision.ts

@@ -1,4 +1,5 @@
 import type { TimelineElement } from "../store/playerStore";
+import { INSERT_BOUNDARY_BAND } from "./timelineLayout";
 
 /**
  * Keep a landing track inside the dragged clip's kind-zone: visual clips stay in
@@ -139,28 +140,18 @@ export function resolveZoneDropPlacement(input: {
   return { track: placement.track, insertRow: null };
 }
 
-/**
- * Fallback half-width (fraction of a track height) of the insert band straddling
- * a lane boundary — used only when the caller passes no explicit band. Production
- * threads the geometry-exact `INSERT_BOUNDARY_BAND` (timelineLayout.ts, = the clip
- * inset `CLIP_Y / TRACK_H`) so the band matches the rendered inter-clip gutter and
- * NEVER reaches into a clip body. Kept in sync with that constant; do not widen it
- * back toward the old 0.32 (which armed an insert across ~64% of every row — the
- * misfire that turned a plain horizontal drag into a phantom track insert).
- */
-const INSERT_BAND = 3 / 48;
-
 /**
  * Decide whether a vertical drag is inserting a new track at a lane boundary.
  * `rowFloat` is the pointer's position in track-height units from the top of the
  * first lane (0 = top of lane 0). Returns the boundary row to insert at
  * (0 = above the top lane, `trackCount` = below the bottom), or null when the
- * pointer is over a lane's middle band (a normal move/target).
+ * pointer is over a lane's middle band (a normal move/target). The default band
+ * preserves collapsed-row behavior; production passes the concrete row's band.
  */
 export function resolveInsertRow(
   rowFloat: number,
   trackCount: number,
-  band: number = INSERT_BAND,
+  band: number = INSERT_BOUNDARY_BAND,
 ): number | null {
   if (trackCount === 0) return 0;
   if (rowFloat <= 0) return 0;