@pulse-js/core 0.1.7 → 0.1.9

package/README.md

@@ -2,21 +2,15 @@
 
 <img width="200" height="200" alt="logo" src="https://raw.githubusercontent.com/ZtaMDev/Pulse/refs/heads/main/pulse.svg" />
 
-# Pulse
+# Pulse-JS
 
-> A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.
-
-Pulse differs from traditional signals or state managers by treating `Conditions` as first-class citizens. Instead of embedding complex boolean logic inside components or selectors, you define **Semantic Guards** that can be observed, composed, and debugged independently.
+[![npm version](https://img.shields.io/npm/v/@pulse-js/core.svg)](https://www.npmjs.com/package/@pulse-js/core)
 
-### Mental Model
+> A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.
 
-Compare Pulse primitives at a glance:
+Official [Documentation](https://pulse-js.vercel.app)
 
-| Concept     | Can be async | Has state | Observable | Purpose                              |
-| :---------- | :----------: | :-------: | :--------: | :----------------------------------- |
-| **Source**  |      ❌      |    ❌     |     ✅     | Reactive data (facts).               |
-| **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
-| **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
+Pulse differs from traditional signals or state managers by treating `Conditions` as first-class citizens. Instead of embedding complex boolean logic inside components or selectors, you define **Semantic Guards** that can be observed, composed, and debugged independently.
 
 </div>
 
@@ -146,37 +140,33 @@ import { hydrate } from "@pulse-js/core";
 hydrate(window.__PULSE_STATE__);
 ```
 
-## API Reference
-
-### `source<T>(initialValue: T, options?: SourceOptions)`
-
-Creates a reactive source.
-
-- `options.name`: Unique string name (highly recommended for debugging).
-- `options.equals`: Custom equality function `(prev, next) => boolean`.
+### Mental Model
 
-Methods:
+Compare Pulse primitives:
 
-- `.set(value: T)`: Updates the value.
-- `.update(fn: (current: T) => T)`: Updates value using a transform.
-- `.subscribe(fn: (value: T) => void)`: Manual subscription.
+| Concept     | Can be async | Has state | Observable | Purpose                              |
+| :---------- | :----------: | :-------: | :--------: | :----------------------------------- |
+| **Source**  |      ❌      |    ❌     |     ✅     | Reactive data (facts).               |
+| **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
+| **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
 
-### `guard<T>(name: string, evaluator: () => T | Promise<T>)`
+## Framework Integrations
 
-Creates a semantic guard.
+Pulse provides official adapters for major frameworks to ensure seamless integration.
 
-Methods:
+| Framework  | Package            | Documentation                                                |
+| :--------- | :----------------- | :----------------------------------------------------------- |
+| **React**  | `@pulse-js/react`  | [Read Docs](https://pulse-js.vercel.app/integrations/react)  |
+| **Vue**    | `@pulse-js/vue`    | [Read Docs](https://pulse-js.vercel.app/integrations/vue)    |
+| **Svelte** | `@pulse-js/svelte` | [Read Docs](https://pulse-js.vercel.app/integrations/svelte) |
 
-- `.ok()`: Returns true if status is 'ok'.
-- `.fail()`: Returns true if status is 'fail'.
-- `.pending()`: Returns true if evaluating async.
-- `.reason()`: Returns the failure message.
-- `.state()`: Returns full `{ status, value, reason }` object.
-- `.subscribe(fn: (state: GuardState) => void)`: Manual subscription.
+## Developer Tools
 
----
+Debug your reactive graph with **[Pulse Tools](https://pulse-js.vercel.app/guides/devtools/)**, a powerful framework-agnostic inspector.
 
-## Ecosystem
+### Features
 
-- **@pulse-js/react**: React bindings and hooks.
-- **@pulse-js/tools**: Visual debugging tools.
+- **Component Tree**: Visualize your entire guard dependency graph.
+- **Editable Logic**: Update source values directly from the UI to test logic branches.
+- **Time Travel**: (Coming Soon) Replay state changes.
+- **Zero Config**: Works out of the box with `@pulse-js/tools`.

package/dist/index.cjs

@@ -25,6 +25,8 @@ __export(index_exports, {
   evaluate: () => evaluate,
   getCurrentGuard: () => getCurrentGuard,
   guard: () => extendedGuard,
+  guardFail: () => guardFail,
+  guardOk: () => guardOk,
   hydrate: () => hydrate,
   registerGuardForHydration: () => registerGuardForHydration,
   runInContext: () => runInContext,
@@ -33,18 +35,20 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/tracking.ts
-var activeGuard = null;
+var guardStack = [];
 function runInContext(guard2, fn) {
-  const prev = activeGuard;
-  activeGuard = guard2;
+  if (guardStack.includes(guard2)) {
+    throw new Error(`Cyclic guard dependency detected: ${guard2._name || "unnamed guard"}`);
+  }
+  guardStack.push(guard2);
   try {
     return fn();
   } finally {
-    activeGuard = prev;
+    guardStack.pop();
   }
 }
 function getCurrentGuard() {
-  return activeGuard;
+  return guardStack[guardStack.length - 1] ?? null;
 }
 
 // src/ssr.ts
@@ -77,7 +81,21 @@ function hydrate(state) {
 }
 
 // src/guard.ts
-function guard(nameOrFn, fn) {
+function guardFail(reason) {
+  const guardReason = typeof reason === "string" ? {
+    code: "GUARD_FAIL",
+    message: reason,
+    toString: () => reason
+  } : reason;
+  const err = new Error(guardReason.message);
+  err._pulseFail = true;
+  err._reason = guardReason;
+  throw err;
+}
+function guardOk(value) {
+  return value;
+}
+function guard(nameOrFn, fn, _internalOffset = 3) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
   if (!evaluator) {
@@ -87,10 +105,11 @@ function guard(nameOrFn, fn) {
   const dependents = /* @__PURE__ */ new Set();
   const subscribers = /* @__PURE__ */ new Set();
   let evaluationId = 0;
-  const dependencies = /* @__PURE__ */ new Set();
+  const currentDeps = /* @__PURE__ */ new Set();
+  let lastDeps = /* @__PURE__ */ new Set();
   const node = {
     addDependency(trackable) {
-      dependencies.add(trackable);
+      currentDeps.add(trackable);
     },
     notify() {
       evaluate2();
@@ -100,56 +119,111 @@ function guard(nameOrFn, fn) {
     const currentId = ++evaluationId;
     const oldStatus = state.status;
     const oldValue = state.value;
-    dependencies.clear();
+    currentDeps.clear();
     try {
-      const result = runInContext(node, () => evaluator());
-      if (result instanceof Promise) {
-        if (state.status !== "pending") {
-          state = { ...state, status: "pending", updatedAt: Date.now() };
-          notifyDependents();
+      runInContext(node, () => {
+        node.isEvaluating = true;
+        let result;
+        try {
+          result = _evaluator();
+        } finally {
+          node.isEvaluating = false;
         }
-        result.then((resolved) => {
-          if (currentId === evaluationId) {
-            if (resolved === false) {
-              state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
-            } else {
-              state = { status: "ok", value: resolved, updatedAt: Date.now() };
-            }
+        if (result instanceof Promise) {
+          if (state.status !== "pending") {
+            state = { ...state, status: "pending", updatedAt: Date.now() };
             notifyDependents();
           }
-        }).catch((err) => {
-          if (currentId === evaluationId) {
-            state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
+          result.then((resolved) => {
+            if (currentId === evaluationId) {
+              persistDependencies();
+              if (resolved === false) {
+                const reason = name ? `${name} failed` : "condition failed";
+                state = { status: "fail", reason, lastReason: reason, updatedAt: Date.now() };
+              } else if (resolved === void 0) {
+                state = { ...state, status: "pending", updatedAt: Date.now() };
+              } else {
+                state = { status: "ok", value: resolved, updatedAt: Date.now() };
+              }
+              notifyDependents();
+            }
+          }).catch((err) => {
+            if (currentId === evaluationId) {
+              persistDependencies();
+              const message = err instanceof Error ? err.message : String(err);
+              const reason = err.meta ? {
+                code: err.code || "ERROR",
+                message,
+                meta: err.meta,
+                toString: () => message
+              } : message;
+              state = {
+                status: "fail",
+                reason,
+                lastReason: state.reason || reason,
+                updatedAt: Date.now()
+              };
+              notifyDependents();
+            }
+          });
+        } else {
+          persistDependencies();
+          if (result === false) {
+            const reason = name ? `${name} failed` : "condition failed";
+            state = { status: "fail", reason, lastReason: reason, updatedAt: Date.now() };
+          } else if (result === void 0) {
+            state = { ...state, status: "pending", updatedAt: Date.now() };
+          } else {
+            state = { status: "ok", value: result, updatedAt: Date.now() };
+          }
+          if (oldStatus !== state.status || oldValue !== state.value) {
             notifyDependents();
           }
-        });
-      } else {
-        if (result === false) {
-          state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
-        } else {
-          state = { status: "ok", value: result, updatedAt: Date.now() };
-        }
-        if (oldStatus !== state.status || oldValue !== state.value) {
-          notifyDependents();
         }
-      }
+      });
     } catch (err) {
-      state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
+      node.isEvaluating = false;
+      persistDependencies();
+      if (err._pulseFail) {
+        state = {
+          status: "fail",
+          reason: err._reason,
+          lastReason: err._reason,
+          updatedAt: Date.now()
+        };
+      } else {
+        const message = err instanceof Error ? err.message : String(err);
+        const reason = err.meta ? {
+          code: err.code || "ERROR",
+          message,
+          meta: err.meta,
+          toString: () => message
+        } : message;
+        state = {
+          status: "fail",
+          reason,
+          lastReason: reason,
+          updatedAt: Date.now()
+        };
+      }
       notifyDependents();
     }
   };
+  const _evaluator = () => evaluator();
+  const persistDependencies = () => {
+    lastDeps = new Set(currentDeps);
+  };
   const notifyDependents = () => {
     const deps = Array.from(dependents);
     dependents.clear();
     deps.forEach((dep) => dep.notify());
     subscribers.forEach((sub) => sub({ ...state }));
   };
-  evaluate2();
   const track = () => {
-    const activeGuard2 = getCurrentGuard();
-    if (activeGuard2 && activeGuard2 !== node) {
-      dependents.add(activeGuard2);
-      activeGuard2.addDependency(g);
+    const activeGuard = getCurrentGuard();
+    if (activeGuard && activeGuard !== node) {
+      dependents.add(activeGuard);
+      activeGuard.addDependency(g);
     }
   };
   const g = (() => {
@@ -170,7 +244,7 @@ function guard(nameOrFn, fn) {
   };
   g.reason = () => {
     track();
-    return state.reason;
+    return state.reason || state.lastReason;
   };
   g.state = () => {
     track();
@@ -182,7 +256,7 @@ function guard(nameOrFn, fn) {
   };
   g.explain = () => {
     const deps = [];
-    dependencies.forEach((dep) => {
+    lastDeps.forEach((dep) => {
       const depName = dep._name || "unnamed";
       const isG = "state" in dep;
       deps.push({
@@ -195,6 +269,7 @@ function guard(nameOrFn, fn) {
       name: name || "guard",
       status: state.status,
       reason: state.reason,
+      lastReason: state.lastReason,
       value: state.value,
       dependencies: deps
     };
@@ -210,6 +285,7 @@ function guard(nameOrFn, fn) {
     registerGuardForHydration(name, g);
   }
   PulseRegistry.register(g);
+  evaluate2();
   return g;
 }
 
@@ -217,13 +293,84 @@ function guard(nameOrFn, fn) {
 var Registry = class {
   units = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
+  currentGeneration = 0;
+  cleanupScheduled = false;
+  autoNameCache = /* @__PURE__ */ new Map();
+  /**
+   * Generates a stable auto-name based on source code location.
+   * Uses file path and line number to ensure the same location always gets the same name.
+   * Cached to avoid repeated stack trace parsing.
+   */
+  generateAutoName(type, offset = 3) {
+    const err = new Error();
+    const stack = err.stack?.split("\n") || [];
+    let callSite = stack[offset]?.trim() || "";
+    const cacheKey = `${type}:${callSite}`;
+    if (this.autoNameCache.has(cacheKey)) {
+      return this.autoNameCache.get(cacheKey);
+    }
+    const match = callSite.match(/([^/\\]+)\.(?:ts|tsx|js|jsx):(\d+):\d+/);
+    let name;
+    if (match) {
+      const filename = match[1];
+      const line = match[2];
+      if (filename && line) {
+        name = `${type}@${filename}:${line}`;
+      } else {
+        name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+      }
+    } else {
+      name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+    }
+    this.autoNameCache.set(cacheKey, name);
+    return name;
+  }
+  /**
+   * Increments generation and schedules cleanup of old units.
+   * Called automatically when HMR is detected.
+   */
+  scheduleCleanup() {
+    if (this.cleanupScheduled) return;
+    this.cleanupScheduled = true;
+    this.currentGeneration++;
+    setTimeout(() => {
+      this.cleanupOldGenerations();
+      this.cleanupScheduled = false;
+    }, 100);
+  }
+  /**
+   * Removes units from old generations (likely orphaned by HMR).
+   */
+  cleanupOldGenerations() {
+    const toDelete = [];
+    this.units.forEach((unit, key) => {
+      const gen = unit._generation;
+      if (gen !== void 0 && gen < this.currentGeneration) {
+        toDelete.push(key);
+      }
+    });
+    toDelete.forEach((key) => this.units.delete(key));
+    if (toDelete.length > 0) {
+      console.log(`[Pulse] Cleaned up ${toDelete.length} stale units after HMR`);
+    }
+  }
   /**
    * Registers a new unit (Source or Guard).
-   * Uses the unit's name as a key to prevent duplicates during HMR.
+   * Auto-assigns stable names to unnamed units for HMR stability.
    */
-  register(unit) {
-    const key = unit._name || unit;
-    this.units.set(key, unit);
+  register(unit, offset = 3) {
+    const unitWithMetadata = unit;
+    let name = unitWithMetadata._name;
+    if (!name) {
+      const isGuard2 = "state" in unit;
+      name = this.generateAutoName(isGuard2 ? "guard" : "source", offset);
+      unitWithMetadata._name = name;
+    }
+    unitWithMetadata._generation = this.currentGeneration;
+    if (this.units.has(name)) {
+      this.scheduleCleanup();
+    }
+    this.units.set(name, unit);
     this.listeners.forEach((l) => l(unit));
   }
   /**
@@ -244,19 +391,32 @@ var Registry = class {
       this.listeners.delete(listener);
     };
   }
+  /**
+   * Clears all registered units.
+   */
+  reset() {
+    this.units.clear();
+    this.currentGeneration = 0;
+    this.autoNameCache.clear();
+  }
 };
-var PulseRegistry = new Registry();
+var GLOBAL_KEY = "__PULSE_REGISTRY__";
+var globalSymbols = globalThis;
+if (!globalSymbols[GLOBAL_KEY]) {
+  globalSymbols[GLOBAL_KEY] = new Registry();
+}
+var PulseRegistry = globalSymbols[GLOBAL_KEY];
 
 // src/source.ts
-function source(initialValue, options = {}) {
+function source(initialValue, options = {}, _internalOffset = 3) {
   let value = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
   const dependents = /* @__PURE__ */ new Set();
   const s = (() => {
-    const activeGuard2 = getCurrentGuard();
-    if (activeGuard2) {
-      dependents.add(activeGuard2);
-      activeGuard2.addDependency(s);
+    const activeGuard = getCurrentGuard();
+    if (activeGuard) {
+      dependents.add(activeGuard);
+      activeGuard.addDependency(s);
     }
     return value;
   });
@@ -287,7 +447,7 @@ function compute(name, dependencies, processor) {
   return guard(name, () => {
     const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
     return processor(...values);
-  });
+  }, 4);
 }
 
 // src/composition.ts
@@ -305,10 +465,12 @@ function guardAll(nameOrGuards, maybeGuards) {
       }
     }
     if (firstFail) {
-      throw new Error(firstFail.reason() || "condition failed");
+      const reason = firstFail.reason();
+      const message = typeof reason === "string" ? reason : reason?.toString() || "condition failed";
+      throw new Error(message);
     }
     return true;
-  });
+  }, 4);
 }
 function guardAny(nameOrGuards, maybeGuards) {
   const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
@@ -317,10 +479,12 @@ function guardAny(nameOrGuards, maybeGuards) {
     let allFails = [];
     for (const g of guards) {
       if (g.ok()) return true;
-      allFails.push(g.reason() || "failed");
+      const reason = g.reason();
+      const message = typeof reason === "string" ? reason : reason?.toString() || "failed";
+      allFails.push(message);
     }
     throw new Error(allFails.length > 0 ? allFails.join(" and ") : "no conditions met");
-  });
+  }, 4);
 }
 function guardNot(nameOrTarget, maybeTarget) {
   const name = typeof nameOrTarget === "string" ? nameOrTarget : void 0;
@@ -330,7 +494,7 @@ function guardNot(nameOrTarget, maybeTarget) {
       return !target.ok();
     }
     return !target();
-  });
+  }, 4);
 }
 var guardExtensions = {
   all: guardAll,
@@ -348,6 +512,8 @@ var extendedGuard = Object.assign(guard, guardExtensions);
   evaluate,
   getCurrentGuard,
   guard,
+  guardFail,
+  guardOk,
   hydrate,
   registerGuardForHydration,
   runInContext,

package/dist/index.d.cts

@@ -19,6 +19,8 @@ interface GuardNode extends Trackable {
      * Internal use only.
      */
     addDependency(trackable: any): void;
+    /** Whether the guard is currently evaluating. */
+    isEvaluating?: boolean;
 }
 /**
  * Executes a function within the context of a specific Guard.
@@ -28,6 +30,7 @@ interface GuardNode extends Trackable {
  * @param guard The guard node to set as active.
  * @param fn The function to execute.
  * @returns The result of the function.
+ * @throws Error if a cyclic dependency is detected.
  */
 declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
 /**
@@ -41,10 +44,20 @@ declare function getCurrentGuard(): GuardNode | null;
 /**
  * Status of a Pulse Guard evaluation.
  * - 'pending': Async evaluation is in progress.
- * - 'ok': Evaluation completed successfully (return value was not `false`).
- * - 'fail': Evaluation encountered an error or return value was `false`.
+ * - 'ok': Evaluation completed successfully.
+ * - 'fail': Evaluation encountered an error or return value was explicitly `false`.
  */
 type GuardStatus = 'ok' | 'fail' | 'pending';
+/**
+ * Structured reason for a guard failure.
+ * Includes toString() so it can be rendered directly in React and other UI frameworks.
+ */
+interface GuardReason {
+    code: string;
+    message: string;
+    meta?: any;
+    toString(): string;
+}
 /**
  * The internal state of a Pulse Guard.
  */
@@ -53,8 +66,10 @@ interface GuardState<T> {
     status: GuardStatus;
     /** The value returned by the evaluator (only if status is 'ok'). */
     value?: T;
-    /** The message explaining why the guard failed (only if status is 'fail'). */
-    reason?: string;
+    /** The reason why the guard failed. */
+    reason?: string | GuardReason;
+    /** The last known failure reason, persisted even during 'pending'. */
+    lastReason?: string | GuardReason;
     /** The timestamp when the status last changed. */
     updatedAt?: number;
 }
@@ -64,7 +79,8 @@ interface GuardState<T> {
 interface GuardExplanation {
     name: string;
     status: GuardStatus;
-    reason?: string;
+    reason?: string | GuardReason;
+    lastReason?: string | GuardReason;
     value?: any;
     dependencies: Array<{
         name: string;
@@ -110,7 +126,7 @@ interface Guard<T = boolean> {
      *
      * @returns The error message or undefined.
      */
-    reason(): string | undefined;
+    reason(): string | GuardReason | undefined;
     /**
      * Returns a snapshot of the full internal state of the guard.
      * Useful for adapters (like React) to synchronize with the guard.
@@ -127,12 +143,10 @@ interface Guard<T = boolean> {
     subscribe(listener: Subscriber<GuardState<T>>): () => void;
     /**
      * Returns a structured explanation of the guard's state and its direct dependencies.
-     * Useful for DevTools and sophisticated error reporting.
      */
     explain(): GuardExplanation;
     /**
      * Manually forces a re-evaluation of the guard.
-     * Typically used internally by Pulse or for debugging.
      * @internal
      */
     _evaluate(): void;
@@ -160,7 +174,19 @@ interface Guard<T = boolean> {
  * });
  * ```
  */
-declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+/**
+ * Signals that a Guard should fail with a specific reason.
+ *
+ * @param reason - The reason for failure.
+ * @throws An internal signal error caught by the Guard evaluator.
+ */
+declare function guardFail(reason: string | GuardReason): never;
+/**
+ * Explicitly signals a successful Guard evaluation.
+ * Returns the value passed to it.
+ */
+declare function guardOk<T>(value: T): T;
+declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>, _internalOffset?: number): Guard<T>;
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -335,7 +361,7 @@ interface Source<T> {
  * user.set({ name: 'Bob' });
  * ```
  */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+declare function source<T>(initialValue: T, options?: SourceOptions<T>, _internalOffset?: number): Source<T>;
 
 /**
  * Serialized state of guards for transfer from server to client.
@@ -396,11 +422,29 @@ type PulseUnit = Source<any> | Guard<any>;
 declare class Registry {
     private units;
     private listeners;
+    private currentGeneration;
+    private cleanupScheduled;
+    private autoNameCache;
+    /**
+     * Generates a stable auto-name based on source code location.
+     * Uses file path and line number to ensure the same location always gets the same name.
+     * Cached to avoid repeated stack trace parsing.
+     */
+    generateAutoName(type: 'source' | 'guard', offset?: number): string;
+    /**
+     * Increments generation and schedules cleanup of old units.
+     * Called automatically when HMR is detected.
+     */
+    private scheduleCleanup;
+    /**
+     * Removes units from old generations (likely orphaned by HMR).
+     */
+    private cleanupOldGenerations;
     /**
      * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
+     * Auto-assigns stable names to unnamed units for HMR stability.
      */
-    register(unit: PulseUnit): void;
+    register(unit: PulseUnit, offset?: number): void;
     /**
      * Retrieves all registered units.
      */
@@ -412,6 +456,10 @@ declare class Registry {
      * @returns Unsubscribe function.
      */
     onRegister(listener: (unit: PulseUnit) => void): () => void;
+    /**
+     * Clears all registered units.
+     */
+    reset(): void;
 }
 declare const PulseRegistry: Registry;
 
@@ -434,4 +482,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-export { type Guard, type GuardExplanation, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, registerGuardForHydration, runInContext, source };

package/dist/index.d.ts

@@ -19,6 +19,8 @@ interface GuardNode extends Trackable {
      * Internal use only.
      */
     addDependency(trackable: any): void;
+    /** Whether the guard is currently evaluating. */
+    isEvaluating?: boolean;
 }
 /**
  * Executes a function within the context of a specific Guard.
@@ -28,6 +30,7 @@ interface GuardNode extends Trackable {
  * @param guard The guard node to set as active.
  * @param fn The function to execute.
  * @returns The result of the function.
+ * @throws Error if a cyclic dependency is detected.
  */
 declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
 /**
@@ -41,10 +44,20 @@ declare function getCurrentGuard(): GuardNode | null;
 /**
  * Status of a Pulse Guard evaluation.
  * - 'pending': Async evaluation is in progress.
- * - 'ok': Evaluation completed successfully (return value was not `false`).
- * - 'fail': Evaluation encountered an error or return value was `false`.
+ * - 'ok': Evaluation completed successfully.
+ * - 'fail': Evaluation encountered an error or return value was explicitly `false`.
  */
 type GuardStatus = 'ok' | 'fail' | 'pending';
+/**
+ * Structured reason for a guard failure.
+ * Includes toString() so it can be rendered directly in React and other UI frameworks.
+ */
+interface GuardReason {
+    code: string;
+    message: string;
+    meta?: any;
+    toString(): string;
+}
 /**
  * The internal state of a Pulse Guard.
  */
@@ -53,8 +66,10 @@ interface GuardState<T> {
     status: GuardStatus;
     /** The value returned by the evaluator (only if status is 'ok'). */
     value?: T;
-    /** The message explaining why the guard failed (only if status is 'fail'). */
-    reason?: string;
+    /** The reason why the guard failed. */
+    reason?: string | GuardReason;
+    /** The last known failure reason, persisted even during 'pending'. */
+    lastReason?: string | GuardReason;
     /** The timestamp when the status last changed. */
     updatedAt?: number;
 }
@@ -64,7 +79,8 @@ interface GuardState<T> {
 interface GuardExplanation {
     name: string;
     status: GuardStatus;
-    reason?: string;
+    reason?: string | GuardReason;
+    lastReason?: string | GuardReason;
     value?: any;
     dependencies: Array<{
         name: string;
@@ -110,7 +126,7 @@ interface Guard<T = boolean> {
      *
      * @returns The error message or undefined.
      */
-    reason(): string | undefined;
+    reason(): string | GuardReason | undefined;
     /**
      * Returns a snapshot of the full internal state of the guard.
      * Useful for adapters (like React) to synchronize with the guard.
@@ -127,12 +143,10 @@ interface Guard<T = boolean> {
     subscribe(listener: Subscriber<GuardState<T>>): () => void;
     /**
      * Returns a structured explanation of the guard's state and its direct dependencies.
-     * Useful for DevTools and sophisticated error reporting.
      */
     explain(): GuardExplanation;
     /**
      * Manually forces a re-evaluation of the guard.
-     * Typically used internally by Pulse or for debugging.
      * @internal
      */
     _evaluate(): void;
@@ -160,7 +174,19 @@ interface Guard<T = boolean> {
  * });
  * ```
  */
-declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+/**
+ * Signals that a Guard should fail with a specific reason.
+ *
+ * @param reason - The reason for failure.
+ * @throws An internal signal error caught by the Guard evaluator.
+ */
+declare function guardFail(reason: string | GuardReason): never;
+/**
+ * Explicitly signals a successful Guard evaluation.
+ * Returns the value passed to it.
+ */
+declare function guardOk<T>(value: T): T;
+declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>, _internalOffset?: number): Guard<T>;
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -335,7 +361,7 @@ interface Source<T> {
  * user.set({ name: 'Bob' });
  * ```
  */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+declare function source<T>(initialValue: T, options?: SourceOptions<T>, _internalOffset?: number): Source<T>;
 
 /**
  * Serialized state of guards for transfer from server to client.
@@ -396,11 +422,29 @@ type PulseUnit = Source<any> | Guard<any>;
 declare class Registry {
     private units;
     private listeners;
+    private currentGeneration;
+    private cleanupScheduled;
+    private autoNameCache;
+    /**
+     * Generates a stable auto-name based on source code location.
+     * Uses file path and line number to ensure the same location always gets the same name.
+     * Cached to avoid repeated stack trace parsing.
+     */
+    generateAutoName(type: 'source' | 'guard', offset?: number): string;
+    /**
+     * Increments generation and schedules cleanup of old units.
+     * Called automatically when HMR is detected.
+     */
+    private scheduleCleanup;
+    /**
+     * Removes units from old generations (likely orphaned by HMR).
+     */
+    private cleanupOldGenerations;
     /**
      * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
+     * Auto-assigns stable names to unnamed units for HMR stability.
      */
-    register(unit: PulseUnit): void;
+    register(unit: PulseUnit, offset?: number): void;
     /**
      * Retrieves all registered units.
      */
@@ -412,6 +456,10 @@ declare class Registry {
      * @returns Unsubscribe function.
      */
     onRegister(listener: (unit: PulseUnit) => void): () => void;
+    /**
+     * Clears all registered units.
+     */
+    reset(): void;
 }
 declare const PulseRegistry: Registry;
 
@@ -434,4 +482,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-export { type Guard, type GuardExplanation, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, registerGuardForHydration, runInContext, source };

package/dist/index.js

@@ -1,16 +1,18 @@
 // src/tracking.ts
-var activeGuard = null;
+var guardStack = [];
 function runInContext(guard2, fn) {
-  const prev = activeGuard;
-  activeGuard = guard2;
+  if (guardStack.includes(guard2)) {
+    throw new Error(`Cyclic guard dependency detected: ${guard2._name || "unnamed guard"}`);
+  }
+  guardStack.push(guard2);
   try {
     return fn();
   } finally {
-    activeGuard = prev;
+    guardStack.pop();
   }
 }
 function getCurrentGuard() {
-  return activeGuard;
+  return guardStack[guardStack.length - 1] ?? null;
 }
 
 // src/ssr.ts
@@ -43,7 +45,21 @@ function hydrate(state) {
 }
 
 // src/guard.ts
-function guard(nameOrFn, fn) {
+function guardFail(reason) {
+  const guardReason = typeof reason === "string" ? {
+    code: "GUARD_FAIL",
+    message: reason,
+    toString: () => reason
+  } : reason;
+  const err = new Error(guardReason.message);
+  err._pulseFail = true;
+  err._reason = guardReason;
+  throw err;
+}
+function guardOk(value) {
+  return value;
+}
+function guard(nameOrFn, fn, _internalOffset = 3) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
   if (!evaluator) {
@@ -53,10 +69,11 @@ function guard(nameOrFn, fn) {
   const dependents = /* @__PURE__ */ new Set();
   const subscribers = /* @__PURE__ */ new Set();
   let evaluationId = 0;
-  const dependencies = /* @__PURE__ */ new Set();
+  const currentDeps = /* @__PURE__ */ new Set();
+  let lastDeps = /* @__PURE__ */ new Set();
   const node = {
     addDependency(trackable) {
-      dependencies.add(trackable);
+      currentDeps.add(trackable);
     },
     notify() {
       evaluate2();
@@ -66,56 +83,111 @@ function guard(nameOrFn, fn) {
     const currentId = ++evaluationId;
     const oldStatus = state.status;
     const oldValue = state.value;
-    dependencies.clear();
+    currentDeps.clear();
     try {
-      const result = runInContext(node, () => evaluator());
-      if (result instanceof Promise) {
-        if (state.status !== "pending") {
-          state = { ...state, status: "pending", updatedAt: Date.now() };
-          notifyDependents();
+      runInContext(node, () => {
+        node.isEvaluating = true;
+        let result;
+        try {
+          result = _evaluator();
+        } finally {
+          node.isEvaluating = false;
         }
-        result.then((resolved) => {
-          if (currentId === evaluationId) {
-            if (resolved === false) {
-              state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
-            } else {
-              state = { status: "ok", value: resolved, updatedAt: Date.now() };
-            }
+        if (result instanceof Promise) {
+          if (state.status !== "pending") {
+            state = { ...state, status: "pending", updatedAt: Date.now() };
             notifyDependents();
           }
-        }).catch((err) => {
-          if (currentId === evaluationId) {
-            state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
+          result.then((resolved) => {
+            if (currentId === evaluationId) {
+              persistDependencies();
+              if (resolved === false) {
+                const reason = name ? `${name} failed` : "condition failed";
+                state = { status: "fail", reason, lastReason: reason, updatedAt: Date.now() };
+              } else if (resolved === void 0) {
+                state = { ...state, status: "pending", updatedAt: Date.now() };
+              } else {
+                state = { status: "ok", value: resolved, updatedAt: Date.now() };
+              }
+              notifyDependents();
+            }
+          }).catch((err) => {
+            if (currentId === evaluationId) {
+              persistDependencies();
+              const message = err instanceof Error ? err.message : String(err);
+              const reason = err.meta ? {
+                code: err.code || "ERROR",
+                message,
+                meta: err.meta,
+                toString: () => message
+              } : message;
+              state = {
+                status: "fail",
+                reason,
+                lastReason: state.reason || reason,
+                updatedAt: Date.now()
+              };
+              notifyDependents();
+            }
+          });
+        } else {
+          persistDependencies();
+          if (result === false) {
+            const reason = name ? `${name} failed` : "condition failed";
+            state = { status: "fail", reason, lastReason: reason, updatedAt: Date.now() };
+          } else if (result === void 0) {
+            state = { ...state, status: "pending", updatedAt: Date.now() };
+          } else {
+            state = { status: "ok", value: result, updatedAt: Date.now() };
+          }
+          if (oldStatus !== state.status || oldValue !== state.value) {
             notifyDependents();
           }
-        });
-      } else {
-        if (result === false) {
-          state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
-        } else {
-          state = { status: "ok", value: result, updatedAt: Date.now() };
-        }
-        if (oldStatus !== state.status || oldValue !== state.value) {
-          notifyDependents();
         }
-      }
+      });
     } catch (err) {
-      state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
+      node.isEvaluating = false;
+      persistDependencies();
+      if (err._pulseFail) {
+        state = {
+          status: "fail",
+          reason: err._reason,
+          lastReason: err._reason,
+          updatedAt: Date.now()
+        };
+      } else {
+        const message = err instanceof Error ? err.message : String(err);
+        const reason = err.meta ? {
+          code: err.code || "ERROR",
+          message,
+          meta: err.meta,
+          toString: () => message
+        } : message;
+        state = {
+          status: "fail",
+          reason,
+          lastReason: reason,
+          updatedAt: Date.now()
+        };
+      }
       notifyDependents();
     }
   };
+  const _evaluator = () => evaluator();
+  const persistDependencies = () => {
+    lastDeps = new Set(currentDeps);
+  };
   const notifyDependents = () => {
     const deps = Array.from(dependents);
     dependents.clear();
     deps.forEach((dep) => dep.notify());
     subscribers.forEach((sub) => sub({ ...state }));
   };
-  evaluate2();
   const track = () => {
-    const activeGuard2 = getCurrentGuard();
-    if (activeGuard2 && activeGuard2 !== node) {
-      dependents.add(activeGuard2);
-      activeGuard2.addDependency(g);
+    const activeGuard = getCurrentGuard();
+    if (activeGuard && activeGuard !== node) {
+      dependents.add(activeGuard);
+      activeGuard.addDependency(g);
     }
   };
   const g = (() => {
@@ -136,7 +208,7 @@ function guard(nameOrFn, fn) {
   };
   g.reason = () => {
     track();
-    return state.reason;
+    return state.reason || state.lastReason;
   };
   g.state = () => {
     track();
@@ -148,7 +220,7 @@ function guard(nameOrFn, fn) {
   };
   g.explain = () => {
     const deps = [];
-    dependencies.forEach((dep) => {
+    lastDeps.forEach((dep) => {
       const depName = dep._name || "unnamed";
       const isG = "state" in dep;
       deps.push({
@@ -161,6 +233,7 @@ function guard(nameOrFn, fn) {
       name: name || "guard",
       status: state.status,
       reason: state.reason,
+      lastReason: state.lastReason,
       value: state.value,
       dependencies: deps
     };
@@ -176,6 +249,7 @@ function guard(nameOrFn, fn) {
     registerGuardForHydration(name, g);
   }
   PulseRegistry.register(g);
+  evaluate2();
   return g;
 }
 
@@ -183,13 +257,84 @@ function guard(nameOrFn, fn) {
 var Registry = class {
   units = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
+  currentGeneration = 0;
+  cleanupScheduled = false;
+  autoNameCache = /* @__PURE__ */ new Map();
+  /**
+   * Generates a stable auto-name based on source code location.
+   * Uses file path and line number to ensure the same location always gets the same name.
+   * Cached to avoid repeated stack trace parsing.
+   */
+  generateAutoName(type, offset = 3) {
+    const err = new Error();
+    const stack = err.stack?.split("\n") || [];
+    let callSite = stack[offset]?.trim() || "";
+    const cacheKey = `${type}:${callSite}`;
+    if (this.autoNameCache.has(cacheKey)) {
+      return this.autoNameCache.get(cacheKey);
+    }
+    const match = callSite.match(/([^/\\]+)\.(?:ts|tsx|js|jsx):(\d+):\d+/);
+    let name;
+    if (match) {
+      const filename = match[1];
+      const line = match[2];
+      if (filename && line) {
+        name = `${type}@${filename}:${line}`;
+      } else {
+        name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+      }
+    } else {
+      name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+    }
+    this.autoNameCache.set(cacheKey, name);
+    return name;
+  }
+  /**
+   * Increments generation and schedules cleanup of old units.
+   * Called automatically when HMR is detected.
+   */
+  scheduleCleanup() {
+    if (this.cleanupScheduled) return;
+    this.cleanupScheduled = true;
+    this.currentGeneration++;
+    setTimeout(() => {
+      this.cleanupOldGenerations();
+      this.cleanupScheduled = false;
+    }, 100);
+  }
+  /**
+   * Removes units from old generations (likely orphaned by HMR).
+   */
+  cleanupOldGenerations() {
+    const toDelete = [];
+    this.units.forEach((unit, key) => {
+      const gen = unit._generation;
+      if (gen !== void 0 && gen < this.currentGeneration) {
+        toDelete.push(key);
+      }
+    });
+    toDelete.forEach((key) => this.units.delete(key));
+    if (toDelete.length > 0) {
+      console.log(`[Pulse] Cleaned up ${toDelete.length} stale units after HMR`);
+    }
+  }
   /**
    * Registers a new unit (Source or Guard).
-   * Uses the unit's name as a key to prevent duplicates during HMR.
+   * Auto-assigns stable names to unnamed units for HMR stability.
    */
-  register(unit) {
-    const key = unit._name || unit;
-    this.units.set(key, unit);
+  register(unit, offset = 3) {
+    const unitWithMetadata = unit;
+    let name = unitWithMetadata._name;
+    if (!name) {
+      const isGuard2 = "state" in unit;
+      name = this.generateAutoName(isGuard2 ? "guard" : "source", offset);
+      unitWithMetadata._name = name;
+    }
+    unitWithMetadata._generation = this.currentGeneration;
+    if (this.units.has(name)) {
+      this.scheduleCleanup();
+    }
+    this.units.set(name, unit);
     this.listeners.forEach((l) => l(unit));
   }
   /**
@@ -210,19 +355,32 @@ var Registry = class {
       this.listeners.delete(listener);
     };
   }
+  /**
+   * Clears all registered units.
+   */
+  reset() {
+    this.units.clear();
+    this.currentGeneration = 0;
+    this.autoNameCache.clear();
+  }
 };
-var PulseRegistry = new Registry();
+var GLOBAL_KEY = "__PULSE_REGISTRY__";
+var globalSymbols = globalThis;
+if (!globalSymbols[GLOBAL_KEY]) {
+  globalSymbols[GLOBAL_KEY] = new Registry();
+}
+var PulseRegistry = globalSymbols[GLOBAL_KEY];
 
 // src/source.ts
-function source(initialValue, options = {}) {
+function source(initialValue, options = {}, _internalOffset = 3) {
   let value = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
   const dependents = /* @__PURE__ */ new Set();
   const s = (() => {
-    const activeGuard2 = getCurrentGuard();
-    if (activeGuard2) {
-      dependents.add(activeGuard2);
-      activeGuard2.addDependency(s);
+    const activeGuard = getCurrentGuard();
+    if (activeGuard) {
+      dependents.add(activeGuard);
+      activeGuard.addDependency(s);
     }
     return value;
   });
@@ -253,7 +411,7 @@ function compute(name, dependencies, processor) {
   return guard(name, () => {
     const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
     return processor(...values);
-  });
+  }, 4);
 }
 
 // src/composition.ts
@@ -271,10 +429,12 @@ function guardAll(nameOrGuards, maybeGuards) {
       }
     }
     if (firstFail) {
-      throw new Error(firstFail.reason() || "condition failed");
+      const reason = firstFail.reason();
+      const message = typeof reason === "string" ? reason : reason?.toString() || "condition failed";
+      throw new Error(message);
     }
     return true;
-  });
+  }, 4);
 }
 function guardAny(nameOrGuards, maybeGuards) {
   const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
@@ -283,10 +443,12 @@ function guardAny(nameOrGuards, maybeGuards) {
     let allFails = [];
     for (const g of guards) {
       if (g.ok()) return true;
-      allFails.push(g.reason() || "failed");
+      const reason = g.reason();
+      const message = typeof reason === "string" ? reason : reason?.toString() || "failed";
+      allFails.push(message);
     }
     throw new Error(allFails.length > 0 ? allFails.join(" and ") : "no conditions met");
-  });
+  }, 4);
 }
 function guardNot(nameOrTarget, maybeTarget) {
   const name = typeof nameOrTarget === "string" ? nameOrTarget : void 0;
@@ -296,7 +458,7 @@ function guardNot(nameOrTarget, maybeTarget) {
       return !target.ok();
     }
     return !target();
-  });
+  }, 4);
 }
 var guardExtensions = {
   all: guardAll,
@@ -313,6 +475,8 @@ export {
   evaluate,
   getCurrentGuard,
   extendedGuard as guard,
+  guardFail,
+  guardOk,
   hydrate,
   registerGuardForHydration,
   runInContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/core",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "module": "dist/index.js",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -17,7 +17,9 @@
   "type": "module",
   "description": "A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.",
   "workspaces": [
-    "packages/*"
+    "packages/*",
+    "tests",
+    "tests/*"
   ],
   "keywords": [
     "reactivity",
@@ -36,7 +38,7 @@
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/ZtaMDev/pulse/issues"
+    "url": "https://github.com/ZtaMDev/pulse-js/issues"
   },
   "license": "MIT",
   "scripts": {
@@ -46,12 +48,22 @@
     "test": "vitest run"
   },
   "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/svelte": "^5.3.1",
+    "@testing-library/vue": "^8.1.0",
     "@types/bun": "latest",
     "@types/react": "^19.2.8",
     "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^27.4.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
-    "vitest": "^4.0.17"
+    "svelte": "^5.46.4",
+    "vitest": "^4.0.17",
+    "vue": "^3.5.26"
   },
   "peerDependencies": {
     "typescript": "^5"