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/lint/rules/gsap.ts

@@ -867,4 +867,33 @@ export const gsapRules: LintRule<LintContext>[] = [
     }
     return findings;
   },
+
+  // gsap_group_selector_keyframes
+  ({ scripts }) => {
+    const findings: HyperframeLintFinding[] = [];
+    for (const script of scripts) {
+      const content = stripJsComments(script.content);
+      const pattern = /\.(?:to|from|fromTo)\(\s*["']([^"']+,\s*[^"']+)["']\s*,\s*\{[^}]*keyframes/g;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(content)) !== null) {
+        const selector = match[1]!;
+        const count = selector.split(",").length;
+        const contextStart = Math.max(0, match.index - 20);
+        const contextEnd = Math.min(content.length, match.index + match[0].length + 40);
+        findings.push({
+          code: "gsap_group_selector_keyframes",
+          severity: "warning",
+          message:
+            `GSAP tween targets ${count} elements with shared keyframes ("${truncateSnippet(selector, 60)}"). ` +
+            `Editing one element's keyframes in Studio will affect all ${count} elements. ` +
+            `Split into individual tweens for per-element keyframe control.`,
+          fixHint:
+            `Replace the group selector with individual tl.to() calls per element, ` +
+            `each with their own keyframes object.`,
+          snippet: truncateSnippet(content.slice(contextStart, contextEnd)),
+        });
+      }
+    }
+    return findings;
+  },
 ];

packages/core/src/parsers/gsapParser.ts

@@ -1623,18 +1623,18 @@ export function removeAllKeyframesFromScript(script: string, animationId: string
   const kfNode = findKeyframesObjectNode(loc.target.call.varsArg);
   if (!kfNode) return script;
 
-  // Collect all percentage keyframe entries, sorted
   const kfEntries = filterPercentageProps(kfNode)
     .map((p: any) => ({ pct: percentageFromKey(propKeyName(p)!), prop: p }))
     .filter((e) => !Number.isNaN(e.pct))
     .sort((a, b) => a.pct - b.pct);
   if (kfEntries.length === 0) return script;
 
-  const lastRecord = objectExpressionToRecord(
-    kfEntries[kfEntries.length - 1]!.prop.value,
-    loc.parsed.scope,
-  );
-  collapseKeyframesToFlat(loc.target.call.varsArg, lastRecord);
+  // For to()/set(): collapse to last keyframe (the destination = visible state).
+  // For from(): collapse to first keyframe (the starting state).
+  const method = loc.target.call.method;
+  const collapseEntry = method === "from" ? kfEntries[0]! : kfEntries[kfEntries.length - 1]!;
+  const record = objectExpressionToRecord(collapseEntry.prop.value, loc.parsed.scope);
+  collapseKeyframesToFlat(loc.target.call.varsArg, record);
 
   return recast.print(loc.parsed.ast).code;
 }

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),
@@ -330,7 +333,11 @@ export function StudioApp() {
   });
 
   const compositionDimensions = useCompositionDimensions();
-  const { lintModal, linting, handleLint, closeLintModal } = useLintModal(projectId);
+  const { lintModal, linting, handleLint, closeLintModal, findingsByElement, findingsByFile } =
+    useLintModal(projectId, refreshKey);
+  useEffect(() => {
+    usePlayerStore.getState().setLintFindingsByElement(findingsByElement);
+  }, [findingsByElement]);
   const frameCapture = useFrameCapture({
     projectId,
     activeCompPath,
@@ -482,6 +489,8 @@ export function StudioApp() {
                   onPreviewBlock={setBlockPreview}
                   onLint={handleLint}
                   linting={linting}
+                  lintFindingCount={lintModal?.length ?? findingsByFile.size}
+                  lintFindingsByFile={findingsByFile}
                 />
                 <StudioPreviewArea
                   timelineToolbar={timelineToolbar}
@@ -529,7 +538,7 @@ export function StudioApp() {
                     }}
                     recordingState={gestureState}
                     recordingDuration={gestureRecording.recordingDuration}
-                    onToggleRecording={handleToggleRecording}
+                    onToggleRecording={STUDIO_KEYFRAMES_ENABLED ? handleToggleRecording : undefined}
                   />
                 )}
               </div>

packages/studio/src/components/StudioLeftSidebar.tsx

@@ -16,6 +16,8 @@ export interface StudioLeftSidebarProps {
   onPreviewBlock?: (preview: BlockPreviewInfo | null) => void;
   onLint: () => void;
   linting: boolean;
+  lintFindingCount?: number;
+  lintFindingsByFile?: Map<string, { count: number; messages: string[] }>;
 }
 
 // fallow-ignore-next-line complexity
@@ -26,6 +28,8 @@ export function StudioLeftSidebar({
   onPreviewBlock,
   onLint,
   linting,
+  lintFindingCount,
+  lintFindingsByFile,
 }: StudioLeftSidebarProps) {
   const {
     leftCollapsed,
@@ -129,6 +133,8 @@ export function StudioLeftSidebar({
         isRendering={renderQueue.isRendering}
         onLint={onLint}
         linting={linting}
+        lintFindingCount={lintFindingCount}
+        lintFindingsByFile={lintFindingsByFile}
         onToggleCollapse={toggleLeftSidebar}
         onAddBlock={onAddBlock}
         onPreviewBlock={onPreviewBlock}

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,26 @@ 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" : "Auto-keyframe OFF"}>
+      <button
+        type="button"
+        onClick={() => usePlayerStore.getState().setAutoKeyframeEnabled(!enabled)}
+        className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
+          enabled ? "text-red-400" : "text-neutral-600 hover:text-neutral-400"
+        }`}
+      >
+        <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+          <circle cx="7" cy="7" r="5" stroke="currentColor" strokeWidth="1.5" />
+          {enabled && <circle cx="7" cy="7" r="3" fill="currentColor" />}
+        </svg>
+      </button>
+    </Tooltip>
+  );
+}
+
 interface DomEditSessionSlice extends EnableKeyframesSession {
   domEditSelection: DomEditSelection | null;
   selectedGsapAnimations: GsapAnimation[];
@@ -74,40 +94,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 &&
             (() => {