@cyberart-io/engine 0.0.5 → 0.0.7

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/docs/visual-layers.md

@@ -0,0 +1,151 @@
+# Visual layers
+
+Versioned overlay / mask / sprite declarations with deterministic show, hide, replace, and crossfade. Presentation cues own timing. The compositor swaps `ImageData` / canvas sources in one `setLayer` so a partial or failed asset never becomes the live frame.
+
+Hosts persist `controller.snapshot()` JSON inside envelope `hostState`. This module does not edit the snapshot envelope.
+
+Related: [presentation cue](presentation-cue.md), [compositor](compositor.md), [asset resolver](asset-resolver.md), [snapshots](snapshots.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-66-visual-layers.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createVisualLayerController` from `@cyberart-io/engine` | Bind `host.state.accepted` to a preloaded overlay version. |
+| Vitest / jsdom | same controller after `installHeadlessCanvas()` | `captureVisualLayers` / `captureComposedFrame` / `inspect`. |
+
+Generic ids only: overlay `overlay`, versions `v1` / `v2`, `sceneId: 'alpha'`. Cyberart owns presentation; the host owns which version is authoritative.
+
+## `createVisualLayerController(options)`
+
+```ts
+import {
+  ASSET_READY_EVENT,
+  HOST_STATE_ACCEPTED_EVENT,
+  createCompositor,
+  createRuntimeGroup,
+  createVisualLayerController,
+} from '@cyberart-io/engine';
+
+const group = createRuntimeGroup({
+  participants: [{ id: 'base', cart: baseCart }],
+});
+const compositor = createCompositor({
+  group,
+  host: { color: '#000080' },
+  layers: [
+    { id: 'base', order: 0 },
+    { id: 'overlay', order: 1, visible: false },
+  ],
+});
+const layers = createVisualLayerController({
+  compositor,
+  sceneId: 'alpha',
+  originFrame: 0,
+  layers: [
+    {
+      id: 'overlay',
+      kind: 'layer', // also 'mask' | 'sprite'
+      order: 1,
+      initialVersion: 'v1',
+      fallback: 'keep-prior',
+      versions: [
+        { id: 'v1', assetId: 'overlay.v1', provenance: { source: 'fixture', version: 'v1' } },
+        { id: 'v2', assetId: 'overlay.v2', provenance: { source: 'fixture', version: 'v2' } },
+      ],
+    },
+  ],
+  onAccepted: [{ layerId: 'overlay', toVersion: 'v2', kind: 'replace', durationFrames: 2 }],
+});
+
+layers.registerSource('overlay.v1', imageV1);
+layers.registerSource('overlay.v2', imageV2);
+layers.handleHostEvent({ type: ASSET_READY_EVENT, kind: 'state', payload: { id: 'overlay.v1' } });
+layers.handleHostEvent({ type: ASSET_READY_EVENT, kind: 'state', payload: { id: 'overlay.v2' } });
+layers.handleHostEvent({
+  type: HOST_STATE_ACCEPTED_EVENT,
+  kind: 'state',
+  payload: { sceneId: 'alpha' },
+});
+layers.step(2);
+const capture = layers.captureComposedFrame();
+// capture.imageData is v2; inspect().activeVersion is 'v2'
+```
+
+`kind: 'mask'` defaults `pointerEvents` to `none`. Incoming crossfade pixels use compositor layer `overlay:incoming` (`visualIncomingLayerId('overlay')`).
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `compositor` | required | `createCompositor` handle. The controller drives `setLayer` / `addLayer`. |
+| `layers` | required | Versioned declarations with stable ids. |
+| `preloader` | none | Optional `createAssetPreloader`. `get(id)` counts as ready when no event has been recorded yet. |
+| `originFrame` | `0` | Passed to `createPresentationTimeline`. |
+| `reducedMotion` | `false` | Host flag. Instant-complete cues still wait for a ready source before revealing. |
+| `sceneId` | none | When set, `host.state.accepted` with a different `sceneId` is ignored. |
+| `fallback` | `'keep-prior'` | Default when a version asset fails: keep the last valid frame, `'hide'`, or `{ version: 'v1' }`. |
+| `onAccepted` | none | Transitions to play when `host.state.accepted` has no `overlayId`/`version`. |
+| `dispatch` | none | Optional mailbox for `visual.layer.*` events. Failed events use `kind: 'diagnostic'`. |
+
+Payload `{ overlayId, version }` (or `layerId`) on `host.state.accepted` plays a replace of that version (duration 2). `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` are keyed by payload `id` (`overlay.v2`).
+
+### Handle
+
+| Member | Meaning |
+|---|---|
+| `registerSource(assetId, imageData \| canvas)` | Pixel buffer for that asset. Cloned for `ImageData`. Required before a version can become visible. |
+| `handleHostEvent(event)` | `host.state.accepted`, `ASSET_READY_EVENT`, `ASSET_FAILED_EVENT`. |
+| `play(spec)` | `CueSpec` plus `layerId`, `kind` (`show` / `hide` / `replace` / `crossfade`), `toVersion`. |
+| `step(frames?)` | Advance the presentation timeline (default 1). Returns new `visual.layer.*` events. |
+| `override(layerId, version \| null)` | Host override. Ready versions swap immediately; missing assets keep the prior frame. |
+| `snapshot()` | JSON-serializable visibility, versions, transition position, provenance, assets, events, diagnostics. |
+| `restore(json)` | `{ ok: true, snapshot }` or `{ ok: false, errors }`. Pixels are not in the JSON — register sources first. |
+| `inspect()` | Per-layer `activeVersion`, `pendingVersion`, `committedVersion`, transition progress. |
+| `captureComposedFrame()` | Delegates to the compositor (headless `ImageData` + `declaredOrder`). |
+| `destroy()` | Drops cues. Does not destroy the compositor. |
+
+`captureVisualLayers(controller)` returns `{ frame, layers }` (also from `@cyberart-io/engine/headless`).
+
+## Atomic swaps
+
+Replace does not paint `v2` until the cue completes **and** `overlay.v2` is ready with a registered source. Mid-cue pixels stay on the last valid frame (`v1`). Crossfade paints `overlay:incoming` only after that same gate; opacity follows cue progress (outgoing `1 - t`, incoming `t`). If the cue ends before the asset is ready, the pending version waits for `ASSET_READY_EVENT` and then swaps in one `setLayer`. `ASSET_FAILED_EVENT` keeps the prior frame and records a diagnostic (`code: 'asset-failed'`).
+
+## Snapshot / restore
+
+`snapshot()` survives `JSON.parse(JSON.stringify(snapshot))`. Hosts store it in envelope `hostState` (for example `{ sceneId: 'alpha', visualLayers: snapshot }`). Restore:
+
+| When | Result |
+|---|---|
+| Mid-transition | Same `frame`, `committedVersion`, and cue `progress`. Further `step` continues the fade. |
+| After complete | `activeVersion` is the committed version; `transition` is `null`. |
+
+Restore does not replay host events. It reapplies version ids onto sources already registered on that controller. `schemaVersion` is `VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION` (`1`).
+
+## Public exports
+
+| Export | Meaning |
+|---|---|
+| `createVisualLayerController` | Constructor. |
+| `captureVisualLayers` | `{ frame, layers }` helper. |
+| `visualIncomingLayerId` / `VISUAL_LAYER_INCOMING_SUFFIX` | Incoming compositor id (`overlay:incoming`). |
+| `VISUAL_LAYER_KINDS` / `isVisualLayerKind` | `'layer'` \| `'mask'` \| `'sprite'`. |
+| `VISUAL_LAYER_TRANSITIONS` / `isVisualLayerTransitionKind` | `'show'` \| `'hide'` \| `'replace'` \| `'crossfade'`. |
+| `VISUAL_LAYER_EVENTS` / `isVisualLayerEventType` | Lifecycle type names. |
+| `VISUAL_LAYER_REVEALED_EVENT` | `'visual.layer.revealed'` |
+| `VISUAL_LAYER_HIDDEN_EVENT` | `'visual.layer.hidden'` |
+| `VISUAL_LAYER_TRANSITION_STARTED_EVENT` | `'visual.layer.transition-started'` |
+| `VISUAL_LAYER_TRANSITION_COMPLETED_EVENT` | `'visual.layer.transition-completed'` |
+| `VISUAL_LAYER_FAILED_EVENT` | `'visual.layer.failed'` |
+| `VISUAL_LAYER_FAILURE_CODES` | `'asset-failed'` \| `'missing-source'` \| `'unknown-layer'` \| `'unknown-version'` \| `'invalid-snapshot'` |
+| `VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION` | `1` |
+| `HOST_STATE_ACCEPTED_EVENT` | `'host.state.accepted'` |
+
+Types: `VisualLayerDeclaration`, `VisualLayerVersionDeclaration`, `VisualLayerCueSpec`, `VisualLayerController`, `VisualLayerControllerSnapshot`, `VisualLayerInspect`, `VisualLayerEvent`, `VisualLayerDiagnostic`, `VisualLayerFallbackPolicy`, `VisualLayerAcceptedBinding`, `PlayVisualLayerResult`, `RestoreVisualLayerResult`, `CreateVisualLayerControllerOptions`, `VisualLayerCapture`, and related aliases.
+
+Do not `await` wall-clock loads inside cart `update` / `render`. Drive `step` from the same clock as deterministic `cart.step`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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",