pulse-js-framework 1.4.5 → 1.4.6

package/README.md

@@ -13,6 +13,7 @@ A declarative DOM framework with CSS selector-based structure and reactive pulsa
 - **No Build Required** - Works directly in the browser
 - **Lightweight** - Minimal footprint, maximum performance
 - **Router & Store** - Built-in SPA routing and state management
+- **Hot Module Replacement** - Full HMR with state preservation
 - **Mobile Apps** - Build native Android & iOS apps (zero dependencies)
 - **TypeScript Support** - Full type definitions for IDE autocomplete
 
@@ -280,6 +281,57 @@ const store = createStore({
 store.user.set({ name: 'John' });
 ```
 
+### HMR (Hot Module Replacement)
+
+Pulse supports full HMR with state preservation during development:
+
+```javascript
+import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+
+const hmr = createHMRContext(import.meta.url);
+
+// State preserved across HMR updates
+const count = hmr.preservePulse('count', 0);
+const items = hmr.preservePulse('items', []);
+
+// Effects tracked for automatic cleanup
+hmr.setup(() => {
+  effect(() => {
+    document.title = `Count: ${count.get()}`;
+  });
+});
+
+// Accept HMR updates
+hmr.accept();
+```
+
+**HMR Features:**
+- `preservePulse(key, value)` - Create pulses that survive module replacement
+- `setup(callback)` - Execute with effect tracking for cleanup
+- Automatic event listener cleanup (no accumulation)
+- Works with Vite dev server
+
+### Logger
+
+```javascript
+import { createLogger, setLogLevel, LogLevel } from 'pulse-js-framework/runtime/logger';
+
+// Create a namespaced logger
+const log = createLogger('MyComponent');
+
+log.info('Component initialized');    // [MyComponent] Component initialized
+log.warn('Deprecated method used');
+log.error('Failed to load', error);
+log.debug('Detailed info');           // Only shown at DEBUG level
+
+// Set global log level
+setLogLevel(LogLevel.DEBUG);  // SILENT, ERROR, WARN, INFO, DEBUG
+
+// Child loggers for sub-namespaces
+const childLog = log.child('Validation');
+childLog.info('Validating'); // [MyComponent:Validation] Validating
+```
+
 ## CLI Commands
 
 ```bash
@@ -399,6 +451,28 @@ onNativeReady(({ platform }) => {
 
 **Available APIs:** Storage, Device Info, Network Status, Toast, Vibration, Clipboard, App Lifecycle
 
+## VSCode Extension
+
+Pulse includes a VSCode extension for `.pulse` files with syntax highlighting and snippets.
+
+### Installation
+
+```bash
+# Windows (PowerShell)
+cd vscode-extension
+powershell -ExecutionPolicy Bypass -File install.ps1
+
+# macOS/Linux
+cd vscode-extension
+bash install.sh
+```
+
+Then restart VSCode. You'll get:
+- Syntax highlighting for `.pulse` files
+- Code snippets (`page`, `state`, `view`, `@click`, etc.)
+- Bracket matching and auto-closing
+- Comment toggling (Ctrl+/)
+
 ## TypeScript Support
 
 Pulse includes full TypeScript definitions for IDE autocomplete and type checking:

package/loader/vite-plugin.js

@@ -69,22 +69,30 @@ export default function pulsePlugin(options = {}) {
     /**
      * Handle hot module replacement
      */
-    handleHotUpdate({ file, server }) {
+    handleHotUpdate({ file, server, modules }) {
       if (file.endsWith('.pulse')) {
         console.log(`[Pulse] HMR update: ${file}`);
 
-        // Invalidate the module
+        // Invalidate the module in Vite's module graph
         const module = server.moduleGraph.getModuleById(file);
         if (module) {
           server.moduleGraph.invalidateModule(module);
         }
 
-        // Send full reload for now
-        // In a more advanced implementation, we could do partial updates
+        // Send HMR update instead of full reload
+        // The module will handle its own state preservation via hmrRuntime
         server.ws.send({
-          type: 'full-reload',
-          path: '*'
+          type: 'update',
+          updates: [{
+            type: 'js-update',
+            path: file,
+            acceptedPath: file,
+            timestamp: Date.now()
+          }]
         });
+
+        // Return empty array to prevent Vite's default HMR handling
+        return [];
       }
     },
 
@@ -117,6 +125,14 @@ export default function pulsePlugin(options = {}) {
  */
 export const hmrRuntime = `
 if (import.meta.hot) {
+  // Cleanup effects before module replacement
+  import.meta.hot.dispose(() => {
+    import('pulse-js-framework/runtime/pulse').then(m => {
+      m.disposeModule(import.meta.url);
+    });
+  });
+
+  // Accept HMR updates
   import.meta.hot.accept((newModule) => {
     if (newModule) {
       // Re-render with new module

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -41,6 +41,9 @@
       "types": "./types/logger.d.ts",
       "default": "./runtime/logger.js"
     },
+    "./runtime/hmr": {
+      "default": "./runtime/hmr.js"
+    },
     "./compiler": {
       "types": "./types/index.d.ts",
       "default": "./compiler/index.js"
@@ -67,12 +70,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:lint && npm run test:format && npm run test:analyze",
+    "test": "npm run test:compiler && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze",
     "test:compiler": "node test/compiler.test.js",
     "test:pulse": "node test/pulse.test.js",
     "test:dom": "node test/dom.test.js",
     "test:router": "node test/router.test.js",
     "test:store": "node test/store.test.js",
+    "test:hmr": "node test/hmr.test.js",
     "test:lint": "node test/lint.test.js",
     "test:format": "node test/format.test.js",
     "test:analyze": "node test/analyze.test.js",

package/runtime/dom.js

@@ -10,6 +10,10 @@ import { loggers } from './logger.js';
 
 const log = loggers.dom;
 
+// Selector cache for parseSelector
+const selectorCache = new Map();
+const SELECTOR_CACHE_MAX = 500;
+
 // Lifecycle tracking
 let mountCallbacks = [];
 let unmountCallbacks = [];
@@ -41,6 +45,7 @@ export function onUnmount(fn) {
 /**
  * Parse a CSS selector-like string into element configuration
  * Supports: tag, #id, .class, [attr=value]
+ * Results are cached for performance.
  *
  * Examples:
  *   "div" -> { tag: "div" }
@@ -50,6 +55,22 @@ export function onUnmount(fn) {
  *   "input[type=text][placeholder=Name]" -> { tag: "input", attrs: { type: "text", placeholder: "Name" } }
  */
 export function parseSelector(selector) {
+  if (!selector || selector === '') {
+    return { tag: 'div', id: null, classes: [], attrs: {} };
+  }
+
+  // Check cache first
+  const cached = selectorCache.get(selector);
+  if (cached) {
+    // Return a shallow copy to prevent mutation
+    return {
+      tag: cached.tag,
+      id: cached.id,
+      classes: [...cached.classes],
+      attrs: { ...cached.attrs }
+    };
+  }
+
   const config = {
     tag: 'div',
     id: null,
@@ -57,30 +78,30 @@ export function parseSelector(selector) {
     attrs: {}
   };
 
-  if (!selector || selector === '') return config;
+  let remaining = selector;
 
   // Match tag name at the start
-  const tagMatch = selector.match(/^([a-zA-Z][a-zA-Z0-9-]*)/);
+  const tagMatch = remaining.match(/^([a-zA-Z][a-zA-Z0-9-]*)/);
   if (tagMatch) {
     config.tag = tagMatch[1];
-    selector = selector.slice(tagMatch[0].length);
+    remaining = remaining.slice(tagMatch[0].length);
   }
 
   // Match ID
-  const idMatch = selector.match(/#([a-zA-Z][a-zA-Z0-9-_]*)/);
+  const idMatch = remaining.match(/#([a-zA-Z][a-zA-Z0-9-_]*)/);
   if (idMatch) {
     config.id = idMatch[1];
-    selector = selector.replace(idMatch[0], '');
+    remaining = remaining.replace(idMatch[0], '');
   }
 
   // Match classes
-  const classMatches = selector.matchAll(/\.([a-zA-Z][a-zA-Z0-9-_]*)/g);
+  const classMatches = remaining.matchAll(/\.([a-zA-Z][a-zA-Z0-9-_]*)/g);
   for (const match of classMatches) {
     config.classes.push(match[1]);
   }
 
   // Match attributes
-  const attrMatches = selector.matchAll(/\[([a-zA-Z][a-zA-Z0-9-_]*)(?:=([^\]]+))?\]/g);
+  const attrMatches = remaining.matchAll(/\[([a-zA-Z][a-zA-Z0-9-_]*)(?:=([^\]]+))?\]/g);
   for (const match of attrMatches) {
     const key = match[1];
     let value = match[2] || '';
@@ -92,7 +113,21 @@ export function parseSelector(selector) {
     config.attrs[key] = value;
   }
 
-  return config;
+  // Cache the result (with size limit to prevent memory leaks)
+  if (selectorCache.size >= SELECTOR_CACHE_MAX) {
+    // Remove oldest entry (first key)
+    const firstKey = selectorCache.keys().next().value;
+    selectorCache.delete(firstKey);
+  }
+  selectorCache.set(selector, config);
+
+  // Return a copy
+  return {
+    tag: config.tag,
+    id: config.id,
+    classes: [...config.classes],
+    attrs: { ...config.attrs }
+  };
 }
 
 /**
@@ -265,6 +300,12 @@ export function style(element, prop, getValue) {
  */
 export function on(element, event, handler, options) {
   element.addEventListener(event, handler, options);
+
+  // Auto-cleanup: remove listener when effect is disposed (HMR support)
+  onCleanup(() => {
+    element.removeEventListener(event, handler, options);
+  });
+
   return element;
 }
 

package/runtime/hmr.js

@@ -0,0 +1,169 @@
+/**
+ * HMR (Hot Module Replacement) utilities for Pulse framework
+ * @module pulse-js-framework/runtime/hmr
+ *
+ * Provides state preservation and effect cleanup during hot module replacement.
+ *
+ * @example
+ * import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+ *
+ * const hmr = createHMRContext(import.meta.url);
+ *
+ * // State preserved across HMR updates
+ * const count = hmr.preservePulse('count', 0);
+ *
+ * // Effects tracked for cleanup
+ * hmr.setup(() => {
+ *   effect(() => console.log(count.get()));
+ * });
+ */
+
+import { pulse } from './pulse.js';
+import { setCurrentModule, clearCurrentModule, disposeModule } from './pulse.js';
+
+/**
+ * @typedef {Object} HMRContext
+ * @property {Object} data - Persistent data storage across HMR updates
+ * @property {function(string, *, Object=): Pulse} preservePulse - Create a pulse with preserved state
+ * @property {function(function): *} setup - Execute code with module tracking
+ * @property {function(function): void} accept - Register HMR accept callback
+ * @property {function(function): void} dispose - Register HMR dispose callback
+ */
+
+/**
+ * Create an HMR context for a module.
+ * Provides utilities for state preservation and effect cleanup during HMR.
+ *
+ * @param {string} moduleId - The module identifier (typically import.meta.url)
+ * @returns {HMRContext} HMR context with preservation utilities
+ *
+ * @example
+ * const hmr = createHMRContext(import.meta.url);
+ *
+ * // Preserve state across HMR
+ * const todos = hmr.preservePulse('todos', []);
+ * const filter = hmr.preservePulse('filter', 'all');
+ *
+ * // Setup effects with automatic cleanup
+ * hmr.setup(() => {
+ *   effect(() => {
+ *     document.title = `${todos.get().length} todos`;
+ *   });
+ * });
+ *
+ * // Accept HMR updates
+ * hmr.accept();
+ */
+export function createHMRContext(moduleId) {
+  // Check if HMR is available (Vite dev server)
+  if (typeof import.meta === 'undefined' || !import.meta.hot) {
+    return createNoopContext();
+  }
+
+  const hot = import.meta.hot;
+
+  // Initialize data storage if not present
+  if (!hot.data) {
+    hot.data = {};
+  }
+
+  return {
+    /**
+     * Persistent data storage across HMR updates.
+     * Values stored here survive module reloads.
+     */
+    data: hot.data,
+
+    /**
+     * Create a pulse with state preservation across HMR updates.
+     * If a value exists from a previous module load, it's restored.
+     *
+     * @param {string} key - Unique key for this pulse within the module
+     * @param {*} initialValue - Initial value (used on first load only)
+     * @param {Object} [options] - Pulse options (equals function, etc.)
+     * @returns {Pulse} A pulse instance with preserved state
+     */
+    preservePulse(key, initialValue, options) {
+      const fullKey = `__pulse_${key}`;
+
+      // Check if we have a preserved value from previous load
+      if (fullKey in hot.data) {
+        const p = pulse(hot.data[fullKey], options);
+        // Register to save state on next HMR update
+        hot.dispose(() => {
+          hot.data[fullKey] = p.peek();
+        });
+        return p;
+      }
+
+      // First load - create new pulse with initial value
+      const p = pulse(initialValue, options);
+      // Register to save state on HMR update
+      hot.dispose(() => {
+        hot.data[fullKey] = p.peek();
+      });
+      return p;
+    },
+
+    /**
+     * Execute code with module tracking enabled.
+     * Effects created within this callback will be registered
+     * for automatic cleanup during HMR.
+     *
+     * @param {function} callback - Code to execute with tracking
+     * @returns {*} The return value of the callback
+     */
+    setup(callback) {
+      setCurrentModule(moduleId);
+      try {
+        return callback();
+      } finally {
+        clearCurrentModule();
+      }
+    },
+
+    /**
+     * Register a callback to run when the module accepts an HMR update.
+     *
+     * @param {function} [callback] - Optional callback for custom handling
+     */
+    accept(callback) {
+      if (callback) {
+        hot.accept(callback);
+      } else {
+        hot.accept();
+      }
+    },
+
+    /**
+     * Register a callback to run before the module is replaced.
+     * Use this for custom cleanup logic.
+     *
+     * @param {function} callback - Cleanup callback
+     */
+    dispose(callback) {
+      hot.dispose(callback);
+    }
+  };
+}
+
+/**
+ * Create a no-op HMR context for production or non-HMR environments.
+ * All methods work normally but without HMR-specific behavior.
+ *
+ * @returns {HMRContext} A no-op HMR context
+ * @private
+ */
+function createNoopContext() {
+  return {
+    data: {},
+    preservePulse: (key, initialValue, options) => pulse(initialValue, options),
+    setup: (callback) => callback(),
+    accept: () => {},
+    dispose: () => {}
+  };
+}
+
+export default {
+  createHMRContext
+};

package/runtime/pulse.js

@@ -22,17 +22,96 @@ import { loggers } from './logger.js';
 
 const log = loggers.pulse;
 
-// Current tracking context for automatic dependency collection
-/** @type {EffectFn|null} */
-let currentEffect = null;
-/** @type {number} */
-let batchDepth = 0;
-/** @type {Set<EffectFn>} */
-let pendingEffects = new Set();
-/** @type {boolean} */
-let isRunningEffects = false;
-/** @type {Array<Function>} */
-let cleanupQueue = [];
+/**
+ * @typedef {Object} ReactiveContext
+ * @property {EffectFn|null} currentEffect - Currently executing effect for dependency tracking
+ * @property {number} batchDepth - Nesting depth of batch() calls
+ * @property {Set<EffectFn>} pendingEffects - Effects queued during batch
+ * @property {boolean} isRunningEffects - Flag to prevent recursive effect flushing
+ * @property {string|null} currentModuleId - Current module ID for HMR effect tracking
+ * @property {Map<string, Set<EffectFn>>} effectRegistry - Module ID to effects mapping for HMR
+ */
+
+/**
+ * Global reactive context - holds all tracking state.
+ * Exported for testing purposes (use resetContext() to reset).
+ * @type {ReactiveContext}
+ */
+export const context = {
+  currentEffect: null,
+  batchDepth: 0,
+  pendingEffects: new Set(),
+  isRunningEffects: false,
+  // HMR support
+  currentModuleId: null,
+  effectRegistry: new Map()
+};
+
+/**
+ * Reset the reactive context to initial state.
+ * Use this in tests to ensure isolation between test cases.
+ * @returns {void}
+ * @example
+ * // In test setup/teardown
+ * import { resetContext } from 'pulse-js-framework/runtime/pulse';
+ * beforeEach(() => resetContext());
+ */
+export function resetContext() {
+  context.currentEffect = null;
+  context.batchDepth = 0;
+  context.pendingEffects.clear();
+  context.isRunningEffects = false;
+  context.currentModuleId = null;
+  context.effectRegistry.clear();
+}
+
+/**
+ * Set the current module ID for HMR effect tracking.
+ * Effects created while a module ID is set will be registered for cleanup.
+ * @param {string} moduleId - The module identifier (typically import.meta.url)
+ * @returns {void}
+ */
+export function setCurrentModule(moduleId) {
+  context.currentModuleId = moduleId;
+}
+
+/**
+ * Clear the current module ID after module initialization.
+ * @returns {void}
+ */
+export function clearCurrentModule() {
+  context.currentModuleId = null;
+}
+
+/**
+ * Dispose all effects associated with a module.
+ * Called during HMR to clean up before re-executing the module.
+ * @param {string} moduleId - The module identifier to dispose
+ * @returns {void}
+ */
+export function disposeModule(moduleId) {
+  const effects = context.effectRegistry.get(moduleId);
+  if (effects) {
+    for (const effectFn of effects) {
+      // Run cleanup functions
+      for (const cleanup of effectFn.cleanups) {
+        try {
+          cleanup();
+        } catch (e) {
+          log.error('HMR cleanup error:', e);
+        }
+      }
+      effectFn.cleanups = [];
+
+      // Unsubscribe from all dependencies
+      for (const dep of effectFn.dependencies) {
+        dep._unsubscribe(effectFn);
+      }
+      effectFn.dependencies.clear();
+    }
+    context.effectRegistry.delete(moduleId);
+  }
+}
 
 /**
  * @typedef {Object} EffectFn
@@ -88,8 +167,8 @@ let cleanupQueue = [];
  * });
  */
 export function onCleanup(fn) {
-  if (currentEffect) {
-    currentEffect.cleanups.push(fn);
+  if (context.currentEffect) {
+    context.currentEffect.cleanups.push(fn);
   }
 }
 
@@ -126,9 +205,9 @@ export class Pulse {
    * });
    */
   get() {
-    if (currentEffect) {
-      this.#subscribers.add(currentEffect);
-      currentEffect.dependencies.add(this);
+    if (context.currentEffect) {
+      this.#subscribers.add(context.currentEffect);
+      context.currentEffect.dependencies.add(this);
     }
     return this.#value;
   }
@@ -199,8 +278,8 @@ export class Pulse {
     const subs = [...this.#subscribers];
 
     for (const subscriber of subs) {
-      if (batchDepth > 0 || isRunningEffects) {
-        pendingEffects.add(subscriber);
+      if (context.batchDepth > 0 || context.isRunningEffects) {
+        context.pendingEffects.add(subscriber);
       } else {
         runEffect(subscriber);
       }
@@ -292,17 +371,17 @@ function runEffect(effectFn) {
  * @returns {void}
  */
 function flushEffects() {
-  if (isRunningEffects) return;
+  if (context.isRunningEffects) return;
 
-  isRunningEffects = true;
+  context.isRunningEffects = true;
   let iterations = 0;
   const maxIterations = 100; // Prevent infinite loops
 
   try {
-    while (pendingEffects.size > 0 && iterations < maxIterations) {
+    while (context.pendingEffects.size > 0 && iterations < maxIterations) {
       iterations++;
-      const effects = [...pendingEffects];
-      pendingEffects.clear();
+      const effects = [...context.pendingEffects];
+      context.pendingEffects.clear();
 
       for (const effect of effects) {
         runEffect(effect);
@@ -311,10 +390,10 @@ function flushEffects() {
 
     if (iterations >= maxIterations) {
       log.warn('Maximum effect iterations reached. Possible infinite loop.');
-      pendingEffects.clear();
+      context.pendingEffects.clear();
     }
   } finally {
-    isRunningEffects = false;
+    context.isRunningEffects = false;
   }
 }
 
@@ -371,13 +450,13 @@ export function computed(fn, options = {}) {
     p.get = function() {
       if (dirty) {
         // Run computation
-        const prevEffect = currentEffect;
+        const prevEffect = context.currentEffect;
         const tempEffect = {
           run: () => {},
           dependencies: new Set(),
           cleanups: []
         };
-        currentEffect = tempEffect;
+        context.currentEffect = tempEffect;
 
         try {
           cachedValue = fn();
@@ -400,14 +479,14 @@ export function computed(fn, options = {}) {
 
           p._init(cachedValue);
         } finally {
-          currentEffect = prevEffect;
+          context.currentEffect = prevEffect;
         }
       }
 
       // Track dependency on this computed
-      if (currentEffect) {
-        p._addSubscriber(currentEffect);
-        currentEffect.dependencies.add(p);
+      if (context.currentEffect) {
+        p._addSubscriber(context.currentEffect);
+        context.currentEffect.dependencies.add(p);
       }
 
       return cachedValue;
@@ -467,6 +546,9 @@ export function computed(fn, options = {}) {
  * });
  */
 export function effect(fn) {
+  // Capture module ID at creation time for HMR tracking
+  const moduleId = context.currentModuleId;
+
   const effectFn = {
     run: () => {
       // Run cleanup functions from previous run
@@ -486,21 +568,29 @@ export function effect(fn) {
       effectFn.dependencies.clear();
 
       // Set as current effect for dependency tracking
-      const prevEffect = currentEffect;
-      currentEffect = effectFn;
+      const prevEffect = context.currentEffect;
+      context.currentEffect = effectFn;
 
       try {
         fn();
       } catch (error) {
         log.error('Effect execution error:', error);
       } finally {
-        currentEffect = prevEffect;
+        context.currentEffect = prevEffect;
       }
     },
     dependencies: new Set(),
     cleanups: []
   };
 
+  // HMR: Register effect with current module
+  if (moduleId) {
+    if (!context.effectRegistry.has(moduleId)) {
+      context.effectRegistry.set(moduleId, new Set());
+    }
+    context.effectRegistry.get(moduleId).add(effectFn);
+  }
+
   // Run immediately to collect dependencies
   effectFn.run();
 
@@ -511,7 +601,7 @@ export function effect(fn) {
       try {
         cleanup();
       } catch (e) {
-        console.error('Cleanup error:', e);
+        log.error('Cleanup error:', e);
       }
     }
     effectFn.cleanups = [];
@@ -520,6 +610,11 @@ export function effect(fn) {
       dep._unsubscribe(effectFn);
     }
     effectFn.dependencies.clear();
+
+    // HMR: Remove from registry
+    if (moduleId && context.effectRegistry.has(moduleId)) {
+      context.effectRegistry.get(moduleId).delete(effectFn);
+    }
   };
 }
 
@@ -545,12 +640,12 @@ export function effect(fn) {
  * });
  */
 export function batch(fn) {
-  batchDepth++;
+  context.batchDepth++;
   try {
     return fn();
   } finally {
-    batchDepth--;
-    if (batchDepth === 0) {
+    context.batchDepth--;
+    if (context.batchDepth === 0) {
       flushEffects();
     }
   }
@@ -831,12 +926,12 @@ export function fromPromise(promise, initialValue = undefined) {
  * // Effect only re-runs when aSignal changes, not bSignal
  */
 export function untrack(fn) {
-  const prevEffect = currentEffect;
-  currentEffect = null;
+  const prevEffect = context.currentEffect;
+  context.currentEffect = null;
   try {
     return fn();
   } finally {
-    currentEffect = prevEffect;
+    context.currentEffect = prevEffect;
   }
 }
 
@@ -852,5 +947,11 @@ export default {
   untrack,
   onCleanup,
   memo,
-  memoComputed
+  memoComputed,
+  context,
+  resetContext,
+  // HMR support
+  setCurrentModule,
+  clearCurrentModule,
+  disposeModule
 };

package/types/index.d.ts

@@ -13,6 +13,8 @@ export {
   EqualsFn,
   ReactiveState,
   PromiseState,
+  EffectFn,
+  ReactiveContext,
   pulse,
   computed,
   effect,
@@ -23,7 +25,9 @@ export {
   memoComputed,
   fromPromise,
   untrack,
-  onCleanup
+  onCleanup,
+  context,
+  resetContext
 } from './pulse';
 
 // DOM Helpers

package/types/pulse.d.ts

@@ -147,3 +147,36 @@ export declare function untrack<T>(fn: () => T): T;
  * Register cleanup function for current effect
  */
 export declare function onCleanup(fn: () => void): void;
+
+/** Effect function with dependency tracking */
+export interface EffectFn {
+  run: () => void;
+  dependencies: Set<Pulse>;
+  cleanups: (() => void)[];
+}
+
+/**
+ * Reactive context - holds global tracking state.
+ * Exposed for testing and advanced use cases.
+ */
+export interface ReactiveContext {
+  /** Currently executing effect for dependency tracking */
+  currentEffect: EffectFn | null;
+  /** Nesting depth of batch() calls */
+  batchDepth: number;
+  /** Effects queued during batch */
+  pendingEffects: Set<EffectFn>;
+  /** Flag to prevent recursive effect flushing */
+  isRunningEffects: boolean;
+}
+
+/**
+ * Global reactive context
+ */
+export declare const context: ReactiveContext;
+
+/**
+ * Reset the reactive context to initial state.
+ * Use this in tests to ensure isolation between test cases.
+ */
+export declare function resetContext(): void;