@cyberart-io/engine 0.0.1 → 0.0.3

package/docs/events.md

@@ -0,0 +1,272 @@
+# 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`), [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 |
+|---|---|
+| 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. 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';
+
+// 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
+```
+
+`HostEvent` is `EventInput`: at least `{ type, payload? }`. Extra envelope fields are optional on an unattached mailbox.
+
+| Member | Meaning |
+|---|---|
+| `dispatch(event)` | Queue inbound. Oldest dropped past **32** unconsumed events. |
+| `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. |
+| `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`.
+
+## Envelope
+
+Routed events are normalized to `EventEnvelope` (`EVENT_ENVELOPE_VERSION = 1`).
+
+| Field | Set by | Meaning |
+|---|---|---|
+| `schemaVersion` | router | Always `1`. Other versions are `malformed`. |
+| `type` | emitter | Dotted name, e.g. `adventure.intent.exit-requested`. |
+| `kind` | explicit or inferred | `intent` \| `state` \| `diagnostic`. |
+| `source` | router | Participant id (or `host` / `router`). Claimed `source` is overwritten. |
+| `target` | emitter | Optional **participant id**, not a domain object (put the exit id in `payload`). |
+| `id` | router (`createId`) | Claimed `id` is ignored. |
+| `correlationId` | emitter or `id` | Groups a request and its follow-ups. |
+| `causationId` | cause / auto-link | Parent event `id`. |
+| `seq` | router | Monotonic **per source**. No global order across sources. |
+| `hops` | router | Remaining TTL. Claimed hop counts are ignored. |
+| `idempotencyKey` | emitter | Replay-safe emit; scoped by `source`. |
+| `payload` | emitter | JSON-serializable. Cycles / BigInt → `malformed`. |
+
+`kind` on the input wins. Otherwise:
+
+- `cyberart.state.save` / `cyberart.state.load` are **intents** (historical names).
+- 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 } from '@cyberart-io/engine';
+
+const router = createEventRouter({
+  now: () => cart.getClock().now,
+  createId: () => `evt-${seq++}`, // seed-stable in deterministic tests
+  validate: (event) => true, // or { reason: 'host-rejected', detail: '…' }
+});
+
+router.attach('presentation', runtime.hostChannel, {
+  emit: ['adventure.intent.*'],
+  subscribe: ['adventure.state.*', 'cyberart.diagnostic.rejected'],
+});
+
+router.subscribe(['adventure.intent.*'], (event) => {
+  router.publish(
+    { type: 'adventure.state.room-changed', kind: 'state', payload: { roomId: 'brook' } },
+    { cause: event },
+  );
+});
+
+router.turn(); // once per step / frame
+```
+
+### Options (`EventRouterOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `validate` | none | Sync hook on **cart-originated** events only. Return `true` or `{ reason: 'host-rejected', detail? }`. |
+| `createId` | `evt-1`, `evt-2`, … | Envelope ids. Inject a seed-stable function for replays. |
+| `now` | `Date.now` | Sliding window timestamps. Inject `() => cart.getClock().now` in deterministic mode. |
+| `hostSource` | `'host'` | `source` on host `publish`. |
+| `maxPerTurn` | `8` | Cart emits per source per `turn()`. Excess → `rate-limited`. |
+| `maxPerWindow` | off | Cart emits per source in `windowMs`. Excess → `rate-limited`. |
+| `windowMs` | `1000` | Window for `maxPerWindow`. |
+| `maxCausationDepth` | `8` | Causation-chain depth / cycle → `loop-detected`. |
+| `maxHops` | `DEFAULT_MAX_HOPS` (`8`) | Remaining hops on a new root. A caused follow-up gets `cause.hops - 1`. At 0 → `hop-limit`. |
+| `maxCorrelationPerTurn` | `16` | Events sharing a `correlationId` per turn → `storm-detected`. |
+| `maxIndex` | `256` | Bound on causation / idempotency maps (oldest keys dropped). |
+
+### Router methods (`EventRouter`)
+
+| Method | Meaning |
+|---|---|
+| `attach(id, channel, options?)` | Bind a cart mailbox. `id` is the participant source. Re-attach replaces. |
+| `detach(id)` | Unbind. In-flight targeted emits to this id fail `unknown-target`. |
+| `publish(event, extras?)` | Host emit. `extras.cause` sets causation and inherited idempotency/correlation. Returns the envelope, or `undefined` if rejected. |
+| `subscribe(patterns, listener)` | Host listener (not a cart). Returns unsubscribe. |
+| `turn()` | Reset per-turn budgets and the auto-link causation cursor. Idempotency records **survive**. Call once per `step`. |
+
+### `AttachOptions`
+
+| Option | Default | Meaning |
+|---|---|---|
+| `emit` | `['*.intent.*']` | Types this cart may emit. |
+| `subscribe` | `[]` | Types delivered to this channel. |
+| `authoritative` | `false` | If true, may emit `state` / `diagnostic` **when those types are also in `emit`**. |
+
+Patterns are dotted segments; `*` matches one segment. `adventure.intent.*` matches `adventure.intent.exit-requested`, not `adventure.intent.exit.requested`.
+
+## Delivery and ordering
+
+- FIFO **per source**, monotonic `seq`.
+- No global order across sources unless the host serializes `publish`.
+- Delivery is always queued `dispatch`. A cart sees routed events on the next `consume()`.
+- An explicit `target` that is missing is `unknown-target`. A target that is attached but does not subscribe is `not-subscribed` (not cached; a later `attach` can retry).
+
+Cart-to-cart still goes through the router:
+
+```ts
+presentationChannel.emit({
+  type: 'adventure.intent.remark',
+  target: 'npc',
+  payload: { text: 'Anyone there?' },
+  idempotencyKey: 'hello-1',
+});
+```
+
+## Hops, idempotency, storms
+
+- New root: `hops = maxHops`. Follow-up: `cause.hops - 1`. Claimed hop counts ignored.
+- At 0 the router rejects `hop-limit` without consulting the causation index (replayed logs stay bounded).
+- `idempotencyKey` is scoped by `source`. Terminal outcomes (accept, or a **non-transient** reject) are remembered; a second emit with the same key returns the original envelope and does not fan out.
+- Transient rejects are **not** cached: `rate-limited`, `storm-detected`, `hop-limit`, `loop-detected`, `not-subscribed`. Retry after `turn()` or a later `attach`.
+- Host `publish({ cause })` and same-turn cart follow-ups inherit `${cause.idempotencyKey}::${type}` and the parent `correlationId` when the follow-up omits its own.
+
+## Rejections
+
+Type `REJECTED_EVENT_TYPE` (`cyberart.diagnostic.rejected`). Payload (`RejectionPayload`):
+
+| Field | Meaning |
+|---|---|
+| `reason` | See below. |
+| `detail` | Optional string. |
+| `eventType` | The rejected type. |
+| `source` | Claimed / assigned source. |
+
+| `reason` | When |
+|---|---|
+| `malformed` | Bad type, kind, schemaVersion, or non-JSON payload. |
+| `unauthorized` | Cart emitted a type/kind not on its allowlist. |
+| `host-rejected` | `validate` returned reject. |
+| `rate-limited` | `maxPerTurn` or `maxPerWindow`. |
+| `loop-detected` | Causation cycle or `maxCausationDepth`. |
+| `storm-detected` | `maxCorrelationPerTurn` on one `correlationId`. |
+| `unknown-target` | `target` is not attached. |
+| `not-subscribed` | `target` attached but that type is not in `subscribe`. |
+| `hop-limit` | Remaining hops hit 0. |
+
+## Helpers (exported)
+
+| Export | Role |
+|---|---|
+| `EVENT_ENVELOPE_VERSION` | `1`. |
+| `DEFAULT_MAX_HOPS` | `8`. |
+| `REJECTED_EVENT_TYPE` | `'cyberart.diagnostic.rejected'`. |
+| `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`, `EventContract`, `EventContractManifest`, `ContractRegistry`, `DefineContractResult`, `PayloadSchema`, `PayloadFieldSpec`, `PayloadValidation`, `ContractDiagnostic`, `ContractFieldType`, `InferredPayload`, `SchemaCompatibility`.
+
+`matchesAnyPattern` / `clonePayload` / `isEventKind` are not on the public package surface.
+
+## Deterministic hosts
+
+```ts
+const router = createEventRouter({
+  now: () => cart.getClock().now,
+  createId: () => `evt-${stableCounter++}`,
+});
+await cart.step(1);
+router.turn();
+```
+
+See [deterministic mode](deterministic-mode.md).

package/docs/headless-harness.md

@@ -0,0 +1,186 @@
+# Headless harness
+
+CI / agent wrapper around production `createRuntime({ deterministic })`. Not a second engine. Do not call this from Player or kaleidoscope.
+
+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 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).
+
+## Canvas install (test-only)
+
+```ts
+import {
+  installHeadlessCanvas,
+  HEADLESS_PNG_DATA_URL,
+  DEFAULT_HEADLESS_WIDTH,
+  DEFAULT_HEADLESS_HEIGHT,
+} from '@cyberart-io/engine/headless';
+
+installHeadlessCanvas();
+```
+
+Mutates `HTMLCanvasElement.prototype`: `ImageData` polyfill (width/height constructor), stub `getContext` (`fillRect`, `putImageData`, `createImageData`), `toDataURL` → `HEADLESS_PNG_DATA_URL` (a real 1×1 PNG, not visual `fillRect` pixels). Idempotent. **Do not call from production playback.**
+
+`createHeadlessHarness` calls this for you. Default container size is `DEFAULT_HEADLESS_WIDTH` × `DEFAULT_HEADLESS_HEIGHT` (320×180).
+
+## `createHeadlessHarness(options)`
+
+```ts
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
+
+const harness = createHeadlessHarness({
+  cart: artProject,
+  seed: 42,
+  width: 320,
+  height: 180,
+  origin: 0,
+  actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
+  initialState: { room: 'glade' },
+  gameManager: hostAdapter, // site injection; presentation overlay is attachPresentationAdapter
+  onEvent: (event) => {},
+  onError: (error, info) => {},
+});
+```
+
+### Options (`CreateHeadlessHarnessOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `cart` | required | `AnimationCart` to mount. |
+| `seed` | generated | Passed to `createRuntime` (canonicalized). |
+| `width` / `height` | `320` / `180` | `clientWidth` / `clientHeight` on the container. Canvas buffer is `getDrawDimensions × devicePixelRatio`. |
+| `origin` | `0` | Virtual clock origin (ms). |
+| `actions` | `[]` | Constructor `ScriptedAction` tape. |
+| `initialState` | none | `mount` boot overrides (`customState`). |
+| `gameManager` | none | Opaque host adapter into `getDefaultState` / `update`. |
+| `onEvent` | none | Also forwarded; the harness still logs outbound events. |
+| `onError` | none | Also forwarded; the harness still logs structured errors. Wire happens **before** `mount`. |
+
+Always sets `deterministic: { origin, actions }`.
+
+## Handle (`HeadlessHarness`)
+
+| Member | Meaning |
+|---|---|
+| `runtime` | The `CyberArtRuntime`. Assigning `runtime.onError` replaces **your** handler; the harness still records errors. |
+| `container` | Sized mount element (on `document.body` until `destroy`). |
+| `cart` | Current `CartHandle` (updates on `remount`). |
+| `events` / `errors` | **Copies** of the logs. Mutating them does not change internals. Prefer `inspect()` for a snapshot. |
+| `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()`. |
+| `captureFrame(path?)` | `cart.snapshot()`. Optional `path` writes PNG bytes (Node only). Stub-stable. |
+| `remount(options?)` | `runtime.mount` again while alive. Constructor `actions` replay; prior `click`/`key`/`schedule` dropped. `'onEvent' in options` replaces the listener; `{ onEvent: undefined }` clears it. Invalid after `destroy()`. |
+| `destroy()` | Unload cart, destroy runtime, remove container. Idempotent. Always removes the container even if unload throws. |
+
+Repeated mount/destroy = a **new** `createHeadlessHarness` (or `remount` then `destroy`). Do not `remount` after `destroy()`.
+
+### Click / clock
+
+After `step(5)`, `framesElapsed === 5`. `click` / `key` schedule at that index; `step(1)` applies them. Hit-test pointer against `dimensionContext` (drawing space), not the CSS box.
+
+### `inspect()` (`HeadlessInspect`)
+
+| Field | Meaning |
+|---|---|
+| `state` | `exportState().state` / replay `state`. |
+| `events` | Outbound log copy. |
+| `errors` | `{ error, info: FrameErrorInfo }[]`. |
+| `replay` | `getReplayMetadata()`. |
+| `clock` | `getClock()`. |
+
+First frame throw: `{ phase: 'update', consecutive: 1, stopped: false }`. See [deterministic mode](deterministic-mode.md) for the 120-frame breaker.
+
+### `captureFrame(path?)`
+
+Returns `CartSnapshot`: `{ seed, metadata?, pngDataUrl }`.
+
+- Omit `path` for in-memory snapshot (`pngDataUrl` is `HEADLESS_PNG_DATA_URL` under the stub).
+- With `path`: Node `fs.promises.writeFile` of decoded PNG bytes. Throws a harness message if not Node, if `node:fs/promises` cannot load, or if the write fails (missing directory, etc.). Write under `os.tmpdir()`, not the repo.
+
+## Interaction loop (agent recipe)
+
+```ts
+import {
+  attachPresentationAdapter,
+  createReferencePresentationCart,
+} from '@cyberart-io/engine';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
+
+const harness = createHeadlessHarness({
+  cart: createReferencePresentationCart(),
+  seed: 42,
+});
+const adapter = attachPresentationAdapter(harness);
+
+await harness.step(1);
+const canvas = harness.cart.canvas!;
+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 } = await harness.inspect();
+// assert exactly one adventure.intent.exit-requested; cart state is still Glade
+
+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. `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
+
+`CreateHeadlessHarnessOptions`, `HeadlessHarness`, `HeadlessInspect`, `HeadlessFrameError`.

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`.