Summary
<hyperframes-player src="..."> treats the mere existence of window.__hf in the composition
frame as "the core runtime is present". But @hyperframes/shader-transitions — the sibling
package, at the same version — creates that global itself at the end of HyperShader.init():
// @hyperframes/shader-transitions 0.8.41, dist/index.global.js
let gr = window;
return gr.__hf = gr.__hf || {}, gr.__hf.shaderTransitionsReady = Qo, ...So any composition that uses shader transitions and registers its own timeline
(window.__timelines) — i.e. an authored GSAP composition, not one bundled by the CLI — can never
be played through the player when loaded with src. The probe:
- sees
hasRuntime = !!(win.__hf || win.__player) → true, so it never injects the runtime
(we() returns false); and
hasRuntimeBridge() → true, so _resolveDirectTimelineAdapterFromWindow() returns null
and the direct-timeline adapter is refused.
Nothing is ever resolved, and 8 s later the element emits
error: "Composition timeline not found after 8s". The frame stays black.
window.__hf is a namespace, not a bridge — shader-transitions only ever augments it (it polls
for window.__hf.seek and warns "the engine bridge did not initialize" when the core runtime is
absent). The presence check should be for the bridge itself (__player, or a callable
__hf.seek), not for the object.
Reproduction
Two identical compositions; the only difference is the three lines shader-transitions would have
run. No GSAP needed — the stub has exactly the shape the player duck-types for.
timeline.js
window.__timelines = { main: (function () {
var t = 0;
return {
duration: function () { return 10; },
time: function (v) { if (v === undefined) return t; t = v; return this; },
seek: function (v) { t = v; return this; },
play: function () { return this; },
pause: function () { return this; },
};
})() };comp-clean.html
<!doctype html><html><head><meta charset="utf-8"></head><body>
<div id="root" data-composition-id="main" data-width="1080" data-height="1920"></div>
<script src="timeline.js"></script>
</body></html>
comp-shader.html — identical, plus what HyperShader.init() leaves behind:
<!doctype html><html><head><meta charset="utf-8"></head><body>
<div id="root" data-composition-id="main" data-width="1080" data-height="1920"></div>
<script>
window.__hf = window.__hf || {};
window.__hf.shaderTransitionsReady = Promise.resolve();
</script>
<script src="timeline.js"></script>
</body></html>host.html
<script src="https://cdn.jsdelivr.net/npm/@hyperframes/player@0.8.41/dist/hyperframes-player.global.js"></script>
<hyperframes-player id="a" src="comp-clean.html" width="1080" height="1920"></hyperframes-player>
<hyperframes-player id="b" src="comp-shader.html" width="1080" height="1920"></hyperframes-player>
<script>
for (const id of ["a", "b"])
for (const type of ["ready", "error"])
document.getElementById(id).addEventListener(type, (e) =>
console.log(id, type, e.detail));
</script>Serve the folder over http and open host.html.
Actual
a ready {duration: 10}
b error {message: "Composition timeline not found after 8s"}
Expected
Both report ready. A composition does not stop being playable because it also uses
@hyperframes/shader-transitions.
Environment
@hyperframes/player 0.8.41, @hyperframes/shader-transitions 0.8.41, hyperframes 0.8.41- Chromium 141, Linux
Notes
The same compositions render correctly with hyperframes render, because the CLI injects the core
runtime into the document before loading it — window.__player then exists and the player takes
the runtime path. The failure is specific to embedding an authored composition with src.
Summary
<hyperframes-player src="...">treats the mere existence ofwindow.__hfin the compositionframe as "the core runtime is present". But
@hyperframes/shader-transitions— the siblingpackage, at the same version — creates that global itself at the end of
HyperShader.init():So any composition that uses shader transitions and registers its own timeline
(
window.__timelines) — i.e. an authored GSAP composition, not one bundled by the CLI — can neverbe played through the player when loaded with
src. The probe:hasRuntime = !!(win.__hf || win.__player)→true, so it never injects the runtime(
we()returns false); andhasRuntimeBridge()→true, so_resolveDirectTimelineAdapterFromWindow()returnsnulland the direct-timeline adapter is refused.
Nothing is ever resolved, and 8 s later the element emits
error: "Composition timeline not found after 8s". The frame stays black.window.__hfis a namespace, not a bridge — shader-transitions only ever augments it (it pollsfor
window.__hf.seekand warns "the engine bridge did not initialize" when the core runtime isabsent). The presence check should be for the bridge itself (
__player, or a callable__hf.seek), not for the object.Reproduction
Two identical compositions; the only difference is the three lines shader-transitions would have
run. No GSAP needed — the stub has exactly the shape the player duck-types for.
timeline.jscomp-clean.htmlcomp-shader.html— identical, plus whatHyperShader.init()leaves behind:host.htmlServe the folder over http and open
host.html.Actual
Expected
Both report
ready. A composition does not stop being playable because it also uses@hyperframes/shader-transitions.Environment
@hyperframes/player0.8.41,@hyperframes/shader-transitions0.8.41,hyperframes0.8.41Notes
The same compositions render correctly with
hyperframes render, because the CLI injects the coreruntime into the document before loading it —
window.__playerthen exists and the player takesthe runtime path. The failure is specific to embedding an authored composition with
src.