From 8edf799dbd3b0700728a3d6f3b740551e082ec01 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 21 Apr 2026 01:00:59 -0700
Subject: [PATCH 1/4] perf(player): scope MutationObserver to composition hosts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The player previously observed `iframe.contentDocument.body` wholesale to
catch sub-composition `<audio data-start>` elements added after initial
mount. That fired for every body-level mutation — analytics scripts,
runtime telemetry markers, dev overlays — even though only composition
subtrees can introduce new timed media.

Replace the body-wide observer with a per-host observer scoped to the
top-level `[data-composition-id]` elements selected by the new internal
`selectMediaObserverTargets` helper. A single MutationObserver instance
is attached to each top-level host (subtree: true), so callbacks still
batch across hosts but skip out-of-host noise. Falls back to observing
`body` when no composition hosts exist (e.g. blank iframe between src
changes) to preserve the prior behavior for non-composition documents.

Also filter out `[data-composition-id]` hosts that are themselves nested
inside another composition host — those are sub-compositions whose
media is already covered by the parent observer, so observing them
separately would double-fire on every mutation.

Tests: 8 new unit tests in mediaObserverScope.test.ts covering empty
docs, single/multiple hosts, nested-host filtering, and body fallback;
2 new integration tests in hyperframes-player.test.ts spying on
`MutationObserver.prototype.observe` to confirm targets and options.
---
 .../player/src/hyperframes-player.test.ts     |  78 ++++++++++++++
 .../player/src/mediaObserverScope.test.ts     | 102 ++++++++++++++++++
 packages/player/src/mediaObserverScope.ts     |  54 ++++++++++
 3 files changed, 234 insertions(+)
 create mode 100644 packages/player/src/mediaObserverScope.test.ts
 create mode 100644 packages/player/src/mediaObserverScope.ts

diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index 3d86de851..c55e3f7d3 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -362,3 +362,81 @@ describe("HyperframesPlayer adoptedStyleSheets", () => {
     expect(player.shadowRoot?.querySelector("style")).toBeNull();
   });
 });
+
+// ── Media MutationObserver scoping ──
+//
+// The observer that catches late-attached `<audio data-start>` from
+// sub-composition activation used to watch `iframe.contentDocument.body`
+// wholesale. That fired on every body-level mutation — analytics scripts,
+// runtime telemetry markers, dev-only overlays — even though only
+// composition-tree changes can introduce new timed media. The fix is to
+// scope per top-level composition host (see `selectMediaObserverTargets`);
+// these tests verify the player honors that scoping.
+
+describe("HyperframesPlayer media MutationObserver scoping", () => {
+  type PlayerInternal = HTMLElement & {
+    _observeDynamicMedia?: (doc: Document) => void;
+  };
+
+  beforeEach(async () => {
+    await import("./hyperframes-player.js");
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("attaches the observer to each top-level composition host (not the body)", () => {
+    const observeSpy = vi.spyOn(MutationObserver.prototype, "observe");
+
+    const player = document.createElement("hyperframes-player") as PlayerInternal;
+    document.body.appendChild(player);
+    // The constructor doesn't install an observer — only `_observeDynamicMedia`
+    // does — so the spy starts clean for the call we care about.
+    observeSpy.mockClear();
+
+    // Simulates the iframe document the runtime hands the player after mount.
+    // Bypassing the iframe lifecycle keeps the test deterministic; the
+    // selection logic itself is exercised in `mediaObserverScope.test.ts`.
+    const fakeDoc = document.implementation.createHTMLDocument("test");
+    fakeDoc.body.innerHTML = `
+      <div data-composition-id="root-a"></div>
+      <div data-composition-id="root-b"></div>
+      <script>// runtime telemetry — body-level, must NOT be observed</script>
+    `;
+
+    player._observeDynamicMedia?.(fakeDoc);
+
+    expect(observeSpy).toHaveBeenCalledTimes(2);
+    const observedTargets = observeSpy.mock.calls.map((call) => call[0]);
+    expect(observedTargets.map((t) => (t as Element).getAttribute("data-composition-id"))).toEqual([
+      "root-a",
+      "root-b",
+    ]);
+    expect(observedTargets).not.toContain(fakeDoc.body);
+    // Subtree is still required — sub-composition media can be deeply nested
+    // inside the host (e.g. wrapper div around the `<audio>`).
+    for (const call of observeSpy.mock.calls) {
+      expect(call[1]).toEqual({ childList: true, subtree: true });
+    }
+  });
+
+  it("falls back to observing the document body when no composition hosts exist", () => {
+    // Preserves the legacy behavior for documents that haven't bootstrapped
+    // a composition tree yet (e.g. a blank iframe between src changes).
+    const observeSpy = vi.spyOn(MutationObserver.prototype, "observe");
+
+    const player = document.createElement("hyperframes-player") as PlayerInternal;
+    document.body.appendChild(player);
+    observeSpy.mockClear();
+
+    const fakeDoc = document.implementation.createHTMLDocument("test");
+    fakeDoc.body.innerHTML = `<div class="not-a-composition"></div>`;
+
+    player._observeDynamicMedia?.(fakeDoc);
+
+    expect(observeSpy).toHaveBeenCalledTimes(1);
+    expect(observeSpy.mock.calls[0]?.[0]).toBe(fakeDoc.body);
+  });
+});
diff --git a/packages/player/src/mediaObserverScope.test.ts b/packages/player/src/mediaObserverScope.test.ts
new file mode 100644
index 000000000..aab385175
--- /dev/null
+++ b/packages/player/src/mediaObserverScope.test.ts
@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { selectMediaObserverTargets } from "./mediaObserverScope.js";
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function makeDoc(html: string): Document {
+  // happy-dom doesn't ship a usable XMLHttpRequest path for parser-driven
+  // doc creation, so we build a fresh document by hand and inject markup
+  // through the body — same DOM shape the iframe document will have when
+  // the runtime finishes mounting compositions.
+  const doc = document.implementation.createHTMLDocument("test");
+  doc.body.innerHTML = html;
+  return doc;
+}
+
+describe("selectMediaObserverTargets", () => {
+  it("returns the single root composition host", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root"></div>
+    `);
+
+    const targets = selectMediaObserverTargets(doc);
+
+    expect(targets).toHaveLength(1);
+    expect(targets[0]?.getAttribute("data-composition-id")).toBe("root");
+  });
+
+  it("returns only top-level hosts when sub-composition hosts are nested", () => {
+    // Mirrors the runtime structure: root host with a sub-composition host
+    // mounted inside it. The nested host is already covered by the root
+    // host's subtree observation.
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div data-composition-id="sub-1"></div>
+        <div>
+          <div data-composition-id="sub-2"></div>
+        </div>
+      </div>
+    `);
+
+    const targets = selectMediaObserverTargets(doc);
+
+    expect(targets).toHaveLength(1);
+    expect(targets[0]?.getAttribute("data-composition-id")).toBe("root");
+  });
+
+  it("returns multiple hosts when they are siblings (no shared ancestor host)", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="comp-a"></div>
+      <div data-composition-id="comp-b"></div>
+    `);
+
+    const targets = selectMediaObserverTargets(doc);
+
+    expect(targets).toHaveLength(2);
+    expect(targets.map((t) => t.getAttribute("data-composition-id"))).toEqual(["comp-a", "comp-b"]);
+  });
+
+  it("ignores attribute presence on intermediate non-host elements", () => {
+    // Only `data-composition-id` is meaningful; an unrelated `data-composition`
+    // attribute on a wrapper must not promote a nested host to top-level.
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div data-composition="not-a-host">
+          <div data-composition-id="sub"></div>
+        </div>
+      </div>
+    `);
+
+    const targets = selectMediaObserverTargets(doc);
+
+    expect(targets).toHaveLength(1);
+    expect(targets[0]?.getAttribute("data-composition-id")).toBe("root");
+  });
+
+  it("falls back to the document body when no composition hosts exist", () => {
+    // Documents that haven't been bootstrapped (or never will be) keep the
+    // legacy behavior so adoption logic still runs against late additions.
+    const doc = makeDoc(`<div class="not-a-composition"></div>`);
+
+    const targets = selectMediaObserverTargets(doc);
+
+    expect(targets).toEqual([doc.body]);
+  });
+
+  it("returns an empty array when neither hosts nor body are available", () => {
+    // Synthetic edge case — guards the caller against attaching an observer
+    // to `undefined` if the document is missing both signals. happy-dom
+    // auto-fills `<body>`, so we hand-roll a minimal Document shape rather
+    // than fight the runtime.
+    const doc = {
+      body: null,
+      querySelectorAll: () => [],
+    } as unknown as Document;
+
+    const targets = selectMediaObserverTargets(doc);
+
+    expect(targets).toEqual([]);
+  });
+});
diff --git a/packages/player/src/mediaObserverScope.ts b/packages/player/src/mediaObserverScope.ts
new file mode 100644
index 000000000..0ccff40ac
--- /dev/null
+++ b/packages/player/src/mediaObserverScope.ts
@@ -0,0 +1,54 @@
+/**
+ * Internal helper for scoping the player's media MutationObserver to the
+ * composition tree inside the iframe.
+ *
+ * Not part of the package's public API — kept in its own module so the
+ * decision logic can be exercised by unit tests without exposing it through
+ * the player entry point.
+ */
+
+/**
+ * Pick the elements inside `doc` that the media MutationObserver should
+ * attach to.
+ *
+ * Compositions mount inside `[data-composition-id]` host elements — the
+ * runtime root and any sub-composition hosts that `compositionLoader` writes
+ * into them. Watching only those hosts (with `subtree: true`) catches every
+ * late-arriving timed media element from sub-composition activation, while
+ * filtering out churn from analytics tags, runtime telemetry markers, and
+ * other out-of-host nodes that the runtime appends straight to `<body>`
+ * during bootstrap.
+ *
+ * Nested hosts are filtered out — they're already covered by their nearest
+ * host ancestor's subtree observation, so observing them too would deliver
+ * each callback twice and double-count adoption work.
+ *
+ * Falls back to `[doc.body]` when no composition hosts are present, which
+ * preserves the previous behavior for documents that aren't yet (or never
+ * will be) composition-structured. Returns an empty array when neither a
+ * host nor a body is available — the caller should treat that as "nothing
+ * to observe".
+ */
+export function selectMediaObserverTargets(doc: Document): Element[] {
+  const all = Array.from(doc.querySelectorAll<Element>("[data-composition-id]"));
+  if (all.length === 0) {
+    return doc.body ? [doc.body] : [];
+  }
+
+  const topLevel: Element[] = [];
+  for (const el of all) {
+    if (!hasCompositionAncestor(el)) {
+      topLevel.push(el);
+    }
+  }
+  return topLevel;
+}
+
+function hasCompositionAncestor(el: Element): boolean {
+  let cursor = el.parentElement;
+  while (cursor) {
+    if (cursor.hasAttribute("data-composition-id")) return true;
+    cursor = cursor.parentElement;
+  }
+  return false;
+}

From c16e2dd9df6ebed25ceab4984c8b5f9ba146616e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 21 Apr 2026 17:36:17 -0700
Subject: [PATCH 2/4] perf(player): warn when scoped observer skips body-level
 timed media

Reviewer feedback on PR #395: when composition hosts are present we now
attach the MutationObserver only to those subtrees, so any
`<audio data-start>` / `<video data-start>` injected at body level (or
under a non-host wrapper) will silently never get a parent-frame proxy.
Today no runtime path produces that shape, but if one ever does the
failure mode is "audio just doesn't play" with no diagnostic trail.

Add a forensic guard in `selectMediaObserverTargets`: when the scoped
path is taken, walk the body for `[data-start]` audio/video that has no
`[data-composition-id]` ancestor and emit a single `console.warn` with
the orphan elements. The walk is cheap (one typed `querySelectorAll` +
a `closest` per match) and only runs on the scoped branch, so the
no-host fallback retains its legacy behavior with zero extra work.

Tests cover the four meaningful states: scoped + body orphan (warn),
scoped + media inside host (no warn), no-host fallback (no warn even
with body media), and untimed body media (no warn).

Made-with: Cursor
---
 .../player/src/mediaObserverScope.test.ts     | 92 ++++++++++++++++++-
 packages/player/src/mediaObserverScope.ts     | 45 +++++++++
 2 files changed, 136 insertions(+), 1 deletion(-)

diff --git a/packages/player/src/mediaObserverScope.test.ts b/packages/player/src/mediaObserverScope.test.ts
index aab385175..b2a09da74 100644
--- a/packages/player/src/mediaObserverScope.test.ts
+++ b/packages/player/src/mediaObserverScope.test.ts
@@ -1,8 +1,9 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { selectMediaObserverTargets } from "./mediaObserverScope.js";
 
 afterEach(() => {
   document.body.innerHTML = "";
+  vi.restoreAllMocks();
 });
 
 function makeDoc(html: string): Document {
@@ -99,4 +100,93 @@ describe("selectMediaObserverTargets", () => {
 
     expect(targets).toEqual([]);
   });
+
+  describe("body-fallback collision warning", () => {
+    it("warns when scoped observation skips body-level timed media", () => {
+      // Composition host present → scoped path. The body-level <audio data-start>
+      // is outside every host subtree, so the observer would never see it.
+      // This is precisely the silent-miss the warning is designed to surface.
+      const doc = makeDoc(`
+        <audio data-start="0" src="theme.mp3"></audio>
+        <div data-composition-id="root">
+          <video data-start="1" src="hero.mp4"></video>
+        </div>
+      `);
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      selectMediaObserverTargets(doc);
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      const [message, orphans] = warn.mock.calls[0] ?? [];
+      expect(typeof message).toBe("string");
+      expect(message).toContain("body-level timed media");
+      expect(Array.isArray(orphans)).toBe(true);
+      expect((orphans as Element[]).map((el) => el.tagName)).toEqual(["AUDIO"]);
+    });
+
+    it("does not warn when every body-level timed media element lives inside a host", () => {
+      // Same body-level audio as above, but now nested under a composition
+      // host — the scoped observer will pick it up via the host subtree, so
+      // there's no silent-miss to flag.
+      const doc = makeDoc(`
+        <div data-composition-id="root">
+          <audio data-start="0" src="theme.mp3"></audio>
+          <video data-start="1" src="hero.mp4"></video>
+        </div>
+      `);
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      selectMediaObserverTargets(doc);
+
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it("does not warn on the body-fallback path even with orphan timed media", () => {
+      // No composition hosts → fallback observer attaches to `doc.body`, which
+      // already covers any body-level media. Emitting the warning here would
+      // be noise on every legacy / pre-bootstrap document.
+      const doc = makeDoc(`
+        <audio data-start="0" src="theme.mp3"></audio>
+      `);
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      selectMediaObserverTargets(doc);
+
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it("ignores body-level audio/video that are not timed (no data-start)", () => {
+      // Untimed media isn't part of the time-sync pipeline, so it doesn't
+      // matter whether the observer sees it. Only `[data-start]` orphans
+      // qualify as a silent miss worth surfacing.
+      const doc = makeDoc(`
+        <audio src="ambient.mp3"></audio>
+        <div data-composition-id="root"></div>
+      `);
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      selectMediaObserverTargets(doc);
+
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it("emits a single warn for multiple orphaned timed media elements", () => {
+      // The whole point of the forensic guard is to give a single, batched
+      // signal. Spamming one warn per orphan would drown out the diagnostic
+      // value on documents with many late-bound clips.
+      const doc = makeDoc(`
+        <audio data-start="0" src="a.mp3"></audio>
+        <video data-start="1" src="b.mp4"></video>
+        <audio data-start="2" src="c.mp3"></audio>
+        <div data-composition-id="root"></div>
+      `);
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      selectMediaObserverTargets(doc);
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      const [, orphans] = warn.mock.calls[0] ?? [];
+      expect((orphans as Element[]).map((el) => el.tagName)).toEqual(["AUDIO", "VIDEO", "AUDIO"]);
+    });
+  });
 });
diff --git a/packages/player/src/mediaObserverScope.ts b/packages/player/src/mediaObserverScope.ts
index 0ccff40ac..26e6ef144 100644
--- a/packages/player/src/mediaObserverScope.ts
+++ b/packages/player/src/mediaObserverScope.ts
@@ -28,6 +28,14 @@
  * will be) composition-structured. Returns an empty array when neither a
  * host nor a body is available — the caller should treat that as "nothing
  * to observe".
+ *
+ * When the scoped path is taken but the body still carries timed media
+ * outside every host, a `console.warn` fires once per call as a forensic
+ * signal: the new scope skips that media, so any `<audio data-start>` /
+ * `<video data-start>` injected at body level will silently never get a
+ * parent-frame proxy. Today every runtime path appends inside a host so
+ * this branch shouldn't trip; if it does, the warn surfaces the drift
+ * immediately rather than presenting as a missing-audio bug downstream.
  */
 export function selectMediaObserverTargets(doc: Document): Element[] {
   const all = Array.from(doc.querySelectorAll<Element>("[data-composition-id]"));
@@ -41,9 +49,46 @@ export function selectMediaObserverTargets(doc: Document): Element[] {
       topLevel.push(el);
     }
   }
+
+  warnOnUnscopedTimedMedia(doc);
   return topLevel;
 }
 
+/**
+ * Forensic guard: with composition hosts present the observer attaches only
+ * to those subtrees, so any timed media sitting at body level (or under a
+ * non-host wrapper) is invisible to the adoption pipeline. Walk the body for
+ * `[data-start]` audio/video that has no `[data-composition-id]` ancestor
+ * and emit a single `console.warn` listing the orphans. The walk is cheap
+ * (one `querySelectorAll` over a typed selector + a `closest` per match)
+ * and only runs on the scoped path, so the no-host fallback retains its
+ * legacy behavior with zero extra work.
+ */
+function warnOnUnscopedTimedMedia(doc: Document): void {
+  const body = doc.body;
+  if (!body) return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+
+  const candidates = body.querySelectorAll<HTMLMediaElement>(
+    "audio[data-start], video[data-start]",
+  );
+  if (candidates.length === 0) return;
+
+  const orphans: HTMLMediaElement[] = [];
+  for (const el of candidates) {
+    if (!el.closest("[data-composition-id]")) orphans.push(el);
+  }
+  if (orphans.length === 0) return;
+
+  console.warn(
+    "[hyperframes-player] selectMediaObserverTargets: composition hosts are present, " +
+      `but ${orphans.length} body-level timed media element(s) sit outside every ` +
+      "[data-composition-id] subtree and will not be observed. Move them inside a " +
+      "composition host or the parent-frame proxy will never adopt them.",
+    orphans,
+  );
+}
+
 function hasCompositionAncestor(el: Element): boolean {
   let cursor = el.parentElement;
   while (cursor) {

From bc1d71cc47ef83c00d4329c825702332fd7363b3 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 22 Apr 2026 16:29:08 -0700
Subject: [PATCH 3/4] force


From 292ec9e00c6fcb3a9cd82e607cf17f8b14aea450 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 22 Apr 2026 16:40:49 -0700
Subject: [PATCH 4/4] fix: text

---
 packages/player/src/hyperframes-player.ts | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index e51e23f89..dee146015 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -830,7 +830,14 @@ class HyperframesPlayer extends HTMLElement {
         }
       }
     });
-    obs.observe(doc.body, { childList: true, subtree: true });
+    const hosts = doc.querySelectorAll("[data-composition-id]");
+    if (hosts.length > 0) {
+      for (const host of hosts) {
+        obs.observe(host, { childList: true, subtree: true });
+      }
+    } else {
+      obs.observe(doc.body, { childList: true, subtree: true });
+    }
     this._mediaObserver = obs;
   }