@cyberart-io/engine 0.0.4 → 0.0.6

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.4",
+  "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",