@cyberart-io/engine 0.0.2 → 0.0.4

package/docs/events.md

@@ -1,24 +1,32 @@
 # 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`).
+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).
 
 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. |
+| Runtime group | Same router plus lockstep `step`, pause/reset/teardown, and a routed trace. |
 
-`createRuntime` does **not** attach a router. You attach each cart’s channel yourself.
+`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.
 
 ## Mailbox (`HostChannel`)
 
 ```ts
 import { HostChannel, type HostEvent } from '@cyberart-io/engine';
 
-// Usually you do not construct this. createRuntime owns one; mount({ onEvent }) listens.
+// 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
@@ -32,7 +40,9 @@ hostChannel.emit({ type: 'art-project.theme', payload: 'dusk' }); // cart → ho
 | `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. |
-| `clear()` | Drop inbound queue and listeners. |
+| `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`.
 
@@ -58,15 +68,17 @@ 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 second dotted segment of `type` if it is `intent`, `state`, or `diagnostic`.
-- Else `malformed` (`cannot infer kind`).
+- 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.
 
 Only the host (`publish`) or an `authoritative` participant may emit `state` / `diagnostic`. Carts emit allowed `intent` patterns. Domain data belongs in `payload`.
 
 ## `createEventRouter(options?)`
 
 ```ts
-import { createEventRouter, HostChannel } from '@cyberart-io/engine';
+import { createEventRouter } from '@cyberart-io/engine';
 
 const router = createEventRouter({
   now: () => cart.getClock().now,
@@ -74,7 +86,7 @@ const router = createEventRouter({
   validate: (event) => true, // or { reason: 'host-rejected', detail: '…' }
 });
 
-router.attach('presentation', presentationChannel, {
+router.attach('presentation', runtime.hostChannel, {
   emit: ['adventure.intent.*'],
   subscribe: ['adventure.state.*', 'cyberart.diagnostic.rejected'],
 });

package/docs/headless-harness.md

@@ -2,14 +2,25 @@
 
 CI / agent wrapper around production `createRuntime({ deterministic })`. Not a second engine. Do not call this from Player or kaleidoscope.
 
-Depends on [deterministic mode](deterministic-mode.md). Host reducers: [events](events.md).
+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). Several carts: [runtime group](runtime-group.md) (`createHeadlessMultiCartHarness`).
 
 Back to the [package README](../README.md).
 
+## Migration
+
+| Surface | Import |
+|---|---|
+| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, assets, presentation adapter) |
+| Vitest / jsdom / CI capture | `@cyberart-io/engine/headless` (`createHeadlessHarness`, `createHeadlessMultiCartHarness`, `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
+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).
@@ -22,7 +33,7 @@ import {
   HEADLESS_PNG_DATA_URL,
   DEFAULT_HEADLESS_WIDTH,
   DEFAULT_HEADLESS_HEIGHT,
-} from '@cyberart-io/engine';
+} from '@cyberart-io/engine/headless';
 
 installHeadlessCanvas();
 ```
@@ -34,7 +45,7 @@ Mutates `HTMLCanvasElement.prototype`: `ImageData` polyfill (width/height constr
 ## `createHeadlessHarness(options)`
 
 ```ts
-import { createHeadlessHarness } from '@cyberart-io/engine';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
 
 const harness = createHeadlessHarness({
   cart: artProject,
@@ -44,7 +55,7 @@ const harness = createHeadlessHarness({
   origin: 0,
   actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
   initialState: { room: 'glade' },
-  gameManager: hostAdapter, // existing mount injection; not a new adapter contract
+  gameManager: hostAdapter, // site injection; presentation overlay is attachPresentationAdapter
   onEvent: (event) => {},
   onError: (error, info) => {},
 });
@@ -77,6 +88,7 @@ Always sets `deterministic: { origin, actions }`.
 | `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()`. |
@@ -112,32 +124,62 @@ Returns `CartSnapshot`: `{ seed, metadata?, pngDataUrl }`.
 ## Interaction loop (agent recipe)
 
 ```ts
+import {
+  attachPresentationAdapter,
+  createReferencePresentationCart,
+} from '@cyberart-io/engine';
+import { createHeadlessHarness } from '@cyberart-io/engine/headless';
+
 const harness = createHeadlessHarness({
-  cart,
+  cart: createReferencePresentationCart(),
   seed: 42,
-  gameManager: adapter,
-  actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
 });
+const adapter = attachPresentationAdapter(harness);
 
-await harness.step(5);
+await harness.step(1);
 const canvas = harness.cart.canvas!;
-harness.click(canvas.width / 2, canvas.height * 0.1); // canvas pixels
+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, state } = await harness.inspect();
-// assert exactly one intent, e.g. room.exit.requested
+const { events } = await harness.inspect();
+// assert exactly one adventure.intent.exit-requested; cart state is still Glade
 
-harness.dispatch({
-  type: 'adventure.state.room-changed',
-  payload: { roomId: 'brook' },
+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.
+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
 

package/docs/normalized-geometry.md

@@ -0,0 +1,88 @@
+# Normalized geometry
+
+Shared 0–1 content-box coordinates, anchors, hit regions, and resize-stable
+contain/cover/crop layouts. Pixel `PresentationRegion` on the presentation
+adapter is unchanged; hosts can adopt this contract later.
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-60-normalized-geometry.repro.spec.ts
+```
+
+## Contract (`GEOMETRY_CONTRACT_VERSION = 1`)
+
+| Field | Meaning |
+|---|---|
+| `version` | Always `1`. Other versions fail `validateGeometry`. |
+| `landmarks` | Named anchors (`id` + normalized point + optional origin keyword). |
+| `regions` | Hitboxes: axis-aligned `rect` and/or `polygon` in normalized space. |
+| `padding` | Normalized insets `{ top, right, bottom, left }`. |
+| `safeArea` | Same inset shape; authoring hint, not applied by the layout math. |
+
+Documents are JSON-serializable (`JSON.parse(JSON.stringify(doc))` round-trips). Import from **`@cyberart-io/engine`** (`createPresentationLayout`, `pointerToRegion`, `serializeGeometry`, …).
+
+If a region sets both `rect` and `polygon`, hit-testing uses the polygon and overlay/AABB helpers use the rect. Prefer one shape per region.
+
+## Coordinate spaces
+
+Normalized is **0–1 of the content box** (intrinsic artwork), not the letterboxed viewport.
+
+| Space | Unit | Box |
+|---|---|---|
+| `normalized` | 0–1 | Full content (`contentWidth` × `contentHeight`) |
+| `asset` | px | Same content, intrinsic pixels |
+| `css` / `viewport` | CSS px | Layout (`viewportWidth` × `viewportHeight`) |
+| `canvas` | buffer px | `css * devicePixelRatio` (default dpr `1`) |
+
+`pointerToRegion` defaults to **canvas** space (same as `PointerManager` / harness `click`). Pass `{ space: 'css' }` for layout pixels.
+
+## Layout (`createPresentationLayout`)
+
+```ts
+import { createPresentationLayout } from '@cyberart-io/engine';
+
+const layout = createPresentationLayout({
+  contentWidth: 1920,
+  contentHeight: 1080,
+  viewportWidth: 1280,
+  viewportHeight: 800,
+  mode: 'contain', // or 'cover' | 'crop'
+});
+```
+
+| Mode | Scale | Offsets |
+|---|---|---|
+| `contain` | `min(vw/cw, vh/ch)` | Letterbox ≥ 0 |
+| `cover` | `max(vw/cw, vh/ch)` | Crop ≤ 0 (centered) |
+| `crop` | Same as `cover` | Same as `cover` |
+
+Resize-stable under **contain**: a normalized point stays on the same content location when only the viewport changes. Cover/crop keep the content centered and report `visibleNormalizedRect` for the uncropped slice.
+
+## Round-trip tolerance
+
+| Constant | Value | Use |
+|---|---|---|
+| `ROUND_TRIP_TOLERANCE` | `1e-6` | Max \|Δ\| in normalized units after canvas/css round-trip |
+| `ROUND_TRIP_TOLERANCE_CANVAS_PX` | `0.5` | Max \|Δ\| in canvas pixels after normalized round-trip |
+
+## Helpers
+
+| Export | Role |
+|---|---|
+| `normalizedToCanvas` / `canvasToNormalized` | Content box ↔ drawing buffer |
+| `normalizedToCss` / `cssToNormalized` | Content box ↔ layout pixels |
+| `normalizedToAsset` / `assetToNormalized` | Content box ↔ intrinsic pixels |
+| `pointerToRegion(pointer, layout, doc)` | First matching region (document order) |
+| `regionToViewport(region, layout)` | CSS rect (polygon AABB) |
+| `createLandmarkRegistry()` | `register` / `get` / `list`; duplicate ids → `{ ok: false, error: 'duplicate-id' }` |
+| `validateGeometry(doc)` | Overlap, out-of-bounds, duplicate id, invalid shape; diagnostics include region ids |
+| `drawGeometryDebug(ctx, layout, doc, diagnostics)` | Canvas2D `fillRect` / `strokeRect` / `fillText` when present; always returns recorded calls with region ids |
+
+Origin keywords: `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `top`, `bottom`, `left`, `right`. `pointFromOrigin` yields the matching unit-square point.
+
+## Fixture (CYB-60)
+
+Content **1920×1080**. Hotspot point `(0.25, 0.4)` inside region `hotspot` `{ x: 0.2, y: 0.35, width: 0.1, height: 0.1 }`. Contain viewports **1280×800** and **390×844**.

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). Normalized 0–1 regions: [normalized geometry](normalized-geometry.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 on `PresentationRegion` are drawing-space pixels, the same space as `PointerManager` and harness `click`. Convert 0–1 content-box geometry with `createPresentationLayout` / `pointerToRegion` from [normalized geometry](normalized-geometry.md).
+
+`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`.

package/docs/presentation-cue.md

@@ -0,0 +1,82 @@
+# Presentation cue / timeline
+
+Deterministic cue/effect primitive. Carts call `step(frames)` with the same clock they use for CYB-23; there are no `setTimeout` / rAF timers. Gold checkmarks, ripples, room transitions, weather pulses, and NPC beats should share this lifecycle instead of ad-hoc frame counters.
+
+Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-58-presentation-cue.repro.spec.ts
+```
+
+## `createPresentationTimeline(options?)`
+
+```ts
+import {
+  createPresentationTimeline,
+  CUE_STARTED_EVENT,
+  CUE_COMPLETED_EVENT,
+  CUE_CANCELLED_EVENT,
+  CUE_REPLACED_EVENT,
+} from '@cyberart-io/engine';
+
+const timeline = createPresentationTimeline({
+  originFrame: 0,
+  reducedMotion: false, // host flag, not a CSS media query
+});
+
+timeline.play({
+  name: 'checkmark',
+  idempotencyKey: 'gold',
+  durationFrames: 90,
+  delayFrames: 0,
+  easing: 'ease-out', // or 'linear'
+  repeat: { count: 0 },
+  reducedMotion: 'complete', // 'skip' | 'complete' | { durationFrames: n }
+  onDuplicate: 'replace', // 'ignore' | 'replace' | 'reject'
+});
+
+timeline.step(90);
+```
+
+| Member | Meaning |
+|---|---|
+| `play(spec)` | Schedule or start a cue. `{ ok: true, cue }` or `{ ok: false, reason: 'duplicate' \| 'invalid' }`. |
+| `step(frames?)` | Advance the frame index (default 1). Returns lifecycle events emitted during those frames. |
+| `cancel(key)` | Cancel an active/scheduled cue (`cue.cancelled`). |
+| `reset()` | Cancel remaining cues, drop dedupe, rewind to `originFrame`, clear the event log. |
+| `snapshot()` | JSON-serializable `{ frame, reducedMotion, cues, events }`. |
+| `get(key)` | Copy of the live cue, or `undefined`. |
+
+`startFrame` defaults to the play frame. If `play` happens after `startFrame + delayFrames`, the timeline catches up on that call: mid-cue progress is applied, and a cue whose duration is already over completes immediately (`cue.started` then `cue.completed`). Progress is `0…1` after easing. `step` ignores non-finite counts (no infinite loop). Two identical `play` / `step` tapes produce identical snapshots.
+
+## Duplicate policy
+
+Keyed by `idempotencyKey` among scheduled and active cues.
+
+| `onDuplicate` | Effect |
+|---|---|
+| `replace` (default) | Emit `cue.replaced` for the old cue, start the new spec. |
+| `ignore` | Keep the existing cue. |
+| `reject` | `{ ok: false, reason: 'duplicate' }`. Unrelated cues keep running. |
+
+## Reduced motion
+
+Pass `reducedMotion: true` on the timeline (host-owned). Per-cue `reducedMotion`:
+
+- `complete` / `skip` — duration 0; `cue.started` then `cue.completed` at the play frame
+- `{ durationFrames: n }` — use `n` instead of the authored duration
+
+## Lifecycle events (stable names)
+
+| `type` | When |
+|---|---|
+| `cue.started` | Cue becomes active |
+| `cue.completed` | Duration elapsed (or reduced-motion complete) |
+| `cue.cancelled` | `cancel` or `reset` |
+| `cue.replaced` | Duplicate with `replace` |
+
+Each event: `{ type, atFrame, name, idempotencyKey, progress }`. Repeat `{ count: n }` restarts immediately after complete (`repeatIndex` increments). `{ forever: true }` with `durationFrames: 0` completes once (no infinite loop).
+
+Do not `await` wall-clock time inside cart `update` / `render`. Drive the timeline from `cart.step` / `getClock().framesElapsed`.

package/docs/runtime-group.md

@@ -0,0 +1,120 @@
+# Runtime group
+
+Host helper that mounts several production `createRuntime` carts, attaches each mailbox with `router.attach(id, runtime.hostChannel, attachOptions)`, and locksteps one shared deterministic clock. Carts never receive the router. Not a second engine. Do not call the headless wrapper from Player or kaleidoscope.
+
+Capability-manifest integration is optional and structural (`capability?: { emit, subscribe, authoritative }`). This module does not import the manifest.
+
+Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-61-runtime-group.repro.spec.ts
+```
+
+## When to use which
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createRuntimeGroup` from `@cyberart-io/engine` | Several carts in one page; host injects containers or lets the group create them. |
+| Vitest / jsdom | `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` | Same group API after `installHeadlessCanvas()`. |
+
+`createRuntime` still does **not** attach a router by itself. The group is the attach + lockstep layer.
+
+## `createRuntimeGroup(options)`
+
+```ts
+import { createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  origin: 0,
+  createId: (() => {
+    let n = 0;
+    return () => `g-${++n}`;
+  })(),
+  participants: [
+    {
+      id: 'effects',
+      cart: effectsCart,
+      seed: `0x${'61'.repeat(32)}`,
+      emit: ['ambience.intent.*'],
+      subscribe: ['adventure.state.*'],
+    },
+    {
+      id: 'ambience',
+      cart: ambienceCart,
+      kind: 'render',
+      seed: `0x${'62'.repeat(32)}`,
+      subscribe: ['ambience.intent.*'],
+    },
+  ],
+});
+
+group.publish({
+  type: 'adventure.state.loon-whistle',
+  kind: 'state',
+  payload: { habitat: 'pond' },
+});
+await group.step(2);
+const { participants, trace, diagnostics } = await group.inspect();
+group.destroy();
+```
+
+Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.state.loon-whistle` is consumed by the effects cart, which emits `ambience.intent.play`; the router delivers that cue to the ambience cart. No project-specific bridge.
+
+### Options (`CreateRuntimeGroupOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `participants` | required | One entry per cart. Ids must be unique. Sorted lexicographically for lockstep. |
+| `origin` | `0` | Passed to every `createRuntime({ deterministic: { origin } })`. |
+| `width` / `height` | `320` / `180` | Used when the group creates a container. |
+| `createId` / `now` | `evt-1`… / first cart clock | Injected into the **one** shared router. |
+| `validate` | none | Router `validate` for cart-originated events. |
+| `router` | `{}` | Extra `createEventRouter` options (`maxHops`, `maxPerTurn`, …). |
+
+### Participant config
+
+| Field | Meaning |
+|---|---|
+| `id` | Router participant id. Reserved: `host`, `router`. |
+| `cart` | `AnimationCart` mounted through `createRuntime`. |
+| `kind` | `'render'` (default) or `'calculation'` (no-op/minimal render; still a real cart). |
+| `seed` | `0x` + 64 hex, or any seed `createRuntime` accepts. Default: derived from `id`. |
+| `container` | Injected mount node. If omitted, the group creates and owns a sized `div`. |
+| `emit` / `subscribe` / `authoritative` | Passed to `router.attach`. |
+| `capability` | Structural fallback for those three fields when the explicit ones are omitted. |
+| `initialState` / `gameManager` / `onEvent` | `mount` options. The group still records outbound events. |
+
+### Handle (`RuntimeGroup`)
+
+| Member | Meaning |
+|---|---|
+| `router` | The shared `EventRouter`. Do not create a second one. |
+| `step(n)` | For each frame: `router.turn()` once, then `await cart.step(1)` in sorted id order. No-op while paused. Throws after `destroy()`. |
+| `pause` / `resume` | Group flag plus every cart. `step` does not advance while paused. |
+| `reset` | Remounts every cart to its initial state, clears traces / logs, `router.turn()`. Does not change `paused`; call `resume()` if you need lockstep after a paused reset. |
+| `dispatch(id, event)` | Mailbox inbound on that participant. |
+| `publish(event)` | Host `router.publish`. Unknown `target` → `unknown-target` rejection. |
+| `inspect()` | `{ participants: Record<id, { state, events, errors, kind, clock }>, trace, diagnostics }`. |
+| `destroy()` | Detach router listeners, `runtime.destroy()` each cart, remove owned containers. Idempotent. |
+
+Idempotency, correlation, causation, unauthorized emit, hop/loop checks are the existing router. The group only attaches and locksteps.
+
+## `createHeadlessMultiCartHarness(options)`
+
+```ts
+import { createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless';
+
+const harness = createHeadlessMultiCartHarness({
+  participants: [effects, ambience, telemetry],
+});
+await harness.step(2);
+harness.destroy();
+```
+
+Calls `installHeadlessCanvas()` then `createRuntimeGroup`. Same handle. Three-cart CI fixture: effects + ambience + a calculation telemetry cart.
+
+Cleanup: `afterEach(() => group.destroy())` so a failed assertion does not leak nodes. After `destroy`, `step` throws and owned containers are gone from `document.body`.