@viji-dev/core 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,568 @@
+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;
+}
+
+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 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 SelectParameter {
+    value: string | number;
+    options: string[] | 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 TextParameter {
+    value: string;
+    maxLength?: number;
+    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.1.0-alpha.1";
+
+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: SliderParameter) => SliderParameter;
+    color: (defaultValue: string, config: ColorParameter) => ColorParameter;
+    toggle: (defaultValue: boolean, config: ToggleParameter) => ToggleParameter;
+    select: (defaultValue: string | number, config: SelectParameter) => SelectParameter;
+    text: (defaultValue: string, config: TextParameter) => TextParameter;
+    number: (defaultValue: number, config: NumberParameter) => NumberParameter;
+    useContext(type: '2d' | 'webgl'): OffscreenCanvasRenderingContext2D | WebGL2RenderingContext;
+}
+
+/**
+ * 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 parameterGroups;
+    private parameterValues;
+    private parametersInitialized;
+    private parameterListeners;
+    private parameterDefinedListeners;
+    private parameterErrorListeners;
+    private capabilitiesChangeListeners;
+    private stats;
+    constructor(config: VijiCoreConfig);
+    /**
+     * 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;
+    /**
+     * 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 { }