[robinebers]

Why

When you watch a video in the HyperFrames player and click somewhere on the progress bar to jump ahead, the video stops. You land on the new moment, frozen, and have to press play again. Dragging along the bar does the same. Every other video player, from YouTube to the browser's own, keeps playing from the new spot, so this feels broken. Apps that draw their own play button also fall out of sync, because the player stops without announcing it: paused turns true and no pause event fires.

What changes

• Clicking or dragging the progress bar while a video plays keeps it playing from wherever you let go. While you hold the button down, the video waits on that frame, and it continues when you release, the way the browser's own video controls behave.
• A paused video stays paused when you click or drag the bar.
• Touch works the same way.
• The play button keeps showing "pause" through the click.
• Developers get the same choice for their own buttons and keyboard shortcuts: player.seek(30, { keepPlaying: true }) jumps without stopping. A plain player.seek(30) and player.currentTime = 30 still stop at the new time, exactly as before, so existing pages keep working the same way.
• The package README and the docs page describe both.

Before

Clicking the bar at 65% while the video plays: it stops at 6.5 s. A drag afterwards leaves it stopped too.

Watch the Before recording (MP4)

After

The same clicks: the video keeps playing from 6.5 s, and again from where the drag ends.

Watch the After recording (MP4)

Test plan

Checked in Chrome 157 with the built player (dist/hyperframes-player.global.js) against a build of main, on four kinds of embed: an opaque-origin composition (sandbox-origin="opaque"), a same-origin composition, a composition that only registers window.__timelines, and an MP4 in video mode.

• Clicking the bar at 70% while playing continues from 7.0 s (8.2 s one second later) on all four. Events arrive as pause then play, the same order Chrome's own <video controls> uses (pause, seeking, seeked, play, playing).
• Dragging while playing continues from the release point.
• Clicking or dragging while paused stays paused and fires no events.
• A touch tap and a touch drag (Chrome touch emulation) continue playing with one pause/play pair.
• The play button shows "pause" in all 89 frames recorded around a click.
• seek(2, { keepPlaying: true }) while playing keeps playing and fires no events; seek(6) still lands paused.
• bun run --cwd packages/player test (589 tests, 10 new, 6 of which fail on main), typecheck, oxlint, oxfmt, fallow, the comment checks and bun run verify:packed-manifests pass.

How

• controls.ts: pressing the scrubber while playing pauses through the existing onPause callback and remembers that it did; releasing calls onPlay. The play button ignores state changes during that press. When a touch scrub ends, its touchend is cancelled so the browser doesn't follow the tap with mouse events, which would scrub a second time.
• hyperframes-player.ts: seek(t, { keepPlaying: true }) runs the normal seek, then resumes through the internal play path (no second play event) if the player was playing or had a play queued while its assets loaded.
• Size budget: packed 157,145 → 159,100. With CI's pnpm 10.17.1, main packs to 158,705 bytes, 11 under the old limit. This change adds 235 bytes of code and 104 bytes of README (159,044). The unpacked size stays within its budget.

Why seek() keeps pausing by default

Landing paused is seek()'s deliberate contract. Maintainer comments say so (#750, #4054), a test asserts it, and the loop wrap, play-range jumps and the scrubber's own settle rely on it. The runtime (#863) and Studio (#842) both made playing on an opt-in keepPlaying flag, so the player's API takes the same shape. The built-in controls are different: nothing chose for the scrubber to pause, it inherited seek()'s contract (#890 noticed that a scrubber click pauses and made the audio match). CONTRIBUTING asks for default changes to be discussed, so treat this part as a proposal. If you'd rather keep today's scrubber behavior by default, it can move behind an attribute.

Notes

• On the runtime paths, paused can read true for a few milliseconds after a keep-playing seek, until the runtime's next state message arrives. The same already happens after a loop wrap, and nothing changes on screen.
• Clicking the very end of an MP4's bar while it plays restarts it, because play() at the end starts over (the player's existing rule, and the HTML one). Compositions end normally.
• Open question: should setting currentTime keep playing, as it does on a <video>? This PR leaves it landing paused.

Related work

• feat: allow clip animation + ship <hyperframes-player> web component #209 introduced the player with a video-like API.
• fix(studio): preserve playback state on Jump-to-in/out shortcuts #842 and fix(runtime): respect keepPlaying option in player seek #863 added keepPlaying to Studio and the runtime.
• feat(studio): add a preview seek bar #6103 kept pause-on-seek for Studio's preview seek bar; this PR doesn't touch Studio.
• Overlaps the player branding change (feat(player): add customizable branding to the preview player robinebers/hyperframes#1): both raise the player's packed size budget and both add tests at the end of controls.test.ts, so whichever lands second rebases and re-measures.

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 53c33cf.

Approve preview