@hyperframes/studio 0.8.180 → 0.8.181

package/dist/index.html

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

package/dist/index.js

@@ -31726,8 +31726,19 @@ function useShadowPreviewReload({
     (gen) => {
       clearTimeout(readyTimerRef.current);
       if (isDocumentHidden()) return;
+      let drew = false;
+      let starved = false;
+      requestAnimationFrame(() => {
+        if (!starved) drew = true;
+        else if (budgetGenRef.current === gen) armReadyTimerRef.current(gen);
+      });
       readyTimerRef.current = setTimeout(() => {
         if (gen !== shadowGenRef.current) return;
+        if (!drew) {
+          starved = true;
+          logReload("shadow-starved", { gen });
+          return;
+        }
         budgetsSpentRef.current += 1;
         if (budgetsSpentRef.current < SHADOW_READY_BUDGETS) {
           logReload("shadow-slow", { budgetsSpent: budgetsSpentRef.current });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.180",
+  "version": "0.8.181",
   "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.180",
-    "@hyperframes/sdk": "0.8.180",
-    "@hyperframes/parsers": "0.8.180",
-    "@hyperframes/shader-transitions": "0.8.180",
-    "@hyperframes/player": "0.8.180",
-    "@hyperframes/studio-server": "0.8.180"
+    "@hyperframes/core": "0.8.181",
+    "@hyperframes/parsers": "0.8.181",
+    "@hyperframes/player": "0.8.181",
+    "@hyperframes/sdk": "0.8.181",
+    "@hyperframes/shader-transitions": "0.8.181",
+    "@hyperframes/studio-server": "0.8.181"
   },
   "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.180"
+    "@hyperframes/producer": "0.8.181"
   },
   "peerDependencies": {
     "react": "19",

package/src/player/hooks/useShadowPreviewReload.ts

@@ -25,7 +25,7 @@ import { usePlayerStore } from "../store/playerStore";
 
 // One wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
 // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
-// It only runs while the tab is visible: readiness is frame-driven, and a hidden tab renders none.
+// Spent only while frames are drawn (readiness needs them); a hidden tab or a covered Linux window draws none.
 export const SHADOW_READY_TIMEOUT_MS = 15_000;
 // A busy machine can need more than one budget; the shadow keeps loading for this many before it is dropped.
 export const SHADOW_READY_BUDGETS = 3;
@@ -276,8 +276,19 @@ export function useShadowPreviewReload({
     (gen: number) => {
       clearTimeout(readyTimerRef.current);
       if (isDocumentHidden()) return;
+      let drew = false;
+      let starved = false;
+      requestAnimationFrame(() => {
+        if (!starved) drew = true;
+        else if (budgetGenRef.current === gen) armReadyTimerRef.current(gen);
+      });
       readyTimerRef.current = setTimeout(() => {
         if (gen !== shadowGenRef.current) return;
+        if (!drew) {
+          starved = true;
+          logReload("shadow-starved", { gen });
+          return;
+        }
         budgetsSpentRef.current += 1;
         if (budgetsSpentRef.current < SHADOW_READY_BUDGETS) {
           logReload("shadow-slow", { budgetsSpent: budgetsSpentRef.current });

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

@@ -545,6 +545,60 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  // A window behind others on some Linux desktops draws no frames yet reports visible; readiness needs frames.
+  it("does not spend the budget while the window draws no frames, and promotes once they return", () => {
+    vi.useFakeTimers();
+    const frames = holdFrames();
+    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 * 2));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    expect(getApi().previewSlots).toHaveLength(2);
+
+    act(() => frames.resume());
+    act(() => getApi().onShadowReadyChange(gen, true));
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    unmount(root);
+  });
+
+  it("gives a shadow its full budget once frames return, then fails one that stays silent", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const frames = holdFrames();
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, live, root } = beginReload({ onPreviewReloadFailed });
+
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
+    act(() => frames.resume());
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS - 1));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(1));
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    expect(getApi().iframeRef.current).toBe(live);
+    unmount(root);
+  });
+
+  it("keeps a reload's own budget when the frames a replaced one waited on return", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const frames = holdFrames();
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, root } = beginReload({ onPreviewReloadFailed });
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS + 1000));
+
+    act(() => getApi().refreshPlayer());
+    act(() => frames.resume());
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    unmount(root);
+  });
+
   it("still drops and reports a shadow whose window throws on access", () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const onPreviewReloadFailed = vi.fn();
@@ -806,6 +860,25 @@ function unmount(root: ReturnType<typeof createRoot>) {
   });
 }
 
+/** A window that draws no frames although it reports visible: frames are held until `resume`, then one per 16 ms. */
+function holdFrames() {
+  let held: FrameRequestCallback[] = [];
+  let flowing = false;
+  vi.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
+    if (flowing) return Number(setTimeout(() => callback(performance.now()), 16));
+    held.push(callback);
+    return held.length;
+  });
+  return {
+    resume: () => {
+      flowing = true;
+      const waiting = held;
+      held = [];
+      for (const callback of waiting) callback(performance.now());
+    },
+  };
+}
+
 function stubVisibility(initial: DocumentVisibilityState) {
   let state = initial;
   vi.spyOn(document, "visibilityState", "get").mockImplementation(() => state);