@glissade/player 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,23 @@
+# @glissade/player
+
+The embed runtime: `Player` (play/pause/seek/loop/rate — time-based, never frame-counted), the **Driver** seam (`InputDriver<T>`: clock, scroll, or anything that writes a value), and `mount()` — scene + timeline + canvas in one call. v2 machines attach here: `player.attach(machine)` steps them on every host tick, even while linear playback is paused, with hard target-disjointness validation.
+
+```sh
+npm i @glissade/player
+```
+
+```ts
+import { mount } from '@glissade/player';
+
+const { player } = mount(scene, doc, canvas, { loop: true, autoplay: true });
+player.seek(1.5); // pure: identical to having played there
+```
+
+## Part of glissade
+
+*(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.
+
+- [Repository & full README](https://github.com/tyevco/glissade)
+- [Getting started](https://github.com/tyevco/glissade/blob/main/docs/getting-started.md) · [Concepts](https://github.com/tyevco/glissade/blob/main/docs/concepts.md) · [Interactivity](https://github.com/tyevco/glissade/blob/main/docs/interactivity.md)
+
+Apache-2.0.

package/dist/index.d.ts

@@ -10,14 +10,19 @@ import { Canvas2DBackend } from "@glissade/backend-canvas2d";
  * clock is the default Driver, not a privileged one — this seam is the v2
  * interactivity path (§2.9).
  */
-interface Driver {
-  /** Begin writing. Call write(seconds) whenever the driven value changes. */
-  start(write: (t: number) => void, ctx: DriverContext): void;
+interface InputDriver<T = number> {
+  /** Begin writing. Call write(value) whenever the driven value changes. */
+  start(write: (value: T) => void, ctx: DriverContext): void;
   stop(): void;
 }
+/** v1 alias (v2 §C.1): the playhead was always just the T = number case. */
+type Driver = InputDriver<number>;
 interface DriverContext {
-  /** Timeline duration, for normalization. */
-  duration: number;
+  /**
+   * Timeline duration — present when driving a playhead; ABSENT in input mode
+   * (machines have no duration, v2 §C.1).
+   */
+  duration?: number;
   visibility: () => 'visible' | 'hidden';
 }
 /**
@@ -55,6 +60,20 @@ interface PlayerInit {
   /** Injected clock; defaults to the rAF clockDriver. Tests pass a manual driver. */
   driver?: Driver;
   visibility?: () => 'visible' | 'hidden';
+  /** Track targets of the bound timeline — the v2 §A.1 disjointness set for attach(). */
+  targets?: Iterable<string>;
+}
+/**
+ * The structural shape of an attached machine (v2 addendum §A.5). Defined
+ * structurally so @glissade/player never imports @glissade/interact (§7.1).
+ */
+interface AttachedMachine {
+  step(now: number): void;
+  readonly targets?: ReadonlySet<string>;
+}
+/** §A.1: machine and Player track-target sets must be statically disjoint. */
+declare class TargetOverlapError extends Error {
+  constructor(overlaps: string[]);
 }
 interface Player {
   readonly playhead: Playhead;
@@ -69,6 +88,12 @@ interface Player {
   seek(t: number): void;
   /** Register a marker callback; fired only when continuous playback crosses it. */
   onMarker(name: 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.
+   * Returns detach. Throws TargetOverlapError on a non-disjoint target set.
+   */
+  attach(machine: AttachedMachine): () => void;
   dispose(): void;
 }
 declare function createPlayer(init: PlayerInit, opts?: PlayerOptions): Player;
@@ -83,4 +108,4 @@ interface Mounted {
 }
 declare function mount(scene: Scene, doc: Timeline, canvas: HTMLCanvasElement | OffscreenCanvas, opts?: PlayerOptions): Mounted;
 //#endregion
-export { type Driver, type DriverContext, type LoopMode, type Mounted, type PlayHandle, type Player, type PlayerInit, type PlayerOptions, type ScrollDriverOptions, 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 ScrollDriverOptions, TargetOverlapError, clockDriver, createPlayer, mount, scrollDriver };

package/dist/index.js

@@ -34,7 +34,7 @@ function scrollDriver(opts) {
 	const el = opts.source;
 	return {
 		start(write, ctx) {
-			const range = opts.range ?? [0, ctx.duration];
+			const range = opts.range ?? [0, ctx.duration ?? 1];
 			const progress = () => {
 				if (el instanceof Element) {
 					const max = axis === "y" ? el.scrollHeight - el.clientHeight : el.scrollWidth - el.clientWidth;
@@ -61,6 +61,13 @@ function scrollDriver(opts) {
 }
 //#endregion
 //#region src/player.ts
+/** §A.1: machine and Player track-target sets must be statically disjoint. */
+var TargetOverlapError = class extends Error {
+	constructor(overlaps) {
+		super(`machine targets overlap an already-bound target set: ${overlaps.join(", ")} — concurrent writers to one property is the silent last-writer-wins §2.2 exists to kill`);
+		this.name = "TargetOverlapError";
+	}
+};
 function createPlayer(init, opts = {}) {
 	const { playhead, duration } = init;
 	const markers = init.markers ?? [];
@@ -70,6 +77,8 @@ function createPlayer(init, opts = {}) {
 	let rate = opts.rate ?? 1;
 	let playing = false;
 	let driverRunning = false;
+	const ownTargets = new Set(init.targets ?? []);
+	const machines = [];
 	let base = 0;
 	let elapsedOrigin = null;
 	let lastElapsed = 0;
@@ -90,6 +99,7 @@ function createPlayer(init, opts = {}) {
 	}
 	function onElapsed(elapsed) {
 		lastElapsed = elapsed;
+		for (const m of machines) m.step(elapsed);
 		if (!playing) return;
 		elapsedOrigin ??= elapsed;
 		const prev = playhead.peek();
@@ -170,6 +180,20 @@ function createPlayer(init, opts = {}) {
 			elapsedOrigin = playing ? lastElapsed : null;
 			playhead.set(base);
 		},
+		attach(machine) {
+			if (machine.targets) {
+				const overlaps = [];
+				for (const t of machine.targets) if (ownTargets.has(t)) overlaps.push(`'${t}' (player timeline)`);
+				else if (machines.some((m) => m.targets?.has(t))) overlaps.push(`'${t}' (another machine)`);
+				if (overlaps.length > 0) throw new TargetOverlapError(overlaps);
+			}
+			machines.push(machine);
+			ensureDriver();
+			return () => {
+				const i = machines.indexOf(machine);
+				if (i >= 0) machines.splice(i, 1);
+			};
+		},
 		onMarker(name, cb) {
 			let set = callbacks.get(name);
 			if (!set) {
@@ -181,6 +205,7 @@ function createPlayer(init, opts = {}) {
 		},
 		dispose() {
 			if (playing) settle(false);
+			machines.length = 0;
 			if (driverRunning) driver.stop();
 			driverRunning = false;
 		}
@@ -200,7 +225,8 @@ function mount(scene, doc, canvas, opts = {}) {
 	const player = createPlayer({
 		playhead: scene.playhead,
 		duration: compiled.duration,
-		markers: compiled.markers
+		markers: compiled.markers,
+		targets: compiled.tracks.keys()
 	}, opts);
 	const renderNow = () => backend.render(evaluate(scene, doc, scene.playhead.peek()));
 	let scheduled = false;
@@ -233,4 +259,4 @@ function mount(scene, doc, canvas, opts = {}) {
 	};
 }
 //#endregion
-export { clockDriver, createPlayer, mount, scrollDriver };
+export { TargetOverlapError, clockDriver, createPlayer, mount, scrollDriver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/player",
-  "version": "0.1.0",
+  "version": "0.3.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.1.0",
-    "@glissade/core": "0.1.0",
-    "@glissade/scene": "0.1.0"
+    "@glissade/core": "0.3.0",
+    "@glissade/backend-canvas2d": "0.3.0",
+    "@glissade/scene": "0.3.0"
   },
   "repository": {
     "type": "git",