perf(core): bound audio pre-decode to the playhead window; tear down on pagehide

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.

Author: I-bangash

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();
+      }
+    });
   });
 });

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);
 }