mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
Miguel Ángel
ebd156bcc1
* fix: batch GSAP timeline construction to prevent main-thread hang (#1231) Compositions with thousands of tl.to() calls (e.g. 8,562 in the reported case) block Chrome's main thread synchronously during HTML parsing, preventing DOMContentLoaded from firing before Puppeteer's navigation timeout. This caused render jobs to hang indefinitely at 'Initializing calibration session...' with no error message. Root cause: GSAP's timeline API is synchronous — each tl.to() call registers a tween immediately on the main thread. A script with 8k+ calls holds the thread for seconds, starving the browser event loop and delaying DCL past the navigation timeout window. Fix: install a property trap on window.gsap in HF_EARLY_STUB (injected at the top of <head>, before GSAP or user scripts load). When GSAP assigns itself to window.gsap, the setter intercepts the real gsap object and wraps gsap.timeline() to return a proxy that queues tween descriptors (to/from/fromTo/set) instead of calling them synchronously. A requestAnimationFrame-based flush loop drains 100 tweens per frame, yielding the main thread between batches so DCL can fire. When the queue is drained, the stub sets window.__hfTimelinesBuilding = false and dispatches a 'hf-timelines-built' CustomEvent. init.ts checks this flag at DOMContentLoaded time; if building is still in progress it defers bindRootTimelineIfAvailable() until the event fires, then sets window.__renderReady = true as normal. pollHfReady continues to gate on both __renderReady and window.__hf.duration > 0, so the render pipeline does not start until the full timeline is bound. - Batch size: 100 tweens/rAF tick (empirical; ~4ms/batch at 8k scale) - Yield mechanism: requestAnimationFrame (cooperative, no setTimeout(0)) - Determinism: 'hf-timelines-built' event guarantees sequencing - Proxy forwards: pause/seek/totalTime/time/duration/add/paused/ timeScale/play delegate to the real timeline immediately - No GSAP package changes; no navigation timeout increase Fixes #1231 * style: apply oxfmt formatting to producer stub files * fix(producer): unwrap proxy children in add(), gate setter return on args.length Addresses two latent correctness concerns from code review: 1. proxy.add() now unwraps __hfReal from any proxy child before passing it to the real timeline. GSAP's internal tween graph (_first/_next/_prev linkage) requires real timeline instances — proxy objects lack internal fields like _dp that GSAP's iteration paths expect. 2. totalTime/time/paused/timeScale now return proxy when called in setter form (args.length > 0). Previously these returned the real timeline, causing callers who chain .to(...) after a setter call to bypass batching. Also: build-hf-early-stub.ts now runs oxfmt on the generated output file so the format check passes in CI on every build. * fix(producer): gate __hf.duration=0 while GSAP timelines are batching The HF_BRIDGE_SCRIPT duration getter now returns 0 whenever window.__hfTimelinesBuilding is true (set by HF_EARLY_STUB while the rAF batch loop is draining queued tl.to() calls). pollHfReady in the engine polls until window.__hf.duration > 0, so returning 0 keeps the engine waiting until the hf-timelines-built event fires and all tweens are committed to the real GSAP timelines. Without this gate, normal compositions (style-6, style-13, vignelli) were being captured mid-batch — the real timelines were empty so GSAP could not seek them, producing frozen/blank frames in the output video. * fix(producer): flush GSAP batching under virtual time * fix(producer): gate render bridge on runtime readiness * fix(producer): preserve timeline child binding under batching
83 lines
2.7 KiB
TypeScript
83 lines
2.7 KiB
TypeScript
/**
|
|
* Build script: compile stubs/hf-early-stub.ts → src/generated/hf-early-stub-inline.ts
|
|
*
|
|
* Run via: bun run scripts/build-hf-early-stub.ts
|
|
* (also called automatically as part of `bun run build`)
|
|
*
|
|
* Output format mirrors packages/core/scripts/build-hyperframes-runtime-artifact.ts:
|
|
* a TypeScript module exporting a single string-constant getter that is
|
|
* compiled by tsc into dist/ — no esbuild, no file I/O, no dynamic paths at
|
|
* runtime.
|
|
*/
|
|
|
|
import { mkdirSync, writeFileSync } from "node:fs";
|
|
import { dirname, resolve } from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { buildSync } from "esbuild";
|
|
import { execSync } from "node:child_process";
|
|
|
|
const thisDir = dirname(fileURLToPath(import.meta.url));
|
|
const repoRoot = resolve(thisDir, "..");
|
|
|
|
const stubEntry = resolve(repoRoot, "stubs/hf-early-stub.ts");
|
|
const generatedDir = resolve(repoRoot, "src/generated");
|
|
const outPath = resolve(generatedDir, "hf-early-stub-inline.ts");
|
|
|
|
// ── Compile the stub to a self-contained IIFE ─────────────────────────────────
|
|
const result = buildSync({
|
|
entryPoints: [stubEntry],
|
|
bundle: true,
|
|
write: false,
|
|
platform: "browser",
|
|
format: "iife",
|
|
target: ["es2020"],
|
|
// Minify for production — the stub is injected on every page load.
|
|
minify: true,
|
|
legalComments: "none",
|
|
});
|
|
|
|
const iife = result.outputFiles[0]?.text ?? "";
|
|
if (!iife) {
|
|
throw new Error("esbuild produced no output for hf-early-stub.ts");
|
|
}
|
|
|
|
// ── Write the generated module ────────────────────────────────────────────────
|
|
mkdirSync(generatedDir, { recursive: true });
|
|
|
|
const escaped = JSON.stringify(iife);
|
|
writeFileSync(
|
|
outPath,
|
|
[
|
|
"// AUTO-GENERATED by scripts/build-hf-early-stub.ts — do not edit",
|
|
`const HF_EARLY_STUB_IIFE: string = ${escaped};`,
|
|
"",
|
|
"/**",
|
|
" * Returns the pre-built HyperFrames early stub IIFE as a string constant.",
|
|
" * Inject into <head> before any other scripts so the GSAP batching",
|
|
" * interceptor is in place when user composition scripts run.",
|
|
" */",
|
|
"export function getHfEarlyStub(): string {",
|
|
" return HF_EARLY_STUB_IIFE;",
|
|
"}",
|
|
"",
|
|
].join("\n"),
|
|
"utf8",
|
|
);
|
|
|
|
// Format the generated file so `oxfmt --check` passes in CI.
|
|
// Errors are intentionally swallowed — oxfmt unavailable in some envs.
|
|
try {
|
|
execSync(`bunx oxfmt ${outPath}`, { stdio: "ignore" });
|
|
} catch {
|
|
// not fatal
|
|
}
|
|
|
|
console.log(
|
|
JSON.stringify({
|
|
event: "hf_early_stub_generated",
|
|
stubEntry,
|
|
outPath,
|
|
bytes: Buffer.byteLength(iife, "utf8"),
|
|
}),
|
|
);
|