scope-state 0.1.4 → 0.1.6

package/README.md

@@ -170,7 +170,10 @@ const TodoList = () => {
 ### Core Functions
 
 #### `useScope(selector)`
-Subscribe to reactive state changes.
+Subscribe to reactive state changes and receive a read-only snapshot for rendering.
+
+Mutate state through the main `$` proxy. The value returned from `useScope()` is
+intended for reads only.
 
 ```tsx
 // Subscribe to entire object
@@ -184,6 +187,10 @@ const isAdmin = useScope(() => $.user.role === 'admin');
 
 // Subscribe to array
 const todos = useScope(() => $.todos);
+
+// Mutate through the main store proxy
+$.user.$merge({ name: 'John' });
+$.todos.push({ id: 1, text: 'Ship feature', completed: false });
 ```
 
 #### `configure(options)`

package/dist/core/proxy.d.ts

@@ -1,5 +1,6 @@
 import type { CustomMethods, CustomArrayMethods } from '../types';
 export declare const proxyPathMap: WeakMap<object, string[]>;
+export declare const proxyTargetMap: WeakMap<object, object>;
 export declare const pathUsageStats: {
     accessedPaths: Set<string>;
     modifiedPaths: Set<string>;

package/dist/core/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/core/proxy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAIlE,eAAO,MAAM,YAAY,2BAAkC,CAAC;AAM5D,eAAO,MAAM,cAAc;;;;CAI1B,CAAC;AAGF,eAAO,MAAM,aAAa,aAAoB,CAAC;AAM/C,eAAO,MAAM,eAAe;;;;;CAK3B,CAAC;AAiGF,eAAO,MAAM,cAAc;;;;;;2BA4CF,MAAM;CAS9B,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAErD;AAYD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,MAAM,EAAE,CAAC,EACT,IAAI,GAAE,MAAM,EAAO,EACnB,KAAK,GAAE,MAAU,GAChB,CAAC,GAAG,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CA4JrE;AA8UD;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAUtC;AAED;;GAEG;AACH,wBAAgB,kBAAkB;;;;;;;EAMjC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,UAAQ,GAAG,GAAG,CA4B3D"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/core/proxy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAIlE,eAAO,MAAM,YAAY,2BAAkC,CAAC;AAC5D,eAAO,MAAM,cAAc,yBAAgC,CAAC;AAM5D,eAAO,MAAM,cAAc;;;;CAI1B,CAAC;AAGF,eAAO,MAAM,aAAa,aAAoB,CAAC;AAM/C,eAAO,MAAM,eAAe;;;;;CAK3B,CAAC;AAiGF,eAAO,MAAM,cAAc;;;;;;2BA4CF,MAAM;CAS9B,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAErD;AAYD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,MAAM,EAAE,CAAC,EACT,IAAI,GAAE,MAAM,EAAO,EACnB,KAAK,GAAE,MAAU,GAChB,CAAC,GAAG,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAwJrE;AAqRD;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAUtC;AAED;;GAEG;AACH,wBAAgB,kBAAkB;;;;;;;EAMjC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,UAAQ,GAAG,GAAG,CA4B3D"}

package/dist/core/snapshot.d.ts

@@ -0,0 +1,9 @@
+import type { ScopeSnapshot } from '../types';
+/**
+ * Create a read-only snapshot suitable for rendering.
+ *
+ * Snapshots are plain arrays/objects with no proxy methods, which makes them
+ * safe for React Compiler memoization while keeping `$` as the mutable API.
+ */
+export declare function createReadonlySnapshot<T>(value: T, seen?: WeakMap<object, unknown>): ScopeSnapshot<T>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/core/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/core/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAgB9C;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,CAAC,EACR,IAAI,2BAAiC,GACpC,aAAa,CAAC,CAAC,CAAC,CAsClB"}

package/dist/hooks/useScope.d.ts

@@ -1,4 +1,4 @@
-import type { CustomMethods, CustomArrayMethods } from '../types';
+import type { ScopeSnapshot } from '../types';
 /**
  * Hook to subscribe to the global store and re-render when specific data changes.
  *
@@ -6,15 +6,16 @@ import type { CustomMethods, CustomArrayMethods } from '../types';
  * 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.
+ * The returned value is a read-only snapshot of the selected state. Mutate the
+ * store through the main `$` proxy (or a proxy created explicitly for commands),
+ * and use the hook return value only for rendering.
  *
  * @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' });
+ * // Mutate through the main store proxy
+ * $.user.$merge({ name: 'New Name' });
  *
  * // Subscribe to a specific property
  * const userName = useScope(() => $.user.name);
@@ -23,7 +24,7 @@ import type { CustomMethods, CustomArrayMethods } from '../types';
  * 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
+ * @returns A read-only snapshot of the selected data
  */
-export declare function useScope<T>(selector: () => T): T extends object ? T & CustomMethods<T> : T extends Array<infer U> ? U[] & CustomArrayMethods<U> : T;
+export declare function useScope<T>(selector: () => T): ScopeSnapshot<T>;
 //# sourceMappingURL=useScope.d.ts.map

package/dist/hooks/useScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useScope.d.ts","sourceRoot":"","sources":["../../src/hooks/useScope.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,CAAC,GAChB,CAAC,SAAS,MAAM,GACf,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GACpB,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACxB,CAAC,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAC3B,CAAC,CAsDJ"}
+{"version":3,"file":"useScope.d.ts","sourceRoot":"","sources":["../../src/hooks/useScope.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,CAAC,GAChB,aAAa,CAAC,CAAC,CAAC,CAiFlB"}

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { persistenceAPI, hydrateState, mergePersistedIntoState } from './persist
 export { createLocalStorageAdapter, createMemoryAdapter, createCachedAdapter, getDefaultAdapter } from './persistence/adapters';
 export { setStorageAdapter, getStorageAdapter } from './persistence/storage';
 export { setInitialStoreState, createAdvancedProxy, pathUsageStats, selectorPaths, clearProxyCache, getProxyCacheStats, optimizeMemoryUsage, proxyPathMap } from './core/proxy';
-export type { ScopeConfig, ProxyConfig, MonitoringConfig, PersistenceConfig, StorageAdapter, MaybePromise, CustomMethods, CustomArrayMethods, StoreType, MonitoringStats, ProxyCacheStats, PathUsageStats } from './types';
+export type { ScopeConfig, ProxyConfig, MonitoringConfig, PersistenceConfig, StorageAdapter, MaybePromise, CustomMethods, CustomArrayMethods, ScopeSnapshot, StoreType, MonitoringStats, ProxyCacheStats, PathUsageStats } from './types';
 import type { StoreType, CustomMethods, CustomArrayMethods, ScopeConfig } from './types';
 /**
  * Configure Scope with custom settings and return a properly typed store

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAIrE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChI,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,eAAe,EACf,cAAc,EACf,MAAM,SAAS,CAAC;AASjB,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAYzF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GACrB,SAAS,CAAC,CAAC,CAAC,CAwEd;AAGD,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAqB7F;AASD,eAAO,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,CAAoB,CAAC;AAGlD,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAE5H;AAGD,eAAO,MAAM,MAAM,uBAAiB,CAAC;AAGrC,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAE5C;AAGD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAyBrC;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAEtC;AAED,wBAAgB,QAAQ,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC,CAsClE;AAED,wBAAgB,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAK5D;AAYD,eAAO,MAAM,SAAS;;;;CAUrB,CAAC;AAGF,eAAO,MAAM,QAAQ,KAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAIrE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAC/F,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChI,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,SAAS,EACT,eAAe,EACf,eAAe,EACf,cAAc,EACf,MAAM,SAAS,CAAC;AASjB,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAYzF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GACrB,SAAS,CAAC,CAAC,CAAC,CAwEd;AAGD,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAqB7F;AASD,eAAO,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,CAAoB,CAAC;AAGlD,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAE5H;AAGD,eAAO,MAAM,MAAM,uBAAiB,CAAC;AAGrC,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAE5C;AAGD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAyBrC;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAEtC;AAED,wBAAgB,QAAQ,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC,CAsClE;AAED,wBAAgB,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAK5D;AAYD,eAAO,MAAM,SAAS;;;;CAUrB,CAAC;AAGF,eAAO,MAAM,QAAQ,KAAc,CAAC"}

package/dist/index.esm.js

@@ -351,6 +351,7 @@ function logSubscriptionRemoved(path) {
 
 // Track proxy to path mapping for type-safe activation
 const proxyPathMap = new WeakMap();
+const proxyTargetMap = new WeakMap();
 // Store a deep clone of the initial store state for use with $reset
 let initialStoreState$1 = {};
 // Path usage tracking
@@ -568,6 +569,11 @@ function createAdvancedProxy(target, path = [], depth = 0) {
             if (typeof prop === 'symbol') {
                 return Reflect.get(obj, prop, receiver);
             }
+            const value = Reflect.get(obj, prop, receiver);
+            // Functions are commands/helpers, not reactive data dependencies.
+            if (typeof value === 'function') {
+                return value;
+            }
             const currentPropPath = [...path, prop.toString()];
             const propPathKey = currentPropPath.join('.');
             // Track path access during dependency tracking
@@ -578,9 +584,12 @@ function createAdvancedProxy(target, path = [], depth = 0) {
             }
             // Track path access for dependency tracking (inline to avoid circular dependency)
             trackPathAccess(currentPropPath);
-            const value = obj[prop];
             // For objects, create proxies for nested values
             if (value && typeof value === 'object' && path.length < proxyConfig.maxDepth) {
+                // If value is already a proxy, return it directly to prevent double-wrapping
+                if (proxyPathMap.has(value)) {
+                    return value;
+                }
                 const shouldProxy = !proxyConfig.lazyProxyDeepObjects ||
                     pathUsageStats.accessedPaths.has(propPathKey) ||
                     pathUsageStats.modifiedPaths.has(propPathKey) ||
@@ -592,27 +601,16 @@ function createAdvancedProxy(target, path = [], depth = 0) {
             }
             return value;
         },
-        set(obj, prop, value, receiver) {
+        set(obj, prop, value) {
             if (typeof prop === 'symbol') {
-                return Reflect.set(obj, prop, value, receiver);
+                return Reflect.set(obj, prop, value);
             }
             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)
+            const result = Reflect.set(obj, prop, value);
             notifyListeners(propPath);
             return result;
         },
@@ -638,6 +636,7 @@ function createAdvancedProxy(target, path = [], depth = 0) {
     proxyCacheLRU.add(target, proxy);
     // Track the path for this proxy
     proxyPathMap.set(proxy, [...path]);
+    proxyTargetMap.set(proxy, target);
     return proxy;
 }
 /**
@@ -654,16 +653,7 @@ function addObjectMethods(target, path) {
                         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);
-                    }
+                    Reflect.set(this, key, newProps[key], this);
                 });
                 return this;
             },
@@ -674,28 +664,17 @@ function addObjectMethods(target, path) {
         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);
-                    }
+                    Reflect.set(this, key, newProps[key], this);
                 });
                 return this;
             },
@@ -725,12 +704,7 @@ function addObjectMethods(target, path) {
                     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
+                const newValue = updater(currentValue);
                 Reflect.set(this, key, newValue, this);
                 return this;
             },
@@ -788,20 +762,13 @@ function addObjectMethods(target, path) {
  * Add custom methods to array targets
  */
 function addArrayMethods(target, path) {
-    const originalPush = target.push;
-    const originalSplice = target.splice;
+    const originalPush = Array.prototype.push;
+    const originalSplice = Array.prototype.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);
+            const result = originalPush.apply(this, items);
             if (currentPath.length > 0) {
                 if (proxyConfig.trackPathUsage) {
                     pathUsageStats.modifiedPaths.add(currentPath.join('.'));
@@ -818,22 +785,13 @@ function addArrayMethods(target, path) {
         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]);
+            const result = originalSplice.apply(this, [start, actualDeleteCount, ...items]);
             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);
@@ -854,14 +812,7 @@ function addArrayMethods(target, path) {
                 }
                 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);
+                originalPush.apply(this, newArray);
                 if (currentPath.length > 0) {
                     if (proxyConfig.trackPathUsage) {
                         pathUsageStats.modifiedPaths.add(currentPath.join('.'));
@@ -893,15 +844,8 @@ function addArrayMethods(target, path) {
                     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 (initialValue.length > 0) {
+                    originalPush.apply(this, JSON.parse(JSON.stringify(initialValue)));
                 }
                 if (currentPath.length > 0) {
                     notifyListeners(currentPath);
@@ -1018,6 +962,52 @@ function trackPathAccess(path) {
     }
 }
 
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function unwrapProxyTarget(value) {
+    if (value && typeof value === 'object' && proxyTargetMap.has(value)) {
+        return proxyTargetMap.get(value);
+    }
+    return value;
+}
+/**
+ * Create a read-only snapshot suitable for rendering.
+ *
+ * Snapshots are plain arrays/objects with no proxy methods, which makes them
+ * safe for React Compiler memoization while keeping `$` as the mutable API.
+ */
+function createReadonlySnapshot(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    const source = unwrapProxyTarget(value);
+    if (seen.has(source)) {
+        return seen.get(source);
+    }
+    if (Array.isArray(source)) {
+        const snapshot = [];
+        seen.set(source, snapshot);
+        source.forEach(item => {
+            snapshot.push(createReadonlySnapshot(item, seen));
+        });
+        return snapshot;
+    }
+    if (!isPlainObject(source)) {
+        return source;
+    }
+    const snapshot = {};
+    seen.set(source, snapshot);
+    Object.keys(source).forEach(key => {
+        const propertyValue = source[key];
+        if (typeof propertyValue !== 'function') {
+            snapshot[key] = createReadonlySnapshot(propertyValue, seen);
+        }
+    });
+    return snapshot;
+}
+
 /**
  * Hook to subscribe to the global store and re-render when specific data changes.
  *
@@ -1025,15 +1015,16 @@ function trackPathAccess(path) {
  * 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.
+ * The returned value is a read-only snapshot of the selected state. Mutate the
+ * store through the main `$` proxy (or a proxy created explicitly for commands),
+ * and use the hook return value only for rendering.
  *
  * @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' });
+ * // Mutate through the main store proxy
+ * $.user.$merge({ name: 'New Name' });
  *
  * // Subscribe to a specific property
  * const userName = useScope(() => $.user.name);
@@ -1042,22 +1033,24 @@ function trackPathAccess(path) {
  * 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
+ * @returns A read-only snapshot of the selected data
  */
 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);
+    const snapshotCacheRef = useRef({
+        revision: -1,
+        source: undefined,
+        snapshot: undefined,
+    });
+    // Track dependencies and get the selected value from the store
+    const { value: selectedValue, 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);
+    // Use a counter to invalidate the cached snapshot only when this hook
+    // receives a relevant store notification.
+    const [revision, forceUpdate] = useState(0);
     // Create stable update handler that forces re-render
     const handleChange = useCallback(() => {
         try {
@@ -1068,6 +1061,16 @@ function useScope(selector) {
         }
     }, []);
     useEffect(() => {
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(() => {
+                handleChange();
+            });
+        }
+        else {
+            setTimeout(() => {
+                handleChange();
+            }, 16);
+        }
         // 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
@@ -1084,8 +1087,18 @@ function useScope(selector) {
             unsubscribeFunctions.forEach(unsubscribe => unsubscribe());
         };
     }, [trackedPaths.join(','), handleChange]); // Stable dependencies
-    // Always return the fresh result from the selector (preserves proxy and methods)
-    return selectorRef.current();
+    if (selectedValue === null || typeof selectedValue !== 'object') {
+        return selectedValue;
+    }
+    if (snapshotCacheRef.current.revision !== revision ||
+        snapshotCacheRef.current.source !== selectedValue) {
+        snapshotCacheRef.current = {
+            revision,
+            source: selectedValue,
+            snapshot: createReadonlySnapshot(selectedValue),
+        };
+    }
+    return snapshotCacheRef.current.snapshot;
 }
 
 /**