@pulse-js/core 0.2.1 → 0.3.0

package/README.md

@@ -1,172 +1,97 @@
 <div align="center">
-
 <img width="200" height="200" alt="logo" src="https://raw.githubusercontent.com/ZtaMDev/Pulse/refs/heads/main/pulse.svg" />
 
-# Pulse-JS
+# Pulse-JS v2.0
 
-[![npm version](https://img.shields.io/npm/v/@pulse-js/core.svg)](https://www.npmjs.com/package/@pulse-js/core)
+[![npm version](https://img.shields.io/npm/v/@pulse-js/core.svg?color=blue)](https://www.npmjs.com/package/@pulse-js/core)
 
-> A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.
+> A semantic reactivity system for modern applications. Separate reactive state (pulse) from business conditions (guards) with a declarative, composable, and proxied approach.
 
 Official [Documentation](https://pulse-js.vercel.app)
 
-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.
+Pulse differs from traditional signals or state managers by treating `Conditions` as first-class citizens. Instead of embedding complex boolean logic inside components, you define **Semantic Guards** that are observed, composed, and debugged independently.
 
 </div>
 
 ## Installation
 
-```bash
-npm install @pulse-js/core @pulse-js/tools
-```
-
-### or
-
 ```bash
 bun add @pulse-js/core @pulse-js/tools
 ```
 
-Pulse works with React via adapters like `@pulse-js/react`.
-
-```bash
-bun add @pulse-js/react
-```
-
 ## Core Concepts
 
-### Sources (Refined Data)
+### Pulse Objects (Universal Reactivity)
 
-Sources are the primitive containers for your application state. They hold values and notify dependents when those values change.
+`pulse()` creates a deep reactive Proxy. Use it for complex objects and arrays. Track property access automatically and mutate state directly.
 
 ```typescript
-import { source } from "@pulse-js/core";
+import { pulse } from "@pulse-js/core";
+
+const user = pulse({
+  name: "Alice",
+  role: "admin",
+  increment() {
+    this.stats.clicks++;
+  },
+  stats: { clicks: 0 },
+});
 
-// Create a source
-const user = source({ name: "Alice", id: 1 });
-const rawCount = source(0);
+// Mutate directly - it's reactive!
+user.name = "Bob";
+user.increment();
+```
 
-// Read the value (dependencies are tracked automatically if called inside a Guard)
-console.log(user());
+### Sources (Primitive Records)
 
-// Update the value
-user.set({ name: "Bob", id: 1 });
+Sources are primitive containers for your application state. They hold values and notify dependents when those values change.
 
-// Update using a callback
-rawCount.update((n) => n + 1);
+```typescript
+import { source } from "@pulse-js/core";
+const count = source(0);
+count.set(5);
 ```
 
 ### Guards (Semantic Logic)
 
-Guards represent business rules or derivations. A Guard is not just a boolean: it is a **Semantic Guard**—an observable rule with context. They track their own state including `status` (ok, fail, pending) and `reason` (why it failed).
+Guards represent business rules or derivations. They act as high-performance **Selectors** with built-in dependency tracking and rich failure context.
 
 ```typescript
 import { guard } from "@pulse-js/core";
 
-// Synchronous Guard
-const isAdmin = guard("is-admin", () => {
+const isAuthorized = guard("auth-check", async () => {
   const u = user();
-  if (u.role !== "admin") return false; // Implicitly sets status to 'fail'
-  return true;
-});
-
-// Guards can be checked explicitly
-if (isAdmin.ok()) {
-  // Grant access
-} else {
-  console.log(isAdmin.reason()); // e.g. "is-admin failed"
-}
-```
-
-### Computed Values
-
-You can derive new data from sources or other guards using `compute`. It works like a memoized transformation that automatically re-evaluates when dependencies change.
-
-```typescript
-import { compute } from "@pulse-js/core";
-
-const fullName = compute("full-name", [firstName, lastName], (first, last) => {
-  return `${first} ${last}`;
-});
-```
-
-### Async Guards & Race Control
-
-Pulse handles asynchronous logic natively. Guards can return Promises, and their status will automatically transition from `pending` to `ok` or `fail`.
-
-Pulse implements internal **runId versioning** to automatically cancel stale async evaluations if the underlying sources change multiple times before a promise resolves, preventing race conditions.
-
-```typescript
-const isServerOnline = guard("check-server", async () => {
-  const response = await fetch("/health");
-  if (!response.ok) throw new Error("Server unreachable");
+  if (!u) return false;
   return true;
 });
 ```
 
 ### Explanable Guards
 
-For complex conditions, you can call `.explain()` to get a structured tree of the current status, failure reason, and the status of all direct dependencies.
+Get a structured tree of the current status, failure reasons, and the status of all direct dependencies.
 
 ```ts
 const explanation = canCheckout.explain();
-console.log(explanation);
-// { status: 'fail', reason: 'auth failed', dependencies: [...] }
+// { status: 'fail', reason: { code: 'AUTH', message: '...' }, dependencies: [...] }
 ```
 
-## Server-Side Rendering (SSR)
-
-Pulse is designed with SSR in mind. It supports isomorphic rendering where async guards can be evaluated on the server, their state serialized, and then hydrated on the client.
-
-### Server Side
-
-```typescript
-import { evaluate } from "@pulse-js/core";
-
-// 1. Evaluate critical guards on the server
-const hydrationState = await evaluate([isUserAuthenticated, appSettings]);
-
-// 2. Serialize this state into your HTML
-const html = `
-  <script>window.__PULSE_STATE__ = ${JSON.stringify(hydrationState)}</script>
-`;
-```
-
-### Client Side (Hydration)
-
-```typescript
-import { hydrate } from "@pulse-js/core";
-
-// 1. Hydrate before rendering
-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).  |
-
 ## Framework Integrations
 
-Pulse provides official adapters for major frameworks to ensure seamless integration.
+Pulse provides official adapters for all major frameworks.
 
-| 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) |
+| Framework    | Package              | Status |
+| :----------- | :------------------- | :----- |
+| **Astro**    | `@pulse-js/astro`    | NEW    |
+| **React**    | `@pulse-js/react`    | Stable |
+| **Vue**      | `@pulse-js/vue`      | Stable |
+| **Svelte**   | `@pulse-js/svelte`   | Stable |
+| **TanStack** | `@pulse-js/tanstack` | NEW    |
 
 ## Developer Tools
 
-Debug your reactive graph with **[Pulse Tools](https://pulse-js.vercel.app/guides/devtools/)**, a powerful framework-agnostic inspector.
-
-### Features
+Debug your reactive graph with **[Pulse Tools](https://pulse-js.vercel.app/guides/devtools/)**, a decoupled Agent-Client inspector.
 
-- **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.
+- **Agent-Client Architecture**: Isolated UI that doesn't restart your app.
+- **Dependency Graph**: Visualize how your guards are connected.
+- **Glassmorphism UI**: A premium, draggable development experience.
 - **Zero Config**: Works out of the box with `@pulse-js/tools`.