refactor(studio): extract timeline render contracts

packages/studio/src/player/components/Timeline.tsx

@@ -1,10 +1,9 @@
-import { useRef, useMemo, useCallback, useState, useEffect, memo } from "react";
+import { useRef, useMemo, useCallback, useState, memo } from "react";
 import { useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
 import { isMusicTrack } from "../../utils/timelineInspector";
 import { remapBeatAnalysisToComposition } from "../../utils/beatEditActions";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { useExpandedTimelineElements } from "../hooks/useExpandedTimelineElements";
-import { useMountEffect } from "../../hooks/useMountEffect";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
@@ -16,14 +15,12 @@ import { TimelineCanvas } from "./TimelineCanvas";
 import { type KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
 import { TimelineOverlays } from "./TimelineOverlays";
-import { animationContributesLane } from "./TimelinePropertyLanes";
 import { useTimelineEditPinning } from "./useTimelineEditPinning";
 import { useTimelineStackingSync } from "./useTimelineStackingSync";
 import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
-import { GUTTER, LABEL_COL_W, generateTicks } from "./timelineLayout";
+import { GUTTER, LABEL_COL_W } from "./timelineLayout";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
-import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineProps } from "./TimelineTypes";
 import {
@@ -37,6 +34,14 @@ import { useTrackGapMenu } from "./useTrackGapMenu";
 import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
 import { useStudioPlaybackContextOptional } from "../../contexts/StudioContext";
 import { TimelineRazorGuide, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
+import {
+  getEffectiveTimelineDuration,
+  getTimelinePreviewElement,
+  hasKeyframedTimelineClips,
+} from "./timelineViewModel";
+import { useTimelineSelectionLifecycle } from "./useTimelineSelectionLifecycle";
+import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
+import { useTimelineTicks } from "./useTimelineTicks";
 
 // Re-export pure utilities so existing imports from "./Timeline" still resolve.
 export {
@@ -118,13 +123,7 @@ export const Timeline = memo(function Timeline({
   // Label mode = comp has keyframed clips (not just when expanded): keeps the layer
   // disclosure + property column visible and reserves a GUTTER before 0s (Figma).
   const hasKeyframedClips = useMemo(
-    () =>
-      Array.from(gsapAnimations.values()).some((list) =>
-        // Same lane-contribution predicate the layout uses: real keyframes OR a
-        // synthesizable flat tween. Checking animation.keyframes alone left a
-        // flat-tween-only comp without its reserved label column.
-        list.some((animation) => animationContributesLane(animation)),
-      ),
+    () => hasKeyframedTimelineClips(gsapAnimations),
     [gsapAnimations],
   );
   const labelMode = STUDIO_KEYFRAMES_ENABLED && hasKeyframedClips;
@@ -140,20 +139,7 @@ export const Timeline = memo(function Timeline({
   const activeTool = usePlayerStore((s) => s.activeTool);
   const [hoveredClip, setHoveredClip] = useState<string | null>(null);
   const isDragging = useRef(false);
-  const [shiftHeld, setShiftHeld] = useState(false);
-
-  useMountEffect(() => {
-    const key = (e: KeyboardEvent) => e.key === "Shift" && setShiftHeld(e.type === "keydown");
-    const blur = () => setShiftHeld(false);
-    window.addEventListener("keydown", key);
-    window.addEventListener("keyup", key);
-    window.addEventListener("blur", blur);
-    return () => {
-      window.removeEventListener("keydown", key);
-      window.removeEventListener("keyup", key);
-      window.removeEventListener("blur", blur);
-    };
-  });
+  const shiftHeld = useTimelineShiftModifier();
 
   const [showPopover, setShowPopover] = useState(false);
   const [kfContextMenu, setKfContextMenu] = useState<KeyframeDiamondContextMenuState | null>(null);
@@ -170,12 +156,10 @@ export const Timeline = memo(function Timeline({
   // Last horizontal scroll offset, restored across the post-edit iframe reload (pinned zoom).
   const lastScrollLeftRef = useRef(0);
 
-  const effectiveDuration = useMemo(() => {
-    const safeDur = Number.isFinite(duration) ? duration : 0;
-    if (rawElements.length === 0) return safeDur;
-    const result = Math.max(safeDur, ...rawElements.map((el) => el.start + el.duration));
-    return Number.isFinite(result) ? result : safeDur;
-  }, [rawElements, duration]);
+  const effectiveDuration = useMemo(
+    () => getEffectiveTimelineDuration(duration, rawElements),
+    [duration, rawElements],
+  );
 
   const keyframeCache = usePlayerStore((s) => s.keyframeCache);
   useAutoExpandKeyframedClips(gsapAnimations);
@@ -293,14 +277,6 @@ export const Timeline = memo(function Timeline({
       toggleSelectedKeyframe,
     });
 
-  const selectedElement = useMemo(
-    () =>
-      expandedElements.find((element) => (element.key ?? element.id) === selectedElementId) ?? null,
-    [expandedElements, selectedElementId],
-  );
-  const selectedElementRef = useRef<TimelineElement | null>(selectedElement);
-  selectedElementRef.current = selectedElement;
-
   const {
     pps,
     fitPps,
@@ -399,41 +375,15 @@ export const Timeline = memo(function Timeline({
   });
   setRangeSelectionRef.current = setRangeSelection; // stable ref consumed by useTimelineClipDrag
 
-  const prevSelectedRef = useRef(selectedElementRef.current);
-  // eslint-disable-next-line no-restricted-syntax, react-hooks/exhaustive-deps
-  useEffect(() => {
-    const prev = prevSelectedRef.current;
-    const curr = selectedElementRef.current;
-    prevSelectedRef.current = curr;
-    if (prev && !curr) {
-      setShowPopover(false);
-      setRangeSelection(null);
-    }
-  });
-
-  // Frame display mode labels ruler ticks as frame numbers — pass the fps so ticks snap to frames.
-  const tickFps = timeDisplayMode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
-  const { major, minor } = useMemo(
-    () => generateTicks(displayDuration, pps, tickFps),
-    [displayDuration, pps, tickFps],
+  useTimelineSelectionLifecycle(expandedElements, selectedElementId, setShowPopover, () =>
+    setRangeSelection(null),
   );
+
+  const { major, minor } = useTimelineTicks(displayDuration, pps, timeDisplayMode);
   const majorTickInterval = major.length >= 2 ? major[1] - major[0] : effectiveDuration;
 
   const getPreviewElement = useCallback(
-    (element: TimelineElement): TimelineElement => {
-      if (
-        resizingClip &&
-        (resizingClip.element.key ?? resizingClip.element.id) === (element.key ?? element.id)
-      ) {
-        return {
-          ...element,
-          start: resizingClip.previewStart,
-          duration: resizingClip.previewDuration,
-          playbackStart: resizingClip.previewPlaybackStart,
-        };
-      }
-      return element;
-    },
+    (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
     [resizingClip],
   );
 

packages/studio/src/player/components/TimelineCanvas.tsx

@@ -20,7 +20,8 @@ import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import type { Rect } from "../../utils/marqueeGeometry";
 import { TimelineClip } from "./TimelineClip";
-import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
+import { TimelineLanes } from "./TimelineLanes";
+import type { TimelineLaneBaseProps } from "./TimelineLaneTypes";
 import { renderClipChildren } from "./timelineClipChildren";
 import { useTimelineRevealClip } from "./useTimelineRevealClip";
 import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";

packages/studio/src/player/components/TimelineLaneTypes.ts

@@ -0,0 +1,75 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
+import type { ReactNode } from "react";
+import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
+import type { TimelineTheme } from "./timelineTheme";
+import type { BlockedClipState, DraggedClipState, ResizingClipState } from "./useTimelineClipDrag";
+import type { TrackVisualStyle } from "./timelineIcons";
+import type { KeyframeCacheEntry, TimelineElement } from "../store/playerStore";
+
+/** Props shared by TimelineCanvas and its lane renderer. */
+export interface TimelineLaneBaseProps {
+  pps: number;
+  contentOrigin: number;
+  contentGutter: number;
+  trackContentWidth: number;
+  theme: TimelineTheme;
+  displayTrackOrder: number[];
+  rowHeights: readonly number[];
+  trackOrder: number[];
+  tracks: [number, TimelineElement[]][];
+  trackStyles: Map<number, TrackVisualStyle>;
+  laneCounts: ReadonlyMap<string, number>;
+  selectedElementId: string | null;
+  selectedElementIds: Set<string>;
+  hoveredClip: string | null;
+  draggedClip: DraggedClipState | null;
+  blockedClipRef: React.RefObject<BlockedClipState | null>;
+  suppressClickRef: React.RefObject<boolean>;
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  renderClipContent?: (
+    element: TimelineElement,
+    style: { clip: string; label: string },
+  ) => ReactNode;
+  renderClipOverlay?: (element: TimelineElement) => ReactNode;
+  onDrillDown?: (element: TimelineElement) => void;
+  onSelectElement?: (element: TimelineElement | null) => void;
+  setHoveredClip: (key: string | null) => void;
+  setShowPopover: (value: boolean) => void;
+  setRangeSelection: (value: null) => void;
+  setResizingClip: (value: ResizingClipState | null) => void;
+  setDraggedClip: (value: DraggedClipState | null) => void;
+  setSelectedElementId: (id: string | null) => void;
+  syncClipDragAutoScroll: (x: number, y: number) => void;
+  shiftClickClipRef: React.RefObject<{
+    element: TimelineElement;
+    anchorX: number;
+    anchorY: number;
+  } | null>;
+  getPreviewElement: (element: TimelineElement) => TimelineElement;
+  getTrackStyle: (tag: string) => TrackVisualStyle;
+  keyframeCache?: Map<string, KeyframeCacheEntry>;
+  gsapAnimations: Map<string, GsapAnimation[]>;
+  selectedKeyframes: Set<string>;
+  currentTime: number;
+  onSeek?: (time: number) => void;
+  onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
+  onClickKeyframe?: (element: TimelineElement, target: TimelineKeyframeTarget) => void;
+  onShiftClickKeyframe?: (elementId: string, target: TimelineKeyframeTarget) => void;
+  onContextMenuKeyframe?: (
+    event: React.MouseEvent,
+    elementId: string,
+    target: TimelineKeyframeTarget,
+  ) => void;
+  onMoveKeyframe?: (
+    elementId: string,
+    fromClipPercentage: number,
+    toClipPercentage: number,
+    propertyGroup?: string,
+    tweenPercentage?: number,
+    animationId?: string,
+  ) => Promise<boolean>;
+  onContextMenuClip?: (event: React.MouseEvent, element: TimelineElement) => void;
+  onContextMenuLane?: (event: React.MouseEvent, track: number, time: number) => void;
+  beatAnalysis?: MusicBeatAnalysis | null;
+}

packages/studio/src/player/components/TimelineLanes.tsx

@@ -1,111 +1,24 @@
-import { type ReactNode } from "react";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
 import { TimelineClip } from "./TimelineClip";
 import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
 import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { TimelineTrackHeader } from "./TimelineTrackHeader";
 import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
-import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
-import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 import { getTimelineEditCapabilities, resolveBlockedTimelineEditIntent } from "./timelineEditing";
-import type { TimelineTheme } from "./timelineTheme";
 import { CLIP_Y, CLIP_HANDLE_W, TRACK_H, getTimelineRowHeight } from "./timelineLayout";
-import {
-  usePlayerStore,
-  type TimelineElement,
-  type KeyframeCacheEntry,
-} from "../store/playerStore";
-import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import {
   isMultiDragPassenger,
   multiDragPassengerOffsetPx,
   type MultiDragPreviewInput,
 } from "./timelineMultiDragPreview";
-import type { TrackVisualStyle } from "./timelineIcons";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
 import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
 import { renderClipChildren } from "./timelineClipChildren";
-
-/**
- * Props shared by the scroll container ({@link TimelineCanvas}) and the lane
- * renderer below. TimelineCanvas passes these straight through via spread, so
- * they are declared once here and both prop types compose from this base — no
- * duplicated prop list.
- */
-export interface TimelineLaneBaseProps {
-  pps: number;
-  contentOrigin: number;
-  contentGutter: number;
-  trackContentWidth: number;
-  theme: TimelineTheme;
-  displayTrackOrder: number[];
-  rowHeights: readonly number[];
-  trackOrder: number[];
-  tracks: [number, TimelineElement[]][];
-  trackStyles: Map<number, TrackVisualStyle>;
-  laneCounts: ReadonlyMap<string, number>;
-  selectedElementId: string | null;
-  selectedElementIds: Set<string>;
-  hoveredClip: string | null;
-  draggedClip: DraggedClipState | null;
-  blockedClipRef: React.RefObject<BlockedClipState | null>;
-  suppressClickRef: React.RefObject<boolean>;
-  scrollRef: React.RefObject<HTMLDivElement | null>;
-  renderClipContent?: (
-    element: TimelineElement,
-    style: { clip: string; label: string },
-  ) => ReactNode;
-  renderClipOverlay?: (element: TimelineElement) => ReactNode;
-  onDrillDown?: (element: TimelineElement) => void;
-  onSelectElement?: (element: TimelineElement | null) => void;
-  setHoveredClip: (key: string | null) => void;
-  setShowPopover: (v: boolean) => void;
-  setRangeSelection: (v: null) => void;
-  setResizingClip: (v: ResizingClipState | null) => void;
-  setDraggedClip: (v: DraggedClipState | null) => void;
-  setSelectedElementId: (id: string | null) => void;
-  syncClipDragAutoScroll: (x: number, y: number) => void;
-  shiftClickClipRef: React.RefObject<{
-    element: TimelineElement;
-    anchorX: number;
-    anchorY: number;
-  } | null>;
-  getPreviewElement: (element: TimelineElement) => TimelineElement;
-  getTrackStyle: (tag: string) => TrackVisualStyle;
-  keyframeCache?: Map<string, KeyframeCacheEntry>;
-  gsapAnimations: Map<string, GsapAnimation[]>;
-  selectedKeyframes: Set<string>;
-  currentTime: number;
-  onSeek?: (time: number) => void;
-  onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
-  onClickKeyframe?: (element: TimelineElement, target: TimelineKeyframeTarget) => void;
-  onShiftClickKeyframe?: (elementId: string, target: TimelineKeyframeTarget) => void;
-  onContextMenuKeyframe?: (
-    e: React.MouseEvent,
-    elementId: string,
-    target: TimelineKeyframeTarget,
-  ) => void;
-  onMoveKeyframe?: (
-    elementId: string,
-    fromClipPercentage: number,
-    toClipPercentage: number,
-    propertyGroup?: string,
-    tweenPercentage?: number,
-    animationId?: string,
-  ) => Promise<boolean>;
-  onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
-  /**
-   * Right-click on EMPTY lane space (not on a clip — those preventDefault
-   * before this fires — not the gutter/ruler, not below the lanes). `time` is
-   * the timeline time (seconds) under the pointer on that lane.
-   */
-  onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
-  beatAnalysis?: MusicBeatAnalysis | null;
-}
+import type { TimelineLaneBaseProps } from "./TimelineLaneTypes";
 
 interface TimelineLanesProps extends TimelineLaneBaseProps {
   /** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */