@hyperframes/studio 0.5.0-alpha.1 → 0.5.0-alpha.11

package/src/player/components/Timeline.tsx

@@ -26,7 +26,7 @@ import {
   type TimelineTrackStyle,
   type TimelineTheme,
 } from "./timelineTheme";
-import { getTimelinePixelsPerSecond } from "./timelineZoom";
+import { getPinchTimelineZoomPercent, getTimelinePixelsPerSecond } from "./timelineZoom";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
 
 /* ── Layout ─────────────────────────────────────────────────────── */
@@ -35,7 +35,7 @@ const TRACK_H = 72;
 const RULER_H = 24;
 const CLIP_Y = 3; // vertical inset inside track
 const CLIP_HANDLE_W = 18;
-const TIMELINE_SCROLL_BUFFER = 24;
+const TIMELINE_SCROLL_BUFFER = 20;
 
 interface TrackVisualStyle extends TimelineTrackStyle {
   icon: ReactNode;
@@ -88,16 +88,47 @@ function getStyle(tag: string): TrackVisualStyle {
 }
 
 /* ── Tick Generation ────────────────────────────────────────────── */
-export function generateTicks(duration: number): { major: number[]; minor: number[] } {
+function getMajorTickInterval(duration: number, pixelsPerSecond?: number): number {
+  const zoomIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600];
+  if (Number.isFinite(pixelsPerSecond) && (pixelsPerSecond ?? 0) > 0) {
+    const targetMajorPx = 128;
+    return (
+      zoomIntervals.find((interval) => interval * (pixelsPerSecond ?? 0) >= targetMajorPx) ?? 600
+    );
+  }
+  const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
+  const target = duration / 6;
+  return durationIntervals.find((interval) => interval >= target) ?? 60;
+}
+
+function getMinorTickInterval(majorInterval: number, pixelsPerSecond?: number): number {
+  let interval = majorInterval / 2;
+  if (majorInterval >= 30) interval = majorInterval / 6;
+  else if (majorInterval >= 15) interval = majorInterval / 3;
+  else if (majorInterval >= 5) interval = majorInterval / 5;
+  else if (majorInterval >= 1) interval = majorInterval / 4;
+
+  if (
+    Number.isFinite(pixelsPerSecond) &&
+    (pixelsPerSecond ?? 0) > 0 &&
+    interval * (pixelsPerSecond ?? 0) < 20
+  ) {
+    return Math.max(0.25, majorInterval / 2);
+  }
+  return Math.max(0.25, interval);
+}
+
+export function generateTicks(
+  duration: number,
+  pixelsPerSecond?: number,
+): { major: number[]; minor: number[] } {
   if (duration <= 0 || !Number.isFinite(duration) || duration > 7200)
     return { major: [], minor: [] };
-  const intervals = [0.5, 1, 2, 5, 10, 15, 30, 60];
-  const target = duration / 6;
-  const majorInterval = intervals.find((i) => i >= target) ?? 60;
-  const minorInterval = Math.max(0.25, majorInterval / 2);
+  const majorInterval = getMajorTickInterval(duration, pixelsPerSecond);
+  const minorInterval = getMinorTickInterval(majorInterval, pixelsPerSecond);
   const major: number[] = [];
   const minor: number[] = [];
-  const maxTicks = 500; // Safety cap to prevent infinite loop
+  const maxTicks = 2000; // Safety cap to prevent runaway tick generation
   for (
     let t = 0;
     t <= duration + 0.001 && major.length + minor.length < maxTicks;
@@ -113,6 +144,25 @@ export function generateTicks(duration: number): { major: number[]; minor: numbe
   return { major, minor };
 }
 
+export function formatTimelineTickLabel(time: number, duration: number, majorInterval: number) {
+  if (!Number.isFinite(time)) return "0:00";
+  const safeTime = Math.max(0, time);
+  if (majorInterval < 1) {
+    const totalTenths = Math.round(safeTime * 10);
+    const wholeSeconds = Math.floor(totalTenths / 10);
+    const tenth = totalTenths % 10;
+    return `${formatTime(wholeSeconds)}.${tenth}`;
+  }
+  if (duration >= 3600 || safeTime >= 3600) {
+    const totalSeconds = Math.floor(safeTime);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
+  }
+  return formatTime(safeTime);
+}
+
 export function shouldAutoScrollTimeline(
   zoomMode: ZoomMode,
   scrollWidth: number,
@@ -131,6 +181,32 @@ export function getTimelineScrollLeftForZoomTransition(
   if (previousZoomMode === "manual" && nextZoomMode === "fit") return 0;
   return currentScrollLeft;
 }
+
+export function getTimelineScrollLeftForZoomAnchor(input: {
+  pointerX: number;
+  currentScrollLeft: number;
+  gutter: number;
+  currentPixelsPerSecond: number;
+  nextPixelsPerSecond: number;
+  duration: number;
+}): number {
+  const currentPps = Math.max(0, input.currentPixelsPerSecond);
+  const nextPps = Math.max(0, input.nextPixelsPerSecond);
+  if (
+    !Number.isFinite(input.pointerX) ||
+    !Number.isFinite(input.currentScrollLeft) ||
+    !Number.isFinite(input.duration) ||
+    input.duration <= 0 ||
+    currentPps <= 0 ||
+    nextPps <= 0
+  ) {
+    return Math.max(0, input.currentScrollLeft);
+  }
+  const timelineX = Math.max(0, input.currentScrollLeft + input.pointerX - input.gutter);
+  const timeAtPointer = Math.max(0, Math.min(input.duration, timelineX / currentPps));
+  return Math.max(0, input.gutter + timeAtPointer * nextPps - input.pointerX);
+}
+
 export function getTimelinePlayheadLeft(time: number, pixelsPerSecond: number): number {
   if (!Number.isFinite(time) || !Number.isFinite(pixelsPerSecond)) return GUTTER;
   return GUTTER + Math.max(0, time) * Math.max(0, pixelsPerSecond);
@@ -140,6 +216,14 @@ export function getTimelineCanvasHeight(trackCount: number): number {
   return RULER_H + Math.max(0, trackCount) * TRACK_H + TIMELINE_SCROLL_BUFFER;
 }
 
+export function shouldShowTimelineShortcutHint(
+  scrollHeight: number,
+  clientHeight: number,
+): boolean {
+  if (!Number.isFinite(scrollHeight) || !Number.isFinite(clientHeight)) return true;
+  return scrollHeight - clientHeight <= 1;
+}
+
 export function shouldHandleTimelineDeleteKey(input: {
   key: string;
   metaKey?: boolean;
@@ -304,6 +388,8 @@ export const Timeline = memo(function Timeline({
   const currentTime = usePlayerStore((s) => s.currentTime);
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
+  const setZoomMode = usePlayerStore((s) => s.setZoomMode);
+  const setManualZoomPercent = usePlayerStore((s) => s.setManualZoomPercent);
   const playheadRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -348,30 +434,51 @@ export const Timeline = memo(function Timeline({
   onDeleteElementRef.current = onDeleteElement;
   const suppressClickRef = useRef(false);
   const [showPopover, setShowPopover] = useState(false);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
   const [viewportWidth, setViewportWidth] = useState(0);
   const roRef = useRef<ResizeObserver | null>(null);
+  const shortcutHintRafRef = useRef(0);
+  const syncShortcutHintVisibility = useCallback(() => {
+    const scroll = scrollRef.current;
+    setShowShortcutHint(
+      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
+    );
+  }, []);
+  const scheduleShortcutHintVisibilitySync = useCallback(() => {
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    shortcutHintRafRef.current = requestAnimationFrame(() => {
+      shortcutHintRafRef.current = 0;
+      syncShortcutHintVisibility();
+    });
+  }, [syncShortcutHintVisibility]);
 
   // Callback ref: sets up ResizeObserver when the DOM element actually mounts.
   // useMountEffect can't work here because the component returns null on first
   // render (timelineReady=false), so containerRef.current is null when the
   // effect fires and the ResizeObserver is never created.
-  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
-    if (roRef.current) {
-      roRef.current.disconnect();
-      roRef.current = null;
-    }
-    containerRef.current = el;
-    if (!el) return;
-    setViewportWidth(el.clientWidth);
-    roRef.current = new ResizeObserver(([entry]) => {
-      setViewportWidth(entry.contentRect.width);
-    });
-    roRef.current.observe(el);
-  }, []);
+  const setContainerRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      containerRef.current = el;
+      if (!el) return;
+      setViewportWidth(el.clientWidth);
+      scheduleShortcutHintVisibilitySync();
+      roRef.current = new ResizeObserver(([entry]) => {
+        setViewportWidth(entry.contentRect.width);
+        scheduleShortcutHintVisibilitySync();
+      });
+      roRef.current.observe(el);
+    },
+    [scheduleShortcutHintVisibilitySync],
+  );
 
   // Clean up ResizeObserver on unmount
   useMountEffect(() => () => {
     roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
   });
 
   // Effective duration: max of store duration and the furthest element end.
@@ -416,6 +523,7 @@ export const Timeline = memo(function Timeline({
     }
     return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
   }, [draggedClip, trackOrder]);
+  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const selectedElement = useMemo(
     () => elements.find((element) => (element.key ?? element.id) === selectedElementId) ?? null,
     [elements, selectedElementId],
@@ -433,7 +541,11 @@ export const Timeline = memo(function Timeline({
   const trackContentWidth = Math.max(0, effectiveDuration * pps);
   const zoomModeRef = useRef(zoomMode);
   zoomModeRef.current = zoomMode;
+  const manualZoomPercentRef = useRef(manualZoomPercent);
+  manualZoomPercentRef.current = manualZoomPercent;
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
+  const fitPpsRef = useRef(fitPps);
+  fitPpsRef.current = fitPps;
 
   const durationRef = useRef(effectiveDuration);
   durationRef.current = effectiveDuration;
@@ -922,7 +1034,16 @@ export const Timeline = memo(function Timeline({
     cancelAnimationFrame(dragScrollRaf.current);
   }, []);
 
-  const { major, minor } = useMemo(() => generateTicks(effectiveDuration), [effectiveDuration]);
+  const { major, minor } = useMemo(
+    () => generateTicks(effectiveDuration, pps),
+    [effectiveDuration, pps],
+  );
+  const majorTickInterval =
+    major.length >= 2 ? Math.max(0.25, major[1] - major[0]) : effectiveDuration;
+  useEffect(() => {
+    syncShortcutHintVisibility();
+  }, [syncShortcutHintVisibility, timelineReady, elements.length, totalH]);
+
   const getPreviewElement = useCallback(
     (element: TimelineElement): TimelineElement => {
       if (resizingClip?.element.id === element.id) {
@@ -1008,6 +1129,57 @@ export const Timeline = memo(function Timeline({
     [onAssetDrop, onFileDrop],
   );
 
+  const handlePinchWheel = useCallback(
+    (e: WheelEvent) => {
+      if (!e.ctrlKey) return;
+      const scroll = scrollRef.current;
+      if (!scroll || durationRef.current <= 0 || fitPpsRef.current <= 0 || ppsRef.current <= 0) {
+        return;
+      }
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      const rect = scroll.getBoundingClientRect();
+      const pointerX = e.clientX - rect.left;
+      const nextZoomPercent = getPinchTimelineZoomPercent(
+        e.deltaY,
+        zoomModeRef.current,
+        manualZoomPercentRef.current,
+      );
+      if (nextZoomPercent === manualZoomPercentRef.current && zoomModeRef.current === "manual") {
+        return;
+      }
+
+      const nextPps = fitPpsRef.current * (nextZoomPercent / 100);
+      const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
+        pointerX,
+        currentScrollLeft: scroll.scrollLeft,
+        gutter: GUTTER,
+        currentPixelsPerSecond: ppsRef.current,
+        nextPixelsPerSecond: nextPps,
+        duration: durationRef.current,
+      });
+
+      setZoomMode("manual");
+      setManualZoomPercent(nextZoomPercent);
+      requestAnimationFrame(() => {
+        const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+        scroll.scrollLeft = Math.min(maxScrollLeft, nextScrollLeft);
+      });
+    },
+    [setManualZoomPercent, setZoomMode],
+  );
+
+  useEffect(() => {
+    const scroll = scrollRef.current;
+    if (!scroll) return;
+    scroll.addEventListener("wheel", handlePinchWheel, { passive: false, capture: true });
+    return () => {
+      scroll.removeEventListener("wheel", handlePinchWheel, { capture: true });
+    };
+  }, [handlePinchWheel, timelineReady, elements.length]);
+
   if (!timelineReady || elements.length === 0) {
     return (
       <div
@@ -1096,7 +1268,6 @@ export const Timeline = memo(function Timeline({
     );
   }
 
-  const totalH = getTimelineCanvasHeight(displayTrackOrder.length);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -1170,7 +1341,7 @@ export const Timeline = memo(function Timeline({
     <div
       ref={setContainerRef}
       aria-label="Timeline"
-      className={`border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
+      className={`relative border-t select-none h-full overflow-hidden ${shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
       style={{
         touchAction: "pan-x pan-y",
         background: theme.shellBackground,
@@ -1239,7 +1410,7 @@ export const Timeline = memo(function Timeline({
                   className="text-[9px] font-mono tabular-nums leading-none mb-0.5"
                   style={{ color: theme.tickText }}
                 >
-                  {formatTime(t)}
+                  {formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
                 </span>
                 <div className="w-px h-[5px]" style={{ background: theme.tickMajor }} />
               </div>
@@ -1509,8 +1680,8 @@ export const Timeline = memo(function Timeline({
         </div>
       </div>
 
-      {/* Keyboard shortcut hint — always visible */}
-      {!showPopover && !rangeSelection && (
+      {/* Keyboard shortcut hint */}
+      {showShortcutHint && !showPopover && !rangeSelection && (
         <div className="absolute bottom-2 right-3 pointer-events-none z-20">
           <div
             className="flex items-center gap-1.5 px-2 py-1 rounded-md border"

package/src/player/components/timelineEditing.test.ts

@@ -248,7 +248,7 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("disables move and trims for generic motion clips even when patchable", () => {
+  it("allows moving generic motion clips while keeping trims blocked", () => {
     expect(
       getTimelineEditCapabilities({
         tag: "section",
@@ -256,7 +256,7 @@ describe("getTimelineEditCapabilities", () => {
         selector: ".feature-card",
       }),
     ).toEqual({
-      canMove: false,
+      canMove: true,
       canTrimStart: false,
       canTrimEnd: false,
     });

package/src/player/components/timelineEditing.ts

@@ -233,7 +233,7 @@ export function getTimelineEditCapabilities(input: {
   const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
   const hasDeterministicWindow = isDeterministicTimelineWindow(input);
   return {
-    canMove: canPatch && hasDeterministicWindow,
+    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
     canTrimEnd: canPatch && hasFiniteDuration && hasDeterministicWindow,
     canTrimStart: canPatch && hasFiniteDuration && canOffsetTrimClipStart(input),
   };

package/src/player/components/timelineTheme.ts

@@ -63,12 +63,12 @@ const TRACK_STYLES: Record<string, TimelineTrackStyle> = {
 const DEFAULT_TRACK_STYLE: TimelineTrackStyle = createTrackStyle();
 
 export const defaultTimelineTheme: TimelineTheme = {
-  shellBackground: "#0A0E15",
+  shellBackground: "#0A0A0B",
   shellBorder: "rgba(255,255,255,0.05)",
   rulerBorder: "rgba(255,255,255,0.045)",
-  rowBackground: "#0A0E15",
+  rowBackground: "#0A0A0B",
   rowBorder: "rgba(255,255,255,0.05)",
-  gutterBackground: "#0D121B",
+  gutterBackground: "#0A0A0B",
   gutterBorder: "rgba(255,255,255,0.05)",
   textPrimary: "#E8EDF5",
   textSecondary: "#8391A8",

package/src/player/components/timelineZoom.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
   clampTimelineZoomPercent,
   getNextTimelineZoomPercent,
+  getPinchTimelineZoomPercent,
   getTimelinePixelsPerSecond,
   getTimelineZoomPercent,
   MAX_TIMELINE_ZOOM_PERCENT,
@@ -60,3 +61,23 @@ describe("getNextTimelineZoomPercent", () => {
     );
   });
 });
+
+describe("getPinchTimelineZoomPercent", () => {
+  it("zooms in for upward pinch wheel deltas", () => {
+    expect(getPinchTimelineZoomPercent(-80, "fit", 100)).toBeGreaterThan(100);
+  });
+
+  it("zooms out for downward pinch wheel deltas", () => {
+    expect(getPinchTimelineZoomPercent(80, "manual", 200)).toBeLessThan(200);
+  });
+
+  it("keeps the current zoom for zero or invalid deltas", () => {
+    expect(getPinchTimelineZoomPercent(0, "manual", 180)).toBe(180);
+    expect(getPinchTimelineZoomPercent(Number.NaN, "manual", 180)).toBe(180);
+  });
+
+  it("clamps pinch zoom to the supported range", () => {
+    expect(getPinchTimelineZoomPercent(10000, "manual", 100)).toBe(MIN_TIMELINE_ZOOM_PERCENT);
+    expect(getPinchTimelineZoomPercent(-10000, "manual", 100)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
+  });
+});

package/src/player/components/timelineZoom.ts

@@ -4,6 +4,7 @@ export const MIN_TIMELINE_ZOOM_PERCENT = 10;
 export const MAX_TIMELINE_ZOOM_PERCENT = 2000;
 const ZOOM_OUT_FACTOR = 0.8;
 const ZOOM_IN_FACTOR = 1.25;
+const PINCH_ZOOM_SENSITIVITY = 0.0035;
 
 export function clampTimelineZoomPercent(percent: number): number {
   if (!Number.isFinite(percent)) return 100;
@@ -36,3 +37,13 @@ export function getNextTimelineZoomPercent(
   const next = direction === "in" ? current * ZOOM_IN_FACTOR : current * ZOOM_OUT_FACTOR;
   return clampTimelineZoomPercent(next);
 }
+
+export function getPinchTimelineZoomPercent(
+  deltaY: number,
+  zoomMode: ZoomMode,
+  manualZoomPercent: number,
+): number {
+  const current = getTimelineZoomPercent(zoomMode, manualZoomPercent);
+  if (!Number.isFinite(deltaY) || deltaY === 0) return current;
+  return clampTimelineZoomPercent(current * Math.exp(-deltaY * PINCH_ZOOM_SENSITIVITY));
+}

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

@@ -1,10 +1,59 @@
 import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
+  findTimelineDomNodeForClip,
+  getTimelineElementSelector,
+  type ClipManifestClip,
   mergeTimelineElementsPreservingDowngrades,
   resolveStandaloneRootCompositionSrc,
+  shouldIgnorePlaybackShortcutEvent,
+  shouldIgnorePlaybackShortcutTarget,
 } from "./useTimelinePlayer";
 
+function createDocument(markup: string): Document {
+  const window = new Window();
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+function createClip(overrides: Partial<ClipManifestClip>): ClipManifestClip {
+  return {
+    id: null,
+    label: "",
+    start: 0,
+    duration: 4,
+    track: 0,
+    kind: "element",
+    tagName: "div",
+    compositionId: null,
+    parentCompositionId: null,
+    compositionSrc: null,
+    assetUrl: null,
+    ...overrides,
+  };
+}
+
+function mockTargetMatching(selectorNeedle: string): EventTarget {
+  return {
+    closest: (selector: string) => (selector.includes(selectorNeedle) ? ({} as Element) : null),
+  } as unknown as EventTarget;
+}
+
+function mockKeyboardEvent(
+  code: string,
+  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "target">> = {},
+): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "code" | "target"> {
+  return {
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    code,
+    target: mockTargetMatching("[data-missing]"),
+    ...overrides,
+  };
+}
+
 describe("buildStandaloneRootTimelineElement", () => {
   it("includes selector and source metadata for standalone composition fallback clips", () => {
     expect(
@@ -65,6 +114,38 @@ describe("resolveStandaloneRootCompositionSrc", () => {
   });
 });
 
+describe("findTimelineDomNodeForClip", () => {
+  it("matches anonymous manifest clips back to repeated DOM nodes in timeline order", () => {
+    const doc = createDocument(`
+      <div data-composition-id="main" data-start="0" data-duration="8">
+        <section id="identity-card" class="clip identity-card" data-start="0" data-duration="4" data-track-index="0"></section>
+        <div class="clip duplicate-card first" data-start="0" data-duration="4" data-track-index="1"></div>
+        <div class="clip duplicate-card second" data-start="0" data-duration="4" data-track-index="2"></div>
+      </div>
+    `);
+    const used = new Set<Element>();
+
+    const first = findTimelineDomNodeForClip(
+      doc,
+      createClip({ id: "__node__index_2", track: 1 }),
+      1,
+      used,
+    ) as HTMLElement;
+    used.add(first);
+    const second = findTimelineDomNodeForClip(
+      doc,
+      createClip({ id: "__node__index_3", track: 2 }),
+      2,
+      used,
+    ) as HTMLElement;
+
+    expect(first.className).toBe("clip duplicate-card first");
+    expect(second.className).toBe("clip duplicate-card second");
+    expect(getTimelineElementSelector(first)).toBe(".duplicate-card");
+    expect(getTimelineElementSelector(second)).toBe(".duplicate-card");
+  });
+});
+
 describe("mergeTimelineElementsPreservingDowngrades", () => {
   it("preserves missing current elements when a shorter manifest arrives", () => {
     expect(
@@ -94,3 +175,60 @@ describe("mergeTimelineElementsPreservingDowngrades", () => {
     ).toEqual([{ id: "hero", tag: "div", start: 0, duration: 4, track: 0 }]);
   });
 });
+
+describe("shouldIgnorePlaybackShortcutTarget", () => {
+  it("ignores focused toolbar buttons so Space can activate the button itself", () => {
+    expect(shouldIgnorePlaybackShortcutTarget(mockTargetMatching("button"))).toBe(true);
+  });
+
+  it("ignores the seek slider so ArrowRight reaches the slider key handler", () => {
+    expect(shouldIgnorePlaybackShortcutTarget(mockTargetMatching("[role='slider']"))).toBe(true);
+  });
+
+  it("allows non-interactive preview targets to use playback shortcuts", () => {
+    expect(shouldIgnorePlaybackShortcutTarget(mockTargetMatching("[data-missing]"))).toBe(false);
+  });
+});
+
+describe("shouldIgnorePlaybackShortcutEvent", () => {
+  it("ignores modified playback shortcuts so browser and app chords can handle them", () => {
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowLeft", { altKey: true })),
+    ).toBe(true);
+    expect(shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("KeyK", { ctrlKey: true }))).toBe(
+      true,
+    );
+    expect(shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("KeyL", { metaKey: true }))).toBe(
+      true,
+    );
+  });
+
+  it("defers Arrow frame shortcuts while caption edit mode has selected words", () => {
+    const captionSelection = { isCaptionEditMode: true, selectedCaptionSegmentCount: 1 };
+
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowLeft"), captionSelection),
+    ).toBe(true);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowRight"), captionSelection),
+    ).toBe(true);
+    expect(shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("KeyJ"), captionSelection)).toBe(
+      false,
+    );
+  });
+
+  it("allows Arrow frame shortcuts when captions are not selected", () => {
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowRight"), {
+        isCaptionEditMode: true,
+        selectedCaptionSegmentCount: 0,
+      }),
+    ).toBe(false);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowRight"), {
+        isCaptionEditMode: false,
+        selectedCaptionSegmentCount: 1,
+      }),
+    ).toBe(false);
+  });
+});