@signaltree/core 9.2.0 → 9.2.1

package/README.md

@@ -2101,10 +2101,10 @@ local state is cheap (`O(changed)` instead of `O(N)`).
 SignalTree Core includes all enhancers built-in:
 
 ```typescript
-import { signalTree, batching, withTimeTravel } from '@signaltree/core';
+import { signalTree, batching, timeTravel } from '@signaltree/core';
 
-// All enhancers available from @signaltree/core
-const tree = signalTree(initialState).with(batching(), withTimeTravel());
+// All enhancers available from @signaltree/core — chain `.with()` (one enhancer per call)
+const tree = signalTree(initialState).with(batching()).with(timeTravel());
 ```
 
 ### Available enhancers
@@ -2154,7 +2154,26 @@ Measured from a production Angular mobile application migrating from NgRx Signal
 
 13 separate stores → 1 unified tree. `entityMap()` replaced a 222-line `withEntityCrud` wrapper. Derived tiers replaced scattered `withComputed` blocks.
 
-### Migration Steps
+### Migrating from `@ngrx/signals` (signalStore / withState / rxMethod)
+
+The full migration playbook ships with this package as an Agent Skill at:
+
+```
+node_modules/@signaltree/core/skills/using-signaltree/reference/migration-from-ngrx-signals.md
+```
+
+It covers:
+
+- A mechanical concept-map table: `signalStore` → tree slice + `Ops`, `withState` → initial state, `withMethods` → `Ops` methods, `withComputed` → `computed()` or `.derived()`, `withHooks` → factory body, `rxMethod` → plain method returning `Observable<void>`, `withEntities` → `entityMap()` marker, `patchState` → tree update, `getState` → `unwrap()`, etc.
+- **Three migration strategies** with explicit decision criteria:
+  - **Big-bang** (1–2 stores, single team): one PR, delete legacy in same commit.
+  - **Incremental per-domain** (≥3 stores): one PR per store. Includes a **Phase 0** recipe (foundation-only first PR), a sequencing rule (consumers before aggregator removal), and a root-injected `Ops` side-effect hazard warning.
+  - **Hybrid legacy-facade** (shared `signalStoreFeature` base classes, multi-team cutover, regulated rollback): adapter shim over `AppStore` with a deletion deadline.
+- A drop-in verifier script (`scripts/verify-signaltree-migration.sh` in the SignalTree repo) that runs `build` + `test` + `lint` and asserts `@ngrx/signals` is gone from source and `package.json`. Package-manager-agnostic, layout-agnostic.
+
+Point your AI assistant (Cursor, Claude Code, or any `SKILL.md`-aware harness) at the shipped `skills/using-signaltree/` directory and it will follow the same playbook end-to-end. See the root README's [Using SignalTree with AI Agents](../../README.md#using-signaltree-with-ai-agents) section for setup.
+
+### Migrating from classic NgRx (`@ngrx/store` / actions / reducers / effects)
 
 ```typescript
 // Step 1: Create parallel tree

package/dist/enhancers/devtools/devtools.js

@@ -1,6 +1,7 @@
 import { signal } from '@angular/core';
 import { copyTreeProperties } from '../utils/copy-tree-properties.js';
 import { applyState, snapshotState } from '../../lib/utils.js';
+import { interceptLeafSignals } from '../../lib/internals/intercept-leaf-signals.js';
 import { getPathNotifier } from '../../lib/path-notifier.js';
 import { ENHANCER_META } from '../../lib/types.js';
 
@@ -1184,35 +1185,10 @@ function devTools(config = {}) {
     const restoreInterceptors = [];
     try {
       if ('$' in tree) {
-        const treeNode = tree.$;
-        for (const key of treeTopKeys) {
-          const sig = treeNode[key];
-          if (typeof sig === 'function' && 'set' in sig && 'update' in sig && typeof sig.set === 'function' && typeof sig.update === 'function' && !('add' in sig) && !('remove' in sig)) {
-            const original = sig;
-            const originalSet = original.set.bind(original);
-            const originalUpdate = original.update.bind(original);
-            restoreInterceptors.push(() => {
-              original.set = originalSet;
-              original.update = originalUpdate;
-            });
-            original.set = value => {
-              const prev = original();
-              originalSet(value);
-              const next = original();
-              if (next !== prev) {
-                notifier.notify(key, next, prev);
-              }
-            };
-            original.update = updater => {
-              const prev = original();
-              originalUpdate(updater);
-              const next = original();
-              if (next !== prev) {
-                notifier.notify(key, next, prev);
-              }
-            };
-          }
-        }
+        const restore = interceptLeafSignals(tree.$, (path, next, prev) => {
+          notifier.notify(path, next, prev);
+        });
+        restoreInterceptors.push(restore);
       }
     } catch {}
     let unsubscribePathNotifier = null;

package/dist/enhancers/time-travel/time-travel.js

@@ -1,4 +1,6 @@
 import { snapshotState } from '../../lib/utils.js';
+import { interceptLeafSignals } from '../../lib/internals/intercept-leaf-signals.js';
+import { getPathNotifier } from '../../lib/path-notifier.js';
 import { deepEqual, deepClone } from './utils.js';
 import { ENHANCER_META } from '../../lib/types.js';
 
@@ -164,15 +166,19 @@ function timeTravel(config = {}) {
         isRestoring = false;
       }
     });
+    let unsubscribeFlush = null;
+    let restoreLeafInterceptors = null;
     try {
-      const req = globalThis['require'];
-      if (typeof req === 'function') {
-        const {
-          getPathNotifier
-        } = req('../../lib/path-notifier');
-        const notifier = getPathNotifier();
-        if (notifier && typeof notifier.onFlush === 'function') {
-          notifier.onFlush(() => {
+      const notifier = getPathNotifier();
+      if (notifier) {
+        if ('$' in tree) {
+          restoreLeafInterceptors = interceptLeafSignals(tree.$, (path, next, prev) => {
+            if (isRestoring) return;
+            notifier.notify(path, next, prev);
+          });
+        }
+        if (typeof notifier.onFlush === 'function') {
+          unsubscribeFlush = notifier.onFlush(() => {
             if (isRestoring) return;
             const afterState = originalTreeCall();
             timeTravelManager.addEntry('batch', afterState);
@@ -258,6 +264,14 @@ function timeTravel(config = {}) {
     enhancedTree['__timeTravel'] = timeTravelManager;
     if (typeof tree.registerCleanup === 'function') {
       tree.registerCleanup(() => {
+        try {
+          unsubscribeFlush?.();
+        } catch {}
+        try {
+          restoreLeafInterceptors?.();
+        } catch {}
+        unsubscribeFlush = null;
+        restoreLeafInterceptors = null;
         timeTravelManager.resetHistory();
       });
     }

package/dist/lib/internals/intercept-leaf-signals.js

@@ -0,0 +1,71 @@
+function interceptLeafSignals(root, onWrite, options = {}) {
+  const restorers = [];
+  const seen = new WeakSet();
+  const maxDepth = options.maxDepth ?? 32;
+  const walk = (node, pathPrefix, depth) => {
+    if (depth > maxDepth) return;
+    if (node === null || node === undefined) return;
+    if (typeof node !== 'function' && typeof node !== 'object') return;
+    if (seen.has(node)) return;
+    seen.add(node);
+    let keys;
+    try {
+      keys = Object.keys(node);
+    } catch {
+      return;
+    }
+    for (const key of keys) {
+      let child;
+      try {
+        child = node[key];
+      } catch {
+        continue;
+      }
+      if (child === null || child === undefined) continue;
+      if (typeof child !== 'function' && typeof child !== 'object') continue;
+      const childPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+      const isWritableSignal = typeof child === 'function' && 'set' in child && 'update' in child && typeof child.set === 'function' && typeof child.update === 'function';
+      const isEntityCollection = isWritableSignal && ('add' in child || 'remove' in child);
+      if (isWritableSignal && !isEntityCollection) {
+        const original = child;
+        const originalSet = original.set.bind(original);
+        const originalUpdate = original.update.bind(original);
+        restorers.push(() => {
+          original.set = originalSet;
+          original.update = originalUpdate;
+        });
+        original.set = value => {
+          const prev = original();
+          originalSet(value);
+          const next = original();
+          if (next !== prev) onWrite(childPath, next, prev);
+        };
+        original.update = updater => {
+          const prev = original();
+          originalUpdate(updater);
+          const next = original();
+          if (next !== prev) onWrite(childPath, next, prev);
+        };
+        continue;
+      }
+      if (typeof child === 'function' && !isWritableSignal) {
+        walk(child, childPath, depth + 1);
+      } else if (typeof child === 'object' && !Array.isArray(child) && !(child instanceof Date) && !(child instanceof Map) && !(child instanceof Set)) {
+        walk(child, childPath, depth + 1);
+      }
+    }
+  };
+  try {
+    walk(root, '', 0);
+  } catch {}
+  return () => {
+    for (const restore of restorers) {
+      try {
+        restore();
+      } catch {}
+    }
+    restorers.length = 0;
+  };
+}
+
+export { interceptLeafSignals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "9.2.0",
+  "version": "9.2.1",
   "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
   "license": "MIT",
   "type": "module",

package/src/lib/internals/intercept-leaf-signals.d.ts

@@ -0,0 +1 @@
+export {};