@cyberart-io/engine 0.0.2 → 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
 
@@ -87,9 +87,12 @@ window.addEventListener('pagehide', () => {
 
 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, `createEventRouter`, hops, idempotency, rejections
+- [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`, jsdom canvas, inspect / screenshot
+- [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
 
@@ -130,6 +133,10 @@ 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 |
@@ -139,6 +146,7 @@ const cart = runtime.mount(artProject, {
 | `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):
 
@@ -228,12 +236,17 @@ const replay = await cart.getReplayMetadata();
 
 ## Headless harness
 
-CI and agents should drive the **same** `createRuntime({ deterministic })` path. `installHeadlessCanvas` is the documented jsdom install (test-only). `createHeadlessHarness` sizes a container, mounts, and wraps step / input / inspect / snapshot.
+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';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
 
 const harness = createHeadlessHarness({ cart: artProject, seed: 42 });
 await harness.step(5);
@@ -258,7 +271,124 @@ const cart = runtime.mount(artProject, {
 cart.dispatch({ type: 'art-project.theme', payload: 'dusk' });
 ```
 
-Envelope, `attach` / `detach` / `publish` / `turn`, hops, idempotency, budgets, and rejection reasons: [events and router](docs/events.md).
+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
 
@@ -333,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. Engine source lives in `packages/engine/src/` (not mixed into the site). 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`, `docs/` (event / deterministic / harness API), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
+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