Skip to content

Write HTML. Render video. Built for agents.

fix(core): composition scripts start after web fonts are ready, so renders repeat (#4980)

Miguel Ángel44b583625095
diff --git a/bun.lock b/bun.lock
index 11a5bc144b..a8d7af76cf 100644
--- a/bun.lock
+++ b/bun.lock
@@ -24,7 +24,7 @@
},
"packages/aws-lambda": {
"name": "@hyperframes/aws-lambda",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@aws-sdk/client-s3": "^3.700.0",
"@aws-sdk/client-sfn": "^3.700.0",
@@ -57,7 +57,7 @@
},
"packages/cli": {
"name": "@hyperframes/cli",
- "version": "0.8.111",
+ "version": "0.8.119",
"bin": {
"hyperframes": "./bin/hyperframes.mjs",
"hyperframes-localize-fonts": "./bin/hyperframes-localize-fonts.mjs",
@@ -109,7 +109,7 @@
},
"packages/core": {
"name": "@hyperframes/core",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@chenglou/pretext": "^0.0.5",
"@hyperframes/lint": "workspace:*",
@@ -135,7 +135,7 @@
},
"packages/engine": {
"name": "@hyperframes/engine",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@hono/node-server": "^2.0.5",
"@hyperframes/core": "workspace:^",
@@ -154,7 +154,7 @@
},
"packages/gcp-cloud-run": {
"name": "@hyperframes/gcp-cloud-run",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@google-cloud/storage": "^7.14.0",
"@google-cloud/workflows": "^4.2.0",
@@ -175,7 +175,7 @@
},
"packages/lint": {
"name": "@hyperframes/lint",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@hyperframes/parsers": "workspace:*",
"acorn": "^8.17.0",
@@ -195,7 +195,7 @@
},
"packages/parsers": {
"name": "@hyperframes/parsers",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@babel/parser": "^7.27.0",
"acorn": "^8.17.0",
@@ -215,7 +215,7 @@
},
"packages/player": {
"name": "@hyperframes/player",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@hyperframes/core": "workspace:*",
},
@@ -230,7 +230,7 @@
},
"packages/producer": {
"name": "@hyperframes/producer",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@fontsource/archivo-black": "^5.2.8",
"@fontsource/eb-garamond": "^5.2.7",
@@ -275,7 +275,7 @@
},
"packages/sdk": {
"name": "@hyperframes/sdk",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@hyperframes/core": "workspace:*",
"@hyperframes/parsers": "workspace:*",
@@ -305,7 +305,7 @@
},
"packages/shader-transitions": {
"name": "@hyperframes/shader-transitions",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"html2canvas": "^1.4.1",
},
@@ -317,7 +317,7 @@
},
"packages/studio": {
"name": "@hyperframes/studio",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@base-ui/react": "1.7.0",
"@codemirror/autocomplete": "^6.20.1",
@@ -370,7 +370,7 @@
},
"packages/studio-server": {
"name": "@hyperframes/studio-server",
- "version": "0.8.111",
+ "version": "0.8.119",
"dependencies": {
"@hyperframes/core": "workspace:*",
"@hyperframes/parsers": "workspace:*",
diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.ts
index baad424554..76a0e34a99 100644
--- a/packages/cli/src/capture/captureCompositionFrame.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts
@@ -1,6 +1,7 @@
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
AUDIT_SEEK_OPTIONS,
@@ -14,6 +15,7 @@ import {
resolveCropRegion,
runFfmpegOnce,
seekCompositionTimeline,
+ waitForRuntimeReady,
type CompositionSeekPage,
} from "./captureCompositionFrame.js";
@@ -48,6 +50,39 @@ afterEach(() => {
vi.unstubAllGlobals();
});
+describe("waitForRuntimeReady", () => {
+ it("waits for the runtime's render-ready flag and reports a timeout as not ready", async () => {
+ const { waitForFunction } = fakeSeekPage();
+
+ await expect(waitForRuntimeReady({ waitForFunction }, 123)).resolves.toBe(true);
+ expect(waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 123 });
+ const ready = waitForFunction.mock.calls[0]![0];
+ vi.stubGlobal("window", { __timelines: {} });
+ expect(ready()).toBe(false);
+ vi.stubGlobal("window", { __timelines: {}, __renderReady: true });
+ expect(ready()).toBe(true);
+
+ waitForFunction.mockRejectedValueOnce(new Error("Waiting failed: 1ms exceeded"));
+ await expect(waitForRuntimeReady({ waitForFunction }, 1)).resolves.toBe(false);
+ });
+
+ it("is what layout, motion-shot and validate wait on before they sample the page", () => {
+ const commands = join(dirname(fileURLToPath(import.meta.url)), "../commands");
+ const firstSample = {
+ layout: "getCompositionDuration(page)",
+ motionShot: "installSeekHelper(page)",
+ validate: "auditClipDurations(page,",
+ };
+ for (const [name, sample] of Object.entries(firstSample)) {
+ const source = readFileSync(join(commands, `${name}.ts`), "utf8");
+ const wait = source.indexOf("await waitForRuntimeReady(page, ");
+ expect(wait, name).toBeGreaterThan(-1);
+ expect(source.indexOf(sample), name).toBeGreaterThan(wait);
+ expect(source, name).not.toContain("__timelines?: unknown }).__timelines");
+ }
+ });
+});
+
describe("seekCompositionTimeline", () => {
it("keeps the raced double-frame settle and adds a bounded font wait by default", async () => {
const { page, evaluate, waitForFunction } = fakeSeekPage();
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index 6c271f83a8..367081cd72 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -125,14 +125,21 @@ function shaderTransitionsReadyInBrowser(): boolean {
return shaderTransitionRegistryReady() ?? shaderLoadingOverlayReady();
}
+export function waitForRuntimeReady(
+ page: Required<Pick<CompositionSeekPage, "waitForFunction">>,
+ timeoutMs: number,
+): Promise<boolean> {
+ return page
+ .waitForFunction(compositionRuntimeReadyInBrowser, { timeout: timeoutMs })
+ .then(() => true)
+ .catch(() => false);
+}
+
async function waitForCompositionSettle(
page: Page,
options: OpenSettledCompositionPageOptions,
): Promise<boolean> {
- const runtimeReady = await page
- .waitForFunction(compositionRuntimeReadyInBrowser, { timeout: options.renderReadyTimeoutMs })
- .then(() => true)
- .catch(() => false);
+ const runtimeReady = await waitForRuntimeReady(page, options.renderReadyTimeoutMs);
if (!runtimeReady) {
console.warn(
diff --git a/packages/cli/src/commands/layout.ts b/packages/cli/src/commands/layout.ts
index f7416b7b70..a6c0288996 100644
--- a/packages/cli/src/commands/layout.ts
+++ b/packages/cli/src/commands/layout.ts
@@ -34,6 +34,7 @@ import {
installPageFunctionGuard,
seekCompositionTimeline,
waitForCompositionFonts,
+ waitForRuntimeReady,
type SeekCompositionTimelineOptions,
} from "../capture/captureCompositionFrame.js";
@@ -237,11 +238,7 @@ async function runLayoutAudit(
});
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
await alignViewportToComposition(page, server.url);
- await page
- .waitForFunction(() => !!(window as unknown as { __timelines?: unknown }).__timelines, {
- timeout: opts.timeout,
- })
- .catch(() => {});
+ await waitForRuntimeReady(page, opts.timeout);
await waitForCompositionFonts(page, 750);
await new Promise((resolveSettle) => setTimeout(resolveSettle, 250));
diff --git a/packages/cli/src/commands/motionShot.ts b/packages/cli/src/commands/motionShot.ts
index 12c3fe15b6..19aa23dc1a 100644
--- a/packages/cli/src/commands/motionShot.ts
+++ b/packages/cli/src/commands/motionShot.ts
@@ -15,6 +15,7 @@ import { mkdirSync, statSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
+import { waitForRuntimeReady } from "../capture/captureCompositionFrame.js";
import {
assertWebGpuAdapterAvailable,
compositionRequiresWebGpu,
@@ -415,11 +416,7 @@ async function openCompositionPage(
await page.setViewport(size);
await page.goto(url, { waitUntil: "domcontentloaded", timeout: navigationTimeout });
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
- await page
- .waitForFunction(() => !!(window as unknown as { __timelines?: unknown }).__timelines, {
- timeout: 10000,
- })
- .catch(() => {});
+ await waitForRuntimeReady(page, 10000);
await page
.evaluate(async () => {
const d = document as unknown as { fonts?: { ready?: Promise<unknown> } };
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
index cef5ccc74c..d842509c37 100644
--- a/packages/cli/src/commands/validate.ts
+++ b/packages/cli/src/commands/validate.ts
@@ -20,6 +20,7 @@ import {
installPageFunctionGuard,
resolveCliChromeGpuMode,
seekCompositionTimeline,
+ waitForRuntimeReady,
} from "../capture/captureCompositionFrame.js";
const __filename = fileURLToPath(import.meta.url);
@@ -503,6 +504,7 @@ async function validateInBrowser(
throw err;
}
await assertWebGpuAdapterAvailable(page, requiresWebGpu);
+ await waitForRuntimeReady(page, opts.timeout ?? 3000);
await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
for (const w of await auditClipDurations(page, analyzeClipMediaFit, opts.timeout ?? 3000)) {
diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts
index 5d3e9d28e0..ef4faacfc2 100644
--- a/packages/core/src/compiler/htmlBundler.test.ts
+++ b/packages/core/src/compiler/htmlBundler.test.ts
@@ -10,6 +10,7 @@ import { resetUnknownEnumWarnings } from "../runtime/getVariables";
import { sanitizeCssValue } from "../runtime/applyVariableBindings";
import { getHyperframeRuntimeScript } from "../generated/runtime-inline";
import { ensureHfIds } from "../parsers/hfIds";
+import { AFTER_FONTS_SCRIPT_TYPE, AFTER_FONTS_SCRIPTS } from "./scriptRuns";
function makeTempProject(files: Record<string, string>): string {
const dir = mkdtempSync(join(tmpdir(), "hf-bundler-test-"));
@@ -215,6 +216,33 @@ describe("bundleToSingleHtml", () => {
expect(bundled).toContain('document.getElementById("scene")');
});
+ it("defers the root's and every mounted composition's scripts until fonts, but not the runtime", async () => {
+ const dir = makeTempProject({
+ "index.html": `<!doctype html>
+<html><body>
+ <div data-composition-id="main" data-width="320" data-height="180">
+ <div data-composition-id="scene" data-composition-src="compositions/scene.html"></div>
+ </div>
+ <script>window.ROOT_SCRIPT = 1;</script>
+ <script type="module">window.ROOT_MODULE = 1;</script>
+</body></html>`,
+ "compositions/scene.html": `<template><div data-composition-id="scene" data-width="320" data-height="180">
+ <script>window.SCENE_SCRIPT = 1;</script>
+</div></template>`,
+ });
+
+ const { document } = parseHTML(await bundleToSingleHtml(dir));
+ const deferred = [...document.querySelectorAll(AFTER_FONTS_SCRIPTS)].map(
+ (el) => el.textContent,
+ );
+ for (const mark of ["SCENE_SCRIPT", "ROOT_SCRIPT", "ROOT_MODULE"]) {
+ expect(deferred.some((text) => text?.includes(mark))).toBe(true);
+ }
+ expect([...document.querySelectorAll("body script")].length).toBe(deferred.length);
+ const runtime = document.querySelector("script[data-hyperframes-preview-runtime]");
+ expect(runtime?.getAttribute("type")).toBeNull();
+ });
+
it("binds a mounted composition's scripts to its own file for __hyperframes.assetUrl", async () => {
const dir = makeTempProject({
"index.html": `<!doctype html>
@@ -257,8 +285,13 @@ describe("bundleToSingleHtml", () => {
const { document } = parseHTML(await bundleToSingleHtml(dir));
const importMaps = [...document.querySelectorAll('script[type="importmap"]')];
- const modules = [...document.querySelectorAll('script[type="module"]')];
- const classic = [...document.querySelectorAll("script:not([type])")].map((s) => s.textContent);
+ // Deferred until fonts: the runtime runs each as the type its marker names.
+ const modules = [
+ ...document.querySelectorAll(`script[type="${AFTER_FONTS_SCRIPT_TYPE}+module"]`),
+ ];
+ const classic = [...document.querySelectorAll(`script[type="${AFTER_FONTS_SCRIPT_TYPE}"]`)].map(
+ (s) => s.textContent,
+ );
expect(importMaps).toHaveLength(1);
expect(JSON.parse(importMaps[0]!.textContent || "")).toEqual({
@@ -599,7 +632,9 @@ describe("bundleToSingleHtml", () => {
const bundled = await bundleToSingleHtml(dir);
- expect(bundled).toMatch(/<script\b[^>]*\btype="module"[^>]*\bsrc="\.\/module\.js"/);
+ expect(bundled).toMatch(
+ /<script\b[^>]*\btype="text\/hf-after-fonts\+module"[^>]*\bsrc="\.\/module\.js"/,
+ );
expect(bundled).not.toContain('import { value } from "./value.js"');
});
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index 999577830a..399f0c3c9e 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -1,6 +1,7 @@
import {
compositionStyle,
cssStyleMergeKey,
+ deferScriptsUntilFonts,
UNCONDITIONAL_CSS_KEY,
headStyleRuns,
inlineScriptRuns,
@@ -1293,6 +1294,7 @@ async function bundleProject(projectDir: string, options?: BundleOptions): Promi
enforceCompositionPixelSizing(document);
autoHealMissingCompositionIds(document);
coalesceHeadStylesAndBodyScripts(document);
+ deferScriptsUntilFonts(document, (el) => el.hasAttribute(RUNTIME_BOOTSTRAP_ATTR));
injectTextRenderingRule(document);
// Inline textual assets
diff --git a/packages/core/src/compiler/index.ts b/packages/core/src/compiler/index.ts
index 5affe4f181..0030fbeb9d 100644
--- a/packages/core/src/compiler/index.ts
+++ b/packages/core/src/compiler/index.ts
@@ -61,8 +61,10 @@ export { addScenePartsManifest } from "./scenePartsManifest";
// Script ordering shared by the bundler and the producer coalescers
export {
+ AFTER_FONTS_SCRIPT_TYPE,
compositionStyle,
cssStyleMergeKey,
+ deferScriptsUntilFonts,
headStyleRuns,
inlineScriptRuns,
styleElementsFor,
diff --git a/packages/core/src/compiler/scriptRuns.test.ts b/packages/core/src/compiler/scriptRuns.test.ts
index 83c2eb7263..dbcb7f8f85 100644
--- a/packages/core/src/compiler/scriptRuns.test.ts
+++ b/packages/core/src/compiler/scriptRuns.test.ts
@@ -1,7 +1,12 @@
// @vitest-environment node
import { parseHTML } from "linkedom";
import { describe, expect, it } from "vitest";
-import { inlineScriptRuns } from "./scriptRuns";
+import {
+ AFTER_FONTS_SCRIPT_TYPE,
+ deferScriptsUntilFonts,
+ inlineScriptRuns,
+ typeAfterFonts,
+} from "./scriptRuns";
function runsOf(bodyHtml: string, isPinned?: (el: Element) => boolean) {
const { document } = parseHTML(`<!doctype html><html><body>${bodyHtml}</body></html>`);
@@ -50,3 +55,40 @@ describe("inlineScriptRuns", () => {
expect(runsOf('<script src="x.js"></script>')).toEqual([]);
});
});
+
+describe("deferScriptsUntilFonts", () => {
+ it("defers each classic and module body script, and only those", () => {
+ const { document } = parseHTML(
+ `<!doctype html><html><head><script>head</script></head><body>` +
+ `<script>a</script><script src="lib.js"></script><script type="text/javascript">b</script>` +
+ `<script type="module">m</script><script type="application/json">{}</script>` +
+ `<script type="importmap">{}</script><script data-runtime>r</script>` +
+ `<svg><script>s</script></svg><noscript><script>n</script></noscript></body></html>`,
+ );
+ deferScriptsUntilFonts(document as unknown as Document, (el) =>
+ el.hasAttribute("data-runtime"),
+ );
+ const deferred = AFTER_FONTS_SCRIPT_TYPE;
+ // First in the head: the fallback that runs them under a runtime without the gate.
+ expect(document.head.firstElementChild?.textContent).toContain("no web-font gate");
+ expect([...document.querySelectorAll("script")].map((el) => el.getAttribute("type"))).toEqual([
+ null,
+ null,
+ deferred,
+ deferred,
+ deferred,
+ `${deferred}+module`,
+ "application/json",
+ "importmap",
+ null,
+ null,
+ null,
+ ]);
+ expect([...document.querySelectorAll("body script")].slice(0, 4).map(typeAfterFonts)).toEqual([
+ null,
+ null,
+ null,
+ "module",
+ ]);
+ });
+});
diff --git a/packages/core/src/compiler/scriptRuns.ts b/packages/core/src/compiler/scriptRuns.ts
index 367a133cb7..29801174e6 100644
--- a/packages/core/src/compiler/scriptRuns.ts
+++ b/packages/core/src/compiler/scriptRuns.ts
@@ -38,6 +38,70 @@ export function inlineScriptRuns(
return runs;
}
+export const AFTER_FONTS_SCRIPT_TYPE = "text/hf-after-fonts";
+const AFTER_FONTS_MODULE_TYPE = `${AFTER_FONTS_SCRIPT_TYPE}+module`;
+export const AFTER_FONTS_SCRIPTS = `script[type="${AFTER_FONTS_SCRIPT_TYPE}"], script[type="${AFTER_FONTS_MODULE_TYPE}"]`;
+
+export const AFTER_FONTS_CLAIM = "__hfAfterFontsClaimed";
+const AFTER_FONTS_FALLBACK_ATTR = "data-hf-after-fonts-fallback";
+
+// For a runtime older than the gate: at DOMContentLoaded, before that runtime boots, run them in parser order.
+const afterFontsFallback = () => `document.addEventListener("DOMContentLoaded", function () {
+ if (window.${AFTER_FONTS_CLAIM}) return;
+ var T = "${AFTER_FONTS_SCRIPT_TYPE}";
+ var all = [].slice.call(document.querySelectorAll('${AFTER_FONTS_SCRIPTS}'));
+ if (!all.length) return;
+ console.warn("[hyperframes] the runtime has no web-font gate; composition scripts run without waiting for fonts");
+ var late = function (el) { return el.type !== T || (el.hasAttribute("src") && el.hasAttribute("defer")); };
+ var queue = all.filter(function (el) { return !late(el); }).concat(all.filter(late));
+ (function next() {
+ var el = queue.shift();
+ if (!el) return;
+ var s = document.createElement("script");
+ for (var i = 0; i < el.attributes.length; i++) s.setAttribute(el.attributes[i].name, el.attributes[i].value);
+ if (el.type === T) s.removeAttribute("type"); else s.type = "module";
+ s.async = el.hasAttribute("async");
+ s.text = el.text;
+ var waits = s.type !== "module" && s.hasAttribute("src") && !s.async && !s.noModule;
+ if (waits) { s.addEventListener("load", next); s.addEventListener("error", next); }
+ el.replaceWith(s);
+ if (!waits) next();
+ })();
+});`;
+
+/** Gives each body script a type the browser does not run, so the runtime can run it once web fonts are ready. */
+export function deferScriptsUntilFonts(
+ document: Document,
+ isFramework: (el: Element) => boolean = () => false,
+): void {
+ let deferred = false;
+ for (const el of document.querySelectorAll("body script")) {
+ if (isFramework(el) || el.closest("noscript, svg")) continue;
+ if (isClassicInline(el)) el.setAttribute("type", AFTER_FONTS_SCRIPT_TYPE);
+ else if ((el.getAttribute("type") || "").trim().toLowerCase() === "module") {
+ el.setAttribute("type", AFTER_FONTS_MODULE_TYPE);
+ } else continue;
+ deferred = true;
+ }
+ if (
+ !deferred ||
+ !document.head ||
+ document.querySelector(`script[${AFTER_FONTS_FALLBACK_ATTR}]`)
+ ) {
+ return;
+ }
+ const fallback = document.createElement("script");
+ fallback.setAttribute(AFTER_FONTS_FALLBACK_ATTR, "");
+ fallback.textContent = afterFontsFallback();
+ document.head.insertBefore(fallback, document.head.firstChild);
+}
+
+export function typeAfterFonts(el: Element): string | null {
+ const type = el.getAttribute("type");
+ if (type === AFTER_FONTS_SCRIPT_TYPE) return null;
+ return type === AFTER_FONTS_MODULE_TYPE ? "module" : type;
+}
+
/** Undefined for a type the browser never applies as CSS; `media="all"` and an empty title count as none. */
export function cssStyleMergeKey(el: Element): string | undefined {
const rawType = el.getAttribute("type") ?? "";
diff --git a/packages/core/src/runtime/afterFonts.ts b/packages/core/src/runtime/afterFonts.ts
new file mode 100644
index 0000000000..a9af761b03
--- /dev/null
+++ b/packages/core/src/runtime/afterFonts.ts
@@ -0,0 +1,135 @@
+import { AFTER_FONTS_CLAIM, typeAfterFonts } from "../compiler/scriptRuns";
+import { postRuntimeMessage } from "./bridge";
+
+/** Past the 3 s a font-display:block face holds text back, far under the engine's 45 s player-ready wait. */
+export const FONT_WAIT_TIMEOUT_MS = 5000;
+
+(window as unknown as Record<string, unknown>)[AFTER_FONTS_CLAIM] = true;
+
+/** Resolves once the page's web fonts are ready or the timeout passes, reporting faces still loading. */
+export async function waitForFonts(): Promise<void> {
+ const fonts = document.fonts;
+ if (!fonts) return;
+ // Layout starts loading the faces laid-out text uses; with none loading, ready resolves at once.
+ void document.body?.offsetHeight;
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const timedOut = await Promise.race([
+ fonts.ready.then(() => false),
+ new Promise<boolean>((resolve) => (timer = setTimeout(resolve, FONT_WAIT_TIMEOUT_MS, true))),
+ ]);
+ clearTimeout(timer);
+ if (!timedOut) return;
+ const loadingFamilies = [
+ ...new Set(
+ Array.from(fonts)
+ .filter((face) => face.status === "loading")
+ .map((face) => face.family),
+ ),
+ ];
+ console.warn(
+ `[hyperframes] fonts still loading after ${FONT_WAIT_TIMEOUT_MS} ms, composition scripts run without them: ${loadingFamilies.join(", ")}`,
+ );
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: "runtime_font_wait_timeout",
+ details: { loadingFamilies, timeoutMs: FONT_WAIT_TIMEOUT_MS },
+ });
+}
+
+type HeldListener = {
+ target: EventTarget;
+ type: string;
+ listener: EventListenerOrEventListenerObject;
+};
+
+/** Queues DOMContentLoaded listeners, and load listeners once the page has loaded: both events have passed. */
+function holdPassedLoadEvents(target: Document | Window, held: HeldListener[]): () => void {
+ const own = Object.getOwnPropertyDescriptor(target, "addEventListener");
+ const add = target.addEventListener;
+ const hold = (
+ type: string,
+ listener: EventListenerOrEventListenerObject | null,
+ options?: boolean | AddEventListenerOptions,
+ ) => {
+ if (!listener) return;
+ const passed =
+ type === "DOMContentLoaded" ||
+ (type === "load" && target === window && document.readyState === "complete");
+ if (passed) held.push({ target, type, listener });
+ else add.call(target, type, listener, options);
+ };
+ target.addEventListener = hold;
+ return () => {
+ // A script that wrapped it meanwhile keeps its wrapper.
+ if (target.addEventListener !== hold) return;
+ if (own) Object.defineProperty(target, "addEventListener", own);
+ else delete (target as { addEventListener?: unknown }).addEventListener;
+ };
+}
+
+function runInPlace(el: Element): HTMLScriptElement | undefined {
+ if (!el.isConnected) return;
+ const script = document.createElement("script");
+ for (const { name, value } of Array.from(el.attributes)) script.setAttribute(name, value);
+ const type = typeAfterFonts(el);
+ if (type === null) script.removeAttribute("type");
+ else script.setAttribute("type", type);
+ // Not async: inserted src and module scripts then run in insertion order.
+ script.async = el.hasAttribute("async");
+ script.text = el.textContent ?? "";
+ el.replaceWith(script);
+ return script;
+}
+
+const loaded = (script: HTMLScriptElement) =>
+ new Promise((resolve) => {
+ script.addEventListener("load", resolve);
+ script.addEventListener("error", resolve);
+ });
+
+// An inline module fires no load event; a module queued after the others runs once they have.
+function afterQueuedModules(): Promise<unknown> {
+ const sentinel = document.createElement("script");
+ sentinel.type = "module";
+ sentinel.async = false;
+ sentinel.text = `document.dispatchEvent(new Event("hf-after-fonts-modules"))`;
+ const ran = new Promise((resolve) =>
+ document.addEventListener("hf-after-fonts-modules", resolve, { once: true }),
+ );
+ document.body.appendChild(sentinel);
+ return ran.then(() => sentinel.remove());
+}
+
+/**
+ * Once fonts are ready, runs each script in its own place in parser order (classic, then module and
+ * deferred), calls `afterRun`, then the load listeners the scripts added after those events passed.
+ */
+export async function runScriptsAfterFonts(
+ scripts: readonly Element[],
+ afterRun?: () => void,
+): Promise<void> {
+ await waitForFonts();
+ const isLate = (el: Element) =>
+ typeAfterFonts(el) === "module" || (el.hasAttribute("src") && el.hasAttribute("defer"));
+ const late = scripts.filter(isLate);
+ const held: HeldListener[] = [];
+ const release = [document, window].map((target) => holdPassedLoadEvents(target, held));
+ for (const el of scripts.filter((el) => !isLate(el))) {
+ const script = runInPlace(el);
+ if (script?.hasAttribute("src") && !script.async && !script.noModule) await loaded(script);
+ }
+ for (const el of late) runInPlace(el);
+ if (late.length > 0) await afterQueuedModules();
+ for (const undo of release) undo();
+ afterRun?.();
+ for (const { target, type, listener } of held) {
+ const event = new Event(type);
+ try {
+ if (typeof listener === "function") listener.call(target, event);
+ else listener.handleEvent(event);
+ } catch (error) {
+ reportError(error);
+ }
+ }
+}
diff --git a/packages/core/src/runtime/compositionLoader.test.ts b/packages/core/src/runtime/compositionLoader.test.ts
index 69f2654ccf..f8d901042e 100644
--- a/packages/core/src/runtime/compositionLoader.test.ts
+++ b/packages/core/src/runtime/compositionLoader.test.ts
@@ -20,6 +20,7 @@ describe("loadExternalCompositions", () => {
delete (window as Window & { __hyperframes?: unknown }).__hyperframes;
delete (window as Window & { __timelines?: unknown }).__timelines;
delete (window as WindowWithScopedVars).__hfVariablesByComp;
+ delete (document as { fonts?: unknown }).fonts;
vi.restoreAllMocks();
});
@@ -503,6 +504,28 @@ describe("loadExternalCompositions", () => {
expect(injectedScripts[0].textContent).toContain("console.log");
});
+ it("mounts the content, then runs its scripts only once web fonts are ready", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/comp.html");
+ document.body.appendChild(host);
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(`<html><body><p>Text</p><script>void 0</script></body></html>`, {
+ status: 200,
+ }),
+ );
+ let fontsLoaded = () => {};
+ const ready = new Promise<void>((resolve) => (fontsLoaded = resolve));
+ Object.defineProperty(document, "fonts", { configurable: true, value: { ready } });
+ const injectedScripts: HTMLScriptElement[] = [];
+
+ const loading = loadExternalCompositions({ ...defaultParams, injectedScripts });
+ await vi.waitFor(() => expect(host.textContent).toContain("Text"));
+ expect(injectedScripts).toHaveLength(0);
+ fontsLoaded();
+ await loading;
+ expect(injectedScripts).toHaveLength(1);
+ });
+
it("scopes injected styles and document selectors to the mounted composition root", async () => {
const otherRoot = document.createElement("div");
otherRoot.setAttribute("data-composition-id", "other");
diff --git a/packages/core/src/runtime/compositionLoader.ts b/packages/core/src/runtime/compositionLoader.ts
index 443199e715..28f99d3a04 100644
--- a/packages/core/src/runtime/compositionLoader.ts
+++ b/packages/core/src/runtime/compositionLoader.ts
@@ -9,6 +9,7 @@ import {
} from "../compiler/compositionScoping";
import { parseImportMap } from "../compiler/importMaps";
import { hasSameLink } from "../compiler/scriptRuns";
+import { waitForFonts } from "./afterFonts";
import { parseLayoutDimension } from "./compositionDimension";
import { markFlattenedInnerRoot } from "./flattenedRoot";
import {
@@ -554,6 +555,7 @@ async function mountCompositionContent(params: {
stashInstanceVariables(params, contentNode, runtimeScopeCompositionId);
}
+ if (scriptPayloads.length > 0) await waitForFonts();
for (const scriptPayload of scriptPayloads) {
const injectedScript = document.createElement("script");
if (scriptPayload.type) {
diff --git a/packages/core/src/runtime/entry.afterFonts.test.ts b/packages/core/src/runtime/entry.afterFonts.test.ts
new file mode 100644
index 0000000000..e017fcd331
--- /dev/null
+++ b/packages/core/src/runtime/entry.afterFonts.test.ts
@@ -0,0 +1,182 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ AFTER_FONTS_CLAIM,
+ AFTER_FONTS_SCRIPT_TYPE,
+ deferScriptsUntilFonts,
+} from "../compiler/scriptRuns";
+import { FONT_WAIT_TIMEOUT_MS } from "./afterFonts";
+
+type Face = { family: string; status: FontFaceLoadStatus };
+
+// jsdom runs scripts in its own global, so they report through the shared document.
+const logs = (entry: string) =>
+ `document.getElementById("log").textContent += ${JSON.stringify(`${entry} `)};`;
+
+function mountDeferredScripts(): void {
+ document.body.innerHTML =
+ `<output id="log"></output>` +
+ `<div data-composition-id="main" data-root="true" data-start="0" data-width="1920" data-height="1080">` +
+ `<div id="scene"><script type="${AFTER_FONTS_SCRIPT_TYPE}">${logs("a")}` +
+ `document.addEventListener("DOMContentLoaded", function () { ${logs("ready")} });` +
+ `if (document.currentScript.closest("#scene")) { ${logs("in-place")} }</script></div></div>` +
+ `<script type="${AFTER_FONTS_SCRIPT_TYPE}">${logs("b")}</script>`;
+}
+
+function serveFonts(ready: Promise<unknown>, faces: Face[]): void {
+ Object.defineProperty(document, "fonts", {
+ configurable: true,
+ value: { ready, [Symbol.iterator]: () => faces[Symbol.iterator]() },
+ });
+}
+
+async function parseThenLoad(): Promise<void> {
+ Object.defineProperty(document, "readyState", { configurable: true, get: () => "loading" });
+ vi.resetModules();
+ await import("./entry");
+ delete (document as { readyState?: unknown }).readyState;
+ document.dispatchEvent(new Event("DOMContentLoaded"));
+}
+
+const log = () => document.getElementById("log")!.textContent;
+const claims = (claimed: boolean) =>
+ claimed
+ ? ((window as unknown as Record<string, unknown>)[AFTER_FONTS_CLAIM] = true)
+ : delete (window as unknown as Record<string, unknown>)[AFTER_FONTS_CLAIM];
+
+// A page compiled elsewhere and imported, so jsdom runs none of its scripts; the test runs the fallback.
+function compilePage(): void {
+ const compiled = new DOMParser().parseFromString(
+ `<output id="log"></output><script>${logs("a")}</script><script>${logs("b")}</script>`,
+ "text/html",
+ );
+ deferScriptsUntilFonts(compiled);
+ const fallback = compiled.head.querySelector("script")!;
+ expect(fallback.textContent).toContain("no web-font gate");
+ document.body.replaceChildren(
+ ...Array.from(compiled.body.childNodes, (node) => document.importNode(node, true)),
+ );
+ new Function(fallback.textContent!)();
+}
+
+describe("runtime entry: composition scripts after web fonts", () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ window.__hfRuntimeTeardown?.();
+ document.body.innerHTML = "";
+ window.__timelines = {};
+ claims(true);
+ delete window.__player;
+ delete (window as { __hyperframeRuntimeBootstrapped?: boolean })
+ .__hyperframeRuntimeBootstrapped;
+ delete (document as { fonts?: unknown }).fonts;
+ delete (document as { addEventListener?: unknown }).addEventListener;
+ });
+
+ it("runs deferred scripts once fonts are ready, in order and in place, then boots and fires their DOMContentLoaded", async () => {
+ let fontsLoaded = () => {};
+ serveFonts(new Promise<void>((resolve) => (fontsLoaded = resolve)), []);
+ mountDeferredScripts();
+
+ await parseThenLoad();
+ await Promise.resolve();
+ expect(log()).toBe("");
+ expect(window.__player).toBeUndefined();
+
+ fontsLoaded();
+ await vi.waitFor(() => expect(window.__player).toBeDefined());
+ expect(log()).toBe("a in-place b ready ");
+ expect(document.querySelectorAll(`script[type="${AFTER_FONTS_SCRIPT_TYPE}"]`)).toHaveLength(0);
+ });
+
+ it("keeps an addEventListener wrapper a deferred script installs while its load events are held", async () => {
+ serveFonts(Promise.resolve(), []);
+ document.body.innerHTML =
+ `<output id="log"></output>` +
+ `<script type="${AFTER_FONTS_SCRIPT_TYPE}">var add = document.addEventListener;` +
+ `document.addEventListener = function () { ${logs("wrapped")} return add.apply(this, arguments); };` +
+ `</script>`;
+
+ await parseThenLoad();
+ await vi.waitFor(() => expect(window.__player).toBeDefined());
+ const before = log();
+ document.addEventListener("hf-later", () => {});
+ expect(log()).toBe(`${before}wrapped `);
+ });
+
+ it("runs an inline script after an external one only once the external one has loaded", async () => {
+ serveFonts(Promise.resolve(), []);
+ // jsdom fetches no src: the test loads the library, once the runtime has put its script in place.
+ const library = new MutationObserver((records) => {
+ for (const node of records.flatMap((record) => [...record.addedNodes])) {
+ if (!(node instanceof HTMLScriptElement) || !node.src || node.type) continue;
+ document.body.dataset.lib = "loaded";
+ node.dispatchEvent(new Event("load"));
+ }
+ });
+ library.observe(document.body, { childList: true });
+ document.body.innerHTML =
+ `<output id="log"></output>` +
+ `<script type="${AFTER_FONTS_SCRIPT_TYPE}" src="https://cdn.example/lib.js"></script>` +
+ `<script type="${AFTER_FONTS_SCRIPT_TYPE}">` +
+ `document.getElementById("log").textContent += "lib:" + document.body.dataset.lib;</script>`;
+
+ await parseThenLoad();
+ await vi.waitFor(() => expect(window.__player).toBeDefined());
+ library.disconnect();
+ delete document.body.dataset.lib;
+ expect(log()).toBe("lib:loaded");
+ });
+
+ it("runs the scripts at the font timeout and reports the families still loading", async () => {
+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+ const posted = vi.spyOn(window.parent, "postMessage").mockImplementation(() => {});
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ serveFonts(new Promise(() => {}), [
+ { family: "Hanken Grotesk", status: "loading" },
+ { family: "Inter", status: "loaded" },
+ ]);
+ mountDeferredScripts();
+
+ await parseThenLoad();
+ await vi.advanceTimersByTimeAsync(FONT_WAIT_TIMEOUT_MS - 1);
+ expect(log()).toBe("");
+
+ await vi.advanceTimersByTimeAsync(1);
+ expect(log()).toMatch(/^a .*b /);
+ expect(posted).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: "diagnostic",
+ code: "runtime_font_wait_timeout",
+ details: { loadingFamilies: ["Hanken Grotesk"], timeoutMs: FONT_WAIT_TIMEOUT_MS },
+ }),
+ "*",
+ );
+ });
+
+ it("runs deferred scripts once and in order through the page's fallback when the runtime predates the gate", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ claims(false);
+ compilePage();
+
+ document.dispatchEvent(new Event("DOMContentLoaded"));
+ document.dispatchEvent(new Event("DOMContentLoaded"));
+ expect(log()).toBe("a b ");
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining("no web-font gate"));
+ });
+
+ it("leaves the scripts to a runtime with the gate, which runs them once after fonts", async () => {
+ let fontsLoaded = () => {};
+ serveFonts(new Promise<void>((resolve) => (fontsLoaded = resolve)), []);
+ claims(false);
+ compilePage();
+
+ await parseThenLoad();
+ await Promise.resolve();
+ expect(log()).toBe("");
+ fontsLoaded();
+ await vi.waitFor(() => expect(window.__player).toBeDefined());
+ document.dispatchEvent(new Event("DOMContentLoaded"));
+ expect(log()).toBe("a b ");
+ });
+});
diff --git a/packages/core/src/runtime/entry.ts b/packages/core/src/runtime/entry.ts
index e445e1c89d..88fa54ec26 100644
--- a/packages/core/src/runtime/entry.ts
+++ b/packages/core/src/runtime/entry.ts
@@ -7,6 +7,8 @@ import { pretext } from "../text/pretext";
import { assetUrl } from "./assetUrl";
import { getVariables } from "./getVariables";
import { clearRuntimeData, registerRuntimeDataHandler, setRuntimeData } from "./runtimeData";
+import { runScriptsAfterFonts } from "./afterFonts";
+import { AFTER_FONTS_SCRIPTS } from "../compiler/scriptRuns";
type HyperframeWindow = Window & {
__hyperframeRuntimeBootstrapped?: boolean;
@@ -56,8 +58,15 @@ function bootstrapHyperframeRuntime(): void {
initSandboxRuntimeModular();
}
+// Compiled composition scripts wait for web fonts, so what they measure matches every run.
+function startAfterCompositionScripts(): void {
+ const deferred = Array.from(document.querySelectorAll(AFTER_FONTS_SCRIPTS));
+ if (deferred.length === 0) bootstrapHyperframeRuntime();
+ else void runScriptsAfterFonts(deferred, bootstrapHyperframeRuntime);
+}
+
if (document.readyState === "loading") {
- document.addEventListener("DOMContentLoaded", bootstrapHyperframeRuntime, { once: true });
+ document.addEventListener("DOMContentLoaded", startAfterCompositionScripts, { once: true });
} else {
- bootstrapHyperframeRuntime();
+ startAfterCompositionScripts();
}
diff --git a/packages/core/src/runtime/init.swapScenes.test.ts b/packages/core/src/runtime/init.swapScenes.test.ts
index 5935a3c6e0..dfb37af6dd 100644
--- a/packages/core/src/runtime/init.swapScenes.test.ts
+++ b/packages/core/src/runtime/init.swapScenes.test.ts
@@ -7,6 +7,7 @@ import { resetRuntimeDataForTests } from "./runtimeData";
import { WebAudioTransport } from "./webAudioTransport";
import { probeAndCacheElementVolume } from "./mediaVolumeEnvelope.js";
import { wrapScopedCompositionScript } from "../compiler/compositionScoping";
+import { AFTER_FONTS_SCRIPT_TYPE } from "../compiler/scriptRuns";
vi.mock("./mediaVolumeEnvelope.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("./mediaVolumeEnvelope.js")>();
@@ -105,7 +106,7 @@ function preview(scenes: Scene[], shared = "s1", sharedMarkup = "") {
scenes
.map(
(s) =>
- `<script data-hf-scene="${s.id}">${sceneScript(s.id, s.label)}${s.script ?? ""}</script>`,
+ `<script type="${AFTER_FONTS_SCRIPT_TYPE}" data-hf-scene="${s.id}">${sceneScript(s.id, s.label)}${s.script ?? ""}</script>`,
)
.join("");
return {
@@ -139,14 +140,15 @@ function mount(scenes: Scene[], root: Tl, editHead = (head: string) => head) {
document.body.innerHTML = body;
window.__timelines = { main: root };
for (const s of scenes) window.__timelines[s.id] = made[s.label];
- // Run each scene script the swap appends when it is appended, as a browser would.
- const append = document.body.appendChild.bind(document.body);
- document.body.appendChild = <T extends Node>(node: T): T => {
- append(node);
- if (node instanceof HTMLScriptElement && node.hasAttribute("data-hf-scene"))
- new Function(node.textContent ?? "")();
- return node;
- };
+ // Run each scene script the swap puts in place, as a browser runs a created script.
+ const replaceWith = Element.prototype.replaceWith;
+ vi.spyOn(Element.prototype, "replaceWith").mockImplementation(function (this: Element, ...nodes) {
+ replaceWith.apply(this, nodes);
+ for (const node of nodes) {
+ if (node instanceof HTMLScriptElement && node.hasAttribute("data-hf-scene"))
+ new Function(node.textContent ?? "")();
+ }
+ });
}
function boot(scenes: Scene[], root: Tl, editHead = (head: string) => head) {
@@ -205,7 +207,6 @@ describe("__hfSwapScenes", () => {
(window as unknown as { __made: typeof made }).__made = made;
});
afterEach(() => {
- Reflect.deleteProperty(document.body, "appendChild");
Reflect.deleteProperty(window, "gsap");
window.__hfRuntimeTeardown?.();
document.head.innerHTML = "";
@@ -243,6 +244,26 @@ describe("__hfSwapScenes", () => {
expect(JSON.parse(meta).scenes.a).toBe("ha2");
});
+ it("runs the swapped scene's script only once web fonts are ready", async () => {
+ const { root } = trackingRoot();
+ boot([A1, B], root);
+ await tick();
+ let fontsLoaded = () => {};
+ const ready = new Promise<void>((resolve) => (fontsLoaded = resolve));
+ Object.defineProperty(document, "fonts", { configurable: true, value: { ready } });
+ try {
+ const swap = window.__hfSwapScenes!(preview([A2, B]).html);
+ for (let i = 0; i < 5; i++) await tick();
+ expect(window.__timelines.a).not.toBe(made.a2);
+
+ fontsLoaded();
+ await swap;
+ expect(window.__timelines.a).toBe(made.a2);
+ } finally {
+ Reflect.deleteProperty(document, "fonts");
+ }
+ });
+
it("rejects without touching the film when anything outside the scenes changed", async () => {
const { root } = trackingRoot();
boot([A1, B], root);
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 20b7a3e9f0..4b3716c33d 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -65,6 +65,7 @@ import {
import { createRuntimeStartTimeResolver } from "./startResolver";
import { createClipTree } from "./clipTree";
import { loadExternalCompositions, loadInlineTemplateCompositions } from "./compositionLoader";
+import { runScriptsAfterFonts } from "./afterFonts";
import {
applyCaptionOverrides,
applyFetchedCaptionOverrides,
@@ -3600,24 +3601,22 @@ export function initSandboxRuntimeModular(): void {
.forEach((el, i) => el.replaceWith(document.importNode(newStyles[i]!, true)));
for (const el of oldParts) if (el !== oldHost) el.remove();
const host = document.importNode(newHost, true);
+ // Text only: a live script that ran no longer carries the deferred type its new copy has.
const scripts = (parts: Element[]) =>
- parts.flatMap((el) => (el.tagName === "SCRIPT" ? el.outerHTML : [])).join("");
+ JSON.stringify(parts.flatMap((el) => (el.tagName === "SCRIPT" ? el.textContent : [])));
keepUnchangedMedia(oldHost, host, scripts(oldParts) === scripts(newParts));
oldHost.replaceWith(host);
swappedHosts.push(host);
if (host.querySelector(".caption-group")) captionHosts.push(host);
}
// Run once every host is replaced, so no new script binds to a scene still to be swapped.
- for (const { newParts } of swaps) {
- for (const el of newParts) {
- if (el.tagName !== "SCRIPT") continue;
- // An imported <script> never runs; a created one does.
- const script = document.createElement("script");
- for (const attr of Array.from(el.attributes)) script.setAttribute(attr.name, attr.value);
- script.textContent = el.textContent;
- document.body.appendChild(script);
- }
- }
+ const sceneScripts = swaps.flatMap(({ newParts }) =>
+ newParts
+ .filter((el) => el.tagName === "SCRIPT")
+ .map((el) => document.body.appendChild(document.importNode(el, true))),
+ );
+ await runScriptsAfterFonts(sceneScripts);
+ if (state.tornDown) throw new Error("the preview was torn down during the swap");
document
.querySelector(`meta[name="${SCENE_PARTS_META}"]`)
?.setAttribute("content", JSON.stringify(nextParts));
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index ca5a315b28..d331c333fc 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -1552,7 +1552,7 @@ class HyperframesPlayer extends HTMLElement {
private _onIframeLoad() {
// In video mode the iframe only ever loads about:blank; its load must not reset the video.
if (!this._connected || this._videoSource) return;
- // The runtime posts its timeline at DOMContentLoaded, before `load`, and every
+ // The runtime posts its timeline once its scripts ran, before or after `load`, and every
// host-initiated navigation clears `_ready` first. So a ready player already holds this
// document's handshake (an opaque origin reads as null); a paused runtime never posts it again.
const doc = this._getSameOriginIframeDocument();
@@ -1563,8 +1563,8 @@ class HyperframesPlayer extends HTMLElement {
}
this._ready = false;
- // The runtime installs its bridge at DOMContentLoaded, posts `ready`, and only then does the
- // iframe's load event fire. Do not erase that authoritative handshake here: doing so strands
+ // The runtime installs its bridge once its scripts ran and posts `ready`, which can come before
+ // the iframe's load event. Do not erase that authoritative handshake here: doing so strands
// retained data set after load until a second `ready` that never comes. Source setters and
// sandbox-policy reloads already clear bridge readiness before starting a navigation.
this._invalidateAssetsWait();
diff --git a/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts b/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts
index c8be300d6d..8cfbdc634b 100644
--- a/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts
+++ b/packages/producer/src/services/htmlCompiler.moduleScripts.test.ts
@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { parseHTML } from "linkedom";
import { afterEach, describe, expect, it } from "vitest";
+import { AFTER_FONTS_SCRIPT_TYPE } from "@hyperframes/core/compiler";
import { compileForRender } from "./htmlCompiler.js";
const tempDirs: string[] = [];
@@ -46,8 +47,13 @@ describe("compileForRender mounted module scripts", () => {
});
const { document } = parseHTML(html);
const importMap = document.querySelector('script[type="importmap"]');
- const modules = [...document.querySelectorAll('script[type="module"]')];
- const classic = [...document.querySelectorAll("script:not([type])")].map((s) => s.textContent);
+ // Deferred until fonts: the runtime runs each as the type its marker names.
+ const modules = [
+ ...document.querySelectorAll(`script[type="${AFTER_FONTS_SCRIPT_TYPE}+module"]`),
+ ];
+ const classic = [...document.querySelectorAll(`script[type="${AFTER_FONTS_SCRIPT_TYPE}"]`)].map(
+ (s) => s.textContent,
+ );
expect(JSON.parse(importMap?.textContent || "null")).toEqual({
imports: { three: "./compositions/blk/assets/three.js" },
diff --git a/packages/producer/src/services/htmlCompiler.scriptOrder.test.ts b/packages/producer/src/services/htmlCompiler.scriptOrder.test.ts
index 9d9a403e9c..9661ad0ea2 100644
--- a/packages/producer/src/services/htmlCompiler.scriptOrder.test.ts
+++ b/packages/producer/src/services/htmlCompiler.scriptOrder.test.ts
@@ -3,6 +3,8 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
+import { parseHTML } from "linkedom";
+import { AFTER_FONTS_SCRIPT_TYPE } from "@hyperframes/core/compiler";
import { compileForRender } from "./htmlCompiler.js";
const tempDirs: string[] = [];
@@ -99,4 +101,43 @@ describe("compileForRender script order", () => {
expect(lib).toBeGreaterThan(-1);
expect(lib).toBeLessThan(before);
});
+
+ it("defers every body script it emits until fonts, the position edit script and CDN libraries too", async () => {
+ vi.stubGlobal("fetch", async () => new Response("window.CDN_LIB = 1;"));
+ const dir = project({
+ "index.html": `<!doctype html>
+<html><body>
+ <div data-composition-id="root" data-width="320" data-height="180">
+ <div id="block" data-composition-id="block" data-composition-src="compositions/block/block.html" data-width="320" data-height="180"></div>
+ <div id="moved" data-hf-studio-path-offset="true"></div>
+ </div>
+ <script>window.ROOT_SCRIPT = 1;</script>
+ <script src="assets/needs-before.js"></script>
+</body></html>`,
+ "assets/needs-before.js": "void 0;",
+ "compositions/block/block.html": `<!doctype html>
+<html><body>
+ <div data-composition-id="block" data-width="320" data-height="180"></div>
+ <script src="https://cdn.example/lib.js"></script>
+ <script>window.BLOCK_SCRIPT = 1;</script>
+</body></html>`,
+ });
+ const { html } = await compileForRender(dir, join(dir, "index.html"), join(dir, ".downloads"), {
+ allowSystemFontCapture: false,
+ });
+ const { document } = parseHTML(html);
+ const body = [...document.querySelectorAll("body script")];
+ const deferred = [...document.querySelectorAll(`script[type="${AFTER_FONTS_SCRIPT_TYPE}"]`)];
+ expect(deferred).toEqual(body);
+ const text = deferred.map((el) => el.getAttribute("src") ?? el.textContent ?? "");
+ for (const mark of [
+ "ROOT_SCRIPT",
+ "needs-before.js",
+ "CDN_LIB",
+ "BLOCK_SCRIPT",
+ "data-hf-studio-path-offset",
+ ]) {
+ expect(text.some((t) => t.includes(mark))).toBe(true);
+ }
+ });
});
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 1b0913e63f..810869803f 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -43,6 +43,7 @@ import {
inlineSubCompositions as inlineSubCompositionsShared,
ensureExternalLinkTag,
ensureExternalScriptTag,
+ deferScriptsUntilFonts,
emitMountedModuleScripts,
prepareFlattenedInnerRoot,
emitRootCompositionVariableStyles,
@@ -127,6 +128,12 @@ function parseSubCompHtmlForValidity(html: string): ParsableDocumentLike {
return parseHTML(html).document as unknown as ParsableDocumentLike;
}
+function deferBodyScriptsUntilFonts(html: string): string {
+ const { document } = parseHTML(html);
+ deferScriptsUntilFonts(document as unknown as Document);
+ return document.toString();
+}
+
export function injectSdkPositionEditsRenderScript(html: string): string {
if (!html.includes("data-hf-edit-base-x") && !html.includes("data-hf-edit-base-y")) {
return html;
@@ -2036,7 +2043,9 @@ export async function compileForRender(
`<script>${createStudioPositionSeekReapplyScript()}</script>`,
) ?? assembledHtml)
: assembledHtml;
- const htmlWithSdkPositionScript = injectSdkPositionEditsRenderScript(htmlWithPositionScript);
+ const htmlWithDeferredScripts = deferBodyScriptsUntilFonts(
+ injectSdkPositionEditsRenderScript(htmlWithPositionScript),
+ );
// Download remote <video> and <audio> sources to compiledDir and rewrite the
// src attributes so the renderer reads from localhost. Remote S3 URLs cause
@@ -2044,7 +2053,7 @@ export async function compileForRender(
// over the network; any that don't reach readyState >= 2 in time render as
// blank black frames. Localising them eliminates the race.
const { html: htmlWithLocalMedia, remoteMediaAssets } = await localizeRemoteMediaSources(
- htmlWithSdkPositionScript,
+ htmlWithDeferredScripts,
downloadDir,
);
diff --git a/packages/producer/stubs/hf-early-stub.ts b/packages/producer/stubs/hf-early-stub.ts
index dac4cd49b5..cb844f336a 100644
--- a/packages/producer/stubs/hf-early-stub.ts
+++ b/packages/producer/stubs/hf-early-stub.ts
@@ -451,8 +451,7 @@ if (typeof window !== "undefined") {
// Expose a synchronous flush so headless renderers can drain the queue
// instantly instead of waiting for rAF-based batch ticks. Also force-
// publishes the "timelines built" signal immediately (normally deferred
- // via setTimeout(0)) — the caller guarantees page scripts have finished
- // loading, so no more operations can arrive after the flush.
+ // via setTimeout(0)). Scripts that wait for fonts queue later; duration() drains them.
(window as Record<string, unknown>).__hfFlushSync = () => {
flushPendingOperations();
if (pendingOperations.length === 0 && window.__hfTimelinesBuilding) {
diff --git a/packages/studio-server/src/helpers/subComposition.test.ts b/packages/studio-server/src/helpers/subComposition.test.ts
index c6d18c5863..36e5de024f 100644
--- a/packages/studio-server/src/helpers/subComposition.test.ts
+++ b/packages/studio-server/src/helpers/subComposition.test.ts
@@ -4,6 +4,8 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, onTestFinished } from "vitest";
import { gsapCdnDist } from "@hyperframes/core/gsap-cdn";
+import { parseHTML } from "linkedom";
+import { AFTER_FONTS_SCRIPT_TYPE } from "@hyperframes/core/compiler";
import { buildSubCompositionHtml, hasBaseElement } from "./subComposition";
function makeTempProject(files: Record<string, string>): string {
@@ -121,6 +123,33 @@ describe("buildSubCompositionHtml", () => {
expect(html!.slice(body)).not.toContain("<html");
});
+ it.each([
+ ["a template", (body: string) => `<template>${body}</template>`],
+ ["a full document", (body: string) => `<!doctype html><html><body>${body}</body></html>`],
+ ["a fragment", (body: string) => body],
+ ])("defers the scripts of %s composition until fonts, but not the preview's own", (_, wrap) => {
+ const dir = makeTempProject({
+ "index.html": `<!doctype html><html><head></head><body></body></html>`,
+ "compositions/card.html": wrap(
+ `<div data-composition-id="card" data-width="400" data-height="300"><p>Hi</p>` +
+ `<script>window.CARD = 1;</script><script type="module">window.CARD_MODULE = 1;</script></div>`,
+ ),
+ });
+
+ const html = buildSubCompositionHtml(dir, "compositions/card.html", "/api/runtime.js")!;
+ const types = [...parseHTML(html).document.querySelectorAll("script")].map((el) => [
+ el.textContent?.trim() || el.getAttribute("src"),
+ el.getAttribute("type"),
+ ]);
+ expect(types).toEqual([
+ ["/api/runtime.js", null],
+ [`${gsapCdnDist()}gsap.min.js`, null],
+ ["window.__timelines=window.__timelines||{};", null],
+ ["window.CARD = 1;", AFTER_FONTS_SCRIPT_TYPE],
+ ["window.CARD_MODULE = 1;", `${AFTER_FONTS_SCRIPT_TYPE}+module`],
+ ]);
+ });
+
it("handles raw fragment compositions (no template, no full document)", () => {
const dir = makeTempProject({
"index.html": `<!doctype html>
diff --git a/packages/studio-server/src/helpers/subComposition.ts b/packages/studio-server/src/helpers/subComposition.ts
index 72c6d17839..6b585bf09c 100644
--- a/packages/studio-server/src/helpers/subComposition.ts
+++ b/packages/studio-server/src/helpers/subComposition.ts
@@ -6,7 +6,7 @@ import {
rewriteCssAssetUrls,
rewriteInlineStyleAssetUrls,
} from "@hyperframes/core";
-import { stripEmbeddedRuntimeScripts } from "@hyperframes/core/compiler";
+import { deferScriptsUntilFonts, stripEmbeddedRuntimeScripts } from "@hyperframes/core/compiler";
import { isFullHtmlDocument } from "@hyperframes/core/compiler/html-document";
import { gsapCdnDist } from "@hyperframes/core/gsap-cdn";
@@ -310,6 +310,11 @@ export function buildSubCompositionHtml(
// double-loaded AND the baked inline copy can fail to parse inline (the
// "Unexpected token '<'" SyntaxError seen on comps with a baked runtime).
rewrittenContent = stripEmbeddedRuntimeScripts(rewrittenContent);
+ const { document: scriptsDoc } = parseHTML(
+ `<!DOCTYPE html><html><head></head><body>${rewrittenContent}</body></html>`,
+ );
+ deferScriptsUntilFonts(scriptsDoc as unknown as Document);
+ rewrittenContent = scriptsDoc.body.innerHTML;
// The comp's root carries data-composition-id but (unlike inlined sub-comps,
// which inlineSubCompositions tags) no data-composition-file. Without it the
diff --git a/packages/studio-server/src/routes/preview.test.ts b/packages/studio-server/src/routes/preview.test.ts
index 8b5f779dd9..414e89c3c5 100644
--- a/packages/studio-server/src/routes/preview.test.ts
+++ b/packages/studio-server/src/routes/preview.test.ts
@@ -1,6 +1,7 @@
// fallow-ignore-file code-duplication
import { afterEach, describe, expect, it, vi } from "vitest";
import { Hono } from "hono";
+import { parseHTML } from "linkedom";
import {
closeSync,
ftruncateSync,
@@ -21,6 +22,7 @@ import { tmpdir } from "node:os";
import { join, parse } from "node:path";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { STUDIO_PREVIEW_MARK_META } from "@hyperframes/core/studio-preview-mark";
+import { AFTER_FONTS_SCRIPT_TYPE } from "@hyperframes/core/compiler";
import { PREVIEW_BUNDLE_OPTIONS, PREVIEW_CAPTURE_PARAM, registerPreviewRoutes } from "./preview";
import { registerFileRoutes } from "./files";
import { createPreviewDocumentStore } from "../helpers/previewDocumentStore";
@@ -194,7 +196,11 @@ describe("registerPreviewRoutes", () => {
const html = await response.text();
expect(response.status).toBe(200);
- expect(html).toContain("__hfStudioMotionApply");
+ const motionScript = [...parseHTML(html).document.querySelectorAll("script")].find((el) =>
+ el.textContent?.includes("__hfStudioMotionApply"),
+ );
+ // Deferred with the composition scripts, so it still runs after them.
+ expect(motionScript?.getAttribute("type")).toBe(AFTER_FONTS_SCRIPT_TYPE);
expect(html).toContain("studio-motion");
expect(html).toContain("[email protected]/dist/gsap.min.js");
});
@@ -249,6 +255,41 @@ describe("registerPreviewRoutes", () => {
expect(html).toContain("gsap@3/dist/MotionPathPlugin.min.js");
// Plugin must load AFTER the core gsap script so it can register onto it.
expect(html.indexOf("gsap.min.js")).toBeLessThan(html.indexOf("MotionPathPlugin.min.js"));
+ const plugin = parseHTML(html).document.querySelector('script[src*="MotionPathPlugin"]');
+ expect(plugin?.hasAttribute("type")).toBe(false);
+ });
+
+ it("defers the MotionPathPlugin with a body gsap script, so it still runs right after gsap", async () => {
+ const projectDir = createProjectDir();
+ writeFileSync(
+ join(projectDir, "index.html"),
+ `<!doctype html><html><head></head><body><div id="card" class="clip"></div>
+ <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+ <script>
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#card", { motionPath: { path: [{ x: 0, y: 0 }, { x: 100, y: 50 }] }, duration: 1 }, 0);
+ window.__timelines = { index: tl };
+ </script>
+ </body></html>`,
+ );
+ const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
+ const app = new Hono();
+ registerPreviewRoutes(
+ app,
+ createAdapter(projectDir, {
+ bundle: (dir, options) =>
+ bundleToSingleHtml(dir, { ...PREVIEW_BUNDLE_OPTIONS, ...options }),
+ }),
+ );
+
+ const html = await (await app.request("http://localhost/projects/demo/preview")).text();
+
+ const scripts = [...parseHTML(html).document.querySelectorAll("script[src]")];
+ const gsapAt = scripts.findIndex((el) => el.getAttribute("src")?.endsWith("/gsap.min.js"));
+ expect(scripts[gsapAt]?.getAttribute("type")).toBe(AFTER_FONTS_SCRIPT_TYPE);
+ const plugin = scripts[gsapAt + 1];
+ expect(plugin?.getAttribute("src")).toContain("gsap@3/dist/MotionPathPlugin.min.js");
+ expect(plugin?.getAttribute("type")).toBe(AFTER_FONTS_SCRIPT_TYPE);
});
it("does NOT inject MotionPathPlugin when the composition has no motionPath", async () => {
diff --git a/packages/studio-server/src/routes/preview.ts b/packages/studio-server/src/routes/preview.ts
index 482b4d910c..fd933e9ebc 100644
--- a/packages/studio-server/src/routes/preview.ts
+++ b/packages/studio-server/src/routes/preview.ts
@@ -4,8 +4,8 @@ import { Readable } from "node:stream";
import { join, resolve } from "node:path";
import { createHash } from "node:crypto";
import {
+ AFTER_FONTS_SCRIPT_TYPE,
addScenePartsManifest,
- injectScriptsIntoHtml,
insertBeforeCloseTag,
stripEmbeddedRuntimeScripts,
type BundleOptions,
@@ -158,7 +158,8 @@ function injectMotionPathPluginIfNeeded(html: string): string {
const match = html.match(gsapScript);
if (match) {
const version = match[0].match(/gsap@([\d.]+)/)?.[1];
- const pluginTag = `<script src="${motionPathPluginUrl(version)}"></script>`;
+ const gsapTagType = match[0].match(/\stype=("[^"]*"|'[^']*')/i)?.[0] ?? "";
+ const pluginTag = `<script${gsapTagType} src="${motionPathPluginUrl(version)}"></script>`;
const end = html.indexOf(match[0]) + match[0].length;
return html.slice(0, end) + "\n" + pluginTag + html.slice(end);
}
@@ -186,12 +187,9 @@ function injectStudioMotionScript(
activeCompositionPath,
});
if (!script) return html;
- return injectScriptsIntoHtml(
- injectStudioMotionDependencies(html, manifestContent),
- [],
- [script],
- false,
- );
+ const withDependencies = injectStudioMotionDependencies(html, manifestContent);
+ const tag = `<script type="${AFTER_FONTS_SCRIPT_TYPE}">${script.replace(/<\/script/gi, "<\\/script")}</script>`;
+ return insertBeforeCloseTag(withDependencies, "body", tag) ?? `${withDependencies}${tag}`;
}
const GSAP_FALLBACK_ATTR = "data-hf-gsap-fallback";
diff --git a/packages/studio/src/utils/gsapSoftReload.test.ts b/packages/studio/src/utils/gsapSoftReload.test.ts
index d6e69d9eb8..6284196a12 100644
--- a/packages/studio/src/utils/gsapSoftReload.test.ts
+++ b/packages/studio/src/utils/gsapSoftReload.test.ts
@@ -384,6 +384,56 @@ describe("ensureMotionPathPluginLoaded", () => {
expect(appendedScripts).toHaveLength(0);
});
+ describe("when gsap is not there yet at load", () => {
+ const post = (source: unknown, type = "ready") => {
+ const event = new MessageEvent("message", { data: { source: "hf-preview", type } });
+ Object.defineProperty(event, "source", { value: source });
+ window.dispatchEvent(event);
+ };
+
+ it("loads the plugin once that iframe's runtime is ready", () => {
+ const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe({ gsap: undefined });
+ ensureMotionPathPluginLoaded(iframe);
+ contentWindow.gsap = { registerPlugin: vi.fn() };
+ post({});
+ post(contentWindow, "timeline");
+ expect(appendedScripts).toHaveLength(0);
+ post(contentWindow);
+ post(contentWindow);
+ expect(appendedScripts).toHaveLength(1);
+ expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+ });
+
+ it("stops listening at the first ready, even when it brought no gsap", () => {
+ const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe({ gsap: undefined });
+ ensureMotionPathPluginLoaded(iframe);
+ post(contentWindow);
+ contentWindow.gsap = { registerPlugin: vi.fn() };
+ post(contentWindow);
+ expect(appendedScripts).toHaveLength(0);
+ });
+
+ it("drops a preview that never became ready once a newer one loads", () => {
+ const stale = buildBootstrapIframe({ gsap: undefined });
+ ensureMotionPathPluginLoaded(stale.iframe);
+ ensureMotionPathPluginLoaded(buildBootstrapIframe({ gsap: undefined }).iframe);
+ stale.contentWindow.gsap = { registerPlugin: vi.fn() };
+ post(stale.contentWindow);
+ expect(stale.appendedScripts).toHaveLength(0);
+ });
+
+ it("does not wait when the runtime already booted, since its ready has gone out", () => {
+ const { iframe, contentWindow, appendedScripts } = buildBootstrapIframe({
+ gsap: undefined,
+ __playerReady: true,
+ });
+ ensureMotionPathPluginLoaded(iframe);
+ contentWindow.gsap = { registerPlugin: vi.fn() };
+ post(contentWindow);
+ expect(appendedScripts).toHaveLength(0);
+ });
+ });
+
it("loads the plugin at the composition's own gsap version", () => {
const { iframe, appendedScripts } = buildBootstrapIframe({
gsap: { version: "3.14.2", registerPlugin: vi.fn() },
diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.ts
index 6ea507be38..c5855b731d 100644
--- a/packages/studio/src/utils/gsapSoftReload.ts
+++ b/packages/studio/src/utils/gsapSoftReload.ts
@@ -14,6 +14,7 @@ type IframeWindow = Window & {
// reloads (each needing the plugin) don't queue duplicate plugin scripts that
// re-flash the iframe. Cleared once the plugin loads or errors.
__hfMotionPathPluginLoading?: boolean;
+ __playerReady?: boolean;
gsap?: {
version?: string;
timeline?: (...args: unknown[]) => unknown;
@@ -37,10 +38,15 @@ type IframeWindow = Window & {
* studio edits.
*
* Idempotent (no-ops once the plugin is present or already loading) and
- * defensive: no-ops without gsap/registerPlugin and tolerates a CDN failure
+ * defensive: without gsap it waits for the runtime's ready, and it tolerates a CDN failure
* (the soft-reload async fallback in applySoftReload still covers that case).
*/
+// At most one preview waits for its runtime; a newer load replaces it, so a frame that never boots is not kept alive.
+let pendingReadyRetry: ((event: MessageEvent) => void) | null = null;
+
export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null): void {
+ if (pendingReadyRetry) window.removeEventListener("message", pendingReadyRetry);
+ pendingReadyRetry = null;
if (!iframe?.contentWindow || !iframe.contentDocument) return;
const win = iframe.contentWindow as IframeWindow;
const doc = iframe.contentDocument;
@@ -53,7 +59,21 @@ export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null):
} catch {}
return;
}
- if (!win.gsap?.registerPlugin) return;
+ // A body gsap runs after web fonts, which can be after the iframe's load: retry once the runtime is ready.
+ // A booted runtime (`__playerReady`, set in the same task it posts ready) has nothing left to wait for.
+ if (!win.gsap?.registerPlugin) {
+ if (win.__playerReady) return;
+ const retry = (event: MessageEvent) => {
+ const data = event.data as { source?: unknown; type?: unknown } | null;
+ if (event.source !== win || data?.source !== "hf-preview" || data.type !== "ready") return;
+ window.removeEventListener("message", retry);
+ pendingReadyRetry = null;
+ if (win.gsap?.registerPlugin) ensureMotionPathPluginLoaded(iframe);
+ };
+ pendingReadyRetry = retry;
+ window.addEventListener("message", retry);
+ return;
+ }
// A load is already in flight for this iframe — don't queue a second script.
if (win.__hfMotionPathPluginLoading) return;