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