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
This commit is contained in:
kevin
2026-11-05 02:15:44 +00:00
committed by GitHub
parent 33c17df5ae
commit 071ec1fddd
4 changed files with 154 additions and 7 deletions
@@ -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<o.length;a++){let i=o[a];if(i===void 0||!_(i))continue;let g=i.getAttribute(m)??"";g===""?i.style.removeProperty("translate"):i.style.setProperty("translate",g),i.removeAttribute(m),b.delete(i)}let r=e.querySelectorAll(`[${y}], [${w}]`),s=0;for(let a=0;a<r.length;a++){let i=r[a];i===void 0||!_(i)||(B(i,t),s+=1)}return s}var L="__hfPositionEditsSeekReapplyWrapped",D=new WeakSet,F=new WeakMap,H=new WeakMap;function M(e){let t=e,o=()=>{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<o.length;a++){let i=o[a];if(i===void 0||!k(i))continue;let g=i.getAttribute(m)??"";g===""?i.style.removeProperty("translate"):i.style.setProperty("translate",g),i.removeAttribute(m),b.delete(i)}let r=e.querySelectorAll(`[${w}], [${y}]`),s=0;for(let a=0;a<r.length;a++){let i=r[a];i===void 0||!k(i)||(V(i,t),s+=1)}return s}var L="__hfPositionEditsSeekReapplyWrapped",D=new WeakSet,F=new WeakMap,H=new WeakMap;function W(e){let t=e,o=()=>{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 {
+20
View File
@@ -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();
+85
View File
@@ -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<void>((_, 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");
+48 -6
View File
@@ -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<unknown>[], b: PromiseLike<unknown>[] | 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<object, PromiseLike<unknown>>();
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<unknown> =>
p != null && typeof (p as PromiseLike<unknown>).then === "function",
);
const promises: PromiseLike<unknown>[] = [];
for (const [key, p] of Object.entries(registry)) {
if (p == null || typeof (p as PromiseLike<unknown>).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();