@viji-dev/core 0.2.0-alpha.3 → 0.2.0-alpha.4

package/dist/artist-dts.d.ts

@@ -0,0 +1 @@
+export declare const artistDts: string;

package/dist/artist-dts.js

@@ -0,0 +1 @@
+export const artistDts = "declare namespace VijiCore {\ndeclare interface AnalysisConfiguration {\r\n    fftSize?: number;\r\n    smoothing?: number;\r\n    frequencyBands?: FrequencyBand[];\r\n    beatDetection?: boolean;\r\n    onsetDetection?: boolean;\r\n}\r\n\r\ndeclare interface AudioAPI {\r\n    isConnected: boolean;\r\n    volume: {\r\n        rms: number;\r\n        peak: number;\r\n    };\r\n    beat?: {\r\n        isKick: boolean;\r\n        confidence: number;\r\n    };\r\n    bands: Record<string, number>;\r\n    getFrequencyData: () => Uint8Array;\r\n}\r\n\r\ndeclare interface CaptureFrameOptions {\r\n    /** MIME type for output, e.g., 'image/png', 'image/jpeg', 'image/webp' */\r\n    type?: string;\r\n    /**\r\n     * Target resolution.\r\n     * - number: scale factor relative to current canvas size (e.g., 0.5 = 50%)\r\n     * - { width, height }: exact output size; if aspect ratio differs from canvas,\r\n     *   the source is center-cropped to match the target aspect ratio before scaling\r\n     */\r\n    resolution?: number | {\r\n        width: number;\r\n        height: number;\r\n    };\r\n}\r\n\r\ndeclare interface ColorParameter {\r\n    value: string;\r\n    label: string;\r\n    description?: string;\r\n    group: string;\r\n    category: ParameterCategory;\r\n}\r\n\r\ndeclare interface CoreCapabilities {\r\n    /** Audio input is active and connected */\r\n    hasAudio: boolean;\r\n    /** Video input is active and connected */\r\n    hasVideo: boolean;\r\n    /** User interactions (mouse, touch, keyboard) are enabled */\r\n    hasInteraction: boolean;\r\n    /** General parameters are always available */\r\n    hasGeneral: boolean;\r\n}\r\n\r\ndeclare interface FaceData {\r\n    bounds: {\r\n        x: number;\r\n        y: number;\r\n        width: number;\r\n        height: number;\r\n    };\r\n    confidence: number;\r\n    landmarks: {\r\n        x: number;\r\n        y: number;\r\n    }[];\r\n    expressions: Record<string, number>;\r\n}\r\n\r\ndeclare interface FrameRateInfo {\r\n    mode: FrameRateMode;\r\n    screenRefreshRate: number;\r\n    effectiveRefreshRate: number;\r\n}\r\n\r\ndeclare type FrameRateMode = 'full' | 'half';\r\n\r\ndeclare interface FrequencyBand {\r\n    name: string;\r\n    min: number;\r\n    max: number;\r\n}\r\n\r\ndeclare interface HandData {\r\n    palm: {\r\n        x: number;\r\n        y: number;\r\n    };\r\n    fingers: {\r\n        x: number;\r\n        y: number;\r\n    }[];\r\n    gestures: Record<string, boolean>;\r\n}\r\n\r\ndeclare interface KeyboardAPI {\r\n    isPressed(key: string): boolean;\r\n    wasPressed(key: string): boolean;\r\n    wasReleased(key: string): boolean;\r\n    activeKeys: Set<string>;\r\n    pressedThisFrame: Set<string>;\r\n    releasedThisFrame: Set<string>;\r\n    lastKeyPressed: string;\r\n    lastKeyReleased: string;\r\n    shift: boolean;\r\n    ctrl: boolean;\r\n    alt: boolean;\r\n    meta: boolean;\r\n}\r\n\r\ndeclare interface MouseAPI {\r\n    x: number;\r\n    y: number;\r\n    isInCanvas: boolean;\r\n    isPressed: boolean;\r\n    leftButton: boolean;\r\n    rightButton: boolean;\r\n    middleButton: boolean;\r\n    velocity: {\r\n        x: number;\r\n        y: number;\r\n    };\r\n    deltaX: number;\r\n    deltaY: number;\r\n    wheelDelta: number;\r\n    wheelX: number;\r\n    wheelY: number;\r\n    wasPressed: boolean;\r\n    wasReleased: boolean;\r\n    wasMoved: boolean;\r\n}\r\n\r\ndeclare interface NumberParameter {\r\n    value: number;\r\n    min: number;\r\n    max: number;\r\n    step: number;\r\n    label: string;\r\n    description?: string;\r\n    group: string;\r\n    category: ParameterCategory;\r\n}\r\n\r\ndeclare interface ParameterAPI {\r\n    define(groups: ParameterGroup[]): void;\r\n    [key: string]: any;\r\n}\r\n\r\ndeclare type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';\r\n\r\ndeclare interface ParameterConfig {\r\n    min?: number;\r\n    max?: number;\r\n    step?: number;\r\n    options?: string[] | number[];\r\n    maxLength?: number;\r\n    label?: string;\r\n    description?: string;\r\n    hidden?: boolean;\r\n    precision?: number;\r\n}\r\n\r\ndeclare interface ParameterDefinition {\r\n    type: 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number';\r\n    defaultValue: any;\r\n    label?: string;\r\n    description?: string;\r\n    group?: string;\r\n    category?: ParameterCategory;\r\n    config?: ParameterConfig;\r\n    validate?: (value: any) => boolean;\r\n}\r\n\r\ndeclare interface ParameterGroup {\r\n    groupName: string;\r\n    category?: ParameterCategory;\r\n    description?: string;\r\n    collapsed?: boolean;\r\n    order?: number;\r\n    parameters: Record<string, ParameterDefinition>;\r\n}\r\n\r\ndeclare type ParameterValue = string | number | boolean;\r\n\r\ndeclare interface PerformanceStats {\r\n    frameTime: number;\r\n    resolution: Resolution;\r\n    scale: number;\r\n    frameRate: FrameRateInfo;\r\n    memoryUsage?: number;\r\n    activeStreams?: number;\r\n    parameterCount?: number;\r\n}\r\n\r\ndeclare type Resolution = {\r\n    width: number;\r\n    height: number;\r\n};\r\n\r\ndeclare interface SelectParameter {\r\n    value: string | number;\r\n    options: string[] | number[];\r\n    label: string;\r\n    description?: string;\r\n    group: string;\r\n    category: ParameterCategory;\r\n}\r\n\r\ndeclare interface SliderParameter {\r\n    value: number;\r\n    min: number;\r\n    max: number;\r\n    step: number;\r\n    label: string;\r\n    description?: string;\r\n    group: string;\r\n    category: ParameterCategory;\r\n}\r\n\r\ndeclare interface TextParameter {\r\n    value: string;\r\n    maxLength?: number;\r\n    label: string;\r\n    description?: string;\r\n    group: string;\r\n    category: ParameterCategory;\r\n}\r\n\r\ndeclare interface ToggleParameter {\r\n    value: boolean;\r\n    label: string;\r\n    description?: string;\r\n    group: string;\r\n    category: ParameterCategory;\r\n}\r\n\r\ndeclare interface TouchAPI {\r\n    points: TouchPoint[];\r\n    count: number;\r\n    started: TouchPoint[];\r\n    moved: TouchPoint[];\r\n    ended: TouchPoint[];\r\n    primary: TouchPoint | null;\r\n    gestures: TouchGestureAPI;\r\n}\r\n\r\ndeclare interface TouchGestureAPI {\r\n    isPinching: boolean;\r\n    isRotating: boolean;\r\n    isPanning: boolean;\r\n    isTapping: boolean;\r\n    pinchScale: number;\r\n    pinchDelta: number;\r\n    rotationAngle: number;\r\n    rotationDelta: number;\r\n    panDelta: {\r\n        x: number;\r\n        y: number;\r\n    };\r\n    tapCount: number;\r\n    lastTapTime: number;\r\n    tapPosition: {\r\n        x: number;\r\n        y: number;\r\n    } | null;\r\n}\r\n\r\ndeclare interface TouchPoint {\r\n    id: number;\r\n    x: number;\r\n    y: number;\r\n    pressure: number;\r\n    radius: number;\r\n    radiusX: number;\r\n    radiusY: number;\r\n    rotationAngle: number;\r\n    force: number;\r\n    deltaX: number;\r\n    deltaY: number;\r\n    velocity: {\r\n        x: number;\r\n        y: number;\r\n    };\r\n    isNew: boolean;\r\n    isActive: boolean;\r\n    isEnding: boolean;\r\n}\r\n\r\ndeclare const VERSION = \"0.1.0-alpha.1\";\r\n\r\ndeclare interface VideoAPI {\r\n    isConnected: boolean;\r\n    currentFrame: OffscreenCanvas | null;\r\n    frameWidth: number;\r\n    frameHeight: number;\r\n    frameRate: number;\r\n    getFrameData: () => ImageData | null;\r\n    faces: FaceData[];\r\n    hands: HandData[];\r\n}\r\n\r\ndeclare interface VijiAPI {\r\n    canvas: OffscreenCanvas;\r\n    ctx?: OffscreenCanvasRenderingContext2D;\r\n    gl?: WebGL2RenderingContext;\r\n    width: number;\r\n    height: number;\r\n    pixelRatio: number;\r\n    time: number;\r\n    deltaTime: number;\r\n    frameCount: number;\r\n    fps: number;\r\n    audio: AudioAPI;\r\n    video: VideoAPI;\r\n    mouse: MouseAPI;\r\n    keyboard: KeyboardAPI;\r\n    touches: TouchAPI[];\r\n    slider: (defaultValue: number, config: SliderParameter) => SliderParameter;\r\n    color: (defaultValue: string, config: ColorParameter) => ColorParameter;\r\n    toggle: (defaultValue: boolean, config: ToggleParameter) => ToggleParameter;\r\n    select: (defaultValue: string | number, config: SelectParameter) => SelectParameter;\r\n    text: (defaultValue: string, config: TextParameter) => TextParameter;\r\n    number: (defaultValue: number, config: NumberParameter) => NumberParameter;\r\n    useContext(type: '2d' | 'webgl'): OffscreenCanvasRenderingContext2D | WebGL2RenderingContext;\r\n}\r\n\r\n/**\r\n * Main VijiCore class - Universal execution engine for creative scenes.\r\n *\r\n * Orchestrates secure IFrame + WebWorker execution with controlled communication.\r\n * Provides the foundation for scene execution across platform and SDK contexts.\r\n */\r\ndeclare class VijiCore {\r\n    private iframeManager;\r\n    private workerManager;\r\n    private interactionManager;\r\n    private audioSystem;\r\n    private videoCoordinator;\r\n    private isInitialized;\r\n    private isDestroyed;\r\n    private isInitializing;\r\n    private instanceId;\r\n    private screenRefreshRate;\r\n    private debugMode;\r\n    /**\r\n     * Debug logging helper\r\n     */\r\n    private debugLog;\r\n    private config;\r\n    private currentAudioStream;\r\n    private currentVideoStream;\r\n    private currentInteractionEnabled;\r\n    private parameterGroups;\r\n    private parameterValues;\r\n    private parametersInitialized;\r\n    private parameterListeners;\r\n    private parameterDefinedListeners;\r\n    private parameterErrorListeners;\r\n    private capabilitiesChangeListeners;\r\n    private stats;\r\n    constructor(config: VijiCoreConfig);\r\n    /**\r\n     * Capture current scene frame as an image Blob.\r\n     * Resolution can be a scale (0-1+) or explicit width/height with center-crop.\r\n     */\r\n    captureFrame(options?: CaptureFrameOptions): Promise<Blob>;\r\n    /**\r\n     * Enable or disable debug logging\r\n     */\r\n    setDebugMode(enabled: boolean): void;\r\n    /**\r\n     * Get current debug mode status\r\n     */\r\n    getDebugMode(): boolean;\r\n    /**\r\n     * Initializes the core components in sequence\r\n     */\r\n    initialize(): Promise<void>;\r\n    /**\r\n     * Creates canvas with retry logic to handle timing issues\r\n     */\r\n    private createCanvasWithRetry;\r\n    /**\r\n     * Sets up the interaction system for Phase 7\r\n     */\r\n    private setupInteractionSystem;\r\n    /**\r\n     * Sets up communication between components\r\n     */\r\n    private setupCommunication;\r\n    /**\r\n     * Handle parameter definitions received from worker\r\n     */\r\n    private handleParametersDefined;\r\n    /**\r\n     * Handle parameter validation errors\r\n     */\r\n    private handleParameterError;\r\n    /**\r\n     * Set a single parameter value\r\n     */\r\n    setParameter(name: string, value: ParameterValue): Promise<void>;\r\n    /**\r\n     * Set multiple parameter values efficiently\r\n     */\r\n    setParameters(values: Record<string, ParameterValue>): Promise<void>;\r\n    /**\r\n     * Get current parameter value\r\n     */\r\n    getParameter(name: string): ParameterValue | undefined;\r\n    /**\r\n     * Get all current parameter values\r\n     */\r\n    getParameterValues(): Record<string, ParameterValue>;\r\n    /**\r\n     * Get parameter groups (for UI generation)\r\n     */\r\n    getParameterGroups(): ParameterGroup[];\r\n    /**\r\n     * Get current core capabilities (what's currently active)\r\n     */\r\n    getCapabilities(): CoreCapabilities;\r\n    /**\r\n     * Get parameter groups filtered by active capabilities\r\n     */\r\n    getVisibleParameterGroups(): ParameterGroup[];\r\n    /**\r\n     * Check if a specific parameter category is currently active\r\n     */\r\n    isCategoryActive(category: ParameterCategory): boolean;\r\n    /**\r\n     * Check if parameters have been initialized\r\n     */\r\n    get parametersReady(): boolean;\r\n    /**\r\n     * Send all current parameter values to worker (used for initial sync)\r\n     */\r\n    private syncAllParametersToWorker;\r\n    /**\r\n     * Add listener for when parameters are defined\r\n     */\r\n    onParametersDefined(listener: (groups: ParameterGroup[]) => void): void;\r\n    /**\r\n     * Remove parameter defined listener\r\n     */\r\n    offParametersDefined(listener: (groups: ParameterGroup[]) => void): void;\r\n    /**\r\n     * Add listener for parameter value changes\r\n     */\r\n    onParameterChange(parameterName: string, listener: (value: ParameterValue) => void): void;\r\n    /**\r\n     * Remove parameter change listener\r\n     */\r\n    offParameterChange(parameterName: string, listener: (value: ParameterValue) => void): void;\r\n    /**\r\n     * Add listener for parameter errors\r\n     */\r\n    onParameterError(listener: (error: {\r\n        message: string;\r\n        code: string;\r\n    }) => void): void;\r\n    /**\r\n     * Add listener for when core capabilities change (audio/video/interaction state)\r\n     */\r\n    onCapabilitiesChange(listener: (capabilities: CoreCapabilities) => void): void;\r\n    /**\r\n     * Remove capabilities change listener\r\n     */\r\n    removeCapabilitiesListener(listener: (capabilities: CoreCapabilities) => void): void;\r\n    /**\r\n     * Notify capability change listeners\r\n     */\r\n    private notifyCapabilitiesChange;\r\n    /**\r\n     * Remove parameter error listener\r\n     */\r\n    offParameterError(listener: (error: {\r\n        message: string;\r\n        code: string;\r\n    }) => void): void;\r\n    /**\r\n     * Notify parameter change listeners\r\n     */\r\n    private notifyParameterListeners;\r\n    /**\r\n     * Sets the frame rate to full speed (every animation frame)\r\n     */\r\n    setFullFrameRate(): Promise<void>;\r\n    /**\r\n     * Sets the frame rate to half speed (every second animation frame)\r\n     */\r\n    setHalfFrameRate(): Promise<void>;\r\n    /**\r\n     * Updates the canvas resolution by sending effective dimensions to the worker\r\n     */\r\n    updateResolution(): void;\r\n    /**\r\n     * Sets the audio stream for analysis\r\n     */\r\n    setAudioStream(audioStream: MediaStream | null): Promise<void>;\r\n    /**\r\n     * Sets the video stream for processing\r\n     */\r\n    setVideoStream(videoStream: MediaStream | null): Promise<void>;\r\n    /**\r\n     * Gets the current audio stream\r\n     */\r\n    getAudioStream(): MediaStream | null;\r\n    /**\r\n     * Gets the current video stream\r\n     */\r\n    getVideoStream(): MediaStream | null;\r\n    /**\r\n     * Enables or disables user interactions (mouse, keyboard, touch) at runtime\r\n     */\r\n    setInteractionEnabled(enabled: boolean): Promise<void>;\r\n    /**\r\n     * Gets the current interaction enabled state\r\n     */\r\n    getInteractionEnabled(): boolean;\r\n    /**\r\n     * Updates audio analysis configuration\r\n     */\r\n    setAudioAnalysisConfig(config: {\r\n        fftSize?: number;\r\n        smoothing?: number;\r\n    }): Promise<void>;\r\n    /**\r\n     * Updates the canvas resolution by scale\r\n     */\r\n    setResolution(scale: number): void;\r\n    /**\r\n     * Detects the screen refresh rate\r\n     */\r\n    private detectScreenRefreshRate;\r\n    /**\r\n     * Updates frame rate statistics\r\n     */\r\n    private updateFrameRateStats;\r\n    /**\r\n     * Gets current performance statistics\r\n     */\r\n    getStats(): PerformanceStats;\r\n    /**\r\n     * Checks if the core is ready for use\r\n     */\r\n    get ready(): boolean;\r\n    /**\r\n     * Gets the current configuration\r\n     */\r\n    get configuration(): Readonly<VijiCoreConfig>;\r\n    /**\r\n     * Destroys the core instance and cleans up all resources\r\n     */\r\n    destroy(): Promise<void>;\r\n    /**\r\n     * Validates that the core is ready for operations\r\n     */\r\n    private validateReady;\r\n    /**\r\n     * Validates the provided configuration\r\n     */\r\n    private validateConfig;\r\n    /**\r\n     * Cleans up all resources\r\n     */\r\n    private cleanup;\r\n}\r\n\r\ndeclare interface VijiCoreConfig {\r\n    /** Container element where the scene will be rendered */\r\n    hostContainer: HTMLElement;\r\n    /** Artist scene code to execute */\r\n    sceneCode: string;\r\n    /** Frame rate mode - 'full' for every animation frame, 'half' for every second frame */\r\n    frameRateMode?: FrameRateMode;\r\n    /** Enable automatic performance optimization */\r\n    autoOptimize?: boolean;\r\n    /** Audio input stream */\r\n    audioStream?: MediaStream;\r\n    /** Video input stream */\r\n    videoStream?: MediaStream;\r\n    /** Audio analysis configuration */\r\n    analysisConfig?: AnalysisConfiguration;\r\n    /** Initial parameter values */\r\n    parameters?: ParameterGroup[];\r\n    /** Disable input processing (for preview instances) */\r\n    noInputs?: boolean;\r\n    /** Enable user interaction events */\r\n    allowUserInteraction?: boolean;\r\n}\r\n\r\ndeclare class VijiCoreError extends Error {\r\n    code: string;\r\n    context?: any | undefined;\r\n    constructor(message: string, code: string, context?: any | undefined);\r\n}\r\n\r\n{ }\r\n\n}\n\ndeclare const viji: VijiCore.ArtistAPI;\n";

package/dist/artist-global.d.ts

@@ -0,0 +1,606 @@
+declare namespace VijiCore {
+declare interface AnalysisConfiguration {
+    fftSize?: number;
+    smoothing?: number;
+    frequencyBands?: FrequencyBand[];
+    beatDetection?: boolean;
+    onsetDetection?: boolean;
+}
+
+declare interface AudioAPI {
+    isConnected: boolean;
+    volume: {
+        rms: number;
+        peak: number;
+    };
+    beat?: {
+        isKick: boolean;
+        confidence: number;
+    };
+    bands: Record<string, number>;
+    getFrequencyData: () => Uint8Array;
+}
+
+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 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;
+}
+
+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';
+
+declare interface FrequencyBand {
+    name: string;
+    min: number;
+    max: number;
+}
+
+declare interface HandData {
+    palm: {
+        x: number;
+        y: number;
+    };
+    fingers: {
+        x: number;
+        y: number;
+    }[];
+    gestures: Record<string, boolean>;
+}
+
+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;
+}
+
+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;
+}
+
+declare interface ParameterAPI {
+    define(groups: ParameterGroup[]): void;
+    [key: string]: any;
+}
+
+declare type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';
+
+declare interface ParameterConfig {
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: string[] | number[];
+    maxLength?: number;
+    label?: string;
+    description?: string;
+    hidden?: boolean;
+    precision?: number;
+}
+
+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;
+}
+
+declare interface ParameterGroup {
+    groupName: string;
+    category?: ParameterCategory;
+    description?: string;
+    collapsed?: boolean;
+    order?: number;
+    parameters: Record<string, ParameterDefinition>;
+}
+
+declare type ParameterValue = string | number | boolean;
+
+declare interface PerformanceStats {
+    frameTime: number;
+    resolution: Resolution;
+    scale: number;
+    frameRate: FrameRateInfo;
+    memoryUsage?: number;
+    activeStreams?: number;
+    parameterCount?: number;
+}
+
+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;
+}
+
+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;
+}
+
+declare const VERSION = "0.1.0-alpha.1";
+
+declare interface VideoAPI {
+    isConnected: boolean;
+    currentFrame: OffscreenCanvas | null;
+    frameWidth: number;
+    frameHeight: number;
+    frameRate: number;
+    getFrameData: () => ImageData | null;
+    faces: FaceData[];
+    hands: HandData[];
+}
+
+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.
+ */
+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;
+}
+
+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;
+}
+
+declare class VijiCoreError extends Error {
+    code: string;
+    context?: any | undefined;
+    constructor(message: string, code: string, context?: any | undefined);
+}
+
+{ }
+
+}
+
+declare const viji: VijiCore.ArtistAPI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.4",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,13 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./artist-global": {
+      "types": "./dist/artist-global.d.ts"
+    },
+    "./artist-dts": {
+      "import": "./dist/artist-dts.js",
+      "types": "./dist/artist-dts.d.ts"
     }
   },
   "files": [
@@ -18,6 +25,7 @@
   ],
   "scripts": {
     "build": "vite build",
+    "postbuild": "node scripts/wrap-ambient.mjs",
     "dev": "vite build --watch",
     "test": "vitest",
     "test:coverage": "vitest --coverage",
@@ -40,6 +48,7 @@
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "@vitest/coverage-v8": "^1.0.0",
+    "dts-bundle-generator": "^9.5.1",
     "eslint": "^8.0.0",
     "happy-dom": "^18.0.1",
     "typescript": "^5.0.0",