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

The audio-locked attribute was correctly setting `muted = true` and posting
`set-muted` to the iframe runtime, but on warm-cache reloads of claude.ai
and inside the Claude desktop Electron client, the iframe finishes loading
*after* the parent has already sent control messages — the iframe runtime's
postMessage listener isn't installed yet, so the messages are silently
dropped. Audio plays unmuted with no UI to recover.

Confirmed via:
- "First open" on claude.ai: cold cache, iframe slow → listener up before
  `set-muted` lands → audio muted ✅
- "Hard refresh" on claude.ai: warm cache, iframe fast → listener up after
  message arrives → message lost → audio plays ❌
- Claude desktop: Electron renderer consistently fast → race always loses
  → audio plays ❌

Fix: add a `{source: "hf-preview", type: "ready"}` event the runtime emits
once `installRuntimeControlBridge` has registered the listener. The player
listens for it and replays current bridge state (`set-muted`, `set-volume`,
`set-playback-rate`). Pre-ready messages are now safe to send — they'll be
replayed once the runtime can receive them.

The replay is idempotent — re-asserting defaults is a no-op — so it's also
safe across iframe reloads (new runtime instance emits ready again).

Tests: 6 new (1 bridge: ready posted on install; 5 player: replays muted /
volume / playback-rate / audio-locked-forced-mute / handles second ready /
ignores ready from wrong source). Suites green: core 1387, player 137.

Refs:
- Investigation: heygen-com/hyperframes#1300 (UA-fallback attempt — unrelated
  to actual root cause)
- claude.ai-web.log analysis revealed cross-origin iframe + race condition,
  not attribute stripping as originally hypothesized

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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(