@grandgular/rive-angular 0.1.2 → 0.2.0

package/fesm2022/grandgular-rive-angular.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { viewChild, inject, DestroyRef, PLATFORM_ID, NgZone, input, output, signal, effect, untracked, ChangeDetectionStrategy, Component, Injectable } from '@angular/core';
+import { inject, PLATFORM_ID, Injectable, InjectionToken, viewChild, DestroyRef, NgZone, input, output, signal, effect, untracked, ChangeDetectionStrategy, Component } from '@angular/core';
 import { isPlatformBrowser } from '@angular/common';
 import { Fit, Alignment, Layout, Rive, RiveFile, EventType } from '@rive-app/canvas';
 export { Alignment, EventType, Fit, Layout, Rive, RiveFile, StateMachineInput } from '@rive-app/canvas';
@@ -8,16 +8,104 @@ export { Alignment, EventType, Fit, Layout, Rive, RiveFile, StateMachineInput }
  * Re-export Rive SDK types for consumer convenience
  */
 /**
- * Error thrown when Rive animation fails to load
+ * Error thrown when Rive animation fails to load.
+ * Supports legacy constructor for backward compatibility.
  */
 class RiveLoadError extends Error {
+    code;
+    suggestion;
+    docsUrl;
     originalError;
-    constructor(message, originalError) {
-        super(message);
-        this.originalError = originalError;
+    constructor(messageOrOptions, originalError) {
+        if (typeof messageOrOptions === 'string') {
+            // Legacy constructor: new RiveLoadError(message, originalError)
+            super(messageOrOptions);
+            this.originalError =
+                originalError instanceof Error ? originalError : undefined;
+        }
+        else {
+            // New constructor: new RiveLoadError(options)
+            super(messageOrOptions.message);
+            this.code = messageOrOptions.code;
+            this.suggestion = messageOrOptions.suggestion;
+            this.docsUrl = messageOrOptions.docsUrl;
+            this.originalError =
+                messageOrOptions.cause instanceof Error
+                    ? messageOrOptions.cause
+                    : undefined;
+        }
         this.name = 'RiveLoadError';
     }
 }
+/**
+ * Error thrown when validation fails (e.g. missing artboard/animation/input).
+ * These errors are typically non-fatal but indicate a configuration mismatch.
+ */
+class RiveValidationError extends Error {
+    code;
+    availableOptions;
+    suggestion;
+    constructor(message, code, availableOptions, suggestion) {
+        super(message);
+        this.code = code;
+        this.availableOptions = availableOptions;
+        this.suggestion = suggestion;
+        this.name = 'RiveValidationError';
+    }
+}
+
+/**
+ * Error codes used throughout the Rive Angular library.
+ *
+ * Ranges:
+ * - RIVE_1xx: Load errors (file not found, network, bad format)
+ * - RIVE_2xx: Validation errors (artboard, animation, state machine mismatch)
+ * - RIVE_3xx: Configuration/Usage errors (missing source, bad canvas)
+ */
+var RiveErrorCode;
+(function (RiveErrorCode) {
+    // Load Errors
+    RiveErrorCode["FileNotFound"] = "RIVE_101";
+    RiveErrorCode["InvalidFormat"] = "RIVE_102";
+    RiveErrorCode["NetworkError"] = "RIVE_103";
+    // Validation Errors
+    RiveErrorCode["ArtboardNotFound"] = "RIVE_201";
+    RiveErrorCode["AnimationNotFound"] = "RIVE_202";
+    RiveErrorCode["StateMachineNotFound"] = "RIVE_203";
+    RiveErrorCode["InputNotFound"] = "RIVE_204";
+    // Configuration Errors
+    RiveErrorCode["NoSource"] = "RIVE_301";
+    RiveErrorCode["InvalidCanvas"] = "RIVE_302";
+})(RiveErrorCode || (RiveErrorCode = {}));
+/**
+ * Template messages for each error code.
+ * Used by formatErrorMessage to generate user-friendly descriptions.
+ */
+const ERROR_MESSAGES = {
+    [RiveErrorCode.FileNotFound]: 'File not found: {url}',
+    [RiveErrorCode.InvalidFormat]: 'Invalid .riv file format',
+    [RiveErrorCode.NetworkError]: 'Network error while loading file',
+    [RiveErrorCode.ArtboardNotFound]: 'Artboard "{name}" not found',
+    [RiveErrorCode.AnimationNotFound]: 'Animation "{name}" not found',
+    [RiveErrorCode.StateMachineNotFound]: 'State machine "{name}" not found',
+    [RiveErrorCode.InputNotFound]: 'Input "{name}" not found in "{stateMachine}"',
+    [RiveErrorCode.NoSource]: 'No animation source provided',
+    [RiveErrorCode.InvalidCanvas]: 'Invalid canvas element',
+};
+/**
+ * Formats an error message by replacing placeholders with actual values.
+ *
+ * @param code - The error code
+ * @param params - Record of values to replace in the template (e.g. { name: 'MyAnim' })
+ * @returns The formatted error string
+ */
+function formatErrorMessage(code, params = {}) {
+    let message = ERROR_MESSAGES[code] || 'Unknown Rive error';
+    for (const [key, value] of Object.entries(params)) {
+        message = message.replace(`{${key}}`, value);
+    }
+    return message;
+}
 
 /**
  * Fake IntersectionObserver for environments where it's not available (e.g., SSR)
@@ -45,12 +133,21 @@ const MyIntersectionObserver = (typeof globalThis !== 'undefined' && globalThis.
  * Singleton IntersectionObserver wrapper for observing multiple elements
  * with individual callbacks. This avoids creating multiple IntersectionObserver
  * instances which is more efficient.
+ *
+ * Provided as an Angular service for better testability and DI integration.
  */
 class ElementObserver {
     observer;
     elementsMap = new Map();
+    platformId = inject(PLATFORM_ID);
     constructor() {
-        this.observer = new MyIntersectionObserver(this.onObserved);
+        // Only create real observer in browser environment
+        if (isPlatformBrowser(this.platformId)) {
+            this.observer = new MyIntersectionObserver(this.onObserved);
+        }
+        else {
+            this.observer = new FakeIntersectionObserver();
+        }
     }
     onObserved = (entries) => {
         entries.forEach((entry) => {
@@ -68,17 +165,238 @@ class ElementObserver {
         this.observer.unobserve(element);
         this.elementsMap.delete(element);
     }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: ElementObserver, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: ElementObserver, providedIn: 'root' });
 }
-// Singleton instance
-let observerInstance = null;
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: ElementObserver, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }], ctorParameters: () => [] });
+// Legacy function for backward compatibility
+// New code should inject ElementObserver directly
+let legacyObserverInstance = null;
 /**
+ * @deprecated Use dependency injection instead: `inject(ElementObserver)`
  * Get the singleton ElementObserver instance
  */
 function getElementObserver() {
-    if (!observerInstance) {
-        observerInstance = new ElementObserver();
+    if (!legacyObserverInstance) {
+        legacyObserverInstance = new ElementObserver();
+    }
+    return legacyObserverInstance;
+}
+
+/**
+ * Injection token for global Rive debug configuration.
+ * Can be provided via provideRiveDebug().
+ */
+const RIVE_DEBUG_CONFIG = new InjectionToken('RIVE_DEBUG_CONFIG');
+/**
+ * Provides global configuration for Rive debugging.
+ * Use this in your app.config.ts or module providers.
+ *
+ * @example
+ * providers: [
+ *   provideRiveDebug({ logLevel: 'debug' })
+ * ]
+ */
+function provideRiveDebug(config) {
+    return {
+        provide: RIVE_DEBUG_CONFIG,
+        useValue: config,
+    };
+}
+
+/**
+ * Internal logger for Rive Angular library.
+ * Handles log levels and formatting.
+ * Not exported publicly.
+ */
+class RiveLogger {
+    level;
+    constructor(globalConfig, localDebug) {
+        this.level = this.resolveLogLevel(globalConfig, localDebug);
+    }
+    /**
+     * Resolve effective log level based on precedence rules:
+     * 1. Local debug=true -> 'debug'
+     * 2. Local debug=false/undefined -> Use global config
+     * 3. No config -> 'error' (default)
+     */
+    resolveLogLevel(globalConfig, localDebug) {
+        if (localDebug === true) {
+            return 'debug';
+        }
+        if (globalConfig?.logLevel) {
+            return globalConfig.logLevel;
+        }
+        return 'error';
+    }
+    /**
+     * Update log level dynamically (e.g. when input changes)
+     */
+    update(globalConfig, localDebug) {
+        this.level = this.resolveLogLevel(globalConfig, localDebug);
+    }
+    debug(message, ...args) {
+        if (this.shouldLog('debug')) {
+            console.debug(`[Rive] ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.shouldLog('info')) {
+            console.info(`[Rive] ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(`[Rive] ${message}`, ...args);
+        }
+    }
+    error(message, ...args) {
+        if (this.shouldLog('error')) {
+            console.error(`[Rive] ${message}`, ...args);
+        }
+    }
+    shouldLog(level) {
+        const levels = ['none', 'error', 'warn', 'info', 'debug'];
+        const currentIdx = levels.indexOf(this.level);
+        const targetIdx = levels.indexOf(level);
+        return currentIdx >= targetIdx;
+    }
+}
+
+/**
+ * Validates requested artboard name against available artboards.
+ * Returns error if not found.
+ */
+function validateArtboard(rive, requestedName) {
+    if (!requestedName)
+        return null;
+    try {
+        // Safe check: ensure artboardNames exist on runtime
+        // Note: These properties exist at runtime but may not be in type definitions
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const available = rive.artboardNames;
+        if (!available || !available.includes(requestedName)) {
+            return new RiveValidationError(formatErrorMessage(RiveErrorCode.ArtboardNotFound, {
+                name: requestedName,
+            }), RiveErrorCode.ArtboardNotFound, available || [], available && available.length > 0
+                ? `Available artboards: ${available.join(', ')}`
+                : 'No artboards found in file');
+        }
+    }
+    catch {
+        // Graceful fallback if runtime metadata is not accessible
+        // Return null silently to avoid breaking validation flow
+    }
+    return null;
+}
+/**
+ * Validates requested animation names against available animations.
+ * Returns first error found.
+ */
+function validateAnimations(rive, requestedNames) {
+    if (!requestedNames)
+        return null;
+    const names = Array.isArray(requestedNames)
+        ? requestedNames
+        : [requestedNames];
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const available = rive.animationNames;
+        for (const name of names) {
+            if (!available || !available.includes(name)) {
+                return new RiveValidationError(formatErrorMessage(RiveErrorCode.AnimationNotFound, { name }), RiveErrorCode.AnimationNotFound, available || [], available && available.length > 0
+                    ? `Available animations: ${available.join(', ')}`
+                    : 'No animations found in file');
+            }
+        }
+    }
+    catch {
+        // Graceful fallback if runtime metadata is not accessible
+        // Return null silently to avoid breaking validation flow
+    }
+    return null;
+}
+/**
+ * Validates requested state machine names against available state machines.
+ * Returns first error found.
+ */
+function validateStateMachines(rive, requestedNames) {
+    if (!requestedNames)
+        return null;
+    const names = Array.isArray(requestedNames)
+        ? requestedNames
+        : [requestedNames];
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const available = rive.stateMachineNames;
+        for (const name of names) {
+            if (!available || !available.includes(name)) {
+                return new RiveValidationError(formatErrorMessage(RiveErrorCode.StateMachineNotFound, { name }), RiveErrorCode.StateMachineNotFound, available || [], available && available.length > 0
+                    ? `Available state machines: ${available.join(', ')}`
+                    : 'No state machines found in file');
+            }
+        }
+    }
+    catch {
+        // Graceful fallback if runtime metadata is not accessible
+        // Return null silently to avoid breaking validation flow
+    }
+    return null;
+}
+/**
+ * Validates if an input exists within a specific state machine.
+ */
+function validateInput(rive, stateMachineName, inputName) {
+    try {
+        const inputs = rive.stateMachineInputs(stateMachineName);
+        if (!inputs)
+            return null; // Should not happen if SM exists
+        const found = inputs.find((i) => i.name === inputName);
+        if (!found) {
+            const available = inputs.map((i) => i.name);
+            return new RiveValidationError(formatErrorMessage(RiveErrorCode.InputNotFound, {
+                name: inputName,
+                stateMachine: stateMachineName,
+            }), RiveErrorCode.InputNotFound, available, available.length > 0
+                ? `Available inputs in "${stateMachineName}": ${available.join(', ')}`
+                : `No inputs found in state machine "${stateMachineName}"`);
+        }
+    }
+    catch {
+        // Graceful fallback if runtime metadata is not accessible
+        // Return null silently to avoid breaking validation flow
     }
-    return observerInstance;
+    return null;
+}
+/**
+ * Runs full configuration validation.
+ * Logs warnings and returns array of errors.
+ */
+function validateConfiguration(rive, config, logger) {
+    const errors = [];
+    const artboardError = validateArtboard(rive, config.artboard);
+    if (artboardError)
+        errors.push(artboardError);
+    const animError = validateAnimations(rive, config.animations);
+    if (animError)
+        errors.push(animError);
+    const smError = validateStateMachines(rive, config.stateMachines);
+    if (smError)
+        errors.push(smError);
+    if (errors.length > 0) {
+        logger.warn(`Validation failed with ${errors.length} errors:`);
+        errors.forEach((err) => {
+            logger.warn(`- ${err.message}`);
+            if (err.suggestion)
+                logger.warn(`  Suggestion: ${err.suggestion}`);
+        });
+    }
+    return errors;
 }
 
 /**
@@ -110,6 +428,8 @@ class RiveCanvasComponent {
     #destroyRef = inject(DestroyRef);
     #platformId = inject(PLATFORM_ID);
     #ngZone = inject(NgZone);
+    #globalDebugConfig = inject(RIVE_DEBUG_CONFIG, { optional: true });
+    #elementObserver = inject(ElementObserver);
     src = input(...(ngDevMode ? [undefined, { debugName: "src" }] : []));
     buffer = input(...(ngDevMode ? [undefined, { debugName: "buffer" }] : []));
     /**
@@ -139,6 +459,13 @@ class RiveCanvasComponent {
      * Default is false for security - events must be handled manually via riveEvent output.
      */
     automaticallyHandleEvents = input(false, ...(ngDevMode ? [{ debugName: "automaticallyHandleEvents" }] : []));
+    /**
+     * Enable debug mode for this specific instance.
+     * Overrides global configuration if set.
+     * - true: 'debug' level
+     * - false/undefined: use global level
+     */
+    debugMode = input(...(ngDevMode ? [undefined, { debugName: "debugMode" }] : []));
     // Outputs (Events)
     loaded = output();
     loadError = output();
@@ -153,21 +480,28 @@ class RiveCanvasComponent {
      */
     riveEvent = output();
     /**
-     * Emitted when Rive instance is created and ready.
+     * Emitted when Rive instance is fully loaded and ready.
      * Provides direct access to the Rive instance for advanced use cases.
+     * Note: This fires AFTER the animation is loaded, not just instantiated.
      */
     riveReady = output();
-    // Signals for reactive state
-    isPlaying = signal(false, ...(ngDevMode ? [{ debugName: "isPlaying" }] : []));
-    isPaused = signal(false, ...(ngDevMode ? [{ debugName: "isPaused" }] : []));
-    isLoaded = signal(false, ...(ngDevMode ? [{ debugName: "isLoaded" }] : []));
+    // Private writable signals
+    #isPlaying = signal(false, ...(ngDevMode ? [{ debugName: "#isPlaying" }] : []));
+    #isPaused = signal(false, ...(ngDevMode ? [{ debugName: "#isPaused" }] : []));
+    #isLoaded = signal(false, ...(ngDevMode ? [{ debugName: "#isLoaded" }] : []));
+    #riveInstance = signal(null, ...(ngDevMode ? [{ debugName: "#riveInstance" }] : []));
+    // Public readonly signals
+    isPlaying = this.#isPlaying.asReadonly();
+    isPaused = this.#isPaused.asReadonly();
+    isLoaded = this.#isLoaded.asReadonly();
     /**
      * Public signal providing access to the Rive instance.
      * Use this to access advanced Rive SDK features.
      */
-    riveInstance = signal(null, ...(ngDevMode ? [{ debugName: "riveInstance" }] : []));
+    riveInstance = this.#riveInstance.asReadonly();
     // Private state
     #rive = null;
+    logger;
     resizeObserver = null;
     isInitialized = false;
     isPausedByIntersectionObserver = false;
@@ -176,11 +510,20 @@ class RiveCanvasComponent {
     lastWidth = 0;
     lastHeight = 0;
     constructor() {
-        // Effect to reload animation when src, buffer, or riveFile changes
+        this.logger = new RiveLogger(this.#globalDebugConfig, this.debugMode());
+        // Effect to update logger level when debugMode changes
+        effect(() => {
+            this.logger.update(this.#globalDebugConfig, this.debugMode());
+        });
+        // Effect to reload animation when src, buffer, riveFile, or configuration changes
         effect(() => {
             const src = this.src();
             const buffer = this.buffer();
             const riveFile = this.riveFile();
+            // Track configuration changes to trigger reload
+            this.artboard();
+            this.animations();
+            this.stateMachines();
             untracked(() => {
                 if ((src || buffer || riveFile) &&
                     isPlatformBrowser(this.#platformId) &&
@@ -188,6 +531,17 @@ class RiveCanvasComponent {
                     this.loadAnimation();
             });
         });
+        // Effect to update layout when fit or alignment changes
+        effect(() => {
+            const fit = this.fit();
+            const alignment = this.alignment();
+            untracked(() => {
+                if (this.#rive && isPlatformBrowser(this.#platformId)) {
+                    const layoutParams = { fit, alignment };
+                    this.#rive.layout = new Layout(layoutParams);
+                }
+            });
+        });
         // Auto cleanup on destroy
         this.#destroyRef.onDestroy(() => {
             this.cleanupRive();
@@ -208,7 +562,6 @@ class RiveCanvasComponent {
      */
     setupResizeObserver() {
         const canvas = this.canvas().nativeElement;
-        const dpr = window.devicePixelRatio || 1;
         this.resizeObserver = new ResizeObserver((entries) => {
             // Cancel any pending resize frame
             if (this.resizeRafId) {
@@ -224,6 +577,8 @@ class RiveCanvasComponent {
                 this.lastHeight = height;
                 // Defer resize to next animation frame to prevent excessive updates in Safari
                 this.resizeRafId = requestAnimationFrame(() => {
+                    // Read current DPR to support monitor changes and zoom
+                    const dpr = window.devicePixelRatio || 1;
                     // Set canvas size with device pixel ratio for sharp rendering
                     canvas.width = width * dpr;
                     canvas.height = height * dpr;
@@ -255,7 +610,6 @@ class RiveCanvasComponent {
         if (!this.shouldUseIntersectionObserver())
             return;
         const canvas = this.canvas().nativeElement;
-        const observer = getElementObserver();
         const onIntersectionChange = (entry) => {
             if (entry.isIntersecting) {
                 // Canvas is visible - start rendering
@@ -282,7 +636,7 @@ class RiveCanvasComponent {
                 }
             }
         };
-        observer.registerCallback(canvas, onIntersectionChange);
+        this.#elementObserver.registerCallback(canvas, onIntersectionChange);
     }
     /**
      * Retest intersection - workaround for Chrome bug
@@ -314,8 +668,7 @@ class RiveCanvasComponent {
         }
         if (this.shouldUseIntersectionObserver()) {
             const canvas = this.canvas().nativeElement;
-            const observer = getElementObserver();
-            observer.removeCallback(canvas);
+            this.#elementObserver.removeCallback(canvas);
         }
     }
     /**
@@ -331,16 +684,27 @@ class RiveCanvasComponent {
                 const src = this.src();
                 const buffer = this.buffer();
                 const riveFile = this.riveFile();
-                if (!src && !buffer && !riveFile)
+                if (!src && !buffer && !riveFile) {
+                    this.logger.warn('No animation source provided (src, buffer, or riveFile)');
+                    this.#ngZone.run(() => this.loadError.emit(new RiveLoadError({
+                        message: 'No animation source provided',
+                        code: RiveErrorCode.NoSource,
+                    })));
                     return;
+                }
+                this.logger.info(`Loading animation`, {
+                    src: src || (buffer ? 'buffer' : 'riveFile'),
+                    canvasWidth: canvas.width,
+                    canvasHeight: canvas.height,
+                    dpr: window.devicePixelRatio,
+                });
                 // Build layout configuration
                 const layoutParams = {
                     fit: this.fit(),
                     alignment: this.alignment(),
                 };
-                // Create Rive instance configuration
-                // Using Record to allow dynamic property assignment
-                const config = {
+                // Build typed Rive configuration
+                const baseConfig = {
                     canvas,
                     autoplay: this.autoplay(),
                     layout: new Layout(layoutParams),
@@ -355,73 +719,114 @@ class RiveCanvasComponent {
                     onStateChange: (event) => this.onStateChange(event),
                     onRiveEvent: (event) => this.onRiveEvent(event),
                 };
-                // Add src, buffer, or riveFile (priority: riveFile > src > buffer)
-                if (riveFile) {
-                    config['riveFile'] = riveFile;
-                }
-                else if (src) {
-                    config['src'] = src;
-                }
-                else if (buffer) {
-                    config['buffer'] = buffer;
-                }
-                // Add artboard if specified
-                const artboard = this.artboard();
-                if (artboard)
-                    config['artboard'] = artboard;
-                // Add animations if specified
-                const animations = this.animations();
-                if (animations)
-                    config['animations'] = animations;
-                // Add state machines if specified
-                const stateMachines = this.stateMachines();
-                if (stateMachines)
-                    config['stateMachines'] = stateMachines;
-                // Safe type assertion - config contains all required properties
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                // Add source (priority: riveFile > src > buffer)
+                const sourceConfig = riveFile
+                    ? { riveFile }
+                    : src
+                        ? { src }
+                        : buffer
+                            ? { buffer }
+                            : {};
+                // Add optional configuration
+                const optionalConfig = {
+                    ...(this.artboard() ? { artboard: this.artboard() } : {}),
+                    ...(this.animations() ? { animations: this.animations() } : {}),
+                    ...(this.stateMachines()
+                        ? { stateMachines: this.stateMachines() }
+                        : {}),
+                };
+                // Combine all configurations
+                const config = { ...baseConfig, ...sourceConfig, ...optionalConfig };
                 this.#rive = new Rive(config);
-                // Update public signal and emit riveReady event
+                // Update public signal (riveReady will be emitted in onLoad)
                 this.#ngZone.run(() => {
-                    this.riveInstance.set(this.#rive);
-                    this.riveReady.emit(this.#rive);
+                    this.#riveInstance.set(this.#rive);
                 });
             }
             catch (error) {
-                console.error('Failed to initialize Rive instance:', error);
-                this.#ngZone.run(() => this.loadError.emit(new RiveLoadError('Failed to load Rive animation', error)));
+                this.logger.error('Failed to initialize Rive instance:', error);
+                this.#ngZone.run(() => this.loadError.emit(new RiveLoadError({
+                    message: 'Failed to initialize Rive instance',
+                    code: RiveErrorCode.InvalidFormat,
+                    cause: error instanceof Error ? error : undefined,
+                })));
             }
         });
     }
     // Event handlers (run inside Angular zone for change detection)
     onLoad() {
+        // Validate loaded configuration
+        if (this.#rive) {
+            const validationErrors = validateConfiguration(this.#rive, {
+                artboard: this.artboard(),
+                animations: this.animations(),
+                stateMachines: this.stateMachines(),
+            }, this.logger);
+            // Emit validation errors via loadError output
+            if (validationErrors.length > 0) {
+                this.#ngZone.run(() => {
+                    validationErrors.forEach((err) => this.loadError.emit(err));
+                });
+            }
+            // Log available assets in debug mode
+            // Note: These properties exist at runtime but may not be in type definitions
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const riveWithMetadata = this.#rive;
+            this.logger.debug('Animation loaded successfully. Available assets:', {
+                artboards: riveWithMetadata.artboardNames,
+                animations: riveWithMetadata.animationNames,
+                stateMachines: riveWithMetadata.stateMachineNames,
+            });
+        }
         this.#ngZone.run(() => {
-            this.isLoaded.set(true);
+            this.#isLoaded.set(true);
             this.loaded.emit();
+            // Emit riveReady after animation is fully loaded
+            if (this.#rive) {
+                this.riveReady.emit(this.#rive);
+            }
         });
     }
     onLoadError(originalError) {
         this.#ngZone.run(() => {
-            const error = new RiveLoadError('Failed to load Rive animation', originalError instanceof Error ? originalError : undefined);
-            console.error('Rive load error:', error);
+            // Determine probable cause and code
+            let code = RiveErrorCode.NetworkError;
+            let message = 'Failed to load Rive animation';
+            if (originalError instanceof Error) {
+                if (originalError.message.includes('404')) {
+                    code = RiveErrorCode.FileNotFound;
+                    message = `File not found: ${this.src()}`;
+                }
+                else if (originalError.message.includes('format')) {
+                    code = RiveErrorCode.InvalidFormat;
+                    message = 'Invalid .riv file format';
+                }
+            }
+            const error = new RiveLoadError({
+                message,
+                code,
+                cause: originalError instanceof Error ? originalError : undefined,
+            });
+            this.logger.error('Rive load error:', error);
             this.loadError.emit(error);
         });
     }
     onPlay() {
         this.#ngZone.run(() => {
-            this.isPlaying.set(true);
-            this.isPaused.set(false);
+            this.#isPlaying.set(true);
+            this.#isPaused.set(false);
         });
     }
     onPause() {
         this.#ngZone.run(() => {
-            this.isPlaying.set(false);
-            this.isPaused.set(true);
+            this.#isPlaying.set(false);
+            this.#isPaused.set(true);
         });
     }
     onStop() {
         this.#ngZone.run(() => {
-            this.isPlaying.set(false);
-            this.isPaused.set(false);
+            this.#isPlaying.set(false);
+            this.#isPaused.set(false);
         });
     }
     onStateChange(event) {
@@ -493,6 +898,13 @@ class RiveCanvasComponent {
         if (!this.#rive)
             return;
         this.#ngZone.runOutsideAngular(() => {
+            // Validate input existence first
+            const error = validateInput(this.#rive, stateMachineName, inputName);
+            if (error) {
+                this.logger.warn(error.message);
+                this.#ngZone.run(() => this.loadError.emit(error));
+                return;
+            }
             const inputs = this.#rive.stateMachineInputs(stateMachineName);
             const input = inputs.find((i) => i.name === inputName);
             if (input && 'value' in input) {
@@ -507,6 +919,13 @@ class RiveCanvasComponent {
         if (!this.#rive)
             return;
         this.#ngZone.runOutsideAngular(() => {
+            // Validate trigger (input) existence first
+            const error = validateInput(this.#rive, stateMachineName, triggerName);
+            if (error) {
+                this.logger.warn(error.message);
+                this.#ngZone.run(() => this.loadError.emit(error));
+                return;
+            }
             const inputs = this.#rive.stateMachineInputs(stateMachineName);
             const input = inputs.find((i) => i.name === triggerName);
             if (input && 'fire' in input && typeof input.fire === 'function') {
@@ -523,18 +942,18 @@ class RiveCanvasComponent {
                 this.#rive.cleanup();
             }
             catch (error) {
-                console.warn('Error during Rive cleanup:', error);
+                this.logger.warn('Error during Rive cleanup:', error);
             }
             this.#rive = null;
         }
         // Reset signals
-        this.riveInstance.set(null);
-        this.isLoaded.set(false);
-        this.isPlaying.set(false);
-        this.isPaused.set(false);
+        this.#riveInstance.set(null);
+        this.#isLoaded.set(false);
+        this.#isPlaying.set(false);
+        this.#isPaused.set(false);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: RiveCanvasComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "21.1.4", type: RiveCanvasComponent, isStandalone: true, selector: "rive-canvas", inputs: { src: { classPropertyName: "src", publicName: "src", isSignal: true, isRequired: false, transformFunction: null }, buffer: { classPropertyName: "buffer", publicName: "buffer", isSignal: true, isRequired: false, transformFunction: null }, riveFile: { classPropertyName: "riveFile", publicName: "riveFile", isSignal: true, isRequired: false, transformFunction: null }, artboard: { classPropertyName: "artboard", publicName: "artboard", isSignal: true, isRequired: false, transformFunction: null }, animations: { classPropertyName: "animations", publicName: "animations", isSignal: true, isRequired: false, transformFunction: null }, stateMachines: { classPropertyName: "stateMachines", publicName: "stateMachines", isSignal: true, isRequired: false, transformFunction: null }, autoplay: { classPropertyName: "autoplay", publicName: "autoplay", isSignal: true, isRequired: false, transformFunction: null }, fit: { classPropertyName: "fit", publicName: "fit", isSignal: true, isRequired: false, transformFunction: null }, alignment: { classPropertyName: "alignment", publicName: "alignment", isSignal: true, isRequired: false, transformFunction: null }, useOffscreenRenderer: { classPropertyName: "useOffscreenRenderer", publicName: "useOffscreenRenderer", isSignal: true, isRequired: false, transformFunction: null }, shouldUseIntersectionObserver: { classPropertyName: "shouldUseIntersectionObserver", publicName: "shouldUseIntersectionObserver", isSignal: true, isRequired: false, transformFunction: null }, shouldDisableRiveListeners: { classPropertyName: "shouldDisableRiveListeners", publicName: "shouldDisableRiveListeners", isSignal: true, isRequired: false, transformFunction: null }, automaticallyHandleEvents: { classPropertyName: "automaticallyHandleEvents", publicName: "automaticallyHandleEvents", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { loaded: "loaded", loadError: "loadError", stateChange: "stateChange", riveEvent: "riveEvent", riveReady: "riveReady" }, viewQueries: [{ propertyName: "canvas", first: true, predicate: ["canvas"], descendants: true, isSignal: true }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "21.1.4", type: RiveCanvasComponent, isStandalone: true, selector: "rive-canvas", inputs: { src: { classPropertyName: "src", publicName: "src", isSignal: true, isRequired: false, transformFunction: null }, buffer: { classPropertyName: "buffer", publicName: "buffer", isSignal: true, isRequired: false, transformFunction: null }, riveFile: { classPropertyName: "riveFile", publicName: "riveFile", isSignal: true, isRequired: false, transformFunction: null }, artboard: { classPropertyName: "artboard", publicName: "artboard", isSignal: true, isRequired: false, transformFunction: null }, animations: { classPropertyName: "animations", publicName: "animations", isSignal: true, isRequired: false, transformFunction: null }, stateMachines: { classPropertyName: "stateMachines", publicName: "stateMachines", isSignal: true, isRequired: false, transformFunction: null }, autoplay: { classPropertyName: "autoplay", publicName: "autoplay", isSignal: true, isRequired: false, transformFunction: null }, fit: { classPropertyName: "fit", publicName: "fit", isSignal: true, isRequired: false, transformFunction: null }, alignment: { classPropertyName: "alignment", publicName: "alignment", isSignal: true, isRequired: false, transformFunction: null }, useOffscreenRenderer: { classPropertyName: "useOffscreenRenderer", publicName: "useOffscreenRenderer", isSignal: true, isRequired: false, transformFunction: null }, shouldUseIntersectionObserver: { classPropertyName: "shouldUseIntersectionObserver", publicName: "shouldUseIntersectionObserver", isSignal: true, isRequired: false, transformFunction: null }, shouldDisableRiveListeners: { classPropertyName: "shouldDisableRiveListeners", publicName: "shouldDisableRiveListeners", isSignal: true, isRequired: false, transformFunction: null }, automaticallyHandleEvents: { classPropertyName: "automaticallyHandleEvents", publicName: "automaticallyHandleEvents", isSignal: true, isRequired: false, transformFunction: null }, debugMode: { classPropertyName: "debugMode", publicName: "debugMode", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { loaded: "loaded", loadError: "loadError", stateChange: "stateChange", riveEvent: "riveEvent", riveReady: "riveReady" }, viewQueries: [{ propertyName: "canvas", first: true, predicate: ["canvas"], descendants: true, isSignal: true }], ngImport: i0, template: `
     <canvas #canvas [style.width.%]="100" [style.height.%]="100"></canvas>
   `, isInline: true, styles: [":host{display:block;width:100%;height:100%}canvas{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
@@ -543,7 +962,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.4", ngImpor
             args: [{ selector: 'rive-canvas', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, template: `
     <canvas #canvas [style.width.%]="100" [style.height.%]="100"></canvas>
   `, styles: [":host{display:block;width:100%;height:100%}canvas{display:block}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { canvas: [{ type: i0.ViewChild, args: ['canvas', { isSignal: true }] }], src: [{ type: i0.Input, args: [{ isSignal: true, alias: "src", required: false }] }], buffer: [{ type: i0.Input, args: [{ isSignal: true, alias: "buffer", required: false }] }], riveFile: [{ type: i0.Input, args: [{ isSignal: true, alias: "riveFile", required: false }] }], artboard: [{ type: i0.Input, args: [{ isSignal: true, alias: "artboard", required: false }] }], animations: [{ type: i0.Input, args: [{ isSignal: true, alias: "animations", required: false }] }], stateMachines: [{ type: i0.Input, args: [{ isSignal: true, alias: "stateMachines", required: false }] }], autoplay: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoplay", required: false }] }], fit: [{ type: i0.Input, args: [{ isSignal: true, alias: "fit", required: false }] }], alignment: [{ type: i0.Input, args: [{ isSignal: true, alias: "alignment", required: false }] }], useOffscreenRenderer: [{ type: i0.Input, args: [{ isSignal: true, alias: "useOffscreenRenderer", required: false }] }], shouldUseIntersectionObserver: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldUseIntersectionObserver", required: false }] }], shouldDisableRiveListeners: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldDisableRiveListeners", required: false }] }], automaticallyHandleEvents: [{ type: i0.Input, args: [{ isSignal: true, alias: "automaticallyHandleEvents", required: false }] }], loaded: [{ type: i0.Output, args: ["loaded"] }], loadError: [{ type: i0.Output, args: ["loadError"] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }], riveEvent: [{ type: i0.Output, args: ["riveEvent"] }], riveReady: [{ type: i0.Output, args: ["riveReady"] }] } });
+        }], ctorParameters: () => [], propDecorators: { canvas: [{ type: i0.ViewChild, args: ['canvas', { isSignal: true }] }], src: [{ type: i0.Input, args: [{ isSignal: true, alias: "src", required: false }] }], buffer: [{ type: i0.Input, args: [{ isSignal: true, alias: "buffer", required: false }] }], riveFile: [{ type: i0.Input, args: [{ isSignal: true, alias: "riveFile", required: false }] }], artboard: [{ type: i0.Input, args: [{ isSignal: true, alias: "artboard", required: false }] }], animations: [{ type: i0.Input, args: [{ isSignal: true, alias: "animations", required: false }] }], stateMachines: [{ type: i0.Input, args: [{ isSignal: true, alias: "stateMachines", required: false }] }], autoplay: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoplay", required: false }] }], fit: [{ type: i0.Input, args: [{ isSignal: true, alias: "fit", required: false }] }], alignment: [{ type: i0.Input, args: [{ isSignal: true, alias: "alignment", required: false }] }], useOffscreenRenderer: [{ type: i0.Input, args: [{ isSignal: true, alias: "useOffscreenRenderer", required: false }] }], shouldUseIntersectionObserver: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldUseIntersectionObserver", required: false }] }], shouldDisableRiveListeners: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldDisableRiveListeners", required: false }] }], automaticallyHandleEvents: [{ type: i0.Input, args: [{ isSignal: true, alias: "automaticallyHandleEvents", required: false }] }], debugMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "debugMode", required: false }] }], loaded: [{ type: i0.Output, args: ["loaded"] }], loadError: [{ type: i0.Output, args: ["loadError"] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }], riveEvent: [{ type: i0.Output, args: ["riveEvent"] }], riveReady: [{ type: i0.Output, args: ["riveReady"] }] } });
 
 /**
  * Service for preloading and caching Rive files.
@@ -576,7 +995,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.4", ngImpor
 class RiveFileService {
     cache = new Map();
     pendingLoads = new Map();
+    bufferIdMap = new WeakMap();
     bufferIdCounter = 0;
+    // Optional debug configuration
+    globalDebugConfig = inject(RIVE_DEBUG_CONFIG, {
+        optional: true,
+    });
     /**
      * Load a RiveFile from URL or ArrayBuffer.
      * Returns a signal with the file state and loading status.
@@ -588,15 +1012,20 @@ class RiveFileService {
      */
     loadFile(params) {
         const cacheKey = this.getCacheKey(params);
+        // Initialize logger for this request
+        const logger = new RiveLogger(this.globalDebugConfig, params.debug);
+        logger.debug(`RiveFileService: Request to load file`, { cacheKey });
         // Return cached entry if exists
         const cached = this.cache.get(cacheKey);
         if (cached) {
             cached.refCount++;
+            logger.debug(`RiveFileService: Cache hit for ${cacheKey}`);
             return cached.state;
         }
         // Return pending load if already in progress
         const pending = this.pendingLoads.get(cacheKey);
         if (pending) {
+            logger.debug(`RiveFileService: Reuse pending load for ${cacheKey}`);
             return pending.stateSignal.asReadonly();
         }
         // Create new loading state
@@ -605,7 +1034,7 @@ class RiveFileService {
             status: 'loading',
         }, ...(ngDevMode ? [{ debugName: "stateSignal" }] : []));
         // Start loading and track as pending
-        const promise = this.loadRiveFile(params, stateSignal, cacheKey);
+        const promise = this.loadRiveFile(params, stateSignal, cacheKey, logger);
         this.pendingLoads.set(cacheKey, { stateSignal, promise });
         return stateSignal.asReadonly();
     }
@@ -631,9 +1060,18 @@ class RiveFileService {
         }
     }
     /**
-     * Clear all cached files
+     * Clear all cached files and abort pending loads
      */
     clearCache() {
+        // Clear pending loads first to prevent them from populating the cache
+        this.pendingLoads.forEach((pending) => {
+            pending.stateSignal.set({
+                riveFile: null,
+                status: 'failed',
+            });
+        });
+        this.pendingLoads.clear();
+        // Clean up cached files
         this.cache.forEach((entry) => {
             try {
                 entry.file.cleanup();
@@ -652,67 +1090,73 @@ class RiveFileService {
             return `src:${params.src}`;
         }
         if (params.buffer) {
-            // For buffers, generate unique ID to avoid collisions
-            // Store the ID on the buffer object itself
-            const bufferWithId = params.buffer;
-            if (!bufferWithId.__riveBufferId) {
-                bufferWithId.__riveBufferId = ++this.bufferIdCounter;
+            // For buffers, use WeakMap to track unique IDs without mutating the buffer
+            let bufferId = this.bufferIdMap.get(params.buffer);
+            if (bufferId === undefined) {
+                bufferId = ++this.bufferIdCounter;
+                this.bufferIdMap.set(params.buffer, bufferId);
             }
-            return `buffer:${bufferWithId.__riveBufferId}`;
+            return `buffer:${bufferId}`;
         }
         return 'unknown';
     }
     /**
-     * Load RiveFile and update state signal
+     * Load RiveFile and update state signal.
+     * Addresses race condition by setting up listeners BEFORE init.
      */
-    loadRiveFile(params, stateSignal, cacheKey) {
-        return new Promise((resolve) => {
-            try {
-                const file = new RiveFile(params);
-                file.init();
-                file.on(EventType.Load, () => {
-                    // Request an instance to increment reference count
-                    // This prevents the file from being destroyed while in use
-                    file.getInstance();
-                    stateSignal.set({
-                        riveFile: file,
-                        status: 'success',
-                    });
-                    // Cache the successfully loaded file
-                    this.cache.set(cacheKey, {
-                        file,
-                        state: stateSignal.asReadonly(),
-                        refCount: 1,
-                    });
-                    // Remove from pending loads
-                    this.pendingLoads.delete(cacheKey);
-                    resolve();
+    async loadRiveFile(params, stateSignal, cacheKey, logger) {
+        // Guard to ensure pending load is cleaned up exactly once
+        let pendingCleanupDone = false;
+        const finalizePendingLoadOnce = () => {
+            if (!pendingCleanupDone) {
+                this.pendingLoads.delete(cacheKey);
+                pendingCleanupDone = true;
+            }
+        };
+        try {
+            // Extract debug parameter - it's not part of RiveFile SDK API
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { debug, ...sdkParams } = params;
+            const file = new RiveFile(sdkParams);
+            // Listeners must be attached BEFORE calling init() to avoid race conditions
+            // where init() completes or fails synchronously/immediately.
+            file.on(EventType.Load, () => {
+                logger.debug(`RiveFileService: File loaded successfully`, { cacheKey });
+                // Request an instance to increment reference count
+                // This prevents the file from being destroyed while in use
+                file.getInstance();
+                stateSignal.set({
+                    riveFile: file,
+                    status: 'success',
                 });
-                file.on(EventType.LoadError, () => {
-                    stateSignal.set({
-                        riveFile: null,
-                        status: 'failed',
-                    });
-                    // Remove from pending loads
-                    this.pendingLoads.delete(cacheKey);
-                    // Resolve (not reject) — error state is communicated via the signal.
-                    // Rejecting would cause an unhandled promise rejection since no
-                    // consumer awaits or catches this promise.
-                    resolve();
+                // Cache the successfully loaded file
+                this.cache.set(cacheKey, {
+                    file,
+                    state: stateSignal.asReadonly(),
+                    refCount: 1,
                 });
-            }
-            catch (error) {
-                console.error('Failed to load RiveFile:', error);
+                finalizePendingLoadOnce();
+            });
+            file.on(EventType.LoadError, () => {
+                logger.warn(`RiveFileService: Failed to load file`, { cacheKey });
                 stateSignal.set({
                     riveFile: null,
                     status: 'failed',
                 });
-                // Remove from pending loads
-                this.pendingLoads.delete(cacheKey);
-                // Resolve (not reject) — error state is communicated via the signal.
-                resolve();
-            }
-        });
+                finalizePendingLoadOnce();
+            });
+            logger.debug(`RiveFileService: Initializing file`, { cacheKey });
+            // Await init() to catch initialization errors (e.g. WASM issues)
+            await file.init();
+        }
+        catch (error) {
+            logger.error('RiveFileService: Unexpected error loading file', error);
+            stateSignal.set({
+                riveFile: null,
+                status: 'failed',
+            });
+            finalizePendingLoadOnce();
+        }
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: RiveFileService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: RiveFileService, providedIn: 'root' });
@@ -733,5 +1177,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.4", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { RiveCanvasComponent, RiveFileService, RiveLoadError };
+export { RiveCanvasComponent, RiveErrorCode, RiveFileService, RiveLoadError, RiveValidationError, provideRiveDebug };
 //# sourceMappingURL=grandgular-rive-angular.mjs.map