player: window.__hf from @hyperframes/shader-transitions makes an src embed reject its own composition

Author: srinvasmishraCreated Sep 16, 2026Updated Sep 16, 2026

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():

javascript

// @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

javascript

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

xml

<!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:

xml

<!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

xml

<script src="https://cdn.jsdelivr.net/npm/@hyperframes/[email protected]/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.

Source: heygen-com/hyperframes

View original on GitHub View discussion on GitHub