@cyberart-io/engine 0.0.5 → 0.0.6

package/README.md

@@ -94,11 +94,15 @@ Full API for the event router, deterministic replay, and CI harness (so agents c
 - [Asset resolver](docs/asset-resolver.md) — host-pluggable images/audio/fonts/spritesheets, cache, preload, fallbacks
 - [Presentation cue](docs/presentation-cue.md) — deterministic `createPresentationTimeline`, duplicate policy, reduced-motion, lifecycle events
 - [Capability manifest](docs/capability-manifest.md) — versioned JSON for runtime features, phases, managers, assets, events, permissions, integrations
+- [Executable modules](docs/executable-modules.md) — trusted versioned factories, host allowlists, isolation, per-module failures
 - [Normalized geometry](docs/normalized-geometry.md) — coordinate spaces, contain/cover/crop layout, landmarks, hit regions, debug overlay
 - [Runtime group](docs/runtime-group.md) — `createRuntimeGroup`, shared router attach, lockstep clock; `createHeadlessMultiCartHarness` from `@cyberart-io/engine/headless`
 - [Compositor](docs/compositor.md) — `createCompositor`, transparent stacking, `screen` blend, `writeComposedFrame`
 - [Browser harness](docs/browser-harness.md) — `createBrowserHarness`, DOM clicks, viewport/DPR, composed screenshots
 - [Replay inspector](docs/replay-inspector.md) — `createReplayInspector`, causation trees, redacted export/import, headless replay
+- [MIDI](docs/midi.md) — host-owned `MidiManager`, note/CC/pitch in and out, `inject` / fake port, structured `requestAccess`
+- [Snapshots](docs/snapshots.md) — versioned envelope, `defineSnapshot` / `applySnapshotMigrations`, host-owned `hostState`
+- [Audio](docs/audio.md) — `createAudioBroker`, `createAudioCueTimeline`, headless cue traces (PCM is not deterministic)
 
 ## Write a cart
 
@@ -153,6 +157,8 @@ const cart = runtime.mount(artProject, {
 | `audio` | none | Libraries to unlock if `unlockAudio()` runs before `mount`. After mount, the cart’s `metadata.audio` wins. |
 | `deterministic` | off | Host-controlled clock, `step`/`advance`, and scripted input/assets. Leave unset for live kaleidoscope / Art Blocks. |
 | `assets` | off | Host `AssetResolver` plus engine cache/preload. Carts keep logical refs. Leave unset when the piece has no media. |
+| `audioBroker` | off | Shared `createAudioBroker` instance. Optional. Omit when the cart only uses `metadata.audio: 'tone'`. |
+| `audioParticipantId` | none | Group participant id to authorize / teardown on this runtime. |
 
 `CartHandle` (what `mount` returns):
 
@@ -165,8 +171,10 @@ const cart = runtime.mount(artProject, {
 | `step(frames)` / `advance(ms)` | Deterministic ticks only. Throw if `deterministic` was not set. |
 | `schedule(action)` | Queue a pointer/key/host-event/asset for a future frame. |
 | `getClock()` / `getRandomState()` / `getReplayMetadata()` | Replay inspection. |
-| `exportState()` / `exportStateJSON()` | Pause-safe serializable bundle. |
-| `importState(bundle)` | Restore a bundle (or JSON string). |
+| `exportState()` / `exportStateJSON()` | Pause-safe serializable `CartStateBundle` (schema 1 blob). |
+| `importState(bundle)` | Restore a bundle, JSON string, or snapshot envelope (migrates then loads `engineState`). |
+| `exportSnapshot()` / `exportSnapshotJSON()` | Schema 2 envelope wrapping the bundle plus clock, rng, optional `hostState`. |
+| `importSnapshot(envelope)` | Migrate to the current schema and restore `engineState`. Hosts reapply `hostState`. |
 | `destroy()` | Unload this cart. Idempotent. |
 | `needsAudio` | True when the cart declared audio libraries. Use this to show a click overlay. |
 | `paused` / `isPrepared` / `isLoopRunning` | Loop flags. |
@@ -199,6 +207,14 @@ Install the peer: `npm i tone@^14.8.15`. Call `cart.start()` **inside a click or
 
 If a click can happen before `mount` finishes, pass the same `audio` into `createRuntime` and/or call `runtime.unlockAudio()` from that click. After mount, the cart’s metadata wins.
 
+Several carts on one page should share **one** `createAudioBroker` (pass it to `createRuntime` / `createRuntimeGroup`). One `unlock()` covers authorized participants. Channel gain, mute, duck, and priority live on the broker; cue timing is `createAudioCueTimeline` / `scheduleAudioCue` (presentation-frame clock). Headless CI records cue events with `createHeadlessAudioAdapter` from `@cyberart-io/engine/headless` — the event trace is deterministic, PCM is not. Full API: [audio](docs/audio.md).
+
+## MIDI
+
+Host-owned `MidiManager` — carts and hosts construct it. The runtime does not pass it into `getDefaultState`. Subscribe to note / CC / pitch, `inject` for tests without hardware, and `send` note-on/off, CC, or raw bytes through an injectable port. `requestAccess()` wraps `navigator.requestMIDIAccess` when present; a missing API or denied permission is a structured result, so silent carts keep running. Headless/jsdom has no Web MIDI; inject and send still work via a test port.
+
+Full API and the reproduce command: [MIDI](docs/midi.md). Capability manifests already list `midi` as an integration.
+
 ## Seed
 
 Pass `seed` when you want a deterministic output (for example from `?hash=`):
@@ -358,6 +374,40 @@ validateCapabilityManifest(defined.manifest, {
 
 Fields, host allowlists, and diagnostic codes: [capability manifest](docs/capability-manifest.md).
 
+## Executable modules
+
+Trusted factories keyed by exact `id` + `version`. The host allowlists which refs may load. There is no `eval` / `new Function` path for cart-supplied strings.
+
+```ts
+import { createExecutableModuleHost } from '@cyberart-io/engine';
+
+const host = createExecutableModuleHost({
+  allowlist: [
+    { id: 'overlay-fx', version: '1.0.0' },
+    { id: 'host.module', version: '1.0.0' },
+  ],
+  limits: { maxInvokeMs: 16, maxInvokesPerTurn: 4 },
+  modules: [
+    {
+      id: 'overlay-fx',
+      version: '1.0.0',
+      create: (capabilities) => ({
+        invoke: (input, { signal }) => {
+          if (signal.aborted) return;
+          return { input, seed: capabilities.seed };
+        },
+      }),
+    },
+  ],
+});
+
+const allowed = await host.invoke({ id: 'overlay-fx', version: '1.0.0' });
+await host.invoke({ id: 'overlay-fx', version: '2.0.0' }); // version-mismatch, not invoked
+host.destroy();
+```
+
+Unknown ids, wrong versions, and refs missing from the allowlist fail closed. A throwing module returns `{ ok: false, error }` and the next allowlisted invoke still runs. Isolation is in-process (trusted factories), not a worker or iframe. Carts may declare required refs as optional `modules.refs` on a [capability manifest](docs/capability-manifest.md). Full API and the reproduce command: [executable modules](docs/executable-modules.md).
+
 ## Runtime group
 
 Several production carts, one router, one lockstep clock. Use this instead of intercepting each `onEvent` and republishing by hand.
@@ -476,14 +526,22 @@ The same declarations produce fixture URLs locally and CDN URLs (plus a typed CO
 
 ## Save and load
 
-Live `state` is not JSON-safe (audio nodes, managers, typed arrays, possible cycles). `snapshot()` is PNG + seed. Use export/import when you want the simulation itself:
+Live `state` is not JSON-safe (audio nodes, managers, typed arrays, possible cycles). `snapshot()` is PNG + seed. Use export/import when you want the simulation itself.
+
+`exportState` still returns the engine-owned `CartStateBundle` (`CART_STATE_BUNDLE_VERSION = 1`) so existing carts keep working. The versioned envelope (`SNAPSHOT_SCHEMA_VERSION = 2`) wraps that blob in `engineState` and keeps host-owned JSON in `hostState` (or a `hostStateRef`). Hosts persist the envelope; Cyberart is not the database. Full field list, migration registry, and diagnostic codes: [versioned snapshots](docs/snapshots.md).
 
 ```ts
 const bundle = await cart.exportState();
 const json = await cart.exportStateJSON();
+const envelope = await cart.exportSnapshot({
+  cartVersion: '3',
+  hostState: { sceneId: 'alpha' },
+});
 
 await cart.importState(bundle);
 await cart.importState(json);
+await cart.importState(envelope);
+await cart.importSnapshot(envelope);
 ```
 
 Both pause, wait until any in-flight `update` finishes, then restore the previous pause flag. Import tears down, runs `getDefaultState` again (fresh managers, empty audio graph), overlays the save onto that scaffold unless `getDefaultState` already returned the revived `customState`, and restores `framesElapsed`. Works on a prepared cart before `start()`. Throws if nothing is prepared, or if the bundle is incompatible (`IncompatibleCartStateError`).
@@ -547,7 +605,7 @@ A canvas the host adopted is left in place on destroy; a canvas the engine creat
 
 ## Publishing this package (maintainers)
 
-Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (including compositor, browser harness, and replay inspector), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
+Not part of writing a cart. Engine source lives in `packages/engine/src/` (not mixed into the site). The npm tarball is built from `packages/engine/src/index.ts` and `packages/engine/src/headless.ts` and contains minified `dist/index.js` + `dist/headless.js`, rolled-up `.d.ts` for both, `LICENSE`, `README.md`, `docs/` (including compositor, browser harness, replay inspector, MIDI, executable modules, snapshots, and audio), and `package.json`. Site code that still imports `src/ui/lib/...` hits thin re-export shims so those paths keep working.
 
 ```bash
 pnpm run pack:engine

package/dist/headless.d.ts

@@ -328,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
@@ -475,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
@@ -519,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. */
@@ -549,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;
@@ -590,6 +745,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;
 };
 
@@ -726,6 +883,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 +920,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;
@@ -1213,6 +1373,127 @@ 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;
+};
+
+/**
+ * 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
@@ -1232,4 +1513,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 WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };