From 071ec1fdddb874927f85827a42e84f04924f1bd2 Mon Sep 17 00:00:00 2001 From: kevin <5299031+kevin9327@users.noreply.github.com> Date: Thu, 5 Nov 2026 02:15:44 +0000 Subject: [PATCH] fix(runtime): fail readiness waits when a buildReady promise rejects (#5746) A rejected window.__hf.buildReady hold now sets window.__hfStartupError naming the key and the reason, so render, snapshot and check fail instead of capturing a scene that was never built. Fixes #5603 --- .../generated/position-edits-render-inline.ts | 2 +- packages/core/src/runtime/diagnostics.ts | 20 +++++ packages/core/src/runtime/init.test.ts | 85 +++++++++++++++++++ packages/core/src/runtime/init.ts | 54 ++++++++++-- 4 files changed, 154 insertions(+), 7 deletions(-) diff --git a/packages/core/src/generated/position-edits-render-inline.ts b/packages/core/src/generated/position-edits-render-inline.ts index 030b1e1556..8e4f79d69a 100644 --- a/packages/core/src/generated/position-edits-render-inline.ts +++ b/packages/core/src/generated/position-edits-render-inline.ts @@ -1,6 +1,6 @@ // Generated by scripts/build-position-edits-render.ts; do not edit. const POSITION_EDITS_RENDER_IIFE: string = - '"use strict";(()=>{function x(){return globalThis}function T(e,t){if(typeof window>"u")return;let o=x(),r=o.__hf?.onSwallowed;if(r)try{r({label:e,error:t})}catch(s){}(o.__hfDebug||o.__HYPERFRAMES_DEBUG)&&console.debug(`[hyperframes] ${e} swallowed:`,t)}var P=null;function R(e,t){if(P)try{P({source:"hf-preview",type:"analytics",event:e,properties:t??{}})}catch(o){T("runtime.analytics.site1",o)}}var I="http://www.w3.org/1999/xhtml";function N(e){return e!=null&&e.nodeType===1}function _(e){return N(e)&&(e.namespaceURI===I||e.namespaceURI==="http://www.w3.org/2000/svg")}var y="data-hf-edit-base-x",w="data-hf-edit-base-y",m="data-hf-edit-original-translate",k=e=>{let t=parseFloat(e??"");return Number.isFinite(t)?t:0},C=e=>{let t=[],o=0,r="";for(let s of e.trim())s==="("&&(o+=1),s===")"&&(o=Math.max(0,o-1)),/\\s/.test(s)&&o===0?(r&&t.push(r),r=""):r+=s;return r&&t.push(r),t},$=/^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)px$/,E=(e,t)=>$.test(e)&&$.test(t)?`${parseFloat(e)+parseFloat(t)}px`:`calc(${e} + ${t})`,O=(e,t,o)=>{if(!e||e==="none")return`${t} ${o}`;let[r,s,a]=C(e);if(r===void 0)return`${t} ${o}`;if(s===void 0)return`${E(r,t)} ${o}`;let i=a===void 0?"":` ${a}`;return`${E(r,t)} ${E(s,o)}${i}`},j=e=>{try{e.ownerDocument.defaultView?.gsap?.getProperty?.(e,"x")}catch{}},V=e=>{let t=e.style.getPropertyValue("translate").trim();if(t)return t==="none"?"":t;try{let o=e.ownerDocument.defaultView,r=o?o.getComputedStyle(e).getPropertyValue("translate").trim():"";return r==="none"?"":r}catch{return""}},b=new WeakMap;function B(e,t){let o=b.get(e);if(!t?.force&&o!==void 0&&e.style.getPropertyValue("translate")!==o){R("position_edit_fold_skipped",{hfId:e.getAttribute("data-hf-id")});return}let r=k(e.getAttribute("data-x"))-k(e.getAttribute(y)),s=k(e.getAttribute("data-y"))-k(e.getAttribute(w));e.hasAttribute(m)||e.setAttribute(m,V(e)),o===void 0&&j(e);let a=e.getAttribute(m)??"",i=O(a,`${r}px`,`${s}px`);e.style.setProperty("translate",i),b.set(e,e.style.getPropertyValue("translate"))}function S(e,t){let o=e.querySelectorAll(`[${m}]:not([${y}]):not([${w}])`);for(let a=0;a{try{S(t.document)}catch{}},r=n=>typeof n=="function"&&(D.has(n)||!!n[L]),s=n=>{D.add(n);try{Object.defineProperty(n,L,{value:!0})}catch{}},a=n=>{if(typeof n!="function"||r(n))return n;let l=function(...u){let d=n.apply(this,u);return o(),d};return s(l),l},i=(n,l)=>{let u=F.get(n);if(u?.has(l))return!0;let d=Object.getOwnPropertyDescriptor(n,l);if(d?.configurable===!1){let c=n[l];return typeof c=="function"&&(n[l]=a(c),o()),!1}let p=n[l],f=d?.set;return Object.defineProperty(n,l,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>p,set:c=>{p=a(c),f?.call(n,c)}}),p=a(p),u??(u=new Set),u.add(l),F.set(n,u),o(),!0},g=(n,l)=>{let u=H.get(t),d=Object.getOwnPropertyDescriptor(t,n);if(!u?.has(n)){if(d?.configurable===!1){let c=t[n];return c?i(c,l):!1}let f=t[n];Object.defineProperty(t,n,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>f,set:c=>{f=c,f&&i(f,l)}}),u??(u=new Set),u.add(n),H.set(t,u)}let p=t[n];return p?i(p,l):!1},h=()=>{let n=g("__hf","seek"),l=g("__player","renderSeek");return n&&l};if(h())return;let v=120,A=t.setInterval(()=>{if(h()){t.clearInterval(A);return}v-=1,v<=0&&t.clearInterval(A)},50)}function W(){document.querySelector(`[${y}], [${w}]`)&&(S(document),M(window))}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",W,{once:!0}):W();})();\n'; + '"use strict";(()=>{function x(){return globalThis}function R(e,t){if(typeof window>"u")return;let o=x(),r=o.__hf?.onSwallowed;if(r)try{r({label:e,error:t})}catch(s){}(o.__hfDebug||o.__HYPERFRAMES_DEBUG)&&console.debug(`[hyperframes] ${e} swallowed:`,t)}var T=null;function P(e,t){if(T)try{T({source:"hf-preview",type:"analytics",event:e,properties:t??{}})}catch(o){R("runtime.analytics.site1",o)}}var I="http://www.w3.org/1999/xhtml";function N(e){return e!=null&&e.nodeType===1}function k(e){return N(e)&&(e.namespaceURI===I||e.namespaceURI==="http://www.w3.org/2000/svg")}var w="data-hf-edit-base-x",y="data-hf-edit-base-y",m="data-hf-edit-original-translate",_=e=>{let t=parseFloat(e??"");return Number.isFinite(t)?t:0},C=e=>{let t=[],o=0,r="";for(let s of e.trim())s==="("&&(o+=1),s===")"&&(o=Math.max(0,o-1)),/\\s/.test(s)&&o===0?(r&&t.push(r),r=""):r+=s;return r&&t.push(r),t},$=/^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)px$/,E=(e,t)=>$.test(e)&&$.test(t)?`${parseFloat(e)+parseFloat(t)}px`:`calc(${e} + ${t})`,O=(e,t,o)=>{if(!e||e==="none")return`${t} ${o}`;let[r,s,a]=C(e);if(r===void 0)return`${t} ${o}`;if(s===void 0)return`${E(r,t)} ${o}`;let i=a===void 0?"":` ${a}`;return`${E(r,t)} ${E(s,o)}${i}`},j=e=>{try{e.ownerDocument.defaultView?.gsap?.getProperty?.(e,"x")}catch{}},B=e=>{let t=e.style.getPropertyValue("translate").trim();if(t)return t==="none"?"":t;try{let o=e.ownerDocument.defaultView,r=o?o.getComputedStyle(e).getPropertyValue("translate").trim():"";return r==="none"?"":r}catch{return""}},b=new WeakMap;function V(e,t){let o=b.get(e);if(!t?.force&&o!==void 0&&e.style.getPropertyValue("translate")!==o){P("position_edit_fold_skipped",{hfId:e.getAttribute("data-hf-id")});return}let r=_(e.getAttribute("data-x"))-_(e.getAttribute(w)),s=_(e.getAttribute("data-y"))-_(e.getAttribute(y));e.hasAttribute(m)||e.setAttribute(m,B(e)),o===void 0&&j(e);let a=e.getAttribute(m)??"",i=O(a,`${r}px`,`${s}px`);e.style.setProperty("translate",i),b.set(e,e.style.getPropertyValue("translate"))}function h(e,t){let o=e.querySelectorAll(`[${m}]:not([${w}]):not([${y}])`);for(let a=0;a{try{h(t.document)}catch{}},r=n=>typeof n=="function"&&(D.has(n)||!!n[L]),s=n=>{D.add(n);try{Object.defineProperty(n,L,{value:!0})}catch{}},a=n=>{if(typeof n!="function"||r(n))return n;let l=function(...u){let d=n.apply(this,u);return o(),d};return s(l),l},i=(n,l)=>{let u=F.get(n);if(u?.has(l))return!0;let d=Object.getOwnPropertyDescriptor(n,l);if(d?.configurable===!1){let c=n[l];return typeof c=="function"&&(n[l]=a(c),o()),!1}let p=n[l],f=d?.set;return Object.defineProperty(n,l,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>p,set:c=>{p=a(c),f?.call(n,c)}}),p=a(p),u??(u=new Set),u.add(l),F.set(n,u),o(),!0},g=(n,l)=>{let u=H.get(t),d=Object.getOwnPropertyDescriptor(t,n);if(!u?.has(n)){if(d?.configurable===!1){let c=t[n];return c?i(c,l):!1}let f=t[n];Object.defineProperty(t,n,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>f,set:c=>{f=c,f&&i(f,l)}}),u??(u=new Set),u.add(n),H.set(t,u)}let p=t[n];return p?i(p,l):!1},S=()=>{let n=g("__hf","seek"),l=g("__player","renderSeek");return n&&l};if(S())return;let v=120,A=t.setInterval(()=>{if(S()){t.clearInterval(A);return}v-=1,v<=0&&t.clearInterval(A)},50)}function M(){document.querySelector(`[${w}], [${y}]`)&&(h(document),W(window))}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",M,{once:!0}):M();})();\n'; /** Returns the pre-built position-edits render IIFE as a string constant. */ export function getPositionEditsRenderScript(): string { diff --git a/packages/core/src/runtime/diagnostics.ts b/packages/core/src/runtime/diagnostics.ts index 17ac1f66c2..d110e6f55f 100644 --- a/packages/core/src/runtime/diagnostics.ts +++ b/packages/core/src/runtime/diagnostics.ts @@ -51,6 +51,26 @@ export function recordStartupError(error: unknown): void { /** Starts the warning for a scene callback that threw; the render log shows it once per render. */ export const SCENE_CALLBACK_ERROR_PREFIX = "[hyperframes] scene timeline callback threw:"; +/** + * A rejected `window.__hf.buildReady[key]` is the composition saying its own setup failed, so + * readiness waits (render, snapshot, check) fail with the key and reason instead of capturing an + * unbuilt scene. Returns the recorded message so a teardown can clear exactly this error. + */ +export function recordBuildReadyRejection(key: string, error: unknown): string { + let detail = "unknown error"; + try { + detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error); + } catch (err) { + swallow("runtime.buildReadyRejection", err); + } + const message = + `window.__hf.buildReady[${JSON.stringify(key)}] rejected: ${detail}. ` + + `The composition reported that its own setup failed, so it cannot be rendered. Fix that ` + + `setup, or resolve the promise only once the scene is drawable.`; + (window as Window & { __hfStartupError?: string }).__hfStartupError = message; + return message; +} + export function swallow(label: string, error?: unknown): void { if (typeof window === "undefined") return; const w = getDebugSurface(); diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts index 93c9911528..953b093c66 100644 --- a/packages/core/src/runtime/init.test.ts +++ b/packages/core/src/runtime/init.test.ts @@ -4540,6 +4540,91 @@ describe("initSandboxRuntimeModular", () => { expect(window.__renderReady).toBe(true); }); + // GH #5603: a rejected hold must fail render, snapshot and check rather than let them capture a + // scene that was never built. + describe("a rejected window.__hf.buildReady promise", () => { + const mountRoot = () => { + const root = document.createElement("div"); + root.setAttribute("data-composition-id", "main"); + root.setAttribute("data-root", "true"); + root.setAttribute("data-start", "0"); + root.setAttribute("data-width", "1920"); + root.setAttribute("data-height", "1080"); + document.body.appendChild(root); + window.__timelines = { main: createMockTimeline(10) }; + }; + const flush = async () => { + for (let i = 0; i < 5; i++) await Promise.resolve(); + }; + + afterEach(() => { + delete window.__hfStartupError; + }); + + it("records a startup error naming the key and the reason", async () => { + mountRoot(); + window.__hf = window.__hf || {}; + window.__hf.buildReady = { + mesh: Promise.resolve(), + scene: Promise.reject(new Error("build failed: bad baked data")), + }; + + initSandboxRuntimeModular(); + await flush(); + + expect(window.__hfStartupError).toContain('window.__hf.buildReady["scene"] rejected'); + expect(window.__hfStartupError).toContain("Error: build failed: bad baked data"); + expect(window.__hfStartupError).not.toContain('"mesh"'); + }); + + it("holds render-ready until the rejection, then releases it with the error set", async () => { + mountRoot(); + let rejectBuild: (reason: unknown) => void = () => {}; + window.__hf = window.__hf || {}; + window.__hf.buildReady = { + scene: new Promise((_, reject) => { + rejectBuild = reject; + }), + }; + + initSandboxRuntimeModular(); + expect(window.__renderReady).toBe(false); + expect(window.__hfStartupError).toBeUndefined(); + + rejectBuild("no WebGPU adapter"); + await flush(); + + // The error lands in the same tick as render-ready, so no readiness poll sees one without the other. + expect(window.__renderReady).toBe(true); + expect(window.__hfStartupError).toContain('["scene"] rejected: no WebGPU adapter'); + }); + + it("leaves no startup error when every hold resolves", async () => { + mountRoot(); + window.__hf = window.__hf || {}; + window.__hf.buildReady = { scene: Promise.resolve() }; + + initSandboxRuntimeModular(); + await flush(); + + expect(window.__renderReady).toBe(true); + expect(window.__hfStartupError).toBeUndefined(); + }); + + it("does not fail the next composition loaded after teardown", async () => { + mountRoot(); + window.__hf = window.__hf || {}; + window.__hf.buildReady = { scene: Promise.reject(new Error("first build failed")) }; + initSandboxRuntimeModular(); + await flush(); + expect(window.__hfStartupError).toContain("first build failed"); + + window.__hfRuntimeTeardown?.(); + + expect(window.__hfStartupError).toBeUndefined(); + }); + }); + it("clears a stale buildReady entry on teardown so the next init isn't blocked by it", async () => { const root = document.createElement("div"); root.setAttribute("data-composition-id", "main"); diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts index 0c473dd061..85beab1cfb 100644 --- a/packages/core/src/runtime/init.ts +++ b/packages/core/src/runtime/init.ts @@ -203,7 +203,12 @@ import type { } from "./types"; import type { PlayerAPI } from "../core.types"; import { parseFps } from "../fps"; -import { recordStartupError, SCENE_CALLBACK_ERROR_PREFIX, swallow } from "./diagnostics"; +import { + recordBuildReadyRejection, + recordStartupError, + SCENE_CALLBACK_ERROR_PREFIX, + swallow, +} from "./diagnostics"; import { readTimelineDurationSeconds } from "./timelineDuration"; import { CHANGE_DRIVEN_SERVICE_MIN_INTERVAL_MS, @@ -310,6 +315,15 @@ function samePromiseSet(a: PromiseLike[], b: PromiseLike[] | n return b !== null && a.length === b.length && a.every((p, i) => p === b[i]); } +class BuildReadyRejection extends Error { + constructor( + readonly key: string, + readonly reason: unknown, + ) { + super(`window.__hf.buildReady[${JSON.stringify(key)}] rejected`); + } +} + // `Promise.all` allocates a fresh promise every call, so comparing ITS // identity across repeat polls is never stable — that re-arms a `.then()` // on every poll and never lets the caller observe "settled", even once the @@ -4066,17 +4080,37 @@ export function initSandboxRuntimeModular(): void { // window.__hf.buildReady[key]: a piece registers a promise for setup no // adapter can observe (mesh building, shader compiles). Waited the same // way as adapter readiness, so render and preview both hold on it. + // A rejection still releases the hold, but it is recorded as a startup error (with the key that + // failed) so render, snapshot and check fail instead of capturing a scene that was never built. + // Each entry is wrapped once and cached so the tracker sees the same promise set on every poll. + const keyedBuildReadyPromises = new WeakMap>(); + let buildReadyRejectionMessage: string | null = null; const isBuildReadinessSettled = createSettledTracker( () => { const registry = window.__hf?.buildReady; if (!registry) return []; - return Object.values(registry).filter( - (p): p is PromiseLike => - p != null && typeof (p as PromiseLike).then === "function", - ); + const promises: PromiseLike[] = []; + for (const [key, p] of Object.entries(registry)) { + if (p == null || typeof (p as PromiseLike).then !== "function") continue; + let keyed = keyedBuildReadyPromises.get(p); + if (!keyed) { + keyed = Promise.resolve(p).then(undefined, (reason: unknown) => { + throw new BuildReadyRejection(key, reason); + }); + keyedBuildReadyPromises.set(p, keyed); + } + promises.push(keyed); + } + return promises; }, () => maybePublishRenderReady(), - (err) => swallow("runtime.init.buildReady", err), + (err) => { + if (err instanceof BuildReadyRejection) { + buildReadyRejectionMessage = recordBuildReadyRejection(err.key, err.reason); + return; + } + swallow("runtime.init.buildReady", err); + }, ); // Passes that must see scene DOM, which arrives after init: when scenes mount, or when one is @@ -6423,6 +6457,14 @@ export function initSandboxRuntimeModular(): void { // would otherwise permanently block render-ready for whatever loads next // into this window, since window.__hf itself is never reset. if (window.__hf?.buildReady) window.__hf.buildReady = {}; + // Likewise its rejected build must not fail the next composition's readiness waits. + if ( + buildReadyRejectionMessage !== null && + window.__hfStartupError === buildReadyRejectionMessage + ) { + delete window.__hfStartupError; + } + buildReadyRejectionMessage = null; for (const cleanup of runtimeCleanupCallbacks.splice(0)) { try { cleanup();