@viji-dev/core/dist/index.d.ts

Universal execution engine for Viji Creative scenes

export declare interface AnalysisConfiguration {
    fftSize?: number;
    smoothing?: number;
    frequencyBands?: FrequencyBand[];
    beatDetection?: boolean;
    onsetDetection?: boolean;
}

export declare interface AudioAPI {
    isConnected: boolean;
    volume: {
        rms: number;
        peak: number;
    };
    beat?: {
        isKick: boolean;
        confidence: number;
    };
    bands: Record<string, number>;
    getFrequencyData: () => Uint8Array;
}

export declare interface CaptureFrameOptions {
    /** MIME type for output, e.g., 'image/png', 'image/jpeg', 'image/webp' */
    type?: string;
    /**
     * Target resolution.
     * - number: scale factor relative to current canvas size (e.g., 0.5 = 50%)
     * - { width, height }: exact output size; if aspect ratio differs from canvas,
     *   the source is center-cropped to match the target aspect ratio before scaling
     */
    resolution?: number | {
        width: number;
        height: number;
    };
}

declare interface ColorConfig {
    label: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
}

declare interface ColorParameter {
    value: string;
    label: string;
    description?: string;
    group: string;
    category: ParameterCategory;
}

declare interface CoreCapabilities {
    /** Audio input is active and connected */
    hasAudio: boolean;
    /** Video input is active and connected */
    hasVideo: boolean;
    /** User interactions (mouse, touch, keyboard) are enabled */
    hasInteraction: boolean;
    /** General parameters are always available */
    hasGeneral: boolean;
}

export declare interface FaceData {
    bounds: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    confidence: number;
    landmarks: {
        x: number;
        y: number;
    }[];
    expressions: Record<string, number>;
}

declare interface FrameRateInfo {
    mode: FrameRateMode;
    screenRefreshRate: number;
    effectiveRefreshRate: number;
}

declare type FrameRateMode = 'full' | 'half';

export declare interface FrequencyBand {
    name: string;
    min: number;
    max: number;
}

export declare interface HandData {
    palm: {
        x: number;
        y: number;
    };
    fingers: {
        x: number;
        y: number;
    }[];
    gestures: Record<string, boolean>;
}

export declare interface KeyboardAPI {
    isPressed(key: string): boolean;
    wasPressed(key: string): boolean;
    wasReleased(key: string): boolean;
    activeKeys: Set<string>;
    pressedThisFrame: Set<string>;
    releasedThisFrame: Set<string>;
    lastKeyPressed: string;
    lastKeyReleased: string;
    shift: boolean;
    ctrl: boolean;
    alt: boolean;
    meta: boolean;
}

export declare interface MouseAPI {
    x: number;
    y: number;
    isInCanvas: boolean;
    isPressed: boolean;
    leftButton: boolean;
    rightButton: boolean;
    middleButton: boolean;
    velocity: {
        x: number;
        y: number;
    };
    deltaX: number;
    deltaY: number;
    wheelDelta: number;
    wheelX: number;
    wheelY: number;
    wasPressed: boolean;
    wasReleased: boolean;
    wasMoved: boolean;
}

declare interface NumberConfig {
    min?: number;
    max?: number;
    step?: number;
    label: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
}

declare interface NumberParameter {
    value: number;
    min: number;
    max: number;
    step: number;
    label: string;
    description?: string;
    group: string;
    category: ParameterCategory;
}

export declare interface ParameterAPI {
    define(groups: ParameterGroup[]): void;
    [key: string]: any;
}

declare type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';

export declare interface ParameterConfig {
    min?: number;
    max?: number;
    step?: number;
    options?: string[] | number[];
    maxLength?: number;
    label?: string;
    description?: string;
    hidden?: boolean;
    precision?: number;
}

export declare interface ParameterDefinition {
    type: 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number';
    defaultValue: any;
    label?: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
    config?: ParameterConfig;
    validate?: (value: any) => boolean;
}

export declare interface ParameterGroup {
    groupName: string;
    category?: ParameterCategory;
    description?: string;
    collapsed?: boolean;
    order?: number;
    parameters: Record<string, ParameterDefinition>;
}

declare type ParameterValue = string | number | boolean;

export declare interface PerformanceStats {
    frameTime: number;
    resolution: Resolution;
    scale: number;
    frameRate: FrameRateInfo;
    memoryUsage?: number;
    activeStreams?: number;
    parameterCount?: number;
}

export declare type Resolution = {
    width: number;
    height: number;
};

declare interface SelectConfig {
    options: string[] | number[];
    label: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
}

declare interface SelectParameter {
    value: string | number;
    options: string[] | number[];
    label: string;
    description?: string;
    group: string;
    category: ParameterCategory;
}

declare interface SliderConfig {
    min?: number;
    max?: number;
    step?: number;
    label: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
}

declare interface SliderParameter {
    value: number;
    min: number;
    max: number;
    step: number;
    label: string;
    description?: string;
    group: string;
    category: ParameterCategory;
}

declare interface TextConfig {
    label: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
    maxLength?: number;
}

declare interface TextParameter {
    value: string;
    maxLength?: number;
    label: string;
    description?: string;
    group: string;
    category: ParameterCategory;
}

declare interface ToggleConfig {
    label: string;
    description?: string;
    group?: string;
    category?: ParameterCategory;
}

declare interface ToggleParameter {
    value: boolean;
    label: string;
    description?: string;
    group: string;
    category: ParameterCategory;
}

export declare interface TouchAPI {
    points: TouchPoint[];
    count: number;
    started: TouchPoint[];
    moved: TouchPoint[];
    ended: TouchPoint[];
    primary: TouchPoint | null;
    gestures: TouchGestureAPI;
}

declare interface TouchGestureAPI {
    isPinching: boolean;
    isRotating: boolean;
    isPanning: boolean;
    isTapping: boolean;
    pinchScale: number;
    pinchDelta: number;
    rotationAngle: number;
    rotationDelta: number;
    panDelta: {
        x: number;
        y: number;
    };
    tapCount: number;
    lastTapTime: number;
    tapPosition: {
        x: number;
        y: number;
    } | null;
}

declare interface TouchPoint {
    id: number;
    x: number;
    y: number;
    pressure: number;
    radius: number;
    radiusX: number;
    radiusY: number;
    rotationAngle: number;
    force: number;
    deltaX: number;
    deltaY: number;
    velocity: {
        x: number;
        y: number;
    };
    isNew: boolean;
    isActive: boolean;
    isEnding: boolean;
}

export declare const VERSION = "0.2.2";

export declare interface VideoAPI {
    isConnected: boolean;
    currentFrame: OffscreenCanvas | null;
    frameWidth: number;
    frameHeight: number;
    frameRate: number;
    getFrameData: () => ImageData | null;
    faces: FaceData[];
    hands: HandData[];
}

export declare interface VijiAPI {
    canvas: OffscreenCanvas;
    ctx?: OffscreenCanvasRenderingContext2D;
    gl?: WebGL2RenderingContext;
    width: number;
    height: number;
    pixelRatio: number;
    time: number;
    deltaTime: number;
    frameCount: number;
    fps: number;
    audio: AudioAPI;
    video: VideoAPI;
    mouse: MouseAPI;
    keyboard: KeyboardAPI;
    touches: TouchAPI[];
    slider: (defaultValue: number, config: SliderConfig) => SliderParameter;
    color: (defaultValue: string, config: ColorConfig) => ColorParameter;
    toggle: (defaultValue: boolean, config: ToggleConfig) => ToggleParameter;
    select: (defaultValue: string | number, config: SelectConfig) => SelectParameter;
    text: (defaultValue: string, config: TextConfig) => TextParameter;
    number: (defaultValue: number, config: NumberConfig) => NumberParameter;
    useContext(type: '2d' | 'webgl'): OffscreenCanvasRenderingContext2D | WebGLRenderingContext | WebGL2RenderingContext | null;
}

/**
 * Main VijiCore class - Universal execution engine for creative scenes.
 *
 * Orchestrates secure IFrame + WebWorker execution with controlled communication.
 * Provides the foundation for scene execution across platform and SDK contexts.
 */
export declare class VijiCore {
    private iframeManager;
    private workerManager;
    private interactionManager;
    private audioSystem;
    private videoCoordinator;
    private isInitialized;
    private isDestroyed;
    private isInitializing;
    private instanceId;
    private screenRefreshRate;
    private debugMode;
    /**
     * Debug logging helper
     */
    private debugLog;
    private config;
    private currentAudioStream;
    private currentVideoStream;
    private currentInteractionEnabled;
    private parameterGroups;
    private parameterValues;
    private parametersInitialized;
    private parameterListeners;
    private parameterDefinedListeners;
    private parameterErrorListeners;
    private capabilitiesChangeListeners;
    private stats;
    constructor(config: VijiCoreConfig);
    /**
     * Capture current scene frame as an image Blob.
     * Resolution can be a scale (0-1+) or explicit width/height with center-crop.
     */
    captureFrame(options?: CaptureFrameOptions): Promise<Blob>;
    /**
     * Enable or disable debug logging
     */
    setDebugMode(enabled: boolean): void;
    /**
     * Get current debug mode status
     */
    getDebugMode(): boolean;
    /**
     * Initializes the core components in sequence
     */
    initialize(): Promise<void>;
    /**
     * Creates canvas with retry logic to handle timing issues
     */
    private createCanvasWithRetry;
    /**
     * Sets up the interaction system for Phase 7
     */
    private setupInteractionSystem;
    /**
     * Sets up communication between components
     */
    private setupCommunication;
    /**
     * Handle parameter definitions received from worker
     */
    private handleParametersDefined;
    /**
     * Handle parameter validation errors
     */
    private handleParameterError;
    /**
     * Set a single parameter value
     */
    setParameter(name: string, value: ParameterValue): Promise<void>;
    /**
     * Set multiple parameter values efficiently
     */
    setParameters(values: Record<string, ParameterValue>): Promise<void>;
    /**
     * Get current parameter value
     */
    getParameter(name: string): ParameterValue | undefined;
    /**
     * Get all current parameter values
     */
    getParameterValues(): Record<string, ParameterValue>;
    /**
     * Get parameter groups (for UI generation)
     */
    getParameterGroups(): ParameterGroup[];
    /**
     * Get current core capabilities (what's currently active)
     */
    getCapabilities(): CoreCapabilities;
    /**
     * Get parameter groups filtered by active capabilities
     */
    getVisibleParameterGroups(): ParameterGroup[];
    /**
     * Check if a specific parameter category is currently active
     */
    isCategoryActive(category: ParameterCategory): boolean;
    /**
     * Check if parameters have been initialized
     */
    get parametersReady(): boolean;
    /**
     * Send all current parameter values to worker (used for initial sync)
     */
    private syncAllParametersToWorker;
    /**
     * Add listener for when parameters are defined
     */
    onParametersDefined(listener: (groups: ParameterGroup[]) => void): void;
    /**
     * Remove parameter defined listener
     */
    offParametersDefined(listener: (groups: ParameterGroup[]) => void): void;
    /**
     * Add listener for parameter value changes
     */
    onParameterChange(parameterName: string, listener: (value: ParameterValue) => void): void;
    /**
     * Remove parameter change listener
     */
    offParameterChange(parameterName: string, listener: (value: ParameterValue) => void): void;
    /**
     * Add listener for parameter errors
     */
    onParameterError(listener: (error: {
        message: string;
        code: string;
    }) => void): void;
    /**
     * Add listener for when core capabilities change (audio/video/interaction state)
     */
    onCapabilitiesChange(listener: (capabilities: CoreCapabilities) => void): void;
    /**
     * Remove capabilities change listener
     */
    removeCapabilitiesListener(listener: (capabilities: CoreCapabilities) => void): void;
    /**
     * Notify capability change listeners
     */
    private notifyCapabilitiesChange;
    /**
     * Remove parameter error listener
     */
    offParameterError(listener: (error: {
        message: string;
        code: string;
    }) => void): void;
    /**
     * Notify parameter change listeners
     */
    private notifyParameterListeners;
    /**
     * Sets the frame rate to full speed (every animation frame)
     */
    setFullFrameRate(): Promise<void>;
    /**
     * Sets the frame rate to half speed (every second animation frame)
     */
    setHalfFrameRate(): Promise<void>;
    /**
     * Updates the canvas resolution by sending effective dimensions to the worker
     */
    updateResolution(): void;
    /**
     * Sets the audio stream for analysis
     */
    setAudioStream(audioStream: MediaStream | null): Promise<void>;
    /**
     * Sets the video stream for processing
     */
    setVideoStream(videoStream: MediaStream | null): Promise<void>;
    /**
     * Gets the current audio stream
     */
    getAudioStream(): MediaStream | null;
    /**
     * Gets the current video stream
     */
    getVideoStream(): MediaStream | null;
    /**
     * Enables or disables user interactions (mouse, keyboard, touch) at runtime
     */
    setInteractionEnabled(enabled: boolean): Promise<void>;
    /**
     * Gets the current interaction enabled state
     */
    getInteractionEnabled(): boolean;
    /**
     * Updates audio analysis configuration
     */
    setAudioAnalysisConfig(config: {
        fftSize?: number;
        smoothing?: number;
    }): Promise<void>;
    /**
     * Updates the canvas resolution by scale
     */
    setResolution(scale: number): void;
    /**
     * Detects the screen refresh rate
     */
    private detectScreenRefreshRate;
    /**
     * Updates frame rate statistics
     */
    private updateFrameRateStats;
    /**
     * Gets current performance statistics
     */
    getStats(): PerformanceStats;
    /**
     * Checks if the core is ready for use
     */
    get ready(): boolean;
    /**
     * Gets the current configuration
     */
    get configuration(): Readonly<VijiCoreConfig>;
    /**
     * Destroys the core instance and cleans up all resources
     */
    destroy(): Promise<void>;
    /**
     * Validates that the core is ready for operations
     */
    private validateReady;
    /**
     * Validates the provided configuration
     */
    private validateConfig;
    /**
     * Cleans up all resources
     */
    private cleanup;
}

export declare interface VijiCoreConfig {
    /** Container element where the scene will be rendered */
    hostContainer: HTMLElement;
    /** Artist scene code to execute */
    sceneCode: string;
    /** Frame rate mode - 'full' for every animation frame, 'half' for every second frame */
    frameRateMode?: FrameRateMode;
    /** Enable automatic performance optimization */
    autoOptimize?: boolean;
    /** Audio input stream */
    audioStream?: MediaStream;
    /** Video input stream */
    videoStream?: MediaStream;
    /** Audio analysis configuration */
    analysisConfig?: AnalysisConfiguration;
    /** Initial parameter values */
    parameters?: ParameterGroup[];
    /** Disable input processing (for preview instances) */
    noInputs?: boolean;
    /** Enable user interaction events */
    allowUserInteraction?: boolean;
}

export declare class VijiCoreError extends Error {
    code: string;
    context?: any | undefined;
    constructor(message: string, code: string, context?: any | undefined);
}

export { }