@hyperframes/studio 0.8.165 → 0.8.166

package/dist/index.html

@@ -14,7 +14,7 @@
         document.documentElement.dataset.theme = "paper";
       }
     </script>
-    <script type="module" crossorigin src="/assets/index-DFRwKDBl.js"></script>
+    <script type="module" crossorigin src="/assets/index-DQ_I6X0d.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DkQKsFxx.css">
   </head>
   <body>

package/dist/index.js

@@ -31510,6 +31510,13 @@ function restoreSeekPainted(iframe) {
   return win?.__hfWaitForSeekCompletion?.().catch(() => {
   });
 }
+function shadowPlayerReachable(iframe) {
+  try {
+    return Boolean(iframe?.contentWindow?.__player);
+  } catch {
+    return false;
+  }
+}
 function isDocumentHidden() {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
@@ -31565,6 +31572,7 @@ function useShadowPreviewReload({
   const failShadow = useCallback39(
     (gen, cause) => {
       if (gen !== shadowGenRef.current) return;
+      const waitingFor = !shadowPlayerReachable(shadowIframeRef.current) ? "the page and its runtime to load" : pendingCommitRef.current?.gen !== gen ? "its timeline to be ready" : "its loaders to clear";
       shadowGenRef.current += 1;
       stopPendingShadow();
       shadowIframeRef.current = null;
@@ -31572,8 +31580,8 @@ function useShadowPreviewReload({
       pendingSeekRef.current = null;
       setPreviewSlots(planShadowDiscard);
       setPreviewReloading(false);
-      const message = `The preview did not reload (${cause}). The previous preview is still showing.`;
-      logReload("shadow-failed", { cause });
+      const message = `The preview did not reload (${cause}). It was still waiting for ${waitingFor}. The previous preview is still showing.`;
+      logReload("shadow-failed", { cause, waitingFor });
       console.error(`[studio] ${message}`);
       onReloadFailedRef.current?.(message);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.165",
+  "version": "0.8.166",
   "description": "",
   "repository": {
     "type": "git",
@@ -59,12 +59,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.165",
-    "@hyperframes/sdk": "0.8.165",
-    "@hyperframes/parsers": "0.8.165",
-    "@hyperframes/shader-transitions": "0.8.165",
-    "@hyperframes/studio-server": "0.8.165",
-    "@hyperframes/player": "0.8.165"
+    "@hyperframes/core": "0.8.166",
+    "@hyperframes/parsers": "0.8.166",
+    "@hyperframes/sdk": "0.8.166",
+    "@hyperframes/player": "0.8.166",
+    "@hyperframes/shader-transitions": "0.8.166",
+    "@hyperframes/studio-server": "0.8.166"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.165"
+    "@hyperframes/producer": "0.8.166"
   },
   "peerDependencies": {
     "react": "19",

package/src/player/hooks/useShadowPreviewReload.ts

@@ -35,6 +35,14 @@ function restoreSeekPainted(iframe: HTMLIFrameElement | null): Promise<void> | u
   return win?.__hfWaitForSeekCompletion?.().catch(() => {});
 }
 
+function shadowPlayerReachable(iframe: HTMLIFrameElement | null): boolean {
+  try {
+    return Boolean((iframe?.contentWindow as IframeWindow | null | undefined)?.__player);
+  } catch {
+    return false;
+  }
+}
+
 function isDocumentHidden(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
@@ -104,6 +112,11 @@ export function useShadowPreviewReload({
   const failShadow = useCallback(
     (gen: number, cause: string) => {
       if (gen !== shadowGenRef.current) return;
+      const waitingFor = !shadowPlayerReachable(shadowIframeRef.current)
+        ? "the page and its runtime to load"
+        : pendingCommitRef.current?.gen !== gen
+          ? "its timeline to be ready"
+          : "its loaders to clear";
       shadowGenRef.current += 1;
       stopPendingShadow();
       shadowIframeRef.current = null;
@@ -111,8 +124,8 @@ export function useShadowPreviewReload({
       pendingSeekRef.current = null;
       setPreviewSlots(planShadowDiscard);
       setPreviewReloading(false);
-      const message = `The preview did not reload (${cause}). The previous preview is still showing.`;
-      logReload("shadow-failed", { cause });
+      const message = `The preview did not reload (${cause}). It was still waiting for ${waitingFor}. The previous preview is still showing.`;
+      logReload("shadow-failed", { cause, waitingFor });
       console.error(`[studio] ${message}`);
       onReloadFailedRef.current?.(message);
     },

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

@@ -371,6 +371,9 @@ describe("shadow reload readiness and failure", () => {
     expect(getApi().iframeRef.current).toBe(live);
     expect(live.style.visibility).toBe("");
     expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(
+      expect.stringContaining("still waiting for the page and its runtime to load"),
+    );
     expect(consoleError).toHaveBeenCalled();
     unmount(root);
   });
@@ -395,6 +398,48 @@ describe("shadow reload readiness and failure", () => {
     act(() => void vi.advanceTimersByTime(1));
     expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
     expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(
+      expect.stringContaining("still waiting for the page and its runtime to load"),
+    );
+    unmount(root);
+  });
+
+  it("names the timeline when a shadow's runtime runs but never reports a length", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, gen, root } = beginReload({ onPreviewReloadFailed });
+    const lengthless = makeFakeIframe(makeAdapterWindow({ duration: 0 }).win);
+    act(() => {
+      getApi().setShadowIframeNode(lengthless);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
+
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(
+      expect.stringContaining("still waiting for its timeline to be ready"),
+    );
+    unmount(root);
+  });
+
+  it("names the loaders when a shadow with a ready timeline never clears them", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, gen, root } = beginReload({ onPreviewReloadFailed });
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+    });
+
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
+
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(
+      expect.stringContaining("still waiting for its loaders to clear"),
+    );
     unmount(root);
   });
 
@@ -475,6 +520,31 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("still drops and reports a shadow whose window throws on access", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, live, gen, root } = beginReload({ onPreviewReloadFailed });
+    const crossOrigin = makeFakeIframe(
+      Object.defineProperty({}, "__player", {
+        get: () => {
+          throw new DOMException("Blocked a frame", "SecurityError");
+        },
+      }),
+    );
+    act(() => getApi().setShadowIframeNode(crossOrigin));
+
+    act(() => getApi().onShadowError(gen, "Composition timeline not found after 8s"));
+
+    expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
+    expect(getApi().iframeRef.current).toBe(live);
+    expect(isPreviewChanging()).toBe(false);
+    expect(onPreviewReloadFailed).toHaveBeenCalledTimes(1);
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(
+      expect.stringContaining("still waiting for the page and its runtime to load"),
+    );
+    unmount(root);
+  });
+
   it("drops a shadow whose document reports an error and reports the cause", () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const onPreviewReloadFailed = vi.fn();