@hyperframes/studio 0.8.53 → 0.8.55

package/src/player/components/Timeline.tsx

@@ -4,6 +4,7 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { useTimelineRowElements } from "../hooks/useTimelineRowElements";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+import { usePublishRangeSelection } from "./usePublishRangeSelection";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 import { useTimelineZoom } from "./useTimelineZoom";
 import { useTimelineAssetDrop } from "./timelineDragDrop";
@@ -80,6 +81,7 @@ export const Timeline = memo(function Timeline({
   onBlockedEditAttempt: onBlockedEditAttemptOverride,
   onSplitElement: onSplitElementOverride,
   onSelectElement,
+  onRangeSelect,
   onCopyClip,
   onPasteClip,
   onDuplicateClip,
@@ -167,10 +169,10 @@ export const Timeline = memo(function Timeline({
     selectedElementIds,
   );
   const expandedElementsRef = useRef(expandedElements);
-  expandedElementsRef.current = expandedElements;
+  expandedElementsRef.current = expandedElements; // oxlint-disable-line react/refs -- event handlers read the latest elements
   const ppsRef = useRef(100);
   const durationRef = useRef(effectiveDuration);
-  durationRef.current = effectiveDuration;
+  durationRef.current = effectiveDuration; // oxlint-disable-line react/refs -- event handlers read the latest duration
   const fitPpsRef = useRef(100);
   const {
     pinZoomBeforeEdit,
@@ -214,7 +216,6 @@ export const Timeline = memo(function Timeline({
     onMoveElements: pinnedOnMoveElements,
   });
   const onContextMenuClip = useClipContextMenu(onSelectElement, dismissGapMenu, setClipContextMenu);
-
   const {
     draggedClip,
     setDraggedClip,
@@ -241,7 +242,6 @@ export const Timeline = memo(function Timeline({
     refreshAfterLaneMove,
     sessionEpoch,
   });
-
   const assetDrop = useTimelineAssetDrop({
     scrollRef,
     ppsRef,
@@ -320,7 +320,6 @@ export const Timeline = memo(function Timeline({
       setKfContextMenu,
       toggleSelectedKeyframe,
     });
-
   const { clipIndex, renderTimeRange, visibleTimeRange, pinnedClipIdentities } =
     useTimelineClipRenderWindow({
       tracks,
@@ -415,7 +414,8 @@ export const Timeline = memo(function Timeline({
     contentOrigin,
     sessionEpoch,
   });
-  setRangeSelectionRef.current = setRangeSelection; // stable ref consumed by useTimelineClipDrag
+  usePublishRangeSelection(rangeSelection, onRangeSelect);
+  setRangeSelectionRef.current = setRangeSelection; // oxlint-disable-line react/refs -- stable ref consumed by useTimelineClipDrag
 
   useTimelineSelectionLifecycle(expandedElements, selectedElementId, setShowPopover, () =>
     setRangeSelection(null),

package/src/player/components/TimelineTypes.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { TimelineElement } from "../store/playerStore";
+import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
@@ -23,6 +24,8 @@ export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverri
   renderClipOverlay?: (element: TimelineElement) => ReactNode;
   onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
   onSelectElement?: (element: TimelineElement | null) => void;
+  /** Notification only; null when cleared. The value lives in usePlayerStore.rangeSelection. */
+  onRangeSelect?: (range: TimelineTimeRange | null) => void;
   onCopyClip?: () => boolean;
   onPasteClip?: () => Promise<void>;
   onDuplicateClip?: () => Promise<boolean>;

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

@@ -0,0 +1,60 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
+import type { TimelineRangeSelection } from "./timelineEditing";
+import { usePublishRangeSelection } from "./usePublishRangeSelection";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function mount(onRangeSelect: (range: TimelineTimeRange | null) => void) {
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  const Harness = ({ selection }: { selection: TimelineRangeSelection | null }) => {
+    usePublishRangeSelection(selection, onRangeSelect);
+    return null;
+  };
+  const render = (selection: TimelineRangeSelection | null) =>
+    act(() => root.render(<Harness selection={selection} />));
+  return { render, unmount: () => act(() => root.unmount()) };
+}
+
+const selection = (start: number, end: number): TimelineRangeSelection => ({
+  start,
+  end,
+  anchorX: 0,
+  anchorY: 0,
+});
+
+describe("usePublishRangeSelection", () => {
+  afterEach(() => usePlayerStore.setState({ rangeSelection: null }));
+
+  it("publishes an ordered range to the store and the host, and clears with null", () => {
+    const onRangeSelect = vi.fn();
+    const view = mount(onRangeSelect);
+
+    view.render(selection(3, 1));
+    expect(usePlayerStore.getState().rangeSelection).toEqual({ t0: 1, t1: 3 });
+    expect(onRangeSelect).toHaveBeenLastCalledWith({ t0: 1, t1: 3 });
+
+    view.render(null);
+    expect(usePlayerStore.getState().rangeSelection).toBeNull();
+    expect(onRangeSelect).toHaveBeenLastCalledWith(null);
+    view.unmount();
+  });
+
+  it("does not re-notify for an unchanged range and preserves a newer store value on unmount", () => {
+    const onRangeSelect = vi.fn();
+    const view = mount(onRangeSelect);
+
+    view.render(selection(1, 3));
+    view.render(selection(3, 1));
+    expect(onRangeSelect).toHaveBeenCalledTimes(1);
+
+    usePlayerStore.setState({ rangeSelection: { t0: 9, t1: 10 } });
+    view.unmount();
+    expect(usePlayerStore.getState().rangeSelection).toEqual({ t0: 9, t1: 10 });
+  });
+});

package/src/player/components/usePublishRangeSelection.ts

@@ -0,0 +1,42 @@
+import { useEffect, useRef } from "react";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
+import type { TimelineRangeSelection } from "./timelineEditing";
+
+/** Mirrors the gesture's range into the store and notifies the host. */
+export function usePublishRangeSelection(
+  rangeSelection: TimelineRangeSelection | null,
+  onRangeSelect?: (range: TimelineTimeRange | null) => void,
+) {
+  const onRangeSelectRef = useRef(onRangeSelect);
+  const publishedRangeRef = useRef<TimelineTimeRange | null>(null);
+
+  useEffect(() => {
+    onRangeSelectRef.current = onRangeSelect;
+  }, [onRangeSelect]);
+
+  useEffect(() => {
+    const range = rangeSelection
+      ? {
+          t0: Math.min(rangeSelection.start, rangeSelection.end),
+          t1: Math.max(rangeSelection.start, rangeSelection.end),
+        }
+      : null;
+    const store = usePlayerStore.getState();
+    const current = store.rangeSelection;
+    if (current?.t0 === range?.t0 && current?.t1 === range?.t1) return;
+    publishedRangeRef.current = range;
+    usePlayerStore.setState({ rangeSelection: range });
+    onRangeSelectRef.current?.(range);
+  }, [rangeSelection]);
+
+  useEffect(
+    () => () => {
+      const current = usePlayerStore.getState().rangeSelection;
+      const published = publishedRangeRef.current;
+      if (current?.t0 !== published?.t0 || current?.t1 !== published?.t1) return;
+      usePlayerStore.setState({ rangeSelection: null });
+    },
+    [],
+  );
+}

package/src/player/index.ts

@@ -12,6 +12,7 @@ export { resolveIframe } from "./lib/timelineDOM";
 // Store
 export { usePlayerStore, liveTime } from "./store/playerStore";
 export type { SelectElementOptions, TimelineElement, ZoomMode } from "./store/playerStore";
+export type { TimelineTimeRange } from "./store/rangeSelectionSlice";
 
 // Utils
 export { formatTime } from "./lib/time";

package/src/player/store/playerStore.ts

@@ -2,7 +2,6 @@ import { create } from "zustand";
 import { attachPlayerStoreDevHandle } from "./playerStoreDevHandle";
 import { nextSelectionSet, revealTargetsSelection } from "./playerStoreSelection";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { BeatEditState } from "../../utils/beatEditing";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import {
@@ -11,7 +10,7 @@ import {
   type TimelineTimeDisplayMode,
 } from "../../utils/studioUiPreferences";
 import { clampTimelineZoomPercent, computePinnedZoomPercent } from "../components/timelineZoom";
-import { createKeyframeSlice, type KeyframeCacheEntry, type KeyframeSlice } from "./keyframeSlice";
+import { createKeyframeSlice, type KeyframeSlice } from "./keyframeSlice";
 import {
   createAutomationSelectionSlice,
   type AutomationSelectionSlice,
@@ -19,10 +18,12 @@ import {
 import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
 import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
-import { createPlaybackReadinessSlice, resetPlaybackReadinessState } from "./readinessSlice";
-
+import { createPlaybackReadinessSlice } from "./readinessSlice";
+import { createRangeSelectionSlice, type RangeSelectionSlice } from "./rangeSelectionSlice";
+import { createTimelineResetState } from "./timelineResetState";
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
+export { createTimelineResetState };
 
 import type {
   TimelineElement,
@@ -59,7 +60,8 @@ type PlayerStoreSlices = KeyframeSlice &
   AutomationSelectionSlice &
   ThumbnailSlice &
   EditingModeSlice &
-  ReturnType<typeof createPlaybackReadinessSlice>;
+  ReturnType<typeof createPlaybackReadinessSlice> &
+  RangeSelectionSlice;
 interface PlayerState extends PlayerStoreSlices {
   isPlaying: boolean;
   currentTime: number;
@@ -250,52 +252,6 @@ interface BeatHistoryEntry {
   label: string;
 }
 
-export function createTimelineResetState() {
-  return {
-    isPlaying: false,
-    currentTime: 0,
-    duration: 0,
-    ...resetPlaybackReadinessState(),
-    beatDragging: false,
-    elements: [],
-    selectedElementId: null,
-    zEditVersion: 0,
-    inPoint: null,
-    outPoint: null,
-    activeTool: "select" as const,
-    activeKeyframePct: null,
-    motionPathArmed: false,
-    motionPathCreateAvailable: false,
-    selectedKeyframes: new Set<string>(),
-    // Ephemeral like every other selection here. A range surviving a project
-    // switch can match a same-keyed clip in the new project and redirect a
-    // paste through `sel.elementKey === paste.elementKey` to a stale t0.
-    automationSelection: null,
-    expandedClipIds: new Set<string>(),
-    // Per-composition: ids from comp A match nothing in B, silencing all of it.
-    collapsedGroupIds: new Set<string>(),
-    expandedLaneOwnerIds: new Set<string>(),
-    focusedEaseSegment: null,
-    revealedAudioFxTarget: null,
-    selectedElementIds: new Set<string>(),
-    requestedSeekTime: null,
-    lintFindingsByElement: new Map<string, { count: number; messages: string[] }>(),
-    timelineFocus: null,
-    keyframeCache: new Map<string, KeyframeCacheEntry>(),
-    gsapAnimations: new Map<string, GsapAnimation[]>(),
-    beatAnalysis: null,
-    beatEdits: null,
-    beatUndo: [],
-    beatRedo: [],
-    beatPersist: null,
-    clipManifest: null,
-    clipParentMap: new Map<string, string>(),
-    topLevelIds: null,
-    domClipChildren: [],
-    subCompositionHostState: new Map<string, SubCompositionHostState>(),
-  };
-}
-
 export const usePlayerStore = create<PlayerState>((set, get) => ({
   isPlaying: false,
   currentTime: 0,
@@ -328,6 +284,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 
   ...createAutomationSelectionSlice(set),
   ...createEditingModeSlice(set),
+  ...createRangeSelectionSlice(),
   ...createPlaybackReadinessSlice(set),
 
   activeKeyframePct: null,

package/src/player/store/rangeSelectionSlice.ts

@@ -0,0 +1,13 @@
+export interface TimelineTimeRange {
+  t0: number;
+  t1: number;
+}
+
+export interface RangeSelectionSlice {
+  /** Shift-drag ruler range in seconds, normalized so t0 <= t1. */
+  rangeSelection: TimelineTimeRange | null;
+}
+
+export function createRangeSelectionSlice(): RangeSelectionSlice {
+  return { rangeSelection: null };
+}

package/src/player/store/timelineResetState.ts

@@ -0,0 +1,51 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { KeyframeCacheEntry } from "./keyframeSlice";
+import { resetPlaybackReadinessState } from "./readinessSlice";
+import type { SubCompositionHostState } from "./timelineElement";
+
+export function createTimelineResetState() {
+  return {
+    isPlaying: false,
+    currentTime: 0,
+    duration: 0,
+    ...resetPlaybackReadinessState(),
+    beatDragging: false,
+    elements: [],
+    selectedElementId: null,
+    zEditVersion: 0,
+    inPoint: null,
+    outPoint: null,
+    rangeSelection: null,
+    activeTool: "select" as const,
+    activeKeyframePct: null,
+    motionPathArmed: false,
+    motionPathCreateAvailable: false,
+    selectedKeyframes: new Set<string>(),
+    // Ephemeral like every other selection here. A range surviving a project
+    // switch can match a same-keyed clip in the new project and redirect a
+    // paste through `sel.elementKey === paste.elementKey` to a stale t0.
+    automationSelection: null,
+    expandedClipIds: new Set<string>(),
+    // Per-composition: ids from comp A match nothing in B, silencing all of it.
+    collapsedGroupIds: new Set<string>(),
+    expandedLaneOwnerIds: new Set<string>(),
+    focusedEaseSegment: null,
+    revealedAudioFxTarget: null,
+    selectedElementIds: new Set<string>(),
+    requestedSeekTime: null,
+    lintFindingsByElement: new Map<string, { count: number; messages: string[] }>(),
+    timelineFocus: null,
+    keyframeCache: new Map<string, KeyframeCacheEntry>(),
+    gsapAnimations: new Map<string, GsapAnimation[]>(),
+    beatAnalysis: null,
+    beatEdits: null,
+    beatUndo: [],
+    beatRedo: [],
+    beatPersist: null,
+    clipManifest: null,
+    clipParentMap: new Map<string, string>(),
+    topLevelIds: null,
+    domClipChildren: [],
+    subCompositionHostState: new Map<string, SubCompositionHostState>(),
+  };
+}

package/src/utils/studioSaveDiagnostics.ts

@@ -165,9 +165,21 @@ export function buildStudioSaveFailureProperties(
     target_id: input.targetId ?? undefined,
     target_selector: input.targetSelector ?? undefined,
     target_source_file: input.targetSourceFile ?? undefined,
+    block_detail: gsapBlockDetail(input.error),
   };
 }
 
+/**
+ * The specific cause behind a blocked GSAP edit. `error_message` only carries
+ * the coarse copy, and one of those strings covers six different situations,
+ * so the message alone cannot say which one a user hit.
+ */
+function gsapBlockDetail(error: unknown): string | undefined {
+  if (!(error instanceof Error) || error.name !== "GsapEditBlockedError") return undefined;
+  const detail = (error as { detail?: unknown }).detail;
+  return typeof detail === "string" ? detail : undefined;
+}
+
 export function trackStudioSaveFailure(input: StudioSaveFailureInput): void {
   trackStudioEvent("save_failure", buildStudioSaveFailureProperties(input));
 }