@cyberart-io/engine 0.0.4 → 0.0.6

package/docs/executable-modules.md

@@ -0,0 +1,112 @@
+# Executable modules
+
+Trusted, versioned factories behind a host allowlist. The engine never `eval`s or `new Function`s untrusted strings. Unknown ids, wrong versions, and unauthorized refs fail closed without invoking. A throwing module does not stop the next allowlisted call.
+
+Related: [capability manifest](capability-manifest.md) (`modules.refs`).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-27-executable-module.repro.spec.ts
+```
+
+## `createExecutableModuleHost(options)`
+
+```ts
+import { createExecutableModuleHost } from '@cyberart-io/engine';
+
+const overlayCalls = { n: 0 };
+const host = createExecutableModuleHost({
+  allowlist: [
+    { id: 'overlay-fx', version: '1.0.0' },
+    { id: 'host.module', version: '1.0.0' },
+  ],
+  limits: { maxInvokeMs: 16, maxInvokesPerTurn: 4 },
+  capabilities: { seed: '0x27' },
+  modules: [
+    {
+      id: 'overlay-fx',
+      version: '1.0.0',
+      create: (capabilities) => ({
+        invoke: (input, { signal }) => {
+          if (signal.aborted) return;
+          overlayCalls.n += 1;
+          return { seed: capabilities.seed, input };
+        },
+      }),
+    },
+    {
+      id: 'host.module',
+      version: '1.0.0',
+      create: () => ({
+        invoke: () => {
+          throw new Error('host.module boom');
+        },
+      }),
+    },
+  ],
+});
+
+const allowed = await host.invoke({ id: 'overlay-fx', version: '1.0.0' }, { tape: 'cyb-27' });
+// allowed.ok === true — overlay-fx ran
+
+await host.invoke({ id: 'leak.module', version: '1.0.0' });
+// { ok: false, error: { code: 'unknown-module' | 'not-allowlisted' } }
+
+await host.invoke({ id: 'overlay-fx', version: '2.0.0' });
+// { ok: false, error: { code: 'version-mismatch' } } — factory is not called
+
+const boom = await host.invoke({ id: 'host.module', version: '1.0.0' });
+// boom.error.code === 'invoke-failed'; overlay-fx still runs next:
+await host.invoke({ id: 'overlay-fx', version: '1.0.0' });
+
+host.beginTurn();
+host.destroy();
+```
+
+Register only trusted `create` functions you compiled with the host. Carts declare required refs on the capability manifest; they do not ship source strings into this API.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `allowlist` | required | `{ id, version }[]`. `id` may be a dotted segment pattern (`host.*`). **Version is always exact** — `*` never loads. |
+| `modules` | required | Trusted factories keyed by exact `id` + `version`. Duplicate refs throw. |
+| `limits.maxInvokeMs` | none | Cooperative timeout. `invoke` receives `AbortSignal`; hanging thenables fail with `timeout`. |
+| `limits.maxInvokesPerTurn` | none | Allowlisted invoke budget. Reset with `beginTurn()`. |
+| `capabilities` | `{}` | Frozen bag passed into each factory. Nested plain objects are frozen; class instances stay shared handles. |
+
+Per-registration `capabilities` overlay the host bag, then the result is frozen.
+
+### Handle
+
+| Member | Meaning |
+|---|---|
+| `load(ref)` | Instantiate the factory if the exact ref is registered and allowlisted. Idempotent. |
+| `invoke(ref, input?)` | `load` if needed, then call `invoke`. Returns `{ ok: true, value }` or `{ ok: false, error }`. |
+| `beginTurn()` | Increment the turn counter and reset `maxInvokesPerTurn`. |
+| `inspect()` | Allowlist, registered/loaded refs, turn, diagnostics. |
+| `destroy()` | Drop the registry, abort in-flight signals, call optional instance `destroy()`. Idempotent. |
+
+`error.code` is one of: `invalid-ref`, `unknown-module`, `version-mismatch`, `not-allowlisted`, `load-failed`, `invoke-failed`, `timeout`, `rate-limited`, `destroyed`. Failures are recorded on `inspect().diagnostics`. Sibling modules and the cart continue.
+
+## Isolation
+
+This boundary is **in-process**. Factories run on the cart’s thread; there is no worker, iframe, or separate origin. Isolation is the allowlist, exact id+version matching, a frozen capability bag, invoke budgets, and `{ ok: false }` on throw so a sibling can still run. Do not pass untrusted source strings. Untrusted code needs a host-owned worker/iframe **outside** this API.
+
+## Capability manifest
+
+Optional additive key (omitted on existing carts):
+
+```ts
+modules: {
+  refs: [
+    { id: 'overlay-fx', version: '1.0.0' },
+    { id: 'host.module', version: '1.0.0' },
+  ],
+}
+```
+
+`validateCapabilityManifest` returns `unsupported-module` when the host does not list a required exact ref on `host.modules.refs`.

package/docs/headless-harness.md

@@ -12,7 +12,7 @@ Back to the [package README](../README.md).
 
 | Surface | Import |
 |---|---|
-| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, assets, presentation adapter) |
+| Carts, Player, kaleidoscope, `/art` | `@cyberart-io/engine` (`createRuntime`, events, contracts, assets, presentation adapter, presentation cue, capability manifest, geometry, runtime group) |
 | 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`.
@@ -38,10 +38,38 @@ import {
 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.**
+Mutates `HTMLCanvasElement.prototype`: `ImageData` polyfill (width/height and `ImageData(data, w, h)`), software `getContext('2d')` (paths, arcs, text via a glyph atlas, transforms, clip, alpha, source-over, linear/radial gradients, `drawImage` from ImageData / headless canvas / `createImageFixture`), `toDataURL` encodes those pixels as PNG. `HEADLESS_PNG_DATA_URL` remains a 1×1 compatibility export for callers that never attached a context. Idempotent. **Do not call from production playback.**
 
 `createHeadlessHarness` calls this for you. Default container size is `DEFAULT_HEADLESS_WIDTH` × `DEFAULT_HEADLESS_HEIGHT` (320×180).
 
+Coverage is binary (pixel-center inside path / nearest-neighbor images). No antialiasing, no `Math.random`. Identical seeded harness runs produce identical `ImageData`. Unsupported operations throw `HeadlessUnsupportedOperationError` with the operation name (never silent no-ops). `createPattern`, non-empty `setLineDash`, `filter`, shadows, HTMLImageElement `drawImage`, and unknown context methods are in that set.
+
+Font/image fixtures: pass `{ glyphAtlas }` to `installHeadlessCanvas`, call `setDefaultGlyphAtlas`, or `ctx.setGlyphAtlas`. `fillText` never loads system fonts. `drawImage` accepts `ImageData`, another headless canvas, or `createImageFixture(width, height, pixels)`.
+
+## Visual assertions
+
+Import `compareImageData`, `assertPixelsEqual`, `assertPngDataUrlsEqual`, and `writeVisualArtifacts` from `@cyberart-io/engine/headless`.
+
+- Exact match: `tolerance` defaults to 0 (every RGBA byte).
+- Perceptual / slack: `tolerance` (max per-channel delta) and/or `perceptualThreshold` (weighted RGB distance with luma weights 0.299 / 0.587 / 0.114).
+- On mismatch the result includes in-memory `expectedPng` / `actualPng` / `diffPng` (magenta where pixels differ) plus data URLs. `writeVisualArtifacts(dir, artifacts)` writes those PNGs (Node `fs` only; same rule as `captureFrame(path)`).
+- Golden update: set `CYBERART_UPDATE_GOLDEN=1` (or `true`) or pass `{ updateGolden: true }`. The compare then treats actual as expected so CI can rewrite goldens. Engine-encoded 8-bit RGBA PNGs round-trip through `decodePng`.
+
+```ts
+import { compareImageData, writeVisualArtifacts } from '@cyberart-io/engine/headless';
+
+const result = compareImageData(actual, expected, { perceptualThreshold: 2 });
+if (!result.match) {
+  await writeVisualArtifacts('/tmp/cyb-62-diff', result.artifacts);
+}
+```
+
+One-command visual reproduce in this repo:
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-62-headless-canvas2d.repro.spec.ts
+```
+
 ## `createHeadlessHarness(options)`
 
 ```ts
@@ -54,7 +82,7 @@ const harness = createHeadlessHarness({
   height: 180,
   origin: 0,
   actions: [{ type: 'asset', atFrame: 0, id: 'room-map', status: 'ready' }],
-  initialState: { room: 'glade' },
+  initialState: { scene: 'alpha' },
   gameManager: hostAdapter, // site injection; presentation overlay is attachPresentationAdapter
   onEvent: (event) => {},
   onError: (error, info) => {},
@@ -92,7 +120,7 @@ Always sets `deterministic: { origin, actions }`.
 | `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. |
+| `captureFrame(path?)` | `cart.snapshot()` (`canvas.toDataURL('image/png')` on the production buffer). Optional `path` writes PNG bytes (Node only). |
 | `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. |
 
@@ -118,9 +146,11 @@ First frame throw: `{ phase: 'update', consecutive: 1, stopped: false }`. See [d
 
 Returns `CartSnapshot`: `{ seed, metadata?, pngDataUrl }`.
 
-- Omit `path` for in-memory snapshot (`pngDataUrl` is `HEADLESS_PNG_DATA_URL` under the stub).
+- Omit `path` for in-memory snapshot (`pngDataUrl` is the software Canvas2D frame, not the 1×1 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.
 
+Composed stacks use `createCompositor` plus `writeComposedFrame(compositor, path)` from the same headless entry. See [compositor](compositor.md).
+
 ## Interaction loop (agent recipe)
 
 ```ts
@@ -142,17 +172,17 @@ adapter.present({
   contractVersion: 1,
   phase: 'ready',
   view: {
-    title: 'Glade',
+    title: 'Alpha',
     regions: [
       {
-        id: 'north-trail',
+        id: 'region-north',
         x: 0,
         y: 0,
         width: canvas.width,
         height: canvas.height * 0.25,
         intent: {
-          type: 'adventure.intent.exit-requested',
-          payload: { exitId: 'brook' },
+          type: 'host.intent.exit-requested',
+          payload: { exitId: 'beta' },
         },
       },
     ],
@@ -163,24 +193,24 @@ 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
+// assert exactly one host.intent.exit-requested; cart state is still Alpha
 
 adapter.present({
   contractVersion: 1,
   phase: 'ready',
-  view: { title: 'Joiner Brook', regions: [] },
+  view: { title: 'Overlook', regions: [] },
 });
 await harness.step(1);
 
-await harness.captureFrame('/tmp/brook.png');
+await harness.captureFrame('/tmp/alpha.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.
+Host-owned scenes / hotspots use this adapter (`present` + `host.intent.*`). `gameManager` is site multiplayer, not this contract.
 
 ## Types
 
-`CreateHeadlessHarnessOptions`, `HeadlessHarness`, `HeadlessInspect`, `HeadlessFrameError`.
+`CreateHeadlessHarnessOptions`, `HeadlessHarness`, `HeadlessInspect`, `HeadlessFrameError`, `InstallHeadlessCanvasOptions`, `HeadlessUnsupportedOperationError`, visual-assert types.

package/docs/midi.md

@@ -0,0 +1,128 @@
+# MIDI controller
+
+Host-owned live MIDI in and out. Carts and hosts construct `MidiManager`. The runtime does not pass it into `getDefaultState`. This is controller I/O (Web MIDI), not MIDI file playback.
+
+Capability manifests already list `midi` under `integrations`. Related: [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-19-midi.repro.spec.ts
+```
+
+## Why this exists
+
+A piece that maps a keyboard or fader to parameters needs the same API in a browser (real ports) and in CI (no hardware). `inject` delivers inbound note / CC / pitch without `navigator.requestMIDIAccess`. `send` writes note-on/off, CC, pitch, or raw bytes through an injectable port. Missing Web MIDI or a denied permission is a structured result, so silent carts keep running.
+
+## `new MidiManager(options?)`
+
+```ts
+import { MidiManager } from '@cyberart-io/engine';
+
+const sent: number[][] = [];
+const midi = new MidiManager({
+  output: {
+    send(data) {
+      sent.push([...data]);
+    },
+  },
+});
+
+const stop = midi.subscribe('note', (message) => {
+  if (message.kind === 'noteon') {
+    // message.channel 0–15, message.note, message.velocity, message.status
+  }
+});
+
+midi.inject({ kind: 'noteon', channel: 0, note: 60, velocity: 100 });
+midi.sendNoteOn(0, 64, 90);
+midi.sendCc(3, 1, 127);
+midi.send([0xf8]);
+
+const access = await midi.requestAccess();
+// jsdom / Node: { ok: false, reason: 'unavailable' }
+// user gesture denied: { ok: false, reason: 'denied' }
+// browser with ports: { ok: true, inputs, outputs, sysexEnabled }
+
+stop();
+midi.destroy();
+```
+
+Headless and jsdom have no `navigator.requestMIDIAccess`. Inject and send still work when you pass a test `output`.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `output` | none | Port used by `send`. Tests pass a recording fake. When omitted, `requestAccess` adopts the first hardware output and re-adopts after hotplug if that port disconnects. A constructor `output` is never replaced. |
+| `requestMIDIAccess` | `navigator.requestMIDIAccess` | Override for tests (fake access or a rejecting function). |
+
+`statechange` on the access object attaches new inputs and **detaches disconnected ports immediately** (not only on `destroy()`). Stale `midimessage` listeners are removed when the input leaves `access.inputs`.
+
+### Inbound
+
+| Member | Meaning |
+|---|---|
+| `subscribe(kind, listener)` | `kind`: `note` (on and off) \| `cc` \| `pitch` \| `raw` \| `*`. Returns unsubscribe. |
+| `inject(input)` | Deliver without hardware. Voice fields, `Uint8Array`, or raw `number[]`. No-op after `destroy`. |
+
+### Outbound
+
+| Member | Meaning |
+|---|---|
+| `sendNoteOn(channel, note, velocity?)` | Status `0x90 \| channel`. Velocity default 100. |
+| `sendNoteOff(channel, note, velocity?)` | Status `0x80 \| channel`. Velocity default 0. |
+| `sendCc(channel, controller, value)` | Status `0xB0 \| channel`. |
+| `sendPitch(channel, value)` | 14-bit pitch bend `0–16383` (center `8192`). Status `0xE0 \| channel`. |
+| `send(bytes)` | Raw bytes through the port. |
+
+Each send returns `{ ok: true, data }` or `{ ok: false, reason: 'no-port' \| 'invalid' \| 'destroyed' }`. Out-of-range channel (not 0–15), 7-bit data, or pitch is `invalid`, not a throw.
+
+### Access and teardown
+
+| Member | Meaning |
+|---|---|
+| `requestAccess({ sysex? })` | Wraps Web MIDI when present. Never throws. |
+| `destroy()` | Removes hardware listeners and subscribers. Idempotent. |
+
+`requestAccess` results:
+
+| Result | When |
+|---|---|
+| `{ ok: true, inputs, outputs, sysexEnabled }` | Access granted. Inputs are attached; a constructor `output` is kept. |
+| `{ ok: false, reason: 'unavailable' }` | No `navigator.requestMIDIAccess` (headless / jsdom / insecure context). |
+| `{ ok: false, reason: 'denied' }` | The request rejected (permission or security). |
+| `{ ok: false, reason: 'destroyed' }` | `destroy()` ran before the promise settled, or after teardown. |
+
+## Types, channels, status bytes
+
+Channel is **0–15** (MIDI channels 1–16) in the status low nibble. Command lives in the high nibble.
+
+| Export | Value | Role |
+|---|---|---|
+| `MIDI_NOTE_OFF` | `0x80` | Note Off command |
+| `MIDI_NOTE_ON` | `0x90` | Note On command |
+| `MIDI_CONTROL_CHANGE` | `0xB0` | Control Change command |
+| `MIDI_PITCH_BEND` | `0xE0` | Pitch Bend command |
+| `MIDI_CHANNEL_MIN` / `MIDI_CHANNEL_MAX` | `0` / `15` | Valid channel range |
+| `MIDI_DATA_MAX` | `127` | Max 7-bit data byte (note, velocity, CC) |
+| `MIDI_PITCH_CENTER` / `MIDI_PITCH_MAX` | `8192` / `16383` | 14-bit pitch bend |
+| `midiStatus(command, channel)` | `(command & 0xF0) \| (channel & 0x0F)` | Build a status byte |
+| `midiChannelFromStatus(status)` | `status & 0x0F` | Channel 0–15 from a status byte |
+| `isMidiChannel(value)` | boolean | Integer 0–15 |
+| `isMidiData(value)` | boolean | Integer 0–127 (`MIDI_DATA_MAX`) |
+| `encodeMidiMessage` / `parseMidiBytes` | bytes ↔ `MidiMessage` | Shared by inject and hardware |
+
+`MidiMessage` kinds: `noteon` / `noteoff` / `cc` / `pitch` / `raw`. Each carries `status` and a copied `data` `Uint8Array`. Note-on with velocity `0` parses as `noteoff` (MIDI convention); the status byte stays `0x9n`.
+
+Public types for the `requestMIDIAccess` option (tests inject a fake; browsers pass the real Web MIDI objects):
+
+| Type | Role |
+|---|---|
+| `MidiRequestAccess` | `(options?: { sysex?: boolean }) => Promise<MidiAccessLike>` |
+| `MidiAccessLike` | `inputs` / `outputs` (`forEach`), `sysexEnabled`, optional `statechange` |
+| `MidiInputLike` | `addEventListener` / `removeEventListener` for `midimessage` (`event.data`) |
+
+Hosts that need a controller construct `MidiManager` themselves. Do not add it to `getDefaultState`.

package/docs/presentation-adapter.md

@@ -46,17 +46,17 @@ const model: PresentationModel = {
   reason: undefined, // string when not ready
   view: {
     background: '#1b3a4a',
-    title: 'Joiner Brook',
+    title: 'Overlook',
     regions: [
       {
-        id: 'north-trail',
+        id: 'region-north',
         x: 0,
         y: 0,
         width: 320,
         height: 45,
         intent: {
-          type: 'adventure.intent.exit-requested',
-          payload: { exitId: 'brook' },
+          type: 'host.intent.exit-requested',
+          payload: { exitId: 'beta' },
         },
       },
     ],
@@ -81,9 +81,9 @@ The reference cart never writes the host’s world. An unknown `contractVersion`
 
 ### 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`).
+Region `intent.type` should be routable: `*.intent.*` (for example `host.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.*`.
+Default router `emit` is `['*.intent.*']`, which does **not** match `room.exit.requested`. Prefer `host.intent.*`.
 
 ## Reference cart + session
 
@@ -121,7 +121,7 @@ const adapter = mountPresentationAdapter(runtime, {
 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.
+A host with a custom view shape passes `cart:` into `mountPresentationAdapter` and still `present()`s the same event. Do not import the host types into engine carts.
 
 ## Router
 
@@ -131,7 +131,7 @@ router.attach('presentation', runtime.hostChannel, {
   subscribe: [...PRESENTATION_SUBSCRIBE_PATTERNS],
 });
 
-router.subscribe(['adventure.intent.*', 'presentation.intent.unsupported'], (event) => {
+router.subscribe(['host.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`

package/docs/presentation-cue.md

@@ -1,8 +1,8 @@
 # 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.
+Deterministic cue/effect primitive. Carts call `step(frames)` with the same clock they use for deterministic mode; there are no `setTimeout` / rAF timers. Overlay pulses, scene transitions, 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).
+Back to the [package README](../README.md). Related: [deterministic mode](deterministic-mode.md), [events](events.md) (routed contracts vs local `cue.*` names).
 
 ## One-command reproduce (this repo)
 

package/docs/replay-inspector.md

@@ -0,0 +1,88 @@
+# Replay inspector
+
+Embeddable debug API for multi-cart routing. It records router decisions, builds a causation tree, redacts configured payload keys, bounds retention, and exports a JSON tape that the headless harness can replay. There is no Player UI.
+
+Related: [events](events.md), [runtime group](runtime-group.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-65-replay-inspector.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createReplayInspector` from `@cyberart-io/engine` | Attach to `createEventRouter` or `createRuntimeGroup`. |
+| Vitest / CI | same API, or from `@cyberart-io/engine/headless` | `replayExportedTrace` against `createHeadlessMultiCartHarness`. |
+
+Hosts attach this inspector to a router or runtime group. Event types stay host-defined.
+
+## `createReplayInspector(options?)`
+
+```ts
+import { createReplayInspector } from '@cyberart-io/engine';
+import { createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless';
+
+const group = createHeadlessMultiCartHarness({
+  origin: 0,
+  participants: [
+    { id: 'effects', cart: effectsCart, emit: ['overlay.intent.*'], subscribe: ['host.state.*'] },
+    { id: 'ambience', cart: ambienceCart, subscribe: ['overlay.intent.*'] },
+  ],
+});
+
+const inspector = createReplayInspector({
+  redactedKeys: ['token'],
+  maxRecords: 512,
+});
+const session = inspector.bind(group);
+session.publish({ type: 'host.state.accepted', kind: 'state', payload: { token: 'secret' } });
+await session.step(2);
+const exported = await session.exportTrace();
+inspector.destroy();
+group.destroy();
+```
+
+`host.state.accepted` delivered to `effects` causes `overlay.intent.play` for `ambience`. The inspector tree is that chain plus any later rejects.
+
+### Options (`CreateReplayInspectorOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `redactedKeys` | `[]` | Object keys replaced with `REDACTED_VALUE` in payloads and cart state summaries. |
+| `maxRecords` | `512` | Oldest records drop; `report().dropped` counts them. |
+| `registry` | none | `ContractRegistry.get` annotates `payloadSchemaVersion`. |
+
+### Bind vs watch
+
+| Method | Meaning |
+|---|---|
+| `watchRouter(router)` | Copy existing `inspectDecisions()`, then subscribe. |
+| `bind(group)` | Watch the group router and record a `publish` / `dispatch` / `step` / asset tape. `publish` extras (`cause`) are stored and replayed. `unbind()` drops the decision subscription. |
+| `importTrace(json)` | Load an export for inspection without replaying. |
+| `exportTrace(filter?)` | JSON: participants, tape, redacted records, snapshots. |
+| `report(filter?)` | Machine-readable CI report: participants, records, trees, dropped. |
+| `causationTree(correlationId?)` | Forest of accepted/rejected nodes. Duplicates are omitted. |
+| `replayExportedTrace(export, group)` | Play the tape on a fresh group; compare with `compareReplayTraces`. |
+
+`dispatch` of `cyberart.asset.ready` / `cyberart.asset.failed` is stored as tape `kind: 'asset'`.
+
+Cart summaries include `emit` / `subscribe` / `authoritative`, clock, redacted state, and `errorCount` / `lastError` (message only).
+
+## Router traces
+
+`createEventRouter` now also exposes:
+
+| Method | Meaning |
+|---|---|
+| `inspectParticipants()` | id, emit, subscribe, authoritative. |
+| `inspectDecisions()` | Bounded decision log (`maxDecisions`, default 256). |
+| `subscribeDecision(listener)` | Live accepted / rejected / duplicate records. |
+
+`RuntimeGroup.inspectParticipants()` adds `kind`. Group `inspect()` includes the same attach fields. `maxTrace` bounds the accepted-event envelope log (default 1024).
+
+Duplicate idempotency hits are `outcome: 'duplicate'` / `reason: 'duplicate'` and do not fan out. Permission failures stay `unauthorized`; missing targets `unknown-target`; spent TTL `hop-limit`.

package/docs/runtime-group.md

@@ -4,7 +4,7 @@ Host helper that mounts several production `createRuntime` carts, attaches each
 
 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).
+Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md).
 
 Back to the [package README](../README.md).
 
@@ -40,7 +40,7 @@ const group = createRuntimeGroup({
       cart: effectsCart,
       seed: `0x${'61'.repeat(32)}`,
       emit: ['ambience.intent.*'],
-      subscribe: ['adventure.state.*'],
+      subscribe: ['host.state.*'],
     },
     {
       id: 'ambience',
@@ -53,16 +53,16 @@ const group = createRuntimeGroup({
 });
 
 group.publish({
-  type: 'adventure.state.loon-whistle',
+  type: 'host.state.accepted',
   kind: 'state',
-  payload: { habitat: 'pond' },
+  payload: { id: 'north' },
 });
 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.
+Example mapping: an accepted `host.state.accepted` 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`)
 
@@ -74,6 +74,7 @@ Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.sta
 | `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`, …). |
+| `maxTrace` | `1024` | Bound on the accepted-event inspect trace. |
 
 ### Participant config
 
@@ -98,10 +99,11 @@ Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.sta
 | `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 }`. |
+| `inspect()` | `{ participants: Record<id, { state, events, errors, kind, clock, emit, subscribe, authoritative }>, trace, diagnostics }`. |
+| `inspectParticipants()` | Sync attach view (`id`, `kind`, `emit`, `subscribe`, `authoritative`). |
 | `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.
+Idempotency, correlation, causation, unauthorized emit, hop/loop checks are the existing router. The group only attaches and locksteps. For “why did this effect not fire?”, attach [`createReplayInspector`](replay-inspector.md).
 
 ## `createHeadlessMultiCartHarness(options)`