@cyberart-io/engine 0.0.2 → 0.0.3

package/docs/events.md

@@ -1,9 +1,15 @@
 # Events and router
 
-Mailbox (one runtime) and `createEventRouter` (many carts). Carts never receive the router object or another cart’s `HostChannel`. Related: [deterministic mode](deterministic-mode.md) (`now` / `createId` / `turn` per `step`).
+Mailbox (one runtime) and `createEventRouter` (many carts). Carts never receive the router object or another cart’s `HostChannel`. Related: [deterministic mode](deterministic-mode.md) (`now` / `createId` / `turn` per `step`), [presentation adapter](presentation-adapter.md) (`presentation.state.model`), [presentation cue](presentation-cue.md) (frame-local lifecycle, not routed unless you define a contract).
 
 Back to the [package README](../README.md).
 
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-59-event-contract.repro.spec.ts
+```
+
 ## When to use which
 
 | Path | Use |
@@ -11,14 +17,14 @@ Back to the [package README](../README.md).
 | Mailbox only | One cart, host `dispatch` / cart `emit`. No permissions, hops, or loop checks. |
 | Router | Several carts, host reducer in the middle, Adventure-style intent vs state. |
 
-`createRuntime` does **not** attach a router. You attach each cart’s channel yourself.
+`createRuntime` does **not** attach a router. Attach `runtime.hostChannel` yourself. Cart unload clears the inbound queue only; router listeners stay until `runtime.destroy()`. If the channel is attached to a router, use `router.subscribe` for host logic — a second `mount({ onEvent })` will see every cart emit twice.
 
 ## Mailbox (`HostChannel`)
 
 ```ts
 import { HostChannel, type HostEvent } from '@cyberart-io/engine';
 
-// Usually you do not construct this. createRuntime owns one; mount({ onEvent }) listens.
+// createRuntime owns one: `runtime.hostChannel`. mount({ onEvent }) also listens.
 cart.dispatch({ type: 'art-project.theme', payload: 'dusk' }); // host → cart
 hostChannel.consume(); // cart drains inbound (typically in update)
 hostChannel.emit({ type: 'art-project.theme', payload: 'dusk' }); // cart → host
@@ -32,7 +38,9 @@ hostChannel.emit({ type: 'art-project.theme', payload: 'dusk' }); // cart → ho
 | `consume()` | Return and clear the inbound batch. Empty array if none. |
 | `emit(event)` | Notify `onEvent` listeners (host and, if attached, the router). |
 | `onEvent(listener)` | Subscribe. Returns an unsubscribe function. |
-| `clear()` | Drop inbound queue and listeners. |
+| `clearInbound()` | Drop the inbound queue. Listeners stay (cart unload). |
+| `clear()` | Drop inbound queue and listeners (runtime teardown). |
+| `close()` | Permanent. Further dispatch / emit / consume / onEvent throw. `runtime.destroy()` calls this. |
 
 Carts that never mention `hostChannel` ignore both directions. Guard it: the argument is undefined when the cart is not mounted through `createRuntime`.
 
@@ -58,15 +66,73 @@ Routed events are normalized to `EventEnvelope` (`EVENT_ENVELOPE_VERSION = 1`).
 `kind` on the input wins. Otherwise:
 
 - `cyberart.state.save` / `cyberart.state.load` are **intents** (historical names).
-- Else the second dotted segment of `type` if it is `intent`, `state`, or `diagnostic`.
-- Else `malformed` (`cannot infer kind`).
+- Else the first dotted segment of `type` that is `intent`, `state`, or `diagnostic` (not necessarily the second segment — `adventure.presentation.intent.cue-started` is an intent).
+- Else `malformed` (`cannot infer kind`). `adventure.presentation.cue.started` does not infer a kind; define it with `defineIntent` / `defineStateEvent` / `defineDiagnostic` so the kind is in the name.
 
 Only the host (`publish`) or an `authoritative` participant may emit `state` / `diagnostic`. Carts emit allowed `intent` patterns. Domain data belongs in `payload`.
 
+## Typed contracts
+
+Define each routed type once. That object is the TypeScript payload shape (`InferredPayload`), the runtime validator, the router permission source, and the JSON manifest row.
+
+```ts
+import {
+  defineIntent,
+  defineStateEvent,
+  createContractRegistry,
+  deriveAttachOptions,
+  createEventRouter,
+} from '@cyberart-io/engine';
+
+const exit = defineIntent('adventure.intent.exit-requested', {
+  version: 1,
+  fields: { exitId: { type: 'string' } },
+});
+const room = defineStateEvent('adventure.state.room-changed', {
+  version: 1,
+  fields: { roomId: { type: 'string' } },
+});
+if (!exit.ok || !room.ok) {
+  // structured errors — these helpers do not throw
+}
+const contracts = [exit.contract, room.contract];
+const registry = createContractRegistry(contracts);
+const router = createEventRouter({ validate: registry.asRouterValidate });
+router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
+```
+
+`adventure.presentation.cue.started` has no `intent` / `state` / `diagnostic` segment, so `inferEventKind` returns undefined and `defineIntent` returns `{ ok: false, errors }` with `kind-mismatch`. Use `adventure.presentation.intent.cue-started` (kind anywhere after the namespace, not only the second segment). Cue timeline names (`cue.started`, …) are **not** routed envelopes until you wrap them in a contract.
+
+| Helper | Kind stamped | Name rule |
+|---|---|---|
+| `defineIntent(type, schema)` | `intent` | `type` must contain an `intent` dotted segment |
+| `defineStateEvent(type, schema)` | `state` | `type` must contain a `state` dotted segment |
+| `defineDiagnostic(type, schema)` | `diagnostic` | `type` must contain a `diagnostic` dotted segment |
+
+`schema` is `{ version: integer >= 1, fields: { name: { type: 'string' \| 'number' \| 'boolean' \| 'object' \| 'array', optional?: true } } }`. Extra payload keys are allowed. Missing required fields and wrong JSON types return `{ ok: false, errors: ContractDiagnostic[] }` (`code`, `detail`, optional `path`). Invalid definitions return the same shape; they never throw.
+
+| Export | Role |
+|---|---|
+| `createContractRegistry(contracts)` | `get`, `manifest()` (JSON-serializable), `validateEnvelope`, `asRouterValidate` (safe to pass as `EventRouterOptions.validate`; does not rely on `this`) |
+| `deriveAttachOptions(contracts, 'cart' \| 'authoritative')` | Cart: emit intent family patterns only. Authoritative: emit every contract family. Subscribe to non-intent families. |
+| `verifyAttachOptions(options, contracts)` | `{ ok: true }` or unauthorized-emit errors when a non-authoritative attach can emit a `state` / `diagnostic` contract |
+| `comparePayloadSchemas(from, to)` | `'identical'` / `'backward-compatible'` / `'breaking'` |
+| `kindSegmentInType(type)` / `familyPatternForType(type)` | First kind segment; last-segment `*` glob (`adventure.presentation.intent.*`) |
+
+Default router `emit: ['*.intent.*']` is **three** segments. Four-segment names such as `adventure.presentation.intent.cue-started` need `deriveAttachOptions` (or an explicit four-segment pattern). Duplicate `type`s in a registry last-win.
+
+### Payload versioning (`comparePayloadSchemas`)
+
+| Change | Result |
+|---|---|
+| Same version, same fields | `identical` |
+| Version bump, only new **optional** fields (or unchanged fields) | `backward-compatible` |
+| Removed field, type change, optional → required, version downgrade, optional add **without** a version bump | `breaking` |
+
 ## `createEventRouter(options?)`
 
 ```ts
-import { createEventRouter, HostChannel } from '@cyberart-io/engine';
+import { createEventRouter } from '@cyberart-io/engine';
 
 const router = createEventRouter({
   now: () => cart.getClock().now,
@@ -74,7 +140,7 @@ const router = createEventRouter({
   validate: (event) => true, // or { reason: 'host-rejected', detail: '…' }
 });
 
-router.attach('presentation', presentationChannel, {
+router.attach('presentation', runtime.hostChannel, {
   emit: ['adventure.intent.*'],
   subscribe: ['adventure.state.*', 'cyberart.diagnostic.rejected'],
 });
@@ -181,11 +247,14 @@ Type `REJECTED_EVENT_TYPE` (`cyberart.diagnostic.rejected`). Payload (`Rejection
 | `EVENT_ENVELOPE_VERSION` | `1`. |
 | `DEFAULT_MAX_HOPS` | `8`. |
 | `REJECTED_EVENT_TYPE` | `'cyberart.diagnostic.rejected'`. |
-| `inferEventKind(input)` | Kind from `kind` or type name. |
+| `inferEventKind(input)` | Kind from `kind` or first kind segment in `type`. |
 | `matchEventPattern(pattern, type)` | One-segment `*` glob. |
 | `normalizeEvent(input, context)` | Build an envelope or `{ ok: false, reason: 'malformed', detail }`. The router calls this; hosts rarely need it. |
+| `defineIntent` / `defineStateEvent` / `defineDiagnostic` | Contract constructors (see Typed contracts). |
+| `createContractRegistry` / `deriveAttachOptions` / `verifyAttachOptions` / `comparePayloadSchemas` | Registry, permissions, schema compatibility. |
+| `kindSegmentInType` / `familyPatternForType` | Name helpers used by contracts. |
 
-Types: `EventEnvelope`, `EventInput`, `EventKind`, `NormalizeContext`, `NormalizeResult`, `RejectionPayload`, `RejectionReason`, `AttachOptions`, `EventRouter`, `EventRouterOptions`, `PublishExtras`, `ValidateResult`.
+Types: `EventEnvelope`, `EventInput`, `EventKind`, `NormalizeContext`, `NormalizeResult`, `RejectionPayload`, `RejectionReason`, `AttachOptions`, `EventRouter`, `EventRouterOptions`, `PublishExtras`, `ValidateResult`, `EventContract`, `EventContractManifest`, `ContractRegistry`, `DefineContractResult`, `PayloadSchema`, `PayloadFieldSpec`, `PayloadValidation`, `ContractDiagnostic`, `ContractFieldType`, `InferredPayload`, `SchemaCompatibility`.
 
 `matchesAnyPattern` / `clonePayload` / `isEventKind` are not on the public package surface.
 

package/docs/headless-harness.md

@@ -2,14 +2,25 @@
 
 CI / agent wrapper around production `createRuntime({ deterministic })`. Not a second engine. Do not call this from Player or kaleidoscope.
 
-Depends on [deterministic mode](deterministic-mode.md). Host reducers: [events](events.md).
+Import from **`@cyberart-io/engine/headless`**. Production carts and browser hosts keep using `@cyberart-io/engine` so Vite never resolves `node:fs/promises`.
+
+Depends on [deterministic mode](deterministic-mode.md). Host reducers: [events](events.md). Presentation overlay: [presentation adapter](presentation-adapter.md).
 
 Back to the [package README](../README.md).
 
+## Migration
+
+| Surface | Import |
+|---|---|
+| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, contracts, assets, presentation adapter, presentation cue) |
+| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `installHeadlessCanvas`, `captureFrame`) |
+
+The main export does not re-export the harness. A browser bundle that only imports `@cyberart-io/engine` must not warn about `node:fs/promises`.
+
 ## One-command reproduce (this repo)
 
 ```bash
-pnpm exec vitest run packages/engine/src/canvas/headlessHarness.spec.ts
+pnpm exec vitest run packages/engine/src/canvas/headlessHarness.spec.ts packages/engine/src/canvas/cyb-57-exports.repro.spec.ts
 ```
 
 Package consumers copy the loop below into their own test file (Vitest + jsdom or equivalent).
@@ -22,7 +33,7 @@ import {
   HEADLESS_PNG_DATA_URL,
   DEFAULT_HEADLESS_WIDTH,
   DEFAULT_HEADLESS_HEIGHT,
-} from '@cyberart-io/engine';
+} from '@cyberart-io/engine/headless';
 
 installHeadlessCanvas();
 ```
@@ -34,7 +45,7 @@ Mutates `HTMLCanvasElement.prototype`: `ImageData` polyfill (width/height constr
 ## `createHeadlessHarness(options)`
 
 ```ts
-import { createHeadlessHarness } from '@cyberart-io/engine';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
 
 const harness = createHeadlessHarness({
   cart: artProject,
@@ -44,7 +55,7 @@ const harness = createHeadlessHarness({
   origin: 0,
   actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
   initialState: { room: 'glade' },
-  gameManager: hostAdapter, // existing mount injection; not a new adapter contract
+  gameManager: hostAdapter, // site injection; presentation overlay is attachPresentationAdapter
   onEvent: (event) => {},
   onError: (error, info) => {},
 });
@@ -77,6 +88,7 @@ Always sets `deterministic: { origin, actions }`.
 | `step(frames?)` / `advance(ms)` | Deterministic ticks. Throw after `destroy()`. |
 | `schedule(action)` | Pass-through `ScriptedAction`. |
 | `dispatch(event)` | Immediate mailbox enqueue. Cart `consume()`s on the next `update`. |
+| `start()` / `pause()` / `resume()` / `paused` | Pass-through on the current `cart`. Attach the harness to `attachPresentationAdapter` so `remount` stays live. |
 | `click(x, y)` | Pointer-**down** at `getClock().framesElapsed` (next tick). Canvas pixels, not CSS. Use `schedule` for `move` / `up`. |
 | `key(key)` | Same next-frame `schedule` for a key. Cart must `registerAction`. |
 | `inspect()` | `{ state, events, errors, replay, clock }`. `state` is **exported**, not live `getCartState()`. |
@@ -112,32 +124,62 @@ Returns `CartSnapshot`: `{ seed, metadata?, pngDataUrl }`.
 ## Interaction loop (agent recipe)
 
 ```ts
+import {
+  attachPresentationAdapter,
+  createReferencePresentationCart,
+} from '@cyberart-io/engine';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
+
 const harness = createHeadlessHarness({
-  cart,
+  cart: createReferencePresentationCart(),
   seed: 42,
-  gameManager: adapter,
-  actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
 });
+const adapter = attachPresentationAdapter(harness);
 
-await harness.step(5);
+await harness.step(1);
 const canvas = harness.cart.canvas!;
-harness.click(canvas.width / 2, canvas.height * 0.1); // canvas pixels
+adapter.present({
+  contractVersion: 1,
+  phase: 'ready',
+  view: {
+    title: 'Glade',
+    regions: [
+      {
+        id: 'north-trail',
+        x: 0,
+        y: 0,
+        width: canvas.width,
+        height: canvas.height * 0.25,
+        intent: {
+          type: 'adventure.intent.exit-requested',
+          payload: { exitId: 'brook' },
+        },
+      },
+    ],
+  },
+});
+await harness.step(1);
+harness.click(canvas.width / 2, canvas.height * 0.1);
 await harness.step(1);
 
-const { events, state } = await harness.inspect();
-// assert exactly one intent, e.g. room.exit.requested
+const { events } = await harness.inspect();
+// assert exactly one adventure.intent.exit-requested; cart state is still Glade
 
-harness.dispatch({
-  type: 'adventure.state.room-changed',
-  payload: { roomId: 'brook' },
+adapter.present({
+  contractVersion: 1,
+  phase: 'ready',
+  view: { title: 'Joiner Brook', regions: [] },
 });
 await harness.step(1);
 
 await harness.captureFrame('/tmp/brook.png');
+adapter.destroy();
 harness.destroy();
 ```
 
-Cleanup: cart `teardown` runs on unload; after `destroy`, `step` throws and the container is gone. `afterEach(() => harness.destroy())` so a failed assertion does not leak nodes.
+Cleanup: cart `teardown` runs on unload; after `destroy`, `step` throws and the container is gone. `afterEach(() => harness.destroy())` so a failed assertion does not leak nodes. `attachPresentationAdapter(harness)` then `adapter.destroy()` tears down the harness too; `attachPresentationAdapter(harness.cart)` only unloads the cart.
+
+Host-owned rooms / hotspots use this adapter (`present` + `adventure.intent.*`). `gameManager` is site multiplayer, not this contract.
 
 ## Types
 

package/docs/presentation-adapter.md

@@ -0,0 +1,150 @@
+# Presentation adapter
+
+Host-owned render models in, interaction intents out. Cyberart is not authoritative for game rules. Depends on [events](events.md). CI: [headless harness](headless-harness.md).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/presentationAdapter.spec.ts
+```
+
+## Contract (`PRESENTATION_ADAPTER_VERSION = 1`)
+
+The host keeps the canonical world. It projects a **render model** into Cyberart, maps its lifecycle onto a cart handle, and validates intents before mutating anything.
+
+| Host | Adapter | Cyberart |
+|---|---|---|
+| attach / open | `mountPresentationAdapter` or `attachPresentationAdapter` | `runtime.mount` |
+| start loop | `start()` | `cart.start()` (live). Deterministic hosts `step` instead; `pause` does not block `step`. |
+| push view | `present(model)` | `dispatch({ type: presentation.state.model, kind: 'state' })` |
+| pause / resume | `pause()` / `resume()` | `cart.pause` / `cart.resume` |
+| tear down | `destroy()` | `cart.destroy`. Idempotent. Later `present` / `pause` / `resume` / `start` throw. With a harness, still call `harness.destroy()` so the container goes away. |
+
+`gameManager` on `mount` is unchanged (site multiplayer). Do not use it as this contract.
+
+`attachPresentationAdapter(cart)` does **not** dispatch. Pass `{ model }` to push immediately. `mountPresentationAdapter` boots `model` (or `initialState.model`, or loading) through `initialState` and does not queue a second copy. `present()` throws `INVALID_PRESENTATION_MODEL_MESSAGE` if the model is invalid or not JSON-serializable — `adapter.phase` is unchanged.
+
+Attach the **harness** (not `harness.cart`) if you `remount`; dispatch follows the current cart. After `runtime.mount` again, call `adapter.retarget(newHandle)`.
+
+If you `router.attach('presentation', runtime.hostChannel)`, use `router.subscribe` for host logic and omit `mount({ onEvent })` — both would see every intent.
+
+A `present()` from `onEvent` during the click's `update` applies **this frame** (the reference cart consumes once more after emitting).
+
+### Model
+
+```ts
+import {
+  PRESENTATION_ADAPTER_VERSION,
+  type PresentationModel,
+} from '@cyberart-io/engine';
+
+const model: PresentationModel = {
+  contractVersion: PRESENTATION_ADAPTER_VERSION, // 1
+  phase: 'ready', // 'loading' | 'ready' | 'error' | 'unsupported'
+  reason: undefined, // string when not ready
+  view: {
+    background: '#1b3a4a',
+    title: 'Joiner Brook',
+    regions: [
+      {
+        id: 'north-trail',
+        x: 0,
+        y: 0,
+        width: 320,
+        height: 45,
+        intent: {
+          type: 'adventure.intent.exit-requested',
+          payload: { exitId: 'brook' },
+        },
+      },
+    ],
+  },
+};
+```
+
+`view` is host-owned. The reference cart hit-tests `regions` and paints `background`. `title` is inspectable state, not drawn. Extra fields (characters, exits, inventory) are ignored — map clickable things onto `regions`. Coordinates are drawing-space pixels, the same space as `PointerManager` and harness `click`. A shared normalized space is a later ticket.
+
+`adapter.model` / `adapter.phase` are what this session last presented (or the boot model). The getter returns a **copy**. After `step`, `inspect().state.model` is what the cart applied.
+
+`phase`:
+
+| Phase | Clicks |
+|---|---|
+| `loading` | Ignored |
+| `ready` | First matching `view.regions[]` emits its `intent` (`kind` is always `intent`) |
+| `error` | Ignored |
+| `unsupported` | Ignored (unknown `contractVersion`, non-serializable model, or a capability the host cannot present) |
+
+The reference cart never writes the host’s world. An unknown `contractVersion` (or a model that cannot be JSON-cloned) becomes `{ phase: 'unsupported', reason }` in cart state and emits `presentation.intent.unsupported`. Listen on `onEvent` / the router. `adapter.phase` is only what this session successfully `present()`ed (or the boot model); cart-side rejects do not change it.
+
+### Intents
+
+Region `intent.type` should be routable: `*.intent.*` (for example `adventure.intent.exit-requested`). The reference cart always sets `kind: 'intent'` on clicks (a hotspot cannot emit `state`).
+
+Default router `emit` is `['*.intent.*']`, which does **not** match `room.exit.requested`. Prefer `adventure.intent.*`.
+
+## Reference cart + session
+
+```ts
+import {
+  attachPresentationAdapter,
+  createReferencePresentationCart,
+} from '@cyberart-io/engine';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
+
+const harness = createHeadlessHarness({
+  cart: createReferencePresentationCart(),
+  seed: 42,
+  onEvent: (event) => hostReduce(event),
+});
+const adapter = attachPresentationAdapter(harness);
+
+adapter.present(model);
+await harness.step(1);
+harness.click(x, y); // canvas pixels
+await harness.step(1);
+await adapter.start(); // live hosts; optional in deterministic mode
+adapter.pause();
+adapter.resume();
+adapter.destroy();
+```
+
+Already have a runtime:
+
+```ts
+const adapter = mountPresentationAdapter(runtime, {
+  onEvent: (event) => hostReduce(event),
+  model: { contractVersion: 1, phase: 'loading' },
+});
+await adapter.start();
+```
+
+A host with a custom view shape passes `cart:` into `mountPresentationAdapter` and still `present()`s the same event. Do not import Adventure Kit types into engine carts.
+
+## Router
+
+```ts
+router.attach('presentation', runtime.hostChannel, {
+  emit: ['*.intent.*'],
+  subscribe: [...PRESENTATION_SUBSCRIBE_PATTERNS],
+});
+
+router.subscribe(['adventure.intent.*', 'presentation.intent.unsupported'], (event) => {
+  const next = reduce(world, event); // host validates; ignore invalid intents
+  if (next) {
+    // Do not pass `{ cause: event }` — a second `presentation.state.model`
+    // from `host` in that chain is `loop-detected`.
+    router.publish(createPresentationModelEvent(project(next)));
+  }
+});
+```
+
+`PRESENTATION_SUBSCRIBE_PATTERNS` is `presentation.state.*` plus `cyberart.diagnostic.rejected`. Only the host (or an `authoritative` participant) may emit `presentation.state.model`. `adapter.present` writes this cart’s mailbox only; `router.publish` fans out to every subscriber.
+
+## Types and helpers
+
+`PRESENTATION_ADAPTER_VERSION`, `PRESENTATION_MODEL_EVENT`, `PRESENTATION_UNSUPPORTED_EVENT`, `PRESENTATION_PHASES`, `PRESENTATION_SUBSCRIBE_PATTERNS`, `INVALID_PRESENTATION_MODEL_MESSAGE`, `isPresentationModel`, `isPresentationPhase`, `createPresentationModelEvent`, `createReferencePresentationCart`, `attachPresentationAdapter`, `mountPresentationAdapter`.
+
+Types: `PresentationModel`, `PresentationView`, `PresentationRegion`, `PresentationPhase`, `PresentationCartState`, `PresentationAdapter`, `PresentationAdapterTarget`, `AttachPresentationAdapterOptions`, `MountPresentationAdapterOptions`.

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,14 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.2",
-  "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/headless.js",
+    "dist/headless.d.ts",
     "docs"
   ],
   "main": "./dist/index.js",
@@ -16,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,