npm - @viji-dev/core - Versions diffs - 0.3.21 → 0.3.23 - Mend

@viji-dev/core 0.3.21 → 0.3.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +1439 -1439
package/dist/artist-dts-p5.js +1 -1
package/dist/artist-dts.js +1 -1
package/dist/artist-global.d.ts +2 -1
package/dist/assets/cv-tasks.worker.js +878 -878
package/dist/assets/{viji.worker-bm-hvzXt.js → viji.worker-DTQvTudb.js} +82 -5
package/dist/assets/viji.worker-DTQvTudb.js.map +1 -0
package/dist/docs-api.d.ts +52 -0
package/dist/docs-api.js +1231 -0
package/dist/{essentia-wasm.web-C1URJxCY.js → essentia-wasm.web-0nilrUD3.js} +2 -2
package/dist/{essentia-wasm.web-C1URJxCY.js.map → essentia-wasm.web-0nilrUD3.js.map} +1 -1
package/dist/{index-trkn0FNW.js → index-Bu1euCdl.js} +3 -3
package/dist/index-Bu1euCdl.js.map +1 -0
package/dist/index.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/shader-uniforms.js +5 -0
package/package.json +91 -86
package/dist/assets/viji.worker-bm-hvzXt.js.map +0 -1
package/dist/index-trkn0FNW.js.map +0 -1

package/README.md CHANGED Viewed

@@ -1,1440 +1,1440 @@
-# Viji Core Package (`@viji-dev/core`)
-**Universal execution engine for Viji Creative scenes**
-A powerful, secure, and feature-rich JavaScript/TypeScript library that provides the foundation for creative scene execution across all Viji platform contexts. The core offers identical IFrame + WebWorker execution with comprehensive parameter management, audio/video analysis, user interaction handling, and performance optimization.
-## 🚀 Features
-### ✅ **Core Execution Engine**
-- **Secure IFrame + WebWorker Architecture**: Complete isolation with controlled communication
-- **Multi-Instance Support**: Concurrent instances for main scenes and previews
-- **Automatic Resource Management**: Memory leak prevention and cleanup
-### ✅ **Parameter System**
-- **Declarative Parameter Definition**: Define parameters once with automatic UI generation
-- **Proxy-Based Access**: Fast parameter access in render loops
-- **Category-Based Organization**: Audio, video, interaction, and general parameters
-- **Real-time Validation**: Type safety and range checking
-- **Capability-Aware UI**: Parameters shown based on active features
-### ✅ **Audio Analysis**
-- **Real-time Audio Processing**: Volume, frequency analysis, and beat detection
-- **Custom Frequency Bands**: Bass, mid, treble, and custom band analysis
-- **Multiple Input Sources**: Microphone, audio files, and screen capture
-- **Audio-Reactive Scenes**: Make scenes respond to audio input
-### ✅ **Video Analysis**
-- **Real-time Video Processing**: Frame analysis in separate WebWorker
-- **Multiple Input Sources**: Camera, video files, and screen capture
-- **Video-Reactive Scenes**: Make scenes respond to video motion and brightness
-- **Frame Data Access**: Raw video frame data for custom analysis
-### ✅ **User Interaction**
-- **Mouse Tracking**: Position, buttons, movement, and scroll wheel
-- **Keyboard Input**: Key states, modifiers, and event handling
-- **Touch Support**: Multi-touch with gesture detection
-- **Device Sensors**: Motion, orientation, and geolocation (internal + external devices)
-- **Canvas-Coordinate Mapping**: Accurate input positioning
-### ✅ **Performance Optimization**
-- **Configurable Frame Rates**: Full (60fps) or half (30fps) modes
-- **Resolution Scaling**: Fractional or explicit canvas dimensions
-- **Adaptive Performance**: Automatic optimization based on hardware
-- **Memory Management**: Efficient resource pooling and cleanup
-## 📦 Installation
-```bash
-npm install @viji-dev/core
-```
-## 🎯 Quick Start
-### Basic Scene Creation
-```typescript
-import { VijiCore } from '@viji-dev/core';
-// Artist scene code
-const sceneCode = `
-// Define parameters using helper functions
-const color = viji.color('#ff6b6b', {
-  label: 'Shape Color',
-  description: 'Color of the animated shape',
-  group: 'appearance'
-});
-const size = viji.slider(50, {
-  min: 10,
-  max: 150,
-  step: 5,
-  label: 'Shape Size',
-  description: 'Size of the animated shape',
-  group: 'appearance'
-});
-const speed = viji.slider(1.0, {
-  min: 0.1,
-  max: 3.0,
-  step: 0.1,
-  label: 'Animation Speed',
-  description: 'Speed of the animation',
-  group: 'animation'
-});
-// Main render function
-function render(viji) {
-  const ctx = viji.useContext('2d');
-  // Clear canvas
-  ctx.fillStyle = '#2c3e50';
-  ctx.fillRect(0, 0, viji.width, viji.height);
-  // Animated shape
-  const time = viji.time * speed.value;
-  const x = viji.width / 2 + Math.sin(time) * 100;
-  const y = viji.height / 2 + Math.cos(time) * 100;
-  ctx.fillStyle = color.value;
-  ctx.beginPath();
-  ctx.arc(x, y, size.value / 2, 0, Math.PI * 2);
-  ctx.fill();
-}
-`;
-// Create core instance
-const core = new VijiCore({
-  hostContainer: document.getElementById('scene-container'),
-  sceneCode: sceneCode,
-  frameRateMode: 'full',
-  allowUserInteraction: true
-});
-// Initialize and start rendering
-await core.initialize();
-console.log('Scene is running!');
-```
-## 🔧 Integration API
-### Core Configuration
-The `VijiCoreConfig` interface defines all available configuration options:
-```typescript
-interface VijiCoreConfig {
-  // Required configuration
-  hostContainer: HTMLElement;           // Container element for the scene
-  sceneCode: string;                    // Artist JavaScript code with render function
-  // Performance configuration
-  frameRateMode?: 'full' | 'half';      // 'full' = 60fps, 'half' = 30fps
-  // Input streams
-  audioStream?: MediaStream;            // Audio input for analysis
-  videoStream?: MediaStream;            // Video input (main, CV enabled)
-  videoStreams?: MediaStream[];         // Additional video streams (no CV)
-  // Feature toggles
-  noInputs?: boolean;                   // Disable all input processing
-  allowUserInteraction?: boolean;       // Enable mouse/keyboard/touch events
-  allowDeviceInteraction?: boolean;     // Enable device sensors (motion/orientation/geolocation)
-}
-```
-### Instance Management
-#### Creation and Initialization
-```typescript
-// Create core instance
-const core = new VijiCore({
-  hostContainer: document.getElementById('scene-container'),
-  sceneCode: sceneCode,
-  frameRateMode: 'full',
-  allowUserInteraction: true
-});
-// Initialize the core (required before use)
-await core.initialize();
-// Check if core is ready for operations
-  if (core.ready) {
-  console.log('Core is ready for use');
-}
-// Get current configuration
-const config = core.configuration;
-console.log('Current frame rate mode:', config.frameRateMode);
-```
-#### Performance Control
-```typescript
-// Frame rate control
-await core.setFrameRate('full');        // Set to 60fps mode
-await core.setFrameRate('half');        // Set to 30fps mode
-// Resolution control
-await core.setResolution(0.75);         // Set to 75% of container size
-await core.setResolution(0.5);          // Set to 50% for performance
-await core.updateResolution();          // Auto-detect container size changes
-// Get performance statistics
-const stats = core.getStats();
-console.log('Current FPS:', stats.frameRate.effectiveRefreshRate);
-console.log('Canvas size:', stats.resolution);
-console.log('Scale factor:', stats.scale);
-console.log('Parameter count:', stats.parameterCount);
-```
-#### Debug and Development
-```typescript
-// Enable debug logging
-core.setDebugMode(true);
-// Check debug mode status
-const isDebugEnabled = core.getDebugMode();
-// Debug mode provides detailed logging for:
-// - Initialization process
-// - Communication between components
-// - Parameter system operations
-// - Audio/video stream processing
-// - Performance statistics
-```
-### Parameter Management
-The parameter system provides a powerful way to create interactive scenes with automatic UI generation.
-#### Parameter Definition and Access
-```typescript
-// Listen for parameter definitions from artist code
-core.onParametersDefined((groups) => {
-  console.log('Parameters available:', groups);
-  // Each group contains:
-  // - groupName: string
-  // - category: 'audio' | 'video' | 'interaction' | 'general'
-  // - description: string
-  // - parameters: Record<string, ParameterDefinition>
-  // Generate UI based on parameter groups
-  generateParameterUI(groups);
-});
-// Set individual parameter values
-await core.setParameter('color', '#ff0000');
-await core.setParameter('size', 75);
-await core.setParameter('enabled', true);
-// Set multiple parameters efficiently
-await core.setParameters({
-  'color': '#00ff00',
-  'size': 100,
-  'speed': 2.0,
-  'enabled': false
-});
-// Get current parameter values
-const values = core.getParameterValues();
-const color = core.getParameter('color');
-// Listen for parameter changes
-core.onParameterChange('size', (value) => {
-  console.log('Size parameter changed to:', value);
-});
-// Listen for parameter errors
-core.onParameterError((error) => {
-  console.error('Parameter error:', error.message);
-  console.error('Error code:', error.code);
-});
-```
-#### Capability-Aware Parameters
-```typescript
-// Get all parameter groups (unfiltered, use for saving scene parameters)
-const allGroups = core.getAllParameterGroups();
-// Get parameter groups filtered by active capabilities (for UI)
-const visibleGroups = core.getVisibleParameterGroups();
-// Check current capabilities
-const capabilities = core.getCapabilities();
-console.log('Audio available:', capabilities.hasAudio);
-console.log('Video available:', capabilities.hasVideo);
-console.log('Interaction enabled:', capabilities.hasInteraction);
-// Check if specific parameter category is active
-const isAudioActive = core.isCategoryActive('audio');
-const isVideoActive = core.isCategoryActive('video');
-// Parameters are automatically categorized:
-// - 'audio': Only shown when audio stream is connected
-// - 'video': Only shown when video stream is connected
-// - 'interaction': Only shown when user interaction is enabled
-// - 'general': Always available
-```
-### Audio and Video Integration
-#### Audio Stream Management
-```typescript
-// Set audio stream for analysis
-const audioStream = await navigator.mediaDevices.getUserMedia({
-  audio: {
-    echoCancellation: false,
-    noiseSuppression: false,
-    autoGainControl: false
-  }
-});
-await core.setAudioStream(audioStream);
-// Configure audio analysis with the new namespace API
-// Basic control
-core.audio.setSensitivity(1.5);  // Increase sensitivity (0.5-2.0)
-// Tap tempo for manual BPM control
-core.audio.beat.tap();           // Tap to set tempo
-core.audio.beat.clearTaps();     // Clear tap history
-const tapCount = core.audio.beat.getTapCount();
-// Beat mode control
-core.audio.beat.setMode('auto');       // Automatic beat detection (default)
-core.audio.beat.setMode('manual');     // Manual BPM control
-core.audio.beat.setBPM(120);           // Set manual BPM (60-240)
-const currentBPM = core.audio.beat.getBPM();
-// Beat phase control for fine-tuning
-core.audio.beat.nudge(0.1);      // Nudge phase forward
-core.audio.beat.resetPhase();    // Reset phase to zero
-// Advanced configuration (optional)
-core.audio.advanced.setFFTSize(2048);       // FFT resolution (higher = more accurate)
-core.audio.advanced.setSmoothing(0.8);      // Smoothing factor (0-1)
-core.audio.advanced.setAutoGain(true);      // Auto-gain normalization
-core.audio.advanced.setBeatDetection(true); // Enable beat detection
-core.audio.advanced.setOnsetDetection(true); // Enable onset detection
-// Get current audio state
-const state = core.audio.getState();
-console.log('BPM:', state.currentBPM);
-console.log('Confidence:', state.confidence);
-console.log('Mode:', state.mode);
-console.log('Is Locked:', state.isLocked);
-// Get current audio stream
-const currentStream = core.getAudioStream();
-// Disconnect audio
-await core.setAudioStream(null);
-```
-#### Video Stream Management
-```typescript
-// Set video stream for analysis
-const videoStream = await navigator.mediaDevices.getUserMedia({
-  video: {
-    width: { ideal: 640 },
-    height: { ideal: 480 },
-    frameRate: { ideal: 30 }
-  }
-});
-await core.setVideoStream(videoStream);
-// Video analysis includes:
-// - Real-time frame processing
-// - Frame data access for custom analysis
-// - Brightness and motion detection
-// - Custom computer vision processing
-// Disconnect video
-await core.setVideoStream(null);
-```
-#### Interaction Management
-```typescript
-// Enable or disable user interactions at runtime
-await core.setInteractionEnabled(true);  // Enable mouse, keyboard, and touch
-await core.setInteractionEnabled(false); // Disable all interactions
-// Get current interaction state
-const isInteractionEnabled = core.getInteractionEnabled();
-// Interaction state affects:
-// - Mouse, keyboard, and touch event processing
-// - Parameter visibility (interaction category parameters)
-// - Scene behavior that depends on user input
-// Note: Interaction state is separate from initialization config
-// You can toggle interactions regardless of initial allowUserInteraction value
-// The interaction system is always available for runtime control
-```
-#### Capability Change Monitoring
-```typescript
-// Listen for capability changes
-core.onCapabilitiesChange((capabilities) => {
-  console.log('Capabilities updated:', capabilities);
-  // Update UI based on new capabilities
-  if (capabilities.hasAudio) {
-    showAudioControls();
-  } else {
-    hideAudioControls();
-  }
-  if (capabilities.hasVideo) {
-    showVideoControls();
-  } else {
-    hideVideoControls();
-  }
-  if (capabilities.hasInteraction) {
-    showInteractionControls();
-  } else {
-    hideInteractionControls();
-  }
-});
-```
-### Event Handling and Lifecycle
-#### Core Lifecycle Events
-```typescript
-// Core is ready for operations
-if (core.ready) {
-  // All systems initialized and running
-  console.log('Core is fully operational');
-}
-// Check if parameters are initialized
-if (core.parametersReady) {
-  // Parameter system is ready
-  console.log('Parameters are available');
-  }
-```
-#### Cleanup and Resource Management
-```typescript
-// Destroy instance and clean up all resources
-await core.destroy();
-// This automatically:
-// - Stops all rendering loops
-// - Disconnects audio/video streams
-// - Cleans up WebWorker and IFrame
-// - Releases all event listeners
-// - Clears parameter system
-// - Frees memory resources
-```
-## 🎨 Artist API
-The artist API provides a comprehensive set of tools for creating interactive, audio-reactive, and video-responsive scenes.
-### Canvas and Rendering
-```typescript
-function render(viji) {
-  // Get canvas contexts
-  const ctx = viji.useContext('2d');     // 2D rendering context
-  const gl = viji.useContext('webgl');   // WebGL rendering context
-  // Canvas properties
-  viji.canvas;        // OffscreenCanvas object
-  viji.width;         // Canvas width in pixels
-  viji.height;        // Canvas height in pixels
-  viji.pixelRatio;    // Device pixel ratio for crisp rendering
-  // Example: Draw a responsive circle
-  const centerX = viji.width / 2;
-  const centerY = viji.height / 2;
-  const radius = Math.min(viji.width, viji.height) * 0.1;
-  ctx.fillStyle = '#ff6b6b';
-  ctx.beginPath();
-  ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
-  ctx.fill();
-}
-```
-### Timing Information
-The timing system provides FPS-independent timing data for smooth animations:
-```typescript
-function render(viji) {
-  // Timing data (FPS independent)
-  viji.time;          // Elapsed time in seconds since scene start
-  viji.deltaTime;     // Time since last frame in seconds
-  viji.frameCount;    // Total number of frames rendered
-  viji.fps;           // Current frames per second
-  // Example: Smooth animation regardless of frame rate
-  const animationSpeed = 2.0; // rotations per second
-  const rotation = (viji.time * animationSpeed * Math.PI * 2) % (Math.PI * 2);
-  ctx.save();
-  ctx.translate(viji.width / 2, viji.height / 2);
-  ctx.rotate(rotation);
-  ctx.fillRect(-25, -25, 50, 50);
-  ctx.restore();
-}
-```
-### Parameter System
-The parameter system allows artists to define interactive parameters that automatically generate UI controls.
-#### Parameter Definition
-```typescript
-// Define parameters (call once outside render loop)
-const color = viji.color('#ff6b6b', {
-  label: 'Primary Color',
-  description: 'Main color for shapes',
-  group: 'appearance',
-  category: 'general'
-});
-const size = viji.slider(50, {
-  min: 10,
-  max: 150,
-  step: 5,
-  label: 'Shape Size',
-  description: 'Size of shapes in pixels',
-  group: 'appearance',
-  category: 'general'
-});
-const speed = viji.slider(1.0, {
-  min: 0.1,
-  max: 3.0,
-  step: 0.1,
-  label: 'Animation Speed',
-  description: 'Speed of animation in rotations per second',
-  group: 'animation',
-  category: 'general'
-});
-const useAudio = viji.toggle(false, {
-  label: 'Audio Reactive',
-  description: 'Make shapes react to audio input',
-  group: 'audio',
-  category: 'audio'
-});
-const shapeType = viji.select('circle', {
-  options: ['circle', 'square', 'triangle', 'star'],
-  label: 'Shape Type',
-  description: 'Type of shape to draw',
-  group: 'appearance',
-  category: 'general'
-});
-const title = viji.text('My Scene', {
-  label: 'Scene Title',
-  description: 'Title displayed in the scene',
-  group: 'text',
-  category: 'general',
-  maxLength: 50
-});
-const particleCount = viji.number(5, {
-  min: 1,
-  max: 20,
-  step: 1,
-  label: 'Particle Count',
-  description: 'Number of particles to render',
-  group: 'animation',
-  category: 'general'
-});
-```
-#### Parameter Usage in Render Loop
-```typescript
-function render(viji) {
-  const ctx = viji.useContext('2d');
-  // Fast parameter access (proxy-based)
-  ctx.fillStyle = color.value;           // Get current color value
-  const radius = size.value / 2;         // Get current size value
-  const animationSpeed = speed.value;    // Get current speed value
-  // Clear canvas
-  ctx.fillStyle = '#2c3e50';
-  ctx.fillRect(0, 0, viji.width, viji.height);
-  // Draw title
-  ctx.fillStyle = 'white';
-  ctx.font = '20px Arial';
-  ctx.textAlign = 'center';
-  ctx.fillText(title.value, viji.width / 2, 30);
-  // Draw particles
-  for (let i = 0; i < particleCount.value; i++) {
-    const angle = (i / particleCount.value) * Math.PI * 2 + (viji.time * animationSpeed);
-    const x = viji.width / 2 + Math.cos(angle) * 100;
-    const y = viji.height / 2 + Math.sin(angle) * 100;
-    ctx.fillStyle = color.value;
-    ctx.beginPath();
-    switch (shapeType.value) {
-      case 'circle':
-        ctx.arc(x, y, radius, 0, Math.PI * 2);
-        break;
-      case 'square':
-        ctx.rect(x - radius, y - radius, radius * 2, radius * 2);
-        break;
-      case 'triangle':
-        ctx.moveTo(x, y - radius);
-        ctx.lineTo(x - radius, y + radius);
-        ctx.lineTo(x + radius, y + radius);
-        ctx.closePath();
-        break;
-    }
-    ctx.fill();
-  }
-}
-```
-### Audio Analysis
-The audio system provides real-time analysis of audio input with comprehensive frequency and volume data.
-#### Audio API Overview
-```typescript
-function render(viji) {
-  const audio = viji.audio;
-  if (audio.isConnected) {
-    // Volume analysis with smooth values
-    const volume = audio.volume.current;   // 0-1 current volume level (RMS-based)
-    const peak = audio.volume.peak;        // 0-1 peak amplitude (instant)
-    const smooth = audio.volume.smoothed;  // 0-1 smoothed volume (200ms decay)
-    // Frequency bands (0-1 values) with instant and smooth versions
-    const low = audio.bands.low;           // 20-150 Hz (bass/kick range, instant)
-    const lowSmoothed = audio.bands.lowSmoothed; // Smooth low frequency energy
-    const lowMid = audio.bands.lowMid;     // 150-400 Hz
-    const mid = audio.bands.mid;           // 400-2500 Hz (vocals, instruments)
-    const highMid = audio.bands.highMid;   // 2500-8000 Hz (cymbals, hi-hats)
-    const high = audio.bands.high;         // 8000-20000 Hz (air, brilliance)
-    // Automatic beat detection with BPM tracking
-    const beat = audio.beat;
-    // Fast energy curves (300ms decay - primary for most visuals)
-    const kickEnergy = beat.kick;          // 0-1 kick drum energy
-    const snareEnergy = beat.snare;        // 0-1 snare energy
-    const hatEnergy = beat.hat;            // 0-1 hi-hat energy
-    const anyEnergy = beat.any;            // 0-1 any beat type energy
-    // Smoothed energy curves (500ms decay - for slower animations)
-    const kickSmoothed = beat.kickSmoothed;
-    const snareSmoothed = beat.snareSmoothed;
-    const anySmoothed = beat.anySmoothed;
-    // Instant triggers (for advanced use cases)
-    if (beat.triggers.kick) {
-      // Kick drum detected this frame
-      spawnParticle('kick');
-    }
-    // BPM and tempo information
-    const bpm = beat.bpm;                   // Detected BPM (60-180)
-    const phase = beat.phase;               // Beat phase 0-1 within current beat
-    const bar = beat.bar;                   // Current bar number (0-3 for 4/4)
-    const confidence = beat.confidence;     // Detection confidence 0-1
-    const isLocked = beat.isLocked;         // True when beat is locked
-    // Spectral features for advanced audio-reactive effects
-    const brightness = audio.spectral.brightness;  // 0-1 spectral centroid
-    const flatness = audio.spectral.flatness;      // 0-1 spectral flatness (noisiness)
-    const flux = audio.spectral.flux;              // 0-1 spectral flux (change)
-    // Raw frequency data (0-255 values)
-    const frequencyData = audio.getFrequencyData();
-    // Example 1: Smooth beat-reactive animation (primary pattern)
-    const scale = 1 + kickEnergy * 0.5;  // Smooth pulsing with kick
-    const hue = lowSmoothed * 180;       // Smooth color based on low frequencies
-    ctx.save();
-    ctx.translate(viji.width / 2, viji.height / 2);
-    ctx.scale(scale, scale);
-    ctx.fillStyle = `hsl(${hue}, 70%, 60%)`;
-    ctx.fillRect(-25, -25, 50, 50);
-    ctx.restore();
-    // Example 2: Phase-synced rotation
-    const rotation = phase * Math.PI * 2;  // Rotate with beat phase
-    ctx.rotate(rotation);
-  }
-}
-```
-#### Audio-Reactive Scene Example
-```typescript
-// Define audio-reactive parameters
-const audioReactive = viji.toggle(true, {
-  label: 'Audio Reactive',
-  description: 'Make shapes react to audio',
-  group: 'audio',
-  category: 'audio'
-});
-const volumeSensitivity = viji.slider(1.0, {
-  min: 0.1,
-  max: 5.0,
-  step: 0.1,
-  label: 'Volume Sensitivity',
-  description: 'How sensitive shapes are to volume',
-  group: 'audio',
-  category: 'audio'
-});
-const bassReactivity = viji.slider(1.0, {
-  min: 0,
-  max: 3.0,
-  step: 0.1,
-  label: 'Bass Reactivity',
-  description: 'How much shapes react to bass',
-  group: 'audio',
-  category: 'audio'
-});
-function render(viji) {
-  const ctx = viji.useContext('2d');
-  const audio = viji.audio;
-  // Clear canvas
-  ctx.fillStyle = '#2c3e50';
-  ctx.fillRect(0, 0, viji.width, viji.height);
-  if (audioReactive.value && audio.isConnected) {
-    // Audio-reactive animation
-    const volume = audio.volume.current * volumeSensitivity.value;
-    const bass = audio.bands.low * bassReactivity.value;
-    // Scale based on volume
-    const scale = 1 + volume;
-    // Color based on bass
-    const hue = 200 + (bass * 160); // Blue to purple range
-    // Position based on frequency distribution
-    const x = viji.width * (audio.bands.mid + audio.bands.high) / 2;
-    const y = viji.height * (1 - audio.bands.low);
-    ctx.save();
-    ctx.translate(x, y);
-    ctx.scale(scale, scale);
-    ctx.fillStyle = `hsl(${hue}, 80%, 60%)`;
-    ctx.beginPath();
-    ctx.arc(0, 0, 30, 0, Math.PI * 2);
-    ctx.fill();
-    ctx.restore();
-  }
-}
-```
-### Video Analysis
-The video system provides real-time video frame analysis with frame data access for custom processing.
-#### Video API Overview
-```typescript
-function render(viji) {
-  const video = viji.video;
-  if (video.isConnected) {
-    // Video properties
-    const frameWidth = video.frameWidth;
-    const frameHeight = video.frameHeight;
-    const frameRate = video.frameRate;
-    // Current video frame (OffscreenCanvas)
-    if (video.currentFrame) {
-      // Draw video frame as background
-      ctx.globalAlpha = 0.3;
-      ctx.drawImage(video.currentFrame, 0, 0, viji.width, viji.height);
-      ctx.globalAlpha = 1.0;
-    }
-    // Frame data for custom analysis
-    const frameData = video.getFrameData();
-    // Example: Custom video analysis
-    if (frameData) {
-      // Access raw pixel data for custom processing
-      const imageData = frameData.data;
-      const width = frameData.width;
-      const height = frameData.height;
-      // Example: Calculate average brightness
-      let totalBrightness = 0;
-      for (let i = 0; i < imageData.length; i += 4) {
-        const r = imageData[i];
-        const g = imageData[i + 1];
-        const b = imageData[i + 2];
-        totalBrightness += (r + g + b) / 3;
-      }
-      const averageBrightness = totalBrightness / (imageData.length / 4);
-      // Use brightness for effects
-      const brightness = averageBrightness / 255; // Normalize to 0-1
-      // Create brightness-reactive animation
-      ctx.fillStyle = `rgba(255, 255, 255, ${brightness * 0.5})`;
-      ctx.fillRect(0, 0, viji.width, viji.height);
-    }
-  }
-}
-```
-#### Video-Reactive Scene Example
-```typescript
-// Define video-reactive parameters
-const videoReactive = viji.toggle(true, {
-  label: 'Video Reactive',
-  description: 'Make shapes react to video',
-  group: 'video',
-  category: 'video'
-});
-const motionSensitivity = viji.slider(1.0, {
-  min: 0.1,
-  max: 3.0,
-  step: 0.1,
-  label: 'Motion Sensitivity',
-  description: 'How sensitive shapes are to video changes',
-  group: 'video',
-  category: 'video'
-});
-function render(viji) {
-  const ctx = viji.useContext('2d');
-  const video = viji.video;
-  if (videoReactive.value && video.isConnected) {
-    // Video-reactive animation using frame data
-    const frameData = video.getFrameData();
-    if (frameData) {
-      // Simple motion detection (compare with previous frame)
-      // This is a basic example - you can implement more sophisticated analysis
-      const imageData = frameData.data;
-      let motionEnergy = 0;
-      // Calculate motion energy (simplified)
-      for (let i = 0; i < imageData.length; i += 4) {
-        const brightness = (imageData[i] + imageData[i + 1] + imageData[i + 2]) / 3;
-        motionEnergy += brightness;
-      }
-      const normalizedMotion = (motionEnergy / (imageData.length / 4)) / 255;
-      const scale = 1 + (normalizedMotion * motionSensitivity.value);
-      // Create motion-reactive shapes
-      ctx.save();
-      ctx.translate(viji.width / 2, viji.height / 2);
-      ctx.scale(scale, scale);
-      ctx.fillStyle = `hsl(${normalizedMotion * 360}, 70%, 60%)`;
-      ctx.beginPath();
-      ctx.arc(0, 0, 30, 0, Math.PI * 2);
-      ctx.fill();
-      ctx.restore();
-    }
-  }
-}
-```
-### User Interaction
-The interaction system provides comprehensive support for mouse, keyboard, and touch input.
-#### Mouse Interaction
-```typescript
-function render(viji) {
-  const mouse = viji.mouse;
-  // Mouse position (canvas coordinates)
-  if (mouse.isInCanvas) {
-    const x = mouse.x;                   // Current X coordinate
-    const y = mouse.y;                   // Current Y coordinate
-    // Mouse movement
-    const deltaX = mouse.deltaX;         // X movement since last frame
-    const deltaY = mouse.deltaY;         // Y movement since last frame
-    const velocity = mouse.velocity;     // Smoothed velocity { x, y }
-    // Mouse buttons
-    const isPressed = mouse.isPressed;   // Any button currently pressed
-    const leftButton = mouse.leftButton; // Left button state
-    const rightButton = mouse.rightButton; // Right button state
-    const middleButton = mouse.middleButton; // Middle button state
-    // Frame-based events
-    const wasPressed = mouse.wasPressed; // Button was pressed this frame
-    const wasReleased = mouse.wasReleased; // Button was released this frame
-    const wasMoved = mouse.wasMoved;     // Mouse moved this frame
-    // Scroll wheel
-    const wheelDelta = mouse.wheelDelta; // Combined wheel delta
-    const wheelX = mouse.wheelX;         // Horizontal wheel delta
-    const wheelY = mouse.wheelY;         // Vertical wheel delta
-    // Example: Mouse-reactive animation
-    ctx.fillStyle = leftButton ? 'red' : 'blue';
-    ctx.beginPath();
-    ctx.arc(x, y, 20 + Math.abs(velocity.x + velocity.y), 0, Math.PI * 2);
-    ctx.fill();
-  }
-}
-```
-#### Keyboard Interaction
-```typescript
-function render(viji) {
-  const keyboard = viji.keyboard;
-  // Key state queries
-  if (keyboard.isPressed('w')) {
-    // W key is currently pressed
-    console.log('W key is held down');
-  }
-  if (keyboard.wasPressed('space')) {
-    // Space was pressed this frame
-    console.log('Space was pressed!');
-  }
-  if (keyboard.wasReleased('escape')) {
-    // Escape was released this frame
-    console.log('Escape was released!');
-  }
-  // Active key tracking
-  const activeKeys = keyboard.activeKeys;        // Set of currently pressed keys
-  const pressedThisFrame = keyboard.pressedThisFrame; // Set of keys pressed this frame
-  const releasedThisFrame = keyboard.releasedThisFrame; // Set of keys released this frame
-  // Modifier keys
-  const shift = keyboard.shift;          // Shift key is held
-  const ctrl = keyboard.ctrl;            // Ctrl key is held
-  const alt = keyboard.alt;              // Alt key is held
-  const meta = keyboard.meta;            // Meta/Cmd key is held
-  // Recent activity
-  const lastKeyPressed = keyboard.lastKeyPressed;   // Last key that was pressed
-  const lastKeyReleased = keyboard.lastKeyReleased; // Last key that was released
-  // Example: Keyboard-controlled movement
-  let moveX = 0;
-  let moveY = 0;
-  if (keyboard.isPressed('w') || keyboard.isPressed('W')) moveY -= 5;
-  if (keyboard.isPressed('s') || keyboard.isPressed('S')) moveY += 5;
-  if (keyboard.isPressed('a') || keyboard.isPressed('A')) moveX -= 5;
-  if (keyboard.isPressed('d') || keyboard.isPressed('D')) moveX += 5;
-  // Apply movement
-  ctx.save();
-  ctx.translate(moveX, moveY);
-  ctx.fillStyle = 'green';
-  ctx.fillRect(0, 0, 50, 50);
-  ctx.restore();
-}
-```
-#### Touch Interaction
-```typescript
-function render(viji) {
-  const touches = viji.touches;
-  // Touch points
-  for (const touch of touches.points) {
-    const x = touch.x;                   // Touch X coordinate
-    const y = touch.y;                   // Touch Y coordinate
-    const pressure = touch.pressure;     // Pressure (0-1)
-    const radius = touch.radius;         // Touch radius
-    const id = touch.id;                 // Unique touch ID
-    // Movement
-    const deltaX = touch.deltaX;         // X movement since last frame
-    const deltaY = touch.deltaY;         // Y movement since last frame
-    const velocity = touch.velocity;     // Movement velocity { x, y }
-    // Lifecycle
-    const isNew = touch.isNew;           // Touch started this frame
-    const isActive = touch.isActive;     // Touch is currently active
-    const isEnding = touch.isEnding;     // Touch ending this frame
-    // Draw touch point
-    ctx.fillStyle = isNew ? 'red' : isEnding ? 'yellow' : 'blue';
-    ctx.beginPath();
-    ctx.arc(x, y, radius * 2, 0, Math.PI * 2);
-    ctx.fill();
-  }
-  // Touch events
-  const started = touches.started;       // Touches that started this frame
-  const moved = touches.moved;           // Touches that moved this frame
-  const ended = touches.ended;           // Touches that ended this frame
-  // Primary touch (first touch point)
-  const primary = touches.primary;       // Primary touch point or null
-  // Touch gestures
-  const gestures = touches.gestures;
-  if (gestures.isPinching) {
-    const scale = gestures.pinchScale;       // Current pinch scale
-    const delta = gestures.pinchDelta;       // Scale change since last frame
-    // React to pinch gesture
-    ctx.save();
-    ctx.scale(scale, scale);
-    ctx.fillStyle = 'purple';
-    ctx.fillRect(0, 0, 100, 100);
-    ctx.restore();
-  }
-  if (gestures.isRotating) {
-    const angle = gestures.rotationAngle;    // Current rotation angle
-    const delta = gestures.rotationDelta;    // Rotation change since last frame
-    // React to rotation gesture
-    ctx.save();
-    ctx.rotate(angle);
-    ctx.fillStyle = 'orange';
-    ctx.fillRect(-25, -25, 50, 50);
-    ctx.restore();
-  }
-  if (gestures.isPanning) {
-    const panDelta = gestures.panDelta;      // Pan movement { x, y }
-    // React to pan gesture
-    ctx.save();
-    ctx.translate(panDelta.x, panDelta.y);
-    ctx.fillStyle = 'cyan';
-    ctx.fillRect(0, 0, 50, 50);
-    ctx.restore();
-  }
-  if (gestures.isTapping) {
-    const tapCount = gestures.tapCount;      // Number of taps
-    const tapPosition = gestures.tapPosition; // { x, y } tap position
-    // React to tap gesture
-    if (tapPosition) {
-      ctx.fillStyle = 'lime';
-      ctx.beginPath();
-      ctx.arc(tapPosition.x, tapPosition.y, 30, 0, Math.PI * 2);
-      ctx.fill();
-    }
-  }
-}
-```
-#### Device Sensors (Motion, Orientation, Geolocation)
-```typescript
-function render(viji) {
-  // Internal device (current device running the scene)
-  const device = viji.device;
-  // Check if device motion is available
-  if (device.motion?.acceleration) {
-    const accelX = device.motion.acceleration.x;  // m/s² (without gravity)
-    // Example: Shake detection
-    const magnitude = Math.sqrt(
-      accelX**2 + device.motion.acceleration.y**2 + device.motion.acceleration.z**2
-    );
-    if (magnitude > 15) {
-      console.log('Device shaken!');
-    }
-  }
-  // Check if device orientation is available
-  if (device.orientation.gamma !== null) {
-    const tiltLR = device.orientation.gamma;  // -90 to 90 (left/right tilt)
-    const tiltFB = device.orientation.beta;   // -180 to 180 (front/back tilt)
-    // Example: Tilt-based control
-    const moveX = (tiltLR / 90) * 5;
-    ctx.save();
-    ctx.translate(moveX, 0);
-    ctx.fillStyle = 'red';
-    ctx.fillRect(viji.width/2 - 25, viji.height/2 - 25, 50, 50);
-    ctx.restore();
-  }
-  // Check if geolocation is available
-  if (device.geolocation.latitude !== null) {
-    const lat = device.geolocation.latitude;
-    const lon = device.geolocation.longitude;
-    ctx.fillStyle = 'white';
-    ctx.fillText(`Location: ${lat.toFixed(4)}, ${lon.toFixed(4)}`, 10, 30);
-  }
-  // External connected devices (WebRTC/Sockets)
-  viji.devices.forEach((device, index) => {
-    if (device.orientation.gamma !== null) {
-      // Multi-device control example
-      const x = (device.orientation.gamma / 90 + 1) * viji.width / 2;
-      ctx.fillStyle = `hsl(${index * 60}, 70%, 60%)`;
-      ctx.beginPath();
-      ctx.arc(x, 100 + index * 60, 25, 0, Math.PI * 2);
-      ctx.fill();
-    }
-  });
-}
-```
-**Device Sensor Features:**
-- **Motion Sensors**: Accelerometer and gyroscope data for shake detection and motion tracking
-- **Orientation Sensors**: Device tilt for tilt-based controls and compass heading
-- **Geolocation**: GPS coordinates for location-based content
-- **Multi-Device Support**: Connect multiple external devices via WebRTC for installations
-- **Graceful Degradation**: Automatic handling of missing sensors or permissions
-**See `docs/20-device-sensor-system.md` for complete device sensor documentation including WebRTC integration and multi-device installations.**
-## 🎨 P5.js Support
-Viji Core supports **P5.js** as an optional rendering library. P5.js provides familiar creative coding APIs while maintaining all Viji features including audio reactivity, video processing, and parameter management.
-### Enabling P5.js Mode
-Add a single comment at the top of your scene code:
-```javascript
-// @renderer p5
-function setup(viji, p5) {
-  p5.colorMode(p5.HSB);
-}
-function render(viji, p5) {
-  p5.background(220);
-  p5.fill(255, 0, 0);
-  p5.ellipse(viji.mouse.x, viji.mouse.y, 50, 50);
-}
-```
-### What Works
-- ✅ All P5.js drawing functions (shapes, colors, transforms, typography)
-- ✅ P5.js math utilities (`noise()`, `random()`, `map()`, `lerp()`)
-- ✅ P5.js vectors (`p5.Vector` class)
-- ✅ WebGL mode (`p5.WEBGL`)
-- ✅ Full Viji integration (audio, video, parameters, interaction)
-### What Doesn't Work
-- ❌ p5.dom (use Viji parameters instead)
-- ❌ p5.sound (use `viji.audio` instead)
-- ❌ P5.js events (use `viji.mouse`/`keyboard`/`touches` instead)
-- ❌ Direct image loading (use Viji image parameters instead)
-### Audio Reactive P5.js Example
-```javascript
-// @renderer p5
-const audioReactive = viji.toggle(true, {
-  label: 'Audio Reactive',
-  category: 'audio'
-});
-const bassReactivity = viji.slider(1.0, {
-  min: 0,
-  max: 3.0,
-  label: 'Bass Reactivity',
-  category: 'audio'
-});
-function render(viji, p5) {
-  p5.background(0);
-  if (audioReactive.value && viji.audio.isConnected) {
-    const bass = viji.audio.bands.low;
-    const volume = viji.audio.volume.current;
-    const hue = bass * 360 * bassReactivity.value;
-    const size = 100 + volume * 200;
-    p5.colorMode(p5.HSB);
-    p5.fill(hue, 80, 100);
-    p5.ellipse(p5.width / 2, p5.height / 2, size, size);
-  }
-}
-```
-### Image Parameters
-```javascript
-// @renderer p5
-const bgImage = viji.image(null, {
-  label: 'Background Image',
-  group: 'media',
-  accept: 'image/*'
-});
-function render(viji, p5) {
-  p5.background(220);
-  if (bgImage.value) {
-    p5.image(bgImage.value, 0, 0, p5.width, p5.height);
-  }
-  // Draw on top of image
-  p5.fill(255, 0, 0, 128);
-  p5.ellipse(viji.mouse.x, viji.mouse.y, 50, 50);
-}
-```
-### Getting Renderer Type
-```typescript
-const core = new VijiCore({
-  hostContainer: container,
-  sceneCode: sceneCode
-});
-await core.initialize();
-// Check which renderer is being used (from stats, like FPS/resolution)
-const stats = core.getStats();
-const rendererType = stats.rendererType; // 'native' | 'p5'
-```
-### Loading Image Parameters
-```typescript
-core.onParametersDefined((groups) => {
-  groups.forEach(group => {
-    Object.entries(group.parameters).forEach(([name, def]) => {
-      if (def.type === 'image') {
-        // Create file picker
-        const input = createFileInput(name, def);
-        input.addEventListener('change', async (e) => {
-          const file = e.target.files[0];
-          if (file) {
-            await core.setParameter(name, file); // Unified API handles images automatically
-          }
-        });
-      }
-    });
-  });
-});
-```
-**See `docs/16-p5js-integration.md` for comprehensive documentation including migration guides, troubleshooting, and advanced examples.**
-## 🏗️ Architecture
-### Security Model
-The core implements a comprehensive security model to ensure safe execution of artist code:
-- **IFrame Isolation**: Complete separation from host environment with sandboxed execution
-- **WebWorker Sandboxing**: Artist code runs with controlled API access only
-- **Blob URL Creation**: Secure worker and IFrame creation from blob URLs
-- **Resource Protection**: Memory leaks and errors cannot affect main application
-- **Controlled Communication**: Optimized message passing with validation
-### Performance Features
-The core provides extensive performance optimization capabilities:
-- **Configurable Frame Rates**: Full (60fps) or half (30fps) modes for performance tuning
-- **Resolution Scaling**: Fractional (0.1-1.0) or explicit canvas dimensions
-- **Adaptive Optimization**: Automatic performance tuning based on hardware capabilities
-- **Efficient Communication**: Optimized message passing between components
-- **Memory Management**: Automatic resource cleanup and memory leak prevention
-### Multi-Instance Support
-The core supports multiple concurrent instances for complex applications:
-```typescript
-// Main scene with full features
-const mainCore = new VijiCore({
-  hostContainer: document.getElementById('main-scene'),
-  resolution: { width: 1920, height: 1080 },
-  frameRateMode: 'full',
-  allowUserInteraction: true,
-  audioStream: sharedAudioStream,
-  videoStream: sharedVideoStream
-});
-// Preview instance with reduced features
-const previewCore = new VijiCore({
-  hostContainer: document.getElementById('preview'),
-  resolution: 0.25, // 25% resolution for performance
-  frameRateMode: 'half',
-  noInputs: true,
-  allowUserInteraction: false,
-  audioStream: sharedAudioStream // Shared efficiently across instances
-});
-// Thumbnail instance for gallery view
-const thumbnailCore = new VijiCore({
-  hostContainer: document.getElementById('thumbnail'),
-  resolution: 0.1, // 10% resolution
-  frameRateMode: 'half',
-  noInputs: true,
-  allowUserInteraction: false
-});
-// To change scenes, create a new instance and destroy the old one
-const newCore = new VijiCore({
-  hostContainer: document.getElementById('scene-host'),
-  sceneCode: newSceneCode,
-  audioStream: sharedAudioStream,
-  videoStream: sharedVideoStream
-});
-// Automatic comprehensive cleanup when destroyed
-await oldCore.destroy();
-```
-## 🔍 Error Handling
-The core provides comprehensive error handling with detailed error information:
-```typescript
-import { VijiCoreError } from '@viji-dev/core';
-try {
-  const core = new VijiCore(config);
-  await core.initialize();
-} catch (error) {
-  if (error instanceof VijiCoreError) {
-    console.error(`Core error [${error.code}]:`, error.message);
-    console.error('Error context:', error.context);
-    // Handle specific error types
-    switch (error.code) {
-      case 'INVALID_CONFIG':
-        console.error('Configuration is invalid:', error.context);
-        break;
-      case 'INITIALIZATION_ERROR':
-        console.error('Failed to initialize core:', error.context);
-        break;
-      case 'CORE_NOT_READY':
-        console.error('Core is not ready for operations');
-        break;
-      case 'INSTANCE_DESTROYED':
-        console.error('Core instance has been destroyed');
-        break;
-      case 'PARAMETERS_NOT_INITIALIZED':
-        console.error('Parameter system not yet initialized');
-        break;
-      case 'UNKNOWN_PARAMETER':
-        console.error('Parameter not found:', error.context);
-        break;
-    }
-  } else {
-    console.error('Unexpected error:', error);
-  }
-}
-```
-**Common Error Codes:**
-- `INVALID_CONFIG` - Configuration validation failed
-- `INITIALIZATION_ERROR` - Failed to initialize core components
-- `CORE_NOT_READY` - Operation attempted before ready
-- `INSTANCE_DESTROYED` - Operation attempted after destroy
-- `PARAMETERS_NOT_INITIALIZED` - Parameters not yet available
-- `UNKNOWN_PARAMETER` - Parameter not found
-- `CONCURRENT_INITIALIZATION` - Multiple initialization attempts
-- `MANAGER_NOT_READY` - Internal component not available
-## 🧪 Development
-```bash
-# Install dependencies
-npm install
-# Build the package
-npm run build
-# Run tests
-npm test
-# Development build (watch mode)
-npm run dev
-# Type checking
-npm run type-check
-# Linting
-npm run lint
-```
-## 📚 Examples
-The package includes comprehensive examples in the `/example` directory:
-- **Basic Scene Creation**: Simple animated shapes with parameters
-- **Audio-Reactive Scenes**: Scenes that respond to audio input
-- **Video-Reactive Scenes**: Scenes that respond to video analysis
-- **Interactive Scenes**: Mouse, keyboard, and touch interaction
-- **Parameter System**: Complete parameter definition and UI generation
-- **Multi-Instance**: Multiple concurrent scene instances
-## 🎯 Use Cases
-### Platform Integration
-The core integrates seamlessly with the Viji platform, providing scene execution while the platform handles UI, user management, and social features.
-### SDK Development
-The core serves as the execution foundation for the Viji SDK, ensuring identical behavior between development and platform environments.
-### Standalone Applications
-Use the core directly in custom applications for creative scene rendering with full feature support.
-## 📄 License
-Copyright (c) 2025 Artem Verkhovskiy and Dmitry Manoilenko.
-All rights reserved - see the LICENSE file for details.
-## Contributor License Agreement
-By contributing, you agree to the [CLA](./CLA.md).
-Please also confirm your agreement by filling out this short [form](https://forms.gle/A49WTz8nj5b99Yev7).
----
+# Viji Core Package (`@viji-dev/core`)
+**Universal execution engine for Viji Creative scenes**
+A powerful, secure, and feature-rich JavaScript/TypeScript library that provides the foundation for creative scene execution across all Viji platform contexts. The core offers identical IFrame + WebWorker execution with comprehensive parameter management, audio/video analysis, user interaction handling, and performance optimization.
+## 🚀 Features
+### ✅ **Core Execution Engine**
+- **Secure IFrame + WebWorker Architecture**: Complete isolation with controlled communication
+- **Multi-Instance Support**: Concurrent instances for main scenes and previews
+- **Automatic Resource Management**: Memory leak prevention and cleanup
+### ✅ **Parameter System**
+- **Declarative Parameter Definition**: Define parameters once with automatic UI generation
+- **Proxy-Based Access**: Fast parameter access in render loops
+- **Category-Based Organization**: Audio, video, interaction, and general parameters
+- **Real-time Validation**: Type safety and range checking
+- **Capability-Aware UI**: Parameters shown based on active features
+### ✅ **Audio Analysis**
+- **Real-time Audio Processing**: Volume, frequency analysis, and beat detection
+- **Custom Frequency Bands**: Bass, mid, treble, and custom band analysis
+- **Multiple Input Sources**: Microphone, audio files, and screen capture
+- **Audio-Reactive Scenes**: Make scenes respond to audio input
+### ✅ **Video Analysis**
+- **Real-time Video Processing**: Frame analysis in separate WebWorker
+- **Multiple Input Sources**: Camera, video files, and screen capture
+- **Video-Reactive Scenes**: Make scenes respond to video motion and brightness
+- **Frame Data Access**: Raw video frame data for custom analysis
+### ✅ **User Interaction**
+- **Mouse Tracking**: Position, buttons, movement, and scroll wheel
+- **Keyboard Input**: Key states, modifiers, and event handling
+- **Touch Support**: Multi-touch with gesture detection
+- **Device Sensors**: Motion, orientation, and geolocation (internal + external devices)
+- **Canvas-Coordinate Mapping**: Accurate input positioning
+### ✅ **Performance Optimization**
+- **Configurable Frame Rates**: Full (60fps) or half (30fps) modes
+- **Resolution Scaling**: Fractional or explicit canvas dimensions
+- **Adaptive Performance**: Automatic optimization based on hardware
+- **Memory Management**: Efficient resource pooling and cleanup
+## 📦 Installation
+```bash
+npm install @viji-dev/core
+```
+## 🎯 Quick Start
+### Basic Scene Creation
+```typescript
+import { VijiCore } from '@viji-dev/core';
+// Artist scene code
+const sceneCode = `
+// Define parameters using helper functions
+const color = viji.color('#ff6b6b', {
+  label: 'Shape Color',
+  description: 'Color of the animated shape',
+  group: 'appearance'
+});
+const size = viji.slider(50, {
+  min: 10,
+  max: 150,
+  step: 5,
+  label: 'Shape Size',
+  description: 'Size of the animated shape',
+  group: 'appearance'
+});
+const speed = viji.slider(1.0, {
+  min: 0.1,
+  max: 3.0,
+  step: 0.1,
+  label: 'Animation Speed',
+  description: 'Speed of the animation',
+  group: 'animation'
+});
+// Main render function
+function render(viji) {
+  const ctx = viji.useContext('2d');
+  // Clear canvas
+  ctx.fillStyle = '#2c3e50';
+  ctx.fillRect(0, 0, viji.width, viji.height);
+  // Animated shape
+  const time = viji.time * speed.value;
+  const x = viji.width / 2 + Math.sin(time) * 100;
+  const y = viji.height / 2 + Math.cos(time) * 100;
+  ctx.fillStyle = color.value;
+  ctx.beginPath();
+  ctx.arc(x, y, size.value / 2, 0, Math.PI * 2);
+  ctx.fill();
+}
+`;
+// Create core instance
+const core = new VijiCore({
+  hostContainer: document.getElementById('scene-container'),
+  sceneCode: sceneCode,
+  frameRateMode: 'full',
+  allowUserInteraction: true
+});
+// Initialize and start rendering
+await core.initialize();
+console.log('Scene is running!');
+```
+## 🔧 Integration API
+### Core Configuration
+The `VijiCoreConfig` interface defines all available configuration options:
+```typescript
+interface VijiCoreConfig {
+  // Required configuration
+  hostContainer: HTMLElement;           // Container element for the scene
+  sceneCode: string;                    // Artist JavaScript code with render function
+  // Performance configuration
+  frameRateMode?: 'full' | 'half';      // 'full' = 60fps, 'half' = 30fps
+  // Input streams
+  audioStream?: MediaStream;            // Audio input for analysis
+  videoStream?: MediaStream;            // Video input (main, CV enabled)
+  videoStreams?: MediaStream[];         // Additional video streams (no CV)
+  // Feature toggles
+  noInputs?: boolean;                   // Disable all input processing
+  allowUserInteraction?: boolean;       // Enable mouse/keyboard/touch events
+  allowDeviceInteraction?: boolean;     // Enable device sensors (motion/orientation/geolocation)
+}
+```
+### Instance Management
+#### Creation and Initialization
+```typescript
+// Create core instance
+const core = new VijiCore({
+  hostContainer: document.getElementById('scene-container'),
+  sceneCode: sceneCode,
+  frameRateMode: 'full',
+  allowUserInteraction: true
+});
+// Initialize the core (required before use)
+await core.initialize();
+// Check if core is ready for operations
+  if (core.ready) {
+  console.log('Core is ready for use');
+}
+// Get current configuration
+const config = core.configuration;
+console.log('Current frame rate mode:', config.frameRateMode);
+```
+#### Performance Control
+```typescript
+// Frame rate control
+await core.setFrameRate('full');        // Set to 60fps mode
+await core.setFrameRate('half');        // Set to 30fps mode
+// Resolution control
+await core.setResolution(0.75);         // Set to 75% of container size
+await core.setResolution(0.5);          // Set to 50% for performance
+await core.updateResolution();          // Auto-detect container size changes
+// Get performance statistics
+const stats = core.getStats();
+console.log('Current FPS:', stats.frameRate.effectiveRefreshRate);
+console.log('Canvas size:', stats.resolution);
+console.log('Scale factor:', stats.scale);
+console.log('Parameter count:', stats.parameterCount);
+```
+#### Debug and Development
+```typescript
+// Enable debug logging
+core.setDebugMode(true);
+// Check debug mode status
+const isDebugEnabled = core.getDebugMode();
+// Debug mode provides detailed logging for:
+// - Initialization process
+// - Communication between components
+// - Parameter system operations
+// - Audio/video stream processing
+// - Performance statistics
+```
+### Parameter Management
+The parameter system provides a powerful way to create interactive scenes with automatic UI generation.
+#### Parameter Definition and Access
+```typescript
+// Listen for parameter definitions from artist code
+core.onParametersDefined((groups) => {
+  console.log('Parameters available:', groups);
+  // Each group contains:
+  // - groupName: string
+  // - category: 'audio' | 'video' | 'interaction' | 'general'
+  // - description: string
+  // - parameters: Record<string, ParameterDefinition>
+  // Generate UI based on parameter groups
+  generateParameterUI(groups);
+});
+// Set individual parameter values
+await core.setParameter('color', '#ff0000');
+await core.setParameter('size', 75);
+await core.setParameter('enabled', true);
+// Set multiple parameters efficiently
+await core.setParameters({
+  'color': '#00ff00',
+  'size': 100,
+  'speed': 2.0,
+  'enabled': false
+});
+// Get current parameter values
+const values = core.getParameterValues();
+const color = core.getParameter('color');
+// Listen for parameter changes
+core.onParameterChange('size', (value) => {
+  console.log('Size parameter changed to:', value);
+});
+// Listen for parameter errors
+core.onParameterError((error) => {
+  console.error('Parameter error:', error.message);
+  console.error('Error code:', error.code);
+});
+```
+#### Capability-Aware Parameters
+```typescript
+// Get all parameter groups (unfiltered, use for saving scene parameters)
+const allGroups = core.getAllParameterGroups();
+// Get parameter groups filtered by active capabilities (for UI)
+const visibleGroups = core.getVisibleParameterGroups();
+// Check current capabilities
+const capabilities = core.getCapabilities();
+console.log('Audio available:', capabilities.hasAudio);
+console.log('Video available:', capabilities.hasVideo);
+console.log('Interaction enabled:', capabilities.hasInteraction);
+// Check if specific parameter category is active
+const isAudioActive = core.isCategoryActive('audio');
+const isVideoActive = core.isCategoryActive('video');
+// Parameters are automatically categorized:
+// - 'audio': Only shown when audio stream is connected
+// - 'video': Only shown when video stream is connected
+// - 'interaction': Only shown when user interaction is enabled
+// - 'general': Always available
+```
+### Audio and Video Integration
+#### Audio Stream Management
+```typescript
+// Set audio stream for analysis
+const audioStream = await navigator.mediaDevices.getUserMedia({
+  audio: {
+    echoCancellation: false,
+    noiseSuppression: false,
+    autoGainControl: false
+  }
+});
+await core.setAudioStream(audioStream);
+// Configure audio analysis with the new namespace API
+// Basic control
+core.audio.setSensitivity(1.5);  // Increase sensitivity (0.5-2.0)
+// Tap tempo for manual BPM control
+core.audio.beat.tap();           // Tap to set tempo
+core.audio.beat.clearTaps();     // Clear tap history
+const tapCount = core.audio.beat.getTapCount();
+// Beat mode control
+core.audio.beat.setMode('auto');       // Automatic beat detection (default)
+core.audio.beat.setMode('manual');     // Manual BPM control
+core.audio.beat.setBPM(120);           // Set manual BPM (60-240)
+const currentBPM = core.audio.beat.getBPM();
+// Beat phase control for fine-tuning
+core.audio.beat.nudge(0.1);      // Nudge phase forward
+core.audio.beat.resetPhase();    // Reset phase to zero
+// Advanced configuration (optional)
+core.audio.advanced.setFFTSize(2048);       // FFT resolution (higher = more accurate)
+core.audio.advanced.setSmoothing(0.8);      // Smoothing factor (0-1)
+core.audio.advanced.setAutoGain(true);      // Auto-gain normalization
+core.audio.advanced.setBeatDetection(true); // Enable beat detection
+core.audio.advanced.setOnsetDetection(true); // Enable onset detection
+// Get current audio state
+const state = core.audio.getState();
+console.log('BPM:', state.currentBPM);
+console.log('Confidence:', state.confidence);
+console.log('Mode:', state.mode);
+console.log('Is Locked:', state.isLocked);
+// Get current audio stream
+const currentStream = core.getAudioStream();
+// Disconnect audio
+await core.setAudioStream(null);
+```
+#### Video Stream Management
+```typescript
+// Set video stream for analysis
+const videoStream = await navigator.mediaDevices.getUserMedia({
+  video: {
+    width: { ideal: 640 },
+    height: { ideal: 480 },
+    frameRate: { ideal: 30 }
+  }
+});
+await core.setVideoStream(videoStream);
+// Video analysis includes:
+// - Real-time frame processing
+// - Frame data access for custom analysis
+// - Brightness and motion detection
+// - Custom computer vision processing
+// Disconnect video
+await core.setVideoStream(null);
+```
+#### Interaction Management
+```typescript
+// Enable or disable user interactions at runtime
+await core.setInteractionEnabled(true);  // Enable mouse, keyboard, and touch
+await core.setInteractionEnabled(false); // Disable all interactions
+// Get current interaction state
+const isInteractionEnabled = core.getInteractionEnabled();
+// Interaction state affects:
+// - Mouse, keyboard, and touch event processing
+// - Parameter visibility (interaction category parameters)
+// - Scene behavior that depends on user input
+// Note: Interaction state is separate from initialization config
+// You can toggle interactions regardless of initial allowUserInteraction value
+// The interaction system is always available for runtime control
+```
+#### Capability Change Monitoring
+```typescript
+// Listen for capability changes
+core.onCapabilitiesChange((capabilities) => {
+  console.log('Capabilities updated:', capabilities);
+  // Update UI based on new capabilities
+  if (capabilities.hasAudio) {
+    showAudioControls();
+  } else {
+    hideAudioControls();
+  }
+  if (capabilities.hasVideo) {
+    showVideoControls();
+  } else {
+    hideVideoControls();
+  }
+  if (capabilities.hasInteraction) {
+    showInteractionControls();
+  } else {
+    hideInteractionControls();
+  }
+});
+```
+### Event Handling and Lifecycle
+#### Core Lifecycle Events
+```typescript
+// Core is ready for operations
+if (core.ready) {
+  // All systems initialized and running
+  console.log('Core is fully operational');
+}
+// Check if parameters are initialized
+if (core.parametersReady) {
+  // Parameter system is ready
+  console.log('Parameters are available');
+  }
+```
+#### Cleanup and Resource Management
+```typescript
+// Destroy instance and clean up all resources
+await core.destroy();
+// This automatically:
+// - Stops all rendering loops
+// - Disconnects audio/video streams
+// - Cleans up WebWorker and IFrame
+// - Releases all event listeners
+// - Clears parameter system
+// - Frees memory resources
+```
+## 🎨 Artist API
+The artist API provides a comprehensive set of tools for creating interactive, audio-reactive, and video-responsive scenes.
+### Canvas and Rendering
+```typescript
+function render(viji) {
+  // Get canvas contexts
+  const ctx = viji.useContext('2d');     // 2D rendering context
+  const gl = viji.useContext('webgl');   // WebGL rendering context
+  // Canvas properties
+  viji.canvas;        // OffscreenCanvas object
+  viji.width;         // Canvas width in pixels
+  viji.height;        // Canvas height in pixels
+  viji.pixelRatio;    // Device pixel ratio for crisp rendering
+  // Example: Draw a responsive circle
+  const centerX = viji.width / 2;
+  const centerY = viji.height / 2;
+  const radius = Math.min(viji.width, viji.height) * 0.1;
+  ctx.fillStyle = '#ff6b6b';
+  ctx.beginPath();
+  ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+  ctx.fill();
+}
+```
+### Timing Information
+The timing system provides FPS-independent timing data for smooth animations:
+```typescript
+function render(viji) {
+  // Timing data (FPS independent)
+  viji.time;          // Elapsed time in seconds since scene start
+  viji.deltaTime;     // Time since last frame in seconds
+  viji.frameCount;    // Total number of frames rendered
+  viji.fps;           // Current frames per second
+  // Example: Smooth animation regardless of frame rate
+  const animationSpeed = 2.0; // rotations per second
+  const rotation = (viji.time * animationSpeed * Math.PI * 2) % (Math.PI * 2);
+  ctx.save();
+  ctx.translate(viji.width / 2, viji.height / 2);
+  ctx.rotate(rotation);
+  ctx.fillRect(-25, -25, 50, 50);
+  ctx.restore();
+}
+```
+### Parameter System
+The parameter system allows artists to define interactive parameters that automatically generate UI controls.
+#### Parameter Definition
+```typescript
+// Define parameters (call once outside render loop)
+const color = viji.color('#ff6b6b', {
+  label: 'Primary Color',
+  description: 'Main color for shapes',
+  group: 'appearance',
+  category: 'general'
+});
+const size = viji.slider(50, {
+  min: 10,
+  max: 150,
+  step: 5,
+  label: 'Shape Size',
+  description: 'Size of shapes in pixels',
+  group: 'appearance',
+  category: 'general'
+});
+const speed = viji.slider(1.0, {
+  min: 0.1,
+  max: 3.0,
+  step: 0.1,
+  label: 'Animation Speed',
+  description: 'Speed of animation in rotations per second',
+  group: 'animation',
+  category: 'general'
+});
+const useAudio = viji.toggle(false, {
+  label: 'Audio Reactive',
+  description: 'Make shapes react to audio input',
+  group: 'audio',
+  category: 'audio'
+});
+const shapeType = viji.select('circle', {
+  options: ['circle', 'square', 'triangle', 'star'],
+  label: 'Shape Type',
+  description: 'Type of shape to draw',
+  group: 'appearance',
+  category: 'general'
+});
+const title = viji.text('My Scene', {
+  label: 'Scene Title',
+  description: 'Title displayed in the scene',
+  group: 'text',
+  category: 'general',
+  maxLength: 50
+});
+const particleCount = viji.number(5, {
+  min: 1,
+  max: 20,
+  step: 1,
+  label: 'Particle Count',
+  description: 'Number of particles to render',
+  group: 'animation',
+  category: 'general'
+});
+```
+#### Parameter Usage in Render Loop
+```typescript
+function render(viji) {
+  const ctx = viji.useContext('2d');
+  // Fast parameter access (proxy-based)
+  ctx.fillStyle = color.value;           // Get current color value
+  const radius = size.value / 2;         // Get current size value
+  const animationSpeed = speed.value;    // Get current speed value
+  // Clear canvas
+  ctx.fillStyle = '#2c3e50';
+  ctx.fillRect(0, 0, viji.width, viji.height);
+  // Draw title
+  ctx.fillStyle = 'white';
+  ctx.font = '20px Arial';
+  ctx.textAlign = 'center';
+  ctx.fillText(title.value, viji.width / 2, 30);
+  // Draw particles
+  for (let i = 0; i < particleCount.value; i++) {
+    const angle = (i / particleCount.value) * Math.PI * 2 + (viji.time * animationSpeed);
+    const x = viji.width / 2 + Math.cos(angle) * 100;
+    const y = viji.height / 2 + Math.sin(angle) * 100;
+    ctx.fillStyle = color.value;
+    ctx.beginPath();
+    switch (shapeType.value) {
+      case 'circle':
+        ctx.arc(x, y, radius, 0, Math.PI * 2);
+        break;
+      case 'square':
+        ctx.rect(x - radius, y - radius, radius * 2, radius * 2);
+        break;
+      case 'triangle':
+        ctx.moveTo(x, y - radius);
+        ctx.lineTo(x - radius, y + radius);
+        ctx.lineTo(x + radius, y + radius);
+        ctx.closePath();
+        break;
+    }
+    ctx.fill();
+  }
+}
+```
+### Audio Analysis
+The audio system provides real-time analysis of audio input with comprehensive frequency and volume data.
+#### Audio API Overview
+```typescript
+function render(viji) {
+  const audio = viji.audio;
+  if (audio.isConnected) {
+    // Volume analysis with smooth values
+    const volume = audio.volume.current;   // 0-1 current volume level (RMS-based)
+    const peak = audio.volume.peak;        // 0-1 peak amplitude (instant)
+    const smooth = audio.volume.smoothed;  // 0-1 smoothed volume (200ms decay)
+    // Frequency bands (0-1 values) with instant and smooth versions
+    const low = audio.bands.low;           // 20-150 Hz (bass/kick range, instant)
+    const lowSmoothed = audio.bands.lowSmoothed; // Smooth low frequency energy
+    const lowMid = audio.bands.lowMid;     // 150-400 Hz
+    const mid = audio.bands.mid;           // 400-2500 Hz (vocals, instruments)
+    const highMid = audio.bands.highMid;   // 2500-8000 Hz (cymbals, hi-hats)
+    const high = audio.bands.high;         // 8000-20000 Hz (air, brilliance)
+    // Automatic beat detection with BPM tracking
+    const beat = audio.beat;
+    // Fast energy curves (300ms decay - primary for most visuals)
+    const kickEnergy = beat.kick;          // 0-1 kick drum energy
+    const snareEnergy = beat.snare;        // 0-1 snare energy
+    const hatEnergy = beat.hat;            // 0-1 hi-hat energy
+    const anyEnergy = beat.any;            // 0-1 any beat type energy
+    // Smoothed energy curves (500ms decay - for slower animations)
+    const kickSmoothed = beat.kickSmoothed;
+    const snareSmoothed = beat.snareSmoothed;
+    const anySmoothed = beat.anySmoothed;
+    // Instant triggers (for advanced use cases)
+    if (beat.triggers.kick) {
+      // Kick drum detected this frame
+      spawnParticle('kick');
+    }
+    // BPM and tempo information
+    const bpm = beat.bpm;                   // Detected BPM (60-180)
+    const phase = beat.phase;               // Beat phase 0-1 within current beat
+    const bar = beat.bar;                   // Current bar number (0-3 for 4/4)
+    const confidence = beat.confidence;     // Detection confidence 0-1
+    const isLocked = beat.isLocked;         // True when beat is locked
+    // Spectral features for advanced audio-reactive effects
+    const brightness = audio.spectral.brightness;  // 0-1 spectral centroid
+    const flatness = audio.spectral.flatness;      // 0-1 spectral flatness (noisiness)
+    const flux = audio.spectral.flux;              // 0-1 spectral flux (change)
+    // Raw frequency data (0-255 values)
+    const frequencyData = audio.getFrequencyData();
+    // Example 1: Smooth beat-reactive animation (primary pattern)
+    const scale = 1 + kickEnergy * 0.5;  // Smooth pulsing with kick
+    const hue = lowSmoothed * 180;       // Smooth color based on low frequencies
+    ctx.save();
+    ctx.translate(viji.width / 2, viji.height / 2);
+    ctx.scale(scale, scale);
+    ctx.fillStyle = `hsl(${hue}, 70%, 60%)`;
+    ctx.fillRect(-25, -25, 50, 50);
+    ctx.restore();
+    // Example 2: Phase-synced rotation
+    const rotation = phase * Math.PI * 2;  // Rotate with beat phase
+    ctx.rotate(rotation);
+  }
+}
+```
+#### Audio-Reactive Scene Example
+```typescript
+// Define audio-reactive parameters
+const audioReactive = viji.toggle(true, {
+  label: 'Audio Reactive',
+  description: 'Make shapes react to audio',
+  group: 'audio',
+  category: 'audio'
+});
+const volumeSensitivity = viji.slider(1.0, {
+  min: 0.1,
+  max: 5.0,
+  step: 0.1,
+  label: 'Volume Sensitivity',
+  description: 'How sensitive shapes are to volume',
+  group: 'audio',
+  category: 'audio'
+});
+const bassReactivity = viji.slider(1.0, {
+  min: 0,
+  max: 3.0,
+  step: 0.1,
+  label: 'Bass Reactivity',
+  description: 'How much shapes react to bass',
+  group: 'audio',
+  category: 'audio'
+});
+function render(viji) {
+  const ctx = viji.useContext('2d');
+  const audio = viji.audio;
+  // Clear canvas
+  ctx.fillStyle = '#2c3e50';
+  ctx.fillRect(0, 0, viji.width, viji.height);
+  if (audioReactive.value && audio.isConnected) {
+    // Audio-reactive animation
+    const volume = audio.volume.current * volumeSensitivity.value;
+    const bass = audio.bands.low * bassReactivity.value;
+    // Scale based on volume
+    const scale = 1 + volume;
+    // Color based on bass
+    const hue = 200 + (bass * 160); // Blue to purple range
+    // Position based on frequency distribution
+    const x = viji.width * (audio.bands.mid + audio.bands.high) / 2;
+    const y = viji.height * (1 - audio.bands.low);
+    ctx.save();
+    ctx.translate(x, y);
+    ctx.scale(scale, scale);
+    ctx.fillStyle = `hsl(${hue}, 80%, 60%)`;
+    ctx.beginPath();
+    ctx.arc(0, 0, 30, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.restore();
+  }
+}
+```
+### Video Analysis
+The video system provides real-time video frame analysis with frame data access for custom processing.
+#### Video API Overview
+```typescript
+function render(viji) {
+  const video = viji.video;
+  if (video.isConnected) {
+    // Video properties
+    const frameWidth = video.frameWidth;
+    const frameHeight = video.frameHeight;
+    const frameRate = video.frameRate;
+    // Current video frame (OffscreenCanvas)
+    if (video.currentFrame) {
+      // Draw video frame as background
+      ctx.globalAlpha = 0.3;
+      ctx.drawImage(video.currentFrame, 0, 0, viji.width, viji.height);
+      ctx.globalAlpha = 1.0;
+    }
+    // Frame data for custom analysis
+    const frameData = video.getFrameData();
+    // Example: Custom video analysis
+    if (frameData) {
+      // Access raw pixel data for custom processing
+      const imageData = frameData.data;
+      const width = frameData.width;
+      const height = frameData.height;
+      // Example: Calculate average brightness
+      let totalBrightness = 0;
+      for (let i = 0; i < imageData.length; i += 4) {
+        const r = imageData[i];
+        const g = imageData[i + 1];
+        const b = imageData[i + 2];
+        totalBrightness += (r + g + b) / 3;
+      }
+      const averageBrightness = totalBrightness / (imageData.length / 4);
+      // Use brightness for effects
+      const brightness = averageBrightness / 255; // Normalize to 0-1
+      // Create brightness-reactive animation
+      ctx.fillStyle = `rgba(255, 255, 255, ${brightness * 0.5})`;
+      ctx.fillRect(0, 0, viji.width, viji.height);
+    }
+  }
+}
+```
+#### Video-Reactive Scene Example
+```typescript
+// Define video-reactive parameters
+const videoReactive = viji.toggle(true, {
+  label: 'Video Reactive',
+  description: 'Make shapes react to video',
+  group: 'video',
+  category: 'video'
+});
+const motionSensitivity = viji.slider(1.0, {
+  min: 0.1,
+  max: 3.0,
+  step: 0.1,
+  label: 'Motion Sensitivity',
+  description: 'How sensitive shapes are to video changes',
+  group: 'video',
+  category: 'video'
+});
+function render(viji) {
+  const ctx = viji.useContext('2d');
+  const video = viji.video;
+  if (videoReactive.value && video.isConnected) {
+    // Video-reactive animation using frame data
+    const frameData = video.getFrameData();
+    if (frameData) {
+      // Simple motion detection (compare with previous frame)
+      // This is a basic example - you can implement more sophisticated analysis
+      const imageData = frameData.data;
+      let motionEnergy = 0;
+      // Calculate motion energy (simplified)
+      for (let i = 0; i < imageData.length; i += 4) {
+        const brightness = (imageData[i] + imageData[i + 1] + imageData[i + 2]) / 3;
+        motionEnergy += brightness;
+      }
+      const normalizedMotion = (motionEnergy / (imageData.length / 4)) / 255;
+      const scale = 1 + (normalizedMotion * motionSensitivity.value);
+      // Create motion-reactive shapes
+      ctx.save();
+      ctx.translate(viji.width / 2, viji.height / 2);
+      ctx.scale(scale, scale);
+      ctx.fillStyle = `hsl(${normalizedMotion * 360}, 70%, 60%)`;
+      ctx.beginPath();
+      ctx.arc(0, 0, 30, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.restore();
+    }
+  }
+}
+```
+### User Interaction
+The interaction system provides comprehensive support for mouse, keyboard, and touch input.
+#### Mouse Interaction
+```typescript
+function render(viji) {
+  const mouse = viji.mouse;
+  // Mouse position (canvas coordinates)
+  if (mouse.isInCanvas) {
+    const x = mouse.x;                   // Current X coordinate
+    const y = mouse.y;                   // Current Y coordinate
+    // Mouse movement
+    const deltaX = mouse.deltaX;         // X movement since last frame
+    const deltaY = mouse.deltaY;         // Y movement since last frame
+    const velocity = mouse.velocity;     // Smoothed velocity { x, y }
+    // Mouse buttons
+    const isPressed = mouse.isPressed;   // Any button currently pressed
+    const leftButton = mouse.leftButton; // Left button state
+    const rightButton = mouse.rightButton; // Right button state
+    const middleButton = mouse.middleButton; // Middle button state
+    // Frame-based events
+    const wasPressed = mouse.wasPressed; // Button was pressed this frame
+    const wasReleased = mouse.wasReleased; // Button was released this frame
+    const wasMoved = mouse.wasMoved;     // Mouse moved this frame
+    // Scroll wheel
+    const wheelDelta = mouse.wheelDelta; // Combined wheel delta
+    const wheelX = mouse.wheelX;         // Horizontal wheel delta
+    const wheelY = mouse.wheelY;         // Vertical wheel delta
+    // Example: Mouse-reactive animation
+    ctx.fillStyle = leftButton ? 'red' : 'blue';
+    ctx.beginPath();
+    ctx.arc(x, y, 20 + Math.abs(velocity.x + velocity.y), 0, Math.PI * 2);
+    ctx.fill();
+  }
+}
+```
+#### Keyboard Interaction
+```typescript
+function render(viji) {
+  const keyboard = viji.keyboard;
+  // Key state queries
+  if (keyboard.isPressed('w')) {
+    // W key is currently pressed
+    console.log('W key is held down');
+  }
+  if (keyboard.wasPressed('space')) {
+    // Space was pressed this frame
+    console.log('Space was pressed!');
+  }
+  if (keyboard.wasReleased('escape')) {
+    // Escape was released this frame
+    console.log('Escape was released!');
+  }
+  // Active key tracking
+  const activeKeys = keyboard.activeKeys;        // Set of currently pressed keys
+  const pressedThisFrame = keyboard.pressedThisFrame; // Set of keys pressed this frame
+  const releasedThisFrame = keyboard.releasedThisFrame; // Set of keys released this frame
+  // Modifier keys
+  const shift = keyboard.shift;          // Shift key is held
+  const ctrl = keyboard.ctrl;            // Ctrl key is held
+  const alt = keyboard.alt;              // Alt key is held
+  const meta = keyboard.meta;            // Meta/Cmd key is held
+  // Recent activity
+  const lastKeyPressed = keyboard.lastKeyPressed;   // Last key that was pressed
+  const lastKeyReleased = keyboard.lastKeyReleased; // Last key that was released
+  // Example: Keyboard-controlled movement
+  let moveX = 0;
+  let moveY = 0;
+  if (keyboard.isPressed('w') || keyboard.isPressed('W')) moveY -= 5;
+  if (keyboard.isPressed('s') || keyboard.isPressed('S')) moveY += 5;
+  if (keyboard.isPressed('a') || keyboard.isPressed('A')) moveX -= 5;
+  if (keyboard.isPressed('d') || keyboard.isPressed('D')) moveX += 5;
+  // Apply movement
+  ctx.save();
+  ctx.translate(moveX, moveY);
+  ctx.fillStyle = 'green';
+  ctx.fillRect(0, 0, 50, 50);
+  ctx.restore();
+}
+```
+#### Touch Interaction
+```typescript
+function render(viji) {
+  const touches = viji.touches;
+  // Touch points
+  for (const touch of touches.points) {
+    const x = touch.x;                   // Touch X coordinate
+    const y = touch.y;                   // Touch Y coordinate
+    const pressure = touch.pressure;     // Pressure (0-1)
+    const radius = touch.radius;         // Touch radius
+    const id = touch.id;                 // Unique touch ID
+    // Movement
+    const deltaX = touch.deltaX;         // X movement since last frame
+    const deltaY = touch.deltaY;         // Y movement since last frame
+    const velocity = touch.velocity;     // Movement velocity { x, y }
+    // Lifecycle
+    const isNew = touch.isNew;           // Touch started this frame
+    const isActive = touch.isActive;     // Touch is currently active
+    const isEnding = touch.isEnding;     // Touch ending this frame
+    // Draw touch point
+    ctx.fillStyle = isNew ? 'red' : isEnding ? 'yellow' : 'blue';
+    ctx.beginPath();
+    ctx.arc(x, y, radius * 2, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  // Touch events
+  const started = touches.started;       // Touches that started this frame
+  const moved = touches.moved;           // Touches that moved this frame
+  const ended = touches.ended;           // Touches that ended this frame
+  // Primary touch (first touch point)
+  const primary = touches.primary;       // Primary touch point or null
+  // Touch gestures
+  const gestures = touches.gestures;
+  if (gestures.isPinching) {
+    const scale = gestures.pinchScale;       // Current pinch scale
+    const delta = gestures.pinchDelta;       // Scale change since last frame
+    // React to pinch gesture
+    ctx.save();
+    ctx.scale(scale, scale);
+    ctx.fillStyle = 'purple';
+    ctx.fillRect(0, 0, 100, 100);
+    ctx.restore();
+  }
+  if (gestures.isRotating) {
+    const angle = gestures.rotationAngle;    // Current rotation angle
+    const delta = gestures.rotationDelta;    // Rotation change since last frame
+    // React to rotation gesture
+    ctx.save();
+    ctx.rotate(angle);
+    ctx.fillStyle = 'orange';
+    ctx.fillRect(-25, -25, 50, 50);
+    ctx.restore();
+  }
+  if (gestures.isPanning) {
+    const panDelta = gestures.panDelta;      // Pan movement { x, y }
+    // React to pan gesture
+    ctx.save();
+    ctx.translate(panDelta.x, panDelta.y);
+    ctx.fillStyle = 'cyan';
+    ctx.fillRect(0, 0, 50, 50);
+    ctx.restore();
+  }
+  if (gestures.isTapping) {
+    const tapCount = gestures.tapCount;      // Number of taps
+    const tapPosition = gestures.tapPosition; // { x, y } tap position
+    // React to tap gesture
+    if (tapPosition) {
+      ctx.fillStyle = 'lime';
+      ctx.beginPath();
+      ctx.arc(tapPosition.x, tapPosition.y, 30, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+}
+```
+#### Device Sensors (Motion, Orientation, Geolocation)
+```typescript
+function render(viji) {
+  // Internal device (current device running the scene)
+  const device = viji.device;
+  // Check if device motion is available
+  if (device.motion?.acceleration) {
+    const accelX = device.motion.acceleration.x;  // m/s² (without gravity)
+    // Example: Shake detection
+    const magnitude = Math.sqrt(
+      accelX**2 + device.motion.acceleration.y**2 + device.motion.acceleration.z**2
+    );
+    if (magnitude > 15) {
+      console.log('Device shaken!');
+    }
+  }
+  // Check if device orientation is available
+  if (device.orientation.gamma !== null) {
+    const tiltLR = device.orientation.gamma;  // -90 to 90 (left/right tilt)
+    const tiltFB = device.orientation.beta;   // -180 to 180 (front/back tilt)
+    // Example: Tilt-based control
+    const moveX = (tiltLR / 90) * 5;
+    ctx.save();
+    ctx.translate(moveX, 0);
+    ctx.fillStyle = 'red';
+    ctx.fillRect(viji.width/2 - 25, viji.height/2 - 25, 50, 50);
+    ctx.restore();
+  }
+  // Check if geolocation is available
+  if (device.geolocation.latitude !== null) {
+    const lat = device.geolocation.latitude;
+    const lon = device.geolocation.longitude;
+    ctx.fillStyle = 'white';
+    ctx.fillText(`Location: ${lat.toFixed(4)}, ${lon.toFixed(4)}`, 10, 30);
+  }
+  // External connected devices (WebRTC/Sockets)
+  viji.devices.forEach((device, index) => {
+    if (device.orientation.gamma !== null) {
+      // Multi-device control example
+      const x = (device.orientation.gamma / 90 + 1) * viji.width / 2;
+      ctx.fillStyle = `hsl(${index * 60}, 70%, 60%)`;
+      ctx.beginPath();
+      ctx.arc(x, 100 + index * 60, 25, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  });
+}
+```
+**Device Sensor Features:**
+- **Motion Sensors**: Accelerometer and gyroscope data for shake detection and motion tracking
+- **Orientation Sensors**: Device tilt for tilt-based controls and compass heading
+- **Geolocation**: GPS coordinates for location-based content
+- **Multi-Device Support**: Connect multiple external devices via WebRTC for installations
+- **Graceful Degradation**: Automatic handling of missing sensors or permissions
+**See `docs/20-device-sensor-system.md` for complete device sensor documentation including WebRTC integration and multi-device installations.**
+## 🎨 P5.js Support
+Viji Core supports **P5.js** as an optional rendering library. P5.js provides familiar creative coding APIs while maintaining all Viji features including audio reactivity, video processing, and parameter management.
+### Enabling P5.js Mode
+Add a single comment at the top of your scene code:
+```javascript
+// @renderer p5
+function setup(viji, p5) {
+  p5.colorMode(p5.HSB);
+}
+function render(viji, p5) {
+  p5.background(220);
+  p5.fill(255, 0, 0);
+  p5.ellipse(viji.mouse.x, viji.mouse.y, 50, 50);
+}
+```
+### What Works
+- ✅ All P5.js drawing functions (shapes, colors, transforms, typography)
+- ✅ P5.js math utilities (`noise()`, `random()`, `map()`, `lerp()`)
+- ✅ P5.js vectors (`p5.Vector` class)
+- ✅ WebGL mode (`p5.WEBGL`)
+- ✅ Full Viji integration (audio, video, parameters, interaction)
+### What Doesn't Work
+- ❌ p5.dom (use Viji parameters instead)
+- ❌ p5.sound (use `viji.audio` instead)
+- ❌ P5.js events (use `viji.mouse`/`keyboard`/`touches` instead)
+- ❌ Direct image loading (use Viji image parameters instead)
+### Audio Reactive P5.js Example
+```javascript
+// @renderer p5
+const audioReactive = viji.toggle(true, {
+  label: 'Audio Reactive',
+  category: 'audio'
+});
+const bassReactivity = viji.slider(1.0, {
+  min: 0,
+  max: 3.0,
+  label: 'Bass Reactivity',
+  category: 'audio'
+});
+function render(viji, p5) {
+  p5.background(0);
+  if (audioReactive.value && viji.audio.isConnected) {
+    const bass = viji.audio.bands.low;
+    const volume = viji.audio.volume.current;
+    const hue = bass * 360 * bassReactivity.value;
+    const size = 100 + volume * 200;
+    p5.colorMode(p5.HSB);
+    p5.fill(hue, 80, 100);
+    p5.ellipse(p5.width / 2, p5.height / 2, size, size);
+  }
+}
+```
+### Image Parameters
+```javascript
+// @renderer p5
+const bgImage = viji.image(null, {
+  label: 'Background Image',
+  group: 'media',
+  accept: 'image/*'
+});
+function render(viji, p5) {
+  p5.background(220);
+  if (bgImage.value) {
+    p5.image(bgImage.value, 0, 0, p5.width, p5.height);
+  }
+  // Draw on top of image
+  p5.fill(255, 0, 0, 128);
+  p5.ellipse(viji.mouse.x, viji.mouse.y, 50, 50);
+}
+```
+### Getting Renderer Type
+```typescript
+const core = new VijiCore({
+  hostContainer: container,
+  sceneCode: sceneCode
+});
+await core.initialize();
+// Check which renderer is being used (from stats, like FPS/resolution)
+const stats = core.getStats();
+const rendererType = stats.rendererType; // 'native' | 'p5'
+```
+### Loading Image Parameters
+```typescript
+core.onParametersDefined((groups) => {
+  groups.forEach(group => {
+    Object.entries(group.parameters).forEach(([name, def]) => {
+      if (def.type === 'image') {
+        // Create file picker
+        const input = createFileInput(name, def);
+        input.addEventListener('change', async (e) => {
+          const file = e.target.files[0];
+          if (file) {
+            await core.setParameter(name, file); // Unified API handles images automatically
+          }
+        });
+      }
+    });
+  });
+});
+```
+**See `docs/16-p5js-integration.md` for comprehensive documentation including migration guides, troubleshooting, and advanced examples.**
+## 🏗️ Architecture
+### Security Model
+The core implements a comprehensive security model to ensure safe execution of artist code:
+- **IFrame Isolation**: Complete separation from host environment with sandboxed execution
+- **WebWorker Sandboxing**: Artist code runs with controlled API access only
+- **Blob URL Creation**: Secure worker and IFrame creation from blob URLs
+- **Resource Protection**: Memory leaks and errors cannot affect main application
+- **Controlled Communication**: Optimized message passing with validation
+### Performance Features
+The core provides extensive performance optimization capabilities:
+- **Configurable Frame Rates**: Full (60fps) or half (30fps) modes for performance tuning
+- **Resolution Scaling**: Fractional (0.1-1.0) or explicit canvas dimensions
+- **Adaptive Optimization**: Automatic performance tuning based on hardware capabilities
+- **Efficient Communication**: Optimized message passing between components
+- **Memory Management**: Automatic resource cleanup and memory leak prevention
+### Multi-Instance Support
+The core supports multiple concurrent instances for complex applications:
+```typescript
+// Main scene with full features
+const mainCore = new VijiCore({
+  hostContainer: document.getElementById('main-scene'),
+  resolution: { width: 1920, height: 1080 },
+  frameRateMode: 'full',
+  allowUserInteraction: true,
+  audioStream: sharedAudioStream,
+  videoStream: sharedVideoStream
+});
+// Preview instance with reduced features
+const previewCore = new VijiCore({
+  hostContainer: document.getElementById('preview'),
+  resolution: 0.25, // 25% resolution for performance
+  frameRateMode: 'half',
+  noInputs: true,
+  allowUserInteraction: false,
+  audioStream: sharedAudioStream // Shared efficiently across instances
+});
+// Thumbnail instance for gallery view
+const thumbnailCore = new VijiCore({
+  hostContainer: document.getElementById('thumbnail'),
+  resolution: 0.1, // 10% resolution
+  frameRateMode: 'half',
+  noInputs: true,
+  allowUserInteraction: false
+});
+// To change scenes, create a new instance and destroy the old one
+const newCore = new VijiCore({
+  hostContainer: document.getElementById('scene-host'),
+  sceneCode: newSceneCode,
+  audioStream: sharedAudioStream,
+  videoStream: sharedVideoStream
+});
+// Automatic comprehensive cleanup when destroyed
+await oldCore.destroy();
+```
+## 🔍 Error Handling
+The core provides comprehensive error handling with detailed error information:
+```typescript
+import { VijiCoreError } from '@viji-dev/core';
+try {
+  const core = new VijiCore(config);
+  await core.initialize();
+} catch (error) {
+  if (error instanceof VijiCoreError) {
+    console.error(`Core error [${error.code}]:`, error.message);
+    console.error('Error context:', error.context);
+    // Handle specific error types
+    switch (error.code) {
+      case 'INVALID_CONFIG':
+        console.error('Configuration is invalid:', error.context);
+        break;
+      case 'INITIALIZATION_ERROR':
+        console.error('Failed to initialize core:', error.context);
+        break;
+      case 'CORE_NOT_READY':
+        console.error('Core is not ready for operations');
+        break;
+      case 'INSTANCE_DESTROYED':
+        console.error('Core instance has been destroyed');
+        break;
+      case 'PARAMETERS_NOT_INITIALIZED':
+        console.error('Parameter system not yet initialized');
+        break;
+      case 'UNKNOWN_PARAMETER':
+        console.error('Parameter not found:', error.context);
+        break;
+    }
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+**Common Error Codes:**
+- `INVALID_CONFIG` - Configuration validation failed
+- `INITIALIZATION_ERROR` - Failed to initialize core components
+- `CORE_NOT_READY` - Operation attempted before ready
+- `INSTANCE_DESTROYED` - Operation attempted after destroy
+- `PARAMETERS_NOT_INITIALIZED` - Parameters not yet available
+- `UNKNOWN_PARAMETER` - Parameter not found
+- `CONCURRENT_INITIALIZATION` - Multiple initialization attempts
+- `MANAGER_NOT_READY` - Internal component not available
+## 🧪 Development
+```bash
+# Install dependencies
+npm install
+# Build the package
+npm run build
+# Run tests
+npm test
+# Development build (watch mode)
+npm run dev
+# Type checking
+npm run type-check
+# Linting
+npm run lint
+```
+## 📚 Examples
+The package includes comprehensive examples in the `/example` directory:
+- **Basic Scene Creation**: Simple animated shapes with parameters
+- **Audio-Reactive Scenes**: Scenes that respond to audio input
+- **Video-Reactive Scenes**: Scenes that respond to video analysis
+- **Interactive Scenes**: Mouse, keyboard, and touch interaction
+- **Parameter System**: Complete parameter definition and UI generation
+- **Multi-Instance**: Multiple concurrent scene instances
+## 🎯 Use Cases
+### Platform Integration
+The core integrates seamlessly with the Viji platform, providing scene execution while the platform handles UI, user management, and social features.
+### SDK Development
+The core serves as the execution foundation for the Viji SDK, ensuring identical behavior between development and platform environments.
+### Standalone Applications
+Use the core directly in custom applications for creative scene rendering with full feature support.
+## 📄 License
+Copyright (c) 2025 Artem Verkhovskiy and Dmitry Manoilenko.
+All rights reserved - see the LICENSE file for details.
+## Contributor License Agreement
+By contributing, you agree to the [CLA](./CLA.md).
+Please also confirm your agreement by filling out this short [form](https://forms.gle/A49WTz8nj5b99Yev7).
+---
 **Viji Core** - Universal execution engine for creative scenes across all contexts.