@nice2dev/game-engine 1.3.15 → 1.3.17

package/dist/cjs/performance/MemoryManagement.js

@@ -1,484 +1,424 @@
-'use strict';
-
-/**
- * @file MemoryManagement.ts
- * @description Allocation tracking and leak detection
- * PRO-1.5: Runtime & Performance
- *
- * Features:
- * - Allocation tracking
- * - Leak detection
- * - Memory snapshots
- * - Heap profiling
- * - GC monitoring
- * - Memory budgets
- * - Allocation statistics
- * - Memory warnings
- */
-// ============================================================
-// Default Configuration
-// ============================================================
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const DEFAULT_MEMORY_CONFIG = {
-    trackAllocations: true,
-    trackStacks: false,
-    stackDepth: 10,
-    leakDetectionInterval: 30000,
-    leakAgeThreshold: 60000,
-    snapshotRetention: 10,
-    budgets: {
-        total: 512 * 1024 * 1024,
-        categories: {
-            texture: 256 * 1024 * 1024,
-            mesh: 128 * 1024 * 1024,
-            audio: 64 * 1024 * 1024,
-        },
-        warnThreshold: 0.8,
-        criticalThreshold: 0.95,
+  trackAllocations: true,
+  trackStacks: false,
+  stackDepth: 10,
+  leakDetectionInterval: 3e4,
+  leakAgeThreshold: 6e4,
+  snapshotRetention: 10,
+  budgets: {
+    total: 512 * 1024 * 1024,
+    categories: {
+      texture: 256 * 1024 * 1024,
+      mesh: 128 * 1024 * 1024,
+      audio: 64 * 1024 * 1024
     },
+    warnThreshold: 0.8,
+    criticalThreshold: 0.95
+  }
 };
-// ============================================================
-// Memory Tracker
-// ============================================================
 class MemoryTracker {
-    constructor(config) {
-        this.config = { ...DEFAULT_MEMORY_CONFIG };
-        this.allocations = new Map();
-        this.nextAllocationId = 1;
-        // Stats
-        this.stats = {
-            totalAllocated: 0,
-            totalFreed: 0,
-            currentUsage: 0,
-            peakUsage: 0,
-            allocationCount: 0,
-            freeCount: 0,
-            activeAllocations: 0,
-            avgAllocationSize: 0,
-            gcStats: {
-                collections: 0,
-                totalPauseTime: 0,
-                lastPauseTime: 0,
-                lastCollectionTime: 0,
-                avgPauseTime: 0,
-            },
-        };
-        // Category stats
-        this.categoryStats = new Map();
-        this.tagStats = new Map();
-        // Snapshots
-        this.snapshots = [];
-        // Leak detection
-        this.leakDetectionTimer = null;
-        if (config) {
-            this.config = { ...this.config, ...config };
-        }
-        this.initializeCategoryStats();
-    }
-    initializeCategoryStats() {
-        const categories = [
-            'texture',
-            'mesh',
-            'audio',
-            'buffer',
-            'object',
-            'array',
-            'string',
-            'component',
-            'entity',
-            'system',
-            'asset',
-            'other',
-        ];
-        for (const cat of categories) {
-            this.categoryStats.set(cat, {
-                allocated: 0,
-                freed: 0,
-                active: 0,
-                count: 0,
-                peak: 0,
-            });
-        }
-    }
-    // ─── Allocation Tracking ───────────────────────────────
-    /**
-     * Track a memory allocation
-     */
-    alloc(size, category, tag = 'default') {
-        if (!this.config.trackAllocations) {
-            return 0;
-        }
-        const id = this.nextAllocationId++;
-        const record = {
-            id,
-            category,
-            size,
-            tag,
-            timestamp: Date.now(),
-            freed: false,
-        };
-        if (this.config.trackStacks) {
-            record.stack = this.captureStack();
-        }
-        this.allocations.set(id, record);
-        // Update stats
-        this.stats.totalAllocated += size;
-        this.stats.currentUsage += size;
-        this.stats.allocationCount++;
-        this.stats.activeAllocations++;
-        this.stats.peakUsage = Math.max(this.stats.peakUsage, this.stats.currentUsage);
-        this.stats.avgAllocationSize = this.stats.totalAllocated / this.stats.allocationCount;
-        // Update category stats
-        const catStats = this.categoryStats.get(category);
-        catStats.allocated += size;
-        catStats.active += size;
-        catStats.count++;
-        catStats.peak = Math.max(catStats.peak, catStats.active);
-        // Update tag stats
-        this.tagStats.set(tag, (this.tagStats.get(tag) ?? 0) + size);
-        // Check budgets
-        this.checkBudgets(category);
-        return id;
-    }
-    /**
-     * Track memory deallocation
-     */
-    free(id) {
-        const record = this.allocations.get(id);
-        if (!record || record.freed) {
-            return false;
-        }
-        record.freed = true;
-        record.freedAt = Date.now();
-        // Update stats
-        this.stats.totalFreed += record.size;
-        this.stats.currentUsage -= record.size;
-        this.stats.freeCount++;
-        this.stats.activeAllocations--;
-        // Update category stats
-        const catStats = this.categoryStats.get(record.category);
-        catStats.freed += record.size;
-        catStats.active -= record.size;
-        // Update tag stats
-        const tagSize = this.tagStats.get(record.tag) ?? 0;
-        this.tagStats.set(record.tag, Math.max(0, tagSize - record.size));
-        return true;
-    }
-    /**
-     * Track a resize operation
-     */
-    realloc(id, newSize) {
-        const record = this.allocations.get(id);
-        if (!record || record.freed) {
-            return false;
-        }
-        const sizeDiff = newSize - record.size;
-        // Update stats
-        if (sizeDiff > 0) {
-            this.stats.totalAllocated += sizeDiff;
-        }
-        else {
-            this.stats.totalFreed += Math.abs(sizeDiff);
-        }
-        this.stats.currentUsage += sizeDiff;
-        this.stats.peakUsage = Math.max(this.stats.peakUsage, this.stats.currentUsage);
-        // Update category stats
-        const catStats = this.categoryStats.get(record.category);
-        if (sizeDiff > 0) {
-            catStats.allocated += sizeDiff;
-        }
-        else {
-            catStats.freed += Math.abs(sizeDiff);
-        }
-        catStats.active += sizeDiff;
-        catStats.peak = Math.max(catStats.peak, catStats.active);
-        // Update tag stats
-        const tagSize = this.tagStats.get(record.tag) ?? 0;
-        this.tagStats.set(record.tag, tagSize + sizeDiff);
-        record.size = newSize;
-        // Check budgets
-        this.checkBudgets(record.category);
-        return true;
-    }
-    captureStack() {
-        const stack = new Error().stack ?? '';
-        const lines = stack.split('\n').slice(3, 3 + this.config.stackDepth);
-        return lines.join('\n');
-    }
-    // ─── Budget Checking ───────────────────────────────────
-    checkBudgets(category) {
-        const budgets = this.config.budgets;
-        // Check total budget
-        const totalUsage = this.stats.currentUsage / budgets.total;
-        if (totalUsage >= budgets.criticalThreshold) {
-            this.onMemoryCritical?.(this.stats.currentUsage, budgets.total);
-        }
-        else if (totalUsage >= budgets.warnThreshold) {
-            this.onMemoryWarning?.(this.stats.currentUsage, budgets.total);
-        }
-        // Check category budget
-        if (category && budgets.categories[category]) {
-            const catBudget = budgets.categories[category];
-            const catStats = this.categoryStats.get(category);
-            const catUsage = catStats.active / catBudget;
-            if (catUsage >= budgets.warnThreshold) {
-                this.onMemoryWarning?.(catStats.active, catBudget, category);
-            }
-        }
-    }
-    // ─── Leak Detection ────────────────────────────────────
-    startLeakDetection() {
-        if (this.leakDetectionTimer) {
-            return;
-        }
-        this.leakDetectionTimer = setInterval(() => {
-            const report = this.detectLeaks();
-            if (report.suspectedLeaks.length > 0) {
-                this.onLeakDetected?.(report);
-            }
-        }, this.config.leakDetectionInterval);
-    }
-    stopLeakDetection() {
-        if (this.leakDetectionTimer) {
-            clearInterval(this.leakDetectionTimer);
-            this.leakDetectionTimer = null;
-        }
-    }
-    detectLeaks() {
-        const now = Date.now();
-        const suspectedLeaks = [];
-        let totalLeakedSize = 0;
-        for (const record of this.allocations.values()) {
-            if (record.freed) {
-                continue;
-            }
-            const age = now - record.timestamp;
-            if (age > this.config.leakAgeThreshold) {
-                suspectedLeaks.push({
-                    allocation: { ...record },
-                    age,
-                    reason: `Allocation held for ${Math.round(age / 1000)}s without release`,
-                });
-                totalLeakedSize += record.size;
-            }
-        }
-        // Sort by size (largest first)
-        suspectedLeaks.sort((a, b) => b.allocation.size - a.allocation.size);
-        return {
-            suspectedLeaks,
-            totalLeakedSize,
-            reportedAt: now,
-        };
-    }
-    // ─── Snapshots ─────────────────────────────────────────
-    takeSnapshot(id = `snapshot_${Date.now()}`) {
-        const snapshot = {
-            id,
-            timestamp: Date.now(),
-            totalAllocated: this.stats.totalAllocated,
-            totalFreed: this.stats.totalFreed,
-            activeAllocations: this.stats.activeAllocations,
-            byCategory: new Map(this.categoryStats),
-            byTag: new Map(this.tagStats),
-            largestAllocations: this.getLargestAllocations(10),
-        };
-        this.snapshots.push(snapshot);
-        // Trim old snapshots
-        while (this.snapshots.length > this.config.snapshotRetention) {
-            this.snapshots.shift();
-        }
-        return snapshot;
-    }
-    getSnapshots() {
-        return [...this.snapshots];
-    }
-    compareSnapshots(snapshotA, snapshotB) {
-        const a = this.snapshots.find((s) => s.id === snapshotA);
-        const b = this.snapshots.find((s) => s.id === snapshotB);
-        if (!a || !b) {
-            return null;
-        }
-        const categoryDiffs = new Map();
-        for (const [cat, statsA] of a.byCategory) {
-            const statsB = b.byCategory.get(cat);
-            if (statsB) {
-                categoryDiffs.set(cat, statsB.active - statsA.active);
-            }
-        }
-        const tagDiffs = new Map();
-        const allTags = new Set([...a.byTag.keys(), ...b.byTag.keys()]);
-        for (const tag of allTags) {
-            const sizeA = a.byTag.get(tag) ?? 0;
-            const sizeB = b.byTag.get(tag) ?? 0;
-            tagDiffs.set(tag, sizeB - sizeA);
-        }
-        return {
-            allocationDiff: b.totalAllocated - a.totalAllocated,
-            freedDiff: b.totalFreed - a.totalFreed,
-            categoryDiffs,
-            tagDiffs,
-        };
-    }
-    // ─── GC Monitoring ─────────────────────────────────────
-    recordGC(pauseTime) {
-        const gcStats = this.stats.gcStats;
-        gcStats.collections++;
-        gcStats.totalPauseTime += pauseTime;
-        gcStats.lastPauseTime = pauseTime;
-        gcStats.lastCollectionTime = Date.now();
-        gcStats.avgPauseTime = gcStats.totalPauseTime / gcStats.collections;
-        this.onGC?.(gcStats);
-    }
-    // ─── Statistics ────────────────────────────────────────
-    getStats() {
-        return { ...this.stats };
-    }
-    getCategoryStats(category) {
-        return this.categoryStats.get(category);
-    }
-    getAllCategoryStats() {
-        return new Map(this.categoryStats);
-    }
-    getTagStats() {
-        return new Map(this.tagStats);
-    }
-    getLargestAllocations(count = 10) {
-        return Array.from(this.allocations.values())
-            .filter((r) => !r.freed)
-            .sort((a, b) => b.size - a.size)
-            .slice(0, count)
-            .map((r) => ({ ...r }));
-    }
-    getAllocationsByCategory(category) {
-        return Array.from(this.allocations.values())
-            .filter((r) => !r.freed && r.category === category)
-            .map((r) => ({ ...r }));
-    }
-    getAllocationsByTag(tag) {
-        return Array.from(this.allocations.values())
-            .filter((r) => !r.freed && r.tag === tag)
-            .map((r) => ({ ...r }));
-    }
-    // ─── Utilities ─────────────────────────────────────────
-    formatSize(bytes) {
-        if (bytes < 1024) {
-            return `${bytes} B`;
-        }
-        if (bytes < 1024 * 1024) {
-            return `${(bytes / 1024).toFixed(2)} KB`;
-        }
-        if (bytes < 1024 * 1024 * 1024) {
-            return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-        }
-        return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
-    }
-    generateReport() {
-        const lines = [];
-        lines.push('=== Memory Report ===');
-        lines.push(`Current Usage: ${this.formatSize(this.stats.currentUsage)}`);
-        lines.push(`Peak Usage: ${this.formatSize(this.stats.peakUsage)}`);
-        lines.push(`Total Allocated: ${this.formatSize(this.stats.totalAllocated)}`);
-        lines.push(`Total Freed: ${this.formatSize(this.stats.totalFreed)}`);
-        lines.push(`Active Allocations: ${this.stats.activeAllocations}`);
-        lines.push('');
-        lines.push('--- By Category ---');
-        for (const [cat, stats] of this.categoryStats) {
-            if (stats.active > 0) {
-                lines.push(`  ${cat}: ${this.formatSize(stats.active)} (${stats.count} allocations)`);
-            }
-        }
-        lines.push('');
-        lines.push('--- Top Tags ---');
-        const sortedTags = Array.from(this.tagStats.entries())
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 10);
-        for (const [tag, size] of sortedTags) {
-            lines.push(`  ${tag}: ${this.formatSize(size)}`);
-        }
-        lines.push('');
-        lines.push('--- GC Stats ---');
-        lines.push(`  Collections: ${this.stats.gcStats.collections}`);
-        lines.push(`  Avg Pause: ${this.stats.gcStats.avgPauseTime.toFixed(2)}ms`);
-        lines.push(`  Last Pause: ${this.stats.gcStats.lastPauseTime.toFixed(2)}ms`);
-        return lines.join('\n');
-    }
-    // ─── Reset ─────────────────────────────────────────────
-    reset() {
-        this.allocations.clear();
-        this.nextAllocationId = 1;
-        this.snapshots = [];
-        this.stats = {
-            totalAllocated: 0,
-            totalFreed: 0,
-            currentUsage: 0,
-            peakUsage: 0,
-            allocationCount: 0,
-            freeCount: 0,
-            activeAllocations: 0,
-            avgAllocationSize: 0,
-            gcStats: {
-                collections: 0,
-                totalPauseTime: 0,
-                lastPauseTime: 0,
-                lastCollectionTime: 0,
-                avgPauseTime: 0,
-            },
-        };
-        this.initializeCategoryStats();
-        this.tagStats.clear();
-    }
-    // ─── Configuration ─────────────────────────────────────
-    getConfig() {
-        return { ...this.config };
-    }
-    setConfig(config) {
-        this.config = { ...this.config, ...config };
-    }
-    // ─── Callbacks ─────────────────────────────────────────
-    setOnMemoryWarning(callback) {
-        this.onMemoryWarning = callback;
-    }
-    setOnMemoryCritical(callback) {
-        this.onMemoryCritical = callback;
-    }
-    setOnLeakDetected(callback) {
-        this.onLeakDetected = callback;
-    }
-    setOnGC(callback) {
-        this.onGC = callback;
-    }
+  constructor(config) {
+    this.config = { ...DEFAULT_MEMORY_CONFIG };
+    this.allocations = /* @__PURE__ */ new Map();
+    this.nextAllocationId = 1;
+    this.stats = {
+      totalAllocated: 0,
+      totalFreed: 0,
+      currentUsage: 0,
+      peakUsage: 0,
+      allocationCount: 0,
+      freeCount: 0,
+      activeAllocations: 0,
+      avgAllocationSize: 0,
+      gcStats: {
+        collections: 0,
+        totalPauseTime: 0,
+        lastPauseTime: 0,
+        lastCollectionTime: 0,
+        avgPauseTime: 0
+      }
+    };
+    this.categoryStats = /* @__PURE__ */ new Map();
+    this.tagStats = /* @__PURE__ */ new Map();
+    this.snapshots = [];
+    this.leakDetectionTimer = null;
+    if (config) {
+      this.config = { ...this.config, ...config };
+    }
+    this.initializeCategoryStats();
+  }
+  initializeCategoryStats() {
+    const categories = [
+      "texture",
+      "mesh",
+      "audio",
+      "buffer",
+      "object",
+      "array",
+      "string",
+      "component",
+      "entity",
+      "system",
+      "asset",
+      "other"
+    ];
+    for (const cat of categories) {
+      this.categoryStats.set(cat, {
+        allocated: 0,
+        freed: 0,
+        active: 0,
+        count: 0,
+        peak: 0
+      });
+    }
+  }
+  // ─── Allocation Tracking ───────────────────────────────
+  /**
+   * Track a memory allocation
+   */
+  alloc(size, category, tag = "default") {
+    if (!this.config.trackAllocations) {
+      return 0;
+    }
+    const id = this.nextAllocationId++;
+    const record = {
+      id,
+      category,
+      size,
+      tag,
+      timestamp: Date.now(),
+      freed: false
+    };
+    if (this.config.trackStacks) {
+      record.stack = this.captureStack();
+    }
+    this.allocations.set(id, record);
+    this.stats.totalAllocated += size;
+    this.stats.currentUsage += size;
+    this.stats.allocationCount++;
+    this.stats.activeAllocations++;
+    this.stats.peakUsage = Math.max(this.stats.peakUsage, this.stats.currentUsage);
+    this.stats.avgAllocationSize = this.stats.totalAllocated / this.stats.allocationCount;
+    const catStats = this.categoryStats.get(category);
+    catStats.allocated += size;
+    catStats.active += size;
+    catStats.count++;
+    catStats.peak = Math.max(catStats.peak, catStats.active);
+    this.tagStats.set(tag, (this.tagStats.get(tag) ?? 0) + size);
+    this.checkBudgets(category);
+    return id;
+  }
+  /**
+   * Track memory deallocation
+   */
+  free(id) {
+    const record = this.allocations.get(id);
+    if (!record || record.freed) {
+      return false;
+    }
+    record.freed = true;
+    record.freedAt = Date.now();
+    this.stats.totalFreed += record.size;
+    this.stats.currentUsage -= record.size;
+    this.stats.freeCount++;
+    this.stats.activeAllocations--;
+    const catStats = this.categoryStats.get(record.category);
+    catStats.freed += record.size;
+    catStats.active -= record.size;
+    const tagSize = this.tagStats.get(record.tag) ?? 0;
+    this.tagStats.set(record.tag, Math.max(0, tagSize - record.size));
+    return true;
+  }
+  /**
+   * Track a resize operation
+   */
+  realloc(id, newSize) {
+    const record = this.allocations.get(id);
+    if (!record || record.freed) {
+      return false;
+    }
+    const sizeDiff = newSize - record.size;
+    if (sizeDiff > 0) {
+      this.stats.totalAllocated += sizeDiff;
+    } else {
+      this.stats.totalFreed += Math.abs(sizeDiff);
+    }
+    this.stats.currentUsage += sizeDiff;
+    this.stats.peakUsage = Math.max(this.stats.peakUsage, this.stats.currentUsage);
+    const catStats = this.categoryStats.get(record.category);
+    if (sizeDiff > 0) {
+      catStats.allocated += sizeDiff;
+    } else {
+      catStats.freed += Math.abs(sizeDiff);
+    }
+    catStats.active += sizeDiff;
+    catStats.peak = Math.max(catStats.peak, catStats.active);
+    const tagSize = this.tagStats.get(record.tag) ?? 0;
+    this.tagStats.set(record.tag, tagSize + sizeDiff);
+    record.size = newSize;
+    this.checkBudgets(record.category);
+    return true;
+  }
+  captureStack() {
+    const stack = new Error().stack ?? "";
+    const lines = stack.split("\n").slice(3, 3 + this.config.stackDepth);
+    return lines.join("\n");
+  }
+  // ─── Budget Checking ───────────────────────────────────
+  checkBudgets(category) {
+    const budgets = this.config.budgets;
+    const totalUsage = this.stats.currentUsage / budgets.total;
+    if (totalUsage >= budgets.criticalThreshold) {
+      this.onMemoryCritical?.(this.stats.currentUsage, budgets.total);
+    } else if (totalUsage >= budgets.warnThreshold) {
+      this.onMemoryWarning?.(this.stats.currentUsage, budgets.total);
+    }
+    if (category && budgets.categories[category]) {
+      const catBudget = budgets.categories[category];
+      const catStats = this.categoryStats.get(category);
+      const catUsage = catStats.active / catBudget;
+      if (catUsage >= budgets.warnThreshold) {
+        this.onMemoryWarning?.(catStats.active, catBudget, category);
+      }
+    }
+  }
+  // ─── Leak Detection ────────────────────────────────────
+  startLeakDetection() {
+    if (this.leakDetectionTimer) {
+      return;
+    }
+    this.leakDetectionTimer = setInterval(() => {
+      const report = this.detectLeaks();
+      if (report.suspectedLeaks.length > 0) {
+        this.onLeakDetected?.(report);
+      }
+    }, this.config.leakDetectionInterval);
+  }
+  stopLeakDetection() {
+    if (this.leakDetectionTimer) {
+      clearInterval(this.leakDetectionTimer);
+      this.leakDetectionTimer = null;
+    }
+  }
+  detectLeaks() {
+    const now = Date.now();
+    const suspectedLeaks = [];
+    let totalLeakedSize = 0;
+    for (const record of this.allocations.values()) {
+      if (record.freed) {
+        continue;
+      }
+      const age = now - record.timestamp;
+      if (age > this.config.leakAgeThreshold) {
+        suspectedLeaks.push({
+          allocation: { ...record },
+          age,
+          reason: `Allocation held for ${Math.round(age / 1e3)}s without release`
+        });
+        totalLeakedSize += record.size;
+      }
+    }
+    suspectedLeaks.sort((a, b) => b.allocation.size - a.allocation.size);
+    return {
+      suspectedLeaks,
+      totalLeakedSize,
+      reportedAt: now
+    };
+  }
+  // ─── Snapshots ─────────────────────────────────────────
+  takeSnapshot(id = `snapshot_${Date.now()}`) {
+    const snapshot = {
+      id,
+      timestamp: Date.now(),
+      totalAllocated: this.stats.totalAllocated,
+      totalFreed: this.stats.totalFreed,
+      activeAllocations: this.stats.activeAllocations,
+      byCategory: new Map(this.categoryStats),
+      byTag: new Map(this.tagStats),
+      largestAllocations: this.getLargestAllocations(10)
+    };
+    this.snapshots.push(snapshot);
+    while (this.snapshots.length > this.config.snapshotRetention) {
+      this.snapshots.shift();
+    }
+    return snapshot;
+  }
+  getSnapshots() {
+    return [...this.snapshots];
+  }
+  compareSnapshots(snapshotA, snapshotB) {
+    const a = this.snapshots.find((s) => s.id === snapshotA);
+    const b = this.snapshots.find((s) => s.id === snapshotB);
+    if (!a || !b) {
+      return null;
+    }
+    const categoryDiffs = /* @__PURE__ */ new Map();
+    for (const [cat, statsA] of a.byCategory) {
+      const statsB = b.byCategory.get(cat);
+      if (statsB) {
+        categoryDiffs.set(cat, statsB.active - statsA.active);
+      }
+    }
+    const tagDiffs = /* @__PURE__ */ new Map();
+    const allTags = /* @__PURE__ */ new Set([...a.byTag.keys(), ...b.byTag.keys()]);
+    for (const tag of allTags) {
+      const sizeA = a.byTag.get(tag) ?? 0;
+      const sizeB = b.byTag.get(tag) ?? 0;
+      tagDiffs.set(tag, sizeB - sizeA);
+    }
+    return {
+      allocationDiff: b.totalAllocated - a.totalAllocated,
+      freedDiff: b.totalFreed - a.totalFreed,
+      categoryDiffs,
+      tagDiffs
+    };
+  }
+  // ─── GC Monitoring ─────────────────────────────────────
+  recordGC(pauseTime) {
+    const gcStats = this.stats.gcStats;
+    gcStats.collections++;
+    gcStats.totalPauseTime += pauseTime;
+    gcStats.lastPauseTime = pauseTime;
+    gcStats.lastCollectionTime = Date.now();
+    gcStats.avgPauseTime = gcStats.totalPauseTime / gcStats.collections;
+    this.onGC?.(gcStats);
+  }
+  // ─── Statistics ────────────────────────────────────────
+  getStats() {
+    return { ...this.stats };
+  }
+  getCategoryStats(category) {
+    return this.categoryStats.get(category);
+  }
+  getAllCategoryStats() {
+    return new Map(this.categoryStats);
+  }
+  getTagStats() {
+    return new Map(this.tagStats);
+  }
+  getLargestAllocations(count = 10) {
+    return Array.from(this.allocations.values()).filter((r) => !r.freed).sort((a, b) => b.size - a.size).slice(0, count).map((r) => ({ ...r }));
+  }
+  getAllocationsByCategory(category) {
+    return Array.from(this.allocations.values()).filter((r) => !r.freed && r.category === category).map((r) => ({ ...r }));
+  }
+  getAllocationsByTag(tag) {
+    return Array.from(this.allocations.values()).filter((r) => !r.freed && r.tag === tag).map((r) => ({ ...r }));
+  }
+  // ─── Utilities ─────────────────────────────────────────
+  formatSize(bytes) {
+    if (bytes < 1024) {
+      return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+      return `${(bytes / 1024).toFixed(2)} KB`;
+    }
+    if (bytes < 1024 * 1024 * 1024) {
+      return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+    }
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+  }
+  generateReport() {
+    const lines = [];
+    lines.push("=== Memory Report ===");
+    lines.push(`Current Usage: ${this.formatSize(this.stats.currentUsage)}`);
+    lines.push(`Peak Usage: ${this.formatSize(this.stats.peakUsage)}`);
+    lines.push(`Total Allocated: ${this.formatSize(this.stats.totalAllocated)}`);
+    lines.push(`Total Freed: ${this.formatSize(this.stats.totalFreed)}`);
+    lines.push(`Active Allocations: ${this.stats.activeAllocations}`);
+    lines.push("");
+    lines.push("--- By Category ---");
+    for (const [cat, stats] of this.categoryStats) {
+      if (stats.active > 0) {
+        lines.push(`  ${cat}: ${this.formatSize(stats.active)} (${stats.count} allocations)`);
+      }
+    }
+    lines.push("");
+    lines.push("--- Top Tags ---");
+    const sortedTags = Array.from(this.tagStats.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10);
+    for (const [tag, size] of sortedTags) {
+      lines.push(`  ${tag}: ${this.formatSize(size)}`);
+    }
+    lines.push("");
+    lines.push("--- GC Stats ---");
+    lines.push(`  Collections: ${this.stats.gcStats.collections}`);
+    lines.push(`  Avg Pause: ${this.stats.gcStats.avgPauseTime.toFixed(2)}ms`);
+    lines.push(`  Last Pause: ${this.stats.gcStats.lastPauseTime.toFixed(2)}ms`);
+    return lines.join("\n");
+  }
+  // ─── Reset ─────────────────────────────────────────────
+  reset() {
+    this.allocations.clear();
+    this.nextAllocationId = 1;
+    this.snapshots = [];
+    this.stats = {
+      totalAllocated: 0,
+      totalFreed: 0,
+      currentUsage: 0,
+      peakUsage: 0,
+      allocationCount: 0,
+      freeCount: 0,
+      activeAllocations: 0,
+      avgAllocationSize: 0,
+      gcStats: {
+        collections: 0,
+        totalPauseTime: 0,
+        lastPauseTime: 0,
+        lastCollectionTime: 0,
+        avgPauseTime: 0
+      }
+    };
+    this.initializeCategoryStats();
+    this.tagStats.clear();
+  }
+  // ─── Configuration ─────────────────────────────────────
+  getConfig() {
+    return { ...this.config };
+  }
+  setConfig(config) {
+    this.config = { ...this.config, ...config };
+  }
+  // ─── Callbacks ─────────────────────────────────────────
+  setOnMemoryWarning(callback) {
+    this.onMemoryWarning = callback;
+  }
+  setOnMemoryCritical(callback) {
+    this.onMemoryCritical = callback;
+  }
+  setOnLeakDetected(callback) {
+    this.onLeakDetected = callback;
+  }
+  setOnGC(callback) {
+    this.onGC = callback;
+  }
 }
-// ============================================================
-// Tracked Allocator
-// ============================================================
 class TrackedAllocator {
-    constructor(tracker, defaultCategory = 'other', defaultTag = 'default') {
-        this.tracker = tracker;
-        this.defaultCategory = defaultCategory;
-        this.defaultTag = defaultTag;
-    }
-    allocArrayBuffer(size, tag) {
-        const id = this.tracker.alloc(size, 'buffer', tag ?? this.defaultTag);
-        return { buffer: new ArrayBuffer(size), id };
-    }
-    allocTypedArray(ArrayType, length, tag) {
-        const array = new ArrayType(length);
-        const id = this.tracker.alloc(array.byteLength, 'array', tag ?? this.defaultTag);
-        return { array, id };
-    }
-    free(id) {
-        this.tracker.free(id);
-    }
+  constructor(tracker, defaultCategory = "other", defaultTag = "default") {
+    this.tracker = tracker;
+    this.defaultCategory = defaultCategory;
+    this.defaultTag = defaultTag;
+  }
+  allocArrayBuffer(size, tag) {
+    const id = this.tracker.alloc(size, "buffer", tag ?? this.defaultTag);
+    return { buffer: new ArrayBuffer(size), id };
+  }
+  allocTypedArray(ArrayType, length, tag) {
+    const array = new ArrayType(length);
+    const id = this.tracker.alloc(array.byteLength, "array", tag ?? this.defaultTag);
+    return { array, id };
+  }
+  free(id) {
+    this.tracker.free(id);
+  }
 }
-// ============================================================
-// Factory Functions
-// ============================================================
 function createMemoryTracker(config) {
-    return new MemoryTracker(config);
+  return new MemoryTracker(config);
 }
 function createTrackedAllocator(tracker, category, tag) {
-    return new TrackedAllocator(tracker, category, tag);
+  return new TrackedAllocator(tracker, category, tag);
 }
-
 exports.DEFAULT_MEMORY_CONFIG = DEFAULT_MEMORY_CONFIG;
 exports.MemoryTracker = MemoryTracker;
 exports.TrackedAllocator = TrackedAllocator;