From 16959deeac55c65a730d18b3a4ef7c366b0e0223 Mon Sep 17 00:00:00 2001 From: James Russo Date: Tue, 22 Sep 2026 21:05:15 +0100 Subject: [PATCH 1/7] fix(studio): don't fail a shadow reload while the tab is hidden (#4292) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The shadow reload promotes on frame-driven readiness (the player's paint-and-idle, then two requestAnimationFrames) but failed on a wall-clock 15s setTimeout. A hidden tab renders no frames, so every external edit made while Studio was in the background failed with "it took too long to load", the toasts stacked, and the stale preview stayed up even after returning to the tab. The budget now only runs while the document is visible: hiding the tab clears the timer, and showing it again restarts the full budget for the pending shadow, which then promotes normally. Fixes #4290 — Rames Jusso Co-authored-by: Claude Opus 5.5 (1M context) --- .../player/hooks/useShadowPreviewReload.ts | 47 +++++++++++++--- .../useTimelinePlayer.shadowReload.test.ts | 53 +++++++++++++++++++ 2 files changed, 94 insertions(+), 6 deletions(-) diff --git a/packages/studio/src/player/hooks/useShadowPreviewReload.ts b/packages/studio/src/player/hooks/useShadowPreviewReload.ts index 0e01d6d18f..b813ef497a 100644 --- a/packages/studio/src/player/hooks/useShadowPreviewReload.ts +++ b/packages/studio/src/player/hooks/useShadowPreviewReload.ts @@ -16,8 +16,13 @@ import type { PlaybackAdapter } from "../lib/playbackTypes"; // The single 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. export const SHADOW_READY_TIMEOUT_MS = 15_000; +function isDocumentHidden(): boolean { + return typeof document !== "undefined" && document.visibilityState === "hidden"; +} + type UseShadowPreviewReloadParams = Omit< UseTimelineSyncCallbacksParams, "probeIntervalRef" | "onAdapterReady" | "getAdapter" | "isCurrent" | "onLoadGiveUp" @@ -55,11 +60,14 @@ export function useShadowPreviewReload({ const onReloadFailedRef = useRef(onReloadFailed); onReloadFailedRef.current = onReloadFailed; const readyTimerRef = useRef | undefined>(undefined); + // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible. + const budgetGenRef = useRef(null); const cancelPendingLoadRef = useRef<() => void>(() => {}); const [previewSlots, setPreviewSlots] = useState([{ gen: 0, role: "live" }]); const stopPendingShadow = useCallback(() => { clearTimeout(readyTimerRef.current); + budgetGenRef.current = null; cancelPendingLoadRef.current(); pendingCommitRef.current = null; visuallyReadyGenRef.current = null; @@ -145,18 +153,30 @@ export function useShadowPreviewReload({ shadowIframeRef.current = node; }, []); + const armReadyTimer = useCallback( + (gen: number) => { + clearTimeout(readyTimerRef.current); + if (isDocumentHidden()) return; + readyTimerRef.current = setTimeout( + () => failShadow(gen, "it took too long to load"), + SHADOW_READY_TIMEOUT_MS, + ); + }, + [failShadow], + ); + const armReadyTimerRef = useRef(armReadyTimer); + armReadyTimerRef.current = armReadyTimer; + const beginShadowReload = useCallback( (url: string) => { shadowGenRef.current += 1; const gen = shadowGenRef.current; stopPendingShadow(); - readyTimerRef.current = setTimeout( - () => failShadow(gen, "it took too long to load"), - SHADOW_READY_TIMEOUT_MS, - ); + budgetGenRef.current = gen; + armReadyTimer(gen); setPreviewSlots((prev) => planShadowReload(prev, gen, url)); }, - [stopPendingShadow, failShadow], + [stopPendingShadow, armReadyTimer], ); // Composition switch (not an edit reload): drop any in-flight shadow. @@ -169,7 +189,22 @@ export function useShadowPreviewReload({ setPreviewSlots(planShadowDiscard); }, [stopPendingShadow, isRefreshingRef, pendingSeekRef]); - useMountEffect(() => stopPendingShadow); + // Hiding the tab pauses the budget; showing it again restarts the full budget for a pending shadow. + useMountEffect(() => { + const onVisibilityChange = () => { + if (isDocumentHidden()) { + clearTimeout(readyTimerRef.current); + return; + } + const gen = budgetGenRef.current; + if (gen != null && gen === shadowGenRef.current) armReadyTimerRef.current(gen); + }; + document.addEventListener("visibilitychange", onVisibilityChange); + return () => { + document.removeEventListener("visibilitychange", onVisibilityChange); + stopPendingShadow(); + }; + }); return { previewSlots, diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts index 25439e3dc9..7fa37aa5d2 100644 --- a/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +++ b/packages/studio/src/player/hooks/useTimelinePlayer.shadowReload.test.ts @@ -289,6 +289,50 @@ describe("shadow reload readiness and failure", () => { unmount(root); }); + it("does not spend the budget while the tab is hidden, and promotes once it is visible", () => { + vi.useFakeTimers(); + const onPreviewReloadFailed = vi.fn(); + const setVisibility = stubVisibility("hidden"); + const { getApi, gen, root } = beginReload({ onPreviewReloadFailed }); + const shadow = makeShadowWithSpies(); + act(() => { + getApi().setShadowIframeNode(shadow.iframe); + getApi().onShadowIframeLoad(gen); + }); + + // A hidden tab renders no frames, so readiness cannot arrive; the wall clock must not fail it. + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS * 3)); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + expect(getApi().previewSlots).toHaveLength(2); + + act(() => setVisibility("visible")); + act(() => getApi().onShadowReadyChange(gen, true)); + expect(getApi().iframeRef.current).toBe(shadow.iframe); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + unmount(root); + }); + + it("restarts the full budget when a hidden tab becomes visible, then fails a shadow that stays silent", () => { + vi.useFakeTimers(); + vi.spyOn(console, "error").mockImplementation(() => {}); + const onPreviewReloadFailed = vi.fn(); + const setVisibility = stubVisibility("visible"); + const { getApi, live, root } = beginReload({ onPreviewReloadFailed }); + + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS - 1000)); + act(() => setVisibility("hidden")); + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS)); + expect(onPreviewReloadFailed).not.toHaveBeenCalled(); + + act(() => setVisibility("visible")); + act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_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("drops a shadow whose document reports an error and reports the cause", () => { vi.spyOn(console, "error").mockImplementation(() => {}); const onPreviewReloadFailed = vi.fn(); @@ -455,3 +499,12 @@ function unmount(root: ReturnType) { root.unmount(); }); } + +function stubVisibility(initial: DocumentVisibilityState) { + let state = initial; + vi.spyOn(document, "visibilityState", "get").mockImplementation(() => state); + return (next: DocumentVisibilityState) => { + state = next; + document.dispatchEvent(new Event("visibilitychange")); + }; +} From d4485b51f1591241bd82f85ede80faf25c18aecc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Tue, 22 Sep 2026 16:12:35 -0400 Subject: [PATCH 2/7] chore: release v0.8.62 (#4293) --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- docs/changelog.mdx | 16 ++++++++++++++++ packages/aws-lambda/package.json | 2 +- packages/cli/package.json | 2 +- packages/core/package.json | 2 +- packages/engine/package.json | 2 +- packages/gcp-cloud-run/package.json | 2 +- packages/lint/package.json | 2 +- packages/parsers/package.json | 2 +- packages/player/package.json | 2 +- packages/producer/package.json | 2 +- packages/sdk/package.json | 2 +- packages/shader-transitions/package.json | 2 +- packages/studio-server/package.json | 2 +- packages/studio/package.json | 2 +- releases/v0.8.62.md | 17 +++++++++++++++++ 18 files changed, 49 insertions(+), 16 deletions(-) create mode 100644 releases/v0.8.62.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 356339d53a..f379445b7f 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hyperframes", "description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.", - "version": "0.8.61", + "version": "0.8.62", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 44782b6737..2dd1605c7b 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hyperframes", "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.", - "version": "0.8.61", + "version": "0.8.62", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 629623d1e4..a529c3dfba 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -3,7 +3,7 @@ "name": "hyperframes", "displayName": "HyperFrames by HeyGen", "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.", - "version": "0.8.61", + "version": "0.8.62", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com" diff --git a/docs/changelog.mdx b/docs/changelog.mdx index 9564dceef6..f056409202 100644 --- a/docs/changelog.mdx +++ b/docs/changelog.mdx @@ -8,6 +8,22 @@ Recent HyperFrames releases, including user-facing features, fixes, and migratio {/* New release entries are prepended by `bun run changelog:draft --write`. */} + +Studio no longer drops an edit's preview while its tab is in the background, and the catalog gains a text match cut. + +## Fixes + +- **Studio:** Don't fail a shadow reload while the tab is hidden ([16959deea](https://github.com/heygen-com/hyperframes/commit/16959deeac55c65a730d18b3a4ef7c366b0e0223), [#4292](https://github.com/heygen-com/hyperframes/pull/4292)). + +## Catalog + +- **Registry:** Text-match-cut ([0945de83c](https://github.com/heygen-com/hyperframes/commit/0945de83c7f51ba0c20c7c0a56421f066a378ee8), [#4288](https://github.com/heygen-com/hyperframes/pull/4288)). + +