fix(core): never pre-roll a segment whose roll-in sits at/past the media end

play() on an element at its media end rewinds to the beginning
(HTMLMediaElement spec). When a clip's in-point lies at/past the end of
its source, the pre-roll's currentTime assignment clamps to duration,
ended stays true, and play() silently rewinds — the hidden element plays
the source's HEAD and the boundary flip flashes it for ~2-3 frames while
the activation seek recovers. Skip the roll for that shape (parked at the
end is the element's best readiness; the active tick holds the last
frame). A roll-in before the end stays safe even on an ended element:
the assignment clears the ended state before play() runs.

Author: I-bangash

packages/core/src/runtime/media.test.ts

@@ -1149,6 +1149,32 @@ describe("syncRuntimeMedia", () => {
       expect(clip.el.play).not.toHaveBeenCalled();
     });
 
+    it("skips the pre-roll when the roll-in point sits at/past the media end — play() would rewind to 0", () => {
+      // In-point beyond the source's real duration: the roll-in assignment
+      // clamps to the end, `ended` stays true, and play() would silently seek
+      // back to 0 — the hidden element then plays the source's HEAD and the
+      // boundary flip flashes it (the "frame 0 blink" at every cut of an
+      // over-extended clip). The element must stay parked and paused instead.
+      const clip = readyClip({ start: 5.2, end: 12, mediaStart: 2.2 });
+      Object.defineProperty(clip.el, "duration", { value: 1.96, configurable: true });
+      syncAt(clip, 5, { outputMuted: true });
+      expect(clip.el.play).not.toHaveBeenCalled();
+      // Falls back to the pre-seek stage (assignment clamps in a real browser;
+      // the mock records the raw target — the point is the park, not the roll).
+      expect(clip.el.currentTime).toBe(2.2);
+    });
+
+    it("still pre-rolls when the roll-in lands before the media end", () => {
+      // Safe even on an element parked at the end (`ended`): the roll-in
+      // assignment moves currentTime off the end first, clearing the ended
+      // state before play() runs.
+      const clip = readyClip({ start: 5.2, end: 12, mediaStart: 1.9 });
+      Object.defineProperty(clip.el, "duration", { value: 1.96, configurable: true });
+      syncAt(clip, 5, { outputMuted: true });
+      expect(clip.el.play).toHaveBeenCalled();
+      expect(clip.el.currentTime).toBeCloseTo(1.7, 5);
+    });
+
     it("retries the pre-seek on a later tick when the first tick is below HAVE_METADATA", () => {
       const clip = readyClip({ start: 7, end: 12, mediaStart: 30 });
       setReadyState(clip.el, 0 /* HAVE_NOTHING */);

packages/core/src/runtime/media.ts

@@ -192,6 +192,21 @@ const prerolling = new WeakSet<HTMLMediaElement>();
 // would still reach its boundary at the wrong offset, paying the cold seek this
 // whole path exists to avoid. Instead we leave it unlatched and retry on the
 // next tick, once metadata has arrived.
+// HTMLMediaElement.play() on media sitting at its end seeks back to the
+// beginning before playing. A segment whose roll-in point lies at/past the end
+// of its source can't escape that state: the `currentTime` assignment below
+// CLAMPS to `duration`, `ended` stays true, and play() silently rewinds — the
+// hidden element then plays the source's HEAD, and the boundary flip flashes
+// it while the activation seek recovers (a visible "frame 0" blink at every
+// cut of a clip whose in-point outlives its media). Parked at the end IS that
+// element's best readiness: skip the roll and let the active tick hold the
+// last frame. (A roll-in BEFORE the end is safe even on an `ended` element —
+// the assignment clears the ended state before play() runs.)
+function prerollWouldRewind(el: HTMLMediaElement, prerollFrom: number): boolean {
+  const dur = el.duration;
+  return Number.isFinite(dur) && dur > 0 && prerollFrom >= dur - 0.05;
+}
+
 function preseekUpcoming(el: HTMLMediaElement, mediaStart: number): void {
   if (upcomingPreseeked.has(el)) return;
   if (el.readyState < HTMLMediaElement.HAVE_METADATA) return;
@@ -540,7 +555,8 @@ export function syncRuntimeMedia(params: {
         el.tagName === "VIDEO" &&
         mutedThroughPreroll &&
         leadSeconds <= PREROLL_WINDOW_SECONDS &&
-        prerollFrom >= 0
+        prerollFrom >= 0 &&
+        !prerollWouldRewind(el, prerollFrom)
       ) {
         if (!prerolling.has(el)) {
           prerolling.add(el);