feat(player): <hyperframes-slideshow> web component + presenter

Stack-split from the original ss-player PR (#1581): the <hyperframes-slideshow>
custom element (wraps <hyperframes-player>, drives the controller),
presenter/audience BroadcastChannel sync, nav chrome, and the player scenes hook.

Author: vanceingalls

packages/player/src/hyperframes-player.ts

@@ -89,6 +89,7 @@ class HyperframesPlayer extends HTMLElement {
   private _directTimelineClock: DirectTimelineClock;
   private _parentTickRaf: number | null = null;
   private _media: ParentMediaManager;
+  private _scenes: { id: string; start: number; duration: number }[] = [];
 
   constructor() {
     super();
@@ -261,6 +262,12 @@ class HyperframesPlayer extends HTMLElement {
     return this.iframe;
   }
 
+  /** Scene list from the last-received runtime timeline message. Empty until
+   *  the composition runtime fires its first "timeline" postMessage. */
+  get scenes(): { id: string; start: number; duration: number }[] {
+    return this._scenes;
+  }
+
   play() {
     this.posterEl?.remove();
     this.posterEl = null;
@@ -586,6 +593,9 @@ class HyperframesPlayer extends HTMLElement {
       sendControl: (action, extra) => this._sendControl(action, extra),
       getIframeDoc: () => this.iframe.contentDocument,
       onRuntimeReady: () => this._replayBridgeState(),
+      setScenes: (scenes) => {
+        this._scenes = scenes;
+      },
       updateControlsTime: (t, d) => this.controlsApi?.updateTime(t, d),
       updateControlsPlaying: (p) => this.controlsApi?.updatePlaying(p),
       dispatchEvent: (ev) => this.dispatchEvent(ev),

packages/player/src/runtime-message-handler.test.ts

@@ -18,6 +18,7 @@ const makeCallbacks = (): MessageHandlerCallbacks => ({
   media: { mirrorTime: vi.fn(), promoteToParentProxy: vi.fn() } as unknown as ParentMediaManager,
   getPlaybackState: vi.fn(() => ({ currentTime: 0, duration: 0, paused: true, lastUpdateMs: 0 })),
   setPlaybackState: vi.fn(),
+  setScenes: vi.fn(),
   getShaderLoadingMode: vi.fn(() => "auto"),
   shaderLoader: { update: vi.fn() } as unknown as ShaderLoaderState,
   setCompositionSize: vi.fn(),

packages/player/src/runtime-message-handler.ts

@@ -15,6 +15,16 @@ import type { ShaderTransitionState } from "./shader-options.js";
 
 const FPS = 30;
 
+type SceneRecord = { id: string; start: number; duration: number };
+
+function extractScenes(raw: unknown): SceneRecord[] {
+  if (!Array.isArray(raw)) return [];
+  return (raw as SceneRecord[]).filter(
+    (s) =>
+      typeof s.id === "string" && typeof s.start === "number" && typeof s.duration === "number",
+  );
+}
+
 export interface MessageHandlerCallbacks extends PlaybackStateCallbacks {
   getPlaybackState: () => PlaybackState;
   setPlaybackState: (next: PlaybackState) => void;
@@ -27,8 +37,11 @@ export interface MessageHandlerCallbacks extends PlaybackStateCallbacks {
    *  uses it to replay current bridge state (mute, volume, playback rate) so
    *  control messages sent before the iframe's listener registered aren't lost. */
   onRuntimeReady: () => void;
+  /** Called with the scene list whenever a "timeline" message is received. */
+  setScenes: (scenes: SceneRecord[]) => void;
 }
 
+// fallow-ignore-next-line complexity
 export function handleRuntimeMessage(
   event: MessageEvent,
   frameWindow: Window | null,
@@ -90,6 +103,7 @@ export function handleRuntimeMessage(
       callbacks.setPlaybackState({ ...pb, duration });
       callbacks.updateControlsTime(pb.currentTime, duration);
     }
+    callbacks.setScenes(extractScenes(data["scenes"]));
     return;
   }