fix(core): honor root data-duration when GSAP timeline ends short (#1378)

* fix(core): honor root data-duration when GSAP timeline ends short

The authored-duration floor only counted child composition clips, never
the root element's own data-duration. A composition whose GSAP timeline
ended even 0.1s short of its declared data-duration reported the shorter
timeline length from player.getDuration() — and the studio's adapter
selection (docDuration <= adapterDur) then silently rejected the
audio-capable runtime player, downgrading preview playback to the
seek-scrubbing adapter, which never starts media elements or WebAudio.
Result: total audio silence with zero errors anywhere.

- include the root's declared data-duration in
  resolveAuthoredCompositionDurationFloorSeconds, making data-duration
  the source of truth for playable length (per the documented contract)
- console.warn in the studio when playback falls back to the
  seek-driven adapter, since the downgrade loses audio invisibly

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(studio): release static-seek adapter on native win, warn once on downgrade

Review findings on the previous commit, all in the static-seek fallback
path of useTimelinePlayer.getAdapter:

- A cached static-seek adapter was never paused when adapter selection
  later resolved a native adapter (the early returns bypass the fallback
  branch entirely), leaving its private rAF loop seeking the player while
  the native transport also drives it. The core data-duration fix makes
  this switch path much more common. releaseStaticSeekCache() now runs
  at every native-adapter return and at unmount.
- The downgrade warning fired on every cache miss — and the cache key can
  never hold for __timelines compositions because wrapTimeline() returns
  a fresh object per call, so it fired every rAF tick. It now warns once
  per downgrade streak (re-armed when a native adapter takes over).
- The warning interpolated adapterDur (the native __player duration,
  0 when absent) instead of the selected adapter's duration, and used a
  one-off "[hyperframes-studio]" prefix instead of the file's
  "[useTimelinePlayer]" convention.

The fallback cache logic moved to playbackAdapter.ts (with unit tests for
warn-once, cache identity, and pause-on-replace/release), which also
keeps useTimelinePlayer.ts inside the studio 600-line limit. Also
corrected a stale "no DOM reads" comment on the runtime transport tick —
the duration floor has always queried the DOM per call, and now also
reads the root's declared data-duration.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

packages/studio/src/player/lib/playbackAdapter.ts

@@ -134,6 +134,68 @@ export function createStaticSeekPlaybackAdapter(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Static-seek fallback cache
+// ---------------------------------------------------------------------------
+
+export type StaticSeekCacheEntry = {
+  player: RuntimePlaybackAdapter | PlaybackAdapter;
+  duration: number;
+  adapter: PlaybackAdapter;
+};
+
+type StaticSeekCacheRef = { current: StaticSeekCacheEntry | null };
+type WarnedRef = { current: boolean };
+
+/**
+ * Pause and drop the cached static-seek adapter. Must be called whenever
+ * adapter selection switches to a native adapter — a cached static-seek
+ * adapter that was mid-play keeps its private rAF loop seeking the player
+ * forever otherwise, fighting the native transport. Also re-arms the
+ * downgrade warning so a later re-downgrade is surfaced again.
+ */
+export function releaseStaticSeekCache(cache: StaticSeekCacheRef, warned: WarnedRef): void {
+  cache.current?.adapter.pause();
+  cache.current = null;
+  warned.current = false;
+}
+
+/**
+ * Resolve (with caching) the seek-driven fallback adapter. Warns once per
+ * downgrade streak: seek-driven playback never starts media elements or
+ * WebAudio, so without the warning the downgrade silently loses audio.
+ */
+export function resolveStaticSeekFallback(opts: {
+  cache: StaticSeekCacheRef;
+  warned: WarnedRef;
+  bestAdapter: RuntimePlaybackAdapter | PlaybackAdapter;
+  effectiveDuration: number;
+  docDuration: number;
+  clock: StaticSeekPlaybackClock;
+  getPlaybackRate: () => number;
+}): PlaybackAdapter {
+  const { cache, warned, bestAdapter, effectiveDuration, docDuration } = opts;
+  const cached = cache.current;
+  if (cached?.player === bestAdapter && cached.duration === effectiveDuration) {
+    return cached.adapter;
+  }
+  cached?.adapter.pause();
+  if (!warned.current) {
+    warned.current = true;
+    console.warn(
+      `[useTimelinePlayer] Selected adapter duration (${getAdapterDuration(bestAdapter)}s) does not cover the document duration (${docDuration}s); falling back to seek-driven playback, which never starts media elements or WebAudio. Audio will not play in preview — extend the GSAP timeline to cover the declared data-duration.`,
+    );
+  }
+  const adapter = createStaticSeekPlaybackAdapter(
+    bestAdapter,
+    effectiveDuration,
+    opts.clock,
+    opts.getPlaybackRate,
+  );
+  cache.current = { player: bestAdapter, duration: effectiveDuration, adapter };
+  return adapter;
+}
+
 // ---------------------------------------------------------------------------
 // GSAP timeline wrapper
 // ---------------------------------------------------------------------------