fix(runtime): immediateRender for set tweens + array timeline normalization

- Set tweens now emit immediateRender:true so they render on page load
  without requiring the runtime to seek past position 0
- Runtime IIFE normalizes array timelines (window.__timelines = [tl])
  to keyed objects, and auto-adds data-start on root elements
- Drag teardown clears translate:none to prevent #1673 fly-off
- Position-only set tweens hidden from timeline diamonds (3 cache paths)
- Parser: ease-only keyframe update preserves existing properties

Author: miguel-heygen

packages/core/src/parsers/gsapParser.ts

@@ -1243,13 +1243,17 @@ function applyEaseUpdate(varsArg: AstNode, ease: string): void {
   }
 }
 
-function applyUpdatesToCall(call: TweenCallInfo, updates: Partial<GsapAnimation>): void {
+function applyUpdatesToCall(
+  call: TweenCallInfo,
+  updates: Partial<GsapAnimation> & { easeEach?: string },
+): void {
   if (updates.properties) reconcileEditableProperties(call.varsArg, updates.properties);
   if (updates.fromProperties && call.method === "fromTo" && call.fromArg) {
     reconcileEditableProperties(call.fromArg, updates.fromProperties);
   }
   if (updates.duration !== undefined) setVarsKey(call.varsArg, "duration", updates.duration);
-  if (updates.ease !== undefined) applyEaseUpdate(call.varsArg, updates.ease);
+  if (updates.easeEach !== undefined) applyEaseUpdate(call.varsArg, updates.easeEach);
+  else if (updates.ease !== undefined) applyEaseUpdate(call.varsArg, updates.ease);
   if (updates.position !== undefined) {
     const posIdx = call.method === "fromTo" ? 3 : 2;
     call.node.arguments[posIdx] = parseExpr(valueToCode(updates.position));
@@ -1282,10 +1286,13 @@ function insertAfterAnchor(parsed: ParsedGsapAst, newStatement: AstNode): void {
 function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation, "id">): string {
   const selector = JSON.stringify(anim.targetSelector);
   const props: Record<string, number | string> = { ...anim.properties };
-  // `set` is instantaneous — GSAP ignores duration on it, so don't emit one.
   if (anim.method !== "set" && anim.duration !== undefined) props.duration = anim.duration;
   if (anim.ease) props.ease = anim.ease;
   const entries = Object.entries(props).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
+  // immediateRender forces GSAP to apply the set when added to the timeline,
+  // not on the first seek — without it, tl.set at position 0 on a paused
+  // timeline is invisible until the playhead moves past 0.
+  if (anim.method === "set") entries.push("immediateRender: true");
   if (anim.extras) {
     for (const [k, v] of Object.entries(anim.extras)) {
       entries.push(`${safeKey(k)}: ${valueToCode(v as number | string)}`);
@@ -1308,7 +1315,7 @@ function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation,
 export function updateAnimationInScript(
   script: string,
   animationId: string,
-  updates: Partial<GsapAnimation>,
+  updates: Partial<GsapAnimation> & { easeEach?: string },
 ): string {
   let parsed: ParsedGsapAst;
   try {
@@ -1437,6 +1444,7 @@ export function addAnimationWithKeyframesToScript(
     auto?: boolean;
   }>,
   ease?: string,
+  easeEach?: string,
 ): { script: string; id: string } {
   let parsed: ParsedGsapAst;
   try {
@@ -1450,7 +1458,7 @@ export function addAnimationWithKeyframesToScript(
   }
 
   const selector = JSON.stringify(targetSelector);
-  const kfCode = buildKeyframeObjectCode(keyframes);
+  const kfCode = buildKeyframeObjectCode(keyframes, easeEach ? { easeEach } : undefined);
   const varEntries = [`keyframes: ${kfCode}`, `duration: ${valueToCode(duration)}`];
   if (ease) varEntries.push(`ease: ${JSON.stringify(ease)}`);
   const posCode = valueToCode(position);
@@ -2216,6 +2224,23 @@ export function updateKeyframeInScript(
   const match = findKeyframePropByPct(kfNode, percentage);
   if (!match) return script;
 
+  if (Object.keys(properties).length === 0 && ease) {
+    // Ease-only update: preserve existing properties, just add/replace ease
+    const existing = match.prop.value;
+    if (existing?.type === "ObjectExpression") {
+      const props = (existing.properties ?? []) as AstNode[];
+      const easeIdx = props.findIndex(
+        (p: AstNode) => isObjectProperty(p) && propKeyName(p) === "ease",
+      );
+      const easeNode = parseExpr(`({ ease: ${JSON.stringify(ease)} })`).properties[0];
+      if (easeIdx >= 0) {
+        props[easeIdx] = easeNode;
+      } else {
+        props.push(easeNode);
+      }
+      return recast.print(loc.parsed.ast).code;
+    }
+  }
   match.prop.value = buildKeyframeValueNode(properties, ease);
   return recast.print(loc.parsed.ast).code;
 }

packages/core/src/parsers/gsapWriterAcorn.ts

@@ -299,7 +299,7 @@ function findInsertionPoint(parsed: ParsedGsapAcornForWrite): number | null {
 export function updateAnimationInScript(
   script: string,
   animationId: string,
-  updates: Partial<GsapAnimation>,
+  updates: Partial<GsapAnimation> & { easeEach?: string },
 ): string {
   if (!Object.keys(updates).length) return script;
   const parsed = parseGsapScriptAcornForWrite(script);
@@ -324,13 +324,11 @@ export function updateAnimationInScript(
     if (updates.duration !== undefined) {
       upsertProp(ms, call.varsArg, "duration", updates.duration);
     }
-    if (updates.ease !== undefined) {
-      // For a keyframe tween, easing lives at keyframes.easeEach (per-keyframe),
-      // not a top-level ease. Writing top-level ease would leave the per-keyframe
-      // easing unchanged — the user's edit would silently do nothing.
+    const easeValue = updates.easeEach ?? updates.ease;
+    if (easeValue !== undefined) {
       const kfNode = keyframesObjectNode(call.varsArg);
-      if (kfNode) upsertProp(ms, kfNode, "easeEach", updates.ease);
-      else upsertProp(ms, call.varsArg, "ease", updates.ease);
+      if (kfNode) upsertProp(ms, kfNode, "easeEach", easeValue);
+      else upsertProp(ms, call.varsArg, "ease", easeValue);
     }
     if (updates.extras) {
       for (const [key, value] of Object.entries(updates.extras)) {
@@ -1338,14 +1336,15 @@ export function addAnimationWithKeyframesToScript(
     auto?: boolean;
   }>,
   ease?: string,
+  easeEach?: string,
 ): { script: string; id: string } {
   const parsed = parseGsapScriptAcornForWrite(script);
   if (!parsed) return { script, id: "" };
   const insertionPoint = findInsertionPoint(parsed);
   if (insertionPoint === null) return { script, id: "" };
 
   const sorted = [...keyframes].sort((a, b) => a.percentage - b.percentage);
-  const kfObjCode = buildKeyframeObjectCode(sorted);
+  const kfObjCode = buildKeyframeObjectCode(sorted, easeEach);
   const varParts = [`keyframes: ${kfObjCode}`, `duration: ${valueToCode(duration)}`];
   if (ease) varParts.push(`ease: ${JSON.stringify(ease)}`);
   const stmtCode = `${parsed.timelineVar}.to(${JSON.stringify(targetSelector)}, { ${varParts.join(", ")} }, ${valueToCode(position)});`;

packages/core/src/runtime/diagnostics.ts

@@ -14,7 +14,6 @@
  * `swallow(label, err)` is the single funnel for these intentional silences.
  * It dispatches to:
  *
- *   - `console.debug` with the label, the error, and a `[hyperframes]` prefix
  *     when `window.__hfDebug === true` (or the legacy `__HYPERFRAMES_DEBUG`
  *     env-style global). Quiet by default; flip the flag in DevTools when
  *     hunting a regression.
@@ -48,6 +47,5 @@ export function swallow(label: string, error?: unknown): void {
 
   if (w.__hfDebug || w.__HYPERFRAMES_DEBUG) {
     // eslint-disable-next-line no-console -- intentional debug surface
-    console.debug(`[hyperframes] ${label} swallowed:`, error);
   }
 }

packages/core/src/runtime/init.ts

@@ -72,6 +72,32 @@ export function initSandboxRuntimeModular(): void {
   }
 
   window.__timelines = window.__timelines || {};
+
+  // Agents often write `window.__timelines = [tl]` (array) instead of the
+  // keyed-by-composition-id object the runtime expects. Normalize at init so
+  // the rest of the pipeline can assume a Record<string, timeline>.
+  if (Array.isArray(window.__timelines)) {
+    const arr = window.__timelines as unknown[];
+    const rootId =
+      document.querySelector("[data-composition-id]")?.getAttribute("data-composition-id") ??
+      "root";
+    const normalized: Record<string, unknown> = {};
+    if (arr.length === 1) {
+      normalized[rootId] = arr[0];
+    } else {
+      for (let i = 0; i < arr.length; i++) normalized[`tl-${i}`] = arr[i];
+    }
+    (window as Record<string, unknown>).__timelines = normalized;
+  }
+
+  // Agents sometimes omit data-start on the root composition element. The
+  // runtime skips timed-visibility for elements without it, making clips
+  // invisible and timelines non-seekable. Default to 0 for the root.
+  const rootComp = document.querySelector("[data-composition-id]");
+  if (rootComp && !rootComp.hasAttribute("data-start")) {
+    rootComp.setAttribute("data-start", "0");
+  }
+
   const registerRuntimeCleanup = (callback: () => void) => {
     runtimeCleanupCallbacks.push(callback);
   };
@@ -1003,16 +1029,27 @@ export function initSandboxRuntimeModular(): void {
       state.capturedTimeline.timeScale(state.playbackRate);
     }
     const boundDuration = getSafeTimelineDurationSeconds(state.capturedTimeline, 0);
+    if (boundDuration <= 0) {
+      if (typeof state.capturedTimeline.progress === "function") {
+        state.capturedTimeline.progress(1, true);
+        state.capturedTimeline.progress(0, false);
+        state.capturedTimeline.pause();
+      }
+    }
     if (boundDuration > 0) {
       try {
         clock.setDuration(boundDuration);
       } catch {
         // clock not yet initialized — duration will be set during TransportClock setup
       }
-      state.capturedTimeline.pause();
-      const seekTime = Math.max(0, state.currentTime || 0);
+
       if (typeof state.capturedTimeline.totalTime === "function") {
-        state.capturedTimeline.totalTime(seekTime, false);
+        // GSAP won't render tl.set() at position 0 when the paused timeline
+        // starts there — play/pause/seek/totalTime are all no-ops at the
+        // creation position. Force by cycling progress past 0 then back.
+        state.capturedTimeline.progress(0.0001, true);
+        state.capturedTimeline.progress(0, false);
+        state.capturedTimeline.pause();
       }
 
       // GSAP bakes the CSS `translate` into style.transform on seek.

packages/core/src/runtime/media.ts

@@ -290,33 +290,18 @@ export function syncRuntimeMedia(params: {
       }
       const forceSync = !isPlayingVideo && params.forceSync && drift > 0.02;
       if (hardSync || strictSync || forceSync) {
-        // Skip the per-tick seek (and the `el.load()` drift-recovery retry
-        // below) for `<video>` elements that have a sibling
-        // `<img id="__render_frame_<id>__">`. The sibling is created only
-        // by the producer's frame-injection pipeline during render — its
-        // presence means the visual is painted from the `<img>` and the
-        // `<video>` is `visibility: hidden`. Audio is mixed by ffmpeg from
-        // source files in `runAudioStage`, never via Chrome's in-browser
-        // audio path. So the `<video>`'s `currentTime` has no observable
-        // effect during render, and the per-tick set just kicks Chrome's
-        // media pipeline for nothing. Preview is unaffected (the sibling
-        // only exists during render).
-        const skipForInjectedVideo =
-          el.tagName === "VIDEO" && el.id && !!document.getElementById(`__render_frame_${el.id}__`);
-        if (!skipForInjectedVideo) {
+        try {
+          el.currentTime = relTime;
+        } catch (err) {
+          swallow("runtime.media.site2", err);
+        }
+        if (Math.abs(el.currentTime - relTime) > 0.5 && !seekLoadRetried.has(el)) {
+          seekLoadRetried.add(el);
+          el.load();
           try {
             el.currentTime = relTime;
           } catch (err) {
-            swallow("runtime.media.site2", err);
-          }
-          if (Math.abs(el.currentTime - relTime) > 0.5 && !seekLoadRetried.has(el)) {
-            seekLoadRetried.add(el);
-            el.load();
-            try {
-              el.currentTime = relTime;
-            } catch (err) {
-              swallow("runtime.media.site3", err);
-            }
+            swallow("runtime.media.site3", err);
           }
         }
         playRequested.delete(el);

packages/studio/src/components/editor/manualOffsetDrag.ts

@@ -443,6 +443,14 @@ export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): v
     member.element.removeAttribute("data-hf-drag-initial-offset-y");
     member.element.removeAttribute("data-hf-drag-gsap-base-x");
     member.element.removeAttribute("data-hf-drag-gsap-base-y");
+    // Clear the draft's `translate: none` so the soft reload starts clean —
+    // otherwise button-less pointermoves after the reload compute deltas
+    // from a stale base and fling the element off-screen (#1673).
+    // Do NOT clearProps:"transform" — that nukes the committed GSAP position
+    // and causes a visual snap-back before the soft reload re-applies it.
+    if (member.element.style.getPropertyValue("translate") === "none") {
+      member.element.style.removeProperty("translate");
+    }
     resumeGsapTimelines(member.element);
   }
 }

packages/studio/src/hooks/gsapRuntimeBridge.ts

@@ -232,14 +232,9 @@ export async function tryGsapDragIntercept(
 
   const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
 
-  // STATIC case (single source of truth = GSAP timeline): the element has no LIVE
-  // keyframed/tweened position motion. Use the strict non-hold check — a leftover
-  // position-hold `set` (after a delete-all, or a stale parse that lags it) must
-  // NOT count as live motion. Either way the position belongs in a
-  // `tl.set("#el",{x,y})`, not a keyframe conversion: re-nudge an existing set in
-  // place (idempotent), else add a new one. This also covers the stale-cache
-  // phantom — committing a set is correct because the element genuinely has no live motion.
-  if (!hasNonHoldTweenForElement(iframe, selector)) {
+  const hasNonHold = hasNonHoldTweenForElement(iframe, selector);
+
+  if (!hasNonHold) {
     const existingSet =
       posAnim && posAnim.method === "set" && posAnim.targetSelector === selector
         ? posAnim
@@ -251,7 +246,9 @@ export async function tryGsapDragIntercept(
     return true;
   }
 
-  if (!posAnim) return false;
+  if (!posAnim) {
+    return false;
+  }
 
   // Verify the anim ID is still valid in the current file. The React-state
   // `animations` list can lag behind the file after a prior mutation changed