From fa287342a047b890bd3660d7b1c83c727f4499da Mon Sep 17 00:00:00 2001
From: robinebers <16515780+robinebers@users.noreply.github.com>
Date: Sat, 14 Nov 2026 03:54:50 +0000
Subject: [PATCH] fix(player): keep the video playing when you jump to another
 moment

Clicking or dragging the scrubber while a film played left it paused at
the new spot, and `paused` turned true without a `pause` event. The
controls now hold a playing film during the press and play on from where
it is released, like a <video>'s own controls; a paused film stays
paused. A touch scrub no longer replays as mouse events.

seek() gains an opt-in { keepPlaying: true } for hosts (keyboard seeks,
chapter jumps). A plain seek(t), and setting currentTime, still land
paused, so existing callers keep their behavior.

The packed player tarball grows 339 bytes (158705 to 159044, packed with
pnpm 10.17.1 as CI does). main sat 11 bytes under the 1% gate, so the
packed budget moves to 159100; the unpacked size stays within budget.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 docs/packages/player.mdx                      |   9 +-
 packages/player/README.md                     |   7 +-
 packages/player/src/controls.test.ts          |  82 +++++++++++
 packages/player/src/controls.ts               |  34 +++--
 .../player/src/hyperframes-player.test.ts     | 132 +++++++++++++++++-
 packages/player/src/hyperframes-player.ts     |  10 +-
 scripts/package-size-budgets.json             |   2 +-
 7 files changed, 252 insertions(+), 24 deletions(-)

diff --git a/docs/packages/player.mdx b/docs/packages/player.mdx
index 5fdfa28926e..538db4258a8 100644
--- a/docs/packages/player.mdx
+++ b/docs/packages/player.mdx
@@ -44,7 +44,9 @@ import "@hyperframes/player";
 Set `autoplay muted` only when playback should start without a user gesture.
 
 Add or remove `controls` at any time. When shown, the controls reflect the current
-playback state, position and speed.
+playback state, position and speed. Clicking or dragging the scrubber keeps a
+playing film playing from the new spot, as a `<video>`'s own controls do, and
+leaves a paused film paused.
 
 ## Attributes
 
@@ -93,6 +95,7 @@ const player = document.querySelector("hyperframes-player");
 player.play();
 player.pause();
 player.seek(2.5);
+player.seek(2.5, { keepPlaying: true });
 
 player.currentTime = 5;
 player.playbackRate = 1.5;
@@ -102,6 +105,10 @@ console.log(player.duration, player.paused, player.ready);
 console.log(player.compositionWidth, player.compositionHeight);
 ```
 
+`seek()` and setting `currentTime` pause at the new time. Pass `{ keepPlaying: true }`
+to keep a playing film playing from there, as setting a `<video>`'s `currentTime`
+does; a paused film stays paused.
+
 In Studio previews, scrubbing keeps the last complete picture visible while video
 layers decode at the requested time. Rapid seeks keep only the latest queued
 destination, and the captions and video layers appear together once it is ready.
diff --git a/packages/player/README.md b/packages/player/README.md
index c6f89d9c106..8e54af78100 100644
--- a/packages/player/README.md
+++ b/packages/player/README.md
@@ -28,7 +28,7 @@ If you need a classic `<script>` tag instead of ESM, use the explicit global bui
 
 The player loads the composition in a sandboxed iframe, auto-detects its dimensions and duration, and scales it responsively to fit the container.
 
-Add or remove `controls` at any time. When shown, the controls reflect the current playback state, position and speed.
+Add or remove `controls` at any time. When shown, the controls reflect the current playback state, position and speed. Clicking or dragging the scrubber keeps a playing film playing from the new spot, as a `<video>`'s own controls do, and leaves a paused film paused.
 
 ### With a framework
 
@@ -144,10 +144,11 @@ const player = document.querySelector("hyperframes-player");
 // Playback
 player.play();
 player.pause();
-player.seek(2.5); // jump to 2.5 seconds
+player.seek(2.5); // jump to 2.5 seconds and pause there
+player.seek(2.5, { keepPlaying: true }); // jump, and keep playing if it was playing
 
 // Properties
-player.currentTime; // number (read/write)
+player.currentTime; // number (read/write); setting it jumps and pauses, like seek()
 player.duration; // number (read-only)
 player.paused; // boolean (read-only)
 player.ready; // boolean (read-only)
diff --git a/packages/player/src/controls.test.ts b/packages/player/src/controls.test.ts
index d41e29565cc..5eaee9e5980 100644
--- a/packages/player/src/controls.test.ts
+++ b/packages/player/src/controls.test.ts
@@ -165,3 +165,85 @@ describe("createControls idle hide", () => {
     vi.useRealTimers();
   });
 });
+
+describe("createControls scrubbing", () => {
+  function setup() {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const calls: string[] = [];
+    const api = createControls(host, {
+      ...noopCallbacks(),
+      onPlay: () => {
+        calls.push("play");
+        api.updatePlaying(true);
+      },
+      onPause: () => {
+        calls.push("pause");
+        api.updatePlaying(false);
+      },
+      onSeek: (fraction) => calls.push(`seek ${fraction}`),
+      onScrubStart: () => calls.push("scrub start"),
+      onScrubEnd: () => calls.push("scrub end"),
+    });
+    const scrubber = host.querySelector<HTMLElement>(".hfp-scrubber")!;
+    scrubber.getBoundingClientRect = () => ({ left: 0, width: 100 }) as DOMRect;
+    const playButton = host.querySelector<HTMLElement>(".hfp-play-btn")!;
+    const teardown = () => {
+      api.destroy();
+      host.remove();
+    };
+    return { api, calls, scrubber, playButton, teardown };
+  }
+
+  it("holds a playing film while the scrubber is pressed and plays on at release", () => {
+    const { api, calls, scrubber, playButton, teardown } = setup();
+    api.updatePlaying(true);
+
+    scrubber.dispatchEvent(new MouseEvent("mousedown", { clientX: 20 }));
+    document.dispatchEvent(new MouseEvent("mousemove", { clientX: 70 }));
+
+    expect(calls).toEqual(["pause", "scrub start", "seek 0.2", "seek 0.7"]);
+    expect(playButton.classList.contains("hfp-playing")).toBe(true);
+
+    document.dispatchEvent(new MouseEvent("mouseup"));
+
+    expect(calls).toEqual(["pause", "scrub start", "seek 0.2", "seek 0.7", "scrub end", "play"]);
+    expect(playButton.classList.contains("hfp-playing")).toBe(true);
+    teardown();
+  });
+
+  it("leaves a paused film paused", () => {
+    const { calls, scrubber, playButton, teardown } = setup();
+
+    scrubber.dispatchEvent(new MouseEvent("mousedown", { clientX: 30 }));
+    document.dispatchEvent(new MouseEvent("mouseup"));
+
+    expect(calls).toEqual(["scrub start", "seek 0.3", "scrub end"]);
+    expect(playButton.classList.contains("hfp-playing")).toBe(false);
+    teardown();
+  });
+
+  it("plays on once after a touch scrub, without the tap replaying as mouse events", () => {
+    const { api, calls, scrubber, teardown } = setup();
+    api.updatePlaying(true);
+
+    const touch = new Touch({ identifier: 0, target: scrubber, clientX: 40 });
+    scrubber.dispatchEvent(new TouchEvent("touchstart", { touches: [touch] }));
+    const touchEnd = new TouchEvent("touchend", { cancelable: true });
+    document.dispatchEvent(touchEnd);
+
+    expect(calls).toEqual(["pause", "scrub start", "seek 0.4", "scrub end", "play"]);
+    expect(touchEnd.defaultPrevented).toBe(true);
+    teardown();
+  });
+
+  it("leaves taps elsewhere on the page alone", () => {
+    const { teardown } = setup();
+
+    const touchEnd = new TouchEvent("touchend", { cancelable: true });
+    document.dispatchEvent(touchEnd);
+
+    expect(touchEnd.defaultPrevented).toBe(false);
+    teardown();
+  });
+});
diff --git a/packages/player/src/controls.ts b/packages/player/src/controls.ts
index b6485b63b92..1a9240991c3 100644
--- a/packages/player/src/controls.ts
+++ b/packages/player/src/controls.ts
@@ -294,21 +294,30 @@ export function createControls(
   };
 
   let scrubbing = false;
+  let playAfterScrub = false;
 
-  scrubber.addEventListener("mousedown", (e) => {
-    e.stopPropagation();
+  const startScrub = () => {
     scrubbing = true;
+    playAfterScrub = isPlaying;
+    if (playAfterScrub) callbacks.onPause();
     callbacks.onScrubStart?.();
+  };
+  const endScrub = () => {
+    scrubbing = false;
+    callbacks.onScrubEnd?.();
+    if (playAfterScrub) callbacks.onPlay();
+  };
+
+  scrubber.addEventListener("mousedown", (e) => {
+    e.stopPropagation();
+    startScrub();
     handleScrubAt(e.clientX);
   });
   const onMouseMove = (e: MouseEvent) => {
     if (scrubbing) handleScrubAt(e.clientX);
   };
   const onMouseUp = () => {
-    if (scrubbing) {
-      scrubbing = false;
-      callbacks.onScrubEnd?.();
-    }
+    if (scrubbing) endScrub();
   };
   document.addEventListener("mousemove", onMouseMove);
   document.addEventListener("mouseup", onMouseUp);
@@ -316,8 +325,7 @@ export function createControls(
   scrubber.addEventListener(
     "touchstart",
     (e) => {
-      scrubbing = true;
-      callbacks.onScrubStart?.();
+      startScrub();
       const touch = e.touches[0];
       if (touch) handleScrubAt(touch.clientX);
     },
@@ -329,11 +337,10 @@ export function createControls(
       if (touch) handleScrubAt(touch.clientX);
     }
   };
-  const onTouchEnd = () => {
-    if (scrubbing) {
-      scrubbing = false;
-      callbacks.onScrubEnd?.();
-    }
+  const onTouchEnd = (e: TouchEvent) => {
+    if (!scrubbing) return;
+    if (e.cancelable) e.preventDefault();
+    endScrub();
   };
   document.addEventListener("touchmove", onTouchMove, { passive: true });
   document.addEventListener("touchend", onTouchEnd);
@@ -368,6 +375,7 @@ export function createControls(
       time.textContent = `${formatTime(clampedCurrent)} / ${formatTime(duration)}`;
     },
     updatePlaying(playing: boolean) {
+      if (scrubbing && playAfterScrub) return;
       const changed = playing !== isPlaying;
       isPlaying = playing;
       playBtn.classList.toggle("hfp-playing", playing);
diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index 56f84e3a48b..d77a6773296 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -812,12 +812,16 @@ describe("HyperframesPlayer seek() sync path", () => {
     postMessage?: ReturnType<typeof vi.fn>;
   };
   type PlayerInternal = HTMLElement & {
-    seek: (t: number) => void;
+    seek: (t: number, options?: { keepPlaying?: boolean }) => void;
     play: () => void;
     pause: () => void;
     stopMedia: () => void;
     iframe: HTMLIFrameElement;
     _currentTime: number;
+    _ready: boolean;
+    _assetsReady: boolean;
+    currentTime: number;
+    paused: boolean;
     duration: number;
     _parentMedia: Array<{
       el: { pause: ReturnType<typeof vi.fn>; src: string };
@@ -1169,6 +1173,107 @@ describe("HyperframesPlayer seek() sync path", () => {
     player.seek(11);
     expect(player._currentTime).toBe(11);
   });
+
+  function fakeTimeline(duration: number) {
+    const state = { time: 0, playing: false };
+    const timeline: TimelineStub = {
+      duration: () => duration,
+      time: () => state.time,
+      seek: (t) => void (state.time = t),
+      play: () => void (state.playing = true),
+      pause: () => void (state.playing = false),
+    };
+    return { timeline, state };
+  }
+
+  function recordPlayAndPause(): string[] {
+    const events: string[] = [];
+    for (const type of ["play", "pause"]) player.addEventListener(type, () => events.push(type));
+    return events;
+  }
+
+  it("keeps playing from the new time when seek() is asked to keep playing", () => {
+    const { timeline, state } = fakeTimeline(10);
+    stubContentWindow({ __timelines: { main: timeline }, postMessage: vi.fn() });
+    player.play();
+    const events = recordPlayAndPause();
+
+    player.seek(3, { keepPlaying: true });
+
+    expect(player.paused).toBe(false);
+    expect(player.currentTime).toBe(3);
+    expect(state).toEqual({ time: 3, playing: true });
+    expect(events).toEqual([]);
+  });
+
+  it("stays paused when seek() is asked to keep playing a paused film", () => {
+    const { timeline, state } = fakeTimeline(10);
+    stubContentWindow({ __timelines: { main: timeline }, postMessage: vi.fn() });
+    const events = recordPlayAndPause();
+
+    player.seek(3, { keepPlaying: true });
+
+    expect(player.paused).toBe(true);
+    expect(state).toEqual({ time: 3, playing: false });
+    expect(events).toEqual([]);
+  });
+
+  it("asks a cross-origin runtime to play on after a seek that keeps playing", () => {
+    const post = vi.fn();
+    stubContentWindow({ postMessage: post });
+    player._ready = true;
+    player._assetsReady = true;
+    player.play();
+    post.mockClear();
+
+    player.seek(3, { keepPlaying: true });
+
+    const actions = post.mock.calls
+      .map(([message]) => message.action)
+      .filter((action) => action === "seek" || action === "play");
+    expect(actions).toEqual(["seek", "play"]);
+    expect(post).toHaveBeenCalledWith(
+      expect.objectContaining({ action: "seek", timeSeconds: 3 }),
+      "*",
+    );
+    expect(player.paused).toBe(false);
+  });
+
+  it("keeps a playing film playing from where the viewer releases the scrubber", () => {
+    const { timeline, state } = fakeTimeline(10);
+    stubContentWindow({ __timelines: { main: timeline }, postMessage: vi.fn() });
+    player.setAttribute("controls", "");
+    player.play();
+    const events = recordPlayAndPause();
+    const scrubber = player.shadowRoot!.querySelector<HTMLElement>(".hfp-scrubber")!;
+    scrubber.getBoundingClientRect = () => ({ left: 0, width: 100 }) as DOMRect;
+
+    scrubber.dispatchEvent(new MouseEvent("mousedown", { clientX: 20 }));
+    document.dispatchEvent(new MouseEvent("mousemove", { clientX: 70 }));
+    document.dispatchEvent(new MouseEvent("mouseup"));
+
+    expect(player.paused).toBe(false);
+    expect(player.currentTime).toBe(7);
+    expect(state).toEqual({ time: 7, playing: true });
+    expect(events).toEqual(["pause", "play"]);
+  });
+
+  it("leaves a paused film paused when the viewer clicks the scrubber", () => {
+    const { timeline, state } = fakeTimeline(10);
+    stubContentWindow({ __timelines: { main: timeline }, postMessage: vi.fn() });
+    player.setAttribute("controls", "");
+    player.seek(0);
+    const events = recordPlayAndPause();
+    const scrubber = player.shadowRoot!.querySelector<HTMLElement>(".hfp-scrubber")!;
+    scrubber.getBoundingClientRect = () => ({ left: 0, width: 100 }) as DOMRect;
+
+    scrubber.dispatchEvent(new MouseEvent("mousedown", { clientX: 70 }));
+    document.dispatchEvent(new MouseEvent("mouseup"));
+
+    expect(player.paused).toBe(true);
+    expect(state).toEqual({ time: 7, playing: false });
+    expect(events).toEqual([]);
+  });
 });
 
 describe("HyperframesPlayer loop end-state handling", () => {
@@ -3807,7 +3912,7 @@ describe("HyperframesPlayer asset-ready gate", () => {
     _onIframeLoad(): void;
     play(): void;
     pause(): void;
-    seek(timeInSeconds: number): void;
+    seek(timeInSeconds: number, options?: { keepPlaying?: boolean }): void;
     shaderLoader: {
       showAssetsLoading(): void;
       hide(): void;
@@ -4386,6 +4491,29 @@ describe("HyperframesPlayer asset-ready gate", () => {
     player.remove();
   });
 
+  it("keeps a queued play if a seek asks to keep playing while assets are still buffering", async () => {
+    const player = await createConnectedPlayer();
+
+    const { doc, video } = createStalledVideoDoc();
+    stubIframeContentDocument(player.iframe, doc);
+
+    const playSpy = vi.fn();
+    player.addEventListener("play", playSpy);
+
+    player._waitForAssetsReady(doc);
+    player.play();
+    player.seek(1.5, { keepPlaying: true });
+
+    video.dispatchEvent(new Event("canplay"));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(player.assetsReady).toBe(true);
+    expect(player._paused).toBe(false);
+    expect(playSpy).toHaveBeenCalledTimes(1);
+
+    player.remove();
+  });
+
   it("settles a play() called twice while buffering into exactly one playback start (pre-existing idempotency, not the pause/seek cancel)", async () => {
     const player = await createConnectedPlayer();
 
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index 3c257631bce..475131a8e36 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -487,10 +487,11 @@ class HyperframesPlayer extends HTMLElement {
     this._media.stopAdoptedMedia();
   }
 
-  seek(timeInSeconds: number) {
-    // seek()'s own contract is that it lands paused, so a play still queued
-    // from the asset-buffering window is cancelled here too — same reason as
-    // pause() above.
+  seek(timeInSeconds: number, options?: { keepPlaying?: boolean }) {
+    const playOn = options?.keepPlaying === true && (!this._paused || this._pendingPlay);
+    // A plain seek() lands paused, so a play still queued from the
+    // asset-buffering window is cancelled here too — same reason as pause()
+    // above. keepPlaying plays on from the new time, as <video>'s currentTime does.
     this._pendingPlay = false;
     if (!this._trySyncSeek(timeInSeconds) && !this._tryDirectTimelineSeek(timeInSeconds)) {
       this._sendControl("seek", {
@@ -523,6 +524,7 @@ class HyperframesPlayer extends HTMLElement {
     this._paused = true;
     this.controlsApi?.updatePlaying(false);
     this.controlsApi?.updateTime(this._currentTime, this._duration);
+    if (playOn) this._play(false);
   }
 
   setColorGrading(target: ColorGradingTarget, grading: unknown) {
diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json
index 1523d7e3d6c..8c684fb9f11 100644
--- a/scripts/package-size-budgets.json
+++ b/scripts/package-size-budgets.json
@@ -32,7 +32,7 @@
     "unpacked": 885314
   },
   "@hyperframes/player": {
-    "packed": 157145,
+    "packed": 159100,
     "unpacked": 541601
   },
   "@hyperframes/producer": {