@cyberart-io/engine 0.0.4 → 0.0.6

package/dist/headless.d.ts

@@ -177,6 +177,7 @@ declare class PointerManager {
  */
 declare const EVENT_ENVELOPE_VERSION: 1;
 type EventKind = 'intent' | 'state' | 'diagnostic';
+type RejectionReason = 'malformed' | 'unauthorized' | 'host-rejected' | 'rate-limited' | 'loop-detected' | 'storm-detected' | 'unknown-target' | 'not-subscribed' | 'hop-limit';
 type EventEnvelope = {
     schemaVersion: typeof EVENT_ENVELOPE_VERSION;
     type: string;
@@ -327,6 +328,76 @@ type CartStateBundle = {
     state: unknown;
 };
 
+/**
+ * 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;
+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 ExportSnapshotOptions = {
+    cartVersion?: string;
+    modules?: SnapshotModuleRef[];
+    hostState?: unknown;
+    hostStateRef?: string;
+    assets?: SnapshotAssetRef[];
+    createdAt?: string;
+    provenance?: SnapshotProvenance;
+    runtimeVersion?: string;
+};
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -474,6 +545,75 @@ type AssetPreloader = {
     dispose(): void;
 };
 
+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 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;
+};
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -518,6 +658,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. */
@@ -548,7 +699,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;
@@ -589,75 +745,11 @@ 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;
 };
 
-/**
- * Copyright (c) 2026 Aaron Boyarsky
- * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
- * See packages/engine/LICENSE
- *
- * CI / agent harness around production `createRuntime({ deterministic })`.
- * `installHeadlessCanvas` is test-only — do not call it from Player or kaleidoscope.
- */
-
-/** 1×1 PNG so `captureFrame(path)` writes a file that actually opens. */
-declare const HEADLESS_PNG_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
-declare const DEFAULT_HEADLESS_WIDTH = 320;
-declare const DEFAULT_HEADLESS_HEIGHT = 180;
-/**
- * Documented jsdom canvas install. Mutates `HTMLCanvasElement.prototype`.
- * Idempotent. Not for production playback.
- */
-declare function installHeadlessCanvas(): void;
-type HeadlessFrameError = {
-    error: unknown;
-    info: FrameErrorInfo;
-};
-type HeadlessInspect = {
-    state: unknown;
-    events: HostEvent[];
-    errors: HeadlessFrameError[];
-    replay: ReplayMetadata;
-    clock: ClockSnapshot;
-};
-type CreateHeadlessHarnessOptions<T = unknown> = {
-    cart: AnimationCart<T>;
-    seed?: CreateRuntimeOptions['seed'];
-    width?: number;
-    height?: number;
-    /** Virtual clock origin in ms. Default 0. */
-    origin?: number;
-    actions?: ScriptedAction[];
-    initialState?: Partial<T>;
-    gameManager?: unknown;
-    onEvent?: HostEventListener;
-    onError?: (error: unknown, info: FrameErrorInfo) => void;
-};
-type HeadlessHarness<T = unknown> = {
-    readonly runtime: CyberArtRuntime;
-    readonly container: HTMLElement;
-    readonly events: readonly HostEvent[];
-    readonly errors: readonly HeadlessFrameError[];
-    readonly cart: CartHandle;
-    step(frames?: number): Promise<void>;
-    advance(ms: number): Promise<void>;
-    schedule(action: ScriptedAction): void;
-    dispatch(event: HostEvent): void;
-    start(): Promise<void>;
-    pause(): void;
-    resume(): void;
-    readonly paused: boolean;
-    key(key: string): void;
-    /** Pointer-down at the next frame. Use `schedule` for move/up. Canvas pixels, not CSS. */
-    click(x: number, y: number): void;
-    inspect(): Promise<HeadlessInspect>;
-    captureFrame(path?: string): Promise<CartSnapshot>;
-    remount(options?: MountOptions<T>): CartHandle;
-    destroy(): void;
-};
-declare function createHeadlessHarness<T>(options: CreateHeadlessHarnessOptions<T>): HeadlessHarness<T>;
-
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -690,15 +782,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;
 };
 
@@ -755,6 +881,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;
@@ -762,6 +892,9 @@ type RuntimeGroupParticipantInspect = {
     errors: RuntimeGroupFrameError[];
     kind: RuntimeGroupKind;
     clock: ClockSnapshot;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
 };
 type RuntimeGroupDiagnostics = {
     paused: boolean;
@@ -787,19 +920,597 @@ 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 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 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;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Deterministic software Canvas2D for jsdom / CI. Integer pixel coverage
+ * (pixel-center samples, nearest-neighbor images, no antialiasing). No
+ * Math.random. Unsupported operations throw HeadlessUnsupportedOperationError
+ * instead of no-op.
+ */
+declare class HeadlessUnsupportedOperationError extends Error {
+    readonly operation: string;
+    name: string;
+    constructor(operation: string, detail?: string);
+}
+type GlyphAtlas = {
+    cellWidth: number;
+    cellHeight: number;
+    /** Packed 0/1 coverage, `cellWidth * cellHeight` bits per glyph, row-major. */
+    glyphs: Record<string, Uint8Array>;
+};
+type HeadlessImageFixture = {
+    readonly __headlessImage: true;
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+type HeadlessCanvas2DSettings = {
+    alpha?: boolean;
+    glyphAtlas?: GlyphAtlas;
+};
+declare class HeadlessSurface {
+    readonly canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+    readonly alpha: boolean;
+    pixels: Uint8ClampedArray;
+    glyphAtlas: GlyphAtlas;
+    context: CanvasRenderingContext2D | null;
+    onDeviceReset: (() => void) | null;
+    constructor(canvas: HTMLCanvasElement, width: number, height: number, settings: HeadlessCanvas2DSettings);
+    resize(width: number, height: number, clear?: boolean): void;
+    fillOpaqueBlack(): void;
+}
+declare function createImageFixture(width: number, height: number, data?: Uint8ClampedArray): HeadlessImageFixture;
+declare function setDefaultGlyphAtlas(atlas: GlyphAtlas | undefined): void;
+declare function getHeadlessSurface(canvas: HTMLCanvasElement): HeadlessSurface | undefined;
+declare function attachHeadlessCanvas2D(canvas: HTMLCanvasElement, settings?: HeadlessCanvas2DSettings): CanvasRenderingContext2D;
+declare function makeImageData(data: Uint8ClampedArray, width: number, height: number): ImageData;
+declare function createDefaultGlyphAtlas(): GlyphAtlas;
+declare function encodePng(width: number, height: number, pixels: Uint8ClampedArray | Uint8Array): Uint8Array;
+declare function encodePngDataUrl(width: number, height: number, pixels: Uint8ClampedArray | Uint8Array): string;
+declare function decodePng(bytes: Uint8Array): ImageData;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * CI / agent harness around production `createRuntime({ deterministic })`.
+ * `installHeadlessCanvas` is test-only — do not call it from Player or kaleidoscope.
+ */
+
+/** 1×1 PNG fallback when `toDataURL` runs before a 2D context is attached. */
+declare const HEADLESS_PNG_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+declare const DEFAULT_HEADLESS_WIDTH = 320;
+declare const DEFAULT_HEADLESS_HEIGHT = 180;
+type InstallHeadlessCanvasOptions = {
+    glyphAtlas?: GlyphAtlas;
+};
+/**
+ * Documented jsdom canvas install. Mutates `HTMLCanvasElement.prototype`.
+ * Idempotent. Not for production playback. Software Canvas2D pixels flow
+ * through `getContext` / `toDataURL` so `cart.snapshot()` is the real frame.
+ */
+declare function installHeadlessCanvas(options?: InstallHeadlessCanvasOptions): void;
+type HeadlessFrameError = {
+    error: unknown;
+    info: FrameErrorInfo;
+};
+type HeadlessInspect = {
+    state: unknown;
+    events: HostEvent[];
+    errors: HeadlessFrameError[];
+    replay: ReplayMetadata;
+    clock: ClockSnapshot;
+};
+type CreateHeadlessHarnessOptions<T = unknown> = {
+    cart: AnimationCart<T>;
+    seed?: CreateRuntimeOptions['seed'];
+    width?: number;
+    height?: number;
+    /** Virtual clock origin in ms. Default 0. */
+    origin?: number;
+    actions?: ScriptedAction[];
+    initialState?: Partial<T>;
+    gameManager?: unknown;
+    onEvent?: HostEventListener;
+    onError?: (error: unknown, info: FrameErrorInfo) => void;
+};
+type HeadlessHarness<T = unknown> = {
+    readonly runtime: CyberArtRuntime;
+    readonly container: HTMLElement;
+    readonly events: readonly HostEvent[];
+    readonly errors: readonly HeadlessFrameError[];
+    readonly cart: CartHandle;
+    step(frames?: number): Promise<void>;
+    advance(ms: number): Promise<void>;
+    schedule(action: ScriptedAction): void;
+    dispatch(event: HostEvent): void;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+    key(key: string): void;
+    /** Pointer-down at the next frame. Use `schedule` for move/up. Canvas pixels, not CSS. */
+    click(x: number, y: number): void;
+    inspect(): Promise<HeadlessInspect>;
+    captureFrame(path?: string): Promise<CartSnapshot>;
+    remount(options?: MountOptions<T>): CartHandle;
+    destroy(): void;
+};
+declare function createHeadlessHarness<T>(options: CreateHeadlessHarnessOptions<T>): HeadlessHarness<T>;
+
+declare const UPDATE_GOLDEN_ENV = "CYBERART_UPDATE_GOLDEN";
+type VisualCompareOptions = {
+    /** Max per-channel absolute delta (0 = exact). */
+    tolerance?: number;
+    /** Max allowed differing pixels after tolerance. */
+    maxDifferingPixels?: number;
+    /**
+     * When set, a pixel matches if weighted RGB distance <= this value.
+     * Weights are 0.299 / 0.587 / 0.114 (documented luma).
+     */
+    perceptualThreshold?: number;
+    /** Alpha channel max delta. Defaults to `tolerance` (including when perceptual RGB is used). */
+    alphaTolerance?: number;
+    /** Force golden-update behavior regardless of env. */
+    updateGolden?: boolean;
+};
+type VisualArtifacts = {
+    expectedPng: Uint8Array;
+    actualPng: Uint8Array;
+    diffPng: Uint8Array;
+    expectedDataUrl: string;
+    actualDataUrl: string;
+    diffDataUrl: string;
+    differingPixels: number;
+};
+type VisualCompareResult = {
+    match: boolean;
+    differingPixels: number;
+    width: number;
+    height: number;
+    artifacts: VisualArtifacts;
+    updatedGolden: boolean;
+};
+declare function shouldUpdateGolden(env?: {
+    [key: string]: string | undefined;
+} | undefined): boolean;
+declare function imageDataFromPngDataUrl(dataUrl: string): ImageData;
+declare function compareImageData(actual: ImageData, expected: ImageData, options?: VisualCompareOptions): VisualCompareResult;
+declare function assertPixelsEqual(actual: ImageData, expected: ImageData, options?: VisualCompareOptions): VisualCompareResult;
+declare function assertPngDataUrlsEqual(actualDataUrl: string, expectedDataUrl: string, options?: VisualCompareOptions): VisualCompareResult;
+type VisualArtifactPaths = {
+    expectedPath: string;
+    actualPath: string;
+    diffPath: string;
+};
+/**
+ * Node-only. Writes expected.png / actual.png / diff.png under `dir`.
+ * Uses a dynamic `node:fs/promises` import so the browser runtime graph stays clean.
+ */
+declare function writeVisualArtifacts(dir: string, artifacts: VisualArtifacts, names?: {
+    expected?: string;
+    actual?: string;
+    diff?: string;
+}): Promise<VisualArtifactPaths>;
+
 type CreateHeadlessMultiCartHarnessOptions = CreateRuntimeGroupOptions;
 type HeadlessMultiCartHarness = RuntimeGroup;
 declare function createHeadlessMultiCartHarness(options: CreateHeadlessMultiCartHarnessOptions): HeadlessMultiCartHarness;
 
-export { type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, HEADLESS_PNG_DATA_URL, type HeadlessFrameError, type HeadlessHarness, type HeadlessInspect, type HeadlessMultiCartHarness, createHeadlessHarness, createHeadlessMultiCartHarness, installHeadlessCanvas };
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * 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
+ * `host.presentation.cue.started` fail at definition time instead of
+ * silently inferring a bogus kind.
+ */
+
+type ContractFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+type PayloadFieldSpec = {
+    type: ContractFieldType;
+    optional?: boolean;
+};
+type PayloadSchema = {
+    /** Payload schema version. Bump on any field change. */
+    version: number;
+    fields: Record<string, PayloadFieldSpec>;
+};
+type ContractDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type EventContractManifest = {
+    type: string;
+    kind: EventKind;
+    version: number;
+    fields: Record<string, {
+        type: ContractFieldType;
+        optional: boolean;
+    }>;
+    emitPattern: string;
+    subscribePattern: string;
+};
+type PayloadValidation = {
+    ok: true;
+    payload: unknown;
+} | {
+    ok: false;
+    errors: ContractDiagnostic[];
+};
+type EventContract = {
+    type: string;
+    kind: EventKind;
+    payloadSchema: PayloadSchema;
+    emitPattern: string;
+    subscribePattern: string;
+    toManifest(): EventContractManifest;
+    validatePayload(payload: unknown): PayloadValidation;
+};
+type ContractRegistry = {
+    get(type: string): EventContract | undefined;
+    manifest(): EventContractManifest[];
+    validateEnvelope(event: EventEnvelope): PayloadValidation;
+    asRouterValidate(event: EventEnvelope): ValidateResult;
+};
+
+declare const REPLAY_INSPECTOR_SCHEMA_VERSION: 1;
+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;
+}>;
+
+type CueEasing = 'linear' | 'ease-out';
+type CueDuplicatePolicy = 'ignore' | 'replace' | 'reject';
+type CueRepeatPolicy = {
+    count: number;
+} | {
+    forever: true;
+};
+type CueReducedMotionPolicy = 'skip' | 'complete' | {
+    durationFrames: number;
+};
+type CueSpec = {
+    name: string;
+    idempotencyKey: string;
+    /** Frame when the cue is eligible to start (before delay). Default: play frame. */
+    startFrame?: number;
+    durationFrames: number;
+    delayFrames?: number;
+    easing?: CueEasing;
+    repeat?: CueRepeatPolicy;
+    /**
+     * When the timeline is in reduced-motion mode: skip (complete immediately),
+     * complete (same), or a shorter duration. Default `complete`.
+     */
+    reducedMotion?: CueReducedMotionPolicy;
+    onDuplicate?: CueDuplicatePolicy;
+};
+type CuePhase = 'scheduled' | 'active' | 'completed' | 'cancelled';
+type CueView = {
+    name: string;
+    idempotencyKey: string;
+    phase: CuePhase;
+    startFrame: number;
+    durationFrames: number;
+    delayFrames: number;
+    easing: CueEasing;
+    progress: number;
+    repeatIndex: number;
+};
+
+/**
+ * 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_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 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 createHeadlessAudioAdapter(options?: {
+    reducedSensory?: boolean;
+    originFrame?: number;
+}): HeadlessAudioAdapter;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Node/jsdom test helpers. Import from `@cyberart-io/engine/headless`.
+ * Production carts and browser hosts must import `@cyberart-io/engine` instead
+ * so Vite never walks `node:fs/promises`.
+ */
+
+type WriteComposedFrameResult = ComposedFrame & {
+    path?: string;
+};
+/**
+ * Headless composition-order capture. `captureComposedFrame()` stays on the
+ * compositor (browser-safe). This helper writes PNG bytes when a path is given.
+ */
+declare function writeComposedFrame(compositor: Compositor, path?: string): Promise<WriteComposedFrameResult>;
+
+export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };