@cyberart-io/engine 0.0.4 → 0.0.6

package/docs/asset-resolver.md

@@ -1,6 +1,6 @@
 # Asset resolver / preloader
 
-Host-owned URL policy. The engine caches, dedupes, tracks progress, applies timeouts and fallbacks, and (in live mode) dispatches `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT`. Authored carts keep logical refs (`moltazine:post/<id>#primary-image`, `world:asset/…`, `library:…`, or ordinary URLs). Adventure Kit, Cyberart, and a local preview each supply a different `AssetResolver`.
+Host-owned URL policy. The engine caches, dedupes, tracks progress, applies timeouts and fallbacks, and (in live mode) dispatches `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT`. Authored carts keep logical refs (`moltazine:post/<id>#primary-image`, `world:asset/…`, `library:…`, or ordinary URLs). the host, Cyberart, and a local preview each supply a different `AssetResolver`.
 
 Deterministic timing: [deterministic mode](deterministic-mode.md). CI: [headless harness](headless-harness.md). Event mailbox: [events](events.md).
 
@@ -43,7 +43,7 @@ const runtime = createRuntime({
 });
 
 await runtime.assets!.preload([
-  { id: 'room-bg', ref: 'moltazine:post/porch-1#primary-image', type: 'image' },
+  { id: 'backdrop', ref: 'moltazine:post/porch-1#primary-image', type: 'image' },
   {
     id: 'ambience',
     ref: 'world:asset/stream-loop',
@@ -69,7 +69,7 @@ Under `deterministic`, emit and wall-clock timeout are off so scripted `{ type:
 import type { AssetDeclaration } from '@cyberart-io/engine';
 
 const roomBg: AssetDeclaration = {
-  id: 'room-bg',
+  id: 'backdrop',
   ref: 'moltazine:post/porch-1#primary-image',
   type: 'image', // 'image' | 'audio' | 'font' | 'spritesheet'
   integrity: 'sha256-…', // optional; mismatch → `invalid`
@@ -135,7 +135,7 @@ const runtime = createRuntime({
   seed: 42,
   deterministic: {
     actions: [
-      { type: 'asset', atFrame: 2, id: 'room-bg', status: 'ready' },
+      { type: 'asset', atFrame: 2, id: 'backdrop', status: 'ready' },
       {
         type: 'asset',
         atFrame: 3,

package/docs/audio.md

@@ -0,0 +1,152 @@
+# Audio unlock broker and cues
+
+Page-level unlock, channel mix, and frame-stepped cue scheduling. One user gesture unlocks authorized carts onto a single audio graph. Cue traces are deterministic; **PCM output is not**.
+
+Back to the [package README](../README.md). Related: [presentation cue](presentation-cue.md) (scheduling), [asset resolver](asset-resolver.md) (`ASSET_READY_EVENT` / `ASSET_FAILED_EVENT`), [runtime group](runtime-group.md), [deterministic mode](deterministic-mode.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-67-audio.repro.spec.ts
+```
+
+## Why this exists
+
+Browser autoplay policy, load timing, and several carts on one page make it easy to start extra `AudioContext`s or invent per-cart mute/timing rules. Hosts create **one** `createAudioBroker` and pass it into `createRuntime` / `createRuntimeGroup`. Carts that only set `metadata.audio: 'tone'` keep the existing `start()` / `unlockAudio()` path when the broker is omitted.
+
+Silent carts never import Tone. Destroying a cart tears down that participant’s channels; it does not close Tone for remaining carts. There is still **one audio graph per page**.
+
+## `createAudioBroker(options?)`
+
+```ts
+import { createAudioBroker, createRuntime, createRuntimeGroup } from '@cyberart-io/engine';
+
+const broker = createAudioBroker({
+  // tests inject a no-op; default dynamically loads the Tone adapter
+  toneStart: async () => undefined,
+  reducedSensory: false,
+});
+
+await broker.unlock(); // first call runs toneStart; later calls share status
+broker.authorize('effects');
+broker.authorize('ambience');
+
+const group = createRuntimeGroup({
+  audioBroker: broker,
+  participants: [/* … */],
+});
+```
+
+| Member | Meaning |
+|---|---|
+| `unlock()` | Idempotent. First call runs `toneStart`. Default dynamically loads the Tone adapter: `load()` when `navigator.userAgent` matches `/Headless/i` (same as `AnimationManager.unlockAudio`), otherwise `unlock()`. Returns `{ state, error? }`. |
+| `status()` | `locked` / `unlocking` / `unlocked` / `failed`. |
+| `authorize(id)` / `revoke(id)` / `isAuthorized(id)` | Runtime-group participant ids. Empty set = all cues allowed (single-cart host). |
+| `setChannelGain(id, gain)` | Channel gain in `0…1`. |
+| `setPriority(id, n)` | Higher-priority active cues duck lower-priority channels (`DEFAULT_DUCK_GAIN` = `0.25`). |
+| `mute()` / `unmute()` | Page mute. Cues still record; playback is skipped (`audio.cue.skipped`, reason `muted`). |
+| `muteChannel(id)` / `unmuteChannel(id)` | Per-channel mute. |
+| `duck(id, gain?)` / `unduck(id)` | Manual duck; `unduck` restores auto priority ducking. |
+| `effectiveGain(id)` | `0` when page/channel muted, else `gain * duckGain`. |
+| `handleHostEvent(event)` | Records `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` by payload `id`. |
+| `teardown(participantId)` | Drop that cart’s authorization, channels, and active cues. Does **not** close Tone. |
+| `inspect()` | JSON-serializable `{ status, reducedSensory, muted, authorized, channels, assets }`. |
+| `destroy()` | Tear down all participants and listeners. Unlock status stays `unlocked` if it was; the shared context is left running. |
+
+`reducedSensory: true` skips playback and still records cue events (`audio.cue.skipped`, reason `reduced-sensory`). It does **not** pass presentation `reducedMotion`, so authored `delayFrames` still appear on `atFrame`.
+
+`createAudioCueTimeline()` with **no** broker starts cues (no unauthorized skip). Pass a broker when you need authorization, mute, or asset readiness.
+
+Repeat (`CueSpec.repeat`) keeps the audio record across cycles: each presentation `cue.started` can emit another `audio.cue.started`, and `noteCueEnded` runs at the end of a cycle so ducking does not stick after the first loop.
+
+`createRuntime({ audioBroker, audioParticipantId })` authorizes that id, routes mailbox `ASSET_*` events into the broker, and `teardown`s the id on `runtime.destroy()`. `createRuntimeGroup({ audioBroker })` passes each participant id. Carts that only declare `metadata.audio: 'tone'` still unlock on `start()` / `unlockAudio()` when **no** broker is passed.
+
+## `createAudioCueTimeline(options?)` / `scheduleAudioCue`
+
+Composes [`createPresentationTimeline`](presentation-cue.md). Drive `step` from the same clock as deterministic `cart.step`. Duplicate policy, delay, and easing are the presentation cue’s.
+
+```ts
+import {
+  createAudioCueTimeline,
+  scheduleAudioCue,
+  AUDIO_CUE_SCHEDULED_EVENT,
+  AUDIO_CUE_STARTED_EVENT,
+} from '@cyberart-io/engine';
+
+const timeline = createAudioCueTimeline({
+  broker,
+  originFrame: 0,
+  reducedSensory: false,
+});
+
+scheduleAudioCue(timeline, {
+  name: 'overlay',
+  idempotencyKey: 'ripple-overlay',
+  assetId: 'overlay',
+  participantId: 'ambience',
+  channelId: 'ambience',
+  durationFrames: 4,
+  delayFrames: 1,
+  onDuplicate: 'ignore',
+});
+
+timeline.step(6);
+```
+
+`AudioCueSpec` is `CueSpec` plus `assetId` (required), `channelId?`, `participantId?`, `priority?`, `gain?`. `channelId` defaults to `participantId` or `'master'`.
+
+| `onDuplicate` | Effect |
+|---|---|
+| `replace` (presentation default) | Replace the live cue; emit a new `audio.cue.scheduled`. |
+| `ignore` | Keep the existing cue; no second `scheduled`. |
+| `reject` | `{ ok: false, reason: 'duplicate' }`. |
+
+## Cue events (stable names)
+
+| `type` | When |
+|---|---|
+| `audio.cue.scheduled` | `play` / `scheduleAudioCue` accepted |
+| `audio.cue.started` | Presentation start, authorized, not muted, asset ready |
+| `audio.cue.skipped` | Reduced-sensory, muted, or unauthorized (reasons above) |
+| `audio.cue.failed` | Failed audio asset (`asset-failed`) or cart teardown (`torn-down`) |
+
+Each event: `{ type, atFrame, name, idempotencyKey, assetId, channelId, participantId?, reason?, progress }`. Two identical `play` / `step` / asset-event tapes produce identical lists.
+
+A failed `ASSET_FAILED_EVENT` for the cue’s `assetId` emits `audio.cue.failed` and does not wait on I/O. Unknown assets stay scheduled until ready, failed, or the presentation cue completes (then `asset-failed` so `step` cannot hang).
+
+## Headless adapter
+
+Event-only. No Web Audio. Import from **`@cyberart-io/engine/headless`** (also re-exported from `@cyberart-io/engine`).
+
+```ts
+import { createHeadlessAudioAdapter } from '@cyberart-io/engine/headless';
+
+const adapter = createHeadlessAudioAdapter({ originFrame: 0 });
+await adapter.unlock();
+adapter.handleHostEvent({
+  type: 'cyberart.asset.ready',
+  kind: 'state',
+  payload: { id: 'overlay' },
+});
+adapter.play({ /* AudioCueSpec */ });
+adapter.step(4);
+const { events } = adapter.snapshot();
+adapter.destroy();
+```
+
+Replay two runs with the same seed/tape and compare `events`. Do not compare speakers, meters, or decoded PCM — those are not deterministic across machines or browsers.
+
+## Host wiring
+
+```ts
+const broker = createAudioBroker();
+button.addEventListener('click', () => broker.unlock());
+
+const runtime = createRuntime({
+  container,
+  audioBroker: broker,
+  audio: 'tone', // still required for start() to unlock when the cart declares it
+});
+```
+
+`runtime.unlockAudio()` / `cart.start()` call `broker.unlock()` when the cart (or `createRuntime({ audio })` hint) needs audio. A silent cart still never imports Tone.

package/docs/browser-harness.md

@@ -0,0 +1,126 @@
+# Browser / DOM host harness
+
+Opt-in harness that mounts a caller-supplied host into a real viewport, optionally with a runtime group and compositor. It sets viewport / DPR / reduced-motion / input modality, dispatches pointer and keyboard through DOM coordinates, steps a deterministic clock, and captures composed frames plus accessibility HTML.
+
+Import `createBrowserHarness` from **`@cyberart-io/engine`**. It does not load `node:fs`. In Vitest/jsdom, call `installHeadlessCanvas()` from **`@cyberart-io/engine/headless`** first so `Canvas2D` pixels exist. Production Player / kaleidoscope should not call this harness.
+
+Related: [normalized geometry](normalized-geometry.md), [presentation adapter](presentation-adapter.md), [compositor](compositor.md), [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/cyb-63-browser-harness.repro.spec.ts
+```
+
+## Why this exists
+
+`createHeadlessHarness` injects canvas-pixel clicks. It cannot prove a host's DOM overlay, CSS geometry, resize/DPR anchors, focus, or scroll. This harness lets a host mount overlay controls, run its own reducer, route through carts, and compose with `createCompositor` / `captureComposedFrame`. jsdom software Canvas2D is the headless composition path; a Playwright-compatible adapter maps the same scenario API for a later Chromium swap.
+
+Hosts drive the same API with their own overlay markup and event types; those names stay in the host, not in this module.
+
+## `createBrowserHarness(options)`
+
+```ts
+import { createBrowserHarness } from '@cyberart-io/engine';
+import { installHeadlessCanvas } from '@cyberart-io/engine/headless';
+
+installHeadlessCanvas();
+
+const harness = createBrowserHarness({
+  seed: `0x${'00'.repeat(32)}`,
+  viewport: { width: 1280, height: 800, deviceScaleFactor: 1 },
+  geometry,
+  contentWidth: 1920,
+  contentHeight: 1080,
+  mount(ctx) {
+    const hotspot = document.createElement('button');
+    hotspot.id = 'hotspot';
+    ctx.placeRegion('hotspot', hotspot);
+    ctx.root.append(hotspot);
+    return {
+      participants: [overlayA, overlayB],
+      compositor: { layers: [{ id: 'overlay-a', order: 0 }, { id: 'overlay-b', order: 1 }] },
+      ready(runtime) {
+        hotspot.addEventListener('click', () => {
+          runtime.publish({ type: 'host.intent.select', kind: 'intent', payload: { id: 'hotspot' } });
+        });
+      },
+      relayout() {
+        ctx.placeRegion('hotspot', hotspot);
+      },
+      destroy() {
+        hotspot.remove();
+      },
+    };
+  },
+});
+
+harness.goto();
+harness.click('#hotspot');
+await harness.step(1);
+const shot = harness.screenshot();
+const a11y = harness.accessibilitySnapshot();
+const meta = harness.reproduction();
+harness.destroy();
+```
+
+The host owns overlay markup, reducer state, and event type names. The harness owns viewport metrics, DOM input dispatch, the optional group/compositor lifecycle, and cleanup.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `seed` | `0x00…` | Default participant seed when a cart omits one. |
+| `viewport.width` / `height` / `deviceScaleFactor` | `320` / `180` / `1` | CSS viewport and DPR. |
+| `reducedMotion` | `false` | Stubs `matchMedia('(prefers-reduced-motion: reduce)')`. |
+| `inputModality` | `'pointer'` | Recorded on the root (`data-input-modality`). |
+| `geometry` | none | Optional geometry document for `placeRegion` / CSS hit-testing. |
+| `contentWidth` / `contentHeight` / `fit` | viewport / `contain` | Intrinsic box for `createPresentationLayout`. |
+| `mount` | none | Host builds DOM and returns carts / compositor / cleanup. |
+
+### Handle (Playwright-shaped names)
+
+| Member | Meaning |
+|---|---|
+| `goto()` | No-op ready check (fixture is already mounted). |
+| `setViewport(width, height, dpr?)` | Resize root, group canvases, compositor; call host `relayout`. |
+| `click(selector)` / `click(x, y)` | Dispatch `pointerdown` / `pointerup` / `click` on DOM. |
+| `key` / `focus` | Keyboard through the focused element. |
+| `step` / `advance` | Deterministic group clock. |
+| `screenshot` | `captureComposedFrame()` plus `root.outerHTML` when a compositor is mounted. |
+| `accessibilitySnapshot` | Focus, `aria-live` text, HTML. |
+| `reproduction` | Seed, viewport, DPR, reduced-motion, modality, action tape. |
+| `destroy` | Host cleanup, group, compositor, listeners; blur focus; restore `matchMedia` / DPR. |
+
+## Playwright-compatible adapter (no Playwright dependency)
+
+`@playwright/test` is **not** an engine dependency. CI can wrap the same harness:
+
+```ts
+import { createBrowserHarness, createPlaywrightCompatibleAdapter } from '@cyberart-io/engine';
+
+const harness = createBrowserHarness({ viewport: { width: 390, height: 844 }, mount });
+const page = createPlaywrightCompatibleAdapter(harness);
+
+await page.goto();
+await page.setViewportSize({ width: 390, height: 844, deviceScaleFactor: 2 });
+await page.click('#hotspot');
+const shot = await page.screenshot();
+await page.close();
+```
+
+| Playwright `Page` | This adapter |
+|---|---|
+| `goto(url)` | `harness.goto()` (host already mounted) |
+| `setViewportSize` | `harness.setViewport` |
+| `click(selector)` | DOM click at the element's CSS box |
+| `screenshot()` | Composed `ImageData` + HTML (not a Chromium PNG) |
+| `keyboard.press` | `harness.key` |
+| `locator(sel).click` | Same DOM click |
+| `close()` | `harness.destroy()` |
+
+To run the same scenario in Chromium later, keep these method names and swap the adapter body for `chromium.launch()` + `page.goto(hostUrl)` without changing tests.
+
+Visual diffs stay on `assertPixelsEqual` / `compareImageData`. Do not add a second screenshot library.

package/docs/capability-manifest.md

@@ -39,14 +39,14 @@ import {
 } from '@cyberart-io/engine';
 
 const defined = defineCapabilityManifest({
-  id: 'adventure.presentation',
+  id: 'host.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.*'] },
+  assets: { kinds: ['image'], declarations: [{ id: 'backdrop', kind: 'image' }] },
+  acceptedEvents: ['host.state.*'],
+  emittedEvents: ['host.intent.exit-requested'],
+  permissions: { emit: ['host.intent.*'], subscribe: ['host.state.*'] },
   integrations: ['tone'],
 });
 if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
@@ -55,8 +55,8 @@ const host = {
   contractVersion: 1,
   features: ['router'],
   integrations: ['tone'] as const,
-  emit: ['adventure.intent.*'],
-  subscribe: ['adventure.state.*'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*'],
 };
 
 const check = validateCapabilityManifest(defined.manifest, host);
@@ -82,3 +82,14 @@ const parsed = parseCapabilityManifest(JSON.stringify(defined.manifest));
 | `missing-integration` | Host does not provide `tone` / `midi` as required. |
 | `missing-manager` | Host listed `managers` but omitted one the cart requires. |
 | `unknown-permission` | Cart emit/subscribe permission is not on the host allowlist (only if host listed `emit` / `subscribe`). |
+| `invalid-surface` / `invalid-clear-policy` / `invalid-blend` | Cart or host `surface` / `layers` values are the wrong shape or not in the allowlist. |
+| `unsupported-surface` / `unsupported-layer` | Host omitted `surface.alpha` / `clearPolicy` or compositor blend modes the cart requires. |
+
+Optional additive keys (omitted on existing carts):
+
+```ts
+surface: { alpha: true, clearPolicy: 'transparent' }
+layers: { compositor: true, blend: ['source-over', 'screen'] }
+```
+
+See [compositor](compositor.md).

package/docs/compositor.md

@@ -0,0 +1,103 @@
+# Compositor
+
+Transparent multi-cart compositor. Reads each runtime-group canvas with `getImageData`, blends onto a host image (or a transparent clear), and records declared layer order for headless capture. Hosts should not invent CSS `screen` hacks for black-backed carts.
+
+Related: [runtime group](runtime-group.md), [headless harness](headless-harness.md), [capability manifest](capability-manifest.md).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-64-compositor.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createCompositor` from `@cyberart-io/engine` | Stack a host image under participant canvases (effects, overlays, debug). |
+| Vitest / jsdom | same compositor after `installHeadlessCanvas()` | Headless `captureComposedFrame()` / `writeComposedFrame`. |
+
+Browser vs headless pixel agreement is covered by the [browser harness](browser-harness.md). This module still emits a headless capture that includes `declaredOrder`.
+
+## `createCompositor(options)`
+
+```ts
+import { createCompositor, createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  participants: [baseCart, overlayCart],
+});
+const compositor = createCompositor({
+  group,
+  width: 320,
+  height: 180,
+  dpr: 1,
+  host: { image: backdropImageData },
+  clearPolicy: 'transparent',
+  layers: [
+    { id: 'overlay-a', order: 0, blend: 'source-over' },
+    { id: 'overlay-b', order: 1, blend: 'screen' },
+  ],
+});
+
+await group.step(1);
+const frame = compositor.captureComposedFrame();
+// frame.declaredOrder is the compose list; frame.imageData is the stack.
+compositor.destroy();
+```
+
+Typical stack: host image, then opaque overlay carts (`source-over`), then additive layers (`screen` so RGB `0,0,0` backing is identity unless `clearPolicy: 'transparent'` knocks it out). Later `order` values draw on top.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `group` | required | `createRuntimeGroup` handle. |
+| `layers` | required | One entry per participant id. Sorted by `order`, then id. |
+| `width` / `height` / `dpr` | `320` / `180` / `1` | Shared viewport. `resize` updates the group canvases. |
+| `host.image` / `host.color` | none | Back layer. Color is `#rgb` / `#rrggbb`. |
+| `clearPolicy` | `transparent` | Host surface starts clear (never filled black). Per-layer transparent policy knocks out RGB `0,0,0` backing pixels on opaque cart canvases. |
+| `offscreen` | `true` | Compose into a compositor-owned canvas when `target` is omitted. `false` requires `target`. A provided `target` is never destroyed. |
+
+### Layer fields
+
+| Field | Default | Meaning |
+|---|---|---|
+| `id` | required | Runtime-group participant id. |
+| `order` | required | Lower draws first. |
+| `visible` | `true` | Skip compose and pointer hits when false. |
+| `opacity` | `1` | 0..1. |
+| `blend` | `source-over` | Also `screen` (in-engine; same modes as `CAPABILITY_BLEND_MODES`). |
+| `clip` | none | Pixel rect; compose and pointer hits are clipped. |
+| `pointerEvents` | `auto` | `none` skips hit testing and sets `canvas.style.pointerEvents`. |
+| `clearPolicy` | compositor default | `transparent` knocks out black backing. |
+
+### Handle
+
+| Member | Meaning |
+|---|---|
+| `compose()` | Blend host + visible layers; returns `ImageData`. |
+| `captureComposedFrame()` | `{ imageData, pngDataUrl, declaredOrder, width, height }`. |
+| `resize(w, h, dpr?)` | Shared viewport; calls `group.resize` on the buffer size. Order/blend survive `group.step`. Carts that cache `DimensionContext` should `group.reset()` after a size change. |
+| `setLayer` / `layer` / `layers` | Mutate / inspect declarative settings. |
+| `pointerTarget(x, y)` | Top-most visible layer with `pointerEvents: 'auto'` under the pixel. |
+| `unmountLayer(id)` | `group.detach(id)` without clearing sibling canvases. |
+| `inspect()` | Viewport, clear policy, layers, `declaredOrder` ids. |
+| `destroy()` | Drops the host canvas only if the compositor created it. Does not destroy the group. |
+
+`group.step` isolates per-cart update/render throws so a failing layer does not blank siblings.
+
+Node tests that need a PNG file: `writeComposedFrame(compositor, path)` from `@cyberart-io/engine/headless`.
+
+## Capability keys (additive)
+
+Optional manifest fields, omitted on existing carts:
+
+```ts
+surface: { alpha: true, clearPolicy: 'transparent' }
+layers: { compositor: true, blend: ['source-over', 'screen'] }
+```
+
+`validateCapabilityManifest` reports `unsupported-surface` / `unsupported-layer` when the host does not list matching `surface` / `layers`. Carts that omit the keys keep the previous host check.

package/docs/deterministic-mode.md

@@ -2,7 +2,7 @@
 
 Host-controlled time, input, and asset completion so two runs with the same seed, actions, and `step` count match. Production kaleidoscope / Art Blocks **leave `deterministic` unset** (rAF, `performance.now()`, token hash).
 
-CI should use the [headless harness](headless-harness.md) on this path, not a mock engine. Router hosts: [events](events.md).
+CI should use the [headless harness](headless-harness.md) on this path, not a mock engine. Router hosts: [events](events.md). Frame-local effects: [presentation cue](presentation-cue.md) (`timeline.step` beside `cart.step`).
 
 Back to the [package README](../README.md).
 

package/docs/events.md

@@ -1,6 +1,6 @@
 # Events and router
 
-Mailbox (one runtime) and `createEventRouter` (many carts). Prefer `createRuntimeGroup` when several carts should share one router and lockstep clock. 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`), [runtime group](runtime-group.md), [capability manifest](capability-manifest.md).
+Mailbox (one runtime) and `createEventRouter` (many carts). Prefer `createRuntimeGroup` when several carts should share one router and lockstep clock. 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), [runtime group](runtime-group.md), [capability manifest](capability-manifest.md), [replay inspector](replay-inspector.md).
 
 Back to the [package README](../README.md).
 
@@ -16,7 +16,7 @@ pnpm exec vitest run packages/engine/src/canvas/cyb-59-event-contract.repro.spec
 | 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. |
+| Router | Several carts, host reducer in the middle, Dotted-name intent vs state. |
 | Runtime group | Same router plus lockstep `step`, pause/reset/teardown, and a routed trace. |
 
 `createRuntime` does **not** attach a router. Attach `runtime.hostChannel` yourself, or use `createRuntimeGroup()` which calls `router.attach(id, runtime.hostChannel, options)` for each participant. Cart unload clears the inbound queue only; router listeners stay until `runtime.destroy()` (or `group.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.
@@ -53,7 +53,7 @@ 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`. |
+| `type` | emitter | Dotted name, e.g. `host.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`). |
@@ -68,13 +68,69 @@ 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 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.
-
-Typed contracts (`defineIntent`, `defineStateEvent`, `defineDiagnostic`) fail at definition time with structured `{ ok: false, errors }` instead of throwing. `createContractRegistry` produces manifest JSON and a `validate` hook for `createEventRouter`. `deriveAttachOptions` / `verifyAttachOptions` keep non-authoritative carts from emitting `state` / `diagnostic` contracts. Payload schema versioning: adding optional fields with a version bump is backward-compatible; removals, type changes, and version downgrades are breaking.
+- Else the first dotted segment of `type` that is `intent`, `state`, or `diagnostic` (not necessarily the second segment — `host.presentation.intent.cue-started` is an intent).
+- Else `malformed` (`cannot infer kind`). `host.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('host.intent.exit-requested', {
+  version: 1,
+  fields: { exitId: { type: 'string' } },
+});
+const room = defineStateEvent('host.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'));
+```
+
+`host.presentation.cue.started` has no `intent` / `state` / `diagnostic` segment, so `inferEventKind` returns undefined and `defineIntent` returns `{ ok: false, errors }` with `kind-mismatch`. Use `host.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 (`host.presentation.intent.*`) |
+
+Default router `emit: ['*.intent.*']` is **three** segments. Four-segment names such as `host.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
@@ -87,13 +143,13 @@ const router = createEventRouter({
 });
 
 router.attach('presentation', runtime.hostChannel, {
-  emit: ['adventure.intent.*'],
-  subscribe: ['adventure.state.*', 'cyberart.diagnostic.rejected'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*', 'cyberart.diagnostic.rejected'],
 });
 
-router.subscribe(['adventure.intent.*'], (event) => {
+router.subscribe(['host.intent.*'], (event) => {
   router.publish(
-    { type: 'adventure.state.room-changed', kind: 'state', payload: { roomId: 'brook' } },
+    { type: 'host.state.room-changed', kind: 'state', payload: { sceneId: 'beta' } },
     { cause: event },
   );
 });
@@ -116,6 +172,7 @@ router.turn(); // once per step / frame
 | `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). |
+| `maxDecisions` | `256` | Bound on `inspectDecisions()` (oldest dropped). |
 
 ### Router methods (`EventRouter`)
 
@@ -125,8 +182,13 @@ router.turn(); // once per step / frame
 | `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. |
+| `subscribeDecision(listener)` | Routing decisions: accepted, rejected, duplicate. |
+| `inspectParticipants()` | Attached id / emit / subscribe / authoritative. |
+| `inspectDecisions()` | Copy of the bounded decision log. |
 | `turn()` | Reset per-turn budgets and the auto-link causation cursor. Idempotency records **survive**. Call once per `step`. |
 
+Causation trees and tape replay: [replay inspector](replay-inspector.md).
+
 ### `AttachOptions`
 
 | Option | Default | Meaning |
@@ -135,7 +197,7 @@ router.turn(); // once per step / frame
 | `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`.
+Patterns are dotted segments; `*` matches one segment. `host.intent.*` matches `host.intent.exit-requested`, not `host.intent.exit.requested`.
 
 ## Delivery and ordering
 
@@ -148,7 +210,7 @@ Cart-to-cart still goes through the router:
 
 ```ts
 presentationChannel.emit({
-  type: 'adventure.intent.remark',
+  type: 'host.intent.remark',
   target: 'npc',
   payload: { text: 'Anyone there?' },
   idempotencyKey: 'hello-1',