@myned-ai/gsplat-flame-avatar-renderer 1.0.5 → 1.0.6

package/src/utils/Logger.js

@@ -0,0 +1,171 @@
+/**
+ * Logger - Structured logging system
+ *
+ * Provides leveled logging with optional output suppression for production.
+ * Replaces direct console.log calls for better control and debugging.
+ */
+
+/**
+ * Logger levels in order of severity
+ * Note: Named LoggerLevel to avoid conflict with existing LogLevel enum
+ */
+export const LoggerLevel = Object.freeze({
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+    NONE: 4
+});
+
+/**
+ * Logger class for structured application logging
+ */
+export class Logger {
+    /**
+     * Create a Logger instance
+     * @param {string} namespace - Logger namespace (e.g., 'Renderer', 'Loader')
+     * @param {number} [minLevel=LoggerLevel.INFO] - Minimum log level to output
+     */
+    constructor(namespace, minLevel = LoggerLevel.INFO) {
+        this.namespace = namespace;
+        this.minLevel = minLevel;
+    }
+
+    /**
+     * Set minimum log level
+     * @param {number} level - Minimum level from LoggerLevel enum
+     */
+    setLevel(level) {
+        this.minLevel = level;
+    }
+
+    /**
+     * Format log message with namespace and timestamp
+     * @private
+     * @param {string} level - Log level name
+     * @param {Array} args - Log arguments
+     * @returns {Array} Formatted arguments
+     */
+    _format(level, args) {
+        const timestamp = new Date().toISOString();
+        const prefix = `[${timestamp}] [${level}] [${this.namespace}]`;
+        return [prefix, ...args];
+    }
+
+    /**
+     * Log debug message (most verbose)
+     * @param {...*} args - Arguments to log
+     */
+    debug(...args) {
+        if (this.minLevel <= LoggerLevel.DEBUG) {
+            console.debug(...this._format('DEBUG', args));
+        }
+    }
+
+    /**
+     * Log info message
+     * @param {...*} args - Arguments to log
+     */
+    info(...args) {
+        if (this.minLevel <= LoggerLevel.INFO) {
+            console.info(...this._format('INFO', args));
+        }
+    }
+
+    /**
+     * Log warning message
+     * @param {...*} args - Arguments to log
+     */
+    warn(...args) {
+        if (this.minLevel <= LoggerLevel.WARN) {
+            console.warn(...this._format('WARN', args));
+        }
+    }
+
+    /**
+     * Log error message
+     * @param {...*} args - Arguments to log
+     */
+    error(...args) {
+        if (this.minLevel <= LoggerLevel.ERROR) {
+            console.error(...this._format('ERROR', args));
+        }
+    }
+
+    /**
+     * Log error with stack trace
+     * @param {Error} error - Error object
+     * @param {string} [context] - Additional context
+     */
+    errorWithTrace(error, context = '') {
+        if (this.minLevel <= LoggerLevel.ERROR) {
+            const contextStr = context ? ` Context: ${context}` : '';
+            console.error(...this._format('ERROR', [
+                `${error.message}${contextStr}`,
+                '\nStack:', error.stack
+            ]));
+        }
+    }
+
+    /**
+     * Create a child logger with extended namespace
+     * @param {string} childNamespace - Child namespace to append
+     * @returns {Logger} New logger with combined namespace
+     */
+    child(childNamespace) {
+        return new Logger(`${this.namespace}:${childNamespace}`, this.minLevel);
+    }
+}
+
+/**
+ * Global logger registry
+ * @private
+ */
+const loggers = new Map();
+
+/**
+ * Global log level (affects all new loggers)
+ * @private
+ */
+let globalLogLevel = LoggerLevel.INFO;
+
+/**
+ * Set global log level for all loggers
+ * @param {number} level - Log level from LoggerLevel enum
+ */
+export function setGlobalLogLevel(level) {
+    globalLogLevel = level;
+    // Update existing loggers
+    for (const logger of loggers.values()) {
+        logger.setLevel(level);
+    }
+}
+
+/**
+ * Get or create a logger for a namespace
+ * @param {string} namespace - Logger namespace
+ * @returns {Logger} Logger instance
+ */
+export function getLogger(namespace) {
+    if (!loggers.has(namespace)) {
+        loggers.set(namespace, new Logger(namespace, globalLogLevel));
+    }
+    return loggers.get(namespace);
+}
+
+/**
+ * Configure logging for production (suppress all logs)
+ */
+export function configureForProduction() {
+    setGlobalLogLevel(LoggerLevel.NONE);
+}
+
+/**
+ * Configure logging for development (show all logs)
+ */
+export function configureForDevelopment() {
+    setGlobalLogLevel(LoggerLevel.DEBUG);
+}
+
+// Export default logger for convenience
+export default getLogger('App');

package/src/utils/ObjectPool.js

@@ -0,0 +1,248 @@
+/**
+ * ObjectPool - Memory-efficient object pooling
+ *
+ * Reduces garbage collection pressure by reusing objects instead of
+ * repeatedly allocating and deallocating them. Critical for real-time rendering.
+ */
+
+import { Vector3, Matrix4, Quaternion, Euler } from 'three';
+
+/**
+ * Generic object pool
+ */
+export class ObjectPool {
+    /**
+     * Create an ObjectPool
+     * @param {Function} factory - Function that creates new objects
+     * @param {Function} reset - Function that resets an object to initial state
+     * @param {number} [initialSize=10] - Number of objects to pre-allocate
+     */
+    constructor(factory, reset, initialSize = 10) {
+        this._factory = factory;
+        this._reset = reset;
+        this._pool = [];
+        this._allocated = 0;
+        this._maxSize = initialSize * 10; // Prevent unbounded growth
+
+        // Pre-allocate initial objects
+        for (let i = 0; i < initialSize; i++) {
+            this._pool.push(factory());
+        }
+    }
+
+    /**
+     * Acquire an object from the pool
+     * @returns {*} Pooled object
+     */
+    acquire() {
+        this._allocated++;
+        if (this._pool.length > 0) {
+            return this._pool.pop();
+        }
+        // Pool exhausted, create new object
+        return this._factory();
+    }
+
+    /**
+     * Release an object back to the pool
+     * @param {*} obj - Object to return to pool
+     */
+    release(obj) {
+        this._allocated--;
+        if (this._pool.length < this._maxSize) {
+            this._reset(obj);
+            this._pool.push(obj);
+        }
+        // If pool is at max size, let object be garbage collected
+    }
+
+    /**
+     * Release multiple objects
+     * @param {Array} objects - Objects to return to pool
+     */
+    releaseAll(objects) {
+        for (const obj of objects) {
+            this.release(obj);
+        }
+    }
+
+    /**
+     * Get pool statistics
+     * @returns {object} Pool stats
+     */
+    getStats() {
+        return {
+            available: this._pool.length,
+            allocated: this._allocated,
+            maxSize: this._maxSize
+        };
+    }
+
+    /**
+     * Clear the pool and release all objects
+     */
+    dispose() {
+        this._pool.length = 0;
+        this._allocated = 0;
+    }
+}
+
+/**
+ * Pre-configured pools for common Three.js objects
+ */
+
+/**
+ * Vector3 pool
+ * @type {ObjectPool}
+ */
+export const vector3Pool = new ObjectPool(
+    () => new Vector3(),
+    (v) => v.set(0, 0, 0),
+    50 // Pre-allocate 50 vectors
+);
+
+/**
+ * Matrix4 pool
+ * @type {ObjectPool}
+ */
+export const matrix4Pool = new ObjectPool(
+    () => new Matrix4(),
+    (m) => m.identity(),
+    20 // Pre-allocate 20 matrices
+);
+
+/**
+ * Quaternion pool
+ * @type {ObjectPool}
+ */
+export const quaternionPool = new ObjectPool(
+    () => new Quaternion(),
+    (q) => q.set(0, 0, 0, 1),
+    30 // Pre-allocate 30 quaternions
+);
+
+/**
+ * Euler pool
+ * @type {ObjectPool}
+ */
+export const eulerPool = new ObjectPool(
+    () => new Euler(),
+    (e) => e.set(0, 0, 0),
+    30 // Pre-allocate 30 eulers
+);
+
+/**
+ * Scoped pool allocation helper
+ *
+ * Automatically releases pooled objects when scope exits.
+ * Use with try/finally to ensure cleanup.
+ *
+ * @example
+ * const scope = new PoolScope();
+ * try {
+ *   const v1 = scope.vector3();
+ *   const v2 = scope.vector3();
+ *   // Use vectors...
+ * } finally {
+ *   scope.releaseAll();
+ * }
+ */
+export class PoolScope {
+    constructor() {
+        this._allocated = [];
+    }
+
+    /**
+     * Acquire a Vector3 from pool
+     * @returns {Vector3} Pooled vector
+     */
+    vector3() {
+        const obj = vector3Pool.acquire();
+        this._allocated.push({ pool: vector3Pool, obj });
+        return obj;
+    }
+
+    /**
+     * Acquire a Matrix4 from pool
+     * @returns {Matrix4} Pooled matrix
+     */
+    matrix4() {
+        const obj = matrix4Pool.acquire();
+        this._allocated.push({ pool: matrix4Pool, obj });
+        return obj;
+    }
+
+    /**
+     * Acquire a Quaternion from pool
+     * @returns {Quaternion} Pooled quaternion
+     */
+    quaternion() {
+        const obj = quaternionPool.acquire();
+        this._allocated.push({ pool: quaternionPool, obj });
+        return obj;
+    }
+
+    /**
+     * Acquire an Euler from pool
+     * @returns {Euler} Pooled euler
+     */
+    euler() {
+        const obj = eulerPool.acquire();
+        this._allocated.push({ pool: eulerPool, obj });
+        return obj;
+    }
+
+    /**
+     * Release all objects allocated in this scope
+     */
+    releaseAll() {
+        for (const { pool, obj } of this._allocated) {
+            pool.release(obj);
+        }
+        this._allocated.length = 0;
+    }
+
+    /**
+     * Get count of allocated objects in this scope
+     * @returns {number} Number of allocated objects
+     */
+    getAllocatedCount() {
+        return this._allocated.length;
+    }
+}
+
+/**
+ * Module-level temporary objects for hot-path reuse
+ * IMPORTANT: These are NOT thread-safe. Only use in single-threaded contexts.
+ * Reset these before use to avoid stale data.
+ */
+export const tempVector3A = new Vector3();
+export const tempVector3B = new Vector3();
+export const tempVector3C = new Vector3();
+export const tempMatrix4A = new Matrix4();
+export const tempMatrix4B = new Matrix4();
+export const tempQuaternionA = new Quaternion();
+export const tempQuaternionB = new Quaternion();
+
+/**
+ * Get pool statistics for all pre-configured pools
+ * @returns {object} Statistics for all pools
+ */
+export function getPoolStats() {
+    return {
+        vector3: vector3Pool.getStats(),
+        matrix4: matrix4Pool.getStats(),
+        quaternion: quaternionPool.getStats(),
+        euler: eulerPool.getStats()
+    };
+}
+
+/**
+ * Dispose all pre-configured pools
+ */
+export function disposeAllPools() {
+    vector3Pool.dispose();
+    matrix4Pool.dispose();
+    quaternionPool.dispose();
+    eulerPool.dispose();
+}

package/src/utils/RenderLoop.js

@@ -0,0 +1,306 @@
+/**
+ * RenderLoop - Frame-independent animation loop with budget management
+ *
+ * Provides a robust requestAnimationFrame loop with:
+ * - Delta time calculation for frame-independent updates
+ * - Frame budget management to prevent frame drops
+ * - Deferred task execution
+ * - Performance monitoring
+ */
+
+import { getLogger } from './Logger.js';
+
+const logger = getLogger('RenderLoop');
+
+/**
+ * RenderLoop - Manages animation frame loop
+ */
+export class RenderLoop {
+    /**
+     * Create a RenderLoop
+     * @param {Function} updateFn - Update function called each frame with deltaTime
+     * @param {Function} renderFn - Render function called each frame
+     * @param {object} [options] - Configuration options
+     * @param {number} [options.targetFps=60] - Target frames per second
+     * @param {number} [options.maxDeltaTime=0.1] - Maximum delta time in seconds (prevents spiral of death)
+     */
+    constructor(updateFn, renderFn, options = {}) {
+        this._update = updateFn;
+        this._render = renderFn;
+
+        this._targetFps = options.targetFps || 60;
+        this._maxDeltaTime = options.maxDeltaTime || 0.1; // 100ms max
+        this._frameBudget = 1000 / this._targetFps; // ms per frame
+
+        this._running = false;
+        this._rafId = null;
+        this._lastTime = 0;
+        this._frameCount = 0;
+        this._deferredTasks = [];
+
+        // Performance tracking
+        this._fpsHistory = [];
+        this._fpsHistorySize = 60; // Track last 60 frames
+        this._lastFpsUpdate = 0;
+        this._currentFps = 0;
+    }
+
+    /**
+     * Start the render loop
+     */
+    start() {
+        if (this._running) {
+            logger.warn('RenderLoop already running');
+            return;
+        }
+
+        this._running = true;
+        this._lastTime = performance.now();
+        this._frameCount = 0;
+        logger.info('RenderLoop started');
+
+        this._tick();
+    }
+
+    /**
+     * Stop the render loop
+     */
+    stop() {
+        if (!this._running) {
+            return;
+        }
+
+        this._running = false;
+
+        if (this._rafId !== null) {
+            cancelAnimationFrame(this._rafId);
+            this._rafId = null;
+        }
+
+        logger.info(`RenderLoop stopped after ${this._frameCount} frames`);
+    }
+
+    /**
+     * Main loop tick
+     * @private
+     */
+    _tick = () => {
+        if (!this._running) {
+            return;
+        }
+
+        const frameStart = performance.now();
+        const rawDeltaTime = (frameStart - this._lastTime) / 1000; // Convert to seconds
+
+        // Clamp delta time to prevent spiral of death
+        const deltaTime = Math.min(rawDeltaTime, this._maxDeltaTime);
+
+        this._lastTime = frameStart;
+        this._frameCount++;
+
+        try {
+            // Update logic
+            this._update(deltaTime);
+
+            // Render
+            this._render();
+
+            // Process deferred tasks if time permits
+            const frameElapsed = performance.now() - frameStart;
+            const remainingTime = this._frameBudget - frameElapsed;
+
+            if (remainingTime > 1 && this._deferredTasks.length > 0) {
+                this._processDeferredTasks(remainingTime - 1); // Leave 1ms margin
+            }
+
+            // Update FPS tracking
+            this._updateFpsTracking(performance.now() - frameStart);
+
+        } catch (error) {
+            logger.error('Error in render loop:', error);
+            // Continue loop despite error
+        }
+
+        // Schedule next frame
+        this._rafId = requestAnimationFrame(this._tick);
+    };
+
+    /**
+     * Update FPS tracking
+     * @private
+     * @param {number} frameTime - Time taken for this frame in ms
+     */
+    _updateFpsTracking(frameTime) {
+        this._fpsHistory.push(1000 / frameTime);
+
+        if (this._fpsHistory.length > this._fpsHistorySize) {
+            this._fpsHistory.shift();
+        }
+
+        // Update FPS every second
+        const now = performance.now();
+        if (now - this._lastFpsUpdate > 1000) {
+            this._currentFps = this._fpsHistory.reduce((a, b) => a + b, 0) / this._fpsHistory.length;
+            this._lastFpsUpdate = now;
+        }
+    }
+
+    /**
+     * Process deferred tasks within time budget
+     * @private
+     * @param {number} maxTime - Maximum time in ms to spend on tasks
+     */
+    _processDeferredTasks(maxTime) {
+        const startTime = performance.now();
+
+        while (this._deferredTasks.length > 0) {
+            if (performance.now() - startTime >= maxTime) {
+                break;
+            }
+
+            const task = this._deferredTasks.shift();
+
+            try {
+                task.fn();
+            } catch (error) {
+                logger.error(`Error in deferred task: ${task.label}`, error);
+            }
+        }
+    }
+
+    /**
+     * Execute task if within frame budget, otherwise defer
+     *
+     * @param {Function} task - Task function to execute
+     * @param {number} [priority=0] - Task priority (higher = more important)
+     * @param {string} [label=''] - Task label for debugging
+     */
+    executeOrDefer(task, priority = 0, label = '') {
+        const frameElapsed = performance.now() - this._lastTime;
+
+        if (frameElapsed < this._frameBudget * 0.8) {
+            // Within budget, execute now
+            task();
+        } else {
+            // Over budget, defer
+            this._deferredTasks.push({ fn: task, priority, label });
+
+            // Sort by priority (higher first)
+            this._deferredTasks.sort((a, b) => b.priority - a.priority);
+        }
+    }
+
+    /**
+     * Get current FPS
+     * @returns {number} Average FPS over recent frames
+     */
+    getFps() {
+        return Math.round(this._currentFps);
+    }
+
+    /**
+     * Get performance stats
+     * @returns {object} Performance statistics
+     */
+    getStats() {
+        return {
+            fps: this.getFps(),
+            frameCount: this._frameCount,
+            deferredTaskCount: this._deferredTasks.length,
+            running: this._running
+        };
+    }
+
+    /**
+     * Check if loop is running
+     * @returns {boolean} True if running
+     */
+    isRunning() {
+        return this._running;
+    }
+
+    /**
+     * Get frame count
+     * @returns {number} Total frames rendered
+     */
+    getFrameCount() {
+        return this._frameCount;
+    }
+
+    /**
+     * Clear all deferred tasks
+     */
+    clearDeferredTasks() {
+        this._deferredTasks.length = 0;
+        logger.debug('Cleared all deferred tasks');
+    }
+}
+
+/**
+ * FrameBudgetMonitor - Monitors and alerts on frame budget violations
+ */
+export class FrameBudgetMonitor {
+    /**
+     * Create a FrameBudgetMonitor
+     * @param {number} [targetFps=60] - Target FPS
+     * @param {Function} [onViolation] - Callback when budget is violated
+     */
+    constructor(targetFps = 60, onViolation = null) {
+        this._targetFps = targetFps;
+        this._frameBudget = 1000 / targetFps;
+        this._onViolation = onViolation;
+        this._violations = 0;
+        this._frameStart = 0;
+    }
+
+    /**
+     * Mark start of frame
+     */
+    startFrame() {
+        this._frameStart = performance.now();
+    }
+
+    /**
+     * Check if frame is within budget
+     * @param {string} [location] - Location identifier for debugging
+     * @returns {boolean} True if within budget
+     */
+    checkBudget(location = '') {
+        const elapsed = performance.now() - this._frameStart;
+        const withinBudget = elapsed < this._frameBudget;
+
+        if (!withinBudget) {
+            this._violations++;
+
+            if (this._onViolation) {
+                this._onViolation({
+                    location,
+                    elapsed,
+                    budget: this._frameBudget,
+                    overrun: elapsed - this._frameBudget
+                });
+            }
+
+            logger.warn(`Frame budget violation at ${location}: ${elapsed.toFixed(2)}ms / ${this._frameBudget.toFixed(2)}ms`);
+        }
+
+        return withinBudget;
+    }
+
+    /**
+     * Get violation count
+     * @returns {number} Total violations
+     */
+    getViolationCount() {
+        return this._violations;
+    }
+
+    /**
+     * Reset violation count
+     */
+    resetViolations() {
+        this._violations = 0;
+    }
+}
+
+export default RenderLoop;