feat(studio): GSAP runtime read layer + shared helpers

readRuntimeKeyframes skips zero-duration hf-hold sets and picks the first real
timeline; shared tween/selector helpers, tween cache, and fetch fallback.

Author: miguel-heygen

packages/studio/src/hooks/gsapRuntimeKeyframes.test.ts

@@ -1,5 +1,98 @@
 import { describe, expect, it } from "vitest";
-import { arcPathFromMotionPathValue } from "./gsapRuntimeKeyframes";
+import { arcPathFromMotionPathValue, readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
+
+// Build a fake preview iframe whose runtime timeline holds the given child tweens
+// and resolves `selector` to `el`.
+function fakeIframe(el: { id: string }, children: unknown[], now?: number): HTMLIFrameElement {
+  const timeline = {
+    getChildren: () => children,
+    duration: () => 14.6,
+    ...(now != null ? { time: () => now } : {}),
+  };
+  return {
+    contentWindow: { __timelines: { "index.html": timeline } },
+    contentDocument: { querySelector: (sel: string) => (sel === `#${el.id}` ? el : null) },
+  } as unknown as HTMLIFrameElement;
+}
+
+describe("readRuntimeKeyframes — zero-duration set must not shadow the keyframed tween", () => {
+  const el = { id: "puck-b" };
+  const holdSet = {
+    targets: () => [el],
+    vars: { x: 0, y: 0, data: "hf-hold" },
+    duration: () => 0,
+    startTime: () => 0,
+  };
+  const kfTween = {
+    targets: () => [el],
+    vars: {
+      keyframes: [
+        { x: 0, y: 0 },
+        { x: -180, y: -60 },
+        { x: -320, y: 40 },
+        { x: -460, y: -20 },
+      ],
+      duration: 3.4,
+      ease: "power1.inOut",
+    },
+    duration: () => 3.4,
+    startTime: () => 1.0,
+  };
+
+  it("reads all 4 keyframes from the to() even when a hold-set precedes it", () => {
+    const read = readRuntimeKeyframes(fakeIframe(el, [holdSet, kfTween]), "#puck-b");
+    expect(read?.keyframes).toHaveLength(4);
+  });
+
+  it("returns null when the element only has a zero-duration set (no real motion)", () => {
+    expect(readRuntimeKeyframes(fakeIframe(el, [holdSet]), "#puck-b")).toBeNull();
+  });
+});
+
+describe("readRuntimeKeyframes — multiple tweens pick the one under the playhead", () => {
+  const el = { id: "puck-a" };
+  // Two non-overlapping gesture recordings → two separate keyframed tweens.
+  const gestureA = {
+    targets: () => [el],
+    vars: {
+      keyframes: [
+        { x: 0, y: 0 },
+        { x: -100, y: 50 },
+      ],
+      duration: 2.03,
+    },
+    duration: () => 2.03,
+    startTime: () => 1.033, // range [1.033, 3.063]
+  };
+  const gestureB = {
+    targets: () => [el],
+    vars: {
+      keyframes: [
+        { x: 10, y: 10 },
+        { x: 20, y: 20 },
+        { x: 30, y: 30 },
+      ],
+      duration: 1.129,
+    },
+    duration: () => 1.129,
+    startTime: () => 3.342, // range [3.342, 4.471]
+  };
+
+  it("playhead inside the SECOND tween reads the second tween (not the first)", () => {
+    const read = readRuntimeKeyframes(fakeIframe(el, [gestureA, gestureB], 3.373), "#puck-a");
+    expect(read?.keyframes).toHaveLength(3); // gestureB
+  });
+
+  it("playhead inside the FIRST tween reads the first tween", () => {
+    const read = readRuntimeKeyframes(fakeIframe(el, [gestureA, gestureB], 2.0), "#puck-a");
+    expect(read?.keyframes).toHaveLength(2); // gestureA
+  });
+
+  it("playhead outside every range falls back to the first keyframed tween", () => {
+    const read = readRuntimeKeyframes(fakeIframe(el, [gestureA, gestureB], 9.0), "#puck-a");
+    expect(read?.keyframes).toHaveLength(2); // gestureA (first)
+  });
+});
 
 describe("arcPathFromMotionPathValue", () => {
   it("builds arc config from object form { path, curviness }", () => {

packages/studio/src/hooks/gsapRuntimeKeyframes.ts

@@ -22,10 +22,11 @@ interface RuntimeTween {
 interface RuntimeTimeline {
   getChildren?: (deep: boolean) => RuntimeTween[];
   duration?: () => number;
+  time?: () => number;
 }
 
 type Pct = { percentage: number; properties: Record<string, number | string> };
-type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
+export type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
 
 export interface RuntimeKeyframeEntry {
   keyframes: Pct[];
@@ -160,7 +161,11 @@ export function readRuntimeKeyframes(
 ): ReadTween | null {
   const timelines = timelinesOf(iframe);
   if (!timelines) return null;
-  const tlId = compositionId || Object.keys(timelines)[0];
+  // Skip non-timeline markers (e.g. the studio's `__proxied` flag) when no
+  // explicit composition id is given — picking those yields no getChildren.
+  const tlId =
+    compositionId ||
+    Object.keys(timelines).find((k) => typeof timelines[k]?.getChildren === "function");
   if (!tlId) return null;
   const timeline = timelines[tlId];
   if (!timeline?.getChildren) return null;
@@ -173,12 +178,32 @@ export function readRuntimeKeyframes(
   }
   if (!targetEl) return null;
 
+  // The element can have MORE THAN ONE keyframed tween at disjoint time ranges
+  // (e.g. two non-overlapping gesture recordings → two separate `to()`s). The
+  // overlay must draw the segment under the PLAYHEAD, not blindly the first one
+  // — otherwise recording a second gesture leaves the path stuck on the first.
+  const now = typeof timeline.time === "function" ? timeline.time() : null;
+  let firstRead: ReadTween | null = null;
   for (const tween of timeline.getChildren(true)) {
     if (!tween.vars || !matchesElement(tween, targetEl)) continue;
+    // Skip zero-duration tweens (`tl.set(...)`, incl. the studio position-hold
+    // `data:"hf-hold"`). They sit before the real keyframed tween and otherwise
+    // shadow it — `readTween` falls back to a degenerate 2-point flat path from
+    // the set's values, hiding the actual multi-keyframe motion.
+    const dur = typeof tween.duration === "function" ? tween.duration() : 0;
+    if (!(dur > 0)) continue;
     const read = readTween(tween.vars);
-    if (read) return read;
+    if (!read) continue;
+    if (firstRead === null) firstRead = read;
+    // Prefer the tween whose [start, start+dur] contains the playhead.
+    if (now != null) {
+      const start = typeof tween.startTime === "function" ? tween.startTime() : 0;
+      if (now >= start - 1e-3 && now <= start + dur + 1e-3) return read;
+    }
   }
-  return null;
+  // Playhead outside every tween's range (or timeline has no clock): the element
+  // still has motion, so fall back to the first keyframed tween.
+  return firstRead;
 }
 
 /** Convert tween-relative keyframes to clip-relative % using the element's clip dims. */
@@ -217,9 +242,12 @@ function addScanEntry(
   clipById?: ClipDims,
 ): void {
   if (!tween.targets || !tween.vars) return;
+  const { start, duration } = tweenTiming(tween);
+  // Skip zero-duration sets/holds — they shadow the real keyframed tween (see
+  // readRuntimeKeyframes).
+  if (!(duration > 0)) return;
   const read = readTween(tween.vars);
   if (!read) return;
-  const { start, duration } = tweenTiming(tween);
   for (const target of tween.targets()) {
     const id = (target as HTMLElement).id;
     if (id && !result.has(id)) result.set(id, buildEntry(read, start, duration, clipById?.get(id)));

packages/studio/src/hooks/gsapShared.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { parsePercentageKeyframes } from "./gsapShared";
+
+describe("parsePercentageKeyframes", () => {
+  it("parses the object/percentage form", () => {
+    const out = parsePercentageKeyframes({ "0%": { x: 0, y: 0 }, "100%": { x: 9, y: 4 } });
+    expect(out?.keyframes).toEqual([
+      { percentage: 0, properties: { x: 0, y: 0 } },
+      { percentage: 100, properties: { x: 9, y: 4 } },
+    ]);
+  });
+
+  it("parses GSAP array-form keyframes as evenly-distributed steps", () => {
+    // Regression: a multi-point shuttle path authored as `keyframes: [...]` used to
+    // read as null (no `N%` keys) → no motion path. Steps map to i/(n-1)*100%.
+    const out = parsePercentageKeyframes([
+      { x: 0, y: 0 },
+      { x: 520, y: 120 },
+      { x: 1040, y: 0 },
+      { x: 1480, y: 160 },
+    ] as unknown as Record<string, unknown>);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 33.3, 66.7, 100]);
+    expect(out?.keyframes[1]!.properties).toEqual({ x: 520, y: 120 });
+  });
+
+  it("returns null for keyframes with no positional/animatable props", () => {
+    expect(parsePercentageKeyframes([] as unknown as Record<string, unknown>)).toBeNull();
+    expect(parsePercentageKeyframes({})).toBeNull();
+  });
+});

packages/studio/src/hooks/gsapShared.ts

@@ -97,16 +97,6 @@ export function queryIframeElement(
   }
 }
 
-/** Safely access an iframe's contentDocument, returning null on cross-origin errors. */
-export function getIframeDocument(iframe: HTMLIFrameElement | null): Document | null {
-  if (!iframe) return null;
-  try {
-    return iframe.contentDocument;
-  } catch {
-    return null;
-  }
-}
-
 // ── Keyframe parsing ──────────────────────────────────────────────────────────
 
 export interface ParsedPercentageKeyframes {
@@ -125,6 +115,26 @@ export function parsePercentageKeyframes(
   const keyframes: ParsedPercentageKeyframes["keyframes"] = [];
   let easeEach: string | undefined;
 
+  // GSAP array-form keyframes — `keyframes: [{x,y}, {x,y}, ...]` — are evenly
+  // distributed across the tween, so step i of n maps to i/(n-1)*100%. (The object
+  // form below uses explicit "0%" keys.) Without this, array-keyframed tweens (e.g.
+  // a multi-point shuttle path) read as null → no motion path.
+  if (Array.isArray(kfObj)) {
+    const steps = kfObj as unknown[];
+    steps.forEach((entry, i) => {
+      if (!entry || typeof entry !== "object") return;
+      const percentage = steps.length > 1 ? Math.round((i / (steps.length - 1)) * 1000) / 10 : 0;
+      const properties: Record<string, number | string> = {};
+      for (const [pk, pv] of Object.entries(entry as Record<string, unknown>)) {
+        if (pk === "ease") continue;
+        if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
+        else if (typeof pv === "string") properties[pk] = pv;
+      }
+      if (Object.keys(properties).length > 0) keyframes.push({ percentage, properties });
+    });
+    return keyframes.length > 0 ? { keyframes } : null;
+  }
+
   for (const [key, val] of Object.entries(kfObj)) {
     if (key === "easeEach") {
       if (typeof val === "string") easeEach = val;

packages/studio/src/hooks/useGsapAnimationFetchFallback.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
+import { selectElementAnimationsOrRetry } from "./useGsapAnimationFetchFallback";
+
+const anim = (targetSelector: string): GsapAnimation =>
+  ({ id: targetSelector, targetSelector, properties: {} }) as unknown as GsapAnimation;
+const parsed = (anims: GsapAnimation[]): ParsedGsap => ({ animations: anims }) as ParsedGsap;
+const target = { id: "puck-a", selector: "#puck-a" };
+
+describe("selectElementAnimationsOrRetry", () => {
+  it("returns null (retry) when the parse is cold — null or zero total animations", () => {
+    expect(selectElementAnimationsOrRetry(null, target)).toBeNull();
+    expect(selectElementAnimationsOrRetry(parsed([]), target)).toBeNull();
+  });
+
+  it("returns the matching animations from a warm parse", () => {
+    const result = selectElementAnimationsOrRetry(
+      parsed([anim("#puck-a"), anim("#other")]),
+      target,
+    );
+    expect(result?.map((a) => a.targetSelector)).toEqual(["#puck-a"]);
+  });
+
+  it("returns [] (no retry) for a warm parse with no match — element genuinely has no animation", () => {
+    expect(selectElementAnimationsOrRetry(parsed([anim("#other")]), target)).toEqual([]);
+  });
+});

packages/studio/src/hooks/useGsapAnimationFetchFallback.ts

@@ -1,18 +1,43 @@
 import { useCallback } from "react";
+import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
 
+const COLD_PARSE_RETRIES = 5;
+const COLD_PARSE_DELAY_MS = 120;
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Decide an element's animations from a parse result, or signal a retry.
+ *
+ * Returns `null` only when the parse is *cold* (missing or zero total animations)
+ * — the initial-load race where the endpoint isn't ready yet, so the caller should
+ * retry. A warm parse with no match for this element returns `[]` (the element
+ * genuinely has no animation — create a new one, don't retry).
+ */
+export function selectElementAnimationsOrRetry(
+  parsed: ParsedGsap | null,
+  target: { id: string | null; selector: string | null },
+): GsapAnimation[] | null {
+  if (!parsed || parsed.animations.length === 0) return null;
+  return getAnimationsForElement(parsed.animations, target);
+}
+
 export function useGsapAnimationFetchFallback(projectId: string | null, gsapSourceFile: string) {
   return useCallback(
-    (selection: DomEditSelection) => async () => {
-      const pid = projectId;
-      if (!pid) return [];
-      const parsed = await fetchParsedAnimations(pid, gsapSourceFile);
-      if (!parsed) return [];
-      return getAnimationsForElement(parsed.animations, {
-        id: selection.id ?? null,
-        selector: selection.selector ?? null,
-      });
+    (selection: DomEditSelection) => async (): Promise<GsapAnimation[]> => {
+      if (!projectId) return [];
+      const target = { id: selection.id ?? null, selector: selection.selector ?? null };
+      // A drag can fire before the async parse is warm; a cold parse must retry
+      // rather than fall through to the no-animation path (which duplicates the tween).
+      for (let attempt = 0; ; attempt++) {
+        const parsed = await fetchParsedAnimations(projectId, gsapSourceFile);
+        const resolved = selectElementAnimationsOrRetry(parsed, target);
+        if (resolved !== null) return resolved;
+        if (attempt >= COLD_PARSE_RETRIES) return [];
+        await delay(COLD_PARSE_DELAY_MS);
+      }
     },
     [projectId, gsapSourceFile],
   );

packages/studio/src/hooks/useGsapTweenCache.ts

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import type { GsapAnimation, GsapKeyframesData, ParsedGsap } from "@hyperframes/core/gsap-parser";
 import type { GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
+import { isStudioHoldSet } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
 import {
@@ -107,7 +108,12 @@ export async function fetchParsedAnimations(
     const res = await fetch(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-animations/${encodeURIComponent(sourceFile)}`,
     );
-    return res.ok ? ((await res.json()) as ParsedGsap) : null;
+    if (!res.ok) return null;
+    const parsed = (await res.json()) as ParsedGsap;
+    // Studio-emitted pre-keyframe hold `set`s are an internal runtime detail (they
+    // hold an element's first keyframe before its tween). They must not surface as
+    // user animations — otherwise they pollute the keyframe cache / timeline diamonds.
+    return { ...parsed, animations: parsed.animations.filter((a) => !isStudioHoldSet(a)) };
   } catch {
     return null;
   }