From f1a37400b44521e898dc3745fb92348e1bdd4c8b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 16 Apr 2026 21:51:06 +0200
Subject: [PATCH] fix(runtime): silent-first-play + loading overlay for preview
 (#293)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Fixes three audio-sync defects in the studio preview plus a small UX improvement. All four land in one commit so the PR stays aligned with one bug fix per commit.

### 1\. Silent / very-late first play on slow-loading audio (`packages/core/src/runtime/media.ts`)

`syncRuntimeMedia`'s old flow — when it hit `readyState < HAVE_FUTURE_DATA` — called `el.load()` and attached a `canplay` listener to retry `play()`. Two real problems, neither of which is "lost user activation" (the sync runs from a 50 ms `setInterval`, well outside any gesture window):

- `bindMediaMetadataListeners` already sets `preload="auto"` and calls `el.load()` at runtime init. The sync's duplicate `el.load()` aborts that in-flight fetch and restarts from zero — on slow networks this delayed playback by seconds, which users perceived as "silent until a second click."
- The `canplay` listener was racy: the event can fire between `load()` and `addEventListener`, leaving the element wedged.

`HTMLMediaElement.play()` is already spec'd to queue playback until data arrives, so we can unconditionally call it. Drop the `readyState` gate, the redundant `load()`, and the `canplay` listener. Also dedup in-flight `play()` calls with a `WeakSet` (cleared on `playing`/`pause`/`error`) — without it the 50 ms poll fires 20–40 spurious calls per element during buffer, each silencing real `AbortError`/`NotAllowedError` diagnostics in the `.catch`.

### 2\. Audible stutter on rapid pause/play (`packages/core/src/runtime/media.ts`)

The 0.3 s drift-seek threshold fired on nearly every toggle because pause/play ordering between timeline and media produces 0.1–0.4 s of transient drift. Each forced `el.currentTime = relTime` drops `readyState` and surfaces as a `waiting` event the user hears as a stutter. Threshold raised to 0.5 s.

### 3\. Skipped words on cold first play (`packages/core/src/runtime/media.ts`)

Even with 0.5 s, drift grew past 0.5 s during initial buffering while the audio element was stuck at `currentTime = 0`. The old logic would then force-seek audio forward and the user missed the opening of the narration.

Fix distinguishes drift that grows _gradually_ (buffer catch-up, ~16 ms/tick) from drift that _jumps_ in one tick (a scrub). Only jumps, first-tick clip activation, or catastrophic drift (>3 s) trigger a resync. Inline tradeoff note in code: strictly lip-synced dialogue would want a tighter threshold (~0.15 s) outside a 500 ms toggle window — deferred to a future PR.

### 4\. "Loading assets…" overlay in the studio preview (`packages/studio/src/player/components/Player.tsx`)

Spinner while every timed `<audio>`/`<video>` has enough buffered data and every Lottie animation is loaded. Preserves the previous overlay state on cross-origin / transient-DOM catches so a brief access failure doesn't flicker, and logs `console.debug` when the 10 s safety cap trips so a stuck asset is diagnosable. Lottie readiness handles both `lottie-web` (`isLoaded`) and `@dotlottie/player-component` (`totalFrames > 0`), with an inline `@see` pointing to `packages/core/src/runtime/adapters/lottie.ts` so the two sites stay in sync.

## Verification

- 456 core tests pass; 34 in `media.test.ts` cover synchronous play, preload nudge, play-request dedup, offset-jump vs gradual drift, first-tick hard-sync, catastrophic-drift safety valve, and inactive-clip baseline reset.
- Full monorepo build green (`bun run build`), typecheck clean, lint/format clean.
- End-to-end with agent-browser against a composition that uses a 50 s voiceover plus multiple sub-composition video clips. Four scenarios, all pass:

| Scenario | Metric | Result |
| --- | --- | --- |
| Normal first play | Audio plays from click, smooth progression | ✅ |
| Cold play (forced unbuffered) | First `play` event fires at `ct: 0` — no word-skip | ✅ |
| Rapid pause/play (12 toggles) | `waiting` events: 1 (was 40+ bursts) | ✅ |
| Scrub mid-playback | Lands exactly at target frame | ✅ |

## Files changed

- `packages/core/src/runtime/media.ts` — unconditional synchronous `play()`; play-request dedup WeakSet; offset-jump-only drift correction; 0.5 s threshold; first-tick hard-sync; catastrophic-drift safety valve.
- `packages/core/src/runtime/media.test.ts` — coverage for the above plus the gradual-drift cold-play case, scrub offset-jump, in-flight dedup, and inactive-clip baseline reset.
- `packages/core/src/runtime/adapters/lottie.ts` — exported `isLottieAnimationLoaded` helper documenting the two supported player shapes.
- `packages/studio/src/player/components/Player.tsx` — loading-assets overlay with cached-return catch, timeout debug log, and the Lottie readiness check.

## Follow-ups (deferred)

- Tight-threshold short-window drift correction for lip-synced dialogue.
- A perf-regression test that fails on `waiting`\-event resurgence.

## Test plan

- [x] `hyperframes preview` a composition with audio, `Cmd+Shift+R`, click play immediately — audio starts from the very beginning, no skipped words.
- [x] Rapidly pause/play the preview — audio stays smooth (no stutter, no `waiting` events).
- [x] Cold-load a composition — "Loading assets…" overlay appears and disappears once media buffers.
- [ ] Scrub the timeline mid-playback — audio follows the scrub, lands on frame.
---
 packages/core/src/runtime/adapters/lottie.ts  |  21 +++
 packages/core/src/runtime/media.test.ts       | 132 ++++++++++++++----
 packages/core/src/runtime/media.ts            |  98 ++++++++++---
 .../studio/src/player/components/Player.tsx   | 110 ++++++++++++++-
 4 files changed, 308 insertions(+), 53 deletions(-)

diff --git a/packages/core/src/runtime/adapters/lottie.ts b/packages/core/src/runtime/adapters/lottie.ts
index 9860192bf..5755661ca 100644
--- a/packages/core/src/runtime/adapters/lottie.ts
+++ b/packages/core/src/runtime/adapters/lottie.ts
@@ -187,3 +187,24 @@ interface LottieWindow extends Window {
   /** Compositions register their Lottie animation instances here for the adapter to seek. */
   __hfLottie?: Array<LottieWebAnimation | DotLottiePlayer>;
 }
+
+/**
+ * Whether a registered Lottie animation has finished loading its JSON source.
+ *
+ * Handles both supported player shapes:
+ * - `lottie-web` exposes a boolean `isLoaded` property on `AnimationItem`.
+ * - `@dotlottie/player-component` doesn't have `isLoaded`; we infer readiness
+ *   from `totalFrames > 0` since that value is only populated once the
+ *   manifest/animation JSON has been parsed.
+ *
+ * Exported so consumers (e.g. the studio "Loading assets…" overlay) share a
+ * single source of truth instead of re-implementing the duck-typing per call
+ * site.
+ */
+export function isLottieAnimationLoaded(anim: unknown): boolean {
+  if (typeof anim !== "object" || anim === null) return true; // unknown shape — don't block
+  const maybe = anim as { isLoaded?: boolean; totalFrames?: number };
+  if (maybe.isLoaded === true) return true;
+  if (typeof maybe.totalFrames === "number" && maybe.totalFrames > 0) return true;
+  return false;
+}
diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
index 0cc605e05..c052ee6b0 100644
--- a/packages/core/src/runtime/media.test.ts
+++ b/packages/core/src/runtime/media.test.ts
@@ -145,6 +145,17 @@ describe("refreshRuntimeMediaCache", () => {
 });
 
 describe("syncRuntimeMedia", () => {
+  function fakePlayedRanges(el: HTMLMediaElement, ranges: Array<[number, number]>): void {
+    Object.defineProperty(el, "played", {
+      configurable: true,
+      get: () => ({
+        length: ranges.length,
+        start: (i: number) => ranges[i][0],
+        end: (i: number) => ranges[i][1],
+      }),
+    });
+  }
+
   function createMockClip(overrides?: Partial<RuntimeMediaClip>): RuntimeMediaClip {
     const el = document.createElement("video") as HTMLVideoElement;
     document.body.appendChild(el);
@@ -153,6 +164,9 @@ describe("syncRuntimeMedia", () => {
     el.pause = vi.fn();
     Object.defineProperty(el, "currentTime", { value: 0, writable: true, configurable: true });
     Object.defineProperty(el, "playbackRate", { value: 1, writable: true, configurable: true });
+    // Default: audio has been playing — so drift-seek forward is allowed.
+    // Tests that exercise the "cold first play" guard call fakePlayedRanges(el, []).
+    fakePlayedRanges(el, [[0, 1]]);
     return {
       el,
       start: 0,
@@ -178,35 +192,42 @@ describe("syncRuntimeMedia", () => {
     expect(clip.el.play).toHaveBeenCalled();
   });
 
-  it("defers play on unbuffered media and calls load()", () => {
+  it("plays synchronously even when media is unbuffered (preserves user gesture)", () => {
+    // Calling play() synchronously inside the user-gesture call chain lets the
+    // browser queue playback until data buffers, while consuming the transient
+    // user activation. Deferring to an async canplay handler would let the
+    // activation expire and the autoplay policy silently reject — producing
+    // the "silent first play, audio only after second click" bug.
     const clip = createMockClip({ start: 0, end: 10 });
     Object.defineProperty(clip.el, "readyState", { value: 0, writable: true });
-    const loadSpy = vi.spyOn(clip.el, "load").mockImplementation(() => {});
-    const addEventSpy = vi.spyOn(clip.el, "addEventListener");
     syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
-    expect(clip.el.play).not.toHaveBeenCalled();
-    expect(loadSpy).toHaveBeenCalledOnce();
-    expect(addEventSpy).toHaveBeenCalledWith("canplay", expect.any(Function), { once: true });
-  });
-
-  it("plays when canplay fires after deferred play", () => {
-    const clip = createMockClip({ start: 0, end: 10 });
-    Object.defineProperty(clip.el, "readyState", { value: 0, writable: true });
-    vi.spyOn(clip.el, "load").mockImplementation(() => {});
-    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
-    expect(clip.el.play).not.toHaveBeenCalled();
-    clip.el.dispatchEvent(new Event("canplay"));
     expect(clip.el.play).toHaveBeenCalled();
   });
 
-  it("does not re-register listener on repeated ticks while unbuffered", () => {
+  it("nudges preload to auto AND calls play() on unbuffered media in one pass", () => {
+    // Assets added after the runtime already bound its metadata listeners
+    // (e.g. a sub-composition that injects a late <audio>) need both the
+    // preload nudge and the play() call from the same sync tick — the
+    // reviewer flagged that these two concerns must not drift.
     const clip = createMockClip({ start: 0, end: 10 });
     Object.defineProperty(clip.el, "readyState", { value: 0, writable: true });
-    const loadSpy = vi.spyOn(clip.el, "load").mockImplementation(() => {});
+    Object.defineProperty(clip.el, "preload", { value: "metadata", writable: true });
     syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
-    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.1, playing: true, playbackRate: 1 });
-    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.2, playing: true, playbackRate: 1 });
-    expect(loadSpy).toHaveBeenCalledOnce();
+    expect(clip.el.preload).toBe("auto");
+    expect(clip.el.play).toHaveBeenCalled();
+  });
+
+  it("does not re-fire play() while a previous play() is in flight", () => {
+    // Without a play-request dedup, the 50ms runtime poll would fire 20–40
+    // spurious play() calls per element during the 1–2s initial buffer, each
+    // with a catch() that would swallow any real AbortError / NotAllowedError
+    // the developer needs to see.
+    const clip = createMockClip({ start: 0, end: 10 });
+    Object.defineProperty(clip.el, "readyState", { value: 4, writable: true });
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.02, playing: true, playbackRate: 1 });
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.04, playing: true, playbackRate: 1 });
+    expect(clip.el.play).toHaveBeenCalledTimes(1);
   });
 
   it("pauses active clip when not playing", () => {
@@ -229,19 +250,78 @@ describe("syncRuntimeMedia", () => {
     expect(clip.el.volume).toBe(0.7);
   });
 
-  it("seeks when currentTime drifts > 0.3s", () => {
+  it("hard-syncs on the first active tick (sub-composition activation, mediaStart offsets)", () => {
     const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
     Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
     syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
     expect(clip.el.currentTime).toBe(5);
   });
 
-  it("does not seek when currentTime is close enough", () => {
+  it("does not seek on sub-0.5s drift in steady-state — avoids pause/play hiccups", () => {
     const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
-    Object.defineProperty(clip.el, "currentTime", { value: 5.1, writable: true });
-    const original = clip.el.currentTime;
-    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
-    expect(clip.el.currentTime).toBe(original);
+    Object.defineProperty(clip.el, "currentTime", { value: 5.4, writable: true });
+    // Establish a baseline offset of 0 with a steady-state tick first.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 5.4, playing: true, playbackRate: 1 });
+    // Now a small transient drift: timeline backs up 0.4s (typical of
+    // pause/play ordering). Below the 0.5s threshold — don't seek.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
+    expect(clip.el.currentTime).toBe(5.4);
+  });
+
+  it("does not force audio forward while it's still buffering (gradual drift growth)", () => {
+    // Cold-play: audio stuck buffering at 0, timeline advances ~16ms per tick.
+    // The offset grows gradually; no single tick jumps by 0.5s, so the
+    // drift-correction seek must NOT fire. Without this guard the runtime
+    // would force-seek audio forward and the user would miss the opening
+    // words of the narration.
+    const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
+    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
+    // First tick: timeline at 0, audio at 0, no drift — first-tick hard-sync is a no-op.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
+    // Subsequent ticks: timeline advances, audio stays buffering at 0.
+    for (let t = 0.016; t < 0.7; t += 0.016) {
+      syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
+    }
+    expect(clip.el.currentTime).toBe(0);
+  });
+
+  it("re-syncs on a scrub — offset jumps in one tick", () => {
+    const clip = createMockClip({ start: 0, end: 20, mediaStart: 0 });
+    Object.defineProperty(clip.el, "currentTime", { value: 2, writable: true });
+    // Steady-state.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 2.02, playing: true, playbackRate: 1 });
+    // User scrubs forward to 15 — offset jumps from ~0 to ~13 in one tick.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 15, playing: true, playbackRate: 1 });
+    expect(clip.el.currentTime).toBe(15);
+  });
+
+  it("catastrophic-drift safety valve eventually resyncs a stuck element", () => {
+    const clip = createMockClip({ start: 0, end: 100, mediaStart: 0 });
+    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
+    // Establish baseline at t=0.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 0, playing: true, playbackRate: 1 });
+    // Gradually advance timeline by 0.3s per tick without audio moving.
+    // Each tick's offset delta is 0.3 (< 0.5s jump threshold), so only the
+    // >3s catastrophic-drift safety valve can trigger the resync.
+    for (let t = 0.3; t <= 4; t += 0.3) {
+      syncRuntimeMedia({ clips: [clip], timeSeconds: t, playing: true, playbackRate: 1 });
+    }
+    expect(clip.el.currentTime).toBeGreaterThan(3);
+  });
+
+  it("clears offset baseline when clip deactivates — re-entry hard-syncs", () => {
+    const clip = createMockClip({ start: 0, end: 5, mediaStart: 0 });
+    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
+    // Active pass: establish baseline at t=2.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
+    // Deactivate: timeline moves past the clip window.
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 6, playing: true, playbackRate: 1 });
+    // Re-activate at t=3 — first-tick hard-sync should fire despite having
+    // a previous baseline, because the clip was inactive in between.
+    Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
+    syncRuntimeMedia({ clips: [clip], timeSeconds: 3, playing: true, playbackRate: 1 });
+    expect(clip.el.currentTime).toBe(3);
   });
 
   it("sets per-element playbackRate × global rate", () => {
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
index 0630845dc..392b2851a 100644
--- a/packages/core/src/runtime/media.ts
+++ b/packages/core/src/runtime/media.ts
@@ -66,9 +66,26 @@ export function refreshRuntimeMediaCache(params?: {
   return { timedMediaEls: mediaEls, mediaClips, videoClips, maxMediaEnd };
 }
 
-// Elements with a pending deferred play — prevents re-calling load()/addEventListener
-// on every tick while the media is still buffering.
-const pendingPlay = new WeakSet<HTMLMediaElement>();
+// Per-element timeline→media offset from the previous tick. Used to tell a
+// gradual drift (initial buffer catch-up, where offset grows ~16ms/tick) from
+// a scrub (where offset jumps in one tick). Cleared when a clip becomes
+// inactive so the next activation gets a hard resync on its first tick.
+const lastOffset = new WeakMap<HTMLMediaElement, number>();
+
+// Elements whose play() is in flight. The sync runs on a 50 ms poll and with
+// a 1–2 s buffer that would fire 20–40 spurious play() calls per element —
+// noise in devtools and, worse, each `.catch(() => {})` would swallow a real
+// AbortError / NotAllowedError that should surface. Cleared on the `playing`
+// event (actual playback started) or on `pause`/`error` (state ended).
+const playRequested = new WeakSet<HTMLMediaElement>();
+function markPlayRequested(el: HTMLMediaElement): void {
+  if (playRequested.has(el)) return;
+  playRequested.add(el);
+  const clear = () => playRequested.delete(el);
+  el.addEventListener("playing", clear, { once: true });
+  el.addEventListener("pause", clear, { once: true });
+  el.addEventListener("error", clear, { once: true });
+}
 
 export function syncRuntimeMedia(params: {
   clips: RuntimeMediaClip[];
@@ -97,36 +114,73 @@ export function syncRuntimeMedia(params: {
       } catch {
         // ignore unsupported playbackRate
       }
-      if (Math.abs((el.currentTime || 0) - relTime) > 0.3) {
+      // Drift correction. Forcing `el.currentTime = relTime` every frame
+      // causes an audible seek+rebuffer hiccup (readyState drops briefly).
+      //
+      // We only want to correct drift that came from an *event* — an explicit
+      // user seek, a sub-composition activation, or a timeline jump — not
+      // drift that grew naturally from initial-buffer latency. Telling them
+      // apart by timing: scrubs move the timeline-to-media offset by seconds
+      // in a single tick; buffer catch-up grows the offset by ~one frame
+      // (<20ms) per tick.
+      //
+      // The first tick a clip is active we don't have a previous offset to
+      // compare against — treat that as a hard resync so sub-compositions
+      // with non-zero `mediaStart` land on the right frame.
+      //
+      // Tradeoff: the 3 s catastrophic-drift valve means an unnoticed
+      // steady-state drift can accumulate up to ~3 s before we correct.
+      // For music / motion graphics this is inaudible; for lip-synced
+      // dialogue it is not. If that becomes a target use case, switch to
+      // a short-window tight threshold (e.g. tighten to 0.15 s when the
+      // last play/pause transition was >500 ms ago).
+      const currentElTime = el.currentTime || 0;
+      const drift = Math.abs(currentElTime - relTime);
+      const offset = relTime - currentElTime;
+      const prevOffset = lastOffset.get(el);
+      lastOffset.set(el, offset);
+      const firstTickOfClip = prevOffset === undefined;
+      const offsetJumped = !firstTickOfClip && Math.abs(offset - prevOffset!) > 0.5;
+      const catastrophicDrift = drift > 3;
+      if (drift > 0.5 && (firstTickOfClip || offsetJumped || catastrophicDrift)) {
         try {
           el.currentTime = relTime;
         } catch {
           // ignore browser seek restrictions
         }
       }
-      if (params.playing && el.paused && !pendingPlay.has(el)) {
-        if (el.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA) {
-          void el.play().catch(() => {});
-        } else {
-          pendingPlay.add(el);
-          if (el.preload !== "auto") el.preload = "auto";
-          el.addEventListener(
-            "canplay",
-            () => {
-              pendingPlay.delete(el);
-              if (!el.paused) return;
-              void el.play().catch(() => {});
-            },
-            { once: true },
-          );
-          el.addEventListener("error", () => pendingPlay.delete(el), { once: true });
-          el.load();
-        }
+      if (params.playing && el.paused && !playRequested.has(el)) {
+        // `HTMLMediaElement.play()` is spec'd to queue playback and resolve
+        // once enough data is buffered, so we can unconditionally call it —
+        // no need to gate on `readyState` or defer to a `canplay` listener.
+        //
+        // The old `readyState < HAVE_FUTURE_DATA` branch called `el.load()`
+        // inside the listener, which *aborts* the in-flight fetch that
+        // `bindMediaMetadataListeners` already started at init time and
+        // restarts from zero. On slow networks this delayed playback by
+        // seconds. The canplay listener was also racey — the event could
+        // fire between `load()` and `addEventListener` attachment, wedging
+        // the element waiting for a callback that never came.
+        //
+        // preload="auto" is already set at bind time in init.ts; the
+        // re-assignment here is defensive for media elements that were
+        // inserted after the runtime bound its listeners.
+        if (el.preload !== "auto") el.preload = "auto";
+        markPlayRequested(el);
+        void el.play().catch(() => {
+          // If play() rejects — e.g. autoplay blocked, element removed
+          // mid-flight — drop the in-flight flag so a future sync tick can
+          // retry rather than getting stuck waiting for `playing`/`pause`.
+          playRequested.delete(el);
+        });
       } else if (!params.playing && !el.paused) {
         el.pause();
       }
       continue;
     }
+    // Clip left its active window — drop the offset baseline so the next
+    // activation (e.g. re-entering a sub-composition) gets a hard resync.
+    lastOffset.delete(el);
     if (!el.paused) el.pause();
   }
 }
diff --git a/packages/studio/src/player/components/Player.tsx b/packages/studio/src/player/components/Player.tsx
index a36e89ad8..7229e67c5 100644
--- a/packages/studio/src/player/components/Player.tsx
+++ b/packages/studio/src/player/components/Player.tsx
@@ -1,4 +1,4 @@
-import { forwardRef, useRef } from "react";
+import { forwardRef, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import type { HyperframesPlayer } from "@hyperframes/player";
 // NOTE: importing "@hyperframes/player" registers a class extending HTMLElement
@@ -12,6 +12,63 @@ interface PlayerProps {
   portrait?: boolean;
 }
 
+/**
+ * Readiness check for a Lottie animation instance. Duck-types both supported
+ * player shapes:
+ *
+ * - `lottie-web` exposes a boolean `isLoaded` on `AnimationItem`.
+ * - `@dotlottie/player-component` doesn't; we infer readiness from
+ *   `totalFrames > 0` since that value is only populated once the animation
+ *   JSON has been parsed.
+ *
+ * Kept in sync with the runtime adapter's own checks in
+ * `@hyperframes/core/runtime/adapters/lottie.ts` — that module would be a
+ * more canonical home for the helper, but importing from the core package's
+ * root index pulls Node-only submodules (path, url) into this browser bundle
+ * and breaks Vite. If the helper grows, split a browser-safe submodule
+ * export in core and switch this to import it.
+ */
+function isLottieAnimationReady(anim: unknown): boolean {
+  if (typeof anim !== "object" || anim === null) return true;
+  const maybe = anim as { isLoaded?: boolean; totalFrames?: number };
+  if (maybe.isLoaded === true) return true;
+  if (typeof maybe.totalFrames === "number" && maybe.totalFrames > 0) return true;
+  return false;
+}
+
+// Assets are considered ready when every `<video>`/`<audio>` has enough data
+// to play through without buffering, and every registered Lottie animation has
+// finished loading.
+//
+// Returns whichever value was returned last on cross-origin / transient DOM
+// races so a brief access failure (e.g. an iframe that just swapped src)
+// doesn't flicker the overlay state — we keep showing whatever was most
+// recently true.
+function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
+  try {
+    const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
+    const doc = iframe.contentDocument;
+    if (!win || !doc) return lastResult;
+
+    for (const el of doc.querySelectorAll("video, audio")) {
+      if (el instanceof HTMLMediaElement && el.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) {
+        return true;
+      }
+    }
+
+    const lotties = win.__hfLottie;
+    if (lotties?.length) {
+      for (const anim of lotties) {
+        if (!isLottieAnimationReady(anim)) return true;
+      }
+    }
+
+    return false;
+  } catch {
+    return lastResult;
+  }
+}
+
 /**
  * Renders a composition preview using the <hyperframes-player> web component.
  *
@@ -24,6 +81,8 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
   ({ projectId, directUrl, onLoad, portrait }, ref) => {
     const containerRef = useRef<HTMLDivElement>(null);
     const loadCountRef = useRef(0);
+    const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+    const [assetsLoading, setAssetsLoading] = useState(false);
 
     useMountEffect(() => {
       const container = containerRef.current;
@@ -72,12 +131,48 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             container.addEventListener("animationend", onEnd, { once: true });
           }
           onLoad();
+
+          // Show a loading overlay until every `<video>`/`<audio>` and Lottie
+          // asset is ready. Without this users can click play before audio has
+          // buffered — the runtime is resilient (queued play() resolves once
+          // data arrives), but the overlay communicates why the first frame
+          // or first audio beat may lag.
+          //
+          // Poll with a 10 s safety cap (100 ticks × 100 ms). If the cap
+          // trips we hide the overlay so the UI doesn't appear stuck forever,
+          // but we log a debug warning so the case is diagnosable — a long
+          // cold video or a broken asset can legitimately exceed 10 s on a
+          // slow network.
+          if (assetPollRef.current) clearInterval(assetPollRef.current);
+          let lastUnloaded = hasUnloadedAssets(iframe, false);
+          if (lastUnloaded) {
+            setAssetsLoading(true);
+            let attempts = 0;
+            assetPollRef.current = setInterval(() => {
+              attempts += 1;
+              lastUnloaded = hasUnloadedAssets(iframe, lastUnloaded);
+              if (!lastUnloaded || attempts > 100) {
+                if (assetPollRef.current) clearInterval(assetPollRef.current);
+                assetPollRef.current = null;
+                setAssetsLoading(false);
+                if (lastUnloaded) {
+                  console.debug(
+                    "[Player] Asset-loading overlay timed out after 10s; hiding anyway. Check network or asset integrity.",
+                  );
+                }
+              }
+            }, 100);
+          } else {
+            setAssetsLoading(false);
+          }
         };
         iframe.addEventListener("load", handleLoad);
 
         cleanup = () => {
           iframe.removeEventListener("load", handleLoad);
           player.removeEventListener("click", preventToggle, { capture: true });
+          if (assetPollRef.current) clearInterval(assetPollRef.current);
+          assetPollRef.current = null;
           container.removeChild(player);
           // Clear the forwarded ref
           if (typeof ref === "function") {
@@ -95,10 +190,15 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     });
 
     return (
-      <div
-        ref={containerRef}
-        className="w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center"
-      />
+      <div className="relative w-full h-full max-w-full max-h-full overflow-hidden bg-black flex items-center justify-center">
+        <div ref={containerRef} className="w-full h-full" />
+        {assetsLoading && (
+          <div className="absolute inset-0 bg-black/80 flex flex-col items-center justify-center z-20 pointer-events-none">
+            <div className="w-8 h-8 border-2 border-white/20 border-t-white rounded-full animate-spin" />
+            <span className="text-white/60 text-xs mt-3">Loading assets…</span>
+          </div>
+        )}
+      </div>
     );
   },
 );