@pulse-js/core 0.1.9 → 0.2.1

package/dist/index.cjs

@@ -95,7 +95,7 @@ function guardFail(reason) {
 function guardOk(value) {
   return value;
 }
-function guard(nameOrFn, fn, _internalOffset = 3) {
+function guard(nameOrFn, fn) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
   if (!evaluator) {
@@ -259,11 +259,20 @@ function guard(nameOrFn, fn, _internalOffset = 3) {
     lastDeps.forEach((dep) => {
       const depName = dep._name || "unnamed";
       const isG = "state" in dep;
-      deps.push({
-        name: depName,
-        type: isG ? "guard" : "source",
-        status: isG ? dep.state().status : void 0
-      });
+      if (isG) {
+        const depState = dep.state();
+        deps.push({
+          name: depName,
+          type: "guard",
+          status: depState.status,
+          reason: depState.status === "fail" ? depState.reason : void 0
+        });
+      } else {
+        deps.push({
+          name: depName,
+          type: "source"
+        });
+      }
     });
     return {
       name: name || "guard",
@@ -288,6 +297,13 @@ function guard(nameOrFn, fn, _internalOffset = 3) {
   evaluate2();
   return g;
 }
+guard.map = function(source2, mapper, name) {
+  const guardName = name || `map-${source2._name || "source"}`;
+  return guard(guardName, () => {
+    const value = source2();
+    return mapper(value);
+  });
+};
 
 // src/registry.ts
 var Registry = class {
@@ -295,53 +311,23 @@ var Registry = class {
   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.
+   * Schedules cleanup of units that weren't re-registered (deleted from code).
    */
   scheduleCleanup() {
     if (this.cleanupScheduled) return;
     this.cleanupScheduled = true;
-    this.currentGeneration++;
     setTimeout(() => {
-      this.cleanupOldGenerations();
+      this.cleanupDeadUnits();
       this.cleanupScheduled = false;
     }, 100);
   }
   /**
-   * Removes units from old generations (likely orphaned by HMR).
+   * Removes units that weren't re-registered in the current generation.
+   * Uses mark-and-sweep: units that were re-registered have current generation,
+   * units that weren't are from old generation and should be removed.
    */
-  cleanupOldGenerations() {
+  cleanupDeadUnits() {
     const toDelete = [];
     this.units.forEach((unit, key) => {
       const gen = unit._generation;
@@ -351,53 +337,46 @@ var Registry = class {
     });
     toDelete.forEach((key) => this.units.delete(key));
     if (toDelete.length > 0) {
-      console.log(`[Pulse] Cleaned up ${toDelete.length} stale units after HMR`);
+      console.log(`[Pulse] Cleaned up ${toDelete.length} deleted units after HMR`);
     }
   }
   /**
-   * Registers a new unit (Source or Guard).
-   * Auto-assigns stable names to unnamed units for HMR stability.
+   * Registers a unit (only if it has an explicit name).
    */
-  register(unit, offset = 3) {
+  register(unit) {
     const unitWithMetadata = unit;
-    let name = unitWithMetadata._name;
+    const name = unitWithMetadata._name;
     if (!name) {
-      const isGuard2 = "state" in unit;
-      name = this.generateAutoName(isGuard2 ? "guard" : "source", offset);
-      unitWithMetadata._name = name;
+      return;
     }
-    unitWithMetadata._generation = this.currentGeneration;
-    if (this.units.has(name)) {
+    const existingUnit = this.units.get(name);
+    if (existingUnit) {
+      const existingGen = existingUnit?._generation;
+      if (existingGen === this.currentGeneration) {
+        unitWithMetadata._generation = this.currentGeneration;
+        this.units.set(name, unit);
+        this.listeners.forEach((l) => l(unit));
+        return;
+      }
+      this.currentGeneration++;
       this.scheduleCleanup();
     }
+    unitWithMetadata._generation = this.currentGeneration;
     this.units.set(name, unit);
     this.listeners.forEach((l) => l(unit));
   }
-  /**
-   * Retrieves all registered units.
-   */
   getAll() {
     return Array.from(this.units.values());
   }
-  /**
-   * Subscribes to new unit registrations.
-   * 
-   * @param listener - Callback receiving the newly registered unit.
-   * @returns Unsubscribe function.
-   */
   onRegister(listener) {
     this.listeners.add(listener);
     return () => {
       this.listeners.delete(listener);
     };
   }
-  /**
-   * Clears all registered units.
-   */
   reset() {
     this.units.clear();
     this.currentGeneration = 0;
-    this.autoNameCache.clear();
   }
 };
 var GLOBAL_KEY = "__PULSE_REGISTRY__";
@@ -408,7 +387,7 @@ if (!globalSymbols[GLOBAL_KEY]) {
 var PulseRegistry = globalSymbols[GLOBAL_KEY];
 
 // src/source.ts
-function source(initialValue, options = {}, _internalOffset = 3) {
+function source(initialValue, options = {}) {
   let value = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
   const dependents = /* @__PURE__ */ new Set();
@@ -447,7 +426,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
@@ -470,7 +449,7 @@ function guardAll(nameOrGuards, maybeGuards) {
       throw new Error(message);
     }
     return true;
-  }, 4);
+  });
 }
 function guardAny(nameOrGuards, maybeGuards) {
   const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
@@ -484,7 +463,7 @@ function guardAny(nameOrGuards, maybeGuards) {
       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;
@@ -494,7 +473,7 @@ function guardNot(nameOrTarget, maybeTarget) {
       return !target.ok();
     }
     return !target();
-  }, 4);
+  });
 }
 var guardExtensions = {
   all: guardAll,

package/dist/index.d.cts

@@ -41,6 +41,118 @@ declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
  */
 declare function getCurrentGuard(): GuardNode | null;
 
+/**
+ * Options for configuring a Pulse Source.
+ *
+ * @template T - The type of value stored in the source.
+ */
+interface SourceOptions<T> {
+    /**
+     * A descriptive name for the source.
+     * Required for SSR hydration and highly recommended for debugging in DevTools.
+     */
+    name?: string;
+    /**
+     * Custom equality function to determine if a value has changed.
+     * By default, Pulse uses strict equality (`===`).
+     *
+     * @param a - The current value.
+     * @param b - The new value.
+     * @returns `true` if the values are considered equal, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const list = source([1], {
+     *   equals: (a, b) => a.length === b.length
+     * });
+     * ```
+     */
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * A Pulse Source is a reactive container for a value.
+ * It tracks which Guards read its value and notifies them when it changes.
+ *
+ * @template T The type of the value held by the source.
+ */
+interface Source<T> {
+    /**
+     * Returns the current value of the source.
+     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * console.log(count()); // 0
+     * ```
+     */
+    (): T;
+    /**
+     * Updates the source with a new value.
+     * If the value is different (based on strict equality or `options.equals`),
+     * all dependent Guards and subscribers will be notified.
+     *
+     * @param value The new value to set.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.set(1); // Triggers re-evaluation of dependents
+     * ```
+     *
+     * @error
+     * Common error: Mutating an object property without setting a new object reference.
+     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
+     * Solution: Always provide a new object or implement a custom `equals`.
+     */
+    set(value: T): void;
+    /**
+     * Updates the source value using a transformer function based on the current value.
+     * Useful for increments or toggles.
+     *
+     * @param updater A function that receives the current value and returns the new value.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.update(n => n + 1);
+     * ```
+     */
+    update(updater: (current: T) => T): void;
+    /**
+     * Manually subscribes to changes in the source value.
+     *
+     * @param listener A callback that receives the new value.
+     * @returns An unsubscription function.
+     *
+     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
+     */
+    subscribe(listener: Subscriber<T>): () => void;
+}
+/**
+ * Creates a new Pulse Source.
+ *
+ * Sources are the fundamental building blocks of state in Pulse. They hold a value
+ * and track which Guards depend on them.
+ *
+ * @template T - The type of value to store.
+ * @param initialValue - The initial state.
+ * @param options - Configuration options (name, equality).
+ * @returns A reactive Pulse Source.
+ *
+ * @example
+ * ```ts
+ * const user = source({ name: 'Alice' }, { name: 'user_state' });
+ *
+ * // Read value (auto-tracks if inside a guard)
+ * console.log(user());
+ *
+ * // Update value
+ * user.set({ name: 'Bob' });
+ * ```
+ */
+declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+
 /**
  * Status of a Pulse Guard evaluation.
  * - 'pending': Async evaluation is in progress.
@@ -86,6 +198,7 @@ interface GuardExplanation {
         name: string;
         type: 'source' | 'guard';
         status?: GuardStatus;
+        reason?: string | GuardReason;
     }>;
 }
 /**
@@ -186,7 +299,10 @@ declare function guardFail(reason: string | GuardReason): never;
  * 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>;
+declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+declare namespace guard {
+    var map: <T, U>(source: Source<T>, mapper: (value: T) => U | Promise<U>, name?: string) => Guard<U>;
+}
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -251,118 +367,6 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
 
-/**
- * Options for configuring a Pulse Source.
- *
- * @template T - The type of value stored in the source.
- */
-interface SourceOptions<T> {
-    /**
-     * A descriptive name for the source.
-     * Required for SSR hydration and highly recommended for debugging in DevTools.
-     */
-    name?: string;
-    /**
-     * Custom equality function to determine if a value has changed.
-     * By default, Pulse uses strict equality (`===`).
-     *
-     * @param a - The current value.
-     * @param b - The new value.
-     * @returns `true` if the values are considered equal, `false` otherwise.
-     *
-     * @example
-     * ```ts
-     * const list = source([1], {
-     *   equals: (a, b) => a.length === b.length
-     * });
-     * ```
-     */
-    equals?: (a: T, b: T) => boolean;
-}
-/**
- * A Pulse Source is a reactive container for a value.
- * It tracks which Guards read its value and notifies them when it changes.
- *
- * @template T The type of the value held by the source.
- */
-interface Source<T> {
-    /**
-     * Returns the current value of the source.
-     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * console.log(count()); // 0
-     * ```
-     */
-    (): T;
-    /**
-     * Updates the source with a new value.
-     * If the value is different (based on strict equality or `options.equals`),
-     * all dependent Guards and subscribers will be notified.
-     *
-     * @param value The new value to set.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.set(1); // Triggers re-evaluation of dependents
-     * ```
-     *
-     * @error
-     * Common error: Mutating an object property without setting a new object reference.
-     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
-     * Solution: Always provide a new object or implement a custom `equals`.
-     */
-    set(value: T): void;
-    /**
-     * Updates the source value using a transformer function based on the current value.
-     * Useful for increments or toggles.
-     *
-     * @param updater A function that receives the current value and returns the new value.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.update(n => n + 1);
-     * ```
-     */
-    update(updater: (current: T) => T): void;
-    /**
-     * Manually subscribes to changes in the source value.
-     *
-     * @param listener A callback that receives the new value.
-     * @returns An unsubscription function.
-     *
-     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
-     */
-    subscribe(listener: Subscriber<T>): () => void;
-}
-/**
- * Creates a new Pulse Source.
- *
- * Sources are the fundamental building blocks of state in Pulse. They hold a value
- * and track which Guards depend on them.
- *
- * @template T - The type of value to store.
- * @param initialValue - The initial state.
- * @param options - Configuration options (name, equality).
- * @returns A reactive Pulse Source.
- *
- * @example
- * ```ts
- * const user = source({ name: 'Alice' }, { name: 'user_state' });
- *
- * // Read value (auto-tracks if inside a guard)
- * console.log(user());
- *
- * // Update value
- * user.set({ name: 'Bob' });
- * ```
- */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>, _internalOffset?: number): Source<T>;
-
 /**
  * Serialized state of guards for transfer from server to client.
  */
@@ -416,53 +420,56 @@ type PulseUnit = Source<any> | Guard<any>;
 /**
  * Root Registry for Pulse.
  *
- * It tracks all registered Units (Sources and Guards) globally, providing
- * the data source for DevTools and HMR stability.
+ * Tracks all registered Units (Sources and Guards) globally for DevTools.
+ *
+ * **IMPORTANT**: Only units with explicit names are registered and visible in DevTools.
+ * Unnamed units work perfectly but are not tracked to avoid HMR instability.
+ *
+ * @example
+ * ```ts
+ * // ✅ Visible in DevTools
+ * const count = source(0, { name: 'count' });
+ *
+ * // ❌ Not visible in DevTools (but works fine)
+ * const temp = source(0);
+ * ```
  */
 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.
+     * Schedules cleanup of units that weren't re-registered (deleted from code).
      */
     private scheduleCleanup;
     /**
-     * Removes units from old generations (likely orphaned by HMR).
-     */
-    private cleanupOldGenerations;
-    /**
-     * Registers a new unit (Source or Guard).
-     * Auto-assigns stable names to unnamed units for HMR stability.
+     * Removes units that weren't re-registered in the current generation.
+     * Uses mark-and-sweep: units that were re-registered have current generation,
+     * units that weren't are from old generation and should be removed.
      */
-    register(unit: PulseUnit, offset?: number): void;
+    private cleanupDeadUnits;
     /**
-     * Retrieves all registered units.
+     * Registers a unit (only if it has an explicit name).
      */
+    register(unit: PulseUnit): void;
     getAll(): PulseUnit[];
-    /**
-     * Subscribes to new unit registrations.
-     *
-     * @param listener - Callback receiving the newly registered unit.
-     * @returns Unsubscribe function.
-     */
     onRegister(listener: (unit: PulseUnit) => void): () => void;
-    /**
-     * Clears all registered units.
-     */
     reset(): void;
 }
 declare const PulseRegistry: Registry;
 
+/**
+ * Extracts the result type T from a Guard<T>.
+ *
+ * @example
+ * ```ts
+ * const authGuard = guard('auth', async () => fetchUser());
+ * type AuthUser = InferGuardType<typeof authGuard>; // User
+ * ```
+ */
+type InferGuardType<T> = T extends Guard<infer U> ? U : never;
+
 /**
  * Pulse Guard with integrated Composition Helpers.
  *
@@ -482,4 +489,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-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 };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, type InferGuardType, 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

@@ -41,6 +41,118 @@ declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
  */
 declare function getCurrentGuard(): GuardNode | null;
 
+/**
+ * Options for configuring a Pulse Source.
+ *
+ * @template T - The type of value stored in the source.
+ */
+interface SourceOptions<T> {
+    /**
+     * A descriptive name for the source.
+     * Required for SSR hydration and highly recommended for debugging in DevTools.
+     */
+    name?: string;
+    /**
+     * Custom equality function to determine if a value has changed.
+     * By default, Pulse uses strict equality (`===`).
+     *
+     * @param a - The current value.
+     * @param b - The new value.
+     * @returns `true` if the values are considered equal, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const list = source([1], {
+     *   equals: (a, b) => a.length === b.length
+     * });
+     * ```
+     */
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * A Pulse Source is a reactive container for a value.
+ * It tracks which Guards read its value and notifies them when it changes.
+ *
+ * @template T The type of the value held by the source.
+ */
+interface Source<T> {
+    /**
+     * Returns the current value of the source.
+     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * console.log(count()); // 0
+     * ```
+     */
+    (): T;
+    /**
+     * Updates the source with a new value.
+     * If the value is different (based on strict equality or `options.equals`),
+     * all dependent Guards and subscribers will be notified.
+     *
+     * @param value The new value to set.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.set(1); // Triggers re-evaluation of dependents
+     * ```
+     *
+     * @error
+     * Common error: Mutating an object property without setting a new object reference.
+     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
+     * Solution: Always provide a new object or implement a custom `equals`.
+     */
+    set(value: T): void;
+    /**
+     * Updates the source value using a transformer function based on the current value.
+     * Useful for increments or toggles.
+     *
+     * @param updater A function that receives the current value and returns the new value.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.update(n => n + 1);
+     * ```
+     */
+    update(updater: (current: T) => T): void;
+    /**
+     * Manually subscribes to changes in the source value.
+     *
+     * @param listener A callback that receives the new value.
+     * @returns An unsubscription function.
+     *
+     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
+     */
+    subscribe(listener: Subscriber<T>): () => void;
+}
+/**
+ * Creates a new Pulse Source.
+ *
+ * Sources are the fundamental building blocks of state in Pulse. They hold a value
+ * and track which Guards depend on them.
+ *
+ * @template T - The type of value to store.
+ * @param initialValue - The initial state.
+ * @param options - Configuration options (name, equality).
+ * @returns A reactive Pulse Source.
+ *
+ * @example
+ * ```ts
+ * const user = source({ name: 'Alice' }, { name: 'user_state' });
+ *
+ * // Read value (auto-tracks if inside a guard)
+ * console.log(user());
+ *
+ * // Update value
+ * user.set({ name: 'Bob' });
+ * ```
+ */
+declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+
 /**
  * Status of a Pulse Guard evaluation.
  * - 'pending': Async evaluation is in progress.
@@ -86,6 +198,7 @@ interface GuardExplanation {
         name: string;
         type: 'source' | 'guard';
         status?: GuardStatus;
+        reason?: string | GuardReason;
     }>;
 }
 /**
@@ -186,7 +299,10 @@ declare function guardFail(reason: string | GuardReason): never;
  * 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>;
+declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+declare namespace guard {
+    var map: <T, U>(source: Source<T>, mapper: (value: T) => U | Promise<U>, name?: string) => Guard<U>;
+}
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -251,118 +367,6 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
 
-/**
- * Options for configuring a Pulse Source.
- *
- * @template T - The type of value stored in the source.
- */
-interface SourceOptions<T> {
-    /**
-     * A descriptive name for the source.
-     * Required for SSR hydration and highly recommended for debugging in DevTools.
-     */
-    name?: string;
-    /**
-     * Custom equality function to determine if a value has changed.
-     * By default, Pulse uses strict equality (`===`).
-     *
-     * @param a - The current value.
-     * @param b - The new value.
-     * @returns `true` if the values are considered equal, `false` otherwise.
-     *
-     * @example
-     * ```ts
-     * const list = source([1], {
-     *   equals: (a, b) => a.length === b.length
-     * });
-     * ```
-     */
-    equals?: (a: T, b: T) => boolean;
-}
-/**
- * A Pulse Source is a reactive container for a value.
- * It tracks which Guards read its value and notifies them when it changes.
- *
- * @template T The type of the value held by the source.
- */
-interface Source<T> {
-    /**
-     * Returns the current value of the source.
-     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * console.log(count()); // 0
-     * ```
-     */
-    (): T;
-    /**
-     * Updates the source with a new value.
-     * If the value is different (based on strict equality or `options.equals`),
-     * all dependent Guards and subscribers will be notified.
-     *
-     * @param value The new value to set.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.set(1); // Triggers re-evaluation of dependents
-     * ```
-     *
-     * @error
-     * Common error: Mutating an object property without setting a new object reference.
-     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
-     * Solution: Always provide a new object or implement a custom `equals`.
-     */
-    set(value: T): void;
-    /**
-     * Updates the source value using a transformer function based on the current value.
-     * Useful for increments or toggles.
-     *
-     * @param updater A function that receives the current value and returns the new value.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.update(n => n + 1);
-     * ```
-     */
-    update(updater: (current: T) => T): void;
-    /**
-     * Manually subscribes to changes in the source value.
-     *
-     * @param listener A callback that receives the new value.
-     * @returns An unsubscription function.
-     *
-     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
-     */
-    subscribe(listener: Subscriber<T>): () => void;
-}
-/**
- * Creates a new Pulse Source.
- *
- * Sources are the fundamental building blocks of state in Pulse. They hold a value
- * and track which Guards depend on them.
- *
- * @template T - The type of value to store.
- * @param initialValue - The initial state.
- * @param options - Configuration options (name, equality).
- * @returns A reactive Pulse Source.
- *
- * @example
- * ```ts
- * const user = source({ name: 'Alice' }, { name: 'user_state' });
- *
- * // Read value (auto-tracks if inside a guard)
- * console.log(user());
- *
- * // Update value
- * user.set({ name: 'Bob' });
- * ```
- */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>, _internalOffset?: number): Source<T>;
-
 /**
  * Serialized state of guards for transfer from server to client.
  */
@@ -416,53 +420,56 @@ type PulseUnit = Source<any> | Guard<any>;
 /**
  * Root Registry for Pulse.
  *
- * It tracks all registered Units (Sources and Guards) globally, providing
- * the data source for DevTools and HMR stability.
+ * Tracks all registered Units (Sources and Guards) globally for DevTools.
+ *
+ * **IMPORTANT**: Only units with explicit names are registered and visible in DevTools.
+ * Unnamed units work perfectly but are not tracked to avoid HMR instability.
+ *
+ * @example
+ * ```ts
+ * // ✅ Visible in DevTools
+ * const count = source(0, { name: 'count' });
+ *
+ * // ❌ Not visible in DevTools (but works fine)
+ * const temp = source(0);
+ * ```
  */
 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.
+     * Schedules cleanup of units that weren't re-registered (deleted from code).
      */
     private scheduleCleanup;
     /**
-     * Removes units from old generations (likely orphaned by HMR).
-     */
-    private cleanupOldGenerations;
-    /**
-     * Registers a new unit (Source or Guard).
-     * Auto-assigns stable names to unnamed units for HMR stability.
+     * Removes units that weren't re-registered in the current generation.
+     * Uses mark-and-sweep: units that were re-registered have current generation,
+     * units that weren't are from old generation and should be removed.
      */
-    register(unit: PulseUnit, offset?: number): void;
+    private cleanupDeadUnits;
     /**
-     * Retrieves all registered units.
+     * Registers a unit (only if it has an explicit name).
      */
+    register(unit: PulseUnit): void;
     getAll(): PulseUnit[];
-    /**
-     * Subscribes to new unit registrations.
-     *
-     * @param listener - Callback receiving the newly registered unit.
-     * @returns Unsubscribe function.
-     */
     onRegister(listener: (unit: PulseUnit) => void): () => void;
-    /**
-     * Clears all registered units.
-     */
     reset(): void;
 }
 declare const PulseRegistry: Registry;
 
+/**
+ * Extracts the result type T from a Guard<T>.
+ *
+ * @example
+ * ```ts
+ * const authGuard = guard('auth', async () => fetchUser());
+ * type AuthUser = InferGuardType<typeof authGuard>; // User
+ * ```
+ */
+type InferGuardType<T> = T extends Guard<infer U> ? U : never;
+
 /**
  * Pulse Guard with integrated Composition Helpers.
  *
@@ -482,4 +489,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-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 };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, type InferGuardType, 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

@@ -59,7 +59,7 @@ function guardFail(reason) {
 function guardOk(value) {
   return value;
 }
-function guard(nameOrFn, fn, _internalOffset = 3) {
+function guard(nameOrFn, fn) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
   if (!evaluator) {
@@ -223,11 +223,20 @@ function guard(nameOrFn, fn, _internalOffset = 3) {
     lastDeps.forEach((dep) => {
       const depName = dep._name || "unnamed";
       const isG = "state" in dep;
-      deps.push({
-        name: depName,
-        type: isG ? "guard" : "source",
-        status: isG ? dep.state().status : void 0
-      });
+      if (isG) {
+        const depState = dep.state();
+        deps.push({
+          name: depName,
+          type: "guard",
+          status: depState.status,
+          reason: depState.status === "fail" ? depState.reason : void 0
+        });
+      } else {
+        deps.push({
+          name: depName,
+          type: "source"
+        });
+      }
     });
     return {
       name: name || "guard",
@@ -252,6 +261,13 @@ function guard(nameOrFn, fn, _internalOffset = 3) {
   evaluate2();
   return g;
 }
+guard.map = function(source2, mapper, name) {
+  const guardName = name || `map-${source2._name || "source"}`;
+  return guard(guardName, () => {
+    const value = source2();
+    return mapper(value);
+  });
+};
 
 // src/registry.ts
 var Registry = class {
@@ -259,53 +275,23 @@ var Registry = class {
   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.
+   * Schedules cleanup of units that weren't re-registered (deleted from code).
    */
   scheduleCleanup() {
     if (this.cleanupScheduled) return;
     this.cleanupScheduled = true;
-    this.currentGeneration++;
     setTimeout(() => {
-      this.cleanupOldGenerations();
+      this.cleanupDeadUnits();
       this.cleanupScheduled = false;
     }, 100);
   }
   /**
-   * Removes units from old generations (likely orphaned by HMR).
+   * Removes units that weren't re-registered in the current generation.
+   * Uses mark-and-sweep: units that were re-registered have current generation,
+   * units that weren't are from old generation and should be removed.
    */
-  cleanupOldGenerations() {
+  cleanupDeadUnits() {
     const toDelete = [];
     this.units.forEach((unit, key) => {
       const gen = unit._generation;
@@ -315,53 +301,46 @@ var Registry = class {
     });
     toDelete.forEach((key) => this.units.delete(key));
     if (toDelete.length > 0) {
-      console.log(`[Pulse] Cleaned up ${toDelete.length} stale units after HMR`);
+      console.log(`[Pulse] Cleaned up ${toDelete.length} deleted units after HMR`);
     }
   }
   /**
-   * Registers a new unit (Source or Guard).
-   * Auto-assigns stable names to unnamed units for HMR stability.
+   * Registers a unit (only if it has an explicit name).
    */
-  register(unit, offset = 3) {
+  register(unit) {
     const unitWithMetadata = unit;
-    let name = unitWithMetadata._name;
+    const name = unitWithMetadata._name;
     if (!name) {
-      const isGuard2 = "state" in unit;
-      name = this.generateAutoName(isGuard2 ? "guard" : "source", offset);
-      unitWithMetadata._name = name;
+      return;
     }
-    unitWithMetadata._generation = this.currentGeneration;
-    if (this.units.has(name)) {
+    const existingUnit = this.units.get(name);
+    if (existingUnit) {
+      const existingGen = existingUnit?._generation;
+      if (existingGen === this.currentGeneration) {
+        unitWithMetadata._generation = this.currentGeneration;
+        this.units.set(name, unit);
+        this.listeners.forEach((l) => l(unit));
+        return;
+      }
+      this.currentGeneration++;
       this.scheduleCleanup();
     }
+    unitWithMetadata._generation = this.currentGeneration;
     this.units.set(name, unit);
     this.listeners.forEach((l) => l(unit));
   }
-  /**
-   * Retrieves all registered units.
-   */
   getAll() {
     return Array.from(this.units.values());
   }
-  /**
-   * Subscribes to new unit registrations.
-   * 
-   * @param listener - Callback receiving the newly registered unit.
-   * @returns Unsubscribe function.
-   */
   onRegister(listener) {
     this.listeners.add(listener);
     return () => {
       this.listeners.delete(listener);
     };
   }
-  /**
-   * Clears all registered units.
-   */
   reset() {
     this.units.clear();
     this.currentGeneration = 0;
-    this.autoNameCache.clear();
   }
 };
 var GLOBAL_KEY = "__PULSE_REGISTRY__";
@@ -372,7 +351,7 @@ if (!globalSymbols[GLOBAL_KEY]) {
 var PulseRegistry = globalSymbols[GLOBAL_KEY];
 
 // src/source.ts
-function source(initialValue, options = {}, _internalOffset = 3) {
+function source(initialValue, options = {}) {
   let value = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
   const dependents = /* @__PURE__ */ new Set();
@@ -411,7 +390,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
@@ -434,7 +413,7 @@ function guardAll(nameOrGuards, maybeGuards) {
       throw new Error(message);
     }
     return true;
-  }, 4);
+  });
 }
 function guardAny(nameOrGuards, maybeGuards) {
   const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
@@ -448,7 +427,7 @@ function guardAny(nameOrGuards, maybeGuards) {
       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;
@@ -458,7 +437,7 @@ function guardNot(nameOrTarget, maybeTarget) {
       return !target.ok();
     }
     return !target();
-  }, 4);
+  });
 }
 var guardExtensions = {
   all: guardAll,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/core",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "module": "dist/index.js",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",