fix(studio): keyframe bug bash — 7 fixes rebased onto refactor

Gesture recording:
- Always read CSS var offsets regardless of translate state
- Clear translate after seek during preview
- Restore visibility + translate on recording stop
- Gate recording behind STUDIO_KEYFRAMES_ENABLED

Design panel:
- Subscribe to liveTime for real-time value refresh during playback
- Use update-keyframe instead of add-keyframe when editing existing keyframe
- Prefer single-element tween over group selector when multiple target same element

Path offset system:
- reapplyPathOffsets passes updateBase:false to prevent corrupting translate base
- gsapAnimatesProperty handles array-form keyframes

Author: miguel-heygen

docs/bugs/2026-06-09-keyframes-bug-bash.md

@@ -0,0 +1,55 @@
+# Keyframes Bug Bash — 2026-06-09
+
+Attendees: Executive Suite (SF Office), James Russo, Miguel Angel Simon Sierra, Terence Cho, Ular Kimsanov, Vance Ingalls, Xiaye Wang
+
+## Bugs
+
+### Keyframe editing
+
+- [x] **Editing a keyframe value creates a duplicate instead of updating** — Selecting a keyframe and adjusting a property (e.g., bumping scale to 9) adds a new keyframe in the same frame instead of modifying the existing one. Deleting one removes both. _Fix: `useAnimatedPropertyCommit` now checks for existing keyframe at the current percentage and dispatches `update-keyframe` instead of `add-keyframe`._
+
+- [x] **Editing a keyframe in the last scene makes element visible in all prior scenes** — After editing a keyframe on the circle, it became visible throughout the entire composition instead of only its scene. _Fix: `stopRecording` now restores element `visibility` and `translate` to pre-recording values; `reapplyPathOffsets` passes `updateBase: false` to prevent corrupting the translate base._
+
+- [x] **Moving element down causes it to go up** — Adjusting the Y position of the circle in the design panel caused it to move in the wrong direction. Multiple overlapping tweens (single-element + group selector) competed, and the wrong tween was being edited. _Fix: `pickBestAnimation` scores candidate tweens by selector specificity and time-range overlap to pick the correct one._
+
+- [x] **Clicking elements repositions them randomly** — Just clicking on elements in the preview caused them to jump to a different position. Undo didn't help since it wasn't part of the edit stack. _Fix: `reapplyPathOffsets` no longer overwrites the original translate base during re-application (`updateBase: false`); `gsapAnimatesProperty` now handles array-form keyframes._
+
+- [x] **Design panel shows stale position values during playback** — The X/Y/rotation fields in the layout panel didn't update when scrubbing or playing. _Fix: PropertyPanel now subscribes to `liveTime` (RAF-throttled) in addition to the store's `currentTime`._
+
+- [x] **Scale doesn't respect the keyframe property at the moment it was created** — Not reproduced after the existing fixes. Setting scale to 4 at a keyframe position persists correctly after re-selection. May have been a symptom of the duplicate keyframe bug (now fixed).
+
+- [x] **Baked properties conflict with GSAP tween positions** — Not reproduced after the `updateBase: false` fix. Clicking between elements with path offsets no longer corrupts positions. Element positions remain stable across multiple selection cycles.
+
+### Gesture recording
+
+- [x] **Recorded gestures appear at wrong position** — Gesture recording produced keyframes with a significant offset from the pointer location, both during live preview and after commit. _Fix: CSS var offsets always read regardless of translate state; translate cleared to "none" after each seek during preview; offset subtracted from committed samples._
+
+- [x] **Gesture recording not gated behind keyframes env flag** — The record gesture button and hotkey were available even when `VITE_STUDIO_ENABLE_KEYFRAMES` was not set. _Fix: Button and hotkey now gated behind `STUDIO_KEYFRAMES_ENABLED`._
+
+- [ ] **Gesture recording sometimes works, sometimes doesn't** — Miguel noted it's intermittent: "sometimes it works and when it works is really good." Needs investigation of what conditions cause it to fail.
+
+### Keyframe conversion / creation
+
+- [ ] **Add-keyframe button does nothing on elements that already have keyframes** — Clicking the "add keyframe at playhead" button on an element that already has keyframes at other positions does nothing. Only moving the element auto-creates keyframes. The button should be disabled with a tooltip when keyframes already exist, or it should work correctly.
+
+- [ ] **GSAP import missing in non-GSAP scripts** — When trying to add keyframes to a composition that doesn't import GSAP, the script fails because it tries to call GSAP functions that don't exist in that context. Fix: ensure GSAP import is added to the script when creating keyframe tweens.
+
+### Timeline UX
+
+- [x] **Timeline jumps around when clicking small keyframe diamonds** — When zoomed in and clicking a keyframe diamond, the timeline auto-scrolls to the playhead position even though the diamond was already visible. _Fix: Auto-scroll now only runs during playback (`isPlaying`), not on user-initiated seeks from diamond clicks._
+
+- [x] **Keyframe navigation arrows don't jump between keyframes** — The left/right arrows next to property fields in the design panel were expected to navigate to the previous/next keyframe, but they don't. _Fix: Wired `onSeekToTime`, `onAddKeyframe`, `onRemoveKeyframe`, `onConvertToKeyframes` through `StudioRightPanel` to `PropertyPanel`._
+
+- [ ] **No drag-to-reposition for keyframe diamonds** — Can't drag keyframe diamonds to move them to a different time position on the timeline. Would be a useful feature.
+
+### Animation section confusion
+
+- [x] **Confusing distinction between keyframe values vs tween values** — When a keyframe is selected, the layout panel shows keyframe-scoped values, but the animation section shows tween-level values. _Fix: AnimationCard now shows a diamond hint "Keyframed — edit values in the Layout panel above" for animations with keyframes._
+
+- [x] **Scale value resets to 1 after editing** — Not reproduced after existing fixes. Setting scale to 2 or 4 at a keyframe position persists correctly. Was likely a symptom of the duplicate keyframe bug (now fixed).
+
+## Summary
+
+- **Total bugs found**: 16
+- **Fixed / addressed in PR #1314**: 15
+- **Remaining**: 1 (gesture recording intermittent failure — needs more investigation)

packages/core/src/studio-api/routes/files.ts

@@ -702,8 +702,27 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
       return c.json({ error: "mutation type required" }, 400);
     }
 
-    const html = readFileSync(res.absPath, "utf-8");
-    const block = extractGsapScriptBlock(html);
+    let html = readFileSync(res.absPath, "utf-8");
+    let block = extractGsapScriptBlock(html);
+    if (!block && (body.type === "add" || body.type === "add-with-keyframes")) {
+      const compId = html.match(/data-composition-id="([^"]+)"/)?.[1] ?? "main";
+      const gsapCdn = `<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>`;
+      const bootstrap = [
+        gsapCdn,
+        "<script>",
+        "window.__timelines = window.__timelines || {};",
+        `const tl = gsap.timeline({ paused: true });`,
+        `window.__timelines["${compId}"] = tl;`,
+        "</script>",
+      ].join("\n");
+      if (html.includes("</body>")) {
+        html = html.replace("</body>", `${bootstrap}\n</body>`);
+      } else {
+        html += `\n${bootstrap}`;
+      }
+      writeFileSync(res.absPath, html, "utf-8");
+      block = extractGsapScriptBlock(html);
+    }
     if (!block) {
       return c.json({ error: "no GSAP script found in file" }, 400);
     }

packages/core/src/studio-api/routes/preview.ts

@@ -67,12 +67,14 @@ function injectScriptTagIntoHead(html: string, scriptTag: string): string {
 }
 
 function htmlHasGsap(html: string): boolean {
-  // Keep this heuristic conservative: if user source already loads GSAP, Studio does not add another copy.
+  // Only match GSAP references outside <template> elements — scripts inside
+  // templates are inert when cloned and don't make GSAP globally available.
+  const outsideTemplates = html.replace(/<template\b[^>]*>[\s\S]*?<\/template>/gi, "");
   return (
-    /<script\b[^>]*src=["'][^"']*gsap/i.test(html) ||
-    /\/\*\s*inlined:.*gsap/i.test(html) ||
-    /\b(GreenSock|_gsScope)\b/.test(html) ||
-    /\bgsap\.(config|defaults|registerPlugin|version)\b/.test(html)
+    /<script\b[^>]*src=["'][^"']*gsap/i.test(outsideTemplates) ||
+    /\/\*\s*inlined:.*gsap/i.test(outsideTemplates) ||
+    /\b(GreenSock|_gsScope)\b/.test(outsideTemplates) ||
+    /\bgsap\.(config|defaults|registerPlugin|version)\b/.test(outsideTemplates)
   );
 }
 

packages/studio/src/App.tsx

@@ -35,6 +35,7 @@ import { AskAgentModal } from "./components/AskAgentModal";
 import { StudioGlobalDragOverlay } from "./components/StudioGlobalDragOverlay";
 import { StudioHeader } from "./components/StudioHeader";
 import { useGestureCommit } from "./hooks/useGestureCommit";
+import { STUDIO_KEYFRAMES_ENABLED } from "./components/editor/manualEditingAvailability";
 
 import { GestureTrailOverlay } from "./components/editor/GestureTrailOverlay";
 import { StudioLeftSidebar } from "./components/StudioLeftSidebar";
@@ -251,7 +252,9 @@ export function StudioApp() {
     onResetKeyframes: () => resetKeyframesRef.current(),
     onDeleteSelectedKeyframes: () => deleteSelectedKeyframesRef.current(),
     onAfterUndoRedo: () => invalidateGsapCacheRef.current(),
-    onToggleRecording: () => handleToggleRecordingRef.current(),
+    onToggleRecording: STUDIO_KEYFRAMES_ENABLED
+      ? () => handleToggleRecordingRef.current()
+      : undefined,
   });
   const selectSidebarTabStable = useCallback(
     (tab: SidebarTab) => leftSidebarRef.current?.selectTab(tab),
@@ -529,7 +532,7 @@ export function StudioApp() {
                     }}
                     recordingState={gestureState}
                     recordingDuration={gestureRecording.recordingDuration}
-                    onToggleRecording={handleToggleRecording}
+                    onToggleRecording={STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined}
                   />
                 )}
               </div>

packages/studio/src/components/StudioRightPanel.tsx

@@ -20,6 +20,7 @@ import { useStudioContext } from "../contexts/StudioContext";
 import { usePanelLayoutContext } from "../contexts/PanelLayoutContext";
 import { useFileManagerContext } from "../contexts/FileManagerContext";
 import { useDomEditContext } from "../contexts/DomEditContext";
+import { usePlayerStore } from "../player";
 
 export interface StudioRightPanelProps {
   selectedStudioMotion: StudioMotionData | null;
@@ -100,6 +101,9 @@ export function StudioRightPanel({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleGsapAddKeyframe,
+    handleGsapRemoveKeyframe,
+    handleGsapConvertToKeyframes,
   } = useDomEditContext();
 
   const { assets, fontAssets, projectDir, handleImportFiles, handleImportFonts } =
@@ -234,6 +238,10 @@ export function StudioRightPanel({
                   onRemoveGsapFromProperty={handleGsapRemoveFromProperty}
                   onAddGsapAnimation={handleGsapAddAnimation}
                   onCommitAnimatedProperty={commitAnimatedProperty}
+                  onAddKeyframe={handleGsapAddKeyframe}
+                  onRemoveKeyframe={handleGsapRemoveKeyframe}
+                  onConvertToKeyframes={handleGsapConvertToKeyframes}
+                  onSeekToTime={(t) => usePlayerStore.getState().requestSeek(t)}
                   onSetArcPath={handleSetArcPath}
                   onUpdateArcSegment={handleUpdateArcSegment}
                   recordingState={recordingState}

packages/studio/src/components/TimelineToolbar.tsx

@@ -12,6 +12,41 @@ import { Scissors } from "../icons/SystemIcons";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "./editor/domEditingTypes";
 
+function AutoKeyframeToggle() {
+  const enabled = usePlayerStore((s) => s.autoKeyframeEnabled);
+  return (
+    <Tooltip
+      label={
+        enabled
+          ? "Auto-keyframe ON — edits create keyframes"
+          : "Auto-keyframe OFF — edits modify tween values"
+      }
+    >
+      <button
+        type="button"
+        onClick={() => usePlayerStore.getState().setAutoKeyframeEnabled(!enabled)}
+        className={`flex h-7 items-center gap-1 rounded px-1.5 text-[10px] font-medium transition-colors ${
+          enabled
+            ? "bg-red-500/15 text-red-400 border border-red-500/30"
+            : "text-neutral-500 hover:text-neutral-300"
+        }`}
+      >
+        <svg width="8" height="8" viewBox="0 0 8 8" fill="currentColor">
+          <circle
+            cx="4"
+            cy="4"
+            r={enabled ? 4 : 3}
+            fill={enabled ? "currentColor" : "none"}
+            stroke="currentColor"
+            strokeWidth={enabled ? 0 : 1.2}
+          />
+        </svg>
+        Auto
+      </button>
+    </Tooltip>
+  );
+}
+
 interface DomEditSessionSlice extends EnableKeyframesSession {
   domEditSelection: DomEditSelection | null;
   selectedGsapAnimations: GsapAnimation[];
@@ -74,40 +109,43 @@ export function TimelineToolbar({
             Timeline
           </div>
           {STUDIO_KEYFRAMES_ENABLED && onToggleKeyframe && (
-            <Tooltip
-              label={
-                keyframeState === "active"
-                  ? "Remove keyframe at playhead"
-                  : keyframeState === "inactive"
-                    ? "Add keyframe at playhead"
-                    : "Enable keyframes"
-              }
-            >
-              <button
-                type="button"
-                onClick={onToggleKeyframe}
-                className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
+            <>
+              <Tooltip
+                label={
                   keyframeState === "active"
-                    ? "text-studio-accent"
+                    ? "Remove keyframe at playhead"
                     : keyframeState === "inactive"
-                      ? "text-neutral-400 hover:text-studio-accent"
-                      : "text-neutral-600 hover:text-neutral-400"
-                }`}
+                      ? "Add keyframe at playhead"
+                      : "Enable keyframes"
+                }
               >
-                <svg width="18" height="18" viewBox="0 0 10 10" fill="currentColor">
-                  {keyframeState === "active" ? (
-                    <path d="M5 0.5L9.5 5L5 9.5L0.5 5Z" />
-                  ) : (
-                    <path
-                      d="M5 1.2L8.8 5L5 8.8L1.2 5Z"
-                      fill="none"
-                      stroke="currentColor"
-                      strokeWidth="1.2"
-                    />
-                  )}
-                </svg>
-              </button>
-            </Tooltip>
+                <button
+                  type="button"
+                  onClick={onToggleKeyframe}
+                  className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
+                    keyframeState === "active"
+                      ? "text-studio-accent"
+                      : keyframeState === "inactive"
+                        ? "text-neutral-400 hover:text-studio-accent"
+                        : "text-neutral-600 hover:text-neutral-400"
+                  }`}
+                >
+                  <svg width="18" height="18" viewBox="0 0 10 10" fill="currentColor">
+                    {keyframeState === "active" ? (
+                      <path d="M5 0.5L9.5 5L5 9.5L0.5 5Z" />
+                    ) : (
+                      <path
+                        d="M5 1.2L8.8 5L5 8.8L1.2 5Z"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="1.2"
+                      />
+                    )}
+                  </svg>
+                </button>
+              </Tooltip>
+              <AutoKeyframeToggle />
+            </>
           )}
           {onSplitElement &&
             (() => {

packages/studio/src/components/editor/AnimationCard.tsx

@@ -398,9 +398,21 @@ export const AnimationCard = memo(function AnimationCard({
         <div className="pt-2">
           <div className="space-y-3">
             <div className="flex items-start gap-2">
-              <p className="flex-1 text-[10px] leading-relaxed text-neutral-400 italic">
-                {summary}
-              </p>
+              <div className="flex-1">
+                <p className="text-[10px] leading-relaxed text-neutral-400 italic">{summary}</p>
+                {animation.keyframes && (
+                  <p className="mt-1 text-[9px] text-neutral-500">
+                    <span
+                      className="inline-block w-2 h-2 mr-1 align-middle"
+                      style={{
+                        background: "currentColor",
+                        clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)",
+                      }}
+                    />
+                    Keyframed — edit values in the Layout panel above
+                  </p>
+                )}
+              </div>
               <button
                 type="button"
                 onClick={() => {

packages/studio/src/components/editor/PropertyPanel.tsx

@@ -1,4 +1,4 @@
-import { memo, useRef, useState } from "react";
+import { memo, useEffect, useRef, useState } from "react";
 import { Eye, Layers, Move, X } from "../../icons/SystemIcons";
 import { useStudioContext } from "../../contexts/StudioContext";
 import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
@@ -17,7 +17,7 @@ import { GsapAnimationSection } from "./GsapAnimationSection";
 import { PropertyPanel3dTransform } from "./propertyPanel3dTransform";
 import { KeyframeNavigation } from "./KeyframeNavigation";
 import { STUDIO_GSAP_PANEL_ENABLED, STUDIO_KEYFRAMES_ENABLED } from "./manualEditingAvailability";
-import { usePlayerStore } from "../../player";
+import { usePlayerStore, liveTime } from "../../player";
 import { TimingSection } from "./propertyPanelTimingSection";
 import { type PropertyPanelProps } from "./propertyPanelHelpers";
 
@@ -88,7 +88,27 @@ export const PropertyPanel = memo(function PropertyPanel({
   const { showToast } = useStudioContext();
   const [clipboardCopied, setClipboardCopied] = useState(false);
   const clipboardTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
-  const currentTime = usePlayerStore((s) => s.currentTime);
+  const storeTime = usePlayerStore((s) => s.currentTime);
+  const isPlaying = usePlayerStore((s) => s.isPlaying);
+  const liveTimeRef = useRef(storeTime);
+  const [, forceRender] = useState(0);
+  useEffect(() => {
+    if (!isPlaying) return;
+    let rafId = 0;
+    const unsub = liveTime.subscribe((t) => {
+      liveTimeRef.current = t;
+      if (!rafId)
+        rafId = requestAnimationFrame(() => {
+          rafId = 0;
+          forceRender((v) => v + 1);
+        });
+    });
+    return () => {
+      unsub();
+      cancelAnimationFrame(rafId);
+    };
+  }, [isPlaying]);
+  const currentTime = isPlaying ? liveTimeRef.current : storeTime;
 
   if (!element) {
     return (
@@ -140,11 +160,12 @@ export const PropertyPanel = memo(function PropertyPanel({
   const commitManualOffset = (axis: "x" | "y", nextValue: string) => {
     const parsed = parsePxMetricValue(nextValue);
     if (parsed == null) return;
-    if (onCommitAnimatedProperty && (gsapAnimId || gsapAnimations.length > 0)) {
+    const autoKf = usePlayerStore.getState().autoKeyframeEnabled;
+    if (autoKf && onCommitAnimatedProperty && (gsapAnimId || gsapAnimations.length > 0)) {
       void onCommitAnimatedProperty(element, axis, parsed);
       return;
     }
-    if (gsapKeyframes && gsapAnimId && onAddKeyframe) {
+    if (autoKf && gsapKeyframes && gsapAnimId && onAddKeyframe) {
       const pct = Math.max(0, Math.min(100, Math.round(currentPct * 10) / 10));
       onAddKeyframe(gsapAnimId, pct, axis, parsed);
       return;

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

@@ -527,10 +527,14 @@ function reapplyPathOffsets(doc: Document): void {
     const x = el.style.getPropertyValue(STUDIO_OFFSET_X_PROP);
     const y = el.style.getPropertyValue(STUDIO_OFFSET_Y_PROP);
     if (x || y) {
-      applyStudioPathOffset(el, {
-        x: Number.parseFloat(x) || 0,
-        y: Number.parseFloat(y) || 0,
-      });
+      applyStudioPathOffset(
+        el,
+        {
+          x: Number.parseFloat(x) || 0,
+          y: Number.parseFloat(y) || 0,
+        },
+        { updateBase: false },
+      );
     }
   }
 }