@hyperframes/studio 0.6.5 → 0.6.7

package/src/player/components/PlayerControls.tsx

@@ -1,16 +1,35 @@
 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;
 const SEEK_EDGE_SNAP_PX = 8;
 type TimeDisplayMode = "time" | "frame";
-const SHORTCUT_HINTS = [
-  { key: "J", label: "Play backward" },
-  { key: "K", label: "Stop playback" },
-  { key: "L", label: "Play forward" },
-  { key: "←/→", label: "Step one frame backward or forward" },
+const SHORTCUT_SECTIONS = [
+  {
+    title: "Playback",
+    hints: [
+      { key: "Space", label: "Play / Pause" },
+      { key: "J", label: "Play backward" },
+      { key: "K", label: "Stop" },
+      { key: "L", label: "Play forward" },
+      { key: "←/→", label: "Step 1 frame" },
+      { key: "⇧←/⇧→", label: "Step 10 frames" },
+    ],
+  },
+  {
+    title: "Work area",
+    hints: [
+      { key: "I", label: "Set in-point" },
+      { key: "⇧I", label: "Clear in-point" },
+      { key: "O", label: "Set out-point" },
+      { key: "⇧O", label: "Clear out-point" },
+      { key: "A", label: "Jump to in-point" },
+      { key: "E", label: "Jump to out-point" },
+    ],
+  },
 ] as const;
 
 export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth: number): number {
@@ -39,10 +58,17 @@ 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);
+  const setInPoint = usePlayerStore.getState().setInPoint;
+  const setOutPoint = usePlayerStore.getState().setOutPoint;
   const [showSpeedMenu, setShowSpeedMenu] = useState(false);
+  const [showShortcuts, setShowShortcuts] = useState(false);
   const [timeDisplayMode, setTimeDisplayMode] = useState<TimeDisplayMode>("time");
   const [jumpFrame, setJumpFrame] = useState("");
 
@@ -52,6 +78,7 @@ export const PlayerControls = memo(function PlayerControls({
   const seekBarRef = useRef<HTMLDivElement>(null);
   const sliderRef = useRef<HTMLDivElement>(null);
   const speedMenuContainerRef = useRef<HTMLDivElement>(null);
+  const shortcutsPanelRef = useRef<HTMLDivElement>(null);
   const isDraggingRef = useRef(false);
   const currentTimeRef = useRef(0);
   const timeDisplayModeRef = useRef(timeDisplayMode);
@@ -60,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;
@@ -116,6 +150,19 @@ export const PlayerControls = memo(function PlayerControls({
     };
   }, [showSpeedMenu]);
 
+  useEffect(() => {
+    if (!showShortcuts) return;
+    const handleMouseDown = (e: MouseEvent) => {
+      if (shortcutsPanelRef.current && !shortcutsPanelRef.current.contains(e.target as Node)) {
+        setShowShortcuts(false);
+      }
+    };
+    document.addEventListener("mousedown", handleMouseDown);
+    return () => {
+      document.removeEventListener("mousedown", handleMouseDown);
+    };
+  }, [showShortcuts]);
+
   const seekFromClientX = useCallback(
     (clientX: number) => {
       if (disabled) return;
@@ -278,10 +325,14 @@ export const PlayerControls = memo(function PlayerControls({
         )}
       </button>
 
-      {/* Time display */}
-      <span
-        className="font-mono text-[11px] tabular-nums flex-shrink-0 w-[118px]"
-        style={{ color: "#A1A1AA" }}
+      {/* Time display — click to toggle time/frame mode */}
+      <button
+        type="button"
+        onClick={() => setTimeDisplayMode((m) => (m === "time" ? "frame" : "time"))}
+        disabled={disabled}
+        title={timeDisplayMode === "time" ? "Switch to frame display" : "Switch to time display"}
+        className="font-mono text-[11px] tabular-nums flex-shrink-0 w-[118px] text-left transition-colors disabled:pointer-events-none hover:opacity-80"
+        style={{ color: "#A1A1AA", cursor: "pointer" }}
       >
         <span ref={timeDisplayRef}>{formatTime(0)}</span>
         {timeDisplayMode === "time" ? (
@@ -290,7 +341,7 @@ export const PlayerControls = memo(function PlayerControls({
             <span style={{ color: "#52525B" }}>{formatTime(duration)}</span>
           </>
         ) : null}
-      </span>
+      </button>
 
       {/* Seek bar — teal progress fill */}
       <div
@@ -320,16 +371,57 @@ export const PlayerControls = memo(function PlayerControls({
           className="w-full rounded-full relative"
           style={{ background: "rgba(255,255,255,0.15)", height: "3px" }}
         >
+          {/* Work-area band between in/out points */}
+          {(inPoint !== null || outPoint !== null) && duration > 0 && (
+            <div
+              className="absolute top-0 bottom-0 pointer-events-none"
+              style={{
+                left: `${inPoint !== null ? Math.min(100, (inPoint / duration) * 100) : 0}%`,
+                right: `${outPoint !== null ? 100 - Math.min(100, (outPoint / duration) * 100) : 0}%`,
+                background: "rgba(60,230,172,0.15)",
+              }}
+            />
+          )}
           {/* Progress fill — width is controlled imperatively via ref to avoid React re-render resets */}
           <div
             ref={progressFillRef}
             className="absolute top-0 bottom-0 left-0 z-[1] rounded-full"
             style={{ background: "linear-gradient(90deg, var(--hf-accent, #3CE6AC), #2BBFA0)" }}
           />
+          {/* In-point marker */}
+          {inPoint !== null && duration > 0 && (
+            <div
+              className="absolute z-[3] pointer-events-none"
+              style={{
+                left: `${Math.min(100, (inPoint / duration) * 100)}%`,
+                top: "50%",
+                transform: "translate(-50%, -50%)",
+                width: "2px",
+                height: "10px",
+                background: "#3CE6AC",
+                borderRadius: "1px",
+              }}
+            />
+          )}
+          {/* Out-point marker */}
+          {outPoint !== null && duration > 0 && (
+            <div
+              className="absolute z-[3] pointer-events-none"
+              style={{
+                left: `${Math.min(100, (outPoint / duration) * 100)}%`,
+                top: "50%",
+                transform: "translate(-50%, -50%)",
+                width: "2px",
+                height: "10px",
+                background: "#3CE6AC",
+                borderRadius: "1px",
+              }}
+            />
+          )}
           {/* Playhead thumb — left is controlled imperatively via ref */}
           <div
             ref={progressThumbRef}
-            className="absolute top-1/2 z-[2] w-3 h-3 rounded-full -translate-y-1/2 -translate-x-1/2 transition-transform group-hover:scale-125"
+            className="absolute top-1/2 z-[4] w-3 h-3 rounded-full -translate-y-1/2 -translate-x-1/2 transition-transform group-hover:scale-125"
             style={{
               background: "var(--hf-accent, #3CE6AC)",
               boxShadow: "0 0 6px rgba(60,230,172,0.4), 0 1px 4px rgba(0,0,0,0.4)",
@@ -338,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
@@ -385,7 +528,7 @@ export const PlayerControls = memo(function PlayerControls({
         type="button"
         onClick={() => setLoopEnabled(!loopEnabled)}
         disabled={disabled}
-        className={`h-7 w-14 rounded-md border px-2 text-[10px] font-medium transition-colors ${
+        className={`h-7 w-7 flex items-center justify-center rounded-md border transition-colors ${
           loopEnabled
             ? "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"
@@ -394,53 +537,201 @@ export const PlayerControls = memo(function PlayerControls({
         aria-label={loopEnabled ? "Disable loop playback" : "Enable loop playback"}
         aria-pressed={loopEnabled}
       >
-        Loop
-      </button>
-
-      <button
-        type="button"
-        onClick={() => setTimeDisplayMode((mode) => (mode === "time" ? "frame" : "time"))}
-        disabled={disabled}
-        className="h-7 w-14 rounded-md border border-neutral-700 px-2 text-[10px] font-mono text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800"
-        title="Toggle time/frame display"
-        aria-label="Toggle time and frame display"
-      >
-        {timeDisplayMode === "time" ? "m:ss" : "frames"}
+        <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="M17 2l4 4-4 4" />
+          <path d="M3 11V9a4 4 0 0 1 4-4h14" />
+          <path d="M7 22l-4-4 4-4" />
+          <path d="M21 13v2a4 4 0 0 1-4 4H3" />
+        </svg>
       </button>
 
-      <form
-        onSubmit={handleJumpSubmit}
-        className="hidden sm:flex flex-shrink-0 w-[58px] items-center"
-      >
-        <input
-          value={jumpFrame}
-          onChange={(e) => setJumpFrame(e.target.value)}
-          disabled={disabled}
-          inputMode="numeric"
-          pattern="[0-9]*"
-          aria-label="Jump to frame"
-          placeholder="frame"
-          className="h-7 w-[58px] rounded-md border border-neutral-700 bg-neutral-900 px-2 text-[10px] font-mono tabular-nums text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-studio-accent/60"
-          onKeyDown={handleJumpKeyDown}
-          onBlur={commitJumpFrame}
-        />
-      </form>
-
-      <div
-        className="hidden lg:flex items-center gap-1 text-[9px] font-mono text-neutral-500"
-        aria-label="Playback shortcuts: J backward, K stop, L forward, arrows step one frame"
-      >
-        {SHORTCUT_HINTS.map((shortcut) => (
-          <span
-            key={shortcut.key}
-            className="group relative rounded border border-neutral-800 px-1 py-0.5"
+      {/* Keyboard shortcuts + frame jump + work area — click to open panel */}
+      <div ref={shortcutsPanelRef} className="relative flex-shrink-0">
+        <button
+          type="button"
+          onClick={() => setShowShortcuts((v) => !v)}
+          className={`w-6 h-6 flex items-center justify-center rounded border transition-colors ${
+            showShortcuts
+              ? "border-neutral-600 text-neutral-200 bg-neutral-800"
+              : "border-neutral-800 text-neutral-600 hover:text-neutral-300 hover:border-neutral-600"
+          }`}
+          aria-label="Shortcuts and tools"
+          aria-expanded={showShortcuts}
+        >
+          <svg
+            width="11"
+            height="11"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.75"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <rect x="2" y="4" width="20" height="16" rx="2" />
+            <path d="M6 8h.01M10 8h.01M14 8h.01M18 8h.01M6 12h.01M10 12h.01M14 12h.01M18 12h.01M8 16h8" />
+          </svg>
+        </button>
+        {showShortcuts && (
+          <div
+            className="absolute bottom-full right-0 mb-2 z-50 rounded-lg shadow-xl min-w-[220px] overflow-y-auto"
+            style={{
+              background: "#161618",
+              border: "1px solid rgba(255,255,255,0.08)",
+              maxHeight: "min(280px, calc(100vh - 80px))",
+            }}
           >
-            {shortcut.key}
-            <span className="pointer-events-none absolute bottom-full left-1/2 z-50 mb-1.5 hidden -translate-x-1/2 whitespace-nowrap rounded-md border border-neutral-700 bg-neutral-950 px-2 py-1 font-sans text-[10px] text-neutral-200 shadow-lg group-hover:block">
-              {shortcut.label}
-            </span>
-          </span>
-        ))}
+            {/* Frame jump */}
+            <div className="px-3 pt-3 pb-2.5">
+              <p className="text-[9px] font-medium text-neutral-500 uppercase tracking-wider mb-1.5">
+                Jump to frame
+              </p>
+              <form onSubmit={handleJumpSubmit} className="flex items-center gap-1.5">
+                <input
+                  value={jumpFrame}
+                  onChange={(e) => setJumpFrame(e.target.value)}
+                  disabled={disabled}
+                  inputMode="numeric"
+                  pattern="[0-9]*"
+                  aria-label="Jump to frame"
+                  placeholder="frame number"
+                  className="h-6 flex-1 rounded border border-neutral-700 bg-neutral-900 px-2 text-[10px] font-mono tabular-nums text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-studio-accent/60"
+                  onKeyDown={handleJumpKeyDown}
+                  onBlur={commitJumpFrame}
+                />
+                <button
+                  type="submit"
+                  disabled={disabled}
+                  className="h-6 px-2 rounded border border-neutral-700 text-[10px] text-neutral-300 transition-colors hover:border-neutral-500 hover:bg-neutral-800 disabled:opacity-40"
+                >
+                  Go
+                </button>
+              </form>
+            </div>
+            <div style={{ borderTop: "1px solid rgba(255,255,255,0.06)" }} />
+            {/* Work area */}
+            <div className="px-3 pt-2.5 pb-2">
+              <p className="text-[9px] font-medium text-neutral-500 uppercase tracking-wider mb-1.5">
+                Work area
+              </p>
+              <div className="flex flex-col gap-1">
+                <div className="flex items-center justify-between gap-2">
+                  <div className="flex items-center gap-2">
+                    <span
+                      className="font-mono text-[10px] rounded border border-neutral-700 px-1.5 py-0.5 text-neutral-300 min-w-[20px] text-center"
+                      style={{ background: "rgba(255,255,255,0.05)" }}
+                    >
+                      I
+                    </span>
+                    <span className="text-[10px] text-neutral-400">In-point</span>
+                  </div>
+                  <div className="flex items-center gap-1.5">
+                    {inPoint !== null ? (
+                      <>
+                        <span className="font-mono text-[10px] text-neutral-300">
+                          {formatTime(inPoint)}
+                        </span>
+                        <button
+                          type="button"
+                          onClick={() => setInPoint(null)}
+                          className="w-4 h-4 flex items-center justify-center rounded text-neutral-500 hover:text-neutral-200 transition-colors"
+                          aria-label="Clear in-point"
+                        >
+                          <svg
+                            width="8"
+                            height="8"
+                            viewBox="0 0 24 24"
+                            fill="none"
+                            stroke="currentColor"
+                            strokeWidth="2.5"
+                          >
+                            <path d="M18 6L6 18M6 6l12 12" />
+                          </svg>
+                        </button>
+                      </>
+                    ) : (
+                      <span className="text-[10px] text-neutral-600">—</span>
+                    )}
+                  </div>
+                </div>
+                <div className="flex items-center justify-between gap-2">
+                  <div className="flex items-center gap-2">
+                    <span
+                      className="font-mono text-[10px] rounded border border-neutral-700 px-1.5 py-0.5 text-neutral-300 min-w-[20px] text-center"
+                      style={{ background: "rgba(255,255,255,0.05)" }}
+                    >
+                      O
+                    </span>
+                    <span className="text-[10px] text-neutral-400">Out-point</span>
+                  </div>
+                  <div className="flex items-center gap-1.5">
+                    {outPoint !== null ? (
+                      <>
+                        <span className="font-mono text-[10px] text-neutral-300">
+                          {formatTime(outPoint)}
+                        </span>
+                        <button
+                          type="button"
+                          onClick={() => setOutPoint(null)}
+                          className="w-4 h-4 flex items-center justify-center rounded text-neutral-500 hover:text-neutral-200 transition-colors"
+                          aria-label="Clear out-point"
+                        >
+                          <svg
+                            width="8"
+                            height="8"
+                            viewBox="0 0 24 24"
+                            fill="none"
+                            stroke="currentColor"
+                            strokeWidth="2.5"
+                          >
+                            <path d="M18 6L6 18M6 6l12 12" />
+                          </svg>
+                        </button>
+                      </>
+                    ) : (
+                      <span className="text-[10px] text-neutral-600">—</span>
+                    )}
+                  </div>
+                </div>
+              </div>
+            </div>
+            <div style={{ borderTop: "1px solid rgba(255,255,255,0.06)" }} />
+            {/* Shortcuts */}
+            <div className="px-3 pt-2.5 pb-3 flex flex-col gap-3">
+              {SHORTCUT_SECTIONS.map((section) => (
+                <div key={section.title}>
+                  <p className="text-[9px] font-medium text-neutral-500 uppercase tracking-wider mb-1.5">
+                    {section.title}
+                  </p>
+                  <div className="flex flex-col gap-1">
+                    {section.hints.map((hint) => (
+                      <div key={hint.key} className="flex items-center gap-3">
+                        <span
+                          className="font-mono text-[10px] rounded border border-neutral-700 px-1.5 py-0.5 text-neutral-300 min-w-[36px] text-center"
+                          style={{ background: "rgba(255,255,255,0.05)" }}
+                        >
+                          {hint.key}
+                        </span>
+                        <span className="text-[10px] text-neutral-400">{hint.label}</span>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
       </div>
     </div>
   );

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);
+  });
+});