@hyperframes/studio 0.8.85 → 0.8.87

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

@@ -115,3 +115,108 @@ describe("useTimelineGeometry restore-scroll effect", () => {
     expect(scroll.scrollLeft).toBe(300);
   });
 });
+
+function ScaleProbe({
+  duration,
+  width = 1200,
+  clips = duration > 0,
+  seen,
+}: {
+  duration: number;
+  width?: number;
+  clips?: boolean;
+  seen: { pps: number; fitPps: number };
+}) {
+  const ppsRef = useRef(0);
+  const fitPpsRef = useRef(0);
+  const zoomMode = usePlayerStore((s) => s.zoomMode);
+  const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
+  const { pps, fitPps } = useTimelineGeometry({
+    viewportWidth: width,
+    effectiveDuration: duration,
+    zoomMode,
+    manualZoomPercent,
+    ppsRef,
+    fitPpsRef,
+    draggedClip: null,
+    resizingClip: null,
+    expandedElements: clips ? [{ ...element, start: 0, duration }] : [],
+    isDragging: useRef(false),
+    scrollRef: useRef<HTMLDivElement>(null),
+    lastScrollLeftRef: useRef(0),
+    contentOrigin: 32,
+  });
+  seen.pps = pps;
+  seen.fitPps = fitPps;
+  return null;
+}
+
+describe("useTimelineGeometry keeps the scale when only the length changes", () => {
+  const seen = { pps: 0, fitPps: 0 };
+  const renderAt = (duration: number, width?: number, clips?: boolean) =>
+    act(() =>
+      root.render(<ScaleProbe duration={duration} width={width} clips={clips} seen={seen} />),
+    );
+  const within = (pps: number) => Math.abs(seen.pps - pps) < seen.fitPps * 0.005;
+
+  it("keeps a short film's clips the same size when the first edit lengthens it", () => {
+    usePlayerStore.setState({ zoomMode: "fit", manualZoomPercent: 100 });
+    renderAt(17);
+    const before = seen.pps;
+    act(() => usePlayerStore.getState().pinTimelineZoom(seen.pps, seen.fitPps));
+    renderAt(25);
+    expect(seen.fitPps).toBeLessThan(before);
+    expect(within(before)).toBe(true);
+  });
+
+  it("keeps the scale in manual zoom when a later edit shortens the film", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(17);
+    const before = seen.pps;
+    renderAt(12);
+    expect(seen.fitPps).toBeGreaterThan(before / 1.5);
+    expect(within(before)).toBe(true);
+  });
+
+  it("still scales with the fit width when the timeline is resized, and when the length first loads", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(0);
+    renderAt(17);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+    renderAt(17, 900);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+  });
+
+  it("refits when another composition opens, which empties the clips first", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(120);
+    renderAt(120, undefined, false);
+    renderAt(5);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+  });
+
+  it("refits after a project reset, which empties the clips and the length", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 150 });
+    renderAt(120);
+    renderAt(0);
+    renderAt(17);
+    expect(seen.pps).toBeCloseTo(seen.fitPps * 1.5);
+  });
+
+  it("keeps a lengthened film's scale near the maximum zoom", () => {
+    usePlayerStore.setState({ zoomMode: "manual", manualZoomPercent: 100_000 });
+    renderAt(17);
+    const before = seen.pps;
+    expect(before).toBeLessThan(seen.fitPps * 1000);
+    renderAt(25);
+    expect(within(before)).toBe(true);
+  });
+
+  it("leaves the manual zoom alone in fit mode", () => {
+    usePlayerStore.setState({ zoomMode: "fit", manualZoomPercent: 100 });
+    renderAt(17);
+    renderAt(25);
+    expect(seen.pps).toBe(seen.fitPps);
+    expect(usePlayerStore.getState().manualZoomPercent).toBe(100);
+  });
+});

package/src/player/components/useTimelineGeometry.ts

@@ -1,6 +1,6 @@
-import { useEffect, useRef, type RefObject } from "react";
+import { useEffect, useLayoutEffect, useRef, type RefObject } from "react";
 import { usePlayerStore, type TimelineElement, type ZoomMode } from "../store/playerStore";
-import { getTimelinePixelsPerSecond } from "./timelineZoom";
+import { computePinnedZoomPercent, getTimelinePixelsPerSecond } from "./timelineZoom";
 import {
   DRAG_EXTEND_MARGIN_PX,
   getTimelineDisplayContentWidth,
@@ -43,12 +43,9 @@ export function useTimelineGeometry({
   lastScrollLeftRef,
   contentOrigin,
 }: UseTimelineGeometryInput) {
-  // Fit pps maps at least MIN_TIMELINE_EXTENT_S onto the viewport, so short
-  // comps show a 60s ruler with usable empty space (see getTimelineFitPps).
   const fitPps = getTimelineFitPps(viewportWidth, effectiveDuration, contentOrigin);
   const pps = getTimelinePixelsPerSecond(fitPps, zoomMode, manualZoomPercent);
   ppsRef.current = pps;
-  const trackContentWidth = Math.max(0, effectiveDuration * pps);
   // Drag-to-extend: while a clip is dragged, keep the rendered extent a margin
   // past the ghost's end. Holding the pointer in the right edge zone then keeps
   // auto-scroll stepping (scrollWidth grows with the ghost), so the timeline
@@ -65,12 +62,12 @@ export function useTimelineGeometry({
   const resizeGhostEndPx = resizingClip?.started
     ? (resizingClip.previewStart + resizingClip.previewDuration) * pps + DRAG_EXTEND_MARGIN_PX
     : 0;
-  // The timeline canvas always fills at least the viewport width AND the
-  // MIN_TIMELINE_EXTENT_S floor: the ruler + empty track lanes keep going into
+  // The timeline canvas always fills at least the viewport width AND the fit
+  // span at this zoom: the ruler + empty track lanes keep going into
   // the space instead of leaving dead black — CapCut-style. Only the RENDERED
   // extent grows; clip positions/durations are untouched.
   const displayContentWidth = getTimelineDisplayContentWidth({
-    trackContentWidth,
+    effectiveDuration,
     viewportWidth,
     contentOrigin,
     pps,
@@ -108,8 +105,7 @@ export function useTimelineGeometry({
     return () => cancelAnimationFrame(raf);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [expandedElements, zoomMode]);
-  // Publish the live scale so edit handlers OUTSIDE <Timeline> (the keyboard-delete
-  // path) can pin the zoom via pinTimelineZoomToCurrent without threading geometry.
+  // Publish the live scale for readers outside <Timeline> (the toolbar's zoom controls).
   // In a useEffect (not the render body) so React-18 concurrent replay — Suspense
   // retry, transitions, StrictMode double-invoke — can't double-publish. The write is
   // idempotent (same pps/fitPps → same fields), so this is behavior-preserving; the
@@ -117,6 +113,18 @@ export function useTimelineGeometry({
   useEffect(() => {
     usePlayerStore.getState().setTimelineScale(pps, fitPps);
   }, [pps, fitPps]);
+  // In manual zoom a length change keeps the on-screen scale instead of rescaling every
+  // clip, whichever edit caused it. A composition switch empties the clips first, so it refits.
+  const hasClips = expandedElements.length > 0;
+  const lastScale = useRef({ effectiveDuration, pps, hasClips });
+  useLayoutEffect(() => {
+    const last = lastScale.current;
+    lastScale.current = { effectiveDuration, pps, hasClips };
+    if (zoomMode !== "manual" || !last.hasClips || !hasClips) return;
+    if (last.effectiveDuration === effectiveDuration) return;
+    // Before paint; the percent is clamped against the new fit, not the store's last published one.
+    usePlayerStore.setState({ manualZoomPercent: computePinnedZoomPercent(last.pps, fitPps) });
+  });
 
   return {
     pps,

package/src/player/components/useTimelineLabelColumn.ts

@@ -0,0 +1,18 @@
+import { useMemo } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { TimelineElement } from "../store/playerStore";
+import { GUTTER, LABEL_COL_W, TRACKS_LEFT_PAD } from "./timelineLayout";
+import { timelineNeedsLabelColumn } from "./timelineViewModel";
+
+export function useTimelineLabelColumn(
+  animationsByElement: ReadonlyMap<string, readonly GsapAnimation[]>,
+  elements: readonly TimelineElement[],
+) {
+  const labelMode = useMemo(
+    () => timelineNeedsLabelColumn(animationsByElement, elements),
+    [animationsByElement, elements],
+  );
+  // The label column provides pre-t=0 space; otherwise keep TRACKS_LEFT_PAD after the gutter.
+  const contentOrigin = labelMode ? LABEL_COL_W + GUTTER : GUTTER + TRACKS_LEFT_PAD;
+  return { labelMode, contentOrigin };
+}

package/src/player/components/useTimelineLaneRowIndexes.ts

@@ -34,5 +34,10 @@ export function useTimelineLaneRowIndexes(
     [groups],
   );
 
-  return { logicalRowsByTrack, groupByAnchor };
+  const groupMemberTracks = useMemo(
+    () => new Set(groups.flatMap((group) => group.memberTracks)),
+    [groups],
+  );
+
+  return { logicalRowsByTrack, groupByAnchor, groupMemberTracks };
 }

package/src/player/components/useTimelinePlayhead.ts

@@ -104,7 +104,7 @@ export function useTimelinePlayhead({
 
   useEffect(() => {
     syncPlayheadPosition(currentTime);
-  }, [currentTime, pps, syncPlayheadPosition]);
+  }, [currentTime, pps, syncPlayheadPosition, timelineReady, elementsLength]);
 
   useLayoutEffect(() => {
     const scroll = scrollRef.current;

package/src/player/components/useTimelineProviderState.tsx

@@ -19,7 +19,8 @@ import { useTimelineEditPinning } from "./useTimelineEditPinning";
 import { useTimelineStackingSync } from "./useTimelineStackingSync";
 import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
-import { GUTTER, LABEL_COL_W, TRACKS_LEFT_PAD } from "./timelineLayout";
+import { GUTTER, LABEL_COL_W } from "./timelineLayout";
+import { useTimelineLabelColumn } from "./useTimelineLabelColumn";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
 import { ClipContentOnceShown } from "./timelineClipChildren";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
@@ -33,11 +34,7 @@ import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
 import { TimelineRazorGuideOverlay, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
 import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemetry";
-import {
-  getEffectiveTimelineDuration,
-  getTimelinePreviewElement,
-  timelineNeedsLabelColumn,
-} from "./timelineViewModel";
+import { getEffectiveTimelineDuration, getTimelinePreviewElement } from "./timelineViewModel";
 import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
 import { useTimelineTicks } from "./useTimelineTicks";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
@@ -70,6 +67,7 @@ export function useTimelineProviderState({
   onDuplicateClip,
   canPasteClip,
   theme: themeOverrides,
+  showAudioEffects = true,
   sessionEpoch = 0,
   previewIframeRef,
   onZIndexReorder,
@@ -107,12 +105,7 @@ export function useTimelineProviderState({
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
   const focusedEaseSegment = usePlayerStore((s) => s.focusedEaseSegment);
   const gsapAnimations = usePlayerStore((s) => s.gsapAnimations);
-  const labelMode = useMemo(
-    () => timelineNeedsLabelColumn(gsapAnimations, timelineElements),
-    [gsapAnimations, timelineElements],
-  );
-  // The label column provides pre-t=0 space; otherwise keep TRACKS_LEFT_PAD after the gutter.
-  const contentOrigin = labelMode ? LABEL_COL_W + GUTTER : GUTTER + TRACKS_LEFT_PAD;
+  const { labelMode, contentOrigin } = useTimelineLabelColumn(gsapAnimations, timelineElements);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
@@ -448,6 +441,7 @@ export function useTimelineProviderState({
     laneGapStrips,
     dropPreview: assetDrop.dropPreview,
     theme,
+    showAudioEffects,
     displayTrackOrder: displayLayout.displayTrackOrder,
     rowHeights: displayLayout.displayRowHeights,
     rowGeometry: displayLayout.rowGeometry,

package/src/player/components/useTimelineRangeSelection.ts

@@ -546,29 +546,30 @@ export function useTimelineRangeSelection({
     [cancelActiveGesture, isGestureSessionCurrent],
   );
 
-  // Escape: cancel an in-flight marquee (restores the pre-drag selection);
-  // otherwise clear any lingering multi-selection.
+  // Escape cancels an in-flight band, captured so a host's own Escape never also fires;
+  // otherwise it clears any lingering multi-selection.
   useEffect(() => {
+    const onBandEscape = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || !(marqueeRef.current || isRangeSelecting.current)) return;
+      e.preventDefault();
+      e.stopPropagation();
+      cancelActiveGesture(true, true);
+    };
     const onKeyDown = (e: KeyboardEvent) => {
       if (e.key !== "Escape") return;
       const store = usePlayerStore.getState();
-      const marquee = marqueeRef.current;
-      if (marquee) {
-        cancelActiveGesture(true, true);
-        return;
-      }
-      if (isRangeSelecting.current || isDragging.current) {
+      if (isDragging.current) {
         cancelActiveGesture(true, true);
         return;
       }
-      // Escape with no marquee clears the whole selection — primary AND set.
-      // setSelectedElementId(null) also collapses the multi-select set.
       if (store.selectedElementId || store.selectedElementIds.size > 0) {
         store.setSelectedElementId(null);
       }
     };
-    window.addEventListener("keydown", onKeyDown);
-    return () => window.removeEventListener("keydown", onKeyDown);
+    const listeners = new AbortController();
+    window.addEventListener("keydown", onBandEscape, { capture: true, signal: listeners.signal });
+    window.addEventListener("keydown", onKeyDown, { signal: listeners.signal });
+    return () => listeners.abort();
   }, [cancelActiveGesture, isDragging]);
 
   const previousSessionEpochRef = useRef(sessionEpoch);

package/src/player/hooks/useShadowPreviewReload.ts

@@ -140,6 +140,7 @@ export function useShadowPreviewReload({
 
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
   const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
+  const previewGeneration = useCallback(() => shadowGenRef.current, []);
   const markAdapterReady = useCallback(
     (iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
       if (gen == null || gen !== shadowGenRef.current) return;
@@ -261,5 +262,6 @@ export function useShadowPreviewReload({
     setShadowIframeNode,
     beginShadowReload,
     resetPreviewSlots,
+    previewGeneration,
   };
 }

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

@@ -649,3 +649,194 @@ function stubVisibility(initial: DocumentVisibilityState) {
     document.dispatchEvent(new Event("visibilitychange"));
   };
 }
+
+describe("useTimelinePlayer scene swap", () => {
+  function liveFilm(swap?: (html: string) => Promise<void>) {
+    const { adapter, win } = makeAdapterWindow();
+    const iframe = makeFakeIframe(swap ? { ...win, __hfSwapScenes: swap } : win);
+    iframe.src = "http://localhost/api/projects/demo/preview";
+    const harness = renderTimelinePlayerHarness();
+    act(() => {
+      harness.getApi().iframeRef.current = iframe;
+      harness.getApi().onIframeLoad();
+    });
+    return { ...harness, adapter };
+  }
+  function playingFilm(swap: (html: string) => Promise<void>) {
+    const film = liveFilm(swap);
+    usePlayerStore.setState({ timelineReady: true });
+    act(() => film.getApi().play());
+    film.adapter.pause.mockClear();
+    return film;
+  }
+  const roles = (api: ReturnType<ReturnType<typeof liveFilm>["getApi"]>) =>
+    api.previewSlots.map((slot) => slot.role);
+  const settle = () => act(async () => void (await new Promise((r) => setTimeout(r, 0))));
+
+  it("swaps the rebuilt preview's scenes into the live preview with no shadow reload", async () => {
+    const swap = vi.fn(async () => {});
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
+    const { getApi } = liveFilm(swap);
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(swap).toHaveBeenCalledWith("<html>v2</html>", expect.anything());
+    expect(roles(getApi())).toEqual(["live"]);
+  });
+
+  it("falls back to the full reload when the preview refuses the swap", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
+    const { getApi } = liveFilm(async () => {
+      throw new Error("the film changed outside its scenes");
+    });
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(roles(getApi())).toEqual(["live", "shadow"]);
+  });
+
+  it("reloads the whole film at once when the preview cannot swap", () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    const { getApi } = liveFilm();
+    act(() => getApi().refreshPlayer());
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(roles(getApi())).toEqual(["live", "shadow"]);
+  });
+
+  it("never swaps in an older document that arrives after a newer reload started", async () => {
+    const swap = vi.fn(async () => {});
+    const replies: Array<(r: Response) => void> = [];
+    vi.spyOn(globalThis, "fetch").mockImplementation(
+      () => new Promise<Response>((resolve) => replies.push(resolve)),
+    );
+    const { getApi } = liveFilm(swap);
+    act(() => getApi().refreshPlayer());
+    act(() => getApi().refreshPlayer());
+    replies[1]!(new Response("<html>v3</html>"));
+    await settle();
+    replies[0]!(new Response("<html>v2</html>"));
+    await settle();
+    expect(swap.mock.calls).toEqual([["<html>v3</html>", expect.anything()]]);
+    expect(roles(getApi())).toEqual(["live"]);
+  });
+
+  it("cancels an older swap still waiting when a newer edit starts, so it cannot land after that edit's reload", async () => {
+    vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("<html>v</html>"));
+    let captionsArrive = () => {};
+    const captions = new Promise<void>((resolve) => (captionsArrive = resolve));
+    const landed: string[] = [];
+    let calls = 0;
+    // As the runtime does: the first waits for caption overrides, then refuses if cancelled; the second is refused.
+    const swap = async (_html: string, signal?: AbortSignal) => {
+      if (++calls > 1) throw new Error("the film changed outside its scenes");
+      await captions;
+      if (signal?.aborted) throw new Error("the swap was cancelled");
+      landed.push("edit 1");
+    };
+    const { getApi } = liveFilm(swap);
+    act(() => getApi().refreshPlayer());
+    await settle();
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(roles(getApi())).toContain("shadow");
+    captionsArrive();
+    await settle();
+    expect(landed).toEqual([]);
+  });
+
+  it("drops a pending swap's fallback once the preview was replaced, e.g. by a composition switch", async () => {
+    let refuse!: (e: Error) => void;
+    const swap = vi.fn(() => new Promise<void>((_, reject) => (refuse = reject)));
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
+    const { getApi } = liveFilm(swap);
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(swap).toHaveBeenCalledTimes(1);
+    act(() => getApi().resetPreviewSlots());
+    const next = makeFakeIframe(makeAdapterWindow().win);
+    next.src = "http://localhost/api/projects/demo/preview/comp/compositions/intro.html";
+    act(() => {
+      getApi().iframeRef.current = next;
+      getApi().onIframeLoad();
+    });
+    refuse(new Error("the preview was torn down during the swap"));
+    await settle();
+    expect(roles(getApi())).toEqual(["live"]);
+  });
+
+  it("skips the swap for an edit made while a full reload is in flight", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response("<html>v2</html>"));
+    const { getApi } = liveFilm(async () => {
+      throw new Error("the film changed outside its scenes");
+    });
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(roles(getApi())).toEqual(["live", "shadow"]);
+    const firstShadow = getApi().previewSlots[1]!.gen;
+    fetchSpy.mockClear();
+    act(() => getApi().refreshPlayer());
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(getApi().previewSlots[1]!.gen).toBeGreaterThan(firstShadow);
+  });
+
+  it("keeps a playing film playing through a swap, ready to swap the next edit", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockImplementation(async () => new Response("<html>v2</html>"));
+    const swap = vi.fn(async () => {});
+    const { getApi, adapter } = playingFilm(swap);
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(adapter.pause).not.toHaveBeenCalled();
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    expect(roles(getApi())).toEqual(["live"]);
+    act(() => getApi().refreshPlayer());
+    await settle();
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(swap).toHaveBeenCalledTimes(2);
+  });
+
+  it("shows a playing film stopped at its new end when a swap cuts it short of the playhead", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
+    let length = 6;
+    // As the runtime's swap does when the edit ends the film at or before the playhead.
+    const cutShort = async () => {
+      length = 5;
+      adapter.pause();
+      adapter.seek(5);
+    };
+    const { getApi, adapter } = playingFilm(cutShort);
+    adapter.getDuration = () => length;
+    adapter.seek(5.5);
+    act(() => getApi().refreshPlayer());
+    await settle();
+    await act(async () => void (await new Promise((r) => setTimeout(r, 50))));
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(usePlayerStore.getState().currentTime).toBe(5);
+    expect(adapter.play).toHaveBeenCalledTimes(1);
+    expect(roles(getApi())).toEqual(["live"]);
+  });
+
+  it("keeps a playing film playing through a refused swap, from where the live frame had reached", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
+    const { getApi, adapter } = playingFilm(async () => {
+      throw new Error("the film changed outside its scenes");
+    });
+    adapter.seek(3);
+    act(() => getApi().refreshPlayer());
+    // The live frame plays on while the swap is tried; the fallback reload starts from here.
+    adapter.seek(4.5);
+    await settle();
+    expect(adapter.pause).not.toHaveBeenCalled();
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    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(shadow.adapter.getTime()).toBe(4.5);
+    expect(shadow.adapter.isPlaying()).toBe(true);
+  });
+});

package/src/player/hooks/useTimelinePlayer.ts

@@ -38,6 +38,7 @@ import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 import { safeContentDocument } from "./timelineSyncHydration";
+import { sceneSwapFor } from "../sceneSwap";
 
 export interface UseTimelinePlayerOptions {
   /** Runs right after a reloaded preview becomes the live iframe. */
@@ -391,6 +392,7 @@ export function useTimelinePlayer({
     setShadowIframeNode,
     beginShadowReload,
     resetPreviewSlots,
+    previewGeneration,
   } = useShadowPreviewReload({
     iframeRef,
     getAdapter,
@@ -443,19 +445,39 @@ export function useTimelinePlayer({
     setIsPlaying(false);
     return false;
   }, [getAdapter, stopRAFLoop, setIsPlaying, stopReverseLoop]);
+  const reloadWholeFilm = useCallback(
+    (url: string) => {
+      // The old iframe is no longer navigated away, so stop its playback (and audio) here.
+      if (!saveSeekPosition()) getAdapter()?.pause();
+      // The live iframe is never hidden; the reload loads in a shadow and is promoted once painted.
+      beginShadowReload(url);
+    },
+    [saveSeekPosition, getAdapter, beginShadowReload],
+  );
+  const refreshGenRef = useRef(0);
+  const swapCancelRef = useRef<AbortController | null>(null);
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
+    swapCancelRef.current?.abort(new Error("superseded by a newer edit"));
+    const cancel = new AbortController();
+    swapCancelRef.current = cancel;
     logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));
-    // The old iframe is no longer navigated away, so stop its playback (and audio) here.
-    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);
+    const url = new URL(iframe.src, window.location.origin);
     url.searchParams.set("_t", String(Date.now()));
     applyPreviewVariablesToUrl(url);
-    beginShadowReload(url.toString());
-  }, [saveSeekPosition, getAdapter, beginShadowReload]);
+    const gen = ++refreshGenRef.current;
+    const slot = previewGeneration();
+    // A newer edit, or anything replacing the live preview (a reload, a composition switch), wins.
+    const isCurrent = () => gen === refreshGenRef.current && slot === previewGeneration();
+    const swap = sceneSwapFor(iframe);
+    if (!swap || isRefreshingRef.current) return reloadWholeFilm(url.toString());
+    swap(url.toString(), isCurrent, cancel.signal).catch((error: unknown) => {
+      if (!isCurrent()) return;
+      logReload("scene-swap-refused", { reason: String(error) });
+      reloadWholeFilm(url.toString());
+    });
+  }, [reloadWholeFilm, previewGeneration]);
   const pauseRef = useRef(pause);
   pauseRef.current = pause;
 

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

@@ -20,6 +20,7 @@ describe("Studio runtime protocol", () => {
         "seek-keep-playing",
         "composition-manifest-v1",
         "runtime-data",
+        "play-range",
       ],
       fps: { numerator: 60, denominator: 1 },
       timeSeconds: 1.25,