@hyperframes/studio 0.8.57 → 0.8.59

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

@@ -0,0 +1,101 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineContextValue } from "./TimelineProvider";
+import { TimelineContextProvider, useTimelineContext } from "./TimelineProvider";
+import { TimelineClipMenu, TimelineLanes, TimelinePlayhead, TimelineRuler } from "./TimelineParts";
+import { createHappyDomRootHarness } from "./testRootHarness";
+
+vi.mock("./TimelineRuler", () => ({
+  TimelineRuler: () => <div data-testid="timeline-ruler" />,
+}));
+vi.mock("./TimelineLanes", () => ({
+  TimelineLanes: ({ renderClipContent }: { renderClipContent?: unknown }) => {
+    const { state } = useTimelineContext();
+    return (
+      <div data-testid="timeline-clip">
+        {state.elements[0]?.id}
+        {renderClipContent ? <span data-testid="lane-render-bridge" /> : null}
+      </div>
+    );
+  },
+}));
+
+const { mount } = createHappyDomRootHarness();
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("Timeline parts composition", () => {
+  it("reads a shared provider context when composed without Timeline or Frame", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = mount(host);
+    const onSplitElement = vi.fn();
+    const element = { id: "clip-a", key: "clip-a", tag: "video", start: 0, duration: 2, track: 0 };
+    const value = {
+      state: {
+        timelineReady: true,
+        elements: [element],
+        selectedElementId: "clip-a",
+        sessionEpoch: 1,
+        keyframeCache: new Map(),
+        canvas: { isScrubbing: false } as TimelineContextValue["state"]["canvas"],
+        overlays: {
+          elements: [element],
+          elementsRef: { current: [element] },
+          theme: {} as TimelineContextValue["state"]["overlays"]["theme"],
+          showShortcutHint: false,
+          showPopover: false,
+          rangeSelection: null,
+          setShowPopover: vi.fn(),
+          setRangeSelection: vi.fn(),
+          kfContextMenu: null,
+          setKfContextMenu: vi.fn(),
+          onDeleteKeyframe: vi.fn(),
+          onDeleteAllKeyframes: vi.fn(),
+          onMoveKeyframeToPlayhead: vi.fn(),
+          clipContextMenu: { x: 10, y: 10, element, sessionEpoch: 1 },
+          setClipContextMenu: vi.fn(),
+          currentTime: 1,
+          onSplitElement,
+          pinZoomBeforeEdit: vi.fn(),
+          gapContextMenu: null,
+          onDismissGapContextMenu: vi.fn(),
+          onCloseTrackGap: vi.fn(),
+          onCloseAllTrackGaps: vi.fn(),
+          onHoverGapAction: vi.fn(),
+        },
+      },
+      actions: {
+        renderClipContent: vi.fn(),
+        renderClipOverlay: undefined,
+        setFocusedEaseSegment: vi.fn(),
+      },
+      meta: { razorGuide: null } as TimelineContextValue["meta"],
+    } satisfies TimelineContextValue;
+
+    try {
+      act(() => {
+        root.render(
+          <TimelineContextProvider value={value}>
+            <TimelineRuler />
+            <TimelineLanes />
+            <TimelinePlayhead />
+            <TimelineClipMenu />
+          </TimelineContextProvider>,
+        );
+      });
+
+      expect(host.querySelector("[data-testid='timeline-ruler']")).not.toBeNull();
+      expect(host.querySelector("[data-testid='timeline-clip']")?.textContent).toBe("clip-a");
+      expect(host.querySelector("[data-testid='lane-render-bridge']")).not.toBeNull();
+      expect(document.querySelector("[role='menu'][aria-label='Clip actions']")).not.toBeNull();
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});

package/src/player/components/TimelineParts.tsx

@@ -0,0 +1,74 @@
+import { TimelineCanvas as TimelineCanvasImpl } from "./TimelineCanvas";
+import {
+  TimelineClipMenuOverlay as TimelineClipMenuImpl,
+  TimelineEditPopoverOverlay as TimelineEditPopoverImpl,
+  TimelineGapMenuOverlay as TimelineGapMenuImpl,
+  TimelineKeyframeMenuOverlay as TimelineKeyframeMenuImpl,
+  TimelineShortcutHintOverlay as TimelineShortcutHintImpl,
+} from "./TimelineOverlays";
+import { TimelineLanes as TimelineLanesImpl } from "./TimelineLanes";
+import { PlayheadIndicator } from "./PlayheadIndicator";
+import { useTimelineContext } from "./TimelineProvider";
+import { TimelineEmptyState } from "./TimelineEmptyState";
+import { TimelineRulerPart } from "./TimelineRulerPart";
+
+/** The provider-backed canvas shell. */
+export function TimelineFrame() {
+  return <TimelineCanvasImpl />;
+}
+
+/** The provider-backed ruler. */
+export const TimelineRuler = TimelineRulerPart;
+
+/**
+ * The provider-backed lane renderer. TimelineFrame remains the composed Studio
+ * canvas; this part is exported for hosts that own the canvas arrangement.
+ */
+export function TimelineLanes() {
+  const { state, actions } = useTimelineContext();
+  const props = state.canvas;
+  return (
+    <TimelineLanesImpl
+      {...props}
+      renderClipContent={actions.renderClipContent}
+      renderClipOverlay={actions.renderClipOverlay}
+    />
+  );
+}
+
+/** The provider-backed playhead indicator. */
+export function TimelinePlayhead() {
+  const { state } = useTimelineContext();
+  const props = state.canvas;
+  return <PlayheadIndicator scrubbing={props.isScrubbing} />;
+}
+
+/** The provider-backed razor guide. */
+export function TimelineRazorGuide() {
+  const { meta } = useTimelineContext();
+  return meta.razorGuide;
+}
+
+/** The composed overlay surface used by the Studio variant. */
+export { TimelineOverlays } from "./TimelineOverlays";
+
+export function TimelineEmptyStatePart() {
+  const { meta } = useTimelineContext();
+  return <TimelineEmptyState {...meta.emptyState} />;
+}
+
+export function TimelineShortcutHint() {
+  return <TimelineShortcutHintImpl />;
+}
+export function TimelineEditPopover() {
+  return <TimelineEditPopoverImpl />;
+}
+export function TimelineClipMenu() {
+  return <TimelineClipMenuImpl />;
+}
+export function TimelineKeyframeMenu() {
+  return <TimelineKeyframeMenuImpl />;
+}
+export function TimelineGapMenu() {
+  return <TimelineGapMenuImpl />;
+}

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

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { Timeline } from "./Timeline";
+import { usePlayerStore } from "../store/playerStore";
+import { useTimelineContext } from "./TimelineProvider";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+function TimelinePartsVariant() {
+  const { meta } = useTimelineContext();
+  return React.createElement(
+    "div",
+    meta.containerProps,
+    React.createElement(
+      "div",
+      meta.viewportProps,
+      React.createElement(Timeline.Frame),
+      React.createElement(Timeline.RazorGuide),
+    ),
+    React.createElement(Timeline.Overlays),
+  );
+}
+
+describe("Timeline provider boundary", () => {
+  it("keeps the composed Timeline markup equal to its provider parts", () => {
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      elements: [{ id: "parity-clip", tag: "div", start: 0, duration: 2, track: 0 }],
+    });
+    const composedHost = document.createElement("div");
+    const partsHost = document.createElement("div");
+    document.body.append(composedHost, partsHost);
+    const composedRoot = createRoot(composedHost);
+    const partsRoot = createRoot(partsHost);
+    act(() => {
+      composedRoot.render(React.createElement(Timeline));
+      partsRoot.render(
+        React.createElement(Timeline.Provider, null, React.createElement(TimelinePartsVariant)),
+      );
+    });
+    const normalizeMarkup = (markup: string) =>
+      markup.replaceAll(/timeline-lanes_[^"]+/g, "timeline-lanes");
+    expect(normalizeMarkup(partsHost.innerHTML)).toBe(normalizeMarkup(composedHost.innerHTML));
+    act(() => {
+      composedRoot.unmount();
+      partsRoot.unmount();
+    });
+  });
+});

package/src/player/components/TimelineProvider.tsx

@@ -17,6 +17,8 @@ import type { Rect } from "../../utils/marqueeGeometry";
 import type { ResizingClipState } from "./useTimelineClipDrag";
 import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import type { TimelineSnapTarget } from "./timelineSnapping";
 import type { TimelineElement } from "../store/playerStore";
 import type { KeyframeCacheEntry } from "../store/keyframeSlice";
 import type { AnimationKeyframeTarget } from "../../hooks/gsapTweenSynth";
@@ -24,6 +26,10 @@ import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import type { KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
 import { useTimelineProviderState } from "./useTimelineProviderState";
+import {
+  TimelineEditProvider,
+  useTimelineEditContextValue,
+} from "../../contexts/TimelineEditContext";
 
 export type TimelineCanvasState = Omit<
   TimelineLaneBaseProps,
@@ -51,6 +57,13 @@ export type TimelineCanvasState = Omit<
   beatDragging: boolean;
   onResizeElement: TimelineEditCallbacks["onResizeElement"];
   onMoveElement: TimelineEditCallbacks["onMoveElement"];
+  draggedElement: TimelineElement | null;
+  snapGuide: TimelineSnapTarget | null;
+  multiDragPreview: MultiDragPreviewInput | null;
+  onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+  onTogglePropertyGroupKeyframe: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  onRazorSplit: TimelineEditCallbacks["onRazorSplit"];
+  onRazorSplitAll: TimelineEditCallbacks["onRazorSplitAll"];
 };
 
 export interface ClipContextMenuState {
@@ -166,6 +179,18 @@ export interface TimelineContextValue {
 const TimelineContext = createContext<TimelineContextValue | null>(null);
 
 export function TimelineProvider({ children, ...props }: TimelineProps & { children: ReactNode }) {
+  const editContext = useTimelineEditContextValue();
+  if (!editContext) {
+    return (
+      <TimelineEditProvider value={props}>
+        <TimelineProviderState {...props}>{children}</TimelineProviderState>
+      </TimelineEditProvider>
+    );
+  }
+  return <TimelineProviderState {...props}>{children}</TimelineProviderState>;
+}
+
+function TimelineProviderState({ children, ...props }: TimelineProps & { children: ReactNode }) {
   const value = useTimelineProviderState(props);
   return <TimelineContext.Provider value={value}>{children}</TimelineContext.Provider>;
 }

package/src/player/components/TimelineRazorInteraction.tsx

@@ -50,7 +50,7 @@ export function useTimelineRazorInteraction({
   return { razorGuideX, updateRazorGuide, clearRazorGuide, splitAllAtPointer };
 }
 
-export function TimelineRazorGuide({ x }: { x: number }) {
+export function TimelineRazorGuideOverlay({ x }: { x: number }) {
   return (
     <div
       className="absolute top-0 bottom-0 pointer-events-none z-10"

package/src/player/components/TimelineRulerPart.tsx

@@ -0,0 +1,22 @@
+import { TimelineRuler as TimelineRulerImpl } from "./TimelineRuler";
+import { useTimelineContext } from "./TimelineProvider";
+
+export function TimelineRulerPart() {
+  const { state } = useTimelineContext();
+  const props = state.canvas;
+  return (
+    <TimelineRulerImpl
+      major={props.major}
+      minor={props.minor}
+      pps={props.pps}
+      trackContentWidth={props.trackContentWidth}
+      totalH={props.totalH}
+      effectiveDuration={props.effectiveDuration}
+      majorTickInterval={props.majorTickInterval}
+      theme={props.theme}
+      beatAnalysis={props.beatAnalysis}
+      contentOrigin={props.contentOrigin}
+      renderTimeRange={props.rowsVirtualized ? props.renderTimeRange : undefined}
+    />
+  );
+}

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

@@ -136,4 +136,14 @@ describe("PlainTrackHeader", () => {
     expect(labelOf(view.host)).toBe("Hide track 1");
     view.unmount();
   });
+
+  it("truncates long names and keeps the full name in the tooltip", () => {
+    const name = "A-very-long-unbroken-clip-name-for-the-timeline";
+    const view = renderHeader({ trackLabel: name });
+    const label = view.host.querySelector("span[title]");
+    expect(label?.className).toContain("truncate");
+    expect(label?.className).not.toContain("wrap-break-word");
+    expect(label?.getAttribute("title")).toBe(name);
+    view.unmount();
+  });
 });

package/src/player/components/TimelineTrackPlainHeader.tsx

@@ -93,14 +93,11 @@ export function PlainTrackHeader({
         )}
         {/* No `flex-1`: the name takes only the width it needs, so the clip
             count sits against it rather than being pushed out to meet the
-            controls. The slack goes to the `ml-auto` group below instead.
-
-            Wraps rather than truncating: a truncated name needs a hover to be
-            read at all, and a tooltip is no use to a name you are scanning a
-            column of. `wrap-break-word` so a long single token breaks instead of
-            forcing the column wider. */}
+            controls. The slack goes to the `ml-auto` group below instead. */}
         {showTrackLabel && (
-          <span className="min-w-0 wrap-break-word text-[11px] leading-tight">{trackLabel}</span>
+          <span title={trackLabel} className="min-w-0 truncate text-[11px] leading-tight">
+            {trackLabel}
+          </span>
         )}
         {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
         {/* `ml-auto` is what anchors the group right: it absorbs the slack the

package/src/player/components/timelineProviderStateBuilders.ts

@@ -5,6 +5,26 @@ import type {
 } from "./TimelineProvider";
 import type { ResizingClipState } from "./useTimelineClipDrag";
 import type { TimelineLaneBaseProps } from "./timelineLaneProps";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+
+export function resolveMultiDragPreview(
+  draggedClip: DraggedClipState | null,
+  selectedKeys: ReadonlySet<string>,
+): MultiDragPreviewInput | null {
+  // The dragged clip is a free ghost; selected companions follow the same
+  // clamped delta so the formation stays rigid at the lane boundary.
+  if (!draggedClip?.started) return null;
+  const draggedKey = getTimelineElementIdentity(draggedClip.element);
+  return {
+    dragStarted: true,
+    draggedKey,
+    draggedOriginStart: draggedClip.element.start,
+    draggedPreviewStart: draggedClip.previewStart,
+    selectedKeys,
+  };
+}
 
 export function resolveResizingElementIds(
   resizingClip: ResizingClipState | null,

package/src/player/components/useTimelineProviderState.tsx

@@ -10,6 +10,7 @@ import { useTimelineClipDrag } from "./useTimelineClipDrag";
 import type { ClipContextMenuState, TimelineContextValue } from "./TimelineProvider";
 import {
   buildTimelineMeta,
+  resolveMultiDragPreview,
   resolveRenderClipContent,
   resolveResizingElementIds,
   shouldIgnoreTimelinePointerDown,
@@ -30,7 +31,7 @@ import {
 } from "./useTimelineTrackLayout";
 import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
-import { TimelineRazorGuide, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
+import { TimelineRazorGuideOverlay, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
 import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemetry";
 import {
   getEffectiveTimelineDuration,
@@ -44,6 +45,8 @@ import { useTimelineClipRenderWindow } from "./useTimelineClipRenderWindow";
 import { useTimelineActiveClips } from "./useTimelineActiveClips";
 import { useTimelineLaneMoveRefresh } from "./useTimelineLaneMoveRefresh";
 import { useTimelineLogicalFocus } from "./useTimelineLogicalFocus";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { resolveSnapGuide } from "./timelineSnapping";
 export function useTimelineProviderState({
   onSeek,
   onDrillDown,
@@ -90,10 +93,10 @@ export function useTimelineProviderState({
     onSplitElement: onSplitElementOverride,
   });
   const theme = useMemo(() => ({ ...defaultTimelineTheme, ...themeOverrides }), [themeOverrides]);
+  const editContext = useTimelineEditContextOptional();
   const refreshAfterLaneMove = useTimelineLaneMoveRefresh();
   useMusicBeatAnalysis();
-  const rawElements = usePlayerStore((s) => s.elements);
-  const timelineElements = rawElements;
+  const timelineElements = usePlayerStore((s) => s.elements);
   const adjustedBeatAnalysis = useAdjustedBeatAnalysis();
   const duration = usePlayerStore((s) => s.duration);
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
@@ -108,7 +111,6 @@ export function useTimelineProviderState({
   );
   // The label column provides pre-t=0 space; otherwise keep TRACKS_LEFT_PAD after the gutter.
   const contentOrigin = labelMode ? LABEL_COL_W + GUTTER : GUTTER + TRACKS_LEFT_PAD;
-  const contentGutter = labelMode ? GUTTER : 0;
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
@@ -130,8 +132,8 @@ export function useTimelineProviderState({
   }, []);
   const lastScrollLeftRef = useRef(0);
   const effectiveDuration = useMemo(
-    () => getEffectiveTimelineDuration(duration, rawElements),
-    [duration, rawElements],
+    () => getEffectiveTimelineDuration(duration, timelineElements),
+    [duration, timelineElements],
   );
   const keyframeCache = usePlayerStore((s) => s.keyframeCache);
   useAutoExpandKeyframedClips(gsapAnimations);
@@ -406,7 +408,6 @@ export function useTimelineProviderState({
     handlePointerCancel,
   } = overlaysProps;
   const { rangeSelection, setRangeSelection } = overlays;
-
   const laneGapStrips = useTimelineGapHighlights({
     gapHighlight,
     tracks,
@@ -416,25 +417,24 @@ export function useTimelineProviderState({
     dragActive: draggedClip?.started === true || resizingClip != null,
     displayDuration,
   });
-
   const { major, minor, majorTickInterval } = useTimelineTicks(
     displayDuration,
     pps,
     timeDisplayMode,
     timelineFocus.rowVirtualizationActive ? renderTimeRange : undefined,
   );
-
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
     [resizingClip],
   );
-
+  const draggedElement = draggedClip?.element ?? null;
+  const multiDragPreview = resolveMultiDragPreview(draggedClip, selectedElementIds);
   const canvasProps = {
     major,
     minor,
     pps,
     contentOrigin,
-    contentGutter,
+    contentGutter: labelMode ? GUTTER : 0,
     trackContentWidth: displayContentWidth,
     totalH: displayLayout.totalH,
     effectiveDuration,
@@ -501,6 +501,13 @@ export function useTimelineProviderState({
     onResizeElement,
     onMoveElement,
     beatDragging,
+    draggedElement,
+    snapGuide: resolveSnapGuide(draggedClip, resizingClip),
+    multiDragPreview,
+    onToggleTrackHidden: editContext.onToggleTrackHidden,
+    onTogglePropertyGroupKeyframe: editContext.onTogglePropertyGroupKeyframe,
+    onRazorSplit: editContext.onRazorSplit,
+    onRazorSplitAll: editContext.onRazorSplitAll,
   };
   const timelineRenderClipContent = resolveRenderClipContent(
     timelineFocus.rowVirtualizationActive,
@@ -559,7 +566,7 @@ export function useTimelineProviderState({
     labelColumnWidth: LABEL_COL_W,
     razorGuide:
       activeTool === "razor" && razorGuideX !== null ? (
-        <TimelineRazorGuide x={razorGuideX} />
+        <TimelineRazorGuideOverlay x={razorGuideX} />
       ) : null,
   });
   const contextValue: TimelineContextValue = {

package/src/player/hooks/playbackAdapterResolution.test.ts

@@ -0,0 +1,41 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
+
+function timeline(duration: number) {
+  return {
+    duration: vi.fn(() => duration),
+    time: vi.fn(() => 0),
+    seek: vi.fn(),
+    play: vi.fn(),
+    pause: vi.fn(),
+    isActive: vi.fn(() => false),
+  };
+}
+
+describe("resolvePlaybackAdapter", () => {
+  it("uses the __timelines key matching the document root, not the first key", () => {
+    const first = timeline(12);
+    const second = timeline(12);
+    const third = timeline(12);
+    const iframe = document.createElement("iframe");
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML = '<div data-composition-id="second" data-duration="10"></div>';
+    Object.defineProperty(iframe, "contentDocument", { configurable: true, value: doc });
+    const win = {
+      __timelines: { first, second, third },
+    } as never;
+
+    const adapter = resolvePlaybackAdapter(iframe, win, {
+      cache: { current: null },
+      warned: { current: false },
+    });
+
+    expect(adapter).not.toBeNull();
+    adapter?.seek(7);
+    expect(second.seek).toHaveBeenCalledWith(7);
+    expect(first.seek).not.toHaveBeenCalled();
+    expect(third.seek).not.toHaveBeenCalled();
+  });
+});