@hyperframes/studio 0.6.97 → 0.6.98

package/src/player/components/BeatStrip.tsx

@@ -0,0 +1,166 @@
+import { memo, useRef, useState } from "react";
+import { moveBeatCompositionTime, deleteBeatAtCompositionTime } from "../../utils/beatEditActions";
+import { usePlayerStore } from "../store/playerStore";
+import { CLIP_Y } from "./timelineLayout";
+
+export const BEAT_BAND_H = 14; // dark band height at top of track
+const BEAT_HIT_W = 12; // grab width per beat (px)
+
+/** Hide both layers when beats are packed tighter than this (px) — too dense to read. */
+function beatsTooDense(beatTimes: number[], pps: number): boolean {
+  if (beatTimes.length < 2) return true;
+  const avgInterval = (beatTimes[beatTimes.length - 1]! - beatTimes[0]!) / (beatTimes.length - 1);
+  return avgInterval * pps < 5;
+}
+
+/**
+ * Faint full-height beat lines painted into a track lane's background. Rendered
+ * behind the clips so they only show through the empty track area (the dots in
+ * BeatStrip mark beats on the clips themselves). Brightness scales with beat
+ * loudness. Drawn on every track lane for a global beat grid.
+ */
+export const BeatBackgroundLines = memo(function BeatBackgroundLines({
+  beatTimes,
+  beatStrengths,
+  pps,
+  highlightTime,
+}: {
+  beatTimes: number[] | undefined;
+  beatStrengths: number[] | undefined;
+  pps: number;
+  /** Beat time a dragged clip will snap to — drawn as a bright neon line. */
+  highlightTime?: number | null;
+}) {
+  if (!beatTimes || beatsTooDense(beatTimes, pps)) return null;
+  return (
+    <div className="absolute inset-0 pointer-events-none" style={{ zIndex: 0 }}>
+      {beatTimes.map((t, i) => {
+        const isHighlight = highlightTime != null && Math.abs(t - highlightTime) < 1e-3;
+        const strength = Math.pow(Math.min(1, beatStrengths?.[i] ?? 0.5), 2.2);
+        const opacity = isHighlight ? 1 : 0.06 + strength * 0.16;
+        return (
+          <div
+            key={`${t}-${i}`}
+            className="absolute top-0 bottom-0"
+            style={{
+              left: t * pps,
+              width: isHighlight ? 2 : 1,
+              background: `rgba(34,197,94,${opacity.toFixed(3)})`,
+              boxShadow: isHighlight ? "0 0 6px rgba(34,197,94,0.9)" : undefined,
+              zIndex: isHighlight ? 1 : undefined,
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+});
+
+/**
+ * Green beat dots on the music track's row. Drag a dot to move its beat,
+ * double-click to delete; both scrub the audio. Dot size/brightness scale with
+ * beat loudness (gamma-curved for contrast).
+ */
+export const BeatStrip = memo(function BeatStrip({
+  beatTimes,
+  beatStrengths,
+  pps,
+}: {
+  beatTimes: number[] | undefined;
+  beatStrengths: number[] | undefined;
+  pps: number;
+}) {
+  // Active drag: which beat and how far (px) it's been dragged.
+  const [drag, setDrag] = useState<{ index: number; dx: number } | null>(null);
+  const dragRef = useRef<{ index: number; startX: number; origTime: number } | null>(null);
+
+  if (!beatTimes || beatsTooDense(beatTimes, pps)) return null;
+  const cy = BEAT_BAND_H / 2;
+
+  return (
+    <div
+      className="absolute left-0 right-0 pointer-events-none"
+      style={{ top: CLIP_Y, height: BEAT_BAND_H, background: "rgba(0,0,0,0.28)", zIndex: 11 }}
+    >
+      {beatTimes.map((t, i) => {
+        // Louder beats → larger, brighter dot. Gamma curve widens the contrast.
+        const strength = Math.pow(Math.min(1, beatStrengths?.[i] ?? 0.5), 2.2);
+        const r = 1.5 + strength * 2.5;
+        const opacity = 0.25 + strength * 0.75;
+        const dxPx = drag?.index === i ? drag.dx : 0;
+        const x = t * pps + dxPx;
+        return (
+          <div
+            key={`${t}-${i}`}
+            className="absolute select-none"
+            title="Drag to move · double-click to delete"
+            draggable={false}
+            style={{
+              left: x - BEAT_HIT_W / 2,
+              top: 0,
+              width: BEAT_HIT_W,
+              height: BEAT_BAND_H,
+              cursor: "ew-resize",
+              pointerEvents: "auto",
+              touchAction: "none",
+            }}
+            onPointerDown={(e) => {
+              // preventDefault stops the browser starting a native text/drag
+              // selection (which otherwise "selects" the whole panel mid-drag).
+              e.preventDefault();
+              e.stopPropagation();
+              e.currentTarget.setPointerCapture(e.pointerId);
+              dragRef.current = { index: i, startX: e.clientX, origTime: t };
+              setDrag({ index: i, dx: 0 });
+              usePlayerStore.getState().setBeatDragging(true); // hide the playhead guideline
+              usePlayerStore.getState().requestSeek(Math.max(0, t)); // scrub audio at beat
+            }}
+            onPointerMove={(e) => {
+              const d = dragRef.current;
+              if (!d || d.index !== i) return;
+              e.preventDefault();
+              const dx = e.clientX - d.startX;
+              setDrag({ index: i, dx });
+              // Scrub the audio (and move the playhead) to follow the dragged beat.
+              usePlayerStore.getState().requestSeek(Math.max(0, d.origTime + dx / pps));
+            }}
+            onPointerUp={(e) => {
+              const d = dragRef.current;
+              dragRef.current = null;
+              setDrag(null);
+              usePlayerStore.getState().setBeatDragging(false);
+              if (e.currentTarget.hasPointerCapture?.(e.pointerId)) {
+                e.currentTarget.releasePointerCapture(e.pointerId);
+              }
+              if (!d || d.index !== i) return;
+              const dx = e.clientX - d.startX;
+              if (Math.abs(dx) > 2) {
+                const newTime = Math.max(0, d.origTime + dx / pps);
+                moveBeatCompositionTime(d.origTime, newTime);
+                usePlayerStore.getState().requestSeek(newTime); // park scrubber at new beat
+              }
+            }}
+            onDoubleClick={(e) => {
+              e.stopPropagation();
+              deleteBeatAtCompositionTime(t);
+              usePlayerStore.getState().requestSeek(Math.max(0, t)); // park scrubber at deleted beat
+            }}
+          >
+            <div
+              className="absolute"
+              style={{
+                left: BEAT_HIT_W / 2 - r,
+                top: cy - r,
+                width: r * 2,
+                height: r * 2,
+                borderRadius: "50%",
+                background: `rgba(34,197,94,${opacity.toFixed(3)})`,
+                pointerEvents: "none",
+              }}
+            />
+          </div>
+        );
+      })}
+    </div>
+  );
+});

package/src/player/components/Timeline.tsx

@@ -1,4 +1,7 @@
 import { useRef, useMemo, useCallback, useState, useEffect, memo, type ReactNode } from "react";
+import { useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
+import { isMusicTrack } from "../../utils/timelineInspector";
+import { remapBeatAnalysisToComposition } from "../../utils/beatEditActions";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { EditPopover } from "./EditModal";
@@ -16,6 +19,7 @@ import {
   type KeyframeDiamondContextMenuState,
 } from "./KeyframeDiamondContextMenu";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
+import { snapKeyframePctToBeat } from "./timelineEditing";
 import { ClipContextMenu } from "./ClipContextMenu";
 import {
   GUTTER,
@@ -23,7 +27,8 @@ import {
   getTimelineCanvasHeight,
   shouldShowTimelineShortcutHint,
 } from "./timelineLayout";
-import type { TimelineEditCallbacks, TimelineDropCallbacks } from "./timelineCallbacks";
+import type { TimelineDropCallbacks } from "./timelineCallbacks";
+import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
 
 // Re-export pure utilities so existing imports from "./Timeline" still resolve.
 export {
@@ -40,7 +45,7 @@ export {
   getDefaultDroppedTrack,
 } from "./timelineLayout";
 
-interface TimelineProps extends TimelineEditCallbacks, TimelineDropCallbacks {
+interface TimelineProps extends TimelineDropCallbacks {
   onSeek?: (time: number) => void;
   onDrillDown?: (element: TimelineElement) => void;
   renderClipContent?: (
@@ -62,22 +67,32 @@ export const Timeline = memo(function Timeline({
   onAssetDrop,
   onBlockDrop,
   onDeleteElement: _onDeleteElement,
-  onMoveElement,
-  onResizeElement,
-  onBlockedEditAttempt,
-  onSplitElement,
-  onRazorSplit,
-  onRazorSplitAll,
   onSelectElement,
-  onDeleteKeyframe,
-  onDeleteAllKeyframes,
-  onChangeKeyframeEase,
-  onMoveKeyframe,
-  onToggleKeyframeAtPlayhead,
   theme: themeOverrides,
 }: TimelineProps = {}) {
+  const {
+    onMoveElement,
+    onResizeElement,
+    onBlockedEditAttempt,
+    onSplitElement,
+    onRazorSplitAll,
+    onDeleteKeyframe,
+    onDeleteAllKeyframes,
+    onChangeKeyframeEase,
+    onMoveKeyframe,
+  } = useTimelineEditContext();
   const theme = useMemo(() => ({ ...defaultTimelineTheme, ...themeOverrides }), [themeOverrides]);
+  useMusicBeatAnalysis();
   const elements = usePlayerStore((s) => s.elements);
+  const beatAnalysis = usePlayerStore((s) => s.beatAnalysis);
+  const musicElement = usePlayerStore((s) => s.elements.find(isMusicTrack) ?? null);
+
+  // Merge user edits + remap beats from audio-file → composition coordinates.
+  const beatEdits = usePlayerStore((s) => s.beatEdits);
+  const adjustedBeatAnalysis = useMemo(
+    () => remapBeatAnalysisToComposition(beatAnalysis, musicElement, beatEdits),
+    [beatAnalysis, musicElement, beatEdits],
+  );
   const duration = usePlayerStore((s) => s.duration);
   const timelineReady = usePlayerStore((s) => s.timelineReady);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
@@ -423,8 +438,6 @@ export const Timeline = memo(function Timeline({
           renderClipContent={renderClipContent}
           renderClipOverlay={renderClipOverlay}
           playheadRef={playheadRef}
-          onResizeElement={onResizeElement}
-          onMoveElement={onMoveElement}
           onDrillDown={onDrillDown}
           onSelectElement={onSelectElement}
           setHoveredClip={setHoveredClip}
@@ -440,7 +453,7 @@ export const Timeline = memo(function Timeline({
           keyframeCache={keyframeCache}
           selectedKeyframes={selectedKeyframes}
           currentTime={currentTime}
-          onToggleKeyframeAtPlayhead={onToggleKeyframeAtPlayhead}
+          beatAnalysis={adjustedBeatAnalysis}
           onClickKeyframe={(el, pct) => {
             usePlayerStore.getState().clearSelectedKeyframes();
             const elKey = el.key ?? el.id;
@@ -458,6 +471,16 @@ export const Timeline = memo(function Timeline({
           onDragKeyframe={(el, oldPct, newPct) => {
             onMoveKeyframe?.(el, oldPct, newPct);
           }}
+          onSnapKeyframePct={(el, pct) =>
+            snapKeyframePctToBeat(el, pct, adjustedBeatAnalysis?.beatTimes, pps)
+          }
+          onPickKeyframeElement={(el) => {
+            const elKey = el.key ?? el.id;
+            if (selectedElementId !== elKey) {
+              setSelectedElementId(elKey);
+              onSelectElement?.(el);
+            }
+          }}
           onContextMenuKeyframe={(e, elId, pct) => {
             const el = elements.find((x) => (x.key ?? x.id) === elId);
             if (el) {
@@ -483,8 +506,6 @@ export const Timeline = memo(function Timeline({
             onSelectElement?.(el);
             setClipContextMenu({ x: e.clientX, y: e.clientY, element: el });
           }}
-          onRazorSplit={onRazorSplit}
-          onRazorSplitAll={onRazorSplitAll}
         />
         {activeTool === "razor" && razorGuideX !== null && (
           <div

package/src/player/components/TimelineCanvas.tsx

@@ -1,7 +1,9 @@
 import { memo, type ReactNode } from "react";
+import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
 import { TimelineClip } from "./TimelineClip";
 import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
 import { TimelineRuler } from "./TimelineRuler";
+import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import { PlayheadIndicator } from "./PlayheadIndicator";
 import {
   getTimelineEditCapabilities,
@@ -19,6 +21,8 @@ import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./us
 import type { TrackVisualStyle } from "./timelineIcons";
 import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
+import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
+import { isMusicTrack } from "../../utils/timelineInspector";
 
 function ClipLabel({ element, color }: { element: TimelineElement; color: string }) {
   const lint = usePlayerStore((s) => s.lintFindingsByElement.get(element.key ?? element.id));
@@ -66,8 +70,6 @@ interface TimelineCanvasProps {
   ) => ReactNode;
   renderClipOverlay?: (element: TimelineElement) => ReactNode;
   playheadRef: React.RefObject<HTMLDivElement | null>;
-  onResizeElement?: unknown;
-  onMoveElement?: unknown;
   onDrillDown?: (element: TimelineElement) => void;
   onSelectElement?: (element: TimelineElement | null) => void;
   setHoveredClip: (key: string | null) => void;
@@ -90,11 +92,13 @@ interface TimelineCanvasProps {
   onClickKeyframe?: (element: TimelineElement, percentage: number) => void;
   onShiftClickKeyframe?: (elementId: string, percentage: number) => void;
   onDragKeyframe?: (element: TimelineElement, oldPct: number, newPct: number) => void;
+  /** Snap a keyframe's clip-relative % to the nearest beat (returns unchanged when none in range). */
+  onSnapKeyframePct?: (element: TimelineElement, pct: number) => number;
+  /** Select the element when a keyframe drag starts (loads its GSAP session). */
+  onPickKeyframeElement?: (element: TimelineElement) => void;
   onContextMenuKeyframe?: (e: React.MouseEvent, elementId: string, percentage: number) => void;
   onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
-  onToggleKeyframeAtPlayhead?: (element: TimelineElement) => void;
-  onRazorSplit?: (element: TimelineElement, splitTime: number) => void;
-  onRazorSplitAll?: (splitTime: number) => void;
+  beatAnalysis?: MusicBeatAnalysis | null;
 }
 
 export const TimelineCanvas = memo(function TimelineCanvas({
@@ -122,8 +126,6 @@ export const TimelineCanvas = memo(function TimelineCanvas({
   renderClipContent,
   renderClipOverlay,
   playheadRef,
-  onResizeElement,
-  onMoveElement,
   onDrillDown,
   onSelectElement,
   setHoveredClip,
@@ -142,12 +144,15 @@ export const TimelineCanvas = memo(function TimelineCanvas({
   onClickKeyframe,
   onShiftClickKeyframe,
   onDragKeyframe,
+  onSnapKeyframePct,
+  onPickKeyframeElement,
   onContextMenuKeyframe,
   onContextMenuClip,
-  onToggleKeyframeAtPlayhead: _onToggleKeyframeAtPlayhead,
-  onRazorSplit,
-  onRazorSplitAll,
+  beatAnalysis,
 }: TimelineCanvasProps) {
+  const { onResizeElement, onMoveElement, onRazorSplit, onRazorSplitAll } =
+    useTimelineEditContext();
+  const beatDragging = usePlayerStore((s) => s.beatDragging);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -204,6 +209,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
         shiftHeld={shiftHeld}
         rangeSelection={rangeSelection}
         theme={theme}
+        beatAnalysis={beatAnalysis}
       />
 
       {displayTrackOrder.map((trackNum) => {
@@ -211,6 +217,14 @@ export const TimelineCanvas = memo(function TimelineCanvas({
         const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
         const isPendingTrack =
           draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
+        // The beat-dot strip occupies the top of this track's lane (active track,
+        // or the music track when nothing is selected). When shown, keyframe
+        // diamonds shrink + drop to the bottom half so they don't collide with it.
+        const beatStripOnTrack =
+          (beatAnalysis?.beatTimes?.length ?? 0) >= 2 &&
+          (selectedElementId
+            ? els.some((e) => (e.key ?? e.id) === selectedElementId)
+            : els.some(isMusicTrack));
         return (
           <div
             key={trackNum}
@@ -244,6 +258,23 @@ export const TimelineCanvas = memo(function TimelineCanvas({
               </div>
             </div>
             <div style={{ width: trackContentWidth }} className="relative">
+              {/* Faint beat lines in every track's background (behind the clips);
+                  the active move-snap target is highlighted. */}
+              <BeatBackgroundLines
+                beatTimes={beatAnalysis?.beatTimes}
+                beatStrengths={beatAnalysis?.beatStrengths}
+                pps={pps}
+                highlightTime={draggedClip?.started ? draggedClip.snapBeatTime : null}
+              />
+              {/* Beat dots on the active track (the one holding the selection),
+                  falling back to the music track when nothing is selected. */}
+              {beatStripOnTrack && (
+                <BeatStrip
+                  beatTimes={beatAnalysis?.beatTimes}
+                  beatStrengths={beatAnalysis?.beatStrengths}
+                  pps={pps}
+                />
+              )}
               {isPendingTrack && (
                 <div
                   className="absolute inset-0 flex items-center"
@@ -358,6 +389,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                         pointerOffsetY: e.clientY - rect.top,
                         previewStart: el.start,
                         previewTrack: el.track,
+                        snapBeatTime: null,
                         started: false,
                       });
                       syncClipDragAutoScroll(e.clientX, e.clientY);
@@ -402,6 +434,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                         keyframesData={keyframeCache.get(elementKey)!}
                         clipWidthPx={Math.max(previewElement.duration * pps, 4)}
                         clipHeightPx={TRACK_H - 2 * CLIP_Y}
+                        beatsActive={beatStripOnTrack}
                         accentColor={clipStyle.accent}
                         isSelected={isSelected}
                         currentPercentage={
@@ -416,6 +449,8 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                         onDragKeyframe={(oldPct, newPct) =>
                           onDragKeyframe?.(previewElement, oldPct, newPct)
                         }
+                        snapPct={(pct) => onSnapKeyframePct?.(previewElement, pct) ?? pct}
+                        onPickForDrag={() => onPickKeyframeElement?.(previewElement)}
                         onContextMenuKeyframe={onContextMenuKeyframe}
                       />
                     )}
@@ -479,11 +514,16 @@ export const TimelineCanvas = memo(function TimelineCanvas({
         />
       )}
 
-      {/* Playhead */}
+      {/* Playhead — hidden while dragging a beat so its guideline doesn't
+          track the scrub and clutter the beat being moved. */}
       <div
         ref={playheadRef}
         className="absolute top-0 bottom-0 pointer-events-none"
-        style={{ left: `${GUTTER}px`, zIndex: 100 }}
+        style={{
+          left: `${GUTTER}px`,
+          zIndex: 100,
+          display: beatDragging ? "none" : undefined,
+        }}
       >
         <PlayheadIndicator />
       </div>

package/src/player/components/TimelineClipDiamonds.tsx

@@ -1,4 +1,5 @@
-import { memo, useRef } from "react";
+import { memo, useEffect, useRef, useState } from "react";
+import { BEAT_BAND_H } from "./BeatStrip";
 
 interface KeyframeEntry {
   percentage: number;
@@ -17,6 +18,9 @@ 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;
@@ -26,14 +30,31 @@ interface TimelineClipDiamondsProps {
   onShiftClickKeyframe?: (elementId: string, percentage: number) => void;
   onDragKeyframe?: (percentage: number, newPercentage: number) => void;
   onContextMenuKeyframe?: (e: React.MouseEvent, elementId: string, percentage: number) => void;
+  /** Snap a clip-relative percentage to the nearest beat (returns it unchanged
+   *  when no beat is within range). Drives live beat-snapping while dragging. */
+  snapPct?: (percentage: number) => number;
+  /** Select this element when a keyframe drag begins, so its GSAP session is
+   *  loaded by the time the move commits (diamonds render on unselected clips
+   *  too, and a drag suppresses the selecting click). */
+  onPickForDrag?: () => void;
 }
 
 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 clamped to the clip edge rather than hidden.
+export const KF_MIN_PCT = -5;
+export const KF_MAX_PCT = 105;
+
+function clampDiamondLeft(rawLeft: number, diamondSize: number, clipWidth: number): number {
+  return Math.max(0, Math.min(clipWidth - diamondSize, rawLeft));
+}
 
 export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
   keyframesData,
   clipWidthPx,
   clipHeightPx,
+  beatsActive,
   accentColor,
   isSelected,
   currentPercentage,
@@ -43,14 +64,62 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
   onShiftClickKeyframe,
   onDragKeyframe,
   onContextMenuKeyframe,
+  snapPct,
+  onPickForDrag,
 }: TimelineClipDiamondsProps) {
-  const dragRef = useRef<{ startX: number; startPct: number } | null>(null);
+  // Live drag: which keyframe (by original %) is being dragged and its current
+  // (beat-snapped) %, so the diamond + its connecting lines follow the cursor.
+  const dragRef = useRef<{ origPct: number; pct: number; moved: boolean } | null>(null);
+  const [drag, setDrag] = useState<{ origPct: number; pct: number } | null>(null);
+  // Commit through the latest callback, not the one captured at pointer-down:
+  // selecting the element on drag-start loads its GSAP session asynchronously,
+  // and the commit must use the closure that sees the loaded session.
+  const onDragKeyframeRef = useRef(onDragKeyframe);
+  onDragKeyframeRef.current = onDragKeyframe;
+  // Optimistic hold: after a commit, keep the diamond at the dropped position
+  // until the cache reflects the change (the file round-trip rewrites
+  // keyframesData), so it doesn't flash back to the old spot in between.
+  const pendingRef = useRef(false);
+  const pendingHeldPctRef = useRef<number | null>(null);
+  const pendingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Cleanup for an in-flight drag's document listeners, so an unmount mid-drag
+  // (clip deleted, comp switch, zoom-out → early return) doesn't leak them.
+  const dragCleanupRef = useRef<(() => void) | null>(null);
+
+  useEffect(() => {
+    if (!pendingRef.current) return;
+    // Only release the optimistic hold once the cache actually reflects the
+    // committed position (a keyframe near the held %). An unrelated cache
+    // rebuild (e.g. elementCount change) rebuilds keyframesData with the SAME
+    // percentages — releasing then would flash the diamond back to the old spot.
+    const held = pendingHeldPctRef.current;
+    if (held != null && !keyframesData.keyframes.some((k) => Math.abs(k.percentage - held) < 0.3)) {
+      return;
+    }
+    pendingRef.current = false;
+    pendingHeldPctRef.current = null;
+    if (pendingTimerRef.current) clearTimeout(pendingTimerRef.current);
+    setDrag(null);
+  }, [keyframesData]);
+
+  useEffect(
+    () => () => {
+      clearTimeout(pendingTimerRef.current ?? undefined);
+      dragCleanupRef.current?.();
+    },
+    [],
+  );
 
   if (clipWidthPx < 20) return null;
 
-  const diamondSize = Math.round(clipHeightPx * DIAMOND_RATIO);
+  // When the beat strip occupies the top band, shrink the diamonds and center
+  // them in the remaining bottom region so they don't collide with it.
+  const diamondSize = Math.round(clipHeightPx * (beatsActive ? 0.45 : DIAMOND_RATIO));
   const half = diamondSize / 2;
-  const sorted = keyframesData.keyframes.slice().sort((a, b) => a.percentage - b.percentage);
+  const centerY = beatsActive ? BEAT_BAND_H + (clipHeightPx - BEAT_BAND_H) / 2 : clipHeightPx / 2;
+  const sorted = keyframesData.keyframes
+    .filter((kf) => kf.percentage >= KF_MIN_PCT && kf.percentage <= KF_MAX_PCT)
+    .sort((a, b) => a.percentage - b.percentage);
   const baseColor = isSelected ? accentColor : "#a3a3a3";
   const baseOpacity = isSelected ? 0.4 : 0.25;
 
@@ -66,47 +135,84 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
   const handlePointerDown = (e: React.PointerEvent, pct: number) => {
     if (e.button !== 0) return;
     e.stopPropagation();
+    // Ignore a new drag while a prior drop is still settling: `pct` comes from
+    // props (the pre-drop position) but the diamond is held at its dropped spot
+    // via effPct(), so a re-grab would track from a stale origin and commit
+    // against the wrong tween. The hold clears on the cache round-trip (≤2s).
+    if (pendingRef.current) return;
+    // Select the element up front so its GSAP session loads during the drag and
+    // the commit (which resolves the animation from the selection) isn't a no-op.
+    onPickForDrag?.();
     const startX = e.clientX;
+    dragRef.current = { origPct: pct, pct, moved: false };
 
     const handleMove = (me: PointerEvent) => {
+      const d = dragRef.current;
+      if (!d) return;
       const dx = me.clientX - startX;
-      if (Math.abs(dx) > 4) {
-        dragRef.current = { startX, startPct: pct };
-      }
+      // 4px dead zone so a click doesn't register as a drag.
+      if (!d.moved && Math.abs(dx) <= 4) return;
+      d.moved = true;
+      const rawPct = Math.max(0, Math.min(100, pct + (dx / clipWidthPx) * 100));
+      const snapped = snapPct ? snapPct(rawPct) : rawPct;
+      d.pct = snapped;
+      setDrag({ origPct: pct, pct: snapped });
     };
 
-    const handleUp = (ue: PointerEvent) => {
+    const handleUp = () => {
       document.removeEventListener("pointermove", handleMove);
       document.removeEventListener("pointerup", handleUp);
-      const start = dragRef.current;
+      dragCleanupRef.current = null;
+      const d = dragRef.current;
       dragRef.current = null;
-      if (!start) return;
-      const dx = ue.clientX - start.startX;
-      const dPct = (dx / clipWidthPx) * 100;
-      const newPct = Math.max(0, Math.min(100, Math.round(start.startPct + dPct)));
-      if (Math.abs(newPct - start.startPct) > 0.5) {
-        onDragKeyframe?.(start.startPct, newPct);
+      const willCommit = !!(d && d.moved && Math.abs(d.pct - d.origPct) > 0.5);
+      if (willCommit && d) {
+        // Hold the dropped position optimistically; the effect clears it once the
+        // cache round-trip lands (fallback timeout in case it never does).
+        pendingRef.current = true;
+        pendingHeldPctRef.current = d.pct;
+        setDrag({ origPct: d.origPct, pct: d.pct });
+        if (pendingTimerRef.current) clearTimeout(pendingTimerRef.current);
+        pendingTimerRef.current = setTimeout(() => {
+          pendingRef.current = false;
+          pendingHeldPctRef.current = null;
+          setDrag(null);
+        }, 2000);
+        onDragKeyframeRef.current?.(d.origPct, d.pct);
+      } else {
+        setDrag(null);
       }
     };
 
+    dragCleanupRef.current = () => {
+      document.removeEventListener("pointermove", handleMove);
+      document.removeEventListener("pointerup", handleUp);
+    };
+
     document.addEventListener("pointermove", handleMove);
     document.addEventListener("pointerup", handleUp);
   };
 
+  const effPct = (p: number): number => (drag && drag.origPct === p ? drag.pct : p);
+
   return (
     <div className="absolute inset-0" style={{ zIndex: 3, pointerEvents: "none" }}>
       {sorted.map((kf, i) => {
         if (i === 0) return null;
         const prev = sorted[i - 1]!;
-        const x1 = (prev.percentage / 100) * clipWidthPx;
-        const x2 = (kf.percentage / 100) * clipWidthPx;
+        const x1 = Math.max(
+          0,
+          Math.min(clipWidthPx, (effPct(prev.percentage) / 100) * clipWidthPx),
+        );
+        const x2 = Math.max(0, Math.min(clipWidthPx, (effPct(kf.percentage) / 100) * clipWidthPx));
+        if (x2 - x1 < 1) return null;
         return (
           <div
             key={`line-${i}-${prev.percentage}-${kf.percentage}`}
             className="absolute"
             style={{
               left: x1,
-              top: "50%",
+              top: centerY,
               width: x2 - x1,
               height: 2,
               transform: "translateY(-1px)",
@@ -119,7 +225,11 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
       })}
 
       {sorted.map((kf, i) => {
-        const leftPx = (kf.percentage / 100) * clipWidthPx - half;
+        const leftPx = clampDiamondLeft(
+          (effPct(kf.percentage) / 100) * clipWidthPx - half,
+          diamondSize,
+          clipWidthPx,
+        );
         const kfKey = `${elementId}:${kf.percentage}`;
         const isKfSelected = selectedKeyframes.has(kfKey);
         const atPlayhead = isSelected && Math.abs(kf.percentage - currentPercentage) < 0.5;
@@ -132,7 +242,7 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
             className="absolute"
             style={{
               left: leftPx,
-              top: "50%",
+              top: centerY,
               transform: "translateY(-50%)",
               width: diamondSize,
               height: diamondSize,