@hyperframes/studio 0.8.75 → 0.8.77

package/src/hostMount.test.tsx

@@ -8,8 +8,15 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 // Backend/storage mocking only, standing in for a host's own server and
 // persistence — not part of the host's integration code under test.
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createStudioApi,
+  openProjectHistory,
+  type StudioApiAdapter,
+} from "@hyperframes/studio-server";
 import { studioFileContentVersion } from "./utils/studioFileVersion";
-import { createMemoryEditHistoryStorage } from "./utils/editHistoryStorage";
 import {
   flushStudioPendingEdits,
   useTimelineEditing,
@@ -27,45 +34,66 @@ import {
 const ORIGINAL_HTML = '<div id="clip" data-start="0" data-track-index="0"></div>';
 
 let root: Root | null = null;
-afterEach(() => {
+const cleanups: Array<() => unknown> = [];
+afterEach(async () => {
   act(() => root?.unmount());
   document.body.innerHTML = "";
   vi.unstubAllGlobals();
+  for (const step of cleanups.splice(0).reverse()) await step();
 });
 
-/** A minimal disk with etag-guarded PUT, faithful enough to exercise a real
- *  conflict: a stale If-Match gets a 409 with the current version + content. */
-function stubHostProjectDisk(
+function tempDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+/** A project folder with etag-guarded PUT, faithful enough to exercise a real
+ *  conflict: a stale If-Match gets a 409 with the current version + content.
+ *  History requests go to the real history routes over the real engine. */
+async function stubHostProjectDisk(
   initial: Record<string, string>,
   options?: { editElsewhereAfterFirstRead?: boolean },
 ) {
-  const content = { ...initial };
+  const dir = tempDir("hf-host-mount-");
+  for (const [path, text] of Object.entries(initial)) writeFileSync(join(dir, path), text);
+  const history = await openProjectHistory({
+    projectDir: dir,
+    historyRoot: tempDir("hf-host-mount-history-"),
+  });
+  cleanups.push(() => history.close());
+  const api = createStudioApi({
+    listProjects: () => [],
+    resolveProject: (id: string) => (id === "p1" ? { id, dir } : null),
+    history: () => history,
+  } as unknown as StudioApiAdapter);
   const readsSeen = new Set<string>();
+  const read = (path: string) => readFileSync(join(dir, path), "utf8");
   // The real backend's etag is a content hash (useProjectFileWriter derives
   // If-Match the same way) — an arbitrary counter here would make every
   // write from a host that hasn't just read the file look stale.
-  const versionOf = (path: string) => studioFileContentVersion(content[path]);
+  const versionOf = (path: string) => studioFileContentVersion(read(path));
 
   async function handlePut(path: string, init: RequestInit | undefined) {
     const ifMatch = new Headers(init?.headers).get("If-Match");
     const currentVersion = await versionOf(path);
     if (ifMatch && ifMatch !== currentVersion) {
-      return new Response(JSON.stringify({ currentVersion, currentContent: content[path] }), {
+      return new Response(JSON.stringify({ currentVersion, currentContent: read(path) }), {
         status: 409,
       });
     }
-    content[path] = String(init?.body ?? "");
+    writeFileSync(join(dir, path), String(init?.body ?? ""));
     return new Response(JSON.stringify({ version: await versionOf(path) }), { status: 200 });
   }
 
   async function handleGet(path: string) {
-    const served = content[path];
+    const served = read(path);
     // Simulates another writer landing between this read and the caller's
     // own write: content moves on right after being served once, so the
     // caller's hash of what it just read no longer matches disk.
     if (options?.editElsewhereAfterFirstRead && !readsSeen.has(path)) {
       readsSeen.add(path);
-      content[path] = `${served} <!--edited elsewhere-->`;
+      writeFileSync(join(dir, path), `${served} <!--edited elsewhere-->`);
     }
     return new Response(
       JSON.stringify({ content: served, version: await studioFileContentVersion(served) }),
@@ -74,12 +102,15 @@ function stubHostProjectDisk(
   }
 
   const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
-    const match = String(input).match(/\/files\/([^?]+)/);
-    const path = match ? decodeURIComponent(match[1]) : "";
+    const url = String(input);
+    if (url.includes("/history")) return api.request(url.replace(/^\/api/, ""), init);
+    const match = url.match(/\/files\/([^?]+)/);
+    if (!match) return new Response("{}", { status: 404 });
+    const path = decodeURIComponent(match[1]);
     return (init?.method ?? "GET") === "PUT" ? handlePut(path, init) : handleGet(path);
   });
   vi.stubGlobal("fetch", fetchMock);
-  return { content, fetchMock };
+  return { read, fetchMock };
 }
 
 type TimelineEditingHandle = {
@@ -108,13 +139,10 @@ function mountHost(
   const bannerHost = document.createElement("div");
   document.body.append(bannerHost);
   const bannerRoot = createRoot(bannerHost);
-  // Created once: a fresh storage object on every render would change
-  // usePersistentEditHistory's effect deps each time and loop forever.
-  const storage = createMemoryEditHistoryStorage();
 
   function Harness() {
     const writer = useProjectFileWriter({ projectId: "p1" });
-    const editHistory = usePersistentEditHistory({ projectId: "p1", storage });
+    const editHistory = usePersistentEditHistory({ projectId: "p1" });
     const historyActions = useEditHistoryActions({
       editHistory,
       readOptionalProjectFile: writer.readOptionalProjectFile,
@@ -170,7 +198,7 @@ function mountHost(
 
 describe("public export surface: a host mounting hand editing outside EditorShell", () => {
   it("writes a move through the history path and undo restores it", async () => {
-    const disk = stubHostProjectDisk({ "index.html": ORIGINAL_HTML });
+    const disk = await stubHostProjectDisk({ "index.html": ORIGINAL_HTML });
     const iframe = document.createElement("iframe");
     document.body.append(iframe);
     iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;
@@ -187,16 +215,19 @@ describe("public export surface: a host mounting hand editing outside EditorShel
     await act(async () => {
       await timelineEditing.handleTimelineElementMove(clip, { start: 5, track: 0 });
     });
-    expect(disk.content["index.html"]).toContain('data-start="5"');
+    expect(disk.read("index.html")).toContain('data-start="5"');
 
     await act(async () => {
       await undo();
     });
-    expect(disk.content["index.html"]).toContain('data-start="0"');
+    expect(disk.read("index.html")).toContain('data-start="0"');
   });
 
   it("surfaces the conflict banner on a 409", async () => {
-    stubHostProjectDisk({ "index.html": ORIGINAL_HTML }, { editElsewhereAfterFirstRead: true });
+    await stubHostProjectDisk(
+      { "index.html": ORIGINAL_HTML },
+      { editElsewhereAfterFirstRead: true },
+    );
     const iframe = document.createElement("iframe");
     document.body.append(iframe);
     iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;

package/src/main.tsx

@@ -5,8 +5,11 @@ import { StudioApp } from "./App";
 import { StudioErrorBoundary } from "./components/StudioErrorBoundary";
 import { readIconTokens } from "./styles/iconTokens";
 import { trackStudioEvent } from "./utils/studioTelemetry";
+import { prefetchPreviewForHash } from "./utils/previewPrefetch";
 import "./styles/studio.css";
 
+prefetchPreviewForHash(window.location.hash);
+window.addEventListener("hashchange", () => prefetchPreviewForHash(window.location.hash));
 trackStudioEvent("session_start");
 
 function errorProps(value: unknown): {

package/src/player/components/CompositionThumbnail.tsx

@@ -24,6 +24,20 @@ interface CompositionThumbnailProps {
 
 const CLIP_HEIGHT = 66;
 const THUMBNAIL_URL_VERSION = "v3";
+export const THUMBNAIL_SEEK_TIME_SECONDS = 3;
+
+export function resolveThumbnailSeekTime(durationSeconds: number | null | undefined): number {
+  if (
+    Number.isFinite(durationSeconds) &&
+    durationSeconds != null &&
+    durationSeconds > 0 &&
+    durationSeconds <= THUMBNAIL_SEEK_TIME_SECONDS
+  ) {
+    return durationSeconds / 2;
+  }
+
+  return THUMBNAIL_SEEK_TIME_SECONDS;
+}
 
 export function buildCompositionThumbnailUrl({
   previewUrl,

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

@@ -9,6 +9,7 @@ import {
   readPreviewErrorMessage,
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
+import { usePlayerStore } from "../store/playerStore";
 
 vi.mock("@hyperframes/player", () => ({}));
 
@@ -271,6 +272,54 @@ describe("ready to show", () => {
     expect(onReadyToShowChange).toHaveBeenLastCalledWith(false);
   });
 
+  it("marks the preview booted when it can show and play, not at ready", async () => {
+    usePlayerStore.setState({ previewBooted: false });
+    const { player } = await mountPlayer({});
+    const el = player as TestHyperframesPlayer;
+
+    loadAndReady(el);
+    act(() => void el.dispatchEvent(new Event("assetsready")));
+    await twoFrames();
+    expect(usePlayerStore.getState().previewBooted).toBe(false);
+
+    painted(el);
+    await twoFrames();
+    expect(usePlayerStore.getState().previewBooted).toBe(true);
+  });
+
+  it("marks the preview booted at its first frame while media is still buffering", async () => {
+    usePlayerStore.setState({ previewBooted: false });
+    const onReadyToShowChange = vi.fn();
+    const { player } = await mountPlayer({ onReadyToShowChange });
+    const el = player as TestHyperframesPlayer;
+    document.body.appendChild(el.iframeElement);
+    const doc = el.iframeElement.contentDocument!;
+    const audio = doc.createElement("audio");
+    Object.defineProperty(audio, "readyState", { value: 0, configurable: true });
+    Object.defineProperty(audio, "networkState", { value: 2, configurable: true });
+    doc.body.appendChild(audio);
+
+    loadAndReady(el);
+    painted(el);
+    await twoFrames();
+    expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+    expect(usePlayerStore.getState().previewBooted).toBe(true);
+  });
+
+  it("stops deferring editing work when the preview never shows", async () => {
+    vi.useFakeTimers();
+    try {
+      usePlayerStore.setState({ previewBooted: false });
+      await mountPlayer({});
+      act(() => void vi.advanceTimersByTime(4999));
+      expect(usePlayerStore.getState().previewBooted).toBe(false);
+      act(() => void vi.advanceTimersByTime(1));
+      expect(usePlayerStore.getState().previewBooted).toBe(true);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("reports the document start time with the painted iframe", async () => {
     const onPainted = vi.fn();
     const now = vi.spyOn(performance, "now").mockReturnValue(100);

package/src/player/components/Player.tsx

@@ -4,6 +4,7 @@ import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readin
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { HyperframesLoader } from "../../components/ui";
+import { usePlayerStore } from "../store/playerStore";
 // Importing "@hyperframes/player" registers a class extending HTMLElement at
 // module load, which throws under SSR, hence the dynamic import behind a
 // `typeof window` guard. Kicking it here rather than in the mount effect puts
@@ -57,6 +58,7 @@ function getShaderTransitionLoading(event: Event): boolean | null {
 }
 
 const COMPOSITION_LOADING_OVERLAY_DELAY_MS = 400;
+const PREVIEW_BOOT_DEADLINE_MS = 5000;
 const DEFAULT_PREVIEW_ERROR = "The composition preview did not become ready.";
 
 export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
@@ -427,13 +429,13 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       setAssetsLoading(false);
     };
 
-    const readyToShow =
-      loaded &&
-      painted &&
-      !compositionLoading &&
-      !shaderTransitionLoading &&
-      !assetsLoading &&
-      !previewError;
+    const firstFrameShown =
+      loaded && painted && !compositionLoading && !shaderTransitionLoading && !previewError;
+    const readyToShow = firstFrameShown && !assetsLoading;
+    // Work waiting on the boot starts at the first frame, while media still buffers.
+    useEffect(() => {
+      if (firstFrameShown) usePlayerStore.getState().markPreviewBooted();
+    }, [firstFrameShown]);
     // `painted` means the player's own loader has finished fading; two frames of grace on top.
     useEffect(() => {
       if (!readyToShow) {
@@ -450,6 +452,18 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       };
     }, [readyToShow]);
 
+    useEffect(() => {
+      if (previewError) usePlayerStore.getState().markPreviewBooted();
+    }, [previewError]);
+
+    useEffect(() => {
+      const timer = setTimeout(
+        () => usePlayerStore.getState().markPreviewBooted(),
+        PREVIEW_BOOT_DEADLINE_MS,
+      );
+      return () => clearTimeout(timer);
+    }, [projectId]);
+
     const showCompositionOverlay =
       !suppressLoadingOverlay &&
       !compositionOverlayDeferred &&

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

@@ -8,11 +8,6 @@ import {
   type DragCommitDeps,
   type TimelineMoveEdit,
 } from "./timelineClipDragCommit";
-import {
-  buildEditHistoryEntry,
-  createEmptyEditHistory,
-  pushEditHistoryEntry,
-} from "../../utils/editHistory";
 import { normalizeToZones } from "./timelineZones";
 import { resolveZMirrorLaneMove } from "./timelineZMirror";
 import type { StackingPatch } from "./timelineStackingSync";
@@ -1151,48 +1146,21 @@ describe("commitDraggedClipMove", () => {
       return { onMoveElements, onStackingPatches };
     };
 
-    it("threads ONE shared coalesceKey to both the move persist and the z-sync, so the two records merge into a single undo entry", async () => {
+    it("threads ONE shared coalesceKey to both the move persist and the z-sync, so the server can fold them into a single undo entry", async () => {
       const { onMoveElements, onStackingPatches } = commitLaneChange(overlapping());
       await flushMicrotasks();
 
-      // Both sides receive the SAME non-empty gesture key (second arg).
+      // Both sides receive the SAME non-empty gesture key (second arg). That
+      // shared, non-empty coalesceKey is what lets the server
+      // (projectHistory.ts, "claim: a writer that records after writing")
+      // fold the "Move timeline clips" write and the "Reorder layers" z patch,
+      // both to the same file, into one undo entry — folding itself is the
+      // server's own tested behaviour, not re-proven here via a reducer.
       const moveKey = onMoveElements.mock.calls[0][1];
       const zKey = onStackingPatches.mock.calls[0][1];
       expect(typeof moveKey).toBe("string");
       expect(moveKey).not.toBe("");
       expect(zKey).toBe(moveKey);
-
-      // With that shared key, editHistory folds the two consecutive records (the
-      // "Move timeline clips" write + the "Reorder layers" z patch, same file,
-      // inside the coalesce window) into ONE undo entry spanning before→after.
-      const now = 1_000;
-      const moveEntry = buildEditHistoryEntry({
-        id: "m",
-        projectId: "p",
-        label: "Move timeline clips",
-        kind: "timeline",
-        coalesceKey: moveKey,
-        now,
-        files: { "index.html": { before: "<v0>", after: "<v1>" } },
-      });
-      const zEntry = buildEditHistoryEntry({
-        id: "z",
-        projectId: "p",
-        label: "Reorder layers",
-        kind: "timeline",
-        coalesceKey: zKey,
-        now: now + 50,
-        files: { "index.html": { before: "<v1>", after: "<v2>" } },
-      });
-      const state = pushEditHistoryEntry(
-        pushEditHistoryEntry(createEmptyEditHistory(), moveEntry),
-        zEntry,
-      );
-      expect(state.undo).toHaveLength(1);
-      expect(state.undo[0].files["index.html"]).toMatchObject({
-        before: "<v0>",
-        after: "<v2>",
-      });
     });
 
     it("distinct gestures get distinct keys (independent moves never cross-merge)", async () => {

package/src/player/hooks/timelineDomBinding.test.ts

@@ -47,6 +47,56 @@ describe("live DOM manifest hydration", () => {
       ).toHaveLength(2);
     }
   });
+  it("binds a root clip to its own element when a mounted sub-composition repeats its id", () => {
+    // The sub-composition's copy comes first in document order, so a bare id lookup finds it.
+    const doc = documentWith(
+      '<div id="strip" data-composition-id="strip" data-composition-src="compositions/strip.html" data-start="0" data-duration="4" data-track-index="1">' +
+        '<video id="frame-1" data-hf-id="hf-inner" data-start="0"></video></div>' +
+        '<video id="frame-1" data-hf-id="hf-root" data-start="6" data-duration="1" data-track-index="7"></video>',
+    );
+    const [element] = buildTimelineElementsFromClips(
+      [
+        clip({
+          id: "frame-1",
+          tagName: "video",
+          kind: "video",
+          start: 6,
+          duration: 1,
+          track: 7,
+          compositionAncestors: ["main"],
+        }),
+      ],
+      doc,
+    );
+    expect([element.hfId, element.sourceFile]).toEqual(["hf-root", undefined]);
+  });
+  it("keeps a unique id bound while its host's composition id is healed after the manifest", () => {
+    // The wrapper's data-composition-id arrived after the runtime recorded the clip's chain as ["main"].
+    const doc = documentWith(
+      '<div id="ho" data-hf-id="ho" data-start="0" data-duration="4"></div>' +
+        '<div id="hs-layer" data-composition-id="hs-comp">' +
+        '<div id="hs" data-hf-id="hs" data-start="0" data-duration="4"></div></div>',
+    );
+    const [element] = buildTimelineElementsFromClips(
+      [clip({ id: "hs", compositionAncestors: ["main"] })],
+      doc,
+    );
+    expect(element.hfId).toBe("hs");
+  });
+  it("binds an id-less host by its composition id over a lone id inside that sub-composition", () => {
+    const doc = documentWith(
+      '<div data-composition-id="card" data-composition-src="compositions/card.html" data-start="0" data-duration="4">' +
+        '<div data-hf-inner-root><div id="card" data-start="0" data-duration="4"></div></div></div>',
+    );
+    const host = doc.querySelector('[data-composition-src="compositions/card.html"]');
+    const card = clip({
+      id: "card",
+      kind: "composition",
+      compositionId: "card",
+      compositionAncestors: ["main"],
+    });
+    expect(findTimelineDomNodeForClip(doc, card, 0)).toBe(host);
+  });
   it("does not bind a cross-tag direct identity", () => {
     const doc = documentWith('<div id="collision" data-start="0" data-duration="4"></div>');
     expect(

package/src/player/hooks/timelineSyncHydration.test.ts

@@ -43,7 +43,7 @@ function mountScene(): Document {
 
 // A composition clip is keyed by its ELEMENT id, not its `data-composition-id`
 // (the runtime's clip tree publishes `scene-2-slot`), so the collector resolves
-// the host with getElementById(clip.id) exactly as the sibling walk does.
+// the host by clip.id in the clip's own composition, exactly as the sibling walk does.
 const sceneClips = [clip({ id: "scene-2-slot", kind: "composition", compositionId: "scene-2" })];
 
 describe("collectSubCompositionHostState", () => {
@@ -83,6 +83,30 @@ describe("collectSubCompositionHostState", () => {
     expect(state.get("scene-2-video")?.hidden).toBe(true);
   });
 
+  it("reads its own host when an earlier sub-composition repeats the host's id", () => {
+    document.body.innerHTML = `
+      <main data-composition-id="main">
+        <div id="intro-slot" data-composition-id="intro" data-composition-src="intro.html">
+          <div data-hf-inner-root data-composition-id="intro">
+            <div id="scene-2-slot"><p id="intro-note" data-hidden></p></div>
+          </div>
+        </div>
+        <div id="scene-2-slot" data-composition-id="scene-2" data-composition-src="scene-2.html">
+          <div data-hf-inner-root><div id="scene-2-title" data-hidden></div></div>
+        </div>
+      </main>`;
+    const host = clip({
+      id: "scene-2-slot",
+      kind: "composition",
+      compositionId: "scene-2",
+      compositionAncestors: ["main"],
+    });
+
+    expect([...collectSubCompositionHostState(document, [host]).keys()]).toEqual(["scene-2-title"]);
+    const rows = collectSubCompositionDomChildren(document, [host], new Map());
+    expect(rows.map((child) => child.id)).toEqual(["scene-2-title"]);
+  });
+
   it("returns empty without a document, rather than throwing", () => {
     expect(collectSubCompositionHostState(null, sceneClips).size).toBe(0);
   });

package/src/player/hooks/timelineSyncHydration.ts

@@ -9,7 +9,7 @@
  * an argument, so each is callable — and readable — on its own.
  */
 
-import { createTimelineDomNodeResolver } from "../lib/timelineElementHelpers";
+import { createTimelineDomNodeResolver, findClipElementById } from "../lib/timelineElementHelpers";
 import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild, SubCompositionHostState } from "../store/playerStore";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
@@ -128,7 +128,7 @@ export function collectSubCompositionDomChildren(
   if (!iframeDoc) return out;
   for (const clip of clips) {
     if (clip.kind !== "composition" || !clip.id) continue;
-    const hostEl = iframeDoc.getElementById(clip.id);
+    const hostEl = findClipElementById(iframeDoc, clip);
     if (!hostEl) continue;
     const innerRoot = hostEl.querySelector("[data-hf-inner-root]") ?? hostEl;
     collectHostDomChildren(clip.id, innerRoot, clip.id, parentMap, out);
@@ -172,7 +172,7 @@ export function collectSubCompositionHostState(
   if (!iframeDoc) return out;
   for (const clip of clips) {
     if (clip.kind !== "composition" || !clip.id) continue;
-    const hostEl = iframeDoc.getElementById(clip.id);
+    const hostEl = findClipElementById(iframeDoc, clip);
     if (!hostEl) continue;
     for (const el of Array.from(hostEl.querySelectorAll("[id]"))) {
       const state = readSubCompositionHostState(el);

package/src/player/hooks/useShadowPreviewReload.ts

@@ -219,6 +219,7 @@ export function useShadowPreviewReload({
     shadowIframeRef.current = null;
     isRefreshingRef.current = false;
     pendingSeekRef.current = null;
+    usePlayerStore.getState().setTimelineReady(false);
     setPreviewSlots(planShadowDiscard);
     thumbnailScheduler.setPreviewReloading(false);
   }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]);

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

@@ -0,0 +1,120 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  makeAdapterWindow,
+  makeFakeIframe,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+import { usePlayerStore } from "../store/playerStore";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+it("does not start playback before the timeline is ready, so iframe load cannot swallow it", () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  const { adapter, win } = makeAdapterWindow();
+  // The runtime has booted (adapter exists) but the iframe's load event has not fired yet.
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+  });
+
+  act(() => api.play());
+  expect(adapter.play).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+
+  act(() => {
+    api.onIframeLoad();
+    usePlayerStore.setState({ timelineReady: true });
+  });
+  act(() => api.play());
+  expect(adapter.play).toHaveBeenCalledTimes(1);
+  expect(usePlayerStore.getState().isPlaying).toBe(true);
+  act(() => root.unmount());
+});
+
+it("does not start playback while a switched-to composition's preview is still loading", () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(makeAdapterWindow().win);
+    api.onIframeLoad();
+    usePlayerStore.setState({ timelineReady: true });
+  });
+
+  // Drill into another composition: a fresh preview whose runtime is up but whose load step hasn't run.
+  const next = makeAdapterWindow();
+  act(() => {
+    api.resetPreviewSlots();
+    api.iframeRef.current = makeFakeIframe(next.win);
+  });
+  act(() => api.play());
+  expect(next.adapter.play).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+  act(() => root.unmount());
+});
+
+function postFromRuntime(win: object, data: Record<string, unknown>) {
+  act(() => {
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        source: win as unknown as Window,
+        data: { source: "hf-preview", ...data },
+      }),
+    );
+  });
+}
+
+async function expectPlayStillOff() {
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  expect(usePlayerStore.getState().timelineReady).toBe(false);
+}
+
+// Duration 0: the adapter cannot enable Play itself, so only the message path can, after the load step.
+it.each([30, 0])(
+  "waits for the preview's load step before a timeline message enables Play (adapter duration %i)",
+  async (duration) => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { win } = makeAdapterWindow({ duration });
+    act(() => {
+      api.iframeRef.current = makeFakeIframe(win);
+    });
+    // The runtime reports its timeline before the document's load event, as a film with large images does.
+    const clip = { id: "clip", label: "Clip", start: 0, duration: 1, track: 0, kind: "element" };
+    postFromRuntime(win, { type: "timeline", clips: [clip], durationInFrames: 30, fps: 30 });
+    await expectPlayStillOff();
+
+    act(() => api.onIframeLoad());
+    await vi.waitFor(() => expect(usePlayerStore.getState().timelineReady).toBe(true));
+    act(() => root.unmount());
+  },
+);
+
+it("does not let the blank page's load step enable Play for the preview that replaces it", async () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  // The iframe's first load is about:blank, before the runtime exists; its load step waits for runtime messages.
+  const iframe = makeFakeIframe({ ...makeAdapterWindow().win, __player: undefined });
+  act(() => {
+    api.iframeRef.current = iframe;
+    api.onIframeLoad();
+  });
+
+  // The same iframe navigates to the preview, whose runtime reports ready before its own load event.
+  const { win } = makeAdapterWindow();
+  Object.defineProperty(iframe, "contentWindow", { value: win, configurable: true });
+  Object.defineProperty(iframe, "contentDocument", {
+    value: document.implementation.createHTMLDocument("preview"),
+    configurable: true,
+  });
+  postFromRuntime(win, { type: "state" });
+  await expectPlayStillOff();
+
+  act(() => api.onIframeLoad());
+  await vi.waitFor(() => expect(usePlayerStore.getState().timelineReady).toBe(true));
+  act(() => root.unmount());
+});

package/src/player/hooks/useTimelinePlayer.ts

@@ -180,6 +180,7 @@ export function useTimelinePlayer({
     applyPreviewAudioFlags(iframeRef.current, audioMuted, audioVolume);
   }, []);
   const play = useCallback(() => {
+    if (!usePlayerStore.getState().timelineReady) return;
     stopRAFLoop();
     stopReverseLoop();
     stopScrubPreviewAudio();

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -295,6 +295,8 @@ export function useTimelineSyncCallbacks({
 
   const onIframeLoad = useCallback(
     (context?: number) => {
+      const loadedDoc = safeContentDocument(iframeRef.current);
+      if (loadedDoc) usePlayerStore.getState().markPreviewLoadStep(loadedDoc);
       applyPreviewAudioState();
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
       stopWaitingRef.current?.();