Skip to content

Commit a7282dc

Browse files
fix(player): wait for a cross-origin composition's assets before playing (#4103)
* fix(player): wait for a cross-origin composition's assets before playing The player's readiness gate scans the iframe document, which is null when the composition is embedded from another origin, so it released playback at once and the first frames could play with images still loading. The runtime now runs the same readiness scan inside the iframe and posts assets-ready; its timeline message reports whether assets have settled so an older runtime, which never posts it, is not waited on. Also declares the animation-frame abort handler before a host whose requestAnimationFrame calls back synchronously can reach it. * fix(player): keep a ready cross-origin player ready across a late iframe load The iframe load event reset readiness for any document the player cannot read. The runtime posts its timeline before load and a paused runtime never posts it again, so a load arriving after the assets settled left the player not ready. A ready cross-origin player already holds this document's handshake, because every navigation clears readiness first. * fix(core): stop RuntimeReadinessWindow widening Window.__hf so the runtime typecheck passes * fix(core): a torn-down runtime no longer posts assets-ready
1 parent f92944a commit a7282dc

11 files changed

Lines changed: 242 additions & 24 deletions

‎packages/core/src/compositionReadiness.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,16 @@ describe("paintAndIdleReadinessInput", () => {
170170
expect(paintAndIdleReadinessInput(docWith(""), new AbortController().signal)).toBeNull();
171171
});
172172

173+
it("settles on a host whose requestAnimationFrame calls back synchronously", async () => {
174+
let ts = 0;
175+
const win = { requestAnimationFrame: (cb: (t: number) => void) => (cb((ts += 16)), 1) };
176+
const doc = { defaultView: win } as unknown as Document;
177+
178+
await expect(
179+
paintAndIdleReadinessInput(doc, new AbortController().signal),
180+
).resolves.toBeUndefined();
181+
});
182+
173183
it("waits for first paint, then two consecutive quiet frame gaps", async () => {
174184
const { fireFrame, isResolved } = startPaintAndIdleTracking();
175185

‎packages/core/src/compositionReadiness.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,8 @@ const RENDER_READY_POLL_MS = 50;
9696
// file lives under src/runtime — excluded from this package's own build
9797
// program (see tsconfig.json) — so it isn't visible here. Same flag, declared
9898
// locally instead of depending on a global merge from outside this file's scope.
99-
interface RuntimeReadinessWindow extends Window {
99+
// `__hf` is omitted from Window so the runtime program's strict shape can't conflict with `unknown`.
100+
interface RuntimeReadinessWindow extends Omit<Window, "__hf"> {
100101
__renderReady?: boolean;
101102
// __renderReady is only ever set by init.ts, which always sets __hf
102103
// first (`window.__hf = window.__hf || {}`) — a doc with no __hf can
@@ -160,15 +161,18 @@ function nextAnimationFrame(win: Window, signal: AbortSignal): Promise<number> {
160161
resolve(-1);
161162
return;
162163
}
163-
const id = win.requestAnimationFrame((ts) => {
164-
signal.removeEventListener("abort", onAbort);
165-
resolve(ts);
166-
});
164+
let id = 0;
167165
const onAbort = () => {
168166
win.cancelAnimationFrame?.(id);
169167
resolve(-1);
170168
};
171169
signal.addEventListener("abort", onAbort, { once: true });
170+
// A host whose rAF calls back synchronously reaches onAbort in the
171+
// callback, so it must already be declared above.
172+
id = win.requestAnimationFrame((ts) => {
173+
signal.removeEventListener("abort", onAbort);
174+
resolve(ts);
175+
});
172176
});
173177
}
174178

‎packages/core/src/runtime/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ postMessage:
3131
- actions: `play`, `pause`, `seek`, `set-muted`, `set-playback-rate`, `enable-pick-mode`, `disable-pick-mode`
3232
- runtime -> parent events:
3333
- `source: "hf-preview"`
34-
- `type: "state"` and `type: "timeline"`
34+
- `type: "state"` and `type: "timeline"`; `timeline` carries `assetsReady` (whether the
35+
composition's media, images and fonts have settled) and the runtime then posts
36+
`type: "assets-ready"` once, so a parent that cannot read the iframe can gate playback
3537
- `type: "ready"` — emitted once when `installRuntimeControlBridge` registers
3638
the control-message listener. The parent uses it to replay current playback
3739
state (`set-muted`, `set-volume`, `set-playback-rate`) so any control

‎packages/core/src/runtime/init.test.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3094,6 +3094,42 @@ describe("initSandboxRuntimeModular", () => {
30943094
expect(seekTimes[seekTimes.length - 1]).toBe(0);
30953095
});
30963096

3097+
it("posts assets-ready once, after the timeline, and only once a pending image settles", async () => {
3098+
const root = document.createElement("div");
3099+
root.setAttribute("data-composition-id", "root");
3100+
root.setAttribute("data-root", "true");
3101+
root.setAttribute("data-duration", "5");
3102+
root.setAttribute("data-width", "1920");
3103+
root.setAttribute("data-height", "1080");
3104+
const img = document.createElement("img");
3105+
const decodes: Array<() => void> = [];
3106+
Object.defineProperty(img, "complete", { value: false, configurable: true });
3107+
img.decode = () => new Promise<void>((resolve) => decodes.push(resolve));
3108+
root.appendChild(img);
3109+
document.body.appendChild(root);
3110+
window.__timelines = { root: createMockTimeline(5) };
3111+
const outbound: Array<Record<string, unknown>> = [];
3112+
vi.spyOn(window.parent, "postMessage").mockImplementation((message: unknown) => {
3113+
if (typeof message === "object" && message !== null) {
3114+
outbound.push(message as Record<string, unknown>);
3115+
}
3116+
});
3117+
3118+
initSandboxRuntimeModular();
3119+
const types = () => outbound.map((m) => m.type);
3120+
expect(outbound.find((m) => m.type === "timeline")?.assetsReady).toBe(false);
3121+
await new Promise((r) => setTimeout(r, 200));
3122+
expect(types()).not.toContain("assets-ready");
3123+
3124+
decodes.forEach((resolve) => resolve());
3125+
await vi.waitFor(() => expect(types()).toContain("assets-ready"));
3126+
window.__player!.renderSeek(1);
3127+
await new Promise((r) => setTimeout(r, 100));
3128+
expect(types().filter((t) => t === "assets-ready")).toHaveLength(1);
3129+
expect(decodes).toHaveLength(1);
3130+
expect(types().indexOf("assets-ready")).toBeGreaterThan(types().indexOf("timeline"));
3131+
});
3132+
30973133
it("accepts replayed transport controls when the bridge announces ready without duplicate listeners", () => {
30983134
const root = document.createElement("div");
30993135
root.setAttribute("data-composition-id", "root");

‎packages/core/src/runtime/init.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ import {
7777
import { installStudioCustomEase } from "./customEase";
7878
import { parseStrictFiniteTimingNumber, resolveMediaElementDurationSeconds } from "./playbackRate";
7979
import { MEDIA_START_BASIS_ATTR } from "../mediaTiming";
80+
import { settleCompositionReadiness } from "../compositionReadiness";
8081
import {
8182
clearRuntimeData,
8283
setRuntimeData,
@@ -2758,6 +2759,8 @@ export function initSandboxRuntimeModular(): void {
27582759
// transport tick. A plain count misses same-count swaps (one sub-comp unloads
27592760
// as another loads), so the signature keys on id+tag in document order.
27602761
let clipTreeSignature = "";
2762+
let assetsReadyStarted = false;
2763+
let assetsSettled = false;
27612764
let liveRootDurationOverrideSeconds = 0;
27622765
const computeClipTreeSignature = (): string => {
27632766
let sig = "";
@@ -2807,7 +2810,15 @@ export function initSandboxRuntimeModular(): void {
28072810
clipTreeSignature = currentSignature;
28082811
}
28092812

2810-
postRuntimeMessage(payload);
2813+
postRuntimeMessage({ ...payload, assetsReady: assetsSettled });
2814+
if (!assetsReadyStarted) {
2815+
assetsReadyStarted = true;
2816+
settleCompositionReadiness(document, ({ timedOut }) => {
2817+
if (state.tornDown) return;
2818+
assetsSettled = true;
2819+
postRuntimeMessage({ source: "hf-preview", type: "assets-ready", timedOut });
2820+
});
2821+
}
28112822
scheduleRootStageLayoutDiagnostics();
28122823
};
28132824

‎packages/core/src/runtime/transportPark.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ import { initSandboxRuntimeModular } from "./init";
33
import { STUDIO_MANUAL_EDIT_GESTURE_ATTR } from "../editing/draftMarkers";
44
import type { RuntimeTimelineLike } from "./types";
55

6+
// The readiness gate's 8s timeout is a one-shot timer these transport tests must not count.
7+
vi.mock("../compositionReadiness", () => ({ settleCompositionReadiness: vi.fn() }));
8+
69
/**
710
* The transport parks itself when the editor is paused and settled. Everything
811
* it used to discover by looking again on the next frame has to arrive by some

‎packages/core/src/runtime/types.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,10 @@ export type RuntimeTimelineMessage = RuntimeProtocolV1 & {
9696
scenes: RuntimeTimelineScene[];
9797
compositionWidth: number;
9898
compositionHeight: number;
99+
/** Present when this runtime will post `assets-ready`; the value is whether
100+
* the composition's assets have settled yet. Absent on older runtimes, whose
101+
* parents must not wait for a message that never comes. */
102+
assetsReady?: boolean;
99103
};
100104

101105
export type RuntimeDiagnosticMessage = {
@@ -171,6 +175,15 @@ export type RuntimeReadyMessage = {
171175
type: "ready";
172176
};
173177

178+
/** Posted once per runtime instance, after the first timeline message, when
179+
* the composition's media, images and fonts have settled (or timed out). It
180+
* lets a parent that cannot read the iframe (opaque origin) gate playback. */
181+
export type RuntimeAssetsReadyMessage = {
182+
source: "hf-preview";
183+
type: "assets-ready";
184+
timedOut: boolean;
185+
};
186+
174187
export type RuntimeDataErrorMessage = {
175188
source: "hf-preview";
176189
type: "runtime-data-error";
@@ -236,6 +249,7 @@ export type RuntimeOutboundMessage =
236249
| RuntimeStageSizeMessage
237250
| RuntimeMediaAutoplayBlockedMessage
238251
| RuntimeReadyMessage
252+
| RuntimeAssetsReadyMessage
239253
| RuntimeDataErrorMessage
240254
| RuntimeDataAppliedMessage
241255
| RuntimeAnalyticsMessage

‎packages/player/src/hyperframes-player.test.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2823,6 +2823,84 @@ describe("HyperframesPlayer asset-ready gate", () => {
28232823
return { doc, video };
28242824
}
28252825

2826+
const post = (player: PlayerInternal, data: Record<string, unknown>) =>
2827+
(player as unknown as { _onMessage(e: MessageEvent): void })._onMessage({
2828+
source: player.iframe.contentWindow,
2829+
data: { source: "hf-preview", ...data },
2830+
} as unknown as MessageEvent);
2831+
2832+
it("holds an opaque-origin composition until its runtime posts assets-ready", async () => {
2833+
const player = await createConnectedPlayer();
2834+
player._ready = false;
2835+
Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
2836+
post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
2837+
expect(player.assetsReady).toBe(false);
2838+
2839+
post(player, { type: "assets-ready", timedOut: false });
2840+
expect(player.assetsReady).toBe(true);
2841+
2842+
player.remove();
2843+
});
2844+
2845+
it("keeps a queued play across the iframe load event while the runtime still reports assets pending", async () => {
2846+
const player = await createConnectedPlayer();
2847+
player._ready = false;
2848+
Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
2849+
post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
2850+
player.play();
2851+
expect(player._pendingPlay).toBe(true);
2852+
2853+
player._onIframeLoad();
2854+
post(player, { type: "assets-ready", timedOut: false });
2855+
2856+
expect(player.assetsReady).toBe(true);
2857+
expect(player._ready).toBe(true);
2858+
expect(player._pendingPlay).toBe(false);
2859+
expect(player._paused).toBe(false);
2860+
2861+
player.remove();
2862+
});
2863+
2864+
it("stays ready when a late iframe load follows a settled opaque-origin wait", async () => {
2865+
const player = await createConnectedPlayer();
2866+
player._ready = false;
2867+
Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
2868+
post(player, { type: "timeline", durationInFrames: 60, assetsReady: false });
2869+
post(player, { type: "assets-ready", timedOut: false });
2870+
expect(player._ready).toBe(true);
2871+
2872+
player._onIframeLoad();
2873+
2874+
expect(player._ready).toBe(true);
2875+
expect(player.assetsReady).toBe(true);
2876+
player.play();
2877+
expect(player._paused).toBe(false);
2878+
2879+
player.remove();
2880+
});
2881+
2882+
it("does not wait on an opaque-origin runtime that already settled its assets", async () => {
2883+
const player = await createConnectedPlayer();
2884+
player._ready = false;
2885+
Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
2886+
post(player, { type: "timeline", durationInFrames: 60, assetsReady: true });
2887+
2888+
expect(player.assetsReady).toBe(true);
2889+
2890+
player.remove();
2891+
});
2892+
2893+
it("does not wait on an opaque-origin runtime that never announced the capability", async () => {
2894+
const player = await createConnectedPlayer();
2895+
player._ready = false;
2896+
Object.defineProperty(player.iframe, "contentDocument", { get: () => null });
2897+
post(player, { type: "timeline", durationInFrames: 60 });
2898+
2899+
expect(player.assetsReady).toBe(true);
2900+
2901+
player.remove();
2902+
});
2903+
28262904
it("settles immediately for a cross-origin composition (doc === null)", async () => {
28272905
const player = await createConnectedPlayer();
28282906

‎packages/player/src/hyperframes-player.ts‎

Lines changed: 35 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ class HyperframesPlayer extends HTMLElement {
130130
private _scenes: { id: string; start: number; duration: number }[] = [];
131131
private _runtimeFps = 30;
132132
private _runtimeBridgeReady = false;
133+
private _runtimeAssetsReadyGeneration = -1;
133134
private _runtimeData = new Map<string, unknown>();
134135
private _runtimeDataRequestId = 0;
135136
private _pendingRuntimeData = new Map<string, PendingRuntimeDataDelivery>();
@@ -955,11 +956,17 @@ class HyperframesPlayer extends HTMLElement {
955956
this._replayBridgeState();
956957
this._replayRuntimeData();
957958
},
959+
onRuntimeAssetsReady: () => {
960+
if (this._runtimeAssetsReadyGeneration === this._assetsGeneration) {
961+
this._settleAssetsReady(this._assetsGeneration);
962+
}
963+
},
958964
onRuntimeDataApplied: (channel, requestId) =>
959965
this._resolveRuntimeDataDelivery(channel, requestId),
960966
onRuntimeDataError: (channel, requestId, message) =>
961967
this._rejectRuntimeDataDelivery(channel, requestId, message),
962-
onRuntimeTimelineReady: (duration) => this._onRuntimeTimelineReady(duration),
968+
onRuntimeTimelineReady: (duration, assetsReady) =>
969+
this._onRuntimeTimelineReady(duration, assetsReady),
963970
setRuntimeFps: (fps) => {
964971
this._runtimeFps = fps;
965972
},
@@ -978,7 +985,7 @@ class HyperframesPlayer extends HTMLElement {
978985
});
979986
}
980987

981-
private _onRuntimeTimelineReady(duration: number) {
988+
private _onRuntimeTimelineReady(duration: number, assetsReady: boolean | undefined) {
982989
if (this._ready) return;
983990
this.probe.stop();
984991
this._duration = duration;
@@ -996,7 +1003,7 @@ class HyperframesPlayer extends HTMLElement {
9961003

9971004
this._replayBridgeState();
9981005
this._setIframeMediaMuted(this.muted);
999-
this._waitForAssetsReady(doc);
1006+
this._waitForAssetsReady(doc, assetsReady);
10001007
if (this.hasAttribute("autoplay") || this._pendingPlay) this.play();
10011008
}
10021009

@@ -1022,15 +1029,23 @@ class HyperframesPlayer extends HTMLElement {
10221029
* bounded by ASSETS_READY_TIMEOUT_MS. The overlay is debounced by
10231030
* ASSETS_LOADING_SHOW_DELAY_MS rather than shown the instant a wait
10241031
* starts, since one is now pending on nearly every Play. */
1025-
private _waitForAssetsReady(doc: Document | null): void {
1032+
private _waitForAssetsReady(doc: Document | null, runtimeAssetsReady?: boolean): void {
10261033
this._clearAssetsLoadingShowTimer();
10271034
this._assetsReady = false;
10281035
// Invalidates any earlier wait still in flight (a composition swap, or
10291036
// disconnect, mid-wait) — its eventual settle checks this and no-ops
10301037
// rather than resolving a since-superseded generation.
10311038
const generation = ++this._assetsGeneration;
10321039
if (!doc) {
1033-
this._settleAssetsReady(generation);
1040+
// An opaque-origin iframe cannot be scanned from here; a runtime that
1041+
// reports `assetsReady: false` runs the same scan itself and posts the result.
1042+
if (runtimeAssetsReady === false) {
1043+
this._runtimeAssetsReadyGeneration = generation;
1044+
this._startAssetsLoadingOverlayTimer(generation);
1045+
setTimeout(() => this._settleAssetsReady(generation), ASSETS_READY_TIMEOUT_MS);
1046+
} else {
1047+
this._settleAssetsReady(generation);
1048+
}
10341049
return;
10351050
}
10361051
settleCompositionReadiness(
@@ -1042,14 +1057,16 @@ class HyperframesPlayer extends HTMLElement {
10421057
},
10431058
{ timeoutMs: ASSETS_READY_TIMEOUT_MS },
10441059
);
1045-
if (!this._assetsReady) {
1046-
this._assetsLoadingShowTimer = setTimeout(() => {
1047-
this._assetsLoadingShowTimer = null;
1048-
if (generation !== this._assetsGeneration || this._assetsReady) return;
1049-
this.setAttribute(ASSETS_LOADING_ATTR, "");
1050-
this.shaderLoader.showAssetsLoading();
1051-
}, ASSETS_LOADING_SHOW_DELAY_MS);
1052-
}
1060+
if (!this._assetsReady) this._startAssetsLoadingOverlayTimer(generation);
1061+
}
1062+
1063+
private _startAssetsLoadingOverlayTimer(generation: number): void {
1064+
this._assetsLoadingShowTimer = setTimeout(() => {
1065+
this._assetsLoadingShowTimer = null;
1066+
if (generation !== this._assetsGeneration || this._assetsReady) return;
1067+
this.setAttribute(ASSETS_LOADING_ATTR, "");
1068+
this.shaderLoader.showAssetsLoading();
1069+
}, ASSETS_LOADING_SHOW_DELAY_MS);
10531070
}
10541071

10551072
/** Timeout diagnostic. Re-scans since some assets may have resolved by
@@ -1128,6 +1145,11 @@ class HyperframesPlayer extends HTMLElement {
11281145
}
11291146

11301147
private _onIframeLoad() {
1148+
// The runtime posts its timeline at DOMContentLoaded, before `load`, and every
1149+
// host-initiated navigation clears `_ready` first. So a ready opaque-origin player already
1150+
// holds this document's handshake; a paused runtime would never post it again.
1151+
if (this._ready && this._getSameOriginIframeDocument() === null) return;
1152+
11311153
this._ready = false;
11321154
// The runtime installs its bridge at DOMContentLoaded, posts `ready`, and only then does the
11331155
// iframe's load event fire. Do not erase that authoritative handshake here: doing so strands

0 commit comments

Comments
 (0)