@cyberart-io/engine 0.0.2 → 0.0.4

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,15 @@ 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
+- [Capability manifest](docs/capability-manifest.md) — versioned JSON for runtime features, phases, managers, assets, events, permissions, integrations
+- [Normalized geometry](docs/normalized-geometry.md) — coordinate spaces, contain/cover/crop layout, landmarks, hit regions, debug overlay
+- [Runtime group](docs/runtime-group.md) — `createRuntimeGroup`, shared router attach, lockstep clock; `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless`
 
 ## Write a cart
 
@@ -130,6 +136,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 +149,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):
 
@@ -162,7 +173,7 @@ const cart = runtime.mount(artProject, {
 
 `runtime.destroy()` tears down the runtime. `runtime.unlockAudio()` is for an early click before `mount`. `runtime.onError` receives frame errors (`phase`, `consecutive`, `stopped`).
 
-One cart per runtime. A second `mount` unloads the first. Several pieces on a page means several `createRuntime()` calls.
+One cart per runtime. A second `mount` unloads the first. Several pieces on a page means several `createRuntime()` calls, or one `createRuntimeGroup()` that attaches each mailbox to a shared router and locksteps a deterministic clock.
 
 ## Audio
 
@@ -228,12 +239,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, createHeadlessMultiCartHarness } 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);
@@ -245,7 +261,7 @@ harness.destroy();
 
 ## Events
 
-Default path: per-runtime **mailbox** (`dispatch` / `consume` / `emit`). Multi-cart hosts attach each `HostChannel` to `createEventRouter` — carts never see the router.
+Default path: per-runtime **mailbox** (`dispatch` / `consume` / `emit`). Multi-cart hosts should prefer `createRuntimeGroup()` (it calls `router.attach` for each mailbox). You can still attach each `HostChannel` to `createEventRouter` yourself — carts never see the router.
 
 ```ts
 const cart = runtime.mount(artProject, {
@@ -258,7 +274,182 @@ 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'));
+```
+
+## Capability manifest
+
+JSON for what a cart needs from the host. `validateCapabilityManifest` returns structured diagnostics instead of throwing.
+
+```ts
+import {
+  defineCapabilityManifest,
+  validateCapabilityManifest,
+} from '@cyberart-io/engine';
+
+const defined = defineCapabilityManifest({
+  id: 'adventure.presentation',
+  runtime: { minContractVersion: 1, features: ['router'] },
+  phases: ['loading', 'ready', 'error', 'unsupported'],
+  managers: ['pointer', 'hostChannel'],
+  assets: { kinds: ['image'], declarations: [{ id: 'room-bg', kind: 'image' }] },
+  acceptedEvents: ['adventure.state.*'],
+  emittedEvents: ['adventure.intent.exit-requested'],
+  permissions: { emit: ['adventure.intent.*'], subscribe: ['adventure.state.*'] },
+  integrations: ['tone'],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+validateCapabilityManifest(defined.manifest, {
+  contractVersion: 1,
+  features: ['router'],
+  integrations: ['tone'],
+  emit: ['adventure.intent.*'],
+  subscribe: ['adventure.state.*'],
+});
+```
+
+Fields, host allowlists, and diagnostic codes: [capability manifest](docs/capability-manifest.md).
+
+## Runtime group
+
+Several production carts, one router, one lockstep clock. Use this instead of intercepting each `onEvent` and republishing by hand.
+
+```ts
+import { createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  origin: 0,
+  participants: [
+    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['adventure.state.*'] },
+    { id: 'ambience', cart: ambienceCart, subscribe: ['ambience.intent.*'] },
+  ],
+});
+group.publish({ type: 'adventure.state.loon-whistle', kind: 'state', payload: { habitat: 'pond' } });
+await group.step(2);
+const { trace } = await group.inspect();
+group.destroy();
+```
+
+Headless / CI: `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` is the same handle after `installHeadlessCanvas()`. Full options: [runtime group](docs/runtime-group.md).
+
+## Normalized geometry
+
+Shared 0–1 content-box coordinates, landmarks, and hit regions. Pixel `PresentationRegion` on the presentation adapter is unchanged.
+
+```ts
+import {
+  createPresentationLayout,
+  pointerToRegion,
+  ROUND_TRIP_TOLERANCE,
+} from '@cyberart-io/engine';
+
+const layout = createPresentationLayout({
+  contentWidth: 1920,
+  contentHeight: 1080,
+  viewportWidth: 1280,
+  viewportHeight: 800,
+  mode: 'contain',
+});
+const hit = pointerToRegion({ x: canvasX, y: canvasY }, layout, doc);
+```
+
+Spaces, contain/cover/crop, debug overlay, and the reproduce command: [normalized geometry](docs/normalized-geometry.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 +524,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