@hyperframes/studio 0.6.5 → 0.6.7

package/src/player/hooks/usePlaybackKeyboard.ts

@@ -22,7 +22,7 @@ interface UsePlaybackKeyboardParams {
   play: () => void;
   playBackward: (rate: number) => void;
   pause: () => void;
-  seek: (time: number) => void;
+  seek: (time: number, options?: { keepPlaying?: boolean }) => void;
 }
 
 export function usePlaybackKeyboard({
@@ -36,7 +36,7 @@ export function usePlaybackKeyboard({
   pause,
   seek,
 }: UsePlaybackKeyboardParams) {
-  const pressedCodesRef = useRef(new Set<string>());
+  const pressedKeysRef = useRef(new Set<string>());
   const playbackKeyDownRef = useRef<(e: KeyboardEvent) => void>(() => {});
   const playbackKeyUpRef = useRef<(e: KeyboardEvent) => void>(() => {});
 
@@ -90,7 +90,8 @@ export function usePlaybackKeyboard({
       ) {
         return;
       }
-      pressedCodesRef.current.add(e.code);
+      const key = e.key.toLowerCase();
+      pressedKeysRef.current.add(key);
       if (e.code === "Space") {
         e.preventDefault();
         togglePlay();
@@ -107,34 +108,60 @@ export function usePlaybackKeyboard({
         return;
       }
       if (e.repeat) return;
-      if (e.code === "KeyK") {
+      if (key === "k") {
         e.preventDefault();
         pause();
         return;
       }
-      if (e.code === "KeyJ") {
+      if (key === "j") {
         e.preventDefault();
-        if (pressedCodesRef.current.has("KeyK")) {
+        if (pressedKeysRef.current.has("k")) {
           stepFrames(-1);
           return;
         }
         shuttle("backward");
         return;
       }
-      if (e.code === "KeyL") {
+      if (key === "l") {
         e.preventDefault();
-        if (pressedCodesRef.current.has("KeyK")) {
+        if (pressedKeysRef.current.has("k")) {
           stepFrames(1);
           return;
         }
         shuttle("forward");
+        return;
+      }
+      if (key === "i") {
+        e.preventDefault();
+        const t = getAdapter()?.getTime() ?? usePlayerStore.getState().currentTime;
+        usePlayerStore.getState().setInPoint(e.shiftKey ? null : t);
+        return;
+      }
+      if (key === "o") {
+        e.preventDefault();
+        const t = getAdapter()?.getTime() ?? usePlayerStore.getState().currentTime;
+        usePlayerStore.getState().setOutPoint(e.shiftKey ? null : t);
+        return;
+      }
+      if (key === "a") {
+        e.preventDefault();
+        seek(usePlayerStore.getState().inPoint ?? 0, { keepPlaying: true });
+        return;
+      }
+      if (key === "e") {
+        e.preventDefault();
+        const { outPoint } = usePlayerStore.getState();
+        seek(outPoint ?? getAdapter()?.getDuration() ?? usePlayerStore.getState().duration, {
+          keepPlaying: true,
+        });
+        return;
       }
     },
-    [pause, shuttle, stepFrames, togglePlay],
+    [pause, shuttle, stepFrames, togglePlay, getAdapter, seek],
   );
 
   const handlePlaybackKeyUp = useCallback((e: KeyboardEvent) => {
-    pressedCodesRef.current.delete(e.code);
+    pressedKeysRef.current.delete(e.key.toLowerCase());
   }, []);
 
   playbackKeyDownRef.current = handlePlaybackKeyDown;

package/src/player/hooks/useTimelinePlayer.seek.test.ts

@@ -0,0 +1,329 @@
+// @vitest-environment happy-dom
+
+import React, { act, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useTimelinePlayer } from "./useTimelinePlayer";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+function resetPlayerStore() {
+  usePlayerStore.getState().reset();
+  usePlayerStore.setState({ requestedSeekTime: null });
+}
+
+function TimelinePlayerHarness({
+  onValue,
+}: {
+  onValue: (value: ReturnType<typeof useTimelinePlayer>) => void;
+}) {
+  const value = useTimelinePlayer();
+  useEffect(() => {
+    onValue(value);
+  }, [onValue, value]);
+  return null;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+function attachIframeAdapter(
+  api: ReturnType<typeof useTimelinePlayer>,
+  options: {
+    postMessage?: (message: unknown, targetOrigin: string) => void;
+    timelines?: Record<string, unknown>;
+  } = {},
+) {
+  const iframe = document.createElement("iframe");
+  let currentTime = 0;
+  const adapter = {
+    play: () => {},
+    pause: () => {},
+    seek: (time: number) => {
+      currentTime = time;
+    },
+    getTime: () => currentTime,
+    getDuration: () => 30,
+    isPlaying: () => false,
+  };
+  Object.defineProperty(iframe, "contentWindow", {
+    value: {
+      __player: adapter,
+      __timelines: options.timelines,
+      postMessage: options.postMessage ?? (() => {}),
+      scrollTo: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+    },
+    configurable: true,
+  });
+  Object.defineProperty(iframe, "contentDocument", {
+    value: document.implementation.createHTMLDocument("preview"),
+    configurable: true,
+  });
+  act(() => {
+    api.iframeRef.current = iframe;
+    api.onIframeLoad();
+  });
+  return adapter;
+}
+
+describe("useTimelinePlayer seek hydration", () => {
+  it("keeps an external seek request until the iframe adapter is ready", () => {
+    let api: ReturnType<typeof useTimelinePlayer> | null = null;
+    const observedTimes: number[] = [];
+    const unsubscribe = liveTime.subscribe((time) => {
+      observedTimes.push(time);
+    });
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }),
+      );
+    });
+
+    act(() => {
+      usePlayerStore.getState().requestSeek(4.2);
+    });
+
+    expect(api).not.toBeNull();
+    expect(usePlayerStore.getState().currentTime).toBe(0);
+    expect(usePlayerStore.getState().requestedSeekTime).toBeNull();
+
+    const iframe = document.createElement("iframe");
+    let currentTime = 0;
+    const adapter = {
+      play: () => {},
+      pause: () => {},
+      seek: (time: number) => {
+        currentTime = time;
+      },
+      getTime: () => currentTime,
+      getDuration: () => 30,
+      isPlaying: () => false,
+    };
+    Object.defineProperty(iframe, "contentWindow", {
+      value: {
+        __player: adapter,
+        postMessage: () => {},
+        scrollTo: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+      },
+      configurable: true,
+    });
+    Object.defineProperty(iframe, "contentDocument", {
+      value: document.implementation.createHTMLDocument("preview"),
+      configurable: true,
+    });
+
+    act(() => {
+      api!.iframeRef.current = iframe;
+      api!.onIframeLoad();
+    });
+
+    expect(currentTime).toBe(4.2);
+    expect(usePlayerStore.getState().currentTime).toBe(4.2);
+    expect(usePlayerStore.getState().timelineReady).toBe(true);
+    expect(observedTimes).toContain(4.2);
+
+    act(() => {
+      root.unmount();
+    });
+    unsubscribe();
+  });
+});
+
+describe("useTimelinePlayer audio controls (#835)", () => {
+  it("applies playback-rate changes immediately and auto-mutes audio above 1x", () => {
+    let api: ReturnType<typeof useTimelinePlayer> | null = null;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const postMessage = vi.fn();
+    const timeScale = vi.fn();
+
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }),
+      );
+    });
+    attachIframeAdapter(api!, {
+      postMessage,
+      timelines: {
+        root: { timeScale },
+      },
+    });
+    postMessage.mockClear();
+    timeScale.mockClear();
+
+    act(() => {
+      usePlayerStore.getState().setAudioMuted(false);
+      usePlayerStore.getState().setPlaybackRate(2);
+    });
+
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        source: "hf-parent",
+        type: "control",
+        action: "set-playback-rate",
+        playbackRate: 2,
+      }),
+      "*",
+    );
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        source: "hf-parent",
+        type: "control",
+        action: "set-muted",
+        muted: true,
+      }),
+      "*",
+    );
+    expect(timeScale).toHaveBeenCalledWith(2);
+
+    postMessage.mockClear();
+
+    act(() => {
+      usePlayerStore.getState().setPlaybackRate(1);
+    });
+
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "set-muted",
+        muted: false,
+      }),
+      "*",
+    );
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("keeps explicit Studio mute active at 1x", () => {
+    let api: ReturnType<typeof useTimelinePlayer> | null = null;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const postMessage = vi.fn();
+
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }),
+      );
+    });
+    attachIframeAdapter(api!, { postMessage });
+    postMessage.mockClear();
+
+    act(() => {
+      usePlayerStore.getState().setPlaybackRate(1);
+      usePlayerStore.getState().setAudioMuted(true);
+    });
+
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "set-muted",
+        muted: true,
+      }),
+      "*",
+    );
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});
+
+describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
+  it("default seek() clears isPlaying when the store reports playing", () => {
+    let api: ReturnType<typeof useTimelinePlayer> | null = null;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }),
+      );
+    });
+    attachIframeAdapter(api!);
+
+    act(() => {
+      usePlayerStore.setState({ isPlaying: true });
+    });
+
+    act(() => {
+      api!.seek(5);
+    });
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(usePlayerStore.getState().currentTime).toBe(5);
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("seek(time, { keepPlaying: true }) preserves isPlaying=true so A/E shortcuts don't pause the timeline", () => {
+    let api: ReturnType<typeof useTimelinePlayer> | null = null;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }),
+      );
+    });
+    attachIframeAdapter(api!);
+
+    act(() => {
+      usePlayerStore.setState({ isPlaying: true });
+    });
+
+    act(() => {
+      api!.seek(5, { keepPlaying: true });
+    });
+
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    expect(usePlayerStore.getState().currentTime).toBe(5);
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("seek(time, { keepPlaying: true }) from paused state stays paused (no spurious resume)", () => {
+    let api: ReturnType<typeof useTimelinePlayer> | null = null;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        React.createElement(TimelinePlayerHarness, { onValue: (value) => (api = value) }),
+      );
+    });
+    attachIframeAdapter(api!);
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+
+    act(() => {
+      api!.seek(5, { keepPlaying: true });
+    });
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(usePlayerStore.getState().currentTime).toBe(5);
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});

package/src/player/hooks/useTimelinePlayer.ts

@@ -37,7 +37,11 @@ import {
   mergeTimelineElementsPreservingDowngrades,
   parseTimelineFromDOM,
 } from "../lib/timelineDOM";
-import { unmutePreviewMedia } from "../lib/timelineIframeHelpers";
+import {
+  setPreviewMediaMuted,
+  setPreviewPlaybackRate,
+  shouldMutePreviewAudio,
+} from "../lib/timelineIframeHelpers";
 
 // ---------------------------------------------------------------------------
 // Hook
@@ -185,15 +189,21 @@ export function useTimelinePlayer() {
         const time = adapter.getTime();
         const dur = adapter.getDuration();
         liveTime.notify(time); // direct DOM updates, no React re-render
-        if (time >= dur && !adapter.isPlaying()) {
+        const { inPoint, outPoint } = usePlayerStore.getState();
+        const rawLoopEnd = outPoint !== null ? outPoint : dur;
+        const rawLoopStart = inPoint !== null ? inPoint : 0;
+        const loopEnd = rawLoopStart < rawLoopEnd ? rawLoopEnd : dur;
+        const loopStart = rawLoopStart < rawLoopEnd ? rawLoopStart : 0;
+        if (time >= loopEnd) {
           if (usePlayerStore.getState().loopEnabled && dur > 0) {
-            adapter.seek(0);
-            liveTime.notify(0);
+            adapter.seek(loopStart);
+            liveTime.notify(loopStart);
             adapter.play();
             setIsPlaying(true);
             rafRef.current = requestAnimationFrame(tick);
             return;
           }
+          if (adapter.isPlaying()) adapter.pause();
           setCurrentTime(time); // sync Zustand once at end
           setIsPlaying(false);
           cancelAnimationFrame(rafRef.current);
@@ -212,11 +222,7 @@ export function useTimelinePlayer() {
   const applyPlaybackRate = useCallback((rate: number) => {
     const iframe = iframeRef.current;
     if (!iframe) return;
-    // Send to runtime via bridge (works with both new and CDN runtime)
-    iframe.contentWindow?.postMessage(
-      { source: "hf-parent", type: "control", action: "set-playback-rate", playbackRate: rate },
-      "*",
-    );
+    setPreviewPlaybackRate(iframe, rate);
     // Also set directly on GSAP timeline if accessible
     try {
       const win = iframe.contentWindow as IframeWindow | null;
@@ -235,21 +241,38 @@ export function useTimelinePlayer() {
     }
   }, []);
 
+  const applyPreviewAudioState = useCallback((playbackRateOverride?: number) => {
+    const { audioMuted, playbackRate } = usePlayerStore.getState();
+    const effectivePlaybackRate = playbackRateOverride ?? playbackRate;
+    setPreviewMediaMuted(
+      iframeRef.current,
+      shouldMutePreviewAudio(audioMuted, effectivePlaybackRate),
+    );
+  }, []);
+
   const play = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
     const adapter = getAdapter();
     if (!adapter) return;
     if (adapter.getTime() >= adapter.getDuration()) {
-      adapter.seek(0);
+      adapter.seek(usePlayerStore.getState().inPoint ?? 0);
     }
-    unmutePreviewMedia(iframeRef.current);
     applyPlaybackRate(usePlayerStore.getState().playbackRate);
+    applyPreviewAudioState();
     adapter.play();
     shuttleDirectionRef.current = "forward";
     setIsPlaying(true);
     startRAFLoop();
-  }, [getAdapter, setIsPlaying, startRAFLoop, applyPlaybackRate, stopRAFLoop, stopReverseLoop]);
+  }, [
+    getAdapter,
+    setIsPlaying,
+    startRAFLoop,
+    applyPlaybackRate,
+    applyPreviewAudioState,
+    stopRAFLoop,
+    stopReverseLoop,
+  ]);
 
   const playBackward = useCallback(
     (rate: number) => {
@@ -261,23 +284,29 @@ export function useTimelinePlayer() {
       const initialTime = adapter.getTime() <= 0 && duration > 0 ? duration : adapter.getTime();
       adapter.pause();
       if (initialTime !== adapter.getTime()) adapter.seek(initialTime);
-      unmutePreviewMedia(iframeRef.current);
       const speed = Math.max(0.1, Math.min(4, rate));
+      applyPlaybackRate(speed);
+      applyPreviewAudioState(speed);
       let startTime = initialTime;
       let startedAt = performance.now();
 
       const tick = (now: number) => {
         const elapsed = ((now - startedAt) / 1000) * speed;
         let nextTime = startTime - elapsed;
-        if (nextTime <= 0) {
+        const { inPoint, outPoint } = usePlayerStore.getState();
+        const rawLoopEnd = outPoint !== null ? outPoint : duration;
+        const rawLoopStart = inPoint !== null ? inPoint : 0;
+        const loopEnd = rawLoopStart < rawLoopEnd ? rawLoopEnd : duration;
+        const loopStart = rawLoopStart < rawLoopEnd ? rawLoopStart : 0;
+        if (nextTime <= loopStart) {
           if (usePlayerStore.getState().loopEnabled && duration > 0) {
-            startTime = duration;
+            startTime = loopEnd;
             startedAt = now;
-            nextTime = duration;
+            nextTime = loopEnd;
           } else {
-            adapter.seek(0);
-            liveTime.notify(0);
-            setCurrentTime(0);
+            adapter.seek(loopStart);
+            liveTime.notify(loopStart);
+            setCurrentTime(loopStart);
             setIsPlaying(false);
             shuttleDirectionRef.current = null;
             reverseRafRef.current = 0;
@@ -294,7 +323,15 @@ export function useTimelinePlayer() {
       shuttleDirectionRef.current = "backward";
       reverseRafRef.current = requestAnimationFrame(tick);
     },
-    [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop],
+    [
+      getAdapter,
+      setCurrentTime,
+      setIsPlaying,
+      applyPlaybackRate,
+      applyPreviewAudioState,
+      stopRAFLoop,
+      stopReverseLoop,
+    ],
   );
 
   const pause = useCallback(() => {
@@ -310,21 +347,39 @@ export function useTimelinePlayer() {
   }, [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop]);
 
   const seek = useCallback(
-    (time: number) => {
+    (time: number, options?: { keepPlaying?: boolean }) => {
+      // Reverse shuttle is always stopped: the RAF reverse tick can't survive
+      // a seek anyway, so `keepPlaying` only preserves forward playback.
+      const wasReverseShuttle = shuttleDirectionRef.current === "backward";
       stopReverseLoop();
       const adapter = getAdapter();
-      if (!adapter) return;
+      if (!adapter) {
+        pendingSeekRef.current = Math.max(0, time);
+        return false;
+      }
       const duration = Math.max(0, adapter.getDuration());
       const nextTime = Math.max(0, duration > 0 ? Math.min(duration, time) : time);
-      adapter.seek(nextTime);
+      adapter.seek(nextTime, options);
       liveTime.notify(nextTime); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
-      stopRAFLoop();
-      if (usePlayerStore.getState().isPlaying) setIsPlaying(false);
-      shuttleDirectionRef.current = null;
-      shuttleSpeedIndexRef.current = 0;
+      if (!options?.keepPlaying || wasReverseShuttle) {
+        stopRAFLoop();
+        if (usePlayerStore.getState().isPlaying) setIsPlaying(false);
+        shuttleDirectionRef.current = null;
+        shuttleSpeedIndexRef.current = 0;
+      }
+      return true;
     },
-    [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop],
+    [
+      getAdapter,
+      pendingSeekRef,
+      setCurrentTime,
+      setIsPlaying,
+      stopRAFLoop,
+      stopReverseLoop,
+      shuttleDirectionRef,
+      shuttleSpeedIndexRef,
+    ],
   );
 
   // Handle seek requests from outside the player loop (e.g. LayersPanel).
@@ -363,6 +418,7 @@ export function useTimelinePlayer() {
       setTimelineReady,
       setIsPlaying,
       attachIframeShortcutListeners,
+      applyPreviewAudioState,
     });
 
   const saveSeekPosition = useCallback(() => {
@@ -487,6 +543,19 @@ export function useTimelinePlayer() {
     usePlayerStore.getState().reset();
   }, [stopRAFLoop, stopReverseLoop]);
 
+  useEffect(() => {
+    return usePlayerStore.subscribe((state, prev) => {
+      const playbackRateChanged = state.playbackRate !== prev.playbackRate;
+      const audioMutedChanged = state.audioMuted !== prev.audioMuted;
+      if (!playbackRateChanged && !audioMutedChanged) return;
+
+      if (playbackRateChanged) {
+        applyPlaybackRate(state.playbackRate);
+      }
+      applyPreviewAudioState();
+    });
+  }, [applyPlaybackRate, applyPreviewAudioState]);
+
   return {
     iframeRef,
     play,