lume-js 0.3.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required, no framework lock-in.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.2.1-green.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.4.0-green.svg)](package.json)
 
 ## Why Lume.js?
 
@@ -43,7 +43,10 @@ npm install lume-js
 
 ```html
 <script type="module">
-  import { state, bindDom } from 'https://cdn.jsdelivr.net/npm/lume-js/src/index.js';
+  import { state, bindDom, effect } from 'https://cdn.jsdelivr.net/npm/lume-js/src/index.js';
+  
+  // For addons:
+  import { computed, watch } from 'https://cdn.jsdelivr.net/npm/lume-js/src/addons/index.js';
 </script>
 ```
 
@@ -51,6 +54,16 @@ npm install lume-js
 
 ## Quick Start
 
+### Examples
+
+Run the live examples (including the new Todo app) with Vite:
+
+```bash
+npm run dev
+```
+
+Then open the Examples index (Vite will auto-open): `http://localhost:5173/examples/`
+
 **HTML:**
 ```html
 <div>
@@ -64,7 +77,7 @@ npm install lume-js
 
 **JavaScript:**
 ```javascript
-import { state, bindDom } from 'lume-js';
+import { state, bindDom, effect } from 'lume-js';
 
 // Create reactive state
 const store = state({
@@ -72,16 +85,24 @@ const store = state({
   name: 'World'
 });
 
-// Bind to DOM
+// Bind to DOM (updates on state changes)
 const cleanup = bindDom(document.body, store);
 
+// Auto-update document title when name changes
+const effectCleanup = effect(() => {
+  document.title = `Hello, ${store.name}!`;
+});
+
 // Update state with standard JavaScript
 document.getElementById('increment').addEventListener('click', () => {
   store.count++;
 });
 
 // Cleanup when done (important!)
-window.addEventListener('beforeunload', () => cleanup());
+window.addEventListener('beforeunload', () => {
+  cleanup();
+  effectCleanup();
+});
 ```
 
 That's it! No build step, no custom syntax, just HTML and JavaScript.
@@ -92,7 +113,7 @@ That's it! No build step, no custom syntax, just HTML and JavaScript.
 
 ### `state(object)`
 
-Creates a reactive state object using Proxy.
+Creates a reactive state object using Proxy with automatic dependency tracking.
 
 ```javascript
 const store = state({
@@ -109,9 +130,39 @@ store.user.name = 'Bob';
 ```
 
 **Features:**
+- ✅ Automatic dependency tracking for effects
+- ✅ Per-state microtask batching for performance
 - ✅ Validates input (must be plain object)
 - ✅ Only triggers updates when value actually changes
 - ✅ Returns cleanup function from `$subscribe`
+- ✅ Deduplicates effect runs per flush cycle
+
+### `effect(fn)`
+
+Creates an effect that automatically tracks dependencies and re-runs when they change.
+
+```javascript
+const store = state({ count: 0, name: 'Alice' });
+
+const cleanup = effect(() => {
+  // Only tracks 'count' (name is not accessed)
+  console.log(`Count: ${store.count}`);
+});
+
+store.count = 5;    // Effect re-runs
+store.name = 'Bob'; // Effect does NOT re-run
+
+cleanup(); // Stop the effect
+```
+
+**Features:**
+- ✅ Automatic dependency collection (tracks what you actually access)
+- ✅ Dynamic dependencies (re-tracks on every execution)
+- ✅ Returns cleanup function
+- ✅ Prevents infinite recursion
+- ✅ Integrates with per-state batching (no global scheduler)
+
+**How it works:** Effects use `globalThis.__LUME_CURRENT_EFFECT__` to track which state properties are accessed during execution. When any tracked property changes, the effect is queued in that state's pending effects set and runs once in the next microtask.
 
 ### `bindDom(root, store)`
 
@@ -134,14 +185,15 @@ cleanup();
 - ✅ Radio buttons: `<input type="radio" data-bind="choice">`
 - ✅ Nested paths: `<span data-bind="user.name"></span>`
 
-**NEW in v0.3.0:**
-- Returns cleanup function
-- Better error messages with `[Lume.js]` prefix
-- Handles edge cases (empty bindings, invalid paths)
+**Features:**
+- ✅ Returns cleanup function
+- ✅ Better error messages with `[Lume.js]` prefix
+- ✅ Handles edge cases (empty bindings, invalid paths)
+- ✅ Two-way binding for form inputs
 
 ### `$subscribe(key, callback)`
 
-Manually subscribe to state changes. Returns unsubscribe function.
+Manually subscribe to state changes. Calls callback immediately with current value, then on every change.
 
 ```javascript
 const unsubscribe = store.$subscribe('count', (value) => {
@@ -157,10 +209,71 @@ const unsubscribe = store.$subscribe('count', (value) => {
 unsubscribe();
 ```
 
-**NEW in v0.3.0:**
-- Returns unsubscribe function (was missing in v0.2.x)
-- Validates callback is a function
-- Only notifies on actual value changes
+**Features:**
+- ✅ Returns unsubscribe function
+- ✅ Validates callback is a function
+- ✅ Calls immediately with current value (not batched)
+- ✅ Only notifies on actual value changes (via batching)
+
+---
+
+## Addons
+
+Lume.js provides optional addons for advanced reactivity patterns. Import from `lume-js/addons`.
+
+### `computed(fn)`
+
+Creates a computed value that automatically updates when its dependencies change.
+
+```javascript
+import { state, effect } from 'lume-js';
+import { computed } from 'lume-js/addons';
+
+const store = state({ count: 5 });
+
+const doubled = computed(() => store.count * 2);
+console.log(doubled.value); // 10
+
+store.count = 10;
+// After microtask:
+console.log(doubled.value); // 20 (auto-updated)
+
+// Subscribe to changes
+const unsub = doubled.subscribe(value => {
+  console.log('Doubled:', value);
+});
+
+// Cleanup
+doubled.dispose();
+unsub();
+```
+
+**Features:**
+- ✅ Automatic dependency tracking using `effect()`
+- ✅ Cached values (only recomputes when dependencies change)
+- ✅ Subscribe to changes with `.subscribe(callback)`
+- ✅ Cleanup with `.dispose()`
+- ✅ Error handling (sets to undefined on error)
+
+### `watch(store, key, callback)`
+
+Alias for `$subscribe` - observes changes to a specific state key.
+
+```javascript
+import { state } from 'lume-js';
+import { watch } from 'lume-js/addons';
+
+const store = state({ count: 0 });
+
+const unwatch = watch(store, 'count', (value) => {
+  console.log('Count is now:', value);
+});
+
+// Cleanup
+unwatch();
+```
+
+**Note:** `watch()` is just a convenience wrapper around `store.$subscribe()`. Use whichever feels more natural.
 
 ---
 
@@ -262,14 +375,65 @@ window.addEventListener('beforeunload', () => {
 <input type="checkbox" data-bind="user.settings.notifications">
 ```
 
+### Using Effects for Auto-Updates
+
+```javascript
+import { state, effect } from 'lume-js';
+
+const store = state({ 
+  firstName: 'Alice', 
+  lastName: 'Smith' 
+});
+
+// Auto-update title when name changes
+effect(() => {
+  document.title = `${store.firstName} ${store.lastName}`;
+});
+
+store.firstName = 'Bob'; 
+// Title automatically updates to "Bob Smith" in next microtask
+```
+
+### Computed Values
+
+```javascript
+import { state } from 'lume-js';
+import { computed } from 'lume-js/addons';
+
+const cart = state({
+  items: state([
+    state({ price: 10, quantity: 2 }),
+    state({ price: 15, quantity: 1 })
+  ])
+});
+
+const total = computed(() => {
+  return cart.items.reduce((sum, item) => 
+    sum + (item.price * item.quantity), 0
+  );
+});
+
+console.log(total.value); // 35
+
+cart.items[0].quantity = 3;
+// After microtask:
+console.log(total.value); // 45
+```
+
 ### Integration with GSAP
 
 ```javascript
 import gsap from 'gsap';
-import { state } from 'lume-js';
+import { state, effect } from 'lume-js';
 
 const ui = state({ x: 0, y: 0 });
 
+// Use effect for automatic animation updates
+effect(() => {
+  gsap.to('.box', { x: ui.x, y: ui.y, duration: 0.5 });
+});
+
+// Or use $subscribe
 const unsubX = ui.$subscribe('x', (value) => {
   gsap.to('.box', { x: value, duration: 0.5 });
 });
@@ -283,17 +447,28 @@ window.addEventListener('beforeunload', () => unsubX());
 ### Cleanup Pattern (Important!)
 
 ```javascript
+import { state, effect, bindDom } from 'lume-js';
+import { computed } from 'lume-js/addons';
+
 const store = state({ data: [] });
 const cleanup = bindDom(root, store);
 
 const unsub1 = store.$subscribe('data', handleData);
 const unsub2 = store.$subscribe('status', handleStatus);
 
+const effectCleanup = effect(() => {
+  console.log('Data length:', store.data.length);
+});
+
+const total = computed(() => store.data.length * 2);
+
 // Cleanup when component unmounts
 function destroy() {
-  cleanup();      // Remove DOM bindings
-  unsub1();       // Remove subscription 1
-  unsub2();       // Remove subscription 2
+  cleanup();           // Remove DOM bindings
+  unsub1();            // Remove subscription 1
+  unsub2();            // Remove subscription 2
+  effectCleanup();     // Stop effect
+  total.dispose();     // Stop computed
 }
 
 // For SPA frameworks
@@ -380,25 +555,27 @@ document.addEventListener('click', () => store.clicks++);
 
 ---
 
-## What's New in v0.3.0?
-
-### Breaking Changes
-- ✅ `subscribe` → `$subscribe` (restored from v0.1.0)
-- ✅ `$subscribe` now returns unsubscribe function
-
-### New Features
-- ✅ TypeScript definitions (`index.d.ts`)
-- ✅ `bindDom()` returns cleanup function
+## What's New
+
+### Core Features
+- ✅ **Automatic dependency tracking** - `effect()` automatically tracks which state properties are accessed
+- ✅ **Per-state batching** - Each state object maintains its own microtask flush for optimal performance
+- ✅ **Effect deduplication** - Effects only run once per flush cycle, even if multiple dependencies change
+- ✅ **TypeScript support** - Full type definitions in `index.d.ts`
+- ✅ **Cleanup functions** - All reactive APIs return cleanup/unsubscribe functions
+
+### Addons
+- ✅ **`computed()`** - Memoized computed values with automatic dependency tracking
+- ✅ **`watch()`** - Convenience alias for `$subscribe`
+
+### API Design
+- ✅ `state()` - Create reactive state with automatic tracking support
+- ✅ `effect()` - Core reactivity primitive (automatic dependency collection)
+- ✅ `bindDom()` - DOM binding with two-way sync for form inputs
+- ✅ `$subscribe()` - Manual subscriptions (calls immediately with current value)
+- ✅ All functions return cleanup/unsubscribe functions
 - ✅ Better error handling with `[Lume.js]` prefix
-- ✅ Input validation (only plain objects)
-- ✅ Only triggers on actual value changes
-- ✅ Support for checkboxes, radio buttons, number inputs
-- ✅ Comprehensive example in `/examples/comprehensive/`
-
-### Bug Fixes
-- ✅ Fixed memory leaks (no cleanup in v0.2.x)
-- ✅ Fixed addon examples (used wrong API)
-- ✅ Better path resolution with detailed errors
+- ✅ Input validation on all public APIs
 
 ---
 
@@ -413,6 +590,39 @@ document.addEventListener('click', () => store.clicks++);
 
 ---
 
+## Testing
+
+Lume.js uses [Vitest](https://vitest.dev) with a jsdom environment. The test suite mirrors the source tree: files under `tests/core/**` map to `src/core/**`, and `tests/addons/**` map to `src/addons/**`.
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage with HTML report in ./coverage
+npm run coverage
+```
+
+**Import alias:** Tests use an alias so you can import from `src/...` without relative `../../` paths.
+
+```js
+// vitest.config.js
+resolve: {
+  alias: {
+    src: fileURLToPath(new URL('./src', import.meta.url))
+  }
+}
+```
+
+**Current coverage:**
+- 100% statements, functions, and lines
+- 100% branches (including edge-case paths)
+- 37 tests covering core behavior, addons, inputs (text/checkbox/radio/number/range/select/textarea), nested state, and cleanup semantics
+
+---
+
 ## Contributing
 
 We welcome contributions! Please:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lume-js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -8,7 +8,10 @@
   "scripts": {
     "dev": "vite",
     "build": "echo 'No build step needed - zero-runtime library!'",
-    "preview": "vite preview"
+    "size": "node scripts/check-size.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
   },
   "files": [
     "src",
@@ -45,7 +48,10 @@
   },
   "homepage": "https://github.com/sathvikc/lume-js#readme",
   "devDependencies": {
-    "vite": "^7.1.9"
+    "vite": "^7.1.9",
+    "vitest": "^2.1.4",
+    "@vitest/coverage-v8": "^2.1.4",
+    "jsdom": "^25.0.1"
   },
   "engines": {
     "node": ">=20.19.0"

package/src/addons/computed.js

@@ -1,53 +1,136 @@
 /**
- * computed - creates a derived value based on state
+ * Lume-JS Computed Addon
  * 
- * NOTE: This is a basic implementation. For production use,
- * consider more robust solutions with automatic dependency tracking.
+ * Creates computed values that automatically update when dependencies change.
+ * Uses core effect() for automatic dependency tracking.
  * 
- * @param {Function} fn - function that computes value from state
- * @returns {Object} - { value, recompute, subscribe }
+ * Usage:
+ *   import { computed } from "lume-js/addons/computed";
+ *   
+ *   const doubled = computed(() => store.count * 2);
+ *   console.log(doubled.value); // Auto-updates when store.count changes
+ * 
+ * Features:
+ * - Automatic dependency tracking (no manual recompute)
+ * - Cached values (only recomputes when dependencies change)
+ * - Subscribe to changes
+ * - Cleanup with dispose()
+ * 
+ * @module addons/computed
+ */
+
+import { effect } from '../core/effect.js';
+
+/**
+ * Creates a computed value with automatic dependency tracking
+ * 
+ * The computation function runs immediately and tracks which state
+ * properties are accessed. When any dependency changes, the value
+ * is automatically recomputed.
+ * 
+ * @param {function} fn - Function that computes the value
+ * @returns {object} Object with .value property and methods
  * 
  * @example
- * const store = state({ count: 0 });
+ * const store = state({ count: 5 });
+ * 
  * const doubled = computed(() => store.count * 2);
+ * console.log(doubled.value); // 10
+ * 
+ * store.count = 10;
+ * // After microtask:
+ * console.log(doubled.value); // 20 (auto-updated)
  * 
+ * @example
  * // Subscribe to changes
- * doubled.subscribe(val => console.log('Doubled:', val));
+ * const unsub = doubled.subscribe(value => {
+ *   console.log('Doubled changed to:', value);
+ * });
  * 
- * // Manually trigger recomputation after state changes
- * store.$subscribe('count', () => doubled.recompute());
+ * @example
+ * // Cleanup
+ * doubled.dispose();
  */
 export function computed(fn) {
-  let value;
-  let dirty = true;
-  const subscribers = new Set();
+  if (typeof fn !== 'function') {
+    throw new Error('computed() requires a function');
+  }
 
-  const recalc = () => {
+  let cachedValue;
+  let isInitialized = false;
+  const subscribers = [];
+  
+  // Use effect to automatically track dependencies
+  const cleanupEffect = effect(() => {
     try {
-      value = fn();
-    } catch (err) {
-      console.error("[computed] Error computing value:", err);
-      value = undefined;
+      const newValue = fn();
+      
+      // Check if value actually changed
+      if (!isInitialized || newValue !== cachedValue) {
+        cachedValue = newValue;
+        isInitialized = true;
+        
+        // Notify all subscribers
+        subscribers.forEach(callback => callback(cachedValue));
+      }
+    } catch (error) {
+      console.error('[Lume.js computed] Error in computation:', error);
+      // Set to undefined on error, mark as initialized
+      if (!isInitialized || cachedValue !== undefined) {
+        cachedValue = undefined;
+        isInitialized = true;
+        
+        // Notify subscribers of error state
+        subscribers.forEach(callback => callback(cachedValue));
+      }
     }
-    dirty = false;
-    subscribers.forEach(cb => cb(value));
-  };
-
+  });
+  
   return {
+    /**
+     * Get the current computed value
+     */
     get value() {
-      if (dirty) recalc();
-      return value;
+      if (!isInitialized) {
+        throw new Error('Computed value accessed before initialization');
+      }
+      return cachedValue;
     },
-    recompute: () => {
-      dirty = true;
-      recalc();
-    },
-    subscribe: cb => {
-      subscribers.add(cb);
-      // Immediately notify subscriber with current value
-      if (!dirty) cb(value);
-      else recalc(); // Compute first time
-      return () => subscribers.delete(cb); // unsubscribe function
+    
+    /**
+     * Subscribe to changes in computed value
+     * 
+     * @param {function} callback - Called when value changes
+     * @returns {function} Unsubscribe function
+     */
+    subscribe(callback) {
+      if (typeof callback !== 'function') {
+        throw new Error('subscribe() requires a function');
+      }
+      
+      subscribers.push(callback);
+      
+      // Call immediately with current value
+      if (isInitialized) {
+        callback(cachedValue);
+      }
+      
+      // Return unsubscribe function
+      return () => {
+        const index = subscribers.indexOf(callback);
+        if (index > -1) {
+          subscribers.splice(index, 1);
+        }
+      };
     },
+    
+    /**
+     * Clean up computed value and stop tracking
+     */
+    dispose() {
+      cleanupEffect();
+      subscribers.length = 0;
+      isInitialized = false;
+    }
   };
 }

package/src/core/bindDom.js

@@ -35,7 +35,7 @@ export function bindDom(root, store) {
   }
 
   const nodes = root.querySelectorAll("[data-bind]");
-  const unsubscribers = [];
+  const cleanups = [];
 
   nodes.forEach(el => {
     const bindPath = el.getAttribute("data-bind");
@@ -61,24 +61,24 @@ export function bindDom(root, store) {
       return;
     }
 
-    // Subscribe to changes
-    const unsub = target.$subscribe(lastKey, val => {
+    // Subscribe to changes - receives already-batched notifications
+    const unsubscribe = target.$subscribe(lastKey, val => {
       updateElement(el, val);
     });
-
-    unsubscribers.push(unsub);
+    cleanups.push(unsubscribe);
 
     // Two-way binding for form inputs
     if (isFormInput(el)) {
-      el.addEventListener("input", e => {
+      const handler = e => {
         target[lastKey] = getInputValue(e.target);
-      });
+      };
+      el.addEventListener("input", handler);
+      cleanups.push(() => el.removeEventListener("input", handler));
     }
   });
 
-  // Return cleanup function
   return () => {
-    unsubscribers.forEach(unsub => unsub());
+    cleanups.forEach(cleanup => cleanup());
   };
 }
 

package/src/core/effect.js

@@ -0,0 +1,104 @@
+/**
+ * Lume-JS Effect
+ * 
+ * Automatic dependency tracking for reactive effects.
+ * Tracks which state properties are accessed during execution
+ * and automatically re-runs when those properties change.
+ * 
+ * Part of core because it's fundamental to modern reactivity.
+ * 
+ * Usage:
+ *   import { effect } from "lume-js";
+ *   
+ *   effect(() => {
+ *     console.log('Count is:', store.count);
+ *     // Automatically re-runs when store.count changes
+ *   });
+ * 
+ * Features:
+ * - Automatic dependency collection
+ * - Dynamic dependencies (tracks what you actually access)
+ * - Returns cleanup function
+ * - Plays nicely with per-state batching (no global scheduler)
+ *
+ */
+
+/**
+ * Creates an effect that automatically tracks dependencies
+ *
+ * The effect runs immediately and collects dependencies by tracking
+ * which state properties are accessed. When any dependency changes,
+ * the effect re-runs automatically.
+ * 
+ * @param {function} fn - Function to run reactively
+ * @returns {function} Cleanup function to stop the effect
+ * 
+ * @example
+ * const store = state({ count: 0, name: 'Alice' });
+ * 
+ * const cleanup = effect(() => {
+ *   // Only tracks 'count' (name not accessed)
+ *   document.title = `Count: ${store.count}`;
+ * });
+ * 
+ * store.count = 5;  // Effect re-runs
+ * store.name = 'Bob'; // Effect does NOT re-run
+ * 
+ * cleanup(); // Stop tracking
+ */
+export function effect(fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('effect() requires a function');
+  }
+
+  const cleanups = [];
+  let isRunning = false; // Prevent infinite recursion
+  
+  /**
+   * Execute the effect function and collect dependencies
+   *
+   * The execution re-tracks accessed keys on every run. Subscriptions
+   * are cleaned up and re-established so the effect always reflects
+   * current dependencies.
+   */
+  const execute = () => {
+    if (isRunning) return; // Prevent re-entry
+    
+    // Clean up previous subscriptions
+    cleanups.forEach(cleanup => cleanup());
+    cleanups.length = 0;
+    
+    // Create effect context for tracking
+    const effectContext = {
+      fn,
+      cleanups,
+      execute, // Reference to this execute function
+      tracking: {} // Map of tracked keys
+    };
+    
+    // Set as current effect (for state.js to detect)
+    globalThis.__LUME_CURRENT_EFFECT__ = effectContext;
+    isRunning = true;
+    
+    try {
+      // Run the effect function (this triggers state getters)
+      fn();
+    } catch (error) {
+      console.error('[Lume.js effect] Error in effect:', error);
+      throw error;
+    } finally {
+      // Always clean up, even if error
+      globalThis.__LUME_CURRENT_EFFECT__ = undefined;
+      isRunning = false;
+    }
+  };
+  
+  // Run immediately to collect initial dependencies
+  execute();
+
+  // Return cleanup function
+  return () => {
+    cleanups.forEach(cleanup => cleanup());
+    cleanups.length = 0;
+  };
+}

package/src/core/state.js

@@ -1,14 +1,17 @@
-// src/core/state.js
 /**
  * Lume-JS Reactive State Core
  *
  * Provides minimal reactive state with standard JavaScript.
+ * Features automatic microtask batching for performance.
+ * Supports automatic dependency tracking for effects.
  * 
  * Features:
  * - Lightweight and Go-style
  * - Explicit nested states
  * - $subscribe for listening to key changes
  * - Cleanup with unsubscribe
+ * - Per-state microtask batching for writes
+ * - Effect dependency tracking support (deduped per state flush)
  *
  * Usage:
  *   import { state } from "lume-js";
@@ -17,6 +20,9 @@
  *   unsub(); // cleanup
  */
 
+// Per-state batching – each state object maintains its own microtask flush.
+// This keeps effects simple and aligned with Lume's minimal philosophy.
+
 /**
  * Creates a reactive state object.
  * 
@@ -30,26 +36,93 @@ export function state(obj) {
   }
 
   const listeners = {};
+  const pendingNotifications = new Map(); // Per-state pending changes
+  const pendingEffects = new Set(); // Dedupe effects per state
+  let flushScheduled = false;
 
-  // Notify subscribers of a key
-  function notify(key, val) {
-    if (listeners[key]) {
-      listeners[key].forEach(fn => fn(val));
-    }
+  /**
+   * Schedule a single microtask flush for this state object.
+   *
+   * Flush order per state:
+   * 1) Notify subscribers for changed keys (key → subscribers)
+   * 2) Run each queued effect exactly once (Set-based dedupe)
+   *
+   * Notes:
+   * - Batching is per state; effects that depend on multiple states
+   *   may run once per state that changed (by design).
+   */
+  function scheduleFlush() {
+    if (flushScheduled) return;
+    
+    flushScheduled = true;
+    queueMicrotask(() => {
+      flushScheduled = false;
+      
+      // Notify all subscribers of changed keys
+      for (const [key, value] of pendingNotifications) {
+        if (listeners[key]) {
+          listeners[key].forEach(fn => fn(value));
+        }
+      }
+      
+      pendingNotifications.clear();
+      
+      // Run each effect exactly once (Set deduplicates)
+      const effects = Array.from(pendingEffects);
+      pendingEffects.clear();
+      effects.forEach(effect => effect());
+    });
   }
 
   const proxy = new Proxy(obj, {
     get(target, key) {
+      // Support effect tracking
+      // Check if we're inside an effect context
+      if (typeof globalThis.__LUME_CURRENT_EFFECT__ !== 'undefined') {
+        const currentEffect = globalThis.__LUME_CURRENT_EFFECT__;
+        
+        if (currentEffect && !currentEffect.tracking[key]) {
+          // Mark as tracked
+          currentEffect.tracking[key] = true;
+          
+          // Subscribe to changes for this key (skip initial call for effects)
+          const unsubscribe = (() => {
+            if (!listeners[key]) listeners[key] = [];
+            
+            const effectFn = () => {
+              // Queue effect in this state's pending set
+              // Set deduplicates - effect runs once even if multiple keys change
+              pendingEffects.add(currentEffect.execute);
+            };
+            
+            listeners[key].push(effectFn);
+            
+            // Return unsubscribe function (no initial call for effects)
+            return () => {
+              if (listeners[key]) {
+                listeners[key] = listeners[key].filter(subscriber => subscriber !== effectFn);
+              }
+            };
+          })();
+          
+          // Store cleanup function
+          currentEffect.cleanups.push(unsubscribe);
+        }
+      }
+      
       return target[key];
     },
+    
     set(target, key, value) {
       const oldValue = target[key];
+      if (oldValue === value) return true;
+      
       target[key] = value;
       
-      // Only notify if value actually changed
-      if (oldValue !== value) {
-        notify(key, value);
-      }
+      // Batch notifications at the state level (per-state, not global)
+      pendingNotifications.set(key, value);
+      scheduleFlush();
+      
       return true;
     }
   });
@@ -71,7 +144,7 @@ export function state(obj) {
     if (!listeners[key]) listeners[key] = [];
     listeners[key].push(fn);
     
-    // Call immediately with current value
+    // Call immediately with current value (NOT batched)
     fn(proxy[key]);
 
     // Return unsubscribe function

package/src/index.d.ts

@@ -85,4 +85,31 @@ export function state<T extends object>(obj: T): ReactiveState<T>;
 export function bindDom(
   root: HTMLElement,
   store: ReactiveState<any>
-): Unsubscribe;
+): Unsubscribe;
+
+/**
+ * Create an effect that automatically tracks dependencies
+ * 
+ * The effect runs immediately and re-runs when any accessed state properties change.
+ * Only tracks properties that are actually accessed during execution.
+ * 
+ * @param fn - Function to run reactively
+ * @returns Cleanup function to stop the effect
+ * @throws {Error} If fn is not a function
+ * 
+ * @example
+ * ```typescript
+ * const store = state({ count: 0, name: 'Alice' });
+ * 
+ * const cleanup = effect(() => {
+ *   // Only tracks 'count' (name not accessed)
+ *   console.log(`Count: ${store.count}`);
+ * });
+ * 
+ * store.count = 5;    // Effect re-runs
+ * store.name = 'Bob'; // Effect does NOT re-run
+ * 
+ * cleanup(); // Stop the effect
+ * ```
+ */
+export function effect(fn: () => void): Unsubscribe;

package/src/index.js

@@ -4,10 +4,12 @@
  * Exposes:
  * - state(): create reactive state
  * - bindDom(): zero-runtime DOM binding
+ * - effect(): reactive effect with automatic dependency tracking
  *
  * Usage:
- *   import { state, bindDom } from "lume-js";
+ *   import { state, bindDom, effect } from "lume-js";
  */
 
 export { state } from "./core/state.js";
 export { bindDom } from "./core/bindDom.js";
+export { effect } from "./core/effect.js";