@cyberart-io/engine 0.0.5 → 0.0.7

package/dist/headless.d.ts

@@ -254,11 +254,16 @@ type AnimationTiming = {
     deltaSinceLastUpdate: number;
     deltaSinceLastRender: number;
 };
+type CartKind = 'render' | 'calculation';
 type AnimationCart<T = unknown, TFeatureState = undefined> = {
     getDefaultFeatureState?: (R: Random, dimensionContext: DimensionContext, rawParams: number[], keyboardManager: KeyboardManager, customState?: Partial<T>, pointerManager?: PointerManager, gameManager?: unknown, hostChannel?: HostChannel) => TFeatureState;
     getDefaultState: (R: Random, dimensionContext: DimensionContext, rawParams: number[], keyboardManager: KeyboardManager, customState?: Partial<T>, pointerManager?: PointerManager, gameManager?: unknown, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => T;
     update: (R: Random, framesElapsed: number, rawParams: number[], dimensionContext: DimensionContext, state: T, keyboardManager: KeyboardManager, pointerManager?: PointerManager, gameManager?: unknown, timing?: AnimationTiming, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => T;
-    render: (R: Random, framesElapsed: number, rawParams: number[], dimensionContext: DimensionContext, state: T, drawingContext: CanvasRenderingContext2D, imageData: ImageData, pointerManager?: PointerManager, gameManager?: unknown, timing?: AnimationTiming, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => void;
+    /**
+     * Draw into the 2D context. Optional on calculation carts (`kind:
+     * 'calculation'`); the runtime does not call it and does not create a canvas.
+     */
+    render?: (R: Random, framesElapsed: number, rawParams: number[], dimensionContext: DimensionContext, state: T, drawingContext: CanvasRenderingContext2D, imageData: ImageData, pointerManager?: PointerManager, gameManager?: unknown, timing?: AnimationTiming, featureState?: Readonly<TFeatureState>, hostChannel?: HostChannel) => void;
     adjust?: Record<string, {
         type: 'switch';
         immediate?: boolean;
@@ -328,6 +333,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
@@ -475,6 +550,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
@@ -519,6 +663,22 @@ type CreateRuntimeOptions = {
      * scripted `{ type: 'asset' }` actions own delivery timing.
      */
     assets?: AssetRuntimeOptions;
+    /**
+     * Shared page-level unlock broker. Optional. Carts that only set
+     * `metadata.audio: 'tone'` keep the existing `start()` / `unlockAudio()`
+     * path when this is omitted.
+     */
+    audioBroker?: AudioBroker;
+    /**
+     * Runtime-group participant id to authorize on this runtime. Teardown of
+     * this id does not close Tone for remaining carts.
+     */
+    audioParticipantId?: string;
+    /**
+     * `'calculation'` skips canvas construction and paint. `getDefaultState`,
+     * `update`, and host-channel events still run. Default `'render'`.
+     */
+    kind?: CartKind;
 };
 type MountOptions<T = unknown> = {
     /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
@@ -549,7 +709,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;
@@ -590,6 +755,10 @@ type CyberArtRuntime = {
      * Survives cart remount; `destroy()` disposes it.
      */
     readonly assets: AssetPreloader | undefined;
+    /** Shared broker when `createRuntime({ audioBroker })` was set. */
+    readonly audioBroker: AudioBroker | undefined;
+    /** `'render'` (default) or `'calculation'` (no canvas / paint). */
+    readonly kind: CartKind;
     onError?: (error: unknown, info: FrameErrorInfo) => void;
 };
 
@@ -681,7 +850,7 @@ type EventRouter = {
  * locksteps a deterministic clock. Carts never receive the router object.
  */
 
-type RuntimeGroupKind = 'render' | 'calculation';
+type RuntimeGroupKind = CartKind;
 /**
  * Optional capability-shaped attach hints. Explicit participant `emit` /
  * `subscribe` / `authoritative` win. Do not import the capability manifest
@@ -699,7 +868,7 @@ type RuntimeGroupFrameError = {
 type RuntimeGroupParticipantConfig<T = unknown> = {
     id: string;
     cart: AnimationCart<T>;
-    /** Rendered surface vs calculation cart (still a real `AnimationCart`). */
+    /** Rendered surface vs calculation cart (update + events, no canvas / paint). */
     kind?: RuntimeGroupKind;
     seed?: CreateRuntimeOptions['seed'];
     container?: HTMLElement;
@@ -726,6 +895,8 @@ type CreateRuntimeGroupOptions = {
     router?: EventRouterOptions;
     /** Bound on the accepted-event trace (oldest dropped). Default 1024. */
     maxTrace?: number;
+    /** Shared page-level audio unlock broker. Optional. */
+    audioBroker?: AudioBroker;
 };
 type RuntimeGroupParticipantInspect = {
     state: unknown;
@@ -761,6 +932,7 @@ type RuntimeGroup = {
     readonly router: EventRouter;
     readonly origin: number;
     readonly paused: boolean;
+    readonly audioBroker: AudioBroker | undefined;
     participant(id: string): RuntimeGroupParticipantHandle;
     step(frames?: number): Promise<void>;
     pause(): void;
@@ -784,6 +956,20 @@ type CompositorBlendMode = (typeof COMPOSITOR_BLEND_MODES)[number];
 declare const COMPOSITOR_CLEAR_POLICIES: readonly ["transparent", "opaque"];
 type CompositorClearPolicy = (typeof COMPOSITOR_CLEAR_POLICIES)[number];
 type CompositorPointerEvents = 'auto' | 'none';
+declare const COMPOSITOR_SOURCE_KINDS: readonly ["participant", "image", "canvas"];
+type CompositorSourceKind = (typeof COMPOSITOR_SOURCE_KINDS)[number];
+type CompositorParticipantSource = {
+    kind: 'participant';
+};
+type CompositorImageSource = {
+    kind: 'image';
+    image: ImageData;
+};
+type CompositorCanvasSource = {
+    kind: 'canvas';
+    canvas: HTMLCanvasElement;
+};
+type CompositorLayerSource = CompositorParticipantSource | CompositorImageSource | CompositorCanvasSource;
 type CompositorClip = {
     x: number;
     y: number;
@@ -799,6 +985,11 @@ type CompositorLayerConfig = {
     clip?: CompositorClip;
     pointerEvents?: CompositorPointerEvents;
     clearPolicy?: CompositorClearPolicy;
+    /**
+     * Pixel source. Default `participant` reads the runtime-group canvas.
+     * `image` / `canvas` swap atomically via `setLayer` / `addLayer`.
+     */
+    source?: CompositorLayerSource;
 };
 type CompositorLayerInspect = {
     id: string;
@@ -809,6 +1000,7 @@ type CompositorLayerInspect = {
     clip: CompositorClip | null;
     pointerEvents: CompositorPointerEvents;
     clearPolicy: CompositorClearPolicy;
+    sourceKind: CompositorSourceKind;
 };
 type ComposedFrame = {
     imageData: ImageData;
@@ -841,6 +1033,7 @@ type Compositor = {
      */
     resize(width: number, height: number, dpr?: number): void;
     setLayer(id: string, patch: Partial<Omit<CompositorLayerConfig, 'id'>>): void;
+    addLayer(config: CompositorLayerConfig): void;
     layer(id: string): CompositorLayerInspect;
     layers(): CompositorLayerInspect[];
     pointerTarget(x: number, y: number): string | undefined;
@@ -1213,6 +1406,289 @@ declare function replayExportedTrace(exported: ReplayInspectorExport, group: Run
     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;
+};
+type PlayCueResult = {
+    ok: true;
+    cue: CueView;
+} | {
+    ok: false;
+    reason: 'duplicate' | 'invalid';
+    detail: string;
+};
+
+/**
+ * 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;
+
+declare const VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const VISUAL_LAYER_KINDS: readonly ["layer", "mask", "sprite"];
+type VisualLayerKind = (typeof VISUAL_LAYER_KINDS)[number];
+declare const VISUAL_LAYER_TRANSITIONS: readonly ["show", "hide", "replace", "crossfade"];
+type VisualLayerTransitionKind = (typeof VISUAL_LAYER_TRANSITIONS)[number];
+declare const VISUAL_LAYER_EVENTS: readonly ["visual.layer.revealed", "visual.layer.hidden", "visual.layer.transition-started", "visual.layer.transition-completed", "visual.layer.failed"];
+type VisualLayerEventType = (typeof VISUAL_LAYER_EVENTS)[number];
+declare const VISUAL_LAYER_FAILURE_CODES: readonly ["asset-failed", "missing-source", "unknown-layer", "unknown-version", "invalid-snapshot"];
+type VisualLayerFailureCode = (typeof VISUAL_LAYER_FAILURE_CODES)[number];
+type VisualLayerAssetStatus = 'pending' | 'ready' | 'failed';
+type VisualLayerFallbackPolicy = 'keep-prior' | 'hide' | {
+    version: string;
+};
+type VisualLayerVersionDeclaration = {
+    id: string;
+    assetId: string;
+    provenance?: AssetProvenance;
+};
+type VisualLayerDeclaration = {
+    id: string;
+    kind: VisualLayerKind;
+    versions: readonly VisualLayerVersionDeclaration[];
+    initialVersion?: string;
+    compositorLayerId?: string;
+    incomingLayerId?: string;
+    order?: number;
+    blend?: CompositorBlendMode;
+    clip?: CompositorClip;
+    pointerEvents?: CompositorPointerEvents;
+    clearPolicy?: CompositorClearPolicy;
+    fallback?: VisualLayerFallbackPolicy;
+};
+type VisualLayerAcceptedBinding = {
+    layerId: string;
+    toVersion: string;
+    kind?: VisualLayerTransitionKind;
+    durationFrames?: number;
+    delayFrames?: number;
+    easing?: CueEasing;
+    idempotencyKey?: string;
+};
+type VisualLayerCueSpec = CueSpec & {
+    layerId: string;
+    kind: VisualLayerTransitionKind;
+    toVersion?: string;
+    fromVersion?: string;
+};
+type VisualLayerTransitionInspect = {
+    kind: VisualLayerTransitionKind;
+    progress: number;
+    fromVersion: string | null;
+    toVersion: string | null;
+    cueKey: string;
+    startFrame: number;
+    durationFrames: number;
+    delayFrames: number;
+    easing: CueEasing;
+};
+type VisualLayerInspect = {
+    id: string;
+    kind: VisualLayerKind;
+    visible: boolean;
+    activeVersion: string | null;
+    pendingVersion: string | null;
+    committedVersion: string | null;
+    opacity: number;
+    order: number;
+    provenance: AssetProvenance | null;
+    overrideVersion: string | null;
+    transition: VisualLayerTransitionInspect | null;
+};
+type VisualLayerEvent = {
+    type: VisualLayerEventType;
+    atFrame: number;
+    layerId: string;
+    version?: string;
+    kind?: VisualLayerTransitionKind;
+    progress: number;
+    code?: VisualLayerFailureCode;
+};
+type VisualLayerDiagnostic = {
+    code: VisualLayerFailureCode;
+    layerId: string;
+    version?: string;
+    assetId?: string;
+    message: string;
+    atFrame: number;
+    failure?: AssetFailure;
+};
+type VisualLayerSnapshotRow = {
+    id: string;
+    kind: VisualLayerKind;
+    visible: boolean;
+    committedVersion: string | null;
+    pendingVersion: string | null;
+    activeVersion: string | null;
+    opacity: number;
+    order: number;
+    overrideVersion: string | null;
+    provenance: AssetProvenance | null;
+    fallback: VisualLayerFallbackPolicy;
+    transition: VisualLayerTransitionInspect | null;
+};
+type VisualLayerControllerSnapshot = {
+    schemaVersion: typeof VISUAL_LAYER_SNAPSHOT_SCHEMA_VERSION;
+    frame: number;
+    sceneId: string | null;
+    reducedMotion: boolean;
+    layers: VisualLayerSnapshotRow[];
+    assets: Record<string, VisualLayerAssetStatus>;
+    events: VisualLayerEvent[];
+    diagnostics: VisualLayerDiagnostic[];
+};
+type PlayVisualLayerResult = PlayCueResult;
+type RestoreVisualLayerResult = {
+    ok: true;
+    snapshot: VisualLayerControllerSnapshot;
+} | {
+    ok: false;
+    errors: VisualLayerDiagnostic[];
+};
+type CreateVisualLayerControllerOptions = {
+    compositor: Compositor;
+    layers: readonly VisualLayerDeclaration[];
+    preloader?: AssetPreloader;
+    originFrame?: number;
+    reducedMotion?: boolean;
+    sceneId?: string;
+    fallback?: VisualLayerFallbackPolicy;
+    onAccepted?: readonly VisualLayerAcceptedBinding[];
+    dispatch?: (event: HostEvent) => void;
+};
+type VisualLayerController = {
+    registerSource(assetId: string, source: ImageData | HTMLCanvasElement): void;
+    handleHostEvent(event: HostEvent): void;
+    override(layerId: string, version: string | null): void;
+    play(spec: VisualLayerCueSpec): PlayVisualLayerResult;
+    step(frames?: number): VisualLayerEvent[];
+    snapshot(): VisualLayerControllerSnapshot;
+    restore(input: unknown): RestoreVisualLayerResult;
+    inspect(): VisualLayerInspect[];
+    captureComposedFrame(): ComposedFrame;
+    destroy(): void;
+    readonly frame: number;
+    readonly sceneId: string | null;
+    readonly compositor: Compositor;
+};
+type VisualLayerCapture = {
+    frame: ComposedFrame;
+    layers: VisualLayerInspect[];
+};
+declare function captureVisualLayers(controller: VisualLayerController): VisualLayerCapture;
+declare function createVisualLayerController(options: CreateVisualLayerControllerOptions): VisualLayerController;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -1220,7 +1696,8 @@ declare function replayExportedTrace(exported: ReplayInspectorExport, group: Run
  *
  * Node/jsdom test helpers. Import from `@cyberart-io/engine/headless`.
  * Production carts and browser hosts must import `@cyberart-io/engine` instead
- * so Vite never walks `node:fs/promises`.
+ * so Vite never walks `node:fs/promises`. `createHeadlessMultiCartHarness`
+ * is the same group API as `createRuntimeGroup`, including calculation carts.
  */
 
 type WriteComposedFrameResult = ComposedFrame & {
@@ -1232,4 +1709,4 @@ type WriteComposedFrameResult = ComposedFrame & {
  */
 declare function writeComposedFrame(compositor: Compositor, path?: string): Promise<WriteComposedFrameResult>;
 
-export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type 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, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };
+export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, captureVisualLayers, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, createVisualLayerController, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };