@hyperframes/studio 0.7.5 → 0.7.7

package/src/hooks/useGestureCommit.ts

@@ -3,16 +3,21 @@
  * Extracted from App.tsx to keep file sizes under the 600-line limit.
  */
 import { useState, useCallback, useRef, useEffect } from "react";
-import { editLog } from "../utils/editDebugLog";
 import { useGestureRecording } from "./useGestureRecording";
 import { simplifyGestureSamples } from "../utils/rdpSimplify";
+import { fitEasesFromVelocity } from "../utils/velocityEaseFitter";
+import { smoothGestureKeyframes } from "../utils/gestureSmoother";
 import { usePlayerStore } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
 
-type RecordedKeyframe = { percentage: number; properties: Record<string, number | string> };
+type RecordedKeyframe = {
+  percentage: number;
+  properties: Record<string, number | string>;
+  ease?: string;
+};
 
 /**
  * Split recorded keyframes into one keyframe-set per property group (position /
@@ -24,6 +29,7 @@ type RecordedKeyframe = { percentage: number; properties: Record<string, number
  * Emitting one tween per group keeps the position tween tagged and editable.
  * Keyframes with no prop in a group are dropped from that group's set.
  */
+// fallow-ignore-next-line complexity
 function partitionKeyframesByGroup(keyframes: RecordedKeyframe[]): RecordedKeyframe[][] {
   // Preserve first-seen group order for deterministic, stable mutation ordering.
   const groupOrder: string[] = [];
@@ -46,7 +52,11 @@ function partitionKeyframesByGroup(keyframes: RecordedKeyframe[]): RecordedKeyfr
         byGroup.set(group, set);
         groupOrder.push(group);
       }
-      set.push({ percentage: kf.percentage, properties: props });
+      set.push({
+        percentage: kf.percentage,
+        properties: props,
+        ...(kf.ease ? { ease: kf.ease } : {}),
+      });
     }
   }
   return groupOrder.map((group) => byGroup.get(group)!);
@@ -130,6 +140,7 @@ export function useGestureCommit({
 
       // Per-property epsilon: small-range properties (opacity 0–1, scale ~0.01–10)
       // need a much tighter tolerance than positional properties (x/y in px).
+      // fallow-ignore-next-line complexity
       const simplified = simplifyGestureSamples(frozenSamples, duration, (key) => {
         if (key === "opacity") return 0.01;
         if (key === "scale" || key === "scaleX" || key === "scaleY") return 0.01;
@@ -150,10 +161,12 @@ export function useGestureCommit({
       }
       if (liveSession.commitMutation) {
         const recStart = recordingStartTimeRef.current;
-        const keyframes = sortedPcts.map((pct) => ({
+        const rawKeyframes = sortedPcts.map((pct) => ({
           percentage: pct,
           properties: simplified.get(pct) as Record<string, number | string>,
         }));
+        const smoothed = smoothGestureKeyframes(rawKeyframes, 3);
+        const keyframes = fitEasesFromVelocity(smoothed, frozenSamples, duration);
         const hasPositionProps = keyframes.some((kf) =>
           Object.keys(kf.properties).some((k) => classifyPropertyGroup(k) === "position"),
         );
@@ -206,6 +219,7 @@ export function useGestureCommit({
               const mapped = keyframes.map((kf) => ({
                 percentage: rangeStartPct + (kf.percentage / 100) * (rangeEndPct - rangeStartPct),
                 properties: kf.properties,
+                ...(kf.ease ? { ease: kf.ease } : {}),
               }));
 
               const merged = [...preserved, ...mapped].sort((a, b) => a.percentage - b.percentage);
@@ -236,6 +250,11 @@ export function useGestureCommit({
                     position: roundTo3(recStart),
                     duration: roundTo3(duration),
                     keyframes: groupKfs,
+                    // Linear fallback: the velocity fitter assigns a per-keyframe
+                    // ease to non-constant segments and intentionally leaves
+                    // constant-speed segments undefined → they must stay linear,
+                    // not inherit a sigmoid.
+                    easeEach: "none",
                   },
                   { label: "Gesture recording (new range)", softReload: true },
                 );
@@ -252,6 +271,8 @@ export function useGestureCommit({
                 position: roundTo3(recStart),
                 duration: roundTo3(duration),
                 keyframes: groupKfs,
+                // Linear fallback (see above) — constant-speed segments stay linear.
+                easeEach: "none",
               },
               { label: "Gesture recording", softReload: true },
             );
@@ -270,10 +291,8 @@ export function useGestureCommit({
     }
   }, [gestureRecording, showToast, isGestureRecordingRef, domEditSessionRef]);
 
+  // fallow-ignore-next-line complexity
   const handleToggleRecording = useCallback(() => {
-    editLog("gesture", gestureStateRef.current === "recording" ? "stop" : "start", {
-      id: domEditSessionRef.current.domEditSelection?.id,
-    });
     if (gestureStateRef.current === "recording") {
       void stopAndCommitRecording();
       return;

package/src/hooks/useGestureRecording.ts

@@ -1,16 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { usePlayerStore, liveTime } from "../player/store/playerStore";
 
-// `import.meta.env` may be undefined in non-Vite bundlers (Next.js Turbopack),
-// so guard the access like the telemetry client does.
-function isDevBuild(): boolean {
-  try {
-    return import.meta.env.DEV === true;
-  } catch {
-    return false;
-  }
-}
-
 export interface GestureSample {
   time: number;
   properties: Record<string, number>;
@@ -385,13 +375,9 @@ export function useGestureRecording() {
         if (r.runtime) {
           try {
             applyRuntimePreview(r.runtime, time, properties);
-          } catch (err) {
+          } catch {
             // Preview failed — disable it for the rest of the gesture (recording
-            // continues). Surface in dev so a dead preview isn't silent; `r.runtime`
-            // is nulled below so this warns at most once per gesture.
-            if (isDevBuild()) {
-              console.warn("[GR] live preview disabled — runtime threw:", err);
-            }
+            // continues). `r.runtime` is nulled so we don't retry on every frame.
             r.runtime = null;
           }
         }

package/src/hooks/useGsapAnimationOps.ts

@@ -41,7 +41,7 @@ export function useGsapAnimationOps({
     async (
       selection: DomEditSelection,
       animationId: string,
-      updates: { duration?: number; ease?: string; position?: number },
+      updates: { duration?: number; ease?: string; easeEach?: string; position?: number },
     ) => {
       if (sdkSession && sdkDeps) {
         const targetPath = selection.sourceFile || activeCompPath || "index.html";
@@ -57,7 +57,7 @@ export function useGsapAnimationOps({
       commitMutationSafely(
         selection,
         { type: "update-meta", animationId, updates },
-        { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta` },
+        { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta`, softReload: true },
       );
     },
     [commitMutationSafely, activeCompPath, sdkSession, sdkDeps],

package/src/hooks/useGsapAwareEditing.ts

@@ -8,7 +8,6 @@
  * from the rest of the editing orchestration.
  */
 import { useCallback } from "react";
-import { editLog } from "../utils/editDebugLog";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
@@ -97,7 +96,6 @@ export function useGsapAwareEditing({
       next: { x: number; y: number },
       modifiers?: { altKey?: boolean },
     ) => {
-      editLog("manual-drag:move", { id: selection.id, next, altKey: modifiers?.altKey });
       if (gsapCommitMutation) {
         try {
           await tryGsapDragIntercept(
@@ -126,7 +124,6 @@ export function useGsapAwareEditing({
 
   const handleGsapAwareBoxSizeCommit = useCallback(
     async (selection: DomEditSelection, next: { width: number; height: number }) => {
-      editLog("manual-drag:resize", { id: selection.id, next });
       if (gsapCommitMutation) {
         try {
           const handled = await tryGsapResizeIntercept(
@@ -157,7 +154,6 @@ export function useGsapAwareEditing({
 
   const handleGsapAwareRotationCommit = useCallback(
     async (selection: DomEditSelection, next: { angle: number }) => {
-      editLog("manual-drag:rotate", { id: selection.id, next });
       if (gsapCommitMutation) {
         try {
           // Single source of truth for rotation too: tryGsapRotationIntercept handles

package/src/hooks/useGsapScriptCommits.ts

@@ -1,5 +1,4 @@
 import { useCallback, useMemo, useRef } from "react";
-import { editLog } from "../utils/editDebugLog";
 import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { applySoftReload, extractGsapScriptText } from "../utils/gsapSoftReload";
@@ -130,12 +129,6 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
   const runCommit = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
     const pid = projectIdRef.current;
     if (!pid) return;
-    editLog("gsap-commit", {
-      type: mutation.type,
-      id: selection.id,
-      file: selection.sourceFile || activeCompPath,
-      label: options.label,
-    });
     const unsafeFields = findUnsafeMutationValues(mutation);
     if (unsafeFields.length > 0) {
       showToast?.("Couldn't read element layout — try again at a different playhead time", "error");
@@ -165,11 +158,6 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     options.beforeReload?.();
     applyPreviewSync(previewIframeRef.current, result, options, reloadPreview);
     onCacheInvalidate();
-    editLog("gsap-commit:done", {
-      type: mutation.type,
-      changed: result.changed,
-      instant: Boolean(options.instantPatch),
-    });
   }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, forceReloadSdkSession]);
   // Every GSAP-script commit is a read-modify-write of one file. Overlapping
   // commits to the SAME file (any op type, any animation) interleave server-side,

package/src/hooks/useGsapTweenCache.test.ts

@@ -1,6 +1,13 @@
 import { describe, it, expect } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { getAnimationsForElement } from "./useGsapTweenCache";
+import { getAnimationsForElement, resolveSelectorElementIds } from "./useGsapTweenCache";
+
+// Minimal Document stub: querySelectorAll returns the elements mapped per selector.
+function fakeDoc(map: Record<string, { id: string }[]>): Document {
+  return {
+    querySelectorAll: (sel: string) => (map[sel] ?? []) as unknown as NodeListOf<Element>,
+  } as unknown as Document;
+}
 
 function anim(targetSelector: string): GsapAnimation {
   return {
@@ -46,4 +53,41 @@ describe("getAnimationsForElement", () => {
     expect(getAnimationsForElement(grouped, { selector: ".clock-hand" })).toHaveLength(1);
     expect(getAnimationsForElement(grouped, { selector: ".unrelated" })).toHaveLength(0);
   });
+
+  it("attributes a class tween to an id-selected element via element.matches", () => {
+    // gsap.from(".dot", {stagger}) — the element is selected by id (#dot-a), so
+    // its selector string never equals ".dot", but the live element matches it.
+    const dots = [anim(".dot")];
+    const el = { matches: (s: string) => s === ".dot" || s === "#dot-a" } as unknown as Element;
+    expect(getAnimationsForElement(dots, { id: "dot-a", selector: "#dot-a" }, el)).toHaveLength(1);
+    // Without the live element the class tween is still missed (legacy behavior).
+    expect(getAnimationsForElement(dots, { id: "dot-a", selector: "#dot-a" })).toHaveLength(0);
+  });
+
+  it("element.matches gates attribution — no over-matching", () => {
+    const dots = [anim(".dot")];
+    const el = { matches: () => false } as unknown as Element;
+    expect(getAnimationsForElement(dots, { id: "other", selector: "#other" }, el)).toHaveLength(0);
+  });
+});
+
+describe("resolveSelectorElementIds", () => {
+  it("resolves a bare #id without touching the DOM", () => {
+    expect(resolveSelectorElementIds("#hero", null)).toEqual(["hero"]);
+  });
+
+  it("resolves a class selector to every matching element id (the .dot+stagger case)", () => {
+    const doc = fakeDoc({ ".dot": [{ id: "dot-a" }, { id: "dot-b" }] });
+    expect(resolveSelectorElementIds(".dot", doc)).toEqual(["dot-a", "dot-b"]);
+  });
+
+  it("resolves a group selector across its parts (deduped)", () => {
+    const doc = fakeDoc({ ".a": [{ id: "x" }], ".b": [{ id: "y" }, { id: "x" }] });
+    expect(resolveSelectorElementIds(".a, .b", doc).sort()).toEqual(["x", "y"]);
+  });
+
+  it("falls back to a leading #id when there is no DOM", () => {
+    expect(resolveSelectorElementIds("#card .label", null)).toEqual(["card"]);
+    expect(resolveSelectorElementIds(".dot", null)).toEqual([]);
+  });
 });

package/src/hooks/useGsapTweenCache.ts

@@ -24,6 +24,7 @@ function deduplicateKeyframes(keyframes: GsapPercentageKeyframe[]): GsapPercenta
   return Array.from(byPct.values()).sort((a, b) => a.percentage - b.percentage);
 }
 
+// fallow-ignore-next-line complexity
 function synthesizeFlatTweenKeyframes(anim: GsapAnimation): GsapKeyframesData | null {
   if (anim.method === "set") {
     return {
@@ -68,6 +69,41 @@ function extractIdFromSelector(selector: string): string | null {
   return match ? match[1] : null;
 }
 
+/**
+ * Resolve a tween's target selector to the ids of the element(s) it animates.
+ * A bare `#id` resolves directly; anything else (a class like `.dot`, a group
+ * `.a, .b`, or a descendant selector) is matched against the live preview DOM so
+ * class/selector tweens (e.g. `gsap.from(".dot", {stagger})`) attribute to every
+ * element they animate — not just one parsed from the string. Falls back to a
+ * leading `#id` when there's no DOM (so the cache still populates pre-iframe).
+ */
+// fallow-ignore-next-line complexity
+export function resolveSelectorElementIds(
+  selector: string,
+  doc: Document | null | undefined,
+): string[] {
+  const bareId = selector.match(/^#([\w-]+)$/);
+  if (bareId) return [bareId[1]];
+  if (!doc) {
+    const lead = extractIdFromSelector(selector);
+    return lead ? [lead] : [];
+  }
+  const ids = new Set<string>();
+  for (const part of selector.split(",")) {
+    const sel = part.trim();
+    if (!sel) continue;
+    try {
+      for (const el of Array.from(doc.querySelectorAll(sel))) {
+        if (el.id) ids.add(el.id);
+      }
+    } catch {
+      const lead = extractIdFromSelector(sel);
+      if (lead) ids.add(lead);
+    }
+  }
+  return Array.from(ids);
+}
+
 /** The selected element's identity for matching tweens to it. */
 export interface GsapElementTarget {
   id?: string | null;
@@ -81,21 +117,37 @@ export interface GsapElementTarget {
  * (`.clock-face, .clock-hand`, emitted for array/`toArray` targets). Real
  * compositions target tweens by class via `querySelector`, so id-only matching
  * misses them.
+ *
+ * When the live DOM `element` is supplied, each comma-part of a tween's selector
+ * is also tested with `element.matches(part)` — true CSS semantics — so a
+ * class/descendant tween shared across elements (e.g. `gsap.from(".dot", {stagger})`)
+ * is attributed to *every* matching element, not just the one whose exact
+ * selector string happens to equal the tween's.
  */
 export function getAnimationsForElement(
   animations: GsapAnimation[],
   target: GsapElementTarget,
+  element?: Element | null,
 ): GsapAnimation[] {
   const matchers = new Set<string>();
   if (target.id) matchers.add(`#${target.id}`);
   if (target.selector) matchers.add(target.selector);
-  if (matchers.size === 0) return [];
+  if (matchers.size === 0 && !element) return [];
   return animations.filter((a) =>
     a.targetSelector.split(",").some((part) => {
       const trimmed = part.trim();
+      if (!trimmed) return false;
       if (matchers.has(trimmed)) return true;
       const lastSimple = trimmed.split(/\s+/).pop();
-      return lastSimple ? matchers.has(lastSimple) : false;
+      if (lastSimple && matchers.has(lastSimple)) return true;
+      if (element) {
+        try {
+          if (element.matches(trimmed)) return true;
+        } catch {
+          /* tween selector isn't a valid CSS selector for matches() — skip */
+        }
+      }
+      return false;
     }),
   );
 }
@@ -107,6 +159,9 @@ export async function fetchParsedAnimations(
   try {
     const res = await fetch(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-animations/${encodeURIComponent(sourceFile)}`,
+      // Always re-read the freshly-parsed source; no per-call timestamp (which
+      // would defeat caching forever and is a deterministic-render no-no).
+      { cache: "no-store" },
     );
     if (!res.ok) return null;
     const parsed = (await res.json()) as ParsedGsap;
@@ -156,7 +211,9 @@ export function useGsapAnimationsForElement(
 
     let cancelled = false;
     fetchParsedAnimations(projectId, sourceFile).then((parsed) => {
-      if (cancelled) return;
+      if (cancelled) {
+        return;
+      }
       if (!parsed) {
         setAllAnimations([]);
         setMultipleTimelines(false);
@@ -169,7 +226,7 @@ export function useGsapAnimationsForElement(
 
       // Retry once if initial fetch returned 0 animations — handles
       // cold-load race where the sourceFile isn't resolved yet.
-      if (parsed.animations.length === 0 && target) {
+      if (parsed.animations.length === 0 && targetKey) {
         retryTimerRef.current = setTimeout(() => {
           if (cancelled) return;
           fetchParsedAnimations(projectId, sourceFile).then((retryParsed) => {
@@ -189,18 +246,36 @@ export function useGsapAnimationsForElement(
         retryTimerRef.current = null;
       }
     };
-  }, [projectId, sourceFile, version, target]);
+  }, [projectId, sourceFile, version, target?.id, target?.selector]);
 
   const targetId = target?.id ?? null;
   const targetSelector = target?.selector ?? null;
-  const rawAnimations = useMemo(
-    () =>
-      targetId || targetSelector
-        ? getAnimationsForElement(allAnimations, { id: targetId, selector: targetSelector })
-        : [],
-    [allAnimations, targetId, targetSelector],
-  );
+  const rawAnimations = useMemo(() => {
+    if (!targetId && !targetSelector) return [];
+    // Resolve the live element so class / descendant tweens (e.g.
+    // gsap.from(".dot", {stagger})) attribute to every matching element, not
+    // just the one whose exact selector equals the tween's. `version` re-runs
+    // this after composition reloads.
+    let element: Element | null = null;
+    const doc = iframeRef?.current?.contentDocument;
+    if (doc) {
+      try {
+        element =
+          (targetId ? doc.getElementById(targetId) : null) ??
+          (targetSelector ? doc.querySelector(targetSelector) : null);
+      } catch {
+        element = null;
+      }
+    }
+    return getAnimationsForElement(
+      allAnimations,
+      { id: targetId, selector: targetSelector },
+      element,
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [allAnimations, targetId, targetSelector, version, iframeRef]);
 
+  // fallow-ignore-next-line complexity
   const animations = useMemo(() => {
     const iframe = iframeRef?.current;
     let result = rawAnimations;
@@ -268,6 +343,7 @@ export function useGsapAnimationsForElement(
   // Merges keyframes from ALL animations targeting this element and synthesizes
   // flat tweens so the cache is never downgraded vs the bulk populate.
   const elementId = target?.id ?? null;
+  // fallow-ignore-next-line complexity
   useEffect(() => {
     if (!elementId) return;
 
@@ -287,6 +363,11 @@ export function useGsapAnimationsForElement(
     let ease: string | undefined;
     let easeEach: string | undefined;
     for (const anim of animations) {
+      if (
+        anim.method === "set" &&
+        Object.keys(anim.properties).every((k) => k === "x" || k === "y")
+      )
+        continue;
       const kf = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
       if (!kf) continue;
       // Convert tween-relative percentages to clip-relative so diamonds
@@ -314,7 +395,14 @@ export function useGsapAnimationsForElement(
       if (kf.easeEach) easeEach = kf.easeEach;
     }
     if (allKeyframes.length === 0) {
-      clearKeyframeCacheForElement(sourceFile, elementId);
+      // The per-element parsed-animation match can transiently miss class /
+      // selector tweens (e.g. `.dot`) that the file-wide populate or runtime
+      // scan already cached. Only clear when no source cached this element —
+      // otherwise selecting it would wipe its diamonds.
+      const { keyframeCache } = usePlayerStore.getState();
+      const hasCached =
+        keyframeCache.has(`${sourceFile}#${elementId}`) || keyframeCache.has(elementId);
+      if (!hasCached) clearKeyframeCacheForElement(sourceFile, elementId);
       return;
     }
     const dedupedKeyframes = deduplicateKeyframes(allKeyframes);
@@ -366,47 +454,59 @@ export function usePopulateKeyframeCacheForFile(
     if (!projectId) return;
 
     const sf = sourceFile;
+    // fallow-ignore-next-line complexity
     fetchParsedAnimations(projectId, sf).then((parsed) => {
       if (!parsed) return;
       const { setKeyframeCache } = usePlayerStore.getState();
       clearKeyframeCacheForFile(sf);
       const { elements } = usePlayerStore.getState();
+      const doc = iframeRef?.current?.contentDocument;
       const mergedByElement = new Map<string, GsapKeyframesData>();
       for (const anim of parsed.animations) {
-        const id = extractIdFromSelector(anim.targetSelector);
-        if (!id) continue;
         if (anim.hasUnresolvedKeyframes) continue;
+        // Position-only set tweens are static holds (created by drag), not
+        // keyframed animations — skip them so they don't show timeline diamonds.
+        if (anim.method === "set") {
+          const propKeys = Object.keys(anim.properties).filter((k) => k !== "immediateRender");
+          if (propKeys.every((k) => k === "x" || k === "y")) {
+            continue;
+          }
+        }
         const kfData = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
         if (!kfData) continue;
         const tweenPos =
           anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
         const tweenDur = anim.duration ?? 1;
-        const timelineEl = elements.find(
-          (el) => el.domId === id || (el.key ?? el.id) === `${sf}#${id}`,
-        );
-        const elStart = timelineEl?.start ?? 0;
-        const elDuration = timelineEl?.duration ?? 1;
-        const clipKeyframes = kfData.keyframes.map((kf) => {
-          const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
-          // 0.001% precision (matching useGsapAnimationsForElement above) so a
-          // beat-snapped keyframe centers exactly on the beat dot and the two
-          // caches agree on a keyframe's percentage.
-          const clipPct =
-            elDuration > 0
-              ? Math.round(((absTime - elStart) / elDuration) * 100000) / 1000
-              : kf.percentage;
-          return {
-            ...kf,
-            percentage: clipPct,
-            tweenPercentage: kf.percentage,
-            propertyGroup: anim.propertyGroup,
-          };
-        });
-        const existing = mergedByElement.get(id);
-        if (existing) {
-          existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
-        } else {
-          mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
+        // Attribute the tween to every element it animates (handles class /
+        // group / descendant selectors, not just `#id`).
+        for (const id of resolveSelectorElementIds(anim.targetSelector, doc)) {
+          const timelineEl = elements.find(
+            (el) => el.domId === id || (el.key ?? el.id) === `${sf}#${id}`,
+          );
+          const elStart = timelineEl?.start ?? 0;
+          const elDuration = timelineEl?.duration ?? 1;
+          const clipKeyframes = kfData.keyframes.map((kf) => {
+            const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
+            // 0.001% precision (matching useGsapAnimationsForElement above) so a
+            // beat-snapped keyframe centers exactly on the beat dot and the two
+            // caches agree on a keyframe's percentage.
+            const clipPct =
+              elDuration > 0
+                ? Math.round(((absTime - elStart) / elDuration) * 100000) / 1000
+                : kf.percentage;
+            return {
+              ...kf,
+              percentage: clipPct,
+              tweenPercentage: kf.percentage,
+              propertyGroup: anim.propertyGroup,
+            };
+          });
+          const existing = mergedByElement.get(id);
+          if (existing) {
+            existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
+          } else {
+            mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
+          }
         }
       }
       for (const [id, kfData] of mergedByElement) {
@@ -419,6 +519,9 @@ export function usePopulateKeyframeCacheForFile(
     // elementCount is in the deps because new timeline elements (e.g. after a
     // sub-composition expand) need their keyframe cache populated immediately;
     // without it the effect won't re-run when elements appear/disappear.
+    // iframeRef is read for DOM selector resolution but intentionally not a dep
+    // (it's a stable ref; the separate runtime-scan effect owns iframe timing).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [projectId, sourceFile, version, elementCount]);
 
   // Separate effect for runtime keyframe discovery — polls until the iframe
@@ -430,6 +533,7 @@ export function usePopulateKeyframeCacheForFile(
     let attempts = 0;
     const maxAttempts = 10;
 
+    // fallow-ignore-next-line complexity
     const tryRuntimeScan = () => {
       if (runtimeScanDoneRef.current === `kf-cache:${projectId}:${sf}:${version}`) return true;
       const iframe =
@@ -449,7 +553,12 @@ export function usePopulateKeyframeCacheForFile(
         const fallbackKey = `index.html#${id}`;
         const alreadyCached =
           keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey) || keyframeCache.has(id);
-        if (alreadyCached) {
+        if (alreadyCached) continue;
+        // Skip position-only set tweens from runtime too — same filter as AST path
+        const isPosOnly =
+          data.keyframes.length === 1 &&
+          Object.keys(data.keyframes[0].properties).every((k) => k === "x" || k === "y");
+        if (isPosOnly) {
           continue;
         }
         const entry = {

package/src/hooks/useMusicBeatAnalysis.ts

@@ -92,33 +92,48 @@ export function useMusicBeatAnalysis(): void {
       return;
     }
     let cancelled = false;
-
-    let promise = analysisCache.get(musicSrc);
-    if (!promise) {
-      promise = analyzeMusicFromUrl(musicSrc);
-      cacheAnalysis(musicSrc, promise);
-    }
-
     const beatPath = beatFilePathForSrc(musicSrc);
-    promise
-      .then(async (analysis) => {
+    const io = ioRef.current;
+
+    // Only run expensive audio decode + beat analysis when the user has an
+    // explicit beats file saved. Without one, skip entirely — no surprise
+    // green lines on the timeline after dragging unrelated assets.
+    (async () => {
+      if (!beatPath || !io) return;
+      let hasSavedBeats = false;
+      try {
+        const content = await io.readOptionalProjectFile(beatPath);
+        const parsed = content ? parseBeats(content) : null;
+        hasSavedBeats = !!(parsed && parsed.times.length > 0);
+      } catch {
+        /* no file */
+      }
+      if (cancelled) return;
+      if (!hasSavedBeats) {
+        setBeatAnalysis(null);
+        return;
+      }
+
+      let promise = analysisCache.get(musicSrc);
+      if (!promise) {
+        promise = analyzeMusicFromUrl(musicSrc);
+        cacheAnalysis(musicSrc, promise);
+      }
+      try {
+        const analysis = await promise;
         const detected = { times: analysis.beatTimes, strengths: analysis.beatStrengths };
-        const io = ioRef.current;
-        if (!io) return;
-        const { times, strengths, hasFile } = await resolveBeats(beatPath, detected, io);
+        const { times, strengths } = await resolveBeats(beatPath, detected, io);
         if (cancelled) return;
         setBeatEdits(null);
         resetBeatHistory();
         setBeatAnalysis({ ...analysis, beatTimes: times, beatStrengths: strengths });
-        // Seed a missing file through the SAME debounced writer the edits use, so
-        // the initial write can't race a near-simultaneous edit's persist.
-        if (beatPath && !hasFile && times.length > 0) usePlayerStore.getState().beatPersist?.();
-      })
-      .catch(() => {
-        if (cancelled) return;
-        setBeatAnalysis(null);
-        analysisCache.delete(musicSrc);
-      });
+      } catch {
+        if (!cancelled) {
+          setBeatAnalysis(null);
+          analysisCache.delete(musicSrc);
+        }
+      }
+    })();
 
     return () => {
       cancelled = true;