@hyperframes/studio 0.8.120 → 0.8.122

package/src/player/components/timelineSnapping.ts

@@ -1,6 +1,7 @@
 import type { TimelineElement } from "../store/playerStore";
+import { roundToCenti } from "../../utils/rounding";
 
-export type TimelineSnapType = "beat" | "playhead" | "clip-edge";
+export type TimelineSnapType = "beat" | "playhead" | "clip-edge" | "grid";
 
 export interface TimelineSnapTarget {
   time: number;
@@ -24,6 +25,7 @@ const TYPE_PRIORITY: Record<TimelineSnapType, number> = {
   playhead: 0,
   "clip-edge": 1,
   beat: 2,
+  grid: 3,
 };
 
 export function collectTimelineSnapTargets(input: {
@@ -31,8 +33,6 @@ export function collectTimelineSnapTargets(input: {
   playheadTime: number | null;
   beatTimes: readonly number[];
   excludeElementKey?: string | null;
-  /** A trim excludes the playhead: the dragged edge drives it, so snapping to it is circular. */
-  includePlayhead?: boolean;
 }): TimelineSnapTarget[] {
   const byTime = new Map<number, TimelineSnapTarget>();
   const add = (time: number, type: TimelineSnapType) => {
@@ -50,16 +50,30 @@ export function collectTimelineSnapTargets(input: {
     add(el.start, "clip-edge");
     add(el.start + el.duration, "clip-edge");
   }
-  if (input.playheadTime != null && input.includePlayhead !== false)
-    add(input.playheadTime, "playhead");
+  if (input.playheadTime != null) add(input.playheadTime, "playhead");
 
   return Array.from(byTime.values()).sort((a, b) => a.time - b.time);
 }
 
+/** Nearest ruler line in range, at its saved centisecond, and only within a pixel of it. */
+function nearestGridLine(
+  time: number,
+  gridStep: number,
+  thresholdSecs: number,
+): TimelineSnapTarget | null {
+  if (!(gridStep > 0)) return null;
+  const line = Math.round(time / gridStep) * gridStep;
+  const saved = roundToCenti(line);
+  const pixelsPerSecond = TIMELINE_SNAP_PX / thresholdSecs;
+  if (Math.abs(saved - line) * pixelsPerSecond >= 1) return null;
+  return Math.abs(saved - time) < thresholdSecs ? { time: saved, type: "grid" } : null;
+}
+
 export function snapTimelineTime(
   time: number,
   targets: readonly TimelineSnapTarget[],
   thresholdSecs: number,
+  gridStep = 0,
 ): { time: number; target: TimelineSnapTarget | null } {
   let best: TimelineSnapTarget | null = null;
   let bestDist = thresholdSecs;
@@ -73,6 +87,7 @@ export function snapTimelineTime(
       best = target;
     }
   }
+  best ??= nearestGridLine(time, gridStep, thresholdSecs);
   return best ? { time: best.time, target: best } : { time, target: null };
 }
 
@@ -88,23 +103,26 @@ export function snapMoveToTargets(
   targets: readonly TimelineSnapTarget[],
   pixelsPerSecond: number,
   timelineDuration: number,
+  gridStep = 0,
 ): { start: number; snapTime: number | null; snapType: TimelineSnapType | null } {
-  if (targets.length === 0) return { start, snapTime: null, snapType: null };
+  if (targets.length === 0 && !(gridStep > 0)) return { start, snapTime: null, snapType: null };
   const thresholdSecs = TIMELINE_SNAP_PX / Math.max(pixelsPerSecond, 1);
-  const startSnap = snapTimelineTime(start, targets, thresholdSecs);
-  const endSnap = snapTimelineTime(start + duration, targets, thresholdSecs);
-  const startMoved = startSnap.target !== null;
-  const endMoved = endSnap.target !== null;
+  const startSnap = snapTimelineTime(start, targets, thresholdSecs, gridStep);
+  const endSnap = snapTimelineTime(start + duration, targets, thresholdSecs, gridStep);
+  // The nearer edge wins, but a grid line only when neither edge has a real target.
+  const rank = (snap: typeof startSnap, edgeTime: number) =>
+    snap.target === null
+      ? Infinity
+      : Math.abs(snap.time - edgeTime) + (snap.target.type === "grid" ? thresholdSecs : 0);
+  const startRank = rank(startSnap, start);
+  const endRank = rank(endSnap, start + duration);
 
   let candidate = start;
   let target: TimelineSnapTarget | null = null;
-  if (
-    startMoved &&
-    (!endMoved || Math.abs(startSnap.time - start) <= Math.abs(endSnap.time - (start + duration)))
-  ) {
+  if (startRank !== Infinity && startRank <= endRank) {
     candidate = startSnap.time;
     target = startSnap.target;
-  } else if (endMoved) {
+  } else if (endRank !== Infinity) {
     candidate = endSnap.time - duration;
     target = endSnap.target;
   }

package/src/player/components/useTimelineClipDrag.resize.test.tsx

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
+import { usePreviewFrameStore } from "../store/previewFrameStore";
 import type { BlockedClipState, DraggedClipState, ResizingClipState } from "./useTimelineClipDrag";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
 import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
@@ -26,6 +27,7 @@ function el(id: string, over: Partial<TimelineElement> = {}): TimelineElement {
 afterEach(() => {
   document.body.innerHTML = "";
   usePlayerStore.getState().reset();
+  usePreviewFrameStore.setState({ time: null });
 });
 
 function renderResizeHarness(
@@ -34,7 +36,6 @@ function renderResizeHarness(
   options: {
     wireGroupResize?: boolean;
     snap?: boolean;
-    onSeek?: (time: number, seekOptions?: { keepPlaying?: boolean }) => void;
   } = {},
 ) {
   usePlayerStore.getState().setElements(elements);
@@ -65,7 +66,6 @@ function renderResizeHarness(
       onMoveElement,
       onBlockedEditAttempt,
       onResizeElements: options.wireGroupResize === false ? undefined : onResizeElements,
-      onSeek: options.onSeek,
       setShowPopover: vi.fn(),
       setRangeSelectionRef: { current: vi.fn() },
       sessionEpoch,
@@ -451,16 +451,7 @@ describe("useTimelineClipDrag — multi-select group resize (restored)", () => {
 });
 
 describe("useTimelineClipDrag — trim guide and preview frame", () => {
-  /** Playhead at 1.25s that follows preview seeks; clip a's end edge grabbed and dragged once. */
-  function trimEndWithSeekingPlayhead(state: { isPlaying?: boolean } = {}) {
-    usePlayerStore.setState({ currentTime: 1.25, ...state });
-    const onSeek = vi.fn((t: number) => usePlayerStore.setState({ currentTime: t }));
-    const a = el("a", { start: 1, duration: 2 });
-    const h = renderResizeHarness([a], [], { onSeek });
-    h.startResize(a, "end");
-    h.movePointer(50);
-    return { onSeek, h };
-  }
+  const previewFrame = () => usePreviewFrameStore.getState().time;
 
   /** Clip a (0-2s) with neighbour b starting at 5s, snapping on, a's end edge grabbed. */
   function trimAEndBesideB() {
@@ -487,45 +478,78 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
 
   it("publishes no snap target when the trimmed edge is free", () => {
     const h = trimAEndBesideB();
-    h.movePointer(150);
+    h.movePointer(162); // 3.62s: 12px from the 3.5s ruler line, 13px from 3.75s
     expect(h.getResizingClip()).toMatchObject({ snapTime: null, snapType: null });
     h.unmount();
   });
 
-  it("never snaps a trimmed edge to the playhead — the edge drives its own seek", () => {
-    usePlayerStore.setState({ currentTime: 5 }); // no clip edge or beat nearby, only the playhead
+  it("snaps a trimmed edge to the playhead, which stays where it was", () => {
+    usePlayerStore.setState({ currentTime: 5.1 }); // off the ruler grid; no clip edge or beat nearby
     const a = el("a", { start: 0, duration: 2 });
     const h = renderResizeHarness([a], [], { snap: true });
     h.startResize(a, "end");
-    h.movePointer(296); // a's end lands at 4.96s, 4px from the playhead
+    h.movePointer(306); // a's end lands at 5.06s, 4px from the playhead
+    expect(h.getResizingClip()).toMatchObject({
+      snapTime: 5.1,
+      snapType: "playhead",
+      previewDuration: 5.1,
+    });
+    expect(usePlayerStore.getState().currentTime).toBe(5.1);
+    h.unmount();
+  });
+
+  it("snaps a trimmed edge to the ruler's grid line when no clip edge is near", () => {
+    const h = trimAEndBesideB();
+    h.movePointer(152); // 3.52s, 2px from the 3.5s line (0.25s apart at 100px/s)
     expect(h.getResizingClip()).toMatchObject({
-      snapTime: null,
-      snapType: null,
-      previewDuration: 4.96,
+      snapTime: 3.5,
+      snapType: "grid",
+      previewDuration: 3.5,
     });
     h.unmount();
   });
 
-  it("shows the frame at the dragged edge, then puts the playhead back on release", async () => {
+  it("does not snap to the grid with the magnet off", () => {
+    const a = el("a", { start: 0, duration: 2 });
+    const h = renderResizeHarness([a], []);
+    h.startResize(a, "end");
+    h.movePointer(152);
+    expect(h.getResizingClip()).toMatchObject({ snapTime: null, previewDuration: 3.52 });
+    h.unmount();
+  });
+
+  it("shows the dragged edge's frame without moving the playhead, and drops it on release", async () => {
     usePlayerStore.setState({ currentTime: 1.25 });
-    const onSeek = vi.fn();
     const a = el("a", { start: 1, duration: 2 });
-    const h = renderResizeHarness([a], [], { onSeek });
+    const h = renderResizeHarness([a], []);
     h.startResize(a, "end");
     h.movePointer(50);
-    expect(onSeek).toHaveBeenLastCalledWith(3.5 - 1 / 30, { keepPlaying: true, follow: false });
+    expect(previewFrame()).toBeCloseTo(3.5 - 1 / 30, 6);
+    h.movePointer(120);
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
     await h.dropPointer();
-    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true, follow: false });
+    expect(previewFrame()).toBeNull();
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    h.unmount();
+  });
+
+  it("drops the preview frame when the trim is cancelled", () => {
+    const a = el("a", { start: 1, duration: 2 });
+    const h = renderResizeHarness([a], []);
+    h.startResize(a, "end");
+    h.movePointer(50);
+    expect(previewFrame()).not.toBeNull();
+    h.pressEscape();
+    expect(previewFrame()).toBeNull();
     h.unmount();
   });
 
   it("previews the new in-point when the start edge is trimmed", () => {
-    const onSeek = vi.fn();
     const a = el("a", { start: 1, duration: 2 });
-    const h = renderResizeHarness([a], [], { onSeek });
+    const h = renderResizeHarness([a], []);
     h.startResize(a, "start");
     h.movePointer(50);
-    expect(onSeek).toHaveBeenLastCalledWith(1.5, { keepPlaying: true, follow: false });
+    expect(previewFrame()).toBe(1.5);
     h.unmount();
   });
 
@@ -540,41 +564,17 @@ describe("useTimelineClipDrag — trim guide and preview frame", () => {
     h.unmount();
   });
 
-  it("restores the playhead it had before the first preview seek, not a seeked time", async () => {
-    const { onSeek, h } = trimEndWithSeekingPlayhead();
-    h.movePointer(80);
-    h.movePointer(120);
-    await h.dropPointer();
-    expect(onSeek).toHaveBeenLastCalledWith(1.25, { keepPlaying: true, follow: false });
-    h.unmount();
-  });
-
-  it("leaves the playhead where playback is when a trim is released while playing", async () => {
-    const { onSeek, h } = trimEndWithSeekingPlayhead({ isPlaying: true });
-    h.movePointer(120);
-    const callsBeforeRelease = onSeek.mock.calls.length;
-    await h.dropPointer();
-    expect(onSeek).toHaveBeenCalledTimes(callsBeforeRelease);
-    expect(onSeek).not.toHaveBeenCalledWith(1.25, expect.anything());
-    usePlayerStore.setState({ isPlaying: false });
-    h.unmount();
-  });
-
-  it("draws no guide and seeks to the rendered edge when a group member clamps the trim", () => {
-    const onSeek = vi.fn();
+  it("draws no guide and previews the rendered edge when a group member clamps the trim", () => {
     const a = el("a", { start: 0, duration: 4 });
     const b = el("b", { start: 0, duration: 1 });
     const c = el("c", { start: 2, duration: 1 });
-    const h = renderResizeHarness([a, b, c], ["a", "b"], { snap: true, onSeek });
+    const h = renderResizeHarness([a, b, c], ["a", "b"], { snap: true });
     h.startResize(a, "end");
     h.movePointer(-198); // a's raw end 2.02s snaps to c at 2s; b clamps the shared delta
     const clip = h.getResizingClip()!;
     expect(clip.previewStart + clip.previewDuration).toBeCloseTo(3.1, 3);
     expect(clip).toMatchObject({ snapTime: null, snapType: null });
-    expect(onSeek).toHaveBeenLastCalledWith(expect.closeTo(3.1 - 1 / 30, 3), {
-      keepPlaying: true,
-      follow: false,
-    });
+    expect(previewFrame()).toBeCloseTo(3.1 - 1 / 30, 3);
     h.unmount();
   });
 });

package/src/player/components/useTimelineClipDrag.ts

@@ -12,6 +12,8 @@ import {
   type TimelineGroupResizeSession,
 } from "./timelineGroupEditing";
 import { collectTimelineSnapTargets, type TimelineSnapTarget } from "./timelineSnapping";
+import { getTimelineGridStep, rulerFrameRate } from "./timelineRulerGeometry";
+import { setPreviewFrame } from "../store/previewFrameStore";
 import type { StackingPatch } from "./timelineStackingSync";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import {
@@ -76,8 +78,6 @@ interface UseTimelineClipDragInput {
   onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
   onLinkEdit?: TimelineEditCallbacks["onLinkEdit"];
-  /** Seeks the preview; a trim shows the frame at its dragged edge. */
-  onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;
   setShowPopover: (show: boolean) => void;
   /** Stable ref to the range selection setter — wired after mount to break circular dependency. */
   setRangeSelectionRef: React.RefObject<((sel: null) => void) | null>;
@@ -108,7 +108,6 @@ export function useTimelineClipDrag({
   onResizeElements,
   onBlockedEditAttempt,
   onLinkEdit,
-  onSeek,
   setShowPopover,
   setRangeSelectionRef,
   readZIndex,
@@ -165,15 +164,11 @@ export function useTimelineClipDrag({
   const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
 
   const buildSnapTargets = useCallback(
-    (
-      excludeElementKey: string | null,
-      includeBeats: boolean,
-      includePlayhead = true,
-    ): TimelineSnapTarget[] => {
+    (excludeElementKey: string | null, includeBeats: boolean): TimelineSnapTarget[] => {
       // Magnet off ⇒ no targets and no scan; do NOT cache so a mid-gesture toggle
       // back on starts scanning immediately (preserves the existing skip).
       if (!snapContextRef.current.enabled) return [];
-      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}|${includePlayhead ? 1 : 0}`;
+      const cacheKey = `${excludeElementKey ?? ""}|${includeBeats ? 1 : 0}`;
       const cached = snapTargetsCacheRef.current.get(cacheKey);
       if (cached) return cached;
       const targets = collectTimelineSnapTargets({
@@ -181,13 +176,18 @@ export function useTimelineClipDrag({
         playheadTime: usePlayerStore.getState().currentTime,
         beatTimes: includeBeats ? snapContextRef.current.beatTimes : [],
         excludeElementKey,
-        includePlayhead,
       });
       snapTargetsCacheRef.current.set(cacheKey, targets);
       return targets;
     },
     [],
   );
+  // The ruler's line spacing at the current zoom; 0 with the magnet off, like the targets.
+  const snapGridStep = useCallback(() => {
+    if (!snapContextRef.current.enabled) return 0;
+    const frameRate = rulerFrameRate(usePlayerStore.getState().timeDisplayMode);
+    return getTimelineGridStep(durationRef.current, ppsRef.current, frameRate);
+  }, [durationRef, ppsRef]);
 
   const [draggedClip, setDraggedClipState] = useState<DraggedClipState | null>(null);
   const draggedClipRef = useRef<DraggedClipState | null>(null);
@@ -285,10 +285,6 @@ export function useTimelineClipDrag({
   onResizeElementRef.current = onResizeElement;
   const onResizeElementsRef = useRef(onResizeElements);
   onResizeElementsRef.current = onResizeElements;
-  const onSeekRef = useRef(onSeek);
-  onSeekRef.current = onSeek;
-  // Playhead time before the first trim preview seek; restored when the gesture ends.
-  const trimSeekOriginRef = useRef<number | null>(null);
   const readZIndexRef = useRef(readZIndex);
   readZIndexRef.current = readZIndex;
   const onStackingPatchesRef = useRef(onStackingPatches);
@@ -325,6 +321,7 @@ export function useTimelineClipDrag({
         selectedKeys: gestureSelectedKeysRef.current,
         buildSnapTargets,
         audioTracks: dragAudioTracksRef.current,
+        gridStep: snapGridStep(),
       });
     },
     [
@@ -335,6 +332,7 @@ export function useTimelineClipDrag({
       trackInsertLayoutRef,
       rowGeometryRef,
       buildSnapTargets,
+      snapGridStep,
     ],
   );
 
@@ -349,15 +347,11 @@ export function useTimelineClipDrag({
         buildSnapTargets,
         elements: elementsRef.current,
         gestureKeys: gestureSelectedKeysRef.current,
+        gridStep: snapGridStep(),
       });
-      trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;
       const setResizeState = (v: ResizePreviewResult) => {
-        // A trim never changes the play state: keepPlaying lets seek() decide,
-        // and it only resumes playback if it was already playing.
-        onSeekRef.current?.(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration), {
-          keepPlaying: true,
-          follow: false,
-        });
+        // The preview shows the dragged edge's frame; the playhead stays where it was.
+        setPreviewFrame(trimPreviewTime(resize.edge, v.previewStart, v.previewDuration));
         publishResizingClip(
           resizingClipRef.current ? { ...resizingClipRef.current, started: true, ...v } : null,
         );
@@ -393,7 +387,7 @@ export function useTimelineClipDrag({
       }
       previewGroupResize(session, next, setResizeState);
     },
-    [scrollRef, ppsRef, buildSnapTargets, publishResizingClip],
+    [scrollRef, ppsRef, buildSnapTargets, snapGridStep, publishResizingClip],
   );
   const applyResizePointerRef = useRef(applyResizePointer);
   applyResizePointerRef.current = applyResizePointer;
@@ -404,13 +398,7 @@ export function useTimelineClipDrag({
       cancelAnimationFrame(clipDragScrollRaf.current);
       clipDragScrollRaf.current = 0;
     }
-    if (trimSeekOriginRef.current != null) {
-      // Paused: put the playhead back. Playing: leave it, a backward jump would rewind live playback.
-      if (!usePlayerStore.getState().isPlaying) {
-        onSeekRef.current?.(trimSeekOriginRef.current, { keepPlaying: true, follow: false });
-      }
-      trimSeekOriginRef.current = null;
-    }
+    setPreviewFrame(null);
     // Gesture teardown: drop frozen caches so the next gesture reads fresh state.
     snapTargetsCacheRef.current.clear();
     dragAudioTracksRef.current = null;

package/src/player/components/useTimelineProviderState.tsx

@@ -223,7 +223,6 @@ export function useTimelineProviderState({
     onResizeElements: pinnedOnResizeElements,
     onBlockedEditAttempt: oneShotEdits.onBlockedEditAttempt,
     onLinkEdit: oneShotEdits.onLinkEdit,
-    onSeek,
     setShowPopover,
     setRangeSelectionRef,
     readZIndex: zSyncEnabled ? readClipZIndex : undefined,

package/src/player/components/useTimelineTicks.ts

@@ -1,8 +1,11 @@
 import { useMemo } from "react";
-import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
-import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import {
+  generateTicks,
+  getTimelineMajorTickInterval,
+  rulerFrameRate,
+} from "./timelineRulerGeometry";
 
 export function useTimelineTicks(
   duration: number,
@@ -10,7 +13,7 @@ export function useTimelineTicks(
   timeDisplayMode: TimelineTimeDisplayMode,
   renderTimeRange?: TimelineTimeRange,
 ) {
-  const frameRate = timeDisplayMode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
+  const frameRate = rulerFrameRate(timeDisplayMode);
   const ticks = useMemo(
     () => generateTicks(duration, pixelsPerSecond, frameRate, renderTimeRange),
     [duration, frameRate, pixelsPerSecond, renderTimeRange],

package/src/player/hooks/timelinePlayerTestHarness.ts

@@ -5,12 +5,14 @@ import { createRoot } from "react-dom/client";
 import { vi } from "vitest";
 import { useTimelinePlayer, type UseTimelinePlayerOptions } from "./useTimelinePlayer";
 import { usePlayerStore } from "../store/playerStore";
+import { setPreviewFrame } from "../store/previewFrameStore";
 
 export type TimelinePlayerApi = ReturnType<typeof useTimelinePlayer>;
 
 export function resetPlayerStore() {
   usePlayerStore.getState().reset();
   usePlayerStore.setState({ requestedSeekTime: null });
+  setPreviewFrame(null);
 }
 
 function TimelinePlayerHarness({

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

@@ -12,6 +12,7 @@ import {
   resetPlayerStore,
 } from "./timelinePlayerTestHarness";
 import { liveTime, usePlayerStore } from "../store/playerStore";
+import { setPreviewFrame } from "../store/previewFrameStore";
 import { setTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -350,6 +351,71 @@ describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
   });
 });
 
+describe("useTimelinePlayer preview frame (a trim's dragged edge)", () => {
+  function previewFrame(time: number | null) {
+    act(() => setPreviewFrame(time));
+  }
+
+  it("shows the frame without moving the playhead, then puts the playhead's frame back", () => {
+    const { api, root, adapter } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 1.25);
+    const seeks = liveTime.seekCount();
+    previewFrame(3.4);
+    expect(adapter.getTime()).toBe(3.4);
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    expect(liveTime.latest()).toBe(1.25);
+    previewFrame(null);
+    expect(adapter.getTime()).toBe(1.25);
+    expect(liveTime.seekCount()).toBe(seeks);
+    unmountWithAct(root);
+  });
+
+  it("keeps the playhead's time when paused, played or reloaded over the frame", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    attachIframeWindow(getApi(), makeAdapterWindow().win);
+    seekWithAct(getApi(), 1.25);
+    previewFrame(3.4);
+    act(() => getApi().pause());
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    act(() => getApi().refreshPlayer());
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeFakeIframe(makeAdapterWindow().win);
+    shadow.src = "http://localhost/api/projects/demo/preview?_t=1";
+    act(() => {
+      getApi().setShadowIframeNode(shadow);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow);
+    expect(usePlayerStore.getState().currentTime).toBe(1.25);
+    previewFrame(3.5);
+    const live = (shadow.contentWindow as unknown as { __player: { getTime(): number } }).__player;
+    expect(live.getTime()).toBe(3.5);
+    act(() => getApi().play());
+    expect(live.getTime()).toBe(1.25);
+    unmountWithAct(root);
+  });
+
+  it("plays from the in-point when play rewinds from the end over the frame", () => {
+    const { api, root, adapter } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 30);
+    act(() => usePlayerStore.setState({ inPoint: 3 }));
+    previewFrame(12);
+    act(() => api.play());
+    expect(adapter.getTime()).toBe(3);
+    unmountWithAct(root);
+  });
+
+  it("leaves live playback alone", () => {
+    const { api, root, adapter } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 2);
+    setStorePlaying();
+    previewFrame(5);
+    expect(adapter.getTime()).toBe(2);
+    unmountWithAct(root);
+  });
+});
+
 describe("useTimelinePlayer RAF loop wrap-around", () => {
   type SeekCall = { time: number; options?: { keepPlaying?: boolean } };
 

package/src/player/hooks/useTimelinePlayer.ts

@@ -5,6 +5,8 @@ import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
 import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
 import { useShadowPreviewReload } from "./useShadowPreviewReload";
 import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
+import { subscribePreviewFrame, transportAdapter } from "../store/previewFrameStore";
+import { clampToDuration } from "../lib/time";
 import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
 import { logReload } from "../../utils/reloadDebug";
 
@@ -148,10 +150,11 @@ export function useTimelinePlayer({
         const iframe = overrideIframe !== undefined ? overrideIframe : iframeRef.current;
         const win = iframe?.contentWindow as IframeWindow | null;
         if (!iframe || !win) return null;
-        return resolvePlaybackAdapter(iframe, win, {
+        const adapter = resolvePlaybackAdapter(iframe, win, {
           cache: staticSeekAdapterRef,
           warned: staticSeekWarnedRef,
         });
+        return transportAdapter(adapter);
       } catch {
         return null;
       }
@@ -301,7 +304,7 @@ export function useTimelinePlayer({
         return false;
       }
       const duration = Math.max(0, adapter.getDuration());
-      const nextTime = Math.max(0, duration > 0 ? Math.min(duration, time) : time);
+      const nextTime = clampToDuration(time, duration);
       const keepPlaying = options?.keepPlaying === true;
       const shouldResumeAfterSeek = shouldResumeForwardPlaybackAfterSeek({
         keepPlaying,
@@ -366,6 +369,7 @@ export function useTimelinePlayer({
       }
     });
   }, [seek, play, pause]);
+  useEffect(() => subscribePreviewFrame(getAdapter), [getAdapter]);
   const { playbackKeyDownRef, playbackKeyUpRef, attachIframeShortcutListeners, togglePlay } =
     usePlaybackKeyboard({
       iframeRef,

package/src/player/lib/time.ts

@@ -1,5 +1,8 @@
 export const STUDIO_PREVIEW_FPS = 30;
 
+export const clampToDuration = (time: number, duration: number) =>
+  Math.max(0, duration > 0 ? Math.min(duration, time) : time);
+
 export function formatTime(time: number): string {
   if (!Number.isFinite(time) || time < 0) return "00:00";
   const mins = Math.floor(time / 60);

package/src/player/store/previewFrameStore.ts

@@ -0,0 +1,48 @@
+import { create } from "zustand";
+import type { PlaybackAdapter } from "../lib/playbackTypes";
+import { clampToDuration } from "../lib/time";
+import { usePlayerStore } from "./playerStore";
+
+/** A frame the preview shows without moving the playhead (a trim's dragged edge); null shows the playhead's. */
+export const usePreviewFrameStore = create<{ time: number | null }>(() => ({ time: null }));
+
+export const setPreviewFrame = (time: number | null) => usePreviewFrameStore.setState({ time });
+
+// A trim's edge frame is on screen, not the transport's time: pause, play and a reload's
+// hand-over read the playhead's time, and play starts from it unless the caller seeked first.
+function showingPreviewFrame(adapter: PlaybackAdapter): PlaybackAdapter {
+  let seeked = false;
+  const time = () => (seeked ? adapter.getTime() : usePlayerStore.getState().currentTime);
+  return {
+    play: () => {
+      adapter.seek(time());
+      adapter.play();
+    },
+    pause: () => adapter.pause(),
+    seek: (t, options) => {
+      seeked = true;
+      adapter.seek(t, options);
+    },
+    getTime: time,
+    getDuration: () => adapter.getDuration(),
+    isPlaying: () => adapter.isPlaying(),
+  };
+}
+
+/** The adapter as the transport must see it while a paused preview frame is on screen. */
+export function transportAdapter(adapter: PlaybackAdapter | null): PlaybackAdapter | null {
+  const showing = usePreviewFrameStore.getState().time !== null;
+  return adapter && showing && !usePlayerStore.getState().isPlaying
+    ? showingPreviewFrame(adapter)
+    : adapter;
+}
+
+/** Puts each preview frame on screen while paused, and the playhead's frame back when it clears. */
+export function subscribePreviewFrame(getAdapter: () => PlaybackAdapter | null): () => void {
+  return usePreviewFrameStore.subscribe((state, prev) => {
+    if (state.time === prev.time || usePlayerStore.getState().isPlaying) return;
+    const adapter = getAdapter();
+    const time = state.time ?? usePlayerStore.getState().currentTime;
+    adapter?.seek(clampToDuration(time, adapter.getDuration()));
+  });
+}