@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/src/core/CanvasManager.js

@@ -1,217 +1,110 @@
 /**
- * Dead Simple Canvas Manager - Just hide/show containers + fresh engines
- * No canvas destruction - HTML canvases stay put, just switch visibility
+ * CanvasManager - Creates and manages 5-layer canvas architecture per system.
+ *
+ * Provides the API surface expected by VIB3Engine:
+ *   constructor(containerId)
+ *   createSystemCanvases(systemName) -> string[]
+ *   registerContext(canvasId, gl)
+ *   destroy()
  */
 
 export class CanvasManager {
-  constructor() {
-    this.currentSystem = null;
-    this.currentEngine = null;
-  }
-
-  async switchToSystem(systemName, engineClasses) {
-    console.log(`🔄 DESTROY OLD → CREATE NEW: ${systemName}`);
-    
-    // STEP 1: DESTROY current engine completely
-    if (this.currentEngine) {
-      if (this.currentEngine.setActive) {
-        this.currentEngine.setActive(false);
-      }
-      if (this.currentEngine.destroy) {
-        this.currentEngine.destroy();
-      }
-      console.log('💥 Old engine destroyed');
-    }
-    
-    // STEP 2: DESTROY old WebGL contexts 
-    this.destroyOldWebGLContexts();
-    
-    // STEP 3: DESTROY all canvases + CREATE 5 fresh ones
-    this.destroyAllCanvasesAndCreateFresh(systemName);
-    
-    // STEP 4: CREATE fresh engine
-    const engine = await this.createFreshEngine(systemName, engineClasses);
-    
-    // STEP 5: Start new engine
-    if (engine && engine.setActive) {
-      engine.setActive(true);
+    constructor(containerId = 'vib3-container') {
+        this.containerId = containerId;
+        this.container = (typeof document !== 'undefined')
+            ? document.getElementById(containerId)
+            : null;
+        this.currentSystem = null;
+        this.createdCanvases = [];
+        this.registeredContexts = new Map();
     }
-    
-    this.currentSystem = systemName;
-    this.currentEngine = engine;
-    console.log(`✅ DESTROY → CREATE complete: ${systemName} ready`);
-    return engine;
-  }
 
-  destroyOldWebGLContexts() {
-    console.log('💥 COMPLETE DESTRUCTION: WebGL contexts + old system cleanup...');
-    
-    // STEP 1: Kill all WebGL contexts first
-    const allCanvases = document.querySelectorAll('canvas');
-    let destroyedCount = 0;
-    
-    allCanvases.forEach(canvas => {
-      // Get any existing WebGL context
-      const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
-      if (gl) {
-        // Force context loss
-        const loseContextExt = gl.getExtension('WEBGL_lose_context');
-        if (loseContextExt) {
-          loseContextExt.loseContext();
-          destroyedCount++;
+    /**
+     * Create 5 canvases with system-appropriate IDs inside the container.
+     * Returns the array of canvas IDs created.
+     */
+    createSystemCanvases(systemName) {
+        // Tear down previous canvases
+        this._removeCreatedCanvases();
+
+        const canvasIds = this._getCanvasIdsForSystem(systemName);
+
+        if (this.container) {
+            const viewWidth = this.container.clientWidth || (typeof window !== 'undefined' ? window.innerWidth : 800);
+            const viewHeight = this.container.clientHeight || (typeof window !== 'undefined' ? window.innerHeight : 600);
+            const dpr = (typeof window !== 'undefined') ? Math.min(window.devicePixelRatio || 1, 2) : 1;
+
+            canvasIds.forEach((canvasId, index) => {
+                const canvas = document.createElement('canvas');
+                canvas.id = canvasId;
+                canvas.className = 'visualization-canvas';
+                canvas.style.position = 'absolute';
+                canvas.style.top = '0';
+                canvas.style.left = '0';
+                canvas.style.width = '100%';
+                canvas.style.height = '100%';
+                canvas.style.zIndex = String(index + 1);
+                canvas.width = viewWidth * dpr;
+                canvas.height = viewHeight * dpr;
+                this.container.appendChild(canvas);
+                this.createdCanvases.push(canvas);
+            });
         }
-      }
-    });
-    
-    // STEP 2: Clear all global engine references (old system cleanup)
-    if (window.engine) {
-      console.log('💥 Clearing window.engine');
-      window.engine = null;
-    }
-    if (window.quantumEngine) {
-      console.log('💥 Clearing window.quantumEngine');
-      window.quantumEngine = null;
-    }
-    if (window.holographicSystem) {
-      console.log('💥 Clearing window.holographicSystem');
-      window.holographicSystem = null;
+
+        this.currentSystem = systemName;
+        return canvasIds;
     }
-    if (window.polychoraSystem) {
-      console.log('💥 Clearing window.polychoraSystem');
-      window.polychoraSystem = null;
+
+    /**
+     * Track a WebGL context so we can force-lose it during cleanup.
+     */
+    registerContext(canvasId, gl) {
+        this.registeredContexts.set(canvasId, gl);
     }
-    
-    console.log(`💥 DESTRUCTION COMPLETE: ${destroyedCount} WebGL contexts destroyed, all engine refs cleared`);
-  }
 
-  destroyAllCanvasesAndCreateFresh(systemName) {
-    console.log('💥 DESTROYING ALL CANVASES + CREATING 5 FRESH ONES');
-    
-    // STEP 1: DESTROY all existing canvases completely
-    const allCanvases = document.querySelectorAll('canvas');
-    allCanvases.forEach(canvas => canvas.remove());
-    console.log(`💥 Destroyed ${allCanvases.length} old canvases`);
-    
-    // STEP 2: Clear all containers
-    const containers = ['vib34dLayers', 'quantumLayers', 'holographicLayers', 'polychoraLayers'];
-    containers.forEach(containerId => {
-      const container = document.getElementById(containerId);
-      if (container) {
-        container.innerHTML = '';
-        container.style.display = 'none';
-      }
-    });
-    
-    // STEP 3: CREATE 5 fresh canvases for the new system
-    const targetId = systemName === 'faceted' ? 'vib34dLayers' : `${systemName}Layers`;
-    const targetContainer = document.getElementById(targetId);
-    
-    if (!targetContainer) {
-      console.error(`❌ Container ${targetId} not found`);
-      return;
+    /**
+     * Destroy all managed canvases and force-lose registered WebGL contexts.
+     */
+    destroy() {
+        // Force-lose all tracked contexts
+        for (const [, gl] of this.registeredContexts) {
+            try {
+                const ext = gl.getExtension('WEBGL_lose_context');
+                if (ext) ext.loseContext();
+            } catch (_) { /* context may already be lost */ }
+        }
+        this.registeredContexts.clear();
+
+        this._removeCreatedCanvases();
+        this.currentSystem = null;
     }
-    
-    // Create canvas IDs for this system
-    const canvasIds = this.getCanvasIdsForSystem(systemName);
-    
-    // Create 5 fresh canvases
-    canvasIds.forEach((canvasId, index) => {
-      const canvas = document.createElement('canvas');
-      canvas.id = canvasId;
-      canvas.className = 'visualization-canvas';
-      canvas.style.position = 'absolute';
-      canvas.style.top = '0';
-      canvas.style.left = '0';
-      canvas.style.width = '100%';
-      canvas.style.height = '100%';
-      canvas.style.zIndex = index + 1;
-      
-      // Set canvas dimensions
-      const viewWidth = window.innerWidth;
-      const viewHeight = window.innerHeight;
-      const dpr = Math.min(window.devicePixelRatio || 1, 2);
-      canvas.width = viewWidth * dpr;
-      canvas.height = viewHeight * dpr;
-      
-      targetContainer.appendChild(canvas);
-    });
-    
-    // Show the target container
-    targetContainer.style.display = 'block';
-    targetContainer.style.visibility = 'visible';
-    targetContainer.style.opacity = '1';
-    
-    console.log(`✅ Created 5 fresh canvases for ${systemName}: ${canvasIds.join(', ')}`);
-  }
-  
-  getCanvasIdsForSystem(systemName) {
-    const baseIds = ['background-canvas', 'shadow-canvas', 'content-canvas', 'highlight-canvas', 'accent-canvas'];
-    
-    switch (systemName) {
-      case 'faceted':
-        return baseIds;
-      case 'quantum':
-        return baseIds.map(id => `quantum-${id}`);
-      case 'holographic':
-        return baseIds.map(id => `holo-${id}`);
-      case 'polychora':
-        return baseIds.map(id => `polychora-${id}`);
-      default:
-        return baseIds;
+
+    // ── Private helpers ──
+
+    _removeCreatedCanvases() {
+        for (const canvas of this.createdCanvases) {
+            canvas.remove();
+        }
+        this.createdCanvases = [];
     }
-  }
-  
-  async createFreshEngine(systemName, engineClasses) {
-    console.log(`🚀 Creating fresh ${systemName} engine`);
-    
-    let engine = null;
-    
-    try {
-      switch(systemName) {
-        case 'faceted':
-          if (engineClasses.VIB34DIntegratedEngine) {
-            engine = new engineClasses.VIB34DIntegratedEngine();
-            window.engine = engine;
-            console.log('✅ Fresh Faceted engine');
-          }
-          break;
-          
-        case 'quantum':
-          if (engineClasses.QuantumEngine) {
-            engine = new engineClasses.QuantumEngine();
-            window.quantumEngine = engine;
-            console.log('✅ Fresh Quantum engine');
-          }
-          break;
-          
-        case 'holographic':
-          if (engineClasses.RealHolographicSystem) {
-            engine = new engineClasses.RealHolographicSystem();
-            window.holographicSystem = engine;
-            console.log('✅ Fresh Holographic engine');
-          }
-          break;
-          
-        case 'polychora':
-          // POLYCHORA: TBD placeholder - not production ready
-          // Engine disabled until system is complete
-          console.warn('⚠️ Polychora system is TBD placeholder - not available');
-          if (false && engineClasses.NewPolychoraEngine) {
-            engine = new engineClasses.NewPolychoraEngine();
-            window.newPolychoraEngine = engine;
-            console.log('✅ Fresh TRUE 4D Polychora Engine with VIB34D DNA');
-          }
-          break;
-          
-        default:
-          console.error(`❌ Unknown system: ${systemName}`);
-      }
-      
-    } catch (error) {
-      console.error(`💥 Engine creation failed for ${systemName}:`, error);
-      engine = null;
+
+    _getCanvasIdsForSystem(systemName) {
+        const baseIds = [
+            'background-canvas', 'shadow-canvas', 'content-canvas',
+            'highlight-canvas', 'accent-canvas'
+        ];
+
+        switch (systemName) {
+            case 'faceted':
+                return baseIds;
+            case 'quantum':
+                return baseIds.map(id => `quantum-${id}`);
+            case 'holographic':
+                return baseIds.map(id => `holo-${id}`);
+            case 'polychora':
+                return baseIds.map(id => `polychora-${id}`);
+            default:
+                return baseIds;
+        }
     }
-    
-    return engine;
-  }
-}
+}

package/src/core/ErrorReporter.js

@@ -86,7 +86,7 @@ export class ErrorReporter {
             timestamp: Date.now(),
             url: typeof location !== 'undefined' ? location.pathname : '',
             userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
-            sdkVersion: '2.0.0',
+            sdkVersion: '2.0.3',
         };
 
         // Custom callback takes priority

package/src/core/Parameters.js

@@ -272,7 +272,7 @@ export class ParameterManager {
     exportConfiguration() {
         return {
             type: 'vib34d-integrated-config',
-            version: '1.0.0',
+            version: '2.0.3',
             timestamp: new Date().toISOString(),
             name: `VIB34D Config ${new Date().toLocaleDateString()}`,
             parameters: { ...this.params }

package/src/core/VIB3Engine.js

@@ -15,6 +15,7 @@ import { RealHolographicSystem } from '../holograms/RealHolographicSystem.js';
 import { ReactivityManager } from '../reactivity/ReactivityManager.js';
 import { ReactivityConfig } from '../reactivity/ReactivityConfig.js';
 import { SpatialInputSystem } from '../reactivity/SpatialInputSystem.js';
+import { VitalitySystem } from './VitalitySystem.js';
 
 export class VIB3Engine {
     /**
@@ -25,7 +26,7 @@ export class VIB3Engine {
      */
     constructor(options = {}) {
         this.activeSystem = null; // Only one system active at a time
-        this.currentSystemName = 'quantum';
+        this.currentSystemName = options.system || 'quantum';
         this.parameters = new ParameterManager();
         this.initialized = false;
         this.canvasManager = null;
@@ -36,6 +37,9 @@ export class VIB3Engine {
         /** @type {boolean} Debug mode */
         this.debug = options.debug || false;
 
+        /** @type {VitalitySystem} Global breathing rhythm */
+        this.vitality = new VitalitySystem();
+
         /** @type {ReactivityManager} Reactivity system for audio/tilt/interaction */
         this.reactivity = new ReactivityManager((name, value) => {
             this.parameters.setParameter(name, value);
@@ -78,16 +82,44 @@ export class VIB3Engine {
         }
 
         // Initialize starting system
-        await this.switchSystem(this.currentSystemName);
+        const systemOk = await this.switchSystem(this.currentSystemName);
+        if (!systemOk) {
+            console.error(`VIB3+ Engine: Failed to create initial system "${this.currentSystemName}"`);
+            return false;
+        }
 
         // Sync base parameters to reactivity manager
         this.reactivity.setBaseParameters(this.parameters.getAllParameters());
 
+        // Start vitality system
+        this.vitality.start();
+
+        // Start global loop to drive vitality updates
+        this._startGlobalLoop();
+
         this.initialized = true;
         console.log('VIB3+ Engine initialized');
         return true;
     }
 
+    _startGlobalLoop() {
+        this._globalLoopActive = true;
+        const loop = () => {
+            if (!this._globalLoopActive) return;
+            if (this.initialized) {
+                // Update breath cycle
+                const breath = this.vitality.update();
+
+                // Push breath to current system
+                if (this.activeSystem && this.activeSystem.updateParameters) {
+                    this.activeSystem.updateParameters({ breath });
+                }
+            }
+            this._globalRafId = requestAnimationFrame(loop);
+        };
+        this._globalRafId = requestAnimationFrame(loop);
+    }
+
     /**
      * Create and initialize a specific system
      * CRITICAL: Engines find canvases by ID in DOM, not passed as parameters!
@@ -139,7 +171,7 @@ export class VIB3Engine {
                         }
                     }
 
-                    const facetedSuccess = system.initialize();
+                    const facetedSuccess = await system.initialize();
                     if (!facetedSuccess) {
                         throw new Error('Faceted system initialization failed');
                     }
@@ -245,6 +277,17 @@ export class VIB3Engine {
 
         if (this.activeSystem && this.activeSystem.updateParameters) {
             this.activeSystem.updateParameters(params);
+        } else if (this.debug && this.activeSystem && !this.activeSystem.updateParameters) {
+            console.warn('VIB3+ Engine [debug]: activeSystem missing updateParameters() method');
+        } else if (this.debug && !this.activeSystem) {
+            console.warn('VIB3+ Engine [debug]: updateCurrentSystemParameters() called with no activeSystem');
+        }
+
+        // Notify parameter change listeners
+        if (this._parameterListeners && this._parameterListeners.size > 0) {
+            for (const listener of this._parameterListeners) {
+                try { listener(params); } catch (_) { /* listener error */ }
+            }
         }
     }
 
@@ -534,7 +577,7 @@ export class VIB3Engine {
             spatialActive: this.spatialInput.enabled,
             backend: this.getActiveBackendType(),
             timestamp: new Date().toISOString(),
-            version: '1.2.0'
+            version: '2.0.3'
         };
     }
 
@@ -604,10 +647,56 @@ export class VIB3Engine {
         }
     }
 
+    // ========================================================================
+    // Convenience Methods (dogfood feedback)
+    // ========================================================================
+
+    /**
+     * Create a parameter update callback for use with creative modules.
+     * Returns (name, value) => void that calls setParameter internally.
+     * Eliminates boilerplate: `(name, value) => engine.setParameter(name, value)`.
+     * @returns {(name: string, value: number) => void}
+     */
+    createParameterCallback() {
+        return (name, value) => this.setParameter(name, value);
+    }
+
+    /**
+     * Get current breath value from VitalitySystem (0-1).
+     * Avoids reaching into engine.vitality.getBreath() directly.
+     * @returns {number}
+     */
+    getBreath() {
+        return this.vitality.getBreath();
+    }
+
+    /**
+     * Register a listener for parameter changes.
+     * Callback receives the full parameter object after each change.
+     * @param {(params: object) => void} callback
+     * @returns {() => void} Unsubscribe function
+     */
+    onParameterChange(callback) {
+        if (!this._parameterListeners) {
+            this._parameterListeners = new Set();
+        }
+        this._parameterListeners.add(callback);
+        return () => this._parameterListeners.delete(callback);
+    }
+
     /**
      * Destroy engine and clean up
      */
     destroy() {
+        // Cancel global breath loop
+        this._globalLoopActive = false;
+        if (this._globalRafId) {
+            cancelAnimationFrame(this._globalRafId);
+            this._globalRafId = null;
+        }
+
+        this.vitality.stop();
+
         // Stop and destroy spatial input
         if (this.spatialInput) {
             this.spatialInput.destroy();

package/src/core/VitalitySystem.js

@@ -0,0 +1,53 @@
+/**
+ * VitalitySystem.js
+ * Manages the "breath of life" for the VIB3+ Engine.
+ * Generates a global rhythmic breath cycle (Exhale/Evoke) that modulates
+ * all visualization systems for a unified, organic feel.
+ */
+export class VitalitySystem {
+    constructor() {
+        this.time = 0;
+        this.breath = 0;
+        this.cycleDuration = 6000; // 6 seconds per breath
+        this.isRunning = false;
+    }
+
+    start() {
+        this.isRunning = true;
+        this.startTime = Date.now();
+    }
+
+    stop() {
+        this.isRunning = false;
+    }
+
+    /**
+     * Update the breath cycle.
+     * Returns a normalized 0-1 value representing the breath phase.
+     * 0 = Empty, 1 = Full
+     * Uses a sine wave for smooth organic motion.
+     */
+    update(deltaTime) {
+        if (!this.isRunning) return 0;
+
+        const now = Date.now();
+        const elapsed = now - this.startTime;
+
+        // 0 to 2PI over cycleDuration
+        const phase = (elapsed % this.cycleDuration) / this.cycleDuration;
+        const angle = phase * Math.PI * 2;
+
+        // Smooth sine wave: -1 to 1 -> 0 to 1
+        // We use -cos to start at 0 (empty), go to 1 (full), back to 0
+        this.breath = (1.0 - Math.cos(angle)) * 0.5;
+
+        // Add a small "pause" at the top and bottom for realism?
+        // For now, pure sine is hypnotic enough.
+
+        return this.breath;
+    }
+
+    getBreath() {
+        return this.breath;
+    }
+}

package/src/core/index.js

@@ -0,0 +1,18 @@
+/**
+ * VIB3+ Core Module
+ * @module core
+ */
+
+export { VIB3Engine } from './VIB3Engine.js';
+export { CanvasManager } from './CanvasManager.js';
+export { ParameterManager } from './Parameters.js';
+export { ParameterMapper } from './ParameterMapper.js';
+export { ErrorReporter } from './ErrorReporter.js';
+export { VitalitySystem } from './VitalitySystem.js';
+export { UnifiedResourceManager } from './UnifiedResourceManager.js';
+export {
+    RendererContract,
+    RendererContractAdapter,
+    verifyRendererContract,
+    ResourceManagerContract
+} from './RendererContracts.js';

package/src/core/renderers/FacetedRendererAdapter.js

@@ -8,18 +8,19 @@ export class FacetedRendererAdapter extends RendererContract {
     }
 
     init(context = {}) {
-        const initialized = this.system.initialize(context.canvas ?? null);
-        if (!initialized) {
-            throw new Error('Faceted renderer failed to initialize.');
-        }
+        return this.system.init ? this.system.init(context) : true;
     }
 
-    resize() {
-        this.system.setupCanvasSize();
+    resize(width, height, pixelRatio = 1) {
+        if (this.system.resize) {
+            this.system.resize(width, height, pixelRatio);
+        }
     }
 
-    render() {
-        this.system.renderFrame();
+    render(frameState) {
+        if (this.system.render) {
+            this.system.render(frameState);
+        }
     }
 
     setActive(active) {
@@ -27,6 +28,6 @@ export class FacetedRendererAdapter extends RendererContract {
     }
 
     dispose() {
-        this.system.stop();
+        this.system.dispose();
     }
 }

package/src/core/renderers/HolographicRendererAdapter.js

@@ -1,22 +1,26 @@
 import { RendererContract } from '../RendererContracts.js';
-import { HolographicSystem } from '../../holograms/HolographicSystem.js';
+import { RealHolographicSystem } from '../../holograms/RealHolographicSystem.js';
 
 export class HolographicRendererAdapter extends RendererContract {
-    constructor(system = new HolographicSystem({ autoStart: false })) {
+    constructor(system = new RealHolographicSystem({ autoStart: false })) {
         super();
         this.system = system;
     }
 
-    init() {
-        return true;
+    init(context = {}) {
+        return this.system.init ? this.system.init(context) : true;
     }
 
-    resize() {
-        // Visualizers handle their own resizing.
+    resize(width, height, pixelRatio = 1) {
+        if (this.system.resize) {
+            this.system.resize(width, height, pixelRatio);
+        }
     }
 
-    render() {
-        this.system.renderFrame();
+    render(frameState) {
+        if (this.system.render) {
+            this.system.render(frameState);
+        }
     }
 
     setActive(active) {
@@ -24,6 +28,6 @@ export class HolographicRendererAdapter extends RendererContract {
     }
 
     dispose() {
-        this.system.setActive(false);
+        this.system.dispose();
     }
 }