fix(studio): preserve playback across forward RAF loop wrap-around

[calcarazgre646]

Summary

Pass { keepPlaying: true } to the forward RAF loop's wrap-around adapter.seek(loopStart) call so the seek doesn't trigger the adapter's implicit pause that the very next line (adapter.play()) has to undo.

Background

After the keepPlaying contract was established for the public seek API (#842, #863) and aligned across both adapters (wrapTimeline hardened in 3e7b464b, createStaticSeekPlaybackAdapter in #1089), the internal loop wrap-around in useTimelinePlayer.ts:232 still calls the bare 1-arg form:

if (time >= loopEnd) {
  if (usePlayerStore.getState().loopEnabled && dur > 0) {
    adapter.seek(loopStart);   // ← default seek, which now means "pause"
    liveTime.notify(loopStart);
    adapter.play();            // ← resume what was just paused
    setIsPlaying(true);
    rafRef.current = requestAnimationFrame(tick);
    return;
  }

The intent here is unambiguous: we are inside loopEnabled && dur > 0, the return short-circuits the no-loop terminal-pause branch below, and the very next statement resumes playback. The default-pause behavior is pure churn.

What happens per wrap, per adapter

Path	Without keepPlaying	With keepPlaying
wrapTimeline (GSAP)	tl.pause() → tl.seek() → tl.pause() → tl.play() (4 ops, two of which fight each other)	tl.seek(); tl.play() is a no-op on an already-playing timeline (1 op)
createStaticSeekPlaybackAdapter	renderSeek() → playing = false → cancelAnimationFrame → then play() re-arms playing = true and re-schedules RAF	renderSeek() → rebase playStartTime / playStartNow; play() early-returns because playing is still true

The follow-up adapter.play() and setIsPlaying(true) stay as a safety belt — they're cheap no-ops on the happy path but keep the branch correct if the adapter somehow already drifted to paused.

Tests

packages/studio/src/player/hooks/useTimelinePlayer.seek.test.ts had no coverage for the RAF wrap-around path (verified by grep: zero loop/wrap/loopStart references across the entire studio test suite for this file). Adds a new describe("useTimelinePlayer RAF loop wrap-around") block with:

1. Wrap-around with loop enabled — sets inPoint=2, outPoint=5 (which auto-enables loop per fix(studio): auto-enable loop when work-area markers are set #859), calls api.play(), advances mock adapter time past outPoint, drives one captured RAF callback, asserts adapter.seek was invoked with (2, { keepPlaying: true }) and adapter.play ran.
2. End of timeline without loop (regression guard) — sets loopEnabled=false, advances past duration, asserts no seek to loopStart happened and adapter.pause() was called instead (the other branch in the same if (time >= loopEnd) block).

Both tests install/restore a local requestAnimationFrame capture so RAF callbacks can be driven deterministically; no global state leaks between tests.

Validation

Check	Result
bun run --cwd packages/studio test	620/620 ✅ (+2)
bun run --cwd packages/studio typecheck	clean
bunx oxlint (touched files)	0/0
bunx oxfmt --check (touched files)	clean
Lefthook (filesize + lint + format + typecheck + fallow + commitlint)	✅
Fallow audit	clean (no new findings)
useTimelinePlayer.ts line count	599 (under the 600-line studio gate)

Cross-PR check

Branched from upstream/main at 7be4f92f. Of the open PRs, none touch packages/studio/src/player/hooks/useTimelinePlayer.ts:

• fix(studio): fit preview reset to composition dimensions #1085 already merged (refactored the public seek path; the loop-wrap line is untouched by that refactor).
• fix(studio): stabilize hook deps to prevent update loops #1019, fix(cli): preflight FFmpeg + Chrome check before studio renders #1014, fix(player): guard play/pause/removeEventListener against null refs #1016, fix(core): guard getTimeline() against missing time/duration #1017 (@miguel-heygen) touch runtime/, cli/, player/, usePlaybackKeyboard.ts respectively — no overlap.

Out of scope (intentionally)

• The backward RAF loop's terminal adapter.seek(loopStart) at line 336 correctly stays on the default (it is followed by setIsPlaying(false) and is the no-loop terminal pause).
• The backward loop's wraparound case (if (loopEnabled) branch at line 327) doesn't call adapter.seek directly — it resets local startTime / nextTime and lets the reverse RAF drive the seek on the next tick with the adapter already paused (adapter.pause() at the start of playBackward).
• The play() callback's recover-from-end seek at line 297 was considered but is an edge case (the adapter is usually paused there, so keepPlaying would be inert); leaving it out keeps this PR tight.

[miguel-heygen]

Fix is correct. { keepPlaying: true } on the forward RAF loop wrap-around seek prevents both adapters from implicitly stopping playback mid-transition:

• createStaticSeekPlaybackAdapter: skips playing = false + cancelAnimationFrame
• wrapTimeline (GSAP): skips the double tl.pause() around tl.seek()

The subsequent adapter.play() stays as a safety belt. Backward loop seek sites correctly left untouched (terminal-pause and per-tick-on-paused-adapter paths).

Tests cover both the positive case (keepPlaying: true passed + play() called after RAF) and the regression guard (no wrap-around seek when loopEnabled=false).

Minor: the inline comment "play() below is then a no-op" is only true for the happy path — if the adapter drifted paused despite keepPlaying, play() would catch it. Could say "fallback" instead of "no-op." Non-blocking.