feat(studio): consolidate timeline editor callbacks

packages/studio/src/App.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback, useRef, useMemo, useEffect, useLayoutEffect } from "react";
 import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
-import { usePlayerStore, type TimelineElement } from "./player";
+import { usePlayerStore } from "./player";
 import { StudioOverlays } from "./components/StudioOverlays";
 import { SaveQueuePausedBanner } from "./components/SaveQueuePausedBanner";
 import { useCaptionStore } from "./captions/store";
@@ -12,9 +12,12 @@ import { useFileManager } from "./hooks/useFileManager";
 import { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 import { usePreviewDocumentVersion } from "./hooks/usePreviewDocumentVersion";
 import { useTimelineEditing } from "./hooks/useTimelineEditing";
-import { persistTimelineMoveEditsAtomically } from "./hooks/timelineMoveAdapter";
+import {
+  persistTimelineMoveEditsAtomically,
+  type TimelineMoveEditsHandler,
+  type TimelineMoveOperation,
+} from "./hooks/timelineMoveAdapter";
 import type { TimelineZIndexReorderCommit } from "./hooks/useTimelineEditingTypes";
-import type { TimelineStackingReorderIntent } from "./player/components/timelineStacking";
 import type { BlockPreviewInfo } from "./components/sidebar/BlocksTab";
 import { useDomEditSession } from "./hooks/useDomEditSession";
 import { useSdkSelectionSync } from "./hooks/useSdkSelectionSync";
@@ -62,7 +65,6 @@ import {
 } from "./utils/studioUrlState";
 import { trackStudioSessionStart } from "./telemetry/events";
 import { hasFiredSessionStart, markSessionStartFired } from "./telemetry/config";
-type TimelineMoveOperation = Parameters<typeof persistTimelineMoveEditsAtomically>[2];
 // fallow-ignore-next-line complexity
 export function StudioApp() {
   const { projectId, resolving, waitingForServer } = useServerConnection();
@@ -154,6 +156,7 @@ export function StudioApp() {
     reloadPreview: () => setRefreshKey((k) => k + 1),
     pendingTimelineEditPathRef,
   });
+  const invalidateGsapCacheRef = useRef<() => void>(() => {});
   const timelineEditing = useTimelineEditing({
     projectId,
     activeCompPath,
@@ -171,20 +174,11 @@ export function StudioApp() {
     sdkSession: editFlowSdkSession,
     publishSdkSession: sdkHandle.publish,
     forceReloadSdkSession: sdkHandle.forceReload,
+    invalidateGsapCache: () => invalidateGsapCacheRef.current(),
     handleDomZIndexReorderCommitRef,
   });
-  const handleTimelineElementsMove = useCallback(
-    async (
-      edits: Array<{
-        element: TimelineElement;
-        updates: Pick<TimelineElement, "start" | "track"> & {
-          stackingReorder?: TimelineStackingReorderIntent | null;
-        };
-      }>,
-      coalesceKey?: string,
-      operation: TimelineMoveOperation = "timing",
-      coalesceMs?: number,
-    ) => {
+  const handleTimelineElementsMove: TimelineMoveEditsHandler = useCallback(
+    async (edits, coalesceKey, operation: TimelineMoveOperation = "timing", coalesceMs) => {
       const deps = { handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove };
       await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);
     },
@@ -228,7 +222,6 @@ export function StudioApp() {
   const domEditDeleteBridge = (s: DomEditSelection) => handleDomEditElementDeleteRef.current(s);
   const resetKeyframesRef = useRef<() => boolean>(() => false);
   const deleteSelectedKeyframesRef = useRef<() => void>(() => {});
-  const invalidateGsapCacheRef = useRef<() => void>(() => {});
   const { handleCopy, handlePaste, handleCut } = useClipboard({
     projectId,
     activeCompPath,
@@ -408,6 +401,7 @@ export function StudioApp() {
     panelLayout.rightInspectorPanes,
     panelLayout.rightCollapsed,
     isPlaying,
+    domEditSession.domEditSelection,
     gestureState === "recording",
   );
   useStudioUrlState({

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

@@ -101,6 +101,7 @@ describe("AnimationCard ease editing", () => {
 
     expect(onUpdateKeyframeEase).toHaveBeenCalledExactlyOnceWith(animation.id, 50, ease);
     expect(trackStudioSegmentEaseEdit).toHaveBeenCalledExactlyOnceWith({
+      action: "commit",
       ease,
     });
     act(() => view.root.unmount());

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

@@ -1,4 +1,4 @@
-import { memo, useCallback, useMemo, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { SUPPORTED_EASES, SUPPORTED_PROPS } from "@hyperframes/core/gsap-constants";
 import { trackStudioSegmentEaseEdit } from "../../telemetry/events";
@@ -23,13 +23,17 @@ interface AnimationCardProps extends GsapAnimationEditCallbacks {
   animation: GsapAnimation;
   defaultExpanded: boolean;
   flat?: boolean;
+  focusedSegment?: { tweenPercentage: number } | null;
+  onFocusSegmentConsumed?: () => void;
 }
 
 // fallow-ignore-next-line complexity
 export const AnimationCard = memo(function AnimationCard({
   animation,
   defaultExpanded,
   flat,
+  focusedSegment,
+  onFocusSegmentConsumed,
   onUpdateProperty,
   onUpdateMeta,
   onDeleteAnimation,
@@ -50,6 +54,25 @@ export const AnimationCard = memo(function AnimationCard({
   const [addingProp, setAddingProp] = useState(false);
   const [addingFromProp, setAddingFromProp] = useState(false);
   const [expandedKfPct, setExpandedKfPct] = useState<number | null>(null);
+  const cardRef = useRef<HTMLDivElement>(null);
+  const pendingAutoScrollRef = useRef(false);
+
+  useEffect(() => {
+    if (!focusedSegment) return;
+    setExpanded(true);
+    pendingAutoScrollRef.current = true;
+    setExpandedKfPct(focusedSegment.tweenPercentage);
+    onFocusSegmentConsumed?.();
+  }, [focusedSegment, onFocusSegmentConsumed]);
+
+  useEffect(() => {
+    if (!pendingAutoScrollRef.current || expandedKfPct === null) return;
+    const segment = cardRef.current?.querySelector<HTMLElement>(
+      `[data-ease-segment-pct="${expandedKfPct}"]`,
+    );
+    segment?.scrollIntoView({ block: "nearest", behavior: "smooth" });
+    pendingAutoScrollRef.current = false;
+  }, [expandedKfPct]);
 
   const usedProps = useMemo(
     () => new Set(Object.keys(animation.properties)),
@@ -154,6 +177,7 @@ export const AnimationCard = memo(function AnimationCard({
 
   return (
     <div
+      ref={cardRef}
       data-flat-effect-card={flat ? "true" : undefined}
       className={
         flat
@@ -267,7 +291,7 @@ export const AnimationCard = memo(function AnimationCard({
                     onToggle={setExpandedKfPct}
                     onEaseCommit={(pct, ease) => {
                       onUpdateKeyframeEase(animation.id, pct, ease);
-                      trackStudioSegmentEaseEdit({ ease });
+                      trackStudioSegmentEaseEdit({ action: "commit", ease });
                     }}
                     onApplyAll={
                       onSetAllKeyframeEases

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

@@ -0,0 +1,68 @@
+import { ADD_METHODS, ADD_METHOD_LABELS, METHOD_TOOLTIPS } from "./gsapAnimationConstants";
+
+const STYLES = {
+  classic: {
+    method:
+      "rounded-lg border border-neutral-700 bg-neutral-900 px-2.5 py-1.5 text-[11px] font-medium text-neutral-300 transition-colors hover:border-neutral-600 hover:text-white",
+    cancel: "px-1.5 text-[11px] text-neutral-500 hover:text-neutral-300",
+    trigger: "text-[11px] font-medium text-neutral-400 transition-colors hover:text-neutral-200",
+  },
+  flat: {
+    method:
+      "rounded-lg border border-panel-border-input bg-panel-input px-2.5 py-1.5 text-[11px] font-medium text-panel-text-2 transition-colors hover:border-panel-text-4 hover:text-panel-text-0",
+    cancel: "px-1.5 text-[11px] text-panel-text-3 hover:text-panel-text-1",
+    trigger: "text-[11px] font-medium text-panel-text-3 transition-colors hover:text-panel-text-1",
+  },
+};
+
+export function GsapAddAnimationControl({
+  open,
+  setOpen,
+  onAddAnimation,
+  track,
+  variant,
+}: {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  onAddAnimation: (method: "to" | "from" | "set" | "fromTo") => void;
+  track: (control: string, name: string) => void;
+  variant: keyof typeof STYLES;
+}) {
+  const styles = STYLES[variant];
+
+  return (
+    <div className="relative pt-1">
+      {open ? (
+        <div className="flex gap-1.5">
+          {ADD_METHODS.map((method) => (
+            <button
+              key={method}
+              type="button"
+              title={METHOD_TOOLTIPS[method]}
+              onClick={() => {
+                track("button", `Add ${method} animation`);
+                onAddAnimation(method);
+                setOpen(false);
+              }}
+              className={styles.method}
+            >
+              {ADD_METHOD_LABELS[method] ?? method}
+            </button>
+          ))}
+          <button type="button" onClick={() => setOpen(false)} className={styles.cancel}>
+            Cancel
+          </button>
+        </div>
+      ) : (
+        <button
+          type="button"
+          onClick={() => setOpen(true)}
+          className={styles.trigger}
+          title="Add a new animation effect to this element"
+        >
+          + Add effect
+        </button>
+      )}
+    </div>
+  );
+}