@cyberart-io/engine 0.0.1 → 0.0.3

package/README.md

@@ -24,7 +24,7 @@ This guide is the path from `npm i` to a piece on screen, then a short map of th
 npm i @cyberart-io/engine
 ```
 
-The package is minified JS plus a rolled-up `.d.ts`. It does not include animation carts. Tone.js is an optional peer — skip it until a cart declares `audio: 'tone'`.
+The package is minified JS plus rolled-up `.d.ts` for two entrypoints: the browser runtime (`.`) and Node/jsdom helpers (`./headless`). It does not include animation carts. Tone.js is an optional peer — skip it until a cart declares `audio: 'tone'`.
 
 ## Quick start
 
@@ -83,6 +83,17 @@ window.addEventListener('pagehide', () => {
 
 `createRuntime` and `mount` are synchronous. `mount` **prepares** the cart (`getDefaultState`) but does not start the loop — that is `start()`. If prepare fails, `mount` throws.
 
+## Feature guides
+
+Full API for the event router, deterministic replay, and CI harness (so agents can use every export):
+
+- [Events and router](docs/events.md) — mailbox, envelope, typed contracts, `createEventRouter`, hops, idempotency, rejections
+- [Deterministic mode](docs/deterministic-mode.md) — `step` / `schedule`, clocks, `ScriptedAction`, replay diffs
+- [Headless harness](docs/headless-harness.md) — `createHeadlessHarness` from `@cyberart-io/engine/headless`, jsdom canvas, inspect / screenshot
+- [Presentation adapter](docs/presentation-adapter.md) — host-owned render model, intents, loading / error / unsupported
+- [Asset resolver](docs/asset-resolver.md) — host-pluggable images/audio/fonts/spritesheets, cache, preload, fallbacks
+- [Presentation cue](docs/presentation-cue.md) — deterministic `createPresentationTimeline`, duplicate policy, reduced-motion, lifecycle events
+
 ## Write a cart
 
 A cart is an `AnimationCart`. Required:
@@ -122,14 +133,20 @@ const cart = runtime.mount(artProject, {
 });
 ```
 
+`runtime.hostChannel` is the mailbox for this instance. Attach it to `createEventRouter` from the host; carts never receive the router.
+
+`runtime.assets` is the preloader when `createRuntime({ assets: { resolver } })` was set. Logical refs and fallbacks: [asset resolver](docs/asset-resolver.md).
+
 `createRuntime` options:
 
 | Option | Default | Meaning |
 |---|---|---|
 | `container` | required | Element that will hold the canvas. |
-| `seed` | generated | Token hash for `Random`. Instance-local; does not clobber a global cache. |
-| `captureKeyboard` | `false` | When true, the cart listens for `window` keydown. Full-page players pass `true`. |
+| `seed` | generated | Token hash for `Random`. Instance-local; does not clobber a global cache. 64-hex hashes pass through; other seeds are mixed via `canonicalizeSeed`. |
+| `captureKeyboard` | `false` | When true, the cart listens for `window` keydown. Full-page players pass `true`. Off in deterministic mode. |
 | `audio` | none | Libraries to unlock if `unlockAudio()` runs before `mount`. After mount, the cart’s `metadata.audio` wins. |
+| `deterministic` | off | Host-controlled clock, `step`/`advance`, and scripted input/assets. Leave unset for live kaleidoscope / Art Blocks. |
+| `assets` | off | Host `AssetResolver` plus engine cache/preload. Carts keep logical refs. Leave unset when the piece has no media. |
 
 `CartHandle` (what `mount` returns):
 
@@ -139,6 +156,9 @@ const cart = runtime.mount(artProject, {
 | `pause()` / `resume()` | Freeze / continue the loop. |
 | `snapshot()` | PNG data URL + seed + metadata. Not live `state`. |
 | `dispatch(event)` | Queue an inbound host event for the cart. |
+| `step(frames)` / `advance(ms)` | Deterministic ticks only. Throw if `deterministic` was not set. |
+| `schedule(action)` | Queue a pointer/key/host-event/asset for a future frame. |
+| `getClock()` / `getRandomState()` / `getReplayMetadata()` | Replay inspection. |
 | `exportState()` / `exportStateJSON()` | Pause-safe serializable bundle. |
 | `importState(bundle)` | Restore a bundle (or JSON string). |
 | `destroy()` | Unload this cart. Idempotent. |
@@ -187,12 +207,58 @@ const runtime = createRuntime({
 
 `Random` in `getDefaultState` / `update` / `render` follows that hash. Mark `metadata.generative: true` when the piece is a function of the seed — saves then refuse to load onto a different hash.
 
-## Events
+`Random.getState()` / `setState()` snapshot the dual sfc32 generators (post-warmup). Same hash always yields the same sequence; do not use `Math.random()` or `Date.now()` in cart logic. `setState` throws if the snapshot seed does not match.
+
+A 64-hex Art Blocks hash is used as-is (optional `0x`, lowercased). `canonicalizeSeed` mixes any other value — including a number such as `42` — into a 64-hex hash. `createRuntime` uses `resolveRuntimeSeed`: live mode keeps a short `?hash=` string as `0x…` so kaleidoscope local hashes do not change; deterministic mode always canonicalizes.
+
+## Deterministic mode
+
+Seeded `Random` is not enough to reproduce an interactive scene. Opt in with `deterministic` so the host owns time and input. **Leave this unset for kaleidoscope / Art Blocks.**
+
+```ts
+const runtime = createRuntime({
+  container,
+  seed: 42,
+  deterministic: {
+    origin: 0,
+    actions: [
+      { type: 'asset', atFrame: 2, id: 'room', status: 'ready' },
+      { type: 'pointer', atFrame: 7, pointer: { kind: 'down', x: 40, y: 20 } },
+    ],
+  },
+});
+const cart = runtime.mount(artProject);
+await cart.step(10);
+const replay = await cart.getReplayMetadata();
+```
+
+`step` / `advance` / `schedule` / `getClock` / `getReplayMetadata` / `describeReplayMismatch` are documented in [deterministic mode](docs/deterministic-mode.md) (`ScriptedAction` includes `key` and `event`; asset types are `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT`; clocks are `createVirtualClock` / `createWallClock`).
+
+## Headless harness
+
+CI and agents should drive the **same** `createRuntime({ deterministic })` path. Import the harness from **`@cyberart-io/engine/headless`** so browser production builds never walk `node:fs/promises`.
+
+- Carts and production hosts: `import { createRuntime } from '@cyberart-io/engine'`
+- Tests, CI, and frame capture: `import { createHeadlessHarness } from '@cyberart-io/engine/headless'`
+
+`@cyberart-io/engine` does not re-export the harness. `installHeadlessCanvas` is the documented jsdom install (test-only). `createHeadlessHarness` sizes a container, mounts, and wraps step / input / inspect / snapshot.
+
+Full options, `click` clock rule, Node-only `captureFrame`, remount, and the reproduce command: [headless harness](docs/headless-harness.md).
+
+```ts
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
+
+const harness = createHeadlessHarness({ cart: artProject, seed: 42 });
+await harness.step(5);
+harness.click(x, y); // pointer-down, canvas pixels, next frame
+await harness.step(1);
+const { state, events } = await harness.inspect();
+harness.destroy();
+```
 
-The runtime does not ship an event schema. Types are yours.
+## Events
 
-- Host → cart: `cart.dispatch({ type, payload })`. The cart opts in by calling `hostChannel.consume()` (typically in `update`). Unconsumed events keep the newest 32.
-- Cart → host: `hostChannel.emit({ type, payload })`. Pass `onEvent` at `mount` to hear them.
+Default path: per-runtime **mailbox** (`dispatch` / `consume` / `emit`). Multi-cart hosts attach each `HostChannel` to `createEventRouter` — carts never see the router.
 
 ```ts
 const cart = runtime.mount(artProject, {
@@ -202,11 +268,127 @@ const cart = runtime.mount(artProject, {
     }
   },
 });
-
 cart.dispatch({ type: 'art-project.theme', payload: 'dusk' });
 ```
 
-Carts that never mention `HostChannel` ignore both directions.
+Envelope, contracts (`defineIntent` / `defineStateEvent` / `defineDiagnostic`), `attach` / `detach` / `publish` / `turn`, hops, idempotency, budgets, and rejection reasons: [events and router](docs/events.md).
+
+```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) throw new Error('contracts');
+const contracts = [exit.contract, room.contract];
+const registry = createContractRegistry(contracts);
+const router = createEventRouter({
+  validate: registry.asRouterValidate,
+});
+router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
+```
+
+## Presentation cue
+
+Frame-stepped effects (checkmarks, ripples, room fades). No `setTimeout` / rAF. Drive `step` from the same clock as deterministic `cart.step`.
+
+```ts
+import { createPresentationTimeline } from '@cyberart-io/engine';
+
+const timeline = createPresentationTimeline({ originFrame: 0, reducedMotion: false });
+timeline.play({
+  name: 'checkmark',
+  idempotencyKey: 'gold',
+  durationFrames: 90,
+  easing: 'ease-out',
+  onDuplicate: 'replace',
+});
+timeline.step(90);
+```
+
+Lifecycle names `cue.started` / `cue.completed` / `cue.cancelled` / `cue.replaced` are local to the timeline. They are not router envelopes unless you define a contract. Duplicate policy, late-play catch-up, and reduced-motion: [presentation cue](docs/presentation-cue.md).
+
+## Presentation adapter
+
+Host-owned render model in, interaction intents out. Cyberart does not mutate the canonical world. `gameManager` is not this contract.
+
+```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({
+  contractVersion: 1,
+  phase: 'ready',
+  view: { title: 'Joiner Brook', regions: [] },
+});
+```
+
+`start()` maps to `cart.start()`. Phases: `loading` / `ready` / `error` / `unsupported`. Full contract, router attach (`runtime.hostChannel`), and the reproduce command: [presentation adapter](docs/presentation-adapter.md).
+
+## Assets
+
+Hosts resolve logical refs (Library IDs, Moltazine posts, `world:asset/…`, ordinary URLs). The engine caches, dedupes, reports progress, and applies timeouts / CORS-shaped failures / silent fallbacks. Policy stays out of authored cart code.
+
+```ts
+import {
+  createRuntime,
+  createFixtureAssetResolver,
+  createHostedAssetResolver,
+} from '@cyberart-io/engine';
+
+const roomAssets = [
+  { id: 'room-bg', ref: 'moltazine:post/porch-1#primary-image', type: 'image' as const },
+  {
+    id: 'ambience',
+    ref: 'world:asset/stream-loop',
+    type: 'audio' as const,
+    fallback: 'silent' as const,
+  },
+];
+
+const local = createRuntime({
+  container,
+  assets: {
+    resolver: createFixtureAssetResolver({
+      'moltazine:post/porch-1#primary-image': { url: 'fixture://images/porch.png' },
+      'world:asset/stream-loop': { url: 'fixture://audio/stream-loop.ogg' },
+    }),
+  },
+});
+await local.assets!.preload(roomAssets);
+
+const hosted = createRuntime({
+  container,
+  assets: {
+    resolver: createHostedAssetResolver({
+      cdnBase: 'https://cdn.example/library/',
+      failures: { 'world:asset/stream-loop': 'cors' },
+    }),
+  },
+});
+```
+
+The same declarations produce fixture URLs locally and CDN URLs (plus a typed CORS failure and silent audio fallback) when hosted. Live preload dispatches `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT`. Deterministic mode leaves those events to scripted `{ type: 'asset' }` actions so tests do not wait on wall-clock fetch. Full API and the reproduce command: [asset resolver](docs/asset-resolver.md).
 
 ## Save and load
 
@@ -258,7 +440,7 @@ const cart = runtime.mount(artProject, {
 });
 ```
 
-Pass `captureKeyboard: true` on `createRuntime` or the keys never reach the cart. Without `persist: 'localStorage'`, the host adapter ignores the events.
+Pass `captureKeyboard: true` on `createRuntime` or the keys never reach the cart. Without `persist: 'localStorage'`, the host adapter ignores the events. W/E emits `cyberart.state.save` / `cyberart.state.load`; those names are historical — they are intents, not authoritative state events.
 
 Slots are `localStorage['cyberart.state.' + cartId]`, or per-hash when the cart is generative. JSON can persist even if a framebuffer write fails.
 
@@ -281,7 +463,7 @@ A canvas the host adopted is left in place on destroy; a canvas the engine creat
 
 ## Publishing this package (maintainers)
 
-Not part of writing a cart. The npm tarball is built from `packages/engine/src/index.ts` and contains minified `dist/index.js`, rolled-up `dist/index.d.ts`, `LICENSE`, `README.md`, and `package.json`.
+Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (event / deterministic / harness / presentation-adapter / asset-resolver / presentation-cue API), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
 
 ```bash
 pnpm run pack:engine