scope-state 0.1.5 → 0.1.7

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;AAUlE,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;AAsTD;;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/core/tracking.d.ts

@@ -1,5 +1,5 @@
 /**
- * Track dependencies during selector execution - tracks individual path segments
+ * Track dependencies during selector execution - tracks full dotted paths
  */
 export declare function trackDependencies<T>(selector: () => T): {
     value: T;
@@ -13,16 +13,28 @@ export declare function isCurrentlyTracking(): boolean;
  * Temporarily skip tracking (for array method internals)
  */
 export declare function skipTracking<T>(fn: () => T): T;
+/**
+ * Run fn while capturing any newly tracked paths, then remove them from the main set.
+ * Caller decides whether to re-add captured paths (e.g. on a matched find iteration).
+ */
+export declare function capturePathsDuring<T>(fn: () => T): {
+    value: T;
+    paths: string[];
+};
+/**
+ * Add paths to the active tracking set (used by smart array method overrides)
+ */
+export declare function addTrackedPaths(paths: string[]): void;
 /**
  * Get current tracking state (for debugging)
  */
 export declare function getTrackingState(): {
     isTracking: boolean;
-    currentPath: string[];
+    trackedPaths: string[];
     skipDepth: number;
 };
 /**
- * Add a path segment to tracking during proxy get operations
+ * Add a full path to tracking during proxy get operations
  */
 export declare function trackPathAccess(path: string[]): void;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/core/tracking.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAqBrF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAO9C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAMA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAepD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAQ1D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAIpC"}
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/core/tracking.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBrF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAO9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAahF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAGrD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAMA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CASpD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAK1D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAIpC"}

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,CAiEJ"}
+{"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,CA6ElB"}

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('.'));
@@ -813,27 +780,40 @@ function addArrayMethods(target, path) {
         writable: true,
         configurable: true
     });
+    // Override find with smart tracking during dependency collection
+    Object.defineProperty(target, 'find', {
+        value: function (predicate, thisArg) {
+            if (!isCurrentlyTracking() || !proxyConfig.smartArrayTracking) {
+                return Array.prototype.find.call(this, predicate, thisArg);
+            }
+            const currentPath = proxyPathMap.get(this) || path;
+            const length = skipTracking(() => this.length);
+            for (let i = 0; i < length; i++) {
+                const element = skipTracking(() => Reflect.get(this, i));
+                const { value: matched, paths } = capturePathsDuring(() => Boolean(predicate.call(thisArg, element, i, this)));
+                if (matched) {
+                    addTrackedPaths([[...currentPath, String(i)].join('.')]);
+                    addTrackedPaths(paths);
+                    return element;
+                }
+            }
+            return undefined;
+        },
+        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]);
+            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 +834,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 +866,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);
@@ -976,48 +942,125 @@ function optimizeMemoryUsage(aggressive = false) {
     };
 }
 
-// Track the current path we're accessing during a selector function
-let currentPath = [];
+// Unique full dotted paths accessed during selector execution
+let trackedPaths = new Set();
 let isTracking = false;
 let skipTrackingDepth = 0;
 /**
- * Track dependencies during selector execution - tracks individual path segments
+ * Track dependencies during selector execution - tracks full dotted paths
  */
 function trackDependencies(selector) {
-    // Start tracking
     isTracking = true;
-    currentPath = [];
+    trackedPaths = new Set();
     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
-        return segment && segment.length < 100; // Basic length check for individual segments
+    const paths = Array.from(trackedPaths).filter(path => path && path.length < 500);
+    trackedPaths = new Set();
+    return { value, paths };
+}
+/**
+ * Check if we're currently tracking dependencies
+ */
+function isCurrentlyTracking() {
+    return isTracking && skipTrackingDepth === 0;
+}
+/**
+ * Temporarily skip tracking (for array method internals)
+ */
+function skipTracking(fn) {
+    skipTrackingDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        skipTrackingDepth--;
+    }
+}
+/**
+ * Run fn while capturing any newly tracked paths, then remove them from the main set.
+ * Caller decides whether to re-add captured paths (e.g. on a matched find iteration).
+ */
+function capturePathsDuring(fn) {
+    const snapshot = new Set(trackedPaths);
+    const value = fn();
+    const newPaths = [];
+    trackedPaths.forEach(path => {
+        if (!snapshot.has(path)) {
+            newPaths.push(path);
+            trackedPaths.delete(path);
+        }
     });
-    currentPath = [];
-    return { value, paths: cleanedPaths };
+    return { value, paths: newPaths };
+}
+/**
+ * Add paths to the active tracking set (used by smart array method overrides)
+ */
+function addTrackedPaths(paths) {
+    if (!isTracking)
+        return;
+    paths.forEach(path => trackedPaths.add(path));
 }
 /**
- * Add a path segment to tracking during proxy get operations
+ * Add a full path 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
+    if (path.length <= proxyConfig.maxPathLength) {
         const fullPath = path.join('.');
+        trackedPaths.add(fullPath);
         pathUsageStats.accessedPaths.add(fullPath);
         selectorPaths.add(fullPath);
     }
 }
 
+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 +1068,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 +1086,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 {
@@ -1078,11 +1124,7 @@ function useScope(selector) {
                 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
-            ? trackedPaths.map((_, index, array) => array.slice(0, index + 1).join('.'))
-            : [''];
+        const pathKeys = trackedPaths.length > 0 ? trackedPaths : [''];
         // Subscribe to all relevant paths
         const unsubscribeFunctions = pathKeys.map(pathKey => {
             // Mark this path as subscribed for usage tracking
@@ -1094,8 +1136,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;
 }
 
 /**