@hyperframes/studio 0.8.90 → 0.8.91

package/src/player/components/useTimelinePlayhead.test.tsx

@@ -1,12 +1,15 @@
 // @vitest-environment happy-dom
 
-import { act, createRef } from "react";
-import { createRoot } from "react-dom/client";
-import { describe, expect, it } from "vitest";
+import { act, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
+const ORIGIN = 32;
+
 function scrollBox(scrollLeft: number) {
   const el = document.createElement("div");
   let left = scrollLeft;
@@ -18,18 +21,34 @@ function scrollBox(scrollLeft: number) {
   return el;
 }
 
-function Harness({ pps, scroll }: { pps: number; scroll: HTMLDivElement }) {
+interface HarnessProps {
+  pps: number;
+  scroll: HTMLDivElement;
+  percent?: number;
+  dragging?: boolean;
+  zoomMode?: ZoomMode;
+}
+
+function Harness({
+  pps,
+  scroll,
+  percent = 100,
+  dragging = false,
+  zoomMode = "manual",
+}: HarnessProps) {
+  const scrollRef = useRef(scroll);
+  const durationRef = useRef(60);
   useTimelinePlayhead({
-    playheadRef: createRef(),
-    scrollRef: { current: scroll },
+    playheadRef: { current: document.createElement("div") },
+    scrollRef,
     ppsRef: { current: pps },
-    durationRef: { current: 60 },
-    isDragging: { current: false },
+    durationRef,
+    isDragging: { current: dragging },
     currentTime: 0,
-    zoomMode: "manual",
-    manualZoomPercent: 100,
-    zoomModeRef: { current: "manual" },
-    manualZoomPercentRef: { current: 100 },
+    zoomMode,
+    manualZoomPercent: percent,
+    zoomModeRef: { current: zoomMode },
+    manualZoomPercentRef: { current: percent },
     fitPps: pps,
     fitPpsRef: { current: pps },
     effectiveDuration: 60,
@@ -38,28 +57,198 @@ function Harness({ pps, scroll }: { pps: number; scroll: HTMLDivElement }) {
     elementsLength: 1,
     setZoomMode: () => {},
     setManualZoomPercent: () => {},
-    contentOrigin: 32,
+    contentOrigin: ORIGIN,
   });
   return null;
 }
 
-function zoom(scrollLeft: number, fromPps: number, toPps: number) {
-  const scroll = scrollBox(scrollLeft);
-  const host = document.createElement("div");
-  const root = createRoot(host);
-  act(() => root.render(<Harness pps={fromPps} scroll={scroll} />));
-  act(() => root.render(<Harness pps={toPps} scroll={scroll} />));
-  act(() => root.unmount());
-  return scroll.scrollLeft;
+const roots: Root[] = [];
+function mount(props: HarnessProps) {
+  const root = createRoot(document.createElement("div"));
+  roots.push(root);
+  act(() => root.render(<Harness {...props} />));
+  return (next: Partial<HarnessProps>, byPerson = false) =>
+    act(() => {
+      if (byPerson) usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
+      root.render(<Harness {...props} {...next} />);
+    });
 }
 
-describe("useTimelinePlayhead centre anchor", () => {
-  it("keeps a view at the start at the start when the scale changes", () => {
-    expect(zoom(0, 100, 114)).toBe(0);
+beforeEach(() => {
+  usePlayerStore.setState({ currentTime: 0, isPlaying: false, beatDragging: false });
+});
+afterEach(() => {
+  for (const root of roots.splice(0)) act(() => root.unmount());
+});
+
+/** Where the playhead at `time` sits inside the 800px viewport. */
+const onScreenX = (scroll: HTMLDivElement, time: number, pps: number) =>
+  ORIGIN + time * pps - scroll.scrollLeft;
+function expectVisible(scroll: HTMLDivElement, time: number, pps: number) {
+  const x = onScreenX(scroll, time, pps);
+  expect(x).toBeGreaterThanOrEqual(ORIGIN);
+  expect(x).toBeLessThanOrEqual(800);
+}
+
+describe("useTimelinePlayhead zoom anchor", () => {
+  it("keeps a view at the start at the start when the window resizes", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll })({ pps: 114 });
+    expect(scroll.scrollLeft).toBe(0);
   });
 
-  it("keeps the time at the viewport centre when the view is scrolled", () => {
+  it("keeps the time at the viewport centre when a scrolled window resizes", () => {
+    const scroll = scrollBox(400);
     // Centre time (400 + 400 - 32) / 100 = 7.68s lands at 32 + 7.68 * 200 - 400.
-    expect(zoom(400, 100, 200)).toBe(1168);
+    mount({ pps: 100, scroll })({ pps: 200 });
+    expect(scroll.scrollLeft).toBe(1168);
+  });
+
+  it("keeps a view at 00:00 on a resize even when the playhead is mid-film", () => {
+    usePlayerStore.setState({ currentTime: 6 });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll })({ pps: 150 });
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps the playhead where it is on screen when the toolbar zooms", () => {
+    usePlayerStore.setState({ currentTime: 6 });
+    const scroll = scrollBox(400);
+    const before = onScreenX(scroll, 6, 100);
+    mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+    expect(onScreenX(scroll, 6, 200)).toBeCloseTo(before);
+  });
+
+  it("stays at 00:00 when a zoom is set with the playhead at 0, as a zoom restored on open is", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, percent: 100 })({ pps: 250, percent: 250 }, true);
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps the centre on a resize after a toolbar zoom that hit the zoom limit", () => {
+    usePlayerStore.setState({ currentTime: 6 });
+    const scroll = scrollBox(400);
+    const update = mount({ pps: 100, scroll });
+    update({}, true);
+    update({ pps: 200 });
+    expect(scroll.scrollLeft).toBe(1168);
+  });
+
+  it("brings an off-screen playhead into view when the toolbar zooms", () => {
+    usePlayerStore.setState({ currentTime: 30 });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, percent: 100 })({ pps: 200, percent: 200 }, true);
+    expectVisible(scroll, 30, 200);
+  });
+});
+
+describe("useTimelinePlayhead zoom anchor, percent written by Studio itself", () => {
+  it("keeps 00:00 when the window resizes after an edit pinned the zoom", () => {
+    usePlayerStore.setState({ currentTime: 6 });
+    const scroll = scrollBox(0);
+    const update = mount({ pps: 100, scroll, percent: 200 });
+    update({ percent: 100 });
+    update({ pps: 130, percent: 100 });
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("leaves an off-screen playhead alone when a length change re-pins the zoom", () => {
+    usePlayerStore.setState({ currentTime: 30 });
+    const scroll = scrollBox(400);
+    const update = mount({ pps: 100, scroll, percent: 150 });
+    update({ pps: 90, percent: 150 });
+    update({ pps: 101, percent: 168 });
+    const x = onScreenX(scroll, 30, 101);
+    expect(x > 800 || x < ORIGIN).toBe(true);
+  });
+
+  it("anchors a person's zoom that lands on the percent already stored", () => {
+    usePlayerStore.setState({ currentTime: 30 });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, percent: 200 })({ pps: 200, percent: 200 }, true);
+    expectVisible(scroll, 30, 200);
+  });
+});
+
+describe("useTimelinePlayhead follow while paused", () => {
+  it("scrolls a paused seek that lands off screen into view", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(30));
+    expectVisible(scroll, 30, 100);
+  });
+
+  it("leaves the view alone when a paused seek lands on screen, even past the follow line", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(7));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("scrolls back to the playhead when a person seeks to the time it already has", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(30));
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notifySeek(30));
+    expectVisible(scroll, 30, 100);
+  });
+
+  it("keeps a person's scroll when a reload republishes the seek rounded to a frame", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(12.3456));
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notify(Math.floor(12.3456 * 30) / 30));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps a person's scroll when a reload follows a keyboard pause", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => usePlayerStore.setState({ isPlaying: true }));
+    act(() => liveTime.notify(30));
+    act(() => {
+      usePlayerStore.getState().setCurrentTime(30.012);
+      usePlayerStore.setState({ isPlaying: false });
+    });
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notify(30.012));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("keeps a person's scroll when a reload stops a reverse shuttle", () => {
+    usePlayerStore.setState({ currentTime: 30 });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => usePlayerStore.setState({ isPlaying: true }));
+    act(() => liveTime.notify(29));
+    act(() => liveTime.notify(20));
+    act(() => usePlayerStore.setState({ isPlaying: false }));
+    scroll.scrollLeft = 0;
+    act(() => liveTime.notify(20));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("does not scroll while the playhead is being dragged", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, dragging: true });
+    act(() => liveTime.notifySeek(30));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("does not scroll while a beat is being dragged past the edge", () => {
+    usePlayerStore.setState({ beatDragging: true });
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll });
+    act(() => liveTime.notifySeek(30));
+    expect(scroll.scrollLeft).toBe(0);
+  });
+
+  it("does not scroll in Fit", () => {
+    const scroll = scrollBox(0);
+    mount({ pps: 100, scroll, zoomMode: "fit" });
+    act(() => liveTime.notifySeek(30));
+    expect(scroll.scrollLeft).toBe(0);
   });
 });

package/src/player/components/useTimelinePlayhead.ts

@@ -12,6 +12,22 @@ import {
 import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
+function revealPlayheadScrollLeft(
+  scroll: HTMLDivElement,
+  playheadX: number,
+  contentOrigin: number,
+  from = scroll.scrollLeft,
+): number {
+  if (playheadX >= from + contentOrigin && playheadX <= from + scroll.clientWidth) return from;
+  return getTimelinePlaybackFollowScrollLeft({
+    playheadX,
+    currentScrollLeft: from,
+    viewportWidth: scroll.clientWidth,
+    contentOrigin,
+    maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
+  });
+}
+
 interface UseTimelinePlayheadInput {
   playheadRef: React.RefObject<HTMLDivElement | null>;
   scrollRef: React.RefObject<HTMLDivElement | null>;
@@ -58,10 +74,13 @@ export function useTimelinePlayhead({
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
-  // Center-anchored magnify: keep the time at the viewport center fixed when
-  // the zoom level (pps) changes via the toolbar / slider. The pinch handler
-  // anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+  // A toolbar zoom keeps the playhead in place; a resize keeps the centre, or 00:00 at the start.
+  // The pinch handler anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
   const previousAnchorPpsRef = useRef(pps);
+  const userZoomCount = usePlayerStore((s) => s.userZoomCount);
+  const previousZoomCountRef = useRef(userZoomCount);
+  const lastLiveTimeRef = useRef(usePlayerStore.getState().currentTime);
+  const lastSeekCountRef = useRef(liveTime.seekCount());
   const skipCenterAnchorRef = useRef(false);
   const contentOriginRef = useRef(contentOrigin);
   contentOriginRef.current = contentOrigin;
@@ -70,15 +89,22 @@ export function useTimelinePlayhead({
     const scroll = scrollRef.current;
     const prevPps = previousAnchorPpsRef.current;
     previousAnchorPpsRef.current = pps;
+    const prevZoomCount = previousZoomCountRef.current;
+    previousZoomCountRef.current = userZoomCount;
     // Always consume the skip flag, even when pps didn't change — otherwise a
     // pinch that produced no pps change (already at the zoom clamp) would strand
     // it true and the next toolbar zoom would wrongly skip center-anchoring.
     const skip = skipCenterAnchorRef.current;
     skipCenterAnchorRef.current = false;
-    // A view at the start stays there: a resize or a host zoom must not hide 00:00.
-    if (!scroll || pps === prevPps || skip || scroll.scrollLeft < 1) return;
+    if (!scroll || pps === prevPps || skip) return;
+    const zoomed = userZoomCount !== prevZoomCount;
+    if (!zoomed && scroll.scrollLeft < 1) return;
+    const time = Math.max(0, lastLiveTimeRef.current);
+    const playheadX = contentOrigin + time * prevPps;
+    const onScreen =
+      revealPlayheadScrollLeft(scroll, playheadX, contentOrigin) === scroll.scrollLeft;
     const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
-      pointerX: scroll.clientWidth / 2,
+      pointerX: zoomed && onScreen ? playheadX - scroll.scrollLeft : scroll.clientWidth / 2,
       currentScrollLeft: scroll.scrollLeft,
       contentOrigin,
       currentPixelsPerSecond: prevPps,
@@ -86,8 +112,11 @@ export function useTimelinePlayhead({
       duration: durationRef.current,
     });
     const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
-    scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft));
-  }, [pps, scrollRef, durationRef, contentOrigin]);
+    const anchored = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft));
+    scroll.scrollLeft = zoomed
+      ? revealPlayheadScrollLeft(scroll, contentOrigin + time * pps, contentOrigin, anchored)
+      : anchored;
+  }, [pps, userZoomCount, scrollRef, durationRef, contentOrigin]);
 
   const syncPlayheadPosition = useCallback(
     (time: number) => {
@@ -127,7 +156,6 @@ export function useTimelinePlayhead({
   }, [zoomMode, scrollRef]);
 
   useMountEffect(() => {
-    let lastLiveTime = usePlayerStore.getState().currentTime;
     const place = (t: number, atRest: boolean) => {
       if (!playheadRef.current || durationRef.current <= 0) return false;
       playheadRef.current.style.transform = getTimelinePlayheadTransform(
@@ -138,29 +166,30 @@ export function useTimelinePlayhead({
       );
       return true;
     };
+    const dragging = () => isDragging.current || usePlayerStore.getState().beatDragging;
     const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
-      if (prev.isPlaying && !state.isPlaying) place(lastLiveTime, true);
+      if (prev.isPlaying && !state.isPlaying) place(lastLiveTimeRef.current, true);
     });
+    lastSeekCountRef.current = liveTime.seekCount();
     const unsub = liveTime.subscribe((t) => {
-      lastLiveTime = t;
-      if (!place(t, !usePlayerStore.getState().isPlaying)) return;
+      const sought = liveTime.seekCount() !== lastSeekCountRef.current;
+      lastSeekCountRef.current = liveTime.seekCount();
+      lastLiveTimeRef.current = t;
+      const playing = usePlayerStore.getState().isPlaying;
+      if (!place(t, !playing)) return;
       const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
       const scroll = scrollRef.current;
-      if (
-        !scroll ||
-        !usePlayerStore.getState().isPlaying ||
-        isDragging.current ||
-        zoomModeRef.current === "fit"
-      ) {
-        return;
-      }
-      const nextScrollLeft = getTimelinePlaybackFollowScrollLeft({
-        playheadX,
-        currentScrollLeft: scroll.scrollLeft,
-        viewportWidth: scroll.clientWidth,
-        contentOrigin: contentOriginRef.current,
-        maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
-      });
+      // Paused, only a seek scrolls: a reload's republish, frame-rounded, must not undo a person's scroll.
+      if (!scroll || dragging() || zoomModeRef.current === "fit" || (!playing && !sought)) return;
+      const nextScrollLeft = playing
+        ? getTimelinePlaybackFollowScrollLeft({
+            playheadX,
+            currentScrollLeft: scroll.scrollLeft,
+            viewportWidth: scroll.clientWidth,
+            contentOrigin: contentOriginRef.current,
+            maxScrollLeft: scroll.scrollWidth - scroll.clientWidth,
+          })
+        : revealPlayheadScrollLeft(scroll, playheadX, contentOriginRef.current);
       if (Math.abs(nextScrollLeft - scroll.scrollLeft) >= 0.5) {
         scroll.scrollLeft = nextScrollLeft;
       }

package/src/player/components/useTimelineProviderState.tsx

@@ -548,6 +548,7 @@ export function useTimelineProviderState({
       ref: setScrollRef,
       tabIndex: -1,
       labelMode,
+      contentOrigin,
       zoomMode,
       onScroll: (e) => {
         lastScrollLeftRef.current = e.currentTarget.scrollLeft;

package/src/player/components/useTimelineZoom.ts

@@ -1,4 +1,5 @@
 // fallow-ignore-file dead-code
+import { useCallback } from "react";
 import { usePlayerStore, type ZoomMode } from "../store/playerStore";
 
 export interface TimelineZoomState {
@@ -13,6 +14,13 @@ export function useTimelineZoom(): TimelineZoomState {
   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 setStorePercent = usePlayerStore((s) => s.setManualZoomPercent);
+  const setManualZoomPercent = useCallback(
+    (percent: number) => {
+      usePlayerStore.setState((s) => ({ userZoomCount: s.userZoomCount + 1 }));
+      setStorePercent(percent);
+    },
+    [setStorePercent],
+  );
   return { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent };
 }

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

@@ -6,6 +6,8 @@ import type { useTimelinePlayer } from "./useTimelinePlayer";
 import {
   attachIframeAdapter,
   attachIframeWindow,
+  makeAdapterWindow,
+  makeFakeIframe,
   renderTimelinePlayerHarness,
   resetPlayerStore,
 } from "./timelinePlayerTestHarness";
@@ -263,6 +265,48 @@ describe("useTimelinePlayer audio controls (#835)", () => {
 });
 
 describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
+  it("publishes a seek as a person's seek, so a paused timeline follows it", () => {
+    const { root, api } = renderAttachedTimelinePlayer();
+    const before = liveTime.seekCount();
+    seekWithAct(api, 5);
+    expect(liveTime.seekCount()).toBe(before + 1);
+    expect(liveTime.latest()).toBe(5);
+    unmountWithAct(root);
+  });
+
+  it("does not count a reload's hand-over as a person's seek", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(makeAdapterWindow().win);
+      getApi().onIframeLoad();
+    });
+    seekWithAct(getApi(), 7);
+    act(() => getApi().refreshPlayer());
+    const seeks = liveTime.seekCount();
+    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(liveTime.latest()).toBe(7);
+    expect(liveTime.seekCount()).toBe(seeks);
+    unmountWithAct(root);
+  });
+
+  it("does not count the audition's return to the paused time as a person's seek", () => {
+    const { api, root } = renderAttachedTimelinePlayer();
+    seekWithAct(api, 4);
+    const seeks = liveTime.seekCount();
+    act(() => usePlayerStore.getState().requestPlayback(false, 2));
+    expect(liveTime.latest()).toBe(2);
+    expect(liveTime.seekCount()).toBe(seeks);
+    unmountWithAct(root);
+  });
+
   it("default seek() clears isPlaying when the store reports playing", () => {
     const { api, root } = renderAttachedTimelinePlayer();
     setStorePlaying();

package/src/player/hooks/useTimelinePlayer.ts

@@ -47,6 +47,9 @@ export interface UseTimelinePlayerOptions {
   onPreviewReloadFailed?: (message: string) => void;
 }
 
+const publishSeek = (time: number, options?: { follow?: boolean }) =>
+  options?.follow === false ? liveTime.notify(time) : liveTime.notifySeek(time);
+
 export function useTimelinePlayer({
   onShadowPromoted,
   onPreviewReloadFailed,
@@ -276,7 +279,7 @@ export function useTimelinePlayer({
     stopRAFLoop();
   }, [getAdapter, setCurrentTime, setIsPlaying, stopRAFLoop, stopReverseLoop]);
   const seek = useCallback(
-    (time: number, options?: { keepPlaying?: boolean }) => {
+    (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => {
       const wasReverseShuttle = shuttleDirectionRef.current === "backward";
       stopReverseLoop();
       const adapter = getAdapter();
@@ -295,7 +298,7 @@ export function useTimelinePlayer({
         nextTime,
       });
       adapter.seek(nextTime, options);
-      liveTime.notify(nextTime); // Direct DOM updates (playhead, timecode, progress) — no re-render
+      publishSeek(nextTime, options); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
       if (!shouldResumeAfterSeek && !keepPlaying) scrubMusicAtSeek(iframeRef.current, nextTime);
       if (shouldResumeAfterSeek) {
@@ -344,7 +347,7 @@ export function useTimelinePlayer({
         if (request.playing) play();
         else {
           pause();
-          if (request.returnTo !== null) seek(request.returnTo);
+          if (request.returnTo !== null) seek(request.returnTo, { follow: false });
         }
         usePlayerStore.getState().clearPlaybackRequest();
       }
@@ -409,7 +412,7 @@ export function useTimelinePlayer({
     onReloadFailed: onPreviewReloadFailed,
     handOverPlayback: (time, playing) => {
       // keepPlaying: move the playhead without the paused-seek audio scrub.
-      seek(time, { keepPlaying: true });
+      seek(time, { keepPlaying: true, follow: false });
       const adapter = getAdapter();
       // An edit that cut the film short of the live time stops it at the new end, as playback does.
       if (playing && adapter && adapter.getTime() < adapter.getDuration()) play();

package/src/player/lib/timelineDOM.test.ts

@@ -7,6 +7,8 @@ import {
   mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
+import { clipTimingStart, resolveClipTimingBasis } from "../../hooks/gsapShared";
+import { toAuthoredStart } from "../store/timelineElement";
 import { computeResizePreview } from "../components/timelineClipDragPreview";
 import type { TimelineElement } from "../store/playerStore";
 import {
@@ -25,6 +27,83 @@ function makeDoc(html: string): Document {
   return d;
 }
 
+describe("parseTimelineFromDOM — nested master time", () => {
+  it("adds every enclosing host's start to a clip inside a sub-composition", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="intro" data-composition-id="intro" data-start="2" data-duration="10">
+          <div data-composition-id="intro">
+            <div id="logo" data-composition-id="logo" data-start="3" data-duration="5">
+              <div data-composition-id="logo">
+                <div id="badge" class="clip" data-start="1" data-duration="2"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `);
+    const starts = parseTimelineFromDOM(doc, 20).map((e) => [
+      e.domId,
+      e.start,
+      e.parentCompositionStart,
+    ]);
+    expect(starts).toEqual([
+      ["intro", 2, 0],
+      ["logo", 5, 2],
+      ["badge", 6, 5],
+    ]);
+  });
+
+  it("places a clip inside a referenced scene after the scene's authored length", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="s1" data-composition-id="s1" data-start="0" data-hf-authored-duration="8"></div>
+        <div id="s2" data-composition-id="s2" data-start="s1 + 1" data-duration="6">
+          <div data-composition-id="s2">
+            <div id="c" class="clip" data-start="1" data-duration="2"></div>
+          </div>
+        </div>
+      </div>
+    `);
+    const timelines = { s1: { duration: () => 6 } } as never;
+    const c = parseTimelineFromDOM(doc, 20, timelines).find((e) => e.domId === "c");
+    expect(c?.start).toBe(10);
+  });
+});
+
+describe("parseTimelineFromDOM — nested rows' keyframe basis", () => {
+  const doc = () =>
+    makeDoc(`
+      <div data-composition-id="main" data-start="0" data-duration="20">
+        <div id="intro" data-composition-id="intro" data-start="2" data-duration="10">
+          <div data-composition-id="intro">
+            <video id="vo" data-start="7" data-duration="2" data-hf-media-start-basis="global"></video>
+            <div id="logo" data-composition-id="logo" data-start="3" data-duration="5">
+              <div data-composition-id="logo">
+                <div id="badge" class="clip" data-start="1" data-duration="2"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `);
+
+  it("measures diamonds and keyframe percentages against the local tween clock", () => {
+    const rows = parseTimelineFromDOM(doc(), 20);
+    const basis = (id: string) => resolveClipTimingBasis(id, "index.html", rows, []).elStart;
+    const at = (id: string) => rows.find((e) => e.domId === id)!;
+    expect([clipTimingStart(at("logo")), basis("logo")]).toEqual([3, 3]);
+    expect([clipTimingStart(at("badge")), basis("badge")]).toEqual([1, 1]);
+  });
+
+  it("keys a legacy root-time video on its host's clock but writes its start as master time", () => {
+    const vo = parseTimelineFromDOM(doc(), 20).find((e) => e.domId === "vo")!;
+    expect(vo.start).toBe(7);
+    expect(clipTimingStart(vo)).toBe(5);
+    expect(toAuthoredStart(vo, 8)).toBe(8);
+  });
+});
+
 describe("parseTimelineFromDOM — media in-point", () => {
   it("reads a negative in-point as 0, as the runtime does, so a head trim keeps the clip", () => {
     const doc = makeDoc(`