dopaminejs 2.0.2 → 2.2.0

package/src/dopamine/ui/GameUI.js

@@ -3,6 +3,8 @@
  * Reusable UI elements for XP bars, achievement popups, level-up screens, etc.
  */
 
+const OVERLAY_ID = 'game-ui-overlay';
+
 export class GameUI {
     constructor(particleSystem) {
         this.particleSystem = particleSystem;
@@ -10,6 +12,12 @@ export class GameUI {
         this.xpBar = null;
         this.levelDisplay = null;
         this.streakDisplay = null;
+
+        // Everything this instance put in the DOM or scheduled, so destroy()
+        // can take it all back out again.
+        this._timers = new Set();
+        this._detached = [];
+
         this.init();
     }
 
@@ -19,50 +27,92 @@ export class GameUI {
     init() {
         // Create main container
         this.container = document.createElement('div');
-        this.container.id = 'game-ui-overlay';
+        this.container.className = 'game-ui-overlay';
+
+        // The stylesheet targets #game-ui-overlay. Claim the id only if it is
+        // free, so a second instance cannot produce a duplicate id.
+        if (!document.getElementById(OVERLAY_ID)) {
+            this.container.id = OVERLAY_ID;
+        }
+
         this.container.innerHTML = `
             <div class="game-ui-top-bar">
-                <div class="level-badge" id="level-badge">
+                <div class="level-badge">
                     <span class="level-label">LVL</span>
-                    <span class="level-number" id="level-number">1</span>
+                    <span class="level-number">1</span>
                 </div>
-                
+
                 <div class="xp-container">
                     <div class="xp-bar-bg">
-                        <div class="xp-bar-fill" id="xp-bar-fill" style="width: 0%"></div>
+                        <div class="xp-bar-fill" style="width: 0%"></div>
                     </div>
-                    <div class="xp-text" id="xp-text">0 /100 XP</div>
+                    <div class="xp-text">0 / 100 XP</div>
                 </div>
-                
-                <div class="streak-badge" id="streak-badge">
+
+                <div class="streak-badge">
                     <span class="streak-icon">🔥</span>
-                    <span class="streak-number" id="streak-number">1</span>
+                    <span class="streak-number">1</span>
                 </div>
             </div>
         `;
 
         document.body.appendChild(this.container);
 
-        // Cache elements
-        this.xpBar = document.getElementById('xp-bar-fill');
-        this.xpText = document.getElementById('xp-text');
-        this.levelDisplay = document.getElementById('level-number');
-        this.streakDisplay = document.getElementById('streak-number');
+        // Scoped to this instance. Document-wide getElementById would make a
+        // second GameUI silently rebind every element to the first one's DOM.
+        this.levelBadge = this.container.querySelector('.level-badge');
+        this.streakBadge = this.container.querySelector('.streak-badge');
+        this.xpBar = this.container.querySelector('.xp-bar-fill');
+        this.xpText = this.container.querySelector('.xp-text');
+        this.levelDisplay = this.container.querySelector('.level-number');
+        this.streakDisplay = this.container.querySelector('.streak-number');
+    }
+
+    /**
+     * setTimeout that destroy() can cancel.
+     * @private
+     */
+    _defer(fn, delay) {
+        const id = setTimeout(() => {
+            this._timers.delete(id);
+            fn();
+        }, delay);
+        this._timers.add(id);
+        return id;
+    }
+
+    /**
+     * Append a transient element and remember it for cleanup.
+     * @private
+     */
+    _mount(el) {
+        document.body.appendChild(el);
+        this._detached.push(el);
+        return el;
+    }
+
+    /**
+     * Replay a CSS animation by clearing it for one tick.
+     * @private
+     */
+    _replayAnimation(el, animation) {
+        if (!el) return;
+        el.style.animation = 'none';
+        this._defer(() => { el.style.animation = animation; }, 10);
     }
 
     /**
      * Update XP bar
+     * @param {number} current - XP held right now
+     * @param {number} needed - XP still required for the next level
+     * @param {number} total - XP total that marks the next level
      */
     updateXP(current, needed, total) {
-        const progress = (current / total) * 100;
-        this.xpBar.style.width = `${Math.min(100, progress)}%`;
+        const progress = total > 0 ? (current / total) * 100 : 0;
+        this.xpBar.style.width = `${Math.max(0, Math.min(100, progress))}%`;
         this.xpText.textContent = `${current} / ${total} XP`;
 
-        // Add pulse animation when gaining XP
-        this.xpBar.style.animation = 'none';
-        setTimeout(() => {
-            this.xpBar.style.animation = 'xp-pulse 0.3s ease-out';
-        }, 10);
+        this._replayAnimation(this.xpBar, 'xp-pulse 0.3s ease-out');
     }
 
     /**
@@ -70,13 +120,7 @@ export class GameUI {
      */
     updateLevel(level) {
         this.levelDisplay.textContent = level;
-
-        // Pulse animation
-        const badge = document.getElementById('level-badge');
-        badge.style.animation = 'none';
-        setTimeout(() => {
-            badge.style.animation = 'level-pulse 0.5s ease-out';
-        }, 10);
+        this._replayAnimation(this.levelBadge, 'level-pulse 0.5s ease-out');
     }
 
     /**
@@ -86,16 +130,20 @@ export class GameUI {
         this.streakDisplay.textContent = days;
 
         // Change color based on streak
-        const badge = document.getElementById('streak-badge');
         if (days >= 7) {
-            badge.style.background = 'linear-gradient(135deg, #ff6b00 0%, #ff4400 100%)';
+            this.streakBadge.style.background = 'linear-gradient(135deg, #ff6b00 0%, #ff4400 100%)';
         } else if (days >= 3) {
-            badge.style.background = 'linear-gradient(135deg, #ff8800 0%, #ff6b00 100%)';
+            this.streakBadge.style.background = 'linear-gradient(135deg, #ff8800 0%, #ff6b00 100%)';
         }
     }
 
     /**
      * Show achievement unlocked popup
+     *
+     * `icon` is rendered as HTML by design (documented in ARCHITECTURE.md, so
+     * games can pass an <img> or inline SVG). Every other field is game state
+     * and could carry a player-supplied or server-supplied string, so it goes
+     * in as text.
      */
     showAchievement(achievement) {
         const popup = document.createElement('div');
@@ -103,28 +151,33 @@ export class GameUI {
         popup.innerHTML = `
             <div class="achievement-shine"></div>
             <div class="achievement-content">
-                <div class="achievement-icon">${achievement.icon}</div>
+                <div class="achievement-icon"></div>
                 <div class="achievement-info">
                     <div class="achievement-title">Achievement Unlocked!</div>
-                    <div class="achievement-name">${achievement.name}</div>
-                    <div class="achievement-desc">${achievement.description}</div>
-                    <div class="achievement-xp">+${achievement.xp} XP</div>
+                    <div class="achievement-name"></div>
+                    <div class="achievement-desc"></div>
+                    <div class="achievement-xp"></div>
                 </div>
             </div>
         `;
 
-        document.body.appendChild(popup);
+        popup.querySelector('.achievement-icon').innerHTML = achievement.icon ?? '';
+        popup.querySelector('.achievement-name').textContent = achievement.name ?? '';
+        popup.querySelector('.achievement-desc').textContent = achievement.description ?? '';
+        popup.querySelector('.achievement-xp').textContent = `+${achievement.xp ?? 0} XP`;
+
+        this._mount(popup);
 
         // Trigger confetti at popup location
-        setTimeout(() => {
+        this._defer(() => {
             const rect = popup.getBoundingClientRect();
             this.particleSystem.confetti(rect.left + rect.width / 2, rect.top + rect.height / 2, 40);
         }, 300);
 
         // Remove after animation
-        setTimeout(() => {
+        this._defer(() => {
             popup.style.animation = 'slideOut 0.3s ease-in forwards';
-            setTimeout(() => popup.remove(), 300);
+            this._defer(() => this._remove(popup), 300);
         }, 4000);
     }
 
@@ -137,17 +190,18 @@ export class GameUI {
         overlay.innerHTML = `
             <div class="level-up-content">
                 <div class="level-up-title">LEVEL UP!</div>
-                <div class="level-up-number">${newLevel}</div>
+                <div class="level-up-number"></div>
                 <div class="level-up-subtitle">Amazing progress!</div>
             </div>
         `;
+        overlay.querySelector('.level-up-number').textContent = newLevel;
 
-        document.body.appendChild(overlay);
+        this._mount(overlay);
 
         // Fireworks effect
-        setTimeout(() => {
+        this._defer(() => {
             for (let i = 0; i < 5; i++) {
-                setTimeout(() => {
+                this._defer(() => {
                     const x = Math.random() * window.innerWidth;
                     const y = Math.random() * window.innerHeight * 0.6;
                     this.particleSystem.confetti(x, y, 30);
@@ -156,9 +210,9 @@ export class GameUI {
         }, 300);
 
         // Remove after 3 seconds
-        setTimeout(() => {
+        this._defer(() => {
             overlay.style.opacity = '0';
-            setTimeout(() => overlay.remove(), 500);
+            this._defer(() => this._remove(overlay), 500);
         }, 2500);
     }
 
@@ -174,9 +228,9 @@ export class GameUI {
         floater.style.color = color;
         floater.style.fontSize = size;
 
-        document.body.appendChild(floater);
+        this._mount(floater);
 
-        setTimeout(() => floater.remove(), 2000);
+        this._defer(() => this._remove(floater), 2000);
     }
 
     /**
@@ -188,7 +242,7 @@ export class GameUI {
     }
 
     /**
-     * Show "near miss"indicator
+     * Show "near miss" indicator
      */
     showNearMiss(x, y) {
         this.showFloatingText('CLOSE CALL!', x, y, '#45b7d1', '20px');
@@ -222,6 +276,12 @@ export class GameUI {
 
     /**
      * Show Game Over Summary
+     *
+     * @param {Object} data
+     * @param {number|string} data.score - Final score
+     * @param {Object} [data.metrics] - Label/value pairs listed under the score
+     * @param {Function} [data.onReplay] - Replay button handler (default: reload)
+     * @param {Function} [data.onExit] - Exit button handler (button hidden if omitted)
      */
     showSummary(data) {
         const overlay = document.createElement('div');
@@ -233,23 +293,85 @@ export class GameUI {
         overlay.style.transform = 'translate(-50%, -50%)';
         overlay.style.zIndex = '1000';
 
-        let metricsHtml = '';
-        if (data.metrics) {
-            metricsHtml = Object.entries(data.metrics)
-                .map(([key, value]) => `<div style="display:flex;justify-content:space-between;width:100%"><span>${key}:</span> <strong>${value}</strong></div>`)
-                .join('');
+        const heading = document.createElement('h1');
+        heading.textContent = 'Game Over';
+
+        const score = document.createElement('div');
+        score.className = 'summary-score';
+        score.style.cssText = 'font-size: 3rem; font-weight: bold; color: #e06020; margin: 10px 0;';
+        score.textContent = data.score;
+
+        const metrics = document.createElement('div');
+        metrics.className = 'summary-metrics';
+        metrics.style.cssText = 'width: 100%; margin-bottom: 20px;';
+
+        for (const [key, value] of Object.entries(data.metrics || {})) {
+            const row = document.createElement('div');
+            row.style.cssText = 'display:flex;justify-content:space-between;width:100%';
+
+            const label = document.createElement('span');
+            label.textContent = `${key}:`;
+
+            const amount = document.createElement('strong');
+            amount.textContent = value;
+
+            row.append(label, amount);
+            metrics.appendChild(row);
         }
 
-        overlay.innerHTML = `
-            <h1>Game Over</h1>
-            <div style="font-size: 3rem; font-weight: bold; color: #e06020; margin: 10px 0;">${data.score}</div>
-            <div style="width: 100%; margin-bottom: 20px;">
-                ${metricsHtml}
-            </div>
-            <button class="btn" onclick="location.reload()">Play Again</button>
-            <button class="btn" onclick="window.location.href='index.html'" style="margin-top: 10px; background: #543847;">Exit</button>
-        `;
+        overlay.append(heading, score, metrics);
+
+        // addEventListener rather than an onclick attribute: inline handlers
+        // are blocked by any script-src CSP without 'unsafe-inline'.
+        const replay = document.createElement('button');
+        replay.className = 'btn';
+        replay.textContent = 'Play Again';
+        replay.addEventListener('click', data.onReplay || (() => window.location.reload()));
+        overlay.appendChild(replay);
 
-        document.body.appendChild(overlay);
+        if (data.onExit) {
+            const exit = document.createElement('button');
+            exit.className = 'btn';
+            exit.textContent = 'Exit';
+            exit.style.cssText = 'margin-top: 10px; background: #543847;';
+            exit.addEventListener('click', data.onExit);
+            overlay.appendChild(exit);
+        }
+
+        this._mount(overlay);
+        return overlay;
+    }
+
+    /**
+     * @private
+     */
+    _remove(el) {
+        el.remove();
+        const i = this._detached.indexOf(el);
+        if (i > -1) this._detached.splice(i, 1);
+    }
+
+    /**
+     * Tear down the overlay, any transient popups, and all pending timers.
+     */
+    destroy() {
+        for (const id of this._timers) {
+            clearTimeout(id);
+        }
+        this._timers.clear();
+
+        for (const el of this._detached) {
+            el.remove();
+        }
+        this._detached = [];
+
+        this.container?.remove();
+        this.container = null;
+        this.xpBar = null;
+        this.xpText = null;
+        this.levelBadge = null;
+        this.streakBadge = null;
+        this.levelDisplay = null;
+        this.streakDisplay = null;
     }
 }

package/src/dopamine/ui/dopamine.css

@@ -6,7 +6,10 @@
 
 /* ==================== TOP BAR (XP, Level, Streak) ==================== */
 
-#game-ui-overlay {
+/* The id is kept so existing `#game-ui-overlay` overrides still win on
+   specificity; the class is what every instance actually carries. */
+#game-ui-overlay,
+.game-ui-overlay {
     position: fixed;
     top: 0;
     left: 0;

package/src/dopamine/utils/storage.js

@@ -0,0 +1,49 @@
+/**
+ * Storage resolution for environments that may not have localStorage.
+ *
+ * Three cases need to work:
+ *  - Browser: localStorage.
+ *  - SSR / worker / test runner: no `window` at all, so importing the package
+ *    must not throw at module or constructor time.
+ *  - Safari private browsing and storage-blocked iframes: localStorage exists
+ *    but every write throws QuotaExceededError.
+ */
+
+/**
+ * A Storage-shaped object backed by a Map. Values do not survive a reload,
+ * which is the correct degradation: the game runs, progress just is not kept.
+ *
+ * @returns {{getItem: Function, setItem: Function, removeItem: Function, clear: Function}}
+ */
+export function createMemoryStorage() {
+    const map = new Map();
+
+    return {
+        getItem: (key) => (map.has(key) ? map.get(key) : null),
+        setItem: (key, value) => { map.set(key, String(value)); },
+        removeItem: (key) => { map.delete(key); },
+        clear: () => { map.clear(); }
+    };
+}
+
+/**
+ * Return localStorage if it is present and writable, otherwise a memory store.
+ *
+ * @returns {Object} Storage-shaped object
+ */
+export function resolveStorage() {
+    try {
+        if (typeof localStorage === 'undefined') {
+            return createMemoryStorage();
+        }
+
+        // Presence is not enough: blocked contexts throw only on write.
+        const probe = '__dopamine_probe__';
+        localStorage.setItem(probe, '1');
+        localStorage.removeItem(probe);
+
+        return localStorage;
+    } catch {
+        return createMemoryStorage();
+    }
+}

package/src/index.js

@@ -12,6 +12,12 @@ export { PluginRegistry } from './core/PluginRegistry.js';
 // Export System Interfaces
 export * from './interfaces/index.js';
 
+// The emitter RewardSystem extends, so consumers can type their listeners.
+export { EventEmitter } from './dopamine/core/EventEmitter.js';
+
+// Storage resolution, useful for tests and for SSR where localStorage is absent.
+export { createMemoryStorage, resolveStorage } from './dopamine/utils/storage.js';
+
 // Export New Engine Core
 export { Game } from './core/Game.js';
 export { Scene } from './core/Scene.js';

package/src/systems/Input.js

@@ -1,3 +1,5 @@
+import { deprecatedGlobal } from './deprecate.js';
+
 /**
  * Input System
  * Tracks keyboard and mouse input.
@@ -71,7 +73,9 @@ export class Input {
     }
 }
 
-// DEPRECATED: Keep for backward compatibility
-export const GlobalInput = new Input();
-// Note: GlobalInput won't have listeners attached unless init() is called
-console.warn('[DopamineJS] GlobalInput is deprecated. Use kernel.input instead.');
+// DEPRECATED: kept for v1 compatibility. Warns on first use, not on import.
+// Note: listeners are not attached unless init() is called.
+export const GlobalInput = deprecatedGlobal(
+    new Input(),
+    '[DopamineJS] GlobalInput is deprecated. Use kernel.input instead.'
+);

package/src/systems/Loader.js

@@ -1,3 +1,5 @@
+import { deprecatedGlobal } from './deprecate.js';
+
 /**
  * Asset Loader
  * Loads and caches images, audio, etc.
@@ -39,6 +41,8 @@ export class Loader {
     }
 }
 
-// DEPRECATED: Keep for backward compatibility
-export const GlobalLoader = new Loader();
-console.warn('[DopamineJS] GlobalLoader is deprecated. Use kernel.loader instead.');
+// DEPRECATED: kept for v1 compatibility. Warns on first use, not on import.
+export const GlobalLoader = deprecatedGlobal(
+    new Loader(),
+    '[DopamineJS] GlobalLoader is deprecated. Use kernel.loader instead.'
+);

package/src/systems/Physics.js

@@ -1,3 +1,5 @@
+import { deprecatedGlobal } from './deprecate.js';
+
 import { Collider } from '../core/Collider.js';
 
 export class Physics {
@@ -112,6 +114,8 @@ export class Physics {
     setGravity(x, y) { /* TODO: Add gravity support */ }
 }
 
-// DEPRECATED: Keep for backward compatibility, but log warning
-export const GlobalPhysics = new Physics();
-console.warn('[DopamineJS] GlobalPhysics is deprecated. Use kernel.physics instead.');
+// DEPRECATED: kept for v1 compatibility. Warns on first use, not on import.
+export const GlobalPhysics = deprecatedGlobal(
+    new Physics(),
+    '[DopamineJS] GlobalPhysics is deprecated. Use kernel.physics instead.'
+);

package/src/systems/Ticker.js

@@ -7,6 +7,7 @@ export class Ticker {
         this.running = false;
         this.lastTime = 0;
         this.callbacks = new Set();
+        this._frameHandle = null;
         this._tick = this._tick.bind(this);
     }
 
@@ -33,7 +34,14 @@ export class Ticker {
         if (this.running) return;
         this.running = true;
         this.lastTime = performance.now();
-        requestAnimationFrame(this._tick);
+
+        // Cancel first: a frame queued before the last stop() may still be
+        // pending, and letting it through would leave two live loops running
+        // the game at double speed.
+        if (this._frameHandle !== null) {
+            cancelAnimationFrame(this._frameHandle);
+        }
+        this._frameHandle = requestAnimationFrame(this._tick);
     }
 
     /**
@@ -41,9 +49,16 @@ export class Ticker {
      */
     stop() {
         this.running = false;
+
+        if (this._frameHandle !== null) {
+            cancelAnimationFrame(this._frameHandle);
+            this._frameHandle = null;
+        }
     }
 
     _tick(time) {
+        this._frameHandle = null;
+
         if (!this.running) return;
 
         const dt = (time - this.lastTime) / 1000; // Delta time in seconds
@@ -52,10 +67,14 @@ export class Ticker {
         // Cap dt to prevent huge jumps if tab was inactive
         const safeDt = Math.min(dt, 0.1);
 
-        for (const callback of this.callbacks) {
+        // Snapshot: a callback may add or remove callbacks mid-frame.
+        for (const callback of [...this.callbacks]) {
             callback(safeDt);
         }
 
-        requestAnimationFrame(this._tick);
+        // A callback may have called stop(); don't queue another frame if so.
+        if (this.running) {
+            this._frameHandle = requestAnimationFrame(this._tick);
+        }
     }
 }

package/src/systems/deprecate.js

@@ -0,0 +1,38 @@
+/**
+ * Deprecation helper for the v1 global singletons.
+ *
+ * These used to warn at module scope, which meant importing the package
+ * printed a warning for every legacy global whether or not the consumer
+ * touched one. A deprecation notice should cost you something only when you
+ * use the deprecated thing, otherwise it is just noise that trains people to
+ * ignore warnings.
+ *
+ * @param {Object} instance - The real system to delegate to
+ * @param {string} message - Warning text, emitted once on first use
+ * @returns {Object} A proxy that warns on first property access
+ */
+export function deprecatedGlobal(instance, message) {
+    let warned = false;
+
+    return new Proxy(instance, {
+        get(target, prop, receiver) {
+            if (!warned) {
+                warned = true;
+                console.warn(message);
+            }
+
+            const value = Reflect.get(target, prop, receiver);
+            // Methods must stay bound to the real instance, not the proxy,
+            // or internal `this` access re-enters the trap on every field.
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+
+        set(target, prop, value) {
+            if (!warned) {
+                warned = true;
+                console.warn(message);
+            }
+            return Reflect.set(target, prop, value);
+        }
+    });
+}