@cyberart-io/engine 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -48,7 +48,7 @@ type TokenData = {
  *
  * A full 64-hex hash (optional `0x`) is returned unchanged aside from a
  * lowercase `0x` prefix — this is the kaleidoscope / Art Blocks path.
- * Any other seed (including the Adventure Kit example `42`) is mixed into
+ * Any other seed (including the numeric example `42`) is mixed into
  * a 64-hex hash so `Random` always sees the same shape.
  */
 declare function canonicalizeSeed(seed: string | number): string;
@@ -256,8 +256,8 @@ type NormalizeResult = NormalizeSuccess | NormalizeFailure;
 /**
  * `kind` on the input wins. Otherwise persistence types are intents, then
  * the first dotted segment that is `intent` | `state` | `diagnostic`.
- * `adventure.presentation.*` does not infer a kind (the presentation segment
- * is not one); put the kind in the name, e.g. `adventure.presentation.intent.*`.
+ * `host.presentation.*` does not infer a kind (the presentation segment
+ * is not one); put the kind in the name, e.g. `host.presentation.intent.*`.
  */
 declare function inferEventKind(input: EventInput): EventKind | undefined;
 declare function matchEventPattern(pattern: string, type: string): boolean;
@@ -406,6 +406,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 +764,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 +888,17 @@ 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;
 };
 type MountOptions<T = unknown> = {
     /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
@@ -691,7 +929,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 +975,8 @@ type CyberArtRuntime = {
      * Survives cart remount; `destroy()` disposes it.
      */
     readonly assets: AssetPreloader | undefined;
+    /** Shared broker when `createRuntime({ audioBroker })` was set. */
+    readonly audioBroker: AudioBroker | undefined;
     onError?: (error: unknown, info: FrameErrorInfo) => void;
 };
 declare function createRuntime(options: CreateRuntimeOptions): CyberArtRuntime;
@@ -749,7 +994,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 +1028,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
@@ -815,15 +1107,49 @@ type EventRouterOptions = {
     maxHops?: number;
     maxCorrelationPerTurn?: number;
     maxIndex?: number;
+    /** Bound on the decision trace (oldest dropped). Default 256. */
+    maxDecisions?: number;
 };
 type PublishExtras = {
     cause?: EventEnvelope;
 };
+type RouterParticipantInspect = {
+    id: string;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
+};
+type RouterDecisionOutcome = 'accepted' | 'rejected' | 'duplicate';
+type RouterDecisionReason = RejectionReason | 'duplicate';
+type RouterDecision = {
+    outcome: RouterDecisionOutcome;
+    reason?: RouterDecisionReason;
+    detail?: string;
+    source: string;
+    type: string;
+    kind?: EventKind;
+    envelopeId?: string;
+    priorEnvelopeId?: string;
+    target?: string;
+    deliveredTo: string[];
+    hops?: number;
+    seq?: number;
+    correlationId?: string;
+    causationId?: string;
+    idempotencyKey?: string;
+    schemaVersion?: number;
+    payload?: unknown;
+    turn: number;
+    time: number;
+};
 type EventRouter = {
     attach(id: string, channel: HostChannel, options?: AttachOptions): void;
     detach(id: string): void;
     publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
     subscribe(patterns: string[], listener: (event: EventEnvelope) => void): () => void;
+    subscribeDecision(listener: (decision: RouterDecision) => void): () => void;
+    inspectParticipants(): RouterParticipantInspect[];
+    inspectDecisions(): RouterDecision[];
     turn(): void;
 };
 declare function createEventRouter(options?: EventRouterOptions): EventRouter;
@@ -836,7 +1162,7 @@ declare function createEventRouter(options?: EventRouterOptions): EventRouter;
  * One contract definition drives TypeScript payload types, runtime
  * validation, router permission checks, and machine-readable manifests.
  * Kind must appear as a dotted segment of `type` so names like
- * `adventure.presentation.cue.started` fail at definition time instead of
+ * `host.presentation.cue.started` fail at definition time instead of
  * silently inferring a bogus kind.
  */
 
@@ -931,7 +1257,7 @@ declare function createContractRegistry(contracts: EventContract[]): ContractReg
  *
  * Versioned presentation-adapter contract. Hosts own canonical state and
  * push a render model; Cyberart presents it and emits interaction intents.
- * Adventure Kit concepts stay in the host.
+ * Host domain concepts stay in the host.
  */
 
 declare const PRESENTATION_ADAPTER_VERSION: 1;
@@ -946,7 +1272,7 @@ declare const PRESENTATION_PHASES: readonly ["loading", "ready", "error", "unsup
 type PresentationPhase = (typeof PRESENTATION_PHASES)[number];
 /**
  * Recommended router `subscribe` for a presentation cart. Intent type names
- * are host-owned (`adventure.intent.*`); do not put domain objects in `target`.
+ * are host-owned (`host.intent.*`); do not put domain objects in `target`.
  */
 declare const PRESENTATION_SUBSCRIBE_PATTERNS: readonly ["presentation.state.*", "cyberart.diagnostic.rejected"];
 declare const INVALID_PRESENTATION_MODEL_MESSAGE = "Presentation adapter: model is invalid or not JSON-serializable";
@@ -1119,6 +1445,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
@@ -1137,6 +1557,10 @@ declare const CAPABILITY_ASSET_KINDS: readonly ["image", "audio", "font", "sprit
 type CapabilityAssetKind = (typeof CAPABILITY_ASSET_KINDS)[number];
 declare const CAPABILITY_INTEGRATIONS: readonly ["tone", "midi"];
 type CapabilityIntegration = (typeof CAPABILITY_INTEGRATIONS)[number];
+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];
 type CapabilityDiagnostic = {
     code: string;
     detail: string;
@@ -1159,6 +1583,24 @@ type CapabilityPermissions = {
     subscribe: string[];
     authoritative?: boolean;
 };
+/** Optional surface requirements. Omitted on existing manifests. */
+type CapabilitySurfaceRequirements = {
+    alpha?: boolean;
+    clearPolicy?: CapabilityClearPolicy;
+};
+/** Optional compositor/layer requirements. Omitted on existing manifests. */
+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;
@@ -1170,6 +1612,9 @@ type CapabilityManifest = {
     emittedEvents: string[];
     permissions: CapabilityPermissions;
     integrations: CapabilityIntegration[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
 };
 type CapabilityManifestInput = {
     version?: number;
@@ -1182,6 +1627,9 @@ type CapabilityManifestInput = {
     emittedEvents: string[];
     permissions: CapabilityPermissions;
     integrations: CapabilityIntegration[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
 };
 type HostCapabilities = {
     contractVersion: number;
@@ -1190,6 +1638,11 @@ type HostCapabilities = {
     managers?: CapabilityManager[];
     emit?: string[];
     subscribe?: string[];
+    surface?: CapabilitySurfaceRequirements & {
+        clearPolicy?: CapabilityClearPolicy | CapabilityClearPolicy[];
+    };
+    layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
 };
 type DefineCapabilityManifestResult = {
     ok: true;
@@ -1440,6 +1893,10 @@ type CreateRuntimeGroupOptions = {
     now?: () => number;
     /** Extra router options. Group injects shared `createId` / `now` unless set here. */
     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;
@@ -1447,6 +1904,9 @@ type RuntimeGroupParticipantInspect = {
     errors: RuntimeGroupFrameError[];
     kind: RuntimeGroupKind;
     clock: ClockSnapshot;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
 };
 type RuntimeGroupDiagnostics = {
     paused: boolean;
@@ -1472,16 +1932,691 @@ 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;
     resume(): void;
     reset(): void;
+    /** Shared viewport. Sets each container and canvas buffer size. Does not clear sibling pixels on detach. */
+    resize(width: number, height: number): void;
+    /** Tear down one participant without destroying the group or blanking siblings. */
+    detach(id: string): void;
     dispatch(participantId: string, event: HostEvent): void;
     publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
+    inspectParticipants(): Array<RouterParticipantInspect & {
+        kind: RuntimeGroupKind;
+    }>;
     inspect(): Promise<RuntimeGroupInspect>;
     destroy(): void;
 };
 declare function createRuntimeGroup(options: CreateRuntimeGroupOptions): RuntimeGroup;
 
-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, CAPABILITY_ASSET_KINDS, CAPABILITY_INTEGRATIONS, CAPABILITY_MANAGERS, CAPABILITY_MANIFEST_VERSION, CAPABILITY_PHASES, 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 CapabilityDiagnostic, type CapabilityIntegration, type CapabilityManager, type CapabilityManifest, type CapabilityManifestInput, type CapabilityPermissions, type CapabilityPhase, type CapabilityRuntime, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type Clock, type ClockSnapshot, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CoordinateSpace, type CreateAssetPreloaderOptions, type CreatePresentationLayoutInput, type CreatePresentationTimelineOptions, 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_GROUP_HEIGHT, DEFAULT_GROUP_WIDTH, DEFAULT_MAX_HOPS, 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, 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 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, REJECTED_EVENT_TYPE, ROUND_TRIP_TOLERANCE, ROUND_TRIP_TOLERANCE_CANVAS_PX, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayMetadata, type ResolvedAsset, 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, createAssetFailure, createAssetPreloader, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createLandmarkRegistry, createPresentationLayout, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, 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, resolveRuntimeSeed, rewriteHostedAssetRef, serializeGeometry, validateCapabilityManifest, validateGeometry, verifyAttachOptions };
+declare const REPLAY_INSPECTOR_SCHEMA_VERSION: 1;
+declare const DEFAULT_MAX_INSPECTOR_RECORDS = 512;
+declare const REDACTED_VALUE = "[REDACTED]";
+type ReplayTraceFilter = {
+    types?: string[];
+    sources?: string[];
+    outcomes?: RouterDecisionOutcome[];
+    correlationId?: string;
+};
+type CreateReplayInspectorOptions = {
+    redactedKeys?: string[];
+    maxRecords?: number;
+    /** Optional contracts so records can include payload schema version. */
+    registry?: Pick<ContractRegistry, 'get'>;
+};
+type InspectorRecord = {
+    index: number;
+    turn: number;
+    time: number;
+    outcome: RouterDecisionOutcome;
+    reason?: RouterDecisionReason;
+    detail?: string;
+    source: string;
+    target?: string;
+    type: string;
+    kind?: EventKind;
+    envelopeId?: string;
+    priorEnvelopeId?: string;
+    correlationId?: string;
+    causationId?: string;
+    hops?: number;
+    seq?: number;
+    idempotencyKey?: string;
+    schemaVersion?: number;
+    payloadSchemaVersion?: number;
+    deliveredTo: string[];
+    payload?: unknown;
+};
+type CausationTreeNode = {
+    envelopeId?: string;
+    type: string;
+    source: string;
+    outcome: RouterDecisionOutcome;
+    reason?: RouterDecisionReason;
+    children: CausationTreeNode[];
+};
+type ReplayParticipantSummary = {
+    id: string;
+    kind?: RuntimeGroupKind;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
+    seed?: string;
+    clock?: ClockSnapshot;
+    state?: unknown;
+    errorCount: number;
+    lastError?: string;
+};
+type ReplayInspectorReport = {
+    schemaVersion: typeof REPLAY_INSPECTOR_SCHEMA_VERSION;
+    participants: ReplayParticipantSummary[];
+    records: InspectorRecord[];
+    trees: CausationTreeNode[];
+    dropped: number;
+};
+type ReplayTapeAction = {
+    kind: 'publish';
+    event: EventInput;
+    extras?: PublishExtras;
+} | {
+    kind: 'dispatch';
+    participantId: string;
+    event: HostEvent;
+} | {
+    kind: 'step';
+    frames: number;
+} | {
+    kind: 'asset';
+    participantId: string;
+    event: HostEvent;
+};
+type ReplayInspectorExport = {
+    schemaVersion: typeof REPLAY_INSPECTOR_SCHEMA_VERSION;
+    origin: number;
+    redactedKeys: string[];
+    participants: ReplayParticipantSummary[];
+    tape: ReplayTapeAction[];
+    records: InspectorRecord[];
+    snapshots: Record<string, unknown>;
+};
+type ReplayCompareResult = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+type BoundReplaySession = {
+    publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
+    dispatch(participantId: string, event: HostEvent): void;
+    step(frames?: number): Promise<void>;
+    report(): Promise<ReplayInspectorReport>;
+    exportTrace(filter?: ReplayTraceFilter): Promise<ReplayInspectorExport>;
+    unbind(): void;
+};
+type ReplayInspector = {
+    watchRouter(router: EventRouter): () => void;
+    bind(group: RuntimeGroup): BoundReplaySession;
+    importTrace(exported: ReplayInspectorExport | string): void;
+    exportTrace(filter?: ReplayTraceFilter): ReplayInspectorExport;
+    report(filter?: ReplayTraceFilter): ReplayInspectorReport;
+    causationTree(correlationId?: string): CausationTreeNode[];
+    records(): InspectorRecord[];
+    reset(): void;
+    destroy(): void;
+};
+declare function compareReplayTraces(expected: InspectorRecord[], actual: InspectorRecord[]): ReplayCompareResult;
+declare function createReplayInspector(options?: CreateReplayInspectorOptions): ReplayInspector;
+declare function replayExportedTrace(exported: ReplayInspectorExport, group: RuntimeGroup, options?: CreateReplayInspectorOptions): Promise<{
+    inspector: ReplayInspector;
+    report: ReplayInspectorReport;
+}>;
+
+declare const COMPOSITOR_BLEND_MODES: readonly ["source-over", "screen"];
+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';
+type CompositorClip = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type CompositorLayerConfig = {
+    id: string;
+    order: number;
+    visible?: boolean;
+    opacity?: number;
+    blend?: CompositorBlendMode;
+    clip?: CompositorClip;
+    pointerEvents?: CompositorPointerEvents;
+    clearPolicy?: CompositorClearPolicy;
+};
+type CompositorLayerInspect = {
+    id: string;
+    order: number;
+    visible: boolean;
+    opacity: number;
+    blend: CompositorBlendMode;
+    clip: CompositorClip | null;
+    pointerEvents: CompositorPointerEvents;
+    clearPolicy: CompositorClearPolicy;
+};
+type CompositorHostOptions = {
+    /** Back-layer pixels. Scaled nearest-neighbor to the compositor viewport. */
+    image?: ImageData;
+    /** Opaque CSS `#rgb` / `#rrggbb` fill when `image` is omitted. */
+    color?: string;
+};
+type CreateCompositorOptions = {
+    group: RuntimeGroup;
+    layers: CompositorLayerConfig[];
+    width?: number;
+    height?: number;
+    dpr?: number;
+    host?: CompositorHostOptions;
+    /**
+     * Host surface clear. Default `transparent` — never fill black.
+     * Per-layer `clearPolicy: 'transparent'` knocks out RGB 0,0,0 backing
+     * pixels so opaque cart canvases can stack over a host image.
+     */
+    clearPolicy?: CompositorClearPolicy;
+    /**
+     * When true (default), compose into a compositor-owned canvas.
+     * When false, require `target` and draw there.
+     */
+    offscreen?: boolean;
+    target?: HTMLCanvasElement;
+};
+type ComposedFrame = {
+    imageData: ImageData;
+    pngDataUrl: string;
+    width: number;
+    height: number;
+    declaredOrder: CompositorLayerInspect[];
+};
+type CompositorInspect = {
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    clearPolicy: CompositorClearPolicy;
+    layers: CompositorLayerInspect[];
+    declaredOrder: string[];
+};
+type Compositor = {
+    readonly canvas: HTMLCanvasElement;
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+    compose(): ImageData;
+    captureComposedFrame(): ComposedFrame;
+    /**
+     * Shared CSS viewport. Updates group canvas buffer size (`width * dpr`).
+     * Layer order/blend survive. Carts that cache layout from `DimensionContext`
+     * need `group.reset()` (or remount) so they rebuild at the new size.
+     */
+    resize(width: number, height: number, dpr?: number): void;
+    setLayer(id: string, patch: Partial<Omit<CompositorLayerConfig, 'id'>>): void;
+    layer(id: string): CompositorLayerInspect;
+    layers(): CompositorLayerInspect[];
+    pointerTarget(x: number, y: number): string | undefined;
+    unmountLayer(id: string): void;
+    inspect(): CompositorInspect;
+    destroy(): void;
+};
+declare function createCompositor(options: CreateCompositorOptions): Compositor;
+
+/**
+ * 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
+ * See packages/engine/LICENSE
+ *
+ * Opt-in DOM/browser host harness. Mounts a caller-supplied host into a
+ * viewport, optionally wires a runtime group and compositor, and dispatches
+ * pointer/keyboard through layout coordinates. Does not import Node built-ins
+ * and does not encode host-product event types or fixtures.
+ */
+
+declare const DEFAULT_BROWSER_VIEWPORT: {
+    readonly width: 320;
+    readonly height: 180;
+    readonly deviceScaleFactor: 1;
+};
+type BrowserInputModality = 'pointer' | 'keyboard' | 'touch';
+type BrowserViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+type BrowserHarnessAction = {
+    type: 'viewport';
+    width: number;
+    height: number;
+    dpr: number;
+} | {
+    type: 'click';
+    x: number;
+    y: number;
+    selector?: string;
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'step';
+    frames: number;
+} | {
+    type: 'advance';
+    ms: number;
+} | {
+    type: 'reducedMotion';
+    value: boolean;
+} | {
+    type: 'inputModality';
+    value: BrowserInputModality;
+};
+type BrowserHarnessScreenshot = {
+    imageData: ImageData | null;
+    pngDataUrl: string | null;
+    html: string;
+    declaredOrder: string[];
+};
+type BrowserA11ySnapshot = {
+    focus: {
+        tag: string;
+        id: string;
+        role: string | null;
+        name: string;
+    };
+    live: string;
+    html: string;
+};
+type BrowserReproductionMetadata = {
+    seed: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    reducedMotion: boolean;
+    inputModality: BrowserInputModality;
+    actions: BrowserHarnessAction[];
+};
+type BrowserCompositorConfig = Omit<CreateCompositorOptions, 'group' | 'width' | 'height' | 'dpr'>;
+type BrowserHarnessMountContext = {
+    root: HTMLElement;
+    layout: PresentationLayout;
+    reducedMotion: boolean;
+    inputModality: BrowserInputModality;
+    placeRegion(id: string, element: HTMLElement): PixelRect | undefined;
+};
+type BrowserHarnessRuntimeContext = BrowserHarnessMountContext & {
+    group: RuntimeGroup | undefined;
+    compositor: Compositor | undefined;
+    publish(event: EventInput): EventEnvelope | undefined;
+};
+type BrowserHostSession = {
+    participants?: RuntimeGroupParticipantConfig[];
+    compositor?: BrowserCompositorConfig;
+    hostState?: () => unknown;
+    ready?: (ctx: BrowserHarnessRuntimeContext) => void;
+    relayout?: (ctx: BrowserHarnessRuntimeContext) => void;
+    destroy?: () => void;
+};
+type CreateBrowserHarnessOptions = {
+    seed?: string;
+    viewport?: BrowserViewport;
+    reducedMotion?: boolean;
+    inputModality?: BrowserInputModality;
+    origin?: number;
+    createId?: () => string;
+    geometry?: GeometryDocument;
+    contentWidth?: number;
+    contentHeight?: number;
+    fit?: PresentationFitMode;
+    mount?: (ctx: BrowserHarnessMountContext) => BrowserHostSession | void;
+};
+type BrowserHarnessInspect = {
+    host: unknown;
+    layout: PresentationLayout;
+    events: EventEnvelope[];
+    participantEvents: Record<string, HostEvent[]>;
+    state: Record<string, unknown>;
+    focus: BrowserA11ySnapshot['focus'];
+    scrollTop: number;
+    clock: {
+        framesElapsed: number;
+    };
+};
+type BrowserHarness = {
+    readonly root: HTMLElement;
+    readonly group: RuntimeGroup | undefined;
+    readonly compositor: Compositor | undefined;
+    readonly layout: PresentationLayout;
+    readonly events: readonly EventEnvelope[];
+    goto(url?: string): void;
+    setViewport(width: number, height: number, dpr?: number): void;
+    setReducedMotion(value: boolean): void;
+    setInputModality(value: BrowserInputModality): void;
+    click(selectorOrX: string | number, y?: number): void;
+    key(key: string): void;
+    focus(selector: string): void;
+    step(frames?: number): Promise<void>;
+    advance(ms: number): Promise<void>;
+    screenshot(): BrowserHarnessScreenshot;
+    accessibilitySnapshot(): BrowserA11ySnapshot;
+    inspect(): Promise<BrowserHarnessInspect>;
+    reproduction(): BrowserReproductionMetadata;
+    captureComposedFrame(): ComposedFrame;
+    destroy(): void;
+};
+declare function createBrowserHarness(options?: CreateBrowserHarnessOptions): BrowserHarness;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Playwright-shaped adapter over `createBrowserHarness`. Same method names as
+ * a Playwright `Page` (`goto`, `setViewportSize`, `click`, `screenshot`) so CI
+ * can swap engines later without `@playwright/test` as an engine dependency.
+ */
+
+type PlaywrightCompatibleViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+type PlaywrightCompatibleAdapter = {
+    goto(url?: string): Promise<void>;
+    setViewportSize(viewport: PlaywrightCompatibleViewport): Promise<void>;
+    click(selector: string): Promise<void>;
+    screenshot(): Promise<BrowserHarnessScreenshot>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    locator(selector: string): {
+        click(): Promise<void>;
+        focus(): Promise<void>;
+    };
+    close(): Promise<void>;
+};
+declare function createPlaywrightCompatibleAdapter(harness: BrowserHarness): PlaywrightCompatibleAdapter;
+
+/**
+ * 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_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 CapabilityModuleRef, type CapabilityModuleRequirements, 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 CreateAudioBrokerOptions, type CreateAudioCueTimelineOptions, type CreateBrowserHarnessOptions, type CreateCompositorOptions, type CreateExecutableModuleHostOptions, 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_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, 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 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 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, type ValidateCapabilityManifestResult, type ValidateResult, type ValidateSnapshotResult, type VersionedSnapshot, type VirtualClock, applyCueEasing, applySnapshotMigrations, assetStatusEvent, assetToNormalized, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, canvasToCss, canvasToNormalized, toJSON as capabilityManifestToJSON, 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, 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, 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 };