@cyberart-io/engine 0.0.6 → 0.0.8

package/README.md

@@ -1,6 +1,6 @@
 # `@cyberart-io/engine`
 
-An engine for building animated, interactive, generative programs for the web. You write a **cart** — a small object with `getDefaultState` (initial state), `update` (advance that state each tick), and `render` (draw it). That is a state machine in a loop that paints to the screen. The engine mounts it into a DOM element you own, runs the loop, and gives you pause, snapshot, events, and save/load.
+An engine for building animated, interactive, generative programs for the web. You write a **cart** — a small object with `getDefaultState` (initial state), `update` (advance that state each tick), and optional `render` (draw it). A render cart is a state machine in a loop that paints to the screen. A calculation cart runs the same state machine without a canvas, and talks to a sibling that does paint. The engine mounts it into a DOM element you own, runs the loop, and gives you pause, snapshot, events, and save/load.
 
 ## License
 
@@ -90,6 +90,7 @@ 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`, software Canvas2D, `compareImageData` / `assertPixelsEqual`, inspect / screenshot
+- [Frame benchmarking](docs/frame-benchmark.md) — `benchmarkCartFrames` (headless) and optional `onFrameTiming` (live); zero cost when unset
 - [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
@@ -97,7 +98,9 @@ Full API for the event router, deterministic replay, and CI harness (so agents c
 - [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`
+- [Calculation carts](docs/calculation-carts.md) — `kind: 'calculation'`, update + events without paint; sibling render carts still paint
 - [Compositor](docs/compositor.md) — `createCompositor`, transparent stacking, `screen` blend, `writeComposedFrame`
+- [Visual layers](docs/visual-layers.md) — `createVisualLayerController`, versioned overlay `v1`/`v2`, deterministic swaps, `hostState` JSON
 - [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`
@@ -112,18 +115,20 @@ A cart is an `AnimationCart`. Required:
 |---|---|
 | `getDefaultState` | Build the initial `state`. Use `R` (`Random`) for anything that should follow the seed. |
 | `update` | Advance `state` each tick. Return the next state. |
-| `render` | Draw into the 2D context (and optional `ImageData`). |
 | `metadata.id` / `name` / `frameRate` | Identity and loop rate. |
 
+`render` draws into the 2D context (and optional `ImageData`). Omit it on calculation carts (`createRuntime({ kind: 'calculation' })` or a group participant with `kind: 'calculation'`). The runtime does not call `render` and does not create a canvas for that kind. Render carts (the default) still paint as before.
+
 Useful optionals:
 
 | Piece | Role |
 |---|---|
+| `render` | Draw into the 2D context. Omit on calculation carts; the runtime will not call a no-op either. |
 | `teardown` | Dispose long-lived resources (Tone nodes, listeners) when the cart unloads. |
 | `metadata.audio` | `'tone'` if the piece needs Web Audio. Omit for a silent cart. |
 | `metadata.generative` | `true` when output is a function of the token hash. Saves then only load on the same seed. |
 
-Callbacks also receive `DimensionContext` (`width` / `height` and derived size fields), `KeyboardManager`, `PointerManager`, and an optional `HostChannel`. You do not have to use them. Types live on the package: `AnimationCart`, `Random`, `DimensionContext`, `KeyboardManager`, `PointerManager`, `HostChannel`.
+Callbacks also receive `DimensionContext` (`width` / `height` and derived size fields), `KeyboardManager`, `PointerManager`, and an optional `HostChannel`. You do not have to use them. Types live on the package: `AnimationCart`, `CartKind`, `Random`, `DimensionContext`, `KeyboardManager`, `PointerManager`, `HostChannel`.
 
 `Random` is seed-stable: `R.dec(min, max)`, `R.int(min, max)`, `R.bool()`, `R.choose(list)`.
 
@@ -159,6 +164,7 @@ const cart = runtime.mount(artProject, {
 | `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. |
+| `kind` | `'render'` | `'calculation'` skips canvas construction and paint. `getDefaultState`, `update`, and host-channel events still run. |
 
 `CartHandle` (what `mount` returns):
 
@@ -182,9 +188,9 @@ const cart = runtime.mount(artProject, {
 | `tokenData` | Live hash and token id. |
 | `getCartState()` | Live object for debug UI. Not JSON-safe — use export/import for saves. |
 
-`runtime.destroy()` tears down the runtime. `runtime.unlockAudio()` is for an early click before `mount`. `runtime.onError` receives frame errors (`phase`, `consecutive`, `stopped`).
+`runtime.destroy()` tears down the runtime. `runtime.unlockAudio()` is for an early click before `mount`. `runtime.onError` receives frame errors (`phase`, `consecutive`, `stopped`). `runtime.kind` is `'render'` (default) or `'calculation'`.
 
-One cart per runtime. A second `mount` unloads the first. Several pieces on a page means several `createRuntime()` calls, or one `createRuntimeGroup()` that attaches each mailbox to a shared router and locksteps a deterministic clock.
+One cart per runtime. A second `mount` unloads the first. Several pieces on a page means several `createRuntime()` calls, or one `createRuntimeGroup()` that attaches each mailbox to a shared router and locksteps a deterministic clock. Calculation participants (`kind: 'calculation'`) share that group without a canvas; see [calculation carts](docs/calculation-carts.md).
 
 ## Audio
 
@@ -267,6 +273,8 @@ CI and agents should drive the **same** `createRuntime({ deterministic })` path.
 
 Full options, `click` clock rule, Node-only `captureFrame`, remount, visual asserts, and the reproduce command: [headless harness](docs/headless-harness.md).
 
+Hash / trait cost A/B without a browser: `benchmarkCartFrames` / `formatFrameBenchmarkResult` from the same headless entry. Live overlays: `runtime.onFrameTiming`. Details and the zero-overhead-when-off contract: [frame benchmarking](docs/frame-benchmark.md).
+
 ```ts
 import { createHeadlessHarness } from '@cyberart-io/engine/headless';
 
@@ -418,17 +426,57 @@ import { createRuntimeGroup } from '@cyberart-io/engine';
 const group = createRuntimeGroup({
   origin: 0,
   participants: [
-    { id: 'effects', cart: effectsCart, emit: ['ambience.intent.*'], subscribe: ['host.state.*'] },
-    { id: 'ambience', cart: ambienceCart, subscribe: ['ambience.intent.*'] },
+    { id: 'world', cart: worldCart, kind: 'calculation', emit: ['host.intent.*'], subscribe: ['host.state.*'] },
+    { id: 'overlay', cart: overlayCart, subscribe: ['host.intent.*'] },
   ],
 });
-group.publish({ type: 'host.state.accepted', kind: 'state', payload: { id: 'north' } });
+group.publish({ type: 'host.state.scene-changed', kind: 'state', payload: { sceneId: 'alpha' } });
 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). Causation trees, redaction, and tape replay: [replay inspector](docs/replay-inspector.md).
+Headless / CI: `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless` is the same handle after `installHeadlessCanvas()`. Full options: [runtime group](docs/runtime-group.md). Calculation carts (no canvas / paint): [calculation carts](docs/calculation-carts.md). Causation trees, redaction, and tape replay: [replay inspector](docs/replay-inspector.md).
+
+## Visual layers
+
+Durable overlay / mask / sprite versions (`v1`, `v2`) with deterministic show, hide, replace, and crossfade. An accepted `host.state.accepted` (`sceneId: 'alpha'`) runs a presentation cue; the compositor reveals a **preloaded** alternate source in one `setLayer`. Failed assets keep the prior valid frame and emit `visual.layer.failed`. Persist `controller.snapshot()` in envelope `hostState` — do not put pixels in the envelope.
+
+```ts
+import {
+  ASSET_READY_EVENT,
+  HOST_STATE_ACCEPTED_EVENT,
+  createVisualLayerController,
+} from '@cyberart-io/engine';
+
+const layers = createVisualLayerController({
+  compositor,
+  sceneId: 'alpha',
+  layers: [
+    {
+      id: 'overlay',
+      kind: 'layer',
+      initialVersion: 'v1',
+      versions: [
+        { id: 'v1', assetId: 'overlay.v1' },
+        { id: 'v2', assetId: 'overlay.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.v2' } });
+layers.handleHostEvent({
+  type: HOST_STATE_ACCEPTED_EVENT,
+  kind: 'state',
+  payload: { sceneId: 'alpha' },
+});
+layers.step(2);
+```
+
+Headless capture: `captureVisualLayers(layers)` from `@cyberart-io/engine` or `@cyberart-io/engine/headless`. Full API: [visual layers](docs/visual-layers.md).
 
 ## Normalized geometry
 
@@ -594,7 +642,7 @@ The engine prefers, in order:
 2. The container’s first `<canvas>`
 3. A canvas it creates (no `id="canvas"`)
 
-A canvas the host adopted is left in place on destroy; a canvas the engine created is removed. Both `cart.destroy()` and `runtime.destroy()` are idempotent.
+A canvas the host adopted is left in place on destroy; a canvas the engine created is removed. Both `cart.destroy()` and `runtime.destroy()` are idempotent. `createRuntime({ kind: 'calculation' })` never creates or adopts a canvas (`cart.canvas` is `undefined`).
 
 ## Limits
 
@@ -605,7 +653,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/` (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.
+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, visual layers, browser harness, replay inspector, MIDI, executable modules, snapshots, audio, and calculation carts), 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

package/dist/headless.d.ts

@@ -254,11 +254,16 @@ type AnimationTiming = {
     deltaSinceLastUpdate: number;
     deltaSinceLastRender: number;
 };
+type CartKind = 'render' | 'calculation';
 type AnimationCart<T = unknown, TFeatureState = undefined> = {
     getDefaultFeatureState?: (R: Random, dimensionContext: DimensionContext, rawParams: number[], keyboardManager: KeyboardManager, customState?: Partial<T>, pointerManager?: PointerManager, gameManager?: unknown, hostChannel?: HostChannel) => TFeatureState;
     getDefaultState: (R: Random, dimensionContext: DimensionContext, rawParams: number[], keyboardManager: KeyboardManager, customState?: Partial<T>, pointerManager?: PointerManager, gameManager?: unknown, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => T;
     update: (R: Random, framesElapsed: number, rawParams: number[], dimensionContext: DimensionContext, state: T, keyboardManager: KeyboardManager, pointerManager?: PointerManager, gameManager?: unknown, timing?: AnimationTiming, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => T;
-    render: (R: Random, framesElapsed: number, rawParams: number[], dimensionContext: DimensionContext, state: T, drawingContext: CanvasRenderingContext2D, imageData: ImageData, pointerManager?: PointerManager, gameManager?: unknown, timing?: AnimationTiming, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => void;
+    /**
+     * Draw into the 2D context. Optional on calculation carts (`kind:
+     * 'calculation'`); the runtime does not call it and does not create a canvas.
+     */
+    render?: (R: Random, framesElapsed: number, rawParams: number[], dimensionContext: DimensionContext, state: T, drawingContext: CanvasRenderingContext2D, imageData: ImageData, pointerManager?: PointerManager, gameManager?: unknown, timing?: AnimationTiming, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => void;
     adjust?: Record<string, {
         type: 'switch';
         immediate?: boolean;
@@ -328,6 +333,73 @@ type CartStateBundle = {
     state: unknown;
 };
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host-controlled time, input, and asset completion for deterministic replays.
+ * Production kaleidoscope / Art Blocks playback does not enable this mode.
+ * Logical asset URLs are resolved by the host preloader (`assetResolver.ts`);
+ * this module only times `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` delivery.
+ */
+
+type PointerKind = 'down' | 'move' | 'up';
+type ScriptedAction = {
+    atFrame: number;
+} & ({
+    type: 'pointer';
+    pointer: {
+        kind: PointerKind;
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'event';
+    event: HostEvent;
+} | {
+    type: 'asset';
+    id: string;
+    status: 'ready' | 'failed';
+    /** Optional structured failure or resolved resource. Envelope is unchanged. */
+    detail?: unknown;
+});
+type DeterministicRuntimeOptions = {
+    /** Virtual clock origin in ms. Default 0. */
+    origin?: number;
+    /** Actions applied at the start of `atFrame`, before `update`. */
+    actions?: ScriptedAction[];
+};
+type ClockSnapshot = {
+    now: number;
+    framesElapsed: number;
+    frameRate: number;
+};
+type ReplayMetadata = {
+    seed: string;
+    clock: ClockSnapshot;
+    rng: RandomState;
+    actions: ScriptedAction[];
+    applied: AppliedAction[];
+    events: HostEvent[];
+    state: unknown;
+};
+type AppliedAction = {
+    frame: number;
+    action: ScriptedAction;
+};
+
+type FrameTimingSample = {
+    frame: number;
+    updateMs: number;
+    renderMs: number;
+    drawMs: number;
+    totalMs: number;
+};
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -398,65 +470,6 @@ type ExportSnapshotOptions = {
     runtimeVersion?: string;
 };
 
-/**
- * Copyright (c) 2026 Aaron Boyarsky
- * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
- * See packages/engine/LICENSE
- *
- * Host-controlled time, input, and asset completion for deterministic replays.
- * Production kaleidoscope / Art Blocks playback does not enable this mode.
- * Logical asset URLs are resolved by the host preloader (`assetResolver.ts`);
- * this module only times `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` delivery.
- */
-
-type PointerKind = 'down' | 'move' | 'up';
-type ScriptedAction = {
-    atFrame: number;
-} & ({
-    type: 'pointer';
-    pointer: {
-        kind: PointerKind;
-        x: number;
-        y: number;
-    };
-} | {
-    type: 'key';
-    key: string;
-} | {
-    type: 'event';
-    event: HostEvent;
-} | {
-    type: 'asset';
-    id: string;
-    status: 'ready' | 'failed';
-    /** Optional structured failure or resolved resource. Envelope is unchanged. */
-    detail?: unknown;
-});
-type DeterministicRuntimeOptions = {
-    /** Virtual clock origin in ms. Default 0. */
-    origin?: number;
-    /** Actions applied at the start of `atFrame`, before `update`. */
-    actions?: ScriptedAction[];
-};
-type ClockSnapshot = {
-    now: number;
-    framesElapsed: number;
-    frameRate: number;
-};
-type ReplayMetadata = {
-    seed: string;
-    clock: ClockSnapshot;
-    rng: RandomState;
-    actions: ScriptedAction[];
-    applied: AppliedAction[];
-    events: HostEvent[];
-    state: unknown;
-};
-type AppliedAction = {
-    frame: number;
-    action: ScriptedAction;
-};
-
 declare const ASSET_KINDS: readonly ["image", "audio", "font", "spritesheet"];
 type AssetKind = (typeof ASSET_KINDS)[number];
 declare const ASSET_FAILURE_CODES: readonly ["timeout", "cors", "not-found", "invalid", "aborted", "resolver"];
@@ -625,6 +638,7 @@ type FrameErrorInfo = {
     consecutive: number;
     stopped: boolean;
 };
+
 type CreateRuntimeOptions = {
     /** Required mount point. The runtime creates or adopts a canvas inside this element. */
     container: HTMLElement;
@@ -669,6 +683,16 @@ type CreateRuntimeOptions = {
      * this id does not close Tone for remaining carts.
      */
     audioParticipantId?: string;
+    /**
+     * `'calculation'` skips canvas construction and paint. `getDefaultState`,
+     * `update`, and host-channel events still run. Default `'render'`.
+     */
+    kind?: CartKind;
+    /**
+     * Optional per-frame update/render/draw timings. Can also be assigned later
+     * via `runtime.onFrameTiming`. Unset = no `performance.now` in the draw loop.
+     */
+    onFrameTiming?: (sample: FrameTimingSample) => void;
 };
 type MountOptions<T = unknown> = {
     /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
@@ -747,7 +771,14 @@ type CyberArtRuntime = {
     readonly assets: AssetPreloader | undefined;
     /** Shared broker when `createRuntime({ audioBroker })` was set. */
     readonly audioBroker: AudioBroker | undefined;
+    /** `'render'` (default) or `'calculation'` (no canvas / paint). */
+    readonly kind: CartKind;
     onError?: (error: unknown, info: FrameErrorInfo) => void;
+    /**
+     * Optional per-frame update/render/draw timings. Unset = zero overhead in the
+     * draw loop (single null check). Same pattern as `onError`.
+     */
+    onFrameTiming?: (sample: FrameTimingSample) => void;
 };
 
 /**
@@ -838,7 +869,7 @@ type EventRouter = {
  * locksteps a deterministic clock. Carts never receive the router object.
  */
 
-type RuntimeGroupKind = 'render' | 'calculation';
+type RuntimeGroupKind = CartKind;
 /**
  * Optional capability-shaped attach hints. Explicit participant `emit` /
  * `subscribe` / `authoritative` win. Do not import the capability manifest
@@ -856,7 +887,7 @@ type RuntimeGroupFrameError = {
 type RuntimeGroupParticipantConfig<T = unknown> = {
     id: string;
     cart: AnimationCart<T>;
-    /** Rendered surface vs calculation cart (still a real `AnimationCart`). */
+    /** Rendered surface vs calculation cart (update + events, no canvas / paint). */
     kind?: RuntimeGroupKind;
     seed?: CreateRuntimeOptions['seed'];
     container?: HTMLElement;
@@ -944,6 +975,20 @@ type CompositorBlendMode = (typeof COMPOSITOR_BLEND_MODES)[number];
 declare const COMPOSITOR_CLEAR_POLICIES: readonly ["transparent", "opaque"];
 type CompositorClearPolicy = (typeof COMPOSITOR_CLEAR_POLICIES)[number];
 type CompositorPointerEvents = 'auto' | 'none';
+declare const COMPOSITOR_SOURCE_KINDS: readonly ["participant", "image", "canvas"];
+type CompositorSourceKind = (typeof COMPOSITOR_SOURCE_KINDS)[number];
+type CompositorParticipantSource = {
+    kind: 'participant';
+};
+type CompositorImageSource = {
+    kind: 'image';
+    image: ImageData;
+};
+type CompositorCanvasSource = {
+    kind: 'canvas';
+    canvas: HTMLCanvasElement;
+};
+type CompositorLayerSource = CompositorParticipantSource | CompositorImageSource | CompositorCanvasSource;
 type CompositorClip = {
     x: number;
     y: number;
@@ -959,6 +1004,11 @@ type CompositorLayerConfig = {
     clip?: CompositorClip;
     pointerEvents?: CompositorPointerEvents;
     clearPolicy?: CompositorClearPolicy;
+    /**
+     * Pixel source. Default `participant` reads the runtime-group canvas.
+     * `image` / `canvas` swap atomically via `setLayer` / `addLayer`.
+     */
+    source?: CompositorLayerSource;
 };
 type CompositorLayerInspect = {
     id: string;
@@ -969,6 +1019,7 @@ type CompositorLayerInspect = {
     clip: CompositorClip | null;
     pointerEvents: CompositorPointerEvents;
     clearPolicy: CompositorClearPolicy;
+    sourceKind: CompositorSourceKind;
 };
 type ComposedFrame = {
     imageData: ImageData;
@@ -1001,6 +1052,7 @@ type Compositor = {
      */
     resize(width: number, height: number, dpr?: number): void;
     setLayer(id: string, patch: Partial<Omit<CompositorLayerConfig, 'id'>>): void;
+    addLayer(config: CompositorLayerConfig): void;
     layer(id: string): CompositorLayerInspect;
     layers(): CompositorLayerInspect[];
     pointerTarget(x: number, y: number): string | undefined;
@@ -1411,6 +1463,14 @@ type CueView = {
     progress: number;
     repeatIndex: number;
 };
+type PlayCueResult = {
+    ok: true;
+    cue: CueView;
+} | {
+    ok: false;
+    reason: 'duplicate' | 'invalid';
+    detail: string;
+};
 
 /**
  * Copyright (c) 2026 Aaron Boyarsky
@@ -1494,6 +1554,207 @@ declare function createHeadlessAudioAdapter(options?: {
     originFrame?: number;
 }): HeadlessAudioAdapter;
 
+declare const VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const VISUAL_LAYER_KINDS: readonly ["layer", "mask", "sprite"];
+type VisualLayerKind = (typeof VISUAL_LAYER_KINDS)[number];
+declare const VISUAL_LAYER_TRANSITIONS: readonly ["show", "hide", "replace", "crossfade"];
+type VisualLayerTransitionKind = (typeof VISUAL_LAYER_TRANSITIONS)[number];
+declare const VISUAL_LAYER_EVENTS: readonly ["visual.layer.revealed", "visual.layer.hidden", "visual.layer.transition-started", "visual.layer.transition-completed", "visual.layer.failed"];
+type VisualLayerEventType = (typeof VISUAL_LAYER_EVENTS)[number];
+declare const VISUAL_LAYER_FAILURE_CODES: readonly ["asset-failed", "missing-source", "unknown-layer", "unknown-version", "invalid-snapshot"];
+type VisualLayerFailureCode = (typeof VISUAL_LAYER_FAILURE_CODES)[number];
+type VisualLayerAssetStatus = 'pending' | 'ready' | 'failed';
+type VisualLayerFallbackPolicy = 'keep-prior' | 'hide' | {
+    version: string;
+};
+type VisualLayerVersionDeclaration = {
+    id: string;
+    assetId: string;
+    provenance?: AssetProvenance;
+};
+type VisualLayerDeclaration = {
+    id: string;
+    kind: VisualLayerKind;
+    versions: readonly VisualLayerVersionDeclaration[];
+    initialVersion?: string;
+    compositorLayerId?: string;
+    incomingLayerId?: string;
+    order?: number;
+    blend?: CompositorBlendMode;
+    clip?: CompositorClip;
+    pointerEvents?: CompositorPointerEvents;
+    clearPolicy?: CompositorClearPolicy;
+    fallback?: VisualLayerFallbackPolicy;
+};
+type VisualLayerAcceptedBinding = {
+    layerId: string;
+    toVersion: string;
+    kind?: VisualLayerTransitionKind;
+    durationFrames?: number;
+    delayFrames?: number;
+    easing?: CueEasing;
+    idempotencyKey?: string;
+};
+type VisualLayerCueSpec = CueSpec & {
+    layerId: string;
+    kind: VisualLayerTransitionKind;
+    toVersion?: string;
+    fromVersion?: string;
+};
+type VisualLayerTransitionInspect = {
+    kind: VisualLayerTransitionKind;
+    progress: number;
+    fromVersion: string | null;
+    toVersion: string | null;
+    cueKey: string;
+    startFrame: number;
+    durationFrames: number;
+    delayFrames: number;
+    easing: CueEasing;
+};
+type VisualLayerInspect = {
+    id: string;
+    kind: VisualLayerKind;
+    visible: boolean;
+    activeVersion: string | null;
+    pendingVersion: string | null;
+    committedVersion: string | null;
+    opacity: number;
+    order: number;
+    provenance: AssetProvenance | null;
+    overrideVersion: string | null;
+    transition: VisualLayerTransitionInspect | null;
+};
+type VisualLayerEvent = {
+    type: VisualLayerEventType;
+    atFrame: number;
+    layerId: string;
+    version?: string;
+    kind?: VisualLayerTransitionKind;
+    progress: number;
+    code?: VisualLayerFailureCode;
+};
+type VisualLayerDiagnostic = {
+    code: VisualLayerFailureCode;
+    layerId: string;
+    version?: string;
+    assetId?: string;
+    message: string;
+    atFrame: number;
+    failure?: AssetFailure;
+};
+type VisualLayerSnapshotRow = {
+    id: string;
+    kind: VisualLayerKind;
+    visible: boolean;
+    committedVersion: string | null;
+    pendingVersion: string | null;
+    activeVersion: string | null;
+    opacity: number;
+    order: number;
+    overrideVersion: string | null;
+    provenance: AssetProvenance | null;
+    fallback: VisualLayerFallbackPolicy;
+    transition: VisualLayerTransitionInspect | null;
+};
+type VisualLayerControllerSnapshot = {
+    schemaVersion: typeof VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION;
+    frame: number;
+    sceneId: string | null;
+    reducedMotion: boolean;
+    layers: VisualLayerSnapshotRow[];
+    assets: Record<string, VisualLayerAssetStatus>;
+    events: VisualLayerEvent[];
+    diagnostics: VisualLayerDiagnostic[];
+};
+type PlayVisualLayerResult = PlayCueResult;
+type RestoreVisualLayerResult = {
+    ok: true;
+    snapshot: VisualLayerControllerSnapshot;
+} | {
+    ok: false;
+    errors: VisualLayerDiagnostic[];
+};
+type CreateVisualLayerControllerOptions = {
+    compositor: Compositor;
+    layers: readonly VisualLayerDeclaration[];
+    preloader?: AssetPreloader;
+    originFrame?: number;
+    reducedMotion?: boolean;
+    sceneId?: string;
+    fallback?: VisualLayerFallbackPolicy;
+    onAccepted?: readonly VisualLayerAcceptedBinding[];
+    dispatch?: (event: HostEvent) => void;
+};
+type VisualLayerController = {
+    registerSource(assetId: string, source: ImageData | HTMLCanvasElement): void;
+    handleHostEvent(event: HostEvent): void;
+    override(layerId: string, version: string | null): void;
+    play(spec: VisualLayerCueSpec): PlayVisualLayerResult;
+    step(frames?: number): VisualLayerEvent[];
+    snapshot(): VisualLayerControllerSnapshot;
+    restore(input: unknown): RestoreVisualLayerResult;
+    inspect(): VisualLayerInspect[];
+    captureComposedFrame(): ComposedFrame;
+    destroy(): void;
+    readonly frame: number;
+    readonly sceneId: string | null;
+    readonly compositor: Compositor;
+};
+type VisualLayerCapture = {
+    frame: ComposedFrame;
+    layers: VisualLayerInspect[];
+};
+declare function captureVisualLayers(controller: VisualLayerController): VisualLayerCapture;
+declare function createVisualLayerController(options: CreateVisualLayerControllerOptions): VisualLayerController;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Cart-agnostic update/render frame benchmark for CI and agent workflows.
+ * Prefer this over ad-hoc vitest probes when evaluating hash / trait cost.
+ */
+
+type FrameBenchmarkOptions = {
+    /** Measured frames after warmup. Default 30. */
+    frames?: number;
+    /** Discarded frames before measurement. Default 5. */
+    warmupFrames?: number;
+    /** Simulated frame advance in ms. Default 1000/60. */
+    frameStepMs?: number;
+    width?: number;
+    height?: number;
+    tokenId?: string;
+    /**
+     * Mutate state after `getDefaultState` (e.g. skip Tone init in jsdom by
+     * setting `audioContextStarted = true`).
+     */
+    prepareState?: (state: unknown, featureState: unknown) => void;
+    /** Optional stub drawing context; defaults to a no-op `putImageData`. */
+    drawingContext?: CanvasRenderingContext2D;
+};
+type FrameBenchmarkResult = {
+    frames: number;
+    updateAvgMs: number;
+    renderAvgMs: number;
+    totalAvgMs: number;
+    updateMaxMs: number;
+    renderMaxMs: number;
+    estFps: number;
+    updatePct: number;
+    renderPct: number;
+};
+/**
+ * Run a cart's update/render loop headlessly and report average / max phase
+ * timings. Does not start audio or mount a live AnimationManager — suitable
+ * for jsdom vitest and agent hash probes.
+ */
+declare function benchmarkCartFrames<T, TFeatureState = undefined>(cart: AnimationCart<T, TFeatureState>, hash: string, rawParams: number[], options?: FrameBenchmarkOptions): FrameBenchmarkResult;
+/** Round timing fields for stable console / snapshot logging. */
+declare function formatFrameBenchmarkResult(result: FrameBenchmarkResult, digits?: number): Record<string, number>;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -1501,7 +1762,8 @@ declare function createHeadlessAudioAdapter(options?: {
  *
  * Node/jsdom test helpers. Import from `@cyberart-io/engine/headless`.
  * Production carts and browser hosts must import `@cyberart-io/engine` instead
- * so Vite never walks `node:fs/promises`.
+ * so Vite never walks `node:fs/promises`. `createHeadlessMultiCartHarness`
+ * is the same group API as `createRuntimeGroup`, including calculation carts.
  */
 
 type WriteComposedFrameResult = ComposedFrame & {
@@ -1513,4 +1775,4 @@ type WriteComposedFrameResult = ComposedFrame & {
  */
 declare function writeComposedFrame(compositor: Compositor, path?: string): Promise<WriteComposedFrameResult>;
 
-export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };
+export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type FrameBenchmarkOptions, type FrameBenchmarkResult, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, benchmarkCartFrames, captureVisualLayers, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, createVisualLayerController, decodePng, encodePng, encodePngDataUrl, formatFrameBenchmarkResult, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };