@hyperframes/studio 0.8.55 → 0.8.57

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

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { TimelineClip } from "./TimelineClip";
 import type { TimelineEditCapabilities } from "./timelineEditing";
+import { defaultTimelineTheme, type TimelineTheme } from "./timelineTheme";
 
 Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
   configurable: true,
@@ -27,11 +28,13 @@ function renderClip({
   pps = 100,
   isSelected = false,
   hasCustomContent = true,
+  theme = defaultTimelineTheme,
 }: {
   element: TimelineElement;
   pps?: number;
   isSelected?: boolean;
   hasCustomContent?: boolean;
+  theme?: TimelineTheme;
 }) {
   const host = document.createElement("div");
   document.body.append(host);
@@ -48,6 +51,7 @@ function renderClip({
         isHovered={false}
         hasCustomContent={hasCustomContent}
         capabilities={capabilities}
+        theme={theme}
         isComposition={false}
         onHoverStart={vi.fn()}
         onHoverEnd={vi.fn()}
@@ -115,6 +119,54 @@ describe("TimelineClip", () => {
     act(() => root.unmount());
   });
 
+  it("passes clip and handle theme tokens to the rendered elements", () => {
+    const theme: TimelineTheme = {
+      ...defaultTimelineTheme,
+      clipBackground: "var(--test-clip-bg)",
+      clipBackgroundActive: "var(--test-clip-bg-active)",
+      clipBackgroundHover: "var(--test-clip-bg-hover)",
+      clipBackgroundDragging: "var(--test-clip-bg-dragging)",
+      clipBorder: "var(--test-clip-border)",
+      clipBorderHover: "var(--test-clip-border-hover)",
+      clipBorderActive: "var(--test-clip-border-active)",
+      handleColor: "var(--test-handle)",
+    };
+    const { host, root } = renderClip({
+      element: { id: "themed", label: "Themed", tag: "div", start: 0, duration: 1, track: 0 },
+      isSelected: true,
+      theme,
+    });
+    const clip = host.querySelector<HTMLElement>(".timeline-clip")!;
+    expect(clip.style.getPropertyValue("--clip-bg")).toBe("var(--test-clip-bg)");
+    expect(clip.style.getPropertyValue("--clip-border-active")).toBe(
+      "var(--test-clip-border-active)",
+    );
+    expect(clip.style.getPropertyValue("--clip-handle")).toBe("var(--test-handle)");
+    expect(clip.querySelector<HTMLElement>(".timeline-clip__handle-bar")?.style.background).toBe(
+      "var(--clip-handle)",
+    );
+    act(() => root.unmount());
+  });
+
+  it("keeps default token references off the properties they resolve", () => {
+    const { host, root } = renderClip({
+      element: {
+        id: "default-theme",
+        label: "Default",
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: 0,
+      },
+      isSelected: true,
+    });
+    const clip = host.querySelector<HTMLElement>(".timeline-clip")!;
+    expect(clip.style.getPropertyValue("--clip-bg")).toBe("var(--timeline-clip-bg)");
+    expect(clip.style.getPropertyValue("--clip-bg")).not.toBe("var(--clip-bg)");
+    expect(clip.style.getPropertyValue("--clip-handle")).toBe("var(--timeline-handle)");
+    act(() => root.unmount());
+  });
+
   it("is a roving native button with explicit selection semantics", () => {
     const { host, onClick, root } = renderClip({
       element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 2, track: 0 },

package/src/player/components/TimelineClip.tsx

@@ -64,6 +64,16 @@ export const TimelineClip = memo(function TimelineClip({
   const showDefaultText = !hasCustomContent && (widthPx >= 40 || isSelected);
   const startLabel = el.start.toFixed(1);
   const endLabel = (el.start + el.duration).toFixed(1);
+  const themeVariables = {
+    "--clip-bg": theme.clipBackground,
+    "--clip-bg-active": theme.clipBackgroundActive,
+    "--clip-bg-hover": theme.clipBackgroundHover,
+    "--clip-bg-dragging": theme.clipBackgroundDragging,
+    "--clip-border": theme.clipBorder,
+    "--clip-border-hover": theme.clipBorderHover,
+    "--clip-border-active": theme.clipBorderActive,
+    "--clip-handle": theme.handleColor,
+  } as CSSProperties;
   const clipClassName = [
     "timeline-clip",
     "absolute",
@@ -81,6 +91,7 @@ export const TimelineClip = memo(function TimelineClip({
     top: clipY,
     ...(clipHeight === undefined ? { bottom: clipY } : { height: clipHeight }),
     borderRadius: theme.clipRadius,
+    ...themeVariables,
     zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
     // Regular cursor over clips (CapCut-style, user preference) — no grab hand.
     cursor: "default",
@@ -144,7 +155,7 @@ export const TimelineClip = memo(function TimelineClip({
               bottom: 6,
               width: 2,
               borderRadius: 1,
-              background: "rgba(255, 255, 255, 0.55)",
+              background: "var(--clip-handle)",
               opacity: handleOpacity * 0.6,
             }}
           />
@@ -174,7 +185,7 @@ export const TimelineClip = memo(function TimelineClip({
               bottom: 6,
               width: 2,
               borderRadius: 1,
-              background: "rgba(255, 255, 255, 0.55)",
+              background: "var(--clip-handle)",
               opacity: handleOpacity * 0.6,
             }}
           />

package/src/player/components/TimelineOverlays.test.ts

@@ -1,19 +1,22 @@
 // @vitest-environment happy-dom
 import { act, createElement } from "react";
-import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
 import { type KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
 import { TimelineOverlays, resolveTimelineContextElement } from "./TimelineOverlays";
+import {
+  TimelineContextProvider,
+  type TimelineContextValue,
+  type TimelineOverlaysState,
+} from "./TimelineProvider";
 import { defaultTimelineTheme } from "./timelineTheme";
+import { createHappyDomRootHarness } from "./testRootHarness";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-const roots: Root[] = [];
+const { mount } = createHappyDomRootHarness();
 afterEach(() => {
-  for (const root of roots.splice(0)) act(() => root.unmount());
-  document.body.innerHTML = "";
   usePlayerStore.setState({ selectedElementId: null, timelineSessionEpoch: 0 });
 });
 
@@ -76,8 +79,7 @@ function renderKeyframeOverlay(options: {
 }) {
   const container = document.createElement("div");
   document.body.appendChild(container);
-  const root = createRoot(container);
-  roots.push(root);
+  const root = mount(container);
   const elements = [options.currentElement];
   const setKfContextMenu = options.setKfContextMenu ?? vi.fn();
   const onDeleteAllKeyframes = options.onDeleteAllKeyframes ?? vi.fn();
@@ -90,6 +92,64 @@ function renderKeyframeOverlay(options: {
     percentage: 50,
     animationId: "child-position",
   };
+  const overlays = {
+    elements,
+    elementsRef: { current: elements },
+    theme: defaultTimelineTheme,
+    showShortcutHint: false,
+    showPopover: false,
+    rangeSelection: null,
+    setShowPopover: vi.fn(),
+    setRangeSelection: vi.fn(),
+    kfContextMenu: menu,
+    setKfContextMenu,
+    onDeleteKeyframe: vi.fn(),
+    onDeleteAllKeyframes,
+    onMoveKeyframeToPlayhead: vi.fn(),
+    clipContextMenu: null,
+    setClipContextMenu: vi.fn(),
+    currentTime: 0,
+    onSplitElement: vi.fn(),
+    pinZoomBeforeEdit: vi.fn(),
+    onDeleteElement: vi.fn(),
+    gapContextMenu: null,
+    onDismissGapContextMenu: vi.fn(),
+    onCloseTrackGap: vi.fn(),
+    onCloseAllTrackGaps: vi.fn(),
+    onHoverGapAction: vi.fn(),
+  } satisfies TimelineOverlaysState;
+  const contextValue = {
+    state: {
+      timelineReady: true,
+      elements,
+      selectedElementId: null,
+      sessionEpoch: 0,
+      keyframeCache: new Map(),
+      canvas: {} as TimelineContextValue["state"]["canvas"],
+      overlays,
+    },
+    actions: {
+      renderClipContent: undefined,
+      renderClipOverlay: undefined,
+      setFocusedEaseSegment: vi.fn(),
+    },
+    meta: {} as TimelineContextValue["meta"],
+  } satisfies TimelineContextValue;
+
+  function TestTimelineContext({ value }: { value: TimelineContextValue }) {
+    const selectedElementId = usePlayerStore((state) => state.selectedElementId);
+    const sessionEpoch = usePlayerStore((state) => state.timelineSessionEpoch);
+    return createElement(
+      TimelineContextProvider,
+      {
+        value: {
+          ...value,
+          state: { ...value.state, selectedElementId, sessionEpoch },
+        },
+      },
+      createElement(TimelineOverlays),
+    );
+  }
 
   act(() => {
     usePlayerStore.setState({
@@ -97,32 +157,7 @@ function renderKeyframeOverlay(options: {
       timelineSessionEpoch: 2,
     });
     root.render(
-      createElement(TimelineOverlays, {
-        elements,
-        elementsRef: { current: elements },
-        theme: defaultTimelineTheme,
-        showShortcutHint: false,
-        showPopover: false,
-        rangeSelection: null,
-        setShowPopover: vi.fn(),
-        setRangeSelection: vi.fn(),
-        kfContextMenu: menu,
-        setKfContextMenu,
-        onDeleteKeyframe: vi.fn(),
-        onDeleteAllKeyframes,
-        onMoveKeyframeToPlayhead: vi.fn(),
-        clipContextMenu: null,
-        setClipContextMenu: vi.fn(),
-        currentTime: 0,
-        onSplitElement: vi.fn(),
-        pinZoomBeforeEdit: vi.fn(),
-        onDeleteElement: vi.fn(),
-        gapContextMenu: null,
-        onDismissGapContextMenu: vi.fn(),
-        onCloseTrackGap: vi.fn(),
-        onCloseAllTrackGaps: vi.fn(),
-        onHoverGapAction: vi.fn(),
-      }),
+      createElement(TestTimelineContext, { value: contextValue }, createElement(TimelineOverlays)),
     );
   });
   return { setKfContextMenu, onDeleteAllKeyframes };

package/src/player/components/TimelineOverlays.tsx

@@ -1,67 +1,13 @@
-import { useEffect, type MutableRefObject } from "react";
+import { useEffect } from "react";
 import type { TimelineElement } from "../store/playerStore";
-import { usePlayerStore } from "../store/playerStore";
-import type { TimelineTheme } from "./timelineTheme";
-import type { TimelineRangeSelection } from "./timelineEditing";
-import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { EditPopover } from "./EditModal";
-import {
-  KeyframeDiamondContextMenu,
-  type KeyframeDiamondContextMenuState,
-} from "./KeyframeDiamondContextMenu";
+import { KeyframeDiamondContextMenu } from "./KeyframeDiamondContextMenu";
 import { ClipContextMenu } from "./ClipContextMenu";
 import { TrackGapContextMenu } from "./TrackGapContextMenu";
 import { TimelineShortcutHint } from "./TimelineShortcutHint";
 import { copyTextToClipboard } from "../../utils/clipboard";
 import { trackStudioSegmentEaseEdit } from "../../telemetry/events";
-
-export interface ClipContextMenuState {
-  x: number;
-  y: number;
-  element: TimelineElement;
-  sessionEpoch: number;
-}
-
-/** Resolved model for the empty-lane-space (track gap) context menu. */
-interface TrackGapContextMenuState {
-  x: number;
-  y: number;
-  gapWidth: number | null;
-  canCloseGap: boolean;
-  canCloseAllGaps: boolean;
-  hasAnyGaps: boolean;
-}
-
-interface TimelineOverlaysProps {
-  elements: readonly TimelineElement[];
-  elementsRef: MutableRefObject<readonly TimelineElement[]>;
-  theme: TimelineTheme;
-  showShortcutHint: boolean;
-  showPopover: boolean;
-  rangeSelection: TimelineRangeSelection | null;
-  setShowPopover: (value: boolean) => void;
-  setRangeSelection: (value: TimelineRangeSelection | null) => void;
-  kfContextMenu: KeyframeDiamondContextMenuState | null;
-  setKfContextMenu: (value: KeyframeDiamondContextMenuState | null) => void;
-  onDeleteKeyframe: TimelineEditCallbacks["onDeleteKeyframe"];
-  onDeleteAllKeyframes: TimelineEditCallbacks["onDeleteAllKeyframes"];
-  onMoveKeyframeToPlayhead: TimelineEditCallbacks["onMoveKeyframeToPlayhead"];
-  clipContextMenu: ClipContextMenuState | null;
-  setClipContextMenu: (value: ClipContextMenuState | null) => void;
-  currentTime: number;
-  onSplitElement: TimelineEditCallbacks["onSplitElement"];
-  pinZoomBeforeEdit: () => void;
-  onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
-  onCopyClip?: () => boolean;
-  onPasteClip?: () => Promise<void>;
-  onDuplicateClip?: () => Promise<boolean>;
-  canPasteClip?: () => boolean;
-  gapContextMenu: TrackGapContextMenuState | null;
-  onDismissGapContextMenu: () => void;
-  onCloseTrackGap: () => void;
-  onCloseAllTrackGaps: () => void;
-  onHoverGapAction: (action: "close-gap" | "close-all" | null) => void;
-}
+import { useTimelineContext } from "./TimelineProvider";
 
 interface TimelineContextTargetInput {
   capturedElement: TimelineElement;
@@ -85,56 +31,43 @@ export function resolveTimelineContextElement({
   return elements.find((element) => (element.key ?? element.id) === identity) ?? null;
 }
 
-function readTimelineContextElement(
-  capturedElement: TimelineElement,
-  targetSessionEpoch: number | undefined,
-  elements: readonly TimelineElement[],
-): TimelineElement | null {
-  const state = usePlayerStore.getState();
-  return resolveTimelineContextElement({
-    capturedElement,
-    targetSessionEpoch,
-    sessionEpoch: state.timelineSessionEpoch,
-    selectedElementId: state.selectedElementId,
-    elements,
-  });
-}
-
 // The timeline's floating overlays, rendered as siblings above the scroll area:
 // the shortcut hint, the range-edit popover, the keyframe-diamond context menu,
 // and the clip context menu.
-export function TimelineOverlays({
-  elements,
-  elementsRef,
-  theme,
-  showShortcutHint,
-  showPopover,
-  rangeSelection,
-  setShowPopover,
-  setRangeSelection,
-  kfContextMenu,
-  setKfContextMenu,
-  onDeleteKeyframe,
-  onDeleteAllKeyframes,
-  onMoveKeyframeToPlayhead,
-  clipContextMenu,
-  setClipContextMenu,
-  currentTime,
-  onSplitElement,
-  pinZoomBeforeEdit,
-  onDeleteElement,
-  onCopyClip,
-  onPasteClip,
-  onDuplicateClip,
-  canPasteClip,
-  gapContextMenu,
-  onDismissGapContextMenu,
-  onCloseTrackGap,
-  onCloseAllTrackGaps,
-  onHoverGapAction,
-}: TimelineOverlaysProps) {
-  const selectedElementId = usePlayerStore((state) => state.selectedElementId);
-  const sessionEpoch = usePlayerStore((state) => state.timelineSessionEpoch);
+export function TimelineOverlays() {
+  const { state, actions } = useTimelineContext();
+  const overlayProps = state.overlays;
+  const {
+    elements,
+    elementsRef,
+    theme,
+    showShortcutHint,
+    showPopover,
+    rangeSelection,
+    setShowPopover,
+    setRangeSelection,
+    kfContextMenu,
+    setKfContextMenu,
+    onDeleteKeyframe,
+    onDeleteAllKeyframes,
+    onMoveKeyframeToPlayhead,
+    clipContextMenu,
+    setClipContextMenu,
+    currentTime,
+    onSplitElement,
+    pinZoomBeforeEdit,
+    onDeleteElement,
+    onCopyClip,
+    onPasteClip,
+    onDuplicateClip,
+    canPasteClip,
+    gapContextMenu,
+    onDismissGapContextMenu,
+    onCloseTrackGap,
+    onCloseAllTrackGaps,
+    onHoverGapAction,
+  } = overlayProps;
+  const { selectedElementId, sessionEpoch, keyframeCache } = state;
   const kfTargetSessionEpoch = kfContextMenu?.sessionEpoch;
   const clipTargetSessionEpoch = clipContextMenu?.sessionEpoch;
   const keyframeElement = kfContextMenu
@@ -156,7 +89,13 @@ export function TimelineOverlays({
       })
     : null;
   const readCurrentElement = (element: TimelineElement, targetSessionEpoch: number | undefined) =>
-    readTimelineContextElement(element, targetSessionEpoch, elementsRef.current);
+    resolveTimelineContextElement({
+      capturedElement: element,
+      targetSessionEpoch,
+      sessionEpoch,
+      selectedElementId,
+      elements: elementsRef.current,
+    });
 
   useEffect(() => {
     if (kfContextMenu && !keyframeElement) setKfContextMenu(null);
@@ -217,7 +156,7 @@ export function TimelineOverlays({
                   ) {
                     return;
                   }
-                  usePlayerStore.getState().setFocusedEaseSegment({
+                  actions.setFocusedEaseSegment({
                     animationId: keyframe.animationId,
                     collidingAnimationTargets: keyframe.collidingAnimationTargets,
                     tweenPercentage: keyframe.tweenPercentage,
@@ -228,7 +167,7 @@ export function TimelineOverlays({
               : undefined
           }
           onCopyProperties={(elementId, keyframe) => {
-            const entry = usePlayerStore.getState().keyframeCache.get(elementId);
+            const entry = keyframeCache.get(elementId);
             // Tolerance match on clip-%, the same basis the cache is keyed on —
             // an exact float compare misses a keyframe the menu just opened over.
             const kf = entry?.keyframes.find(

package/src/player/components/TimelineProvider.tsx

@@ -0,0 +1,191 @@
+import {
+  createContext,
+  useContext,
+  type ComponentProps,
+  type CSSProperties,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactNode,
+  type RefCallback,
+  type UIEvent,
+} from "react";
+import type { TimelineEmptyState } from "./TimelineEmptyState";
+import type { TimelineProps } from "./TimelineTypes";
+import type { TimelineRangeSelection } from "./timelineEditing";
+import type { TimelineDropPlacement } from "./timelineCallbacks";
+import type { Rect } from "../../utils/marqueeGeometry";
+import type { ResizingClipState } from "./useTimelineClipDrag";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
+import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
+import type { TimelineElement } from "../store/playerStore";
+import type { KeyframeCacheEntry } from "../store/keyframeSlice";
+import type { AnimationKeyframeTarget } from "../../hooks/gsapTweenSynth";
+import type { TimelineTheme } from "./timelineTheme";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
+import { useTimelineProviderState } from "./useTimelineProviderState";
+
+export type TimelineCanvasState = Omit<
+  TimelineLaneBaseProps,
+  | "setRangeSelection"
+  | "setResizingClip"
+  | "setDraggedClip"
+  | "renderClipContent"
+  | "renderClipOverlay"
+> & {
+  major: number[];
+  minor: number[];
+  totalH: number;
+  effectiveDuration: number;
+  majorTickInterval: number;
+  rangeSelection: TimelineRangeSelection | null;
+  marqueeRect: Rect | null;
+  resizingClip: ResizingClipState | null;
+  isScrubbing: boolean;
+  playheadRef: React.RefObject<HTMLDivElement | null>;
+  laneGapStrips: TimelineLaneGapStrips[];
+  dropPreview: TimelineDropPlacement | null;
+  setRangeSelection: (value: TimelineRangeSelection | null) => void;
+  setResizingClip: (value: ResizingClipState | null) => void;
+  setDraggedClip: (value: TimelineLaneBaseProps["draggedClip"]) => void;
+  beatDragging: boolean;
+  onResizeElement: TimelineEditCallbacks["onResizeElement"];
+  onMoveElement: TimelineEditCallbacks["onMoveElement"];
+};
+
+export interface ClipContextMenuState {
+  x: number;
+  y: number;
+  element: TimelineElement;
+  sessionEpoch: number;
+}
+
+export interface TrackGapContextMenuState {
+  x: number;
+  y: number;
+  gapWidth: number | null;
+  canCloseGap: boolean;
+  canCloseAllGaps: boolean;
+  hasAnyGaps: boolean;
+}
+
+export interface TimelineOverlaysState {
+  elements: readonly TimelineElement[];
+  elementsRef: { current: readonly TimelineElement[] };
+  theme: TimelineTheme;
+  showShortcutHint: boolean;
+  showPopover: boolean;
+  rangeSelection: TimelineRangeSelection | null;
+  setShowPopover: (value: boolean) => void;
+  setRangeSelection: (value: TimelineRangeSelection | null) => void;
+  kfContextMenu: KeyframeDiamondContextMenuState | null;
+  setKfContextMenu: (value: KeyframeDiamondContextMenuState | null) => void;
+  onDeleteKeyframe: TimelineEditCallbacks["onDeleteKeyframe"];
+  onDeleteAllKeyframes: TimelineEditCallbacks["onDeleteAllKeyframes"];
+  onMoveKeyframeToPlayhead: TimelineEditCallbacks["onMoveKeyframeToPlayhead"];
+  clipContextMenu: ClipContextMenuState | null;
+  setClipContextMenu: (value: ClipContextMenuState | null) => void;
+  currentTime: number;
+  onSplitElement: TimelineEditCallbacks["onSplitElement"];
+  pinZoomBeforeEdit: () => void;
+  onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
+  onCopyClip?: () => boolean;
+  onPasteClip?: () => Promise<void>;
+  onDuplicateClip?: () => Promise<boolean>;
+  canPasteClip?: () => boolean;
+  gapContextMenu: TrackGapContextMenuState | null;
+  onDismissGapContextMenu: () => void;
+  onCloseTrackGap: () => void;
+  onCloseAllTrackGaps: () => void;
+  onHoverGapAction: (action: "close-gap" | "close-all" | null) => void;
+}
+
+export interface TimelineContainerProps {
+  ref: RefCallback<HTMLDivElement>;
+  "aria-label": string;
+  "data-timeline-element-count": number;
+  className: string;
+  onMouseMove: (event: MouseEvent<HTMLDivElement>) => void;
+  onMouseLeave: () => void;
+  style: CSSProperties;
+}
+
+export interface TimelineViewportProps {
+  ref: RefCallback<HTMLDivElement>;
+  "data-timeline-scroll-viewport": boolean;
+  "data-timeline-auto-scroll-left-inset": number;
+  tabIndex: number;
+  className: string;
+  onScroll: (event: UIEvent<HTMLDivElement>) => void;
+  onFocus: (event: React.FocusEvent<HTMLDivElement>) => void;
+  onBlur: (event: React.FocusEvent<HTMLDivElement>) => void;
+  onDragOver: (event: React.DragEvent<HTMLDivElement>) => void;
+  onDragLeave: (event: React.DragEvent<HTMLDivElement>) => void;
+  onDrop: (event: React.DragEvent<HTMLDivElement>) => void;
+  onPointerDown: (event: PointerEvent<HTMLDivElement>) => void;
+  onPointerMove: (event: PointerEvent<HTMLDivElement>) => void;
+  onPointerUp: (event: PointerEvent<HTMLDivElement>) => void;
+  onPointerCancel: (event: PointerEvent<HTMLDivElement>) => void;
+  onLostPointerCapture: (event: PointerEvent<HTMLDivElement>) => void;
+}
+
+export interface TimelineState {
+  timelineReady: boolean;
+  elements: readonly TimelineElement[];
+  selectedElementId: string | null;
+  sessionEpoch: number;
+  keyframeCache: Map<string, KeyframeCacheEntry>;
+  canvas: TimelineCanvasState;
+  overlays: TimelineOverlaysState;
+}
+
+export interface TimelineActions {
+  renderClipContent: TimelineLaneBaseProps["renderClipContent"];
+  renderClipOverlay: TimelineLaneBaseProps["renderClipOverlay"];
+  setFocusedEaseSegment: (target: {
+    animationId: string;
+    collidingAnimationTargets?: AnimationKeyframeTarget[];
+    tweenPercentage: number;
+    elementId: string;
+  }) => void;
+}
+
+export interface TimelineMeta {
+  emptyState: ComponentProps<typeof TimelineEmptyState>;
+  containerProps: TimelineContainerProps;
+  viewportProps: TimelineViewportProps;
+  razorGuide: ReactNode;
+}
+
+export interface TimelineContextValue {
+  state: TimelineState;
+  actions: TimelineActions;
+  meta: TimelineMeta;
+}
+
+const TimelineContext = createContext<TimelineContextValue | null>(null);
+
+export function TimelineProvider({ children, ...props }: TimelineProps & { children: ReactNode }) {
+  const value = useTimelineProviderState(props);
+  return <TimelineContext.Provider value={value}>{children}</TimelineContext.Provider>;
+}
+
+export function TimelineContextProvider({
+  value,
+  children,
+}: {
+  value: TimelineContextValue;
+  children: ReactNode;
+}) {
+  return <TimelineContext.Provider value={value}>{children}</TimelineContext.Provider>;
+}
+
+export function useTimelineContext(): TimelineContextValue {
+  const value = useTimelineContextOptional();
+  if (value === null) throw new Error("useTimelineContext must be used inside TimelineProvider");
+  return value;
+}
+
+function useTimelineContextOptional(): TimelineContextValue | null {
+  return useContext(TimelineContext);
+}