@cyberart-io/engine 0.0.5 → 0.0.7

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/calculation-carts.md

@@ -0,0 +1,134 @@
+# Calculation carts
+
+Carts that run `getDefaultState`, `update`, and host-channel events without a paint surface. They share a lockstep clock and router with sibling render carts. They do not create a canvas and the runtime does not call `render`, even if a no-op is supplied.
+
+Generic names only: telemetry, world, overlay. Event types stay on `host.intent.*` / `host.state.*`. Scene ids such as `alpha` and overlay ids such as `banner` are payload fields, not product names.
+
+Related: [runtime group](runtime-group.md), [events](events.md), [capability manifest](capability-manifest.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-20-calculation-cart.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createRuntime({ kind: 'calculation' })` or `createRuntimeGroup` participant `kind: 'calculation'` from `@cyberart-io/engine` | World / telemetry carts that emit and consume events for a sibling overlay (or other render) cart. |
+| Vitest / jsdom | `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` | Same group API after `installHeadlessCanvas()`. |
+
+`kind` defaults to `'render'`. Existing carts, `/art`, and `metadata.audio: 'tone'` pieces are unchanged: they still get a canvas and a paint phase.
+
+## `createRuntime({ kind: 'calculation' })`
+
+```ts
+import { createRuntime } from '@cyberart-io/engine';
+import type { AnimationCart } from '@cyberart-io/engine';
+
+type WorldState = { sceneId: string | null };
+
+const worldCart: AnimationCart<WorldState> = {
+  metadata: { id: 'world', name: 'World', frameRate: 30 },
+  getDefaultState: () => ({ sceneId: null }),
+  update: (_R, _f, _p, _d, state, _k, _ptr, _gm, _t, _fs, hostChannel) => {
+    const events = hostChannel?.consume() ?? [];
+    let sceneId = state.sceneId;
+    for (const event of events) {
+      if (event.type === 'host.state.scene-changed') {
+        sceneId = (event.payload as { sceneId?: string } | undefined)?.sceneId ?? null;
+        hostChannel?.emit({
+          type: 'host.intent.overlay',
+          kind: 'intent',
+          payload: { overlayId: 'banner' },
+        });
+      }
+    }
+    return { sceneId };
+  },
+  // render omitted
+};
+
+const runtime = createRuntime({
+  container,
+  kind: 'calculation',
+  deterministic: { origin: 0 },
+  seed: `0x${'20'.repeat(32)}`,
+});
+const cart = runtime.mount(worldCart);
+// cart.canvas === undefined; container has no <canvas>
+```
+
+`runtime.kind` is `'calculation'`. `CartHandle.canvas` is `undefined`. `step` / `advance` still run `update`. A no-op `render` is not invoked.
+
+## Runtime group
+
+```ts
+import { createRuntimeGroup } from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  origin: 0,
+  participants: [
+    {
+      id: 'world',
+      cart: worldCart,
+      kind: 'calculation',
+      seed: `0x${'20'.repeat(32)}`,
+      emit: ['host.intent.*'],
+      subscribe: ['host.state.*'],
+    },
+    {
+      id: 'overlay',
+      cart: overlayCart,
+      kind: 'render',
+      subscribe: ['host.intent.*'],
+    },
+    {
+      id: 'telemetry',
+      cart: telemetryCart,
+      kind: 'calculation',
+      subscribe: ['host.state.*', 'host.intent.*'],
+    },
+  ],
+});
+
+group.publish({
+  type: 'host.state.scene-changed',
+  kind: 'state',
+  payload: { sceneId: 'alpha' },
+});
+await group.step(2);
+const { participants } = await group.inspect();
+// participants.world.kind === 'calculation'
+// group.participant('world').cart.canvas === undefined
+// overlay still paints
+group.destroy();
+```
+
+`createRuntimeGroup` passes each participant `kind` into `createRuntime`. Calculation participants keep a mount container (for the runtime) but never attach a canvas. `resize` skips missing canvases. Compositor layers that point at a calculation id are skipped (`cart.canvas` is absent).
+
+## Capability manifest
+
+Optional `kind: 'calculation'` on the manifest (omitted means render). Hosts that want to enforce it pass `kinds: ['render', 'calculation']`. Existing manifests and hosts that omit `kinds` are unchanged.
+
+```ts
+import { defineCapabilityManifest, validateCapabilityManifest } from '@cyberart-io/engine';
+
+const defined = defineCapabilityManifest({
+  id: 'world.telemetry',
+  kind: 'calculation',
+  runtime: { minContractVersion: 1, features: ['router'] },
+  phases: ['ready'],
+  managers: ['hostChannel'],
+  assets: { kinds: [], declarations: [] },
+  acceptedEvents: ['host.state.*'],
+  emittedEvents: ['host.intent.overlay'],
+  permissions: { emit: ['host.intent.*'], subscribe: ['host.state.*'] },
+  integrations: [],
+});
+```
+
+`CAPABILITY_CART_KINDS` is `['render', 'calculation']`. Diagnostics: `invalid-kind`, `unsupported-kind`.

package/docs/capability-manifest.md

@@ -1,6 +1,6 @@
 # Capability manifest
 
-Versioned JSON for what a cart needs from the host: runtime contract, lifecycle phases, managers, asset kinds, event patterns, permissions, and integrations. Related: [events](events.md) (emit / subscribe patterns), [asset resolver](asset-resolver.md) (kinds only — this file does not resolve URLs).
+Versioned JSON for what a cart needs from the host: runtime contract, lifecycle phases, managers, asset kinds, event patterns, permissions, and integrations. Related: [events](events.md) (emit / subscribe patterns), [asset resolver](asset-resolver.md) (kinds only — this file does not resolve URLs), [calculation carts](calculation-carts.md) (`kind`).
 
 Back to the [package README](../README.md).
 
@@ -26,6 +26,7 @@ pnpm exec vitest run packages/engine/src/canvas/cyb-25-capability-manifest.repro
 | `acceptedEvents` / `emittedEvents` | Dotted type patterns (`*` = one segment). |
 | `permissions` | `emit` / `subscribe` patterns; optional `authoritative`. |
 | `integrations` | Required host libraries: `tone` \| `midi`. |
+| `kind` | Optional. `'render'` (omitted) or `'calculation'`. |
 
 Emitted types must be covered by `permissions.emit`; accepted types by `permissions.subscribe`.
 
@@ -84,12 +85,14 @@ const parsed = parseCapabilityManifest(JSON.stringify(defined.manifest));
 | `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. |
+| `invalid-kind` / `unsupported-kind` | Manifest `kind` is not `render` / `calculation`, or the host `kinds` list does not include it. |
 
 Optional additive keys (omitted on existing carts):
 
 ```ts
 surface: { alpha: true, clearPolicy: 'transparent' }
 layers: { compositor: true, blend: ['source-over', 'screen'] }
+kind: 'calculation'
 ```
 
-See [compositor](compositor.md).
+`host.kinds` is optional. When omitted, `unsupported-kind` is not checked. See [calculation carts](calculation-carts.md).

package/docs/compositor.md

@@ -48,7 +48,7 @@ const frame = compositor.captureComposedFrame();
 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.
+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. Versioned overlay swaps (`v1` → `v2`) belong on [`createVisualLayerController`](visual-layers.md), which calls `setLayer` / `addLayer` with `source: { kind: 'image', image }` so a failed asset never becomes the live frame.
 
 ### Options
 
@@ -65,7 +65,7 @@ Typical stack: host image, then opaque overlay carts (`source-over`), then addit
 
 | Field | Default | Meaning |
 |---|---|---|
-| `id` | required | Runtime-group participant id. |
+| `id` | required | Runtime-group participant id, or a visual-layer slot with an `image` / `canvas` source. |
 | `order` | required | Lower draws first. |
 | `visible` | `true` | Skip compose and pointer hits when false. |
 | `opacity` | `1` | 0..1. |
@@ -73,6 +73,11 @@ Typical stack: host image, then opaque overlay carts (`source-over`), then addit
 | `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. |
+| `source` | `{ kind: 'participant' }` | `participant` reads the group canvas. `image` clones `ImageData`. `canvas` rereads that canvas each compose. |
+
+`setLayer` applies a patch, including an atomic `source` swap. `addLayer` appends a declaration (ImageData slots do not need a group participant). `unmountLayer` detaches a participant when one exists; ImageData-only layers are removed from the compose list.
+
+`inspect().layers[].sourceKind` is `participant` | `image` | `canvas`.
 
 ### Handle
 
@@ -81,7 +86,7 @@ Typical stack: host image, then opaque overlay carts (`source-over`), then addit
 | `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. |
+| `setLayer` / `addLayer` / `layer` / `layers` | Mutate / inspect declarative settings. `setLayer` can swap `source`. |
 | `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. |

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/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/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), [compositor](compositor.md), [replay inspector](replay-inspector.md).
+Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md), [calculation carts](calculation-carts.md).
 
 Back to the [package README](../README.md).
 
@@ -82,7 +82,7 @@ Example mapping: an accepted `host.state.accepted` is consumed by the effects ca
 |---|---|
 | `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). |
+| `kind` | `'render'` (default) or `'calculation'` (no canvas / paint; `update` and host-channel events still run). See [calculation carts](calculation-carts.md). |
 | `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`. |
@@ -117,6 +117,6 @@ await harness.step(2);
 harness.destroy();
 ```
 
-Calls `installHeadlessCanvas()` then `createRuntimeGroup`. Same handle. Three-cart CI fixture: effects + ambience + a calculation telemetry cart.
+Calls `installHeadlessCanvas()` then `createRuntimeGroup`. Same handle. Three-cart CI fixture: effects + ambience + a calculation telemetry cart (no canvas).
 
 Cleanup: `afterEach(() => group.destroy())` so a failed assertion does not leak nodes. After `destroy`, `step` throws and owned containers are gone from `document.body`.