@glissade/player 0.7.0-pre.0 → 0.8.0-pre.0

package/dist/index.d.ts

@@ -39,6 +39,20 @@ interface ScrollDriverOptions {
 /** User-controlled scalar: scroll progress 0..1 → t. Writes the playhead directly. */
 declare function scrollDriver(opts: ScrollDriverOptions): Driver;
 //#endregion
+//#region src/reducedMotion.d.ts
+type ReducedMotionMode = 'respect' | 'ignore' | ((doc: Timeline) => Timeline);
+interface ReducedMotionPlan {
+  /** Whether to autoplay after applying the plan. */
+  autoplay: boolean;
+  /** Seek the playhead here before first paint (the poster frame). */
+  seekTo?: number;
+  /** Replace the bound timeline with this calmer alternative (the fn form). */
+  swapTo?: Timeline;
+}
+declare function planReducedMotion(mode: ReducedMotionMode | undefined, prefersReduced: boolean, doc: Timeline, duration: number, autoplayRequested: boolean): ReducedMotionPlan;
+/** Live `prefers-reduced-motion: reduce` reading; false off-DOM. */
+declare function mediaPrefersReducedMotion(): boolean;
+//#endregion
 //#region src/player.d.ts
 type LoopMode = boolean | {
   mode: 'restart' | 'alternate';
@@ -48,6 +62,20 @@ interface PlayerOptions {
   loop?: LoopMode;
   rate?: number;
   autoplay?: boolean;
+  /**
+   * What playback does while the tab is hidden (§4.1, via the driver's
+   * `visibility`). `'pause'` (default) freezes and resumes where it left off —
+   * no wall-clock jump on return; `'run'` advances by the hidden duration.
+   */
+  background?: 'pause' | 'run';
+  /**
+   * prefers-reduced-motion policy (applied by mount(), §4.2). `'respect'`
+   * (default) holds the poster frame and suppresses autoplay; `'ignore'` opts
+   * out; a function returns a calmer alternative timeline.
+   */
+  reducedMotion?: ReducedMotionMode;
+  /** Override reduced-motion detection (defaults to the media query). */
+  prefersReducedMotion?: () => boolean;
 }
 interface PlayHandle {
   /** true = completed naturally, false = interrupted. Completion signal ONLY (§2). */
@@ -86,8 +114,21 @@ interface Player {
   pause(): void;
   /** Direct playhead write: pure, never fires marker callbacks (§4.2). */
   seek(t: number): void;
+  /**
+   * Rebind to a recompiled timeline (HMR, §4.3): swap duration/markers/targets
+   * in place and **preserve the current playhead** (clamped to the new
+   * duration) — no replay-to-frame. Playing state and registered marker/cue
+   * callbacks survive; range resets to the new full span.
+   */
+  swap(next: {
+    duration: number;
+    markers?: Marker[];
+    targets?: Iterable<string>;
+  }): void;
   /** Register a marker callback; fired only when continuous playback crosses it. */
   onMarker(name: string, cb: (marker: Marker) => void): () => void;
+  /** Like onMarker but matches a cue's `data.kind` (e.g. 'ad-break') across all names. */
+  onCue(kind: string, cb: (marker: Marker) => void): () => void;
   /**
    * Wire a machine to the host clock (v2 §A.5): step(now) on every tick, in
    * attach order, before evaluation — even while linear playback is paused.
@@ -104,8 +145,31 @@ interface Mounted {
   backend: Canvas2DBackend;
   /** Force a synchronous render of the current playhead time. */
   render(): void;
+  /**
+   * Hot-swap the bound scene and/or timeline (HMR, §4.3) while preserving the
+   * playhead: recompiles, rebinds the player (duration/markers/targets), and
+   * re-renders at the current time. A scene node a track targeted but the new
+   * scene no longer has simply stops being written (stale binding) — it keeps
+   * its last value rather than erroring.
+   */
+  swap(next: {
+    scene?: Scene;
+    timeline: Timeline;
+  }): void;
   dispose(): void;
 }
-declare function mount(scene: Scene, doc: Timeline, canvas: HTMLCanvasElement | OffscreenCanvas, opts?: PlayerOptions): Mounted;
+declare function mount(initialScene: Scene, initialDoc: Timeline, canvas: HTMLCanvasElement | OffscreenCanvas, opts?: PlayerOptions): Mounted;
+//#endregion
+//#region src/hmr.d.ts
+interface SceneModuleShape {
+  scene?: Scene;
+  timeline: Timeline;
+}
+/**
+ * Build the `import.meta.hot.accept` callback that hot-swaps `mounted` from a
+ * re-evaluated scene module. `rerun` maps the updated module namespace to the
+ * fresh `{ scene?, timeline }`.
+ */
+declare function swapOnHmr(mounted: Mounted, initialTimeline: Timeline, rerun: (mod: Record<string, unknown>) => SceneModuleShape): (mod: Record<string, unknown> | undefined) => void;
 //#endregion
-export { type AttachedMachine, type Driver, type DriverContext, type InputDriver, type LoopMode, type Mounted, type PlayHandle, type Player, type PlayerInit, type PlayerOptions, type ScrollDriverOptions, TargetOverlapError, clockDriver, createPlayer, mount, scrollDriver };
+export { type AttachedMachine, type Driver, type DriverContext, type InputDriver, type LoopMode, type Mounted, type PlayHandle, type Player, type PlayerInit, type PlayerOptions, type ReducedMotionMode, type ReducedMotionPlan, type SceneModuleShape, type ScrollDriverOptions, TargetOverlapError, clockDriver, createPlayer, mediaPrefersReducedMotion, mount, planReducedMotion, scrollDriver, swapOnHmr };

package/dist/index.js

@@ -69,26 +69,35 @@ var TargetOverlapError = class extends Error {
 	}
 };
 function createPlayer(init, opts = {}) {
-	const { playhead, duration } = init;
-	const markers = init.markers ?? [];
+	const { playhead } = init;
+	let liveDuration = init.duration;
+	let markers = init.markers ?? [];
 	const driver = init.driver ?? clockDriver();
 	const loop = opts.loop ?? false;
+	const background = opts.background ?? "pause";
+	const visibility = init.visibility ?? (() => "visible");
 	const callbacks = /* @__PURE__ */ new Map();
+	const cueCallbacks = /* @__PURE__ */ new Map();
 	let rate = opts.rate ?? 1;
 	let playing = false;
 	let driverRunning = false;
-	const ownTargets = new Set(init.targets ?? []);
+	let ownTargets = new Set(init.targets ?? []);
 	const machines = [];
 	let base = 0;
 	let elapsedOrigin = null;
 	let lastElapsed = 0;
-	let range = [0, duration];
+	let range = [0, liveDuration];
 	let loopsDone = 0;
 	let resolveFinished = null;
 	function fireMarkers(from, to) {
-		if (from === to || callbacks.size === 0) return;
+		if (from === to || callbacks.size === 0 && cueCallbacks.size === 0) return;
 		const forward = to > from;
-		for (const m of markers) if (forward ? m.t > from && m.t <= to : m.t >= to && m.t < from) for (const cb of callbacks.get(m.name) ?? []) cb(m);
+		for (const m of markers) {
+			if (!(forward ? m.t > from && m.t <= to : m.t >= to && m.t < from)) continue;
+			for (const cb of callbacks.get(m.name) ?? []) cb(m);
+			const kind = m.data?.kind;
+			if (typeof kind === "string") for (const cb of cueCallbacks.get(kind) ?? []) cb(m);
+		}
 	}
 	function settle(completed) {
 		playing = false;
@@ -101,6 +110,11 @@ function createPlayer(init, opts = {}) {
 		lastElapsed = elapsed;
 		for (const m of machines) m.step(elapsed);
 		if (!playing) return;
+		if (background === "pause" && visibility() === "hidden") {
+			base = playhead.peek();
+			elapsedOrigin = null;
+			return;
+		}
 		elapsedOrigin ??= elapsed;
 		const prev = playhead.peek();
 		let t = base + (elapsed - elapsedOrigin) * rate;
@@ -137,13 +151,15 @@ function createPlayer(init, opts = {}) {
 		if (driverRunning) return;
 		driverRunning = true;
 		driver.start(onElapsed, {
-			duration,
-			visibility: init.visibility ?? (() => "visible")
+			duration: liveDuration,
+			visibility
 		});
 	}
 	return {
 		playhead,
-		duration,
+		get duration() {
+			return liveDuration;
+		},
 		get playing() {
 			return playing;
 		},
@@ -157,7 +173,7 @@ function createPlayer(init, opts = {}) {
 		},
 		play(playOpts) {
 			if (resolveFinished) settle(false);
-			range = playOpts?.range ?? [0, duration];
+			range = playOpts?.range ?? [0, liveDuration];
 			const t = playhead.peek();
 			const [lo, hi] = range;
 			base = rate >= 0 ? t >= hi || t < lo ? lo : t : t <= lo || t > hi ? hi : t;
@@ -176,10 +192,21 @@ function createPlayer(init, opts = {}) {
 			settle(false);
 		},
 		seek(t) {
-			base = Math.min(Math.max(t, 0), duration);
+			base = Math.min(Math.max(t, 0), liveDuration);
 			elapsedOrigin = playing ? lastElapsed : null;
 			playhead.set(base);
 		},
+		swap(next) {
+			liveDuration = next.duration;
+			markers = next.markers ?? [];
+			ownTargets = new Set(next.targets ?? []);
+			const t = Math.min(playhead.peek(), liveDuration);
+			range = [0, liveDuration];
+			base = t;
+			elapsedOrigin = playing ? lastElapsed : null;
+			loopsDone = 0;
+			playhead.set(t);
+		},
 		attach(machine) {
 			if (machine.targets) {
 				const overlaps = [];
@@ -203,6 +230,15 @@ function createPlayer(init, opts = {}) {
 			set.add(cb);
 			return () => set.delete(cb);
 		},
+		onCue(kind, cb) {
+			let set = cueCallbacks.get(kind);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				cueCallbacks.set(kind, set);
+			}
+			set.add(cb);
+			return () => set.delete(cb);
+		},
 		dispose() {
 			if (playing) settle(false);
 			machines.length = 0;
@@ -212,23 +248,44 @@ function createPlayer(init, opts = {}) {
 	};
 }
 //#endregion
+//#region src/reducedMotion.ts
+function planReducedMotion(mode, prefersReduced, doc, duration, autoplayRequested) {
+	const m = mode ?? "respect";
+	if (m === "ignore" || !prefersReduced) return { autoplay: autoplayRequested };
+	if (typeof m === "function") return {
+		autoplay: autoplayRequested,
+		swapTo: m(doc)
+	};
+	return {
+		autoplay: false,
+		seekTo: doc.posterTime ?? duration
+	};
+}
+/** Live `prefers-reduced-motion: reduce` reading; false off-DOM. */
+function mediaPrefersReducedMotion() {
+	return typeof matchMedia !== "undefined" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+//#endregion
 //#region src/mount.ts
 /**
 * mount() — the vanilla embedding primitive (DESIGN.md §4.3): wire a scene +
 * timeline + canvas into a rendering Player. Rendering is pulled: a playhead
 * invalidation schedules one rAF-coalesced render.
 */
-function mount(scene, doc, canvas, opts = {}) {
+function mount(initialScene, initialDoc, canvas, opts = {}) {
+	let scene = initialScene;
+	let doc = initialDoc;
 	const compiled = compileTimeline(doc);
 	const backend = new Canvas2DBackend(canvas);
 	scene.setTextMeasurer(backend);
+	const playhead = scene.playhead;
 	const player = createPlayer({
-		playhead: scene.playhead,
+		playhead,
 		duration: compiled.duration,
 		markers: compiled.markers,
 		targets: compiled.tracks.keys()
 	}, opts);
-	const renderNow = () => backend.render(evaluate(scene, doc, scene.playhead.peek()));
+	const renderNow = () => backend.render(evaluate(scene, doc, playhead.peek()));
 	let scheduled = false;
 	const schedule = () => {
 		if (scheduled) return;
@@ -238,19 +295,51 @@ function mount(scene, doc, canvas, opts = {}) {
 			renderNow();
 		});
 	};
-	const unsubscribe = scene.playhead.subscribe(schedule);
-	if (typeof FontFace !== "undefined") for (const [family, ref] of Object.entries(doc.assets ?? {})) {
-		if (ref.kind !== "font") continue;
-		const face = new FontFace(family, `url(${ref.url})`);
-		document.fonts.add(face);
-		face.load().then(() => renderNow(), () => void 0);
+	const unsubscribe = playhead.subscribe(schedule);
+	const loadFonts = (forDoc) => {
+		if (typeof FontFace === "undefined") return;
+		for (const [family, ref] of Object.entries(forDoc.assets ?? {})) {
+			if (ref.kind !== "font") continue;
+			const face = new FontFace(family, `url(${ref.url})`);
+			document.fonts.add(face);
+			face.load().then(() => renderNow(), () => void 0);
+		}
+	};
+	loadFonts(doc);
+	const prefersReduced = (opts.prefersReducedMotion ?? mediaPrefersReducedMotion)();
+	const plan = planReducedMotion(opts.reducedMotion, prefersReduced, doc, compiled.duration, !!opts.autoplay);
+	if (plan.swapTo) {
+		doc = plan.swapTo;
+		const recompiled = compileTimeline(doc);
+		player.swap({
+			duration: recompiled.duration,
+			markers: recompiled.markers,
+			targets: recompiled.tracks.keys()
+		});
+		loadFonts(doc);
 	}
+	if (plan.seekTo !== void 0) player.seek(plan.seekTo);
 	renderNow();
-	if (opts.autoplay) player.play();
+	if (plan.autoplay) player.play();
 	return {
 		player,
 		backend,
 		render: renderNow,
+		swap(next) {
+			if (next.scene) {
+				scene = next.scene;
+				scene.setTextMeasurer(backend);
+			}
+			doc = next.timeline;
+			const recompiled = compileTimeline(doc);
+			player.swap({
+				duration: recompiled.duration,
+				markers: recompiled.markers,
+				targets: recompiled.tracks.keys()
+			});
+			loadFonts(doc);
+			renderNow();
+		},
 		dispose() {
 			unsubscribe();
 			player.dispose();
@@ -259,4 +348,40 @@ function mount(scene, doc, canvas, opts = {}) {
 	};
 }
 //#endregion
-export { TargetOverlapError, clockDriver, createPlayer, mount, scrollDriver };
+//#region src/hmr.ts
+/**
+* Vite HMR glue for a mounted embed (DESIGN.md §4.3). When the scene module is
+* edited, the dev server hands us the re-evaluated module; we hot-swap the live
+* Mounted without losing the playhead (see Mounted.swap / Player.swap). The
+* consumer owns the dependency path (only they know it), so this returns the
+* accept callback rather than calling `import.meta.hot.accept` itself:
+*
+*   import * as sceneMod from './hero.scene';
+*   const mounted = mount(sceneMod.createScene(), sceneMod.timeline, canvas);
+*   import.meta.hot?.accept(
+*     './hero.scene',
+*     swapOnHmr(mounted, sceneMod.timeline, (m) => ({ scene: m.createScene(), timeline: m.timeline })),
+*   );
+*
+* It also warns when an edit removes a label the previous timeline declared —
+* code that seeks to that label (`play({ range: [labels.x, …] })`) would break.
+*/
+/**
+* Build the `import.meta.hot.accept` callback that hot-swaps `mounted` from a
+* re-evaluated scene module. `rerun` maps the updated module namespace to the
+* fresh `{ scene?, timeline }`.
+*/
+function swapOnHmr(mounted, initialTimeline, rerun) {
+	let prevLabels = Object.keys(compileTimeline(initialTimeline).labels);
+	return (mod) => {
+		if (mod == null) return;
+		const next = rerun(mod);
+		const nextLabels = Object.keys(compileTimeline(next.timeline).labels);
+		const dropped = prevLabels.filter((l) => !nextLabels.includes(l));
+		if (dropped.length > 0) console.warn(`[glissade] HMR: this edit removed label(s) ${dropped.map((l) => `'${l}'`).join(", ")} — anything seeking to them will no longer resolve`);
+		prevLabels = nextLabels;
+		mounted.swap(next);
+	};
+}
+//#endregion
+export { TargetOverlapError, clockDriver, createPlayer, mediaPrefersReducedMotion, mount, planReducedMotion, scrollDriver, swapOnHmr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/player",
-  "version": "0.7.0-pre.0",
+  "version": "0.8.0-pre.0",
   "description": "glissade embed runtime: Player, Drivers (clock, scroll), mount().",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,9 +15,9 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/backend-canvas2d": "0.7.0-pre.0",
-    "@glissade/core": "0.7.0-pre.0",
-    "@glissade/scene": "0.7.0-pre.0"
+    "@glissade/backend-canvas2d": "0.8.0-pre.0",
+    "@glissade/core": "0.8.0-pre.0",
+    "@glissade/scene": "0.8.0-pre.0"
   },
   "repository": {
     "type": "git",