@hyperframes/studio 0.7.90 → 0.7.93

package/src/player/components/useTimelineRowVirtualization.ts

@@ -20,30 +20,23 @@ interface UseTimelineRowVirtualizationInput {
   viewport: TimelineScrollViewportSnapshot;
   rowGeometry: TimelineRowGeometry;
   sessionEpoch: number;
-  elements: TimelineElement[];
+  elements: readonly TimelineElement[];
   selectedElementId: string | null;
-  revealElementId: string | null;
+  focusedRowKey?: number;
   draggedRowKey?: number;
-  resizingRowKey?: number;
+  resizingElementIds?: readonly string[];
   clipContextMenuRowKey?: number;
   keyframeContextMenuRowKey?: number;
   lastScrollLeftRef: RefObject<number>;
   syncScrollViewport: (element: HTMLDivElement, isScrolling?: boolean) => void;
 }
 
-interface TimelineDomFocusPin {
-  readonly rowKey?: number;
-  readonly elementId?: string;
-}
-
-function getTimelineDomFocusPin(target: EventTarget | null): TimelineDomFocusPin | undefined {
+function getFocusedTimelineRowKey(target: EventTarget | null): number | undefined {
   if (!(target instanceof Element)) return undefined;
   const value = target.closest<HTMLElement>("[data-timeline-row-key]")?.dataset.timelineRowKey;
-  const parsedRowKey = value === undefined ? undefined : Number(value);
-  const rowKey =
-    parsedRowKey !== undefined && Number.isFinite(parsedRowKey) ? parsedRowKey : undefined;
-  const elementId = target.closest<HTMLElement>("[data-el-id]")?.dataset.elId;
-  return rowKey === undefined && elementId === undefined ? undefined : { rowKey, elementId };
+  if (value === undefined) return undefined;
+  const rowKey = Number(value);
+  return Number.isFinite(rowKey) ? rowKey : undefined;
 }
 
 export function useTimelineRowVirtualization({
@@ -53,45 +46,50 @@ export function useTimelineRowVirtualization({
   sessionEpoch,
   elements,
   selectedElementId,
-  revealElementId,
+  focusedRowKey,
   draggedRowKey,
-  resizingRowKey,
+  resizingElementIds,
   clipContextMenuRowKey,
   keyframeContextMenuRowKey,
   lastScrollLeftRef,
   syncScrollViewport,
 }: UseTimelineRowVirtualizationInput) {
   const enabled = STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED;
-  const [domFocusPin, setDomFocusPin] = useState<TimelineDomFocusPin>();
+  const [domFocusedRowKey, setDomFocusedRowKey] = useState<number>();
   const onTimelineFocus = useCallback((event: ReactFocusEvent<HTMLDivElement>) => {
-    setDomFocusPin(getTimelineDomFocusPin(event.target));
+    setDomFocusedRowKey(getFocusedTimelineRowKey(event.target));
   }, []);
   const onTimelineBlur = useCallback((event: ReactFocusEvent<HTMLDivElement>) => {
-    setDomFocusPin(getTimelineDomFocusPin(event.relatedTarget));
+    setDomFocusedRowKey(getFocusedTimelineRowKey(event.relatedTarget));
   }, []);
-  const focusIdentity = useMemo(
+  const selectedIdentity = useMemo(
     () => resolveTimelineFocusIdentity(elements, selectedElementId),
     [elements, selectedElementId],
   );
-  const revealIdentity = useMemo(
-    () => resolveTimelineFocusIdentity(elements, revealElementId),
-    [elements, revealElementId],
+  const resizingRowKeys = useMemo(
+    () =>
+      resizingElementIds
+        ?.map((elementId) => resolveTimelineFocusIdentity(elements, elementId)?.rowKey)
+        .filter((rowKey): rowKey is number => rowKey !== undefined) ?? [],
+    [elements, resizingElementIds],
   );
   const pinnedRowKeys = useMemo(
     () =>
       [
         draggedRowKey,
-        resizingRowKey,
-        revealIdentity?.rowKey,
+        ...resizingRowKeys,
+        selectedIdentity?.rowKey,
+        focusedRowKey,
         clipContextMenuRowKey,
         keyframeContextMenuRowKey,
       ].filter((rowKey): rowKey is number => rowKey !== undefined),
     [
       clipContextMenuRowKey,
       draggedRowKey,
+      focusedRowKey,
       keyframeContextMenuRowKey,
-      resizingRowKey,
-      revealIdentity,
+      resizingRowKeys,
+      selectedIdentity,
     ],
   );
   const virtualRows = useTimelineVirtualRows({
@@ -101,7 +99,7 @@ export function useTimelineRowVirtualization({
     rowGeometry,
     sessionEpoch,
     pinnedRowKeys,
-    focusedRowKey: domFocusPin?.rowKey ?? focusIdentity?.rowKey,
+    focusedRowKey: domFocusedRowKey ?? focusedRowKey,
   });
 
   const previousLayoutRef = useRef(rowGeometry);
@@ -134,7 +132,6 @@ export function useTimelineRowVirtualization({
   return {
     enabled,
     virtualRows,
-    focusedElementId: domFocusPin?.elementId,
     timelineFocusProps: { onFocus: onTimelineFocus, onBlur: onTimelineBlur },
   };
 }

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

@@ -0,0 +1,64 @@
+// @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, type TimelineElement } from "../store/playerStore";
+import { useTrackGapMenu } from "./useTrackGapMenu";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const lane: TimelineElement[] = [
+  { id: "first", tag: "div", start: 0, duration: 1, track: 0 },
+  { id: "second", tag: "div", start: 3, duration: 1, track: 0 },
+];
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.innerHTML = "";
+});
+
+describe("useTrackGapMenu", () => {
+  it("does not commit an anchor captured in a previous project session", () => {
+    usePlayerStore.setState({ elements: lane, timelineSessionEpoch: 1 });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const onMoveElement = vi.fn();
+    const onMoveElements = vi.fn();
+    let api: ReturnType<typeof useTrackGapMenu> | null = null;
+
+    function getApi(): ReturnType<typeof useTrackGapMenu> {
+      if (!api) throw new Error("gap menu harness did not render");
+      return api;
+    }
+
+    function Probe() {
+      api = useTrackGapMenu({
+        tracks: [[0, lane]],
+        expandedElementsRef: { current: lane },
+        trackOrderRef: { current: [0] },
+        onMoveElement,
+        onMoveElements,
+      });
+      return null;
+    }
+
+    act(() => root.render(<Probe />));
+    act(() => getApi().openGapMenu({ x: 10, y: 20, track: 0, time: 2 }));
+    expect(getApi().gapMenuModel).not.toBeNull();
+    const staleCloseTrackGap = getApi().closeTrackGap;
+    const staleCloseAllTrackGaps = getApi().closeAllTrackGaps;
+
+    act(() => {
+      usePlayerStore.setState({ timelineSessionEpoch: 2 });
+      staleCloseTrackGap();
+      staleCloseAllTrackGaps();
+    });
+    expect(getApi().gapMenuModel).toBeNull();
+
+    expect(onMoveElement).not.toHaveBeenCalled();
+    expect(onMoveElements).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTrackGapMenu.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useState, type MutableRefObject } from "react";
+import { useCallback, useEffect, useMemo, useState, type MutableRefObject } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { DragCommitDeps } from "./timelineClipDragCommit";
 import {
@@ -21,6 +21,7 @@ interface TrackGapMenuAnchor {
   y: number;
   track: number;
   time: number;
+  sessionEpoch: number;
 }
 
 /** Gap strips to paint on one lane while a menu row is hovered. */
@@ -32,9 +33,9 @@ export interface TrackGapHighlight {
 /**
  * Track-gap context menu (right-click on empty lane space) — state, the
  * derived menu model, and the two commit actions. Extracted from Timeline.tsx
- * as a cohesive unit (600-line studio cap); behavior identical.
+ * as a cohesive unit (600-line studio cap).
  *
- * Only the ANCHOR (and the hovered row) is state; the menu model (gap under
+ * Only the session-stamped ANCHOR (and the hovered row) is state; the menu model (gap under
  * the pointer, compaction, movability) derives from live `tracks` so an open
  * menu reflects concurrent edits. `gapHighlight` — the strips TimelineCanvas
  * paints while "Close gap" / "Close all gaps" is hovered — derives the same
@@ -55,12 +56,16 @@ export function useTrackGapMenu({
   onMoveElements: DragCommitDeps["onMoveElements"];
 }) {
   const updateElement = usePlayerStore((s) => s.updateElement);
+  const sessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
   const [gapContextMenu, setGapContextMenu] = useState<TrackGapMenuAnchor | null>(null);
   const [hoveredGapAction, setHoveredGapAction] = useState<"close-gap" | "close-all" | null>(null);
 
   const gapMenuLaneElements = useMemo(
-    () => (gapContextMenu ? (tracks.find(([t]) => t === gapContextMenu.track)?.[1] ?? []) : null),
-    [gapContextMenu, tracks],
+    () =>
+      gapContextMenu?.sessionEpoch === sessionEpoch
+        ? (tracks.find(([t]) => t === gapContextMenu.track)?.[1] ?? [])
+        : null,
+    [gapContextMenu, sessionEpoch, tracks],
   );
   const gapMenuModel = useMemo(() => {
     if (!gapContextMenu || !gapMenuLaneElements) return null;
@@ -99,7 +104,12 @@ export function useTrackGapMenu({
   }, [gapContextMenu, gapMenuLaneElements, hoveredGapAction]);
 
   const closeTrackGap = useCallback(() => {
-    if (!gapContextMenu || !gapMenuLaneElements) return;
+    if (
+      !gapContextMenu ||
+      !gapMenuLaneElements ||
+      gapContextMenu.sessionEpoch !== usePlayerStore.getState().timelineSessionEpoch
+    )
+      return;
     commitCloseTrackGap(gapMenuLaneElements, gapContextMenu.time, {
       elements: expandedElementsRef.current,
       trackOrder: trackOrderRef.current,
@@ -117,7 +127,12 @@ export function useTrackGapMenu({
     onMoveElements,
   ]);
   const closeAllTrackGaps = useCallback(() => {
-    if (!gapMenuLaneElements) return;
+    if (
+      !gapContextMenu ||
+      !gapMenuLaneElements ||
+      gapContextMenu.sessionEpoch !== usePlayerStore.getState().timelineSessionEpoch
+    )
+      return;
     commitCloseAllTrackGaps(gapMenuLaneElements, {
       elements: expandedElementsRef.current,
       trackOrder: trackOrderRef.current,
@@ -126,6 +141,7 @@ export function useTrackGapMenu({
       onMoveElements,
     });
   }, [
+    gapContextMenu,
     gapMenuLaneElements,
     expandedElementsRef,
     trackOrderRef,
@@ -134,15 +150,22 @@ export function useTrackGapMenu({
     onMoveElements,
   ]);
 
-  const openGapMenu = useCallback((anchor: TrackGapMenuAnchor) => {
+  const openGapMenu = useCallback((anchor: Omit<TrackGapMenuAnchor, "sessionEpoch">) => {
     setHoveredGapAction(null);
-    setGapContextMenu(anchor);
+    setGapContextMenu({
+      ...anchor,
+      sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+    });
   }, []);
   const dismissGapMenu = useCallback(() => {
     setHoveredGapAction(null);
     setGapContextMenu(null);
   }, []);
 
+  useEffect(() => {
+    if (gapContextMenu && gapContextMenu.sessionEpoch !== sessionEpoch) dismissGapMenu();
+  }, [dismissGapMenu, gapContextMenu, sessionEpoch]);
+
   return {
     gapMenuModel,
     gapHighlight,

package/src/player/store/keyframeSlice.ts

@@ -22,6 +22,34 @@ export interface KeyframeCacheEntry {
   easeEach?: string;
 }
 
+export interface FocusedEaseSegment {
+  animationId: string;
+  collidingAnimationTargets?: AnimationKeyframeTarget[];
+  tweenPercentage: number;
+  elementId: string;
+  projectId: string | null;
+  sessionEpoch: number;
+  nonce: number;
+}
+
+type FocusedEaseSegmentTarget = Omit<FocusedEaseSegment, "projectId" | "sessionEpoch" | "nonce">;
+
+interface TimelineSessionIdentity {
+  timelineProjectId: string | null;
+  timelineSessionEpoch: number;
+}
+
+export function isFocusedEaseRequestCurrent(
+  request: FocusedEaseSegment,
+  state: TimelineSessionIdentity & { selectedElementId: string | null },
+): boolean {
+  return (
+    request.projectId === state.timelineProjectId &&
+    request.sessionEpoch === state.timelineSessionEpoch &&
+    request.elementId === state.selectedElementId
+  );
+}
+
 export interface KeyframeSlice {
   /** Selected collapsed (`element:pct`) or expanded (`element:group:animation:clipPct`) diamonds. */
   selectedKeyframes: Set<string>;
@@ -35,22 +63,14 @@ export interface KeyframeSlice {
   /** Union-expand clips (keyframed clips are expanded by default on load). */
   expandClips: (ids: readonly string[]) => void;
 
-  /** elementId scopes the request to one element so a shared (class-selector)
-   * animation id can't open the ease editor on the wrong element. */
-  focusedEaseSegment: {
-    animationId: string;
-    collidingAnimationTargets?: AnimationKeyframeTarget[];
-    tweenPercentage: number;
-    elementId: string;
-  } | null;
-  setFocusedEaseSegment: (
-    target: {
-      animationId: string;
-      collidingAnimationTargets?: AnimationKeyframeTarget[];
-      tweenPercentage: number;
-      elementId: string;
-    } | null,
-  ) => void;
+  /**
+   * Project/session/element-scoped request. Its nonce is monotonic across store
+   * resets so a stale consumer can never collide with a later request.
+   */
+  focusedEaseSegment: FocusedEaseSegment | null;
+  focusedEaseRequestNonce: number;
+  setFocusedEaseSegment: (target: FocusedEaseSegmentTarget) => void;
+  clearFocusedEaseSegment: (nonce: number) => void;
 
   /** Keyframe data per element id, populated from parsed GSAP animations. */
   keyframeCache: Map<string, KeyframeCacheEntry>;
@@ -60,7 +80,10 @@ export interface KeyframeSlice {
   setKeyframeCache: (elementId: string, data: KeyframeCacheEntry | undefined) => void;
 }
 
-export function createKeyframeSlice(set: StoreApi<KeyframeSlice>["setState"]): KeyframeSlice {
+export function createKeyframeSlice(
+  set: StoreApi<KeyframeSlice>["setState"],
+  getTimelineSessionIdentity: () => TimelineSessionIdentity,
+): KeyframeSlice {
   return {
     selectedKeyframes: new Set(),
     toggleSelectedKeyframe: (key) =>
@@ -97,7 +120,25 @@ export function createKeyframeSlice(set: StoreApi<KeyframeSlice>["setState"]): K
       }),
 
     focusedEaseSegment: null,
-    setFocusedEaseSegment: (target) => set({ focusedEaseSegment: target }),
+    focusedEaseRequestNonce: 0,
+    setFocusedEaseSegment: (target) =>
+      set((state) => {
+        const nonce = state.focusedEaseRequestNonce + 1;
+        const { timelineProjectId, timelineSessionEpoch } = getTimelineSessionIdentity();
+        return {
+          focusedEaseRequestNonce: nonce,
+          focusedEaseSegment: {
+            ...target,
+            projectId: timelineProjectId,
+            sessionEpoch: timelineSessionEpoch,
+            nonce,
+          },
+        };
+      }),
+    clearFocusedEaseSegment: (nonce) =>
+      set((state) =>
+        state.focusedEaseSegment?.nonce === nonce ? { focusedEaseSegment: null } : state,
+      ),
 
     keyframeCache: new Map(),
     setKeyframeCache: (elementId, data) =>

package/src/player/store/liveTime.ts

@@ -0,0 +1,11 @@
+// ponytail: Playback RAF updates the playhead/time display without per-frame React renders.
+type TimeListener = (time: number) => void;
+const timeListeners = new Set<TimeListener>();
+
+export const liveTime = {
+  notify: (time: number) => timeListeners.forEach((listener) => listener(time)),
+  subscribe: (listener: TimeListener) => {
+    timeListeners.add(listener);
+    return () => timeListeners.delete(listener);
+  },
+};

package/src/player/store/playerStore.test.ts

@@ -53,6 +53,82 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("focused ease requests", () => {
+    it("stamps the current project session and only lets its nonce clear it", () => {
+      const store = usePlayerStore.getState();
+      store.beginTimelineSession("project-a");
+      store.setSelectedElementId("index.html#hero");
+      store.setFocusedEaseSegment({
+        elementId: "index.html#hero",
+        animationId: "animation-a",
+        tweenPercentage: 50,
+      });
+      const first = usePlayerStore.getState().focusedEaseSegment;
+      if (!first) throw new Error("expected focused ease request");
+      expect(first.projectId).toBe("project-a");
+      expect(first.sessionEpoch).toBeGreaterThan(0);
+      expect(first.nonce).toBeGreaterThan(0);
+
+      store.setFocusedEaseSegment({
+        elementId: "index.html#hero",
+        animationId: "animation-a",
+        tweenPercentage: 75,
+      });
+      const second = usePlayerStore.getState().focusedEaseSegment;
+      if (!second) throw new Error("expected replacement request");
+      expect(second.nonce).toBe(first.nonce + 1);
+
+      store.clearFocusedEaseSegment(first.nonce);
+      expect(usePlayerStore.getState().focusedEaseSegment).toBe(second);
+      store.clearFocusedEaseSegment(second.nonce);
+      expect(usePlayerStore.getState().focusedEaseSegment).toBeNull();
+    });
+
+    it("clears a pending request when the project session changes", () => {
+      const store = usePlayerStore.getState();
+      store.beginTimelineSession("project-a");
+      store.setFocusedEaseSegment({
+        elementId: "index.html#hero",
+        animationId: "animation-a",
+        tweenPercentage: 50,
+      });
+
+      store.beginTimelineSession("project-b");
+      expect(usePlayerStore.getState().focusedEaseSegment).toBeNull();
+    });
+
+    it("does not revive an old request after selecting away and back", () => {
+      const store = usePlayerStore.getState();
+      store.setSelectedElementId("index.html#a");
+      store.setFocusedEaseSegment({
+        elementId: "index.html#a",
+        animationId: "animation-a",
+        tweenPercentage: 50,
+      });
+
+      store.setSelectedElementId("index.html#b");
+      expect(usePlayerStore.getState().focusedEaseSegment).toBeNull();
+      store.setSelectedElementId("index.html#a");
+      expect(usePlayerStore.getState().focusedEaseSegment).toBeNull();
+    });
+
+    it("invalidates on a genuine selection-anchor change but not a same-anchor echo", () => {
+      const store = usePlayerStore.getState();
+      store.setSelection(new Set(["index.html#a", "index.html#b"]), "index.html#a");
+      store.setFocusedEaseSegment({
+        elementId: "index.html#a",
+        animationId: "animation-a",
+        tweenPercentage: 50,
+      });
+      const request = usePlayerStore.getState().focusedEaseSegment;
+
+      store.setSelectionAnchor("index.html#a");
+      expect(usePlayerStore.getState().focusedEaseSegment).toBe(request);
+      store.setSelectionAnchor("index.html#b");
+      expect(usePlayerStore.getState().focusedEaseSegment).toBeNull();
+    });
+  });
+
   describe("setIsPlaying", () => {
     it("sets isPlaying to true", () => {
       usePlayerStore.getState().setIsPlaying(true);
@@ -416,29 +492,36 @@ describe("usePlayerStore", () => {
     });
   });
 
-  describe("clipRevealRequest", () => {
-    it("starts null and carries the requested element id", () => {
-      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-      usePlayerStore.getState().requestClipReveal("el-1");
-      expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("el-1");
-    });
-
-    it("bumps the nonce on repeat requests for the same clip", () => {
-      usePlayerStore.getState().requestClipReveal("el-1");
-      const first = usePlayerStore.getState().clipRevealRequest;
-      usePlayerStore.getState().requestClipReveal("el-1");
-      const second = usePlayerStore.getState().clipRevealRequest;
-      expect(second?.nonce).not.toBe(first?.nonce);
-    });
-
-    it("clears via clearClipRevealRequest and on reset", () => {
-      usePlayerStore.getState().requestClipReveal("el-1");
-      usePlayerStore.getState().clearClipRevealRequest();
-      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-
-      usePlayerStore.getState().requestClipReveal("el-2");
-      usePlayerStore.getState().reset();
-      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+  describe("timelineFocus", () => {
+    it("stamps project scope and carries the requested logical id", () => {
+      usePlayerStore.getState().beginTimelineSession("project-a");
+      usePlayerStore.getState().requestTimelineFocus("clip:el-1");
+      expect(usePlayerStore.getState().timelineFocus).toMatchObject({
+        id: "clip:el-1",
+        projectId: "project-a",
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+      });
+      const store = usePlayerStore.getState();
+      store.requestTimelineFocus("clip:el-1");
+      const first = usePlayerStore.getState().timelineFocus;
+      if (!first) throw new Error("expected timeline focus request");
+      store.clearTimelineFocus(first.nonce);
+      store.reset();
+      store.requestTimelineFocus("clip:el-1");
+      const second = usePlayerStore.getState().timelineFocus;
+      expect(second?.nonce).toBe(first.nonce + 1);
+
+      store.beginTimelineSession("project-a");
+      store.requestTimelineFocus("clip:el-1");
+      const stale = usePlayerStore.getState().timelineFocus;
+      if (!stale) throw new Error("expected timeline focus request");
+      store.requestTimelineFocus("clip:el-2");
+      const replacement = usePlayerStore.getState().timelineFocus;
+      if (!replacement) throw new Error("expected replacement timeline focus request");
+      store.clearTimelineFocus(stale.nonce);
+      expect(usePlayerStore.getState().timelineFocus).toBe(replacement);
+      store.beginTimelineSession("project-b");
+      expect(usePlayerStore.getState().timelineFocus).toBeNull();
     });
   });