@vib3code/sdk 2.0.1

package/src/core/Parameters.js

@@ -0,0 +1,396 @@
+/**
+ * VIB34D Parameter Management System
+ * Unified parameter control for both holographic and polytopal systems
+ */
+
+export class ParameterManager {
+    constructor() {
+        // Default parameter set combining both systems
+        this.params = {
+            // Current variation
+            variation: 0,
+            
+            // 6D Rotation - 3D space rotations
+            rot4dXY: 0.0,      // X-Y plane rotation (-6.28 to 6.28)
+            rot4dXZ: 0.0,      // X-Z plane rotation (-6.28 to 6.28)
+            rot4dYZ: 0.0,      // Y-Z plane rotation (-6.28 to 6.28)
+            // 4D hyperspace rotations
+            rot4dXW: 0.0,      // X-W plane rotation (-6.28 to 6.28)
+            rot4dYW: 0.0,      // Y-W plane rotation (-6.28 to 6.28)
+            rot4dZW: 0.0,      // Z-W plane rotation (-6.28 to 6.28)
+            dimension: 3.5,    // Dimensional level (3.0 to 4.5)
+            
+            // Holographic Visualization
+            gridDensity: 15,   // Geometric detail (4 to 30)
+            morphFactor: 1.0,  // Shape transformation (0 to 2)
+            chaos: 0.2,        // Randomization level (0 to 1)
+            speed: 1.0,        // Animation speed (0.1 to 3)
+            hue: 200,          // Color rotation (0 to 360)
+            intensity: 0.5,    // Visual intensity (0 to 1)
+            saturation: 0.8,   // Color saturation (0 to 1)
+            
+            // Geometry selection
+            geometry: 0        // Current geometry type (0-7)
+        };
+        
+        // Parameter definitions for validation and UI
+        this.parameterDefs = {
+            variation: { min: 0, max: 99, step: 1, type: 'int' },
+            // 3D Space Rotations
+            rot4dXY: { min: -6.28, max: 6.28, step: 0.01, type: 'float' },
+            rot4dXZ: { min: -6.28, max: 6.28, step: 0.01, type: 'float' },
+            rot4dYZ: { min: -6.28, max: 6.28, step: 0.01, type: 'float' },
+            // 4D Hyperspace Rotations
+            rot4dXW: { min: -2, max: 2, step: 0.01, type: 'float' },
+            rot4dYW: { min: -2, max: 2, step: 0.01, type: 'float' },
+            rot4dZW: { min: -2, max: 2, step: 0.01, type: 'float' },
+            dimension: { min: 3.0, max: 4.5, step: 0.01, type: 'float' },
+            gridDensity: { min: 4, max: 100, step: 0.1, type: 'float' },
+            morphFactor: { min: 0, max: 2, step: 0.01, type: 'float' },
+            chaos: { min: 0, max: 1, step: 0.01, type: 'float' },
+            speed: { min: 0.1, max: 3, step: 0.01, type: 'float' },
+            hue: { min: 0, max: 360, step: 1, type: 'int' },
+            intensity: { min: 0, max: 1, step: 0.01, type: 'float' },
+            saturation: { min: 0, max: 1, step: 0.01, type: 'float' },
+            geometry: { min: 0, max: 23, step: 1, type: 'int' }
+        };
+        
+        // Default parameter backup for reset
+        this.defaults = { ...this.params };
+    }
+    
+    /**
+     * Get all current parameters
+     */
+    getAllParameters() {
+        return { ...this.params };
+    }
+    
+    /**
+     * Set a specific parameter with validation
+     */
+    setParameter(name, value) {
+        if (this.parameterDefs[name]) {
+            const def = this.parameterDefs[name];
+
+            // Coerce to number and reject NaN/Infinity
+            value = Number(value);
+            if (!Number.isFinite(value)) {
+                console.warn(`Parameter "${name}" received non-finite value, ignoring`);
+                return false;
+            }
+
+            // Clamp value to valid range
+            value = Math.max(def.min, Math.min(def.max, value));
+
+            // Apply type conversion
+            if (def.type === 'int') {
+                value = Math.round(value);
+            }
+
+            this.params[name] = value;
+            return true;
+        }
+
+        console.warn(`Unknown parameter: ${name}`);
+        return false;
+    }
+    
+    /**
+     * Set multiple parameters at once
+     */
+    setParameters(paramObj) {
+        for (const [name, value] of Object.entries(paramObj)) {
+            this.setParameter(name, value);
+        }
+    }
+    
+    /**
+     * Get a specific parameter value
+     */
+    getParameter(name) {
+        return this.params[name];
+    }
+    
+    /**
+     * Set geometry type with validation
+     */
+    setGeometry(geometryType) {
+        this.setParameter('geometry', geometryType);
+    }
+    
+    /**
+     * Update parameters from UI controls
+     */
+    updateFromControls() {
+        const controlIds = [
+            'variationSlider', 'rot4dXW', 'rot4dYW', 'rot4dZW', 'dimension',
+            'gridDensity', 'morphFactor', 'chaos', 'speed', 'hue'
+        ];
+        
+        controlIds.forEach(id => {
+            const element = document.getElementById(id);
+            if (element) {
+                const value = parseFloat(element.value);
+                if (!Number.isFinite(value)) return;
+
+                // Map slider IDs to parameter names
+                let paramName = id;
+                if (id === 'variationSlider') {
+                    paramName = 'variation';
+                }
+
+                this.setParameter(paramName, value);
+            }
+        });
+    }
+    
+    /**
+     * Update UI display values from current parameters
+     */
+    updateDisplayValues() {
+        // Update slider values
+        this.updateSliderValue('variationSlider', this.params.variation);
+        this.updateSliderValue('rot4dXW', this.params.rot4dXW);
+        this.updateSliderValue('rot4dYW', this.params.rot4dYW);
+        this.updateSliderValue('rot4dZW', this.params.rot4dZW);
+        this.updateSliderValue('dimension', this.params.dimension);
+        this.updateSliderValue('gridDensity', this.params.gridDensity);
+        this.updateSliderValue('morphFactor', this.params.morphFactor);
+        this.updateSliderValue('chaos', this.params.chaos);
+        this.updateSliderValue('speed', this.params.speed);
+        this.updateSliderValue('hue', this.params.hue);
+        
+        // Update display texts
+        this.updateDisplayText('rot4dXWDisplay', this.params.rot4dXW.toFixed(2));
+        this.updateDisplayText('rot4dYWDisplay', this.params.rot4dYW.toFixed(2));
+        this.updateDisplayText('rot4dZWDisplay', this.params.rot4dZW.toFixed(2));
+        this.updateDisplayText('dimensionDisplay', this.params.dimension.toFixed(2));
+        this.updateDisplayText('gridDensityDisplay', this.params.gridDensity.toFixed(1));
+        this.updateDisplayText('morphFactorDisplay', this.params.morphFactor.toFixed(2));
+        this.updateDisplayText('chaosDisplay', this.params.chaos.toFixed(2));
+        this.updateDisplayText('speedDisplay', this.params.speed.toFixed(2));
+        this.updateDisplayText('hueDisplay', this.params.hue + '°');
+        
+        // Update variation info
+        this.updateVariationInfo();
+        
+        // Update geometry preset buttons
+        this.updateGeometryButtons();
+    }
+    
+    updateSliderValue(id, value) {
+        const element = document.getElementById(id);
+        if (element) {
+            element.value = value;
+        }
+    }
+    
+    updateDisplayText(id, text) {
+        const element = document.getElementById(id);
+        if (element) {
+            element.textContent = text;
+        }
+    }
+    
+    updateVariationInfo() {
+        const variationDisplay = document.getElementById('currentVariationDisplay');
+        if (variationDisplay) {
+            const geometryNames = [
+                'TETRAHEDRON LATTICE', 'HYPERCUBE LATTICE', 'SPHERE LATTICE', 'TORUS LATTICE',
+                'KLEIN BOTTLE LATTICE', 'FRACTAL LATTICE', 'WAVE LATTICE', 'CRYSTAL LATTICE'
+            ];
+            
+            const geometryType = Math.floor(this.params.variation / 4);
+            const geometryLevel = (this.params.variation % 4) + 1;
+            const geometryName = geometryNames[geometryType] || 'CUSTOM VARIATION';
+            
+            variationDisplay.textContent = `${this.params.variation + 1} - ${geometryName}`;
+            
+            if (this.params.variation < 30) {
+                variationDisplay.textContent += ` ${geometryLevel}`;
+            }
+        }
+    }
+    
+    updateGeometryButtons() {
+        document.querySelectorAll('[data-geometry]').forEach(btn => {
+            btn.classList.toggle('active', parseInt(btn.dataset.geometry) === this.params.geometry);
+        });
+    }
+    
+    /**
+     * Randomize all parameters
+     */
+    randomizeAll() {
+        // 3D Space Rotations
+        this.params.rot4dXY = Math.random() * 12.56 - 6.28;
+        this.params.rot4dXZ = Math.random() * 12.56 - 6.28;
+        this.params.rot4dYZ = Math.random() * 12.56 - 6.28;
+        // 4D Hyperspace Rotations
+        this.params.rot4dXW = Math.random() * 4 - 2;
+        this.params.rot4dYW = Math.random() * 4 - 2;
+        this.params.rot4dZW = Math.random() * 4 - 2;
+        // Visual Parameters
+        this.params.dimension = 3.0 + Math.random() * 1.5;
+        this.params.gridDensity = 4 + Math.random() * 26;
+        this.params.morphFactor = Math.random() * 2;
+        this.params.chaos = Math.random();
+        this.params.speed = 0.1 + Math.random() * 2.9;
+        this.params.hue = Math.random() * 360;
+        this.params.geometry = Math.floor(Math.random() * 24);
+    }
+    
+    /**
+     * Reset to default parameters
+     */
+    resetToDefaults() {
+        this.params = { ...this.defaults };
+    }
+    
+    /**
+     * Load parameter configuration
+     */
+    loadConfiguration(config) {
+        if (!config || typeof config !== 'object') return false;
+
+        // If it has a parameters sub-object, use that (export format)
+        const params = config.parameters || config;
+        if (typeof params !== 'object') return false;
+
+        for (const [key, value] of Object.entries(params)) {
+            if (this.parameterDefs[key]) {
+                this.setParameter(key, value);
+            }
+        }
+        return true;
+    }
+    
+    /**
+     * Export current configuration
+     */
+    exportConfiguration() {
+        return {
+            type: 'vib34d-integrated-config',
+            version: '1.0.0',
+            timestamp: new Date().toISOString(),
+            name: `VIB34D Config ${new Date().toLocaleDateString()}`,
+            parameters: { ...this.params }
+        };
+    }
+    
+    /**
+     * Generate variation-specific parameters
+     */
+    generateVariationParameters(variationIndex) {
+        if (variationIndex < 30) {
+            // Default variations with consistent patterns
+            const geometryType = Math.floor(variationIndex / 4);
+            const level = variationIndex % 4;
+            
+            return {
+                geometry: geometryType,
+                gridDensity: 8 + (level * 4),
+                morphFactor: 0.5 + (level * 0.3),
+                chaos: level * 0.15,
+                speed: 0.8 + (level * 0.2),
+                hue: (geometryType * 45 + level * 15) % 360,
+                rot4dXW: (level - 1.5) * 0.5,
+                rot4dYW: (geometryType % 2) * 0.3,
+                rot4dZW: ((geometryType + level) % 3) * 0.2,
+                dimension: 3.2 + (level * 0.2)
+            };
+        } else {
+            // Custom variations - return current parameters
+            return { ...this.params };
+        }
+    }
+    
+    /**
+     * Apply variation to current parameters
+     */
+    applyVariation(variationIndex) {
+        const variationParams = this.generateVariationParameters(variationIndex);
+        this.setParameters(variationParams);
+        this.params.variation = variationIndex;
+    }
+    
+    /**
+     * Get HSV color values for current hue
+     */
+    getColorHSV() {
+        return {
+            h: this.params.hue,
+            s: 0.8, // Fixed saturation
+            v: 0.9  // Fixed value
+        };
+    }
+    
+    /**
+     * Get RGB color values for current hue
+     */
+    getColorRGB() {
+        const hsv = this.getColorHSV();
+        return this.hsvToRgb(hsv.h, hsv.s, hsv.v);
+    }
+    
+    /**
+     * Convert HSV to RGB
+     */
+    hsvToRgb(h, s, v) {
+        h = h / 60;
+        const c = v * s;
+        const x = c * (1 - Math.abs((h % 2) - 1));
+        const m = v - c;
+        
+        let r, g, b;
+        if (h < 1) {
+            [r, g, b] = [c, x, 0];
+        } else if (h < 2) {
+            [r, g, b] = [x, c, 0];
+        } else if (h < 3) {
+            [r, g, b] = [0, c, x];
+        } else if (h < 4) {
+            [r, g, b] = [0, x, c];
+        } else if (h < 5) {
+            [r, g, b] = [x, 0, c];
+        } else {
+            [r, g, b] = [c, 0, x];
+        }
+        
+        return {
+            r: Math.round((r + m) * 255),
+            g: Math.round((g + m) * 255),
+            b: Math.round((b + m) * 255)
+        };
+    }
+    
+    /**
+     * Validate parameter configuration
+     */
+    validateConfiguration(config) {
+        if (!config || typeof config !== 'object') {
+            return { valid: false, error: 'Configuration must be an object' };
+        }
+        
+        if (config.type !== 'vib34d-integrated-config') {
+            return { valid: false, error: 'Invalid configuration type' };
+        }
+        
+        if (!config.parameters) {
+            return { valid: false, error: 'Missing parameters object' };
+        }
+        
+        // Validate individual parameters
+        for (const [key, value] of Object.entries(config.parameters)) {
+            if (this.parameterDefs[key]) {
+                const def = this.parameterDefs[key];
+                if (typeof value !== 'number' || value < def.min || value > def.max) {
+                    return { valid: false, error: `Invalid value for parameter ${key}: ${value}` };
+                }
+            }
+        }
+        
+        return { valid: true };
+    }
+}

package/src/core/RendererContracts.js

@@ -0,0 +1,200 @@
+/**
+ * Renderer and resource manager contracts for unified engine integrations.
+ * These contracts provide a minimal API surface so renderers and resource managers
+ * can be swapped without rewriting orchestration layers.
+ *
+ * @fileoverview VIB3+ SDK Renderer Contract System
+ *
+ * Contract Methods:
+ * - init(context)              Initialize renderer with optional context
+ * - resize(width, height, dpr) Handle canvas resize
+ * - render(frameState)         Render a single frame
+ * - setActive(active)          Activate/deactivate renderer
+ * - dispose()                  Clean up all resources
+ *
+ * Systems implementing this contract:
+ * - QuantumEngine       (src/quantum/QuantumEngine.js)
+ * - FacetedSystem       (src/faceted/FacetedSystem.js)
+ * - RealHolographicSystem (src/holograms/RealHolographicSystem.js)
+ */
+
+/**
+ * Abstract renderer contract - base class for all visualization systems
+ * @abstract
+ */
+export class RendererContract {
+    /**
+     * Initialize the renderer
+     * @param {Object} context - Initialization context (canvas, options, etc.)
+     * @returns {boolean|Promise<boolean>} Success status
+     */
+    init(context) {
+        throw new Error('RendererContract.init() must be implemented.');
+    }
+
+    /**
+     * Handle canvas resize
+     * @param {number} width - New width in pixels
+     * @param {number} height - New height in pixels
+     * @param {number} [pixelRatio=1] - Device pixel ratio
+     */
+    resize(width, height, pixelRatio = 1) {
+        throw new Error('RendererContract.resize() must be implemented.');
+    }
+
+    /**
+     * Render a single frame
+     * @param {Object} [frameState] - Frame state with time, parameters, audio data
+     * @param {number} [frameState.time] - Current time in seconds
+     * @param {Object} [frameState.params] - Visualization parameters
+     * @param {Object} [frameState.audio] - Audio reactivity data
+     */
+    render(frameState) {
+        throw new Error('RendererContract.render() must be implemented.');
+    }
+
+    /**
+     * Set active/inactive state
+     * @param {boolean} active - Whether the renderer should be active
+     */
+    setActive(active) {
+        throw new Error('RendererContract.setActive() must be implemented.');
+    }
+
+    /**
+     * Clean up all resources (WebGL contexts, audio, event listeners)
+     */
+    dispose() {
+        throw new Error('RendererContract.dispose() must be implemented.');
+    }
+}
+
+/**
+ * Adapter base class that provides default implementations
+ * Systems can extend this instead of RendererContract for easier compliance
+ */
+export class RendererContractAdapter extends RendererContract {
+    constructor() {
+        super();
+        this._initialized = false;
+        this._active = false;
+        this._width = 0;
+        this._height = 0;
+        this._pixelRatio = 1;
+    }
+
+    /**
+     * Check if renderer is initialized
+     * @returns {boolean}
+     */
+    get initialized() {
+        return this._initialized;
+    }
+
+    /**
+     * Check if renderer is active
+     * @returns {boolean}
+     */
+    get isActive() {
+        return this._active;
+    }
+
+    /**
+     * Default init - override in subclass
+     * @param {Object} context
+     * @returns {boolean}
+     */
+    init(context) {
+        this._initialized = true;
+        return true;
+    }
+
+    /**
+     * Default resize - stores dimensions, override to apply to canvases
+     * @param {number} width
+     * @param {number} height
+     * @param {number} pixelRatio
+     */
+    resize(width, height, pixelRatio = 1) {
+        this._width = width;
+        this._height = height;
+        this._pixelRatio = pixelRatio;
+    }
+
+    /**
+     * Default render - no-op, override in subclass
+     * @param {Object} frameState
+     */
+    render(frameState) {
+        // Override in subclass
+    }
+
+    /**
+     * Default setActive - stores state
+     * @param {boolean} active
+     */
+    setActive(active) {
+        this._active = active;
+    }
+
+    /**
+     * Default dispose - resets state
+     */
+    dispose() {
+        this._initialized = false;
+        this._active = false;
+    }
+}
+
+/**
+ * Verify that a system implements the RendererContract
+ * @param {Object} system - System instance to verify
+ * @returns {{compliant: boolean, missing: string[], warnings: string[]}}
+ */
+export function verifyRendererContract(system) {
+    const required = ['init', 'resize', 'render', 'setActive', 'dispose'];
+    const missing = [];
+    const warnings = [];
+
+    for (const method of required) {
+        if (typeof system[method] !== 'function') {
+            // Check for common aliases
+            const aliases = {
+                init: ['initialize'],
+                dispose: ['destroy', 'cleanup'],
+                render: ['renderFrame', 'draw']
+            };
+
+            const hasAlias = aliases[method]?.some(alias => typeof system[alias] === 'function');
+            if (hasAlias) {
+                warnings.push(`${method}() missing but alias exists - consider adding standard method`);
+            } else {
+                missing.push(method);
+            }
+        }
+    }
+
+    return {
+        compliant: missing.length === 0,
+        missing,
+        warnings
+    };
+}
+
+export class ResourceManagerContract {
+    registerResource(type, id, resource, bytes = 0) {
+        throw new Error('ResourceManagerContract.registerResource() must be implemented.');
+    }
+
+    releaseResource(type, id) {
+        throw new Error('ResourceManagerContract.releaseResource() must be implemented.');
+    }
+
+    disposeAll() {
+        throw new Error('ResourceManagerContract.disposeAll() must be implemented.');
+    }
+
+    getStats() {
+        throw new Error('ResourceManagerContract.getStats() must be implemented.');
+    }
+}