From 32a1492d05a6e17cb2d5f7d4676c2de92e29073b Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Thu, 30 Jul 2026 13:24:46 +0100
Subject: [PATCH 1/7] perf(core): cache-friendly audio fetch, edge gain ramps,
 fade-out stop in WebAudio transport

- decodeAudioElement: first fetch per src uses the normal HTTP cache (media
  URLs are stable; edited assets ship under new URLs). no-store is applied
  only on a RETRY after a failed attempt, preserving the late-asset
  self-heal semantics from #1602 without re-downloading identical bytes on
  every fresh document.
- schedulePlayback: ~8ms linear gain ramps at each source's effective start
  and (for bounded clips) into its scheduled end, so adjacent trimmed clips
  hand off with a micro-crossfade instead of a waveform-discontinuity pop.
- stopAll: fade to zero and defer the stop ~20ms instead of hard-cutting
  mid-waveform; node teardown moves to the ended listener.
---
 .../src/runtime/webAudioTransport.test.ts     | 116 +++++++++++++++-
 .../core/src/runtime/webAudioTransport.ts     | 128 ++++++++++++++----
 2 files changed, 220 insertions(+), 24 deletions(-)

diff --git a/packages/core/src/runtime/webAudioTransport.test.ts b/packages/core/src/runtime/webAudioTransport.test.ts
index 15f1825a13..96e0da471e 100644
--- a/packages/core/src/runtime/webAudioTransport.test.ts
+++ b/packages/core/src/runtime/webAudioTransport.test.ts
@@ -17,7 +17,13 @@ function createMockAudioContext(currentTime = 100) {
     _fireEnded: () => endedListeners.forEach((cb) => cb()),
   };
   const gainNode = {
-    gain: { value: 1 },
+    gain: {
+      value: 1,
+      setValueAtTime: vi.fn(),
+      linearRampToValueAtTime: vi.fn(),
+      cancelScheduledValues: vi.fn(),
+      setTargetAtTime: vi.fn(),
+    },
     connect: vi.fn(),
     disconnect: vi.fn(),
   };
@@ -464,5 +470,113 @@ describe("WebAudioTransport", () => {
       expect(fetchMock).toHaveBeenCalledTimes(1); // short-circuited, no re-fetch
       vi.unstubAllGlobals();
     });
+
+    it("first fetch per src uses the HTTP cache; only a RETRY bypasses it with no-store", async () => {
+      const transport = transportWithDecode(async () => ({}) as AudioBuffer);
+      const fetchMock = vi
+        .fn()
+        .mockResolvedValueOnce({ ok: false, status: 404 }) // transient — not blacklisted
+        .mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(8) });
+      vi.stubGlobal("fetch", fetchMock);
+
+      await transport.decodeAudioElement(el("tts.wav"));
+      // Media URLs are stable (edited assets ship under new URLs), so the first
+      // request must be allowed to hit the HTTP cache.
+      expect(fetchMock).toHaveBeenNthCalledWith(1, "tts.wav", undefined);
+
+      await transport.decodeAudioElement(el("tts.wav"));
+      // A retry after a failure must actually re-request — not replay a cached
+      // 404 from the attempt we chose not to blacklist.
+      expect(fetchMock).toHaveBeenNthCalledWith(2, "tts.wav", { cache: "no-store" });
+      vi.unstubAllGlobals();
+    });
+  });
+
+  describe("edge gain ramps (cut-boundary pop suppression)", () => {
+    async function rampsFor(args: {
+      compositionStart: number;
+      compositionTime: number;
+      volume: number;
+      clipDuration?: number;
+    }) {
+      const { transport, mock, gen } = setupTransport(100);
+      await transport.schedulePlayback(
+        mockEl,
+        mockBuffer,
+        args.compositionStart,
+        0,
+        args.compositionTime,
+        args.volume,
+        gen,
+        1,
+        args.clipDuration,
+      );
+      return mock.gainNode.gain;
+    }
+
+    function expectRamps(
+      g: Awaited<ReturnType<typeof rampsFor>>,
+      volume: number,
+      startAt: number,
+      endAt: number,
+    ) {
+      expect(g.setValueAtTime).toHaveBeenNthCalledWith(1, 0, startAt);
+      expect(g.linearRampToValueAtTime).toHaveBeenNthCalledWith(1, volume, startAt + 0.008);
+      expect(g.setValueAtTime).toHaveBeenNthCalledWith(2, volume, endAt - 0.008);
+      expect(g.linearRampToValueAtTime).toHaveBeenNthCalledWith(2, 0, endAt);
+    }
+
+    it("ramps gain in at the source's effective start and out before a bounded end", async () => {
+      // elapsed = 8-5 = 3 into a 10s clip → starts now (100), ends at 107.
+      const g = await rampsFor({
+        compositionStart: 5,
+        compositionTime: 8,
+        volume: 0.7,
+        clipDuration: 10,
+      });
+      expectRamps(g, 0.7, 100, 107);
+    });
+
+    it("a future-scheduled bounded clip ramps at its delayed start/end", async () => {
+      // compositionStart 10 at compositionTime 8 → starts at ctx time 102, ends 112.
+      const g = await rampsFor({
+        compositionStart: 10,
+        compositionTime: 8,
+        volume: 1,
+        clipDuration: 10,
+      });
+      expectRamps(g, 1, 102, 112);
+    });
+
+    it("unbounded sources get only the ramp-in", async () => {
+      const g = await rampsFor({ compositionStart: 0, compositionTime: 0, volume: 1 });
+      expect(g.setValueAtTime).toHaveBeenCalledTimes(1);
+      expect(g.linearRampToValueAtTime).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("stopAll fade-out (pause/seek pop suppression)", () => {
+    it("fades gain and defers the stop instead of hard-cutting mid-waveform", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+      const el = { muted: false } as HTMLMediaElement;
+
+      await transport.schedulePlayback(el, mockBuffer, 0, 0, 0, 1, gen);
+      expect(el.muted).toBe(true);
+
+      transport.stopAll();
+
+      const g = mock.gainNode.gain;
+      expect(g.cancelScheduledValues).toHaveBeenCalledWith(100);
+      expect(g.setTargetAtTime).toHaveBeenCalledWith(0, 100, expect.any(Number));
+      expect(mock.sourceNode.stop).toHaveBeenCalledWith(expect.closeTo(100.02, 5));
+      // State restores immediately; node teardown happens on `ended`.
+      expect(el.muted).toBe(false);
+      expect(transport.isActive()).toBe(false);
+      expect(mock.gainNode.disconnect).not.toHaveBeenCalled();
+
+      mock.sourceNode._fireEnded();
+      expect(mock.sourceNode.disconnect).toHaveBeenCalled();
+      expect(mock.gainNode.disconnect).toHaveBeenCalled();
+    });
   });
 });
diff --git a/packages/core/src/runtime/webAudioTransport.ts b/packages/core/src/runtime/webAudioTransport.ts
index d4497ac389..40a2f779fc 100644
--- a/packages/core/src/runtime/webAudioTransport.ts
+++ b/packages/core/src/runtime/webAudioTransport.ts
@@ -70,10 +70,58 @@ export type ScheduledSource = {
   bounded: boolean;
 };
 
+/** Seconds of linear gain ramp applied at a scheduled source's start (and, for
+ *  bounded clips, before its end). Short enough to be inaudible as a fade, long
+ *  enough to remove the waveform-discontinuity click a hard cut produces. */
+const EDGE_RAMP_SECONDS = 0.008;
+
+/** Time constant for the stop-side fade in stopAll(); sources are stopped a few
+ *  time constants later so pause/seek never end mid-waveform with a pop. */
+const STOP_FADE_TIME_CONSTANT = 0.004;
+const STOP_FADE_TAIL_SECONDS = 0.02;
+
+/**
+ * Anti-pop gain automation: a hard cut starts/stops mid-waveform, which is an
+ * audible click. Ramp gain over EDGE_RAMP_SECONDS at the source's effective
+ * start and (for bounded clips) into its scheduled end, so adjacent trimmed
+ * clips hand off with a ~8ms micro-crossfade instead of a pop. Best-effort: a
+ * missing/throwing AudioParam API must never break playback.
+ */
+function applyEdgeGainRamps(
+  gain: GainNode["gain"],
+  opts: {
+    volume: number;
+    elapsed: number;
+    scheduledAt: number;
+    safeRate: number;
+    clipDuration: number;
+  },
+): void {
+  try {
+    const { volume, elapsed, scheduledAt, safeRate, clipDuration } = opts;
+    const startAt = elapsed >= 0 ? scheduledAt : scheduledAt + -elapsed / safeRate;
+    gain.setValueAtTime(0, startAt);
+    gain.linearRampToValueAtTime(volume, startAt + EDGE_RAMP_SECONDS);
+    const hasBound = Number.isFinite(clipDuration) && clipDuration > 0;
+    if (!hasBound) return;
+    const clipSourceLen = clipDuration * safeRate;
+    const endAt =
+      elapsed >= 0
+        ? scheduledAt + (clipSourceLen - elapsed) / safeRate
+        : startAt + clipSourceLen / safeRate;
+    if (endAt - startAt <= EDGE_RAMP_SECONDS * 4) return;
+    gain.setValueAtTime(volume, endAt - EDGE_RAMP_SECONDS);
+    gain.linearRampToValueAtTime(0, endAt);
+  } catch (err) {
+    swallow("webAudioTransport.edgeRamp", err);
+  }
+}
+
 export class WebAudioTransport {
   private _ctx: AudioContext | null = null;
   private _bufferCache = new Map<string, AudioBuffer>();
   private _failedSrcs = new Set<string>();
+  private _fetchAttemptedSrcs = new Set<string>();
   private _activeSources: ScheduledSource[] = [];
   private _masterGain: GainNode | null = null;
   // Composition-time reference frame: at AudioContext time `_rateAnchorCtx`,
@@ -112,26 +160,8 @@ export class WebAudioTransport {
     if (this._failedSrcs.has(src)) return null;
     if (!this._ctx) return null;
 
-    // Fetch the bytes. A network error or non-OK status (e.g. a 404 for an
-    // asset that simply has not been uploaded yet) is TRANSIENT — return null
-    // WITHOUT blacklisting, so the next play/seek generation retries once the
-    // asset becomes available. (Previously these were added to `_failedSrcs`,
-    // which is never cleared, permanently silencing a merely-late track.)
-    let arrayBuffer: ArrayBuffer;
-    try {
-      // `no-store`: a retry must actually re-request the asset — not replay a
-      // cached 404/stale response from the failed attempt that we chose not to
-      // blacklist.
-      const response = await fetch(src, { cache: "no-store" });
-      if (!response.ok) {
-        swallow("webAudioTransport.fetch", new Error(`${response.status} ${src}`));
-        return null;
-      }
-      arrayBuffer = await response.arrayBuffer();
-    } catch (err) {
-      swallow("webAudioTransport.fetch", err);
-      return null;
-    }
+    const arrayBuffer = await this._fetchAudioBytes(src);
+    if (!arrayBuffer) return null;
 
     // A decode failure means the bytes themselves are unusable (corrupt or an
     // unsupported codec) — that IS permanent, so blacklist to avoid re-decoding
@@ -147,6 +177,35 @@ export class WebAudioTransport {
     }
   }
 
+  /**
+   * Fetch the bytes for a source. A network error or non-OK status (e.g. a 404
+   * for an asset that simply has not been uploaded yet) is TRANSIENT — return
+   * null WITHOUT blacklisting, so the next play/seek generation retries once
+   * the asset becomes available. (Previously these were added to `_failedSrcs`,
+   * which is never cleared, permanently silencing a merely-late track.)
+   *
+   * The first attempt per src uses the normal HTTP cache — media sources are
+   * stable URLs (an edited asset ships under a new URL), so bypassing the cache
+   * here just re-downloads identical bytes on every fresh document. `no-store`
+   * only on a RETRY: a retry must actually re-request the asset — not replay a
+   * cached 404/stale response from the failed attempt we chose not to blacklist.
+   */
+  private async _fetchAudioBytes(src: string): Promise<ArrayBuffer | null> {
+    try {
+      const isRetry = this._fetchAttemptedSrcs.has(src);
+      this._fetchAttemptedSrcs.add(src);
+      const response = await fetch(src, isRetry ? { cache: "no-store" } : undefined);
+      if (!response.ok) {
+        swallow("webAudioTransport.fetch", new Error(`${response.status} ${src}`));
+        return null;
+      }
+      return await response.arrayBuffer();
+    } catch (err) {
+      swallow("webAudioTransport.fetch", err);
+      return null;
+    }
+  }
+
   startGeneration(): number {
     this._playGeneration += 1;
     return this._playGeneration;
@@ -208,6 +267,8 @@ export class WebAudioTransport {
         return null;
       }
 
+      applyEdgeGainRamps(gainNode.gain, { volume, elapsed, scheduledAt, safeRate, clipDuration });
+
       const priorMuted = el.muted;
       el.muted = true;
       logFallbackHandoff(el, priorMuted);
@@ -226,6 +287,14 @@ export class WebAudioTransport {
       this._paused = false;
 
       sourceNode.addEventListener("ended", () => {
+        // Sources are one-shot; release the graph nodes whether the source
+        // ended naturally or via stopAll()'s deferred fade-out stop.
+        try {
+          sourceNode.disconnect();
+          gainNode.disconnect();
+        } catch {
+          // already disconnected
+        }
         const idx = this._activeSources.indexOf(scheduled);
         if (idx !== -1) {
           this._activeSources.splice(idx, 1);
@@ -273,11 +342,24 @@ export class WebAudioTransport {
   }
 
   stopAll(): void {
+    const ctx = this._ctx;
     for (const source of this._activeSources) {
       try {
-        source.sourceNode.stop();
-        source.sourceNode.disconnect();
-        source.gainNode.disconnect();
+        if (ctx) {
+          // Fade instead of a hard cut so pause/seek never stop mid-waveform
+          // with an audible pop. The source rings for ~STOP_FADE_TAIL_SECONDS
+          // at rapidly-decaying gain, then stops; its `ended` listener
+          // disconnects the nodes. (A seek's freshly-scheduled sources overlap
+          // this brief tail — a micro-crossfade, which is the point.)
+          const now = ctx.currentTime;
+          source.gainNode.gain.cancelScheduledValues(now);
+          source.gainNode.gain.setTargetAtTime(0, now, STOP_FADE_TIME_CONSTANT);
+          source.sourceNode.stop(now + STOP_FADE_TAIL_SECONDS);
+        } else {
+          source.sourceNode.stop();
+          source.sourceNode.disconnect();
+          source.gainNode.disconnect();
+        }
       } catch {
         // already stopped
       }

From f75042a440d95b944704ae8a4ed43a790442829e Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Thu, 30 Jul 2026 13:25:18 +0100
Subject: [PATCH 2/7] perf(core): pre-decode audio at mount, upcoming-clip
 readiness, stall telemetry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cut-boundary playback smoothness for segment-heavy compositions (an editor
emitting one media element per cut):

- init: decode-only warm pass over audio[data-start] as soon as the WebAudio
  transport exists (and periodically for late-loaded sub-compositions), so
  first play after a document (re)load doesn't run full-file decodeAudioData
  lazily while sound falls back to the buffering HTMLMedia element.
- init: staged preload — when a composition carries >6 timed media elements,
  far-future segments (start >10s) begin preload=metadata; the sync layer
  upgrades them as the playhead approaches. Stops the mount-time fetch
  stampede that leaves EARLY segments buffering late.
- media: two readiness stages for upcoming clips while playing: pre-seek to
  the clip's media offset ~3s ahead (buffer the RIGHT region), and a muted
  video pre-roll ~350ms ahead so activation is a visibility flip instead of
  a cold seek+play (decoder reset ~150ms freeze).
- init: bounded runtime_media_stall diagnostics (waiting/stalled while
  playing) + freeze the transport clock when a buffering ACTIVE video has no
  audio mastering the clock (video-only compositions), mirroring the
  existing audio-buffering freeze.
---
 packages/core/src/runtime/init.test.ts  |  57 ++++++++++++
 packages/core/src/runtime/init.ts       | 114 +++++++++++++++++++++++-
 packages/core/src/runtime/media.test.ts |  70 +++++++++++++++
 packages/core/src/runtime/media.ts      |  87 ++++++++++++++++++
 4 files changed, 326 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts
index ff91e738ed..9f81d9de71 100644
--- a/packages/core/src/runtime/init.test.ts
+++ b/packages/core/src/runtime/init.test.ts
@@ -2683,4 +2683,61 @@ describe("initSandboxRuntimeModular", () => {
       }).not.toThrow();
     });
   });
+
+  describe("audio buffer pre-decode at mount", () => {
+    it("warm-decodes every timed audio source before any play()", async () => {
+      const decodeAudioData = vi.fn(async () => ({}) as AudioBuffer);
+      class MockAudioContext {
+        currentTime = 0;
+        state = "running";
+        destination = {};
+        decodeAudioData = decodeAudioData;
+        createGain() {
+          return { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
+        }
+        resume = vi.fn();
+        close = vi.fn();
+      }
+      vi.stubGlobal("AudioContext", MockAudioContext);
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        arrayBuffer: async () => new ArrayBuffer(8),
+      }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      try {
+        const root = document.createElement("div");
+        root.setAttribute("data-composition-id", "main");
+        root.setAttribute("data-root", "true");
+        root.setAttribute("data-start", "0");
+        root.setAttribute("data-duration", "10");
+        root.setAttribute("data-width", "1920");
+        root.setAttribute("data-height", "1080");
+        const audioA = document.createElement("audio");
+        audioA.setAttribute("data-start", "0");
+        audioA.setAttribute("data-duration", "5");
+        audioA.setAttribute("src", "https://media.example/a.mp3");
+        const audioB = document.createElement("audio");
+        audioB.setAttribute("data-start", "5");
+        audioB.setAttribute("data-duration", "5");
+        audioB.setAttribute("src", "https://media.example/b.mp3");
+        root.append(audioA, audioB);
+        document.body.appendChild(root);
+        window.__timelines = { main: createMockTimeline(10) };
+
+        initSandboxRuntimeModular();
+
+        // No play() has happened — the decode must be driven by mount alone.
+        await vi.waitFor(() => {
+          expect(fetchMock).toHaveBeenCalledTimes(2);
+          expect(decodeAudioData).toHaveBeenCalledTimes(2);
+        });
+        const urls = fetchMock.mock.calls.map((call) => String(call[0]));
+        expect(urls.some((u) => u.endsWith("a.mp3"))).toBe(true);
+        expect(urls.some((u) => u.endsWith("b.mp3"))).toBe(true);
+      } finally {
+        vi.unstubAllGlobals();
+      }
+    });
+  });
 });
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index cf65ecd262..d6b268c2c0 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -174,6 +174,9 @@ export function initSandboxRuntimeModular(): void {
   let webAudioReady = false;
   void webAudio.init().then((ok) => {
     webAudioReady = ok;
+    // Warm the decoded-buffer cache as soon as the transport exists (decode
+    // works on a suspended AudioContext, so no user gesture is needed).
+    if (ok) predecodeAudioClipBuffers();
   });
   // `_auto` is a Studio-internal keyframe marker (an auto-tracked endpoint the
   // parser reads back), NOT an animatable property. Register it as a no-op GSAP
@@ -1808,12 +1811,49 @@ export function initSandboxRuntimeModular(): void {
     }
   };
 
+  // Boundary-readiness telemetry: surface playback stalls (`waiting`/`stalled`
+  // on a timed media element while the transport plays) so cut-boundary tuning
+  // can target the right layer. Bounded per document to avoid diagnostic spam.
+  let mediaStallDiagnosticsPosted = 0;
+  const MAX_MEDIA_STALL_DIAGNOSTICS = 20;
+  const onMediaStallEvent = (event: Event) => {
+    const el = event.currentTarget;
+    if (!(el instanceof HTMLMediaElement)) return;
+    if (!state.isPlaying || state.tornDown) return;
+    if (mediaStallDiagnosticsPosted >= MAX_MEDIA_STALL_DIAGNOSTICS) return;
+    mediaStallDiagnosticsPosted += 1;
+    let bufferedEnd: number | null = null;
+    try {
+      bufferedEnd = el.buffered.length > 0 ? el.buffered.end(el.buffered.length - 1) : null;
+    } catch {
+      // buffered ranges unavailable
+    }
+    postRuntimeMessage({
+      source: "hf-preview",
+      type: "diagnostic",
+      code: "runtime_media_stall",
+      details: {
+        event: event.type,
+        tagName: el.tagName.toLowerCase(),
+        currentSrc: el.currentSrc || null,
+        readyState: el.readyState,
+        networkState: el.networkState,
+        mediaTime: el.currentTime,
+        bufferedEnd,
+        compositionTime: state.currentTime,
+        clipStart: Number.parseFloat(el.dataset.start ?? "") || null,
+      },
+    });
+  };
+
   const unbindMediaMetadataListeners = () => {
     for (const mediaEl of metadataBoundMedia) {
       mediaEl.removeEventListener("loadedmetadata", scheduleMetadataDurationHydration);
       mediaEl.removeEventListener("durationchange", scheduleMetadataDurationHydration);
       mediaEl.removeEventListener("loadedmetadata", onMediaLoadedMetadataForProxy);
       mediaEl.removeEventListener("error", onMediaErrorForProxy);
+      mediaEl.removeEventListener("waiting", onMediaStallEvent);
+      mediaEl.removeEventListener("stalled", onMediaStallEvent);
     }
     metadataBoundMedia.clear();
   };
@@ -1821,6 +1861,19 @@ export function initSandboxRuntimeModular(): void {
   const bindMediaMetadataListeners = () => {
     if (state.tornDown) return;
     const mediaEls = Array.from(document.querySelectorAll("video, audio")) as HTMLMediaElement[];
+    // Segment-heavy compositions (editors emit one media element per cut) must
+    // not full-preload EVERYTHING at mount: dozens of parallel fetches contend
+    // for the connection pool and the EARLY segments buffer late. Above the
+    // threshold, far-future timed segments start metadata-only; the sync layer
+    // upgrades them to full preload as the playhead approaches (media.ts
+    // readiness stages set preload="auto" ~3s ahead).
+    const EAGER_PRELOAD_MAX_TIMED_MEDIA = 6;
+    const STAGED_PRELOAD_HORIZON_SECONDS = 10;
+    const timedMediaCount = mediaEls.reduce(
+      (count, el) => count + (el.hasAttribute("data-start") ? 1 : 0),
+      0,
+    );
+    const stagePreload = timedMediaCount > EAGER_PRELOAD_MAX_TIMED_MEDIA;
     for (const mediaEl of mediaEls) {
       if (metadataBoundMedia.has(mediaEl)) continue;
       metadataBoundMedia.add(mediaEl);
@@ -1835,6 +1888,8 @@ export function initSandboxRuntimeModular(): void {
       // for <audio> — all guarded inside mediaProxy.ts itself.
       mediaEl.addEventListener("loadedmetadata", onMediaLoadedMetadataForProxy);
       mediaEl.addEventListener("error", onMediaErrorForProxy);
+      mediaEl.addEventListener("waiting", onMediaStallEvent);
+      mediaEl.addEventListener("stalled", onMediaStallEvent);
 
       // Proactive proxy-fallback trigger: consult the codec map and swap
       // BEFORE the eager load() below, so a known-hostile asset never even
@@ -1845,8 +1900,12 @@ export function initSandboxRuntimeModular(): void {
       // Eagerly preload media data so audio/video is buffered before the user
       // clicks play. Without this, the first play() call fires on un-fetched
       // media, producing silence or choppy audio until the browser caches it.
-      if (mediaEl.preload !== "auto") {
-        mediaEl.preload = "auto";
+      // Exception: staged preload for far-future segments (see above).
+      const startAttr = Number.parseFloat(mediaEl.dataset.start ?? "");
+      const farFuture = Number.isFinite(startAttr) && startAttr > STAGED_PRELOAD_HORIZON_SECONDS;
+      const targetPreload = stagePreload && farFuture ? "metadata" : "auto";
+      if (mediaEl.preload !== targetPreload) {
+        mediaEl.preload = targetPreload;
       }
       if (mediaEl.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) {
         mediaEl.load();
@@ -1861,6 +1920,29 @@ export function initSandboxRuntimeModular(): void {
     }
   };
 
+  // Decode-only warm pass over every timed audio source so WebAudio buffers are
+  // ready BEFORE the first play() instead of being decoded lazily inside it.
+  // The lazy path costs a full-file fetch+decodeAudioData per source at the
+  // moment the user hits play — on a freshly (re)loaded document (every editor
+  // edit reloads the preview iframe) that gap plays through the HTMLMedia
+  // fallback, heard as an audio dropout. Pre-decoding overlaps that work with
+  // document load. `decodeAudioElement` dedupes via its buffer cache and
+  // failure blacklist, so repeated calls per element are cheap map hits.
+  // Skipped during render capture: the producer mixes audio with ffmpeg from
+  // source files and never plays through WebAudio.
+  const predecodeAudioClipBuffers = () => {
+    if (state.tornDown || !webAudioReady) return;
+    if (state.nativeMediaSyncDisabled || state.webAudioMediaDisabled) return;
+    if ((window as Window & { __HF_RENDER_CAPTURE_MODE?: boolean }).__HF_RENDER_CAPTURE_MODE) {
+      return;
+    }
+    const audioEls = document.querySelectorAll("audio[data-start]");
+    for (const el of audioEls) {
+      if (!(el instanceof HTMLMediaElement) || !el.isConnected) continue;
+      void webAudio.decodeAudioElement(el);
+    }
+  };
+
   const probeAndCacheVolumeKeyframes = (mediaEl: HTMLMediaElement) => {
     if (volumeKeyframeCache.has(mediaEl)) return;
     probeAndCacheElementVolume(
@@ -2882,6 +2964,9 @@ export function initSandboxRuntimeModular(): void {
       }
       if (transportTickCount % 30 === 0) {
         bindMediaMetadataListeners();
+        // Also warm decode for audio elements discovered after mount (loaded
+        // sub-compositions) or bound before the async WebAudio init resolved.
+        predecodeAudioClipBuffers();
       }
 
       // Sync clock duration with the resolved timeline each tick (catches async
@@ -2933,6 +3018,31 @@ export function initSandboxRuntimeModular(): void {
               break;
             }
           }
+          if (!foundActive) {
+            // No audio is mastering the clock (video-only composition, or the
+            // audio hasn't reached its window). A buffering ACTIVE video should
+            // freeze time the same way buffering audio does above — otherwise
+            // the monotonic clock runs ahead while frames are stuck, and the
+            // drift correction later hard-seeks (decoder reset) to catch up.
+            const videoEls = document.querySelectorAll("video[data-start]");
+            for (const rawEl of videoEls) {
+              if (!(rawEl instanceof HTMLMediaElement) || !rawEl.isConnected) continue;
+              const start = Number.parseFloat(rawEl.dataset.start ?? "");
+              if (!Number.isFinite(start)) continue;
+              const durAttr = Number.parseFloat(rawEl.dataset.duration ?? "");
+              const end = Number.isFinite(durAttr) && durAttr > 0 ? start + durAttr : Infinity;
+              if (state.currentTime < start || state.currentTime >= end) continue;
+              if (
+                !rawEl.paused &&
+                !rawEl.error &&
+                rawEl.readyState < HTMLMediaElement.HAVE_FUTURE_DATA
+              ) {
+                clock.attachAudioSource({ currentTimeSeconds: state.currentTime });
+                foundActive = true;
+              }
+              break;
+            }
+          }
           if (!foundActive && clock.hasAudioSource()) {
             clock.detachAudioSource();
           }
diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
index 6de44a32fb..3a1b63e3fb 100644
--- a/packages/core/src/runtime/media.test.ts
+++ b/packages/core/src/runtime/media.test.ts
@@ -1045,4 +1045,74 @@ describe("syncRuntimeMedia", () => {
     });
     expect(clip.el.muted).toBe(true);
   });
+
+  describe("upcoming-clip readiness (boundary smoothness)", () => {
+    function readyClip(overrides?: Partial<RuntimeMediaClip>): RuntimeMediaClip {
+      const clip = createMockClip(overrides);
+      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+      return clip;
+    }
+
+    function syncAt(
+      clip: RuntimeMediaClip,
+      timeSeconds: number,
+      extra?: { playing?: boolean; outputMuted?: boolean },
+    ): void {
+      syncRuntimeMedia({
+        clips: [clip],
+        timeSeconds,
+        playing: extra?.playing ?? true,
+        playbackRate: 1,
+        outputMuted: extra?.outputMuted,
+      });
+    }
+
+    it("pre-seeks an upcoming clip to its media offset within the lookahead window", () => {
+      const clip = readyClip({ start: 7, end: 12, mediaStart: 30 });
+      clip.el.preload = "metadata";
+      syncAt(clip, 5);
+      expect(clip.el.currentTime).toBe(30);
+      expect(clip.el.preload).toBe("auto");
+      expect(clip.el.play).not.toHaveBeenCalled();
+    });
+
+    it("leaves clips beyond the lookahead window untouched", () => {
+      const clip = readyClip({ start: 20, end: 30, mediaStart: 30 });
+      clip.el.currentTime = 3;
+      syncAt(clip, 5);
+      expect(clip.el.currentTime).toBe(3);
+      expect(clip.el.play).not.toHaveBeenCalled();
+    });
+
+    it("pre-rolls a mutable upcoming video just before its boundary — playing, muted, not paused", () => {
+      const clip = readyClip({ start: 5.2, end: 12, mediaStart: 30 });
+      syncAt(clip, 5, { outputMuted: true });
+      expect(clip.el.play).toHaveBeenCalled();
+      expect(clip.el.muted).toBe(true);
+      // Rolls in from mediaStart - lead so playback crosses the boundary at
+      // exactly mediaStart — activation then sees ~zero drift (no cold seek).
+      expect(clip.el.currentTime).toBeCloseTo(29.8, 5);
+      expect(clip.el.pause).not.toHaveBeenCalled();
+    });
+
+    it("never pre-rolls a video that would be audible — falls back to pre-seek", () => {
+      const clip = readyClip({ start: 5.2, end: 12, mediaStart: 30 });
+      syncAt(clip, 5);
+      expect(clip.el.play).not.toHaveBeenCalled();
+      expect(clip.el.currentTime).toBe(30);
+    });
+
+    it("skips the pre-roll when the roll-in would cross media time 0", () => {
+      const clip = readyClip({ start: 5.2, end: 12, mediaStart: 0.05 });
+      syncAt(clip, 5, { outputMuted: true });
+      expect(clip.el.play).not.toHaveBeenCalled();
+    });
+
+    it("paused transport leaves upcoming clips untouched", () => {
+      const clip = readyClip({ start: 6, end: 12, mediaStart: 30 });
+      syncAt(clip, 5, { playing: false });
+      expect(clip.el.currentTime).toBe(0);
+      expect(clip.el.play).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
index 21af57b1e0..117971883f 100644
--- a/packages/core/src/runtime/media.ts
+++ b/packages/core/src/runtime/media.ts
@@ -161,6 +161,28 @@ function isUnplayable(el: HTMLMediaElement): boolean {
 
 const lastRuntimeAppliedVolume = new WeakMap<HTMLMediaElement, number>();
 
+// ── Upcoming-clip readiness (boundary smoothness) ───────────────────────────
+// A clip whose window starts soon is prepared BEFORE it activates, so the
+// boundary doesn't pay a cold seek (decoder reset ≈ ~150ms freeze) or an
+// unbuffered play. Two stages:
+//
+//  1. Pre-seek (UPCOMING_PRESEEK_WINDOW_SECONDS ahead): park el.currentTime at
+//     the clip's media offset so the browser buffers the RIGHT region of the
+//     source. Eager mount-time preload buffers from offset 0 — useless for a
+//     segment trimmed to start at, say, 63s.
+//
+//  2. Pre-roll (PREROLL_WINDOW_SECONDS ahead, muted VIDEO only): start playing
+//     from (mediaStart - lead·rate) while the element is still hidden by the
+//     visibility sync, so its decoder is already running when the window
+//     opens. Activation's first tick then sees near-zero drift → no hard seek,
+//     and the element is already playing → no play() latency. The boundary
+//     becomes a pure visibility flip. Only entered when the element is (or
+//     must be) muted, so the pre-roll can never leak audio.
+const UPCOMING_PRESEEK_WINDOW_SECONDS = 3;
+const PREROLL_WINDOW_SECONDS = 0.35;
+const upcomingPreseeked = new WeakSet<HTMLMediaElement>();
+const prerolling = new WeakSet<HTMLMediaElement>();
+
 function clampVolume(volume: number): number {
   if (!Number.isFinite(volume)) return 1;
   return Math.max(0, Math.min(1, volume));
@@ -257,6 +279,9 @@ export function syncRuntimeMedia(params: {
       relTime >= 0 &&
       (!el.ended || clip.loop || isHeldVideoTail || canSeekEndedVideoBackward);
     if (isActive) {
+      // A fresh activation ends any readiness stage for this element.
+      upcomingPreseeked.delete(el);
+      prerolling.delete(el);
       // Loop wrapping: when media reaches end, restart from mediaStart
       if (clip.loop && clip.sourceDuration != null && clip.sourceDuration > 0) {
         const loopLength = clip.sourceDuration - clip.mediaStart;
@@ -439,6 +464,68 @@ export function syncRuntimeMedia(params: {
       }
       continue;
     }
+    // Inactive but starting soon while the transport plays: run the readiness
+    // stages (see the constants above) instead of the plain evict+pause.
+    const leadSeconds = clip.start - params.timeSeconds;
+    if (
+      params.playing &&
+      leadSeconds > 0 &&
+      leadSeconds <= UPCOMING_PRESEEK_WINDOW_SECONDS &&
+      !isUnplayable(el)
+    ) {
+      if (el.preload !== "auto") el.preload = "auto";
+      const rate = clip.playbackRate * params.playbackRate;
+      // Pre-roll only when the element is already muted or the tick would mute
+      // it anyway (transport-owned output / user mute) — audio can never leak.
+      const mutedThroughPreroll = forceMuteAll || !!params.outputMuted || el.muted;
+      const prerollFrom = clip.mediaStart - leadSeconds * rate;
+      if (
+        el.tagName === "VIDEO" &&
+        mutedThroughPreroll &&
+        leadSeconds <= PREROLL_WINDOW_SECONDS &&
+        prerollFrom >= 0
+      ) {
+        if (!prerolling.has(el)) {
+          prerolling.add(el);
+          el.muted = true;
+          try {
+            el.playbackRate = rate;
+            el.currentTime = prerollFrom;
+          } catch (err) {
+            swallow("runtime.media.preroll", err);
+          }
+          if (el.paused && !playRequested.has(el)) {
+            markPlayRequested(el);
+            void el.play().catch(() => {
+              // Muted playback is allowed by every autoplay policy; a rejection
+              // here is transient (element mid-load) — clear the in-flight flag
+              // so a later tick can retry, and let the activation-path play()
+              // remain the authority for surfacing real failures.
+              playRequested.delete(el);
+            });
+          }
+        }
+        continue; // never pause a pre-rolling element
+      }
+      prerolling.delete(el);
+      if (!upcomingPreseeked.has(el)) {
+        upcomingPreseeked.add(el);
+        if (
+          el.readyState >= HTMLMediaElement.HAVE_METADATA &&
+          Math.abs(el.currentTime - clip.mediaStart) > 0.25
+        ) {
+          try {
+            el.currentTime = clip.mediaStart;
+          } catch (err) {
+            swallow("runtime.media.preseek", err);
+          }
+        }
+      }
+      if (!el.paused) el.pause();
+      continue;
+    }
+    prerolling.delete(el);
+    upcomingPreseeked.delete(el);
     // Clip left its active window — drop the offset baseline so the next
     // activation (e.g. re-entering a sub-composition) gets a hard resync.
     evictMediaSyncState(el);

From 3ad5af3fb53c4bcddbc68ff6a31aa560698036ec Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Thu, 30 Jul 2026 14:41:43 +0100
Subject: [PATCH 3/7] perf(core): bound audio pre-decode to the playhead
 window; tear down on pagehide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The mount-time warm pass fetched every timed audio source's WHOLE file and
held its decoded PCM (~23MB per stereo minute) — on every document load. In
an editor that reloads the preview iframe per edit (and keeps a standby
iframe), a multi-clip composition multiplied that into gigabytes and could
OOM the tab. Pre-decode now warms only clips near the current time (the
periodic re-run slides the window with the playhead; play() decodes exactly
what it needs as before), embedders can opt a never-played document out via
window.__HF_AUDIO_PREDECODE_DISABLED, and teardown (which closes the
AudioContext and drops the buffer cache) also runs on pagehide — the
dependable unload signal for iframes whose document is replaced.
---
 packages/core/src/runtime/init.test.ts | 67 ++++++++++++++++++++++++++
 packages/core/src/runtime/init.ts      | 59 ++++++++++++++++++-----
 2 files changed, 113 insertions(+), 13 deletions(-)

diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts
index 9f81d9de71..57026dee82 100644
--- a/packages/core/src/runtime/init.test.ts
+++ b/packages/core/src/runtime/init.test.ts
@@ -2739,5 +2739,72 @@ describe("initSandboxRuntimeModular", () => {
         vi.unstubAllGlobals();
       }
     });
+
+    it("only warms clips near the playhead, and honors the embedder opt-out", async () => {
+      const decodeAudioData = vi.fn(async () => ({}) as AudioBuffer);
+      class MockAudioContext {
+        currentTime = 0;
+        state = "running";
+        destination = {};
+        decodeAudioData = decodeAudioData;
+        createGain() {
+          return { gain: { value: 1 }, connect: vi.fn(), disconnect: vi.fn() };
+        }
+        resume = vi.fn();
+        close = vi.fn();
+      }
+      vi.stubGlobal("AudioContext", MockAudioContext);
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        arrayBuffer: async () => new ArrayBuffer(8),
+      }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      try {
+        const root = document.createElement("div");
+        root.setAttribute("data-composition-id", "main");
+        root.setAttribute("data-root", "true");
+        root.setAttribute("data-start", "0");
+        root.setAttribute("data-duration", "600");
+        root.setAttribute("data-width", "1920");
+        root.setAttribute("data-height", "1080");
+        const near = document.createElement("audio");
+        near.setAttribute("data-start", "0");
+        near.setAttribute("data-duration", "5");
+        near.setAttribute("src", "https://media.example/near.mp3");
+        const far = document.createElement("audio");
+        far.setAttribute("data-start", "300");
+        far.setAttribute("data-duration", "5");
+        far.setAttribute("src", "https://media.example/far.mp3");
+        root.append(near, far);
+        document.body.appendChild(root);
+        window.__timelines = { main: createMockTimeline(600) };
+
+        initSandboxRuntimeModular();
+
+        // Warming a whole long composition costs a full-file fetch + ~23MB of
+        // PCM per stereo minute PER SOURCE — only playhead-proximate clips may
+        // pre-decode; the rest stay lazy until the playhead approaches.
+        await vi.waitFor(() => {
+          expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+        expect(String(fetchMock.mock.calls[0]?.[0])).toContain("near.mp3");
+
+        window.__hfRuntimeTeardown?.();
+        fetchMock.mockClear();
+        (
+          window as Window & { __HF_AUDIO_PREDECODE_DISABLED?: boolean }
+        ).__HF_AUDIO_PREDECODE_DISABLED = true;
+        initSandboxRuntimeModular();
+        // A document that exists but is never played (e.g. a double-buffered
+        // preview's standby iframe) must not warm anything.
+        await new Promise((r) => setTimeout(r, 20));
+        expect(fetchMock).not.toHaveBeenCalled();
+      } finally {
+        delete (window as Window & { __HF_AUDIO_PREDECODE_DISABLED?: boolean })
+          .__HF_AUDIO_PREDECODE_DISABLED;
+        vi.unstubAllGlobals();
+      }
+    });
   });
 });
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index d6b268c2c0..0f2ad759d8 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -1920,25 +1920,49 @@ export function initSandboxRuntimeModular(): void {
     }
   };
 
-  // Decode-only warm pass over every timed audio source so WebAudio buffers are
-  // ready BEFORE the first play() instead of being decoded lazily inside it.
-  // The lazy path costs a full-file fetch+decodeAudioData per source at the
-  // moment the user hits play — on a freshly (re)loaded document (every editor
-  // edit reloads the preview iframe) that gap plays through the HTMLMedia
-  // fallback, heard as an audio dropout. Pre-decoding overlaps that work with
-  // document load. `decodeAudioElement` dedupes via its buffer cache and
-  // failure blacklist, so repeated calls per element are cheap map hits.
-  // Skipped during render capture: the producer mixes audio with ffmpeg from
-  // source files and never plays through WebAudio.
+  // Decode-only warm pass over timed audio sources NEAR THE PLAYHEAD so
+  // WebAudio buffers are ready BEFORE the first play() instead of being decoded
+  // lazily inside it. The lazy path costs a full-file fetch+decodeAudioData per
+  // source at the moment the user hits play — on a freshly (re)loaded document
+  // (every editor edit reloads the preview iframe) that gap plays through the
+  // HTMLMedia fallback, heard as an audio dropout. Pre-decoding overlaps that
+  // work with document load.
+  //
+  // BOUNDED, not exhaustive: a source's fetch pulls the WHOLE file into memory
+  // and the decoded PCM is ~23MB per stereo minute — warming EVERY clip of a
+  // long multi-clip composition on EVERY document load multiplies to gigabytes
+  // (an editor with a standby iframe doubles it again). So each pass only warms
+  // clips whose window is near the current time; the periodic re-run (every 30
+  // transport ticks) slides the window as the playhead moves, and play() still
+  // decodes whatever it needs exactly as before. `decodeAudioElement` dedupes
+  // via its buffer cache and failure blacklist, so repeated calls per element
+  // are cheap map hits.
+  //
+  // Skipped during render capture (the producer mixes audio with ffmpeg) and
+  // when the embedder set `__HF_AUDIO_PREDECODE_DISABLED` — the opt-out for
+  // documents that exist but are never played (e.g. a double-buffered editor
+  // preview's hidden standby iframe).
+  const PREDECODE_BEHIND_SECONDS = 10;
+  const PREDECODE_AHEAD_SECONDS = 45;
   const predecodeAudioClipBuffers = () => {
     if (state.tornDown || !webAudioReady) return;
     if (state.nativeMediaSyncDisabled || state.webAudioMediaDisabled) return;
-    if ((window as Window & { __HF_RENDER_CAPTURE_MODE?: boolean }).__HF_RENDER_CAPTURE_MODE) {
-      return;
-    }
+    const w = window as Window & {
+      __HF_RENDER_CAPTURE_MODE?: boolean;
+      __HF_AUDIO_PREDECODE_DISABLED?: boolean;
+    };
+    if (w.__HF_RENDER_CAPTURE_MODE || w.__HF_AUDIO_PREDECODE_DISABLED) return;
+    const now = Math.max(0, state.currentTime || 0);
+    const windowStart = now - PREDECODE_BEHIND_SECONDS;
+    const windowEnd = now + PREDECODE_AHEAD_SECONDS;
     const audioEls = document.querySelectorAll("audio[data-start]");
     for (const el of audioEls) {
       if (!(el instanceof HTMLMediaElement) || !el.isConnected) continue;
+      const start = Number.parseFloat(el.dataset.start ?? "");
+      if (!Number.isFinite(start)) continue;
+      const durAttr = Number.parseFloat(el.dataset.duration ?? "");
+      const end = Number.isFinite(durAttr) && durAttr > 0 ? start + durAttr : Infinity;
+      if (end < windowStart || start > windowEnd) continue;
       void webAudio.decodeAudioElement(el);
     }
   };
@@ -3357,6 +3381,7 @@ export function initSandboxRuntimeModular(): void {
       window.removeEventListener("beforeunload", state.beforeUnloadHandler);
       state.beforeUnloadHandler = null;
     }
+    window.removeEventListener("pagehide", teardown);
     picker.disablePickMode();
     for (const adapter of state.deterministicAdapters) {
       if (!adapter || typeof adapter.revert !== "function") continue;
@@ -3411,4 +3436,12 @@ export function initSandboxRuntimeModular(): void {
   window.__hfRuntimeTeardown = teardown;
   state.beforeUnloadHandler = teardown;
   window.addEventListener("beforeunload", state.beforeUnloadHandler);
+  // `pagehide` too: in an iframe whose document is replaced (an editor writing
+  // a new `srcdoc` on every edit), pagehide is the dependable unload signal.
+  // Without a teardown there, each discarded document keeps a live
+  // AudioContext + decoded-buffer cache until GC gets around to it — under
+  // rapid edits that transiently stacks hundreds of MB of PCM per reload.
+  // teardown() is idempotent (state.tornDown), so double-firing with
+  // beforeunload is harmless.
+  window.addEventListener("pagehide", teardown);
 }

From b38f9020a72285945dcd9b049a1eff8167f0036a Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Thu, 30 Jul 2026 15:08:47 +0100
Subject: [PATCH 4/7] fix(core): coalesce in-flight audio decodes; cap
 decodable source size
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two independent OOM paths in the WebAudio decode pipeline, both hit by a
composition whose audio rides inside large camera-video containers:

- No in-flight dedup: decoding a long source takes seconds, while the warm
  pass / play() / rate changes may re-request the same src many times a
  second. Each re-request launched ANOTHER whole-file fetch — dozens of
  concurrent copies of the same source could stack up before the first
  decode ever reached the buffer cache. decodeAudioElement now coalesces
  concurrent requests per src onto one fetch+decode promise.
- No size bound: WebAudio decode requires the ENTIRE file in an ArrayBuffer.
  Sources beyond 96MB are now permanently skipped for the session
  (content-length short-circuit before any bytes buffer, plus a capped
  stream read when length is undeclared) and keep playing through the
  streamed HTMLMediaElement path instead.
---
 .../src/runtime/webAudioTransport.test.ts     | 67 ++++++++++++++
 .../core/src/runtime/webAudioTransport.ts     | 91 ++++++++++++++++++-
 2 files changed, 156 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/runtime/webAudioTransport.test.ts b/packages/core/src/runtime/webAudioTransport.test.ts
index 96e0da471e..7a6c8bd4ac 100644
--- a/packages/core/src/runtime/webAudioTransport.test.ts
+++ b/packages/core/src/runtime/webAudioTransport.test.ts
@@ -471,6 +471,73 @@ describe("WebAudioTransport", () => {
       vi.unstubAllGlobals();
     });
 
+    it("coalesces concurrent decodes of the same src onto ONE fetch", async () => {
+      const transport = transportWithDecode(async () => ({}) as AudioBuffer);
+      let release: (() => void) | null = null;
+      const gate = new Promise<void>((r) => {
+        release = r;
+      });
+      const fetchMock = vi.fn(async () => {
+        await gate;
+        return { ok: true, arrayBuffer: async () => new ArrayBuffer(8) };
+      });
+      vi.stubGlobal("fetch", fetchMock);
+
+      // The periodic warm pass / play / rate changes can all request the same
+      // src while a long fetch+decode is still in flight — without coalescing,
+      // each launched ANOTHER whole-file fetch (the OOM amplifier).
+      const first = transport.decodeAudioElement(el("long.mp4"));
+      const second = transport.decodeAudioElement(el("long.mp4"));
+      release!();
+      const [a, b] = await Promise.all([first, second]);
+      expect(a).not.toBeNull();
+      expect(b).toBe(a);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      vi.unstubAllGlobals();
+    });
+
+    it("skips oversized sources via content-length and never re-fetches them", async () => {
+      const decode = vi.fn(async () => ({}) as AudioBuffer);
+      const transport = transportWithDecode(decode);
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        headers: { get: () => String(200 * 1024 * 1024) },
+        body: { cancel: async () => undefined },
+        arrayBuffer: async () => new ArrayBuffer(8),
+      }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      expect(await transport.decodeAudioElement(el("huge-camera.mp4"))).toBeNull();
+      expect(decode).not.toHaveBeenCalled();
+      // Permanent per-session skip — the element keeps its streamed fallback.
+      expect(await transport.decodeAudioElement(el("huge-camera.mp4"))).toBeNull();
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      vi.unstubAllGlobals();
+    });
+
+    it("caps an unbounded streamed body instead of buffering it all", async () => {
+      const transport = transportWithDecode(async () => ({}) as AudioBuffer);
+      // Chunks report huge byteLengths without allocating them — the cap logic
+      // only inspects sizes until it aborts.
+      const chunk = { byteLength: 60 * 1024 * 1024 } as Uint8Array;
+      let reads = 0;
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        headers: { get: () => null },
+        body: {
+          getReader: () => ({
+            read: async () => (reads++ < 3 ? { done: false, value: chunk } : { done: true }),
+            cancel: async () => undefined,
+          }),
+        },
+      }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      expect(await transport.decodeAudioElement(el("no-length.mp4"))).toBeNull();
+      expect(reads).toBeLessThanOrEqual(2); // aborted once past the cap
+      vi.unstubAllGlobals();
+    });
+
     it("first fetch per src uses the HTTP cache; only a RETRY bypasses it with no-store", async () => {
       const transport = transportWithDecode(async () => ({}) as AudioBuffer);
       const fetchMock = vi
diff --git a/packages/core/src/runtime/webAudioTransport.ts b/packages/core/src/runtime/webAudioTransport.ts
index 40a2f779fc..57b4ec5456 100644
--- a/packages/core/src/runtime/webAudioTransport.ts
+++ b/packages/core/src/runtime/webAudioTransport.ts
@@ -80,6 +80,41 @@ const EDGE_RAMP_SECONDS = 0.008;
 const STOP_FADE_TIME_CONSTANT = 0.004;
 const STOP_FADE_TAIL_SECONDS = 0.02;
 
+/**
+ * Decoding a source through WebAudio requires fetching the ENTIRE file into an
+ * ArrayBuffer first — for audio that rides inside a large camera/screen-capture
+ * video container, that is hundreds of MB per source and can OOM the tab
+ * before a single decoded sample exists. Sources whose bytes exceed this cap
+ * are permanently skipped for the session (they keep playing through the
+ * streamed HTMLMediaElement path instead of the sample-accurate transport).
+ */
+const MAX_DECODE_SOURCE_BYTES = 96 * 1024 * 1024;
+
+/** Read a response body while enforcing MAX_DECODE_SOURCE_BYTES; null = over cap. */
+async function readBodyCapped(body: ReadableStream<Uint8Array>): Promise<ArrayBuffer | null> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > MAX_DECODE_SOURCE_BYTES) {
+      void reader.cancel().catch(() => undefined);
+      return null;
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out.buffer;
+}
+
 /**
  * Anti-pop gain automation: a hard cut starts/stops mid-waveform, which is an
  * audible click. Ramp gain over EDGE_RAMP_SECONDS at the source's effective
@@ -122,6 +157,13 @@ export class WebAudioTransport {
   private _bufferCache = new Map<string, AudioBuffer>();
   private _failedSrcs = new Set<string>();
   private _fetchAttemptedSrcs = new Set<string>();
+  // In-flight decode per src. Decoding a long source takes SECONDS (full-file
+  // fetch + decodeAudioData) while callers — the periodic warm pass, play(),
+  // rate changes — may re-request the same src many times a second. Without
+  // this map each re-request launched ANOTHER whole-file fetch: dozens of
+  // concurrent copies of the same source stacked up in memory and could OOM
+  // the tab before the first decode ever landed in `_bufferCache`.
+  private _pendingDecodes = new Map<string, Promise<AudioBuffer | null>>();
   private _activeSources: ScheduledSource[] = [];
   private _masterGain: GainNode | null = null;
   // Composition-time reference frame: at AudioContext time `_rateAnchorCtx`,
@@ -160,8 +202,21 @@ export class WebAudioTransport {
     if (this._failedSrcs.has(src)) return null;
     if (!this._ctx) return null;
 
+    // Coalesce concurrent requests for the same src onto one fetch+decode.
+    const pending = this._pendingDecodes.get(src);
+    if (pending) return pending;
+    const task = this._decodeSrc(src);
+    this._pendingDecodes.set(src, task);
+    try {
+      return await task;
+    } finally {
+      this._pendingDecodes.delete(src);
+    }
+  }
+
+  private async _decodeSrc(src: string): Promise<AudioBuffer | null> {
     const arrayBuffer = await this._fetchAudioBytes(src);
-    if (!arrayBuffer) return null;
+    if (!arrayBuffer || !this._ctx) return null;
 
     // A decode failure means the bytes themselves are unusable (corrupt or an
     // unsupported codec) — that IS permanent, so blacklist to avoid re-decoding
@@ -199,13 +254,44 @@ export class WebAudioTransport {
         swallow("webAudioTransport.fetch", new Error(`${response.status} ${src}`));
         return null;
       }
-      return await response.arrayBuffer();
+      return await this._readResponseCapped(response, src);
     } catch (err) {
       swallow("webAudioTransport.fetch", err);
       return null;
     }
   }
 
+  /** Permanent per-session skip for a source too large to decode; the element
+   *  keeps playing through the streamed HTMLMediaElement path. */
+  private _markOversized(src: string, size: string): null {
+    this._failedSrcs.add(src);
+    swallow("webAudioTransport.oversize", new Error(`${size} ${src}`));
+    return null;
+  }
+
+  /**
+   * Enforce MAX_DECODE_SOURCE_BYTES while reading a response. Declared length
+   * short-circuits before any bytes buffer; otherwise the capped stream read
+   * bounds the damage. Optional-chained so environments whose fetch shim lacks
+   * headers/body (tests, exotic embedders) use the plain arrayBuffer path.
+   */
+  private async _readResponseCapped(response: Response, src: string): Promise<ArrayBuffer | null> {
+    const declared = Number(response.headers?.get?.("content-length") ?? "");
+    if (Number.isFinite(declared) && declared > MAX_DECODE_SOURCE_BYTES) {
+      void response.body?.cancel?.().catch(() => undefined);
+      return this._markOversized(src, `${declared}B`);
+    }
+    if (response.body?.getReader) {
+      const capped = await readBodyCapped(response.body);
+      return capped ?? this._markOversized(src, `>${MAX_DECODE_SOURCE_BYTES}B`);
+    }
+    const buf = await response.arrayBuffer();
+    if (buf.byteLength > MAX_DECODE_SOURCE_BYTES) {
+      return this._markOversized(src, `${buf.byteLength}B`);
+    }
+    return buf;
+  }
+
   startGeneration(): number {
     this._playGeneration += 1;
     return this._playGeneration;
@@ -407,6 +493,7 @@ export class WebAudioTransport {
     this.stopAll();
     this._bufferCache.clear();
     this._failedSrcs.clear();
+    this._pendingDecodes.clear();
     if (this._ctx) {
       try {
         void this._ctx.close();

From 21327959308db137c52a9105ef656782d619a5b7 Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Thu, 30 Jul 2026 15:39:27 +0100
Subject: [PATCH 5/7] fix(core): recover silently-evicted media elements; drop
 the video clock-freeze
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Under memory pressure the browser can evict a media element's resource with
no error and no event — readyState collapses to HAVE_NOTHING, videoWidth to
0, and an active clip goes permanently blank. syncRuntimeMedia now detects
that shape on active clips (resource present, not fetching, rate-limited)
and load()s + reseeks it, letting the normal play path re-issue play().

The video-buffering clock freeze from the previous commit is removed: on an
evicted element it never released — a permanent playback hang worse than the
transient lag it smoothed. Video stalls surface via runtime_media_stall
diagnostics and the eviction recovery instead.
---
 packages/core/src/runtime/init.ts       | 34 ++++++-----------------
 packages/core/src/runtime/media.test.ts | 37 +++++++++++++++++++++++++
 packages/core/src/runtime/media.ts      | 33 ++++++++++++++++++++++
 3 files changed, 79 insertions(+), 25 deletions(-)

diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 0f2ad759d8..b48f709aa4 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -3042,31 +3042,15 @@ export function initSandboxRuntimeModular(): void {
               break;
             }
           }
-          if (!foundActive) {
-            // No audio is mastering the clock (video-only composition, or the
-            // audio hasn't reached its window). A buffering ACTIVE video should
-            // freeze time the same way buffering audio does above — otherwise
-            // the monotonic clock runs ahead while frames are stuck, and the
-            // drift correction later hard-seeks (decoder reset) to catch up.
-            const videoEls = document.querySelectorAll("video[data-start]");
-            for (const rawEl of videoEls) {
-              if (!(rawEl instanceof HTMLMediaElement) || !rawEl.isConnected) continue;
-              const start = Number.parseFloat(rawEl.dataset.start ?? "");
-              if (!Number.isFinite(start)) continue;
-              const durAttr = Number.parseFloat(rawEl.dataset.duration ?? "");
-              const end = Number.isFinite(durAttr) && durAttr > 0 ? start + durAttr : Infinity;
-              if (state.currentTime < start || state.currentTime >= end) continue;
-              if (
-                !rawEl.paused &&
-                !rawEl.error &&
-                rawEl.readyState < HTMLMediaElement.HAVE_FUTURE_DATA
-              ) {
-                clock.attachAudioSource({ currentTimeSeconds: state.currentTime });
-                foundActive = true;
-              }
-              break;
-            }
-          }
+          // NOTE: an earlier revision also froze the clock here while an ACTIVE
+          // video was buffering (mirroring the audio-buffering freeze above).
+          // That proved hazardous: when the browser silently EVICTS a media
+          // element's resource under memory pressure (readyState collapses to
+          // HAVE_NOTHING with no error and, without recovery, never rises
+          // again), the frozen clock never released — a permanent playback
+          // hang, worse than the transient video lag it was smoothing. Video
+          // stalls now surface via the runtime_media_stall diagnostics and the
+          // eviction-recovery reload in syncRuntimeMedia instead.
           if (!foundActive && clock.hasAudioSource()) {
             clock.detachAudioSource();
           }
diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
index 3a1b63e3fb..a897fd81c7 100644
--- a/packages/core/src/runtime/media.test.ts
+++ b/packages/core/src/runtime/media.test.ts
@@ -1046,6 +1046,43 @@ describe("syncRuntimeMedia", () => {
     expect(clip.el.muted).toBe(true);
   });
 
+  describe("silent-eviction recovery", () => {
+    function evictedClip(networkState: number): RuntimeMediaClip {
+      const clip = createMockClip({ start: 0, end: 10, mediaStart: 2 });
+      clip.el.load = vi.fn();
+      // Browser-evicted shape: resource present, readyState collapsed to
+      // HAVE_NOTHING, not currently fetching, no error.
+      Object.defineProperty(clip.el, "currentSrc", { value: "blob:clip", configurable: true });
+      Object.defineProperty(clip.el, "readyState", { value: 0, writable: true });
+      Object.defineProperty(clip.el, "networkState", {
+        value: networkState,
+        writable: true,
+        configurable: true,
+      });
+      return clip;
+    }
+
+    it("reloads and reseeks an active element whose resource was evicted", () => {
+      const clip = evictedClip(1 /* NETWORK_IDLE */);
+      syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
+      expect(clip.el.load).toHaveBeenCalledTimes(1);
+      expect(clip.el.currentTime).toBe(7); // (5 - start) * rate + mediaStart
+    });
+
+    it("does not reload an element that is still fetching", () => {
+      const clip = evictedClip(2 /* NETWORK_LOADING */);
+      syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
+      expect(clip.el.load).not.toHaveBeenCalled();
+    });
+
+    it("rate-limits reloads so a broken source cannot reload-loop", () => {
+      const clip = evictedClip(1);
+      syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
+      syncRuntimeMedia({ clips: [clip], timeSeconds: 5.05, playing: true, playbackRate: 1 });
+      expect(clip.el.load).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("upcoming-clip readiness (boundary smoothness)", () => {
     function readyClip(overrides?: Partial<RuntimeMediaClip>): RuntimeMediaClip {
       const clip = createMockClip(overrides);
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
index 117971883f..026347353a 100644
--- a/packages/core/src/runtime/media.ts
+++ b/packages/core/src/runtime/media.ts
@@ -183,6 +183,36 @@ const PREROLL_WINDOW_SECONDS = 0.35;
 const upcomingPreseeked = new WeakSet<HTMLMediaElement>();
 const prerolling = new WeakSet<HTMLMediaElement>();
 
+// ── Silent-eviction recovery ────────────────────────────────────────────────
+// Under memory pressure the browser can EVICT a media element's resource with
+// no error and no event: readyState collapses to HAVE_NOTHING, videoWidth
+// drops to 0, and the element never recovers on its own — an active clip goes
+// (and stays) blank. The only way back is an explicit load() + reseek. Guarded
+// to elements that are NOT currently fetching (a load() would abort an
+// in-flight fetch and restart it from zero — the exact bug the play() path
+// comment below describes) and rate-limited per element so a genuinely broken
+// source doesn't reload-loop.
+const EVICTION_RELOAD_MIN_INTERVAL_MS = 4000;
+const lastEvictionReloadAt = new WeakMap<HTMLMediaElement, number>();
+
+function recoverEvictedElement(el: HTMLMediaElement, relTime: number): void {
+  if (el.readyState !== HTMLMediaElement.HAVE_NOTHING) return;
+  if (!el.currentSrc || isUnplayable(el)) return;
+  const NETWORK_LOADING = 2;
+  if (el.networkState === NETWORK_LOADING) return; // still fetching — not evicted
+  const now = Date.now();
+  if (now - (lastEvictionReloadAt.get(el) ?? 0) < EVICTION_RELOAD_MIN_INTERVAL_MS) return;
+  lastEvictionReloadAt.set(el, now);
+  el.load();
+  try {
+    el.currentTime = relTime;
+  } catch (err) {
+    swallow("runtime.media.evictionReload", err);
+  }
+  // Let the normal play-path re-issue play() for the fresh resource.
+  playRequested.delete(el);
+}
+
 function clampVolume(volume: number): number {
   if (!Number.isFinite(volume)) return 1;
   return Math.max(0, Math.min(1, volume));
@@ -327,6 +357,9 @@ export function syncRuntimeMedia(params: {
       // (no-op when already "auto") and catches elements whose preload
       // was overridden after init.ts set it.
       if (el.preload !== "auto") el.preload = "auto";
+      // Bring a silently-evicted resource back before any drift math runs on
+      // a dead element (see recoverEvictedElement).
+      recoverEvictedElement(el, relTime);
       try {
         // Per-element rate × global transport rate
         el.playbackRate = clip.playbackRate * params.playbackRate;

From 70da7f869e2906c61dc3f0d233d49a783e245a91 Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Sat, 1 Aug 2026 09:24:50 +0100
Subject: [PATCH 6/7] fix(core): latch the upcoming pre-seek only after the
 seek lands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The readiness latch was added before the readyState check, so an element
below HAVE_METADATA was marked pre-seeked without any seek happening. The
browser drops a currentTime assignment with no metadata, and every later
tick short-circuited on set membership — the clip still reached its
boundary at the wrong offset and paid the cold seek this path exists to
remove (exactly the ~150ms decoder-reset freeze).

preseekUpcoming() now closes the latch only when the element is verifiably
parked: metadata present and the assignment succeeded, or already within
tolerance. Below HAVE_METADATA it stays unlatched and retries next tick.

Extracted to a helper so syncRuntimeMedia doesn't grow further.
---
 packages/core/src/runtime/media.test.ts | 32 ++++++++++++++++++++-
 packages/core/src/runtime/media.ts      | 38 ++++++++++++++++---------
 2 files changed, 56 insertions(+), 14 deletions(-)

diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
index a897fd81c7..a832b0dfde 100644
--- a/packages/core/src/runtime/media.test.ts
+++ b/packages/core/src/runtime/media.test.ts
@@ -1084,9 +1084,13 @@ describe("syncRuntimeMedia", () => {
   });
 
   describe("upcoming-clip readiness (boundary smoothness)", () => {
+    function setReadyState(el: HTMLMediaElement, value: number): void {
+      Object.defineProperty(el, "readyState", { value, writable: true, configurable: true });
+    }
+
     function readyClip(overrides?: Partial<RuntimeMediaClip>): RuntimeMediaClip {
       const clip = createMockClip(overrides);
-      Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+      setReadyState(clip.el, 4);
       return clip;
     }
 
@@ -1145,6 +1149,32 @@ describe("syncRuntimeMedia", () => {
       expect(clip.el.play).not.toHaveBeenCalled();
     });
 
+    it("retries the pre-seek on a later tick when the first tick is below HAVE_METADATA", () => {
+      const clip = readyClip({ start: 7, end: 12, mediaStart: 30 });
+      setReadyState(clip.el, 0 /* HAVE_NOTHING */);
+
+      // Too early to seek: the browser drops a currentTime assignment with no
+      // metadata. The element must NOT be latched as pre-seeked here.
+      syncAt(clip, 5);
+      expect(clip.el.currentTime).toBe(0);
+
+      setReadyState(clip.el, 1 /* HAVE_METADATA */);
+      syncAt(clip, 5.1);
+      expect(clip.el.currentTime).toBe(30);
+    });
+
+    it("pre-seeks an upcoming clip only once while it stays parked", () => {
+      const clip = readyClip({ start: 7, end: 12, mediaStart: 30 });
+      syncAt(clip, 5);
+      expect(clip.el.currentTime).toBe(30);
+
+      // A user scrub of the underlying element must not be re-corrected every
+      // tick — the latch closed on the first successful seek.
+      clip.el.currentTime = 12;
+      syncAt(clip, 5.1);
+      expect(clip.el.currentTime).toBe(12);
+    });
+
     it("paused transport leaves upcoming clips untouched", () => {
       const clip = readyClip({ start: 6, end: 12, mediaStart: 30 });
       syncAt(clip, 5, { playing: false });
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
index 026347353a..6f44ade6de 100644
--- a/packages/core/src/runtime/media.ts
+++ b/packages/core/src/runtime/media.ts
@@ -183,6 +183,30 @@ const PREROLL_WINDOW_SECONDS = 0.35;
 const upcomingPreseeked = new WeakSet<HTMLMediaElement>();
 const prerolling = new WeakSet<HTMLMediaElement>();
 
+// Park an upcoming element at its media offset so the browser buffers the right
+// region of the source. Latched per element to keep repeated readiness ticks
+// from re-issuing the same seek — but the latch closes ONLY once the element is
+// verifiably parked. Below HAVE_METADATA a `currentTime` assignment is dropped
+// by the browser (and can throw), so latching there would burn the element's one
+// chance: every later tick would short-circuit on set membership and the clip
+// would still reach its boundary at the wrong offset, paying the cold seek this
+// whole path exists to avoid. Instead we leave it unlatched and retry on the
+// next tick, once metadata has arrived.
+function preseekUpcoming(el: HTMLMediaElement, mediaStart: number): void {
+  if (upcomingPreseeked.has(el)) return;
+  if (el.readyState < HTMLMediaElement.HAVE_METADATA) return;
+  if (Math.abs(el.currentTime - mediaStart) <= 0.25) {
+    upcomingPreseeked.add(el); // already parked — nothing to seek
+    return;
+  }
+  try {
+    el.currentTime = mediaStart;
+    upcomingPreseeked.add(el);
+  } catch (err) {
+    swallow("runtime.media.preseek", err);
+  }
+}
+
 // ── Silent-eviction recovery ────────────────────────────────────────────────
 // Under memory pressure the browser can EVICT a media element's resource with
 // no error and no event: readyState collapses to HAVE_NOTHING, videoWidth
@@ -541,19 +565,7 @@ export function syncRuntimeMedia(params: {
         continue; // never pause a pre-rolling element
       }
       prerolling.delete(el);
-      if (!upcomingPreseeked.has(el)) {
-        upcomingPreseeked.add(el);
-        if (
-          el.readyState >= HTMLMediaElement.HAVE_METADATA &&
-          Math.abs(el.currentTime - clip.mediaStart) > 0.25
-        ) {
-          try {
-            el.currentTime = clip.mediaStart;
-          } catch (err) {
-            swallow("runtime.media.preseek", err);
-          }
-        }
-      }
+      preseekUpcoming(el, clip.mediaStart);
       if (!el.paused) el.pause();
       continue;
     }

From c0a2f89ba1f77c976e24710df4d33b6303c1db53 Mon Sep 17 00:00:00 2001
From: I-bangash <irtezabangash3d@gmail.com>
Date: Sat, 1 Aug 2026 09:24:57 +0100
Subject: [PATCH 7/7] fix(core): don't tear the runtime down on a bfcache
 pagehide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pagehide` also fires with persisted === true when the document is frozen
into the back-forward cache. That is not a death: `pageshow` restores the
same document without re-running initialization. Tearing down there
latched state.tornDown, stripped the listeners and injected styles, and
closed the AudioContext — leaving a restored player permanently inert with
nothing to bring it back.

The destructive path is now gated to non-persisted page hides — the
srcdoc-replacement case the listener was added for. A BFCached document is
frozen by the browser, which suspends its AudioContext and media anyway,
so skipping teardown while it sits there costs nothing, and the listener
stays armed for the eventual real hide.
---
 packages/core/src/runtime/init.test.ts | 46 ++++++++++++++++++++++++++
 packages/core/src/runtime/init.ts      | 22 +++++++++---
 2 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts
index 57026dee82..c081d420fc 100644
--- a/packages/core/src/runtime/init.test.ts
+++ b/packages/core/src/runtime/init.test.ts
@@ -652,6 +652,52 @@ describe("initSandboxRuntimeModular", () => {
     expect(injectedLink?.isConnected).toBe(false);
   });
 
+  describe("pagehide teardown", () => {
+    async function initMinimalRuntime(): Promise<void> {
+      const root = document.createElement("div");
+      root.setAttribute("data-composition-id", "main");
+      root.setAttribute("data-root", "true");
+      root.setAttribute("data-start", "0");
+      root.setAttribute("data-width", "1920");
+      root.setAttribute("data-height", "1080");
+      document.body.appendChild(root);
+      window.__timelines = { main: createMockTimeline(3) };
+      initSandboxRuntimeModular();
+      await new Promise<void>((resolve) => window.setTimeout(resolve, 0));
+    }
+
+    function firePageHide(persisted: boolean): void {
+      const event = new Event("pagehide");
+      Object.defineProperty(event, "persisted", { value: persisted });
+      window.dispatchEvent(event);
+    }
+
+    it("tears down on a real page hide", async () => {
+      await initMinimalRuntime();
+      expect(window.__hfRuntimeTeardown).toBeTypeOf("function");
+
+      firePageHide(false);
+
+      expect(window.__hfRuntimeTeardown).toBeNull();
+    });
+
+    it("survives a bfcache page hide so a pageshow restore stays playable", async () => {
+      await initMinimalRuntime();
+
+      // persisted === true means the document is frozen into the back-forward
+      // cache, not destroyed — `pageshow` restores it WITHOUT re-running init,
+      // so a teardown here would leave the player permanently inert.
+      firePageHide(true);
+
+      expect(window.__hfRuntimeTeardown).toBeTypeOf("function");
+
+      // ...and the listener is still armed, so the eventual real hide still
+      // reclaims the AudioContext and decoded buffers.
+      firePageHide(false);
+      expect(window.__hfRuntimeTeardown).toBeNull();
+    });
+  });
+
   it("keeps compiled external composition hosts visible through their authored duration", async () => {
     const root = document.createElement("div");
     root.setAttribute("data-composition-id", "main");
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index b48f709aa4..f29ae6754e 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -3365,7 +3365,7 @@ export function initSandboxRuntimeModular(): void {
       window.removeEventListener("beforeunload", state.beforeUnloadHandler);
       state.beforeUnloadHandler = null;
     }
-    window.removeEventListener("pagehide", teardown);
+    window.removeEventListener("pagehide", handlePageHide);
     picker.disablePickMode();
     for (const adapter of state.deterministicAdapters) {
       if (!adapter || typeof adapter.revert !== "function") continue;
@@ -3417,9 +3417,6 @@ export function initSandboxRuntimeModular(): void {
       window.__hfRuntimeTeardown = null;
     }
   };
-  window.__hfRuntimeTeardown = teardown;
-  state.beforeUnloadHandler = teardown;
-  window.addEventListener("beforeunload", state.beforeUnloadHandler);
   // `pagehide` too: in an iframe whose document is replaced (an editor writing
   // a new `srcdoc` on every edit), pagehide is the dependable unload signal.
   // Without a teardown there, each discarded document keeps a live
@@ -3427,5 +3424,20 @@ export function initSandboxRuntimeModular(): void {
   // rapid edits that transiently stacks hundreds of MB of PCM per reload.
   // teardown() is idempotent (state.tornDown), so double-firing with
   // beforeunload is harmless.
-  window.addEventListener("pagehide", teardown);
+  //
+  // But `pagehide` ALSO fires with `persisted: true` when the document enters
+  // the back-forward cache, and that is not a death — the very same document is
+  // restored by `pageshow` with no re-initialization. Tearing down there would
+  // leave the restored player permanently inert (tornDown latched, listeners and
+  // injected styles gone, AudioContext closed) with nothing to bring it back. A
+  // BFCached document is frozen by the browser, which suspends its AudioContext
+  // and media for us, so skipping teardown costs nothing while it sits there.
+  const handlePageHide = (event: PageTransitionEvent) => {
+    if (event.persisted) return;
+    teardown();
+  };
+  window.__hfRuntimeTeardown = teardown;
+  state.beforeUnloadHandler = teardown;
+  window.addEventListener("beforeunload", state.beforeUnloadHandler);
+  window.addEventListener("pagehide", handlePageHide);
 }