@hyperframes/studio 0.7.25 → 0.7.26

package/src/hooks/gsapWholePropertyOffsetCommit.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
+import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
+
+// Regression (#1808): with auto-keyframe recording off, a manual edit on an
+// element that already has a keyframed tween must shift every keyframe by
+// the edit's delta (preserving the animation's shape) instead of inserting
+// or updating a keyframe at the playhead.
+
+const selection = (): DomEditSelection => ({ id: "box", selector: "#box" }) as DomEditSelection;
+
+function recordingCallbacks(): {
+  mutations: Array<Record<string, unknown>>;
+  callbacks: GsapDragCommitCallbacks;
+} {
+  const mutations: Array<Record<string, unknown>> = [];
+  return {
+    mutations,
+    callbacks: {
+      commitMutation: async (_sel, mutation) => {
+        mutations.push(mutation);
+      },
+    },
+  };
+}
+
+describe("commitWholePropertyOffset", () => {
+  it("shifts every keyframe of a keyframed tween by the delta at the nearest keyframe", async () => {
+    const anim = {
+      id: "#box-rotate",
+      targetSelector: "#box",
+      method: "to",
+      resolvedStart: 0,
+      duration: 2,
+      keyframes: {
+        keyframes: [
+          { percentage: 0, properties: { rotation: 10 } },
+          { percentage: 50, properties: { rotation: 20 } },
+          { percentage: 100, properties: { rotation: 40 } },
+        ],
+      },
+    } as unknown as GsapAnimation;
+
+    const { mutations, callbacks } = recordingCallbacks();
+    // currentPct=48 lands nearest the 50% keyframe (rotation 20) — dragging to
+    // 30 is a +10 delta, applied to every keyframe.
+    await commitWholePropertyOffset(
+      selection(),
+      anim,
+      { rotation: 30 },
+      48,
+      null,
+      callbacks,
+      "Rotate",
+    );
+
+    expect(mutations).toHaveLength(1);
+    const mutation = mutations[0]!;
+    expect(mutation.type).toBe("replace-with-keyframes");
+    const keyframes = mutation.keyframes as Array<{
+      percentage: number;
+      properties: Record<string, number>;
+    }>;
+    expect(keyframes.map((k) => k.percentage)).toEqual([0, 50, 100]);
+    expect(keyframes.map((k) => k.properties.rotation)).toEqual([20, 30, 50]);
+  });
+
+  it("materializes a flat tween into a 2-point range before shifting", async () => {
+    const anim = {
+      id: "#box-fade",
+      targetSelector: "#box",
+      method: "fromTo",
+      resolvedStart: 0,
+      duration: 1,
+      properties: { opacity: 1 },
+      fromProperties: { opacity: 0 },
+    } as unknown as GsapAnimation;
+
+    const { mutations, callbacks } = recordingCallbacks();
+    // Nearest keyframe to pct=100 is the synthesized 100% stop (opacity 1) —
+    // dragging opacity to 0.5 is a -0.5 delta, applied to both stops.
+    await commitWholePropertyOffset(
+      selection(),
+      anim,
+      { opacity: 0.5 },
+      100,
+      null,
+      callbacks,
+      "Fade",
+    );
+
+    expect(mutations).toHaveLength(1);
+    const keyframes = mutations[0]!.keyframes as Array<{
+      percentage: number;
+      properties: Record<string, number>;
+    }>;
+    expect(keyframes).toEqual([
+      { percentage: 0, properties: { opacity: -0.5 } },
+      { percentage: 100, properties: { opacity: 0.5 } },
+    ]);
+  });
+
+  it("preserves keyframes' other properties and per-keyframe ease untouched", async () => {
+    const anim = {
+      id: "#box-move",
+      targetSelector: "#box",
+      method: "to",
+      resolvedStart: 0,
+      duration: 1,
+      keyframes: {
+        keyframes: [
+          { percentage: 0, properties: { x: 0, opacity: 1 }, ease: "power1.in" },
+          { percentage: 100, properties: { x: 100, opacity: 0.5 } },
+        ],
+      },
+    } as unknown as GsapAnimation;
+
+    const { mutations, callbacks } = recordingCallbacks();
+    await commitWholePropertyOffset(selection(), anim, { x: 120 }, 100, null, callbacks, "Move");
+
+    const keyframes = mutations[0]!.keyframes as Array<{
+      percentage: number;
+      properties: Record<string, number>;
+      ease?: string;
+    }>;
+    // Delta is +20 (120 - 100 at the nearest, 100%, keyframe).
+    expect(keyframes[0]).toEqual({
+      percentage: 0,
+      properties: { x: 20, opacity: 1 },
+      ease: "power1.in",
+    });
+    expect(keyframes[1]).toEqual({ percentage: 100, properties: { x: 120, opacity: 0.5 } });
+  });
+
+  it("persists a flat update instead of crashing when the tween has no synthesizable shape", async () => {
+    // Regression: removeAllKeyframesFromScript collapses a keyframed tween into a
+    // zero-duration immediateRender hold — synthesizeFlatTweenKeyframes treats that
+    // as a static hold (returns null), so `kfs` is empty. Resizing this element with
+    // auto-keyframe off used to call `kfs.reduce(...)` with no initial value, which
+    // throws "Reduce of empty array with no initial value".
+    const anim = {
+      id: "#box-hold",
+      targetSelector: "#box",
+      method: "to",
+      resolvedStart: 0,
+      duration: 0,
+      properties: { width: 200 },
+      extras: { immediateRender: "__raw:true" },
+    } as unknown as GsapAnimation;
+
+    const { mutations, callbacks } = recordingCallbacks();
+    await expect(
+      commitWholePropertyOffset(selection(), anim, { width: 300 }, 0, null, callbacks, "Resize"),
+    ).resolves.toBeUndefined();
+
+    expect(mutations).toEqual([
+      { type: "update-properties", animationId: "#box-hold", properties: { width: 300 } },
+    ]);
+  });
+});

package/src/hooks/gsapWholePropertyOffsetCommit.ts

@@ -0,0 +1,85 @@
+/**
+ * commitWholePropertyOffset — extracted from gsapDragCommit.ts to keep file
+ * sizes under the 600-line limit (mirrors gsapDragPositionCommit.ts).
+ */
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { roundTo3 } from "../utils/rounding";
+import { PROPERTY_DEFAULTS } from "./gsapShared";
+import { synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
+import { materializeIfDynamic, type GsapDragCommitCallbacks } from "./gsapDragCommit";
+
+/**
+ * Generic sibling of commitWholePathOffset for property groups other than
+ * position (rotation, size, scale) — shift every keyframe of `anim` by the
+ * same delta for each key in `newValues`, preserving the tween's shape. The
+ * delta is computed against the keyframe NEAREST `currentPct` (the one an
+ * ordinary edit would otherwise overwrite), not the live DOM: by the time a
+ * drag gesture reaches its commit step, the preview has often already
+ * gsap.set the dragged property to its new value, so the DOM can no longer
+ * tell "old" from "new".
+ */
+export async function commitWholePropertyOffset(
+  selection: DomEditSelection,
+  anim: GsapAnimation,
+  newValues: Record<string, number>,
+  currentPct: number,
+  iframe: HTMLIFrameElement | null,
+  callbacks: GsapDragCommitCallbacks,
+  label: string,
+): Promise<void> {
+  let effectiveAnim = anim;
+  if (anim.keyframes) {
+    const newId = await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
+    if (newId) effectiveAnim = { ...anim, id: newId };
+  }
+
+  const ts = resolveTweenStart(effectiveAnim);
+  const td = resolveTweenDuration(effectiveAnim);
+  const ease = effectiveAnim.keyframes?.easeEach ?? effectiveAnim.ease;
+  const keys = Object.keys(newValues);
+  const at = (props: Record<string, number | string>, key: string) =>
+    typeof props[key] === "number" ? (props[key] as number) : (PROPERTY_DEFAULTS[key] ?? 0);
+
+  const kfs =
+    effectiveAnim.keyframes?.keyframes ?? synthesizeFlatTweenKeyframes(effectiveAnim)?.keyframes;
+  if (!kfs || kfs.length === 0) {
+    // A `to()`/`from()` collapsed to a zero-duration immediateRender hold (what
+    // removeAllKeyframesFromScript leaves behind) has no shape to preserve —
+    // just persist the flat value instead of replacing with an empty keyframe list.
+    await callbacks.commitMutation(
+      selection,
+      { type: "update-properties", animationId: effectiveAnim.id, properties: newValues },
+      { label, softReload: true },
+    );
+    return;
+  }
+  const nearest = kfs.reduce((best, kf) =>
+    Math.abs(kf.percentage - currentPct) < Math.abs(best.percentage - currentPct) ? kf : best,
+  );
+
+  const shifted = kfs.map((kf) => {
+    const properties = { ...kf.properties };
+    for (const key of keys) {
+      properties[key] = roundTo3(
+        at(properties, key) + (newValues[key]! - at(nearest.properties, key)),
+      );
+    }
+    return { percentage: kf.percentage, properties, ...(kf.ease ? { ease: kf.ease } : {}) };
+  });
+
+  await callbacks.commitMutation(
+    selection,
+    {
+      type: "replace-with-keyframes",
+      animationId: effectiveAnim.id,
+      targetSelector: effectiveAnim.targetSelector,
+      position: roundTo3(ts ?? 0),
+      duration: roundTo3(td || 1),
+      keyframes: shifted,
+      ease,
+    },
+    { label, softReload: true },
+  );
+}

package/src/hooks/useAnimatedPropertyCommit.test.tsx

@@ -0,0 +1,105 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
+import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 0 });
+});
+
+const selection = { id: "box", selector: "#box" } as DomEditSelection;
+
+const keyframedAnim = {
+  id: "#box-to-position",
+  targetSelector: "#box",
+  propertyGroup: "position",
+  method: "to",
+  properties: {},
+  resolvedStart: 0,
+  duration: 2,
+  keyframes: {
+    keyframes: [
+      { percentage: 0, properties: { x: 0, y: 0 } },
+      { percentage: 100, properties: { x: 100, y: 0 } },
+    ],
+  },
+} as unknown as GsapAnimation;
+
+type Commit = (
+  selection: DomEditSelection,
+  props: Record<string, number | string>,
+) => Promise<void>;
+
+/** Renders the hook and hands its commit function to the caller via a ref callback. */
+function renderCommitHook(
+  mutations: Array<Record<string, unknown>>,
+  onReady: (commit: Commit) => void,
+) {
+  function Harness() {
+    const { commitAnimatedProperties } = useAnimatedPropertyCommit({
+      selectedGsapAnimations: [keyframedAnim],
+      gsapCommitMutation: async (_sel, mutation) => {
+        mutations.push(mutation);
+      },
+      addGsapAnimation: vi.fn(),
+      convertToKeyframes: vi.fn(),
+      previewIframeRef: { current: null },
+      bumpGsapCache: vi.fn(),
+    });
+    onReady(commitAnimatedProperties);
+    return null;
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(<Harness />);
+  });
+  return root;
+}
+
+// Regression (#1808): a "3D transform" / design-panel property edit on an
+// element that already has a keyframed tween is the ACTUAL path a manual
+// canvas nudge exercises (not the raw drag intercept) — with auto-keyframe
+// off, it must shift the whole tween instead of adding/updating a keyframe
+// at the playhead.
+describe("useAnimatedPropertyCommit — autoKeyframeEnabled toggle (#1808)", () => {
+  it("shifts the whole tween instead of updating a keyframe when the toggle is off", async () => {
+    usePlayerStore.setState({ autoKeyframeEnabled: false, currentTime: 0 });
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit: Commit | undefined;
+    const root = renderCommitHook(mutations, (fn) => (commit = fn));
+
+    await act(async () => {
+      await commit!(selection, { x: 50 });
+    });
+
+    expect(mutations).toHaveLength(1);
+    expect(mutations[0]!.type).toBe("replace-with-keyframes");
+    act(() => root.unmount());
+  });
+
+  it("still updates a keyframe at the playhead when the toggle is on (default)", async () => {
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit: Commit | undefined;
+    const root = renderCommitHook(mutations, (fn) => (commit = fn));
+
+    await act(async () => {
+      await commit!(selection, { x: 50 });
+    });
+
+    expect(mutations.some((m) => m.type === "update-keyframe" || m.type === "add-keyframe")).toBe(
+      true,
+    );
+    expect(mutations.some((m) => m.type === "replace-with-keyframes")).toBe(false);
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -17,6 +17,7 @@ import type { SetPatchProps } from "./gsapRuntimePatch";
 import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
+import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 
 interface CommitAnimatedPropertyDeps {
   selectedGsapAnimations: GsapAnimation[];
@@ -341,6 +342,27 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
         // keyframe would never land (the bug: scrolling depth on a keyframed element
         // just changed the constant instead of dropping a keyframe).
         if (elementHasKeyframes && anim) {
+          // With auto-keyframe off (#1808), nudge the whole tween instead of
+          // adding/updating a keyframe at the playhead.
+          if (!usePlayerStore.getState().autoKeyframeEnabled) {
+            const pct = computeElementPercentage(
+              usePlayerStore.getState().currentTime,
+              selection,
+              anim,
+            );
+            await commitWholePropertyOffset(
+              selection,
+              anim,
+              Object.fromEntries(
+                propEntries.filter((e): e is [string, number] => typeof e[1] === "number"),
+              ),
+              pct,
+              iframe,
+              { commitMutation: gsapCommitMutation },
+              `Edit ${primaryProp} (whole animation)`,
+            );
+            return;
+          }
           await commitKeyframeProps(
             selection,
             anim,

package/src/hooks/useAppHotkeys.ts

@@ -228,6 +228,9 @@ function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks
   }
 
   if (event.key === "s" && !event.altKey) {
+    // Reserve bare `s` for Split even when the current selection cannot split,
+    // so secondary listeners do not reinterpret the same key as Snap toggle.
+    event.preventDefault();
     const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
     if (selectedElementId) {
       const el = elements.find((e) => (e.key ?? e.id) === selectedElementId);
@@ -237,7 +240,6 @@ function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks
         currentTime > el.start &&
         currentTime < el.start + el.duration
       ) {
-        event.preventDefault();
         void cb.handleTimelineElementSplit(el, currentTime);
         return;
       }
@@ -245,7 +247,6 @@ function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks
       // that isn't in the raw `elements` list, so the s-key can't resolve them.
       // Nudge toward the razor tool instead of failing silently.
       if (!el && selectedElementId.includes("#")) {
-        event.preventDefault();
         cb.showToast("Use the razor tool (B) to split clips inside a sub-composition", "info");
         return;
       }

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -86,7 +86,7 @@ describe("applyPreviewSync", () => {
 
     // reloadPreview is wired as onAsyncFailure (3rd arg) so a MotionPath-plugin
     // CDN load failure escalates to a full reload — but it is NOT called eagerly.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).not.toHaveBeenCalled();
     // A successful instant patch is the fast path; here it missed → fallback event.
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -113,7 +113,7 @@ describe("applyPreviewSync", () => {
 
     // U4: "verify-failed" is the TRANSIENT empty-timeline window — the live state
     // is correct, so we must NOT escalate to a full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).not.toHaveBeenCalled();
     // Telemetry records the suppressed transient (escalated: false).
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -143,7 +143,7 @@ describe("applyPreviewSync", () => {
     );
 
     // Structural failure: the preview is genuinely stale/broken → full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -167,7 +167,7 @@ describe("applyPreviewSync", () => {
     );
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).not.toHaveBeenCalled();
     // "applied" emits no telemetry (only the failure paths do).
     expect(trackStudioEvent).not.toHaveBeenCalled();
@@ -185,7 +185,7 @@ describe("applyPreviewSync", () => {
     );
 
     // onAsyncFailure is wired, but the transient result does not trigger it.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -204,7 +204,7 @@ describe("applyPreviewSync", () => {
       reloadPreview,
     );
 
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -345,7 +345,7 @@ describe("runCommit — instantPatch wiring", () => {
     });
 
     expect(fetch).toHaveBeenCalledTimes(1);
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview, 0);
     expect(deps.reloadPreview).not.toHaveBeenCalled();
     expect(deps.onCacheInvalidate).toHaveBeenCalledTimes(1);
   });
@@ -360,7 +360,7 @@ describe("runCommit — instantPatch wiring", () => {
     });
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview);
+    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview, 0);
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 });

package/src/hooks/useGsapScriptCommits.ts

@@ -1,6 +1,7 @@
 import { useCallback, useMemo, useRef } from "react";
 import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
 import { applySoftReload, extractGsapScriptText } from "../utils/gsapSoftReload";
 import type { SoftReloadResult } from "../utils/gsapSoftReload";
 import { trackStudioEvent } from "../utils/studioTelemetry";
@@ -66,7 +67,11 @@ function softReloadOrEscalate(
   reloadPreview: () => void,
   origin: "preview_sync" | "sdk_refresh",
 ): void {
-  const result: SoftReloadResult = applySoftReload(iframe, scriptText, reloadPreview);
+  // Seek the rebuilt timeline to the studio's own authoritative scrub position,
+  // not the iframe's raw `__player.getTime()` — see the comment in
+  // applySoftReload for why the two can desync after a keyframe-node drag.
+  const currentTime = usePlayerStore.getState().currentTime;
+  const result: SoftReloadResult = applySoftReload(iframe, scriptText, reloadPreview, currentTime);
   if (result === "applied") return;
   trackStudioEvent("gsap_soft_reload_outcome", {
     origin,

package/src/hooks/useRenderClipContent.test.ts

@@ -1,5 +1,18 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment happy-dom
+
+import React, { act, isValidElement, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { AudioWaveform } from "../player/components/AudioWaveform";
+import type { TimelineElement } from "../player/store/playerStore";
 import { normalizeCompositionSrc } from "./useRenderClipContent";
+import { useRenderClipContent } from "./useRenderClipContent";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
 
 describe("normalizeCompositionSrc", () => {
   const origin = "http://localhost:5190";
@@ -48,3 +61,43 @@ describe("normalizeCompositionSrc", () => {
     expect(result).toBe("compositions/scenes/hero.html");
   });
 });
+
+describe("useRenderClipContent", () => {
+  function renderClipContent(el: TimelineElement): ReactNode {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    let content: ReactNode = null;
+
+    function Harness() {
+      const render = useRenderClipContent({
+        projectIdRef: { current: "my-project" },
+        compIdToSrc: new Map(),
+        activePreviewUrl: "/api/projects/my-project/preview",
+        effectiveTimelineDuration: 12,
+      });
+      content = render(el, { clip: "#222", label: "#fff" });
+      return null;
+    }
+
+    act(() => {
+      root.render(React.createElement(Harness));
+    });
+    act(() => root.unmount());
+    return content;
+  }
+
+  it("renders audio clips as waveforms even when a composition preview URL is active", () => {
+    const content = renderClipContent({
+      id: "voiceover",
+      tag: "audio",
+      start: 1,
+      duration: 4,
+      track: 1,
+      src: "assets/voiceover.mp3",
+    });
+
+    expect(isValidElement(content)).toBe(true);
+    if (isValidElement(content)) expect(content.type).toBe(AudioWaveform);
+  });
+});

package/src/hooks/useRenderClipContent.ts

@@ -110,6 +110,13 @@ export function useRenderClipContent({
         });
       }
 
+      // Audio clips — waveform visualization. Resolve these before the generic
+      // activePreviewUrl thumbnail branch; audio rows need waveform data, not a
+      // captured frame from the currently drilled composition preview.
+      if (el.tag === "audio") {
+        return renderAudioClip(el, pid, style.label);
+      }
+
       // When drilled into a composition, render all inner elements via
       // CompositionThumbnail at their start time — most accurate visual.
       if (activePreviewUrl && el.duration > 0) {
@@ -131,11 +138,6 @@ export function useRenderClipContent({
         el.duration < effectiveTimelineDuration * 0.92 &&
         !/(backdrop|background|overlay|scrim|mask)/i.test(el.id);
 
-      // Audio clips — waveform visualization
-      if (el.tag === "audio") {
-        return renderAudioClip(el, pid, style.label);
-      }
-
       if ((el.tag === "video" || el.tag === "img") && el.src) {
         const mediaSrc = el.src.startsWith("http")
           ? el.src

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

@@ -3,7 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach } from "vitest";
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import {
   Timeline,
   formatTimelineTickLabel,
@@ -54,6 +54,56 @@ describe("Timeline provider boundary", () => {
 
     act(() => root.unmount());
   });
+
+  it("opens the keyframe context menu without seeking to that keyframe", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    Object.defineProperty(host, "clientWidth", {
+      configurable: true,
+      value: 720,
+    });
+
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      currentTime: 0.25,
+      selectedElementId: "clip-1",
+      elements: [{ id: "clip-1", tag: "div", start: 0, duration: 4, track: 0 }],
+      keyframeCache: new Map([
+        [
+          "clip-1",
+          {
+            format: "percentage",
+            keyframes: [{ percentage: 50, properties: { x: 100 }, tweenPercentage: 50 }],
+          },
+        ],
+      ]),
+    });
+
+    const onSeek = vi.fn();
+    const root = createRoot(host);
+    act(() => {
+      root.render(React.createElement(Timeline, { onSeek }));
+    });
+
+    const diamond = host.querySelector<HTMLButtonElement>('button[title="50%"]');
+    expect(diamond).not.toBeNull();
+
+    act(() => {
+      diamond!.dispatchEvent(
+        new MouseEvent("contextmenu", {
+          bubbles: true,
+          cancelable: true,
+          button: 2,
+          clientX: 120,
+          clientY: 40,
+        }),
+      );
+    });
+
+    expect(onSeek).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
 });
 
 describe("generateTicks", () => {

package/src/player/components/Timeline.tsx

@@ -487,8 +487,6 @@ export const Timeline = memo(function Timeline({
             if (el) {
               setSelectedElementId(elId);
               onSelectElement?.(el);
-              const absTime = el.start + (pct / 100) * el.duration;
-              onSeek?.(absTime);
             }
             const kfData = keyframeCache.get(elId);
             const kf = kfData?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.2);

package/src/player/components/TimelineCanvas.tsx

@@ -446,6 +446,7 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                         onShiftClickKeyframe={onShiftClickKeyframe}
                         onContextMenuKeyframe={onContextMenuKeyframe}
                         onMoveKeyframe={onMoveKeyframe}
+                        suppressClickRef={suppressClickRef}
                       />
                     )}
                   </TimelineClip>