dopaminejs 2.1.0 → 2.3.0

package/src/dopamine/core/DataService.js

@@ -1,6 +1,9 @@
 /**
  * Data Service Module
  * Handles local storage persistence
+ *
+ * The storage may be synchronous (localStorage) or return promises
+ * (AsyncStorage, an IndexedDB wrapper, a server call). Every call is awaited.
  */
 
 import { resolveStorage } from '../utils/storage.js';
@@ -9,6 +12,30 @@ export class DataService {
     constructor(config = {}) {
         this.storage = config.storage || resolveStorage();
         this.prefix = config.prefix || 'dopamine_';
+
+        // Last write still in flight on promise storage, or null.
+        this._tail = null;
+    }
+
+    /**
+     * Run a write after any write still in flight.
+     *
+     * Promise storage can finish two overlapping writes in either order, and
+     * the older value would win. Synchronous storage never has one in flight,
+     * so it still writes before this returns.
+     * @private
+     */
+    _write(op) {
+        const result = this._tail ? this._tail.then(op) : op();
+
+        if (typeof result?.then === 'function') {
+            const tail = Promise.resolve(result).catch(() => {}).then(() => {
+                if (this._tail === tail) this._tail = null;
+            });
+            this._tail = tail;
+        }
+
+        return result;
     }
 
     /**
@@ -19,7 +46,7 @@ export class DataService {
     async save(key, data) {
         try {
             const serialized = JSON.stringify(data);
-            this.storage.setItem(this.prefix + key, serialized);
+            await this._write(() => this.storage.setItem(this.prefix + key, serialized));
             return true;
         } catch (e) {
             console.error('Error saving data:', e);
@@ -34,7 +61,8 @@ export class DataService {
      */
     async load(key, defaultValue = null) {
         try {
-            const data = this.storage.getItem(this.prefix + key);
+            await this._tail;
+            const data = await this.storage.getItem(this.prefix + key);
             return data ? JSON.parse(data) : defaultValue;
         } catch (e) {
             console.error('Error loading data:', e);
@@ -47,6 +75,6 @@ export class DataService {
      * @param {string} key 
      */
     async clear(key) {
-        this.storage.removeItem(this.prefix + key);
+        await this._write(() => this.storage.removeItem(this.prefix + key));
     }
 }

package/src/dopamine/core/RewardSystem.js

@@ -5,12 +5,76 @@
 
 import { EventEmitter } from './EventEmitter.js';
 
+// Keys that resolve to something on Object.prototype. Game names and
+// achievement ids index plain objects, so these must never be used as one.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const isSafeKey = (key) => typeof key === 'string' && key.length > 0 && !UNSAFE_KEYS.has(key);
+const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const toCount = (value, fallback, min = 0) => {
+    const number = Number(value);
+    return Number.isInteger(number) && number >= min ? number : fallback;
+};
+
 export class RewardSystem extends EventEmitter {
+    /**
+     * @param {Object} dataService - Persistence, see DataService
+     * @param {Object} [config]
+     * @param {Object} [config.achievements] - Extra achievement definitions
+     * @param {Object} [config.events] - Kernel EventBus to mirror events onto
+     * @param {Object} [config.kernel] - Kernel; its `events` bus is used if present
+     */
     constructor(dataService, config = {}) {
         super();
         this.dataService = dataService;
         this.player = null;
         this.achievements = { ...this._initAchievements(), ...(config.achievements || {}) };
+
+        // Optional bridge to the kernel bus. EventBus.Events already declared
+        // XP_GAINED, LEVEL_UP and ACHIEVEMENT_UNLOCKED with nothing emitting
+        // them; this connects the two event systems without changing the
+        // existing rewardSystem.on(...) surface that games already use.
+        this.events = config.events || config.kernel?.events || null;
+
+        // Write batching. Every mutation used to hit storage directly, so one
+        // recordGame produced four full serializations of the player object.
+        this._batchDepth = 0;
+        this._pendingSave = false;
+    }
+
+    /**
+     * Emit locally, and mirror onto the kernel bus when one is attached.
+     * @private
+     */
+    _publish(event, data) {
+        this.emit(event, data);
+        if (this.events) {
+            this.events.emit(event, data);
+        }
+    }
+
+    /**
+     * Run `fn` with saves collapsed into a single write at the end.
+     *
+     * Nested batches are counted, so an inner operation that batches on its
+     * own still results in exactly one write for the outermost call.
+     *
+     * @param {Function} fn
+     * @private
+     */
+    async _batch(fn) {
+        this._batchDepth++;
+        try {
+            return await fn();
+        } finally {
+            this._batchDepth--;
+            if (this._batchDepth === 0 && this._pendingSave) {
+                this._pendingSave = false;
+                await this._write();
+            }
+        }
     }
 
     /**
@@ -22,14 +86,35 @@ export class RewardSystem extends EventEmitter {
         this.player = this._migrate(saved);
 
         // Check daily streak
-        this._updateDailyStreak();
+        const streakChanged = this._updateDailyStreak();
 
         // Save updated player data
         await this.save();
 
+        if (streakChanged) {
+            this._publishStreak();
+        }
+
         return this.player;
     }
 
+    /**
+     * @private
+     */
+    _requirePlayer() {
+        if (!this.player) {
+            throw new Error('[DopamineJS] RewardSystem.init() must be awaited before use');
+        }
+    }
+
+    /**
+     * @private
+     */
+    _publishStreak() {
+        const { current, longest } = this.player.streak;
+        this._publish('streak_updated', { current, longest });
+    }
+
     /**
      * Get default player data structure
      */
@@ -67,26 +152,118 @@ export class RewardSystem extends EventEmitter {
     _migrate(saved) {
         const defaults = this._getDefaultPlayer();
 
-        if (!saved || typeof saved !== 'object') {
+        if (!isRecord(saved)) {
             return defaults;
         }
 
+        // Storage is writable by the player and by anything else on the
+        // origin, so every field is checked. A string xp would concatenate on
+        // the next addXP, and a non-object stats would throw on first use.
+        const xpValue = Number(saved.xp);
+        const xp = Number.isFinite(xpValue) && xpValue >= 0 ? xpValue : 0;
+        const earned = this._calculateLevel(xp);
+
+        const savedStreak = isRecord(saved.streak) ? saved.streak : {};
+        const current = toCount(savedStreak.current, 1, 1);
+        const lastPlayDate = typeof savedStreak.lastPlayDate === 'string'
+            && /^\d{4}-\d{2}-\d{2}$/.test(savedStreak.lastPlayDate)
+            ? savedStreak.lastPlayDate
+            : defaults.streak.lastPlayDate;
+
         return {
             ...defaults,
             ...saved,
-            streak: { ...defaults.streak, ...(saved.streak || {}) },
-            achievements: saved.achievements || {},
-            stats: saved.stats || {}
+            name: typeof saved.name === 'string' ? saved.name : defaults.name,
+            xp,
+            // A level above the curve is kept: older versions banked levels
+            // at half the XP and those players keep what they earned.
+            level: Math.max(earned, toCount(saved.level, earned, 1)),
+            totalGamesPlayed: toCount(saved.totalGamesPlayed, 0),
+            createdAt: Number.isFinite(saved.createdAt) ? saved.createdAt : defaults.createdAt,
+            lastPlayedAt: Number.isFinite(saved.lastPlayedAt) ? saved.lastPlayedAt : defaults.lastPlayedAt,
+            streak: {
+                current,
+                longest: Math.max(current, toCount(savedStreak.longest, current, 1)),
+                lastPlayDate
+            },
+            achievements: this._migrateAchievements(saved.achievements),
+            stats: this._migrateStats(saved.stats)
         };
     }
 
+    /**
+     * @private
+     */
+    _migrateAchievements(saved) {
+        const achievements = {};
+        if (!isRecord(saved)) return achievements;
+
+        for (const id of Object.keys(saved)) {
+            const entry = saved[id];
+            if (!isSafeKey(id) || !isRecord(entry)) continue;
+
+            achievements[id] = {
+                unlockedAt: Number.isFinite(entry.unlockedAt) ? entry.unlockedAt : Date.now(),
+                seen: entry.seen === true
+            };
+        }
+
+        return achievements;
+    }
+
+    /**
+     * @private
+     */
+    _migrateStats(saved) {
+        const stats = {};
+        if (!isRecord(saved)) return stats;
+
+        for (const gameName of Object.keys(saved)) {
+            const entry = saved[gameName];
+            if (!isSafeKey(gameName) || !isRecord(entry)) continue;
+
+            const game = {};
+            for (const key of Object.keys(entry)) {
+                if (isSafeKey(key) && Number.isFinite(entry[key])) {
+                    game[key] = entry[key];
+                }
+            }
+            game.totalPlays = toCount(entry.totalPlays, 0);
+            game.highScore = Number.isFinite(entry.highScore) ? entry.highScore : 0;
+
+            stats[gameName] = game;
+        }
+
+        return stats;
+    }
+
     /**
      * Save player data
      */
     async save() {
-        if (this.player) {
-            this.player.lastPlayedAt = Date.now();
-            await this.dataService.save('player', this.player);
+        if (!this.player) return;
+
+        // Inside a batch, mark dirty and let the outermost call do the write.
+        if (this._batchDepth > 0) {
+            this._pendingSave = true;
+            return;
+        }
+
+        await this._write();
+    }
+
+    /**
+     * The actual persistence call. Bypasses batching.
+     * @private
+     */
+    async _write() {
+        this.player.lastPlayedAt = Date.now();
+        const saved = await this.dataService.save('player', this.player);
+
+        // DataService logs and returns false rather than throwing, so a full
+        // or blocked storage would otherwise lose progress without a sign.
+        if (saved === false) {
+            this._publish('save_failed', { key: 'player' });
         }
     }
 
@@ -103,11 +280,18 @@ export class RewardSystem extends EventEmitter {
             throw new TypeError(`[DopamineJS] addXP expects a finite number, received ${amount}`);
         }
 
+        this._requirePlayer();
+
         const oldLevel = this.player.level;
+
+        // XP stops at zero, so a large negative amount removes less than
+        // asked. Report what changed.
+        amount = Math.max(amount, -this.player.xp);
         this.player.xp += amount;
 
-        // Check for level up
-        const newLevel = this._calculateLevel(this.player.xp);
+        // Check for level up. Levels are never taken back, so a negative
+        // amount or a level banked under an older curve reports the stored one.
+        const newLevel = Math.max(oldLevel, this._calculateLevel(this.player.xp));
         const leveledUp = newLevel > oldLevel;
 
         if (leveledUp) {
@@ -117,10 +301,11 @@ export class RewardSystem extends EventEmitter {
         await this.save();
 
         // Notify listeners
-        this.emit('xp_gained', { amount, reason, leveledUp, newLevel });
+        const total = this.player.xp;
+        this._publish('xp_gained', { amount, reason, leveledUp, newLevel, total });
 
         if (leveledUp) {
-            this.emit('level_up', { oldLevel, newLevel });
+            this._publish('level_up', { oldLevel, newLevel, totalXP: total });
         }
 
         return { leveledUp, newLevel, xpGained: amount };
@@ -132,6 +317,8 @@ export class RewardSystem extends EventEmitter {
     _calculateLevel(xp) {
         // Curve: XP = 50 * level * (level - 1)
         // 50L² - 50L - xp = 0  =>  L = (1 + sqrt(1 + 4*xp/50)) / 2
+        if (!(xp > 0)) return 1;
+
         const level = Math.floor((1 + Math.sqrt(1 + 4 * xp / 50)) / 2);
         return Math.max(1, level);
     }
@@ -140,6 +327,8 @@ export class RewardSystem extends EventEmitter {
      * Get XP needed for next level
      */
     getXPForNextLevel() {
+        this._requirePlayer();
+
         const nextLevel = this.player.level + 1;
         const xpNeeded = 50 * nextLevel * (nextLevel - 1);
         const currentLevelXP = 50 * this.player.level * (this.player.level - 1);
@@ -164,9 +353,40 @@ export class RewardSystem extends EventEmitter {
      * @param {string} gameName - Unique ID for the game
      * @param {Object} result - Game-specific result data
      */
-    async recordGame(gameName, result) {
+    async recordGame(gameName, result = {}) {
+        this._requirePlayer();
+
+        if (!isSafeKey(gameName)) {
+            throw new TypeError(`[DopamineJS] recordGame expects a game name, received ${String(gameName)}`);
+        }
+
+        if (!isRecord(result)) {
+            throw new TypeError('[DopamineJS] recordGame expects a result object');
+        }
+
+        // Checked before anything is touched, so a bad score cannot leave the
+        // play counted and the XP missing.
+        if (result.score !== undefined && !Number.isFinite(result.score)) {
+            throw new TypeError(`[DopamineJS] recordGame expects a finite score, received ${String(result.score)}`);
+        }
+
+        // Batched: addXP and each unlockAchievement below also save, which
+        // meant four full serializations of the player object per game.
+        return this._batch(() => this._recordGame(gameName, result));
+    }
+
+    /**
+     * @private
+     */
+    async _recordGame(gameName, result) {
+        // A game played on a new day counts for the streak, not only a
+        // page load. A tab left open past midnight used to miss the day.
+        if (this._updateDailyStreak()) {
+            this._publishStreak();
+        }
+
         // Initialize stats for this game if not exists
-        if (!this.player.stats[gameName]) {
+        if (!hasOwn(this.player.stats, gameName)) {
             this.player.stats[gameName] = { totalPlays: 0, highScore: 0 };
         }
 
@@ -179,22 +399,24 @@ export class RewardSystem extends EventEmitter {
         // Update high score if applicable
         if (result.score !== undefined && result.score > stats.highScore) {
             stats.highScore = result.score;
-            this.emit('new_high_score', { gameName, score: result.score });
+            this._publish('new_high_score', { gameName, score: result.score });
         }
 
         // Merge other result data into stats
         Object.keys(result).forEach(key => {
-            if (key !== 'score') {
-                stats[key] = (stats[key] || 0) + (typeof result[key] === 'number' ? result[key] : 0);
+            if (key !== 'score' && isSafeKey(key)) {
+                const current = hasOwn(stats, key) && Number.isFinite(stats[key]) ? stats[key] : 0;
+                stats[key] = current + (Number.isFinite(result[key]) ? result[key] : 0);
             }
         });
 
         // Base XP for playing
         let xp = 10;
 
-        // Score-based bonus
+        // Score-based bonus. A negative score earns nothing extra; it does
+        // not take XP away.
         if (result.score) {
-            xp += Math.floor(result.score / 5);
+            xp += Math.max(0, Math.floor(result.score / 5));
         }
 
         // Streak multiplier
@@ -216,7 +438,7 @@ export class RewardSystem extends EventEmitter {
 
         for (const [id, achievement] of Object.entries(this.achievements)) {
             // Skip if already unlocked
-            if (this.player.achievements[id]) continue;
+            if (hasOwn(this.player.achievements, id)) continue;
 
             // Check conditions are user-supplied; one throwing must not stop
             // the others from ever unlocking.
@@ -228,8 +450,7 @@ export class RewardSystem extends EventEmitter {
                 continue;
             }
 
-            if (met) {
-                await this.unlockAchievement(id);
+            if (met && await this.unlockAchievement(id)) {
                 unlockedAchievements.push(achievement);
             }
         }
@@ -241,6 +462,13 @@ export class RewardSystem extends EventEmitter {
      * Unlock an achievement
      */
     async unlockAchievement(achievementId) {
+        this._requirePlayer();
+
+        if (!isSafeKey(achievementId) || !hasOwn(this.achievements, achievementId)) return false;
+
+        // Already unlocked: paying the XP again would let one call farm levels.
+        if (hasOwn(this.player.achievements, achievementId)) return false;
+
         const achievement = this.achievements[achievementId];
         if (!achievement) return false;
 
@@ -254,7 +482,7 @@ export class RewardSystem extends EventEmitter {
         await this.addXP(Number.isFinite(achievement.xp) ? achievement.xp : 0,
             `Achievement: ${achievement.name}`);
 
-        this.emit('achievement_unlocked', achievement);
+        this._publish('achievement_unlocked', { ...achievement, id: achievementId });
         await this.save();
 
         return true;
@@ -284,7 +512,7 @@ export class RewardSystem extends EventEmitter {
      */
     async markAchievementsSeen(achievementIds) {
         for (const id of achievementIds) {
-            if (this.player.achievements[id]) {
+            if (hasOwn(this.player.achievements, id)) {
                 this.player.achievements[id].seen = true;
             }
         }
@@ -293,6 +521,7 @@ export class RewardSystem extends EventEmitter {
 
     /**
      * Update daily streak
+     * @returns {boolean} True when the calendar day changed
      */
     _updateDailyStreak() {
         const today = this._getTodayDateString();
@@ -300,7 +529,7 @@ export class RewardSystem extends EventEmitter {
 
         if (lastPlayed === today) {
             // Already played today
-            return;
+            return false;
         }
 
         const yesterday = this._getYesterdayDateString();
@@ -317,6 +546,7 @@ export class RewardSystem extends EventEmitter {
         }
 
         this.player.streak.lastPlayDate = today;
+        return true;
     }
 
     /**

package/src/dopamine/effects/ParticleSystem.js

@@ -9,6 +9,20 @@ export class ParticleSystem {
             (typeof config.container === 'string' ? document.querySelector(config.container) : config.container)
             : document.body;
 
+        if (!this.container) {
+            console.warn(`[DopamineJS] Particle container '${config.container}' not found. Using document.body.`);
+            this.container = document.body;
+        }
+
+        // Upper bound on live particles. Each one is drawn every frame, so an
+        // oversized count would freeze the tab.
+        this.maxParticles = Number.isFinite(config.maxParticles) ? Math.max(0, Math.floor(config.maxParticles)) : 5000;
+
+        // Effects are skipped for users who asked the OS for less motion.
+        this._reducedMotion = config.respectReducedMotion !== false && typeof window.matchMedia === 'function'
+            ? window.matchMedia('(prefers-reduced-motion: reduce)')
+            : null;
+
         this.canvasId = config.canvasId || 'dopamine-particle-canvas';
 
         // Each instance owns its canvas. Sharing one by id meant two systems
@@ -50,6 +64,7 @@ export class ParticleSystem {
         this._onResize = () => this._resize();
         this._resizeObserver = null;
         this._frameHandle = null;
+        this._lastFrameTime = null;
 
         this._resize();
         // Use ResizeObserver for container resizing if supported, fallback to window resize
@@ -133,10 +148,13 @@ export class ParticleSystem {
             sprite = null,
             spread = Math.PI * 2,
             angle = 0,
-            size = 5
+            size = 5,
+            type = null
         } = config;
 
-        for (let i = 0; i < count; i++) {
+        const total = this._allowed(count);
+
+        for (let i = 0; i < total; i++) {
             const p = this._getParticle();
             const pAngle = angle + (Math.random() - 0.5) * spread;
             const pSpeed = Math.random() * speed;
@@ -151,13 +169,29 @@ export class ParticleSystem {
             p.color = Array.isArray(color) ? color[Math.floor(Math.random() * color.length)] : color;
             p.size = size * (0.8 + Math.random() * 0.4);
             p.sprite = sprite;
+            // Always set: pooled particles keep the fields of their last use.
+            p.type = type;
             p.rotation = Math.random() * Math.PI * 2;
             p.rotationSpeed = (Math.random() - 0.5) * 0.2;
 
             this.particles.push(p);
         }
 
-        this._startAnimation();
+        if (total > 0) {
+            this._startAnimation();
+        }
+    }
+
+    /**
+     * How many of `count` particles may be created right now.
+     * @private
+     */
+    _allowed(count) {
+        if (this._reducedMotion?.matches) return 0;
+        if (!Number.isFinite(count)) return 0;
+
+        const room = this.maxParticles - this.particles.length;
+        return Math.max(0, Math.min(Math.floor(count), room));
     }
 
     _getParticle() {
@@ -228,9 +262,11 @@ export class ParticleSystem {
         // Star burst is unique because of fixed angles, so we keep manual loop or use emit carefully
         // For simplicity, let's use emit but we lose the perfect star shape distribution
         // To keep it perfect, we'll manually push particles but use the pool
-        for (let i = 0; i < count; i++) {
+        const total = this._allowed(count);
+
+        for (let i = 0; i < total; i++) {
             const p = this._getParticle();
-            const angle = (Math.PI * 2 / count) * i;
+            const angle = (Math.PI * 2 / total) * i;
             const speed = 4;
 
             p.x = x;
@@ -249,38 +285,59 @@ export class ParticleSystem {
 
             this.particles.push(p);
         }
-        this._startAnimation();
+
+        if (total > 0) {
+            this._startAnimation();
+        }
     }
 
     _startAnimation() {
         if (!this.isAnimating) {
             this.isAnimating = true;
+            this._lastFrameTime = null;
             this._animate();
         }
     }
 
-    _animate() {
+    /**
+     * @param {number} [time] - requestAnimationFrame timestamp
+     */
+    _animate(time) {
         this._frameHandle = null;
         // CSS pixels: the context is pre-scaled by devicePixelRatio.
         this.ctx.clearRect(0, 0, this.width, this.height);
 
+        // Velocities are tuned per 60 Hz frame. Scaling by elapsed time keeps
+        // the same speed on a 120 Hz display instead of running twice as fast.
+        let step = 1;
+        if (Number.isFinite(time)) {
+            if (this._lastFrameTime !== null) {
+                step = Math.max(0, Math.min(3, (time - this._lastFrameTime) / (1000 / 60)));
+            }
+            this._lastFrameTime = time;
+        }
+
         for (let i = this.particles.length - 1; i >= 0; i--) {
             const p = this.particles[i];
 
             // Physics
-            p.vy += p.gravity;
-            p.x += p.vx;
-            p.y += p.vy;
-            p.life -= p.decay;
+            p.vy += p.gravity * step;
+            p.x += p.vx * step;
+            p.y += p.vy * step;
+            p.life -= p.decay * step;
 
             if (p.rotationSpeed) {
-                p.rotation += p.rotationSpeed;
+                p.rotation += p.rotationSpeed * step;
             }
 
-            // Death
+            // Death. Swap with the last particle rather than splice, which
+            // shifts the rest of the array for every particle that dies.
             if (p.life <= 0) {
                 this._recycleParticle(p);
-                this.particles.splice(i, 1);
+                const last = this.particles.pop();
+                if (i < this.particles.length) {
+                    this.particles[i] = last;
+                }
                 continue;
             }
 
@@ -313,7 +370,7 @@ export class ParticleSystem {
         }
 
         if (this.particles.length > 0) {
-            this._frameHandle = requestAnimationFrame(() => this._animate());
+            this._frameHandle = requestAnimationFrame((next) => this._animate(next));
         } else {
             this.isAnimating = false;
         }