@cyberart-io/engine 0.0.5 → 0.0.7

package/dist/index.d.ts

@@ -329,11 +329,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;
@@ -406,6 +411,153 @@ declare class IncompatibleCartStateError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Versioned snapshot envelope. Schema 1 is the previous engine-owned
+ * `CartStateBundle` (`CART_STATE_BUNDLE_VERSION = 1`). Schema 2 wraps that
+ * blob in `engineState` and separates host-owned payload. Hosts persist
+ * the JSON; this module is not a database.
+ */
+
+/**
+ * Current envelope schema. Independent of `CART_STATE_BUNDLE_VERSION` (still
+ * 1 inside `engineState`) and of the npm package version.
+ */
+declare const SNAPSHOT_SCHEMA_VERSION: 2;
+/** Previous supported schema: a raw `CartStateBundle`. */
+declare const LEGACY_SNAPSHOT_SCHEMA_VERSION: 1;
+/**
+ * Snapshot runtime id stamped on new envelopes. Documented independently of
+ * `packages/engine/package.json` so a schema bump does not require an npm
+ * release, and vice versa. Currently `'0.0.5'` to match the published package.
+ */
+declare const ENGINE_SNAPSHOT_RUNTIME = "0.0.5";
+/** Carts without an authored version stamp this exact string. */
+declare const UNVERSIONED_CART_VERSION = "0";
+type SnapshotDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type SnapshotCartRef = {
+    id: string;
+    version: string;
+    generative?: boolean;
+};
+type SnapshotModuleRef = {
+    id: string;
+    version: string;
+};
+type SnapshotClock = {
+    framesElapsed: number;
+    elapsedSinceStart?: number;
+    now?: number;
+    frameRate?: number;
+};
+type SnapshotAssetRef = {
+    id: string;
+    version?: string;
+    ref?: string;
+};
+type SnapshotIntegrity = {
+    alg: string;
+    hash: string;
+};
+type SnapshotProvenance = {
+    source?: string;
+    integrity?: SnapshotIntegrity;
+};
+type SnapshotEnvelope = {
+    schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;
+    runtimeVersion: string;
+    cart: SnapshotCartRef;
+    seed: string;
+    clock: SnapshotClock;
+    engineState: CartStateBundle;
+    createdAt: string;
+    modules?: SnapshotModuleRef[];
+    rng?: RandomState;
+    hostState?: unknown;
+    hostStateRef?: string;
+    assets?: SnapshotAssetRef[];
+    provenance?: SnapshotProvenance;
+};
+type LegacySnapshot = {
+    schemaVersion: number;
+    engineState: CartStateBundle;
+    seed: string;
+    clock: SnapshotClock;
+    cart?: SnapshotCartRef;
+};
+type VersionedSnapshot = SnapshotEnvelope | LegacySnapshot;
+type SnapshotEnvelopeInput = {
+    schemaVersion?: number;
+    runtimeVersion?: string;
+    cart: SnapshotCartRef;
+    seed: string;
+    clock: SnapshotClock;
+    engineState: CartStateBundle;
+    createdAt?: string;
+    modules?: SnapshotModuleRef[];
+    rng?: RandomState;
+    hostState?: unknown;
+    hostStateRef?: string;
+    assets?: SnapshotAssetRef[];
+    provenance?: SnapshotProvenance;
+};
+type ExportSnapshotOptions = {
+    cartVersion?: string;
+    modules?: SnapshotModuleRef[];
+    hostState?: unknown;
+    hostStateRef?: string;
+    assets?: SnapshotAssetRef[];
+    createdAt?: string;
+    provenance?: SnapshotProvenance;
+    runtimeVersion?: string;
+};
+type DefineSnapshotResult = {
+    ok: true;
+    snapshot: SnapshotEnvelope;
+} | {
+    ok: false;
+    errors: SnapshotDiagnostic[];
+};
+type ParseSnapshotResult = {
+    ok: true;
+    snapshot: VersionedSnapshot;
+} | {
+    ok: false;
+    errors: SnapshotDiagnostic[];
+};
+type ValidateSnapshotResult = {
+    ok: true;
+    snapshot: SnapshotEnvelope;
+} | {
+    ok: false;
+    errors: SnapshotDiagnostic[];
+};
+declare function cloneSnapshotJson<T>(value: T): T;
+/**
+ * True when `value` is the previous engine-owned blob, not an envelope.
+ * Envelopes are discriminated by `schemaVersion`.
+ */
+declare function isLegacyCartStateBundle(value: unknown): value is CartStateBundle;
+declare function isSnapshotEnvelope(value: unknown): value is SnapshotEnvelope;
+declare function isVersionedSnapshot(value: unknown): value is VersionedSnapshot;
+declare function detectSnapshotSchemaVersion(value: unknown): number | undefined;
+declare function defineSnapshot(input: SnapshotEnvelopeInput): DefineSnapshotResult;
+declare function snapshotFromCartBundle(bundle: CartStateBundle, extras?: ExportSnapshotOptions & {
+    rng?: RandomState;
+    clock?: SnapshotClock;
+}): DefineSnapshotResult;
+declare function parseSnapshot(input: SnapshotEnvelope | CartStateBundle | LegacySnapshot | string | unknown): ParseSnapshotResult;
+declare function validateSnapshot(value: unknown): ValidateSnapshotResult;
+declare function snapshotErrorsToMessage(errors: SnapshotDiagnostic[]): string;
+declare function engineStateFromEnvelope(snapshot: SnapshotEnvelope): CartStateBundle;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -617,6 +769,86 @@ declare function createFixtureAssetResolver(catalog: FixtureAssetCatalog): Asset
 declare function createHostedAssetResolver(options: HostedAssetResolverOptions): AssetResolver;
 declare function createAssetPreloader(options: CreateAssetPreloaderOptions): AssetPreloader;
 
+declare const DEFAULT_DUCK_GAIN = 0.25;
+type AudioUnlockState = 'locked' | 'unlocking' | 'unlocked' | 'failed';
+type AudioUnlockStatus = {
+    state: AudioUnlockState;
+    error?: string;
+};
+type AudioAssetStatus = 'ready' | 'failed';
+type AudioChannelInspect = {
+    id: string;
+    participantId?: string;
+    gain: number;
+    muted: boolean;
+    duckGain: number;
+    priority: number;
+    effectiveGain: number;
+};
+type AudioBrokerInspect = {
+    status: AudioUnlockStatus;
+    reducedSensory: boolean;
+    muted: boolean;
+    authorized: string[];
+    channels: AudioChannelInspect[];
+    assets: Record<string, AudioAssetStatus>;
+};
+type AudioBrokerNotice = {
+    type: 'asset';
+    id: string;
+    status: AudioAssetStatus;
+} | {
+    type: 'teardown';
+    participantId: string;
+} | {
+    type: 'mute';
+} | {
+    type: 'destroy';
+};
+type AudioBrokerListener = (notice: AudioBrokerNotice) => void;
+type ActiveAudioCue = {
+    idempotencyKey: string;
+    channelId: string;
+    participantId?: string;
+    priority: number;
+};
+type CreateAudioBrokerOptions = {
+    /**
+     * Called once on the first `unlock()`. Inject in tests. Default dynamically
+     * loads the Tone adapter (never a static `import 'tone'`).
+     */
+    toneStart?: () => Promise<void>;
+    /** Host reduced-sensory flag. Skips playback; cue events still record. */
+    reducedSensory?: boolean;
+};
+type AudioBroker = {
+    unlock(): Promise<AudioUnlockStatus>;
+    status(): AudioUnlockStatus;
+    authorize(participantId: string): void;
+    revoke(participantId: string): void;
+    isAuthorized(participantId: string | undefined): boolean;
+    setChannelGain(channelId: string, gain: number, participantId?: string): void;
+    setPriority(channelId: string, priority: number, participantId?: string): void;
+    mute(): void;
+    unmute(): void;
+    muteChannel(channelId: string, participantId?: string): void;
+    unmuteChannel(channelId: string): void;
+    duck(channelId: string, gain?: number): void;
+    unduck(channelId: string): void;
+    effectiveGain(channelId: string): number;
+    handleHostEvent(event: HostEvent): void;
+    assetStatus(id: string): AudioAssetStatus | undefined;
+    noteCueStarted(cue: ActiveAudioCue): void;
+    noteCueEnded(idempotencyKey: string): void;
+    teardown(participantId: string): void;
+    onNotice(listener: AudioBrokerListener): () => void;
+    inspect(): AudioBrokerInspect;
+    destroy(): void;
+    readonly reducedSensory: boolean;
+    readonly muted: boolean;
+};
+declare function createAudioBroker(options?: CreateAudioBrokerOptions): AudioBroker;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -661,6 +893,22 @@ type CreateRuntimeOptions = {
      * scripted `{ type: 'asset' }` actions own delivery timing.
      */
     assets?: AssetRuntimeOptions;
+    /**
+     * Shared page-level unlock broker. Optional. Carts that only set
+     * `metadata.audio: 'tone'` keep the existing `start()` / `unlockAudio()`
+     * path when this is omitted.
+     */
+    audioBroker?: AudioBroker;
+    /**
+     * Runtime-group participant id to authorize on this runtime. Teardown of
+     * 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;
 };
 type MountOptions<T = unknown> = {
     /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
@@ -691,7 +939,12 @@ type CartHandle = {
     getCartState(): unknown;
     exportState(): Promise<CartStateBundle>;
     exportStateJSON(): Promise<string>;
-    importState(bundle: CartStateBundle | string, extras?: {
+    importState(bundle: CartStateBundle | SnapshotEnvelope | string, extras?: {
+        framebuffer?: ImageData | null;
+    }): Promise<void>;
+    exportSnapshot(options?: ExportSnapshotOptions): Promise<SnapshotEnvelope>;
+    exportSnapshotJSON(options?: ExportSnapshotOptions): Promise<string>;
+    importSnapshot(input: SnapshotEnvelope | CartStateBundle | string, extras?: {
         framebuffer?: ImageData | null;
     }): Promise<void>;
     peekExportedFramebuffer(): ImageData | null;
@@ -732,6 +985,10 @@ type CyberArtRuntime = {
      * Survives cart remount; `destroy()` disposes it.
      */
     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;
 };
 declare function createRuntime(options: CreateRuntimeOptions): CyberArtRuntime;
@@ -749,7 +1006,7 @@ type ImportCartStateExtras = {
 };
 type CartStatePersister = {
     exportState: () => Promise<CartStateBundle>;
-    importState: (bundle: CartStateBundle | string, extras?: ImportCartStateExtras) => Promise<void>;
+    importState: (bundle: CartStateBundle | SnapshotEnvelope | string, extras?: ImportCartStateExtras) => Promise<void>;
     peekExportedFramebuffer?: () => ImageData | null;
     /** Live token hash; used to look up a generative cart's per-hash save. */
     peekSeed?: () => string | undefined;
@@ -783,6 +1040,53 @@ type CartStateHotkeyOptions = {
  */
 declare function registerCartStateHotkeys(keyboardManager: KeyboardManager, hostChannel: HostChannel, options?: CartStateHotkeyOptions): void;
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Step-by-step snapshot migrations. The original object is never mutated.
+ * Hosts own persistence; this registry only transforms envelopes in memory.
+ */
+
+type SnapshotMigration = {
+    from: number;
+    to: number;
+    migrate: (snapshot: unknown) => unknown;
+};
+type SnapshotMigrationRegistry = {
+    migrations: readonly SnapshotMigration[];
+    get(from: number): SnapshotMigration | undefined;
+};
+type ApplySnapshotMigrationsResult = {
+    ok: true;
+    snapshot: SnapshotEnvelope;
+} | {
+    ok: false;
+    errors: SnapshotDiagnostic[];
+};
+type ResolveImportableCartStateResult = {
+    ok: true;
+    bundle: CartStateBundle;
+    snapshot?: SnapshotEnvelope;
+} | {
+    ok: false;
+    errors: SnapshotDiagnostic[];
+};
+declare function createEngineSnapshotMigrations(): SnapshotMigration[];
+declare function createSnapshotMigrationRegistry(options?: {
+    migrations?: SnapshotMigration[];
+}): SnapshotMigrationRegistry;
+declare function defaultSnapshotMigrationRegistry(): SnapshotMigrationRegistry;
+declare function applySnapshotMigrations(snapshot: unknown, registry?: SnapshotMigrationRegistry): ApplySnapshotMigrationsResult;
+/**
+ * Detect envelope vs legacy cart bundle. Envelopes migrate first; raw
+ * `CartStateBundle` objects pass through so existing exportState/importState
+ * callers keep working.
+ */
+declare function resolveImportableCartState(input: unknown, registry?: SnapshotMigrationRegistry): ResolveImportableCartStateResult;
+declare function restoreSnapshotFromUnknown(input: unknown, registry?: SnapshotMigrationRegistry): ApplySnapshotMigrationsResult;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -1153,6 +1457,100 @@ declare function isCueLifecycleType(value: unknown): value is CueLifecycleType;
 declare function applyCueEasing(t: number, easing: CueEasing): number;
 declare function createPresentationTimeline(options?: CreatePresentationTimelineOptions): PresentationTimeline;
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Deterministic audio-cue timeline. Scheduling is frame-stepped via
+ * `createPresentationTimeline`; PCM output is not part of the event trace.
+ */
+
+declare const AUDIO_CUE_SCHEDULED_EVENT: "audio.cue.scheduled";
+declare const AUDIO_CUE_STARTED_EVENT: "audio.cue.started";
+declare const AUDIO_CUE_SKIPPED_EVENT: "audio.cue.skipped";
+declare const AUDIO_CUE_FAILED_EVENT: "audio.cue.failed";
+declare const AUDIO_CUE_EVENTS: readonly ["audio.cue.scheduled", "audio.cue.started", "audio.cue.skipped", "audio.cue.failed"];
+type AudioCueEventType = (typeof AUDIO_CUE_EVENTS)[number];
+type AudioCueSkipReason = 'reduced-sensory' | 'muted' | 'unauthorized';
+type AudioCueFailReason = 'asset-failed' | 'torn-down' | 'invalid';
+type AudioCueReason = AudioCueSkipReason | AudioCueFailReason;
+type AudioCueSpec = CueSpec & {
+    assetId: string;
+    channelId?: string;
+    participantId?: string;
+    priority?: number;
+    gain?: number;
+};
+type AudioCueView = CueView & {
+    assetId: string;
+    channelId: string;
+    participantId?: string;
+    priority: number;
+    audioPhase: 'scheduled' | 'started' | 'skipped' | 'failed' | 'completed';
+};
+type AudioCueEvent = {
+    type: AudioCueEventType;
+    atFrame: number;
+    name: string;
+    idempotencyKey: string;
+    assetId: string;
+    channelId: string;
+    participantId?: string;
+    reason?: AudioCueReason;
+    progress: number;
+};
+type AudioCueTimelineSnapshot = {
+    frame: number;
+    reducedSensory: boolean;
+    cues: AudioCueView[];
+    events: AudioCueEvent[];
+};
+type PlayAudioCueResult = {
+    ok: true;
+    cue: AudioCueView;
+} | {
+    ok: false;
+    reason: 'duplicate' | 'invalid';
+    detail: string;
+};
+type CreateAudioCueTimelineOptions = {
+    broker?: AudioBroker;
+    reducedSensory?: boolean;
+    originFrame?: number;
+};
+type AudioCueTimeline = {
+    play(spec: AudioCueSpec): PlayAudioCueResult;
+    step(frames?: number): AudioCueEvent[];
+    cancel(idempotencyKey: string): boolean;
+    reset(): void;
+    snapshot(): AudioCueTimelineSnapshot;
+    get(idempotencyKey: string): AudioCueView | undefined;
+    dispose(): void;
+    readonly frame: number;
+    readonly reducedSensory: boolean;
+};
+type HeadlessAudioAdapter = {
+    readonly broker: AudioBroker;
+    readonly timeline: AudioCueTimeline;
+    unlock(): Promise<AudioUnlockStatus>;
+    play(spec: AudioCueSpec): PlayAudioCueResult;
+    step(frames?: number): AudioCueEvent[];
+    handleHostEvent(event: HostEvent): void;
+    snapshot(): AudioCueTimelineSnapshot & {
+        unlock: AudioUnlockStatus;
+        muted: boolean;
+    };
+    destroy(): void;
+};
+declare function isAudioCueEventType(value: unknown): value is AudioCueEventType;
+declare function createAudioCueTimeline(options?: CreateAudioCueTimelineOptions): AudioCueTimeline;
+declare function scheduleAudioCue(timeline: AudioCueTimeline, spec: AudioCueSpec): PlayAudioCueResult;
+declare function createHeadlessAudioAdapter(options?: {
+    reducedSensory?: boolean;
+    originFrame?: number;
+}): HeadlessAudioAdapter;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -1175,6 +1573,8 @@ declare const CAPABILITY_BLEND_MODES: readonly ["source-over", "screen"];
 type CapabilityBlendMode = (typeof CAPABILITY_BLEND_MODES)[number];
 declare const CAPABILITY_CLEAR_POLICIES: readonly ["transparent", "opaque"];
 type CapabilityClearPolicy = (typeof CAPABILITY_CLEAR_POLICIES)[number];
+declare const CAPABILITY_CART_KINDS: readonly ["render", "calculation"];
+type CapabilityCartKind = (typeof CAPABILITY_CART_KINDS)[number];
 type CapabilityDiagnostic = {
     code: string;
     detail: string;
@@ -1207,6 +1607,14 @@ type CapabilityLayerRequirements = {
     compositor?: boolean;
     blend?: CapabilityBlendMode[];
 };
+/** Optional executable-module refs. Omitted on existing manifests. */
+type CapabilityModuleRef = {
+    id: string;
+    version: string;
+};
+type CapabilityModuleRequirements = {
+    refs?: CapabilityModuleRef[];
+};
 type CapabilityManifest = {
     version: typeof CAPABILITY_MANIFEST_VERSION;
     id: string;
@@ -1220,6 +1628,9 @@ type CapabilityManifest = {
     integrations: CapabilityIntegration[];
     surface?: CapabilitySurfaceRequirements;
     layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
+    /** Omitted means `'render'`. `'calculation'` carts have no surface. */
+    kind?: CapabilityCartKind;
 };
 type CapabilityManifestInput = {
     version?: number;
@@ -1234,6 +1645,8 @@ type CapabilityManifestInput = {
     integrations: CapabilityIntegration[];
     surface?: CapabilitySurfaceRequirements;
     layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
+    kind?: CapabilityCartKind;
 };
 type HostCapabilities = {
     contractVersion: number;
@@ -1246,6 +1659,9 @@ type HostCapabilities = {
         clearPolicy?: CapabilityClearPolicy | CapabilityClearPolicy[];
     };
     layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
+    /** Cart kinds this host can run. Omitted: kind is not checked. */
+    kinds?: CapabilityCartKind[];
 };
 type DefineCapabilityManifestResult = {
     ok: true;
@@ -1453,7 +1869,7 @@ declare function parseGeometry(json: string): GeometryDocument;
 
 declare const DEFAULT_GROUP_WIDTH = 320;
 declare const DEFAULT_GROUP_HEIGHT = 180;
-type RuntimeGroupKind = 'render' | 'calculation';
+type RuntimeGroupKind = CartKind;
 /**
  * Optional capability-shaped attach hints. Explicit participant `emit` /
  * `subscribe` / `authoritative` win. Do not import the capability manifest
@@ -1471,7 +1887,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;
@@ -1498,6 +1914,8 @@ type CreateRuntimeGroupOptions = {
     router?: EventRouterOptions;
     /** Bound on the accepted-event trace (oldest dropped). Default 1024. */
     maxTrace?: number;
+    /** Shared page-level audio unlock broker. Optional. */
+    audioBroker?: AudioBroker;
 };
 type RuntimeGroupParticipantInspect = {
     state: unknown;
@@ -1533,6 +1951,7 @@ type RuntimeGroup = {
     readonly router: EventRouter;
     readonly origin: number;
     readonly paused: boolean;
+    readonly audioBroker: AudioBroker | undefined;
     participant(id: string): RuntimeGroupParticipantHandle;
     step(frames?: number): Promise<void>;
     pause(): void;
@@ -1679,6 +2098,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;
@@ -1694,6 +2127,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;
@@ -1704,6 +2142,7 @@ type CompositorLayerInspect = {
     clip: CompositorClip | null;
     pointerEvents: CompositorPointerEvents;
     clearPolicy: CompositorClearPolicy;
+    sourceKind: CompositorSourceKind;
 };
 type CompositorHostOptions = {
     /** Back-layer pixels. Scaled nearest-neighbor to the compositor viewport. */
@@ -1762,6 +2201,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;
@@ -1771,6 +2211,253 @@ type Compositor = {
 };
 declare function createCompositor(options: CreateCompositorOptions): Compositor;
 
+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_INCOMING_SUFFIX: ":incoming";
+declare const VISUAL_LAYER_REVEALED_EVENT: "visual.layer.revealed";
+declare const VISUAL_LAYER_HIDDEN_EVENT: "visual.layer.hidden";
+declare const VISUAL_LAYER_TRANSITION_STARTED_EVENT: "visual.layer.transition-started";
+declare const VISUAL_LAYER_TRANSITION_COMPLETED_EVENT: "visual.layer.transition-completed";
+declare const VISUAL_LAYER_FAILED_EVENT: "visual.layer.failed";
+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 HOST_STATE_ACCEPTED_EVENT: "host.state.accepted";
+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 isVisualLayerKind(value: unknown): value is VisualLayerKind;
+declare function isVisualLayerTransitionKind(value: unknown): value is VisualLayerTransitionKind;
+declare function isVisualLayerEventType(value: unknown): value is VisualLayerEventType;
+declare function visualIncomingLayerId(layerId: string): string;
+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
+ *
+ * Trusted, versioned executable-module host. Factories are registered by
+ * exact id+version; the host allowlists which refs may load. Untrusted
+ * source strings are not compiled. Per-module failures do not stop siblings.
+ */
+declare const EXECUTABLE_MODULE_ERROR_CODES: readonly ["invalid-ref", "unknown-module", "version-mismatch", "not-allowlisted", "load-failed", "invoke-failed", "timeout", "rate-limited", "destroyed"];
+type ExecutableModuleErrorCode = (typeof EXECUTABLE_MODULE_ERROR_CODES)[number];
+type ExecutableModuleRef = {
+    id: string;
+    version: string;
+};
+type ExecutableModuleError = {
+    code: ExecutableModuleErrorCode;
+    detail: string;
+    ref?: ExecutableModuleRef;
+};
+type ExecutableModuleDiagnostic = ExecutableModuleError;
+type ExecutableModuleCapabilities = {
+    readonly [key: string]: unknown;
+};
+type ExecutableModuleInvokeContext = {
+    signal: AbortSignal;
+    turn: number;
+};
+type ExecutableModuleInstance = {
+    invoke(input: unknown, context: ExecutableModuleInvokeContext): unknown | Promise<unknown>;
+    destroy?: () => void;
+};
+type ExecutableModuleFactory = (capabilities: ExecutableModuleCapabilities) => ExecutableModuleInstance;
+type ExecutableModuleRegistration = {
+    id: string;
+    version: string;
+    create: ExecutableModuleFactory;
+    capabilities?: ExecutableModuleCapabilities;
+};
+type ExecutableModuleLimits = {
+    /** Cooperative timeout; the invoke AbortSignal aborts after this many ms. */
+    maxInvokeMs?: number;
+    maxInvokesPerTurn?: number;
+};
+type CreateExecutableModuleHostOptions = {
+    allowlist: readonly ExecutableModuleRef[];
+    modules: readonly ExecutableModuleRegistration[];
+    limits?: ExecutableModuleLimits;
+    /** Default capability bag. Frozen per module; class instances stay shared handles. */
+    capabilities?: ExecutableModuleCapabilities;
+};
+type ExecutableModuleInvokeResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: ExecutableModuleError;
+};
+type ExecutableModuleLoadResult = {
+    ok: true;
+    ref: ExecutableModuleRef;
+} | {
+    ok: false;
+    error: ExecutableModuleError;
+};
+type ExecutableModuleHostInspect = {
+    allowlist: ExecutableModuleRef[];
+    registered: ExecutableModuleRef[];
+    loaded: ExecutableModuleRef[];
+    turn: number;
+    invokesThisTurn: number;
+    diagnostics: ExecutableModuleDiagnostic[];
+};
+type ExecutableModuleHost = {
+    load(ref: ExecutableModuleRef): ExecutableModuleLoadResult;
+    invoke(ref: ExecutableModuleRef, input?: unknown): Promise<ExecutableModuleInvokeResult>;
+    beginTurn(): void;
+    inspect(): ExecutableModuleHostInspect;
+    destroy(): void;
+};
+declare function createExecutableModuleHost(options: CreateExecutableModuleHostOptions): ExecutableModuleHost;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -1947,4 +2634,194 @@ type PlaywrightCompatibleAdapter = {
 };
 declare function createPlaywrightCompatibleAdapter(harness: BrowserHarness): PlaywrightCompatibleAdapter;
 
-export { ANCHOR_ORIGINS, ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, type AnchorOrigin, type AnimationCart, type AnimationTiming, type AppliedAction, type AssetCorsMode, type AssetDeclaration, type AssetFailure, type AssetFailureCode, type AssetItemStatus, type AssetKind, type AssetPreloadSnapshot, type AssetPreloader, type AssetProvenance, type AssetResolveRequest, type AssetResolver, type AssetRuntimeOptions, type AttachOptions, type AttachPresentationAdapterOptions, type AudioLibraryId, type AudioLibrarySpec, type BoundReplaySession, type BrowserA11ySnapshot, type BrowserCompositorConfig, type BrowserHarness, type BrowserHarnessAction, type BrowserHarnessInspect, type BrowserHarnessMountContext, type BrowserHarnessRuntimeContext, type BrowserHarnessScreenshot, type BrowserHostSession, type BrowserInputModality, type BrowserReproductionMetadata, type BrowserViewport, CAPABILITY_ASSET_KINDS, CAPABILITY_BLEND_MODES, CAPABILITY_CLEAR_POLICIES, CAPABILITY_INTEGRATIONS, CAPABILITY_MANAGERS, CAPABILITY_MANIFEST_VERSION, CAPABILITY_PHASES, COMPOSITOR_BLEND_MODES, COMPOSITOR_CLEAR_POLICIES, COORDINATE_SPACES, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CapabilityAssetDeclarationSummary, type CapabilityAssetKind, type CapabilityAssetSummary, type CapabilityBlendMode, type CapabilityClearPolicy, type CapabilityDiagnostic, type CapabilityIntegration, type CapabilityLayerRequirements, type CapabilityManager, type CapabilityManifest, type CapabilityManifestInput, type CapabilityPermissions, type CapabilityPhase, type CapabilityRuntime, type CapabilitySurfaceRequirements, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type CausationTreeNode, type Clock, type ClockSnapshot, type ComposedFrame, type Compositor, type CompositorBlendMode, type CompositorClearPolicy, type CompositorClip, type CompositorHostOptions, type CompositorInspect, type CompositorLayerConfig, type CompositorLayerInspect, type CompositorPointerEvents, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CoordinateSpace, type CreateAssetPreloaderOptions, type CreateBrowserHarnessOptions, type CreateCompositorOptions, type CreatePresentationLayoutInput, type CreatePresentationTimelineOptions, type CreateReplayInspectorOptions, type CreateRuntimeGroupOptions, type CreateRuntimeOptions, type CueDuplicatePolicy, type CueEasing, type CueLifecycleEvent, type CueLifecycleType, type CuePhase, type CueReducedMotionPolicy, type CueRepeatPolicy, type CueSpec, type CueTimelineSnapshot, type CueView, type CyberArtRuntime, DEFAULT_BROWSER_VIEWPORT, DEFAULT_GROUP_HEIGHT, DEFAULT_GROUP_WIDTH, DEFAULT_MAX_HOPS, DEFAULT_MAX_INSPECTOR_RECORDS, type DebugDrawCall, type DefineCapabilityManifestResult, type DefineContractResult, type DeterministicRuntimeOptions, type DimensionContext, EVENT_ENVELOPE_VERSION, type EventContract, type EventContractManifest, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type FixtureAssetCatalog, type FixtureAssetRecord, type FrameErrorInfo, GEOMETRY_CONTRACT_VERSION, type GeometryAnchor, type GeometryDebugContext, type GeometryDiagnostic, type GeometryDocument, type GeometryHitbox, type GeometryPadding, type GeometrySafeArea, type GeometryValidation, type HostCapabilities, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, type InspectorRecord, KeyboardManager, type LandmarkRegisterResult, type LandmarkRegistry, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, type NormalizedPoint, type NormalizedPolygon, type NormalizedRect, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PixelPoint, type PixelRect, type PlayCueResult, type PlaywrightCompatibleAdapter, type PlaywrightCompatibleViewport, type PointerClick, PointerManager, type PointerSpace, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationFitMode, type PresentationLayout, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REDACTED_VALUE, REJECTED_EVENT_TYPE, REPLAY_INSPECTOR_SCHEMA_VERSION, ROUND_TRIP_TOLERANCE, ROUND_TRIP_TOLERANCE_CANVAS_PX, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayMetadata, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, type ResolvedAsset, type RouterDecision, type RouterDecisionOutcome, type RouterDecisionReason, type RouterParticipantInspect, type RuntimeGroup, type RuntimeGroupCapability, type RuntimeGroupDiagnostics, type RuntimeGroupFrameError, type RuntimeGroupInspect, type RuntimeGroupKind, type RuntimeGroupParticipantConfig, type RuntimeGroupParticipantHandle, type RuntimeGroupParticipantInspect, SILENT_ASSET_FALLBACK_REF, type SchemaCompatibility, type ScriptedAction, type TokenData, type ValidateCapabilityManifestResult, type ValidateResult, type VirtualClock, applyCueEasing, assetStatusEvent, assetToNormalized, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, canvasToCss, canvasToNormalized, toJSON as capabilityManifestToJSON, comparePayloadSchemas, compareReplayTraces, createAssetFailure, createAssetPreloader, createBrowserHarness, createCompositor, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createLandmarkRegistry, createPlaywrightCompatibleAdapter, createPresentationLayout, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createReplayInspector, createRuntime, createRuntimeGroup, createVirtualClock, createWallClock, cssToCanvas, cssToNormalized, defineCapabilityManifest, defineDiagnostic, defineIntent, defineStateEvent, deriveAttachOptions, describeReplayMismatch, drawGeometryDebug, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isCueLifecycleType, isPresentationModel, isPresentationPhase, kindSegmentInType, matchEventPattern, mountPresentationAdapter, normalizeEvent, normalizedToAsset, normalizedToCanvas, normalizedToCss, parseCapabilityManifest, parseGeometry, pointFromOrigin, pointerToRegion, rectToCanvas, rectToCss, regionToViewport, registerCartStateHotkeys, replayExportedTrace, resolveRuntimeSeed, rewriteHostedAssetRef, serializeGeometry, validateCapabilityManifest, validateGeometry, verifyAttachOptions };
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host-owned MIDI controller I/O. Carts and hosts construct MidiManager;
+ * the runtime does not pass it into getDefaultState. Live Web MIDI is
+ * optional — inject and send work in headless/jsdom through a test port.
+ */
+/** Note Off command nibble (status = this | channel). */
+declare const MIDI_NOTE_OFF = 128;
+/** Note On command nibble (status = this | channel). */
+declare const MIDI_NOTE_ON = 144;
+/** Control Change command nibble (status = this | channel). */
+declare const MIDI_CONTROL_CHANGE = 176;
+/** Pitch Bend command nibble (status = this | channel). */
+declare const MIDI_PITCH_BEND = 224;
+declare const MIDI_CHANNEL_MIN = 0;
+declare const MIDI_CHANNEL_MAX = 15;
+declare const MIDI_DATA_MAX = 127;
+declare const MIDI_PITCH_CENTER = 8192;
+declare const MIDI_PITCH_MAX = 16383;
+/** Channel index 0–15 (MIDI channels 1–16). */
+type MidiChannel = number;
+/** Channel-voice status byte: command in the high nibble, channel 0–15 in the low. */
+type MidiStatusByte = number;
+type MidiNoteMessage = {
+    kind: 'noteon' | 'noteoff';
+    channel: number;
+    note: number;
+    velocity: number;
+    status: MidiStatusByte;
+    data: Uint8Array;
+};
+type MidiCcMessage = {
+    kind: 'cc';
+    channel: number;
+    controller: number;
+    value: number;
+    status: MidiStatusByte;
+    data: Uint8Array;
+};
+type MidiPitchMessage = {
+    kind: 'pitch';
+    channel: number;
+    /** 14-bit pitch bend, 0–16383. Center is 8192. */
+    value: number;
+    status: MidiStatusByte;
+    data: Uint8Array;
+};
+type MidiRawMessage = {
+    kind: 'raw';
+    channel?: number;
+    status: MidiStatusByte;
+    data: Uint8Array;
+};
+type MidiMessage = MidiNoteMessage | MidiCcMessage | MidiPitchMessage | MidiRawMessage;
+type MidiVoiceInput = {
+    kind: 'noteon' | 'noteoff';
+    channel: number;
+    note: number;
+    velocity?: number;
+} | {
+    kind: 'cc';
+    channel: number;
+    controller: number;
+    value: number;
+} | {
+    kind: 'pitch';
+    channel: number;
+    value: number;
+};
+type MidiInjectInput = MidiVoiceInput | MidiMessage | Uint8Array | readonly number[];
+type MidiSubscribeKind = 'note' | 'cc' | 'pitch' | 'raw' | '*';
+type MidiSubscribeListener = (message: MidiMessage) => void;
+type MidiOutputPort = {
+    send(data: number[], timestamp?: number): void;
+};
+type MidiInputLike = {
+    addEventListener(type: string, listener: (event: Event | {
+        data?: Uint8Array | null;
+    }) => void): void;
+    removeEventListener(type: string, listener: (event: Event | {
+        data?: Uint8Array | null;
+    }) => void): void;
+};
+type MidiAccessLike = {
+    readonly inputs: {
+        forEach(callback: (input: MidiInputLike) => void): void;
+    };
+    readonly outputs: {
+        forEach(callback: (output: MidiOutputPort) => void): void;
+    };
+    readonly sysexEnabled: boolean;
+    addEventListener?(type: string, listener: EventListener): void;
+    removeEventListener?(type: string, listener: EventListener): void;
+};
+type MidiRequestAccess = (options?: {
+    sysex?: boolean;
+}) => Promise<MidiAccessLike>;
+type MidiAccessFailureReason = 'unavailable' | 'denied' | 'destroyed';
+type MidiAccessResult = {
+    ok: true;
+    inputs: number;
+    outputs: number;
+    sysexEnabled: boolean;
+} | {
+    ok: false;
+    reason: MidiAccessFailureReason;
+    detail?: string;
+};
+type MidiSendFailureReason = 'no-port' | 'invalid' | 'destroyed';
+type MidiSendResult = {
+    ok: true;
+    data: Uint8Array;
+} | {
+    ok: false;
+    reason: MidiSendFailureReason;
+    detail?: string;
+};
+type MidiManagerOptions = {
+    /** Fake or real output. Tests pass a recording port. */
+    output?: MidiOutputPort;
+    /**
+     * Override Web MIDI request. Tests inject a fake or a rejecting
+     * function. When omitted, uses `navigator.requestMIDIAccess`.
+     */
+    requestMIDIAccess?: MidiRequestAccess;
+};
+declare function isMidiChannel(value: unknown): value is number;
+declare function isMidiData(value: unknown): value is number;
+declare function midiStatus(command: number, channel: number): MidiStatusByte;
+declare function midiChannelFromStatus(status: MidiStatusByte): number;
+declare function encodeMidiMessage(input: MidiVoiceInput): Uint8Array | undefined;
+declare function parseMidiBytes(data: Uint8Array | readonly number[]): MidiMessage | undefined;
+/**
+ * Live MIDI in and out for a host or cart. Missing Web MIDI or a denied
+ * permission is a structured result — constructing this never throws.
+ */
+declare class MidiManager {
+    private output;
+    private readonly outputOwned;
+    private adoptedHardwareOutput;
+    private readonly requestMIDIAccess;
+    private listeners;
+    private readonly attachedInputs;
+    private access;
+    private inputCount;
+    private outputCount;
+    private destroyed;
+    constructor(options?: MidiManagerOptions);
+    /**
+     * Subscribe to parsed inbound messages. `note` matches note-on and
+     * note-off. Returns an unsubscribe function.
+     */
+    subscribe(kind: MidiSubscribeKind, listener: MidiSubscribeListener): () => void;
+    /**
+     * Deliver a message without Web MIDI hardware. Deterministic hosts and
+     * tests call this instead of waiting on a controller.
+     */
+    inject(input: MidiInjectInput): void;
+    sendNoteOn(channel: number, note: number, velocity?: number): MidiSendResult;
+    sendNoteOff(channel: number, note: number, velocity?: number): MidiSendResult;
+    sendCc(channel: number, controller: number, value: number): MidiSendResult;
+    sendPitch(channel: number, value: number): MidiSendResult;
+    /** Send raw bytes through the output port. */
+    send(data: Uint8Array | readonly number[]): MidiSendResult;
+    /**
+     * Wrap `navigator.requestMIDIAccess` when present. Missing API or a
+     * denied permission returns `{ ok: false }` — it does not throw.
+     */
+    requestAccess(options?: {
+        sysex?: boolean;
+    }): Promise<MidiAccessResult>;
+    /**
+     * Remove hardware listeners and subscribers. Idempotent. Further inject
+     * is a no-op; send / requestAccess return `{ reason: 'destroyed' }`.
+     */
+    destroy(): void;
+    private sendEncoded;
+    private write;
+    private dispatch;
+    private deliverBytes;
+    private onHardwareMessage;
+    private onAccessStateChange;
+    private attachAccess;
+    private syncPorts;
+    private detachHardware;
+}
+
+export { ANCHOR_ORIGINS, ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, AUDIO_CUE_EVENTS, AUDIO_CUE_FAILED_EVENT, AUDIO_CUE_SCHEDULED_EVENT, AUDIO_CUE_SKIPPED_EVENT, AUDIO_CUE_STARTED_EVENT, type ActiveAudioCue, type AnchorOrigin, type AnimationCart, type AnimationTiming, type AppliedAction, type ApplySnapshotMigrationsResult, type AssetCorsMode, type AssetDeclaration, type AssetFailure, type AssetFailureCode, type AssetItemStatus, type AssetKind, type AssetPreloadSnapshot, type AssetPreloader, type AssetProvenance, type AssetResolveRequest, type AssetResolver, type AssetRuntimeOptions, type AttachOptions, type AttachPresentationAdapterOptions, type AudioAssetStatus, type AudioBroker, type AudioBrokerInspect, type AudioBrokerListener, type AudioBrokerNotice, type AudioChannelInspect, type AudioCueEvent, type AudioCueEventType, type AudioCueFailReason, type AudioCueReason, type AudioCueSkipReason, type AudioCueSpec, type AudioCueTimeline, type AudioCueTimelineSnapshot, type AudioCueView, type AudioLibraryId, type AudioLibrarySpec, type AudioUnlockState, type AudioUnlockStatus, type BoundReplaySession, type BrowserA11ySnapshot, type BrowserCompositorConfig, type BrowserHarness, type BrowserHarnessAction, type BrowserHarnessInspect, type BrowserHarnessMountContext, type BrowserHarnessRuntimeContext, type BrowserHarnessScreenshot, type BrowserHostSession, type BrowserInputModality, type BrowserReproductionMetadata, type BrowserViewport, CAPABILITY_ASSET_KINDS, CAPABILITY_BLEND_MODES, CAPABILITY_CART_KINDS, CAPABILITY_CLEAR_POLICIES, CAPABILITY_INTEGRATIONS, CAPABILITY_MANAGERS, CAPABILITY_MANIFEST_VERSION, CAPABILITY_PHASES, COMPOSITOR_BLEND_MODES, COMPOSITOR_CLEAR_POLICIES, COMPOSITOR_SOURCE_KINDS, COORDINATE_SPACES, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CapabilityAssetDeclarationSummary, type CapabilityAssetKind, type CapabilityAssetSummary, type CapabilityBlendMode, type CapabilityCartKind, type CapabilityClearPolicy, type CapabilityDiagnostic, type CapabilityIntegration, type CapabilityLayerRequirements, type CapabilityManager, type CapabilityManifest, type CapabilityManifestInput, type CapabilityModuleRef, type CapabilityModuleRequirements, type CapabilityPermissions, type CapabilityPhase, type CapabilityRuntime, type CapabilitySurfaceRequirements, type CartHandle, type CartKind, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type CausationTreeNode, type Clock, type ClockSnapshot, type ComposedFrame, type Compositor, type CompositorBlendMode, type CompositorCanvasSource, type CompositorClearPolicy, type CompositorClip, type CompositorHostOptions, type CompositorImageSource, type CompositorInspect, type CompositorLayerConfig, type CompositorLayerInspect, type CompositorLayerSource, type CompositorParticipantSource, type CompositorPointerEvents, type CompositorSourceKind, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CoordinateSpace, type CreateAssetPreloaderOptions, type CreateAudioBrokerOptions, type CreateAudioCueTimelineOptions, type CreateBrowserHarnessOptions, type CreateCompositorOptions, type CreateExecutableModuleHostOptions, type CreatePresentationLayoutInput, type CreatePresentationTimelineOptions, type CreateReplayInspectorOptions, type CreateRuntimeGroupOptions, type CreateRuntimeOptions, type CreateVisualLayerControllerOptions, type CueDuplicatePolicy, type CueEasing, type CueLifecycleEvent, type CueLifecycleType, type CuePhase, type CueReducedMotionPolicy, type CueRepeatPolicy, type CueSpec, type CueTimelineSnapshot, type CueView, type CyberArtRuntime, DEFAULT_BROWSER_VIEWPORT, DEFAULT_DUCK_GAIN, DEFAULT_GROUP_HEIGHT, DEFAULT_GROUP_WIDTH, DEFAULT_MAX_HOPS, DEFAULT_MAX_INSPECTOR_RECORDS, type DebugDrawCall, type DefineCapabilityManifestResult, type DefineContractResult, type DefineSnapshotResult, type DeterministicRuntimeOptions, type DimensionContext, ENGINE_SNAPSHOT_RUNTIME, EVENT_ENVELOPE_VERSION, EXECUTABLE_MODULE_ERROR_CODES, type EventContract, type EventContractManifest, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type ExecutableModuleCapabilities, type ExecutableModuleDiagnostic, type ExecutableModuleError, type ExecutableModuleErrorCode, type ExecutableModuleFactory, type ExecutableModuleHost, type ExecutableModuleHostInspect, type ExecutableModuleInstance, type ExecutableModuleInvokeContext, type ExecutableModuleInvokeResult, type ExecutableModuleLimits, type ExecutableModuleLoadResult, type ExecutableModuleRef, type ExecutableModuleRegistration, type ExportSnapshotOptions, type FixtureAssetCatalog, type FixtureAssetRecord, type FrameErrorInfo, GEOMETRY_CONTRACT_VERSION, type GeometryAnchor, type GeometryDebugContext, type GeometryDiagnostic, type GeometryDocument, type GeometryHitbox, type GeometryPadding, type GeometrySafeArea, type GeometryValidation, HOST_STATE_ACCEPTED_EVENT, type HeadlessAudioAdapter, type HostCapabilities, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, type InspectorRecord, KeyboardManager, LEGACY_SNAPSHOT_SCHEMA_VERSION, type LandmarkRegisterResult, type LandmarkRegistry, type LegacySnapshot, MIDI_CHANNEL_MAX, MIDI_CHANNEL_MIN, MIDI_CONTROL_CHANGE, MIDI_DATA_MAX, MIDI_NOTE_OFF, MIDI_NOTE_ON, MIDI_PITCH_BEND, MIDI_PITCH_CENTER, MIDI_PITCH_MAX, type MidiAccessFailureReason, type MidiAccessLike, type MidiAccessResult, type MidiCcMessage, type MidiChannel, type MidiInjectInput, type MidiInputLike, MidiManager, type MidiManagerOptions, type MidiMessage, type MidiNoteMessage, type MidiOutputPort, type MidiPitchMessage, type MidiRawMessage, type MidiRequestAccess, type MidiSendFailureReason, type MidiSendResult, type MidiStatusByte, type MidiSubscribeKind, type MidiSubscribeListener, type MidiVoiceInput, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, type NormalizedPoint, type NormalizedPolygon, type NormalizedRect, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type ParseSnapshotResult, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PixelPoint, type PixelRect, type PlayAudioCueResult, type PlayCueResult, type PlayVisualLayerResult, type PlaywrightCompatibleAdapter, type PlaywrightCompatibleViewport, type PointerClick, PointerManager, type PointerSpace, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationFitMode, type PresentationLayout, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REDACTED_VALUE, REJECTED_EVENT_TYPE, REPLAY_INSPECTOR_SCHEMA_VERSION, ROUND_TRIP_TOLERANCE, ROUND_TRIP_TOLERANCE_CANVAS_PX, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayMetadata, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, type ResolveImportableCartStateResult, type ResolvedAsset, type RestoreVisualLayerResult, type RouterDecision, type RouterDecisionOutcome, type RouterDecisionReason, type RouterParticipantInspect, type RuntimeGroup, type RuntimeGroupCapability, type RuntimeGroupDiagnostics, type RuntimeGroupFrameError, type RuntimeGroupInspect, type RuntimeGroupKind, type RuntimeGroupParticipantConfig, type RuntimeGroupParticipantHandle, type RuntimeGroupParticipantInspect, SILENT_ASSET_FALLBACK_REF, SNAPSHOT_SCHEMA_VERSION, type SchemaCompatibility, type ScriptedAction, type SnapshotAssetRef, type SnapshotCartRef, type SnapshotClock, type SnapshotDiagnostic, type SnapshotEnvelope, type SnapshotEnvelopeInput, type SnapshotIntegrity, type SnapshotMigration, type SnapshotMigrationRegistry, type SnapshotModuleRef, type SnapshotProvenance, type TokenData, UNVERSIONED_CART_VERSION, VISUAL_LAYER_EVENTS, VISUAL_LAYER_FAILED_EVENT, VISUAL_LAYER_FAILURE_CODES, VISUAL_LAYER_HIDDEN_EVENT, VISUAL_LAYER_INCOMING_SUFFIX, VISUAL_LAYER_KINDS, VISUAL_LAYER_REVEALED_EVENT, VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION, VISUAL_LAYER_TRANSITIONS, VISUAL_LAYER_TRANSITION_COMPLETED_EVENT, VISUAL_LAYER_TRANSITION_STARTED_EVENT, type ValidateCapabilityManifestResult, type ValidateResult, type ValidateSnapshotResult, type VersionedSnapshot, type VirtualClock, type VisualLayerAcceptedBinding, type VisualLayerAssetStatus, type VisualLayerCapture, type VisualLayerController, type VisualLayerControllerSnapshot, type VisualLayerCueSpec, type VisualLayerDeclaration, type VisualLayerDiagnostic, type VisualLayerEvent, type VisualLayerEventType, type VisualLayerFailureCode, type VisualLayerFallbackPolicy, type VisualLayerInspect, type VisualLayerKind, type VisualLayerSnapshotRow, type VisualLayerTransitionInspect, type VisualLayerTransitionKind, type VisualLayerVersionDeclaration, applyCueEasing, applySnapshotMigrations, assetStatusEvent, assetToNormalized, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, canvasToCss, canvasToNormalized, toJSON as capabilityManifestToJSON, captureVisualLayers, cloneSnapshotJson, comparePayloadSchemas, compareReplayTraces, createAssetFailure, createAssetPreloader, createAudioBroker, createAudioCueTimeline, createBrowserHarness, createCompositor, createContractRegistry, createEngineSnapshotMigrations, createEventRouter, createExecutableModuleHost, createFixtureAssetResolver, createHeadlessAudioAdapter, createHostedAssetResolver, createLandmarkRegistry, createPlaywrightCompatibleAdapter, createPresentationLayout, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createReplayInspector, createRuntime, createRuntimeGroup, createSnapshotMigrationRegistry, createVirtualClock, createVisualLayerController, createWallClock, cssToCanvas, cssToNormalized, defaultSnapshotMigrationRegistry, defineCapabilityManifest, defineDiagnostic, defineIntent, defineSnapshot, defineStateEvent, deriveAttachOptions, describeReplayMismatch, detectSnapshotSchemaVersion, drawGeometryDebug, encodeMidiMessage, engineStateFromEnvelope, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isAudioCueEventType, isCueLifecycleType, isLegacyCartStateBundle, isMidiChannel, isMidiData, isPresentationModel, isPresentationPhase, isSnapshotEnvelope, isVersionedSnapshot, isVisualLayerEventType, isVisualLayerKind, isVisualLayerTransitionKind, kindSegmentInType, matchEventPattern, midiChannelFromStatus, midiStatus, mountPresentationAdapter, normalizeEvent, normalizedToAsset, normalizedToCanvas, normalizedToCss, parseCapabilityManifest, parseGeometry, parseMidiBytes, parseSnapshot, pointFromOrigin, pointerToRegion, rectToCanvas, rectToCss, regionToViewport, registerCartStateHotkeys, replayExportedTrace, resolveImportableCartState, resolveRuntimeSeed, restoreSnapshotFromUnknown, rewriteHostedAssetRef, scheduleAudioCue, serializeGeometry, snapshotErrorsToMessage, snapshotFromCartBundle, validateCapabilityManifest, validateGeometry, validateSnapshot, verifyAttachOptions, visualIncomingLayerId };