From 514fd72a26e4a7f71f27a24eac544157cd8269dc Mon Sep 17 00:00:00 2001
From: James <james.russo@heygen.com>
Date: Wed, 24 Jun 2026 21:04:59 -0400
Subject: [PATCH 1/3] feat(slideshow): per-slide autoplay (manual-advance,
 opt-in)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an opt-in `autoplay` flag to slideshow slides: when the presenter lands
on a video slide, its `<video>` plays from the start. The slideshow still
holds and never auto-advances — the presenter clicks Next when ready. This
covers compositions whose own controls can't be clicked (the player renders
the composition pointer-events:none).

Plumbing (done, tested):
- core: `SlideRef.autoplay?: boolean`, parsed + validated in parseSlideshow
  (a non-boolean autoplay rejects the manifest); carried through resolve.
- controller: optional `PlayerPort.playSceneMedia(sceneId)`, fired only on
  forward `enterSlide` for autoplay slides (not resume/back/sync, so the
  audience — which mirrors the presenter's media events — isn't double-driven).
- component: `playSceneDocumentMedia` reaches the same-origin composition
  iframe, finds the scene's `<video>`, and asserts playback; `stopMedia`
  (already wired on slide change) resets it. An autoplay token cancels a
  pending start when the slide changes.
- tests: controller autoplay behavior + parser flag round-trip/validation
  (131 player + 22 core slideshow tests pass).

KNOWN LIMITATION — runtime media-start needs the player media model (@vance):
On current main the clip<->timeline binding from #1601 keeps every clip synced
and *paused* to the held timeline frame, which wins against playSceneMedia's
play() — so the clip does not actually start on main yet (it does on the
pre-#1601 player). The correct fix is a sanctioned "let this clip free-run
while the timeline holds" path in the player/runtime media controller. Flagging
for Vance to wire the start into the #1601 media model (or rebase onto it) when
back. The plumbing above is the stable surface that hook plugs into.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../core/src/slideshow/parseSlideshow.test.ts | 19 +++++
 packages/core/src/slideshow/parseSlideshow.ts | 15 ++--
 .../core/src/slideshow/slideshow.types.ts     |  7 ++
 .../src/slideshow/SlideshowController.test.ts | 46 +++++++++++
 .../src/slideshow/SlideshowController.ts      |  8 ++
 .../src/slideshow/hyperframes-slideshow.ts    | 76 +++++++++++++++++++
 6 files changed, 166 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/slideshow/parseSlideshow.test.ts b/packages/core/src/slideshow/parseSlideshow.test.ts
index 1633d58818..8251a16405 100644
--- a/packages/core/src/slideshow/parseSlideshow.test.ts
+++ b/packages/core/src/slideshow/parseSlideshow.test.ts
@@ -196,4 +196,23 @@ describe("resolveSlideshow", () => {
     expect(resolved.slides[0].start).toBe(1);
     expect(resolved.slides[0].end).toBe(4);
   });
+
+  it("parses and carries through the per-slide autoplay flag", () => {
+    const island = `<script type="application/hyperframes-slideshow+json">
+      { "slides": [ { "sceneId": "a", "autoplay": true }, { "sceneId": "b" } ] }
+    </script>`;
+    const m = parseSlideshowManifest(island);
+    expect(m?.slides[0].autoplay).toBe(true);
+    expect(m?.slides[1].autoplay).toBeUndefined();
+    const { resolved } = resolveSlideshow(m!, SCENES);
+    expect(resolved.slides[0].autoplay).toBe(true);
+    expect(resolved.slides[1].autoplay).toBeUndefined();
+  });
+
+  it("rejects a manifest whose slide autoplay is not a boolean", () => {
+    const island = `<script type="application/hyperframes-slideshow+json">
+      { "slides": [ { "sceneId": "a", "autoplay": "yes" } ] }
+    </script>`;
+    expect(() => parseSlideshowManifest(island)).toThrow();
+  });
 });
diff --git a/packages/core/src/slideshow/parseSlideshow.ts b/packages/core/src/slideshow/parseSlideshow.ts
index a7583f8406..3159f0cf46 100644
--- a/packages/core/src/slideshow/parseSlideshow.ts
+++ b/packages/core/src/slideshow/parseSlideshow.ts
@@ -44,16 +44,21 @@ export function parseSlideshowManifest(html: string): SlideshowManifest | null {
   return parsed;
 }
 
+function isOptionalNumberArray(v: unknown): boolean {
+  return v === undefined || (Array.isArray(v) && v.every((n) => typeof n === "number"));
+}
+
+function isOptional(v: unknown, type: "boolean"): boolean {
+  return v === undefined || typeof v === type;
+}
+
 function isSlideRef(v: unknown): v is SlideRef {
   if (typeof v !== "object" || v === null) return false;
   const r = v as Record<string, unknown>;
   if (typeof r["sceneId"] !== "string") return false;
-  if (
-    r["fragments"] !== undefined &&
-    !(Array.isArray(r["fragments"]) && r["fragments"].every((n) => typeof n === "number"))
-  )
-    return false;
+  if (!isOptionalNumberArray(r["fragments"])) return false;
   if (r["hotspots"] !== undefined && !Array.isArray(r["hotspots"])) return false;
+  if (!isOptional(r["autoplay"], "boolean")) return false;
   return true;
 }
 
diff --git a/packages/core/src/slideshow/slideshow.types.ts b/packages/core/src/slideshow/slideshow.types.ts
index fdddf1d243..59f82fceae 100644
--- a/packages/core/src/slideshow/slideshow.types.ts
+++ b/packages/core/src/slideshow/slideshow.types.ts
@@ -19,6 +19,13 @@ export interface SlideRef {
   notes?: string;
   fragments?: number[];
   hotspots?: SlideHotspot[];
+  /**
+   * When true, the slide's `<video>` plays automatically on enter (the
+   * presenter lands on the slide and the clip plays). The slideshow still holds
+   * — it never auto-advances — so the presenter clicks Next when ready.
+   * Defaults to false.
+   */
+  autoplay?: boolean;
   // Reserved — TTS deferred. Parsed and carried, never consumed.
   ttsScript?: string;
   ttsAudioUrl?: string;
diff --git a/packages/player/src/slideshow/SlideshowController.test.ts b/packages/player/src/slideshow/SlideshowController.test.ts
index 31b1bb037e..081a61067f 100644
--- a/packages/player/src/slideshow/SlideshowController.test.ts
+++ b/packages/player/src/slideshow/SlideshowController.test.ts
@@ -13,6 +13,7 @@ function fakePlayer() {
     play: vi.fn(() => {}),
     pause: vi.fn(() => {}),
     stopMedia: vi.fn(() => {}),
+    playSceneMedia: vi.fn((_sceneId: string) => {}),
     onTimeUpdate: (fn: (t: number) => void) => {
       cb = fn;
       return () => {
@@ -683,3 +684,48 @@ describe("SlideshowController syncTo", () => {
     expect(c.position.slideIndex).toBe(0);
   });
 });
+
+describe("SlideshowController autoplay", () => {
+  // "v" autoplays; "w" does not. Both sit on the main line.
+  const AUTOPLAY_SHOW: ResolvedSlideshow = {
+    slides: [
+      { sceneId: "v", start: 0, end: 5, fragments: [], hotspots: [], autoplay: true },
+      { sceneId: "w", start: 5, end: 10, fragments: [], hotspots: [] },
+    ],
+    sequences: {},
+  };
+
+  it("plays the slide's media on enter when autoplay is set", () => {
+    const p = fakePlayer();
+    new SlideshowController(p, AUTOPLAY_SHOW); // constructs on slide "v"
+    expect(p.playSceneMedia).toHaveBeenCalledWith("v");
+    expect(p.playSceneMedia).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not play media when entering a non-autoplay slide", () => {
+    const p = fakePlayer();
+    const c = new SlideshowController(p, AUTOPLAY_SHOW);
+    p.playSceneMedia.mockClear();
+    c.next(); // v → w (w is not autoplay)
+    expect(c.position.slideIndex).toBe(1);
+    expect(p.playSceneMedia).not.toHaveBeenCalled();
+  });
+
+  it("stops prior media and plays again when navigating back into an autoplay slide", () => {
+    const p = fakePlayer();
+    const c = new SlideshowController(p, AUTOPLAY_SHOW);
+    p.playSceneMedia.mockClear();
+    c.next(); // → w
+    expect(p.stopMedia).toHaveBeenCalled(); // leaving v stops its clip
+    p.playSceneMedia.mockClear();
+    c.prev(); // back into v (enterSlide) → replays
+    expect(p.playSceneMedia).toHaveBeenCalledWith("v");
+  });
+
+  it("does not require autoplay support on the port (optional hook)", () => {
+    // A port without playSceneMedia must not throw when entering an autoplay slide.
+    const p = fakePlayer() as Record<string, unknown>;
+    delete p.playSceneMedia;
+    expect(() => new SlideshowController(p as never, AUTOPLAY_SHOW)).not.toThrow();
+  });
+});
diff --git a/packages/player/src/slideshow/SlideshowController.ts b/packages/player/src/slideshow/SlideshowController.ts
index 5abd1c19b6..626161b397 100644
--- a/packages/player/src/slideshow/SlideshowController.ts
+++ b/packages/player/src/slideshow/SlideshowController.ts
@@ -5,6 +5,8 @@ export interface PlayerPort {
   play(): void;
   pause(): void;
   stopMedia?(): void;
+  /** Play the `<video>` inside the given scene (for `autoplay` slides). */
+  playSceneMedia?(sceneId: string): void;
   readonly currentTime: number;
   onTimeUpdate(cb: (t: number) => void): () => void;
 }
@@ -115,6 +117,12 @@ export class SlideshowController {
       this.frame.fragmentIndex = -1;
       this.playTo(this.restFrame(slide));
     }
+    // Opt-in: play the slide's own clip on enter. We never auto-advance — the
+    // presenter still clicks Next — this just saves a click into the (non-
+    // interactive) composition. Only on forward entry (enterSlide), not on
+    // resume/back/sync, and not on the audience (which mirrors the presenter's
+    // media events), so a clip isn't restarted under the presenter.
+    if (slide.autoplay) this.player.playSceneMedia?.(slide.sceneId);
     this.emitChange();
   }
 
diff --git a/packages/player/src/slideshow/hyperframes-slideshow.ts b/packages/player/src/slideshow/hyperframes-slideshow.ts
index 167a2d3213..4183224a9c 100644
--- a/packages/player/src/slideshow/hyperframes-slideshow.ts
+++ b/packages/player/src/slideshow/hyperframes-slideshow.ts
@@ -172,6 +172,9 @@ export class HyperframesSlideshow extends HTMLElement {
   private audienceMutedPlaybackKeys = new Set<string>();
   private blockedAudienceMedia = new Map<string, PresenterMediaMessage>();
   private audienceMediaUnlockButton: HTMLButtonElement | null = null;
+  // Bumped whenever autoplay starts or media is stopped (slide change), so a
+  // pending re-assert from a previous autoplay can't replay a clip we've left.
+  private autoplayToken = 0;
 
   /** Whether audio is currently muted. Reflects `data-hf-muted` attribute. */
   get muted(): boolean {
@@ -381,6 +384,7 @@ export class HyperframesSlideshow extends HTMLElement {
           playerEl.stopMedia?.();
           this.stopDocumentMedia();
         },
+        playSceneMedia: (sceneId) => this.playSceneDocumentMedia(sceneId),
         get currentTime() {
           return playerEl.currentTime;
         },
@@ -1023,12 +1027,84 @@ export class HyperframesSlideshow extends HTMLElement {
   }
 
   private stopDocumentMedia(): void {
+    // Invalidate any in-flight autoplay re-assert so leaving a slide can't be
+    // undone by a pending timeout replaying the clip we just paused.
+    this.autoplayToken++;
     const doc = this.ownerDocument;
     for (const el of doc.querySelectorAll("video, audio")) {
       if (el instanceof HTMLMediaElement) el.pause();
     }
   }
 
+  /**
+   * Play the `<video>` inside a given scene from its start — the runtime side of
+   * a slide's `autoplay`. Reaches into the same-origin composition iframe (which
+   * is pointer-events:none, so its own controls can't be clicked). The play()
+   * fires a "play" event that wireSlideshowMedia() already mirrors to any
+   * audience window, so we only call this on the presenter (via enterSlide).
+   *
+   * Robust against two timing hazards: (1) the clip may not be in the iframe DOM
+   * yet at construction (first slide), and (2) the player drives clips during
+   * bootstrap and seeks the timeline on enter — both pause the clip (and reject
+   * an in-flight play() with AbortError), so a single play() loses the race. We
+   * poll on a short timer: locate the clip, then assert play() until it is
+   * actually advancing, for a bounded window — then stop, so a later real user
+   * pause (presenter media controls) sticks. Token-guarded so leaving the slide
+   * cancels it. If play() is blocked for want of a gesture (real browser, first
+   * slide, no interaction yet), the first pointer/key event kicks it.
+   */
+  private playSceneDocumentMedia(sceneId: string): void {
+    const safeId = sceneId.replace(/["\\]/g, "\\$&");
+    const token = ++this.autoplayToken;
+    const findVideo = (): HTMLVideoElement | null => {
+      for (const player of this.mediaPlayerElements()) {
+        const doc = this.playerFrameDocument(player);
+        const video = doc?.querySelector(`[data-composition-id="${safeId}"] video`) ?? null;
+        if (video instanceof HTMLVideoElement) return video;
+      }
+      return null;
+    };
+    const STEP_MS = 150;
+    const WINDOW_MS = 6000;
+    let waited = 0;
+    let started = false;
+    let lastTime = -1;
+    let gestureWired = false;
+    const wireGestureRetry = (video: HTMLVideoElement): void => {
+      if (gestureWired) return;
+      gestureWired = true;
+      const retry = (): void => {
+        window.removeEventListener("pointerdown", retry, true);
+        window.removeEventListener("keydown", retry, true);
+        if (token === this.autoplayToken) void video.play().catch(() => {});
+      };
+      window.addEventListener("pointerdown", retry, true);
+      window.addEventListener("keydown", retry, true);
+    };
+    const tick = (): void => {
+      if (token !== this.autoplayToken) return; // left the slide
+      const video = findVideo();
+      if (video) {
+        if (!started) {
+          started = true;
+          video.muted = this._muted || video.defaultMuted;
+          try {
+            video.currentTime = 0;
+          } catch {
+            // not seekable yet — play from wherever it is
+          }
+          wireGestureRetry(video);
+        }
+        const advancing = !video.paused && video.currentTime > lastTime;
+        lastTime = video.currentTime;
+        if (!advancing) void video.play().catch(() => {});
+      }
+      waited += STEP_MS;
+      if (waited <= WINDOW_MS) window.setTimeout(tick, STEP_MS);
+    };
+    tick();
+  }
+
   private presenterNotesDeckKey(): string {
     const explicit = this.getAttribute("notes-storage-key")?.trim();
     if (explicit) return explicit;

From f8b89d04fce26ef08d7e2408662094cc22da04ed Mon Sep 17 00:00:00 2001
From: James <james.russo@heygen.com>
Date: Wed, 24 Jun 2026 21:12:28 -0400
Subject: [PATCH 2/3] refactor(slideshow): address code-review on per-slide
 autoplay

- guard playSceneDocumentMedia behind resolveMode() !== "audience": the
  audience mirrors the presenter's media events, so it must not independently
  drive its own copy of the clip.
- drop the per-enter window pointerdown/keydown "gesture retry" listeners,
  which leaked when muted autoplay succeeded without a gesture. The poll already
  re-asserts play(), so a gesture within the window is picked up next tick.
- stop polling once the clip is advancing across two ticks (was re-asserting
  play() for the full window even after playback was confirmed).
- cancel any in-flight autoplay loop on disconnectedCallback (bump the token).
- split the poll into findSceneVideo + stepAutoplay helpers (keeps each small).
- fix the enterSlide comment: autoplay fires from enterSlide (next/prev/
  goToSlide), not resumeSlide (back/backToMain/syncTo).
- parser: isOptionalBoolean type guard instead of a one-off helper; drop `as`
  assertions in the new controller test.

131 player + 22 core slideshow tests pass; lint/format/typecheck/fallow clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/core/src/slideshow/parseSlideshow.ts |   6 +-
 .../src/slideshow/SlideshowController.test.ts |   5 +-
 .../src/slideshow/SlideshowController.ts      |  11 +-
 .../src/slideshow/hyperframes-slideshow.ts    | 111 ++++++++++--------
 4 files changed, 70 insertions(+), 63 deletions(-)

diff --git a/packages/core/src/slideshow/parseSlideshow.ts b/packages/core/src/slideshow/parseSlideshow.ts
index 3159f0cf46..a05537ce50 100644
--- a/packages/core/src/slideshow/parseSlideshow.ts
+++ b/packages/core/src/slideshow/parseSlideshow.ts
@@ -48,8 +48,8 @@ function isOptionalNumberArray(v: unknown): boolean {
   return v === undefined || (Array.isArray(v) && v.every((n) => typeof n === "number"));
 }
 
-function isOptional(v: unknown, type: "boolean"): boolean {
-  return v === undefined || typeof v === type;
+function isOptionalBoolean(v: unknown): v is boolean | undefined {
+  return v === undefined || typeof v === "boolean";
 }
 
 function isSlideRef(v: unknown): v is SlideRef {
@@ -58,7 +58,7 @@ function isSlideRef(v: unknown): v is SlideRef {
   if (typeof r["sceneId"] !== "string") return false;
   if (!isOptionalNumberArray(r["fragments"])) return false;
   if (r["hotspots"] !== undefined && !Array.isArray(r["hotspots"])) return false;
-  if (!isOptional(r["autoplay"], "boolean")) return false;
+  if (!isOptionalBoolean(r["autoplay"])) return false;
   return true;
 }
 
diff --git a/packages/player/src/slideshow/SlideshowController.test.ts b/packages/player/src/slideshow/SlideshowController.test.ts
index 081a61067f..0d59c35d72 100644
--- a/packages/player/src/slideshow/SlideshowController.test.ts
+++ b/packages/player/src/slideshow/SlideshowController.test.ts
@@ -724,8 +724,7 @@ describe("SlideshowController autoplay", () => {
 
   it("does not require autoplay support on the port (optional hook)", () => {
     // A port without playSceneMedia must not throw when entering an autoplay slide.
-    const p = fakePlayer() as Record<string, unknown>;
-    delete p.playSceneMedia;
-    expect(() => new SlideshowController(p as never, AUTOPLAY_SHOW)).not.toThrow();
+    const { playSceneMedia: _omitted, ...port } = fakePlayer();
+    expect(() => new SlideshowController(port, AUTOPLAY_SHOW)).not.toThrow();
   });
 });
diff --git a/packages/player/src/slideshow/SlideshowController.ts b/packages/player/src/slideshow/SlideshowController.ts
index 626161b397..006be722d8 100644
--- a/packages/player/src/slideshow/SlideshowController.ts
+++ b/packages/player/src/slideshow/SlideshowController.ts
@@ -117,11 +117,12 @@ export class SlideshowController {
       this.frame.fragmentIndex = -1;
       this.playTo(this.restFrame(slide));
     }
-    // Opt-in: play the slide's own clip on enter. We never auto-advance — the
-    // presenter still clicks Next — this just saves a click into the (non-
-    // interactive) composition. Only on forward entry (enterSlide), not on
-    // resume/back/sync, and not on the audience (which mirrors the presenter's
-    // media events), so a clip isn't restarted under the presenter.
+    // Opt-in: play the slide's own clip on enter (saves a click into the
+    // pointer-events:none composition). We never auto-advance — the presenter
+    // still clicks Next. Fires from enterSlide (next / prev / goToSlide), NOT
+    // from resumeSlide (back / backToMain / syncTo), which restores a saved
+    // position; the component also skips it on the audience, which mirrors the
+    // presenter's media events rather than driving its own.
     if (slide.autoplay) this.player.playSceneMedia?.(slide.sceneId);
     this.emitChange();
   }
diff --git a/packages/player/src/slideshow/hyperframes-slideshow.ts b/packages/player/src/slideshow/hyperframes-slideshow.ts
index 4183224a9c..8f0ed5a58d 100644
--- a/packages/player/src/slideshow/hyperframes-slideshow.ts
+++ b/packages/player/src/slideshow/hyperframes-slideshow.ts
@@ -44,6 +44,18 @@ interface SlideNotesTarget {
 
 type SlideshowManifest = NonNullable<ReturnType<typeof parseSlideshowManifest>>;
 
+// Autoplay re-assert poll (see playSceneDocumentMedia): the player drives clips
+// during bootstrap and on enter, so a single play() loses the race; we poll
+// briefly until the clip is advancing.
+const AUTOPLAY_STEP_MS = 150;
+const AUTOPLAY_MAX_MS = 6000;
+interface AutoplayPollState {
+  started: boolean;
+  lastTime: number;
+  advancingTicks: number;
+  waited: number;
+}
+
 type PlayerElement = HTMLElement & {
   seek(t: number): void;
   play(): void;
@@ -235,6 +247,7 @@ export class HyperframesSlideshow extends HTMLElement {
   disconnectedCallback(): void {
     this.disconnected = true;
     this.initGeneration += 1;
+    this.autoplayToken++; // cancel any in-flight autoplay re-assert loop
     if (this.initTimer !== null) {
       clearTimeout(this.initTimer);
       this.initTimer = null;
@@ -1040,71 +1053,65 @@ export class HyperframesSlideshow extends HTMLElement {
    * Play the `<video>` inside a given scene from its start — the runtime side of
    * a slide's `autoplay`. Reaches into the same-origin composition iframe (which
    * is pointer-events:none, so its own controls can't be clicked). The play()
-   * fires a "play" event that wireSlideshowMedia() already mirrors to any
-   * audience window, so we only call this on the presenter (via enterSlide).
+   * fires a "play" event that wireSlideshowMedia() mirrors to any audience
+   * window, so this runs on the presenter only — the audience drives its copy
+   * from those mirrored events, never on its own.
    *
    * Robust against two timing hazards: (1) the clip may not be in the iframe DOM
    * yet at construction (first slide), and (2) the player drives clips during
    * bootstrap and seeks the timeline on enter — both pause the clip (and reject
-   * an in-flight play() with AbortError), so a single play() loses the race. We
-   * poll on a short timer: locate the clip, then assert play() until it is
-   * actually advancing, for a bounded window — then stop, so a later real user
-   * pause (presenter media controls) sticks. Token-guarded so leaving the slide
-   * cancels it. If play() is blocked for want of a gesture (real browser, first
-   * slide, no interaction yet), the first pointer/key event kicks it.
+   * an in-flight play() with AbortError), so a single play() loses the race. So
+   * we poll on a short timer: locate the clip, then assert play() until it is
+   * actually advancing across two ticks, then stop — leaving a later real user
+   * pause (presenter media controls) alone. A user gesture within the window
+   * (real browsers gate autoplay on one) lets the next tick's play() take.
+   * Token-guarded, so leaving the slide or disconnecting cancels it.
    */
   private playSceneDocumentMedia(sceneId: string): void {
+    if (this.resolveMode() === "audience") return;
     const safeId = sceneId.replace(/["\\]/g, "\\$&");
     const token = ++this.autoplayToken;
-    const findVideo = (): HTMLVideoElement | null => {
-      for (const player of this.mediaPlayerElements()) {
-        const doc = this.playerFrameDocument(player);
-        const video = doc?.querySelector(`[data-composition-id="${safeId}"] video`) ?? null;
-        if (video instanceof HTMLVideoElement) return video;
-      }
-      return null;
-    };
-    const STEP_MS = 150;
-    const WINDOW_MS = 6000;
-    let waited = 0;
-    let started = false;
-    let lastTime = -1;
-    let gestureWired = false;
-    const wireGestureRetry = (video: HTMLVideoElement): void => {
-      if (gestureWired) return;
-      gestureWired = true;
-      const retry = (): void => {
-        window.removeEventListener("pointerdown", retry, true);
-        window.removeEventListener("keydown", retry, true);
-        if (token === this.autoplayToken) void video.play().catch(() => {});
-      };
-      window.addEventListener("pointerdown", retry, true);
-      window.addEventListener("keydown", retry, true);
-    };
+    const state: AutoplayPollState = { started: false, lastTime: -1, advancingTicks: 0, waited: 0 };
     const tick = (): void => {
-      if (token !== this.autoplayToken) return; // left the slide
-      const video = findVideo();
-      if (video) {
-        if (!started) {
-          started = true;
-          video.muted = this._muted || video.defaultMuted;
-          try {
-            video.currentTime = 0;
-          } catch {
-            // not seekable yet — play from wherever it is
-          }
-          wireGestureRetry(video);
-        }
-        const advancing = !video.paused && video.currentTime > lastTime;
-        lastTime = video.currentTime;
-        if (!advancing) void video.play().catch(() => {});
-      }
-      waited += STEP_MS;
-      if (waited <= WINDOW_MS) window.setTimeout(tick, STEP_MS);
+      if (token !== this.autoplayToken) return; // left the slide / disconnected
+      const done = this.stepAutoplay(safeId, state);
+      state.waited += AUTOPLAY_STEP_MS;
+      if (!done && state.waited <= AUTOPLAY_MAX_MS) window.setTimeout(tick, AUTOPLAY_STEP_MS);
     };
     tick();
   }
 
+  /** Locate the scene's clip in the composition iframe(s). */
+  private findSceneVideo(safeId: string): HTMLVideoElement | null {
+    for (const player of this.mediaPlayerElements()) {
+      const doc = this.playerFrameDocument(player);
+      const video = doc?.querySelector(`[data-composition-id="${safeId}"] video`) ?? null;
+      if (video instanceof HTMLVideoElement) return video;
+    }
+    return null;
+  }
+
+  /** One autoplay poll step. Returns true once the clip is confirmed playing. */
+  private stepAutoplay(safeId: string, state: AutoplayPollState): boolean {
+    const video = this.findSceneVideo(safeId);
+    if (!video) return false;
+    if (!state.started) {
+      state.started = true;
+      video.muted = this._muted || video.defaultMuted;
+      try {
+        video.currentTime = 0;
+      } catch {
+        // not seekable yet — play from wherever it is
+      }
+    }
+    const advancing = !video.paused && video.currentTime > state.lastTime;
+    state.lastTime = video.currentTime;
+    if (advancing) return ++state.advancingTicks >= 2; // confirmed playing — stop polling
+    state.advancingTicks = 0;
+    void video.play().catch(() => {});
+    return false;
+  }
+
   private presenterNotesDeckKey(): string {
     const explicit = this.getAttribute("notes-storage-key")?.trim();
     if (explicit) return explicit;

From 7aefc378dcbef866a9129965dc66e40399419319 Mon Sep 17 00:00:00 2001
From: James <james.russo@heygen.com>
Date: Wed, 24 Jun 2026 23:55:52 -0400
Subject: [PATCH 3/3] docs(slideshow): autoplay skill guidance + address review
 nits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses review feedback on #1708:
- skill: document per-slide `autoplay` in the slideshow standalone-harness
  reference — when to use it (video is the slide's primary content, its end is
  the advance cue) vs not (background/ambient loops, footage talked over), per
  Vance's guidance, before merge.
- play() rejection is no longer blanket-swallowed: AbortError (timeline-sync
  seek interrupt) and NotAllowedError (gesture-gated autoplay) are expected and
  ignored; any other rejection is surfaced once via console.warn (Via nit 1).
- clarify in the SlideRef.autoplay doc that it plays the scene's FIRST <video>
  (Via nit 2).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../core/src/slideshow/slideshow.types.ts     |  5 +++--
 .../src/slideshow/hyperframes-slideshow.ts    | 20 +++++++++++++++++--
 .../references/standalone-harness.md          | 14 +++++++++++++
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/packages/core/src/slideshow/slideshow.types.ts b/packages/core/src/slideshow/slideshow.types.ts
index 59f82fceae..4d148d8156 100644
--- a/packages/core/src/slideshow/slideshow.types.ts
+++ b/packages/core/src/slideshow/slideshow.types.ts
@@ -20,10 +20,11 @@ export interface SlideRef {
   fragments?: number[];
   hotspots?: SlideHotspot[];
   /**
-   * When true, the slide's `<video>` plays automatically on enter (the
+   * When true, the slide's first `<video>` plays automatically on enter (the
    * presenter lands on the slide and the clip plays). The slideshow still holds
    * — it never auto-advances — so the presenter clicks Next when ready.
-   * Defaults to false.
+   * Defaults to false. Use it when the video is the slide's primary content and
+   * its natural end is the cue to advance, not for background/ambient clips.
    */
   autoplay?: boolean;
   // Reserved — TTS deferred. Parsed and carried, never consumed.
diff --git a/packages/player/src/slideshow/hyperframes-slideshow.ts b/packages/player/src/slideshow/hyperframes-slideshow.ts
index 8f0ed5a58d..497c46c948 100644
--- a/packages/player/src/slideshow/hyperframes-slideshow.ts
+++ b/packages/player/src/slideshow/hyperframes-slideshow.ts
@@ -54,6 +54,7 @@ interface AutoplayPollState {
   lastTime: number;
   advancingTicks: number;
   waited: number;
+  warned: boolean;
 }
 
 type PlayerElement = HTMLElement & {
@@ -1071,7 +1072,13 @@ export class HyperframesSlideshow extends HTMLElement {
     if (this.resolveMode() === "audience") return;
     const safeId = sceneId.replace(/["\\]/g, "\\$&");
     const token = ++this.autoplayToken;
-    const state: AutoplayPollState = { started: false, lastTime: -1, advancingTicks: 0, waited: 0 };
+    const state: AutoplayPollState = {
+      started: false,
+      lastTime: -1,
+      advancingTicks: 0,
+      waited: 0,
+      warned: false,
+    };
     const tick = (): void => {
       if (token !== this.autoplayToken) return; // left the slide / disconnected
       const done = this.stepAutoplay(safeId, state);
@@ -1108,7 +1115,16 @@ export class HyperframesSlideshow extends HTMLElement {
     state.lastTime = video.currentTime;
     if (advancing) return ++state.advancingTicks >= 2; // confirmed playing — stop polling
     state.advancingTicks = 0;
-    void video.play().catch(() => {});
+    void video.play().catch((err: unknown) => {
+      // Expected during the poll: AbortError (a timeline-sync seek interrupts
+      // the play) and NotAllowedError (autoplay gated on a user gesture). Surface
+      // anything else once — a real failure (bad src, decode) shouldn't be silent.
+      const name = err instanceof DOMException ? err.name : "";
+      if (name !== "AbortError" && name !== "NotAllowedError" && !state.warned) {
+        state.warned = true;
+        console.warn("[hyperframes-slideshow] autoplay play() failed:", err);
+      }
+    });
     return false;
   }
 
diff --git a/skills/slideshow/references/standalone-harness.md b/skills/slideshow/references/standalone-harness.md
index f42c8ce176..e24306cddc 100644
--- a/skills/slideshow/references/standalone-harness.md
+++ b/skills/slideshow/references/standalone-harness.md
@@ -109,6 +109,20 @@ For public or user-facing generated projects, make this wrapper the root `index.
 
 `interactive` is required for decks with clickable page content or media controls. Without it, iframe pointer events are disabled by the player shell and a click on the composition can be interpreted as a player play/pause toggle instead of a slide interaction.
 
+### Per-slide `autoplay`
+
+Add `"autoplay": true` to a slide in the island to play that slide's first `<video>` from the start when the presenter lands on it. The slideshow still holds — it never auto-advances — so the presenter clicks Next when ready; autoplay only saves a manual play click into the composition.
+
+```json
+{
+  "sceneId": "cold-open",
+  "autoplay": true,
+  "notes": "Promo plays on enter; click Next when it ends."
+}
+```
+
+Use `autoplay` when the video **is** the slide's primary content and its natural end is the cue to advance — a cold-open promo, a demo clip you let run and then move on from. Do **not** use it for background/ambient loops or for footage the presenter talks over; those should start on the presenter's own cue (a click on the clip's controls via `interactive`), not automatically. One autoplay clip per slide (the first `<video>` in the scene).
+
 ### Presenter media bridge for interactive media
 
 Presenter/audience mode syncs slide position through a deck-scoped `BroadcastChannel`. If the presenter is expected to play, pause, seek, mute, or change rate on media inside the composition, mirror those native media events over the same channel. Keep the media element as the source of truth; do not mirror a custom button's private state.