dopaminejs 2.2.0 → 2.3.1

package/dist/style.css

@@ -1 +1 @@
-#game-ui-overlay,.game-ui-overlay{position:fixed;top:0;left:0;width:100%;pointer-events:none;z-index:1000;font-family:Inter,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif}.game-ui-top-bar{display:flex;align-items:center;gap:12px;padding:12px 16px;background:#0000004d;-webkit-backdrop-filter:blur(10px);backdrop-filter:blur(10px)}.level-badge{display:flex;flex-direction:column;align-items:center;background:linear-gradient(135deg,#667eea,#764ba2);padding:8px 12px;border-radius:12px;box-shadow:0 4px 12px #667eea66;min-width:60px}.level-label{font-size:10px;font-weight:600;color:#fffc;letter-spacing:.5px}.level-number{font-size:24px;font-weight:800;color:#fff;line-height:1}.xp-container{flex:1;display:flex;flex-direction:column;gap:4px}.xp-bar-bg{height:12px;background:#fff3;border-radius:6px;overflow:hidden;box-shadow:inset 0 2px 4px #0003}.xp-bar-fill{height:100%;background:linear-gradient(90deg,#4facfe,#00f2fe);border-radius:6px;transition:width .5s ease-out;box-shadow:0 0 10px #4facfe99}.xp-text{font-size:11px;color:#fff;font-weight:600;text-align:center;text-shadow:0 1px 2px rgba(0,0,0,.5)}.streak-badge{display:flex;align-items:center;gap:6px;background:linear-gradient(135deg,#f80,#f40);padding:8px 12px;border-radius:12px;box-shadow:0 4px 12px #f806}.streak-icon{font-size:20px;animation:flicker 2s infinite}.streak-number{font-size:18px;font-weight:800;color:#fff}.achievement-popup{position:fixed;top:80px;right:20px;background:linear-gradient(135deg,#667eea,#764ba2);border-radius:16px;padding:16px;box-shadow:0 8px 32px #0006;animation:slideIn .5s cubic-bezier(.68,-.55,.265,1.55);z-index:10000;max-width:320px;overflow:hidden}.achievement-shine{position:absolute;top:0;left:-100%;width:100%;height:100%;background:linear-gradient(90deg,transparent,rgba(255,255,255,.3),transparent);animation:shine 2s infinite}.achievement-content{position:relative;display:flex;gap:12px;align-items:center}.achievement-icon{font-size:48px;animation:bounce .6s ease-out}.achievement-info{flex:1}.achievement-title{font-size:12px;font-weight:600;color:#ffffffe6;text-transform:uppercase;letter-spacing:.5px}.achievement-name{font-size:18px;font-weight:800;color:#fff;margin:2px 0}.achievement-desc{font-size:13px;color:#fffc;margin-bottom:4px}.achievement-xp{display:inline-block;background:#fff3;padding:4px 8px;border-radius:8px;font-size:12px;font-weight:700;color:gold}.level-up-overlay{position:fixed;top:0;left:0;width:100%;height:100%;background:#000000d9;display:flex;align-items:center;justify-content:center;z-index:10001;animation:fadeIn .3s ease-out}.level-up-content{text-align:center;animation:scaleIn .5s cubic-bezier(.68,-.55,.265,1.55)}.level-up-title{font-size:32px;font-weight:800;background:linear-gradient(135deg,gold,#ffed4e);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;text-transform:uppercase;letter-spacing:4px;margin-bottom:16px}.level-up-number{font-size:120px;font-weight:900;color:#fff;text-shadow:0 0 20px rgba(255,215,0,.8),0 0 40px rgba(255,215,0,.6),0 0 60px rgba(255,215,0,.4);animation:glow 1s ease-in-out infinite alternate}.level-up-subtitle{font-size:24px;color:#fffc;font-weight:600;margin-top:16px}.floating-text{position:fixed;font-weight:800;text-shadow:2px 2px 0 #000,-1px -1px 0 #000,1px -1px 0 #000,-1px 1px 0 #000;pointer-events:none;z-index:9998;animation:floatUp 2s ease-out forwards}@keyframes slideIn{0%{transform:translate(400px);opacity:0}to{transform:translate(0);opacity:1}}@keyframes slideOut{0%{transform:translate(0);opacity:1}to{transform:translate(400px);opacity:0}}@keyframes fadeIn{0%{opacity:0}to{opacity:1}}@keyframes scaleIn{0%{transform:scale(.5);opacity:0}to{transform:scale(1);opacity:1}}@keyframes bounce{0%,to{transform:translateY(0)}50%{transform:translateY(-10px)}}@keyframes glow{0%{text-shadow:0 0 20px rgba(255,215,0,.8),0 0 40px rgba(255,215,0,.6),0 0 60px rgba(255,215,0,.4)}to{text-shadow:0 0 30px rgba(255,215,0,1),0 0 60px rgba(255,215,0,.8),0 0 90px rgba(255,215,0,.6)}}@keyframes shine{0%{left:-100%}30%{left:100%}to{left:100%}}@keyframes flicker{0%,to{opacity:1}50%{opacity:.8}}@keyframes floatUp{0%{transform:translateY(0);opacity:1}to{transform:translateY(-100px);opacity:0}}@keyframes xp-pulse{0%{transform:scaleY(1)}50%{transform:scaleY(1.2)}to{transform:scaleY(1)}}@keyframes level-pulse{0%{transform:scale(1)}50%{transform:scale(1.1)}to{transform:scale(1)}}@media (max-width: 480px){.game-ui-top-bar{gap:8px;padding:10px 12px}.level-badge{padding:6px 10px;min-width:50px}.level-number{font-size:20px}.xp-bar-bg{height:10px}.xp-text{font-size:10px}.achievement-popup{right:12px;max-width:calc(100% - 24px)}.level-up-number{font-size:80px}}
+#game-ui-overlay,.game-ui-overlay{position:fixed;top:0;left:0;width:100%;pointer-events:none;z-index:1000;font-family:Inter,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif}.game-ui-top-bar{display:flex;align-items:center;gap:12px;padding:12px 16px;background:#0000004d;-webkit-backdrop-filter:blur(10px);backdrop-filter:blur(10px)}.level-badge{display:flex;flex-direction:column;align-items:center;background:linear-gradient(135deg,#667eea,#764ba2);padding:8px 12px;border-radius:12px;box-shadow:0 4px 12px #667eea66;min-width:60px}.level-label{font-size:10px;font-weight:600;color:#fffc;letter-spacing:.5px}.level-number{font-size:24px;font-weight:800;color:#fff;line-height:1}.xp-container{flex:1;display:flex;flex-direction:column;gap:4px}.xp-bar-bg{height:12px;background:#fff3;border-radius:6px;overflow:hidden;box-shadow:inset 0 2px 4px #0003}.xp-bar-fill{height:100%;background:linear-gradient(90deg,#4facfe,#00f2fe);border-radius:6px;transition:width .5s ease-out;box-shadow:0 0 10px #4facfe99}.xp-text{font-size:11px;color:#fff;font-weight:600;text-align:center;text-shadow:0 1px 2px rgba(0,0,0,.5)}.streak-badge{display:flex;align-items:center;gap:6px;background:linear-gradient(135deg,#f80,#f40);padding:8px 12px;border-radius:12px;box-shadow:0 4px 12px #f806}.streak-icon{font-size:20px;animation:flicker 2s infinite}.streak-number{font-size:18px;font-weight:800;color:#fff}.achievement-popup{position:fixed;top:80px;right:20px;background:linear-gradient(135deg,#667eea,#764ba2);border-radius:16px;padding:16px;box-shadow:0 8px 32px #0006;animation:slideIn .5s cubic-bezier(.68,-.55,.265,1.55);z-index:10000;max-width:320px;overflow:hidden}.achievement-shine{position:absolute;top:0;left:-100%;width:100%;height:100%;background:linear-gradient(90deg,transparent,rgba(255,255,255,.3),transparent);animation:shine 2s infinite}.achievement-content{position:relative;display:flex;gap:12px;align-items:center}.achievement-icon{font-size:48px;animation:bounce .6s ease-out}.achievement-info{flex:1}.achievement-title{font-size:12px;font-weight:600;color:#ffffffe6;text-transform:uppercase;letter-spacing:.5px}.achievement-name{font-size:18px;font-weight:800;color:#fff;margin:2px 0}.achievement-desc{font-size:13px;color:#fffc;margin-bottom:4px}.achievement-xp{display:inline-block;background:#fff3;padding:4px 8px;border-radius:8px;font-size:12px;font-weight:700;color:gold}.level-up-overlay{position:fixed;top:0;left:0;width:100%;height:100%;background:#000000d9;display:flex;align-items:center;justify-content:center;z-index:10001;animation:fadeIn .3s ease-out}.level-up-content{text-align:center;animation:scaleIn .5s cubic-bezier(.68,-.55,.265,1.55)}.level-up-title{font-size:32px;font-weight:800;background:linear-gradient(135deg,gold,#ffed4e);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;text-transform:uppercase;letter-spacing:4px;margin-bottom:16px}.level-up-number{font-size:120px;font-weight:900;color:#fff;text-shadow:0 0 20px rgba(255,215,0,.8),0 0 40px rgba(255,215,0,.6),0 0 60px rgba(255,215,0,.4);animation:glow 1s ease-in-out infinite alternate}.level-up-subtitle{font-size:24px;color:#fffc;font-weight:600;margin-top:16px}.floating-text{position:fixed;font-weight:800;text-shadow:2px 2px 0 #000,-1px -1px 0 #000,1px -1px 0 #000,-1px 1px 0 #000;pointer-events:none;z-index:9998;animation:floatUp 2s ease-out forwards}@keyframes slideIn{0%{transform:translate(400px);opacity:0}to{transform:translate(0);opacity:1}}@keyframes slideOut{0%{transform:translate(0);opacity:1}to{transform:translate(400px);opacity:0}}@keyframes fadeIn{0%{opacity:0}to{opacity:1}}@keyframes scaleIn{0%{transform:scale(.5);opacity:0}to{transform:scale(1);opacity:1}}@keyframes bounce{0%,to{transform:translateY(0)}50%{transform:translateY(-10px)}}@keyframes glow{0%{text-shadow:0 0 20px rgba(255,215,0,.8),0 0 40px rgba(255,215,0,.6),0 0 60px rgba(255,215,0,.4)}to{text-shadow:0 0 30px rgba(255,215,0,1),0 0 60px rgba(255,215,0,.8),0 0 90px rgba(255,215,0,.6)}}@keyframes shine{0%{left:-100%}30%{left:100%}to{left:100%}}@keyframes flicker{0%,to{opacity:1}50%{opacity:.8}}@keyframes floatUp{0%{transform:translateY(0);opacity:1}to{transform:translateY(-100px);opacity:0}}@keyframes xp-pulse{0%{transform:scaleY(1)}50%{transform:scaleY(1.2)}to{transform:scaleY(1)}}@keyframes level-pulse{0%{transform:scale(1)}50%{transform:scale(1.1)}to{transform:scale(1)}}@media(max-width:480px){.game-ui-top-bar{gap:8px;padding:10px 12px}.level-badge{padding:6px 10px;min-width:50px}.level-number{font-size:20px}.xp-bar-bg{height:10px}.xp-text{font-size:10px}.achievement-popup{right:12px;max-width:calc(100% - 24px)}.level-up-number{font-size:80px}}@media(prefers-reduced-motion:reduce){.game-ui-overlay *,.achievement-popup,.achievement-popup *,.level-up-overlay,.level-up-overlay *{animation:none!important;transition:none!important}.floating-text{animation:none!important}}

package/package.json

@@ -1,18 +1,24 @@
 {
     "name": "dopaminejs",
-    "version": "2.2.0",
-    "description": "Lightweight Game Feel Engine - Add juice, rewards, and feedback to HTML5 games",
+    "version": "2.3.1",
+    "description": "Progression mechanics for web apps: XP, levels, achievements and timezone-correct daily streaks, with the particles and sound to make them land. Zero dependencies.",
     "type": "module",
-    "main": "./dist/dopamine.umd.cjs",
+    "main": "./dist/dopamine.cjs",
     "module": "./dist/dopamine.js",
     "exports": {
         ".": {
             "types": "./types/index.d.ts",
             "import": "./dist/dopamine.js",
-            "require": "./dist/dopamine.umd.cjs"
+            "require": "./dist/dopamine.cjs"
+        },
+        "./engine": {
+            "types": "./types/index.d.ts",
+            "import": "./dist/engine.js",
+            "require": "./dist/engine.cjs"
         },
         "./style.css": "./dist/style.css"
     },
+    "sideEffects": false,
     "files": [
         "dist",
         "src",
@@ -21,20 +27,25 @@
     "scripts": {
         "dev": "vite",
         "build": "vite build",
-        "test": "vitest",
+        "test": "vitest run",
+        "test:watch": "vitest",
         "preview": "vite preview"
     },
     "keywords": [
-        "game",
-        "gamedev",
+        "gamification",
+        "progression",
+        "streaks",
+        "daily-streak",
+        "xp",
+        "levels",
+        "achievements",
+        "engagement",
+        "rewards",
+        "user-retention",
         "game-feel",
         "juice",
-        "feedback",
-        "rewards",
         "particles",
-        "sound",
-        "xp",
-        "achievements"
+        "confetti"
     ],
     "author": "BaryoDev",
     "license": "MPL-2.0",
@@ -47,5 +58,8 @@
         "url": "https://github.com/BaryoDev/dopaminejs/issues"
     },
     "homepage": "https://github.com/BaryoDev/dopaminejs#readme",
-    "types": "./types/index.d.ts"
+    "types": "./types/index.d.ts",
+    "engines": {
+        "node": ">=20.19"
+    }
 }

package/src/core/Collider.js

@@ -14,19 +14,55 @@ export class Collider extends Component {
         this.tag = null; // For collision filtering
     }
 
+    get kernel() {
+        return this._kernel ?? null;
+    }
+
+    /**
+     * The kernel can arrive after onAttach(), when the collider was added to
+     * an object before that object joined a scene. Registering only in
+     * onAttach() left such colliders out of physics for good.
+     */
+    set kernel(value) {
+        if (value === this._kernel) return;
+
+        this._unregister();
+        this._kernel = value;
+        this._register();
+    }
+
     onAttach() {
         super.onAttach();
-        // Register with physics system through kernel
-        if (this.physics) {
-            this.physics.add(this);
-        }
+        this._attached = true;
+        this._register();
     }
 
     onDetach() {
         super.onDetach();
-        // Unregister from physics
-        if (this.physics) {
-            this.physics.remove(this);
+        this._attached = false;
+        this._unregister();
+    }
+
+    /**
+     * @private
+     */
+    _register() {
+        if (this._physics || !this._attached) return;
+
+        const physics = this.physics;
+        if (physics) {
+            physics.add(this);
+            this._physics = physics;
+        }
+    }
+
+    /**
+     * @private
+     */
+    _unregister() {
+        if (this._physics) {
+            this._physics.remove(this);
+            this._physics = null;
         }
     }
 

package/src/core/PluginRegistry.js

@@ -16,6 +16,62 @@ export class PluginRegistry {
 
         // Track plugin load order for proper cleanup
         this._loadOrder = [];
+
+        // Async inits in flight. Each notes the systems other plugins added
+        // meanwhile, so a failed one removes only its own.
+        this._inFlight = new Set();
+    }
+
+    /**
+     * @private
+     */
+    _systemsSince(before) {
+        return this.kernel.systems.getSystemNames().filter((name) => !before.has(name));
+    }
+
+    /**
+     * Mark systems as belonging to a plugin that loaded.
+     * @private
+     */
+    _claim(names) {
+        for (const pending of this._inFlight) {
+            for (const name of names) {
+                pending.foreign.add(name);
+            }
+        }
+    }
+
+    /**
+     * Remove the systems a failed plugin registered. They would keep updating
+     * with nothing left to remove them.
+     * @private
+     */
+    _rollback(names) {
+        for (const name of names) {
+            try {
+                this.kernel.systems.unregister(name);
+            } catch (error) {
+                // The caller is about to rethrow the init error. This one
+                // must not replace it or stop the loop.
+                console.error(`[PluginRegistry] Error removing system "${name}":`, error);
+            }
+        }
+    }
+
+    /**
+     * Forget a plugin whose init failed.
+     *
+     * Removed by name: with two async inits in flight, the failed plugin is
+     * not necessarily the last entry.
+     * @private
+     */
+    _forget(name) {
+        this._plugins.delete(name);
+
+        const index = this._loadOrder.indexOf(name);
+        if (index > -1) {
+            this._loadOrder.splice(index, 1);
+        }
     }
 
     /**
@@ -51,6 +107,8 @@ export class PluginRegistry {
         this._loadOrder.push(plugin.name);
 
         // Initialize plugin
+        const systemsBefore = new Set(this.kernel.systems.getSystemNames());
+
         try {
             plugin.init(this.kernel);
 
@@ -60,11 +118,12 @@ export class PluginRegistry {
                 version: plugin.version
             });
 
-            // Plugin loaded successfully
+            this._claim(this._systemsSince(systemsBefore));
         } catch (error) {
             console.error(`[PluginRegistry] Failed to initialize plugin "${plugin.name}":`, error);
-            this._plugins.delete(plugin.name);
-            this._loadOrder.pop();
+            this._forget(plugin.name);
+            this._rollback(this._systemsSince(systemsBefore));
+
             throw error;
         }
 
@@ -96,21 +155,39 @@ export class PluginRegistry {
         this._plugins.set(plugin.name, plugin);
         this._loadOrder.push(plugin.name);
 
+        const pending = {
+            before: new Set(this.kernel.systems.getSystemNames()),
+            foreign: new Set()
+        };
+        const own = () => this._systemsSince(pending.before).filter((name) => !pending.foreign.has(name));
+        this._inFlight.add(pending);
+
         // Initialize plugin (await if it returns a promise)
         try {
             await plugin.init(this.kernel);
 
+            this._inFlight.delete(pending);
+            this._claim(own());
+
             // Emit event
             this.kernel.events.emit('plugin_loaded', {
                 name: plugin.name,
                 version: plugin.version
             });
-
-            // Plugin loaded successfully
         } catch (error) {
             console.error(`[PluginRegistry] Failed to initialize plugin "${plugin.name}":`, error);
-            this._plugins.delete(plugin.name);
-            this._loadOrder.pop();
+            this._inFlight.delete(pending);
+            this._forget(plugin.name);
+
+            const leftover = own();
+            if (this._inFlight.size === 0) {
+                this._rollback(leftover);
+            } else if (leftover.length > 0) {
+                // Another init is still running and may have registered some
+                // of these. Removing them could break a plugin that loads.
+                console.warn(`[PluginRegistry] Left systems in place after "${plugin.name}" failed: ${leftover.join(', ')}`);
+            }
+
             throw error;
         }
 

package/src/core/Scene.js

@@ -4,7 +4,25 @@
 export class Scene {
     constructor() {
         this.gameObjects = [];
-        this.kernel = null; // Injected by Game
+        this._kernel = null; // Injected by Game
+    }
+
+    get kernel() {
+        return this._kernel;
+    }
+
+    /**
+     * Objects added before the scene had a kernel receive it here. Scenes are
+     * often built in a constructor, before Game.setScene() injects the kernel.
+     * The Director sets it to null on exit, which takes colliders out of
+     * physics until the scene runs again.
+     */
+    set kernel(value) {
+        this._kernel = value;
+
+        for (const gameObject of this.gameObjects) {
+            gameObject.kernel = value;
+        }
     }
 
     /**
@@ -25,6 +43,13 @@ export class Scene {
         if (this.kernel) {
             gameObject.kernel = this.kernel; // Inject kernel
         }
+
+        // Coming back after a remove(): components were detached then.
+        if (gameObject._detached) {
+            gameObject._detached = false;
+            this._eachComponent(gameObject, (component) => component.onAttach());
+        }
+
         this.gameObjects.push(gameObject);
         return gameObject;
     }
@@ -37,6 +62,24 @@ export class Scene {
         const index = this.gameObjects.indexOf(gameObject);
         if (index > -1) {
             this.gameObjects.splice(index, 1);
+
+            // Lets components release what they hold. A Collider left in
+            // physics keeps colliding for an object that is gone.
+            gameObject._detached = true;
+            this._eachComponent(gameObject, (component) => component.onDetach());
+        }
+    }
+
+    /**
+     * Visit the components of an object and of all its children.
+     * @private
+     */
+    _eachComponent(gameObject, fn) {
+        for (const component of [...gameObject.components]) {
+            fn(component);
+        }
+        for (const child of gameObject.children) {
+            this._eachComponent(child, fn);
         }
     }
 
@@ -45,8 +88,10 @@ export class Scene {
      * @param {number} dt 
      */
     update(dt) {
-        for (const obj of this.gameObjects) {
-            obj.update(dt);
+        // Snapshot: an object may add or remove objects mid-frame, and
+        // splicing the live array would skip the one after it.
+        for (const obj of [...this.gameObjects]) {
+            if (!obj._detached) obj.update(dt);
         }
     }
 
@@ -55,8 +100,8 @@ export class Scene {
      * @param {CanvasRenderingContext2D} ctx 
      */
     render(ctx) {
-        for (const obj of this.gameObjects) {
-            obj.render(ctx);
+        for (const obj of [...this.gameObjects]) {
+            if (!obj._detached) obj.render(ctx);
         }
     }
 }

package/src/core/SystemRegistry.js

@@ -17,6 +17,25 @@ export class SystemRegistry {
 
         // Flag to track if order needs recomputation
         this._needsRecompute = false;
+
+        // Systems that have thrown from an update, so each is logged once
+        // instead of sixty times a second.
+        this._failed = new WeakSet();
+    }
+
+    /**
+     * Run one system's update without letting a throw stop the others.
+     * @private
+     */
+    _run(system, method, dt) {
+        try {
+            system[method](dt);
+        } catch (error) {
+            if (!this._failed.has(system)) {
+                this._failed.add(system);
+                console.error(`[SystemRegistry] System ${method}() threw:`, error);
+            }
+        }
     }
 
     /**
@@ -92,16 +111,18 @@ export class SystemRegistry {
             return false;
         }
 
-        // Call destroy if available
-        if (entry.system.destroy) {
-            entry.system.destroy();
-        }
-
-        this._systems.delete(name);
-        this._needsRecompute = true;
+        // A destroy that throws must not leave the system registered.
+        try {
+            if (entry.system.destroy) {
+                entry.system.destroy();
+            }
+        } finally {
+            this._systems.delete(name);
+            this._needsRecompute = true;
 
-        // Emit event
-        this.kernel.events.emit('system_unregistered', { name });
+            // Emit event
+            this.kernel.events.emit('system_unregistered', { name });
+        }
 
         return true;
     }
@@ -119,7 +140,7 @@ export class SystemRegistry {
         for (let i = 0; i < this._updateOrder.length; i++) {
             const system = this._updateOrder[i];
             if (system.update) {
-                system.update(dt);
+                this._run(system, 'update', dt);
             }
         }
     }
@@ -136,7 +157,7 @@ export class SystemRegistry {
         for (let i = 0; i < this._fixedUpdateOrder.length; i++) {
             const system = this._fixedUpdateOrder[i];
             if (system.fixedUpdate) {
-                system.fixedUpdate(dt);
+                this._run(system, 'fixedUpdate', dt);
             }
         }
     }

package/src/dopamine/audio/SoundManager.js

@@ -5,6 +5,8 @@
 
 import { resolveStorage } from '../utils/storage.js';
 
+const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+
 export class SoundManager {
     constructor(config = {}) {
         this.audioContext = null;
@@ -18,12 +20,27 @@ export class SoundManager {
 
         // Master gain, created with the AudioContext on first use.
         this.masterGain = null;
-        this._volume = config.volume ?? 1;
+        this._volume = 1;
+        this.setVolume(config.volume ?? 1);
 
-        // Preload custom sounds if provided
-        if (Object.keys(this.customSounds).length > 0) {
-            this.preloadSounds(this.customSounds);
-        }
+        // In-flight loads by key, so a play() during preload does not fetch
+        // the same file twice.
+        this._loading = new Map();
+
+        // Queued follow-up tones, so destroy() can cancel them.
+        this._timers = new Set();
+    }
+
+    /**
+     * setTimeout that destroy() can cancel.
+     * @private
+     */
+    _later(fn, delay) {
+        const id = setTimeout(() => {
+            this._timers.delete(id);
+            fn();
+        }, delay);
+        this._timers.add(id);
     }
 
     /**
@@ -43,6 +60,10 @@ export class SoundManager {
             this.masterGain = this.audioContext.createGain();
             this.masterGain.gain.value = this._volume;
             this.masterGain.connect(this.audioContext.destination);
+
+            // Decoding needs a context, so sounds registered before this
+            // point could not be loaded until now.
+            this.preloadSounds(this.customSounds);
         }
 
         if (this.audioContext.state === 'suspended') {
@@ -57,6 +78,9 @@ export class SoundManager {
      * @param {number} value - 0..1
      */
     setVolume(value) {
+        // NaN would pass through Math.min/max and silence the gain node.
+        if (!Number.isFinite(value)) return this._volume;
+
         this._volume = Math.max(0, Math.min(1, value));
         if (this.masterGain) {
             this.masterGain.gain.value = this._volume;
@@ -116,19 +140,39 @@ export class SoundManager {
      * Load and decode a sound file
      */
     async loadSound(key, url) {
+        // We need an audio context to decode. Without one this waits for
+        // initAudio(), which loads everything registered so far.
+        if (!this.audioContext) return;
+
+        if (this._loading.has(key)) {
+            return this._loading.get(key);
+        }
+
+        const loading = this._load(key, url).finally(() => this._loading.delete(key));
+        this._loading.set(key, loading);
+        return loading;
+    }
+
+    /**
+     * @private
+     */
+    async _load(key, url) {
         try {
-            // We need audio context to decode
-            if (!this.audioContext) {
-                // If no context yet, we can't decode. 
-                // In a real app, we might fetch buffer first, decode later.
-                // For simplicity, we'll wait for initAudio() or lazy load.
-                return;
+            const context = this.audioContext;
+            const response = await fetch(url);
+
+            // fetch resolves on a 404. Its body is an error page, not audio.
+            if (response.ok === false) {
+                throw new Error(`HTTP ${response.status}`);
             }
 
-            const response = await fetch(url);
             const arrayBuffer = await response.arrayBuffer();
-            const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
-            this.assets.set(key, audioBuffer);
+            const audioBuffer = await context.decodeAudioData(arrayBuffer);
+
+            // destroy() may have run while this was in flight.
+            if (this.audioContext === context) {
+                this.assets.set(key, audioBuffer);
+            }
         } catch (error) {
             console.warn(`[DopamineJS] Failed to load sound '${key}':`, error);
         }
@@ -149,8 +193,14 @@ export class SoundManager {
         }
 
         // 2. Try to load if registered but not loaded
-        if (this.customSounds[key] && !this.assets.has(key)) {
+        if (hasOwn(this.customSounds, key) && !this.assets.has(key)) {
+            const context = this.audioContext;
             await this.loadSound(key, this.customSounds[key]);
+
+            // destroy() ran while the file loaded. The synth fallback would
+            // open a new context.
+            if (this.audioContext !== context) return;
+
             if (this.assets.has(key)) {
                 this._playBuffer(this.assets.get(key));
                 return;
@@ -167,7 +217,7 @@ export class SoundManager {
             'gameover': () => this.playGameOver(true)
         };
 
-        if (synthMap[key]) {
+        if (hasOwn(synthMap, key)) {
             synthMap[key]();
         }
     }
@@ -214,14 +264,14 @@ export class SoundManager {
     playScore(force = false) {
         if (!force && this.assets.has('score')) return this.play('score');
         this.playTone(800, 0.15, 'sine', 0.25);
-        setTimeout(() => this.playTone(1000, 0.15, 'sine', 0.25), 50);
+        this._later(() => this.playTone(1000, 0.15, 'sine', 0.25), 50);
     }
 
     playGameOver(force = false) {
         if (!force && this.assets.has('gameover')) return this.play('gameover');
         this.playTone(300, 0.2, 'sawtooth', 0.3);
-        setTimeout(() => this.playTone(200, 0.2, 'sawtooth', 0.3), 100);
-        setTimeout(() => this.playTone(150, 0.3, 'sawtooth', 0.3), 200);
+        this._later(() => this.playTone(200, 0.2, 'sawtooth', 0.3), 100);
+        this._later(() => this.playTone(150, 0.3, 'sawtooth', 0.3), 200);
     }
 
     playClick(force = false) {
@@ -232,11 +282,32 @@ export class SoundManager {
     playSuccess(force = false) {
         if (!force && this.assets.has('success')) return this.play('success');
         this.playTone(600, 0.1, 'sine', 0.2);
-        setTimeout(() => this.playTone(800, 0.2, 'sine', 0.2), 100);
+        this._later(() => this.playTone(800, 0.2, 'sine', 0.2), 100);
     }
 
     playError(force = false) {
         if (!force && this.assets.has('error')) return this.play('error');
         this.playTone(200, 0.2, 'sawtooth', 0.3);
     }
+
+    /**
+     * Cancel queued tones, close the audio context and drop decoded buffers.
+     * Browsers cap the number of live AudioContexts per page.
+     */
+    destroy() {
+        for (const id of this._timers) {
+            clearTimeout(id);
+        }
+        this._timers.clear();
+
+        if (this.audioContext) {
+            const closing = this.audioContext.close?.();
+            closing?.catch?.(() => {});
+        }
+
+        this.audioContext = null;
+        this.masterGain = null;
+        this.assets.clear();
+        this._loading.clear();
+    }
 }

package/src/dopamine/components/ScreenShake.js

@@ -15,16 +15,17 @@ export class ScreenShake extends Component {
     }
 
     shake(intensity = 5, duration = 0.2) {
+        // Save original if not already shaking. Mid-shake the object sits at
+        // an offset, and saving that would move its resting position.
+        if (!this.isShaking) {
+            this.originalPos.x = this.gameObject.x;
+            this.originalPos.y = this.gameObject.y;
+        }
+
         this.intensity = intensity;
         this.duration = duration;
         this.timer = 0;
         this.isShaking = true;
-
-        // Save original if not already shaking
-        if (this.timer === 0) {
-            this.originalPos.x = this.gameObject.x;
-            this.originalPos.y = this.gameObject.y;
-        }
     }
 
     update(dt) {

package/src/dopamine/components/index.js

@@ -1,4 +1,2 @@
-import Dopamine from '../index.js';
-
 export { ParticleEmitter } from './ParticleEmitter.js';
 export { ScreenShake } from './ScreenShake.js';