Files
hyperframes/packages/player/src/slideshow/SlideshowController.ts
James RussoandClaude Opus 4.8 7517f6ac86 feat(slideshow): per-slide autoplay (manual-advance, opt-in) (#1708)
* feat(slideshow): per-slide autoplay (manual-advance, opt-in)

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>

* 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>

* docs(slideshow): autoplay skill guidance + address review nits

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>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 12:47:54 -07:00

284 lines
10 KiB
TypeScript

import type { ResolvedSlideshow, ResolvedSlide } from "@hyperframes/core/slideshow";
export interface PlayerPort {
seek(t: number): void;
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;
}
interface StackFrame {
sequenceId: string;
slideIndex: number;
fragmentIndex: number; // -1 = before first fragment / at slide start
}
const MAIN = "main";
export class SlideshowController {
private stack: StackFrame[] = [{ sequenceId: MAIN, slideIndex: 0, fragmentIndex: -1 }];
private changeCbs = new Set<() => void>();
constructor(
private player: PlayerPort,
private show: ResolvedSlideshow,
) {
this.enterSlide(0);
}
// fallow-ignore-next-line unused-class-member
dispose(): void {
// No subscriptions to tear down — navigation is seek-driven (see playTo).
}
private slidesOf(sequenceId: string): ResolvedSlide[] {
if (sequenceId === MAIN) return this.show.slides;
return this.show.sequences[sequenceId]?.slides ?? [];
}
private get frame(): StackFrame {
return this.stack[this.stack.length - 1];
}
get currentSlide(): ResolvedSlide | undefined {
return this.slidesOf(this.frame.sequenceId)[this.frame.slideIndex];
}
get nextSlide(): ResolvedSlide | null {
const slides = this.slidesOf(this.frame.sequenceId);
const next = slides[this.frame.slideIndex + 1];
return next ?? null;
}
get position(): { sequenceId: string; slideIndex: number; fragmentIndex: number } {
return { ...this.frame };
}
get counter(): { index: number; total: number } {
return {
index: this.frame.slideIndex + 1,
total: this.slidesOf(this.frame.sequenceId).length,
};
}
get canPrev(): boolean {
// prev has a destination: an earlier slide in this sequence, OR (in a branch) the parent.
return this.frame.slideIndex > 0 || this.stack.length > 1;
}
get canNext(): boolean {
// next has a destination: a later slide in this sequence, OR (in a branch) the parent.
const slides = this.slidesOf(this.frame.sequenceId);
return this.frame.slideIndex + 1 < slides.length || this.stack.length > 1;
}
get breadcrumb(): { id: string; label: string }[] {
return this.stack.map((f) =>
f.sequenceId === MAIN
? { id: MAIN, label: "Main deck" }
: { id: f.sequenceId, label: this.show.sequences[f.sequenceId]?.label ?? f.sequenceId },
);
}
// fallow-ignore-next-line unused-class-member
onChange(cb: () => void): () => void {
this.changeCbs.add(cb);
return () => this.changeCbs.delete(cb);
}
private emitChange(): void {
for (const cb of this.changeCbs) cb();
}
private stopSlideMedia(): void {
this.player.stopMedia?.();
}
private enterSlide(index: number): void {
if (index !== this.frame.slideIndex) this.stopSlideMedia();
this.frame.slideIndex = index;
const slide = this.currentSlide;
if (!slide) {
this.frame.fragmentIndex = -1;
return;
}
// Jump to the slide's first hold and stay there (no auto-progress). With
// fragments that's the first fragment (fragmentIndex 0); without, a settled
// frame INSIDE the slide (its midpoint) — NOT slide.end, which is the boundary
// where the next scene begins (else slide 1 would render slide 2's content).
if (slide.fragments.length > 0) {
this.frame.fragmentIndex = 0;
this.playTo(slide.fragments[0] ?? slide.end);
} else {
this.frame.fragmentIndex = -1;
this.playTo(this.restFrame(slide));
}
// 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();
}
/** A representative, non-boundary frame for a slide with no fragments. */
private restFrame(slide: ResolvedSlide): number {
return slide.start + (slide.end - slide.start) * 0.5;
}
/**
* Resumes a slide at a saved fragmentIndex without resetting to slide start.
* Used by back()/backToMain()/syncTo() to restore an exact position.
*/
private resumeSlide(index: number, fragmentIndex: number): void {
this.frame.slideIndex = index;
this.frame.fragmentIndex = fragmentIndex;
const slide = this.currentSlide;
if (!slide) return;
// Resume position, mirroring enterSlide so going back to a slide lands where
// entering it forward does:
// - at a saved fragment → that fragment's hold time
// - fragmented, pre-first → slide.start (before the first reveal)
// - no fragments → restFrame (midpoint), NOT slide.start, so the
// slide is visible at rest instead of frozen at its frame-0 (pre-entrance).
const seekTime =
fragmentIndex >= 0 && fragmentIndex < slide.fragments.length
? (slide.fragments[fragmentIndex] ?? slide.start)
: slide.fragments.length > 0
? slide.start
: this.restFrame(slide);
this.playTo(seekTime);
this.emitChange();
}
/**
* Jump to hold time `t` and hold there — a pure, synchronous seek with NO
* sustained playback, so a slide can never auto-progress.
*
* `player.seek(t)` drives the composition's GSAP timeline directly (the player
* reaches the same-origin iframe's `__timelines`), and GSAP `.seek()` renders
* that frame synchronously AND leaves the timeline paused. So one seek both
* repaints and holds — deterministically, in every window including a
* backgrounded one. (The previous play-a-frame-then-pause-on-a-timeupdate
* "render nudge" left an unfocused audience window playing while it waited for
* a throttled tick to pause it — that was the auto-progress / one-side-frozen
* flakiness. fragmentIndex is now set by the caller, not on a played tick.)
*/
private playTo(t: number): void {
this.player.seek(t);
}
next(): void {
const slide = this.currentSlide;
if (!slide) return;
const hasMoreFragments = this.frame.fragmentIndex + 1 < slide.fragments.length;
if (hasMoreFragments) {
// Reveal the next fragment — advance the index and seek to its hold time.
this.frame.fragmentIndex += 1;
const target = slide.fragments[this.frame.fragmentIndex] ?? slide.end;
this.playTo(target);
this.emitChange();
return;
}
// No more fragments to reveal — advance to the next slide immediately instead of
// playing the current slide out to its end.
const slides = this.slidesOf(this.frame.sequenceId);
if (this.frame.slideIndex + 1 < slides.length) {
this.enterSlide(this.frame.slideIndex + 1);
} else if (this.stack.length > 1) {
// End of a branch → return to the parent timeline.
this.back();
}
}
prev(): void {
if (this.frame.slideIndex > 0) {
this.enterSlide(this.frame.slideIndex - 1);
return;
}
if (this.stack.length > 1) {
// First slide of a branch → return to the parent timeline.
this.back();
}
}
goToSlide(index: number): void {
const slides = this.slidesOf(this.frame.sequenceId);
if (index >= 0 && index < slides.length) this.enterSlide(index);
}
enterBranch(sequenceId: string): void {
const seq = this.show.sequences[sequenceId];
if (!seq || seq.slides.length === 0) return;
this.stopSlideMedia();
this.stack.push({ sequenceId, slideIndex: 0, fragmentIndex: -1 });
this.enterSlide(0);
}
back(): void {
if (this.stack.length <= 1) return;
this.stopSlideMedia();
this.stack.pop();
// Restore the saved fragmentIndex from the parent frame rather than
// resetting to -1 (which enterSlide would do). This preserves the exact
// position the presenter was at before entering the branch.
this.resumeSlide(this.frame.slideIndex, this.frame.fragmentIndex);
}
backToMain(): void {
if (this.stack.length <= 1) return;
this.stopSlideMedia();
this.stack = [this.stack[0]];
this.resumeSlide(this.frame.slideIndex, this.frame.fragmentIndex);
}
/**
* Jump to an absolute position without animation (audience mirroring).
* Re-roots the stack to the target sequence, then restores slide+fragment
* statically via resumeSlide.
*/
syncTo(sequenceId: string, slideIndex: number, fragmentIndex: number): void {
if (!this.isValidSyncTarget(sequenceId, slideIndex)) return;
if (this.isCrossSlide(sequenceId, slideIndex)) this.stopSlideMedia();
if (!this.rerootStackTo(sequenceId)) return;
this.resumeSlide(slideIndex, fragmentIndex);
}
/** True if the target sequence + slide index resolves to a real slide. */
private isValidSyncTarget(sequenceId: string, slideIndex: number): boolean {
if (!this.stack[0]) return false;
const targetSlides =
sequenceId === MAIN ? this.show.slides : (this.show.sequences[sequenceId]?.slides ?? null);
if (!targetSlides) return false;
return slideIndex >= 0 && slideIndex < targetSlides.length;
}
/** True if the sync target lands on a different slide than current. */
private isCrossSlide(sequenceId: string, slideIndex: number): boolean {
return this.frame.sequenceId !== sequenceId || this.frame.slideIndex !== slideIndex;
}
/**
* Re-root the navigation stack to `sequenceId` if we're not already there.
* Returns false only when the target branch sequence is empty (no slides),
* mirroring the early-return guard in the previous inline form.
*/
private rerootStackTo(sequenceId: string): boolean {
if (this.frame.sequenceId === sequenceId) return true;
const base = this.stack[0];
if (!base) return false;
this.stack = [base];
if (sequenceId === MAIN) return true;
const seq = this.show.sequences[sequenceId];
if (!seq || seq.slides.length === 0) return false;
this.stack.push({ sequenceId, slideIndex: 0, fragmentIndex: -1 });
return true;
}
}