@hyperframes/studio 0.8.74 → 0.8.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.74",
+  "version": "0.8.75",
   "description": "",
   "repository": {
     "type": "git",
@@ -52,11 +52,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.74",
-    "@hyperframes/parsers": "0.8.74",
-    "@hyperframes/sdk": "0.8.74",
-    "@hyperframes/studio-server": "0.8.74",
-    "@hyperframes/player": "0.8.74"
+    "@hyperframes/core": "0.8.75",
+    "@hyperframes/player": "0.8.75",
+    "@hyperframes/parsers": "0.8.75",
+    "@hyperframes/sdk": "0.8.75",
+    "@hyperframes/studio-server": "0.8.75"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -72,7 +72,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.74"
+    "@hyperframes/producer": "0.8.75"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/timelineEditingHelpers.ts

@@ -182,6 +182,17 @@ export function patchIframeDomTiming(
   }
 }
 
+/** Takes deleted clips out of the live preview at once: until the reload lands, anything that re-reads the
+ *  preview (composition enrichment) would otherwise put them back on the timeline. */
+export function removeIframeTimelineElements(
+  iframe: HTMLIFrameElement | null,
+  elements: TimelineElement[],
+  activeCompositionPath: string | null = null,
+): void {
+  for (const element of elements)
+    findTimelineElementInIframe(iframe, element, activeCompositionPath)?.remove();
+}
+
 export function playbackStartAttributeForElement(
   element: Pick<TimelineElement, "kind" | "playbackStartAttr">,
 ): "data-media-start" | "data-playback-start" {

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -2,7 +2,7 @@
 
 import { act } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { TimelineElement } from "../player";
+import { usePlayerStore, type TimelineElement } from "../player";
 import { applyRippleShifts, useTimelineDeleteOps } from "./useTimelineDeleteOps";
 import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
@@ -78,9 +78,30 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
       return null;
     }
     mountReactHarness(<Harness />);
-    return { b: elements[1], getHook: () => hook! };
+    return { elements, b: elements[1], getHook: () => hook! };
   }
 
+  it("drops the deleted clip from the timeline while the ripple is still saving", async () => {
+    let finishRipple = () => {};
+    const handleTimelineGroupMove = vi.fn(
+      () => new Promise<void>((resolve) => (finishRipple = resolve)),
+    );
+    const { elements, b, getHook } = mountDeleteHarness({ handleTimelineGroupMove });
+    usePlayerStore.getState().setElements(elements);
+
+    let deleting = Promise.resolve();
+    await act(async () => {
+      deleting = getHook().handleTimelineElementDelete(b);
+      await vi.waitFor(() => expect(handleTimelineGroupMove).toHaveBeenCalled());
+    });
+    expect(usePlayerStore.getState().elements.map((e) => e.id)).toEqual(["hf-a", "hf-c"]);
+
+    await act(async () => {
+      finishRipple();
+      await deleting;
+    });
+  });
+
   // editHistory.ts's coalescing keeps the LAST recordEdit call's label, so the
   // folded ripple move must carry the delete's label, not its own.
   it("passes the delete's own label to the folded ripple move, not 'Move timeline clips'", async () => {
@@ -228,3 +249,65 @@ describe("useTimelineDeleteOps: undo race", () => {
     });
   });
 });
+
+// Regression: the live preview kept a deleted clip until its reload landed, and composition
+// enrichment re-read it from there, so the clip stayed drawn after the file dropped it.
+describe("useTimelineDeleteOps: live preview", () => {
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-composition-id="main" data-duration="4">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+</div>
+</body></html>`;
+
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(JSON.stringify({ changed: true, content: html }))),
+    );
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+  });
+
+  it("takes the deleted clip out of the live preview before its reload", async () => {
+    const preview = document.implementation.createHTMLDocument();
+    preview.documentElement.innerHTML = html;
+    const iframe = { contentDocument: preview } as unknown as HTMLIFrameElement;
+    const clip = (id: string, start: number): TimelineElement => ({
+      id,
+      tag: "div",
+      start,
+      duration: 2,
+      track: 0,
+      hfId: id,
+      sourceFile: "index.html",
+    });
+    const elements = [clip("hf-a", 0), clip("hf-b", 2)];
+    let hook: ReturnType<typeof useTimelineDeleteOps> | null = null;
+    function Harness() {
+      hook = useTimelineDeleteOps({
+        projectIdRef: { current: "test-project" },
+        activeCompPath: "index.html",
+        timelineElements: elements,
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        recordEdit: vi.fn().mockResolvedValue(undefined),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: iframe },
+        handleTimelineGroupMove: vi.fn().mockResolvedValue(undefined),
+      });
+      return null;
+    }
+    mountReactHarness(<Harness />);
+
+    await act(async () => {
+      await hook!.handleTimelineElementDelete(elements[1]);
+    });
+
+    expect(preview.querySelector('[data-hf-id="hf-b"]')).toBeNull();
+    expect(preview.querySelector('[data-hf-id="hf-a"]')).not.toBeNull();
+  });
+});

package/src/hooks/useTimelineDeleteOps.ts

@@ -8,7 +8,7 @@ import { usePlayerStore } from "../player";
 import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { getTimelineElementLabel } from "../utils/studioHelpers";
-import { buildPatchTarget } from "./timelineEditingHelpers";
+import { buildPatchTarget, removeIframeTimelineElements } from "./timelineEditingHelpers";
 import { captureDurationRollback, readFileContent } from "./timelineTimingSync";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
@@ -172,6 +172,7 @@ export function useTimelineDeleteOps({
           throw error;
         }
 
+        removeIframeTimelineElements(previewIframeRef.current, sameFile, activeCompPath);
         const deletedKeys = new Set(sameFile.map((te) => te.key ?? te.id));
         const survivors = timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id));
 
@@ -184,10 +185,11 @@ export function useTimelineDeleteOps({
           sameFile,
           usePlayerStore.getState().rippleEditEnabled,
         );
-        let rippleApplied: TimelineGroupMoveChange[] | null = null;
+        const rippleChanges = rippleShifts ? resolveShiftedElements(survivors, rippleShifts) : null;
+        // The timeline follows the delete's write at once, as the owner of the ripple's optimistic update.
+        usePlayerStore.getState().setElements(applyRippleShifts(survivors, rippleChanges));
         let rippleFailed = false;
-        if (rippleShifts) {
-          const rippleChanges = resolveShiftedElements(survivors, rippleShifts);
+        if (rippleChanges) {
           try {
             await handleTimelineGroupMove(rippleChanges, {
               coalesceKey,
@@ -200,18 +202,17 @@ export function useTimelineDeleteOps({
               // the generic one would tell the user about one action twice.
               suppressFailureToast: true,
             });
-            rippleApplied = rippleChanges;
           } catch (error) {
             // The delete already committed; a failed ripple leaves the gap the
             // toggle-off behaviour would have left anyway — not worth undoing
             // an otherwise-successful delete over.
             rippleFailed = true;
+            usePlayerStore.getState().setElements(survivors);
             console.error("[Timeline] ripple-edit failed to persist after delete", error);
             showToast("Clip deleted, but the gap could not be closed.", "error");
           }
         }
 
-        usePlayerStore.getState().setElements(applyRippleShifts(survivors, rippleApplied));
         usePlayerStore.getState().setSelectedElementId(null);
         usePlayerStore.getState().setSelectedElementIds(new Set());
         forceReloadSdkSession?.();
@@ -224,7 +225,7 @@ export function useTimelineDeleteOps({
             "info",
           );
         }
-        if (rippleApplied && !rippleNoticeShownRef.current) {
+        if (rippleChanges && !rippleFailed && !rippleNoticeShownRef.current) {
           rippleNoticeShownRef.current = true;
           showToast(
             "Ripple closed the gap on the main track. Undo (⌘Z) restores it, or turn off " +

package/src/player/components/PlayheadIndicator.tsx

@@ -11,6 +11,9 @@
  */
 import { PLAYHEAD_HEAD_W } from "./timelineLayout";
 
+/** Widest part of the playhead, centred on its line. */
+export const PLAYHEAD_GLOW_W = 13;
+
 interface PlayheadIndicatorProps {
   /** CSS color, defaults to the HF accent variable */
   color?: string;
@@ -50,7 +53,7 @@ export function PlayheadIndicator({
         className="absolute top-0 bottom-0"
         style={{
           left: "50%",
-          width: 13,
+          width: PLAYHEAD_GLOW_W,
           transform: "translateX(-50%)",
           background: `radial-gradient(closest-side, ${glowColor}, transparent)`,
         }}

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

@@ -88,9 +88,7 @@ function getHorizontalGeometry(host: HTMLElement, clipId: string, tickLabel: str
   if (!ruler) throw new Error("Missing timeline ruler");
   const rulerOrigin = ruler.previousElementSibling;
   if (!(rulerOrigin instanceof HTMLElement)) throw new Error("Missing timeline ruler origin");
-  const playhead = Array.from(host.querySelectorAll<HTMLElement>("div")).find(
-    (node) => node.style.zIndex === "100",
-  );
+  const playhead = host.querySelector<HTMLElement>("[data-timeline-playhead-layer] > div");
   if (!playhead) throw new Error("Missing timeline playhead");
   return { clip, trackHeader, rulerTick, rulerOrigin, playhead };
 }

package/src/player/components/Timeline.virtualization.test.tsx

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
 
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -430,6 +431,26 @@ describe("Timeline without row virtualization", { timeout: 30_000 }, () => {
     };
   }
 
+  it("clips a scrolled-off playhead at the track headers once the scroll settles", async () => {
+    const { host, dispose } = await renderUnvirtualizedTimeline();
+    try {
+      const scroller = host.querySelector<HTMLElement>("[data-timeline-scroll-viewport]")!;
+      const layer = () => host.querySelector<HTMLElement>("[data-timeline-playhead-layer]");
+      await scrollTimelineHorizontally(scroller, 166);
+      expect(layer()?.style.clipPath).toBe("");
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, TIMELINE_SCROLL_SETTLE_MS + 20));
+      });
+      // The ruler's corner is as wide as the track headers; the glow may overhang by 6.5px.
+      const headerWidth = parseFloat(
+        host.querySelector<HTMLElement>(".sticky.left-0")!.style.width,
+      );
+      expect(layer()?.style.clipPath).toContain(`${166 + headerWidth - 6.5}px)`);
+    } finally {
+      dispose();
+    }
+  });
+
   it("mounts every clip rather than a window", async () => {
     const { host, dispose } = await renderUnvirtualizedTimeline();
     try {

package/src/player/components/TimelineCanvas.tsx

@@ -1,6 +1,7 @@
 import { memo } from "react";
 import { TimelineRulerPart } from "./TimelineRulerPart";
 import { PlayheadIndicator } from "./PlayheadIndicator";
+import { TimelinePlayheadLayer } from "./TimelinePlayheadLayer";
 import {
   RULER_H,
   CLIP_Y,
@@ -236,18 +237,19 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           the half-head offset baked into getTimelinePlayheadLeft keep the
           inner 1px line's CENTER exactly on contentOrigin + t * pps (the ruler
           ticks' center), instead of relying on shrink-wrap sizing. */}
-      <div
-        ref={props.playheadRef}
-        className="absolute top-0 bottom-0 pointer-events-none"
-        style={{
-          left: `${getTimelinePlayheadLeft(0, 0, props.contentOrigin)}px`,
-          width: PLAYHEAD_HEAD_W,
-          zIndex: 100,
-          display: beatDragging ? "none" : undefined,
-        }}
-      >
-        <PlayheadIndicator scrubbing={props.isScrubbing} />
-      </div>
+      <TimelinePlayheadLayer scrollRef={props.scrollRef} contentOrigin={props.contentOrigin}>
+        <div
+          ref={props.playheadRef}
+          className="absolute top-0 bottom-0 pointer-events-none"
+          style={{
+            left: `${getTimelinePlayheadLeft(0, 0, props.contentOrigin)}px`,
+            width: PLAYHEAD_HEAD_W,
+            display: beatDragging ? "none" : undefined,
+          }}
+        >
+          <PlayheadIndicator scrubbing={props.isScrubbing} />
+        </div>
+      </TimelinePlayheadLayer>
     </div>
   );
 });

package/src/player/components/TimelinePlayheadLayer.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode, RefObject } from "react";
+import { PLAYHEAD_GLOW_W } from "./PlayheadIndicator";
+import { useSettledScrollLeft } from "./useSettledScrollLeft";
+
+// Clips the playhead at the track headers' edge once a scroll settles, so one scrolled off to
+// the left does not draw over the track names. Half the glow may pass the edge so 00:00 looks
+// as before; mid-scroll it is not clipped.
+export function TimelinePlayheadLayer({
+  scrollRef,
+  contentOrigin,
+  children,
+}: {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  contentOrigin: number;
+  children: ReactNode;
+}) {
+  const settledScrollLeft = useSettledScrollLeft(scrollRef);
+  return (
+    <div
+      data-timeline-playhead-layer=""
+      className="absolute inset-0 pointer-events-none"
+      style={{
+        zIndex: 100,
+        clipPath:
+          settledScrollLeft === null
+            ? undefined
+            : `inset(0 0 0 ${settledScrollLeft + contentOrigin - PLAYHEAD_GLOW_W / 2}px)`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/player/components/TimelineRuler.tsx

@@ -1,5 +1,5 @@
-import { memo, useCallback, useRef, useSyncExternalStore, type RefObject } from "react";
-import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
+import { memo, type RefObject } from "react";
+import { useSettledScrollLeft } from "./useSettledScrollLeft";
 import type { TimelineTheme } from "./timelineTheme";
 import { RULER_H, getTimelineBeatEntries } from "./timelineLayout";
 import { formatTimelineTickLabel } from "./timelineRulerGeometry";
@@ -41,11 +41,8 @@ function tickIndexUnderHeader(major: number[], pps: number, scrollLeft: number):
   return found;
 }
 
-/**
- * Paints over the one label the header corner would slice, once a scroll settles. Moving it
- * on every tick crossing cost 2-3x the scroll budget on a large timeline, so mid-scroll a
- * fragment can still show.
- */
+// Paints over the one label the header corner would slice, once a scroll settles; mid-scroll a
+// fragment can still show.
 const HeaderSlicedLabelMask = memo(function HeaderSlicedLabelMask({
   scrollRef,
   major,
@@ -57,39 +54,9 @@ const HeaderSlicedLabelMask = memo(function HeaderSlicedLabelMask({
   pps: number;
   background: string;
 }) {
-  const scrollingRef = useRef(false);
-  const subscribe = useCallback(
-    (onChange: () => void) => {
-      const el = scrollRef.current;
-      let settle: ReturnType<typeof setTimeout> | undefined;
-      const onScroll = () => {
-        if (!scrollingRef.current) {
-          scrollingRef.current = true;
-          onChange();
-        }
-        clearTimeout(settle);
-        settle = setTimeout(() => {
-          scrollingRef.current = false;
-          onChange();
-        }, TIMELINE_SCROLL_SETTLE_MS);
-      };
-      el?.addEventListener("scroll", onScroll, { passive: true });
-      return () => {
-        clearTimeout(settle);
-        scrollingRef.current = false;
-        el?.removeEventListener("scroll", onScroll);
-      };
-    },
-    [scrollRef],
-  );
-  const index = useSyncExternalStore(
-    subscribe,
-    () =>
-      scrollingRef.current
-        ? -1
-        : tickIndexUnderHeader(major, pps, scrollRef.current?.scrollLeft ?? 0),
-    () => -1,
-  );
+  const settledScrollLeft = useSettledScrollLeft(scrollRef);
+  const index =
+    settledScrollLeft === null ? -1 : tickIndexUnderHeader(major, pps, settledScrollLeft);
   if (index < 0) return null;
   const labelLeft = major[index]! * pps - 0.5 + TICK_LABEL_INSET_PX;
   const next = major[index + 1];

package/src/player/components/useSettledScrollLeft.ts

@@ -0,0 +1,38 @@
+import { useCallback, useRef, useSyncExternalStore, type RefObject } from "react";
+import { TIMELINE_SCROLL_SETTLE_MS } from "./useTimelineScrollViewport";
+
+// The timeline viewport's scrollLeft once a scroll settles, or null while it is scrolling. Readers
+// re-render twice per gesture, never per frame: per-frame work cost 2-3x the viewport gate's budget
+// on a large unvirtualized timeline.
+export function useSettledScrollLeft(scrollRef: RefObject<HTMLDivElement | null>): number | null {
+  const scrollingRef = useRef(false);
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const el = scrollRef.current;
+      let settle: ReturnType<typeof setTimeout> | undefined;
+      const onScroll = () => {
+        if (!scrollingRef.current) {
+          scrollingRef.current = true;
+          onChange();
+        }
+        clearTimeout(settle);
+        settle = setTimeout(() => {
+          scrollingRef.current = false;
+          onChange();
+        }, TIMELINE_SCROLL_SETTLE_MS);
+      };
+      el?.addEventListener("scroll", onScroll, { passive: true });
+      return () => {
+        clearTimeout(settle);
+        scrollingRef.current = false;
+        el?.removeEventListener("scroll", onScroll);
+      };
+    },
+    [scrollRef],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => (scrollingRef.current ? null : (scrollRef.current?.scrollLeft ?? 0)),
+    () => null,
+  );
+}

package/src/player/hooks/useShadowPreviewReload.ts

@@ -14,6 +14,7 @@ import {
 } from "./useTimelineSyncCallbacks";
 import type { PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
+import { usePlayerStore } from "../store/playerStore";
 
 // One wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
 // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
@@ -35,6 +36,8 @@ type UseShadowPreviewReloadParams = Omit<
   onPromoted?: () => void;
   /** A shadow that never became ready was dropped; the live preview is unchanged. */
   onReloadFailed?: (message: string) => void;
+  /** Puts the promoted document at the live frame's time, playing if the live frame was. */
+  handOverPlayback: (time: number, playing: boolean) => void;
 };
 
 export function useShadowPreviewReload({
@@ -51,6 +54,7 @@ export function useShadowPreviewReload({
   applyPreviewAudioState,
   onPromoted,
   onReloadFailed,
+  handOverPlayback,
 }: UseShadowPreviewReloadParams) {
   const shadowIframeRef = useRef<HTMLIFrameElement | null>(null);
   const shadowProbeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
@@ -62,6 +66,8 @@ export function useShadowPreviewReload({
   onPromotedRef.current = onPromoted;
   const onReloadFailedRef = useRef(onReloadFailed);
   onReloadFailedRef.current = onReloadFailed;
+  const handOverPlaybackRef = useRef(handOverPlayback);
+  handOverPlaybackRef.current = handOverPlayback;
   const readyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
   const budgetsSpentRef = useRef(0);
   // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
@@ -102,6 +108,11 @@ export function useShadowPreviewReload({
       const ready = pending?.gen === gen && visuallyReadyGenRef.current === gen;
       if (!shadow || !pending || !ready || gen !== shadowGenRef.current) return;
       stopPendingShadow();
+      // The live frame kept playing, stopped at the end or was seeked while the shadow loaded.
+      const live = getAdapter();
+      const liveTime = live?.getTime();
+      const playing = usePlayerStore.getState().isPlaying;
+      live?.pause();
       // The store takes the new document's timeline only now that it is the one on screen.
       pending.commit();
       iframeRef.current = shadow;
@@ -109,10 +120,17 @@ export function useShadowPreviewReload({
       attachIframeShortcutListeners();
       applyPreviewAudioState();
       setPreviewSlots((prev) => planShadowPromotion(prev, gen));
+      if (liveTime != null) handOverPlaybackRef.current(liveTime, playing);
       onPromotedRef.current?.();
       thumbnailScheduler.setPreviewReloading(false);
     },
-    [stopPendingShadow, iframeRef, attachIframeShortcutListeners, applyPreviewAudioState],
+    [
+      stopPendingShadow,
+      getAdapter,
+      iframeRef,
+      attachIframeShortcutListeners,
+      applyPreviewAudioState,
+    ],
   );
 
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);

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

@@ -224,6 +224,91 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("keeps a playing film playing through a reload, from where the live frame had reached", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const { adapter: liveAdapter, win } = makeAdapterWindow();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(win);
+      getApi().onIframeLoad();
+    });
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => getApi().play());
+    liveAdapter.pause.mockClear();
+    liveAdapter.seek(4.2);
+
+    act(() => getApi().refreshPlayer());
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    expect(liveAdapter.pause).not.toHaveBeenCalled();
+
+    liveAdapter.seek(5.5);
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    expect(liveAdapter.pause).toHaveBeenCalled();
+    expect(shadow.adapter.getTime()).toBe(5.5);
+    expect(shadow.adapter.isPlaying()).toBe(true);
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    unmount(root);
+  });
+
+  it("keeps where a film was paused while the reload loaded", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const { adapter: liveAdapter, win } = makeAdapterWindow();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(win);
+      getApi().onIframeLoad();
+    });
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => getApi().play());
+    liveAdapter.seek(4.2);
+    act(() => getApi().refreshPlayer());
+
+    liveAdapter.seek(7);
+    act(() => getApi().pause());
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    expect(shadow.adapter.getTime()).toBe(7);
+    expect(shadow.adapter.isPlaying()).toBe(false);
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    unmount(root);
+  });
+
+  it("stops a playing film at the new end when the edit cut it short of the live time", () => {
+    const { getApi, root } = renderTimelinePlayerHarness();
+    const { adapter: liveAdapter, win } = makeAdapterWindow();
+    act(() => {
+      getApi().iframeRef.current = makeFakeIframe(win);
+      getApi().onIframeLoad();
+    });
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => getApi().play());
+    act(() => getApi().refreshPlayer());
+
+    liveAdapter.seek(12);
+    const gen = getApi().previewSlots.find((s) => s.role === "shadow")!.gen;
+    const shorter = makeAdapterWindow({ duration: 10 });
+    act(() => {
+      getApi().setShadowIframeNode(makeFakeIframe(shorter.win));
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(shorter.adapter.getTime()).toBe(10);
+    expect(shorter.adapter.isPlaying()).toBe(false);
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    unmount(root);
+  });
+
   it("does not promote a shadow whose loader is still up, and promotes once it clears", () => {
     const { getApi, live, gen, root } = beginReload();
     const shadow = makeShadowWithSpies();

package/src/player/hooks/useTimelinePlayer.ts

@@ -400,6 +400,13 @@ export function useTimelinePlayer({
     applyPreviewAudioState,
     onPromoted: onShadowPromoted,
     onReloadFailed: onPreviewReloadFailed,
+    handOverPlayback: (time, playing) => {
+      // keepPlaying: move the playhead without the paused-seek audio scrub.
+      seek(time, { keepPlaying: true });
+      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();
+    },
   });
 
   const saveSeekPosition = useCallback(() => {
@@ -422,17 +429,21 @@ export function useTimelinePlayer({
       }
     }
     isRefreshingRef.current = true;
-    stopRAFLoop();
+    // Forward playback runs on in the live frame; the promotion hands it to the new document.
+    const keepPlaying =
+      usePlayerStore.getState().isPlaying && shuttleDirectionRef.current !== "backward";
     stopReverseLoop();
+    if (keepPlaying) return true;
+    stopRAFLoop();
     setIsPlaying(false);
+    return false;
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
     logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));
-    saveSeekPosition();
     // The old iframe is no longer navigated away, so stop its playback (and audio) here.
-    getAdapter()?.pause();
+    if (!saveSeekPosition()) getAdapter()?.pause();
     // The live iframe is never hidden; the reload loads in a shadow and is promoted once painted.
     const src = iframe.src;
     const url = new URL(src, window.location.origin);