@hyperframes/studio 0.7.75 → 0.7.77

package/src/player/components/trackHeaderLaneState.ts

@@ -0,0 +1,121 @@
+/**
+ * Resolves what a property lane's header row shows at the current playhead:
+ * which animation owns the lane right now, where the playhead sits inside it,
+ * the sampled values, and the add/remove keyframe target. Pure state, no JSX, so
+ * the header component only renders what this returns.
+ */
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import {
+  clipToTweenPercentage,
+  getKeyframeNavigationState,
+} from "../../components/editor/KeyframeNavigation";
+import {
+  absoluteToPercentageForAnimation,
+  isTimeWithinTween,
+  resolveTweenDuration,
+  resolveTweenStart,
+} from "../../utils/globalTimeCompiler";
+import type { TimelinePropertyGroupKeyframeToggle } from "./timelineCallbacks";
+import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
+import { groupLabel, valuesAt, type LaneValues } from "./trackHeaderLaneValues";
+
+export type TimelinePropertyLane = ReturnType<typeof getTimelinePropertyLanes>[number];
+export type KeyframeNavigationState = ReturnType<
+  typeof getKeyframeNavigationState<TimelinePropertyLane["keyframes"][number]>
+>;
+
+function findNearestLaneKeyframe(lane: TimelinePropertyLane, clipPercentage: number) {
+  return lane.keyframes.reduce<(typeof lane.keyframes)[number] | null>(
+    (nearest, keyframe) =>
+      !nearest ||
+      Math.abs(keyframe.percentage - clipPercentage) < Math.abs(nearest.percentage - clipPercentage)
+        ? keyframe
+        : nearest,
+    null,
+  );
+}
+
+function findAnimationAtTime(animations: TimelinePropertyLane["animations"], currentTime: number) {
+  return animations.find((candidate) => {
+    const start = resolveTweenStart(candidate);
+    return start !== null && isTimeWithinTween(currentTime, start, resolveTweenDuration(candidate));
+  });
+}
+
+function resolveLaneAnimation(
+  lane: TimelinePropertyLane,
+  navigation: KeyframeNavigationState,
+  nearestKeyframe: TimelinePropertyLane["keyframes"][number] | null,
+  animationAtPlayhead: GsapAnimation | undefined,
+) {
+  const animationId = navigation.currentKeyframe?.animationId ?? nearestKeyframe?.animationId;
+  return animationAtPlayhead ?? lane.animations.find((candidate) => candidate.id === animationId);
+}
+
+function resolveLaneTweenPercentage(
+  navigation: KeyframeNavigationState,
+  animation: GsapAnimation | undefined,
+  animationKeyframes: TimelinePropertyLane["keyframes"],
+  currentTime: number,
+  clipPercentage: number,
+) {
+  return (
+    navigation.currentKeyframe?.tweenPercentage ??
+    (animation ? absoluteToPercentageForAnimation(currentTime, animation) : null) ??
+    clipToTweenPercentage(animationKeyframes, clipPercentage)
+  );
+}
+
+function createLaneToggleTarget(
+  animation: GsapAnimation | undefined,
+  lane: TimelinePropertyLane,
+  tweenPercentage: number,
+  values: LaneValues,
+  navigation: KeyframeNavigationState,
+): TimelinePropertyGroupKeyframeToggle | null {
+  return animation
+    ? {
+        animationId: animation.id,
+        propertyGroup: lane.group,
+        tweenPercentage,
+        properties: values,
+        remove: navigation.currentKeyframe !== null,
+      }
+    : null;
+}
+
+export interface LaneHeaderState {
+  navigation: KeyframeNavigationState;
+  values: LaneValues;
+  label: string;
+  toggleTarget: TimelinePropertyGroupKeyframeToggle | null;
+}
+
+export function resolveLaneHeaderState(
+  lane: TimelinePropertyLane,
+  currentTime: number,
+  clipPercentage: number,
+): LaneHeaderState {
+  const navigation = getKeyframeNavigationState(lane.keyframes, clipPercentage);
+  const nearestKeyframe = findNearestLaneKeyframe(lane, clipPercentage);
+  const animationAtPlayhead = findAnimationAtTime(lane.animations, currentTime);
+  const animation = resolveLaneAnimation(lane, navigation, nearestKeyframe, animationAtPlayhead);
+  const animationKeyframes = lane.keyframes.filter(
+    (keyframe) => keyframe.animationId === animation?.id,
+  );
+  const tweenPercentage = resolveLaneTweenPercentage(
+    navigation,
+    animation,
+    animationKeyframes,
+    currentTime,
+    clipPercentage,
+  );
+  const values = animation ? valuesAt(animation, lane.group, tweenPercentage) : {};
+
+  return {
+    navigation,
+    values,
+    label: groupLabel(lane.group, values),
+    toggleTarget: createLaneToggleTarget(animation, lane, tweenPercentage, values, navigation),
+  };
+}

package/src/player/components/trackHeaderLaneValues.ts

@@ -0,0 +1,139 @@
+/**
+ * Sampling and formatting for the property-lane readouts in the track header:
+ * what value a property holds at a given tween percentage, and how that value
+ * reads to a human. Kept apart from the header's JSX so a formatting change and
+ * a layout change never touch the same file.
+ */
+import gsap from "gsap";
+import {
+  classifyPropertyGroup,
+  type GsapAnimation,
+  type PropertyGroupName,
+} from "@hyperframes/core/gsap-parser";
+
+export type LaneValues = Record<string, number | string>;
+
+function roundValue(value: number): string {
+  return String(Math.round(value * 100) / 100);
+}
+
+/** GSAP applies a keyframe's `ease` to the segment ARRIVING at it, so the curve
+ *  between two keyframes is named by the later one (with the tween-level
+ *  `easeEach`/`ease` as the fallback). Sampling linearly would report a value the
+ *  element never has at that time, and stamp that wrong value onto a keyframe
+ *  added from the track header. Unknown ease names parse to undefined -> linear. */
+function easedProgress(progress: number, animation: GsapAnimation, ease?: string): number {
+  const resolved = ease ?? animation.keyframes?.easeEach ?? animation.ease;
+  if (!resolved || resolved === "none") return progress;
+  return gsap.parseEase(resolved)?.(progress) ?? progress;
+}
+
+interface PropertyStop {
+  percentage: number;
+  value: number | string;
+  ease?: string;
+}
+
+function propertyStops(animation: GsapAnimation, property: string): PropertyStop[] {
+  return (animation.keyframes?.keyframes ?? [])
+    .filter((keyframe) => property in keyframe.properties)
+    .map((keyframe) => ({
+      percentage: keyframe.percentage,
+      value: keyframe.properties[property],
+      ease: keyframe.ease,
+    }));
+}
+
+/** A pair only interpolates when both ends are numeric and actually span time;
+ *  string values (colors, keywords) and zero-width pairs hold the earlier value.
+ *  Returns the numeric ends so the caller needs no cast to use them. */
+function interpolableEnds(
+  before: PropertyStop,
+  after: PropertyStop,
+): { from: number; to: number } | null {
+  if (typeof before.value !== "number" || typeof after.value !== "number") return null;
+  if (before.percentage === after.percentage) return null;
+  return { from: before.value, to: after.value };
+}
+
+function propertyValueAt(
+  animation: GsapAnimation,
+  property: string,
+  tweenPercentage: number,
+): number | string | undefined {
+  const stops = propertyStops(animation, property);
+  const before = stops.filter((stop) => stop.percentage <= tweenPercentage).at(-1);
+  const after = stops.find((stop) => stop.percentage >= tweenPercentage);
+  if (!before) return after?.value;
+  if (!after) return before.value;
+  const ends = interpolableEnds(before, after);
+  if (!ends) return before.value;
+  const progress = (tweenPercentage - before.percentage) / (after.percentage - before.percentage);
+  return ends.from + (ends.to - ends.from) * easedProgress(progress, animation, after.ease);
+}
+
+/** Every property of `group` this animation touches, sampled at `tweenPercentage`. */
+export function valuesAt(
+  animation: GsapAnimation,
+  group: PropertyGroupName,
+  tweenPercentage: number,
+): LaneValues {
+  const propertyNames = new Set<string>();
+  for (const keyframe of animation.keyframes?.keyframes ?? []) {
+    for (const property of Object.keys(keyframe.properties)) {
+      if (classifyPropertyGroup(property) === group) propertyNames.add(property);
+    }
+  }
+  const values: LaneValues = {};
+  for (const property of propertyNames) {
+    const value = propertyValueAt(animation, property, tweenPercentage);
+    if (value !== undefined) values[property] = value;
+  }
+  return values;
+}
+
+export function groupLabel(group: PropertyGroupName, properties: LaneValues): string {
+  if (group === "visual" && ("opacity" in properties || "autoAlpha" in properties)) {
+    return "Opacity";
+  }
+  if (group !== "other") return `${group[0]?.toUpperCase() ?? ""}${group.slice(1)}`;
+  const property = Object.keys(properties)[0];
+  return property ? `${property[0]?.toUpperCase() ?? ""}${property.slice(1)}` : "Other";
+}
+
+function defaultValueReadout(values: LaneValues): string {
+  return Object.values(values)
+    .map((value) => (typeof value === "number" ? roundValue(value) : value))
+    .join(", ");
+}
+
+function positionValueReadout(values: LaneValues): string | null {
+  const x = values.x;
+  const y = values.y;
+  return typeof x === "number" && typeof y === "number"
+    ? `${roundValue(x)}, ${roundValue(y)}`
+    : null;
+}
+
+function rotationValueReadout(values: LaneValues): string | null {
+  return typeof values.rotation === "number" ? `${roundValue(values.rotation)}°` : null;
+}
+
+function visualValueReadout(values: LaneValues): string | null {
+  const opacity = values.opacity ?? values.autoAlpha;
+  return typeof opacity === "number"
+    ? `${roundValue(Math.abs(opacity) <= 1 ? opacity * 100 : opacity)}%`
+    : null;
+}
+
+const GROUP_VALUE_READOUTS: Partial<
+  Record<PropertyGroupName, (values: LaneValues) => string | null>
+> = {
+  position: positionValueReadout,
+  rotation: rotationValueReadout,
+  visual: visualValueReadout,
+};
+
+export function valueReadout(group: PropertyGroupName, values: LaneValues): string {
+  return GROUP_VALUE_READOUTS[group]?.(values) ?? defaultValueReadout(values);
+}

package/src/player/components/useAutoExpandKeyframedClips.test.tsx

@@ -0,0 +1,75 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
+
+const studioShell = vi.hoisted(() => ({ projectId: "project-a" }));
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContextOptional: () => studioShell,
+}));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  studioShell.projectId = "project-a";
+  usePlayerStore.getState().reset();
+});
+
+const animations = new Map<string, GsapAnimation[]>([
+  [
+    "clip-1",
+    [
+      {
+        id: "position-tween",
+        targetSelector: "#clip-1",
+        method: "to",
+        position: 0,
+        duration: 1,
+        properties: { x: 100 },
+        propertyGroup: "position",
+      },
+    ],
+  ],
+]);
+
+function AutoExpandHarness({ value }: { value: Map<string, GsapAnimation[]> }) {
+  useAutoExpandKeyframedClips(value);
+  return null;
+}
+
+describe("useAutoExpandKeyframedClips", () => {
+  it("preserves manual collapse within a project and expands again in a different project", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const render = (projectId: string, value = new Map(animations)) => {
+      studioShell.projectId = projectId;
+      act(() => root.render(<AutoExpandHarness value={value} />));
+    };
+
+    const projectAAnimations = new Map(animations);
+    render("project-a", projectAAnimations);
+    expect(usePlayerStore.getState().expandedClipIds).toEqual(new Set(["clip-1"]));
+
+    act(() => usePlayerStore.getState().toggleClipExpanded("clip-1"));
+    expect(usePlayerStore.getState().expandedClipIds).toEqual(new Set());
+
+    const refreshedProjectAAnimations = new Map(animations);
+    render("project-a", refreshedProjectAAnimations);
+    expect(usePlayerStore.getState().expandedClipIds).toEqual(new Set());
+
+    render("project-b", refreshedProjectAAnimations);
+    expect(usePlayerStore.getState().expandedClipIds).toEqual(new Set());
+
+    render("project-b", new Map());
+    render("project-b");
+    expect(usePlayerStore.getState().expandedClipIds).toEqual(new Set(["clip-1"]));
+
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useAutoExpandKeyframedClips.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore } from "../store/playerStore";
+import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { animationContributesLane } from "./TimelinePropertyLanes";
+
+/**
+ * Keyframed clips start expanded (AE/Figma default). Auto-expands each clip the
+ * first time it contributes a lane — real keyframes OR a synthesizable flat tween
+ * — tracked per-clip so a later user collapse sticks and never bounces back open
+ * (and clips added later still auto-expand).
+ */
+/**
+ * Prunes clips that left the source, then returns the ones that newly contribute
+ * a lane. The prune matters because the set is otherwise append-only: a clip
+ * deleted and reinserted under the same id (undo, paste) would be remembered as
+ * already-expanded and never auto-expand again.
+ */
+function freshLaneClips(gsapAnimations: Map<string, GsapAnimation[]>, clips: Set<string>) {
+  for (const key of clips) {
+    if (!gsapAnimations.has(key)) clips.delete(key);
+  }
+  const fresh: string[] = [];
+  for (const [key, animations] of gsapAnimations) {
+    if (clips.has(key)) continue;
+    if (animations.some(animationContributesLane)) fresh.push(key);
+  }
+  return fresh;
+}
+
+export function useAutoExpandKeyframedClips(gsapAnimations: Map<string, GsapAnimation[]>): void {
+  const expandClips = usePlayerStore((s) => s.expandClips);
+  const projectId = useStudioShellContextOptional()?.projectId ?? null;
+  const seen = useRef({ projectId, source: gsapAnimations, clips: new Set<string>() });
+  useEffect(() => {
+    if (!STUDIO_KEYFRAMES_ENABLED) return;
+    if (seen.current.projectId !== projectId) {
+      const sourceChanged = seen.current.source !== gsapAnimations;
+      seen.current = { projectId, source: gsapAnimations, clips: new Set() };
+      if (!sourceChanged) return;
+    } else {
+      seen.current.source = gsapAnimations;
+    }
+    const fresh = freshLaneClips(gsapAnimations, seen.current.clips);
+    if (fresh.length === 0) return;
+    for (const key of fresh) seen.current.clips.add(key);
+    expandClips(fresh);
+  }, [gsapAnimations, expandClips, projectId]);
+}

package/src/player/components/useTimelineClipDrag.ts

@@ -48,6 +48,7 @@ interface UseTimelineClipDragInput {
   ppsRef: React.RefObject<number>;
   durationRef: React.RefObject<number>;
   trackOrderRef: React.RefObject<number[]>;
+  rowHeightsRef?: React.RefObject<readonly number[]>;
   onMoveElement?: (
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "track">,
@@ -85,6 +86,7 @@ export function useTimelineClipDrag({
   ppsRef,
   durationRef,
   trackOrderRef,
+  rowHeightsRef,
   onMoveElement,
   onMoveElements,
   onResizeElement,
@@ -241,13 +243,14 @@ export function useTimelineClipDrag({
         pps: ppsRef.current,
         duration: durationRef.current,
         trackOrder: trackOrderRef.current,
+        rowHeights: rowHeightsRef?.current,
         elements: elementsRef.current,
         selectedKeys: usePlayerStore.getState().selectedElementIds,
         buildSnapTargets,
         audioTracks: dragAudioTracksRef.current,
       });
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef, buildSnapTargets],
+    [scrollRef, ppsRef, durationRef, trackOrderRef, rowHeightsRef, buildSnapTargets],
   );
 
   // Recompute the trim preview for a pointer x. Shared by the pointermove resize

package/src/player/components/useTimelineGeometry.ts

@@ -21,6 +21,7 @@ interface UseTimelineGeometryInput {
   isDragging: RefObject<boolean>;
   scrollRef: RefObject<HTMLDivElement | null>;
   lastScrollLeftRef: RefObject<number>;
+  contentOrigin: number;
 }
 
 // Derive the timeline's horizontal geometry from the viewport, zoom, and any live
@@ -40,10 +41,11 @@ export function useTimelineGeometry({
   isDragging,
   scrollRef,
   lastScrollLeftRef,
+  contentOrigin,
 }: UseTimelineGeometryInput) {
   // Fit pps maps at least MIN_TIMELINE_EXTENT_S onto the viewport, so short
   // comps show a 60s ruler with usable empty space (see getTimelineFitPps).
-  const fitPps = getTimelineFitPps(viewportWidth, effectiveDuration);
+  const fitPps = getTimelineFitPps(viewportWidth, effectiveDuration, contentOrigin);
   const pps = getTimelinePixelsPerSecond(fitPps, zoomMode, manualZoomPercent);
   ppsRef.current = pps;
   const trackContentWidth = Math.max(0, effectiveDuration * pps);
@@ -70,6 +72,7 @@ export function useTimelineGeometry({
   const displayContentWidth = getTimelineDisplayContentWidth({
     trackContentWidth,
     viewportWidth,
+    contentOrigin,
     pps,
     dragGhostEndPx,
     resizeGhostEndPx,

package/src/player/components/useTimelineKeyframeHandlers.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
+import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const trackStudioSegmentEaseEdit = vi.hoisted(() => vi.fn());
+vi.mock("../../telemetry/events", () => ({ trackStudioSegmentEaseEdit }));
+
+const ELEMENT: TimelineElement = {
+  id: "clip-1",
+  label: "Hero card",
+  tag: "div",
+  start: 1,
+  duration: 2,
+  track: 0,
+};
+
+const TARGET: TimelineKeyframeTarget = {
+  percentage: 50,
+  tweenPercentage: 50,
+  propertyGroup: "position",
+  animationId: "position-tween",
+};
+
+const FLAT_TWEEN_TARGET: TimelineKeyframeTarget = {
+  percentage: 100,
+  tweenPercentage: 100,
+  propertyGroup: "position",
+  animationId: "position-tween",
+};
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  trackStudioSegmentEaseEdit.mockClear();
+  usePlayerStore.setState({ focusedEaseSegment: null });
+});
+
+describe("useTimelineKeyframeHandlers", () => {
+  it("tracks opening the segment ease editor when a timeline segment is selected", () => {
+    let onSelectSegment: ((elementId: string, target: TimelineKeyframeTarget) => void) | undefined;
+
+    function Harness() {
+      ({ onSelectSegment } = useTimelineKeyframeHandlers({
+        expandedElements: [ELEMENT],
+        keyframeCache: new Map(),
+        setSelectedElementId: vi.fn(),
+        setKfContextMenu: vi.fn(),
+        toggleSelectedKeyframe: vi.fn(),
+      }));
+      return null;
+    }
+
+    const root = mountReactHarness(<Harness />);
+    act(() => onSelectSegment?.(ELEMENT.id, TARGET));
+
+    expect(trackStudioSegmentEaseEdit).toHaveBeenCalledOnce();
+    expect(trackStudioSegmentEaseEdit).toHaveBeenCalledWith({ action: "open" });
+    act(() => root.unmount());
+  });
+
+  it("focuses a flat tween segment without seeking, while keyframe clicks still seek", () => {
+    const onSeek = vi.fn();
+    const onSelectElement = vi.fn();
+    const setSelectedElementId = vi.fn();
+    let onClickKeyframe:
+      | ((el: TimelineElement, target: TimelineKeyframeTarget) => void)
+      | undefined;
+    let onSelectSegment: ((elementId: string, target: TimelineKeyframeTarget) => void) | undefined;
+
+    function Harness() {
+      ({ onClickKeyframe, onSelectSegment } = useTimelineKeyframeHandlers({
+        expandedElements: [ELEMENT],
+        keyframeCache: new Map(),
+        onSelectElement,
+        onSeek,
+        setSelectedElementId,
+        setKfContextMenu: vi.fn(),
+        toggleSelectedKeyframe: vi.fn(),
+      }));
+      return null;
+    }
+
+    const root = mountReactHarness(<Harness />);
+
+    // Selecting a segment must NOT move the playhead.
+    act(() => onSelectSegment?.(ELEMENT.id, FLAT_TWEEN_TARGET));
+    expect(onSeek).not.toHaveBeenCalled();
+    expect(usePlayerStore.getState().focusedEaseSegment).toEqual({
+      animationId: "position-tween",
+      tweenPercentage: 100,
+      elementId: ELEMENT.id,
+    });
+    expect(setSelectedElementId).toHaveBeenCalledWith(ELEMENT.id);
+    expect(onSelectElement).toHaveBeenCalledWith(ELEMENT);
+
+    // Clicking the keyframe itself still seeks to it (start 1 + 50% of 2 = 2).
+    act(() => onClickKeyframe?.(ELEMENT, TARGET));
+    expect(onSeek).toHaveBeenCalledExactlyOnceWith(2);
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTimelineKeyframeHandlers.ts

@@ -1,7 +1,12 @@
 import { useCallback, type MouseEvent as ReactMouseEvent } from "react";
+import { trackStudioSegmentEaseEdit } from "../../telemetry/events";
 import type { TimelineElement, KeyframeCacheEntry } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
 import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
+import {
+  timelineKeyframeSelectionKey,
+  type TimelineKeyframeTarget,
+} from "./timelineKeyframeIdentity";
 
 interface UseTimelineKeyframeHandlersInput {
   expandedElements: TimelineElement[];
@@ -23,42 +28,71 @@ export function useTimelineKeyframeHandlers({
   toggleSelectedKeyframe,
 }: UseTimelineKeyframeHandlersInput) {
   const onClickKeyframe = useCallback(
-    (el: TimelineElement, pct: number) => {
+    (el: TimelineElement, target: TimelineKeyframeTarget, options?: { seek?: boolean }) => {
       usePlayerStore.getState().clearSelectedKeyframes();
       const elKey = el.key ?? el.id;
       setSelectedElementId(elKey);
       onSelectElement?.(el);
-      toggleSelectedKeyframe(`${elKey}:${pct}`);
-      onSeek?.(el.start + (pct / 100) * el.duration);
+      toggleSelectedKeyframe(timelineKeyframeSelectionKey(elKey, target));
+      // Clicking a diamond seeks the playhead to it; selecting a segment to edit
+      // its ease (options.seek === false) must NOT move the playhead.
+      if (options?.seek !== false) {
+        onSeek?.(el.start + (target.percentage / 100) * el.duration);
+      }
       const kfData = keyframeCache.get(elKey);
-      const kf = kfData?.keyframes.find((item) => Math.abs(item.percentage - pct) < 0.5);
-      usePlayerStore.getState().setActiveKeyframePct(kf?.tweenPercentage ?? null);
+      const kf = kfData?.keyframes.find(
+        (item) => Math.abs(item.percentage - target.percentage) < 0.5,
+      );
+      usePlayerStore
+        .getState()
+        .setActiveKeyframePct(target.tweenPercentage ?? kf?.tweenPercentage ?? null);
     },
     [keyframeCache, onSeek, onSelectElement, setSelectedElementId, toggleSelectedKeyframe],
   );
 
   const onShiftClickKeyframe = useCallback(
-    (elId: string, pct: number) => {
-      toggleSelectedKeyframe(`${elId}:${pct}`);
+    (elId: string, target: TimelineKeyframeTarget) => {
+      toggleSelectedKeyframe(timelineKeyframeSelectionKey(elId, target));
     },
     [toggleSelectedKeyframe],
   );
 
-  const onContextMenuKeyframe = useCallback(
-    (e: ReactMouseEvent, elId: string, pct: number) => {
+  const onSelectSegment = useCallback(
+    (elId: string, target: TimelineKeyframeTarget) => {
       const el = expandedElements.find((item) => (item.key ?? item.id) === elId);
-      if (el) {
-        setSelectedElementId(elId);
-        onSelectElement?.(el);
+      if (!el) return;
+      onClickKeyframe(el, target, { seek: false });
+      if (target.animationId !== undefined && target.tweenPercentage !== undefined) {
+        usePlayerStore.getState().setFocusedEaseSegment({
+          animationId: target.animationId,
+          tweenPercentage: target.tweenPercentage,
+          elementId: elId,
+        });
+        trackStudioSegmentEaseEdit({ action: "open" });
       }
+    },
+    [expandedElements, onClickKeyframe],
+  );
+
+  const onContextMenuKeyframe = useCallback(
+    (e: ReactMouseEvent, elId: string, target: TimelineKeyframeTarget) => {
+      const el = expandedElements.find((item) => (item.key ?? item.id) === elId);
+      if (!el) return;
+      setSelectedElementId(elId);
+      onSelectElement?.(el);
       const kfData = keyframeCache.get(elId);
-      const kf = kfData?.keyframes.find((item) => Math.abs(item.percentage - pct) < 0.2);
+      const kf = kfData?.keyframes.find(
+        (item) => Math.abs(item.percentage - target.percentage) < 0.2,
+      );
       setKfContextMenu({
         x: e.clientX + 4,
         y: e.clientY + 2,
         elementId: elId,
-        percentage: pct,
-        tweenPercentage: kf?.tweenPercentage,
+        percentage: target.percentage,
+        tweenPercentage: target.tweenPercentage ?? kf?.tweenPercentage,
+        propertyGroup: target.propertyGroup,
+        animationId: target.animationId,
+        element: el,
         currentEase: kf?.ease ?? kfData?.ease,
       });
     },
@@ -67,6 +101,7 @@ export function useTimelineKeyframeHandlers({
 
   return {
     onClickKeyframe,
+    onSelectSegment,
     onShiftClickKeyframe,
     onContextMenuKeyframe,
   };