@hyperframes/studio 0.8.86 → 0.8.87

package/src/player/components/TimelineGroupLaneLabels.tsx

@@ -63,8 +63,13 @@ export function TimelineGroupLaneLabels({
             tabIndex={-1}
             key={lane.target}
             data-group-lane-label={lane.target}
-            aria-label={`Show ${groupLabel} ${parts.name}${parts.param ? ` ${parts.param}` : ""} in the effect rack`}
-            className="absolute left-0 flex items-center gap-1.5 overflow-hidden border-0 px-1.5 text-left text-[10px] text-[var(--timeline-text-secondary)] hover:text-[var(--timeline-text-solid)] focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[var(--timeline-accent)]"
+            aria-label={
+              onReveal
+                ? `Show ${groupLabel} ${parts.name}${parts.param ? ` ${parts.param}` : ""} in the effect rack`
+                : undefined
+            }
+            disabled={!onReveal}
+            className="absolute left-0 flex items-center gap-1.5 overflow-hidden border-0 px-1.5 text-left text-[10px] text-[var(--timeline-text-secondary)] enabled:hover:text-[var(--timeline-text-solid)] focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[var(--timeline-accent)]"
             style={{
               top: top + index * AUTOMATION_LANE_H,
               width: columnWidth,

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

@@ -45,9 +45,21 @@ const GROUP: TimelineTrackGroupInfo = {
   hidden: false,
 };
 
+const GAIN_AUTOMATED: Partial<TimelineTrackGroupInfo> = {
+  fxChain: JSON.stringify({
+    version: 1,
+    nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
+  }),
+  automation: JSON.stringify({
+    version: 1,
+    lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
+  }),
+};
+
 function renderRow(
   overrides: Partial<TimelineTrackGroupInfo> = {},
   expandedLaneOwnerIds = new Set<string>(),
+  showAudioEffects?: boolean,
 ) {
   const onSetAudioGroupAttributeQuiet = vi.fn();
   const onSetElementAttributeQuiet = vi.fn();
@@ -66,6 +78,7 @@ function renderRow(
           virtualized={false}
           contentOrigin={232}
           theme={defaultTimelineTheme}
+          showAudioEffects={showAudioEffects}
           collapsedGroupIds={new Set()}
           expandedLaneOwnerIds={expandedLaneOwnerIds}
           toggleGroupExpanded={vi.fn()}
@@ -118,19 +131,7 @@ describe("TimelineGroupRow", () => {
   });
 
   it("opens a group automation lane on its exact rack parameter", async () => {
-    const { host } = renderRow(
-      {
-        fxChain: JSON.stringify({
-          version: 1,
-          nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
-        }),
-        automation: JSON.stringify({
-          version: 1,
-          lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
-        }),
-      },
-      new Set(["voiceover"]),
-    );
+    const { host } = renderRow(GAIN_AUTOMATED, new Set(["voiceover"]));
     const laneTitle = host.querySelector<HTMLButtonElement>('[data-group-lane-label="fx.p1.gain"]');
 
     await act(async () => {
@@ -147,6 +148,14 @@ describe("TimelineGroupRow", () => {
     });
   });
 
+  it("keeps a group lane's name off the rack while audio effects are hidden", () => {
+    const { host } = renderRow(GAIN_AUTOMATED, new Set(["voiceover"]), false);
+    const laneTitle = host.querySelector<HTMLButtonElement>('[data-group-lane-label="fx.p1.gain"]');
+
+    expect(laneTitle?.disabled).toBe(true);
+    expect(laneTitle?.getAttribute("aria-label")).toBeNull();
+  });
+
   // C1 names this as the step's own definition of done: "opening the popover on
   // a GROUP and applying a preset results in exactly ONE `data-fx-chain` write,
   // on the group element, and zero writes on members". A group IS a bus — a
@@ -180,16 +189,7 @@ describe("TimelineGroupRow", () => {
 
     expect(laneToggle(renderRow().host)).toBeUndefined();
 
-    const automated = renderRow({
-      fxChain: JSON.stringify({
-        version: 1,
-        nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
-      }),
-      automation: JSON.stringify({
-        version: 1,
-        lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
-      }),
-    });
+    const automated = renderRow(GAIN_AUTOMATED);
     expect(laneToggle(automated.host)).toBeDefined();
   });
 
@@ -197,16 +197,7 @@ describe("TimelineGroupRow", () => {
   // one right-anchored group. It was two lines — name, then controls — which is
   // what let a stray child overflow the 48px box on the track side.
   it("keeps the caret, the name and every control on one line", () => {
-    const { host } = renderRow({
-      fxChain: JSON.stringify({
-        version: 1,
-        nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
-      }),
-      automation: JSON.stringify({
-        version: 1,
-        lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
-      }),
-    });
+    const { host } = renderRow(GAIN_AUTOMATED);
     const header = host.querySelector<HTMLElement>('[role="rowheader"]');
     // Caret, name, control group — no second line.
     expect(header?.children).toHaveLength(3);

package/src/player/components/TimelineGroupRow.tsx

@@ -33,6 +33,7 @@ interface TimelineGroupRowProps {
   virtualized: boolean;
   contentOrigin: number;
   theme: TimelineTheme;
+  showAudioEffects?: boolean;
   rovingTargetId?: string | null;
   collapsedGroupIds: ReadonlySet<string>;
   expandedLaneOwnerIds: ReadonlySet<string>;
@@ -59,6 +60,7 @@ export function TimelineGroupRow({
   virtualized,
   contentOrigin,
   theme,
+  showAudioEffects = true,
   rovingTargetId = null,
   collapsedGroupIds,
   expandedLaneOwnerIds,
@@ -173,6 +175,7 @@ export function TimelineGroupRow({
           // stays pinned there through horizontal scroll.
           columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
           theme={theme}
+          showAudioEffects={showAudioEffects}
         />
         {/* The group's OWN curves, under the strip. Selected-gated exactly like a
           clip's: a lane is editable once the group is selected, which clicking
@@ -187,7 +190,7 @@ export function TimelineGroupRow({
             columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
             gutterBackground={theme.gutterBackground}
             accentColor={GROUP_LANE_ACCENT}
-            onReveal={openGroupFxRack}
+            onReveal={showAudioEffects ? openGroupFxRack : undefined}
           />
         )}
       </div>

package/src/player/components/TimelineLanes.tsx

@@ -41,6 +41,7 @@ export function TimelineLanes({
   contentGutter,
   trackContentWidth,
   theme,
+  showAudioEffects,
   displayTrackOrder,
   rowGeometry,
   virtualRows,
@@ -115,11 +116,8 @@ export function TimelineLanes({
   // synthetic lane element spans the whole composition rather than a clip.
   const compositionDuration = usePlayerStore((s) => s.duration);
   useAutomationSelectionKeyboard({ lanes: automationLanes });
-  const { logicalRowsByTrack, groupByAnchor } = useTimelineLaneRowIndexes(logicalRows, groups);
-  const groupMemberTracks = useMemo(
-    () => new Set(groups.flatMap((group) => group.memberTracks)),
-    [groups],
-  );
+  const rowIndexes = useTimelineLaneRowIndexes(logicalRows, groups);
+  const { logicalRowsByTrack, groupByAnchor, groupMemberTracks } = rowIndexes;
   const {
     toggleRowExpanded: toggleRowExpandedTracked,
     toggleClipExpanded: toggleClipExpandedTracked,
@@ -168,6 +166,7 @@ export function TimelineLanes({
                 virtualized={rowsVirtualized}
                 contentOrigin={contentOrigin}
                 theme={theme}
+                showAudioEffects={showAudioEffects}
                 rovingTargetId={keyboard.rovingTargetId}
                 collapsedGroupIds={collapsedGroupIds}
                 expandedLaneOwnerIds={expandedLaneOwnerIds}
@@ -292,6 +291,7 @@ export function TimelineLanes({
                 isAudioTrack={isAudioTrack}
                 isGroupMember={groupMemberTracks.has(trackNum)}
                 theme={theme}
+                showAudioEffects={showAudioEffects}
                 onToggleClipExpanded={() => {
                   const keys = els.map(getTimelineElementIdentity);
                   if (keys.length > 0) toggleRowExpandedTracked(keys);

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

@@ -75,6 +75,7 @@ interface RenderHeaderOptions {
   isAudioTrack?: boolean;
   isGroupMember?: boolean;
   isTrackHidden?: boolean;
+  showAudioEffects?: boolean;
 }
 
 function renderHeader(options: RenderHeaderOptions = {}): {
@@ -119,6 +120,7 @@ function renderHeader(options: RenderHeaderOptions = {}): {
           isAudioTrack={next.isAudioTrack}
           isGroupMember={next.isGroupMember}
           theme={defaultTimelineTheme}
+          showAudioEffects={next.showAudioEffects}
           onToggleClipExpanded={vi.fn()}
           onToggleTrackHidden={next.onToggleTrackHidden}
           onTogglePropertyGroupKeyframe={next.onTogglePropertyGroupKeyframe}
@@ -583,6 +585,31 @@ describe("TimelineTrackHeader", () => {
       }),
     } as TimelineElement;
 
+    it("offers the effect rack from an effect lane only while audio effects are shown", () => {
+      const clip = { ...BED, domId: "bed" } as TimelineElement;
+      const gainLabel = (showAudioEffects?: boolean) => {
+        const { host, root } = renderHeader({
+          keyframeClip: clip,
+          animations: [],
+          showAudioEffects,
+        });
+        const button = host
+          .querySelector('[data-automation-lane-label="Peaking EQ 1.6 kHz · Gain"]')
+          ?.querySelector("button");
+        const state = {
+          label: button?.getAttribute("aria-label") ?? null,
+          disabled: button?.disabled,
+        };
+        act(() => root.unmount());
+        return state;
+      };
+      expect(gainLabel()).toEqual({
+        label: "Show Peaking EQ 1.6 kHz · Gain in the effect rack",
+        disabled: false,
+      });
+      expect(gainLabel(false)).toEqual({ label: null, disabled: true });
+    });
+
     it("names every envelope in the label column", () => {
       const { host, root } = renderHeader({ keyframeClip: BED, animations: [] });
       const rows = Array.from(host.querySelectorAll<HTMLElement>("[data-automation-lane-label]"));

package/src/player/components/TimelineTrackHeader.tsx

@@ -72,6 +72,7 @@ interface TimelineTrackHeaderProps {
   isGroupMember?: boolean;
   rovingTargetId?: string | null;
   theme: TimelineTheme;
+  showAudioEffects?: boolean;
   onToggleClipExpanded: () => void;
   onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
   onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
@@ -98,6 +99,7 @@ export function TimelineTrackHeader({
   isAudioTrack,
   isGroupMember = false,
   theme,
+  showAudioEffects = true,
   onToggleClipExpanded,
   onToggleTrackHidden,
   onTogglePropertyGroupKeyframe,
@@ -316,7 +318,7 @@ export function TimelineTrackHeader({
               // On the control line rather than a third row of its own.
               trailing={
                 <>
-                  {singleAudioClip && (
+                  {showAudioEffects && singleAudioClip && (
                     <TimelineFxButton
                       variant="chain"
                       fxChainRaw={singleAudioClip.fxChain}
@@ -340,7 +342,8 @@ export function TimelineTrackHeader({
                       onOpenRack={() => openClipFxRack(singleAudioClip)}
                     />
                   )}
-                  {clipCount > 1 &&
+                  {showAudioEffects &&
+                    clipCount > 1 &&
                     !isTrackGrouped &&
                     (isAudioTrack ? canGroupWholeTrack : isVideoWithAudioTrack) && (
                       <TimelineFxButton
@@ -455,7 +458,7 @@ export function TimelineTrackHeader({
               // element, so a shared row's other envelopes belong to clips it is
               // not showing and there would be nothing to reveal.
               onReveal={
-                revealTarget && revealElementId && keyframeClip
+                showAudioEffects && revealTarget && revealElementId && keyframeClip
                   ? () => {
                       // Select FIRST: the rack is the property panel's view of
                       // the selected element, so a reveal aimed at an unselected

package/src/player/components/TimelineTypes.ts

@@ -33,4 +33,5 @@ export interface TimelineProps
   onDuplicateClip?: () => Promise<boolean>;
   canPasteClip?: () => boolean;
   theme?: Partial<TimelineTheme>;
+  showAudioEffects?: boolean;
 }

package/src/player/components/timelineLaneProps.ts

@@ -29,6 +29,7 @@ export interface TimelineLaneBaseProps {
   contentGutter: number;
   trackContentWidth: number;
   theme: TimelineTheme;
+  showAudioEffects?: boolean;
   displayTrackOrder: number[];
   rowHeights: readonly number[];
   rowGeometry: TimelineRowGeometry;

package/src/player/components/timelineMountTestEnv.ts

@@ -0,0 +1,29 @@
+import { afterAll, beforeAll } from "vitest";
+
+// Mounting a whole <Timeline> in happy-dom needs a width to lay out against and a size report.
+class MockResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+  observe(target: Element) {
+    this.callback([{ target } as ResizeObserverEntry], this as unknown as ResizeObserver);
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+export function installTimelineMountEnv(): void {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  const originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "clientWidth");
+  beforeAll(() => {
+    globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+    Object.defineProperty(HTMLElement.prototype, "clientWidth", {
+      configurable: true,
+      get: () => 900,
+    });
+  });
+  afterAll(() => {
+    globalThis.ResizeObserver = originalResizeObserver;
+    if (originalClientWidth)
+      Object.defineProperty(HTMLElement.prototype, "clientWidth", originalClientWidth);
+    document.body.innerHTML = "";
+  });
+}

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/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);
+  });
+});