@hyperframes/studio 0.6.105 → 0.6.106

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -1,9 +1,15 @@
 /**
  * Read GSAP keyframe data from the live runtime in the preview iframe.
  * Used to discover dynamic keyframes that the AST parser can't resolve
- * (loops, variables, computed selectors).
+ * (data-driven loops, fetched values, computed selectors).
+ *
+ * Keyframe percentages returned here are TWEEN-RELATIVE (0–100 within the
+ * tween), matching the static parser. Callers convert to clip-relative via
+ * `toAbsoluteTime` + the element's clip start/duration. `scanAllRuntimeKeyframes`
+ * does that conversion itself when given a `clipById` map.
  */
-import { parsePercentageKeyframes } from "./gsapShared";
+import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
+import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 
 interface RuntimeTween {
@@ -18,155 +24,224 @@ interface RuntimeTimeline {
   duration?: () => number;
 }
 
-export function readRuntimeKeyframes(
-  iframe: HTMLIFrameElement | null,
-  selector: string,
-  compositionId?: string,
-): {
-  keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+type Pct = { percentage: number; properties: Record<string, number | string> };
+type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
+
+export interface RuntimeKeyframeEntry {
+  keyframes: Pct[];
   easeEach?: string;
-} | null {
-  if (!iframe?.contentWindow) return null;
+  /** Present when the live tween uses motionPath — drives the Arc Motion panel. */
+  arcPath?: ArcPathConfig;
+  /** Absolute start time of the source tween (seconds). */
+  tweenStart: number;
+  /** Duration of the source tween (seconds). */
+  tweenDuration: number;
+}
 
-  let timelines: Record<string, RuntimeTimeline | undefined> | undefined;
+/** Clip start/duration per element id, to convert tween-relative % to clip-relative. */
+export type ClipDims = Map<string, { start: number; duration: number }>;
+
+const FLAT_SKIP_KEYS = new Set([
+  "ease",
+  "duration",
+  "delay",
+  "stagger",
+  "motionPath",
+  "overwrite",
+  "immediateRender",
+  "onComplete",
+  "onUpdate",
+  "onStart",
+  "keyframes",
+]);
+
+function timelinesOf(iframe: HTMLIFrameElement | null): Record<string, RuntimeTimeline> | null {
+  if (!iframe?.contentWindow) return null;
   try {
-    timelines = (
-      iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> }
-    ).__timelines;
+    return (
+      (iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> })
+        .__timelines ?? null
+    );
   } catch {
     return null;
   }
-  if (!timelines) return null;
+}
+
+function isXY(p: unknown): p is { x: number; y: number } {
+  return !!p && typeof (p as any).x === "number" && typeof (p as any).y === "number";
+}
+
+/** Coordinates + curviness from a live `vars.motionPath` value (object or array form), or null. */
+function coordsFromMotionPath(mp: unknown): {
+  coords: Array<{ x: number; y: number }>;
+  curviness: number;
+  autoRotate: boolean | number;
+  isCubic: boolean;
+} | null {
+  if (!mp || typeof mp !== "object") return null;
+  const obj = mp as Record<string, unknown>;
+  const pathVal = Array.isArray(mp) ? mp : obj.path;
+  if (!Array.isArray(pathVal)) return null;
+  const coords = pathVal.filter(isXY).map((p) => ({ x: p.x, y: p.y }));
+  if (coords.length < 2) return null;
+  const curviness = typeof obj.curviness === "number" ? obj.curviness : 1;
+  const autoRotate = typeof obj.autoRotate === "number" ? obj.autoRotate : obj.autoRotate === true;
+  return { coords, curviness, autoRotate, isCubic: obj.type === "cubic" };
+}
+
+/** Build an arcPath config from a live `vars.motionPath` value. */
+export function arcPathFromMotionPathValue(mp: unknown): ArcPathConfig | undefined {
+  const parsed = coordsFromMotionPath(mp);
+  if (!parsed) return undefined;
+  return buildArcPath(parsed.coords, parsed.curviness, parsed.autoRotate, parsed.isCubic)?.arcPath;
+}
+
+function flatTweenKeyframes(vars: Record<string, unknown>): Pct[] | null {
+  const properties: Record<string, number | string> = {};
+  for (const [k, v] of Object.entries(vars)) {
+    if (FLAT_SKIP_KEYS.has(k)) continue;
+    if (typeof v === "number") properties[k] = roundTo3(v);
+    else if (typeof v === "string") properties[k] = v;
+  }
+  if (Object.keys(properties).length === 0) return null;
+  return [
+    { percentage: 0, properties },
+    { percentage: 100, properties },
+  ];
+}
+
+/** Tween-relative keyframes + optional arcPath for one live tween, or null. */
+function readTween(vars: Record<string, unknown>): ReadTween | null {
+  if (vars.keyframes && typeof vars.keyframes === "object") {
+    const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
+    if (parsed) return parsed;
+  }
+  const mp = coordsFromMotionPath(vars.motionPath);
+  if (mp) {
+    const shape = buildArcPath(mp.coords, mp.curviness, mp.autoRotate, mp.isCubic);
+    if (shape) {
+      const n = shape.waypoints.length;
+      const keyframes = shape.waypoints.map((wp, i) => ({
+        percentage: n > 1 ? Math.round((i / (n - 1)) * 100) : 0,
+        properties: { x: wp.x, y: wp.y },
+      }));
+      return { keyframes, arcPath: shape.arcPath };
+    }
+  }
+  const flat = flatTweenKeyframes(vars);
+  return flat ? { keyframes: flat } : null;
+}
+
+function matchesElement(tween: RuntimeTween, el: Element): boolean {
+  if (!tween.targets) return false;
+  for (const t of tween.targets()) {
+    if (t === el || (el.id && (t as Element).id === el.id)) return true;
+  }
+  return false;
+}
 
+function tweenTiming(tween: RuntimeTween): { start: number; duration: number } {
+  const rawStart = typeof tween.startTime === "function" ? tween.startTime() : 0;
+  const rawDur = typeof tween.duration === "function" ? tween.duration() : 0;
+  return {
+    start: Number.isFinite(rawStart) ? rawStart : 0,
+    duration: Number.isFinite(rawDur) ? rawDur : 0,
+  };
+}
+
+/**
+ * Read keyframes (incl. motionPath arcs) for one selector from the live timeline.
+ * Returns tween-relative percentages; callers convert to clip-relative.
+ */
+export function readRuntimeKeyframes(
+  iframe: HTMLIFrameElement | null,
+  selector: string,
+  compositionId?: string,
+): ReadTween | null {
+  const timelines = timelinesOf(iframe);
+  if (!timelines) return null;
   const tlId = compositionId || Object.keys(timelines)[0];
   if (!tlId) return null;
   const timeline = timelines[tlId];
   if (!timeline?.getChildren) return null;
 
-  let doc: Document | null = null;
+  let targetEl: Element | null = null;
   try {
-    doc = iframe.contentDocument;
+    targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
   } catch {
     return null;
   }
-  if (!doc) return null;
-
-  const targetEl = doc.querySelector(selector);
   if (!targetEl) return null;
 
   for (const tween of timeline.getChildren(true)) {
-    if (!tween.targets || !tween.vars) continue;
-    let matches = false;
-    for (const t of tween.targets()) {
-      if (t === targetEl || (targetEl.id && t.id === targetEl.id)) {
-        matches = true;
-        break;
-      }
-    }
-    if (!matches) continue;
-
-    const vars = tween.vars;
-    if (!vars.keyframes || typeof vars.keyframes !== "object") continue;
-
-    const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
-    if (parsed) return parsed;
+    if (!tween.vars || !matchesElement(tween, targetEl)) continue;
+    const read = readTween(tween.vars);
+    if (read) return read;
   }
   return null;
 }
 
-// fallow-ignore-next-line complexity
-export function scanAllRuntimeKeyframes(iframe: HTMLIFrameElement | null): Map<
-  string,
-  {
-    keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
-    easeEach?: string;
-  }
-> {
-  const result = new Map<
-    string,
-    {
-      keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
-      easeEach?: string;
-    }
-  >();
-  if (!iframe?.contentWindow) return result;
+/** Convert tween-relative keyframes to clip-relative % using the element's clip dims. */
+function toClipRelative(
+  keyframes: Pct[],
+  tweenStart: number,
+  tweenDuration: number,
+  clip: { start: number; duration: number } | undefined,
+): Pct[] {
+  if (!clip || clip.duration <= 0) return keyframes;
+  return keyframes.map((kf) => {
+    const abs = toAbsoluteTime(tweenStart, tweenDuration, kf.percentage);
+    return { ...kf, percentage: Math.round(((abs - clip.start) / clip.duration) * 100000) / 1000 };
+  });
+}
 
-  let timelines: Record<string, RuntimeTimeline | undefined> | undefined;
-  try {
-    timelines = (
-      iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> }
-    ).__timelines;
-  } catch {
-    return result;
+function buildEntry(
+  read: ReadTween,
+  start: number,
+  duration: number,
+  clip: { start: number; duration: number } | undefined,
+): RuntimeKeyframeEntry {
+  return {
+    keyframes: toClipRelative(read.keyframes, start, duration, clip),
+    tweenStart: start,
+    tweenDuration: duration,
+    ...(read.easeEach ? { easeEach: read.easeEach } : {}),
+    ...(read.arcPath ? { arcPath: read.arcPath } : {}),
+  };
+}
+
+/** Record one tween's keyframes under each target id (first-tween-per-id wins). */
+function addScanEntry(
+  result: Map<string, RuntimeKeyframeEntry>,
+  tween: RuntimeTween,
+  clipById?: ClipDims,
+): void {
+  if (!tween.targets || !tween.vars) 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)));
   }
-  if (!timelines) return result;
+}
 
+/**
+ * Scan every live tween, grouping keyframes by element id. Percentages are
+ * tween-relative unless `clipById` is supplied, in which case each entry's
+ * keyframes are converted to clip-relative. First keyframe-bearing tween per
+ * element wins (the common single-primary-tween case).
+ */
+export function scanAllRuntimeKeyframes(
+  iframe: HTMLIFrameElement | null,
+  clipById?: ClipDims,
+): Map<string, RuntimeKeyframeEntry> {
+  const result = new Map<string, RuntimeKeyframeEntry>();
+  const timelines = timelinesOf(iframe);
+  if (!timelines) return result;
   for (const timeline of Object.values(timelines)) {
     if (!timeline?.getChildren) continue;
-    const tlDuration = typeof timeline.duration === "function" ? timeline.duration() : 0;
-
-    for (const tween of timeline.getChildren(true)) {
-      if (!tween.targets || !tween.vars) continue;
-      const vars = tween.vars;
-
-      if (vars.keyframes && typeof vars.keyframes === "object") {
-        const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
-        if (parsed) {
-          for (const target of tween.targets()) {
-            const id = (target as HTMLElement).id;
-            if (id && !result.has(id)) {
-              result.set(id, parsed);
-            }
-          }
-          continue;
-        }
-      }
-
-      // Flat tweens: synthesize start + end keyframe entries
-      if (!tlDuration || tlDuration <= 0) continue;
-      const tweenStart = typeof tween.startTime === "function" ? tween.startTime() : undefined;
-      if (typeof tweenStart !== "number" || !Number.isFinite(tweenStart)) continue;
-      const tweenDur = typeof tween.duration === "function" ? tween.duration() : 0;
-
-      const startPct = Math.round((tweenStart / tlDuration) * 1000) / 10;
-      const endPct =
-        tweenDur > 0 ? Math.round(((tweenStart + tweenDur) / tlDuration) * 1000) / 10 : startPct;
-      const properties: Record<string, number | string> = {};
-      const skip = new Set([
-        "ease",
-        "duration",
-        "delay",
-        "stagger",
-        "motionPath",
-        "overwrite",
-        "immediateRender",
-        "onComplete",
-        "onUpdate",
-        "onStart",
-      ]);
-      for (const [k, v] of Object.entries(vars)) {
-        if (skip.has(k)) continue;
-        if (typeof v === "number") properties[k] = roundTo3(v);
-        else if (typeof v === "string") properties[k] = v;
-      }
-      if (Object.keys(properties).length === 0) continue;
-
-      for (const target of tween.targets()) {
-        const id = (target as HTMLElement).id;
-        if (!id) continue;
-        const existing = result.get(id);
-        const entries = existing ?? { keyframes: [] };
-        entries.keyframes.push({ percentage: startPct, properties });
-        if (endPct !== startPct) {
-          entries.keyframes.push({ percentage: endPct, properties });
-        }
-        if (!existing) result.set(id, entries);
-      }
-    }
-  }
-
-  for (const entry of result.values()) {
-    entry.keyframes.sort((a, b) => a.percentage - b.percentage);
+    for (const tween of timeline.getChildren(true)) addScanEntry(result, tween, clipById);
   }
   return result;
 }

package/src/hooks/useDomEditSession.ts

@@ -334,6 +334,7 @@ export function useDomEditSession({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleUnroll,
     commitMutation,
   } = useGsapAwareEditing({
     domEditSelection,
@@ -420,6 +421,7 @@ export function useDomEditSession({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleUnroll,
     invalidateGsapCache: bumpGsapCache,
     previewIframeRef,
     commitMutation,

package/src/hooks/useDomGeometryCommits.ts

@@ -42,7 +42,15 @@ export function useDomGeometryCommits({
 }: UseDomGeometryCommitsParams) {
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
+      const gsapBlocked = isElementGsapTargeted(previewIframeRef.current, selection.element);
+      console.log(
+        "[drag:7] handleDomPathOffsetCommit (CSS path)",
+        JSON.stringify({
+          sel: selection.id,
+          gsapBlocked,
+        }),
+      );
+      if (gsapBlocked) {
         const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
         showToast(error.message, "error");
         return Promise.reject(error);

package/src/hooks/useGsapAwareEditing.ts

@@ -98,6 +98,17 @@ export function useGsapAwareEditing({
   const handleGsapAwarePathOffsetCommit = useCallback(
     async (selection: DomEditSelection, next: { x: number; y: number }) => {
       const hasGsapAnims = selectedGsapAnimations.length > 0;
+      console.log(
+        "[drag:3] handleGsapAwarePathOffsetCommit",
+        JSON.stringify({
+          sel: selection.id,
+          offset: next,
+          hasGsapAnims,
+          interceptEnabled: STUDIO_GSAP_DRAG_INTERCEPT_ENABLED,
+          animCount: selectedGsapAnimations.length,
+          animIds: selectedGsapAnimations.map((a) => a.id).slice(0, 5),
+        }),
+      );
       if (hasGsapAnims && !STUDIO_GSAP_DRAG_INTERCEPT_ENABLED) {
         showToast(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE, "error");
         throw new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
@@ -230,6 +241,15 @@ export function useGsapAwareEditing({
     [domEditSelection, gsapCommitMutation],
   );
 
+  // Unroll all computed (helper/loop) tweens in the active timeline into literal
+  // tweens, so the clicked keyframe becomes directly editable. Visual no-op.
+  const handleUnroll = useCallback(() => {
+    void commitMutation(
+      { type: "unroll-timeline" },
+      { label: "Unroll to literal tweens", softReload: true },
+    );
+  }, [commitMutation]);
+
   return {
     handleGsapAwarePathOffsetCommit,
     handleGsapAwareBoxSizeCommit,
@@ -237,6 +257,7 @@ export function useGsapAwareEditing({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleUnroll,
     commitMutation,
   };
 }

package/src/hooks/useGsapTweenCache.ts

@@ -211,6 +211,7 @@ export function useGsapAnimationsForElement(
             keyframes: runtime.keyframes,
             ...(runtime.easeEach ? { easeEach: runtime.easeEach } : {}),
           },
+          ...(runtime.arcPath ? { arcPath: runtime.arcPath } : {}),
         };
       });
     }
@@ -243,6 +244,7 @@ export function useGsapAnimationsForElement(
                     keyframes: runtimeEntry.keyframes,
                     ...(runtimeEntry.easeEach ? { easeEach: runtimeEntry.easeEach } : {}),
                   },
+                  ...(runtimeEntry.arcPath ? { arcPath: runtimeEntry.arcPath } : {}),
                 },
               ];
             }
@@ -358,19 +360,30 @@ export function usePopulateKeyframeCacheForFile(
 
     const sf = sourceFile;
     fetchParsedAnimations(projectId, sf).then((parsed) => {
-      if (!parsed) return;
+      if (!parsed) {
+        return;
+      }
       const { setKeyframeCache } = usePlayerStore.getState();
-      // Drop the file's stale entries (including the bare keys consumers read)
-      // before repopulating, so an element whose keyframes were removed and is
-      // absent from this scan doesn't keep showing diamonds.
       clearKeyframeCacheForFile(sf);
       const { elements } = usePlayerStore.getState();
+      console.log(
+        "[kf:static] elements in store:",
+        elements
+          .map((e) => e.domId)
+          .filter(Boolean)
+          .join(", "),
+      );
       const mergedByElement = new Map<string, GsapKeyframesData>();
       for (const anim of parsed.animations) {
         const id = extractIdFromSelector(anim.targetSelector);
         if (!id) continue;
+        if (anim.hasUnresolvedKeyframes) {
+          continue;
+        }
         const kfData = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
-        if (!kfData) continue;
+        if (!kfData) {
+          continue;
+        }
         const tweenPos =
           anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
         const tweenDur = anim.duration ?? 1;
@@ -402,6 +415,12 @@ export function usePopulateKeyframeCacheForFile(
           mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
         }
       }
+      console.log(
+        "[kf:static] merged elements:",
+        [...mergedByElement.keys()].join(", "),
+        "kf counts:",
+        [...mergedByElement.entries()].map(([k, v]) => `${k}:${v.keyframes.length}`).join(", "),
+      );
       for (const [id, kfData] of mergedByElement) {
         setKeyframeCache(`${sf}#${id}`, kfData);
         setKeyframeCache(id, kfData);
@@ -428,14 +447,37 @@ export function usePopulateKeyframeCacheForFile(
       const iframe =
         iframeRef?.current ?? document.querySelector<HTMLIFrameElement>("iframe[src*='/preview/']");
       if (!iframe) return false;
-      const scanned = scanAllRuntimeKeyframes(iframe);
+      // Clip dims per element so the scan converts tween-relative keyframes to
+      // clip-relative (matching the static path) instead of timeline-relative.
+      const clipById = new Map<string, { start: number; duration: number }>();
+      for (const el of usePlayerStore.getState().elements) {
+        if (el.domId) clipById.set(el.domId, { start: el.start, duration: el.duration });
+      }
+      const scanned = scanAllRuntimeKeyframes(iframe, clipById);
+      console.log(
+        "[kf:runtime] scanned",
+        scanned.size,
+        "elements:",
+        [...scanned.keys()].join(", "),
+      );
       if (scanned.size === 0) return false;
       const { setKeyframeCache, keyframeCache } = usePlayerStore.getState();
       for (const [id, data] of scanned) {
         const cacheKey = `${sf}#${id}`;
         const fallbackKey = `index.html#${id}`;
-        if (keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey) || keyframeCache.has(id))
+        const alreadyCached =
+          keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey) || keyframeCache.has(id);
+        if (alreadyCached) {
           continue;
+        }
+        console.log(
+          "[kf:runtime] adding runtime entry:",
+          id,
+          "kfs:",
+          data.keyframes.length,
+          "arc:",
+          !!data.arcPath,
+        );
         const entry = {
           format: "percentage" as const,
           keyframes: data.keyframes,