@hyperframes/studio 0.6.122-alpha.0 → 0.7.0

package/src/hooks/useGestureRecording.ts

@@ -1,6 +1,16 @@
 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>;
@@ -29,7 +39,7 @@ interface BasePosition {
 
 interface GsapRuntime {
   seek: (t: number) => void;
-  set: (target: string, vars: Record<string, number>) => void;
+  set: (target: string, vars: Record<string, number | string>) => void;
   selector: string;
   element: HTMLElement;
   startTime: number;
@@ -85,11 +95,18 @@ function connectGsapRuntime(
 ): GsapRuntime | null {
   try {
     const win = iframeEl.contentWindow as Window & {
-      gsap?: { set: (t: string, v: Record<string, number>) => void };
+      gsap?: { set: (t: string, v: Record<string, number | string>) => void };
       __timelines?: Record<string, { seek: (t: number) => void; duration: () => number }>;
       __player?: { getTime: () => number };
     };
-    const tl = win?.__timelines ? Object.values(win.__timelines)[0] : null;
+    // Pick the first REAL timeline. `__timelines` also carries the studio's
+    // `__proxied` marker (a boolean, no `.seek`); `Object.values(...)[0]` would grab
+    // it and fail the connect — the cause of the no-live-preview gesture bug.
+    const tl = win?.__timelines
+      ? (Object.entries(win.__timelines).find(
+          ([key, value]) => key !== "__proxied" && typeof value?.seek === "function",
+        )?.[1] ?? null)
+      : null;
     if (win?.gsap?.set && tl?.seek && selector) {
       const tlDuration = tl.duration();
       return {
@@ -105,7 +122,7 @@ function connectGsapRuntime(
       };
     }
   } catch {
-    /* cross-origin or missing runtime */
+    /* connect failed */
   }
   return null;
 }
@@ -125,14 +142,14 @@ function applyRuntimePreview(
 }
 
 function recordSample(r: RecordingRefs, time: number, properties: Record<string, number>): void {
-  const sampleProps = { ...properties };
-  // Subtract both the CSS var offset AND the pointer-element snap offset
-  // so the first sample doesn't include the snap-to-cursor jump.
-  if ("x" in sampleProps)
-    sampleProps.x -= r.cssVarOffset.x + r.pointerElementOffset.x / (r.scale || 1);
-  if ("y" in sampleProps)
-    sampleProps.y -= r.cssVarOffset.y + r.pointerElementOffset.y / (r.scale || 1);
-  r.samples.push({ time, properties: sampleProps });
+  // Record the FULL position the live preview shows (element centered on the
+  // pointer, with any manual path offset folded into basePosition). Do NOT
+  // subtract the path offset: when this gesture commits as a position tween the
+  // server strips the element's --hf-studio-offset (the tween owns position — see
+  // stripStudioEditsFromTarget in studio-api), so the keyframes must already
+  // include it. Subtracting it made the committed gesture play shoved off by the
+  // offset (the offset was removed twice).
+  r.samples.push({ time, properties: { ...properties } });
   r.trail.push({ x: r.pointer.x, y: r.pointer.y });
 }
 
@@ -204,7 +221,6 @@ interface RecordingRefs {
   basePosition: { x: number; y: number };
   cssVarOffset: { x: number; y: number };
   scale: number;
-  pointerElementOffset: { x: number; y: number };
   runtime: GsapRuntime | null;
   rafId: number;
   samples: GestureSample[];
@@ -223,7 +239,6 @@ function createRecordingRefs(): RecordingRefs {
     basePosition: { x: 0, y: 0 },
     cssVarOffset: { x: 0, y: 0 },
     scale: 1,
-    pointerElementOffset: { x: 0, y: 0 },
     runtime: null,
     rafId: 0,
     samples: [],
@@ -280,30 +295,21 @@ export function useGestureRecording() {
       r.accumulated = { opacity: base.baseOpacity, scale: base.baseScale, z: 0 };
       r.basePosition = { x: base.baseX, y: base.baseY };
 
+      // --- Phase 2: iframe → studio scale, measured BEFORE clearing the path offset ---
+      // The pointer deltas in the RAF loop are in studio-viewport pixels; divide by
+      // this scale to convert them to the iframe's composition pixels.
+      r.scale = computeIframeScale(iframeEl);
+
+      // Now clear the optimistic path offset (already folded into baseX/baseY).
       if (base.cssOffX || base.cssOffY) {
         element.style.setProperty("--hf-studio-offset-x", "0px");
         element.style.setProperty("--hf-studio-offset-y", "0px");
       }
 
-      // --- Phase 2: Connect to the iframe GSAP runtime ---
+      // --- Phase 3: Connect to the iframe GSAP runtime ---
       const selector = element.id ? `#${element.id}` : null;
       r.runtime = connectGsapRuntime(element, iframeEl, selector, elementEndTime);
 
-      // --- Phase 3: Compute iframe viewport → composition scale ---
-      r.scale = computeIframeScale(iframeEl);
-
-      // --- Phase 4: Element center for pointer-element offset ---
-      // element.getBoundingClientRect() is in the iframe's viewport.
-      // Convert to the studio (parent) viewport using the iframe's position and scale.
-      const iframeRect = iframeEl.getBoundingClientRect();
-      const elRect = element.getBoundingClientRect();
-      const iframeScale = r.scale || 1;
-      const elCenterViewport = {
-        x: iframeRect.left + (elRect.left + elRect.width / 2) * iframeScale,
-        y: iframeRect.top + (elRect.top + elRect.height / 2) * iframeScale,
-      };
-      r.pointerElementOffset = { x: 0, y: 0 };
-
       // --- Phase 5: Attach event listeners ---
       const handlePointerMove = (e: PointerEvent) => {
         r.pointer = { x: e.clientX, y: e.clientY };
@@ -315,12 +321,6 @@ export function useGestureRecording() {
         // preventing an enormous bogus first keyframe from stale startPointer.
         if (!r.hasMoved) {
           r.startPointer = { x: r.pointer.x, y: r.pointer.y };
-          r.pointerElementOffset = {
-            x: r.pointer.x - elCenterViewport.x,
-            y: r.pointer.y - elCenterViewport.y,
-          };
-          r.basePosition.x += r.pointerElementOffset.x / iframeScale;
-          r.basePosition.y += r.pointerElementOffset.y / iframeScale;
           r.hasMoved = true;
         }
         r.scrollDelta += e.deltaY;
@@ -341,12 +341,12 @@ export function useGestureRecording() {
       r.startPointer = { ...r.pointer };
       const captureStart = (e: PointerEvent) => {
         if (!r.hasMoved) {
+          // Anchor the delta at the grab point — the element then moves by the
+          // pointer's *movement* from its actual position (preserving both the
+          // manual-drag start position and the grab offset). Do NOT snap the
+          // element's center to the pointer: that discarded the manual position
+          // and made the recorded 0% keyframe wrong.
           r.startPointer = { x: e.clientX, y: e.clientY };
-          const offX = e.clientX - elCenterViewport.x;
-          const offY = e.clientY - elCenterViewport.y;
-          r.pointerElementOffset = { x: offX, y: offY };
-          r.basePosition.x += offX / iframeScale;
-          r.basePosition.y += offY / iframeScale;
           r.hasMoved = true;
         }
       };
@@ -385,12 +385,19 @@ export function useGestureRecording() {
         if (r.runtime) {
           try {
             applyRuntimePreview(r.runtime, time, properties);
-          } catch {
+          } catch (err) {
+            // 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);
+            }
             r.runtime = null;
           }
         }
 
         recordSample(r, time, properties);
+
         setRecordingDuration(time);
         r.rafId = requestAnimationFrame(tick);
       };
@@ -418,6 +425,18 @@ export function useGestureRecording() {
       const { element: el, savedVisibility, savedTranslate } = r.runtime;
       el.style.visibility = savedVisibility;
       el.style.setProperty("translate", savedTranslate || "");
+      // Drop the gesture's inline gsap transform before re-applying the path
+      // offset below, so the two don't briefly stack (the recorded keyframes
+      // already encode the full position, offset included). On commit the
+      // re-seek lands on the gesture's first keyframe; on cancel this leaves the
+      // element at its pre-recording position.
+      try {
+        r.runtime.set(r.runtime.selector, {
+          clearProps: "x,y,scale,scaleX,scaleY,rotation,rotationX,rotationY,opacity,z",
+        });
+      } catch {
+        /* runtime gone */
+      }
     }
     if (r.cssVarOffset.x || r.cssVarOffset.y) {
       const el = r.runtime?.element;

package/src/hooks/useGsapAnimationFetchFallback.test.ts

@@ -0,0 +1,36 @@
+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("signals fetch-error (short retry) when the fetch itself failed (null)", () => {
+    // A null parse means fetchParsedAnimations hit a 404/network/JSON failure —
+    // not a parse-warming race, so it must NOT be conflated with a cold parse.
+    expect(selectElementAnimationsOrRetry(null, target)).toEqual({ kind: "fetch-error" });
+  });
+
+  it("signals cold (full retry budget) when the parse is reachable but has zero total animations", () => {
+    expect(selectElementAnimationsOrRetry(parsed([]), target)).toEqual({ kind: "cold" });
+  });
+
+  it("resolves the matching animations from a warm parse", () => {
+    const outcome = selectElementAnimationsOrRetry(
+      parsed([anim("#puck-a"), anim("#other")]),
+      target,
+    );
+    expect(outcome.kind).toBe("resolved");
+    expect(outcome.kind === "resolved" && outcome.animations.map((a) => a.targetSelector)).toEqual([
+      "#puck-a",
+    ]);
+  });
+
+  it("resolves to [] (no retry) for a warm parse with no match — element genuinely has no animation", () => {
+    const outcome = selectElementAnimationsOrRetry(parsed([anim("#other")]), target);
+    expect(outcome).toEqual({ kind: "resolved", animations: [] });
+  });
+});

package/src/hooks/useGsapAnimationFetchFallback.ts

@@ -1,18 +1,74 @@
 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";
 
+// A cold parse is the initial-load race: the endpoint is reachable but its parse
+// isn't warm yet (zero total animations). It's worth waiting out (~600ms).
+const COLD_PARSE_RETRIES = 5;
+const COLD_PARSE_DELAY_MS = 120;
+// A hard fetch error (404/403/network/JSON failure → `fetchParsedAnimations`
+// returns null) is NOT a parse-warming race, so it shouldn't burn the full
+// cold-parse budget. One short retry covers a transient blip; beyond that the
+// endpoint genuinely isn't serving this file, so fall through to "no animation".
+const FETCH_ERROR_RETRIES = 1;
+const FETCH_ERROR_DELAY_MS = 120;
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Outcome of resolving an element's animations from a single parse result.
+ * - `resolved`: a definitive answer (matched animations, or `[]` when the parse
+ *   is warm but this element has no animation — create a new one, don't retry).
+ * - `fetch-error`: `fetchParsedAnimations` returned null (HTTP/network/JSON
+ *   failure) — retry briefly, not for the full cold-parse budget.
+ * - `cold`: the parse came back reachable but with zero total animations — the
+ *   initial-load warming race, worth the full cold-parse retry budget.
+ */
+export type ElementAnimationsOutcome =
+  | { kind: "resolved"; animations: GsapAnimation[] }
+  | { kind: "fetch-error" }
+  | { kind: "cold" };
+
+/**
+ * Classify a parse result for one element. Differentiates a hard fetch failure
+ * (`parsed === null`) from a warm-but-empty cold parse (`animations.length === 0`)
+ * so the caller can apply the right retry budget to each.
+ */
+export function selectElementAnimationsOrRetry(
+  parsed: ParsedGsap | null,
+  target: { id: string | null; selector: string | null },
+): ElementAnimationsOutcome {
+  if (!parsed) return { kind: "fetch-error" };
+  if (parsed.animations.length === 0) return { kind: "cold" };
+  return { kind: "resolved", animations: 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). A hard fetch error is a different failure — retry only briefly.
+      let coldAttempts = 0;
+      let errorAttempts = 0;
+      for (;;) {
+        const parsed = await fetchParsedAnimations(projectId, gsapSourceFile);
+        const outcome = selectElementAnimationsOrRetry(parsed, target);
+        if (outcome.kind === "resolved") return outcome.animations;
+        if (outcome.kind === "fetch-error") {
+          if (errorAttempts >= FETCH_ERROR_RETRIES) return [];
+          errorAttempts++;
+          await delay(FETCH_ERROR_DELAY_MS);
+          continue;
+        }
+        // cold
+        if (coldAttempts >= COLD_PARSE_RETRIES) return [];
+        coldAttempts++;
+        await delay(COLD_PARSE_DELAY_MS);
+      }
     },
     [projectId, gsapSourceFile],
   );

package/src/hooks/useGsapAnimationOps.ts

@@ -101,7 +101,7 @@ export function useGsapAnimationOps({
       void commitMutation(
         selection,
         { type: "delete-all-for-selector", targetSelector },
-        { label: "Delete all animations for element" },
+        { label: "Delete all animations for element", softReload: true },
       );
     },
     [commitMutation, activeCompPath, sdkSession, sdkDeps],

package/src/hooks/useGsapAwareEditing.ts

@@ -8,16 +8,19 @@
  * 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 { STUDIO_GSAP_DRAG_INTERCEPT_ENABLED } from "../components/editor/manualEditingAvailability";
-import { GSAP_CSS_FALLBACK_BLOCKED_MESSAGE } from "./useDomGeometryCommits";
 import {
   tryGsapDragIntercept,
   tryGsapResizeIntercept,
   tryGsapRotationIntercept,
 } from "./gsapRuntimeBridge";
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
+import {
+  useGsapSaveFailureTelemetry,
+  useSafeGsapCommitMutation,
+} from "./useSafeGsapCommitMutation";
 import type { CommitMutation } from "./gsapScriptCommitTypes";
 
 export interface UseGsapAwareEditingParams {
@@ -35,15 +38,10 @@ export interface UseGsapAwareEditingParams {
     label: string,
   ) => void;
   // DOM fallbacks (from useDomEditCommits)
-  handleDomPathOffsetCommit: (
-    selection: DomEditSelection,
-    next: { x: number; y: number },
-  ) => Promise<void>;
   handleDomBoxSizeCommit: (
     selection: DomEditSelection,
     next: { width: number; height: number },
   ) => Promise<void>;
-  handleDomRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void>;
   // GSAP script commit ops (from useGsapScriptCommits)
   addGsapAnimation: (
     sel: DomEditSelection,
@@ -85,9 +83,7 @@ export function useGsapAwareEditing({
   bumpGsapCache,
   makeFetchFallback,
   trackGsapInteractionFailure,
-  handleDomPathOffsetCommit,
   handleDomBoxSizeCommit,
-  handleDomRotationCommit,
   addGsapAnimation,
   convertToKeyframes,
   setArcPath,
@@ -96,55 +92,42 @@ export function useGsapAwareEditing({
   // ── GSAP-aware geometry commits ──
 
   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);
-      }
-      if (STUDIO_GSAP_DRAG_INTERCEPT_ENABLED && gsapCommitMutation) {
+    async (
+      selection: DomEditSelection,
+      next: { x: number; y: number },
+      modifiers?: { altKey?: boolean },
+    ) => {
+      editLog("manual-drag:move", { id: selection.id, next, altKey: modifiers?.altKey });
+      if (gsapCommitMutation) {
         try {
-          const handled = await tryGsapDragIntercept(
+          await tryGsapDragIntercept(
             selection,
             next,
             selectedGsapAnimations,
             previewIframeRef.current,
             gsapCommitMutation,
             makeFetchFallback(selection),
+            modifiers,
           );
-          if (handled) return;
         } catch (error) {
           trackGsapInteractionFailure(error, selection, "drag", "Move animated layer");
           throw error;
         }
       }
-      return handleDomPathOffsetCommit(selection, next);
     },
     [
-      handleDomPathOffsetCommit,
       selectedGsapAnimations,
       gsapCommitMutation,
       previewIframeRef,
       makeFetchFallback,
       trackGsapInteractionFailure,
-      showToast,
     ],
   );
 
   const handleGsapAwareBoxSizeCommit = useCallback(
     async (selection: DomEditSelection, next: { width: number; height: number }) => {
-      if (STUDIO_GSAP_DRAG_INTERCEPT_ENABLED && gsapCommitMutation) {
+      editLog("manual-drag:resize", { id: selection.id, next });
+      if (gsapCommitMutation) {
         try {
           const handled = await tryGsapResizeIntercept(
             selection,
@@ -174,9 +157,13 @@ export function useGsapAwareEditing({
 
   const handleGsapAwareRotationCommit = useCallback(
     async (selection: DomEditSelection, next: { angle: number }) => {
-      if (STUDIO_GSAP_DRAG_INTERCEPT_ENABLED && gsapCommitMutation) {
+      editLog("manual-drag:rotate", { id: selection.id, next });
+      if (gsapCommitMutation) {
         try {
-          const handled = await tryGsapRotationIntercept(
+          // Single source of truth for rotation too: tryGsapRotationIntercept handles
+          // tweened elements (keyframes) and static ones (a tl.set), so there's no
+          // CSS-var fallback. It returns false only for a selectorless element (no-op).
+          await tryGsapRotationIntercept(
             selection,
             next.angle,
             selectedGsapAnimations,
@@ -184,16 +171,13 @@ export function useGsapAwareEditing({
             gsapCommitMutation,
             makeFetchFallback(selection),
           );
-          if (handled) return;
         } catch (error) {
           trackGsapInteractionFailure(error, selection, "rotation", "Rotate animated layer");
           throw error;
         }
       }
-      return handleDomRotationCommit(selection, next);
     },
     [
-      handleDomRotationCommit,
       selectedGsapAnimations,
       gsapCommitMutation,
       previewIframeRef,
@@ -232,13 +216,27 @@ export function useGsapAwareEditing({
   );
 
   // ── Thin commitMutation facade ──
+  // Routes through the canonical safe wrapper so a server-save failure surfaces a
+  // toast + save telemetry instead of silently reverting — parity with the
+  // arc/keyframe/animation ops that all go through useSafeGsapCommitMutation.
+
+  const noopCommit = useCallback<CommitMutation>(async () => {}, []);
+  const trackGsapSaveFailure = useGsapSaveFailureTelemetry(null);
+  const safeGsapCommit = useSafeGsapCommitMutation(
+    gsapCommitMutation ?? noopCommit,
+    trackGsapSaveFailure,
+    showToast,
+  );
 
   const commitMutation = useCallback(
     async (mutation: Record<string, unknown>, options: { label: string; softReload?: boolean }) => {
       if (!domEditSelection) return;
-      await gsapCommitMutation?.(domEditSelection, mutation, options);
+      // Return (await) the safe-commit chain so consumers that `await
+      // session.commitMutation(...)` (gesture recording, enable-keyframes) run
+      // their post-actions only after the server save has settled.
+      await safeGsapCommit(domEditSelection, mutation, options);
     },
-    [domEditSelection, gsapCommitMutation],
+    [domEditSelection, safeGsapCommit],
   );
 
   // Unroll all computed (helper/loop) tweens in the active timeline into literal