@cyberart-io/engine 0.0.6 → 0.0.7

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/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`.

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