@cyberart-io/engine 0.0.1 → 0.0.3

package/docs/presentation-cue.md

@@ -0,0 +1,82 @@
+# Presentation cue / timeline
+
+Deterministic cue/effect primitive. Carts call `step(frames)` with the same clock they use for CYB-23; there are no `setTimeout` / rAF timers. Gold checkmarks, ripples, room transitions, weather pulses, and NPC beats should share this lifecycle instead of ad-hoc frame counters.
+
+Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md), [events](events.md) (routed contracts vs local `cue.*` names).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-58-presentation-cue.repro.spec.ts
+```
+
+## `createPresentationTimeline(options?)`
+
+```ts
+import {
+  createPresentationTimeline,
+  CUE_STARTED_EVENT,
+  CUE_COMPLETED_EVENT,
+  CUE_CANCELLED_EVENT,
+  CUE_REPLACED_EVENT,
+} from '@cyberart-io/engine';
+
+const timeline = createPresentationTimeline({
+  originFrame: 0,
+  reducedMotion: false, // host flag, not a CSS media query
+});
+
+timeline.play({
+  name: 'checkmark',
+  idempotencyKey: 'gold',
+  durationFrames: 90,
+  delayFrames: 0,
+  easing: 'ease-out', // or 'linear'
+  repeat: { count: 0 },
+  reducedMotion: 'complete', // 'skip' | 'complete' | { durationFrames: n }
+  onDuplicate: 'replace', // 'ignore' | 'replace' | 'reject'
+});
+
+timeline.step(90);
+```
+
+| Member | Meaning |
+|---|---|
+| `play(spec)` | Schedule or start a cue. `{ ok: true, cue }` or `{ ok: false, reason: 'duplicate' \| 'invalid' }`. |
+| `step(frames?)` | Advance the frame index (default 1). Returns lifecycle events emitted during those frames. |
+| `cancel(key)` | Cancel an active/scheduled cue (`cue.cancelled`). |
+| `reset()` | Cancel remaining cues, drop dedupe, rewind to `originFrame`, clear the event log. |
+| `snapshot()` | JSON-serializable `{ frame, reducedMotion, cues, events }`. |
+| `get(key)` | Copy of the live cue, or `undefined`. |
+
+`startFrame` defaults to the play frame. If `play` happens after `startFrame + delayFrames`, the timeline catches up on that call: mid-cue progress is applied, and a cue whose duration is already over completes immediately (`cue.started` then `cue.completed`). Progress is `0…1` after easing. `step` ignores non-finite counts (no infinite loop). Two identical `play` / `step` tapes produce identical snapshots.
+
+## Duplicate policy
+
+Keyed by `idempotencyKey` among scheduled and active cues.
+
+| `onDuplicate` | Effect |
+|---|---|
+| `replace` (default) | Emit `cue.replaced` for the old cue, start the new spec. |
+| `ignore` | Keep the existing cue. |
+| `reject` | `{ ok: false, reason: 'duplicate' }`. Unrelated cues keep running. |
+
+## Reduced motion
+
+Pass `reducedMotion: true` on the timeline (host-owned). Per-cue `reducedMotion`:
+
+- `complete` / `skip` — duration 0; `cue.started` then `cue.completed` at the play frame
+- `{ durationFrames: n }` — use `n` instead of the authored duration
+
+## Lifecycle events (stable names)
+
+| `type` | When |
+|---|---|
+| `cue.started` | Cue becomes active |
+| `cue.completed` | Duration elapsed (or reduced-motion complete) |
+| `cue.cancelled` | `cancel` or `reset` |
+| `cue.replaced` | Duplicate with `replace` |
+
+Each event: `{ type, atFrame, name, idempotencyKey, progress }`. Repeat `{ count: n }` restarts immediately after complete (`repeatIndex` increments). `{ forever: true }` with `durationFrames: 0` completes once (no infinite loop).
+
+Do not `await` wall-clock time inside cart `update` / `render`. Drive the timeline from `cart.step` / `getClock().framesElapsed`.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.1",
-  "description": "Embeddable CyberArt host engine: mount a cart, pause, snapshot, and save/load state.",
+  "version": "0.0.3",
+  "description": "CyberArt host engine: mount a cart, assets, events, deterministic cues, and a Node/jsdom headless entry.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "files": [
     "dist/index.js",
-    "dist/index.d.ts"
+    "dist/index.d.ts",
+    "dist/headless.js",
+    "dist/headless.d.ts",
+    "docs"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -15,6 +18,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./headless": {
+      "types": "./dist/headless.d.ts",
+      "import": "./dist/headless.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "headless": ["./dist/headless.d.ts"]
     }
   },
   "sideEffects": false,