# The Reactive Core: `$( )`

The `$` function is a **Unified Reactive Constructor**. It detects the type of input you provide and returns the appropriate reactive primitive.

---

## 1. Signals (Atomic State)
A **Signal** is the simplest form of reactivity. It holds a single value (string, number, boolean, null).

### **Option A: Standard Signal (RAM)**
Ideal for volatile state that shouldn't persist after a page refresh.
```javascript
const $count = $(0); 

// Usage:
$count();           // Getter: returns 0
$count(10);         // Setter: updates to 10
$count(c => c + 1); // Functional update: updates to 11
```

### **Option B: Persistent Signal (Disk)**
By adding a `key`, SigPro links the signal to `localStorage`.
```javascript
// Syntax: $(initialValue, "storage-key")
const $theme = $("light", "app-theme"); 

// It restores the value from disk automatically on load.
// When you update it, it saves to disk instantly:
$theme("dark"); // localStorage.getItem("app-theme") is now "dark"
```

---

## 2. Stores (Reactive Objects)
A **Store** is a proxy that wraps an **Object**. SigPro makes every property reactive recursively. You access and set properties as if they were individual signals.

### **Option A: Standard Store (RAM)**
```javascript
const user = $({ 
  name: "Alice", 
  profile: { bio: "Developer" } 
});

// Getter: Call the property as a function
console.log(user.name()); // "Alice"

// Setter: Pass the value to the property function
user.name("Bob"); 

// Nested updates work exactly the same:
user.profile.bio("Architect");
```

### **Option B: Persistent Store (Disk)**
The most powerful way to save complex state. The **entire object tree** is serialized to JSON and kept in sync with the disk.
```javascript
const settings = $({ 
  volume: 50, 
  notifications: true 
}, "user-settings");

// Any change in the object triggers a disk sync:
settings.volume(100); // The whole JSON is updated in localStorage
```

---

## 3. Stores (Reactive Arrays)
When you pass an **Array**, SigPro tracks changes to the list. You can use standard methods or access indexes as reactive getters.

```javascript
const $list = $(["Item 1", "Item 2"]);

// Get by index
console.log($list[0]()); // "Item 1"

// Update by index
$list[0]("Updated Item");

// Note: For adding/removing items, use standard array methods 
// which SigPro makes reactive (push, pop, splice, etc.)
```

---

## 4. Computed (Derived Logic)
A **Computed Signal** is a read-only value that depends on other signals. It is defined by passing a **function that returns a value**.

```javascript
const $price = $(100);
const $tax = $(0.21);

// This function HAS a return statement
const $total = $(() => {
  return $price() * (1 + $tax());
});

// Usage (Read-only):
console.log($total()); // 121

$price(200);
console.log($total()); // 242 (Auto-updated)
```

---

## 5. Effects (Reactive Actions)
An **Effect** is used for side-effects. It is defined by passing a **function that does NOT return a value**. It runs once immediately and then re-runs whenever its dependencies change.

```javascript
const $name = $("Alice");

// This function has NO return statement (Side-effect)
$(() => {
  console.log("The name changed to:", $name());
  document.title = `Profile: ${$name()}`;
});

$name("Bob"); // Triggers the console.log and updates document.title
```

---

## 6. Summary: Input Mapping

| If you pass... | SigPro creates a... | Access Method |
| :--- | :--- | :--- |
| **A Value** | **Signal** | `$var()` / `$var(val)` |
| **An Object** | **Store** | `obj.prop()` / `obj.prop(val)` |
| **An Array** | **Array Store** | `arr[i]()` / `arr.push()` |
| **Function (returns)** | **Computed** | `$comp()` (Read-only) |
| **Function (no return)** | **Effect** | Automatically executed |

---

## 💡 Naming Convention: The `$` Prefix
To keep your code clean, always prefix your reactive variables with `$`. This tells you at a glance that you need to call it as a function to get its value.

```javascript
const name = "Static";   // Just a string
const $name = $("Alice"); // A Reactive Signal
```