From 224caf8f49e38a87674dc8d45344812239318d34 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 09:56:41 -0700
Subject: [PATCH 1/7] feat(player): report runtime data application

---
 packages/core/src/runtime/init.ts               | 10 +++++++++-
 packages/core/src/runtime/runtimeData.test.ts   | 17 +++++++++++++++++
 packages/core/src/runtime/runtimeData.ts        | 14 ++++++++++++--
 packages/core/src/runtime/types.ts              |  7 +++++++
 .../player/src/runtime-message-handler.test.ts  | 16 ++++++++++++++++
 packages/player/src/runtime-message-handler.ts  |  7 +++++++
 6 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 831fccce11..b6d3a80582 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -62,7 +62,12 @@ import { shouldAttemptPeriodicTimelineBind } from "./timelineRebindPolicy";
 import { installStudioCustomEase } from "./customEase";
 import { parseNumeric } from "./startExpression";
 import { parseStrictFiniteTimingNumber } from "./playbackRate";
-import { clearRuntimeData, setRuntimeData, setRuntimeDataErrorReporter } from "./runtimeData";
+import {
+  clearRuntimeData,
+  setRuntimeData,
+  setRuntimeDataAppliedReporter,
+  setRuntimeDataErrorReporter,
+} from "./runtimeData";
 
 const AUTHORED_DURATION_ATTR = "data-hf-authored-duration";
 const AUTHORED_END_ATTR = "data-hf-authored-end";
@@ -136,6 +141,9 @@ export function initSandboxRuntimeModular(): void {
       message: error instanceof Error ? error.message : String(error),
     });
   });
+  setRuntimeDataAppliedReporter((channel) => {
+    postRuntimeMessage({ source: "hf-preview", type: "runtime-data-applied", channel });
+  });
   // SDK moveElement edits must render even when no usable GSAP timeline ever
   // binds (CSS/WAAPI-animated or fully static compositions) — apply at init.
   // This runs at DOMContentLoaded, after inline composition scripts have
diff --git a/packages/core/src/runtime/runtimeData.test.ts b/packages/core/src/runtime/runtimeData.test.ts
index 60efc255ee..ac3d949e82 100644
--- a/packages/core/src/runtime/runtimeData.test.ts
+++ b/packages/core/src/runtime/runtimeData.test.ts
@@ -4,6 +4,7 @@ import {
   registerRuntimeDataHandler,
   resetRuntimeDataForTests,
   setRuntimeData,
+  setRuntimeDataAppliedReporter,
   setRuntimeDataErrorReporter,
 } from "./runtimeData";
 
@@ -50,4 +51,20 @@ describe("runtime data registry", () => {
     expect(() => setRuntimeData("captions", {})).not.toThrow();
     expect(reporter).toHaveBeenCalledWith("captions", expect.any(Error));
   });
+
+  it("reports asynchronous completion and rejection", async () => {
+    const applied = vi.fn();
+    const failed = vi.fn();
+    setRuntimeDataAppliedReporter(applied);
+    setRuntimeDataErrorReporter(failed);
+    registerRuntimeDataHandler("captions", async (payload) => {
+      await Promise.resolve();
+      if (payload === "bad") throw new Error("async attach failed");
+    });
+
+    setRuntimeData("captions", "good");
+    await vi.waitFor(() => expect(applied).toHaveBeenCalledWith("captions"));
+    setRuntimeData("captions", "bad");
+    await vi.waitFor(() => expect(failed).toHaveBeenCalledWith("captions", expect.any(Error)));
+  });
 });
diff --git a/packages/core/src/runtime/runtimeData.ts b/packages/core/src/runtime/runtimeData.ts
index d088bd8be7..9fb0f9cac0 100644
--- a/packages/core/src/runtime/runtimeData.ts
+++ b/packages/core/src/runtime/runtimeData.ts
@@ -1,9 +1,11 @@
-export type RuntimeDataHandler = (payload: unknown) => void;
+export type RuntimeDataHandler = (payload: unknown) => void | Promise<void>;
 export type RuntimeDataErrorReporter = (channel: string, error: unknown) => void;
+export type RuntimeDataAppliedReporter = (channel: string) => void;
 
 const retained = new Map<string, unknown>();
 const handlers = new Map<string, RuntimeDataHandler>();
 let reportError: RuntimeDataErrorReporter = () => undefined;
+let reportApplied: RuntimeDataAppliedReporter = () => undefined;
 
 function validChannel(channel: string): boolean {
   return /^[a-z][a-z0-9-]{0,63}$/.test(channel);
@@ -13,7 +15,10 @@ function deliver(channel: string, payload: unknown): void {
   const handler = handlers.get(channel);
   if (!handler) return;
   try {
-    handler(payload);
+    void Promise.resolve(handler(payload)).then(
+      () => reportApplied(channel),
+      (error) => reportError(channel, error),
+    );
   } catch (error) {
     reportError(channel, error);
   }
@@ -23,6 +28,10 @@ export function setRuntimeDataErrorReporter(reporter: RuntimeDataErrorReporter):
   reportError = reporter;
 }
 
+export function setRuntimeDataAppliedReporter(reporter: RuntimeDataAppliedReporter): void {
+  reportApplied = reporter;
+}
+
 export function setRuntimeData(channel: string, payload: unknown): void {
   if (!validChannel(channel)) return;
   retained.set(channel, payload);
@@ -52,4 +61,5 @@ export function resetRuntimeDataForTests(): void {
   retained.clear();
   handlers.clear();
   reportError = () => undefined;
+  reportApplied = () => undefined;
 }
diff --git a/packages/core/src/runtime/types.ts b/packages/core/src/runtime/types.ts
index 5e98822fa5..9c3afc9bd7 100644
--- a/packages/core/src/runtime/types.ts
+++ b/packages/core/src/runtime/types.ts
@@ -178,6 +178,12 @@ export type RuntimeDataErrorMessage = {
   message: string;
 };
 
+export type RuntimeDataAppliedMessage = {
+  source: "hf-preview";
+  type: "runtime-data-applied";
+  channel: string;
+};
+
 /**
  * Analytics events emitted by the runtime.
  *
@@ -229,6 +235,7 @@ export type RuntimeOutboundMessage =
   | RuntimeMediaAutoplayBlockedMessage
   | RuntimeReadyMessage
   | RuntimeDataErrorMessage
+  | RuntimeDataAppliedMessage
   | RuntimeAnalyticsMessage
   | RuntimePerformanceMessage
   | RuntimeGroupLevelsMessage;
diff --git a/packages/player/src/runtime-message-handler.test.ts b/packages/player/src/runtime-message-handler.test.ts
index f463c5f65c..84aa73b297 100644
--- a/packages/player/src/runtime-message-handler.test.ts
+++ b/packages/player/src/runtime-message-handler.test.ts
@@ -92,6 +92,22 @@ describe("handleRuntimeMessage runtime data errors", () => {
       expect.objectContaining({ type: "runtimedataerror" }),
     );
   });
+
+  it("surfaces successful channel application", () => {
+    const frameWindow = {} as Window;
+    const callbacks = makeCallbacks();
+    handleRuntimeMessage(
+      {
+        source: frameWindow,
+        data: { source: "hf-preview", type: "runtime-data-applied", channel: "captions" },
+      } as MessageEvent,
+      frameWindow,
+      callbacks,
+    );
+    expect(callbacks.dispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "runtimedataapplied" }),
+    );
+  });
 });
 
 describe("handleRuntimeMessage media autoplay fallback", () => {
diff --git a/packages/player/src/runtime-message-handler.ts b/packages/player/src/runtime-message-handler.ts
index 47d1335f68..4fd991b08c 100644
--- a/packages/player/src/runtime-message-handler.ts
+++ b/packages/player/src/runtime-message-handler.ts
@@ -101,6 +101,13 @@ export function handleRuntimeMessage(
     return;
   }
 
+  if (data["type"] === "runtime-data-applied") {
+    callbacks.dispatchEvent(
+      new CustomEvent("runtimedataapplied", { detail: { channel: data["channel"] } }),
+    );
+    return;
+  }
+
   if (data["type"] === "state") {
     callbacks.setPlaybackState(
       applyRuntimeStateMessage(

From 0dced8834cfc1a476d445d8b083bff63f7c3e460 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 13:45:46 -0700
Subject: [PATCH 2/7] fix(player): fail closed on runtime data delivery

---
 packages/player/README.md                     |  6 ++-
 .../player/src/hyperframes-player.test.ts     | 47 +++++++++++++++++++
 packages/player/src/hyperframes-player.ts     | 39 +++++++++++++--
 3 files changed, 87 insertions(+), 5 deletions(-)

diff --git a/packages/player/README.md b/packages/player/README.md
index 0627e4e074..782da8c7d6 100644
--- a/packages/player/README.md
+++ b/packages/player/README.md
@@ -134,7 +134,11 @@ player.iframeElement; // HTMLIFrameElement (read-only)
 
 ## Advanced: iframe access
 
-The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. For most use cases you don't need direct access — the JavaScript API above is enough. But if you're building an editor, recorder, or custom timeline that needs to inspect the composition's DOM or read its `__player` / `__timelines` runtime objects, use the `iframeElement` getter:
+The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. The default sandbox includes `allow-same-origin` for editor, recorder, and custom-timeline integrations that inspect the composition DOM. That is a trusted-content mode, not an isolation boundary: same-origin composition code can reach the embedding page.
+
+For read-only or message-bridge integrations, set `sandbox-origin="opaque"`. This removes `allow-same-origin` while retaining scripts, and prevents the composition from reading unrelated parent DOM. Direct `contentDocument`, `__player`, and `__timelines` access is intentionally unavailable in that mode.
+
+If you are building a trusted editor integration that needs direct access, use the `iframeElement` getter:
 
 ```js
 const player = document.querySelector("hyperframes-player");
diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index 8b7fadc7a5..e84335af18 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -2497,7 +2497,54 @@ describe("HyperframesPlayer retained runtime data", () => {
     expect(player.iframeElement.referrerPolicy).toBe("no-referrer");
   });
 
+  it("supports an opaque-origin sandbox for hosts that do not need direct iframe DOM access", () => {
+    player.setAttribute("sandbox-origin", "opaque");
+    expect(player.iframeElement.sandbox.contains("allow-scripts")).toBe(true);
+    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(false);
+    expect(player.iframeElement.sandbox.contains("allow-top-navigation")).toBe(false);
+
+    player.removeAttribute("sandbox-origin");
+    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(true);
+  });
+
   it("rejects payloads that structuredClone cannot transfer", () => {
     expect(() => player.setRuntimeData("captions", () => undefined)).toThrow();
   });
+
+  it("fails closed when structuredClone is unavailable", () => {
+    const original = globalThis.structuredClone;
+    Object.defineProperty(globalThis, "structuredClone", {
+      configurable: true,
+      value: undefined,
+    });
+    try {
+      expect(() => player.setRuntimeData("captions", { words: ["unsafe"] })).toThrow(
+        /requires structuredClone support/,
+      );
+      player._onMessage(readyMessage());
+      expect(runtimeCalls()).toHaveLength(0);
+    } finally {
+      Object.defineProperty(globalThis, "structuredClone", {
+        configurable: true,
+        value: original,
+      });
+    }
+  });
+
+  it("reports postMessage delivery failures instead of silently dropping runtime data", () => {
+    player._onMessage(readyMessage());
+    postSpy.mockImplementation(() => {
+      throw new DOMException("payload cannot be cloned", "DataCloneError");
+    });
+    const errors: CustomEvent[] = [];
+    player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));
+
+    player.setRuntimeData("captions", { words: ["value"] });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.detail).toMatchObject({
+      channel: "captions",
+      message: "payload cannot be cloned",
+    });
+  });
 });
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index 94d1a4d277..05dba34e9b 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -29,6 +29,7 @@ import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
 // production browsers.
 const MIN_PLAYBACK_RATE = 0.1;
 const MAX_PLAYBACK_RATE = 5;
+const SANDBOX_ORIGIN_ATTR = "sandbox-origin";
 
 export type ColorGradingTarget =
   | string
@@ -70,6 +71,7 @@ class HyperframesPlayer extends HTMLElement {
       "poster",
       "playback-rate",
       "audio-src",
+      SANDBOX_ORIGIN_ATTR,
       SHADER_CAPTURE_SCALE_ATTR,
       SHADER_LOADING_ATTR,
     ];
@@ -163,6 +165,7 @@ class HyperframesPlayer extends HTMLElement {
   }
 
   connectedCallback() {
+    this._applySandboxOriginPolicy();
     this.resizeObserver.observe(this);
     window.addEventListener("message", this._onMessage);
     this.iframe.addEventListener("load", this._onIframeLoad);
@@ -218,6 +221,9 @@ class HyperframesPlayer extends HTMLElement {
         if (val !== null) this.iframe.srcdoc = prepareSrcdocForElement(this, val);
         else this.iframe.removeAttribute("srcdoc");
         break;
+      case SANDBOX_ORIGIN_ATTR:
+        this._applySandboxOriginPolicy();
+        break;
       // Reject NaN/zero/negative dimensions the same way the composition
       // probe does (a typo like width="abc" or width="0" would otherwise
       // reach scaleIframeToFit as scale(NaN) or a division by zero and
@@ -275,6 +281,15 @@ class HyperframesPlayer extends HTMLElement {
     }
   }
 
+  private _applySandboxOriginPolicy(): void {
+    const policy = this.getAttribute(SANDBOX_ORIGIN_ATTR);
+    if (policy === "opaque") {
+      this.iframe.sandbox.remove("allow-same-origin");
+      return;
+    }
+    this.iframe.sandbox.add("allow-same-origin");
+  }
+
   /**
    * The inner `<iframe>` rendering the composition. Use this when integrating
    * with tools that need `contentWindow` — `.contentWindow` on the
@@ -395,7 +410,12 @@ class HyperframesPlayer extends HTMLElement {
     if (!/^[a-z][a-z0-9-]{0,63}$/.test(channel)) {
       throw new Error(`Invalid HyperFrames runtime-data channel: ${channel}`);
     }
-    const retained = typeof structuredClone === "function" ? structuredClone(payload) : payload;
+    if (typeof structuredClone !== "function") {
+      throw new Error(
+        "HyperFrames runtime data requires structuredClone support; refusing an unverified payload",
+      );
+    }
+    const retained = structuredClone(payload);
     this._runtimeData.set(channel, retained);
     this._deliverRuntimeData(channel, retained);
   }
@@ -529,7 +549,7 @@ class HyperframesPlayer extends HTMLElement {
     else this.removeAttribute("loop");
   }
 
-  private _sendControl(action: string, extra: Record<string, unknown> = {}) {
+  private _sendControl(action: string, extra: Record<string, unknown> = {}): boolean {
     try {
       this.iframe.contentWindow?.postMessage(
         {
@@ -541,8 +561,19 @@ class HyperframesPlayer extends HTMLElement {
         },
         "*",
       );
-    } catch {
-      /* cross-origin */
+      return true;
+    } catch (error) {
+      if (action === "set-runtime-data" || action === "clear-runtime-data") {
+        this.dispatchEvent(
+          new CustomEvent("runtimedataerror", {
+            detail: {
+              channel: extra["channel"],
+              message: error instanceof Error ? error.message : String(error),
+            },
+          }),
+        );
+      }
+      return false;
     }
   }
 

From c36f7f2764284c7b99126ae6ac7f3facb6486fe5 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 17:57:57 -0700
Subject: [PATCH 3/7] fix(player): close runtime delivery and sandbox gaps

---
 .github/workflows/player-perf.yml             |   7 +
 packages/core/src/runtime/bridge.ts           |   9 +-
 packages/core/src/runtime/init.ts             |  12 +-
 packages/core/src/runtime/runtimeData.test.ts |  27 +++-
 packages/core/src/runtime/runtimeData.ts      |  67 ++++++--
 packages/core/src/runtime/types.ts            |   3 +
 packages/player/README.md                     |  29 +++-
 packages/player/package.json                  |   1 +
 .../player/src/hyperframes-player.test.ts     |  86 +++++++++-
 packages/player/src/hyperframes-player.ts     | 153 +++++++++++++++---
 .../src/runtime-message-handler.test.ts       |  22 +--
 .../player/src/runtime-message-handler.ts     |  12 +-
 .../player/tests/browser/sandbox-origin.ts    |  53 ++++++
 .../perf/fixtures/sandbox-probe/index.html    |  18 +++
 packages/player/tests/perf/runner.ts          |   1 +
 packages/player/tests/perf/server.ts          |   6 +
 16 files changed, 439 insertions(+), 67 deletions(-)
 create mode 100644 packages/player/tests/browser/sandbox-origin.ts
 create mode 100644 packages/player/tests/perf/fixtures/sandbox-probe/index.html

diff --git a/.github/workflows/player-perf.yml b/.github/workflows/player-perf.yml
index 757f531fb7..7bcfd1aa71 100644
--- a/.github/workflows/player-perf.yml
+++ b/.github/workflows/player-perf.yml
@@ -107,6 +107,13 @@ jobs:
         if: matrix.shard == 'parity'
         uses: ./.github/actions/install-ffmpeg-linux
 
+      - name: Verify sandbox origin boundary (load shard only)
+        if: matrix.shard == 'load'
+        working-directory: packages/player
+        env:
+          PUPPETEER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+        run: bun run test:browser-security
+
       - name: Run player perf — ${{ matrix.shard }} (measure mode)
         working-directory: packages/player
         env:
diff --git a/packages/core/src/runtime/bridge.ts b/packages/core/src/runtime/bridge.ts
index 804bde0539..4de5ff306d 100644
--- a/packages/core/src/runtime/bridge.ts
+++ b/packages/core/src/runtime/bridge.ts
@@ -28,8 +28,8 @@ type BridgeDeps = {
   ) => void;
   onEnablePickMode: () => void;
   onDisablePickMode: () => void;
-  onSetRuntimeData?: (channel: string, payload: unknown) => void;
-  onClearRuntimeData?: (channel: string) => void;
+  onSetRuntimeData?: (channel: string, payload: unknown, requestId?: number) => void;
+  onClearRuntimeData?: (channel: string, requestId?: number) => void;
   getCanonicalFps: () => number;
 };
 
@@ -78,10 +78,11 @@ const CONTROL_HANDLERS: Record<string, ControlHandler> = {
   "disable-pick-mode": (_d, deps) => deps.onDisablePickMode(),
   "flash-elements": (data) => handleFlashElements(data),
   "set-runtime-data": (data, deps) => {
-    if (typeof data.channel === "string") deps.onSetRuntimeData?.(data.channel, data.payload);
+    if (typeof data.channel === "string")
+      deps.onSetRuntimeData?.(data.channel, data.payload, data.requestId);
   },
   "clear-runtime-data": (data, deps) => {
-    if (typeof data.channel === "string") deps.onClearRuntimeData?.(data.channel);
+    if (typeof data.channel === "string") deps.onClearRuntimeData?.(data.channel, data.requestId);
   },
 };
 
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index b6d3a80582..61856fae49 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -133,16 +133,22 @@ export function initSandboxRuntimeModular(): void {
   // Own the analytics bridge before any best-effort runtime installation so
   // early failures are observable instead of disappearing before player setup.
   initRuntimeAnalytics(postRuntimeMessage as (payload: unknown) => void);
-  setRuntimeDataErrorReporter((channel, error) => {
+  setRuntimeDataErrorReporter((channel, requestId, error) => {
     postRuntimeMessage({
       source: "hf-preview",
       type: "runtime-data-error",
       channel,
+      requestId,
       message: error instanceof Error ? error.message : String(error),
     });
   });
-  setRuntimeDataAppliedReporter((channel) => {
-    postRuntimeMessage({ source: "hf-preview", type: "runtime-data-applied", channel });
+  setRuntimeDataAppliedReporter((channel, requestId) => {
+    postRuntimeMessage({
+      source: "hf-preview",
+      type: "runtime-data-applied",
+      channel,
+      requestId,
+    });
   });
   // SDK moveElement edits must render even when no usable GSAP timeline ever
   // binds (CSS/WAAPI-animated or fully static compositions) — apply at init.
diff --git a/packages/core/src/runtime/runtimeData.test.ts b/packages/core/src/runtime/runtimeData.test.ts
index ac3d949e82..254424d2a3 100644
--- a/packages/core/src/runtime/runtimeData.test.ts
+++ b/packages/core/src/runtime/runtimeData.test.ts
@@ -49,7 +49,7 @@ describe("runtime data registry", () => {
       throw new Error("attach failed");
     });
     expect(() => setRuntimeData("captions", {})).not.toThrow();
-    expect(reporter).toHaveBeenCalledWith("captions", expect.any(Error));
+    expect(reporter).toHaveBeenCalledWith("captions", expect.any(Number), expect.any(Error));
   });
 
   it("reports asynchronous completion and rejection", async () => {
@@ -63,8 +63,29 @@ describe("runtime data registry", () => {
     });
 
     setRuntimeData("captions", "good");
-    await vi.waitFor(() => expect(applied).toHaveBeenCalledWith("captions"));
+    await vi.waitFor(() => expect(applied).toHaveBeenCalledWith("captions", expect.any(Number)));
     setRuntimeData("captions", "bad");
-    await vi.waitFor(() => expect(failed).toHaveBeenCalledWith("captions", expect.any(Error)));
+    await vi.waitFor(() =>
+      expect(failed).toHaveBeenCalledWith("captions", expect.any(Number), expect.any(Error)),
+    );
+  });
+
+  it("reports only the latest concurrent delivery on a channel", async () => {
+    const applied = vi.fn();
+    setRuntimeDataAppliedReporter(applied);
+    const resolvers: Array<() => void> = [];
+    registerRuntimeDataHandler(
+      "captions",
+      () => new Promise<void>((resolve) => resolvers.push(resolve)),
+    );
+
+    setRuntimeData("captions", "first", 101);
+    setRuntimeData("captions", "latest", 102);
+    resolvers[1]?.();
+    await vi.waitFor(() => expect(applied).toHaveBeenCalledWith("captions", 102));
+    resolvers[0]?.();
+    await Promise.resolve();
+
+    expect(applied).toHaveBeenCalledTimes(1);
   });
 });
diff --git a/packages/core/src/runtime/runtimeData.ts b/packages/core/src/runtime/runtimeData.ts
index 9fb0f9cac0..f97b219041 100644
--- a/packages/core/src/runtime/runtimeData.ts
+++ b/packages/core/src/runtime/runtimeData.ts
@@ -1,26 +1,53 @@
 export type RuntimeDataHandler = (payload: unknown) => void | Promise<void>;
-export type RuntimeDataErrorReporter = (channel: string, error: unknown) => void;
-export type RuntimeDataAppliedReporter = (channel: string) => void;
+export type RuntimeDataErrorReporter = (channel: string, requestId: number, error: unknown) => void;
+export type RuntimeDataAppliedReporter = (channel: string, requestId: number) => void;
 
-const retained = new Map<string, unknown>();
+type RetainedRuntimeData = {
+  payload: unknown;
+  requestId: number;
+  generation: number;
+};
+
+const retained = new Map<string, RetainedRuntimeData>();
 const handlers = new Map<string, RuntimeDataHandler>();
+const generations = new Map<string, number>();
 let reportError: RuntimeDataErrorReporter = () => undefined;
 let reportApplied: RuntimeDataAppliedReporter = () => undefined;
+let localRequestId = 0;
 
 function validChannel(channel: string): boolean {
   return /^[a-z][a-z0-9-]{0,63}$/.test(channel);
 }
 
-function deliver(channel: string, payload: unknown): void {
+function nextGeneration(channel: string): number {
+  const generation = (generations.get(channel) ?? 0) + 1;
+  generations.set(channel, generation);
+  return generation;
+}
+
+function resolveRequestId(requestId: number | undefined): number {
+  if (typeof requestId === "number" && Number.isSafeInteger(requestId) && requestId > 0)
+    return requestId;
+  localRequestId += 1;
+  return localRequestId;
+}
+
+function deliver(channel: string, retainedData: RetainedRuntimeData): void {
   const handler = handlers.get(channel);
   if (!handler) return;
+  const isCurrent = () =>
+    generations.get(channel) === retainedData.generation && handlers.get(channel) === handler;
   try {
-    void Promise.resolve(handler(payload)).then(
-      () => reportApplied(channel),
-      (error) => reportError(channel, error),
+    void Promise.resolve(handler(retainedData.payload)).then(
+      () => {
+        if (isCurrent()) reportApplied(channel, retainedData.requestId);
+      },
+      (error) => {
+        if (isCurrent()) reportError(channel, retainedData.requestId, error);
+      },
     );
   } catch (error) {
-    reportError(channel, error);
+    if (isCurrent()) reportError(channel, retainedData.requestId, error);
   }
 }
 
@@ -32,16 +59,25 @@ export function setRuntimeDataAppliedReporter(reporter: RuntimeDataAppliedReport
   reportApplied = reporter;
 }
 
-export function setRuntimeData(channel: string, payload: unknown): void {
+export function setRuntimeData(channel: string, payload: unknown, requestId?: number): void {
   if (!validChannel(channel)) return;
-  retained.set(channel, payload);
-  deliver(channel, payload);
+  const retainedData = {
+    payload,
+    requestId: resolveRequestId(requestId),
+    generation: nextGeneration(channel),
+  };
+  retained.set(channel, retainedData);
+  deliver(channel, retainedData);
 }
 
-export function clearRuntimeData(channel: string): void {
+export function clearRuntimeData(channel: string, requestId?: number): void {
   if (!validChannel(channel)) return;
   retained.delete(channel);
-  deliver(channel, undefined);
+  deliver(channel, {
+    payload: undefined,
+    requestId: resolveRequestId(requestId),
+    generation: nextGeneration(channel),
+  });
 }
 
 export function registerRuntimeDataHandler(
@@ -51,7 +87,8 @@ export function registerRuntimeDataHandler(
   if (!validChannel(channel))
     throw new Error(`Invalid HyperFrames runtime-data channel: ${channel}`);
   handlers.set(channel, handler);
-  if (retained.has(channel)) deliver(channel, retained.get(channel));
+  const retainedData = retained.get(channel);
+  if (retainedData) deliver(channel, retainedData);
   return () => {
     if (handlers.get(channel) === handler) handlers.delete(channel);
   };
@@ -60,6 +97,8 @@ export function registerRuntimeDataHandler(
 export function resetRuntimeDataForTests(): void {
   retained.clear();
   handlers.clear();
+  generations.clear();
+  localRequestId = 0;
   reportError = () => undefined;
   reportApplied = () => undefined;
 }
diff --git a/packages/core/src/runtime/types.ts b/packages/core/src/runtime/types.ts
index 9c3afc9bd7..edfd520508 100644
--- a/packages/core/src/runtime/types.ts
+++ b/packages/core/src/runtime/types.ts
@@ -175,6 +175,7 @@ export type RuntimeDataErrorMessage = {
   source: "hf-preview";
   type: "runtime-data-error";
   channel: string;
+  requestId: number;
   message: string;
 };
 
@@ -182,6 +183,7 @@ export type RuntimeDataAppliedMessage = {
   source: "hf-preview";
   type: "runtime-data-applied";
   channel: string;
+  requestId: number;
 };
 
 /**
@@ -339,6 +341,7 @@ export type RuntimeGsapSetVars = Record<string, string | number | boolean | null
 type RuntimeDataControlFields = {
   channel?: string;
   payload?: unknown;
+  requestId?: number;
 };
 
 type RuntimeBridgeControlAction =
diff --git a/packages/player/README.md b/packages/player/README.md
index 782da8c7d6..0928213c24 100644
--- a/packages/player/README.md
+++ b/packages/player/README.md
@@ -132,11 +132,38 @@ player.shaderLoading; // "composition" | "player" | "none" (read/write)
 player.iframeElement; // HTMLIFrameElement (read-only)
 ```
 
+## Runtime data delivery
+
+`setRuntimeData(channel, payload)` clones and retains the payload, then delivers it after the
+composition runtime is ready. Invalid channels and non-cloneable payloads throw synchronously.
+Failures after the call returns are reported with `runtimedataerror`; successful application is
+reported with `runtimedataapplied`. Both events include `{ channel, requestId }`, and errors also
+include `message`. Listen for both outcomes when delivery matters:
+
+```js
+player.addEventListener("runtimedataapplied", ({ detail }) => {
+  console.log("applied", detail.channel, detail.requestId);
+});
+player.addEventListener("runtimedataerror", ({ detail }) => {
+  console.error("not applied", detail.channel, detail.requestId, detail.message);
+});
+player.setRuntimeData("captions", captionData);
+```
+
+Only the latest in-flight update for a channel can emit a completion. A missing runtime response,
+iframe teardown, or bridge delivery failure emits `runtimedataerror` instead of remaining pending
+indefinitely.
+
 ## Advanced: iframe access
 
 The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. The default sandbox includes `allow-same-origin` for editor, recorder, and custom-timeline integrations that inspect the composition DOM. That is a trusted-content mode, not an isolation boundary: same-origin composition code can reach the embedding page.
 
-For read-only or message-bridge integrations, set `sandbox-origin="opaque"`. This removes `allow-same-origin` while retaining scripts, and prevents the composition from reading unrelated parent DOM. Direct `contentDocument`, `__player`, and `__timelines` access is intentionally unavailable in that mode.
+For read-only or message-bridge integrations, set `sandbox-origin="opaque"`. Any non-null value is
+treated as opaque so a typo cannot weaken isolation. Changing the attribute reloads the active
+composition because browser sandbox changes take effect only on navigation. Opaque mode removes
+`allow-same-origin` while retaining scripts, and prevents the composition from reading unrelated
+parent DOM. Direct `contentDocument`, `__player`, and `__timelines` access is intentionally
+unavailable in that mode.
 
 If you are building a trusted editor integration that needs direct access, use the `iframeElement` getter:
 
diff --git a/packages/player/package.json b/packages/player/package.json
index 581237fef5..5204969416 100644
--- a/packages/player/package.json
+++ b/packages/player/package.json
@@ -31,6 +31,7 @@
     "build": "tsup && node scripts/verify-runtime-pin.mjs",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tests/perf/tsconfig.json",
     "test": "vitest run",
+    "test:browser-security": "bun run tests/browser/sandbox-origin.ts",
     "perf": "bun run tests/perf/index.ts"
   },
   "dependencies": {
diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index e84335af18..5bc42fd38a 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -2481,7 +2481,7 @@ describe("HyperframesPlayer retained runtime data", () => {
 
     player.setRuntimeData("captions", { words: ["direct"] });
 
-    expect(direct).toHaveBeenCalledWith("captions", { words: ["direct"] });
+    expect(direct).toHaveBeenCalledWith("captions", { words: ["direct"] }, expect.any(Number));
     expect(runtimeCalls()).toHaveLength(0);
   });
 
@@ -2507,6 +2507,11 @@ describe("HyperframesPlayer retained runtime data", () => {
     expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(true);
   });
 
+  it("treats every non-null sandbox-origin value as restrictive", () => {
+    player.setAttribute("sandbox-origin", "opaqu");
+    expect(player.iframeElement.sandbox.contains("allow-same-origin")).toBe(false);
+  });
+
   it("rejects payloads that structuredClone cannot transfer", () => {
     expect(() => player.setRuntimeData("captions", () => undefined)).toThrow();
   });
@@ -2544,7 +2549,86 @@ describe("HyperframesPlayer retained runtime data", () => {
     expect(errors).toHaveLength(1);
     expect(errors[0]?.detail).toMatchObject({
       channel: "captions",
+      requestId: expect.any(Number),
       message: "payload cannot be cloned",
     });
   });
+
+  it("reports a null iframe window as a delivery failure", () => {
+    player._onMessage(readyMessage());
+    Object.defineProperty(player.iframeElement, "contentWindow", {
+      configurable: true,
+      get: () => null,
+    });
+    const errors: CustomEvent[] = [];
+    player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));
+
+    player.setRuntimeData("captions", { words: ["value"] });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.detail).toMatchObject({
+      channel: "captions",
+      requestId: expect.any(Number),
+      message: "Composition iframe is unavailable",
+    });
+  });
+
+  it("reports a bounded error when the runtime never responds", () => {
+    vi.useFakeTimers();
+    try {
+      player._onMessage(readyMessage());
+      const errors: CustomEvent[] = [];
+      player.addEventListener("runtimedataerror", (event) => errors.push(event as CustomEvent));
+
+      player.setRuntimeData("captions", { words: ["value"] });
+      vi.advanceTimersByTime(10_000);
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0]?.detail).toMatchObject({
+        channel: "captions",
+        requestId: expect.any(Number),
+        message: "Runtime data delivery timed out after 10000ms",
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores a superseded completion and correlates the latest application", () => {
+    player._onMessage(readyMessage());
+    postSpy.mockClear();
+    const applied: CustomEvent[] = [];
+    player.addEventListener("runtimedataapplied", (event) => applied.push(event as CustomEvent));
+
+    player.setRuntimeData("captions", { words: ["first"] });
+    player.setRuntimeData("captions", { words: ["latest"] });
+    const requests = runtimeCalls().map((call) => (call[0] as { requestId: number }).requestId);
+
+    player._onMessage(
+      new MessageEvent("message", {
+        source: window,
+        data: {
+          source: "hf-preview",
+          type: "runtime-data-applied",
+          channel: "captions",
+          requestId: requests[0],
+        },
+      }),
+    );
+    expect(applied).toHaveLength(0);
+
+    player._onMessage(
+      new MessageEvent("message", {
+        source: window,
+        data: {
+          source: "hf-preview",
+          type: "runtime-data-applied",
+          channel: "captions",
+          requestId: requests[1],
+        },
+      }),
+    );
+    expect(applied).toHaveLength(1);
+    expect(applied[0]?.detail).toEqual({ channel: "captions", requestId: requests[1] });
+  });
 });
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index 05dba34e9b..badaa9e942 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -30,6 +30,7 @@ import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
 const MIN_PLAYBACK_RATE = 0.1;
 const MAX_PLAYBACK_RATE = 5;
 const SANDBOX_ORIGIN_ATTR = "sandbox-origin";
+const RUNTIME_DATA_DELIVERY_TIMEOUT_MS = 10_000;
 
 export type ColorGradingTarget =
   | string
@@ -48,8 +49,13 @@ export type ColorGradingCompareState = {
 };
 
 type RuntimeDataBridge = {
-  setRuntimeData?: (channel: string, payload: unknown) => void;
-  clearRuntimeData?: (channel: string) => void;
+  setRuntimeData?: (channel: string, payload: unknown, requestId?: number) => void;
+  clearRuntimeData?: (channel: string, requestId?: number) => void;
+};
+
+type PendingRuntimeDataDelivery = {
+  requestId: number;
+  timeoutId: number;
 };
 
 function clampPlaybackRate(rate: number): number {
@@ -106,6 +112,8 @@ class HyperframesPlayer extends HTMLElement {
   private _runtimeFps = 30;
   private _runtimeBridgeReady = false;
   private _runtimeData = new Map<string, unknown>();
+  private _runtimeDataRequestId = 0;
+  private _pendingRuntimeData = new Map<string, PendingRuntimeDataDelivery>();
 
   constructor() {
     super();
@@ -203,26 +211,33 @@ class HyperframesPlayer extends HTMLElement {
     this._paused = true;
     this._ready = false;
     this._runtimeBridgeReady = false;
+    this._rejectAllRuntimeDataDeliveries("Player disconnected before runtime data was applied");
   }
 
   // fallow-ignore-next-line complexity
-  attributeChangedCallback(name: string, _old: string | null, val: string | null) {
+  attributeChangedCallback(name: string, oldVal: string | null, val: string | null) {
     switch (name) {
       case "src":
         if (val) {
           this._ready = false;
           this._runtimeBridgeReady = false;
+          this._rejectAllRuntimeDataDeliveries(
+            "Composition navigated before runtime data was applied",
+          );
           this.iframe.src = prepareSrcForElement(this, val);
         }
         break;
       case "srcdoc":
         this._ready = false;
         this._runtimeBridgeReady = false;
+        this._rejectAllRuntimeDataDeliveries(
+          "Composition navigated before runtime data was applied",
+        );
         if (val !== null) this.iframe.srcdoc = prepareSrcdocForElement(this, val);
         else this.iframe.removeAttribute("srcdoc");
         break;
       case SANDBOX_ORIGIN_ATTR:
-        this._applySandboxOriginPolicy();
+        this._applySandboxOriginPolicy(this.isConnected && oldVal !== val);
         break;
       // Reject NaN/zero/negative dimensions the same way the composition
       // probe does (a typo like width="abc" or width="0" would otherwise
@@ -281,13 +296,26 @@ class HyperframesPlayer extends HTMLElement {
     }
   }
 
-  private _applySandboxOriginPolicy(): void {
-    const policy = this.getAttribute(SANDBOX_ORIGIN_ATTR);
-    if (policy === "opaque") {
+  private _applySandboxOriginPolicy(reloadActiveDocument = false): void {
+    if (this.hasAttribute(SANDBOX_ORIGIN_ATTR)) {
       this.iframe.sandbox.remove("allow-same-origin");
+    } else {
+      this.iframe.sandbox.add("allow-same-origin");
+    }
+    if (reloadActiveDocument) this._reloadForSandboxOriginPolicy();
+  }
+
+  private _reloadForSandboxOriginPolicy(): void {
+    this._ready = false;
+    this._runtimeBridgeReady = false;
+    this._rejectAllRuntimeDataDeliveries("Sandbox policy changed before runtime data was applied");
+    const srcdoc = this.getAttribute("srcdoc");
+    if (srcdoc !== null) {
+      this.iframe.srcdoc = prepareSrcdocForElement(this, srcdoc);
       return;
     }
-    this.iframe.sandbox.add("allow-same-origin");
+    const src = this.getAttribute("src");
+    this.iframe.src = src === null ? "about:blank" : prepareSrcForElement(this, src);
   }
 
   /**
@@ -551,7 +579,18 @@ class HyperframesPlayer extends HTMLElement {
 
   private _sendControl(action: string, extra: Record<string, unknown> = {}): boolean {
     try {
-      this.iframe.contentWindow?.postMessage(
+      const frameWindow = this.iframe.contentWindow;
+      if (!frameWindow) {
+        if (action === "set-runtime-data" || action === "clear-runtime-data") {
+          this._rejectRuntimeDataDelivery(
+            extra["channel"],
+            extra["requestId"],
+            "Composition iframe is unavailable",
+          );
+        }
+        return false;
+      }
+      frameWindow.postMessage(
         {
           ...extra,
           source: "hf-parent",
@@ -564,13 +603,10 @@ class HyperframesPlayer extends HTMLElement {
       return true;
     } catch (error) {
       if (action === "set-runtime-data" || action === "clear-runtime-data") {
-        this.dispatchEvent(
-          new CustomEvent("runtimedataerror", {
-            detail: {
-              channel: extra["channel"],
-              message: error instanceof Error ? error.message : String(error),
-            },
-          }),
+        this._rejectRuntimeDataDelivery(
+          extra["channel"],
+          extra["requestId"],
+          error instanceof Error ? error.message : String(error),
         );
       }
       return false;
@@ -579,36 +615,38 @@ class HyperframesPlayer extends HTMLElement {
 
   private _deliverRuntimeData(channel: string, payload: unknown): void {
     if (!this.isConnected || !this._runtimeBridgeReady) return;
-    if (this._trySetRuntimeDataDirect(channel, payload)) return;
-    this._sendControl("set-runtime-data", { channel, payload });
+    const requestId = this._beginRuntimeDataDelivery(channel);
+    if (this._trySetRuntimeDataDirect(channel, payload, requestId)) return;
+    this._sendControl("set-runtime-data", { channel, payload, requestId });
   }
 
   private _deliverRuntimeDataClear(channel: string): void {
     if (!this.isConnected || !this._runtimeBridgeReady) return;
-    if (this._tryClearRuntimeDataDirect(channel)) return;
-    this._sendControl("clear-runtime-data", { channel });
+    const requestId = this._beginRuntimeDataDelivery(channel);
+    if (this._tryClearRuntimeDataDirect(channel, requestId)) return;
+    this._sendControl("clear-runtime-data", { channel, requestId });
   }
 
-  private _trySetRuntimeDataDirect(channel: string, payload: unknown): boolean {
+  private _trySetRuntimeDataDirect(channel: string, payload: unknown, requestId: number): boolean {
     try {
       const bridge = (
         this.iframe.contentWindow as (Window & { __hyperframes?: RuntimeDataBridge }) | null
       )?.__hyperframes;
       if (typeof bridge?.setRuntimeData !== "function") return false;
-      bridge.setRuntimeData(channel, payload);
+      bridge.setRuntimeData(channel, payload, requestId);
       return true;
     } catch {
       return false;
     }
   }
 
-  private _tryClearRuntimeDataDirect(channel: string): boolean {
+  private _tryClearRuntimeDataDirect(channel: string, requestId: number): boolean {
     try {
       const bridge = (
         this.iframe.contentWindow as (Window & { __hyperframes?: RuntimeDataBridge }) | null
       )?.__hyperframes;
       if (typeof bridge?.clearRuntimeData !== "function") return false;
-      bridge.clearRuntimeData(channel);
+      bridge.clearRuntimeData(channel, requestId);
       return true;
     } catch {
       return false;
@@ -621,6 +659,69 @@ class HyperframesPlayer extends HTMLElement {
     }
   }
 
+  private _beginRuntimeDataDelivery(channel: string): number {
+    const previous = this._pendingRuntimeData.get(channel);
+    if (previous) window.clearTimeout(previous.timeoutId);
+    this._runtimeDataRequestId += 1;
+    const requestId = this._runtimeDataRequestId;
+    const timeoutId = window.setTimeout(() => {
+      this._rejectRuntimeDataDelivery(
+        channel,
+        requestId,
+        `Runtime data delivery timed out after ${RUNTIME_DATA_DELIVERY_TIMEOUT_MS}ms`,
+      );
+    }, RUNTIME_DATA_DELIVERY_TIMEOUT_MS);
+    this._pendingRuntimeData.set(channel, { requestId, timeoutId });
+    return requestId;
+  }
+
+  private _resolveRuntimeDataDelivery(channel: unknown, requestId: unknown): void {
+    const pending = this._takeRuntimeDataDelivery(channel, requestId);
+    if (!pending) return;
+    this.dispatchEvent(
+      new CustomEvent("runtimedataapplied", {
+        detail: { channel, requestId: pending.requestId },
+      }),
+    );
+  }
+
+  private _rejectRuntimeDataDelivery(channel: unknown, requestId: unknown, message: unknown): void {
+    const pending = this._takeRuntimeDataDelivery(channel, requestId);
+    if (!pending) return;
+    this.dispatchEvent(
+      new CustomEvent("runtimedataerror", {
+        detail: {
+          channel,
+          requestId: pending.requestId,
+          message: typeof message === "string" ? message : String(message),
+        },
+      }),
+    );
+  }
+
+  private _takeRuntimeDataDelivery(
+    channel: unknown,
+    requestId: unknown,
+  ): PendingRuntimeDataDelivery | null {
+    if (
+      typeof channel !== "string" ||
+      typeof requestId !== "number" ||
+      !Number.isSafeInteger(requestId)
+    )
+      return null;
+    const pending = this._pendingRuntimeData.get(channel);
+    if (!pending || pending.requestId !== requestId) return null;
+    window.clearTimeout(pending.timeoutId);
+    this._pendingRuntimeData.delete(channel);
+    return pending;
+  }
+
+  private _rejectAllRuntimeDataDeliveries(message: string): void {
+    for (const [channel, pending] of [...this._pendingRuntimeData]) {
+      this._rejectRuntimeDataDelivery(channel, pending.requestId, message);
+    }
+  }
+
   /**
    * Returns the iframe's contentDocument if same-origin and reachable,
    * otherwise null. Accessing contentDocument can throw on cross-origin
@@ -780,6 +881,10 @@ class HyperframesPlayer extends HTMLElement {
         this._replayBridgeState();
         this._replayRuntimeData();
       },
+      onRuntimeDataApplied: (channel, requestId) =>
+        this._resolveRuntimeDataDelivery(channel, requestId),
+      onRuntimeDataError: (channel, requestId, message) =>
+        this._rejectRuntimeDataDelivery(channel, requestId, message),
       onRuntimeTimelineReady: (duration) => this._onRuntimeTimelineReady(duration),
       setRuntimeFps: (fps) => {
         this._runtimeFps = fps;
diff --git a/packages/player/src/runtime-message-handler.test.ts b/packages/player/src/runtime-message-handler.test.ts
index 84aa73b297..5bd2a5f7a5 100644
--- a/packages/player/src/runtime-message-handler.test.ts
+++ b/packages/player/src/runtime-message-handler.test.ts
@@ -13,6 +13,8 @@ const makeCallbacks = (): MessageHandlerCallbacks => ({
   updateControlsPlaying: vi.fn(),
   dispatchEvent: vi.fn(),
   onRuntimeReady: vi.fn(),
+  onRuntimeDataApplied: vi.fn(),
+  onRuntimeDataError: vi.fn(),
   onRuntimeTimelineReady: vi.fn(),
   setRuntimeFps: vi.fn(),
   seek: vi.fn(),
@@ -72,7 +74,7 @@ describe("handleRuntimeMessage stage-size", () => {
 });
 
 describe("handleRuntimeMessage runtime data errors", () => {
-  it("surfaces a channel-scoped player event", () => {
+  it("routes a correlated channel-scoped error", () => {
     const frameWindow = {} as Window;
     const callbacks = makeCallbacks();
     handleRuntimeMessage(
@@ -82,31 +84,33 @@ describe("handleRuntimeMessage runtime data errors", () => {
           source: "hf-preview",
           type: "runtime-data-error",
           channel: "captions",
+          requestId: 41,
           message: "attach failed",
         },
       } as MessageEvent,
       frameWindow,
       callbacks,
     );
-    expect(callbacks.dispatchEvent).toHaveBeenCalledWith(
-      expect.objectContaining({ type: "runtimedataerror" }),
-    );
+    expect(callbacks.onRuntimeDataError).toHaveBeenCalledWith("captions", 41, "attach failed");
   });
 
-  it("surfaces successful channel application", () => {
+  it("routes a correlated successful application", () => {
     const frameWindow = {} as Window;
     const callbacks = makeCallbacks();
     handleRuntimeMessage(
       {
         source: frameWindow,
-        data: { source: "hf-preview", type: "runtime-data-applied", channel: "captions" },
+        data: {
+          source: "hf-preview",
+          type: "runtime-data-applied",
+          channel: "captions",
+          requestId: 42,
+        },
       } as MessageEvent,
       frameWindow,
       callbacks,
     );
-    expect(callbacks.dispatchEvent).toHaveBeenCalledWith(
-      expect.objectContaining({ type: "runtimedataapplied" }),
-    );
+    expect(callbacks.onRuntimeDataApplied).toHaveBeenCalledWith("captions", 42);
   });
 });
 
diff --git a/packages/player/src/runtime-message-handler.ts b/packages/player/src/runtime-message-handler.ts
index 4fd991b08c..8ccb3c027d 100644
--- a/packages/player/src/runtime-message-handler.ts
+++ b/packages/player/src/runtime-message-handler.ts
@@ -40,6 +40,8 @@ export interface MessageHandlerCallbacks extends PlaybackStateCallbacks {
    *  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;
+  onRuntimeDataApplied?: (channel: unknown, requestId: unknown) => void;
+  onRuntimeDataError?: (channel: unknown, requestId: unknown, message: unknown) => void;
   /** Invoked when the runtime posts a finite positive timeline duration. The
    *  player uses this as the cross-origin readiness signal because the
    *  same-origin composition probe cannot inspect CDN iframes. */
@@ -93,18 +95,12 @@ export function handleRuntimeMessage(
   }
 
   if (data["type"] === "runtime-data-error") {
-    callbacks.dispatchEvent(
-      new CustomEvent("runtimedataerror", {
-        detail: { channel: data["channel"], message: data["message"] },
-      }),
-    );
+    callbacks.onRuntimeDataError?.(data["channel"], data["requestId"], data["message"]);
     return;
   }
 
   if (data["type"] === "runtime-data-applied") {
-    callbacks.dispatchEvent(
-      new CustomEvent("runtimedataapplied", { detail: { channel: data["channel"] } }),
-    );
+    callbacks.onRuntimeDataApplied?.(data["channel"], data["requestId"]);
     return;
   }
 
diff --git a/packages/player/tests/browser/sandbox-origin.ts b/packages/player/tests/browser/sandbox-origin.ts
new file mode 100644
index 0000000000..2ba79434ca
--- /dev/null
+++ b/packages/player/tests/browser/sandbox-origin.ts
@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+
+import { launchBrowser } from "../perf/runner.js";
+import { startServer } from "../perf/server.js";
+
+const server = startServer();
+const browser = await launchBrowser();
+
+try {
+  const page = await browser.newPage();
+  await page.goto(`${server.origin}/host.html?fixture=sandbox-probe`, {
+    waitUntil: "domcontentloaded",
+  });
+  await page.waitForFunction(() => (window.__sandboxProbeResults?.length ?? 0) >= 1);
+  assert.equal(
+    await page.evaluate(() => window.__sandboxProbeResults?.at(-1)),
+    true,
+    "the default trusted sandbox should allow same-origin parent access",
+  );
+
+  await page.evaluate(() => {
+    document.querySelector("hyperframes-player")?.setAttribute("sandbox-origin", "opaque");
+  });
+  await page.waitForFunction(() => (window.__sandboxProbeResults?.length ?? 0) >= 2);
+  assert.equal(
+    await page.evaluate(() => window.__sandboxProbeResults?.at(-1)),
+    false,
+    "switching a live player to opaque must reload into an isolated origin",
+  );
+
+  await page.evaluate(() => {
+    document.querySelector("hyperframes-player")?.setAttribute("sandbox-origin", "opaqu");
+  });
+  await page.waitForFunction(() => (window.__sandboxProbeResults?.length ?? 0) >= 3);
+  assert.equal(
+    await page.evaluate(() => window.__sandboxProbeResults?.at(-1)),
+    false,
+    "an unrecognized non-null policy must remain isolated",
+  );
+
+  await page.evaluate(() => {
+    document.querySelector("hyperframes-player")?.removeAttribute("sandbox-origin");
+  });
+  await page.waitForFunction(() => (window.__sandboxProbeResults?.length ?? 0) >= 4);
+  assert.equal(
+    await page.evaluate(() => window.__sandboxProbeResults?.at(-1)),
+    true,
+    "removing the policy must reload into the documented trusted mode",
+  );
+} finally {
+  await browser.close();
+  await server.stop();
+}
diff --git a/packages/player/tests/perf/fixtures/sandbox-probe/index.html b/packages/player/tests/perf/fixtures/sandbox-probe/index.html
new file mode 100644
index 0000000000..bde692c3e9
--- /dev/null
+++ b/packages/player/tests/perf/fixtures/sandbox-probe/index.html
@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Sandbox origin probe</title>
+  </head>
+  <body>
+    <script>
+      let canAccessParent = false;
+      try {
+        canAccessParent = window.parent.document.body !== null;
+      } catch {
+        canAccessParent = false;
+      }
+      window.parent.postMessage({ source: "hf-sandbox-probe", canAccessParent }, "*");
+    </script>
+  </body>
+</html>
diff --git a/packages/player/tests/perf/runner.ts b/packages/player/tests/perf/runner.ts
index 56282c1889..fdfb361b11 100644
--- a/packages/player/tests/perf/runner.ts
+++ b/packages/player/tests/perf/runner.ts
@@ -44,6 +44,7 @@ declare global {
     __playerNavStart?: number;
     __playerDuration?: number;
     __playerError?: string;
+    __sandboxProbeResults?: boolean[];
   }
 }
 
diff --git a/packages/player/tests/perf/server.ts b/packages/player/tests/perf/server.ts
index 3cbedb5881..8dd3561bf8 100644
--- a/packages/player/tests/perf/server.ts
+++ b/packages/player/tests/perf/server.ts
@@ -102,6 +102,12 @@ function buildHostHtml(fixtureName: string, width: number, height: number): stri
       window.__playerReady = false;
       window.__playerReadyAt = null;
       window.__playerNavStart = performance.timeOrigin + performance.now();
+      window.__sandboxProbeResults = [];
+      window.addEventListener("message", function (event) {
+        if (event.data && event.data.source === "hf-sandbox-probe") {
+          window.__sandboxProbeResults.push(event.data.canAccessParent === true);
+        }
+      });
       const player = document.getElementById("player");
       player.addEventListener("ready", function (event) {
         window.__playerReady = true;

From be86ca8878e74524ed1b2e1701df3d49bec7f2b6 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 18:13:43 -0700
Subject: [PATCH 4/7] fix(player): satisfy runtime contract and CodeQL

---
 packages/core/src/runtime/bridge.test.ts      | 10 +++--
 packages/player/src/runtime-in-srcdoc.test.ts | 10 +++++
 packages/player/src/runtime-in-srcdoc.ts      | 40 +++++++++++++++----
 3 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/packages/core/src/runtime/bridge.test.ts b/packages/core/src/runtime/bridge.test.ts
index 60cbd042df..ae94404c7e 100644
--- a/packages/core/src/runtime/bridge.test.ts
+++ b/packages/core/src/runtime/bridge.test.ts
@@ -50,10 +50,12 @@ describe("installRuntimeControlBridge", () => {
     const deps = createMockDeps();
     const handler = installRuntimeControlBridge(deps);
     const payload = { version: 3, segments: [] };
-    handler(makeControlMessage("set-runtime-data", { channel: "captions", payload }));
-    handler(makeControlMessage("clear-runtime-data", { channel: "captions" }));
-    expect(deps.onSetRuntimeData).toHaveBeenCalledWith("captions", payload);
-    expect(deps.onClearRuntimeData).toHaveBeenCalledWith("captions");
+    handler(
+      makeControlMessage("set-runtime-data", { channel: "captions", payload, requestId: 41 }),
+    );
+    handler(makeControlMessage("clear-runtime-data", { channel: "captions", requestId: 42 }));
+    expect(deps.onSetRuntimeData).toHaveBeenCalledWith("captions", payload, 41);
+    expect(deps.onClearRuntimeData).toHaveBeenCalledWith("captions", 42);
   });
 
   it("dispatches stop-media command", () => {
diff --git a/packages/player/src/runtime-in-srcdoc.test.ts b/packages/player/src/runtime-in-srcdoc.test.ts
index ca923d949c..be4b8388de 100644
--- a/packages/player/src/runtime-in-srcdoc.test.ts
+++ b/packages/player/src/runtime-in-srcdoc.test.ts
@@ -68,4 +68,14 @@ describe("ensureRuntimeBeforeBodyScripts", () => {
 
     expect(out.indexOf(URL)).toBeLessThan(out.indexOf("read()"));
   });
+
+  it("does not mistake a longer tag name for head", () => {
+    const out = ensureRuntimeBeforeBodyScripts(
+      `<html><header><script>early()</script></header><body><script>read()</script></body></html>`,
+      URL,
+    );
+
+    expect(out.indexOf(URL)).toBeLessThan(out.indexOf("<body>"));
+    expect(out.indexOf(URL)).toBeGreaterThan(out.indexOf("</header>"));
+  });
 });
diff --git a/packages/player/src/runtime-in-srcdoc.ts b/packages/player/src/runtime-in-srcdoc.ts
index 5027c8b6c5..cc8c0586e9 100644
--- a/packages/player/src/runtime-in-srcdoc.ts
+++ b/packages/player/src/runtime-in-srcdoc.ts
@@ -32,23 +32,49 @@ function alreadyHasRuntime(html: string, runtimeUrl: string): boolean {
   return /hyperframe\.runtime\.iife\.js|__hyperframes\s*=/.test(html);
 }
 
+type OpeningTag = { index: number; end: number };
+
+/** Find an opening tag in one linear pass, without a backtracking regex over caller-owned HTML. */
+function findOpeningTag(html: string, tagName: string): OpeningTag | null {
+  const lower = html.toLowerCase();
+  const prefix = `<${tagName}`;
+  let from = 0;
+  while (from < lower.length) {
+    const index = lower.indexOf(prefix, from);
+    if (index < 0) return null;
+    const boundary = lower[index + prefix.length];
+    const isBoundary =
+      boundary === ">" ||
+      boundary === " " ||
+      boundary === "\t" ||
+      boundary === "\n" ||
+      boundary === "\r" ||
+      boundary === "\f";
+    if (isBoundary) {
+      const close = lower.indexOf(">", index + prefix.length);
+      if (close < 0) return null;
+      return { index, end: close + 1 };
+    }
+    from = index + prefix.length;
+  }
+  return null;
+}
+
 export function ensureRuntimeBeforeBodyScripts(html: string, runtimeUrl: string): string {
   if (!html || alreadyHasRuntime(html, runtimeUrl)) return html;
 
   const tag = `<script src="${runtimeUrl}"></script>`;
-  const head = /<head[^>]*>/i.exec(html);
+  const head = findOpeningTag(html, "head");
   if (head) {
-    const at = head.index + head[0].length;
-    return html.slice(0, at) + tag + html.slice(at);
+    return html.slice(0, head.end) + tag + html.slice(head.end);
   }
   // No head: get in before <body> so body scripts still see the runtime. A
   // fragment with neither lands at the front, which is the same guarantee.
-  const body = /<body[^>]*>/i.exec(html);
+  const body = findOpeningTag(html, "body");
   if (body) return html.slice(0, body.index) + tag + html.slice(body.index);
-  const htmlTag = /<html[^>]*>/i.exec(html);
+  const htmlTag = findOpeningTag(html, "html");
   if (htmlTag) {
-    const at = htmlTag.index + htmlTag[0].length;
-    return html.slice(0, at) + tag + html.slice(at);
+    return html.slice(0, htmlTag.end) + tag + html.slice(htmlTag.end);
   }
   return tag + html;
 }

From 5910a7b1454837838fa14ca5cfae8785c05b1602 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 18:24:47 -0700
Subject: [PATCH 5/7] refactor(player): simplify runtime tag scanner

---
 packages/player/src/runtime-in-srcdoc.ts | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/packages/player/src/runtime-in-srcdoc.ts b/packages/player/src/runtime-in-srcdoc.ts
index cc8c0586e9..07ac7870ce 100644
--- a/packages/player/src/runtime-in-srcdoc.ts
+++ b/packages/player/src/runtime-in-srcdoc.ts
@@ -33,6 +33,7 @@ function alreadyHasRuntime(html: string, runtimeUrl: string): boolean {
 }
 
 type OpeningTag = { index: number; end: number };
+const OPENING_TAG_BOUNDARIES = new Set([">", " ", "\t", "\n", "\r", "\f"]);
 
 /** Find an opening tag in one linear pass, without a backtracking regex over caller-owned HTML. */
 function findOpeningTag(html: string, tagName: string): OpeningTag | null {
@@ -43,14 +44,7 @@ function findOpeningTag(html: string, tagName: string): OpeningTag | null {
     const index = lower.indexOf(prefix, from);
     if (index < 0) return null;
     const boundary = lower[index + prefix.length];
-    const isBoundary =
-      boundary === ">" ||
-      boundary === " " ||
-      boundary === "\t" ||
-      boundary === "\n" ||
-      boundary === "\r" ||
-      boundary === "\f";
-    if (isBoundary) {
+    if (OPENING_TAG_BOUNDARIES.has(boundary)) {
       const close = lower.indexOf(">", index + prefix.length);
       if (close < 0) return null;
       return { index, end: close + 1 };
@@ -60,7 +54,10 @@ function findOpeningTag(html: string, tagName: string): OpeningTag | null {
   return null;
 }
 
-export function ensureRuntimeBeforeBodyScripts(html: string, runtimeUrl: string): string {
+export function ensureRuntimeBeforeBodyScripts(
+  html: string,
+  runtimeUrl: string,
+): string {
   if (!html || alreadyHasRuntime(html, runtimeUrl)) return html;
 
   const tag = `<script src="${runtimeUrl}"></script>`;

From 8a7ddcbbf5421276be5328a31dc3cfd14f8d873a Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 18:29:35 -0700
Subject: [PATCH 6/7] style(player): apply repository formatter

---
 packages/player/src/runtime-in-srcdoc.ts | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/player/src/runtime-in-srcdoc.ts b/packages/player/src/runtime-in-srcdoc.ts
index 07ac7870ce..640958776b 100644
--- a/packages/player/src/runtime-in-srcdoc.ts
+++ b/packages/player/src/runtime-in-srcdoc.ts
@@ -54,10 +54,7 @@ function findOpeningTag(html: string, tagName: string): OpeningTag | null {
   return null;
 }
 
-export function ensureRuntimeBeforeBodyScripts(
-  html: string,
-  runtimeUrl: string,
-): string {
+export function ensureRuntimeBeforeBodyScripts(html: string, runtimeUrl: string): string {
   if (!html || alreadyHasRuntime(html, runtimeUrl)) return html;
 
   const tag = `<script src="${runtimeUrl}"></script>`;

From 5922da3c2442420613e6cce722eefa5772b594d0 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 24 Aug 2026 18:52:52 -0700
Subject: [PATCH 7/7] fix(player): type runtime tag boundaries

---
 packages/player/src/runtime-in-srcdoc.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/player/src/runtime-in-srcdoc.ts b/packages/player/src/runtime-in-srcdoc.ts
index 640958776b..190c73367d 100644
--- a/packages/player/src/runtime-in-srcdoc.ts
+++ b/packages/player/src/runtime-in-srcdoc.ts
@@ -33,7 +33,7 @@ function alreadyHasRuntime(html: string, runtimeUrl: string): boolean {
 }
 
 type OpeningTag = { index: number; end: number };
-const OPENING_TAG_BOUNDARIES = new Set([">", " ", "\t", "\n", "\r", "\f"]);
+const OPENING_TAG_BOUNDARIES = new Set<string | undefined>([">", " ", "\t", "\n", "\r", "\f"]);
 
 /** Find an opening tag in one linear pass, without a backtracking regex over caller-owned HTML. */
 function findOpeningTag(html: string, tagName: string): OpeningTag | null {