@cyberart-io/engine 0.0.2 → 0.0.3

package/dist/headless.d.ts

@@ -0,0 +1,637 @@
+/*!
+ * @cyberart-io/engine
+ * Copyright (c) 2026 Aaron Boyarsky
+ * Licensed under the CyberArt Engine License. See LICENSE.
+ * Not an OSI open-source license.
+ */
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Audio libraries the animation manager knows how to load and unlock.
+ * Carts declare which they need via `metadata.audio`; the manager looks them
+ * up here. Add a new adapter when a second library is supported.
+ */
+type AudioLibraryId = 'tone';
+type AudioLibrarySpec = AudioLibraryId | AudioLibraryId[];
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ */
+type ExternalAssetDependency = {
+    cid: string;
+    [k: string]: unknown;
+};
+type TokenData = {
+    hash: string;
+    tokenId: string;
+    externalAssetDependencies?: ExternalAssetDependency[];
+    /**
+     * Per AB Engine Flex generator spec: gateway URL the script is supposed to
+     * combine with each `externalAssetDependencies[i].cid` of type `"IPFS"`.
+     * AB defaults this to `https://ipfs.artblocks.io/ipfs/` and lets partners
+     * override per-contract via support. Optional because standard (non-Flex)
+     * projects don't get it.
+     */
+    preferredIPFSGateway?: string;
+    /** Same idea for Arweave-typed external assets. We don't currently use it. */
+    preferredArweaveGateway?: string;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ */
+
+type Sfc32Regs = {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+};
+/** Snapshot of the dual sfc32 generators after warmup (or after `setState`). */
+type RandomState = {
+    seed: string;
+    useA: boolean;
+    prngA: Sfc32Regs;
+    prngB: Sfc32Regs;
+};
+declare class Random {
+    readonly seed: string;
+    private useA;
+    private prngA;
+    private prngB;
+    private genA;
+    private genB;
+    constructor(tokenData: TokenData);
+    getState(): RandomState;
+    setState(state: RandomState): void;
+    r_zero_one(): number;
+    dec(min?: number, max?: number): number;
+    int(min: number, max?: number): number;
+    bool(p?: number): boolean;
+    sign(): 1 | -1;
+    choose<T = unknown>(list: T[]): T;
+}
+
+type DimensionContext = {
+    width: number;
+    height: number;
+    iWidth: number;
+    iHeight: number;
+    smallDim: number;
+    largeDim: number;
+    area: number;
+    aspectRatio: number;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ */
+type KeypressHandler = () => void;
+/**
+ * Handler for keyboard inputs.
+ */
+declare class KeyboardManager {
+    private actionMap;
+    private debugMode;
+    private listening;
+    constructor(debugMode?: boolean, captureKeyboard?: boolean);
+    /**
+     * When a key is pressed, check if there's a corresponding action, and execute it.
+     * @param e
+     */
+    checkKeypress({ key }: KeyboardEvent): void;
+    /**
+     * Inject a key without a DOM event. Deterministic hosts call this at a
+     * chosen frame instead of listening on `window`.
+     */
+    inject(key: string): void;
+    /**
+     * Register a certain action to be performed when a given key is pressed.
+     * @param key
+     * @param action
+     * @param overwrite
+     */
+    registerAction(key: string, action: KeypressHandler, overwrite?: boolean): void;
+    /**
+     * Remove the global keydown listener and clear registered actions. Call this
+     * when the owning animation is torn down so listeners don't accumulate across
+     * cart reloads (e.g. on window resize).
+     */
+    destroy(): void;
+}
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ */
+type PointerClick = {
+    x: number;
+    y: number;
+};
+type PointerManagerOptions = {
+    /**
+     * When false, do not attach canvas pointer listeners. Deterministic mode
+     * injects coordinates instead of reading the live pointer.
+     */
+    listen?: boolean;
+};
+declare class PointerManager {
+    x: number;
+    y: number;
+    isDown: boolean;
+    private clicks;
+    private canvas;
+    private listening;
+    constructor(canvas: HTMLCanvasElement, options?: PointerManagerOptions);
+    private toCanvasCoords;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    hasClick(): boolean;
+    consumeClick(): PointerClick | null;
+    /**
+     * Inject a pointer sample in canvas pixel space. Deterministic hosts call
+     * this at a chosen frame instead of waiting on DOM pointer events.
+     */
+    inject(kind: 'down' | 'move' | 'up', x: number, y: number): void;
+    destroy(): void;
+}
+
+type EventKind = 'intent' | 'state' | 'diagnostic';
+type EventInput = {
+    type: string;
+    payload?: unknown;
+    schemaVersion?: number;
+    kind?: EventKind;
+    source?: string;
+    target?: string;
+    id?: string;
+    correlationId?: string;
+    causationId?: string;
+    seq?: number;
+    hops?: number;
+    idempotencyKey?: string;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host ↔ cart mailbox. Inbound events are queued by the host via `dispatch`
+ * and drained by cart code that opts in via `consume()`. Outbound events are
+ * `emit`ted by the cart and forwarded to host `onEvent` listeners.
+ *
+ * Carts that never mention this object behave as they do today.
+ *
+ * Routed traffic is a full EventEnvelope; thin `{ type, payload }` remains
+ * valid on an unattached mailbox. Extra envelope fields are optional here.
+ */
+
+type HostEvent = EventInput;
+type HostEventListener = (event: HostEvent) => void;
+declare class HostChannel {
+    private inbound;
+    private listeners;
+    private closed;
+    dispatch(event: HostEvent): void;
+    consume(): HostEvent[];
+    emit(event: HostEvent): void;
+    onEvent(listener: HostEventListener): () => void;
+    /** Drop queued inbound events. Does not remove `onEvent` listeners. */
+    clearInbound(): void;
+    /** Drop inbound events and listeners. Runtime teardown; not cart unload. */
+    clear(): void;
+    /** Permanent close. Further dispatch / emit / consume / onEvent throw. */
+    close(): void;
+    private requireOpen;
+}
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ */
+
+type AnimationTiming = {
+    now: number;
+    startTime: number;
+    elapsedSinceStart: number;
+    deltaSinceLastUpdate: number;
+    deltaSinceLastRender: number;
+};
+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;
+    adjust?: Record<string, {
+        type: 'switch';
+        immediate?: boolean;
+        label: string;
+        description: string;
+    } | {
+        type: 'slider';
+        immediate?: boolean;
+        description: string;
+        min: number;
+        max: number;
+        step: number;
+        label: string;
+        mapToOutput: (value: number) => number;
+        mapToInput: (value: number) => number;
+    }>;
+    /**
+     * Optional cleanup hook invoked when the cart is unloaded (e.g. on window
+     * resize, which fully rebuilds the animation). Carts that allocate long-lived
+     * resources such as Tone.js audio nodes should dispose them here to avoid
+     * leaks accumulating across reloads.
+     */
+    teardown?: (state: T, featureState?: Readonly<TFeatureState>) => void;
+    metadata?: {
+        id: string;
+        name: string;
+        description?: string;
+        frameRate: number;
+        /**
+         * Optional per-visualMode display FPS overrides (e.g. mycelium at 60
+         * while the cart baseline stays lower). Keys match cart `visualMode`.
+         */
+        frameRateByVisualMode?: Partial<Record<string, number>>;
+        /**
+         * Audio libraries this cart needs (currently `'tone'`). The animation
+         * manager loads and unlocks them; omit or leave unset for a silent cart.
+         */
+        audio?: AudioLibrarySpec;
+        /**
+         * When true, outputs are a function of the token hash. Saved state may
+         * only be loaded back onto the same hash.
+         */
+        generative?: boolean;
+    };
+};
+
+type CartStateDimensions = {
+    /** Canvas buffer pixels (device pixels). */
+    width: number;
+    height: number;
+    /** CSS layout size of the window/container at save. */
+    cssWidth?: number;
+    cssHeight?: number;
+    dpr?: number;
+};
+type CartStateBundle = {
+    version: number;
+    cartId?: string;
+    /** True when the cart is hash-seeded; load requires the same seed. */
+    generative?: boolean;
+    seed: string;
+    framesElapsed: number;
+    /** Pause-aware animation clock; restored so time-based visuals match the save. */
+    elapsedSinceStart?: number;
+    /** Output size the simulation was running at. Load pins the canvas to this. */
+    dimensions?: CartStateDimensions;
+    state: unknown;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host-controlled time, input, and asset completion for deterministic replays.
+ * Production kaleidoscope / Art Blocks playback does not enable this mode.
+ * Logical asset URLs are resolved by the host preloader (`assetResolver.ts`);
+ * this module only times `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` delivery.
+ */
+
+type PointerKind = 'down' | 'move' | 'up';
+type ScriptedAction = {
+    atFrame: number;
+} & ({
+    type: 'pointer';
+    pointer: {
+        kind: PointerKind;
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'event';
+    event: HostEvent;
+} | {
+    type: 'asset';
+    id: string;
+    status: 'ready' | 'failed';
+    /** Optional structured failure or resolved resource. Envelope is unchanged. */
+    detail?: unknown;
+});
+type DeterministicRuntimeOptions = {
+    /** Virtual clock origin in ms. Default 0. */
+    origin?: number;
+    /** Actions applied at the start of `atFrame`, before `update`. */
+    actions?: ScriptedAction[];
+};
+type ClockSnapshot = {
+    now: number;
+    framesElapsed: number;
+    frameRate: number;
+};
+type ReplayMetadata = {
+    seed: string;
+    clock: ClockSnapshot;
+    rng: RandomState;
+    actions: ScriptedAction[];
+    applied: AppliedAction[];
+    events: HostEvent[];
+    state: unknown;
+};
+type AppliedAction = {
+    frame: number;
+    action: ScriptedAction;
+};
+
+declare const ASSET_KINDS: readonly ["image", "audio", "font", "spritesheet"];
+type AssetKind = (typeof ASSET_KINDS)[number];
+declare const ASSET_FAILURE_CODES: readonly ["timeout", "cors", "not-found", "invalid", "aborted", "resolver"];
+type AssetFailureCode = (typeof ASSET_FAILURE_CODES)[number];
+type AssetCorsMode = 'anonymous' | 'use-credentials' | 'omit';
+type AssetProvenance = {
+    readonly [key: string]: string | number | boolean | null | undefined;
+};
+type AssetDeclaration = {
+    /** Cache key and `ASSET_*_EVENT` payload `id`. */
+    id: string;
+    /** Logical URI: `https://…`, `moltazine:post/<id>#fragment`, `world:asset/…`, `library:…`. */
+    ref: string;
+    type: AssetKind;
+    integrity?: string;
+    provenance?: AssetProvenance;
+    /** Per-asset timeout. Ignored when wall-clock timeouts are off (deterministic). */
+    timeoutMs?: number;
+    /**
+     * `'silent'` synthesizes `SILENT_ASSET_FALLBACK_REF`. A string is another
+     * logical ref of the same type. A declaration is resolved as-is.
+     */
+    fallback?: 'silent' | string | AssetDeclaration;
+};
+type AssetResolveRequest = {
+    id: string;
+    ref: string;
+    type: AssetKind;
+    integrity?: string;
+    provenance?: AssetProvenance;
+};
+type ResolvedAsset = {
+    id: string;
+    ref: string;
+    type: AssetKind;
+    url: string;
+    integrity?: string;
+    provenance?: AssetProvenance;
+    cors?: AssetCorsMode;
+    usedFallback?: boolean;
+    /** When true, `dispose` / `forget` call `URL.revokeObjectURL`. */
+    managed?: boolean;
+};
+type AssetFailure = {
+    id: string;
+    ref: string;
+    code: AssetFailureCode;
+    message: string;
+};
+type AssetItemStatus = {
+    state: 'pending';
+} | {
+    state: 'loading';
+} | {
+    state: 'ready';
+    resource: ResolvedAsset;
+    failure?: AssetFailure;
+} | {
+    state: 'failed';
+    failure: AssetFailure;
+};
+type AssetPreloadSnapshot = {
+    total: number;
+    pending: number;
+    ready: number;
+    failed: number;
+    fallbacks: number;
+    items: Record<string, AssetItemStatus>;
+    failures: AssetFailure[];
+};
+type AssetResolver = {
+    resolve(request: AssetResolveRequest, signal?: AbortSignal): Promise<ResolvedAsset>;
+};
+type AssetRuntimeOptions = {
+    resolver: AssetResolver;
+    timeoutMs?: number;
+    emitEvents?: boolean;
+};
+type AssetPreloader = {
+    preload(declarations: readonly AssetDeclaration[]): Promise<AssetPreloadSnapshot>;
+    get(id: string): ResolvedAsset | undefined;
+    getProgress(): AssetPreloadSnapshot;
+    onProgress(listener: (snapshot: AssetPreloadSnapshot) => void): () => void;
+    abort(id?: string): void;
+    forget(id?: string): void;
+    dispose(): void;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ */
+
+type FrameErrorInfo = {
+    phase: 'update' | 'render' | 'draw';
+    consecutive: number;
+    stopped: boolean;
+};
+type CreateRuntimeOptions = {
+    /** Required mount point. The runtime creates or adopts a canvas inside this element. */
+    container: HTMLElement;
+    /**
+     * Token hash (`0x` + 64 hex) or any seed mixed into one. Instance-local;
+     * does not clobber an existing global cache. Kaleidoscope / Art Blocks
+     * pass the platform hash unchanged.
+     */
+    seed?: string | number;
+    /**
+     * When true, the cart listens for window keydown (full-page players).
+     * Defaults to false so an embed does not steal keys from the host.
+     * Ignored when `deterministic` is set — input is injected per frame.
+     */
+    captureKeyboard?: boolean;
+    /**
+     * Audio libraries to unlock if the host calls `unlockAudio()` before `mount`
+     * (click can beat idle prebuild). After mount, `cart.metadata.audio` wins.
+     */
+    audio?: AudioLibrarySpec;
+    /**
+     * Host-controlled time, input, and asset events. Production playback
+     * (kaleidoscope locally and `build:art`) leaves this unset so rAF and the
+     * token hash drive the piece as they do today.
+     */
+    deterministic?: boolean | DeterministicRuntimeOptions;
+    /**
+     * Host-pluggable asset resolver/preloader. Carts request logical refs;
+     * the host maps them to loadable URLs or blobs. Leave unset when unused.
+     * In deterministic mode, preload does not dispatch `ASSET_*` events —
+     * scripted `{ type: 'asset' }` actions own delivery timing.
+     */
+    assets?: AssetRuntimeOptions;
+};
+type MountOptions<T = unknown> = {
+    /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
+    initialState?: Partial<T>;
+    /** Outbound events emitted by cart code via `hostChannel.emit`. */
+    onEvent?: HostEventListener;
+    /** Site-only. Opaque to the published engine; pass a GameManager from the app. */
+    gameManager?: unknown;
+};
+type CartSnapshot = {
+    seed: string;
+    metadata?: AnimationCart['metadata'];
+    pngDataUrl: string;
+};
+type CartHandle = {
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    dispatch(event: HostEvent): void;
+    snapshot(): CartSnapshot;
+    destroy(): void;
+    reload(): void;
+    reinit(event?: Event): void;
+    /**
+     * Live cart state for site chrome (e.g. `/art` debug sliders). Not a public
+     * snapshot API — grids and audio nodes are not structured-cloneable.
+     */
+    getCartState(): unknown;
+    exportState(): Promise<CartStateBundle>;
+    exportStateJSON(): Promise<string>;
+    importState(bundle: CartStateBundle | string, extras?: {
+        framebuffer?: ImageData | null;
+    }): Promise<void>;
+    peekExportedFramebuffer(): ImageData | null;
+    peekSeed(): string | undefined;
+    isGenerative(): boolean;
+    /**
+     * Run `frames` ticks on the virtual clock. Requires `deterministic`.
+     * Does not use rAF; live kaleidoscope playback never calls this.
+     */
+    step(frames?: number): Promise<void>;
+    /** Run the frames that span `ms` at the cart frame rate. Requires `deterministic`. */
+    advance(ms: number): Promise<void>;
+    /** Queue a scripted input/asset/host event for a future frame. */
+    schedule(action: ScriptedAction): void;
+    getClock(): ClockSnapshot;
+    getRandomState(): RandomState;
+    getReplayMetadata(): Promise<ReplayMetadata>;
+    readonly canvas: HTMLCanvasElement | undefined;
+    paused: boolean;
+    readonly tokenData: TokenData;
+    readonly isPrepared: boolean;
+    readonly isLoopRunning: boolean;
+    readonly needsAudio: boolean;
+    readonly audioLibraries: AudioLibraryId[];
+};
+type CyberArtRuntime = {
+    mount<T>(cart: AnimationCart<T, any>, options?: MountOptions<T>): CartHandle;
+    unlockAudio(): Promise<void>;
+    destroy(): void;
+    readonly tokenData: TokenData;
+    /**
+     * This runtime's mailbox. Attach it to `createEventRouter` from the host;
+     * carts never receive the router. Survives cart remount; `destroy()` clears it.
+     */
+    readonly hostChannel: HostChannel;
+    /**
+     * Preloader for this runtime. Undefined when `assets` was omitted.
+     * Survives cart remount; `destroy()` disposes it.
+     */
+    readonly assets: AssetPreloader | 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>;
+
+export { type CreateHeadlessHarnessOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, HEADLESS_PNG_DATA_URL, type HeadlessFrameError, type HeadlessHarness, type HeadlessInspect, createHeadlessHarness, installHeadlessCanvas };