@hyperframes/studio 0.6.6 → 0.6.7

package/src/player/components/PlayerControls.tsx

@@ -1,6 +1,7 @@
 import { useRef, useState, useCallback, useEffect, memo } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { formatFrameTime, frameToSeconds, stepFrameTime, formatTime } from "../lib/time";
+import { shouldMutePreviewAudio } from "../lib/timelineIframeHelpers";
 import { usePlayerStore, liveTime } from "../store/playerStore";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
@@ -57,8 +58,10 @@ export const PlayerControls = memo(function PlayerControls({
   const duration = usePlayerStore((s) => s.duration);
   const timelineReady = usePlayerStore((s) => s.timelineReady);
   const playbackRate = usePlayerStore((s) => s.playbackRate);
+  const audioMuted = usePlayerStore((s) => s.audioMuted);
   const loopEnabled = usePlayerStore((s) => s.loopEnabled);
   const setPlaybackRate = usePlayerStore.getState().setPlaybackRate;
+  const setAudioMuted = usePlayerStore.getState().setAudioMuted;
   const setLoopEnabled = usePlayerStore.getState().setLoopEnabled;
   const inPoint = usePlayerStore((s) => s.inPoint);
   const outPoint = usePlayerStore((s) => s.outPoint);
@@ -84,6 +87,13 @@ export const PlayerControls = memo(function PlayerControls({
   const durationRef = useRef(duration);
   durationRef.current = duration;
   const controlsDisabled = disabled || !timelineReady;
+  const audioAutoMuted = playbackRate > 1;
+  const effectiveAudioMuted = shouldMutePreviewAudio(audioMuted, playbackRate);
+  const muteButtonLabel = audioAutoMuted
+    ? "Audio muted above 1x speed"
+    : audioMuted
+      ? "Unmute audio"
+      : "Mute audio";
   useMountEffect(() => {
     const updateProgress = (t: number) => {
       currentTimeRef.current = t;
@@ -420,6 +430,57 @@ export const PlayerControls = memo(function PlayerControls({
         </div>
       </div>
 
+      {/* Mute toggle */}
+      <button
+        type="button"
+        onClick={() => {
+          if (!audioAutoMuted) setAudioMuted(!audioMuted);
+        }}
+        disabled={controlsDisabled || audioAutoMuted}
+        title={muteButtonLabel}
+        aria-label={muteButtonLabel}
+        aria-pressed={effectiveAudioMuted}
+        className={`h-7 w-7 flex-shrink-0 flex items-center justify-center rounded-md border transition-colors disabled:pointer-events-none ${
+          effectiveAudioMuted
+            ? "text-studio-accent bg-studio-accent/10 border-studio-accent/30"
+            : "border-neutral-700 text-neutral-400 hover:border-neutral-500 hover:bg-neutral-800"
+        } ${audioAutoMuted ? "opacity-70" : ""}`}
+      >
+        {effectiveAudioMuted ? (
+          <svg
+            width="13"
+            height="13"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M11 5 6 9H3v6h3l5 4V5Z" />
+            <path d="m19 9-6 6" />
+            <path d="m13 9 6 6" />
+          </svg>
+        ) : (
+          <svg
+            width="13"
+            height="13"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M11 5 6 9H3v6h3l5 4V5Z" />
+            <path d="M15.5 8.5a5 5 0 0 1 0 7" />
+            <path d="M18.5 5.5a9 9 0 0 1 0 13" />
+          </svg>
+        )}
+      </button>
+
       {/* Speed control */}
       <div ref={speedMenuContainerRef} className="relative flex-shrink-0">
         <button

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

@@ -0,0 +1,174 @@
+// @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 { usePlaybackKeyboard } from "./usePlaybackKeyboard";
+import { usePlayerStore } from "../store/playerStore";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+interface Spies {
+  seek: ReturnType<typeof vi.fn>;
+  play: ReturnType<typeof vi.fn>;
+  playBackward: ReturnType<typeof vi.fn>;
+  pause: ReturnType<typeof vi.fn>;
+}
+
+interface HookHandle {
+  dispatch: (event: KeyboardEvent) => void;
+  release: (event: KeyboardEvent) => void;
+  spies: Spies;
+}
+
+function setupHook(): HookHandle {
+  const spies: Spies = {
+    seek: vi.fn(),
+    play: vi.fn(),
+    playBackward: vi.fn(),
+    pause: vi.fn(),
+  };
+
+  let captured: ReturnType<typeof usePlaybackKeyboard> | null = null;
+
+  function Harness() {
+    const iframeRef = React.useRef<HTMLIFrameElement | null>(null);
+    const shuttleDirectionRef = React.useRef<"forward" | "backward" | null>(null);
+    const shuttleSpeedIndexRef = React.useRef(0);
+    const iframeShortcutCleanupRef = React.useRef<(() => void) | null>(null);
+    const result = usePlaybackKeyboard({
+      iframeRef,
+      shuttleDirectionRef,
+      shuttleSpeedIndexRef,
+      iframeShortcutCleanupRef,
+      getAdapter: () => null,
+      ...spies,
+    });
+    useEffect(() => {
+      captured = result;
+    });
+    return null;
+  }
+
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(React.createElement(Harness));
+  });
+
+  if (!captured) throw new Error("usePlaybackKeyboard harness did not capture handlers");
+
+  return {
+    dispatch: (event) => captured!.playbackKeyDownRef.current(event),
+    release: (event) => captured!.playbackKeyUpRef.current(event),
+    spies,
+  };
+}
+
+function keydown(init: { code: string; key: string; shiftKey?: boolean }): KeyboardEvent {
+  return new KeyboardEvent("keydown", {
+    code: init.code,
+    key: init.key,
+    shiftKey: init.shiftKey ?? false,
+    cancelable: true,
+  });
+}
+
+function keyup(init: { code: string; key: string }): KeyboardEvent {
+  return new KeyboardEvent("keyup", { code: init.code, key: init.key });
+}
+
+describe("usePlaybackKeyboard — keyboard layout independence (#834)", () => {
+  it("'Jump to in-point' fires on physical KeyA in a QWERTY layout", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5 });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a" }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
+  });
+
+  it("'Jump to in-point' fires on AZERTY (physical KeyQ produces e.key='a')", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 2.5 });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyQ", key: "a" }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledWith(2.5, { keepPlaying: true });
+  });
+
+  it("AZERTY 'A' physical key (e.key='q') no longer triggers in-point seek", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 4.0 });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "q" }));
+    });
+
+    expect(spies.seek).not.toHaveBeenCalled();
+  });
+
+  it("Shift+I clears the in-point (e.key='I' is matched after lowercasing)", () => {
+    const { dispatch } = setupHook();
+    usePlayerStore.setState({ inPoint: 3.0 });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyI", key: "I", shiftKey: true }));
+    });
+
+    expect(usePlayerStore.getState().inPoint).toBeNull();
+  });
+
+  it("K-held + L steps forward one frame (combo uses character, not physical position)", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ currentTime: 0 });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyK", key: "k" }));
+    });
+    act(() => {
+      dispatch(keydown({ code: "KeyL", key: "l" }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledTimes(1);
+    expect(spies.play).not.toHaveBeenCalled();
+  });
+
+  it("releasing K removes it from the pressed set so subsequent L resumes forward shuttle", () => {
+    const { dispatch, release, spies } = setupHook();
+
+    act(() => {
+      dispatch(keydown({ code: "KeyK", key: "k" }));
+    });
+    act(() => {
+      release(keyup({ code: "KeyK", key: "k" }));
+    });
+    act(() => {
+      dispatch(keydown({ code: "KeyL", key: "l" }));
+    });
+
+    expect(spies.play).toHaveBeenCalledTimes(1);
+    expect(spies.seek).not.toHaveBeenCalled();
+  });
+
+  it("Space (universal e.code) still toggles play", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ isPlaying: false });
+
+    act(() => {
+      dispatch(keydown({ code: "Space", key: " " }));
+    });
+
+    expect(spies.play).toHaveBeenCalledTimes(1);
+  });
+});

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,50 +108,52 @@ 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 (e.code === "KeyI") {
+      if (key === "i") {
         e.preventDefault();
         const t = getAdapter()?.getTime() ?? usePlayerStore.getState().currentTime;
         usePlayerStore.getState().setInPoint(e.shiftKey ? null : t);
         return;
       }
-      if (e.code === "KeyO") {
+      if (key === "o") {
         e.preventDefault();
         const t = getAdapter()?.getTime() ?? usePlayerStore.getState().currentTime;
         usePlayerStore.getState().setOutPoint(e.shiftKey ? null : t);
         return;
       }
-      if (e.code === "KeyA") {
+      if (key === "a") {
         e.preventDefault();
-        seek(usePlayerStore.getState().inPoint ?? 0);
+        seek(usePlayerStore.getState().inPoint ?? 0, { keepPlaying: true });
         return;
       }
-      if (e.code === "KeyE") {
+      if (key === "e") {
         e.preventDefault();
         const { outPoint } = usePlayerStore.getState();
-        seek(outPoint ?? getAdapter()?.getDuration() ?? usePlayerStore.getState().duration);
+        seek(outPoint ?? getAdapter()?.getDuration() ?? usePlayerStore.getState().duration, {
+          keepPlaying: true,
+        });
         return;
       }
     },
@@ -158,7 +161,7 @@ export function usePlaybackKeyboard({
   );
 
   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();
+    });
+  });
+});