@cyberart-io/engine 0.0.5 → 0.0.6

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/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/snapshots.md

@@ -0,0 +1,102 @@
+# Versioned snapshots
+
+Portable save envelope for carts and embedding hosts. Schema **1** is the previous engine-owned `CartStateBundle` (`CART_STATE_BUNDLE_VERSION = 1`). Schema **2** wraps that blob in `engineState` and keeps host-owned data in `hostState` / `hostStateRef`. Cyberart migrates envelopes in memory; the host owns persistence (local storage, a database, cross-user saves). This package is not the database of record.
+
+Related: [deterministic mode](deterministic-mode.md) (`rng` / clock), [capability manifest](capability-manifest.md) (cart id). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-50-snapshots.repro.spec.ts
+```
+
+## Scheme (`SNAPSHOT_SCHEMA_VERSION = 2`)
+
+`ENGINE_SNAPSHOT_RUNTIME` is `'0.0.5'`. It is a snapshot runtime id, independent of the npm package version — bump whichever one the change actually belongs to.
+
+| Field | Meaning |
+|---|---|
+| `schemaVersion` | Envelope schema. Current **2**. |
+| `runtimeVersion` | `ENGINE_SNAPSHOT_RUNTIME` at save. |
+| `cart` | `{ id, version, generative? }` — exact cart version (`'0'` if unversioned). |
+| `modules` | Optional `{ id, version }[]`. |
+| `seed` | Deterministic token hash. |
+| `rng` | Optional `RandomState` (sfc32 snapshot). Recorded when available; cart `importState` still does not replay the PRNG. |
+| `clock` | `framesElapsed`, optional `elapsedSinceStart` / `now` / `frameRate`. |
+| `engineState` | The existing `CartStateBundle` (bundle `version` remains **1**). |
+| `hostState` | Host-owned JSON payload. Opaque to the engine. |
+| `hostStateRef` | Host persistence pointer (slot id, URL, …). Not loaded by the engine. |
+| `assets` | Optional `{ id, version?, ref? }[]` content version references. |
+| `createdAt` | ISO-8601 creation time. Migrated v1 bundles use `1970-01-01T00:00:00.000Z`. |
+| `provenance` | Optional `{ source?, integrity?: { alg, hash } }`. Hosts fill integrity; the engine does not hash. |
+
+`cart.id` is required. `snapshotFromCartBundle` and the 1→2 migration fail closed when the legacy bundle has no `cartId` — they do not stamp `'unknown'`.
+
+`defineSnapshot` / `parseSnapshot` / `validateSnapshot` return `{ ok: true, snapshot }` or `{ ok: false, errors }`. They do not throw. JSON round-trip: `JSON.parse(JSON.stringify(snapshot))` equals the snapshot.
+
+Legacy cart bundles (no `schemaVersion`, have `version` / `seed` / `framesElapsed` / `state`) parse as schema **1**. `exportState` / `importState` still use that blob so existing carts keep working. `importState` also accepts a current envelope: it migrates if needed and restores `engineState` only.
+
+## Migrations
+
+```ts
+import {
+  applySnapshotMigrations,
+  createEngineSnapshotMigrations,
+  createSnapshotMigrationRegistry,
+  defineSnapshot,
+  parseSnapshot,
+} from '@cyberart-io/engine';
+
+const defined = defineSnapshot({
+  cart: { id: 'art.cart', version: '3' },
+  seed: '0x' + '50'.repeat(32),
+  clock: { framesElapsed: 12 },
+  engineState: {
+    version: 1,
+    cartId: 'art.cart',
+    seed: '0x' + '50'.repeat(32),
+    framesElapsed: 12,
+    state: { n: 12 },
+  },
+  hostState: { sceneId: 'alpha' },
+  createdAt: '2026-01-15T00:00:00.000Z',
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+
+const registry = createSnapshotMigrationRegistry({
+  migrations: createEngineSnapshotMigrations(),
+});
+const migrated = applySnapshotMigrations(legacyBundle, registry);
+```
+
+`applySnapshotMigrations` clones the input, walks `from → from+1` until schema 2, and validates each step. The original object is left unchanged, including when a step is missing or a migrate function fails.
+
+| Diagnostic `code` | When |
+|---|---|
+| `invalid-json` | `parseSnapshot` received unparseable text. |
+| `invalid-snapshot` | Root value is not a JSON object, or a legacy blob is missing. |
+| `invalid-field` | A required string/number/object field is the wrong shape. |
+| `invalid-schema` | `validateSnapshot` / `defineSnapshot` saw the wrong `schemaVersion`. |
+| `invalid-engine-state` | Nested `CartStateBundle` failed `parseCartStateBundle`. |
+| `unsupported-schema` | `schemaVersion` is newer than 2. |
+| `missing-migration` | No registered step from the snapshot's schema to the next integer. |
+| `invalid-migration-result` | A `migrate` function threw, produced the wrong schema, or failed validation. |
+
+Disjoint live cart state still throws `IncompatibleCartStateError` from `importState` / `importSnapshot` after the envelope has been migrated. Missing envelope paths surface as `missing-migration` diagnostics; `importSnapshot` wraps those details in `IncompatibleCartStateError`.
+
+The current engine table is only 1→2 (`SNAPSHOT_SCHEMA_VERSION` is 2). When a later envelope schema ships, compose host migrations after that table; each step must advance by exactly one. Duplicate `from` values throw when the registry is created.
+
+## Runtime
+
+```ts
+const envelope = await cart.exportSnapshot({
+  cartVersion: '3',
+  hostState: { sceneId: 'alpha' },
+  modules: [{ id: 'overlay.module', version: '1' }],
+});
+await cart.importSnapshot(envelope);
+await cart.importState(legacyBundle); // still a CartStateBundle
+await cart.importState(envelope);     // envelope → engineState
+```
+
+`exportSnapshot` wraps `exportState()` plus clock / rng. `importSnapshot` always migrates. Hosts restore `hostState` themselves. W/E localStorage helpers still store the cart bundle; `parseStoredCartState` migrates a stored envelope first and returns null if the path is missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "CyberArt host engine: mount carts, events, capability manifests, geometry, runtime groups, and a Node/jsdom headless entry.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",