@pulse-js/core 0.1.6 → 0.1.8

package/README.md

@@ -8,16 +8,6 @@
 
 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.
 
-### Mental Model
-
-Compare Pulse primitives at a glance:
-
-| Concept     | Can be async | Has state | Observable | Purpose                              |
-| :---------- | :----------: | :-------: | :--------: | :----------------------------------- |
-| **Source**  |      ❌      |    ❌     |     ✅     | Reactive data (facts).               |
-| **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
-| **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
-
 </div>
 
 ## Installation
@@ -146,6 +136,16 @@ import { hydrate } from "@pulse-js/core";
 hydrate(window.__PULSE_STATE__);
 ```
 
+### Mental Model
+
+Compare Pulse primitives:
+
+| Concept     | Can be async | Has state | Observable | Purpose                              |
+| :---------- | :----------: | :-------: | :--------: | :----------------------------------- |
+| **Source**  |      ❌      |    ❌     |     ✅     | Reactive data (facts).               |
+| **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
+| **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
+
 ## API Reference
 
 ### `source<T>(initialValue: T, options?: SourceOptions)`

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,6 +81,20 @@ function hydrate(state) {
 }
 
 // src/guard.ts
+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) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
@@ -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;
 }
 
@@ -253,10 +329,10 @@ function source(initialValue, options = {}) {
   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;
   });
@@ -305,7 +381,9 @@ 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;
   });
@@ -317,7 +395,9 @@ 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");
   });
@@ -348,6 +428,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,6 +174,18 @@ interface Guard<T = boolean> {
  * });
  * ```
  */
+/**
+ * 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>): Guard<T>;
 
 /**
@@ -434,4 +460,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,6 +174,18 @@ interface Guard<T = boolean> {
  * });
  * ```
  */
+/**
+ * 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>): Guard<T>;
 
 /**
@@ -434,4 +460,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,6 +45,20 @@ function hydrate(state) {
 }
 
 // src/guard.ts
+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) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
@@ -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;
 }
 
@@ -219,10 +293,10 @@ function source(initialValue, options = {}) {
   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;
   });
@@ -271,7 +345,9 @@ 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;
   });
@@ -283,7 +359,9 @@ 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");
   });
@@ -313,6 +391,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.6",
+  "version": "0.1.8",
   "module": "dist/index.js",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -17,7 +17,8 @@
   "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"
   ],
   "keywords": [
     "reactivity",
@@ -46,12 +47,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"