From 5f66edd4498bcecd32ac5355f03c4ed3f5b291ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Fri, 17 Apr 2026 19:45:12 +0200
Subject: [PATCH 1/2] fix(player): address review feedback on single-owner
 audio (#298)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses James Russo's review on PR #298.

- Drop drift threshold 150ms → 50ms. ITU-R BT.1359 puts A/V offset
  perceptibility at ±45ms; 150ms risks audible lip-sync drift on
  talking-head content. Steady-state offset under parent ownership
  on the factory-series-c-video repro measures 27–37ms.
- Add MutationObserver for dynamic sub-composition media so late-
  attached audio[data-start] / video[data-start] elements get a
  parent proxy. Without it, parent ownership silences the new
  element in the iframe via sticky outputMuted but has no parent
  counterpart to play — silent hole.
- Make bridgeMuted sticky in syncRuntimeMedia. Symmetric with
  mediaOutputMuted so a sub-composition activating after user mute
  doesn't briefly play at author volume before the next bridge
  message. Both flags feed a single shouldMute gate per tick.
- Reset _audioOwner on iframe load. Latch previously never cleared,
  leaving stale parent-ownership against a fresh runtime after
  composition switch — a brief double-voice window until the next
  NotAllowedError re-promoted.
- Dispatch audioownershipchange CustomEvent on every owner change,
  with reason: 'autoplay-blocked' | 'iframe-reload'. Gives host apps
  an SLO-ready signal for '% of sessions in parent ownership'.
- Surface parent proxy play() rejection as a playbackerror event
  instead of swallowing silently. Covers the rare case where the
  parent also lacks activation.
- Test gaps filled: userMuted stickiness, OR invariant between flags,
  contract pin (media.ts fires onAutoplayBlocked every rejection),
  caller-side latch pattern dedupe, audioownershipchange dispatch,
  mid-playback promotion path, playbackerror surface.
- One-line comment in _promoteToParentProxy on the postMessage
  async race — defensible because the autoplay gate keeps rejecting
  until the mute lands.

Not addressed here:
- Manual verification on a physical iOS / Android device (review
  item #7). Simulated autoplay block via agent-browser + mobile
  emulation was done on the original PR; real-device validation
  is still pending before the next release.
---
 packages/core/src/runtime/init.ts             |   1 +
 packages/core/src/runtime/media.test.ts       | 117 +++++++++++
 packages/core/src/runtime/media.ts            |  20 +-
 .../player/src/hyperframes-player.test.ts     |  54 +++++
 packages/player/src/hyperframes-player.ts     | 184 +++++++++++++++---
 5 files changed, 341 insertions(+), 35 deletions(-)

diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index a4ba9552c..7a430a47d 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -1190,6 +1190,7 @@ export function initSandboxRuntimeModular(): void {
       playing: state.isPlaying,
       playbackRate: state.playbackRate,
       outputMuted: state.mediaOutputMuted,
+      userMuted: state.bridgeMuted,
       onAutoplayBlocked: () => {
         if (state.mediaAutoplayBlockedPosted) return;
         state.mediaAutoplayBlockedPosted = true;
diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
index f9d9a537f..951ca7969 100644
--- a/packages/core/src/runtime/media.test.ts
+++ b/packages/core/src/runtime/media.test.ts
@@ -458,4 +458,121 @@ describe("syncRuntimeMedia", () => {
     await Promise.resolve();
     expect(onAutoplayBlocked).not.toHaveBeenCalled();
   });
+
+  it("asserts muted=true every tick while userMuted is set", () => {
+    // Mirror of the `outputMuted` test — user preference must be sticky
+    // too. A sub-composition that activates after the user mutes should
+    // inherit the silence, not briefly play at author volume before the
+    // next bridge message lands.
+    const clip = createMockClip({ start: 0, end: 10, volume: 1 });
+    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
+    syncRuntimeMedia({
+      clips: [clip],
+      timeSeconds: 5,
+      playing: true,
+      playbackRate: 1,
+      userMuted: true,
+    });
+    expect(clip.el.muted).toBe(true);
+  });
+
+  it("fires onAutoplayBlocked for every rejected play (caller owns the latch)", async () => {
+    // media.ts is intentionally memoryless — each NotAllowedError rejection
+    // invokes the callback. The init.ts caller wraps with
+    // `mediaAutoplayBlockedPosted` so the outbound message is posted at most
+    // once per session. This test pins down the contract (fires always) so
+    // a future refactor can't quietly add deduplication here and break the
+    // caller's latching logic.
+    const clip = createMockClip({ start: 0, end: 10 });
+    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
+    clip.el.play = vi.fn(() => Promise.reject(rejection));
+    const onAutoplayBlocked = vi.fn();
+
+    // Simulate two ticks — between them `playRequested` clears so play() runs
+    // again and rejects again.
+    syncRuntimeMedia({
+      clips: [clip],
+      timeSeconds: 5,
+      playing: true,
+      playbackRate: 1,
+      onAutoplayBlocked,
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+    syncRuntimeMedia({
+      clips: [clip],
+      timeSeconds: 5.05,
+      playing: true,
+      playbackRate: 1,
+      onAutoplayBlocked,
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // No latch inside media.ts — two rejections, two callback invocations.
+    // The caller's latch is what prevents a second outbound message.
+    expect(onAutoplayBlocked).toHaveBeenCalledTimes(2);
+  });
+
+  it("caller-side latch pattern posts once across many rejections", async () => {
+    // Mirrors what init.ts does: the onAutoplayBlocked wrapper checks and
+    // sets a boolean flag so the outbound post fires exactly once even if
+    // the raw callback fires many times. Regression guard for the latch
+    // wiring in the init.ts handler.
+    const clip = createMockClip({ start: 0, end: 10 });
+    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
+    clip.el.play = vi.fn(() => Promise.reject(rejection));
+
+    let posted = 0;
+    const state = { latched: false };
+    const wrapped = () => {
+      if (state.latched) return;
+      state.latched = true;
+      posted += 1;
+    };
+
+    for (let i = 0; i < 5; i++) {
+      syncRuntimeMedia({
+        clips: [clip],
+        timeSeconds: 5 + i * 0.05,
+        playing: true,
+        playbackRate: 1,
+        onAutoplayBlocked: wrapped,
+      });
+      await Promise.resolve();
+      await Promise.resolve();
+    }
+
+    expect(posted).toBe(1);
+  });
+
+  it("mutes when either outputMuted OR userMuted is true (OR invariant)", () => {
+    // Explicit validation of the combined-flag contract: setting one to
+    // false while the other is true must keep the element muted.
+    const clip = createMockClip({ start: 0, end: 10, volume: 1 });
+    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
+    syncRuntimeMedia({
+      clips: [clip],
+      timeSeconds: 5,
+      playing: true,
+      playbackRate: 1,
+      outputMuted: false,
+      userMuted: true,
+    });
+    expect(clip.el.muted).toBe(true);
+    Object.defineProperty(clip.el, "muted", { value: false, writable: true });
+    syncRuntimeMedia({
+      clips: [clip],
+      timeSeconds: 5,
+      playing: true,
+      playbackRate: 1,
+      outputMuted: true,
+      userMuted: false,
+    });
+    expect(clip.el.muted).toBe(true);
+  });
 });
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
index b82b95b2a..f0f65d8d7 100644
--- a/packages/core/src/runtime/media.ts
+++ b/packages/core/src/runtime/media.ts
@@ -93,13 +93,18 @@ export function syncRuntimeMedia(params: {
   playing: boolean;
   playbackRate: number;
   /**
-   * When `true`, assert `el.muted = true` on every active media element on
-   * every tick. Sticky against newly-discovered media (sub-composition
-   * activation, dynamic DOM) so the parent-frame audio-owner invariant holds.
-   * `false` is a no-op — we don't un-mute, because other code paths
-   * (`<audio muted>` author intent, `onSetMuted`) own the un-mute decision.
+   * Parent-frame audio-owner has taken over audible playback. Assert
+   * `el.muted = true` on every active media element per tick so that any
+   * sub-composition media inserted mid-playback inherits the silence.
    */
   outputMuted?: boolean;
+  /**
+   * User's explicit mute preference (set via `onSetMuted`). Symmetric to
+   * `outputMuted` — also asserted per tick — so a sub-composition that
+   * activates after the user mutes doesn't briefly play at author volume
+   * before the next bridge message lands.
+   */
+  userMuted?: boolean;
   /**
    * Invoked at most once when a media element's `play()` promise rejects with
    * `NotAllowedError`. The caller is expected to latch and post a single
@@ -107,6 +112,9 @@ export function syncRuntimeMedia(params: {
    */
   onAutoplayBlocked?: () => void;
 }): void {
+  // Either flag silences output. Combined up front so the per-clip loop is
+  // a single branch instead of two.
+  const shouldMute = !!(params.outputMuted || params.userMuted);
   for (const clip of params.clips) {
     const { el } = clip;
     if (!el.isConnected) continue;
@@ -122,7 +130,7 @@ export function syncRuntimeMedia(params: {
         }
       }
       if (clip.volume != null) el.volume = clip.volume;
-      if (params.outputMuted) el.muted = true;
+      if (shouldMute) el.muted = true;
       try {
         // Per-element rate × global transport rate
         el.playbackRate = clip.playbackRate * params.playbackRate;
diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index fb45422fb..e39ea68e5 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -211,6 +211,60 @@ describe("HyperframesPlayer parent-frame media", () => {
     expect(player._audioOwner).toBe("parent");
   });
 
+  it("dispatches audioownershipchange on promotion", () => {
+    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
+    document.body.appendChild(player);
+
+    const events: Array<{ owner: string; reason: string }> = [];
+    player.addEventListener("audioownershipchange", (e: Event) => {
+      const detail = (e as CustomEvent<{ owner: string; reason: string }>).detail;
+      events.push(detail);
+    });
+
+    player._promoteToParentProxy?.();
+    expect(events).toEqual([{ owner: "parent", reason: "autoplay-blocked" }]);
+
+    // Second promote is idempotent — no duplicate event.
+    player._promoteToParentProxy?.();
+    expect(events).toHaveLength(1);
+  });
+
+  it("promotion mid-playback plays parent proxy immediately", () => {
+    // Previously-missing coverage: if the user is already playing when
+    // the runtime reports autoplay-blocked, the proxy must start audible
+    // right away — not wait for the user to hit pause/play again.
+    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
+    document.body.appendChild(player);
+
+    player.play(); // `_paused = false`, owner still `runtime` → no parent play yet
+    expect(mockAudio.play).not.toHaveBeenCalled();
+
+    player._promoteToParentProxy?.();
+    expect(mockAudio.play).toHaveBeenCalled();
+  });
+
+  it("surfaces playbackerror when parent proxy play() rejects", async () => {
+    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
+    document.body.appendChild(player);
+
+    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
+    mockAudio.play = vi.fn().mockRejectedValueOnce(rejection);
+
+    const errors: unknown[] = [];
+    player.addEventListener("playbackerror", (e: Event) => {
+      errors.push((e as CustomEvent).detail);
+    });
+
+    player._promoteToParentProxy?.();
+    player.play();
+    // Promise rejection delivered on a microtask — flush.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(errors.length).toBeGreaterThan(0);
+    expect((errors[0] as { source: string }).source).toBe("parent-proxy");
+  });
+
   it("cleans up parent media on disconnect", () => {
     player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
     document.body.appendChild(player);
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index c182de32b..bbb59ac64 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -62,6 +62,13 @@ class HyperframesPlayer extends HTMLElement {
    */
   private _audioOwner: "runtime" | "parent" = "runtime";
 
+  /**
+   * Watches the iframe document for sub-composition media added after
+   * initial setup. Disconnected on iframe reload (fresh iframe = fresh
+   * observer against the new document).
+   */
+  private _mediaObserver?: MutationObserver;
+
   constructor() {
     super();
     this.shadow = this.attachShadow({ mode: "open" });
@@ -114,6 +121,7 @@ class HyperframesPlayer extends HTMLElement {
     window.removeEventListener("message", this._onMessage);
     this.iframe.removeEventListener("load", this._onIframeLoad);
     if (this._probeInterval) clearInterval(this._probeInterval);
+    this._teardownMediaObserver();
     this.controlsApi?.destroy();
     for (const m of this._parentMedia) {
       m.el.pause();
@@ -366,6 +374,27 @@ class HyperframesPlayer extends HTMLElement {
   private _onIframeLoad() {
     let attempts = 0;
     this._runtimeInjected = false;
+    // A fresh iframe means a fresh runtime — `mediaOutputMuted` and the
+    // autoplay-blocked latch are both reset inside it. The web component's
+    // `_audioOwner` must reset to match, otherwise a composition switch on
+    // a previously-promoted player would leave the parent thinking it owns
+    // audio against a runtime that's happily playing the iframe copy again
+    // — briefly reintroducing the double-voice bug for one probe window.
+    // The next `NotAllowedError` (if any) will re-promote.
+    const wasPromoted = this._audioOwner === "parent";
+    this._audioOwner = "runtime";
+    this._pauseParentMedia();
+    // The old iframe document is about to go away. Disconnect the
+    // MutationObserver now so we don't hold a reference to it; a fresh
+    // one will attach once the new document settles in `_setupParentMedia`.
+    this._teardownMediaObserver();
+    if (wasPromoted) {
+      this.dispatchEvent(
+        new CustomEvent("audioownershipchange", {
+          detail: { owner: "runtime", reason: "iframe-reload" },
+        }),
+      );
+    }
     if (this._probeInterval) clearInterval(this._probeInterval);
 
     this._probeInterval = setInterval(() => {
@@ -527,10 +556,16 @@ class HyperframesPlayer extends HTMLElement {
   private _playParentMedia() {
     for (const m of this._parentMedia) {
       if (!m.el.src) continue;
-      // Best-effort: if the parent itself has no user activation, this will
-      // also reject — the caller has already decided parent ownership is
-      // warranted, and there's nothing better to fall back to from here.
-      m.el.play().catch(() => {});
+      // Under parent ownership the proxy is the only audible pipeline. If
+      // its `play()` rejects (rare — parent also lacks activation in some
+      // programmatic embed flows), swallowing silently leaves the viewer
+      // staring at motion with no audio and no signal. Surface it as a
+      // `playbackerror` event so host apps can recover or fall back.
+      m.el.play().catch((err: unknown) => {
+        this.dispatchEvent(
+          new CustomEvent("playbackerror", { detail: { source: "parent-proxy", error: err } }),
+        );
+      });
     }
   }
 
@@ -540,15 +575,22 @@ class HyperframesPlayer extends HTMLElement {
 
   /**
    * Drag parent-proxy `currentTime` onto the iframe's timeline. Called on
-   * every runtime state message under parent ownership. Only re-seeks when
-   * drift exceeds 150 ms so we don't trigger a re-buffer on every tick —
-   * native HTMLMediaElement playback rate drift stays well inside that.
+   * every runtime state message under parent ownership. Threshold is 50 ms
+   * — ITU-R BT.1359 puts A/V offset perceptibility at roughly ±45 ms, so
+   * anything looser risks audible lip-sync drift on talking-head content
+   * (a core use case). The re-seek cost at this tightness is a handful of
+   * extra `currentTime` writes per second; the media element's own buffer
+   * smooths them out without visible rebuffer on the mirror path.
    */
+  private static readonly MIRROR_DRIFT_THRESHOLD_SECONDS = 0.05;
+
   private _mirrorParentMediaTime(timelineSeconds: number) {
     for (const m of this._parentMedia) {
       const relTime = timelineSeconds - m.start;
       if (relTime < 0 || relTime >= m.duration) continue;
-      if (Math.abs(m.el.currentTime - relTime) > 0.15) m.el.currentTime = relTime;
+      if (Math.abs(m.el.currentTime - relTime) > HyperframesPlayer.MIRROR_DRIFT_THRESHOLD_SECONDS) {
+        m.el.currentTime = relTime;
+      }
     }
   }
 
@@ -571,9 +613,21 @@ class HyperframesPlayer extends HTMLElement {
   private _promoteToParentProxy() {
     if (this._audioOwner === "parent") return;
     this._audioOwner = "parent";
+    // `_sendControl` is async — the iframe won't see the mute for ~one
+    // message-loop tick. In that narrow window the runtime's next
+    // `syncRuntimeMedia` pass may still try `el.play()` on the iframe
+    // copy; we rely on the autoplay gate (which got us here in the first
+    // place) to keep rejecting until our mute lands. This is defensible
+    // precisely because the scenario that triggered promotion is
+    // "autoplay blocked" — the iframe can't make noise on its own.
     this._sendControl("set-media-output-muted", { muted: true });
     this._mirrorParentMediaTime(this._currentTime);
     if (!this._paused) this._playParentMedia();
+    this.dispatchEvent(
+      new CustomEvent("audioownershipchange", {
+        detail: { owner: "parent", reason: "autoplay-blocked" },
+      }),
+    );
   }
 
   /** Create a parent-frame media element, configure it, and start preloading. */
@@ -609,6 +663,13 @@ class HyperframesPlayer extends HTMLElement {
    * Under runtime ownership (the default) these proxies stay paused and
    * inert; the iframe is the audible source. Ownership flips only in
    * response to a real `media-autoplay-blocked` message from the runtime.
+   *
+   * Also installs a MutationObserver so that media added to the iframe
+   * *after* the initial scan (sub-composition activation is the common
+   * case) gets a proxy on the fly. Without this, under parent ownership
+   * late-added `<audio data-start>` would be silenced by the runtime
+   * (`outputMuted` sticks per-tick) but have no parent-frame counterpart
+   * to play — a silent hole in the audio track.
    */
   private _setupParentMedia() {
     try {
@@ -619,33 +680,98 @@ class HyperframesPlayer extends HTMLElement {
       const mediaEls = doc.querySelectorAll<HTMLMediaElement>(
         "audio[data-start], video[data-start]",
       );
+      for (const iframeEl of mediaEls) this._adoptIframeMedia(iframeEl);
 
-      for (const iframeEl of mediaEls) {
-        const rawSrc =
-          iframeEl.getAttribute("src") || iframeEl.querySelector("source")?.getAttribute("src");
-        if (!rawSrc) continue;
-
-        // Resolve against the iframe's baseURI. The parent-frame <audio>/<video>
-        // we create next lives in the host document, whose base URL differs from
-        // the iframe's — without this, a relative src like "assets/narration.wav"
-        // would resolve against the studio root and 404.
-        const src = new URL(rawSrc, iframeEl.ownerDocument.baseURI).href;
-
-        const start = parseFloat(iframeEl.getAttribute("data-start") || "0");
-        const duration = parseFloat(iframeEl.getAttribute("data-duration") || "Infinity");
-        const tag = iframeEl.tagName === "VIDEO" ? ("video" as const) : ("audio" as const);
-
-        this._createParentMedia(src, tag, start, duration);
-        // Iframe originals stay untouched — the runtime's `syncRuntimeMedia`
-        // queries `audio[data-start]` for state and needs them addressable.
-        // Their audible output is gated later by `set-media-output-muted`
-        // when (and only when) parent ownership is promoted.
-      }
+      this._observeDynamicMedia(doc);
     } catch {
       // Cross-origin iframe — can't access DOM, fall back to iframe media
     }
   }
 
+  /**
+   * Create a parent-frame proxy mirroring a single iframe media element.
+   * Extracted so both the initial scan and the MutationObserver path use
+   * identical URL-resolution and attribute parsing.
+   */
+  private _adoptIframeMedia(iframeEl: HTMLMediaElement): void {
+    const rawSrc =
+      iframeEl.getAttribute("src") || iframeEl.querySelector("source")?.getAttribute("src");
+    if (!rawSrc) return;
+
+    // Resolve against the iframe's baseURI. The parent-frame <audio>/<video>
+    // we create next lives in the host document, whose base URL differs from
+    // the iframe's — without this, a relative src like "assets/narration.wav"
+    // would resolve against the studio root and 404.
+    const src = new URL(rawSrc, iframeEl.ownerDocument.baseURI).href;
+
+    const start = parseFloat(iframeEl.getAttribute("data-start") || "0");
+    const duration = parseFloat(iframeEl.getAttribute("data-duration") || "Infinity");
+    const tag = iframeEl.tagName === "VIDEO" ? ("video" as const) : ("audio" as const);
+
+    const beforeCount = this._parentMedia.length;
+    this._createParentMedia(src, tag, start, duration);
+    const created = this._parentMedia.length > beforeCount;
+    // Iframe originals stay untouched — the runtime's `syncRuntimeMedia`
+    // queries `audio[data-start]` for state and needs them addressable.
+    // Their audible output is gated later by `set-media-output-muted` when
+    // (and only when) parent ownership is promoted.
+
+    // If we're already under parent ownership and the player is playing,
+    // the new proxy needs to pick up where the timeline currently is and
+    // start producing audio right away — otherwise it sits silent through
+    // the next several hundred ms until the next runtime state message.
+    if (created && this._audioOwner === "parent") {
+      this._mirrorParentMediaTime(this._currentTime);
+      if (!this._paused) {
+        const last = this._parentMedia[this._parentMedia.length - 1];
+        if (last && last.el.src) {
+          last.el.play().catch((err: unknown) => {
+            this.dispatchEvent(
+              new CustomEvent("playbackerror", { detail: { source: "parent-proxy", error: err } }),
+            );
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Watch the iframe document for subtree additions of timed media so
+   * sub-composition activation (late-attached `<audio data-start>`) grows
+   * the parent-proxy set automatically. Disconnected on iframe reload via
+   * `_teardownMediaObserver`.
+   */
+  private _observeDynamicMedia(doc: Document): void {
+    this._teardownMediaObserver();
+    if (typeof MutationObserver === "undefined" || !doc.body) return;
+    const obs = new MutationObserver((mutations) => {
+      for (const m of mutations) {
+        for (const added of m.addedNodes) {
+          if (!(added instanceof Element)) continue;
+          // Handle both the node itself and any timed media nested inside
+          // (sub-compositions typically inject a fragment whose root is a
+          // `<div data-composition-id=...>` with `<audio>` children).
+          const candidates: HTMLMediaElement[] = [];
+          if (added.matches?.("audio[data-start], video[data-start]")) {
+            candidates.push(added as HTMLMediaElement);
+          }
+          const inside = added.querySelectorAll?.<HTMLMediaElement>(
+            "audio[data-start], video[data-start]",
+          );
+          if (inside) for (const el of inside) candidates.push(el);
+          for (const el of candidates) this._adoptIframeMedia(el);
+        }
+      }
+    });
+    obs.observe(doc.body, { childList: true, subtree: true });
+    this._mediaObserver = obs;
+  }
+
+  private _teardownMediaObserver(): void {
+    this._mediaObserver?.disconnect();
+    this._mediaObserver = undefined;
+  }
+
   private _hidePoster() {
     this.posterEl?.remove();
     this.posterEl = null;

From 9afafc565dc3c01b57254dce52ac475b210c2565 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Fri, 17 Apr 2026 21:26:29 +0000
Subject: [PATCH 2/2] fix(player): latch playbackerror, handle removedNodes,
 typed _createParentMedia
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses #307 review feedback from @jrusso1020:

- playbackerror dedup: add `_playbackErrorPosted` one-shot latch so under
  parent ownership with parent-also-blocked, repeated paused→playing
  transitions don't spam hosts with one event per tick. Mirrors the
  runtime's `mediaAutoplayBlockedPosted` pattern. Cleared on iframe
  reload alongside the owner reset.
- MutationObserver removedNodes: symmetric detach path so unmounted
  sub-composition media doesn't leak parent-document `<audio>` nodes or
  leave orphaned proxies for `_playParentMedia` to iterate.
- `_createParentMedia` now returns the created entry (or null on dedup),
  removing the fragile length-delta + `[length - 1]` inference in the
  caller — refactor-safe if the creator ever emits >1 element.

Adds a regression test pinning the latch: three paused→playing cycles
under rejecting `play()` yield exactly one `playbackerror` event.
---
 .../player/src/hyperframes-player.test.ts     | 29 ++++++
 packages/player/src/hyperframes-player.ts     | 99 ++++++++++++++-----
 2 files changed, 106 insertions(+), 22 deletions(-)

diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index e39ea68e5..766b0a7d1 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -265,6 +265,35 @@ describe("HyperframesPlayer parent-frame media", () => {
     expect((errors[0] as { source: string }).source).toBe("parent-proxy");
   });
 
+  it("playbackerror dedup: fires at most once per parent-ownership session", async () => {
+    // Under parent ownership with parent-also-blocked, every iframe
+    // paused→playing transition in the state loop re-invokes `_playParentMedia`.
+    // Without a latch, each rejection would re-fire `playbackerror`, spamming
+    // subscribers. Mirrors the runtime's `mediaAutoplayBlockedPosted` latch.
+    player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
+    document.body.appendChild(player);
+
+    const rejection = Object.assign(new Error("blocked"), { name: "NotAllowedError" });
+    mockAudio.play = vi.fn().mockRejectedValue(rejection);
+
+    const errors: unknown[] = [];
+    player.addEventListener("playbackerror", (e: Event) => {
+      errors.push((e as CustomEvent).detail);
+    });
+
+    player._promoteToParentProxy?.();
+    player.play();
+    player.pause();
+    player.play();
+    player.pause();
+    player.play();
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(errors).toHaveLength(1);
+  });
+
   it("cleans up parent media on disconnect", () => {
     player.setAttribute("audio-src", "https://cdn.example.com/narration.mp3");
     document.body.appendChild(player);
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index bbb59ac64..b9503fe20 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -69,6 +69,17 @@ class HyperframesPlayer extends HTMLElement {
    */
   private _mediaObserver?: MutationObserver;
 
+  /**
+   * One-shot latch for `playbackerror`. Without it, under parent ownership
+   * where the parent frame itself lacks activation, every paused→playing
+   * transition in the iframe state loop would re-fire `play()` (and its
+   * rejection) on each proxy — spamming host subscribers through a whole
+   * playback session. Mirrors the `mediaAutoplayBlockedPosted` latch on the
+   * runtime side. Cleared on `_onIframeLoad` alongside the owner reset, so
+   * a fresh composition gets a fresh shot at surfacing the error.
+   */
+  private _playbackErrorPosted = false;
+
   constructor() {
     super();
     this.shadow = this.attachShadow({ mode: "open" });
@@ -383,6 +394,7 @@ class HyperframesPlayer extends HTMLElement {
     // The next `NotAllowedError` (if any) will re-promote.
     const wasPromoted = this._audioOwner === "parent";
     this._audioOwner = "runtime";
+    this._playbackErrorPosted = false;
     this._pauseParentMedia();
     // The old iframe document is about to go away. Disconnect the
     // MutationObserver now so we don't hold a reference to it; a fresh
@@ -560,15 +572,20 @@ class HyperframesPlayer extends HTMLElement {
       // its `play()` rejects (rare — parent also lacks activation in some
       // programmatic embed flows), swallowing silently leaves the viewer
       // staring at motion with no audio and no signal. Surface it as a
-      // `playbackerror` event so host apps can recover or fall back.
-      m.el.play().catch((err: unknown) => {
-        this.dispatchEvent(
-          new CustomEvent("playbackerror", { detail: { source: "parent-proxy", error: err } }),
-        );
-      });
+      // `playbackerror` event — but only once per parent-ownership session;
+      // see `_playbackErrorPosted` for why.
+      m.el.play().catch((err: unknown) => this._reportPlaybackError(err));
     }
   }
 
+  private _reportPlaybackError(err: unknown) {
+    if (this._playbackErrorPosted) return;
+    this._playbackErrorPosted = true;
+    this.dispatchEvent(
+      new CustomEvent("playbackerror", { detail: { source: "parent-proxy", error: err } }),
+    );
+  }
+
   private _pauseParentMedia() {
     for (const m of this._parentMedia) m.el.pause();
   }
@@ -630,10 +647,20 @@ class HyperframesPlayer extends HTMLElement {
     );
   }
 
-  /** Create a parent-frame media element, configure it, and start preloading. */
-  private _createParentMedia(src: string, tag: "audio" | "video", start: number, duration: number) {
+  /**
+   * Create a parent-frame media element, configure it, and start preloading.
+   * Returns the newly-created proxy entry, or `null` if one already exists for
+   * this src (dedup) — callers that need to act on the new element should
+   * branch on the return value rather than inferring via `_parentMedia.length`.
+   */
+  private _createParentMedia(
+    src: string,
+    tag: "audio" | "video",
+    start: number,
+    duration: number,
+  ): { el: HTMLMediaElement; start: number; duration: number } | null {
     // Deduplicate — browsers normalize URLs so we compare on the element after assignment
-    if (this._parentMedia.some((m) => m.el.src === src)) return;
+    if (this._parentMedia.some((m) => m.el.src === src)) return null;
 
     const el = tag === "video" ? document.createElement("video") : new Audio();
     el.preload = "auto";
@@ -642,7 +669,9 @@ class HyperframesPlayer extends HTMLElement {
     el.muted = this.muted;
     if (this.playbackRate !== 1) el.playbackRate = this.playbackRate;
 
-    this._parentMedia.push({ el, start, duration });
+    const entry = { el, start, duration };
+    this._parentMedia.push(entry);
+    return entry;
   }
 
   /**
@@ -708,9 +737,7 @@ class HyperframesPlayer extends HTMLElement {
     const duration = parseFloat(iframeEl.getAttribute("data-duration") || "Infinity");
     const tag = iframeEl.tagName === "VIDEO" ? ("video" as const) : ("audio" as const);
 
-    const beforeCount = this._parentMedia.length;
-    this._createParentMedia(src, tag, start, duration);
-    const created = this._parentMedia.length > beforeCount;
+    const created = this._createParentMedia(src, tag, start, duration);
     // Iframe originals stay untouched — the runtime's `syncRuntimeMedia`
     // queries `audio[data-start]` for state and needs them addressable.
     // Their audible output is gated later by `set-media-output-muted` when
@@ -722,15 +749,8 @@ class HyperframesPlayer extends HTMLElement {
     // the next several hundred ms until the next runtime state message.
     if (created && this._audioOwner === "parent") {
       this._mirrorParentMediaTime(this._currentTime);
-      if (!this._paused) {
-        const last = this._parentMedia[this._parentMedia.length - 1];
-        if (last && last.el.src) {
-          last.el.play().catch((err: unknown) => {
-            this.dispatchEvent(
-              new CustomEvent("playbackerror", { detail: { source: "parent-proxy", error: err } }),
-            );
-          });
-        }
+      if (!this._paused && created.el.src) {
+        created.el.play().catch((err: unknown) => this._reportPlaybackError(err));
       }
     }
   }
@@ -761,6 +781,23 @@ class HyperframesPlayer extends HTMLElement {
           if (inside) for (const el of inside) candidates.push(el);
           for (const el of candidates) this._adoptIframeMedia(el);
         }
+        for (const removed of m.removedNodes) {
+          if (!(removed instanceof Element)) continue;
+          // Symmetric detach: when a sub-composition unmounts, the iframe
+          // media it owned is gone but our parent proxies would otherwise
+          // linger — accumulating host-document <audio> elements and, under
+          // parent ownership, still being played by `_playParentMedia` as
+          // orphans. Match by resolved URL (same resolution as adoption).
+          const dropped: HTMLMediaElement[] = [];
+          if (removed.matches?.("audio[data-start], video[data-start]")) {
+            dropped.push(removed as HTMLMediaElement);
+          }
+          const inside = removed.querySelectorAll?.<HTMLMediaElement>(
+            "audio[data-start], video[data-start]",
+          );
+          if (inside) for (const el of inside) dropped.push(el);
+          for (const el of dropped) this._detachIframeMedia(el);
+        }
       }
     });
     obs.observe(doc.body, { childList: true, subtree: true });
@@ -772,6 +809,24 @@ class HyperframesPlayer extends HTMLElement {
     this._mediaObserver = undefined;
   }
 
+  /**
+   * Inverse of `_adoptIframeMedia`: drop the parent proxy mirroring a removed
+   * iframe media element. Resolves the src identically so matching is exact,
+   * then pauses, clears the src (frees the decoder), and splices it out.
+   */
+  private _detachIframeMedia(iframeEl: HTMLMediaElement): void {
+    const rawSrc =
+      iframeEl.getAttribute("src") || iframeEl.querySelector("source")?.getAttribute("src");
+    if (!rawSrc) return;
+    const src = new URL(rawSrc, iframeEl.ownerDocument.baseURI).href;
+    const idx = this._parentMedia.findIndex((m) => m.el.src === src);
+    if (idx === -1) return;
+    const entry = this._parentMedia[idx];
+    entry.el.pause();
+    entry.el.src = "";
+    this._parentMedia.splice(idx, 1);
+  }
+
   private _hidePoster() {
     this.posterEl?.remove();
     this.posterEl = null;