From 95137a12ea002991713d36db00925f3b8ae15dd5 Mon Sep 17 00:00:00 2001
From: Srikar Sunchu <sri@elide.dev>
Date: Mon, 21 Sep 2026 02:37:51 -0700
Subject: [PATCH] fix(player): detect the runtime by __player and honour
 runtime-src for src embeds

`<hyperframes-player src="...">` treated the existence of `window.__hf` in
the composition frame as "the core runtime is present". `__hf` is a shared
namespace, not a bridge: `@hyperframes/shader-transitions` creates it too
(`window.__hf = window.__hf || {}`) to publish `shaderTransitionsReady`. An
authored composition that used shader transitions and registered its own
`__timelines` therefore never had the runtime injected and had its
direct-timeline adapter refused, and the embed failed 8 s later with
"Composition timeline not found". The only global the player ever drives is
`__player`, which the runtime installs synchronously in the same task as
`__hf`, so that is now the bridge check on both the probe tick and the
adapter path.

The probe's injection also always loaded the runtime from jsDelivr: the
`runtime-src` attribute was resolved for srcdoc only. The resolver is now
shared, and the player passes it to the probe, so an `src` embed can serve
its own pinned copy offline or under a `script-src 'self'` CSP. A runtime
that fails to load reports its URL on the script's own error event instead
of being indistinguishable from a slow one until the timeout.

Closes #4002
Closes #4003

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/player/src/composition-probe.test.ts | 190 +++++++++++++++++-
 packages/player/src/composition-probe.ts      |  42 +++-
 .../player/src/hyperframes-player.test.ts     |  33 +++
 packages/player/src/hyperframes-player.ts     |   4 +
 packages/player/src/shader-options.ts         |  14 +-
 packages/player/src/shouldInjectRuntime.ts    |   4 +-
 6 files changed, 276 insertions(+), 11 deletions(-)

diff --git a/packages/player/src/composition-probe.test.ts b/packages/player/src/composition-probe.test.ts
index 2b4a749ac4..1c6cab8e78 100644
--- a/packages/player/src/composition-probe.test.ts
+++ b/packages/player/src/composition-probe.test.ts
@@ -1,5 +1,10 @@
-import { describe, expect, it } from "vitest";
-import { readCompositionSizeFromDocument, runtimeCdnUrlForVersion } from "./composition-probe.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  CompositionProbe,
+  readCompositionSizeFromDocument,
+  runtimeCdnUrlForVersion,
+} from "./composition-probe.js";
+import { RUNTIME_CDN_URL } from "./runtime-url.js";
 
 describe("readCompositionSizeFromDocument", () => {
   it("reads dimensions from the composition root", () => {
@@ -36,3 +41,184 @@ describe("runtimeCdnUrlForVersion", () => {
     expect(() => runtimeCdnUrlForVersion("latest")).toThrow("Invalid HyperFrames runtime version");
   });
 });
+
+// ── Runtime detection and injection ──
+//
+// `window.__hf` is a namespace, not a bridge. The core runtime creates it, but
+// so does `@hyperframes/shader-transitions` (to publish `shaderTransitionsReady`),
+// so an authored composition that uses shader transitions and registers its
+// own `__timelines` carries `__hf` with no runtime behind it. The probe used
+// to read that as "runtime present": it never injected the runtime, refused
+// the direct-timeline adapter, and the embed timed out after 8 s. The only
+// global the player ever drives is `__player`, so that is the bridge check.
+describe("CompositionProbe runtime detection", () => {
+  type FakeTimeline = {
+    duration: () => number;
+    time: () => number;
+    seek: () => void;
+    play: () => void;
+    pause: () => void;
+  };
+  type FakeWindow = {
+    __hf?: unknown;
+    __player?: unknown;
+    __timelines?: Record<string, FakeTimeline>;
+  };
+  type FakeScript = { src: string; onerror: (() => void) | null };
+
+  function fakeTimeline(duration = 10): FakeTimeline {
+    return { duration: () => duration, time: () => 0, seek() {}, play() {}, pause() {} };
+  }
+
+  // A minimal contentDocument so injection does not go through happy-dom's
+  // real `<script src>` loading. `appendChild` records the injected script.
+  function fakeDocument(bodyHtml: string, appended: FakeScript[]) {
+    const doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = bodyHtml;
+    return {
+      querySelector: (selector: string) => doc.querySelector(selector),
+      createElement: (): FakeScript => ({ src: "", onerror: null }),
+      head: { appendChild: (node: FakeScript) => appended.push(node) },
+    };
+  }
+
+  function fakeIframe(win: FakeWindow, doc: unknown): HTMLIFrameElement {
+    const iframe = document.createElement("iframe");
+    Object.defineProperty(iframe, "contentWindow", { configurable: true, get: () => win });
+    Object.defineProperty(iframe, "contentDocument", { configurable: true, get: () => doc });
+    return iframe;
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("drives __timelines directly when only the shader-transitions __hf namespace is present", () => {
+    const appended: FakeScript[] = [];
+    const win: FakeWindow = {
+      __hf: { shaderTransitionsReady: Promise.resolve() },
+      __timelines: { main: fakeTimeline(10) },
+    };
+    const iframe = fakeIframe(
+      win,
+      fakeDocument(
+        '<div data-composition-id="main" data-width="1080" data-height="1920"></div>',
+        appended,
+      ),
+    );
+    const onReady = vi.fn();
+    const onError = vi.fn();
+    const probe = new CompositionProbe(iframe, { onReady, onError });
+
+    probe.start();
+    vi.advanceTimersByTime(200);
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(appended).toHaveLength(0);
+    expect(onReady).toHaveBeenCalledTimes(1);
+    expect(onReady.mock.calls[0][0]).toMatchObject({
+      duration: 10,
+      adapter: { kind: "direct-timeline" },
+    });
+    expect(probe.hasRuntimeBridge(win as unknown as Window)).toBe(false);
+    probe.stop();
+  });
+
+  it("still prefers an installed __player bridge over direct __timelines", () => {
+    const win: FakeWindow = {
+      __hf: {},
+      __player: { getDuration: () => 7 },
+      __timelines: { main: fakeTimeline(10) },
+    };
+    const iframe = fakeIframe(win, fakeDocument("", []));
+    const onReady = vi.fn();
+    const probe = new CompositionProbe(iframe, { onReady, onError: vi.fn() });
+
+    probe.start();
+    vi.advanceTimersByTime(200);
+
+    expect(onReady).toHaveBeenCalledTimes(1);
+    expect(onReady.mock.calls[0][0]).toMatchObject({ duration: 7, adapter: { kind: "runtime" } });
+    expect(probe.hasRuntimeBridge(win as unknown as Window)).toBe(true);
+    expect(probe.resolveDirectTimelineAdapter()).toBeNull();
+    probe.stop();
+  });
+
+  it("injects the runtime into a nested composition despite a pre-existing __hf namespace", () => {
+    const appended: FakeScript[] = [];
+    const win: FakeWindow = { __hf: { shaderTransitionsReady: Promise.resolve() } };
+    const iframe = fakeIframe(
+      win,
+      fakeDocument('<div data-composition-src="child.html"></div>', appended),
+    );
+    const onRuntimeInjected = vi.fn();
+    const probe = new CompositionProbe(iframe, {
+      onReady: vi.fn(),
+      onError: vi.fn(),
+      onRuntimeInjected,
+    });
+
+    probe.start();
+    vi.advanceTimersByTime(200);
+
+    expect(onRuntimeInjected).toHaveBeenCalledTimes(1);
+    expect(appended).toHaveLength(1);
+    expect(appended[0].src).toBe(RUNTIME_CDN_URL);
+    probe.stop();
+  });
+
+  it("loads the runtime from resolveRuntimeUrl when the host configures one", () => {
+    // `runtime-src` was honoured for srcdoc only; an src embed always fetched
+    // the runtime from jsDelivr, which fails offline or under a strict CSP.
+    const appended: FakeScript[] = [];
+    const iframe = fakeIframe(
+      {},
+      fakeDocument('<div data-composition-src="child.html"></div>', appended),
+    );
+    const probe = new CompositionProbe(iframe, {
+      onReady: vi.fn(),
+      onError: vi.fn(),
+      resolveRuntimeUrl: () => "http://127.0.0.1:8900/hyperframe.runtime.iife.js",
+    });
+
+    probe.start();
+    vi.advanceTimersByTime(200);
+
+    expect(appended).toHaveLength(1);
+    expect(appended[0].src).toBe("http://127.0.0.1:8900/hyperframe.runtime.iife.js");
+    probe.stop();
+  });
+
+  it("reports a runtime that fails to load instead of waiting out the 8 s timeout", () => {
+    const appended: FakeScript[] = [];
+    const iframe = fakeIframe(
+      {},
+      fakeDocument('<div data-composition-src="child.html"></div>', appended),
+    );
+    const onError = vi.fn();
+    const probe = new CompositionProbe(iframe, {
+      onReady: vi.fn(),
+      onError,
+      resolveRuntimeUrl: () => "http://127.0.0.1:8900/missing.js",
+    });
+
+    probe.start();
+    vi.advanceTimersByTime(200);
+    expect(appended).toHaveLength(1);
+
+    appended[0].onerror?.();
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      "HyperFrames runtime failed to load from http://127.0.0.1:8900/missing.js",
+    );
+
+    // The probe has stopped: no second, generic timeout error follows.
+    vi.advanceTimersByTime(10_000);
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/player/src/composition-probe.ts b/packages/player/src/composition-probe.ts
index b3c500b104..fdff6b4e13 100644
--- a/packages/player/src/composition-probe.ts
+++ b/packages/player/src/composition-probe.ts
@@ -35,6 +35,29 @@ export interface ProbeCallbacks {
   onError: (message: string) => void;
   /** Called when runtime is successfully injected (informational). */
   onRuntimeInjected?: () => void;
+  /**
+   * Where to load the runtime from when the probe has to inject it. Read at
+   * injection time, not at construction, so a `runtime-src` set after the
+   * element was created is still honoured. Defaults to the pinned CDN build.
+   */
+  resolveRuntimeUrl?: () => string;
+}
+
+/**
+ * Whether the core runtime has installed its player bridge in this window.
+ *
+ * The bridge is `window.__player`: the runtime creates it synchronously during
+ * init, in the same task as `window.__hf`, and it is the only global the
+ * player ever drives. `window.__hf` on its own is not evidence of a runtime:
+ * it is a shared namespace that `@hyperframes/shader-transitions` also creates
+ * (`window.__hf = window.__hf || {}`) to publish `shaderTransitionsReady`, so
+ * an authored composition using shader transitions carries `__hf` with no
+ * runtime behind it. Treating that as "runtime present" meant the probe never
+ * injected the runtime and refused the direct-timeline adapter, and the embed
+ * timed out after 8 s with a black frame.
+ */
+function hasRuntimeBridge(win: Window): boolean {
+  return isObjectRecord(Reflect.get(win, "__player"));
 }
 
 /**
@@ -88,13 +111,11 @@ export class CompositionProbe {
       attempts++;
       try {
         const win = this._iframe.contentWindow as Window & {
-          __player?: { getDuration: () => number };
           __timelines?: Record<string, { duration: () => number }>;
-          __hf?: unknown;
         };
         if (!win) return;
 
-        const hasRuntime = !!(win.__hf || win.__player);
+        const hasRuntime = hasRuntimeBridge(win);
         const hasTimelines = !!(win.__timelines && Object.keys(win.__timelines).length > 0);
         const hasNestedCompositions =
           !!this._iframe.contentDocument?.querySelector("[data-composition-src]");
@@ -163,7 +184,7 @@ export class CompositionProbe {
   }
 
   hasRuntimeBridge(win: Window): boolean {
-    return Reflect.get(win, "__hf") !== undefined || isObjectRecord(Reflect.get(win, "__player"));
+    return hasRuntimeBridge(win);
   }
 
   // ── Private ──────────────────────────────────────────────────────────────
@@ -173,8 +194,17 @@ export class CompositionProbe {
     try {
       const doc = this._iframe.contentDocument;
       if (!doc) return;
+      const runtimeUrl = this._callbacks.resolveRuntimeUrl?.() ?? RUNTIME_CDN_URL;
       const script = doc.createElement("script");
-      script.src = RUNTIME_CDN_URL;
+      script.src = runtimeUrl;
+      // A runtime that is blocked (CSP, offline, 404) used to look exactly like
+      // a slow one: the probe kept polling and reported a missing timeline 8 s
+      // later. Fail on the script's own error instead, naming the URL.
+      script.onerror = () => {
+        if (this._interval === null) return;
+        this.stop();
+        this._callbacks.onError(`HyperFrames runtime failed to load from ${runtimeUrl}`);
+      };
       (doc.head || doc.documentElement).appendChild(script);
       this._callbacks.onRuntimeInjected?.();
     } catch {
@@ -183,7 +213,7 @@ export class CompositionProbe {
   }
 
   private _resolveDirectTimelineAdapterFromWindow(win: Window): DirectTimelineAdapter | null {
-    if (this.hasRuntimeBridge(win)) return null;
+    if (hasRuntimeBridge(win)) return null;
 
     const timelines = Reflect.get(win, "__timelines");
     if (!isObjectRecord(timelines)) return null;
diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index 8b6efdfda1..735432a7c9 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -1537,6 +1537,39 @@ describe("HyperframesPlayer srcdoc attribute", () => {
     player.remove();
   });
 
+  it("uses a configured runtime source when the probe injects into an src embed", () => {
+    // `runtime-src` used to be read on the srcdoc path only; an `src` embed always
+    // fetched the runtime from jsDelivr, so a local copy could never be used
+    // offline or behind a `script-src 'self'` CSP. Both paths resolve it the
+    // same way now.
+    vi.useFakeTimers();
+    const player = document.createElement("hyperframes-player") as PlayerInternal;
+    player.setAttribute("src", "/comp-nested.html");
+    player.setAttribute("runtime-src", "http://127.0.0.1:8900/hyperframe.runtime.iife.js");
+    document.body.appendChild(player);
+
+    const appended: Array<{ src: string }> = [];
+    const doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = '<div data-composition-src="child.html"></div>';
+    Object.defineProperty(player.iframe, "contentWindow", { configurable: true, get: () => ({}) });
+    stubIframeContentDocument(player.iframe, {
+      querySelector: (selector: string) => doc.querySelector(selector),
+      querySelectorAll: () => [],
+      createElement: () => ({ src: "" }),
+      head: { appendChild: (node: { src: string }) => appended.push(node) },
+    } as unknown as Document);
+
+    player.iframe.dispatchEvent(new Event("load"));
+    vi.advanceTimersByTime(200);
+
+    expect(appended.map((node) => node.src)).toEqual([
+      "http://127.0.0.1:8900/hyperframe.runtime.iife.js",
+    ]);
+
+    player.remove();
+    vi.useRealTimers();
+  });
+
   it("falls back to the pinned runtime for an unsafe runtime source", () => {
     const player = document.createElement("hyperframes-player") as PlayerInternal;
     player.setAttribute("runtime-src", 'javascript:alert("no")');
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index d68099d344..69476c66f1 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -14,6 +14,7 @@ import {
   getShaderModeFromElement,
   prepareSrcForElement,
   prepareSrcdocForElement,
+  resolveRuntimeUrlFromElement,
 } from "./shader-options.js";
 import { createShaderLoader } from "./shader-loader-element.js";
 import { ShaderLoaderState } from "./shader-loader-state.js";
@@ -180,6 +181,9 @@ class HyperframesPlayer extends HTMLElement {
     this.probe = new CompositionProbe(this.iframe, {
       onReady: (result) => this._onProbeReady(result),
       onError: (message) => this.dispatchEvent(new CustomEvent("error", { detail: { message } })),
+      // Same resolution as the srcdoc path, so `runtime-src` applies to an
+      // `src` embed too instead of being silently replaced by the CDN URL.
+      resolveRuntimeUrl: () => resolveRuntimeUrlFromElement(this),
     });
 
     this.addEventListener("click", (event) => {
diff --git a/packages/player/src/shader-options.ts b/packages/player/src/shader-options.ts
index 094867830a..6d1ee1774e 100644
--- a/packages/player/src/shader-options.ts
+++ b/packages/player/src/shader-options.ts
@@ -154,11 +154,21 @@ export function prepareSrcdocForElement(el: Element, srcdoc: string): string {
       normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)),
       getShaderModeFromElement(el),
     ),
-    runtimeSrcFromElement(el),
+    resolveRuntimeUrlFromElement(el),
   );
 }
 
-function runtimeSrcFromElement(el: Element): string {
+/**
+ * The runtime URL an element has asked for: `runtime-src` when it is set and
+ * safe, the pinned jsDelivr build otherwise.
+ *
+ * Shared by both embed paths. srcdoc puts this URL in the document head at
+ * parse time; an `src` embed hands it to the probe, which appends it as a
+ * `<script>` once it knows the composition needs the runtime. Resolving it in
+ * one place keeps the two paths on the same URL, so a `runtime-src` that works
+ * for srcdoc also works for src.
+ */
+export function resolveRuntimeUrlFromElement(el: Element): string {
   const configured = el.getAttribute(RUNTIME_SRC_ATTR)?.trim();
   if (!configured) return RUNTIME_CDN_URL;
   try {
diff --git a/packages/player/src/shouldInjectRuntime.ts b/packages/player/src/shouldInjectRuntime.ts
index f409f519e8..ac33058481 100644
--- a/packages/player/src/shouldInjectRuntime.ts
+++ b/packages/player/src/shouldInjectRuntime.ts
@@ -3,7 +3,9 @@
  * current probe tick.
  *
  * The player polls the loaded iframe every 200ms to discover either:
- *   - a runtime bridge already installed (`window.__hf` / `window.__player`), or
+ *   - a runtime bridge already installed (`window.__player`; `window.__hf` is
+ *     a shared namespace that shader-transitions also creates, so it is not
+ *     evidence of a runtime), or
  *   - GSAP timelines registered at `window.__timelines`.
  *
  * Two classes of composition require different injection timing: