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

package/src/utils/BlobUrlManager.js

@@ -0,0 +1,294 @@
+/**
+ * BlobUrlManager - Secure blob URL lifecycle management
+ *
+ * Tracks blob URLs and ensures they are revoked to prevent memory leaks
+ * and unauthorized access. Critical for security and resource management.
+ */
+
+import { getLogger } from './Logger.js';
+import { ValidationError } from '../errors/index.js';
+
+const logger = getLogger('BlobUrlManager');
+
+/**
+ * BlobUrlManager - Manages blob URL lifecycle
+ */
+export class BlobUrlManager {
+    constructor() {
+        /**
+         * Map of blob URL to metadata
+         * @private
+         */
+        this._urls = new Map();
+
+        /**
+         * Whether manager has been disposed
+         * @private
+         */
+        this._disposed = false;
+    }
+
+    /**
+     * Assert manager is not disposed
+     * @private
+     * @throws {Error} If manager is disposed
+     */
+    _assertNotDisposed() {
+        if (this._disposed) {
+            throw new Error('BlobUrlManager has been disposed');
+        }
+    }
+
+    /**
+     * Create a blob URL from data
+     *
+     * @param {Blob|ArrayBuffer|Uint8Array} data - Data to create blob from
+     * @param {string} mimeType - MIME type (e.g., 'model/gltf-binary')
+     * @param {string} [label] - Optional label for debugging
+     * @returns {string} Blob URL
+     * @throws {ValidationError} If data or mimeType is invalid
+     */
+    createBlobUrl(data, mimeType, label = '') {
+        this._assertNotDisposed();
+
+        // Validate mimeType
+        if (typeof mimeType !== 'string' || mimeType.length === 0) {
+            throw new ValidationError(
+                'mimeType must be a non-empty string',
+                'mimeType'
+            );
+        }
+
+        // Convert data to Blob if needed
+        let blob;
+        if (data instanceof Blob) {
+            blob = data;
+        } else if (data instanceof ArrayBuffer || data instanceof Uint8Array) {
+            blob = new Blob([data], { type: mimeType });
+        } else {
+            throw new ValidationError(
+                'data must be Blob, ArrayBuffer, or Uint8Array',
+                'data'
+            );
+        }
+
+        // Create blob URL
+        const url = URL.createObjectURL(blob);
+
+        // Track metadata
+        this._urls.set(url, {
+            createdAt: Date.now(),
+            mimeType,
+            label: label || 'unlabeled',
+            size: blob.size
+        });
+
+        logger.debug(`Created blob URL: ${label || url.substring(0, 50)}, size: ${blob.size} bytes`);
+
+        return url;
+    }
+
+    /**
+     * Register an externally created blob URL for tracking
+     *
+     * @param {string} url - Blob URL to track
+     * @param {string} [label] - Optional label for debugging
+     * @throws {ValidationError} If URL is not a blob URL
+     */
+    registerBlobUrl(url, label = '') {
+        this._assertNotDisposed();
+
+        if (typeof url !== 'string' || !url.startsWith('blob:')) {
+            throw new ValidationError(
+                'url must be a valid blob URL',
+                'url'
+            );
+        }
+
+        if (!this._urls.has(url)) {
+            this._urls.set(url, {
+                createdAt: Date.now(),
+                mimeType: 'unknown',
+                label: label || 'registered-external',
+                size: 0
+            });
+
+            logger.debug(`Registered external blob URL: ${label || url.substring(0, 50)}`);
+        }
+    }
+
+    /**
+     * Revoke a blob URL and remove from tracking
+     *
+     * @param {string} url - Blob URL to revoke
+     * @returns {boolean} True if URL was tracked and revoked
+     */
+    revokeBlobUrl(url) {
+        this._assertNotDisposed();
+
+        if (this._urls.has(url)) {
+            const metadata = this._urls.get(url);
+            URL.revokeObjectURL(url);
+            this._urls.delete(url);
+
+            logger.debug(`Revoked blob URL: ${metadata.label}, age: ${Date.now() - metadata.createdAt}ms`);
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Revoke all blob URLs and clear tracking
+     */
+    revokeAll() {
+        this._assertNotDisposed();
+
+        logger.debug(`Revoking ${this._urls.size} blob URLs`);
+
+        for (const url of this._urls.keys()) {
+            URL.revokeObjectURL(url);
+        }
+
+        this._urls.clear();
+    }
+
+    /**
+     * Get tracked blob URL metadata
+     *
+     * @param {string} url - Blob URL
+     * @returns {object|null} Metadata or null if not tracked
+     */
+    getMetadata(url) {
+        return this._urls.get(url) || null;
+    }
+
+    /**
+     * Get all tracked blob URLs
+     *
+     * @returns {Array<{url: string, metadata: object}>} Array of URL info
+     */
+    getAllTrackedUrls() {
+        const urls = [];
+        for (const [url, metadata] of this._urls.entries()) {
+            urls.push({ url, metadata });
+        }
+        return urls;
+    }
+
+    /**
+     * Get statistics about tracked URLs
+     *
+     * @returns {object} Statistics
+     */
+    getStats() {
+        let totalSize = 0;
+        let oldestAge = 0;
+        const now = Date.now();
+
+        for (const metadata of this._urls.values()) {
+            totalSize += metadata.size;
+            const age = now - metadata.createdAt;
+            if (age > oldestAge) {
+                oldestAge = age;
+            }
+        }
+
+        return {
+            count: this._urls.size,
+            totalSize,
+            oldestAge
+        };
+    }
+
+    /**
+     * Revoke blob URLs older than specified age
+     *
+     * @param {number} maxAgeMs - Maximum age in milliseconds
+     * @returns {number} Number of URLs revoked
+     */
+    revokeOlderThan(maxAgeMs) {
+        this._assertNotDisposed();
+
+        const now = Date.now();
+        const toRevoke = [];
+
+        for (const [url, metadata] of this._urls.entries()) {
+            const age = now - metadata.createdAt;
+            if (age > maxAgeMs) {
+                toRevoke.push(url);
+            }
+        }
+
+        for (const url of toRevoke) {
+            this.revokeBlobUrl(url);
+        }
+
+        if (toRevoke.length > 0) {
+            logger.info(`Revoked ${toRevoke.length} blob URLs older than ${maxAgeMs}ms`);
+        }
+
+        return toRevoke.length;
+    }
+
+    /**
+     * Check if a URL is being tracked
+     *
+     * @param {string} url - URL to check
+     * @returns {boolean} True if URL is tracked
+     */
+    isTracked(url) {
+        return this._urls.has(url);
+    }
+
+    /**
+     * Dispose manager and revoke all URLs
+     */
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+
+        logger.debug('Disposing BlobUrlManager');
+        this.revokeAll();
+        this._disposed = true;
+    }
+}
+
+/**
+ * Global blob URL manager instance
+ * @type {BlobUrlManager}
+ */
+const globalBlobUrlManager = new BlobUrlManager();
+
+/**
+ * Get the global blob URL manager
+ * @returns {BlobUrlManager} Global manager instance
+ */
+export function getGlobalBlobUrlManager() {
+    return globalBlobUrlManager;
+}
+
+/**
+ * Helper function to create a blob URL with automatic tracking
+ *
+ * @param {Blob|ArrayBuffer|Uint8Array} data - Data to create blob from
+ * @param {string} mimeType - MIME type
+ * @param {string} [label] - Optional label for debugging
+ * @returns {string} Blob URL
+ */
+export function createTrackedBlobUrl(data, mimeType, label) {
+    return globalBlobUrlManager.createBlobUrl(data, mimeType, label);
+}
+
+/**
+ * Helper function to revoke a blob URL
+ *
+ * @param {string} url - Blob URL to revoke
+ * @returns {boolean} True if URL was tracked and revoked
+ */
+export function revokeTrackedBlobUrl(url) {
+    return globalBlobUrlManager.revokeBlobUrl(url);
+}
+
+export default BlobUrlManager;

package/src/utils/EventEmitter.js

@@ -0,0 +1,349 @@
+/**
+ * EventEmitter - Observer pattern implementation for event-driven communication
+ *
+ * Provides decoupled event handling with automatic cleanup to prevent memory leaks.
+ * Critical for managing state changes and component communication.
+ */
+
+import { getLogger } from './Logger.js';
+import { ValidationError } from '../errors/index.js';
+
+const logger = getLogger('EventEmitter');
+
+/**
+ * EventEmitter - Pub/sub event system
+ */
+export class EventEmitter {
+    constructor() {
+        /**
+         * Map of event name to Set of listeners
+         * @private
+         */
+        this._listeners = new Map();
+
+        /**
+         * Whether emitter has been disposed
+         * @private
+         */
+        this._disposed = false;
+
+        /**
+         * Event emission history for debugging (last N events)
+         * @private
+         */
+        this._eventHistory = [];
+        this._maxHistorySize = 50;
+    }
+
+    /**
+     * Assert emitter is not disposed
+     * @private
+     * @throws {Error} If emitter is disposed
+     */
+    _assertNotDisposed() {
+        if (this._disposed) {
+            throw new Error('EventEmitter has been disposed');
+        }
+    }
+
+    /**
+     * Subscribe to an event
+     *
+     * @param {string} event - Event name
+     * @param {Function} callback - Event handler
+     * @param {object} [options] - Subscription options
+     * @param {boolean} [options.once=false] - Auto-unsubscribe after first call
+     * @returns {Function} Unsubscribe function
+     * @throws {ValidationError} If parameters are invalid
+     */
+    on(event, callback, options = {}) {
+        this._assertNotDisposed();
+
+        if (typeof event !== 'string' || event.length === 0) {
+            throw new ValidationError(
+                'event must be a non-empty string',
+                'event'
+            );
+        }
+
+        if (typeof callback !== 'function') {
+            throw new ValidationError(
+                'callback must be a function',
+                'callback'
+            );
+        }
+
+        // Wrap callback if once option is set
+        const wrappedCallback = options.once
+            ? (...args) => {
+                this.off(event, wrappedCallback);
+                callback(...args);
+            }
+            : callback;
+
+        // Store original callback reference for removal
+        if (options.once) {
+            wrappedCallback._originalCallback = callback;
+        }
+
+        // Add listener
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set());
+        }
+        this._listeners.get(event).add(wrappedCallback);
+
+        logger.debug(`Subscribed to event: ${event}`);
+
+        // Return unsubscribe function
+        return () => this.off(event, wrappedCallback);
+    }
+
+    /**
+     * Subscribe to an event (fires once then auto-unsubscribes)
+     *
+     * @param {string} event - Event name
+     * @param {Function} callback - Event handler
+     * @returns {Function} Unsubscribe function
+     */
+    once(event, callback) {
+        return this.on(event, callback, { once: true });
+    }
+
+    /**
+     * Unsubscribe from an event
+     *
+     * @param {string} event - Event name
+     * @param {Function} callback - Event handler to remove
+     * @returns {boolean} True if callback was found and removed
+     */
+    off(event, callback) {
+        this._assertNotDisposed();
+
+        const listeners = this._listeners.get(event);
+        if (!listeners) {
+            return false;
+        }
+
+        // Try to remove directly
+        if (listeners.delete(callback)) {
+            logger.debug(`Unsubscribed from event: ${event}`);
+            return true;
+        }
+
+        // Try to find by original callback (for once listeners)
+        for (const listener of listeners) {
+            if (listener._originalCallback === callback) {
+                listeners.delete(listener);
+                logger.debug(`Unsubscribed from event: ${event} (once listener)`);
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Remove all listeners for an event (or all events if no event specified)
+     *
+     * @param {string} [event] - Event name (optional)
+     */
+    removeAllListeners(event = null) {
+        this._assertNotDisposed();
+
+        if (event) {
+            const count = this._listeners.get(event)?.size || 0;
+            this._listeners.delete(event);
+            logger.debug(`Removed ${count} listeners for event: ${event}`);
+        } else {
+            const totalCount = Array.from(this._listeners.values())
+                .reduce((sum, set) => sum + set.size, 0);
+            this._listeners.clear();
+            logger.debug(`Removed all ${totalCount} listeners`);
+        }
+    }
+
+    /**
+     * Emit an event to all subscribers
+     *
+     * @param {string} event - Event name
+     * @param {...*} args - Arguments to pass to listeners
+     * @returns {boolean} True if event had listeners
+     */
+    emit(event, ...args) {
+        this._assertNotDisposed();
+
+        const listeners = this._listeners.get(event);
+        if (!listeners || listeners.size === 0) {
+            return false;
+        }
+
+        // Record in history for debugging
+        this._recordEvent(event, args);
+
+        // Call all listeners
+        let callCount = 0;
+        for (const callback of listeners) {
+            try {
+                callback(...args);
+                callCount++;
+            } catch (error) {
+                logger.error(`Error in event listener for '${event}':`, error);
+                // Continue calling other listeners
+            }
+        }
+
+        logger.debug(`Emitted event: ${event} to ${callCount} listeners`);
+
+        return true;
+    }
+
+    /**
+     * Record event in history for debugging
+     * @private
+     * @param {string} event - Event name
+     * @param {Array} args - Event arguments
+     */
+    _recordEvent(event, args) {
+        this._eventHistory.push({
+            event,
+            timestamp: Date.now(),
+            argCount: args.length
+        });
+
+        // Keep history bounded
+        if (this._eventHistory.length > this._maxHistorySize) {
+            this._eventHistory.shift();
+        }
+    }
+
+    /**
+     * Get event emission history
+     * @returns {Array} Array of event records
+     */
+    getEventHistory() {
+        return [...this._eventHistory];
+    }
+
+    /**
+     * Check if event has listeners
+     *
+     * @param {string} event - Event name
+     * @returns {boolean} True if event has listeners
+     */
+    hasListeners(event) {
+        const listeners = this._listeners.get(event);
+        return listeners ? listeners.size > 0 : false;
+    }
+
+    /**
+     * Get listener count for an event
+     *
+     * @param {string} event - Event name
+     * @returns {number} Number of listeners
+     */
+    listenerCount(event) {
+        const listeners = this._listeners.get(event);
+        return listeners ? listeners.size : 0;
+    }
+
+    /**
+     * Get all event names with listeners
+     *
+     * @returns {string[]} Array of event names
+     */
+    eventNames() {
+        return Array.from(this._listeners.keys());
+    }
+
+    /**
+     * Get statistics about listeners
+     *
+     * @returns {object} Statistics
+     */
+    getStats() {
+        const stats = {
+            totalEvents: this._listeners.size,
+            totalListeners: 0,
+            eventBreakdown: {}
+        };
+
+        for (const [event, listeners] of this._listeners.entries()) {
+            const count = listeners.size;
+            stats.totalListeners += count;
+            stats.eventBreakdown[event] = count;
+        }
+
+        return stats;
+    }
+
+    /**
+     * Dispose emitter and remove all listeners
+     */
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+
+        logger.debug('Disposing EventEmitter');
+        this.removeAllListeners();
+        this._eventHistory.length = 0;
+        this._disposed = true;
+    }
+}
+
+/**
+ * TypedEventEmitter - Type-safe event emitter with event registry
+ *
+ * Ensures events are pre-registered, preventing typos and providing
+ * better developer experience.
+ */
+export class TypedEventEmitter extends EventEmitter {
+    /**
+     * Create a TypedEventEmitter
+     * @param {string[]} allowedEvents - Array of allowed event names
+     */
+    constructor(allowedEvents) {
+        super();
+
+        /**
+         * Set of allowed event names
+         * @private
+         */
+        this._allowedEvents = new Set(allowedEvents);
+    }
+
+    /**
+     * Validate event name is allowed
+     * @private
+     * @param {string} event - Event name
+     * @throws {ValidationError} If event is not allowed
+     */
+    _validateEvent(event) {
+        if (!this._allowedEvents.has(event)) {
+            throw new ValidationError(
+                `Event '${event}' is not registered. Allowed events: ${Array.from(this._allowedEvents).join(', ')}`,
+                'event'
+            );
+        }
+    }
+
+    /**
+     * Subscribe to an event (override to add validation)
+     * @override
+     */
+    on(event, callback, options) {
+        this._validateEvent(event);
+        return super.on(event, callback, options);
+    }
+
+    /**
+     * Emit an event (override to add validation)
+     * @override
+     */
+    emit(event, ...args) {
+        this._validateEvent(event);
+        return super.emit(event, ...args);
+    }
+}
+
+export default EventEmitter;

package/src/utils/LoaderUtils.js

@@ -28,7 +28,8 @@ export class LoaderUtils {
         try {
             // merges multi-byte utf-8 characters.
             return decodeURIComponent(escape(s));
-        } catch (e) { // see #16358
+        } catch {
+            // see #16358 - ignore decoding errors
             return s;
         }
     }