@hyperframes/studio 0.7.17 → 0.7.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.17",
+  "version": "0.7.19",
   "description": "",
   "repository": {
     "type": "git",
@@ -43,13 +43,14 @@
     "@phosphor-icons/react": "^2.1.10",
     "bpm-detective": "^2.0.5",
     "dompurify": "^3.2.4",
+    "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.7.17",
-    "@hyperframes/player": "0.7.17",
-    "@hyperframes/sdk": "0.7.17",
-    "@hyperframes/studio-server": "0.7.17",
-    "@hyperframes/core": "0.7.17"
+    "@hyperframes/core": "0.7.19",
+    "@hyperframes/player": "0.7.19",
+    "@hyperframes/parsers": "0.7.19",
+    "@hyperframes/studio-server": "0.7.19",
+    "@hyperframes/sdk": "0.7.19"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -64,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.17"
+    "@hyperframes/producer": "0.7.19"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -83,7 +83,7 @@ export function StudioApp() {
   const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
   const [compositionLoading, setCompositionLoading] = useState(true);
   const [refreshKey, setRefreshKey] = useState(0);
-  const [, setPreviewDocumentVersion] = useState(0);
+  const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
   const [blockPreview, setBlockPreview] = useState<BlockPreviewInfo | null>(null);
   const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
   const activeCompPathRef = useRef(activeCompPath);
@@ -296,6 +296,7 @@ export function StudioApp() {
     projectIdRef: fileManager.projectIdRef,
     previewIframe,
     refreshKey,
+    previewDocumentVersion,
     rightPanelTab: panelLayout.rightPanelTab,
     applyStudioManualEditsToPreviewRef: previewPersistence.applyStudioManualEditsToPreviewRef,
     syncPreviewHistoryHotkey: appHotkeys.syncPreviewHistoryHotkey,

package/src/components/StudioPreviewArea.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo, type ReactNode } from "react";
+import { useState, useMemo, useCallback, type ReactNode } from "react";
 import { NLELayout } from "./nle/NLELayout";
 import { CaptionOverlay } from "../captions/components/CaptionOverlay";
 import { CaptionTimeline } from "../captions/components/CaptionTimeline";
@@ -18,6 +18,9 @@ import {
 } from "./editor/manualEditingAvailability";
 import { useStudioPlaybackContext, useStudioShellContext } from "../contexts/StudioContext";
 import { useDomEditActionsContext, useDomEditSelectionContext } from "../contexts/DomEditContext";
+import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { resolveClipTimingBasis } from "../hooks/useGsapTweenCache";
+import { resolveKeyframeRetime } from "./editor/keyframeRetime";
 import { TimelineEditProvider } from "../contexts/TimelineEditContext";
 import type { BlockPreviewInfo } from "./sidebar/BlocksTab";
 import { readStudioUiPreferences } from "../utils/studioUiPreferences";
@@ -130,10 +133,13 @@ export function StudioPreviewArea({
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
     handleGsapRemoveKeyframe,
+    handleGsapMoveKeyframeToPlayhead,
+    handleGsapMoveKeyframe,
+    handleGsapResizeKeyframedTween,
     handleGsapUpdateMeta,
     handleGsapAddKeyframe,
     handleGsapConvertToKeyframes,
-    handleGsapDeleteAllForElement,
+    handleGsapRemoveAllKeyframes,
     buildDomSelectionForTimelineElement,
     applyMarqueeSelection,
   } = useDomEditActionsContext();
@@ -149,6 +155,23 @@ export function StudioPreviewArea({
     };
   });
 
+  // Resolve a timeline-diamond callback's clip-% to the keyframe's anim id + its
+  // tween-relative percentage (shared by the delete/move keyframe callbacks): the
+  // diamond reports a clip-% but the script ops key on the tween-%. Prefers the
+  // anim in the keyframe's property group, falling back to the first keyframed one.
+  const resolveKeyframeTarget = useCallback(
+    (pct: number): { animId: string; tweenPct: number } | null => {
+      const cached = usePlayerStore.getState().keyframeCache.get(domEditSelection?.id ?? "");
+      const kf = cached?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.2);
+      const group = kf?.propertyGroup;
+      const anim =
+        (group ? selectedGsapAnimations.find((a) => a.propertyGroup === group) : undefined) ??
+        selectedGsapAnimations.find((a) => a.keyframes);
+      return anim ? { animId: anim.id, tweenPct: kf?.tweenPercentage ?? pct } : null;
+    },
+    [domEditSelection?.id, selectedGsapAnimations],
+  );
+
   // fallow-ignore-next-line complexity
   const timelineEditCallbacks = useMemo(
     () => ({
@@ -158,21 +181,69 @@ export function StudioPreviewArea({
       onSplitElement: handleTimelineElementSplit,
       onRazorSplit: handleRazorSplit,
       onRazorSplitAll: handleRazorSplitAll,
-      onDeleteAllKeyframes: (elId: string) => {
-        const rawId = elId.includes("#") ? (elId.split("#").pop() ?? elId) : elId;
-        handleGsapDeleteAllForElement(`#${rawId}`);
+      onDeleteAllKeyframes: () => {
+        // Hold the element where it is (collapse keyframes to a static set) rather
+        // than deleting the whole animation — deleting strands a stale GSAP base
+        // that the next drag adds to, flinging the element off-screen.
+        const anim = selectedGsapAnimations.find((a) => a.keyframes);
+        if (!anim) return;
+        handleGsapRemoveAllKeyframes(anim.id);
       },
-      // fallow-ignore-next-line complexity
       onDeleteKeyframe: (_elId: string, pct: number) => {
-        const cacheKey = domEditSelection?.id ?? "";
-        const cached = usePlayerStore.getState().keyframeCache.get(cacheKey);
-        const kf = cached?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.2);
-        const group = kf?.propertyGroup;
-        const anim =
-          (group ? selectedGsapAnimations.find((a) => a.propertyGroup === group) : undefined) ??
-          selectedGsapAnimations.find((a) => a.keyframes);
-        if (!anim) return;
-        handleGsapRemoveKeyframe(anim.id, kf?.tweenPercentage ?? pct);
+        const target = resolveKeyframeTarget(pct);
+        if (target) handleGsapRemoveKeyframe(target.animId, target.tweenPct);
+      },
+      // Retime the keyframe to the playhead, preserving its value + ease.
+      onMoveKeyframeToPlayhead: (_elId: string, pct: number) => {
+        const target = resolveKeyframeTarget(pct);
+        if (target) handleGsapMoveKeyframeToPlayhead(target.animId, target.tweenPct);
+      },
+      // Drag-to-retime. The diamond reports clip-%s; resolveKeyframeTarget gives
+      // the dragged keyframe's anim + tween-%. We convert the clip-% drop to an
+      // absolute time (via the clip's timing basis) and let resolveKeyframeRetime
+      // decide: a drop inside the tween window is a plain move (re-key tween-%); a
+      // drop past the boundary (last keyframe past the end, first before the start)
+      // resizes the tween — position/duration grow so the dragged keyframe lands at
+      // the drop while every other keyframe keeps its absolute time (value+ease too).
+      onMoveKeyframe: (_elId: string, fromClipPct: number, toClipPct: number) => {
+        const target = resolveKeyframeTarget(fromClipPct);
+        const sel = domEditSelection;
+        if (!target || !sel) return;
+        const anim = selectedGsapAnimations.find((a) => a.id === target.animId);
+        const tweenStart = anim ? resolveTweenStart(anim) : null;
+        if (!anim || tweenStart === null) return;
+        const tweenDuration = anim.duration ?? resolveTweenDuration(anim);
+        const sourceFile = sel.sourceFile || activeCompPath || "index.html";
+        const { elements, domClipChildren } = usePlayerStore.getState();
+        const { elStart, elDuration } = resolveClipTimingBasis(
+          sel.id ?? "",
+          sourceFile,
+          elements,
+          domClipChildren,
+        );
+        const dropAbsTime = elStart + (toClipPct / 100) * elDuration;
+        const decision = resolveKeyframeRetime({
+          keyframes: anim.keyframes?.keyframes ?? [],
+          draggedTweenPct: target.tweenPct,
+          tweenStart,
+          tweenDuration,
+          dropAbsTime,
+        });
+        if (decision.kind === "move" && decision.toTweenPct != null) {
+          handleGsapMoveKeyframe(target.animId, target.tweenPct, decision.toTweenPct);
+        } else if (
+          decision.kind === "resize" &&
+          decision.pctRemap &&
+          decision.position != null &&
+          decision.duration != null
+        ) {
+          handleGsapResizeKeyframedTween(
+            target.animId,
+            decision.position,
+            decision.duration,
+            decision.pctRemap,
+          );
+        }
       },
       onChangeKeyframeEase: (_elId: string, _pct: number, ease: string) => {
         for (const anim of selectedGsapAnimations) {
@@ -208,16 +279,20 @@ export function StudioPreviewArea({
       handleTimelineElementSplit,
       handleRazorSplit,
       handleRazorSplitAll,
-      handleGsapDeleteAllForElement,
-      domEditSelection?.id,
+      handleGsapRemoveAllKeyframes,
+      resolveKeyframeTarget,
       selectedGsapAnimations,
       handleGsapRemoveKeyframe,
+      handleGsapMoveKeyframeToPlayhead,
+      handleGsapMoveKeyframe,
+      handleGsapResizeKeyframedTween,
       handleGsapUpdateMeta,
       handleGsapAddKeyframe,
       handleGsapConvertToKeyframes,
       buildDomSelectionForTimelineElement,
       projectId,
       activeCompPath,
+      domEditSelection,
     ],
   );
 

package/src/components/TimelineToolbar.tsx

@@ -5,6 +5,7 @@ import {
   type EnableKeyframesSession,
 } from "../hooks/useEnableKeyframes";
 import { computeElementPercentage } from "../hooks/gsapShared";
+import { useKeyframeKeyboard } from "../hooks/useKeyframeKeyboard";
 import {
   getNextTimelineZoomPercent,
   getTimelineZoomPercent,
@@ -89,6 +90,13 @@ export function TimelineToolbar({
     onToggle: onToggleKeyframe,
   } = useKeyframeToggle(domEditSession);
 
+  // Wire the "Add keyframe (K)" shortcut the toolbar advertises. Active only when
+  // there's a keyframeable selection; otherwise K stays JKL-pause in playback.
+  useKeyframeKeyboard({
+    enabled: STUDIO_KEYFRAMES_ENABLED && Boolean(onToggleKeyframe),
+    onAddKeyframe: onToggleKeyframe,
+  });
+
   return (
     <div className="border-b border-neutral-800/40 bg-neutral-950/96">
       <div className="flex items-center justify-between px-3 py-2">

package/src/components/editor/MotionPathOverlay.tsx

@@ -71,7 +71,8 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     commitMutation,
     selectedGsapAnimations,
     handleGsapRemoveKeyframe,
-    handleGsapDeleteAllForElement,
+    handleGsapRemoveAllKeyframes,
+    handleGsapMoveKeyframeToPlayhead,
   } = useDomEditContext();
   const { rect, geometry, geometryResolved, visibleInPreview, home, pScale } = useMotionPathData(
     iframeRef,
@@ -489,7 +490,8 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
           state={kfMenu}
           onClose={() => setKfMenu(null)}
           onDelete={(_elId, pct) => animId && handleGsapRemoveKeyframe(animId, pct)}
-          onDeleteAll={(elId) => handleGsapDeleteAllForElement(`#${elId}`)}
+          onDeleteAll={() => animId && handleGsapRemoveAllKeyframes(animId)}
+          onMoveToPlayhead={(_elId, pct) => animId && handleGsapMoveKeyframeToPlayhead(animId, pct)}
         />
       )}
     </>

package/src/components/editor/keyframeDrag.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveKeyframeDrag,
+  previewClipPct,
+  clampToNeighbors,
+  KEYFRAME_DRAG_THRESHOLD_PX,
+} from "./keyframeDrag";
+
+// Three keyframes at clip-% 20 / 40 / 60. The dragged one (index 1) is bounded
+// by its neighbours at 20 and 60; first/last are bounded only by the clip.
+const CLIP_PCTS = [20, 40, 60];
+
+describe("resolveKeyframeDrag — click vs drag threshold", () => {
+  const base = {
+    clipWidthPx: 200,
+    draggedClipPct: 40,
+    draggedIndex: 1,
+    sortedClipPcts: CLIP_PCTS,
+  };
+
+  it("treats sub-threshold movement as a click", () => {
+    const r = resolveKeyframeDrag({
+      ...base,
+      pointerDownX: 100,
+      pointerUpX: 100 + (KEYFRAME_DRAG_THRESHOLD_PX - 1),
+    });
+    expect(r.kind).toBe("click");
+  });
+
+  it("treats movement at/over the threshold as a drag", () => {
+    const r = resolveKeyframeDrag({
+      ...base,
+      pointerDownX: 100,
+      pointerUpX: 100 + KEYFRAME_DRAG_THRESHOLD_PX + 1,
+    });
+    expect(r.kind).toBe("move");
+  });
+
+  it("guards a zero-width clip (no division blowup) → click", () => {
+    const r = resolveKeyframeDrag({ ...base, clipWidthPx: 0, pointerDownX: 0, pointerUpX: 50 });
+    expect(r.kind).toBe("click");
+  });
+
+  it("no-ops a past-threshold drag that resolves to the source percentage", () => {
+    // Over the px threshold, but on a huge clip the 5px maps to ~0.00125 clip%
+    // away — under the noop epsilon, so don't commit a churn write.
+    const r = resolveKeyframeDrag({
+      ...base,
+      clipWidthPx: 1_000_000,
+      pointerDownX: 80,
+      pointerUpX: 80 + KEYFRAME_DRAG_THRESHOLD_PX + 1,
+    });
+    expect(r.kind).toBe("noop");
+  });
+});
+
+describe("resolveKeyframeDrag — pixel delta → clip%", () => {
+  // 200px wide clip → 2px per clip-%. Dragged diamond at clip 40%, pointer-down
+  // anchored at its pixel position (80px) for a clean delta.
+  const base = {
+    clipWidthPx: 200,
+    draggedClipPct: 40,
+    draggedIndex: 1,
+    sortedClipPcts: CLIP_PCTS,
+    pointerDownX: 80,
+  };
+
+  it("maps a rightward drag to clip-%", () => {
+    // +20px → +10 clip% → clip 50% (within [20, 60]).
+    const r = resolveKeyframeDrag({ ...base, pointerUpX: 100 });
+    expect(r.kind).toBe("move");
+    expect(r.toClipPct).toBeCloseTo(50, 5);
+  });
+
+  it("maps a leftward drag", () => {
+    // -20px → -10 clip% → clip 30%.
+    const r = resolveKeyframeDrag({ ...base, pointerUpX: 60 });
+    expect(r.toClipPct).toBeCloseTo(30, 5);
+  });
+});
+
+describe("resolveKeyframeDrag — neighbour + clip clamp", () => {
+  const base = { clipWidthPx: 200, pointerDownX: 80 };
+
+  it("an interior keyframe cannot pass its right neighbour", () => {
+    // Drag the middle (clip 40, index 1) far right → clamps just inside 60.
+    const r = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 40,
+      draggedIndex: 1,
+      sortedClipPcts: CLIP_PCTS,
+      pointerUpX: 5000,
+    });
+    expect(r.toClipPct).toBeLessThan(60);
+    expect(r.toClipPct).toBeGreaterThan(59); // epsilon inside, not equal/crossed
+  });
+
+  it("an interior keyframe cannot pass its left neighbour", () => {
+    const r = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 40,
+      draggedIndex: 1,
+      sortedClipPcts: CLIP_PCTS,
+      pointerUpX: -5000,
+    });
+    expect(r.toClipPct).toBeGreaterThan(20);
+    expect(r.toClipPct).toBeLessThan(21);
+  });
+
+  it("the first keyframe is free to the clip start (0%) but bounded by the 2nd", () => {
+    // Index 0 dragged left past 0 → clamps to 0.
+    const left = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 20,
+      draggedIndex: 0,
+      sortedClipPcts: CLIP_PCTS,
+      pointerUpX: -5000,
+    });
+    expect(left.toClipPct).toBe(0);
+    // Dragged right past the 2nd keyframe (40) → clamps just inside it.
+    const right = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 20,
+      draggedIndex: 0,
+      sortedClipPcts: CLIP_PCTS,
+      pointerUpX: 5000,
+    });
+    expect(right.toClipPct).toBeLessThan(40);
+    expect(right.toClipPct).toBeGreaterThan(39);
+  });
+
+  it("the last keyframe is free to the clip end (100%) but bounded by the 2nd-to-last", () => {
+    const right = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 60,
+      draggedIndex: 2,
+      sortedClipPcts: CLIP_PCTS,
+      pointerUpX: 5000,
+    });
+    expect(right.toClipPct).toBe(100);
+    const left = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 60,
+      draggedIndex: 2,
+      sortedClipPcts: CLIP_PCTS,
+      pointerUpX: -5000,
+    });
+    expect(left.toClipPct).toBeGreaterThan(40);
+    expect(left.toClipPct).toBeLessThan(41);
+  });
+
+  it("a lone keyframe moves freely across the whole clip", () => {
+    const r = resolveKeyframeDrag({
+      ...base,
+      draggedClipPct: 50,
+      draggedIndex: 0,
+      sortedClipPcts: [50],
+      pointerUpX: 5000,
+    });
+    expect(r.toClipPct).toBe(100);
+  });
+});
+
+describe("clampToNeighbors", () => {
+  it("pins to the midpoint when neighbours are tighter than 2·epsilon", () => {
+    // Neighbours at 10 and 10.5 → window [10.5, 10] inverts → midpoint 10.25.
+    expect(clampToNeighbors(50, [10, 10.2, 10.5], 1)).toBeCloseTo(10.25, 5);
+  });
+});
+
+describe("previewClipPct", () => {
+  it("follows the pointer in clip-% and clamps to neighbours", () => {
+    expect(
+      previewClipPct({
+        pointerDownX: 80,
+        pointerMoveX: 100,
+        clipWidthPx: 200,
+        draggedClipPct: 40,
+        draggedIndex: 1,
+        sortedClipPcts: CLIP_PCTS,
+      }),
+    ).toBeCloseTo(50, 5);
+    // Far right → clamps just inside the right neighbour (60), not the clip edge.
+    expect(
+      previewClipPct({
+        pointerDownX: 80,
+        pointerMoveX: 5000,
+        clipWidthPx: 200,
+        draggedClipPct: 40,
+        draggedIndex: 1,
+        sortedClipPcts: CLIP_PCTS,
+      }),
+    ).toBeLessThan(60);
+  });
+});

package/src/components/editor/keyframeDrag.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure math for the timeline keyframe-diamond drag-to-retime gesture. Kept free
+ * of React/store so the gesture handler stays a thin orchestrator and the
+ * click-vs-drag + neighbor clamp are unit-testable in isolation.
+ *
+ * The diamond is positioned by clip-relative % (same basis it's drawn with), so
+ * this layer works entirely in clip-%: it converts the pointer pixel delta to a
+ * clip-% drop and clamps it between the dragged keyframe's neighbours (and the
+ * clip bounds). The clip-%→tween-% conversion and the move-vs-resize decision
+ * happen in the studio handler (it has the tween window + clip timing this layer
+ * deliberately doesn't), see `keyframeRetime.ts`.
+ */
+
+/** Screen-px the pointer must travel before a press counts as a drag (else click). */
+export const KEYFRAME_DRAG_THRESHOLD_PX = 4;
+/** Clip-% movement below this is treated as no change (drop == original). */
+const NOOP_EPSILON_PCT = 0.1;
+/** Gap (clip-%) kept between a dragged interior keyframe and each neighbour so it
+ *  can't equal/cross them (which would reorder the keyframes). */
+const NEIGHBOR_EPSILON_PCT = 0.5;
+
+const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n));
+
+/**
+ * Clamp a dragged keyframe's clip-% strictly between its immediate neighbours
+ * (with a small epsilon so it can't equal/cross them) and to the clip bounds.
+ *
+ * - Interior keyframe → bounded by both neighbours.
+ * - First keyframe (index 0) → left bound is the clip start (0%), so it's free to
+ *   travel left toward/past the tween start (a boundary RESIZE the handler owns).
+ * - Last keyframe → right bound is the clip end (100%), free to travel right.
+ * - Lone keyframe → free across the whole clip [0, 100].
+ */
+export function clampToNeighbors(
+  clipPct: number,
+  sortedClipPcts: ReadonlyArray<number>,
+  draggedIndex: number,
+): number {
+  const left =
+    draggedIndex > 0 ? (sortedClipPcts[draggedIndex - 1] ?? 0) + NEIGHBOR_EPSILON_PCT : 0;
+  const right =
+    draggedIndex < sortedClipPcts.length - 1
+      ? (sortedClipPcts[draggedIndex + 1] ?? 100) - NEIGHBOR_EPSILON_PCT
+      : 100;
+  // Degenerate window (neighbours closer than 2·epsilon): pin to the midpoint so
+  // the result stays ordered between them.
+  if (left > right) return (left + right) / 2;
+  return clamp(clipPct, left, right);
+}
+
+export interface KeyframeDragResult {
+  /** `click`: under the drag threshold → seek. `noop`: moved but resolved onto
+   *  the original keyframe → skip the commit. `move`: commit the retime. */
+  kind: "click" | "noop" | "move";
+  /** Clip-relative drop position, neighbour- and clip-clamped (only on `move`). */
+  toClipPct?: number;
+}
+
+/**
+ * Decide whether a diamond press was a click or a drag, and for a drag compute
+ * the neighbour-clamped clip-% drop position.
+ *
+ * - `draggedClipPct`: the dragged diamond's own clip-relative percentage.
+ * - `draggedIndex` / `sortedClipPcts`: index of the dragged keyframe within the
+ *   clip's keyframes sorted by clip-%, used for the neighbour clamp.
+ */
+export function resolveKeyframeDrag(opts: {
+  pointerDownX: number;
+  pointerUpX: number;
+  clipWidthPx: number;
+  draggedClipPct: number;
+  draggedIndex: number;
+  sortedClipPcts: ReadonlyArray<number>;
+}): KeyframeDragResult {
+  const dx = opts.pointerUpX - opts.pointerDownX;
+  if (Math.abs(dx) < KEYFRAME_DRAG_THRESHOLD_PX || opts.clipWidthPx <= 0) {
+    return { kind: "click" };
+  }
+  const rawClipPct = opts.draggedClipPct + (dx / opts.clipWidthPx) * 100;
+  const toClipPct = clampToNeighbors(rawClipPct, opts.sortedClipPcts, opts.draggedIndex);
+  if (Math.abs(toClipPct - opts.draggedClipPct) < NOOP_EPSILON_PCT) return { kind: "noop" };
+  return { kind: "move", toClipPct };
+}
+
+/**
+ * Live drag preview: the dragged diamond's clip-% as it follows the pointer,
+ * neighbour- and clip-clamped to match where the commit will land. Visual only —
+ * no runtime/GSAP hold (the #1763 flake).
+ */
+export function previewClipPct(opts: {
+  pointerDownX: number;
+  pointerMoveX: number;
+  clipWidthPx: number;
+  draggedClipPct: number;
+  draggedIndex: number;
+  sortedClipPcts: ReadonlyArray<number>;
+}): number {
+  if (opts.clipWidthPx <= 0) return opts.draggedClipPct;
+  const dx = opts.pointerMoveX - opts.pointerDownX;
+  return clampToNeighbors(
+    opts.draggedClipPct + (dx / opts.clipWidthPx) * 100,
+    opts.sortedClipPcts,
+    opts.draggedIndex,
+  );
+}