@cyberart-io/engine 0.0.4 → 0.0.6

package/README.md

@@ -89,13 +89,20 @@ Full API for the event router, deterministic replay, and CI harness (so agents c
 
 - [Events and router](docs/events.md) — mailbox, envelope, typed contracts, `createEventRouter`, hops, idempotency, rejections
 - [Deterministic mode](docs/deterministic-mode.md) — `step` / `schedule`, clocks, `ScriptedAction`, replay diffs
-- [Headless harness](docs/headless-harness.md) — `createHeadlessHarness` from `@cyberart-io/engine/headless`, jsdom canvas, inspect / screenshot
+- [Headless harness](docs/headless-harness.md) — `createHeadlessHarness` from `@cyberart-io/engine/headless`, software Canvas2D, `compareImageData` / `assertPixelsEqual`, inspect / screenshot
 - [Presentation adapter](docs/presentation-adapter.md) — host-owned render model, intents, loading / error / unsupported
 - [Asset resolver](docs/asset-resolver.md) — host-pluggable images/audio/fonts/spritesheets, cache, preload, fallbacks
 - [Presentation cue](docs/presentation-cue.md) — deterministic `createPresentationTimeline`, duplicate policy, reduced-motion, lifecycle events
 - [Capability manifest](docs/capability-manifest.md) — versioned JSON for runtime features, phases, managers, assets, events, permissions, integrations
+- [Executable modules](docs/executable-modules.md) — trusted versioned factories, host allowlists, isolation, per-module failures
 - [Normalized geometry](docs/normalized-geometry.md) — coordinate spaces, contain/cover/crop layout, landmarks, hit regions, debug overlay
 - [Runtime group](docs/runtime-group.md) — `createRuntimeGroup`, shared router attach, lockstep clock; `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless`
+- [Compositor](docs/compositor.md) — `createCompositor`, transparent stacking, `screen` blend, `writeComposedFrame`
+- [Browser harness](docs/browser-harness.md) — `createBrowserHarness`, DOM clicks, viewport/DPR, composed screenshots
+- [Replay inspector](docs/replay-inspector.md) — `createReplayInspector`, causation trees, redacted export/import, headless replay
+- [MIDI](docs/midi.md) — host-owned `MidiManager`, note/CC/pitch in and out, `inject` / fake port, structured `requestAccess`
+- [Snapshots](docs/snapshots.md) — versioned envelope, `defineSnapshot` / `applySnapshotMigrations`, host-owned `hostState`
+- [Audio](docs/audio.md) — `createAudioBroker`, `createAudioCueTimeline`, headless cue traces (PCM is not deterministic)
 
 ## Write a cart
 
@@ -150,6 +157,8 @@ const cart = runtime.mount(artProject, {
 | `audio` | none | Libraries to unlock if `unlockAudio()` runs before `mount`. After mount, the cart’s `metadata.audio` wins. |
 | `deterministic` | off | Host-controlled clock, `step`/`advance`, and scripted input/assets. Leave unset for live kaleidoscope / Art Blocks. |
 | `assets` | off | Host `AssetResolver` plus engine cache/preload. Carts keep logical refs. Leave unset when the piece has no media. |
+| `audioBroker` | off | Shared `createAudioBroker` instance. Optional. Omit when the cart only uses `metadata.audio: 'tone'`. |
+| `audioParticipantId` | none | Group participant id to authorize / teardown on this runtime. |
 
 `CartHandle` (what `mount` returns):
 
@@ -162,8 +171,10 @@ const cart = runtime.mount(artProject, {
 | `step(frames)` / `advance(ms)` | Deterministic ticks only. Throw if `deterministic` was not set. |
 | `schedule(action)` | Queue a pointer/key/host-event/asset for a future frame. |
 | `getClock()` / `getRandomState()` / `getReplayMetadata()` | Replay inspection. |
-| `exportState()` / `exportStateJSON()` | Pause-safe serializable bundle. |
-| `importState(bundle)` | Restore a bundle (or JSON string). |
+| `exportState()` / `exportStateJSON()` | Pause-safe serializable `CartStateBundle` (schema 1 blob). |
+| `importState(bundle)` | Restore a bundle, JSON string, or snapshot envelope (migrates then loads `engineState`). |
+| `exportSnapshot()` / `exportSnapshotJSON()` | Schema 2 envelope wrapping the bundle plus clock, rng, optional `hostState`. |
+| `importSnapshot(envelope)` | Migrate to the current schema and restore `engineState`. Hosts reapply `hostState`. |
 | `destroy()` | Unload this cart. Idempotent. |
 | `needsAudio` | True when the cart declared audio libraries. Use this to show a click overlay. |
 | `paused` / `isPrepared` / `isLoopRunning` | Loop flags. |
@@ -196,6 +207,14 @@ Install the peer: `npm i tone@^14.8.15`. Call `cart.start()` **inside a click or
 
 If a click can happen before `mount` finishes, pass the same `audio` into `createRuntime` and/or call `runtime.unlockAudio()` from that click. After mount, the cart’s metadata wins.
 
+Several carts on one page should share **one** `createAudioBroker` (pass it to `createRuntime` / `createRuntimeGroup`). One `unlock()` covers authorized participants. Channel gain, mute, duck, and priority live on the broker; cue timing is `createAudioCueTimeline` / `scheduleAudioCue` (presentation-frame clock). Headless CI records cue events with `createHeadlessAudioAdapter` from `@cyberart-io/engine/headless` — the event trace is deterministic, PCM is not. Full API: [audio](docs/audio.md).
+
+## MIDI
+
+Host-owned `MidiManager` — carts and hosts construct it. The runtime does not pass it into `getDefaultState`. Subscribe to note / CC / pitch, `inject` for tests without hardware, and `send` note-on/off, CC, or raw bytes through an injectable port. `requestAccess()` wraps `navigator.requestMIDIAccess` when present; a missing API or denied permission is a structured result, so silent carts keep running. Headless/jsdom has no Web MIDI; inject and send still work via a test port.
+
+Full API and the reproduce command: [MIDI](docs/midi.md). Capability manifests already list `midi` as an integration.
+
 ## Seed
 
 Pass `seed` when you want a deterministic output (for example from `?hash=`):
@@ -244,9 +263,9 @@ CI and agents should drive the **same** `createRuntime({ deterministic })` path.
 - Carts and production hosts: `import { createRuntime } from '@cyberart-io/engine'`
 - Tests, CI, and frame capture: `import { createHeadlessHarness, createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless'`
 
-`@cyberart-io/engine` does not re-export the harness. `installHeadlessCanvas` is the documented jsdom install (test-only). `createHeadlessHarness` sizes a container, mounts, and wraps step / input / inspect / snapshot.
+`@cyberart-io/engine` does not re-export the harness. `installHeadlessCanvas` is the documented jsdom install (test-only). It attaches a deterministic software Canvas2D (paths, arcs, atlas text, transforms, clip, alpha, gradients, `drawImage`). Unsupported ops throw `HeadlessUnsupportedOperationError`. `createHeadlessHarness` sizes a container, mounts, and wraps step / input / inspect / snapshot. Pixel compare: `compareImageData`, `assertPixelsEqual`, `writeVisualArtifacts` (`CYBERART_UPDATE_GOLDEN=1` to refresh goldens).
 
-Full options, `click` clock rule, Node-only `captureFrame`, remount, and the reproduce command: [headless harness](docs/headless-harness.md).
+Full options, `click` clock rule, Node-only `captureFrame`, remount, visual asserts, and the reproduce command: [headless harness](docs/headless-harness.md).
 
 ```ts
 import { createHeadlessHarness } from '@cyberart-io/engine/headless';
@@ -285,11 +304,11 @@ import {
   createEventRouter,
 } from '@cyberart-io/engine';
 
-const exit = defineIntent('adventure.intent.exit-requested', {
+const exit = defineIntent('host.intent.exit-requested', {
   version: 1,
   fields: { exitId: { type: 'string' } },
 });
-const room = defineStateEvent('adventure.state.room-changed', {
+const room = defineStateEvent('host.state.room-changed', {
   version: 1,
   fields: { roomId: { type: 'string' } },
 });
@@ -302,6 +321,26 @@ const router = createEventRouter({
 router.attach('presentation', runtime.hostChannel, deriveAttachOptions(contracts, 'cart'));
 ```
 
+## Presentation cue
+
+Frame-stepped effects (overlays, pulses, scene fades). No `setTimeout` / rAF. Drive `step` from the same clock as deterministic `cart.step`.
+
+```ts
+import { createPresentationTimeline } from '@cyberart-io/engine';
+
+const timeline = createPresentationTimeline({ originFrame: 0, reducedMotion: false });
+timeline.play({
+  name: 'checkmark',
+  idempotencyKey: 'gold',
+  durationFrames: 90,
+  easing: 'ease-out',
+  onDuplicate: 'replace',
+});
+timeline.step(90);
+```
+
+Lifecycle names `cue.started` / `cue.completed` / `cue.cancelled` / `cue.replaced` are local to the timeline. They are not router envelopes unless you define a contract. Duplicate policy, late-play catch-up, and reduced-motion: [presentation cue](docs/presentation-cue.md).
+
 ## Capability manifest
 
 JSON for what a cart needs from the host. `validateCapabilityManifest` returns structured diagnostics instead of throwing.
@@ -313,14 +352,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('; '));
@@ -328,13 +367,47 @@ validateCapabilityManifest(defined.manifest, {
   contractVersion: 1,
   features: ['router'],
   integrations: ['tone'],
-  emit: ['adventure.intent.*'],
-  subscribe: ['adventure.state.*'],
+  emit: ['host.intent.*'],
+  subscribe: ['host.state.*'],
 });
 ```
 
 Fields, host allowlists, and diagnostic codes: [capability manifest](docs/capability-manifest.md).
 
+## Executable modules
+
+Trusted factories keyed by exact `id` + `version`. The host allowlists which refs may load. There is no `eval` / `new Function` path for cart-supplied strings.
+
+```ts
+import { createExecutableModuleHost } from '@cyberart-io/engine';
+
+const host = createExecutableModuleHost({
+  allowlist: [
+    { id: 'overlay-fx', version: '1.0.0' },
+    { id: 'host.module', version: '1.0.0' },
+  ],
+  limits: { maxInvokeMs: 16, maxInvokesPerTurn: 4 },
+  modules: [
+    {
+      id: 'overlay-fx',
+      version: '1.0.0',
+      create: (capabilities) => ({
+        invoke: (input, { signal }) => {
+          if (signal.aborted) return;
+          return { input, seed: capabilities.seed };
+        },
+      }),
+    },
+  ],
+});
+
+const allowed = await host.invoke({ id: 'overlay-fx', version: '1.0.0' });
+await host.invoke({ id: 'overlay-fx', version: '2.0.0' }); // version-mismatch, not invoked
+host.destroy();
+```
+
+Unknown ids, wrong versions, and refs missing from the allowlist fail closed. A throwing module returns `{ ok: false, error }` and the next allowlisted invoke still runs. Isolation is in-process (trusted factories), not a worker or iframe. Carts may declare required refs as optional `modules.refs` on a [capability manifest](docs/capability-manifest.md). Full API and the reproduce command: [executable modules](docs/executable-modules.md).
+
 ## Runtime group
 
 Several production carts, one router, one lockstep clock. Use this instead of intercepting each `onEvent` and republishing by hand.
@@ -345,17 +418,17 @@ import { createRuntimeGroup } from '@cyberart-io/engine';
 const group = createRuntimeGroup({
   origin: 0,
   participants: [
-    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['adventure.state.*'] },
+    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['host.state.*'] },
     { id: 'ambience', cart: ambienceCart, subscribe: ['ambience.intent.*'] },
   ],
 });
-group.publish({ type: 'adventure.state.loon-whistle', kind: 'state', payload: { habitat: 'pond' } });
+group.publish({ type: 'host.state.accepted', kind: 'state', payload: { id: 'north' } });
 await group.step(2);
 const { trace } = await group.inspect();
 group.destroy();
 ```
 
-Headless / CI: `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` is the same handle after `installHeadlessCanvas()`. Full options: [runtime group](docs/runtime-group.md).
+Headless / CI: `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` is the same handle after `installHeadlessCanvas()`. Full options: [runtime group](docs/runtime-group.md). Causation trees, redaction, and tape replay: [replay inspector](docs/replay-inspector.md).
 
 ## Normalized geometry
 
@@ -400,7 +473,7 @@ const adapter = attachPresentationAdapter(harness);
 adapter.present({
   contractVersion: 1,
   phase: 'ready',
-  view: { title: 'Joiner Brook', regions: [] },
+  view: { title: 'Overlook', regions: [] },
 });
 ```
 
@@ -418,7 +491,7 @@ import {
 } from '@cyberart-io/engine';
 
 const roomAssets = [
-  { id: 'room-bg', ref: 'moltazine:post/porch-1#primary-image', type: 'image' as const },
+  { id: 'backdrop', ref: 'moltazine:post/porch-1#primary-image', type: 'image' as const },
   {
     id: 'ambience',
     ref: 'world:asset/stream-loop',
@@ -453,14 +526,22 @@ The same declarations produce fixture URLs locally and CDN URLs (plus a typed CO
 
 ## Save and load
 
-Live `state` is not JSON-safe (audio nodes, managers, typed arrays, possible cycles). `snapshot()` is PNG + seed. Use export/import when you want the simulation itself:
+Live `state` is not JSON-safe (audio nodes, managers, typed arrays, possible cycles). `snapshot()` is PNG + seed. Use export/import when you want the simulation itself.
+
+`exportState` still returns the engine-owned `CartStateBundle` (`CART_STATE_BUNDLE_VERSION = 1`) so existing carts keep working. The versioned envelope (`SNAPSHOT_SCHEMA_VERSION = 2`) wraps that blob in `engineState` and keeps host-owned JSON in `hostState` (or a `hostStateRef`). Hosts persist the envelope; Cyberart is not the database. Full field list, migration registry, and diagnostic codes: [versioned snapshots](docs/snapshots.md).
 
 ```ts
 const bundle = await cart.exportState();
 const json = await cart.exportStateJSON();
+const envelope = await cart.exportSnapshot({
+  cartVersion: '3',
+  hostState: { sceneId: 'alpha' },
+});
 
 await cart.importState(bundle);
 await cart.importState(json);
+await cart.importState(envelope);
+await cart.importSnapshot(envelope);
 ```
 
 Both pause, wait until any in-flight `update` finishes, then restore the previous pause flag. Import tears down, runs `getDefaultState` again (fresh managers, empty audio graph), overlays the save onto that scaffold unless `getDefaultState` already returned the revived `customState`, and restores `framesElapsed`. Works on a prepared cart before `start()`. Throws if nothing is prepared, or if the bundle is incompatible (`IncompatibleCartStateError`).
@@ -524,7 +605,7 @@ A canvas the host adopted is left in place on destroy; a canvas the engine creat
 
 ## Publishing this package (maintainers)
 
-Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (event / deterministic / harness / presentation-adapter / asset-resolver / presentation-cue API), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
+Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (including compositor, browser harness, replay inspector, MIDI, executable modules, snapshots, and audio), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
 
 ```bash
 pnpm run pack:engine