@hyperframes/studio 0.7.76 → 0.7.77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.76",
+  "version": "0.7.77",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.76",
-    "@hyperframes/parsers": "0.7.76",
-    "@hyperframes/sdk": "0.7.76",
-    "@hyperframes/studio-server": "0.7.76",
-    "@hyperframes/player": "0.7.76"
+    "@hyperframes/core": "0.7.77",
+    "@hyperframes/parsers": "0.7.77",
+    "@hyperframes/player": "0.7.77",
+    "@hyperframes/sdk": "0.7.77",
+    "@hyperframes/studio-server": "0.7.77"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.76"
+    "@hyperframes/producer": "0.7.77"
   },
   "peerDependencies": {
     "react": "19",

package/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,10 @@ export function StudioApp() {
     reloadPreview: () => setRefreshKey((k) => k + 1),
     pendingTimelineEditPathRef,
   });
+  const invalidateGsapCacheRef = useRef<() => void>(() => {});
+  // Stable identity — what the ref indirection is for. An inline arrow re-created
+  // the memoized timeline handlers (it is in their deps) on every render.
+  const invalidateGsapCache = useCallback(() => invalidateGsapCacheRef.current(), []);
   const timelineEditing = useTimelineEditing({
     projectId,
     activeCompPath,
@@ -171,20 +177,11 @@ export function StudioApp() {
     sdkSession: editFlowSdkSession,
     publishSdkSession: sdkHandle.publish,
     forceReloadSdkSession: sdkHandle.forceReload,
+    invalidateGsapCache,
     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 +225,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,
@@ -402,12 +398,14 @@ export function StudioApp() {
     designPanelActive,
     inspectorPanelActive,
     inspectorButtonActive,
+    shouldShowMotionPath,
     shouldShowSelectedDomBounds,
   } = useInspectorState(
     panelLayout.rightPanelTab,
     panelLayout.rightInspectorPanes,
     panelLayout.rightCollapsed,
     isPlaying,
+    domEditSession.domEditSelection,
     gestureState === "recording",
   );
   useStudioUrlState({
@@ -558,6 +556,7 @@ export function StudioApp() {
                     handleRazorSplitAll={timelineEditing.handleRazorSplitAll}
                     setCompIdToSrc={setCompIdToSrc}
                     setCompositionLoading={setCompositionLoading}
+                    shouldShowMotionPath={shouldShowMotionPath}
                     shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
                     isGestureRecording={gestureState === "recording"}
                     recordingState={gestureState}

package/src/components/EditorShell.tsx

@@ -56,6 +56,7 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
   ) => Promise<void> | void;
   setCompIdToSrc: (map: Map<string, string>) => void;
   setCompositionLoading: (loading: boolean) => void;
+  shouldShowMotionPath: boolean;
   shouldShowSelectedDomBounds: boolean;
   blockPreview?: BlockPreviewInfo | null;
   isGestureRecording?: boolean;
@@ -90,6 +91,7 @@ export function EditorShell({
   handleRazorSplitAll,
   setCompIdToSrc,
   setCompositionLoading,
+  shouldShowMotionPath,
   shouldShowSelectedDomBounds,
   isGestureRecording,
   recordingState,
@@ -149,6 +151,7 @@ export function EditorShell({
             onDeleteElement={handleTimelineElementDelete}
             previewOverlay={
               <PreviewOverlays
+                shouldShowMotionPath={shouldShowMotionPath}
                 shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
                 blockPreview={blockPreview}
                 isGestureRecording={isGestureRecording}

package/src/components/TimelineToolbar.test.tsx

@@ -2,8 +2,10 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
+import { makeSelection } from "../hooks/domSelectionTestHarness";
 import { TimelineToolbar } from "./TimelineToolbar";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -13,12 +15,14 @@ afterEach(() => {
   usePlayerStore.setState({ autoKeyframeEnabled: true });
 });
 
-function renderToolbar() {
+function renderToolbar(
+  domEditSession?: React.ComponentProps<typeof TimelineToolbar>["domEditSession"],
+) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
   act(() => {
-    root.render(<TimelineToolbar />);
+    root.render(<TimelineToolbar domEditSession={domEditSession} />);
   });
   return { host, root };
 }
@@ -54,3 +58,44 @@ describe("TimelineToolbar — auto-keyframe toggle (#1808)", () => {
     act(() => root.unmount());
   });
 });
+describe("TimelineToolbar — motion path endpoints", () => {
+  it("does not advertise a destructive keyframe toggle for a required endpoint", () => {
+    usePlayerStore.setState({ currentTime: 10 });
+    const animation: GsapAnimation = {
+      id: "#el-to-0-position",
+      targetSelector: "#el",
+      method: "to",
+      position: 0,
+      duration: 10,
+      properties: {},
+      keyframes: {
+        format: "object-array",
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 } },
+          { percentage: 100, properties: { x: 100, y: 0 } },
+        ],
+      },
+      arcPath: {
+        enabled: true,
+        autoRotate: false,
+        segments: [{ curviness: 1 }],
+      },
+    };
+    const element = document.createElement("div");
+    element.id = "el";
+    const session = {
+      domEditSelection: makeSelection("Element", element),
+      selectedGsapAnimations: [animation],
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapConvertToKeyframes: vi.fn(),
+      handleGsapRemoveKeyframe: vi.fn(),
+    } satisfies NonNullable<React.ComponentProps<typeof TimelineToolbar>["domEditSession"]>;
+
+    const { host, root } = renderToolbar(session);
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Motion path endpoint"]',
+    );
+    expect(button?.disabled).toBe(true);
+    act(() => root.unmount());
+  });
+});

package/src/components/TimelineToolbar.tsx

@@ -5,7 +5,7 @@ import {
   isPlayheadWithinTween,
   type EnableKeyframesSession,
 } from "../hooks/useEnableKeyframes";
-import { computeElementPercentage } from "../hooks/gsapShared";
+import { computeElementPercentage, KEYFRAME_PCT_MATCH } from "../hooks/gsapShared";
 import { useKeyframeKeyboard } from "../hooks/useKeyframeKeyboard";
 import {
   getNextTimelineZoomPercent,
@@ -36,6 +36,60 @@ interface TimelineToolbarProps {
   onSplitElement?: (element: TimelineElement, splitTime: number) => void;
 }
 
+interface KeyframeToggleState {
+  state: "active" | "inactive" | "none";
+  isMotionPath: boolean;
+  pathEndpoint: boolean;
+  willExtend: boolean;
+}
+
+const NO_KEYFRAME_TOGGLE: KeyframeToggleState = {
+  state: "none",
+  isMotionPath: false,
+  pathEndpoint: false,
+  willExtend: false,
+};
+
+function isMotionPathEndpoint(animation: GsapAnimation | undefined, percentage: number): boolean {
+  if (!animation?.keyframes) return false;
+  const keyframes = animation.keyframes.keyframes;
+  return (
+    Math.abs((keyframes[0]?.percentage ?? -Infinity) - percentage) <= KEYFRAME_PCT_MATCH ||
+    Math.abs((keyframes.at(-1)?.percentage ?? Infinity) - percentage) <= KEYFRAME_PCT_MATCH
+  );
+}
+
+function resolveKeyframeToggleState(
+  session: DomEditSessionSlice | undefined,
+  currentTime: number,
+): KeyframeToggleState {
+  if (!session?.domEditSelection) return NO_KEYFRAME_TOGGLE;
+  const arcAnimation = session.selectedGsapAnimations.find(
+    (animation) => animation.arcPath && animation.keyframes,
+  );
+  const animation =
+    arcAnimation ??
+    session.selectedGsapAnimations.find((candidate) => candidate.keyframes && !candidate.arcPath);
+  if (!animation?.keyframes) return NO_KEYFRAME_TOGGLE;
+
+  const isMotionPath = Boolean(arcAnimation);
+  if (!isPlayheadWithinTween(animation, currentTime, session.domEditSelection)) {
+    return { state: "inactive", isMotionPath, pathEndpoint: false, willExtend: true };
+  }
+
+  const percentage = computeElementPercentage(currentTime, session.domEditSelection, animation);
+  const pathEndpoint = isMotionPathEndpoint(arcAnimation, percentage);
+  const active = animation.keyframes.keyframes.some(
+    (keyframe) => Math.abs(keyframe.percentage - percentage) <= KEYFRAME_PCT_MATCH,
+  );
+  return {
+    state: pathEndpoint ? "none" : active ? "active" : "inactive",
+    isMotionPath,
+    pathEndpoint,
+    willExtend: false,
+  };
+}
+
 function useKeyframeToggle(session?: DomEditSessionSlice) {
   const currentTime = usePlayerStore((s) => s.currentTime);
   const sessionRef = useRef(session);
@@ -45,31 +99,12 @@ function useKeyframeToggle(session?: DomEditSessionSlice) {
     sessionRef as React.RefObject<EnableKeyframesSession | undefined>,
   );
 
-  if (!session) return { state: "none" as const, onToggle: undefined };
-
-  const sel = session.domEditSelection;
-  const anims = session.selectedGsapAnimations;
-  const kfAnim = anims.find((a) => a.keyframes);
-
-  let state: "active" | "inactive" | "none" = "none";
-  // Outside the tween, clicking extends the animation to the playhead rather than
-  // toggling a (clamped) edge keyframe — so the button stays an "add" affordance.
-  let willExtend = false;
-  if (kfAnim?.keyframes && sel) {
-    if (!isPlayheadWithinTween(kfAnim, currentTime)) {
-      state = "inactive";
-      willExtend = true;
-    } else {
-      // Tween-relative percentage (not the clip range) so the button state matches
-      // where the keyframe would actually land.
-      const pct = computeElementPercentage(currentTime, sel, kfAnim);
-      state = kfAnim.keyframes.keyframes.some((k) => Math.abs(k.percentage - pct) <= 1)
-        ? "active"
-        : "inactive";
-    }
-  }
+  const toggleState = resolveKeyframeToggleState(session, currentTime);
 
-  return { state, willExtend, onToggle: sel ? onToggle : undefined };
+  return {
+    ...toggleState,
+    onToggle: session?.domEditSelection && !toggleState.pathEndpoint ? onToggle : undefined,
+  };
 }
 
 // fallow-ignore-next-line complexity
@@ -91,6 +126,8 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
   const displayedTimelineZoomPercent = getTimelineZoomPercent(zoomMode, manualZoomPercent);
   const {
     state: keyframeState,
+    isMotionPath: keyframeIsMotionPath,
+    pathEndpoint: keyframePathEndpoint,
     willExtend: keyframeWillExtend,
     onToggle: onToggleKeyframe,
   } = useKeyframeToggle(domEditSession);
@@ -180,15 +217,23 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
             // toolbar layout never shifts.
             <Tooltip
               label={
-                !onToggleKeyframe
-                  ? "Select an animated element to add keyframes"
-                  : keyframeState === "active"
-                    ? "Remove keyframe at playhead (K)"
-                    : keyframeState === "inactive"
+                keyframePathEndpoint
+                  ? "Motion path endpoints cannot be removed"
+                  : !onToggleKeyframe
+                    ? "Select an animated element to add keyframes"
+                    : keyframeIsMotionPath
                       ? keyframeWillExtend
-                        ? "Add keyframe at playhead, extends animation (K)"
-                        : "Add keyframe at playhead (K)"
-                      : "Add keyframe (K)"
+                        ? "Extend motion path to playhead (K)"
+                        : keyframeState === "active"
+                          ? "Remove waypoint from motion path (K)"
+                          : "Add waypoint to motion path (K)"
+                      : keyframeState === "active"
+                        ? "Remove keyframe at playhead (K)"
+                        : keyframeState === "inactive"
+                          ? keyframeWillExtend
+                            ? "Add keyframe at playhead, extends animation (K)"
+                            : "Add keyframe at playhead (K)"
+                          : "Add keyframe (K)"
               }
             >
               <button
@@ -196,9 +241,17 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
                 disabled={!onToggleKeyframe}
                 onClick={onToggleKeyframe}
                 aria-label={
-                  keyframeState === "active"
-                    ? "Remove keyframe at playhead"
-                    : "Add keyframe at playhead"
+                  keyframePathEndpoint
+                    ? "Motion path endpoint"
+                    : keyframeIsMotionPath
+                      ? keyframeState === "active"
+                        ? "Remove motion path waypoint"
+                        : keyframeWillExtend
+                          ? "Extend motion path to playhead"
+                          : "Add motion path waypoint"
+                      : keyframeState === "active"
+                        ? "Remove keyframe at playhead"
+                        : "Add keyframe at playhead"
                 }
                 className={
                   !onToggleKeyframe

package/src/components/editor/AnimationCard.test.tsx

@@ -45,17 +45,22 @@ function selectPreset(host: HTMLElement, presetId: string): string {
   return presetConfig.ease;
 }
 
-function renderExpandedCard({
-  animation,
+/** Every test mounts the same card; only expansion, flat mode, and the spies differ. */
+function renderCard({
+  animation = baseAnimation(),
+  defaultExpanded = true,
   flat,
   onUpdateMeta = vi.fn(),
   onUpdateKeyframeEase = vi.fn(),
+  onDeleteAnimation = noop,
 }: {
-  animation: GsapAnimation;
+  animation?: GsapAnimation;
+  defaultExpanded?: boolean;
   flat?: boolean;
   onUpdateMeta?: ReturnType<typeof vi.fn>;
   onUpdateKeyframeEase?: ReturnType<typeof vi.fn>;
-}) {
+  onDeleteAnimation?: (id: string) => void;
+} = {}) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
@@ -63,11 +68,11 @@ function renderExpandedCard({
     root.render(
       <AnimationCard
         animation={animation}
-        defaultExpanded
+        defaultExpanded={defaultExpanded}
         flat={flat}
         onUpdateProperty={noop}
         onUpdateMeta={onUpdateMeta}
-        onDeleteAnimation={noop}
+        onDeleteAnimation={onDeleteAnimation}
         onAddProperty={noop}
         onRemoveProperty={noop}
         onUpdateKeyframeEase={onUpdateKeyframeEase}
@@ -90,7 +95,7 @@ describe("AnimationCard ease editing", () => {
         ],
       },
     });
-    const view = renderExpandedCard({ animation, onUpdateKeyframeEase });
+    const view = renderCard({ animation, onUpdateKeyframeEase });
 
     const segment = Array.from(view.host.querySelectorAll("button")).find((button) =>
       button.textContent?.includes("0% → 50%"),
@@ -101,6 +106,7 @@ describe("AnimationCard ease editing", () => {
 
     expect(onUpdateKeyframeEase).toHaveBeenCalledExactlyOnceWith(animation.id, 50, ease);
     expect(trackStudioSegmentEaseEdit).toHaveBeenCalledExactlyOnceWith({
+      action: "commit",
       ease,
     });
     act(() => view.root.unmount());
@@ -110,7 +116,7 @@ describe("AnimationCard ease editing", () => {
     const onUpdateMeta = vi.fn();
     const onUpdateKeyframeEase = vi.fn();
     const animation = baseAnimation({ id: "flat-tween" });
-    const view = renderExpandedCard({
+    const view = renderCard({
       animation,
       flat: true,
       onUpdateMeta,
@@ -128,23 +134,7 @@ describe("AnimationCard ease editing", () => {
 
 describe("AnimationCard flat branch", () => {
   it("renders a mint border-left and panel-token colors when flat", () => {
-    const host = document.createElement("div");
-    document.body.append(host);
-    const root = createRoot(host);
-    act(() => {
-      root.render(
-        <AnimationCard
-          animation={baseAnimation()}
-          defaultExpanded={false}
-          flat
-          onUpdateProperty={noop}
-          onUpdateMeta={noop}
-          onDeleteAnimation={noop}
-          onAddProperty={noop}
-          onRemoveProperty={noop}
-        />,
-      );
-    });
+    const { host, root } = renderCard({ defaultExpanded: false, flat: true });
     const card = host.querySelector('[data-flat-effect-card="true"]');
     expect(card).not.toBeNull();
     expect(card?.className).toContain("border-panel-accent");
@@ -152,22 +142,7 @@ describe("AnimationCard flat branch", () => {
   });
 
   it("still renders the legacy (non-flat) appearance when flat is omitted", () => {
-    const host = document.createElement("div");
-    document.body.append(host);
-    const root = createRoot(host);
-    act(() => {
-      root.render(
-        <AnimationCard
-          animation={baseAnimation()}
-          defaultExpanded={false}
-          onUpdateProperty={noop}
-          onUpdateMeta={noop}
-          onDeleteAnimation={noop}
-          onAddProperty={noop}
-          onRemoveProperty={noop}
-        />,
-      );
-    });
+    const { host, root } = renderCard({ defaultExpanded: false });
     expect(host.querySelector('[data-flat-effect-card="true"]')).toBeNull();
     expect(host.textContent).toContain("power2.out");
     act(() => root.unmount());
@@ -175,23 +150,7 @@ describe("AnimationCard flat branch", () => {
 
   it("toggles expanded state when the collapsed header button is clicked, in both modes", () => {
     for (const flat of [false, true]) {
-      const host = document.createElement("div");
-      document.body.append(host);
-      const root = createRoot(host);
-      act(() => {
-        root.render(
-          <AnimationCard
-            animation={baseAnimation()}
-            defaultExpanded={false}
-            flat={flat || undefined}
-            onUpdateProperty={noop}
-            onUpdateMeta={noop}
-            onDeleteAnimation={noop}
-            onAddProperty={noop}
-            onRemoveProperty={noop}
-          />,
-        );
-      });
+      const { host, root } = renderCard({ defaultExpanded: false, flat: flat || undefined });
       expect(host.textContent).not.toContain("Remove");
       const button = host.querySelector("button");
       expect(button).not.toBeNull();
@@ -205,23 +164,7 @@ describe("AnimationCard flat branch", () => {
 
   it("invokes onDeleteAnimation with the animation id when Remove is clicked, in flat mode", () => {
     const onDeleteAnimation = vi.fn();
-    const host = document.createElement("div");
-    document.body.append(host);
-    const root = createRoot(host);
-    act(() => {
-      root.render(
-        <AnimationCard
-          animation={baseAnimation()}
-          defaultExpanded={true}
-          flat
-          onUpdateProperty={noop}
-          onUpdateMeta={noop}
-          onDeleteAnimation={onDeleteAnimation}
-          onAddProperty={noop}
-          onRemoveProperty={noop}
-        />,
-      );
-    });
+    const { host, root } = renderCard({ flat: true, onDeleteAnimation });
     const buttons = Array.from(host.querySelectorAll("button"));
     const removeButton = buttons.find((b) => b.textContent === "Remove");
     expect(removeButton).not.toBeUndefined();

package/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,6 +23,8 @@ interface AnimationCardProps extends GsapAnimationEditCallbacks {
   animation: GsapAnimation;
   defaultExpanded: boolean;
   flat?: boolean;
+  focusedSegment?: { tweenPercentage: number } | null;
+  onFocusSegmentConsumed?: () => void;
 }
 
 // fallow-ignore-next-line complexity
@@ -30,6 +32,8 @@ 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