Merge pull request #1310 from heygen-com/fix/runtime-ready-handshake

fix(runtime,player): replay bridge state on iframe ready to repair race

Author: xiayewang-heygen

packages/core/src/runtime/README.md

@@ -32,6 +32,11 @@ postMessage:
 - runtime -> parent events:
   - `source: "hf-preview"`
   - `type: "state"` and `type: "timeline"`
+  - `type: "ready"` — emitted once when `installRuntimeControlBridge` registers
+    the control-message listener. The parent uses it to replay current playback
+    state (`set-muted`, `set-volume`, `set-playback-rate`) so any control
+    message sent before the listener was installed isn't lost. Emitted again on
+    every iframe reload because the new runtime instance starts with no state.
 
 Determinism baseline:
 

packages/core/src/runtime/bridge.test.ts

@@ -168,4 +168,14 @@ describe("installRuntimeControlBridge", () => {
       handler(makeControlMessage("flash-elements", { selectors: [".test"], duration: 500 })),
     ).not.toThrow();
   });
+
+  it("posts a ready message to window.parent on install", () => {
+    // The bridge announces itself so the parent can replay any control
+    // messages it posted before the iframe runtime's listener was installed.
+    const postSpy = vi.spyOn(window.parent, "postMessage");
+    const deps = createMockDeps();
+    installRuntimeControlBridge(deps);
+    expect(postSpy).toHaveBeenCalledWith({ source: "hf-preview", type: "ready" }, "*");
+    postSpy.mockRestore();
+  });
 });

packages/core/src/runtime/bridge.ts

@@ -79,6 +79,12 @@ export function installRuntimeControlBridge(deps: BridgeDeps): (event: MessageEv
     }
   };
   window.addEventListener("message", handler);
+  // Announce that the bridge listener is installed so the parent can replay
+  // any control messages it posted before the iframe runtime was ready
+  // (avoids losing the initial `set-muted` / `set-volume` / `set-playback-rate`
+  // when the parent finishes loading before the iframe does — a deterministic
+  // race on warm-cache reloads and inside the Claude desktop Electron client).
+  postRuntimeMessage({ source: "hf-preview", type: "ready" });
   return handler;
 }
 

packages/core/src/runtime/types.ts

@@ -153,6 +153,20 @@ export type RuntimeMediaAutoplayBlockedMessage = {
   type: "media-autoplay-blocked";
 };
 
+/**
+ * Posted by the runtime when `installRuntimeControlBridge` finishes registering
+ * its message listener — signals that subsequent control messages
+ * (`set-muted`, `set-volume`, `set-playback-rate`, etc.) will now be received
+ * and processed. The parent (web component / host app) listens for this and
+ * replays current playback state to repair any race where bridge messages
+ * were posted before the listener was installed. Emitted again on every iframe
+ * reload because the new runtime instance starts with no state.
+ */
+export type RuntimeReadyMessage = {
+  source: "hf-preview";
+  type: "ready";
+};
+
 /**
  * Analytics events emitted by the runtime.
  *
@@ -199,6 +213,7 @@ export type RuntimeOutboundMessage =
   | RuntimePickerCancelledMessage
   | RuntimeStageSizeMessage
   | RuntimeMediaAutoplayBlockedMessage
+  | RuntimeReadyMessage
   | RuntimeAnalyticsMessage
   | RuntimePerformanceMessage;
 

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

@@ -1591,6 +1591,130 @@ describe("HyperframesPlayer audio lock", () => {
   });
 });
 
+describe("HyperframesPlayer runtime ready handshake", () => {
+  // When the iframe runtime announces `{type: "ready"}` the player replays
+  // current bridge state (muted, volume, playback rate) so any control message
+  // that arrived before the iframe runtime registered its listener isn't lost.
+  // This fixes a deterministic race on warm-cache reloads of claude.ai and
+  // inside the Claude desktop Electron client where the iframe finishes
+  // loading after the player has already set audio-locked.
+  interface PlayerInternal extends HTMLElement {
+    muted: boolean;
+    volume: number;
+    audioLocked: boolean;
+    playbackRate: number;
+    iframe: HTMLIFrameElement;
+    _onMessage: (event: MessageEvent) => void;
+  }
+
+  let player: PlayerInternal;
+  let frameWindow: Window;
+  let postSpy: ReturnType<typeof vi.spyOn>;
+
+  function readyMessage() {
+    return new MessageEvent("message", {
+      source: frameWindow,
+      data: { source: "hf-preview", type: "ready" },
+    });
+  }
+
+  function findControlCalls(action: string) {
+    return postSpy.mock.calls.filter((call) => {
+      const data = call[0] as { type?: string; action?: string };
+      return data?.type === "control" && data?.action === action;
+    });
+  }
+
+  beforeEach(async () => {
+    await import("./hyperframes-player.js");
+    player = document.createElement("hyperframes-player") as PlayerInternal;
+    frameWindow = window;
+    postSpy = vi.spyOn(frameWindow, "postMessage").mockImplementation(() => undefined);
+    Object.defineProperty(player.iframe, "contentWindow", {
+      configurable: true,
+      get: () => frameWindow,
+    });
+    document.body.appendChild(player);
+  });
+
+  afterEach(() => {
+    player.remove();
+    vi.restoreAllMocks();
+  });
+
+  it("replays current muted state when runtime emits ready", () => {
+    player.muted = true;
+    postSpy.mockClear();
+
+    player._onMessage(readyMessage());
+
+    const muteCalls = findControlCalls("set-muted");
+    expect(muteCalls).toHaveLength(1);
+    expect(muteCalls[0]?.[0]).toMatchObject({
+      source: "hf-parent",
+      type: "control",
+      action: "set-muted",
+      muted: true,
+    });
+  });
+
+  it("replays volume and playback-rate alongside muted", () => {
+    player.volume = 0.5;
+    player.playbackRate = 1.25;
+    postSpy.mockClear();
+
+    player._onMessage(readyMessage());
+
+    expect(findControlCalls("set-muted")).toHaveLength(1);
+    expect(findControlCalls("set-volume")[0]?.[0]).toMatchObject({
+      action: "set-volume",
+      volume: 0.5,
+    });
+    expect(findControlCalls("set-playback-rate")[0]?.[0]).toMatchObject({
+      action: "set-playback-rate",
+      playbackRate: 1.25,
+    });
+  });
+
+  it("replays the muted state forced by audio-locked", () => {
+    // The audio-locked attribute is the original motivating case for this
+    // handshake — its `muted = true` side effect must survive an iframe race.
+    player.setAttribute("audio-locked", "");
+    expect(player.muted).toBe(true);
+    postSpy.mockClear();
+
+    player._onMessage(readyMessage());
+
+    const muteCalls = findControlCalls("set-muted");
+    expect(muteCalls).toHaveLength(1);
+    expect(muteCalls[0]?.[0]).toMatchObject({ action: "set-muted", muted: true });
+  });
+
+  it("replays again on a second ready (idempotent — iframe reloads emit again)", () => {
+    player.muted = true;
+    postSpy.mockClear();
+
+    player._onMessage(readyMessage());
+    player._onMessage(readyMessage());
+
+    expect(findControlCalls("set-muted")).toHaveLength(2);
+  });
+
+  it("ignores ready events from a different window", () => {
+    postSpy.mockClear();
+    const otherSource = {} as Window;
+
+    player._onMessage(
+      new MessageEvent("message", {
+        source: otherSource,
+        data: { source: "hf-preview", type: "ready" },
+      }),
+    );
+
+    expect(findControlCalls("set-muted")).toHaveLength(0);
+  });
+});
+
 describe("HyperframesPlayer audio lock — Claude desktop UA fallback", () => {
   // Some host renderers (observed on the Claude desktop Electron client) strip
   // unknown custom-element attributes before they reach the DOM, so the

packages/player/src/hyperframes-player.ts

@@ -428,6 +428,21 @@ class HyperframesPlayer extends HTMLElement {
     }
   }
 
+  /**
+   * Replay current bridge state to the iframe runtime. Triggered when the
+   * runtime announces `{type: "ready"}` — repairs the race where the parent
+   * posts control messages before the iframe's bridge listener is installed
+   * (warm-cache reloads, the Claude desktop Electron client, anywhere the
+   * iframe finishes loading after we've already called `set-muted` etc).
+   * Re-sending current state is idempotent — even at default values it just
+   * confirms what the runtime would have done anyway.
+   */
+  private _replayBridgeState(): void {
+    this._sendControl("set-muted", { muted: this.muted });
+    this._sendControl("set-volume", { volume: this._volume });
+    this._sendControl("set-playback-rate", { playbackRate: this.playbackRate });
+  }
+
   private _reloadShaderOptions(): void {
     if (getShaderModeFromElement(this) !== "player") this.shaderLoader.reset();
     if (this.hasAttribute("srcdoc")) {
@@ -529,6 +544,7 @@ class HyperframesPlayer extends HTMLElement {
       },
       sendControl: (action, extra) => this._sendControl(action, extra),
       getIframeDoc: () => this.iframe.contentDocument,
+      onRuntimeReady: () => this._replayBridgeState(),
       updateControlsTime: (t, d) => this.controlsApi?.updateTime(t, d),
       updateControlsPlaying: (p) => this.controlsApi?.updatePlaying(p),
       dispatchEvent: (ev) => this.dispatchEvent(ev),

packages/player/src/runtime-message-handler.ts

@@ -23,6 +23,10 @@ export interface MessageHandlerCallbacks extends PlaybackStateCallbacks {
   setCompositionSize: (width: number, height: number) => void;
   sendControl: (action: string, extra?: Record<string, unknown>) => void;
   getIframeDoc: () => Document | null;
+  /** Invoked when the iframe runtime posts `{type: "ready"}` — the player
+   *  uses it to replay current bridge state (mute, volume, playback rate) so
+   *  control messages sent before the iframe's listener registered aren't lost. */
+  onRuntimeReady: () => void;
 }
 
 export function handleRuntimeMessage(
@@ -48,6 +52,11 @@ export function handleRuntimeMessage(
     return;
   }
 
+  if (data["type"] === "ready") {
+    callbacks.onRuntimeReady();
+    return;
+  }
+
   if (data["type"] === "state") {
     callbacks.setPlaybackState(
       applyRuntimeStateMessage(