@hyperframes/studio 0.8.143 → 0.8.145

package/src/hooks/gsapResizeIntercept.test.ts

@@ -455,10 +455,31 @@ it("does not mix the scale shorthand into a tween that speaks longhands", async
  * The fixture models the geometry the browser reported: a 630x252 element
  * dragged from x=432 to x=587 with its box drafted down to 320x128, dropped at
  * a committed scale of 0.837. Scaling about the centre puts it back on the drop
- * point at its pre-gesture position, so the correct persisted correction is
- * NONE.
+ * point at its pre-gesture position, so the persisted correction is only the
+ * drop's sub-pixel offset.
  */
-it("does not move a statically positioned element when a scale resize lands", async () => {
+it.each([
+  {
+    name: "does not move a statically positioned element when a scale resize lands",
+    shift: { x: 0, y: 0 },
+  },
+  {
+    name: "puts a statically positioned element on a sub-pixel drop point",
+    shift: { x: 0.3, y: -0.2 },
+    writes: true,
+  },
+  {
+    name: "leaves a static position alone when the drop is off by less than the file's precision",
+    shift: { x: 0.0003, y: 0 },
+    writes: false,
+  },
+  {
+    name: "leaves an animated position alone for a sub-pixel drop point",
+    shift: { x: 0.3, y: -0.2 },
+    animated: true,
+    writes: false,
+  },
+])("$name", async ({ shift, animated, writes }) => {
   document.body.innerHTML = "";
   const el = document.createElement("div");
   el.id = "clip";
@@ -476,7 +497,7 @@ it("does not move a statically positioned element when a scale resize lands", as
   el.style.height = "128px";
   document.body.append(el);
 
-  const pos = { x: 587, y: 235 };
+  const pos = { x: 587 + shift.x, y: 235 + shift.y };
   const scale = { x: 1.648, y: 1.648 };
   const [LEFT, TOP] = [120, 520];
   el.getBoundingClientRect = () => {
@@ -517,6 +538,15 @@ it("does not move a statically positioned element when a scale resize lands", as
     duration: 0,
     global: true,
   } as unknown as GsapAnimation;
+  const positionTween = {
+    ...positionHold,
+    id: "#clip-to-0-position",
+    method: "to",
+    properties: { x: 500 },
+    duration: 4,
+    global: false,
+  } as unknown as GsapAnimation;
+  const position = animated ? positionTween : positionHold;
   const selection = { id: "clip", selector: "#clip", element: el } as DomEditSelection;
   usePlayerStore.setState({ currentTime: 0.5 });
   const commitMutation = vi.fn();
@@ -524,22 +554,27 @@ it("does not move a statically positioned element when a scale resize lands", as
   await tryGsapResizeIntercept(
     selection,
     { width: 320, height: 128 },
-    [keyframedScaleFixture(), positionHold],
+    [keyframedScaleFixture(), position],
     iframe,
     commitMutation,
-    async () => [keyframedScaleFixture(), positionHold],
+    async () => [keyframedScaleFixture(), position],
   );
 
   const positionWrites = commitMutation.mock.calls
     .map((call) => call[1] as { properties?: Record<string, number> })
     .filter((mutation) => mutation.properties?.x != null || mutation.properties?.y != null);
-  // Either it left the position alone, or it rewrote the same value.
+  // No position write, or one that moves the hold by exactly the drop's sub-pixel offset.
+  if (writes === false) expect(positionWrites).toEqual([]);
+  if (writes) expect(positionWrites.length).toBeGreaterThan(0);
   for (const write of positionWrites) {
-    expect(write.properties?.x).toBe(432);
-    expect(write.properties?.y).toBe(173);
+    expect(write.properties?.x).toBeCloseTo(432 + shift.x, 3);
+    expect(write.properties?.y).toBeCloseTo(173 + shift.y, 3);
   }
-  // And the live element ends on the drop point, not a drag away from it.
-  expect(el.getBoundingClientRect().x).toBeCloseTo(603.3, 0);
+  // And the live box is centred where it was dropped (left 120 + 587 + 160, top 520 + 235 + 64).
+  const landed = animated ? { x: 0, y: 0 } : shift;
+  const box = el.getBoundingClientRect();
+  expect(box.x + box.width / 2).toBeCloseTo(867 + landed.x, 3);
+  expect(box.y + box.height / 2).toBeCloseTo(819 + landed.y, 3);
 });
 
 function titleSelection(): DomEditSelection {

package/src/hooks/gsapResizeIntercept.ts

@@ -170,6 +170,11 @@ function tweenUsesScaleLonghands(anim: GsapAnimation | null): boolean {
 
 // ── Resize intercept ──────────────────────────────────────────────────────
 
+// The resize is centre-anchored, so a scale that cannot reproduce the dragged size splits the gap evenly.
+function rectCentre(rect: DOMRect): { x: number; y: number } {
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+
 // fallow-ignore-next-line complexity
 export async function tryGsapResizeIntercept(
   selection: DomEditSelection,
@@ -371,15 +376,10 @@ export async function tryGsapResizeIntercept(
     committedScale = useScaleLonghands
       ? { x: newScaleX, y: newScaleY }
       : { x: newScaleX, y: newScaleX };
-    // Where the user DROPPED the box: the draft (anchor-pinned to the
-    // gesture-start top-left) is still applied here, so this rect is exactly
-    // what the preview showed at release. The committed scale renders around
-    // the element CENTER instead — the finalize step below measures that
-    // difference and compensates, so release matches the drop pixel-for-pixel
-    // regardless of live scale or repeat resizes.
+    // Where the user DROPPED the box: the draft is still applied, so this is what the preview showed
+    // at release. The finalize step below moves the committed scale's box onto it.
     if (el) {
-      const dropRect = draw(() => el.getBoundingClientRect());
-      scaleDraftDropPoint = { x: dropRect.x, y: dropRect.y };
+      scaleDraftDropPoint = draw(() => rectCentre(el.getBoundingClientRect()));
     }
   } else {
     resizeProps = {
@@ -396,8 +396,8 @@ export async function tryGsapResizeIntercept(
   // position (a `tl.set` hold or none) — a keyframed position path has no
   // single anchor to preserve, so it keeps the plain center-scale behavior.
   // The size route hands its draft to GSAP itself (handOverDraftSize).
-  // ponytail: for a 3D-rotated element the rects are AABBs, so the anchor is
-  // approximate rather than corner-exact.
+  // ponytail: the centre of an AABB is exact for any 2D transform; under
+  // perspective it is approximate.
   // fallow-ignore-next-line complexity
   const finalizeScaleResizeCommit = async (): Promise<boolean> => {
     // Only the scale route captures the element, so a null draft means this
@@ -428,15 +428,9 @@ export async function tryGsapResizeIntercept(
       );
       const base = { x: baseGsapX, y: baseGsapY };
       setElementGsapPosition(draftEl, base.x, base.y);
-      const post = draftEl.getBoundingClientRect();
+      const post = rectCentre(draftEl.getBoundingClientRect());
       const residual = { x: dropPoint.x - post.x, y: dropPoint.y - post.y };
       if (!Number.isFinite(residual.x) || !Number.isFinite(residual.y)) return null;
-      if (Math.abs(residual.x) < 0.5 && Math.abs(residual.y) < 0.5) {
-        logResize("scale-finalize", { skipped: "already-on-drop-point", residual, base });
-        // Settled, with nothing to write. Still ours: forwarding the drag offset
-        // on top would move the box off the point it is already sitting on.
-        return "settled" as const;
-      }
       // The ONE corrected position — rounded once so the live runtime and the
       // persisted file agree exactly (commitStaticGsapPosition composes the same
       // rounded value from this delta).
@@ -444,9 +438,15 @@ export async function tryGsapResizeIntercept(
         x: roundTo3(base.x + residual.x),
         y: roundTo3(base.y + residual.y),
       };
+      if (corrected.x === roundTo3(base.x) && corrected.y === roundTo3(base.y)) {
+        logResize("scale-finalize", { skipped: "already-on-drop-point", residual, base });
+        // Settled, with nothing to write. Still ours: forwarding the drag offset
+        // on top would move the box off the point it is already sitting on.
+        return "settled" as const;
+      }
       logResize("scale-finalize", {
         dropPoint,
-        post: { x: post.x, y: post.y },
+        post,
         residual,
         gsapPos,
         base,
@@ -455,11 +455,11 @@ export async function tryGsapResizeIntercept(
       // Correct the live box in the same task as the measurement, so no frame shows it off the drop
       // point while the position write is in flight.
       setElementGsapPosition(draftEl, corrected.x, corrected.y);
-      return { base, corrected };
+      return { base, corrected, residual };
     });
     if (measured === null) return false;
     if (measured === "settled") return true;
-    const { base, corrected } = measured;
+    const { base, corrected, residual } = measured;
     // Re-fetch: the scale commit above just rewrote the script, so the caller's
     // animation list (and its ids) may be stale for the position lookup.
     const currentAnimations = fetchFallbackAnimations
@@ -482,6 +482,11 @@ export async function tryGsapResizeIntercept(
       moment.time,
     );
     if (positionTween) {
+      // A sub-pixel correction is not worth a keyframe in an authored tween.
+      if (Math.abs(residual.x) < 0.5 && Math.abs(residual.y) < 0.5) {
+        draw(() => setElementGsapPosition(draftEl, base.x, base.y));
+        return true;
+      }
       logResize("scale-finalize", { route: "position-keyframe", tweenId: positionTween.id });
       assertGsapEditPersisted(
         await commitGsapPositionFromDrag(selection, positionTween, delta, base, iframe, {

package/src/hooks/useConsoleErrorCapture.test.tsx

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, expect, it } from "vitest";
 import { STUDIO_PREVIEW_ERRORS } from "@hyperframes/core/studio-preview-mark";
+import { announcePreviewDocumentLoaded } from "../player/sceneSwap";
 import { useConsoleErrorCapture } from "./useConsoleErrorCapture";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
@@ -36,7 +37,7 @@ it("shows the errors a preview raised before its load, once each", async () => {
   root = createRoot(document.createElement("div"));
   await act(async () => root?.render(React.createElement(Harness, { iframe })));
   Object.assign(previewWindow, { [STUDIO_PREVIEW_ERRORS]: [raisedBeforeLoad] });
-  await act(async () => iframe.dispatchEvent(new Event("load")));
+  await act(async () => announcePreviewDocumentLoaded(iframe));
 
   expect(shown()).toEqual([raisedBeforeLoad]);
 });
@@ -79,9 +80,27 @@ it("clears a document's errors when its load replaces it, and when the preview g
     previewWindow.dispatchEvent(new ErrorEvent("error", { message: "Uncaught Error: old" })),
   );
   Object.assign(previewWindow, { [STUDIO_PREVIEW_ERRORS]: ["Uncaught Error: new"] });
-  await act(async () => iframe.dispatchEvent(new Event("load")));
+  await act(async () => announcePreviewDocumentLoaded(iframe));
   expect(shown()).toEqual(["Uncaught Error: new"]);
 
   await act(async () => root?.render(React.createElement(NullableHarness, { frame: null })));
   expect(capture.consoleErrors).toBeNull();
+  await act(async () => announcePreviewDocumentLoaded(iframe));
+  expect(capture.consoleErrors).toBeNull();
+});
+
+it("keeps a page's errors through its own late load, and clears them for the next announced page", async () => {
+  const { iframe, previewWindow } = previewFrame();
+  root = createRoot(document.createElement("div"));
+  await act(async () => root?.render(React.createElement(Harness, { iframe })));
+  await act(async () =>
+    previewWindow.dispatchEvent(new ErrorEvent("error", { message: "Uncaught Error: kept" })),
+  );
+
+  await act(async () => iframe.dispatchEvent(new Event("load")));
+  expect(shown()).toEqual(["Uncaught Error: kept"]);
+
+  Object.assign(previewWindow, { [STUDIO_PREVIEW_ERRORS]: ["Uncaught Error: new page"] });
+  await act(async () => announcePreviewDocumentLoaded(iframe));
+  expect(shown()).toEqual(["Uncaught Error: new page"]);
 });

package/src/hooks/useConsoleErrorCapture.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { STUDIO_PREVIEW_ERRORS } from "@hyperframes/core/studio-preview-mark";
+import { onPreviewDocumentLoaded } from "../player/sceneSwap";
 import type { LintFinding } from "../components/LintModal";
 
 /**
@@ -73,9 +74,9 @@ export function useConsoleErrorCapture(previewIframe: HTMLIFrameElement | null)
     };
 
     attachErrorCapture();
-    previewIframe.addEventListener("load", attachErrorCapture);
+    const stopLoaded = onPreviewDocumentLoaded(previewIframe, attachErrorCapture);
     return () => {
-      previewIframe.removeEventListener("load", attachErrorCapture);
+      stopLoaded();
       detachErrorCapture();
     };
   }, [previewIframe, resetErrors]);

package/src/hooks/useThumbnailStripSize.test.tsx

@@ -18,9 +18,125 @@ vi.mock("../player/components/timelineZoomInput", () => ({
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
+/** Runs the frames the hook asked for, as the browser does after the observer's delivery. */
+function nextFrames() {
+  vi.useFakeTimers({ toFake: ["requestAnimationFrame", "cancelAnimationFrame"] });
+  return () => act(() => vi.advanceTimersToNextFrame());
+}
+
+// A strip that re-rendered inside the observer's delivery resized the timeline Chromium had already measured that
+// frame, which it reported as a ResizeObserver loop on every frame of a trim.
+it("applies a reported size on the next frame, never inside the observer's delivery", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const runFrames = nextFrames();
+  const host = document.createElement("div");
+  document.body.append(host);
+  Object.defineProperty(host, "clientWidth", { configurable: true, value: 300 });
+  Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+  const root = createRoot(host);
+  function Harness() {
+    const [size, ref] = useThumbnailStripSize();
+    return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+  }
+  try {
+    act(() => root.render(<Harness />));
+    reportResize(310, 40);
+    reportResize(320, 40);
+    expect(vi.getTimerCount()).toBe(1);
+    expect(host.textContent).toBe("300x40");
+    runFrames();
+    expect(host.textContent).toBe("320x40");
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
+it("cancels a pending resize frame when the last strip unmounts", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const runFrames = nextFrames();
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  function Harness() {
+    const [, ref] = useThumbnailStripSize();
+    return <div ref={ref} />;
+  }
+  try {
+    act(() => root.render(<Harness />));
+    reportResize(320, 40);
+    expect(vi.getTimerCount()).toBe(1);
+    act(() => root.unmount());
+    expect(vi.getTimerCount()).toBe(0);
+    runFrames();
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
+it("drops a pending size when its strip unmounts, so a strip remounted on that box keeps its own", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const runFrames = nextFrames();
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  function Strip() {
+    const [size, ref] = useThumbnailStripSize();
+    return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+  }
+  function Box({ id }: { id: string }) {
+    const box = (element: HTMLDivElement | null) => {
+      if (!element) return;
+      Object.defineProperty(element, "clientWidth", { configurable: true, value: 300 });
+      Object.defineProperty(element, "clientHeight", { configurable: true, value: 40 });
+    };
+    return (
+      <div ref={box} data-testid="box">
+        <Strip key={id} />
+      </div>
+    );
+  }
+  // The other strip keeps the shared observer alive across the remount.
+  const render = (id: string) =>
+    act(() =>
+      root.render(
+        <>
+          <div>
+            <Strip />
+          </div>
+          <Box id={id} />
+        </>,
+      ),
+    );
+  try {
+    render("a");
+    reportResize(320, 40);
+    render("b");
+    runFrames();
+    expect(host.querySelector('[data-testid="box"]')?.textContent).toBe("300x40");
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
 it("does not re-render the strip when the observer reports the size it already holds", () => {
   const originalResizeObserver = globalThis.ResizeObserver;
   globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const runFrames = nextFrames();
   const host = document.createElement("div");
   document.body.append(host);
   Object.defineProperty(host, "clientWidth", { configurable: true, value: 300 });
@@ -45,14 +161,18 @@ it("does not re-render the strip when the observer reports the size it already h
     const settled = stripRenders;
 
     act(() => reportResize(300, 40));
+    runFrames();
     expect(stripRenders).toBe(settled);
 
     act(() => reportResize(320, 40));
+    runFrames();
     expect(stripRenders).toBe(settled + 1);
     expect(host.textContent).toBe("320x40");
   } finally {
     act(() => root.unmount());
     host.remove();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
     globalThis.ResizeObserver = originalResizeObserver;
   }
 });
@@ -60,6 +180,7 @@ it("does not re-render the strip when the observer reports the size it already h
 it("measures a strip once a zoom preview ends, not while the preview scales it", () => {
   const originalResizeObserver = globalThis.ResizeObserver;
   globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const runFrames = nextFrames();
   const host = document.createElement("div");
   document.body.append(host);
   let width = 300;
@@ -75,6 +196,7 @@ it("measures a strip once a zoom preview ends, not while the preview scales it",
     zoom.previewing = true;
     width = 600;
     act(() => reportResize(600, 40));
+    runFrames();
     expect(host.textContent).toBe("300x40");
     zoom.previewing = false;
     act(() => zoom.listeners.forEach((listener) => listener()));
@@ -83,6 +205,7 @@ it("measures a strip once a zoom preview ends, not while the preview scales it",
     zoom.previewing = false;
     act(() => root.unmount());
     host.remove();
+    vi.useRealTimers();
     globalThis.ResizeObserver = originalResizeObserver;
   }
 });

package/src/hooks/useThumbnailStripSize.ts

@@ -152,13 +152,20 @@ const measure = (entries: { target: Element; size?: { width: number; height: num
 const onPresence = (entries: IntersectionObserverEntry[]) =>
   measure(entries.filter((entry) => entry.isIntersecting));
 
-const onResize = (entries: ResizeObserverEntry[]) =>
-  measure(
-    entries.map(({ target, contentRect: { width, height } }) => ({
-      target,
-      size: { width, height },
-    })),
-  );
+const pendingSizes = new Map<Element, { width: number; height: number }>();
+let pendingSizesFrame = 0;
+const applyPendingSizes = () => {
+  pendingSizesFrame = 0;
+  const entries = [...pendingSizes].map(([target, size]) => ({ target, size }));
+  pendingSizes.clear();
+  measure(entries);
+};
+
+const applyResizesNextFrame = (entries: ResizeObserverEntry[]) => {
+  for (const { target, contentRect } of entries)
+    pendingSizes.set(target, { width: contentRect.width, height: contentRect.height });
+  pendingSizesFrame ||= requestAnimationFrame(applyPendingSizes);
+};
 
 const observeIntersections = (callback: IntersectionObserverCallback) =>
   typeof IntersectionObserver === "undefined"
@@ -168,7 +175,7 @@ const observeIntersections = (callback: IntersectionObserverCallback) =>
 function acquire() {
   if (users++ === 0) {
     shared = {
-      resize: new ResizeObserver(onResize),
+      resize: new ResizeObserver(applyResizesNextFrame),
       presence: observeIntersections(onPresence),
       gaps: observeIntersections(
         (entries) => entries.some((entry) => entry.isIntersecting) && scheduleRefresh(),
@@ -190,6 +197,9 @@ function release() {
   window.removeEventListener("scroll", scheduleRefresh, { capture: true });
   cancelAnimationFrame(frame);
   frame = 0;
+  cancelAnimationFrame(pendingSizesFrame);
+  pendingSizesFrame = 0;
+  pendingSizes.clear();
 }
 
 const watchGap = (gap: HTMLDivElement | null) => {
@@ -234,6 +244,7 @@ export function useThumbnailStripSize() {
       resize.unobserve(target);
       presence?.unobserve(target);
       strips.delete(target);
+      pendingSizes.delete(target);
       release();
     };
   }, []);

package/src/index.ts

@@ -202,6 +202,7 @@ export type { UseClipboardOptions } from "./hooks/useClipboard";
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
 export { useLivePreviewIframe } from "./hooks/useLivePreviewIframe";
+export { announcePreviewDocumentLoaded } from "./player/sceneSwap";
 export type { PreviewPromotion } from "./player/sceneSwap";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence";

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

@@ -47,6 +47,7 @@ beforeEach(() => {
 afterEach(() => {
   act(() => root?.unmount());
   root = null;
+  vi.useRealTimers();
   thumbnailScheduler.invalidateProject("/api/projects/demo/preview");
   globalThis.ResizeObserver = originalResizeObserver;
   globalThis.Image = originalImage;
@@ -175,7 +176,9 @@ describe("CompositionThumbnail", () => {
       await new Promise((resolve) => setTimeout(resolve, 0));
     });
 
+    vi.useFakeTimers({ toFake: ["requestAnimationFrame", "cancelAnimationFrame"] });
     act(() => reportResize(500, 40));
+    act(() => vi.advanceTimersToNextFrame());
 
     expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
   });

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

@@ -2,7 +2,7 @@
 
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { ImageThumbnail } from "./ImageThumbnail";
@@ -64,6 +64,7 @@ beforeEach(() => {
 afterEach(() => {
   act(() => root?.unmount());
   root = null;
+  vi.useRealTimers();
   thumbnailScheduler.invalidateProject("p");
   globalThis.IntersectionObserver = originalIO;
   globalThis.ResizeObserver = originalRO;
@@ -187,7 +188,9 @@ describe("ImageThumbnail", () => {
       probe.onload?.();
     });
 
+    vi.useFakeTimers({ toFake: ["requestAnimationFrame", "cancelAnimationFrame"] });
     act(() => reportResize(500, 40));
+    act(() => vi.advanceTimersToNextFrame());
 
     expect(host.querySelector("img")?.parentElement?.style.width).toBe("108px");
   });

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

@@ -10,6 +10,7 @@ import {
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
 import { usePlayerStore } from "../store/playerStore";
+import { onPreviewDocumentLoaded } from "../sceneSwap";
 
 vi.mock("@hyperframes/player", () => ({}));
 
@@ -196,6 +197,49 @@ describe("callbacks after the player is already mounted", () => {
     expect(first).not.toHaveBeenCalled();
   });
 
+  it("loads the preview on the runtime's ready while a stalled font holds the window's load", async () => {
+    const onLoad = vi.fn();
+    const { player } = await mountPlayer({ onLoad });
+    const iframe = (player as TestHyperframesPlayer).iframeElement;
+    let page = {};
+    Object.defineProperty(iframe, "contentDocument", { get: () => page });
+    Object.defineProperty(iframe, "contentWindow", { get: () => ({ __playerReady: true }) });
+    const announced = vi.fn();
+    onPreviewDocumentLoaded(iframe, announced);
+
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    act(() => void iframe.dispatchEvent(new Event("load")));
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    page = {};
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(2);
+    expect(announced).toHaveBeenCalledTimes(2);
+  });
+
+  it("leaves a ready that arrives before the page's runtime boots to the page's own load", async () => {
+    const onLoad = vi.fn();
+    const { player } = await mountPlayer({ onLoad });
+    const iframe = (player as TestHyperframesPlayer).iframeElement;
+    const page = {};
+    let runtime: { __playerReady?: boolean } = {};
+    Object.defineProperty(iframe, "contentDocument", { get: () => page });
+    Object.defineProperty(iframe, "contentWindow", { get: () => runtime });
+
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).not.toHaveBeenCalled();
+
+    act(() => void iframe.dispatchEvent(new Event("load")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    runtime = { __playerReady: true };
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+  });
+
   it("reports the preview error cause", async () => {
     const onPreviewError = vi.fn();
     const { player } = await mountPlayer({ onPreviewError });

package/src/player/components/Player.tsx

@@ -5,6 +5,8 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { HyperframesLoader } from "../../components/ui";
 import { usePlayerStore } from "../store/playerStore";
+import { announcePreviewDocumentLoaded } from "../sceneSwap";
+import type { IframeWindow } from "../lib/playbackTypes";
 // 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
@@ -128,6 +130,9 @@ export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean
   }
 }
 
+const runtimeBootedIn = (iframe: HTMLIFrameElement) =>
+  (iframe.contentWindow as IframeWindow | null)?.__playerReady === true;
+
 /**
  * Renders a composition preview using the <hyperframes-player> web component.
  *
@@ -228,9 +233,11 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           const loading = getShaderTransitionLoading(event);
           if (loading !== null) setShaderTransitionLoading(loading);
         };
+        let loadedDocument: Document | null = null;
         const handleReady = () => {
           setPreviewError(null);
           setCompositionLoading(false);
+          if (iframe.contentDocument && runtimeBootedIn(iframe)) handleLoad();
         };
         const handlePainted = () => {
           setPainted(true);
@@ -243,6 +250,9 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           setCompositionLoading(false);
         };
         const handleLoad = () => {
+          const doc = iframe.contentDocument;
+          if (doc && doc === loadedDocument) return;
+          loadedDocument = doc;
           loadCountRef.current++;
           setLoaded(true);
           setPreviewError(null);
@@ -258,6 +268,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             container.addEventListener("animationend", onEnd, { once: true });
           }
           onLoadRef.current();
+          announcePreviewDocumentLoaded(iframe);
 
           // Show a loading overlay until every `<video>`/`<audio>` and Lottie
           // asset is ready. Without this users can click play before audio has