scope-state 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,27 +1,6 @@
 'use strict';
 
 var react = require('react');
-var localforage = require('localforage');
-var memoryDriver = require('localforage-driver-memory');
-
-function _interopNamespaceDefault(e) {
-    var n = Object.create(null);
-    if (e) {
-        Object.keys(e).forEach(function (k) {
-            if (k !== 'default') {
-                var d = Object.getOwnPropertyDescriptor(e, k);
-                Object.defineProperty(n, k, d.get ? d : {
-                    enumerable: true,
-                    get: function () { return e[k]; }
-                });
-            }
-        });
-    }
-    n.default = e;
-    return Object.freeze(n);
-}
-
-var memoryDriver__namespace = /*#__PURE__*/_interopNamespaceDefault(memoryDriver);
 
 // Default configurations
 const defaultProxyConfig = {
@@ -67,6 +46,7 @@ const defaultPersistenceConfig = {
     paths: [],
     blacklist: [],
     batchDelay: 300,
+    autoHydrate: true,
 };
 // Current active configurations (will be modified by configure())
 let proxyConfig = { ...defaultProxyConfig };
@@ -168,6 +148,16 @@ const presets = {
 
 // Path-specific listeners
 const pathListeners = new Map();
+// Post-notification callback — used by the persistence layer to react to state changes
+// without creating a circular dependency (listeners -> persistence -> config -> listeners).
+let onStateChangeCallback = null;
+/**
+ * Register a callback that fires after every notifyListeners call.
+ * Used internally by the persistence system to batch-persist changes.
+ */
+function setOnStateChangeCallback(callback) {
+    onStateChangeCallback = callback;
+}
 // Statistics for monitoring
 let monitoringStats = {
     proxyCount: 0,
@@ -281,6 +271,26 @@ function notifyListeners(path) {
         const duration = logTimingEnd$1('Notification cycle', startTime);
         updateTimingStat('notify', duration);
     }
+    // Fire the post-notification callback (persistence, etc.)
+    if (onStateChangeCallback) {
+        onStateChangeCallback(path);
+    }
+}
+/**
+ * Get total number of active listeners
+ */
+function getListenerCount() {
+    let total = 0;
+    pathListeners.forEach(listeners => {
+        total += listeners.size;
+    });
+    return total;
+}
+/**
+ * Get all active paths
+ */
+function getActivePaths() {
+    return Array.from(pathListeners.keys());
 }
 // Logging helper functions
 function logTimestamp$1(action) {
@@ -569,15 +579,7 @@ function createAdvancedProxy(target, path = [], depth = 0) {
                 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
-                }
-            }
+            trackPathAccess(currentPropPath);
             const value = obj[prop];
             // For objects, create proxies for nested values
             if (value && typeof value === 'object' && path.length < proxyConfig.maxDepth) {
@@ -978,13 +980,20 @@ function optimizeMemoryUsage(aggressive = false) {
 
 // Track the current path we're accessing during a selector function
 let currentPath = [];
+let isTracking = false;
+let skipTrackingDepth = 0;
 /**
  * Track dependencies during selector execution - tracks individual path segments
  */
 function trackDependencies(selector) {
+    // Start tracking
+    isTracking = true;
     currentPath = [];
+    skipTrackingDepth = 0;
     // Execute selector to track dependencies
     const value = selector();
+    // Stop tracking and get the tracked paths
+    isTracking = false;
     // Clean up and return individual path segments (not full paths)
     const cleanedPaths = [...currentPath].filter(segment => {
         // Filter out segments that would create overly long paths
@@ -993,6 +1002,23 @@ function trackDependencies(selector) {
     currentPath = [];
     return { value, paths: cleanedPaths };
 }
+/**
+ * Add a path segment to tracking during proxy get operations
+ */
+function trackPathAccess(path) {
+    if (!isTracking || skipTrackingDepth > 0)
+        return;
+    // Track only the last property name (individual segment)
+    const prop = path[path.length - 1];
+    // Only track if prop exists and path isn't too deep
+    if (prop && path.length <= proxyConfig.maxPathLength) {
+        currentPath.push(prop);
+        // Add full path to usage stats and selector paths for ultra-selective proxying
+        const fullPath = path.join('.');
+        pathUsageStats.accessedPaths.add(fullPath);
+        selectorPaths.add(fullPath);
+    }
+}
 
 /**
  * Hook to subscribe to the global store and re-render when specific data changes.
@@ -1477,50 +1503,276 @@ if (typeof window !== 'undefined' && monitoringConfig.enabled && monitoringConfi
     setTimeout(() => monitorAPI.startAutoLeakDetection(), 5000); // Start after 5 seconds
 }
 
-let storage = null;
 /**
- * Initialize storage for persistence
+ * Creates a localStorage-based storage adapter.
+ *
+ * This is the default adapter used in browser environments.
+ * All methods are synchronous (localStorage is synchronous by nature).
+ *
+ * @param prefix - Optional key prefix to namespace all stored keys. Defaults to 'scope_state:'.
+ * @returns A StorageAdapter backed by window.localStorage
+ *
+ * @example
+ * import { configure, createLocalStorageAdapter } from 'scope-state';
+ *
+ * configure({
+ *   initialState: { ... },
+ *   persistence: {
+ *     enabled: true,
+ *     storageAdapter: createLocalStorageAdapter('myapp:'),
+ *   },
+ * });
  */
-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__namespace);
-            localforage.setDriver([
-                localforage.INDEXEDDB,
-                localforage.LOCALSTORAGE,
-                localforage.WEBSQL,
-                memoryDriver__namespace._driver
-            ]);
-            console.log('💾 Storage initialized successfully');
-        }
-    }
-    catch (error) {
-        console.error('❌ Error creating storage instance:', error);
-        storage = null;
+function createLocalStorageAdapter(prefix = 'scope_state:') {
+    return {
+        getItem(key) {
+            try {
+                return localStorage.getItem(prefix + key);
+            }
+            catch {
+                return null;
+            }
+        },
+        setItem(key, value) {
+            try {
+                localStorage.setItem(prefix + key, value);
+            }
+            catch (e) {
+                console.error(`[scope-state] localStorage.setItem failed for key "${key}":`, e);
+            }
+        },
+        removeItem(key) {
+            try {
+                localStorage.removeItem(prefix + key);
+            }
+            catch (e) {
+                console.error(`[scope-state] localStorage.removeItem failed for key "${key}":`, e);
+            }
+        },
+        keys() {
+            try {
+                const allKeys = [];
+                for (let i = 0; i < localStorage.length; i++) {
+                    const key = localStorage.key(i);
+                    if (key && key.startsWith(prefix)) {
+                        allKeys.push(key.slice(prefix.length));
+                    }
+                }
+                return allKeys;
+            }
+            catch {
+                return [];
+            }
+        },
+        clear() {
+            try {
+                // Only remove keys with our prefix, not the entire localStorage
+                const keysToRemove = [];
+                for (let i = 0; i < localStorage.length; i++) {
+                    const key = localStorage.key(i);
+                    if (key && key.startsWith(prefix)) {
+                        keysToRemove.push(key);
+                    }
+                }
+                keysToRemove.forEach(key => localStorage.removeItem(key));
+            }
+            catch (e) {
+                console.error('[scope-state] localStorage.clear failed:', e);
+            }
+        },
+    };
+}
+/**
+ * Creates an in-memory storage adapter.
+ *
+ * Useful for:
+ * - Server-side rendering (SSR) where no persistent storage is available
+ * - Testing environments
+ * - Ephemeral state that should not survive page reloads
+ *
+ * All methods are synchronous.
+ *
+ * @returns A StorageAdapter backed by an in-memory Map
+ *
+ * @example
+ * import { configure, createMemoryAdapter } from 'scope-state';
+ *
+ * configure({
+ *   initialState: { ... },
+ *   persistence: {
+ *     enabled: true,
+ *     storageAdapter: createMemoryAdapter(),
+ *   },
+ * });
+ */
+function createMemoryAdapter() {
+    const store = new Map();
+    return {
+        getItem(key) {
+            var _a;
+            return (_a = store.get(key)) !== null && _a !== void 0 ? _a : null;
+        },
+        setItem(key, value) {
+            store.set(key, value);
+        },
+        removeItem(key) {
+            store.delete(key);
+        },
+        keys() {
+            return Array.from(store.keys());
+        },
+        clear() {
+            store.clear();
+        },
+    };
+}
+/**
+ * Wraps any StorageAdapter in an in-memory cache layer.
+ *
+ * This is automatically applied to all adapters by the persistence system.
+ * The cache prevents hydration mismatches by ensuring:
+ *
+ * 1. **On startup**: the cache is empty, so reads return `null` and the app
+ *    renders with `initialState` (matching SSR output).
+ * 2. **After hydration**: data is pulled from the backing store into the cache,
+ *    and components re-render with persisted data.
+ * 3. **On writes**: both the cache and the backing store are updated, so
+ *    subsequent reads are instant from memory.
+ *
+ * @param backingAdapter - The underlying storage adapter (MMKV, AsyncStorage, etc.)
+ * @returns A StorageAdapter with an in-memory cache in front of the backing store
+ */
+function createCachedAdapter(backingAdapter) {
+    const cache = new Map();
+    return {
+        getItem(key) {
+            var _a;
+            // Always read from the in-memory cache (instant, sync)
+            return (_a = cache.get(key)) !== null && _a !== void 0 ? _a : null;
+        },
+        setItem(key, value) {
+            // Write-through: update cache immediately, then persist to backing store
+            cache.set(key, value);
+            return backingAdapter.setItem(key, value);
+        },
+        removeItem(key) {
+            cache.delete(key);
+            return backingAdapter.removeItem(key);
+        },
+        keys() {
+            // Return keys from cache (this is the source of truth after warmup)
+            return Array.from(cache.keys());
+        },
+        clear() {
+            cache.clear();
+            if (backingAdapter.clear) {
+                return backingAdapter.clear();
+            }
+        },
+        /**
+         * Pre-populate the in-memory cache from the backing store.
+         * Called automatically during hydration. After this completes,
+         * all reads are served instantly from memory.
+         */
+        async warmCache() {
+            const keys = await backingAdapter.keys();
+            for (const key of keys) {
+                const value = await backingAdapter.getItem(key);
+                if (value !== null) {
+                    cache.set(key, value);
+                }
+            }
+        },
+    };
+}
+/**
+ * Returns the default storage adapter for the current environment.
+ *
+ * - In browsers: returns a localStorage adapter
+ * - In non-browser environments (Node, SSR): returns a memory adapter
+ */
+function getDefaultAdapter() {
+    if (typeof window !== 'undefined' && typeof localStorage !== 'undefined') {
+        return createLocalStorageAdapter();
     }
+    return createMemoryAdapter();
 }
+
+/**
+ * The active storage adapter used by the persistence layer.
+ *
+ * Defaults to a localStorage adapter in browsers or a memory adapter in SSR/Node.
+ * Can be overridden via `configure()` or `setStorageAdapter()`.
+ *
+ * All adapters are automatically wrapped in an in-memory cache layer
+ * to prevent hydration mismatches and provide instant reads.
+ */
+let storageAdapter = null;
 /**
- * Get the current storage instance
+ * Get the current storage adapter, lazily initializing the default if needed.
  */
-function getStorage() {
-    return storage;
+function getStorageAdapter() {
+    if (!storageAdapter) {
+        // Default adapters (localStorage, memory) are already fast/sync,
+        // so we don't need to wrap them in a cache — they ARE the cache.
+        storageAdapter = getDefaultAdapter();
+    }
+    return storageAdapter;
 }
-// Initialize storage by default
-if (typeof window !== 'undefined') {
-    initializeStorage();
+/**
+ * Set a custom storage adapter.
+ *
+ * Synchronous adapters (like `createLocalStorageAdapter` and `createMemoryAdapter`)
+ * are stored directly — this enables **synchronous hydration** during `configure()`,
+ * so components render with persisted values on the very first render (no flash of
+ * default values).
+ *
+ * For asynchronous adapters (AsyncStorage, MMKV with async API), wrap them in
+ * `createCachedAdapter()` before passing to `configure()`. The cache layer provides
+ * instant reads after the initial warm-up.
+ *
+ * @param adapter - A StorageAdapter implementation
+ */
+function setStorageAdapter(adapter) {
+    storageAdapter = adapter;
 }
 
 // Storage constants
 const PERSISTED_STATE_KEY = 'persisted_state';
 const PERSISTENCE_CONFIG_KEY = 'persistence_config';
-// Batch persistence state
+// Global store references — set by configure()
+// The raw store is used for reading/serializing state during persistence.
+// The proxy is used for writing during hydration so that set traps fire
+// and components re-render with the hydrated values.
+let globalStoreRef = null;
+let globalProxyRef = null;
+// Flag to suppress persistence during hydration — hydration writes through
+// the proxy (to trigger re-renders), which also triggers the persistence
+// callback. We skip that to avoid wastefully re-persisting the same data.
+let isHydrating = false;
+// Flag to block persistence until the first hydration has completed.
+// This prevents React effects that fire between the initial render and
+// hydration from persisting default values over the correct stored data.
+let hasHydrated = false;
+/**
+ * Set the global store reference (raw object) for serialization during persistence.
+ * Called internally by configure().
+ */
+function setGlobalStoreRef(store) {
+    globalStoreRef = store;
+}
+/**
+ * Set the global proxy reference for hydration writes.
+ * Writing through the proxy ensures set traps fire and components re-render.
+ * Called internally by configure() after the proxy is created.
+ */
+function setGlobalProxyRef(proxy) {
+    globalProxyRef = proxy;
+}
+// Batch persistence state — stores persistence *roots* (e.g. "user", "todos"),
+// not individual leaf paths like "user.preferences.theme".
 const persistenceBatch = {
-    paths: new Set(),
+    roots: new Set(),
     timeoutId: null,
     isPersisting: false,
 };
@@ -1541,42 +1793,114 @@ function logTimingEnd(action, startTime) {
     return duration;
 }
 /**
- * Process all paths in the batch
+ * Determine the "persistence root" for a given change path.
+ *
+ * When a deep property changes (e.g. "user.preferences.theme"), we don't
+ * want to create a separate storage entry for every leaf — that leads to
+ * fragmented, inconsistent data. Instead we figure out the appropriate
+ * root-level slice and persist the entire object at that level.
+ *
+ * Rules:
+ * 1. If `persistenceConfig.paths` lists specific paths, use the matching
+ *    configured path as the root (e.g. if configured with "user.preferences",
+ *    a change to "user.preferences.theme" persists at "user.preferences").
+ * 2. Otherwise, use the first segment of the path (top-level key),
+ *    so "user.preferences.theme" → "user".
+ */
+function getPersistenceRoot(changePath) {
+    const configuredPaths = persistenceConfig.paths;
+    if (configuredPaths && configuredPaths.length > 0) {
+        // Find the configured path that is a parent of (or equal to) the change path
+        for (const configPath of configuredPaths) {
+            if (changePath === configPath || changePath.startsWith(configPath + '.')) {
+                return configPath;
+            }
+        }
+        // The change path might itself be a parent of a configured path — in that
+        // case we persist at the change path's top-level key
+    }
+    // Default: persist at the first-level key (e.g. "user", "todos", "counters")
+    return changePath.split('.')[0];
+}
+/**
+ * Check if a change path should be persisted (respects blacklist + paths config).
+ */
+function shouldPersistPath(path) {
+    if (!persistenceConfig.enabled)
+        return false;
+    // Check if path (or any of its ancestors) is blacklisted
+    const segments = path.split('.');
+    for (let i = 1; i <= segments.length; i++) {
+        const ancestor = segments.slice(0, i).join('.');
+        if (persistenceConfig.blacklist.some(b => b === ancestor)) {
+            return false;
+        }
+    }
+    // If paths array is empty/undefined, persist everything not blacklisted
+    if (!persistenceConfig.paths || persistenceConfig.paths.length === 0)
+        return true;
+    // Check if path falls under one of the configured persistence paths
+    return persistenceConfig.paths.some(persistedPath => path === persistedPath ||
+        path.startsWith(`${persistedPath}.`) ||
+        persistedPath.startsWith(`${path}.`));
+}
+/**
+ * Add a changed path to the persistence batch.
+ *
+ * The path is converted to its persistence root before being added,
+ * so multiple changes within the same slice (e.g. "user.name" and
+ * "user.preferences.theme") are deduplicated into a single "user" persist.
+ */
+function addToPersistenceBatch(path) {
+    if (!persistenceConfig.enabled || isHydrating || !hasHydrated)
+        return;
+    const pathKey = path.join('.');
+    if (shouldPersistPath(pathKey)) {
+        const root = getPersistenceRoot(pathKey);
+        persistenceBatch.roots.add(root);
+        schedulePersistenceBatch();
+    }
+}
+/**
+ * Schedule batch persistence with debounce
+ */
+function schedulePersistenceBatch() {
+    if (persistenceBatch.timeoutId) {
+        clearTimeout(persistenceBatch.timeoutId);
+    }
+    persistenceBatch.timeoutId = setTimeout(() => {
+        persistenceBatch.timeoutId = null;
+        processPersistenceBatch();
+    }, persistenceConfig.batchDelay);
+}
+/**
+ * Process all roots in the batch — persist each root-level slice.
  */
 function processPersistenceBatch() {
     if (typeof window === 'undefined')
         return;
-    if (persistenceBatch.isPersisting || persistenceBatch.paths.size === 0) {
+    if (persistenceBatch.isPersisting || persistenceBatch.roots.size === 0) {
         return;
     }
     persistenceBatch.isPersisting = true;
     let startTime = 0;
     if (monitoringConfig.enabled && monitoringConfig.logPersistence) {
-        startTime = logTimestamp(`💾 Batch persisting ${persistenceBatch.paths.size} paths`);
+        startTime = logTimestamp(`💾 Batch persisting ${persistenceBatch.roots.size} slices`);
     }
     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();
+        const roots = Array.from(persistenceBatch.roots);
+        persistenceBatch.roots.clear();
+        roots.forEach(root => {
+            persistSlice(root);
+        });
     }
     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) {
+        // If new roots were added during processing, schedule another batch
+        if (persistenceBatch.roots.size > 0) {
             schedulePersistenceBatch();
         }
         if (monitoringConfig.enabled && monitoringConfig.logPersistence && startTime > 0) {
@@ -1585,154 +1909,287 @@ function processPersistenceBatch() {
     }
 }
 /**
- * Schedule batch persistence with debounce
+ * Persist a single slice of the store to storage.
+ *
+ * @param rootPath - Dot-separated path like "user" or "user.preferences".
+ *                   The entire value at this path is serialized as one entry.
  */
-function schedulePersistenceBatch() {
-    if (persistenceBatch.timeoutId) {
-        clearTimeout(persistenceBatch.timeoutId);
+function persistSlice(rootPath) {
+    if (!persistenceConfig.enabled)
+        return;
+    if (!globalStoreRef) {
+        console.warn('Cannot persist state without store reference. Call configure() first.');
+        return;
+    }
+    const adapter = getStorageAdapter();
+    // Navigate to the value at this path in the store
+    const segments = rootPath.split('.');
+    let value = globalStoreRef;
+    for (const segment of segments) {
+        if (value === undefined || value === null)
+            return;
+        value = value[segment];
+    }
+    if (value === undefined)
+        return;
+    try {
+        const serialized = JSON.stringify(value);
+        const storageKey = `${PERSISTED_STATE_KEY}_${rootPath}`;
+        const result = adapter.setItem(storageKey, serialized);
+        if (result && typeof result.catch === 'function') {
+            result.catch(e => {
+                console.error(`Error persisting slice "${rootPath}":`, e);
+            });
+        }
+    }
+    catch (e) {
+        // JSON.stringify can fail on circular references or functions — that's fine,
+        // non-serializable values just won't be persisted.
+        if (monitoringConfig.enabled) {
+            console.warn(`Could not serialize slice "${rootPath}" for persistence:`, e);
+        }
     }
-    persistenceBatch.timeoutId = setTimeout(() => {
-        persistenceBatch.timeoutId = null;
-        processPersistenceBatch();
-    }, persistenceConfig.batchDelay);
 }
 /**
- * Add a path to the persistence batch
+ * Persist the entire store as one entry (used by persistenceAPI.persist).
  */
-function addToPersistenceBatch(path) {
-    if (!persistenceConfig.enabled)
+function persistEntireState() {
+    if (!persistenceConfig.enabled || !globalStoreRef)
         return;
-    const pathKey = path.join('.');
-    if (shouldPersistPath(pathKey)) {
-        persistenceBatch.paths.add(pathKey);
-        schedulePersistenceBatch();
+    const adapter = getStorageAdapter();
+    try {
+        const serialized = JSON.stringify(globalStoreRef);
+        const result = adapter.setItem(PERSISTED_STATE_KEY, serialized);
+        if (result && typeof result.catch === 'function') {
+            result.catch(e => {
+                console.error('Error persisting entire state:', e);
+            });
+        }
+    }
+    catch (e) {
+        console.error('Error persisting entire state:', e);
     }
 }
 /**
- * Function to determine if a path should be persisted
+ * Check if a value is a Promise/thenable.
  */
-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}.`));
+function isPromiseLike(value) {
+    return value !== null && value !== undefined && typeof value.then === 'function';
 }
 /**
- * Save state to storage
+ * Merge persisted data into the initial state object **before** the proxy is created.
+ *
+ * This is the fastest possible hydration path for synchronous adapters (localStorage,
+ * memory). Because the merge happens on a plain object — not through the proxy —
+ * there are no set traps, no `notifyListeners`, and no React re-renders. The proxy
+ * is then created wrapping the already-correct state, so components render with
+ * persisted values on their very first render.
+ *
+ * For async adapters (those wrapped in `createCachedAdapter`), this returns `null`
+ * and the caller falls back to the async `hydrateState()` path.
+ *
+ * @param initialState - The default state from the user's config. Not mutated.
+ * @returns A new state object with persisted data merged in, or `null` if the
+ *          adapter is async and synchronous merge isn't possible.
  */
-function persistState(path = []) {
+function mergePersistedIntoState(initialState) {
+    // No localStorage on the server
     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({}));
+        return null;
+    const adapter = getStorageAdapter();
+    // Cached/async adapters can't be read synchronously
+    if (typeof adapter.warmCache === 'function')
+        return null;
+    try {
+        // Shallow clone — persisted slices replace entire top-level values
+        const merged = { ...initialState };
+        // --- Full state blob (from persistenceAPI.persist) ---
+        const fullResult = adapter.getItem(PERSISTED_STATE_KEY);
+        if (isPromiseLike(fullResult))
+            return null;
+        if (fullResult) {
+            try {
+                const parsed = JSON.parse(fullResult);
+                Object.keys(parsed).forEach(key => {
+                    if (key in merged)
+                        merged[key] = parsed[key];
+                });
+            }
+            catch { /* skip malformed blob */ }
         }
-        catch (e) {
-            console.error(`Error persisting path ${pathKey}:`, e);
+        // --- Individual slice entries (persisted_state_user, etc.) ---
+        const keysResult = adapter.keys();
+        if (isPromiseLike(keysResult))
+            return null;
+        const allKeys = keysResult;
+        const sliceKeys = allKeys
+            .filter(key => key.startsWith(`${PERSISTED_STATE_KEY}_`))
+            .sort((a, b) => a.split('.').length - b.split('.').length);
+        const hydratedRoots = new Set();
+        for (const key of sliceKeys) {
+            const pathStr = key.replace(`${PERSISTED_STATE_KEY}_`, '');
+            // Respect blacklist
+            if (!shouldPersistPath(pathStr))
+                continue;
+            // Skip child entries if a parent was already merged
+            const isChild = Array.from(hydratedRoots).some(root => pathStr.startsWith(root + '.'));
+            if (isChild)
+                continue;
+            const valueResult = adapter.getItem(key);
+            if (isPromiseLike(valueResult))
+                return null;
+            const value = valueResult;
+            if (value) {
+                try {
+                    const parsedValue = JSON.parse(value);
+                    const segments = pathStr.split('.');
+                    if (segments.length === 1) {
+                        // Top-level key (common case) — direct assignment
+                        merged[segments[0]] = parsedValue;
+                    }
+                    else {
+                        // Nested path — navigate with shallow copies to avoid mutating original
+                        let current = merged;
+                        for (let i = 0; i < segments.length - 1; i++) {
+                            const seg = segments[i];
+                            if (current[seg] && typeof current[seg] === 'object') {
+                                current[seg] = Array.isArray(current[seg])
+                                    ? [...current[seg]]
+                                    : { ...current[seg] };
+                            }
+                            else {
+                                current[seg] = {};
+                            }
+                            current = current[seg];
+                        }
+                        current[segments[segments.length - 1]] = parsedValue;
+                    }
+                    hydratedRoots.add(pathStr);
+                }
+                catch { /* skip malformed entries */ }
+            }
         }
+        hasHydrated = true;
+        if (monitoringConfig.enabled && hydratedRoots.size > 0) {
+            console.log(`🔄 Merged ${hydratedRoots.size} persisted slices into initial state`);
+        }
+        return merged;
+    }
+    catch {
+        return null;
     }
 }
 /**
- * Hydrate state from storage
+ * Hydrate state from storage using the configured StorageAdapter (async path).
+ *
+ * This is the fallback for asynchronous adapters (e.g. AsyncStorage wrapped in
+ * `createCachedAdapter`). For synchronous adapters, `mergePersistedIntoState()`
+ * is used instead — it's faster because it avoids proxy overhead entirely.
+ *
+ * @param store - The store object to hydrate into. If omitted, uses the
+ *                global store set by `configure()`.
  */
 async function hydrateState(store) {
-    if (typeof window === 'undefined')
-        return false;
-    if (!store) {
-        console.warn('Cannot hydrate state without store reference');
+    // Prefer writing through the proxy so that set traps fire and components
+    // re-render with the hydrated values. Fall back to the raw store ref.
+    const writeTarget = store || globalProxyRef || globalStoreRef;
+    if (!writeTarget) {
+        console.warn('Cannot hydrate state without store reference. Call configure() first or pass a store.');
         return false;
     }
-    const currentStorage = getStorage();
-    if (!currentStorage)
-        return false;
+    const adapter = getStorageAdapter();
+    // If the adapter has a cache layer, warm it first so reads below are fast
+    if (typeof adapter.warmCache === 'function') {
+        await adapter.warmCache();
+    }
+    // Suppress persistence during hydration — writing through the proxy triggers
+    // the persistence callback, but we don't want to re-persist data we just loaded.
+    isHydrating = true;
     try {
-        // First try to load entire state
-        const savedState = await currentStorage.getItem(PERSISTED_STATE_KEY);
+        // First try to load the entire state blob (from persistenceAPI.persist)
+        const savedState = await adapter.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 (key in writeTarget) {
+                    writeTarget[key] = parsedState[key];
                 }
             });
             if (monitoringConfig.enabled) {
-                console.log('🔄 State hydrated from storage');
+                console.log('🔄 Full state hydrated from storage');
             }
         }
-        // Then try to load individual persisted paths
-        const keys = await currentStorage.keys();
-        if (!keys)
+        // Then load individual slice entries (persisted_state_user, persisted_state_todos, etc.)
+        const allKeys = await adapter.keys();
+        if (!allKeys)
             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]];
+        // Collect slice keys and sort by depth (shortest first) so parent slices
+        // are applied before child slices, ensuring correct overwrite order.
+        const sliceKeys = allKeys
+            .filter(key => key.startsWith(`${PERSISTED_STATE_KEY}_`))
+            .sort((a, b) => a.split('.').length - b.split('.').length);
+        // Track which root paths we've already hydrated so we don't
+        // apply stale child entries from the old fragmented format.
+        const hydratedRoots = new Set();
+        for (const key of sliceKeys) {
+            const pathStr = key.replace(`${PERSISTED_STATE_KEY}_`, '');
+            // Skip this entry if a parent slice was already hydrated
+            // (prevents old fragmented entries from overwriting clean slice data)
+            const isChildOfHydrated = Array.from(hydratedRoots).some(root => pathStr.startsWith(root + '.'));
+            if (isChildOfHydrated)
+                continue;
+            const path = pathStr.split('.');
+            const value = await adapter.getItem(key);
+            if (value) {
+                try {
+                    const parsedValue = JSON.parse(value);
+                    // Navigate to the parent in the store, writing through the proxy
+                    // so that set traps fire and components re-render.
+                    let current = writeTarget;
+                    for (let i = 0; i < path.length - 1; i++) {
+                        if (current[path[i]] === undefined || current[path[i]] === null) {
+                            current[path[i]] = {};
                         }
-                        const lastKey = path[path.length - 1];
-                        current[lastKey] = parsedValue;
-                    }
-                    catch (e) {
-                        console.error(`Error hydrating path ${path.join('.')}:`, e);
+                        current = current[path[i]];
                     }
+                    const lastKey = path[path.length - 1];
+                    current[lastKey] = parsedValue;
+                    // Mark this path as hydrated
+                    hydratedRoots.add(pathStr);
+                }
+                catch (e) {
+                    console.error(`Error hydrating path "${pathStr}":`, e);
                 }
             }
         }
-        if (monitoringConfig.enabled) {
-            console.log(`🔄 Hydrated ${keys.length} individual paths`);
+        if (monitoringConfig.enabled && sliceKeys.length > 0) {
+            console.log(`🔄 Hydrated ${hydratedRoots.size} slices from storage`);
         }
     }
     catch (e) {
         console.error('Error hydrating state:', e);
         return false;
     }
+    finally {
+        isHydrating = false;
+        // Enable persistence now that the store has been hydrated.
+        // Any writes from this point forward are intentional user changes.
+        hasHydrated = true;
+    }
     return true;
 }
 /**
  * Load persistence configuration
  */
 async function loadPersistenceConfig() {
-    if (typeof window === 'undefined')
-        return;
-    const currentStorage = getStorage();
-    if (!currentStorage)
-        return;
+    const adapter = getStorageAdapter();
     try {
-        const config = await currentStorage.getItem(PERSISTENCE_CONFIG_KEY);
+        const config = await adapter.getItem(PERSISTENCE_CONFIG_KEY);
         if (config) {
             const parsedConfig = JSON.parse(config);
-            Object.assign(persistenceConfig, parsedConfig);
+            // Only restore serializable config fields (not the adapter itself, not autoHydrate)
+            const { storageAdapter: _a, autoHydrate: _b, ...restConfig } = parsedConfig;
+            Object.assign(persistenceConfig, restConfig);
         }
     }
     catch (e) {
@@ -1740,23 +2197,26 @@ async function loadPersistenceConfig() {
     }
 }
 /**
- * Save persistence configuration
+ * Save persistence configuration (excluding non-serializable fields)
  */
 function savePersistenceConfig() {
-    if (typeof window === 'undefined')
-        return;
-    const currentStorage = getStorage();
-    if (!currentStorage)
-        return;
+    const adapter = getStorageAdapter();
     try {
-        currentStorage.setItem(PERSISTENCE_CONFIG_KEY, JSON.stringify(persistenceConfig));
+        // Exclude the storageAdapter and autoHydrate from serialization
+        const { storageAdapter: _a, autoHydrate: _b, ...serializableConfig } = persistenceConfig;
+        const result = adapter.setItem(PERSISTENCE_CONFIG_KEY, JSON.stringify(serializableConfig));
+        if (result && typeof result.catch === 'function') {
+            result.catch(e => {
+                console.error('Error saving persistence configuration:', e);
+            });
+        }
     }
     catch (e) {
         console.error('Error saving persistence configuration:', e);
     }
 }
 /**
- * Persistence API - matches the original implementation
+ * Persistence API — the public interface for controlling persistence at runtime.
  */
 const persistenceAPI = {
     // Enable or disable persistence
@@ -1781,24 +2241,30 @@ const persistenceAPI = {
             savePersistenceConfig();
         }
         // Remove from storage
-        const currentStorage = getStorage();
-        if (currentStorage) {
-            paths.forEach(path => {
-                currentStorage.removeItem(`${PERSISTED_STATE_KEY}_${path}`);
-            });
-        }
+        const adapter = getStorageAdapter();
+        paths.forEach(path => {
+            const result = adapter.removeItem(`${PERSISTED_STATE_KEY}_${path}`);
+            if (result && typeof result.catch === 'function') {
+                result.catch(e => {
+                    console.error(`Error removing persisted path "${path}":`, e);
+                });
+            }
+        });
     },
     // 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}`);
-            });
-        }
+        const adapter = getStorageAdapter();
+        paths.forEach(path => {
+            const result = adapter.removeItem(`${PERSISTED_STATE_KEY}_${path}`);
+            if (result && typeof result.catch === 'function') {
+                result.catch(e => {
+                    console.error(`Error removing blacklisted path "${path}":`, e);
+                });
+            }
+        });
     },
     // Remove paths from blacklist
     unblacklistPaths: (paths) => {
@@ -1812,31 +2278,38 @@ const persistenceAPI = {
         persistenceConfig.batchDelay = delay;
         savePersistenceConfig();
     },
-    // Reset persistence
+    // Reset persistence — clears all persisted data and resets config to defaults
     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);
+        const adapter = getStorageAdapter();
+        // Use clear() if available, otherwise iterate and remove
+        if (adapter.clear) {
+            await adapter.clear();
+        }
+        else {
+            const keys = await adapter.keys();
+            if (keys) {
+                for (const key of keys) {
+                    if (key.startsWith(PERSISTED_STATE_KEY)) {
+                        await adapter.removeItem(key);
+                    }
                 }
             }
         }
-        // Reset configuration to defaults
+        // Reset configuration to defaults (preserve the current storageAdapter and autoHydrate)
+        const currentAdapter = persistenceConfig.storageAdapter;
+        const currentAutoHydrate = persistenceConfig.autoHydrate;
         Object.assign(persistenceConfig, {
             enabled: true,
             paths: [],
             blacklist: [],
             batchDelay: 300,
+            storageAdapter: currentAdapter,
+            autoHydrate: currentAutoHydrate,
         });
         savePersistenceConfig();
     },
-    // Force persist current state
-    persist: () => persistState(),
+    // Force persist the entire store as one blob
+    persist: () => persistEntireState(),
     // Force persist current batch immediately
     flushBatch: () => {
         if (persistenceBatch.timeoutId) {
@@ -1845,26 +2318,41 @@ const persistenceAPI = {
         }
         processPersistenceBatch();
     },
-    // Force rehydrate state
+    /**
+     * Manually hydrate state from the backing storage adapter.
+     *
+     * Use this when `autoHydrate` is `false` and you want to control
+     * exactly when persisted data is loaded (e.g., after a splash screen).
+     *
+     * @param store - Optional store to hydrate into. Defaults to the global store.
+     */
     rehydrate: (store) => hydrateState(store),
     // Get batch status
     getBatchStatus: () => ({
-        pendingPaths: Array.from(persistenceBatch.paths),
+        pendingRoots: Array.from(persistenceBatch.roots),
         isPersisting: persistenceBatch.isPersisting,
-        batchSize: persistenceBatch.paths.size,
+        batchSize: persistenceBatch.roots.size,
     }),
 };
 /**
- * Initialize persistence system
+ * Initialize persistence system.
+ *
+ * @param willAutoHydrate - Whether hydrateState will be called automatically.
+ *   If false (autoHydrate disabled), persistence is enabled immediately since
+ *   the developer will manually call rehydrate() when ready.
  */
-function initializePersistence() {
-    if (typeof window !== 'undefined') {
-        loadPersistenceConfig();
-        console.log('💾 Advanced persistence system initialized');
+function initializePersistence(willAutoHydrate = true) {
+    loadPersistenceConfig();
+    // If auto-hydration is disabled, the developer is in control.
+    // Enable persistence immediately so state changes before manual rehydrate()
+    // are captured. When they call rehydrate(), hasHydrated will be set again.
+    if (!willAutoHydrate) {
+        hasHydrated = true;
+    }
+    if (typeof window !== 'undefined' && monitoringConfig.enabled) {
+        console.log('💾 Persistence system initialized');
     }
 }
-// Initialize automatically
-initializePersistence();
 
 // Main exports for the library
 // Global state
@@ -1888,26 +2376,55 @@ function configure(config) {
         Object.assign(monitoringConfig, config.monitoring);
     }
     if (config.persistence) {
+        // Register the storage adapter before applying config so it's ready for reads
+        if (config.persistence.storageAdapter) {
+            setStorageAdapter(config.persistence.storageAdapter);
+        }
         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');
+    // ─── Build the store state ───────────────────────────────────────────
+    // For synchronous adapters (localStorage, memory), merge persisted data
+    // into the initial state BEFORE creating the proxy. This way the proxy
+    // wraps the already-correct data and React renders persisted values on
+    // the very first render — no flash of defaults, no re-renders.
+    const originalDefaults = config.initialState;
+    const shouldAutoHydrate = persistenceConfig.enabled && persistenceConfig.autoHydrate !== false;
+    let syncMerged = false;
+    if (shouldAutoHydrate && originalDefaults) {
+        const merged = mergePersistedIntoState(originalDefaults);
+        if (merged) {
+            globalStore = merged;
+            syncMerged = true;
+        }
+        else {
+            globalStore = { ...originalDefaults };
         }
     }
+    else if (originalDefaults) {
+        globalStore = { ...originalDefaults };
+    }
+    // Store original defaults for $reset() (always the un-merged defaults)
+    setInitialStoreState(originalDefaults || globalStore);
+    if (typeof window !== 'undefined' && monitoringConfig.enabled) {
+        console.log('🏪 Store configured with custom state');
+    }
+    // Store raw store ref (used for serialization during persistence)
+    setGlobalStoreRef(globalStore);
     // 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');
-            }
-        });
+    // Store proxy ref (used for writes during hydration so set traps fire)
+    setGlobalProxyRef(globalStoreProxy);
+    // ─── Persistence setup ───────────────────────────────────────────────
+    if (persistenceConfig.enabled) {
+        initializePersistence(shouldAutoHydrate);
+        // If sync merge didn't work (async adapter), fall back to async hydration
+        if (shouldAutoHydrate && !syncMerged) {
+            hydrateState(globalStoreProxy).then((success) => {
+                if (success && typeof window !== 'undefined' && monitoringConfig.enabled) {
+                    console.log('🔄 State hydrated from persistence (async)');
+                }
+            });
+        }
     }
     if (typeof window !== 'undefined' && monitoringConfig.enabled) {
         console.log('🔧 Scope configured with advanced features');
@@ -2010,18 +2527,23 @@ function $get(path) {
     }
     return getProxy(path);
 }
+// Register the persistence callback so state changes are automatically batched for persistence.
+// This connects the proxy notification system (listeners.ts) to the persistence system (advanced.ts)
+// without creating circular dependencies.
+setOnStateChangeCallback((path) => {
+    if (persistenceConfig.enabled) {
+        addToPersistenceBatch(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();
     }
 };
@@ -2029,14 +2551,9 @@ const debugInfo = {
 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);
+    if (monitoringConfig.enabled) {
+        console.log('🎯 Scope State initialized — ready for reactive state management');
+        console.log('💡 Tip: Call configure() with your initialState for full TypeScript support');
     }
 }
 
@@ -2048,14 +2565,21 @@ exports.activate = activate;
 exports.clearProxyCache = clearProxyCache;
 exports.configure = configure;
 exports.createAdvancedProxy = createAdvancedProxy;
+exports.createCachedAdapter = createCachedAdapter;
+exports.createLocalStorageAdapter = createLocalStorageAdapter;
+exports.createMemoryAdapter = createMemoryAdapter;
 exports.createReactive = createReactive;
 exports.debugInfo = debugInfo;
 exports.getConfig = getConfig;
+exports.getDefaultAdapter = getDefaultAdapter;
 exports.getProxy = getProxy;
 exports.getProxyCacheStats = getProxyCacheStats;
+exports.getStorageAdapter = getStorageAdapter;
 exports.getStore = getStore;
+exports.hydrateState = hydrateState;
 exports.initializeStore = initializeStore;
 exports.isReactive = isReactive;
+exports.mergePersistedIntoState = mergePersistedIntoState;
 exports.monitorAPI = monitorAPI;
 exports.optimizeMemoryUsage = optimizeMemoryUsage;
 exports.pathUsageStats = pathUsageStats;
@@ -2067,6 +2591,7 @@ exports.resetConfig = resetConfig;
 exports.resetStore = resetStore;
 exports.selectorPaths = selectorPaths;
 exports.setInitialStoreState = setInitialStoreState;
+exports.setStorageAdapter = setStorageAdapter;
 exports.trackDependenciesAdvanced = trackDependenciesAdvanced;
 exports.useLocal = useLocal;
 exports.useScope = useScope;