@hyperframes/studio 0.7.75 → 0.7.77

package/src/player/components/timelineDiamondTypes.ts

@@ -0,0 +1,120 @@
+/**
+ * The diamond row's data + prop contract, split out of TimelineClipDiamonds so
+ * that file stays under the 600-line studio gate. Types and the shared
+ * keyframe-identity helper live here; the rendering lives there.
+ */
+import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
+
+export interface TimelineDiamondKeyframe {
+  percentage: number;
+  /** Tween-relative percentage (the retime mutation keys on this, not clip %). */
+  tweenPercentage?: number;
+  propertyGroup?: string;
+  animationId?: string;
+  properties: Record<string, number | string>;
+  ease?: string;
+  /** Set when 2+ source animations collide at this percentage (a single inline
+   *  ease button can't target one): the collapsed row hides the button here. */
+  easeAmbiguous?: boolean;
+}
+
+interface KeyframeCacheEntry {
+  format: string;
+  keyframes: TimelineDiamondKeyframe[];
+  ease?: string;
+  easeEach?: string;
+}
+
+export interface TimelineClipDiamondsProps {
+  keyframesData: KeyframeCacheEntry;
+  clipWidthPx: number;
+  clipHeightPx: number;
+  /** Beat-dot strip is shown on this track → shrink diamonds + drop them into
+   *  the bottom half so they clear the strip at the top. */
+  beatsActive?: boolean;
+  accentColor: string;
+  isSelected: boolean;
+  currentPercentage: number;
+  elementId: string;
+  selectedKeyframes: ReadonlySet<string>;
+  onClickKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
+  onShiftClickKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
+  onContextMenuKeyframe?: (
+    e: React.MouseEvent,
+    elementId: string,
+    keyframe: TimelineKeyframeTarget,
+  ) => void;
+  /** Drag-to-retime: move a keyframe to a new time, preserving its value + ease.
+   *  `keyframe` identifies the dragged keyframe (clip-relative percentage plus
+   *  whatever animation identity the row carries); `toClipPercentage` is the
+   *  neighbour-clamped drop position, also clip-relative. The handler decides
+   *  move (within the tween) vs resize (past its boundary). */
+  onMoveKeyframe?: (
+    elementId: string,
+    keyframe: TimelineKeyframeTarget,
+    toClipPercentage: number,
+  ) => Promise<boolean>;
+  /** Open the segment ease editor for the hovered mid-point button — available on
+   *  the inline clip row too, not just the expanded lanes. */
+  onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
+  /** Set while resolving a diamond press so the ancestor clip's onClick (which
+   *  toggles selection off when already selected) ignores the native "click"
+   *  the browser auto-synthesizes after this button's pointerdown+pointerup. */
+  suppressClickRef?: React.RefObject<boolean>;
+}
+
+export interface TimelineDiamondLaneProps extends Omit<
+  TimelineClipDiamondsProps,
+  | "onClickKeyframe"
+  | "onShiftClickKeyframe"
+  | "onContextMenuKeyframe"
+  | "onMoveKeyframe"
+  | "onSelectSegment"
+> {
+  groupAware?: boolean;
+  globalEase?: string;
+  onSelectSegment?: (target: TimelineKeyframeTarget) => void;
+  onClickKeyframe?: (target: TimelineKeyframeTarget) => void;
+  onShiftClickKeyframe?: (target: TimelineKeyframeTarget) => void;
+  onContextMenuKeyframe?: (e: React.MouseEvent, target: TimelineKeyframeTarget) => void;
+  onMoveKeyframe?: (target: TimelineKeyframeTarget, toClipPercentage: number) => Promise<boolean>;
+}
+
+export const DIAMOND_RATIO = 0.8;
+// Percentage tolerance for rendering keyframes near clip boundaries. Keyframes
+// slightly outside [0, 100] (from rounding or stale cache during the async
+// persist → reload cycle) are still rendered (the clip is overflow-visible) at
+// their true position rather than hidden.
+export const KF_MIN_PCT = -5;
+export const KF_MAX_PCT = 105;
+
+export type DragState = {
+  kfKey: string;
+  startX: number;
+  fromClipPct: number;
+  moved: boolean;
+  /** Latest pointer x, flushed to the preview once per frame. */
+  lastX: number;
+  /** Index in the sorted row, needed by the neighbour clamp off the render path. */
+  index: number;
+  /** Escape was pressed: the drag is dead, and the pointerup that follows is
+   *  swallowed rather than falling through to the click branch. */
+  cancelled?: boolean;
+};
+
+/**
+ * The full identity of a diamond, used by every callback and by the selection
+ * key. Collapsed clip rows and expanded property lanes read the same cache, so
+ * they must hash a shared keyframe to the same key: dropping the group here for
+ * the collapsed row would leave a diamond selected in one view and unselected in
+ * the other, and would strip the animation id the retime/delete mutations use to
+ * pick between two animations that collide at one percentage.
+ */
+export function keyframeTarget(keyframe: TimelineDiamondKeyframe): TimelineKeyframeTarget {
+  return {
+    percentage: keyframe.percentage,
+    tweenPercentage: keyframe.tweenPercentage,
+    propertyGroup: keyframe.propertyGroup,
+    animationId: keyframe.animationId,
+  };
+}

package/src/player/components/timelineDragDrop.ts

@@ -5,7 +5,7 @@ import {
   TIMELINE_COMPOSITION_MIME,
 } from "../../utils/timelineCompositionDrop";
 import { usePlayerStore } from "../store/playerStore";
-import { TRACK_H, resolveTimelineAssetDrop } from "./timelineLayout";
+import { resolveTimelineAssetDrop } from "./timelineLayout";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 
 interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
@@ -13,6 +13,8 @@ interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   ppsRef: RefObject<number>;
   durationRef: RefObject<number>;
   trackOrderRef: RefObject<number[]>;
+  rowHeightsRef: RefObject<readonly number[]>;
+  contentOrigin: number;
 }
 
 type TimelinePlacement = { start: number; track: number };
@@ -54,6 +56,8 @@ export function useTimelineAssetDrop({
   ppsRef,
   durationRef,
   trackOrderRef,
+  rowHeightsRef,
+  contentOrigin,
   onFileDrop,
   onAssetDrop,
   onBlockDrop,
@@ -85,10 +89,11 @@ export function useTimelineAssetDrop({
           rectTop: rect?.top ?? 0,
           scrollLeft: scroll?.scrollLeft ?? 0,
           scrollTop: scroll?.scrollTop ?? 0,
+          contentOrigin,
           pixelsPerSecond: ppsRef.current,
           duration: durationRef.current,
           clampStartToDuration: !usePointerStart,
-          trackHeight: TRACK_H,
+          rowHeights: rowHeightsRef.current,
           trackOrder: trackOrderRef.current,
         },
         clientX,
@@ -99,7 +104,7 @@ export function useTimelineAssetDrop({
         track: pointer.track,
       };
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef],
+    [scrollRef, ppsRef, durationRef, trackOrderRef, rowHeightsRef, contentOrigin],
   );
 
   const handleAssetDrop = useCallback(

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

@@ -27,14 +27,13 @@ describe("resolveTimelineMove", () => {
           track: 2,
           duration: 2,
           originClientX: 100,
-          originClientY: 200,
+          originRow: 0,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 8,
           trackOrder: [0, 1, 2, 3, 4],
         },
         245,
-        200,
+        0,
       ),
     ).toEqual({ start: 2.7, track: 2 });
   });
@@ -47,14 +46,13 @@ describe("resolveTimelineMove", () => {
           track: 1,
           duration: 3,
           originClientX: 200,
-          originClientY: 200,
+          originRow: 0,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 10,
           trackOrder: [0, 1, 5, 9],
         },
         150,
-        390,
+        190 / 72,
       ),
     ).toEqual({ start: 1.5, track: 9 });
   });
@@ -67,14 +65,13 @@ describe("resolveTimelineMove", () => {
           track: 0,
           duration: 4,
           originClientX: 300,
-          originClientY: 200,
+          originRow: 0,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 6,
           trackOrder: [0, 10, 20],
         },
         -100,
-        -200,
+        -400 / 72,
       ),
     ).toEqual({ start: 0, track: -1 });
 
@@ -85,14 +82,13 @@ describe("resolveTimelineMove", () => {
           track: 10,
           duration: 4,
           originClientX: 300,
-          originClientY: 200,
+          originRow: 0,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 6,
           trackOrder: [0, 10, 20],
         },
         500,
-        200,
+        0,
       ),
     ).toEqual({ start: 6, track: 10 });
   });
@@ -105,14 +101,13 @@ describe("resolveTimelineMove", () => {
           track: 0,
           duration: 2,
           originClientX: 100,
-          originClientY: 200,
+          originRow: 0,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 8,
           trackOrder: [0, 10, 20],
         },
         100,
-        150,
+        -50 / 72,
       ),
     ).toEqual({ start: 1, track: -1 });
   });
@@ -125,19 +120,18 @@ describe("resolveTimelineMove", () => {
           track: 20,
           duration: 2,
           originClientX: 100,
-          originClientY: 200,
+          originRow: 0,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 8,
           trackOrder: [0, 10, 20],
         },
         100,
-        250,
+        50 / 72,
       ),
     ).toEqual({ start: 1, track: 21 });
   });
 
-  it("accounts for scroll displacement while dragging", () => {
+  it("accounts for horizontal scroll displacement while dragging", () => {
     expect(
       resolveTimelineMove(
         {
@@ -145,18 +139,17 @@ describe("resolveTimelineMove", () => {
           track: 0,
           duration: 2,
           originClientX: 100,
-          originClientY: 200,
+          originRow: 0,
           originScrollLeft: 0,
-          originScrollTop: 0,
           currentScrollLeft: 100,
-          currentScrollTop: 144,
           pixelsPerSecond: 100,
-          trackHeight: 72,
           maxStart: 8,
+          // Vertical scroll never reaches here: the drag preview folds it into the
+          // row index it passes, because rows no longer share one pixel height.
           trackOrder: [0, 1, 2, 3],
         },
         100,
-        200,
+        2,
       ),
     ).toEqual({ start: 2, track: 2 });
   });
@@ -195,9 +188,8 @@ describe("resolveTimelineMove", () => {
         track: 1,
         duration: 2,
         originClientX: 0,
-        originClientY: 0,
+        originRow: 0,
         pixelsPerSecond: 100,
-        trackHeight: 72,
         maxStart: 8,
         trackOrder: [0, 1],
         layerOrder: layers.map((layer) => layer.id),
@@ -206,7 +198,7 @@ describe("resolveTimelineMove", () => {
         stackingElements,
       },
       0,
-      -72,
+      -1,
     );
 
     expect(result).toEqual({

package/src/player/components/timelineEditing.ts

@@ -46,13 +46,11 @@ export interface TimelineMoveInput {
   track: number;
   duration: number;
   originClientX: number;
-  originClientY: number;
+  /** Vertical position as a track-row index, not pixels: rows vary in height. */
+  originRow: number;
   originScrollLeft?: number;
-  originScrollTop?: number;
   currentScrollLeft?: number;
-  currentScrollTop?: number;
   pixelsPerSecond: number;
-  trackHeight: number;
   maxStart: number;
   trackOrder: number[];
   layerOrder?: TimelineLayerId[];
@@ -108,7 +106,7 @@ export function resolveTimelineAutoScroll(
 export function resolveTimelineMove(
   input: TimelineMoveInput,
   clientX: number,
-  clientY: number,
+  currentRow: number,
 ): {
   start: number;
   track: number;
@@ -117,11 +115,12 @@ export function resolveTimelineMove(
   stackingReorder?: TimelineStackingReorderIntent | null;
 } {
   const scrollDeltaX = (input.currentScrollLeft ?? 0) - (input.originScrollLeft ?? 0);
-  const scrollDeltaY = (input.currentScrollTop ?? 0) - (input.originScrollTop ?? 0);
   const deltaTime =
     (clientX - input.originClientX + scrollDeltaX) / Math.max(input.pixelsPerSecond, 1);
-  const trackDeltaRaw =
-    (clientY - input.originClientY + scrollDeltaY) / Math.max(input.trackHeight, 1);
+  // Rows, so vertical scroll and per-row heights are the caller's problem: rows
+  // have varied in height since lanes expand, and a single trackHeight can't
+  // describe them.
+  const trackDeltaRaw = currentRow - input.originRow;
   const deltaTrack = Math.round(trackDeltaRaw);
   const nextStart = clamp(
     roundToCentiseconds(input.start + deltaTime),

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import {
+  timelineKeyframeSelectionKey,
+  timelineKeyframeTargetFromSelectionKey,
+} from "./timelineKeyframeIdentity";
+
+describe("timeline keyframe selection identity", () => {
+  it("round-trips an expanded lane with colon-bearing identities", () => {
+    const key = timelineKeyframeSelectionKey("comp#a:child", {
+      percentage: 75,
+      tweenPercentage: 40,
+      propertyGroup: "position",
+      animationId: "child:position",
+    });
+
+    expect(timelineKeyframeTargetFromSelectionKey("comp#a:child", key)).toEqual({
+      percentage: 75,
+      tweenPercentage: 40,
+      propertyGroup: "position",
+      animationId: "child:position",
+    });
+  });
+
+  it("does not confuse an expanded lane whose element id extends the active id", () => {
+    const key = timelineKeyframeSelectionKey("comp#a:child", {
+      percentage: 75,
+      tweenPercentage: 40,
+      propertyGroup: "position",
+      animationId: "child-position",
+    });
+
+    expect(timelineKeyframeTargetFromSelectionKey("comp#a", key)).toBeNull();
+  });
+
+  // Timeline.tsx still writes the collapsed form for clip-lane shift-clicks, and
+  // an element id can itself contain a colon — the split has to be the LAST one.
+  it("splits the collapsed key at the last colon so a colon-bearing id survives", () => {
+    expect(timelineKeyframeTargetFromSelectionKey("a:b", "a:b:40")).toEqual({ percentage: 40 });
+    expect(timelineKeyframeTargetFromSelectionKey("a", "a:b:40")).toBeNull();
+  });
+
+  it("retains the collapsed key fallback and rejects malformed percentages", () => {
+    expect(timelineKeyframeTargetFromSelectionKey("comp#a", "comp#a:30")).toEqual({
+      percentage: 30,
+    });
+    expect(timelineKeyframeTargetFromSelectionKey("comp#a", "comp#a:NaN")).toBeNull();
+    expect(timelineKeyframeTargetFromSelectionKey("comp#a", "comp#b:30")).toBeNull();
+  });
+});

package/src/player/components/timelineKeyframeIdentity.ts

@@ -0,0 +1,66 @@
+export interface TimelineKeyframeTarget {
+  percentage: number;
+  tweenPercentage?: number;
+  propertyGroup?: string;
+  animationId?: string;
+}
+
+/**
+ * Note the asymmetry: `tweenPercentage` is optional here and defaults to
+ * `percentage`, but the reader treats both slots as authoritative. Callers must
+ * therefore keep the pair consistent — writing a new `tweenPercentage` without
+ * the matching `percentage` hashes two logically-equal selections to different
+ * keys.
+ */
+export function timelineKeyframeSelectionKey(
+  elementId: string,
+  target: TimelineKeyframeTarget,
+): string {
+  if (!target.propertyGroup) return `${elementId}:${target.percentage}`;
+  return JSON.stringify([
+    elementId,
+    target.propertyGroup,
+    target.animationId ?? "",
+    target.percentage,
+    target.tweenPercentage ?? target.percentage,
+  ]);
+}
+
+export function timelineKeyframeTargetFromSelectionKey(
+  elementId: string,
+  key: string,
+): TimelineKeyframeTarget | null {
+  if (key.startsWith("[")) {
+    let decoded: unknown;
+    try {
+      decoded = JSON.parse(key);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(decoded) || decoded.length !== 5) return null;
+    const [selectedElementId, propertyGroup, animationId, percentage, tweenPercentage] = decoded;
+    if (
+      selectedElementId !== elementId ||
+      typeof propertyGroup !== "string" ||
+      propertyGroup.length === 0 ||
+      typeof animationId !== "string" ||
+      typeof percentage !== "number" ||
+      !Number.isFinite(percentage) ||
+      typeof tweenPercentage !== "number" ||
+      !Number.isFinite(tweenPercentage)
+    ) {
+      return null;
+    }
+    return {
+      propertyGroup,
+      animationId: animationId || undefined,
+      percentage,
+      tweenPercentage,
+    };
+  }
+
+  const separator = key.lastIndexOf(":");
+  if (separator < 0 || key.slice(0, separator) !== elementId) return null;
+  const percentage = Number(key.slice(separator + 1));
+  return Number.isFinite(percentage) ? { percentage } : null;
+}

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

@@ -1,17 +1,99 @@
 import { describe, it, expect } from "vitest";
 import {
+  CLIP_Y,
+  INSERT_BOUNDARY_BAND,
+  getTimelineInsertBoundaryBand,
   RULER_H,
   TRACK_H,
+  LANE_H,
   TRACKS_TOP_PAD,
   TRACKS_BOTTOM_PAD,
   GUTTER,
   TRACKS_LEFT_PAD,
   getTimelineRowTop,
+  getTimelineScrubTime,
   getTimelineRowFromY,
+  getTimelineRowOffsets,
   getTimelineCanvasHeight,
+  trackHeights,
   resolveTimelineAssetDrop,
 } from "./timelineLayout";
 
+/** N collapsed rows, the shape every caller passes when nothing is expanded. */
+const baseRows = (count: number) => Array.from({ length: count }, () => TRACK_H);
+
+describe("variable timeline row geometry", () => {
+  const tracks = [
+    [{ clipId: "a", laneCount: 0 }],
+    [{ clipId: "b", laneCount: 2 }],
+    [{ clipId: "c", laneCount: 1 }],
+  ];
+
+  it("resolves every row to the base height when no clip is expanded", () => {
+    expect(trackHeights(tracks)).toEqual([TRACK_H, TRACK_H, TRACK_H]);
+    expect(trackHeights([[], [], []])).toEqual([TRACK_H, TRACK_H, TRACK_H]);
+  });
+
+  it("adds one lane height per lane on an expanded clip", () => {
+    expect(trackHeights(tracks, new Set(["b"]))).toEqual([TRACK_H, TRACK_H + 2 * LANE_H, TRACK_H]);
+  });
+
+  it("derives row tops from cumulative offsets", () => {
+    const heights = trackHeights(tracks, new Set(["b"]));
+    expect(getTimelineRowOffsets(heights)).toEqual([
+      0,
+      TRACK_H,
+      2 * TRACK_H + 2 * LANE_H,
+      3 * TRACK_H + 2 * LANE_H,
+    ]);
+    expect(getTimelineRowTop(2, heights)).toBe(RULER_H + TRACKS_TOP_PAD + 2 * TRACK_H + 2 * LANE_H);
+  });
+
+  it("maps y inside an expanded lane region back to the expanded track", () => {
+    const heights = trackHeights(tracks, new Set(["b"]));
+    const yInSecondExpandedLane = getTimelineRowTop(1, heights) + TRACK_H + LANE_H * 1.5;
+    const row = getTimelineRowFromY(yInSecondExpandedLane, heights);
+    expect(Math.floor(row)).toBe(1);
+    expect(row).toBeGreaterThan(1.5);
+    expect(row).toBeLessThan(2);
+  });
+
+  it("sums resolved row heights into the canvas height", () => {
+    const heights = trackHeights(tracks, new Set(["b"]));
+    expect(getTimelineCanvasHeight(heights)).toBe(
+      RULER_H + TRACKS_TOP_PAD + 3 * TRACK_H + 2 * LANE_H + TRACKS_BOTTOM_PAD,
+    );
+  });
+});
+
+describe("collapsed timeline row geometry characterization", () => {
+  it.each([
+    [0, 74],
+    [1, 122],
+    [4, 266],
+  ])("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],
+  ])("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],
+  ])("keeps the %i-track canvas height at %i", (trackCount, expectedHeight) => {
+    expect(getTimelineCanvasHeight(baseRows(trackCount))).toBe(expectedHeight);
+  });
+});
+
 describe("track-area breathing pad y-math", () => {
   describe("getTimelineRowTop", () => {
     it("offsets the first lane below the ruler by the top pad", () => {
@@ -53,20 +135,16 @@ describe("track-area breathing pad y-math", () => {
 
   describe("getTimelineCanvasHeight", () => {
     it("reserves ruler + top pad + lanes + bottom pad", () => {
-      expect(getTimelineCanvasHeight(0)).toBe(RULER_H + TRACKS_TOP_PAD + TRACKS_BOTTOM_PAD);
-      expect(getTimelineCanvasHeight(3)).toBe(
+      expect(getTimelineCanvasHeight([])).toBe(RULER_H + TRACKS_TOP_PAD + TRACKS_BOTTOM_PAD);
+      expect(getTimelineCanvasHeight(baseRows(3))).toBe(
         RULER_H + TRACKS_TOP_PAD + 3 * TRACK_H + TRACKS_BOTTOM_PAD,
       );
     });
 
-    it("clamps a negative track count to zero lanes", () => {
-      expect(getTimelineCanvasHeight(-4)).toBe(RULER_H + TRACKS_TOP_PAD + TRACKS_BOTTOM_PAD);
-    });
-
     it("leaves room below the last lane for a drag-into-void new track", () => {
       // The gap below the final lane must be at least a full track height so a
       // clip can be dropped there to create a new bottom track.
-      const oneLane = getTimelineCanvasHeight(1);
+      const oneLane = getTimelineCanvasHeight(baseRows(1));
       const lastLaneBottom = getTimelineRowTop(0) + TRACK_H;
       expect(oneLane - lastLaneBottom).toBeGreaterThanOrEqual(TRACK_H);
     });
@@ -78,15 +156,16 @@ describe("track-area breathing pad y-math", () => {
       rectTop: 0,
       scrollLeft: 0,
       scrollTop: 0,
+      contentOrigin: GUTTER,
       pixelsPerSecond: 100,
       duration: 60,
-      trackHeight: TRACK_H,
+      rowHeights: baseRows(3),
       trackOrder: [0, 1, 2],
     };
 
     it("drops onto lane 0 when the pointer is in the middle of the first lane", () => {
       const clientY = getTimelineRowTop(0) + TRACK_H / 2;
-      const clientX = GUTTER + TRACKS_LEFT_PAD + 100; // t = 1s
+      const clientX = GUTTER + 100; // t = 1s (contentOrigin = GUTTER)
       const { start, track } = resolveTimelineAssetDrop(base, clientX, clientY);
       expect(track).toBe(0);
       expect(start).toBe(1);
@@ -103,5 +182,79 @@ describe("track-area breathing pad y-math", () => {
       const { track } = resolveTimelineAssetDrop(base, GUTTER, clientY);
       expect(track).toBe(3); // max(trackOrder)+1
     });
+
+    it("keeps a drop in an expanded lane region on that track", () => {
+      const rowHeights = [TRACK_H + 2 * LANE_H, TRACK_H, TRACK_H];
+      const clientY = getTimelineRowTop(0, rowHeights) + TRACK_H + LANE_H;
+      const { track } = resolveTimelineAssetDrop({ ...base, rowHeights }, GUTTER, clientY);
+      expect(track).toBe(0);
+    });
+  });
+});
+
+describe("getTimelineScrubTime", () => {
+  const at = (clientX: number, duration = 10) =>
+    getTimelineScrubTime({
+      clientX,
+      viewportLeft: 0,
+      scrollLeft: 0,
+      contentOrigin: GUTTER + TRACKS_LEFT_PAD,
+      pixelsPerSecond: 100,
+      duration,
+    });
+  const origin = GUTTER + TRACKS_LEFT_PAD;
+
+  it("maps the content origin to t=0", () => {
+    expect(at(origin)).toBe(0);
+    expect(at(origin + 250)).toBe(2.5);
+  });
+
+  // The bug: a pointer left of the origin used to abort the scrub instead of
+  // clamping, so dragging the playhead to the start only worked if a sample
+  // happened to land in the few px before t=0.
+  it("clamps a pointer left of the origin to 0 instead of dropping the scrub", () => {
+    expect(at(origin - 1)).toBe(0);
+    expect(at(origin - 500)).toBe(0);
+    expect(at(0)).toBe(0);
+  });
+
+  it("clamps past the end to the duration", () => {
+    expect(at(origin + 5000)).toBe(10);
+  });
+
+  it("returns 0 for a degenerate zoom or duration", () => {
+    expect(
+      getTimelineScrubTime({
+        clientX: 500,
+        viewportLeft: 0,
+        scrollLeft: 0,
+        contentOrigin: GUTTER + TRACKS_LEFT_PAD,
+        pixelsPerSecond: 0,
+        duration: 10,
+      }),
+    ).toBe(0);
+    expect(at(origin + 250, Number.NaN)).toBe(0);
+  });
+});
+
+// The only production hook keeping resolveInsertRow's band aligned with the
+// rendered clip inset once rows can be taller than TRACK_H. Pinned directly so a
+// change to CLIP_Y or the invalid-height fallback can't silently drift it.
+describe("getTimelineInsertBoundaryBand", () => {
+  it("matches the fixed band for a plain track row", () => {
+    expect(getTimelineInsertBoundaryBand(TRACK_H)).toBe(INSERT_BOUNDARY_BAND);
+    expect(getTimelineInsertBoundaryBand(TRACK_H)).toBe(CLIP_Y / TRACK_H);
+  });
+
+  it("shrinks as the row grows, so the band stays CLIP_Y pixels tall", () => {
+    const expanded = TRACK_H + 2 * LANE_H;
+    expect(getTimelineInsertBoundaryBand(expanded)).toBeCloseTo(CLIP_Y / expanded, 10);
+    expect(getTimelineInsertBoundaryBand(expanded)).toBeLessThan(INSERT_BOUNDARY_BAND);
+  });
+
+  it("falls back to the plain-track band for a height that is not usable", () => {
+    for (const height of [0, -10, Number.NaN]) {
+      expect(getTimelineInsertBoundaryBand(height)).toBe(INSERT_BOUNDARY_BAND);
+    }
   });
 });