@joshtol/emotive-engine 3.2.2 → 3.2.3

package/src/3d/ThreeRenderer.js

@@ -20,6 +20,7 @@ import { UnrealBloomPassAlpha } from './UnrealBloomPassAlpha.js';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { normalizeColorLuminance } from '../utils/glowIntensityFilter.js';
 import { GlowLayer } from './effects/GlowLayer.js';
+import { CameraPresetManager } from './managers/CameraPresetManager.js';
 
 export class ThreeRenderer {
     constructor(canvas, options = {}) {
@@ -52,6 +53,11 @@ export class ThreeRenderer {
         // Set clear color with full alpha transparency for CSS backgrounds
         this.renderer.setClearColor(0x000000, 0);
 
+        // CRITICAL: Clear the canvas immediately after renderer creation
+        // This ensures no garbage data is visible before the first frame renders
+        // Uninitialized GPU framebuffers can contain random colors (often magenta/red)
+        this.renderer.clear();
+
         // CRITICAL: Disable autoClear for transparency to work in newer Three.js versions
         this.renderer.autoClear = false;
 
@@ -191,6 +197,9 @@ export class ThreeRenderer {
         // Listen for pointer events at capture phase for earliest possible handling
         this.renderer.domElement.addEventListener('pointermove', immediateUpdate, { passive: true });
         this.renderer.domElement.addEventListener('pointerdown', immediateUpdate, { passive: true });
+
+        // Initialize camera preset manager for smooth view transitions
+        this.cameraPresetManager = new CameraPresetManager(this.camera, this.controls, this.cameraDistance);
     }
 
     /**
@@ -262,6 +271,9 @@ export class ThreeRenderer {
         // Guard against calls after destroy (React Strict Mode can unmount during async load)
         if (this._destroyed) return;
 
+        // Mark environment loading as in-progress to prevent rendering magenta flash
+        this._envMapLoading = true;
+
         // Try to load optional HDRI (.hdr format) for enhanced reflections
         // HDRI is optional - apps can place studio_1k.hdr in /hdri/ for better crystal reflections
         try {
@@ -276,14 +288,28 @@ export class ThreeRenderer {
 
             try {
                 const hdrLoader = new HDRLoader();
-                const assetBasePath = this.options.assetBasePath || '/assets';
-                // HDRI is in public root, not in assets folder
-                const hdriBasePath = assetBasePath.replace('/assets', '');
-                const texture = await hdrLoader.loadAsync(`${hdriBasePath}/hdri/studio_1k.hdr`);
 
-                // Validate texture was loaded correctly (404 can return malformed texture)
+                // Try multiple paths to support different server configurations:
+                // - /hdri/... for Next.js (serves site/public at root)
+                // - /site/public/hdri/... for Live Server (serves project root)
+                const hdrPaths = [
+                    '/hdri/studio_1k.hdr',
+                    '/site/public/hdri/studio_1k.hdr'
+                ];
+
+                let texture = null;
+                for (const hdrPath of hdrPaths) {
+                    try {
+                        texture = await hdrLoader.loadAsync(hdrPath);
+                        if (texture && texture.image) break;
+                    } catch (e) {
+                        // Try next path
+                    }
+                }
+
+                // Validate texture was loaded correctly
                 if (!texture || !texture.image) {
-                    throw new Error('HDR texture loaded but image data is missing');
+                    throw new Error('HDR texture not found at any path');
                 }
 
                 // Check if destroyed during load (React Strict Mode)
@@ -297,6 +323,7 @@ export class ThreeRenderer {
                 this.envMap = pmremGenerator.fromEquirectangular(texture).texture;
                 texture.dispose(); // CRITICAL: Dispose source texture after PMREM conversion (GPU memory leak fix)
                 pmremGenerator.dispose();
+                this._envMapLoading = false; // HDRI loaded successfully
                 console.log('[Emotive] HDRI environment map loaded');
                 return;
             } catch (hdrError) {
@@ -346,6 +373,8 @@ export class ThreeRenderer {
         this._envScene = envScene;
         this._envCubeCamera = cubeCamera;
 
+        // Mark environment loading as complete (using fallback)
+        this._envMapLoading = false;
     }
 
     /**
@@ -371,6 +400,17 @@ export class ThreeRenderer {
             });
         this.composer = new EffectComposer(this.renderer, renderTarget);
 
+        // CRITICAL: Clear ALL composer render targets to prevent garbage data flash
+        // The composer creates internal read/write buffers that contain uninitialized GPU memory
+        // This can show as random colors (often magenta/red) on first frame before RenderPass clears
+        this.renderer.setRenderTarget(renderTarget);
+        this.renderer.clear();
+        this.renderer.setRenderTarget(this.composer.readBuffer);
+        this.renderer.clear();
+        this.renderer.setRenderTarget(this.composer.writeBuffer);
+        this.renderer.clear();
+        this.renderer.setRenderTarget(null);
+
         // Render pass - base scene render
         const renderPass = new RenderPass(this.scene, this.camera);
         // CRITICAL: Set clear color to transparent for CSS background blending
@@ -397,6 +437,10 @@ export class ThreeRenderer {
         this.bloomPass.renderToScreen = true; // CRITICAL: Last pass must render to screen
         this.composer.addPass(this.bloomPass);
 
+        // CRITICAL: Clear bloom buffers immediately after creation to prevent garbage data flash
+        // Uninitialized GPU memory can contain random colors (often red/magenta on some drivers)
+        this.bloomPass.clearBloomBuffers(this.renderer);
+
         // === SEPARATE PARTICLE BLOOM PIPELINE ===
         // Particles get their own render target with NON-BLACK clear color
         // This prevents dark halos from blur sampling black transparent pixels
@@ -411,6 +455,11 @@ export class ThreeRenderer {
                 depthBuffer: true
             });
 
+        // Clear particle render target
+        this.renderer.setRenderTarget(this.particleRenderTarget);
+        this.renderer.clear();
+        this.renderer.setRenderTarget(null);
+
         // Particle bloom pass (same settings but separate pipeline)
         this.particleBloomPass = new UnrealBloomPassAlpha(
             bloomResolution,
@@ -426,6 +475,9 @@ export class ThreeRenderer {
         // Skip the base copy step - we only want to add bloom on top of existing scene
         this.particleBloomPass.skipBaseCopy = true;
 
+        // Clear particle bloom buffers too
+        this.particleBloomPass.clearBloomBuffers(this.renderer);
+
         // === SOUL REFRACTION RENDER TARGET ===
         // Soul mesh is rendered to this texture first, then sampled by crystal shader
         // with refraction distortion to create proper lensing effect
@@ -440,6 +492,11 @@ export class ThreeRenderer {
                 depthBuffer: true
             });
 
+        // Clear soul render target
+        this.renderer.setRenderTarget(this.soulRenderTarget);
+        this.renderer.clear();
+        this.renderer.setRenderTarget(null);
+
         // Composite shader to blend particle bloom onto main scene
         this.particleCompositeShader = {
             uniforms: {
@@ -1163,6 +1220,28 @@ export class ThreeRenderer {
             return;
         }
 
+        // Guard against rendering before coreMesh exists (prevents magenta flash from empty scene + bloom)
+        if (!this.coreMesh) {
+            return;
+        }
+
+        // Guard against rendering while environment map is loading (prevents magenta flash from missing HDR)
+        // Three.js shows magenta when textures are pending/failed
+        if (this._envMapLoading) {
+            return;
+        }
+
+        // CRITICAL: Skip the very first frame to allow GPU buffers to be properly initialized
+        // This prevents garbage data (often magenta) from flashing before the first real render
+        if (!this._firstFrameRendered) {
+            this._firstFrameRendered = true;
+            // Clear screen to transparent on first frame instead of rendering garbage
+            this.renderer.setRenderTarget(null);
+            this.renderer.setClearColor(0x000000, 0);
+            this.renderer.clear();
+            return;
+        }
+
         // DEBUG: Check scene for null children before render and REMOVE them
         // Also recursively check children of children
         const validateObject = (obj, path) => {
@@ -1625,6 +1704,12 @@ export class ThreeRenderer {
             this.glowLayer = null;
         }
 
+        // Dispose camera preset manager
+        if (this.cameraPresetManager) {
+            this.cameraPresetManager.dispose();
+            this.cameraPresetManager = null;
+        }
+
         // Dispose controls (removes DOM event listeners)
         if (this.controls) {
             this.controls.dispose();

package/src/3d/effects/CrystalSoul.js

@@ -572,8 +572,7 @@ export class CrystalSoul {
 
     /**
      * Dispose of resources
-     * Removes mesh from scene SYNCHRONOUSLY to avoid render race conditions,
-     * then defers geometry/material disposal to next frame for safety
+     * Defers scene removal AND geometry disposal to next frame to avoid Three.js render race conditions
      */
     dispose() {
         // Prevent double disposal
@@ -582,31 +581,26 @@ export class CrystalSoul {
         // Set disposed flag FIRST to prevent async callbacks from running
         this._disposed = true;
 
-        // Mark invisible immediately
-        if (this.mesh) {
-            this.mesh.visible = false;
-        }
+        // Mark invisible immediately (detach just sets visible=false now)
+        this.detach();
 
         // Store references for deferred cleanup
         const meshToDispose = this.mesh;
         const materialToDispose = this.material;
 
-        // Remove from scene SYNCHRONOUSLY - this prevents the render loop from
-        // trying to traverse a mesh that's being disposed. The key insight is that
-        // scene.remove() is safe during the current frame because Three.js only
-        // traverses children that are currently in the array when render starts.
-        if (meshToDispose?.parent) {
-            meshToDispose.parent.remove(meshToDispose);
-        }
-
         // Clear references immediately (so nothing tries to use them)
         this.mesh = null;
         this.material = null;
         this.parentMesh = null;
 
-        // Defer ONLY geometry/material disposal to next frame
-        // This is safe because the mesh is already removed from the scene
+        // Defer BOTH scene removal AND geometry disposal to next frame
+        // This avoids Three.js render race conditions with projectObject traversal
         requestAnimationFrame(() => {
+            // Remove from scene first
+            if (meshToDispose?.parent) {
+                meshToDispose.parent.remove(meshToDispose);
+            }
+            // Then dispose resources
             if (meshToDispose?.geometry) {
                 meshToDispose.geometry.dispose();
             }

package/src/3d/effects/SolarEclipse.js

@@ -635,23 +635,21 @@ export class SolarEclipse {
         const worldScale = sunScale.x; // World scale for consistent sizing
 
         // Calculate corona fade multiplier for morph transitions
-        // Match the geometry morpher's scale curve so rays and core appear simultaneously
-        // GeometryMorpher uses easeOutQuad for grow phase: t * (2 - t)
-        // GeometryMorpher uses easeInQuad for shrink phase: t * t
+        // Entry (Anything->Sun): rays fade in with inverse cubic (slow start, fast finish - bloom effect)
+        // Exit (Sun->Anything): rays fade out with cubic (fast start, slow finish - rays lead)
         let coronaMorphFade = 1.0;
         if (morphProgress !== null && morphProgress > 0.5) {
             // Grow phase (entry): progress 0.5->1.0
-            // Use easeOutQuad to match geometry scale: t * (2 - t)
-            // This makes rays appear at the same rate as the sun core
+            // Inverse of exit: slow start, accelerating finish (rays bloom from sun)
             const t = (morphProgress - 0.5) * 2; // 0 to 1 as grow progresses
-            coronaMorphFade = t * (2 - t); // easeOutQuad: matches geometry grow curve
+            coronaMorphFade = t * t * t; // Cubic: starts slow at 0, accelerates to 1
         } else if (morphProgress !== null && morphProgress <= 0.5) {
             // Shrink phase (exit): morphProgress goes 0->0.5
             // At start (morphProgress=0): rays should be full (1.0)
             // At end (morphProgress=0.5): rays should be gone (0.0)
-            // Use inverse easeInQuad to match geometry shrink: 1 - t*t
+            // Rays fade FAST (cubic) - they lead ahead of sun's shrink
             const t = morphProgress * 2; // 0 to 1 as shrink progresses
-            coronaMorphFade = 1.0 - (t * t); // Inverse easeInQuad: matches geometry shrink curve
+            coronaMorphFade = (1.0 - t) * (1.0 - t) * (1.0 - t); // Cubic: starts at 1, drops fast to 0
         }
 
         // Update time for corona animation

package/src/3d/geometries/Moon.js

@@ -217,7 +217,7 @@ export function disposeMoon(moonMesh) {
  * @returns {THREE.MeshStandardMaterial}
  */
 export function createMoonMaterial(textureLoader, options = {}) {
-    const resolution = options.resolution || '2k';
+    const resolution = options.resolution || '4k';
     const assetBasePath = options.assetBasePath || '/assets';
 
     // Determine texture paths based on resolution
@@ -338,7 +338,7 @@ export function createMoonFallbackMaterial(glowColor = new THREE.Color(0xffffff)
  * @returns {THREE.ShaderMaterial}
  */
 export function createMoonShadowMaterial(textureLoader, options = {}) {
-    const resolution = options.resolution || '2k';
+    const resolution = options.resolution || '4k';
     const glowColor = options.glowColor || new THREE.Color(1, 1, 1);
     const glowIntensity = options.glowIntensity || 1.0;
     const shadowType = options.shadowType || 'crescent';
@@ -667,7 +667,7 @@ export function updateCrescentShadow(material, offsetX, offsetY, coverage) {
  */
 export function createMoonMultiplexerMaterial(textureLoader, options = {}) {
     const {
-        resolution = '2k',
+        resolution = '4k',
         glowColor = new THREE.Color(0xffffff),
         glowIntensity = 1.0,
         assetBasePath = '/assets'

package/src/3d/index.js

@@ -252,17 +252,21 @@ export class EmotiveMascot3D {
         this.container.appendChild(this.canvas2D);
 
         // Create WebGL canvas for 3D core (Layer 2 - front)
+        // CRITICAL: Canvas is NOT appended to DOM here - it will be appended after first render
+        // This prevents any garbage data from being visible during GPU initialization
         this.webglCanvas = document.createElement('canvas');
         this.webglCanvas.id = `${this.config.canvasId}-3d`;
         this.webglCanvas.width = this.canvas2D.width;
         this.webglCanvas.height = this.canvas2D.height;
-        this.webglCanvas.style.position = 'absolute';
-        this.webglCanvas.style.top = '0';
-        this.webglCanvas.style.left = '0';
-        this.webglCanvas.style.width = '100%';
-        this.webglCanvas.style.height = '100%';
-        this.webglCanvas.style.background = 'transparent';
-        this.webglCanvas.style.zIndex = '2';
+        this.webglCanvas.style.cssText = `
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            background: transparent;
+            z-index: 2;
+        `;
         // Only enable pointer events if controls are enabled (for orbit camera)
         // Otherwise, let events pass through to allow page scrolling
         if (this.config.enableControls) {
@@ -274,7 +278,8 @@ export class EmotiveMascot3D {
             this.webglCanvas.style.pointerEvents = 'none';
             this.webglCanvas.style.touchAction = 'auto';
         }
-        this.container.appendChild(this.webglCanvas);
+        // NOTE: Canvas is NOT appended here - see animate() for deferred append after first render
+        this._canvasAppended = false;
     }
 
     /**
@@ -336,6 +341,14 @@ export class EmotiveMascot3D {
         // Render 3D core - check again as state may have changed
         if (this.core3D && !this._destroyed) {
             this.core3D.render(deltaTime);
+
+            // CRITICAL: Append canvas to DOM after first frame renders
+            // Canvas is created but NOT added to DOM during setup to prevent garbage data flash
+            // Only after the first successful render do we add it to the document
+            if (!this._canvasAppended && this.webglCanvas && this.container) {
+                this.container.appendChild(this.webglCanvas);
+                this._canvasAppended = true;
+            }
         }
 
         // Render 2D particles (or clear canvas if disabled)
@@ -1745,3 +1758,6 @@ export {
 
 // Export rhythm 3D adapter for advanced rhythm sync customization
 export { rhythm3DAdapter, Rhythm3DAdapter } from './animation/Rhythm3DAdapter.js';
+
+// Export CrystalSoul for geometry preloading
+export { CrystalSoul } from './effects/CrystalSoul.js';

package/src/3d/managers/AnimationManager.js

@@ -0,0 +1,269 @@
+/**
+ * AnimationManager - Gesture animation orchestration for 3D mascot
+ *
+ * Manages gesture playback, virtual particle pools, and animation lifecycle.
+ * Extracted from Core3DManager to improve separation of concerns.
+ *
+ * @module 3d/managers/AnimationManager
+ */
+
+import { getGesture } from '../../core/gestures/index.js';
+
+/**
+ * Maximum number of concurrent animations to prevent memory issues
+ */
+const MAX_ACTIVE_ANIMATIONS = 10;
+
+/**
+ * Default pool size for virtual particles
+ */
+const DEFAULT_POOL_SIZE = 5;
+
+export class AnimationManager {
+    /**
+     * Create animation manager
+     * @param {ProceduralAnimator} animator - The procedural animator instance
+     * @param {GestureBlender} gestureBlender - The gesture blender for combining animations
+     */
+    constructor(animator, gestureBlender) {
+        this.animator = animator;
+        this.gestureBlender = gestureBlender;
+
+        // Virtual particle pool for gesture animations (prevents closure memory leaks)
+        this.virtualParticlePool = this._createVirtualParticlePool(DEFAULT_POOL_SIZE);
+        this.nextPoolIndex = 0;
+    }
+
+    /**
+     * Create reusable virtual particle object pool
+     * @param {number} size - Pool size
+     * @returns {Array} Array of reusable particle objects
+     * @private
+     */
+    _createVirtualParticlePool(size) {
+        const pool = [];
+        for (let i = 0; i < size; i++) {
+            pool.push({
+                x: 0,
+                y: 0,
+                vx: 0,
+                vy: 0,
+                size: 1,
+                baseSize: 1,
+                opacity: 1,
+                scaleFactor: 1,
+                gestureData: null
+            });
+        }
+        return pool;
+    }
+
+    /**
+     * Get next virtual particle from pool (round-robin)
+     * @returns {Object} Reusable virtual particle object
+     */
+    getVirtualParticleFromPool() {
+        const particle = this.virtualParticlePool[this.nextPoolIndex];
+        this.nextPoolIndex = (this.nextPoolIndex + 1) % this.virtualParticlePool.length;
+        // Reset particle state
+        particle.x = 0;
+        particle.y = 0;
+        particle.vx = 0;
+        particle.vy = 0;
+        particle.size = 1;
+        particle.baseSize = 1;
+        particle.opacity = 1;
+        particle.scaleFactor = 1;
+        particle.gestureData = null;
+        return particle;
+    }
+
+    /**
+     * Play gesture animation using 2D gesture data translated to 3D
+     * @param {string} gestureName - Name of the gesture to play
+     * @param {Object} callbacks - Callback functions
+     * @param {Function} callbacks.onUpdate - Called with (props, progress) during animation
+     * @param {Function} callbacks.onComplete - Called when animation completes
+     * @returns {boolean} True if gesture was started successfully
+     */
+    playGesture(gestureName, callbacks = {}) {
+        // Get the 2D gesture definition
+        const gesture2D = getGesture(gestureName);
+
+        if (!gesture2D) {
+            console.warn(`Unknown gesture: ${gestureName}`);
+            return false;
+        }
+
+        // Get reusable virtual particle from pool (prevent closure memory leaks)
+        const virtualParticle = this.getVirtualParticleFromPool();
+
+        // Get gesture config for duration
+        const config = gesture2D.config || {};
+        const duration = config.musicalDuration?.musical
+            ? (config.musicalDuration.beats || 2) * 500  // Assume 120 BPM (500ms per beat)
+            : (config.duration || 800);
+
+        // Start time-based animation
+        const startTime = this.animator.time;
+
+        // Enforce animation array size limit (prevent unbounded growth memory leak)
+        if (this.animator.animations.length >= MAX_ACTIVE_ANIMATIONS) {
+            // Remove oldest animation (FIFO cleanup)
+            const removed = this.animator.animations.shift();
+            console.warn(`Animation limit reached (${MAX_ACTIVE_ANIMATIONS}), removed oldest: ${removed.gestureName || 'unknown'}`);
+        }
+
+        // Create persistent gesture data object for this gesture instance
+        const gestureData = { initialized: false };
+
+        // Add to animator's active animations
+        this.animator.animations.push({
+            gestureName, // Store gesture name for particle system
+            duration,
+            startTime,
+            config, // Store config for particle system
+            evaluate: t => {
+                // Reset virtual particle to center each frame
+                virtualParticle.x = 0;
+                virtualParticle.y = 0;
+                virtualParticle.vx = 0;
+                virtualParticle.vy = 0;
+                virtualParticle.size = 1;
+                virtualParticle.opacity = 1;
+
+                // All gestures now have native 3D implementations
+                // Apply gesture to virtual particle if needed
+                if (gesture2D.apply) {
+                    gesture2D.apply(virtualParticle, gestureData, config, t, 1.0, 0, 0);
+                }
+
+                // Call gesture's 3D evaluate function with particle data
+                const motion = {
+                    ...config,
+                    particle: virtualParticle,
+                    config,
+                    strength: config.strength || 1.0
+                };
+
+                // Safety check: if gesture doesn't have 3D implementation, return neutral transform
+                if (!gesture2D['3d'] || !gesture2D['3d'].evaluate) {
+                    return {
+                        position: [0, 0, 0],
+                        rotation: [0, 0, 0],
+                        scale: 1.0
+                    };
+                }
+
+                // Call with gesture2D as context so 'this.config' works
+                return gesture2D['3d'].evaluate.call(gesture2D, t, motion);
+            },
+            callbacks: {
+                onUpdate: callbacks.onUpdate || null,
+                onComplete: () => {
+                    // Clean up gesture
+                    if (gesture2D.cleanup) {
+                        gesture2D.cleanup(virtualParticle);
+                    }
+                    // Call user callback
+                    if (callbacks.onComplete) {
+                        callbacks.onComplete();
+                    }
+                }
+            }
+        });
+
+        return true;
+    }
+
+    /**
+     * Update animations for current frame
+     * @param {number} deltaTime - Time since last frame in seconds
+     */
+    update(deltaTime) {
+        this.animator.update(deltaTime);
+    }
+
+    /**
+     * Blend all active animations
+     * @param {THREE.Quaternion} baseQuaternion - Base rotation quaternion
+     * @param {number} baseScale - Base scale value
+     * @param {number} baseGlowIntensity - Base glow intensity
+     * @returns {Object} Blended animation state
+     */
+    blend(baseQuaternion, baseScale, baseGlowIntensity) {
+        return this.gestureBlender.blend(
+            this.animator.animations,
+            this.animator.time,
+            baseQuaternion,
+            baseScale,
+            baseGlowIntensity
+        );
+    }
+
+    /**
+     * Check if any animations are active
+     * @returns {boolean} True if animations are playing
+     */
+    hasActiveAnimations() {
+        return this.animator.animations.length > 0;
+    }
+
+    /**
+     * Get count of active animations
+     * @returns {number} Number of active animations
+     */
+    getActiveAnimationCount() {
+        return this.animator.animations.length;
+    }
+
+    /**
+     * Get current animator time
+     * @returns {number} Current animation time
+     */
+    getTime() {
+        return this.animator.time;
+    }
+
+    /**
+     * Get active animations array (for external systems like particle translator)
+     * @returns {Array} Active animations
+     */
+    getActiveAnimations() {
+        return this.animator.animations;
+    }
+
+    /**
+     * Stop all animations
+     */
+    stopAll() {
+        this.animator.stopAll();
+    }
+
+    /**
+     * Play emotion animation
+     * @param {string} emotion - Emotion name
+     */
+    playEmotion(emotion) {
+        this.animator.playEmotion(emotion);
+    }
+
+    /**
+     * Clean up and dispose resources
+     */
+    dispose() {
+        this.stopAll();
+
+        if (this.virtualParticlePool) {
+            this.virtualParticlePool.length = 0;
+            this.virtualParticlePool = null;
+        }
+
+        this.animator = null;
+        this.gestureBlender = null;
+        this.tempEuler = null;
+        this.gestureQuaternion = null;
+    }
+}
+
+export default AnimationManager;