scope-state 0.1.0

package/dist/index.esm.js

@@ -0,0 +1,2023 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+import localforage from 'localforage';
+import * as memoryDriver from 'localforage-driver-memory';
+
+// Default configurations
+const defaultProxyConfig = {
+    enabled: true,
+    maxDepth: 5,
+    selectiveProxying: false,
+    trackPathUsage: true,
+    lazyProxyDeepObjects: false,
+    preProxyPaths: [],
+    maxPathLength: 20,
+    smartArrayTracking: true,
+    nonBlockingProxyCreation: true,
+    batchSize: 1,
+    prioritizeUIObjects: true,
+    maxQueueSize: 1000,
+    memoryLimit: false,
+    memoryThreshold: 1,
+    targetMemoryUsage: 3000,
+    proxyEvictionStrategy: 'lru',
+    disableProxyingUnderPressure: false,
+    maxProxyCacheSize: 5000,
+    ultraSelectiveProxying: false,
+    proxySelectorPaths: true,
+    forceMemoryCheck: true,
+    aggressiveMemoryManagement: false,
+    priorityPaths: [],
+};
+const defaultMonitoringConfig = {
+    enabled: true,
+    verboseLogging: false,
+    logSubscriptions: false,
+    logProxyCreation: false,
+    logStateChanges: false,
+    logPersistence: false,
+    logTimings: false,
+    autoLeakDetection: false,
+    leakDetectionInterval: 30000,
+    leakAlertThreshold: 0,
+    leakScanMinimumRenderCycles: 3,
+};
+const defaultPersistenceConfig = {
+    enabled: true,
+    paths: [],
+    blacklist: [],
+    batchDelay: 300,
+};
+// Current active configurations (will be modified by configure())
+let proxyConfig = { ...defaultProxyConfig };
+let monitoringConfig = { ...defaultMonitoringConfig };
+let persistenceConfig = { ...defaultPersistenceConfig };
+// Note: The main configure function is now in src/index.ts to avoid circular dependencies
+// These configuration objects are still exported for internal use
+/**
+ * Get current configuration
+ */
+function getConfig() {
+    return {
+        proxy: { ...proxyConfig },
+        monitoring: { ...monitoringConfig },
+        persistence: { ...persistenceConfig },
+    };
+}
+/**
+ * Reset all configuration to defaults
+ */
+function resetConfig() {
+    proxyConfig = { ...defaultProxyConfig };
+    monitoringConfig = { ...defaultMonitoringConfig };
+    persistenceConfig = { ...defaultPersistenceConfig };
+}
+/**
+ * Quick presets for common use cases
+ */
+const presets = {
+    /**
+     * Development preset: Enhanced debugging and monitoring
+     */
+    development: () => ({
+        monitoring: {
+            enabled: true,
+            verboseLogging: true,
+            logSubscriptions: true,
+            logStateChanges: true,
+            autoLeakDetection: true,
+        },
+        proxy: {
+            maxDepth: 3,
+            smartArrayTracking: true,
+        },
+    }),
+    /**
+     * Production preset: Optimized for performance
+     */
+    production: () => ({
+        monitoring: {
+            enabled: false,
+            verboseLogging: false,
+            logSubscriptions: false,
+            logStateChanges: false,
+            autoLeakDetection: false,
+        },
+        proxy: {
+            maxDepth: 6,
+            ultraSelectiveProxying: false,
+            aggressiveMemoryManagement: false,
+        },
+    }),
+    /**
+     * Memory-constrained preset: Minimal memory usage
+     */
+    minimal: () => ({
+        monitoring: {
+            enabled: false,
+        },
+        proxy: {
+            maxDepth: 1,
+            ultraSelectiveProxying: true,
+            aggressiveMemoryManagement: true,
+            maxProxyCacheSize: 1000,
+            maxQueueSize: 100,
+        },
+        persistence: {
+            enabled: false,
+        },
+    }),
+    /**
+     * Full-featured preset: All features enabled
+     */
+    full: () => ({
+        monitoring: {
+            enabled: true,
+            verboseLogging: true,
+            autoLeakDetection: true,
+        },
+        proxy: {
+            maxDepth: 5,
+            selectiveProxying: false,
+        },
+        persistence: {
+            enabled: true,
+        },
+    }),
+};
+
+// Path-specific listeners
+const pathListeners = new Map();
+// Statistics for monitoring
+let monitoringStats = {
+    proxyCount: 0,
+    totalSubscriptionsCreated: 0,
+    totalSubscriptionsRemoved: 0,
+    activeSubscriptions: 0,
+    pathSubscriptionCounts: {},
+    timings: {
+        lastNotifyTime: 0,
+        lastPersistTime: 0,
+        averageNotifyTime: 0,
+        averagePersistTime: 0,
+        notifyTimeTotal: 0,
+        persistTimeTotal: 0,
+        notifyCount: 0,
+        persistCount: 0,
+    },
+    leakDetection: {
+        lastCheckTime: 0,
+        totalChecks: 0,
+        leaksDetected: 0,
+        renderCyclesSinceCheck: 0,
+        isLeakDetectionRunning: false,
+        leakDetectionTimer: null,
+    }
+};
+/**
+ * Subscribe to changes on a specific path
+ */
+function subscribe(path, listener) {
+    var _a;
+    if (!pathListeners.has(path)) {
+        pathListeners.set(path, new Set());
+    }
+    (_a = pathListeners.get(path)) === null || _a === void 0 ? void 0 : _a.add(listener);
+    logSubscriptionAdded(path);
+    // Return unsubscribe function
+    return () => {
+        var _a, _b;
+        (_a = pathListeners.get(path)) === null || _a === void 0 ? void 0 : _a.delete(listener);
+        logSubscriptionRemoved(path);
+        // Clean up empty listener sets
+        if (((_b = pathListeners.get(path)) === null || _b === void 0 ? void 0 : _b.size) === 0) {
+            pathListeners.delete(path);
+            if (monitoringConfig.enabled && monitoringConfig.logSubscriptions) {
+                console.log(`🧹 Removed empty listener set for ${path}`);
+            }
+        }
+    };
+}
+/**
+ * Notify all listeners for a given path and its parents/children
+ */
+function notifyListeners(path) {
+    if (typeof window === 'undefined')
+        return;
+    const pathKey = path.join('.');
+    let startTime = 0;
+    if (monitoringConfig.enabled && monitoringConfig.logStateChanges) {
+        startTime = logTimestamp$1(`⚡️ Notifying path: ${pathKey}`);
+    }
+    // Track render cycle for leak detection
+    if (monitoringConfig.enabled && monitoringConfig.autoLeakDetection) {
+        monitoringStats.leakDetection.renderCyclesSinceCheck++;
+    }
+    // Notify exact path listeners
+    if (pathListeners.has(pathKey)) {
+        const listeners = pathListeners.get(pathKey);
+        if (monitoringConfig.enabled && monitoringConfig.verboseLogging) {
+            console.log(`🔔 Notifying ${listeners === null || listeners === void 0 ? void 0 : listeners.size} exact listeners for ${pathKey}`);
+        }
+        listeners === null || listeners === void 0 ? void 0 : listeners.forEach(listener => listener());
+    }
+    // Special handling for array index changes - notify the array itself too
+    const lastSegment = path.length > 0 ? path[path.length - 1] : '';
+    if (lastSegment && !isNaN(Number(lastSegment))) {
+        // This is an array index update, also notify about the array
+        const arrayPath = path.slice(0, -1).join('.');
+        if (pathListeners.has(arrayPath)) {
+            const listeners = pathListeners.get(arrayPath);
+            if (monitoringConfig.enabled && monitoringConfig.verboseLogging) {
+                console.log(`🔔 Notifying ${listeners === null || listeners === void 0 ? void 0 : listeners.size} array listeners for ${arrayPath} (index change)`);
+            }
+            listeners === null || listeners === void 0 ? void 0 : listeners.forEach(listener => listener());
+        }
+    }
+    // Also notify parent paths (more granular update notifications)
+    for (let i = path.length - 1; i >= 0; i--) {
+        const parentPath = path.slice(0, i).join('.');
+        if (pathListeners.has(parentPath)) {
+            const listeners = pathListeners.get(parentPath);
+            if (monitoringConfig.enabled && monitoringConfig.verboseLogging) {
+                console.log(`🔔 Notifying ${listeners === null || listeners === void 0 ? void 0 : listeners.size} parent listeners for ${parentPath}`);
+            }
+            listeners === null || listeners === void 0 ? void 0 : listeners.forEach(listener => listener());
+        }
+    }
+    // Notify child paths (if an object was completely replaced)
+    const prefix = pathKey + '.';
+    let childListenerCount = 0;
+    pathListeners.forEach((listeners, key) => {
+        if (key.startsWith(prefix)) {
+            childListenerCount += listeners.size;
+            listeners.forEach(listener => listener());
+        }
+    });
+    if (monitoringConfig.enabled && monitoringConfig.verboseLogging && childListenerCount > 0) {
+        console.log(`🔔 Notified ${childListenerCount} child listeners for paths starting with ${prefix}`);
+    }
+    if (monitoringConfig.enabled && monitoringConfig.logStateChanges && startTime > 0) {
+        const duration = logTimingEnd$1('Notification cycle', startTime);
+        updateTimingStat('notify', duration);
+    }
+}
+// Logging helper functions
+function logTimestamp$1(action) {
+    if (!monitoringConfig.enabled || !monitoringConfig.logTimings)
+        return 0;
+    const now = performance.now();
+    console.log(`⏱️ [${now.toFixed(2)}ms] ${action}`);
+    return now;
+}
+function logTimingEnd$1(action, startTime) {
+    if (!monitoringConfig.enabled || !monitoringConfig.logTimings)
+        return 0;
+    const now = performance.now();
+    const duration = now - startTime;
+    console.log(`⏱️ [${now.toFixed(2)}ms] ${action} completed in ${duration.toFixed(2)}ms`);
+    return duration;
+}
+function updateTimingStat(type, duration) {
+    if (!monitoringConfig.enabled)
+        return;
+    if (type === 'notify') {
+        monitoringStats.timings.lastNotifyTime = duration;
+        monitoringStats.timings.notifyTimeTotal += duration;
+        monitoringStats.timings.notifyCount++;
+        monitoringStats.timings.averageNotifyTime =
+            monitoringStats.timings.notifyTimeTotal / monitoringStats.timings.notifyCount;
+    }
+    else {
+        monitoringStats.timings.lastPersistTime = duration;
+        monitoringStats.timings.persistTimeTotal += duration;
+        monitoringStats.timings.persistCount++;
+        monitoringStats.timings.averagePersistTime =
+            monitoringStats.timings.persistTimeTotal / monitoringStats.timings.persistCount;
+    }
+}
+function logSubscriptionAdded(path) {
+    if (!monitoringConfig.enabled || !monitoringConfig.logSubscriptions)
+        return;
+    monitoringStats.totalSubscriptionsCreated++;
+    monitoringStats.activeSubscriptions++;
+    monitoringStats.pathSubscriptionCounts[path] = (monitoringStats.pathSubscriptionCounts[path] || 0) + 1;
+    console.log(`📈 Subscription ADDED to ${path}. Total: ${monitoringStats.activeSubscriptions}, Path count: ${monitoringStats.pathSubscriptionCounts[path]}`);
+}
+function logSubscriptionRemoved(path) {
+    var _a;
+    if (!monitoringConfig.enabled || !monitoringConfig.logSubscriptions)
+        return;
+    monitoringStats.totalSubscriptionsRemoved++;
+    monitoringStats.activeSubscriptions--;
+    monitoringStats.pathSubscriptionCounts[path] = (monitoringStats.pathSubscriptionCounts[path] || 0) - 1;
+    console.log(`📉 Subscription REMOVED from ${path}. Total: ${monitoringStats.activeSubscriptions}, Path count: ${monitoringStats.pathSubscriptionCounts[path]}`);
+    // Alert if a path has no subscribers but still exists in the map
+    if (monitoringStats.pathSubscriptionCounts[path] <= 0) {
+        const actualListeners = ((_a = pathListeners.get(path)) === null || _a === void 0 ? void 0 : _a.size) || 0;
+        if (actualListeners > 0) {
+            console.warn(`⚠️ Path ${path} shows ${actualListeners} listeners but tracking shows ${monitoringStats.pathSubscriptionCounts[path]}`);
+        }
+    }
+}
+
+// Track proxy to path mapping for type-safe activation
+const proxyPathMap = new WeakMap();
+// Store a deep clone of the initial store state for use with $reset
+let initialStoreState$1 = {};
+// Path usage tracking
+const pathUsageStats = {
+    accessedPaths: new Set(),
+    modifiedPaths: new Set(),
+    subscribedPaths: new Set(),
+};
+// Selector paths for ultra-selective proxying
+const selectorPaths = new Set();
+// Proxy cache using WeakMap for garbage collection
+let proxyCache = new WeakMap();
+// Proxy cache statistics
+const proxyCacheStats = {
+    cacheHits: 0,
+    cacheMisses: 0,
+    totalProxiesCreated: 0,
+    activeCachedProxies: 0
+};
+// LRU tracking for proxy cache
+const proxyCacheLRU = {
+    keys: [],
+    timestamp: [],
+    maxSize: proxyConfig.maxProxyCacheSize,
+    add(key, proxy) {
+        if (key && typeof key === 'object') {
+            const index = this.keys.findIndex(k => k === key);
+            if (index !== -1) {
+                this.timestamp[index] = Date.now();
+            }
+            else {
+                this.keys.push(key);
+                this.timestamp.push(Date.now());
+                if (this.keys.length > this.maxSize) {
+                    this.evictOldest();
+                }
+            }
+        }
+    },
+    touch(key) {
+        const index = this.keys.findIndex(k => k === key);
+        if (index !== -1) {
+            this.timestamp[index] = Date.now();
+        }
+    },
+    evictOldest() {
+        if (this.keys.length === 0)
+            return;
+        let oldestIndex = 0;
+        let oldestTime = this.timestamp[0];
+        for (let i = 1; i < this.timestamp.length; i++) {
+            if (this.timestamp[i] < oldestTime) {
+                oldestTime = this.timestamp[i];
+                oldestIndex = i;
+            }
+        }
+        const oldestKey = this.keys[oldestIndex];
+        if (oldestKey && proxyCache.has(oldestKey)) {
+            proxyCache.delete(oldestKey);
+            proxyCacheStats.activeCachedProxies--;
+        }
+        this.keys.splice(oldestIndex, 1);
+        this.timestamp.splice(oldestIndex, 1);
+    },
+    evictPercentage(percent) {
+        const count = Math.ceil(this.keys.length * percent);
+        if (count <= 0)
+            return 0;
+        const indices = Array.from({ length: this.keys.length }, (_, i) => i)
+            .sort((a, b) => this.timestamp[a] - this.timestamp[b]);
+        let evicted = 0;
+        for (let i = 0; i < count && i < indices.length; i++) {
+            const key = this.keys[indices[i]];
+            if (key && proxyCache.has(key)) {
+                proxyCache.delete(key);
+                evicted++;
+            }
+        }
+        const newKeys = [];
+        const newTimestamps = [];
+        for (let i = count; i < indices.length; i++) {
+            const idx = indices[i];
+            newKeys.push(this.keys[idx]);
+            newTimestamps.push(this.timestamp[idx]);
+        }
+        this.keys = newKeys;
+        this.timestamp = newTimestamps;
+        proxyCacheStats.activeCachedProxies -= evicted;
+        return evicted;
+    },
+    size() {
+        return this.keys.length;
+    },
+    clear() {
+        this.keys = [];
+        this.timestamp = [];
+    }
+};
+// Memory pressure detection
+const memoryPressure = {
+    isUnderPressure: false,
+    lastCheckTime: 0,
+    checkInterval: 5000,
+    highUsageCount: 0,
+    check() {
+        const now = Date.now();
+        if (!proxyConfig.forceMemoryCheck && now - this.lastCheckTime < this.checkInterval) {
+            return this.isUnderPressure;
+        }
+        this.lastCheckTime = now;
+        try {
+            const estimatedUsageMB = this.estimateMemoryUsage();
+            const thresholdMB = proxyConfig.targetMemoryUsage * proxyConfig.memoryThreshold;
+            const wasUnderPressure = this.isUnderPressure;
+            this.isUnderPressure = estimatedUsageMB > thresholdMB;
+            if (proxyConfig.aggressiveMemoryManagement && estimatedUsageMB > thresholdMB * 0.8) {
+                this.highUsageCount++;
+                if (this.highUsageCount > 2) {
+                    this.isUnderPressure = true;
+                }
+            }
+            else {
+                this.highUsageCount = 0;
+            }
+            if (this.isUnderPressure !== wasUnderPressure && monitoringConfig.enabled) {
+                if (this.isUnderPressure) {
+                    console.warn(`⚠️ High memory pressure detected: ${estimatedUsageMB.toFixed(1)}MB > ${thresholdMB.toFixed(1)}MB threshold`);
+                }
+                else {
+                    console.log(`✅ Memory pressure relieved: ${estimatedUsageMB.toFixed(1)}MB < ${thresholdMB.toFixed(1)}MB threshold`);
+                }
+            }
+        }
+        catch (e) {
+            console.error('Error checking memory pressure:', e);
+        }
+        return this.isUnderPressure;
+    },
+    estimateMemoryUsage() {
+        const proxyCacheSize = proxyCacheLRU.size() * 2;
+        const pathStatsSize = (pathUsageStats.accessedPaths.size +
+            pathUsageStats.modifiedPaths.size +
+            pathUsageStats.subscribedPaths.size) * 0.2;
+        const baseMB = 400;
+        return baseMB + proxyCacheSize + pathStatsSize;
+    }
+};
+/**
+ * Set the initial store state for reset functionality
+ */
+function setInitialStoreState(state) {
+    initialStoreState$1 = JSON.parse(JSON.stringify(state));
+}
+/**
+ * Check if a path is high priority
+ */
+function isHighPriorityPath(path) {
+    if (!proxyConfig.prioritizeUIObjects)
+        return false;
+    const pathStr = path.join('.');
+    return proxyConfig.priorityPaths.some(p => pathStr === p || pathStr.startsWith(`${p}.`));
+}
+/**
+ * Create an advanced proxy with all the features from the original code
+ */
+function createAdvancedProxy(target, path = [], depth = 0) {
+    if (target === null || typeof target !== 'object') {
+        return target;
+    }
+    if (!proxyConfig.enabled) {
+        return target;
+    }
+    const pathKey = path.join('.');
+    // Check memory pressure
+    const isUnderPressure = memoryPressure.check();
+    if (isUnderPressure && proxyConfig.disableProxyingUnderPressure && depth > 0 && !isHighPriorityPath(path)) {
+        return target;
+    }
+    // Ultra-selective proxying
+    if (proxyConfig.ultraSelectiveProxying && depth > 0) {
+        if (!selectorPaths.has(pathKey) &&
+            !isHighPriorityPath(path) &&
+            !proxyConfig.preProxyPaths.some(p => pathKey === p || pathKey.startsWith(`${p}.`))) {
+            return target;
+        }
+    }
+    // Check for cached proxy
+    if (proxyCache.has(target)) {
+        proxyCacheStats.cacheHits++;
+        proxyCacheLRU.touch(target);
+        return proxyCache.get(target);
+    }
+    // Check depth limit
+    if (proxyConfig.selectiveProxying && depth > proxyConfig.maxDepth) {
+        return target;
+    }
+    // Create new proxy
+    proxyCacheStats.cacheMisses++;
+    proxyCacheStats.totalProxiesCreated++;
+    proxyCacheStats.activeCachedProxies++;
+    // If target is not extensible, clone it
+    if (!Object.isExtensible(target)) {
+        target = Array.isArray(target) ? [...target] : { ...target };
+    }
+    // Add custom methods for objects
+    if (typeof target === 'object' && !Array.isArray(target)) {
+        addObjectMethods(target, path);
+    }
+    // Add custom methods for arrays
+    if (Array.isArray(target)) {
+        addArrayMethods(target, path);
+    }
+    const proxy = new Proxy(target, {
+        get(obj, prop, receiver) {
+            if (typeof prop === 'symbol') {
+                return Reflect.get(obj, prop, receiver);
+            }
+            const currentPropPath = [...path, prop.toString()];
+            const propPathKey = currentPropPath.join('.');
+            // Track path access during dependency tracking
+            if (proxyConfig.trackPathUsage && propPathKey.split('.').length <= proxyConfig.maxPathLength) {
+                pathUsageStats.accessedPaths.add(propPathKey);
+                // Also add to selector paths for ultra-selective proxying
+                selectorPaths.add(propPathKey);
+            }
+            // Track path access for dependency tracking (inline to avoid circular dependency)
+            if (typeof require !== 'undefined') {
+                try {
+                    const { trackPathAccess } = require('./tracking');
+                    trackPathAccess(currentPropPath);
+                }
+                catch (e) {
+                    // Skip tracking if module not available
+                }
+            }
+            const value = obj[prop];
+            // For objects, create proxies for nested values
+            if (value && typeof value === 'object' && path.length < proxyConfig.maxDepth) {
+                const shouldProxy = !proxyConfig.lazyProxyDeepObjects ||
+                    pathUsageStats.accessedPaths.has(propPathKey) ||
+                    pathUsageStats.modifiedPaths.has(propPathKey) ||
+                    pathUsageStats.subscribedPaths.has(propPathKey) ||
+                    proxyConfig.preProxyPaths.some(p => propPathKey === p || propPathKey.startsWith(`${p}.`));
+                if (shouldProxy) {
+                    return createAdvancedProxy(value, currentPropPath, depth + 1);
+                }
+            }
+            return value;
+        },
+        set(obj, prop, value, receiver) {
+            if (typeof prop === 'symbol') {
+                return Reflect.set(obj, prop, value, receiver);
+            }
+            const propPath = [...path, prop.toString()];
+            const propPathKey = propPath.join('.');
+            // Track modification
+            if (proxyConfig.trackPathUsage) {
+                pathUsageStats.modifiedPaths.add(propPathKey);
+            }
+            // Handle object assignment with proxying
+            if (value && typeof value === 'object' && !proxyCache.has(value)) {
+                const newPath = [...path, prop.toString()];
+                const proxiedValue = createAdvancedProxy(value, newPath, 0);
+                const result = Reflect.set(obj, prop, proxiedValue, receiver);
+                // Notify the specific property path and all parent/child paths
+                notifyListeners(propPath);
+                return result;
+            }
+            const result = Reflect.set(obj, prop, value, receiver);
+            // Notify the specific property path (this will also notify parent/child paths)
+            notifyListeners(propPath);
+            return result;
+        },
+        deleteProperty(obj, prop) {
+            if (typeof prop === 'string') {
+                const propPath = [...path, prop];
+                const propPathKey = propPath.join('.');
+                if (proxyConfig.trackPathUsage) {
+                    pathUsageStats.modifiedPaths.add(propPathKey);
+                }
+                const result = Reflect.deleteProperty(obj, prop);
+                if (result) {
+                    // Notify the deleted property path (this will also notify parent/child paths)
+                    notifyListeners(propPath);
+                }
+                return result;
+            }
+            return Reflect.deleteProperty(obj, prop);
+        }
+    });
+    // Cache the proxy
+    proxyCache.set(target, proxy);
+    proxyCacheLRU.add(target, proxy);
+    // Track the path for this proxy
+    proxyPathMap.set(proxy, [...path]);
+    return proxy;
+}
+/**
+ * Add custom methods to object targets
+ */
+function addObjectMethods(target, path) {
+    const methodsToDefine = {};
+    if (!('$merge' in target)) {
+        methodsToDefine.$merge = {
+            value: function (newProps) {
+                const currentPath = proxyPathMap.get(this) || path;
+                Object.keys(newProps).forEach(key => {
+                    if (proxyConfig.trackPathUsage) {
+                        const propPath = [...currentPath, key].join('.');
+                        pathUsageStats.modifiedPaths.add(propPath);
+                    }
+                    const newValue = newProps[key];
+                    if (newValue && typeof newValue === 'object' && !proxyCache.has(newValue)) {
+                        const newPath = [...currentPath, key];
+                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                        Reflect.set(this, key, createAdvancedProxy(newValue, newPath, 0), this);
+                    }
+                    else {
+                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                        Reflect.set(this, key, newValue, this);
+                    }
+                });
+                return this;
+            },
+            enumerable: false
+        };
+    }
+    if (!('$set' in target)) {
+        methodsToDefine.$set = {
+            value: function (newProps) {
+                const currentPath = proxyPathMap.get(this) || path;
+                // Clear existing properties
+                Object.keys(this).forEach(key => {
+                    if (typeof this[key] !== 'function') {
+                        Reflect.deleteProperty(this, key);
+                    }
+                });
+                // Set new properties
+                Object.keys(newProps || {}).forEach(key => {
+                    if (proxyConfig.trackPathUsage) {
+                        const propPath = [...currentPath, key].join('.');
+                        pathUsageStats.modifiedPaths.add(propPath);
+                    }
+                    const newValue = newProps[key];
+                    if (newValue && typeof newValue === 'object' && !proxyCache.has(newValue)) {
+                        const newPath = [...currentPath, key];
+                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                        Reflect.set(this, key, createAdvancedProxy(newValue, newPath, 0), this);
+                    }
+                    else {
+                        // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                        Reflect.set(this, key, newValue, this);
+                    }
+                });
+                return this;
+            },
+            enumerable: false
+        };
+    }
+    if (!('$delete' in target)) {
+        methodsToDefine.$delete = {
+            value: function (keys) {
+                proxyPathMap.get(this) || path;
+                const keysToDelete = Array.isArray(keys) ? keys : [keys];
+                keysToDelete.forEach(key => {
+                    // Use Reflect.deleteProperty to trigger the deleteProperty handler
+                    Reflect.deleteProperty(this, key);
+                });
+                return this;
+            },
+            enumerable: false
+        };
+    }
+    if (!('$update' in target)) {
+        methodsToDefine.$update = {
+            value: function (key, updater) {
+                const currentPath = proxyPathMap.get(this) || path;
+                if (proxyConfig.trackPathUsage && currentPath.length > 0) {
+                    const propPath = [...currentPath, key].join('.');
+                    pathUsageStats.modifiedPaths.add(propPath);
+                }
+                const currentValue = this[key];
+                let newValue = updater(currentValue);
+                if (newValue && typeof newValue === 'object' && !proxyCache.has(newValue)) {
+                    const newPath = [...currentPath, key];
+                    newValue = createAdvancedProxy(newValue, newPath, 0);
+                }
+                // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                Reflect.set(this, key, newValue, this);
+                return this;
+            },
+            enumerable: false
+        };
+    }
+    if (!('$reset' in target)) {
+        methodsToDefine.$reset = {
+            value: function () {
+                const currentPath = proxyPathMap.get(this) || path;
+                let initialValue = initialStoreState$1;
+                for (const segment of currentPath) {
+                    if (initialValue && typeof initialValue === 'object' && segment in initialValue) {
+                        initialValue = initialValue[segment];
+                    }
+                    else {
+                        initialValue = undefined;
+                        break;
+                    }
+                }
+                if (initialValue !== undefined) {
+                    // Clear existing properties
+                    Object.keys(this).forEach((key) => {
+                        if (typeof this[key] !== 'function') {
+                            Reflect.deleteProperty(this, key);
+                        }
+                    });
+                    // Set new properties
+                    if (initialValue && typeof initialValue === 'object') {
+                        Object.entries(initialValue).forEach(([key, value]) => {
+                            // Use Reflect.set with this proxy as the receiver to trigger the set handler
+                            Reflect.set(this, key, JSON.parse(JSON.stringify(value)), this);
+                        });
+                    }
+                }
+                return this;
+            },
+            enumerable: false
+        };
+    }
+    if (!('raw' in target)) {
+        methodsToDefine.raw = {
+            value: function () {
+                return JSON.parse(JSON.stringify(this));
+            },
+            enumerable: false,
+            configurable: true
+        };
+    }
+    if (Object.keys(methodsToDefine).length > 0) {
+        Object.defineProperties(target, methodsToDefine);
+    }
+}
+/**
+ * Add custom methods to array targets
+ */
+function addArrayMethods(target, path) {
+    const originalPush = target.push;
+    const originalSplice = target.splice;
+    // Override push
+    Object.defineProperty(target, 'push', {
+        value: function (...items) {
+            const currentPath = proxyPathMap.get(this) || path;
+            const processedItems = items.map(item => {
+                if (item && typeof item === 'object' && !proxyCache.has(item)) {
+                    const itemPath = [...currentPath, '_item'];
+                    return createAdvancedProxy(item, itemPath, 0);
+                }
+                return item;
+            });
+            const result = originalPush.apply(this, processedItems);
+            if (currentPath.length > 0) {
+                if (proxyConfig.trackPathUsage) {
+                    pathUsageStats.modifiedPaths.add(currentPath.join('.'));
+                }
+                notifyListeners(currentPath);
+            }
+            return result;
+        },
+        writable: true,
+        configurable: true
+    });
+    // Override splice
+    Object.defineProperty(target, 'splice', {
+        value: function (start, deleteCount, ...items) {
+            const currentPath = proxyPathMap.get(this) || path;
+            const arrayLength = this.length;
+            const processedItems = items.map((item, index) => {
+                if (item && typeof item === 'object' && !proxyCache.has(item)) {
+                    const itemPath = [...currentPath, (start + index).toString()];
+                    return createAdvancedProxy(item, itemPath, 0);
+                }
+                return item;
+            });
+            const actualDeleteCount = deleteCount === undefined ? (arrayLength - start) : deleteCount;
+            const result = originalSplice.apply(this, [start, actualDeleteCount, ...processedItems]);
+            if (currentPath.length > 0) {
+                if (proxyConfig.trackPathUsage) {
+                    pathUsageStats.modifiedPaths.add(currentPath.join('.'));
+                }
+                // Notify the array itself
+                notifyListeners(currentPath);
+                // Also notify about each index that was affected
+                for (let i = start; i < arrayLength; i++) {
+                    const indexPath = [...currentPath, i.toString()];
+                    notifyListeners(indexPath);
+                }
+            }
+            return result;
+        },
+        writable: true,
+        configurable: true
+    });
+    // Add $set method for arrays
+    if (!('$set' in target)) {
+        Object.defineProperty(target, '$set', {
+            value: function (newArray) {
+                if (!Array.isArray(newArray)) {
+                    console.error('$set on array must be called with an array');
+                    return this;
+                }
+                const currentPath = proxyPathMap.get(this) || path;
+                this.length = 0;
+                const processedItems = newArray.map((item, index) => {
+                    if (item && typeof item === 'object' && !proxyCache.has(item)) {
+                        const itemPath = [...currentPath, index.toString()];
+                        return createAdvancedProxy(item, itemPath, 0);
+                    }
+                    return item;
+                });
+                originalPush.apply(this, processedItems);
+                if (currentPath.length > 0) {
+                    if (proxyConfig.trackPathUsage) {
+                        pathUsageStats.modifiedPaths.add(currentPath.join('.'));
+                    }
+                    notifyListeners(currentPath);
+                }
+                return this;
+            },
+            enumerable: false,
+            configurable: true
+        });
+    }
+    // Add $reset method for arrays
+    if (!('$reset' in target)) {
+        Object.defineProperty(target, '$reset', {
+            value: function () {
+                const currentPath = proxyPathMap.get(this) || path;
+                let initialValue = initialStoreState$1;
+                for (const segment of currentPath) {
+                    if (initialValue && typeof initialValue === 'object' && segment in initialValue) {
+                        initialValue = initialValue[segment];
+                    }
+                    else {
+                        initialValue = [];
+                        break;
+                    }
+                }
+                if (!Array.isArray(initialValue)) {
+                    initialValue = [];
+                }
+                this.length = 0;
+                const processedItems = initialValue.map((item, index) => {
+                    if (item && typeof item === 'object' && !proxyCache.has(item)) {
+                        const itemPath = [...currentPath, index.toString()];
+                        return createAdvancedProxy(item, itemPath, 0);
+                    }
+                    return item;
+                });
+                if (processedItems.length > 0) {
+                    originalPush.apply(this, processedItems);
+                }
+                if (currentPath.length > 0) {
+                    notifyListeners(currentPath);
+                }
+                return this;
+            },
+            enumerable: false,
+            configurable: true
+        });
+    }
+    // Add raw method
+    if (!('raw' in target)) {
+        Object.defineProperty(target, 'raw', {
+            value: function () {
+                return JSON.parse(JSON.stringify(this));
+            },
+            enumerable: false,
+            configurable: true
+        });
+    }
+}
+/**
+ * Clear proxy cache
+ */
+function clearProxyCache() {
+    proxyCache = new WeakMap();
+    proxyCacheLRU.clear();
+    proxyCacheStats.cacheHits = 0;
+    proxyCacheStats.cacheMisses = 0;
+    proxyCacheStats.activeCachedProxies = 0;
+    if (monitoringConfig.enabled) {
+        console.log('🧹 Proxy cache cleared');
+    }
+}
+/**
+ * Get proxy cache statistics
+ */
+function getProxyCacheStats() {
+    return {
+        ...proxyCacheStats,
+        hitRatio: proxyCacheStats.cacheHits / (proxyCacheStats.cacheHits + proxyCacheStats.cacheMisses || 1),
+        estimatedCacheSize: proxyCacheLRU.size()
+    };
+}
+/**
+ * Optimize memory usage
+ */
+function optimizeMemoryUsage(aggressive = false) {
+    pathUsageStats.accessedPaths.clear();
+    pathUsageStats.modifiedPaths.clear();
+    const evictedCount = aggressive ?
+        proxyCacheLRU.evictPercentage(0.8) :
+        proxyCacheLRU.evictPercentage(0.4);
+    if (aggressive && typeof global.gc === 'function') {
+        try {
+            global.gc();
+            if (monitoringConfig.enabled) {
+                console.log('🧹 Forced garbage collection');
+            }
+        }
+        catch (e) {
+            console.error('Failed to force garbage collection:', e);
+        }
+    }
+    if (monitoringConfig.enabled) {
+        console.log(`🧹 Memory optimization complete. Evicted ${evictedCount} cached proxies`);
+    }
+    return {
+        proxiesEvicted: evictedCount,
+        currentMemoryEstimate: memoryPressure.estimateMemoryUsage(),
+        selectorPathsRemaining: selectorPaths.size
+    };
+}
+
+// Track the current path we're accessing during a selector function
+let currentPath = [];
+/**
+ * Track dependencies during selector execution - tracks individual path segments
+ */
+function trackDependencies(selector) {
+    currentPath = [];
+    // Execute selector to track dependencies
+    const value = selector();
+    // Clean up and return individual path segments (not full paths)
+    const cleanedPaths = [...currentPath].filter(segment => {
+        // Filter out segments that would create overly long paths
+        return segment && segment.length < 100; // Basic length check for individual segments
+    });
+    currentPath = [];
+    return { value, paths: cleanedPaths };
+}
+
+/**
+ * Hook to subscribe to the global store and re-render when specific data changes.
+ *
+ * The hook tracks which store paths your selector function accesses and only
+ * re-renders the component when those specific paths change. This provides
+ * fine-grained reactivity without unnecessary renders.
+ *
+ * For objects, the returned value includes custom methods ($merge, $set, $delete, $update)
+ * that allow you to modify the data directly and trigger reactive updates.
+ *
+ * @example
+ * // Subscribe to user data
+ * const user = useScope(() => $.user);
+ *
+ * // Update user data directly (triggers re-render only for components using $.user)
+ * user.$merge({ name: 'New Name' });
+ *
+ * // Subscribe to a specific property
+ * const userName = useScope(() => $.user.name);
+ *
+ * // Subscribe to a computed value
+ * const isAdmin = useScope(() => $.user.role === 'admin');
+ *
+ * @param selector - Function that returns the data you want to subscribe to
+ * @returns The selected data, with custom methods attached if it's an object
+ */
+function useScope(selector) {
+    // Use ref to store the latest selector to avoid stale closures
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    // Track dependencies and get initial value with advanced tracking
+    const { value: initialValue, paths: trackedPaths } = trackDependencies(selector);
+    // Add tracked paths to selector paths for ultra-selective proxying
+    trackedPaths.forEach(path => {
+        selectorPaths.add(path);
+        pathUsageStats.subscribedPaths.add(path);
+    });
+    // Use a counter to force re-renders instead of storing the value
+    // This way we always return the fresh proxy object from the selector
+    const [, forceUpdate] = useState(0);
+    // Create stable update handler that forces re-render
+    const handleChange = useCallback(() => {
+        try {
+            forceUpdate(count => count + 1);
+        }
+        catch (error) {
+            console.error('Error in useScope update:', error);
+        }
+    }, []);
+    useEffect(() => {
+        // Create path keys for subscription using the original approach
+        // If trackedPaths is ['user', 'name'], create subscriptions for ['user', 'user.name']
+        const pathKeys = trackedPaths.length > 0
+            ? trackedPaths.map((_, index, array) => array.slice(0, index + 1).join('.'))
+            : [''];
+        // Subscribe to all relevant paths
+        const unsubscribeFunctions = pathKeys.map(pathKey => {
+            // Mark this path as subscribed for usage tracking
+            pathUsageStats.subscribedPaths.add(pathKey);
+            return subscribe(pathKey, handleChange);
+        });
+        // Clean up subscriptions on unmount or dependency change
+        return () => {
+            unsubscribeFunctions.forEach(unsubscribe => unsubscribe());
+        };
+    }, [trackedPaths.join(','), handleChange]); // Stable dependencies
+    // Always return the fresh result from the selector (preserves proxy and methods)
+    return selectorRef.current();
+}
+
+/**
+ * Hook to create reactive local state that persists across component re-renders.
+ *
+ * This creates a reactive proxy object with custom methods ($merge, $set, $update, etc.)
+ * that can be used to update local component state. Unlike the global store,
+ * this state is isolated to the component instance.
+ *
+ * The state persists across re-renders but is reset when the component unmounts.
+ *
+ * @example
+ * function MyComponent() {
+ *   const localState = useLocal({ count: 0, name: 'John' });
+ *
+ *   return (
+ *     <div>
+ *       <p>Count: {localState.count}</p>
+ *       <button onClick={() => localState.$merge({ count: localState.count + 1 })}>
+ *         Increment
+ *       </button>
+ *       <button onClick={() => localState.$update('name', name => name.toUpperCase())}>
+ *         Uppercase Name
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ *
+ * @param initialState - The initial state object
+ * @returns A reactive proxy object with custom methods for state updates
+ */
+function useLocal(initialState) {
+    // Create the reactive state only once using lazy initialization
+    const [localState] = useState(() => createAdvancedProxy(initialState));
+    return localState;
+}
+
+// Default store structure - can be overridden via configuration
+const defaultStore = {
+    user: {
+        name: 'John Doe',
+        age: 30,
+    },
+};
+// The actual store that will be used - start with default but allow override
+let store = defaultStore;
+// Store a deep clone of the initial store state for use with $reset
+let initialStoreState = JSON.parse(JSON.stringify(store));
+/**
+ * Initialize the store with custom initial state
+ * This function updates both the store and its type
+ */
+function initializeStore(config = {}) {
+    if (config.initialState) {
+        // Update the actual store with the new state
+        store = { ...config.initialState };
+        initialStoreState = JSON.parse(JSON.stringify(store));
+        if (typeof window !== 'undefined') {
+            console.log('🏪 Store initialized with custom state');
+        }
+        return store;
+    }
+    else {
+        // Use default store
+        store = { ...defaultStore };
+        initialStoreState = JSON.parse(JSON.stringify(store));
+        return store;
+    }
+}
+/**
+ * Get the current store (for debugging)
+ */
+function getStore() {
+    return store;
+}
+/**
+ * Reset the entire store to its initial state
+ */
+function resetStore() {
+    // Clear current store
+    Object.keys(store).forEach(key => {
+        delete store[key];
+    });
+    // Restore initial state
+    Object.assign(store, JSON.parse(JSON.stringify(initialStoreState)));
+    if (typeof window !== 'undefined') {
+        console.log('🔄 Store reset to initial state');
+    }
+}
+
+/**
+ * Perform automatic leak check
+ */
+function performAutoLeakCheck() {
+    if (typeof window === 'undefined')
+        return;
+    if (!monitoringConfig.enabled || !monitoringConfig.autoLeakDetection ||
+        monitoringStats.leakDetection.isLeakDetectionRunning) {
+        return;
+    }
+    monitoringStats.leakDetection.isLeakDetectionRunning = true;
+    try {
+        console.log(`Running automatic leak detection (check #${monitoringStats.leakDetection.totalChecks + 1})`);
+        const leakReport = monitorAPI.checkForLeaks(false);
+        if (!leakReport)
+            return;
+        // Only show detailed report if threshold is exceeded
+        if (leakReport.orphanedListeners >= monitoringConfig.leakAlertThreshold) {
+            console.warn(`MEMORY LEAK ALERT: ${leakReport.orphanedListeners} orphaned listeners detected!`);
+            console.log('Paths with potential leaks:');
+            leakReport.mismatchedCounts.forEach(msg => console.log(`- ${msg}`));
+            monitoringStats.leakDetection.leaksDetected++;
+            // Auto-optimize if many leaks found
+            if (leakReport.orphanedListeners > monitoringConfig.leakAlertThreshold * 2) {
+                console.log('Auto-optimizing memory due to high leak count...');
+                optimizeMemoryUsage(false);
+            }
+        }
+        monitoringStats.leakDetection.lastCheckTime = Date.now();
+        monitoringStats.leakDetection.totalChecks++;
+        monitoringStats.leakDetection.renderCyclesSinceCheck = 0;
+    }
+    catch (e) {
+        console.error('Error during automatic leak check:', e);
+    }
+    finally {
+        monitoringStats.leakDetection.isLeakDetectionRunning = false;
+    }
+}
+/**
+ * Monitor API for debugging and memory leak detection
+ */
+const monitorAPI = {
+    // Enable or disable monitoring
+    setEnabled: (enabled) => {
+        if (typeof window === 'undefined')
+            return;
+        monitoringConfig.enabled = enabled;
+    },
+    // Set verbose logging
+    setVerboseLogging: (enabled) => {
+        if (typeof window === 'undefined')
+            return;
+        monitoringConfig.verboseLogging = enabled;
+    },
+    // Configure specific monitoring features
+    configure: (config) => {
+        Object.assign(monitoringConfig, config);
+    },
+    // Get current stats
+    getStats: () => ({ ...monitoringStats }),
+    // Get detailed listener info
+    getListenerInfo: () => {
+        const info = {};
+        pathListeners.forEach((listeners, path) => {
+            info[path] = listeners.size;
+        });
+        return info;
+    },
+    // Check for potential memory leaks
+    checkForLeaks: (logReport = true) => {
+        if (typeof window === 'undefined')
+            return null;
+        const leakReport = {
+            orphanedListeners: 0,
+            mismatchedCounts: [],
+            emptyPaths: [],
+            totalListeners: 0,
+            summary: ''
+        };
+        // Check for paths with listeners but no subscribers in our tracking
+        pathListeners.forEach((listeners, path) => {
+            leakReport.totalListeners += listeners.size;
+            const trackedCount = monitoringStats.pathSubscriptionCounts[path] || 0;
+            if (listeners.size > 0 && trackedCount <= 0) {
+                leakReport.orphanedListeners += listeners.size;
+                leakReport.mismatchedCounts.push(`Path ${path}: actual=${listeners.size}, tracked=${trackedCount}`);
+            }
+            if (listeners.size === 0) {
+                leakReport.emptyPaths.push(path);
+            }
+        });
+        leakReport.summary = `Found ${leakReport.orphanedListeners} potential leaked listeners across ${leakReport.mismatchedCounts.length} paths. Total listeners: ${leakReport.totalListeners}`;
+        if (logReport) {
+            console.log('LEAK CHECK REPORT:');
+            console.log(leakReport.summary);
+            if (leakReport.mismatchedCounts.length > 0) {
+                console.log('Paths with potential leaks:');
+                leakReport.mismatchedCounts.forEach(msg => console.log(`- ${msg}`));
+            }
+        }
+        return leakReport;
+    },
+    // Start automatic leak detection
+    startAutoLeakDetection: (interval = 30000) => {
+        if (typeof window === 'undefined')
+            return false;
+        monitoringConfig.autoLeakDetection = true;
+        monitoringConfig.leakDetectionInterval = interval;
+        // Clear any existing timer
+        if (monitoringStats.leakDetection.leakDetectionTimer) {
+            clearInterval(monitoringStats.leakDetection.leakDetectionTimer);
+        }
+        // Set up periodic leak detection
+        monitoringStats.leakDetection.leakDetectionTimer = setInterval(() => {
+            if (monitoringStats.leakDetection.renderCyclesSinceCheck >= monitoringConfig.leakScanMinimumRenderCycles) {
+                performAutoLeakCheck();
+            }
+        }, interval);
+        console.log(`Automatic leak detection started (interval: ${interval}ms)`);
+        return true;
+    },
+    // Stop automatic leak detection
+    stopAutoLeakDetection: () => {
+        if (typeof window === 'undefined')
+            return false;
+        monitoringConfig.autoLeakDetection = false;
+        if (monitoringStats.leakDetection.leakDetectionTimer) {
+            clearInterval(monitoringStats.leakDetection.leakDetectionTimer);
+            monitoringStats.leakDetection.leakDetectionTimer = null;
+        }
+        console.log('Automatic leak detection stopped');
+        return true;
+    },
+    // Configure leak detection
+    configureLeakDetection: (config) => {
+        if (typeof window === 'undefined')
+            return;
+        if (config.enabled !== undefined) {
+            monitoringConfig.autoLeakDetection = config.enabled;
+        }
+        if (config.interval !== undefined) {
+            monitoringConfig.leakDetectionInterval = config.interval;
+        }
+        if (config.alertThreshold !== undefined) {
+            monitoringConfig.leakAlertThreshold = config.alertThreshold;
+        }
+        if (config.minimumRenderCycles !== undefined) {
+            monitoringConfig.leakScanMinimumRenderCycles = config.minimumRenderCycles;
+        }
+        // Restart if enabled
+        if (monitoringConfig.autoLeakDetection) {
+            monitorAPI.startAutoLeakDetection(monitoringConfig.leakDetectionInterval);
+        }
+        else {
+            monitorAPI.stopAutoLeakDetection();
+        }
+        console.log('Leak detection configuration updated:', {
+            enabled: monitoringConfig.autoLeakDetection,
+            interval: monitoringConfig.leakDetectionInterval,
+            alertThreshold: monitoringConfig.leakAlertThreshold,
+            minimumRenderCycles: monitoringConfig.leakScanMinimumRenderCycles
+        });
+    },
+    // Get leak detection stats
+    getLeakDetectionStats: () => ({
+        isEnabled: monitoringConfig.autoLeakDetection,
+        interval: monitoringConfig.leakDetectionInterval,
+        checksPerformed: monitoringStats.leakDetection.totalChecks,
+        leaksDetected: monitoringStats.leakDetection.leaksDetected,
+        alertThreshold: monitoringConfig.leakAlertThreshold
+    }),
+    // Reset statistics
+    resetStats: () => {
+        monitoringStats.proxyCount = 0;
+        monitoringStats.totalSubscriptionsCreated = 0;
+        monitoringStats.totalSubscriptionsRemoved = 0;
+        monitoringStats.activeSubscriptions = 0;
+        monitoringStats.pathSubscriptionCounts = {};
+        monitoringStats.timings = {
+            lastNotifyTime: 0,
+            lastPersistTime: 0,
+            averageNotifyTime: 0,
+            averagePersistTime: 0,
+            notifyTimeTotal: 0,
+            persistTimeTotal: 0,
+            notifyCount: 0,
+            persistCount: 0,
+        };
+        console.log('Monitoring statistics reset');
+    },
+    // Force cleanup of empty listener sets
+    cleanupEmptyListeners: () => {
+        let cleanedCount = 0;
+        pathListeners.forEach((listeners, path) => {
+            if (listeners.size === 0) {
+                pathListeners.delete(path);
+                cleanedCount++;
+            }
+        });
+        console.log(`Cleaned up ${cleanedCount} empty listener sets`);
+        return cleanedCount;
+    },
+    // Get proxy cache stats (delegated to proxy module)
+    getProxyCacheStats,
+    // Get proxy usage stats
+    getProxyUsageStats: () => ({
+        accessedPaths: Array.from(pathUsageStats.accessedPaths),
+        modifiedPaths: Array.from(pathUsageStats.modifiedPaths),
+        subscribedPaths: Array.from(pathUsageStats.subscribedPaths),
+        totalAccessedPaths: pathUsageStats.accessedPaths.size,
+        totalModifiedPaths: pathUsageStats.modifiedPaths.size,
+        totalSubscribedPaths: pathUsageStats.subscribedPaths.size,
+    }),
+    // Reset usage stats
+    resetProxyUsageStats: () => {
+        pathUsageStats.accessedPaths.clear();
+        pathUsageStats.modifiedPaths.clear();
+        // Don't clear subscribedPaths as they're used for optimization
+        console.log('Proxy usage statistics reset (except subscriptions)');
+    },
+    // Generate report of most accessed/modified paths for optimization
+    generatePathUsageReport: () => {
+        const report = {
+            mostAccessedPaths: Array.from(pathUsageStats.accessedPaths).slice(0, 20),
+            mostModifiedPaths: Array.from(pathUsageStats.modifiedPaths).slice(0, 20),
+            subscribedPaths: Array.from(pathUsageStats.subscribedPaths),
+            recommendations: []
+        };
+        // Generate recommendations
+        if (pathUsageStats.accessedPaths.size > 100) {
+            report.recommendations.push(`Consider adding frequently accessed paths to preProxyPaths: ${report.mostAccessedPaths.slice(0, 5).join(', ')}`);
+        }
+        return report;
+    },
+    // Memory-optimized leak detection
+    optimizeMemoryUsage,
+    // Get selector path statistics
+    getSelectorPathStats: () => {
+        return {
+            totalSelectorPaths: selectorPaths.size,
+            paths: Array.from(selectorPaths),
+            mostAccessedSelectorPaths: Array.from(selectorPaths).slice(0, 20),
+        };
+    },
+    // Clear selector paths (force rebuilding)
+    clearSelectorPaths: () => {
+        const count = selectorPaths.size;
+        selectorPaths.clear();
+        console.log(`Cleared ${count} selector paths. They will be rebuilt as components render.`);
+        return count;
+    },
+    // Get comprehensive system status
+    getSystemStatus: () => {
+        const proxyCacheStats = getProxyCacheStats();
+        const leakStats = monitorAPI.getLeakDetectionStats();
+        return {
+            monitoring: {
+                enabled: monitoringConfig.enabled,
+                verboseLogging: monitoringConfig.verboseLogging,
+                autoLeakDetection: monitoringConfig.autoLeakDetection,
+            },
+            listeners: {
+                total: monitoringStats.activeSubscriptions,
+                pathCount: pathListeners.size,
+            },
+            proxies: {
+                cacheSize: proxyCacheStats.estimatedCacheSize,
+                hitRatio: proxyCacheStats.hitRatio,
+                totalCreated: proxyCacheStats.totalProxiesCreated,
+            },
+            paths: {
+                accessed: pathUsageStats.accessedPaths.size,
+                modified: pathUsageStats.modifiedPaths.size,
+                subscribed: pathUsageStats.subscribedPaths.size,
+                selectors: selectorPaths.size,
+            },
+            leakDetection: leakStats,
+            performance: {
+                averageNotifyTime: monitoringStats.timings.averageNotifyTime,
+                averagePersistTime: monitoringStats.timings.averagePersistTime,
+                totalNotifications: monitoringStats.timings.notifyCount,
+                totalPersistOperations: monitoringStats.timings.persistCount,
+            }
+        };
+    },
+    // Force a comprehensive health check
+    performHealthCheck: () => {
+        console.log('Performing comprehensive health check...');
+        const leakReport = monitorAPI.checkForLeaks(true);
+        const systemStatus = monitorAPI.getSystemStatus();
+        const cleanedListeners = monitorAPI.cleanupEmptyListeners();
+        const recommendations = [];
+        if (leakReport && leakReport.orphanedListeners > 5) {
+            recommendations.push('🚨 High number of orphaned listeners detected - consider running optimizeMemoryUsage()');
+        }
+        if (systemStatus.proxies.hitRatio < 0.8) {
+            recommendations.push('📈 Low proxy cache hit ratio - consider reviewing proxy configuration');
+        }
+        if (systemStatus.paths.accessed > 1000) {
+            recommendations.push('📊 High number of accessed paths - consider enabling ultraSelectiveProxying');
+        }
+        const healthScore = Math.max(0, 100 -
+            (leakReport ? leakReport.orphanedListeners * 5 : 0) -
+            (systemStatus.proxies.hitRatio < 0.8 ? 20 : 0) -
+            (systemStatus.paths.accessed > 1000 ? 15 : 0));
+        console.log(`Health Check Complete - Score: ${healthScore}/100`);
+        if (recommendations.length > 0) {
+            console.log('Recommendations:');
+            recommendations.forEach(rec => console.log(`  ${rec}`));
+        }
+        return {
+            healthScore,
+            recommendations,
+            systemStatus,
+            leakReport,
+            cleanedListeners
+        };
+    }
+};
+// Initialize auto leak detection if configured
+if (typeof window !== 'undefined' && monitoringConfig.enabled && monitoringConfig.autoLeakDetection) {
+    setTimeout(() => monitorAPI.startAutoLeakDetection(), 5000); // Start after 5 seconds
+}
+
+let storage = null;
+/**
+ * Initialize storage for persistence
+ */
+function initializeStorage() {
+    try {
+        if (typeof window !== 'undefined') {
+            storage = localforage.createInstance({
+                name: 'SCOPE_STATE',
+                description: 'Scope state management storage'
+            });
+            // Add memory driver as fallback
+            localforage.defineDriver(memoryDriver);
+            localforage.setDriver([
+                localforage.INDEXEDDB,
+                localforage.LOCALSTORAGE,
+                localforage.WEBSQL,
+                memoryDriver._driver
+            ]);
+            console.log('💾 Storage initialized successfully');
+        }
+    }
+    catch (error) {
+        console.error('❌ Error creating storage instance:', error);
+        storage = null;
+    }
+}
+/**
+ * Get the current storage instance
+ */
+function getStorage() {
+    return storage;
+}
+// Initialize storage by default
+if (typeof window !== 'undefined') {
+    initializeStorage();
+}
+
+// Storage constants
+const PERSISTED_STATE_KEY = 'persisted_state';
+const PERSISTENCE_CONFIG_KEY = 'persistence_config';
+// Batch persistence state
+const persistenceBatch = {
+    paths: new Set(),
+    timeoutId: null,
+    isPersisting: false,
+};
+// Performance timing helpers
+function logTimestamp(action) {
+    if (!monitoringConfig.enabled || !monitoringConfig.logTimings)
+        return 0;
+    const now = performance.now();
+    console.log(`⏱️ [${now.toFixed(2)}ms] ${action}`);
+    return now;
+}
+function logTimingEnd(action, startTime) {
+    if (!monitoringConfig.enabled || !monitoringConfig.logTimings)
+        return 0;
+    const now = performance.now();
+    const duration = now - startTime;
+    console.log(`⏱️ [${now.toFixed(2)}ms] ${action} completed in ${duration.toFixed(2)}ms`);
+    return duration;
+}
+/**
+ * Process all paths in the batch
+ */
+function processPersistenceBatch() {
+    if (typeof window === 'undefined')
+        return;
+    if (persistenceBatch.isPersisting || persistenceBatch.paths.size === 0) {
+        return;
+    }
+    persistenceBatch.isPersisting = true;
+    let startTime = 0;
+    if (monitoringConfig.enabled && monitoringConfig.logPersistence) {
+        startTime = logTimestamp(`💾 Batch persisting ${persistenceBatch.paths.size} paths`);
+    }
+    try {
+        // Convert set to array of path arrays
+        const pathArrays = Array.from(persistenceBatch.paths).map(path => path.split('.'));
+        // Persist entire state if we're persisting many paths
+        if (pathArrays.length > 10) {
+            persistState();
+        }
+        else {
+            // Otherwise persist individual paths
+            pathArrays.forEach(pathArray => {
+                persistState(pathArray);
+            });
+        }
+        // Clear the batch
+        persistenceBatch.paths.clear();
+    }
+    catch (e) {
+        console.error('Error during batch persistence:', e);
+    }
+    finally {
+        persistenceBatch.isPersisting = false;
+        // If new paths were added during processing, schedule another batch
+        if (persistenceBatch.paths.size > 0) {
+            schedulePersistenceBatch();
+        }
+        if (monitoringConfig.enabled && monitoringConfig.logPersistence && startTime > 0) {
+            logTimingEnd('Batch persistence', startTime);
+        }
+    }
+}
+/**
+ * Schedule batch persistence with debounce
+ */
+function schedulePersistenceBatch() {
+    if (persistenceBatch.timeoutId) {
+        clearTimeout(persistenceBatch.timeoutId);
+    }
+    persistenceBatch.timeoutId = setTimeout(() => {
+        persistenceBatch.timeoutId = null;
+        processPersistenceBatch();
+    }, persistenceConfig.batchDelay);
+}
+/**
+ * Add a path to the persistence batch
+ */
+function addToPersistenceBatch(path) {
+    if (!persistenceConfig.enabled)
+        return;
+    const pathKey = path.join('.');
+    if (shouldPersistPath(pathKey)) {
+        persistenceBatch.paths.add(pathKey);
+        schedulePersistenceBatch();
+    }
+}
+/**
+ * Function to determine if a path should be persisted
+ */
+function shouldPersistPath(path) {
+    if (!persistenceConfig.enabled)
+        return false;
+    // Check if path is blacklisted
+    if (persistenceConfig.blacklist.some(blacklistedPath => path === blacklistedPath || path.startsWith(`${blacklistedPath}.`))) {
+        return false;
+    }
+    // If paths array is empty, persist everything not blacklisted
+    if (!persistenceConfig.paths || persistenceConfig.paths.length === 0)
+        return true;
+    // Check if path is in the persistence paths list
+    return persistenceConfig.paths.some(persistedPath => path === persistedPath || path.startsWith(`${persistedPath}.`));
+}
+/**
+ * Save state to storage
+ */
+function persistState(path = []) {
+    if (typeof window === 'undefined')
+        return;
+    if (!persistenceConfig.enabled)
+        return;
+    const currentStorage = getStorage();
+    if (!currentStorage)
+        return;
+    const pathKey = path.join('.');
+    if (path.length === 0) {
+        // We need access to the store to persist entire state
+        // For now, we'll skip this and only support path-specific persistence
+        console.warn('Cannot persist entire state without store reference');
+        return;
+    }
+    if (shouldPersistPath(pathKey)) {
+        // For individual path persistence, we'd need access to the store
+        // This will be implemented when integrating with the main store
+        try {
+            currentStorage.setItem(`${PERSISTED_STATE_KEY}_${pathKey}`, JSON.stringify({}));
+        }
+        catch (e) {
+            console.error(`Error persisting path ${pathKey}:`, e);
+        }
+    }
+}
+/**
+ * Hydrate state from storage
+ */
+async function hydrateState(store) {
+    if (typeof window === 'undefined')
+        return false;
+    if (!store) {
+        console.warn('Cannot hydrate state without store reference');
+        return false;
+    }
+    const currentStorage = getStorage();
+    if (!currentStorage)
+        return false;
+    try {
+        // First try to load entire state
+        const savedState = await currentStorage.getItem(PERSISTED_STATE_KEY);
+        if (savedState) {
+            const parsedState = JSON.parse(savedState);
+            // Direct replacement instead of merging
+            Object.keys(parsedState).forEach(key => {
+                if (key in store) {
+                    store[key] = parsedState[key];
+                }
+            });
+            if (monitoringConfig.enabled) {
+                console.log('🔄 State hydrated from storage');
+            }
+        }
+        // Then try to load individual persisted paths
+        const keys = await currentStorage.keys();
+        if (!keys)
+            return true;
+        for (const key of keys) {
+            if (key.startsWith(`${PERSISTED_STATE_KEY}_`)) {
+                const path = key.replace(`${PERSISTED_STATE_KEY}_`, '').split('.');
+                const value = await currentStorage.getItem(key);
+                if (value) {
+                    try {
+                        const parsedValue = JSON.parse(value);
+                        // Set the value in the store
+                        let current = store;
+                        for (let i = 0; i < path.length - 1; i++) {
+                            if (!(path[i] in current)) {
+                                current[path[i]] = {};
+                            }
+                            current = current[path[i]];
+                        }
+                        const lastKey = path[path.length - 1];
+                        current[lastKey] = parsedValue;
+                    }
+                    catch (e) {
+                        console.error(`Error hydrating path ${path.join('.')}:`, e);
+                    }
+                }
+            }
+        }
+        if (monitoringConfig.enabled) {
+            console.log(`🔄 Hydrated ${keys.length} individual paths`);
+        }
+    }
+    catch (e) {
+        console.error('Error hydrating state:', e);
+        return false;
+    }
+    return true;
+}
+/**
+ * Load persistence configuration
+ */
+async function loadPersistenceConfig() {
+    if (typeof window === 'undefined')
+        return;
+    const currentStorage = getStorage();
+    if (!currentStorage)
+        return;
+    try {
+        const config = await currentStorage.getItem(PERSISTENCE_CONFIG_KEY);
+        if (config) {
+            const parsedConfig = JSON.parse(config);
+            Object.assign(persistenceConfig, parsedConfig);
+        }
+    }
+    catch (e) {
+        console.error('Error loading persistence configuration:', e);
+    }
+}
+/**
+ * Save persistence configuration
+ */
+function savePersistenceConfig() {
+    if (typeof window === 'undefined')
+        return;
+    const currentStorage = getStorage();
+    if (!currentStorage)
+        return;
+    try {
+        currentStorage.setItem(PERSISTENCE_CONFIG_KEY, JSON.stringify(persistenceConfig));
+    }
+    catch (e) {
+        console.error('Error saving persistence configuration:', e);
+    }
+}
+/**
+ * Persistence API - matches the original implementation
+ */
+const persistenceAPI = {
+    // Enable or disable persistence
+    setEnabled: (enabled) => {
+        persistenceConfig.enabled = enabled;
+        savePersistenceConfig();
+    },
+    // Add paths to be persisted
+    persistPaths: (paths) => {
+        if (!persistenceConfig.paths) {
+            persistenceConfig.paths = [];
+        }
+        persistenceConfig.paths = Array.from(new Set([...persistenceConfig.paths, ...paths]));
+        savePersistenceConfig();
+        // Force persist current state for these paths
+        paths.forEach(path => addToPersistenceBatch(path.split('.')));
+    },
+    // Remove paths from persistence
+    unpersistPaths: (paths) => {
+        if (persistenceConfig.paths) {
+            persistenceConfig.paths = persistenceConfig.paths.filter(p => !paths.includes(p));
+            savePersistenceConfig();
+        }
+        // Remove from storage
+        const currentStorage = getStorage();
+        if (currentStorage) {
+            paths.forEach(path => {
+                currentStorage.removeItem(`${PERSISTED_STATE_KEY}_${path}`);
+            });
+        }
+    },
+    // Add paths to blacklist
+    blacklistPaths: (paths) => {
+        persistenceConfig.blacklist = Array.from(new Set([...persistenceConfig.blacklist, ...paths]));
+        savePersistenceConfig();
+        // Remove from storage
+        const currentStorage = getStorage();
+        if (currentStorage) {
+            paths.forEach(path => {
+                currentStorage.removeItem(`${PERSISTED_STATE_KEY}_${path}`);
+            });
+        }
+    },
+    // Remove paths from blacklist
+    unblacklistPaths: (paths) => {
+        persistenceConfig.blacklist = persistenceConfig.blacklist.filter(p => !paths.includes(p));
+        savePersistenceConfig();
+    },
+    // Get current persistence configuration
+    getConfig: () => ({ ...persistenceConfig }),
+    // Set the batch delay (in ms)
+    setBatchDelay: (delay) => {
+        persistenceConfig.batchDelay = delay;
+        savePersistenceConfig();
+    },
+    // Reset persistence
+    reset: async () => {
+        const currentStorage = getStorage();
+        if (!currentStorage)
+            return;
+        // Clear all persisted state
+        const keys = await currentStorage.keys();
+        if (keys) {
+            for (const key of keys) {
+                if (key.startsWith(PERSISTED_STATE_KEY)) {
+                    await currentStorage.removeItem(key);
+                }
+            }
+        }
+        // Reset configuration to defaults
+        Object.assign(persistenceConfig, {
+            enabled: true,
+            paths: [],
+            blacklist: [],
+            batchDelay: 300,
+        });
+        savePersistenceConfig();
+    },
+    // Force persist current state
+    persist: () => persistState(),
+    // Force persist current batch immediately
+    flushBatch: () => {
+        if (persistenceBatch.timeoutId) {
+            clearTimeout(persistenceBatch.timeoutId);
+            persistenceBatch.timeoutId = null;
+        }
+        processPersistenceBatch();
+    },
+    // Force rehydrate state
+    rehydrate: (store) => hydrateState(store),
+    // Get batch status
+    getBatchStatus: () => ({
+        pendingPaths: Array.from(persistenceBatch.paths),
+        isPersisting: persistenceBatch.isPersisting,
+        batchSize: persistenceBatch.paths.size,
+    }),
+};
+/**
+ * Initialize persistence system
+ */
+function initializePersistence() {
+    if (typeof window !== 'undefined') {
+        loadPersistenceConfig();
+        console.log('💾 Advanced persistence system initialized');
+    }
+}
+// Initialize automatically
+initializePersistence();
+
+// Main exports for the library
+// Global state
+let globalStore = {
+    user: {
+        name: 'John Doe',
+        age: 30,
+    },
+};
+let globalStoreProxy = null;
+/**
+ * Configure Scope with custom settings and return a properly typed store
+ * This is the main way to set up Scope with TypeScript support
+ */
+function configure(config) {
+    // Update configurations
+    if (config.proxy) {
+        Object.assign(proxyConfig, config.proxy);
+    }
+    if (config.monitoring) {
+        Object.assign(monitoringConfig, config.monitoring);
+    }
+    if (config.persistence) {
+        Object.assign(persistenceConfig, config.persistence);
+    }
+    // Update the global store
+    if (config.initialState) {
+        globalStore = { ...config.initialState };
+        // Store initial state for reset functionality
+        setInitialStoreState(globalStore);
+        if (typeof window !== 'undefined' && monitoringConfig.enabled) {
+            console.log('🏪 Store configured with custom state');
+        }
+    }
+    // Create and cache the advanced proxy
+    globalStoreProxy = createAdvancedProxy(globalStore);
+    // Hydrate persisted state if persistence is enabled
+    if (typeof window !== 'undefined' && persistenceConfig.enabled) {
+        hydrateState(globalStore).then((success) => {
+            if (success && monitoringConfig.enabled) {
+                console.log('🔄 State hydrated from persistence');
+            }
+        });
+    }
+    if (typeof window !== 'undefined' && monitoringConfig.enabled) {
+        console.log('🔧 Scope configured with advanced features');
+    }
+    return globalStoreProxy;
+}
+// Enhanced tracking that integrates with the advanced proxy system
+function trackDependenciesAdvanced(selector) {
+    try {
+        // Execute selector and track paths
+        const result = trackDependencies(selector);
+        // Add tracked paths to selector paths for ultra-selective proxying
+        result.paths.forEach(path => {
+            selectorPaths.add(path);
+            pathUsageStats.subscribedPaths.add(path);
+        });
+        return result;
+    }
+    finally {
+        // Cleanup any temporary tracking state
+    }
+}
+// Default store for when configure() isn't called
+if (!globalStoreProxy) {
+    globalStoreProxy = createAdvancedProxy(globalStore);
+    setInitialStoreState(globalStore);
+}
+// Export the main $ proxy - will be properly typed if configure() is called first
+const $ = globalStoreProxy;
+// Utility functions from the original code
+function createReactive(obj) {
+    return createAdvancedProxy(obj);
+}
+// Legacy alias - use useLocal() hook instead for proper React integration
+const $local = createReactive;
+// Development helper to check if an object is reactive
+function isReactive(obj) {
+    return obj && typeof obj === 'object' && typeof obj.$merge === 'function';
+}
+// Type-safe activation functions from the original
+function activate(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    const path = proxyPathMap.get(obj);
+    if (!path) {
+        console.warn('⚠️ Could not determine path for object. Make sure it\'s from the $ tree.');
+        return obj;
+    }
+    if (monitoringConfig.enabled && monitoringConfig.verboseLogging) {
+        console.log(`🔄 Type-safe activation of path: ${path.join('.')}`);
+    }
+    // Add to selector paths
+    selectorPaths.add(path.join('.'));
+    // Add parent paths
+    for (let i = 1; i < path.length; i++) {
+        const parentPath = path.slice(0, i).join('.');
+        selectorPaths.add(parentPath);
+    }
+    return obj;
+}
+function $activate(obj) {
+    return activate(obj);
+}
+function getProxy(path) {
+    // Handle case where an object from $ is passed directly
+    if (path !== null && typeof path === 'object') {
+        return activate(path);
+    }
+    const pathArray = typeof path === 'string' ? path.split('.') : path;
+    const pathKey = pathArray.join('.');
+    // Add to selector paths
+    selectorPaths.add(pathKey);
+    if (monitoringConfig.enabled && monitoringConfig.verboseLogging) {
+        console.log(`🔄 Explicitly activating proxy for path: ${pathKey}`);
+    }
+    // Navigate to the target
+    let target = globalStore;
+    for (let i = 0; i < pathArray.length; i++) {
+        if (target === undefined || target === null)
+            break;
+        target = target[pathArray[i]];
+    }
+    if (target === undefined || target === null) {
+        console.warn(`⚠️ Path not found: ${pathKey}`);
+        return null;
+    }
+    // Force create an immediate proxy for this specific path
+    const immediateProxy = createAdvancedProxy(target, pathArray, 0);
+    // Add parent paths
+    for (let i = 1; i < pathArray.length; i++) {
+        const parentPath = pathArray.slice(0, i).join('.');
+        selectorPaths.add(parentPath);
+    }
+    return immediateProxy;
+}
+function $get(path) {
+    if (path !== null && typeof path === 'object') {
+        return activate(path);
+    }
+    return getProxy(path);
+}
+// For debugging - matches original API
+const debugInfo = {
+    getListenerCount: () => {
+        const { getListenerCount } = require('./core/listeners');
+        return getListenerCount();
+    },
+    getPathCount: () => {
+        const { pathListeners } = require('./core/listeners');
+        return pathListeners.size;
+    },
+    getActivePaths: () => {
+        const { getActivePaths } = require('./core/listeners');
+        return getActivePaths();
+    }
+};
+// Expose raw store for debugging
+const rawStore = globalStore;
+// Initialize library with enhanced features
+if (typeof window !== 'undefined') {
+    console.log('🎯 Scope State initialized with advanced features - ready for reactive state management');
+    console.log('💡 Tip: Call configure() with your initialState for full TypeScript support');
+    console.log('🔧 Advanced features: WeakMap caching, leak detection, batch persistence, memory management');
+    // Initialize auto-hydration if persistence is enabled
+    if (persistenceConfig.enabled) {
+        setTimeout(() => {
+            hydrateState(globalStore);
+        }, 100);
+    }
+}
+
+export { $, $activate, $get, $local, activate, clearProxyCache, configure, createAdvancedProxy, createReactive, debugInfo, getConfig, getProxy, getProxyCacheStats, getStore, initializeStore, isReactive, monitorAPI, optimizeMemoryUsage, pathUsageStats, persistenceAPI, presets, proxyPathMap, rawStore, resetConfig, resetStore, selectorPaths, setInitialStoreState, trackDependenciesAdvanced, useLocal, useScope };
+//# sourceMappingURL=index.esm.js.map