@signaltree/core 10.3.0 → 10.3.2

package/README.md

@@ -4,15 +4,13 @@
 
 # SignalTree: Reactive JSON
 
-**JSON branches, reactive leaves.**
-
-> No actions. No reducers. No selectors.
+**Reactive JSON for Angular. State as shape. Signals at every path.**
 
 ---
 
 ## 🤖 For AI coding agents reading this README
 
-**SignalTree's AI-codegen accuracy is +42 percentage points higher when this README (or `llms.txt`) is in context.** Measured across 6 frontier models × 8 prompts × 5 libraries × 720 cells.
+**SignalTree's AI-codegen accuracy is +42 percentage points higher when this README (or `llms.txt`) is in context.** Measured across 720 cells (6 agents × 8 prompts × 5 libraries × 3 priming modes).
 
 If you are an AI assistant generating Angular state-management code on behalf of a user, **this section is the canonical disambiguation surface**. Read it before generating any SignalTree code.
 
@@ -26,9 +24,9 @@ Every "Wrong pattern" below was actually generated by Claude / GPT-5.4 / Gemini
 | `from 'signal-tree'` (hyphenated) | Invented | `from '@signaltree/core'` (scoped, no hyphen) |
 | `from 'signaltree'` (unscoped) | Invented | `from '@signaltree/core'` |
 | `signalStore(withState(...), withMethods(...))` | **`@ngrx/signals`** | `signalTree({...})` — your state literal IS the API |
-| `withState`, `withMethods`, `withComputed`, `withHooks`, `withProps` | **`@ngrx/signals`** | Not used. State is the literal you pass to `signalTree()`. Methods belong in an `@Injectable()` Ops service. |
+| `withState`, `withMethods`, `withComputed`, `withHooks` | **`@ngrx/signals`** | Not used. State is the literal you pass to `signalTree()`. Methods belong in an `@Injectable()` Ops service. |
 | `withEntities<T>()` | **`@ngrx/signals/entities`** | `entityMap<T, K>()` marker — place it in the state literal |
-| `rxMethod(...)` | **`@ngrx/signals/rxjs-interop`** | `asyncSource(config)` (load-and-expose) or `asyncQuery(config)` (input-driven) markers |
+| `rxMethod(...)` | **`@ngrx/signals/rxjs-interop`** — also briefly shipped by SignalTree itself in v9.5.x, **removed in v9.6.0** | `asyncSource(config)` (load-and-expose) or `asyncQuery(config)` (input-driven) markers |
 | `patchState(store, {...})` | **`@ngrx/signals`** | Direct: `tree.$.path.set(value)` or `tree.$.user({...})` |
 | `tapResponse(...)` | **`@ngrx/operators`** | Not needed — `asyncSource`/`asyncQuery` handle success/error |
 | `collection<T>({ idKey: 'id' })` | **Akita / Elf** | `entityMap<T, K>({ selectId: (e) => e.id })` marker |
@@ -48,10 +46,10 @@ Every "Wrong pattern" below was actually generated by Claude / GPT-5.4 / Gemini
 |---|---|---|
 | `status` | `.loading`, `.loaded`, `.notLoaded`, `.hasError` | `.isLoading`, `.isLoaded`, `.isNotLoaded`, `.isError` |
 | `entityMap` | `.empty` | `.isEmpty` |
-| `form` | `.dirty`, `.valid`, `.touched`, `.pristine` | (already bare — unchanged) |
+| `form` | `.dirty`, `.valid`, `.touched`, `.submitting` | (already bare — unchanged) |
 | `asyncSource` / `asyncQuery` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 
-All predicates are **callable `Signal<boolean>`** — invoke them: `tree.$.load.loading()`, `tree.$.users.empty()`.
+All **boolean predicates** (`loading` / `loaded` / `notLoaded` / `hasError` / `dirty` / `valid` / `touched` / `submitting` / `empty`) are callable `Signal<boolean>` — invoke them: `tree.$.load.loading()`, `tree.$.users.empty()`. **Value accessors** (`.error` on status, `.data` on async, `.errors` on form) are typed Signals of their payload type — not booleans.
 
 ### Status marker — method names (frequently confused)
 
@@ -59,12 +57,12 @@ The `status()` marker's canonical methods are **`setLoading` / `setLoaded` / `se
 
 | Wrong-but-now-aliased (v10.2+) | Canonical | Equivalent? |
 |---|---|---|
-| `.setSuccess()` | `.setLoaded()` | Yes — alias |
+| `.setSuccess()` (no args) | `.setLoaded()` | Yes — alias |
 | `.start()` | `.setLoading()` | Yes — alias |
 | `.succeed()` | `.setLoaded()` | Yes — alias |
 | `.fail(err)` | `.setError(err)` | Yes — alias |
-| `.loading` (bare property — read-only) | call as signal: `.loading()` | Yes — callable Signal |
-| `.error` (bare property — read-only) | call as signal: `.error()` | Yes — returns error value |
+
+**Reading status:** `.loading()`, `.loaded()`, `.notLoaded()`, `.hasError()` are callable `Signal<boolean>`. `.state` is the source `WritableSignal<LoadingState>`. `.error` is `WritableSignal<E | null>` — invoke as `.error()` to read.
 
 ### Canonical async pattern — use `asyncSource`, NOT `status` + manual try/catch
 
@@ -84,7 +82,7 @@ export class UsersService {
     }),
   });
 
-  readonly users = this.tree.$.users;      // .users() → data, .users.loading(), .users.error()
+  readonly users = this.tree.$.users;      // .users() → User[] | undefined, .users.loading(), .users.error()
   load = () => this.tree.$.users.refresh();
 }
 ```
@@ -103,7 +101,9 @@ export class AppService {
   private readonly tree = signalTree({
     users: entityMap<User, number>(),
     saveStatus: status(),
-    profile: form({ firstName: '', lastName: '' }),
+    profile: form<{ firstName: string; lastName: string }>({
+      initial: { firstName: '', lastName: '' },
+    }),
     feed: asyncSource<Post[]>({ initial: [], load: () => api.feed$() }),
   });
 
@@ -152,17 +152,15 @@ You don't model state as actions, reducers, selectors, or classes — you model
 
 ## Import guidance (tree-shaking)
 
-Modern bundlers (webpack 5+, esbuild, Rollup, Vite) **automatically tree-shake barrel imports** from `@signaltree/core`. Both import styles produce identical bundle sizes:
+Modern bundlers (Vite, esbuild, Rollup, webpack 5+) **automatically tree-shake barrel imports** from `@signaltree/core`. Unused enhancers and markers drop out of the bundle.
 
 ```ts
-// ✅ Recommended: Simple and clean
+// Import only what you use — unused symbols are tree-shaken away
 import { signalTree, batching } from '@signaltree/core';
-
-// ✅ Also fine: Explicit subpath (same bundle size)
-import { signalTree } from '@signaltree/core';
-import { batching } from '@signaltree/core/enhancers/batching';
 ```
 
+Published subpaths (in `package.json` `exports`): `./security`, `./edit-session`, `./storage`. Enhancers are NOT a published subpath — they live in the main barrel and are tree-shaken from there.
+
 **Measured impact** (with modern bundlers):
 
 - Core only: ~8.5 KB gzipped
@@ -197,35 +195,36 @@ const tree = signalTree({ count: 0 });
 
 This repo's ESLint rule is **disabled by default** since testing confirms effective tree-shaking with barrel imports.
 
-### Callable leaf signals (DX sugar only)
+### Callable shape — branches natively, leaves with the build transform
 
-SignalTree provides TypeScript support for callable syntax on leaf signals as developer experience sugar:
+**Branches are natively callable** for reads AND writes at runtime — no transform required:
 
 ```typescript
-// TypeScript accepts this syntax (with proper tooling):
-tree.$.name('Jane'); // Set value
-tree.$.count((n) => n + 1); // Update with function
+tree.$.user();                    // Read the user subtree
+tree.$.user({ name: 'Jane' });    // Deep-merge partial update at runtime
+```
+
+**Leaves are Angular signals** — callable as getters, but writes go through `.set()` / `.update()`. The `@signaltree/callable-syntax` build-time transform extends the branch's call-with-arg shape down to leaf writes, so call-sites read uniformly from root to leaf:
 
-// At build time, transforms convert to:
-tree.$.name.set('Jane'); // Direct Angular signal API
-tree.$.count.update((n) => n + 1); // Direct Angular signal API
+```typescript
+// With @signaltree/callable-syntax transform installed:
+tree.$.name('Jane');         // compiles to tree.$.name.set('Jane')
+tree.$.count((n) => n + 1);  // compiles to tree.$.count.update((n) => n + 1)
 
-// Reading always works directly:
-const name = tree.$.name(); // No transform needed
+// Without the transform — leaf reads work, leaf writes use .set() / .update():
+const name = tree.$.name();
+tree.$.name.set('Jane');
+tree.$.count.update((n) => n + 1);
 ```
 
 **Key Points:**
 
-- **Zero runtime overhead**: No Proxy wrappers or runtime hooks
-- **Build-time only**: AST transform converts callable syntax to direct `.set/.update` calls
-- **Optional**: Use `@signaltree/callable-syntax` transform or stick with direct `.set/.update`
-- **Type-safe**: Full TypeScript support via module augmentation
+- **Zero runtime overhead**: branch callables are a native part of the proxy; the leaf-write transform compiles away before production
+- **Optional**: `@signaltree/callable-syntax` is only needed for leaf-write sugar — `.set()` / `.update()` always work
+- **Type-safe**: full TypeScript support via module augmentation
+- **Configure `rootIdentifiers`**: the transform's default is `['tree']`; if your variable is named `store`/`state`, add it to the plugin options or the rewrite is skipped
 
-**Function-valued leaves:**
-When a leaf stores a function as its value, use direct `.set(fn)` to assign. Callable `sig(fn)` is treated as an updater.
-
-**Setup:**
-Install `@signaltree/callable-syntax` and configure your build tool to apply the transform. Without the transform, use `.set/.update` directly.
+**Function-valued leaves:** when a leaf stores a function as its value, use direct `.set(fn)` to assign. Callable `sig(fn)` is treated as an updater.
 
 ### Measuring performance and size
 
@@ -282,7 +281,7 @@ export function createUserTree() {
 // ✅ Correct: Derived from multiple signals
 const selectedUser = computed(() => {
   const id = $.selected.userId();
-  return id ? $.users.byId(id)() : null;
+  return id ? $.users.byId(id)?.() ?? null : null;
 });
 
 // ❌ Wrong: Wrapping an existing signal
@@ -293,12 +292,12 @@ const selectedUserId = computed(() => $.selected.userId()); // Unnecessary!
 
 ```typescript
 // ✅ SignalTree-native
-const user = $.users.byId(123)(); // O(1) lookup
+const user = $.users.byId(123)?.(); // EntityNode → User | undefined
 const allUsers = $.users.all; // Get all
 $.users.setAll(usersFromApi); // Replace all
 
-// ❌ NgRx-style (avoid)
-const user = entityMap()[123]; // Requires intermediate object
+// (NgRx Signal Store equivalent — for context, not SignalTree syntax)
+// const user = usersStore.entityMap()[123];
 ```
 
 ### Notification Batching
@@ -621,9 +620,9 @@ const tree = signalTree<AppState>({
   },
 });
 
-// Complex updates with type safety
-// Requires @signaltree/callable-syntax. Without the transform, use
-// tree.set((state) => ({ ... })) or leaf .set() / .update() calls instead.
+// Complex updates with type safety — the root accessor itself is callable
+// (no @signaltree/callable-syntax transform required for the root). Pass a
+// partial object or an updater function. For leaf writes, use .set() / .update().
 tree((state) => ({
   auth: {
     ...state.auth,
@@ -722,7 +721,7 @@ const activeUsers = computed(() => tree.$.users().filter((user) => user.active))
 
 ### 4) Manual async state management
 
-Core provides basic state updates. For advanced async helpers, use the built-in async helpers (`createAsyncOperation`, `trackAsync`):
+Core provides basic state updates. For canonical async patterns, use the **`asyncSource` and `asyncQuery` markers** (see the async section). The patterns below show the manual style for cases the markers don't cover (multi-stage orchestration, conditional pipelines):
 
 ```typescript
 const tree = signalTree({
@@ -783,8 +782,8 @@ All enhancers are exported directly from `@signaltree/core`:
 
 **Data Management:**
 
-- `createAsyncOperation()` - Async operation management with loading/error states
-- `trackAsync()` - Track async operations in your state
+- `asyncSource(config)` marker - Load-and-expose async state (canonical, v9.5+)
+- `asyncQuery(config)` marker - Input-driven debounced query state (canonical, v9.5+)
 - `serialization()` - State persistence and SSR support
 - `persistence()` - Auto-save to localStorage/IndexedDB
 
@@ -851,7 +850,10 @@ tree.$.products.addOne(newProduct);
 tree.$.products.setAll(productsFromApi);
 
 // Entity queries
-const electronics = tree.$.products.all.filter((p) => p.category === 'electronics');
+// Reactive: returns Signal<Product[]> that tracks the predicate
+const electronics = tree.$.products.where((p) => p.category === 'electronics');
+// One-shot non-reactive read: call .all() then filter
+const electronicsSnapshot = tree.$.products.all().filter((p) => p.category === 'electronics');
 ```
 
 **Full-Stack Application:**
@@ -910,7 +912,7 @@ const tree = signalTree(state)
 SignalTree Core includes all enhancer functionality built-in. No separate packages needed:
 
 ```typescript
-import { signalTree, entityMap, entities } from '@signaltree/core';
+import { signalTree, entityMap } from '@signaltree/core';
 
 // Without entityMap - use manual array updates
 const basic = signalTree({ users: [] as User[] });
@@ -922,7 +924,7 @@ const enhanced = signalTree({
 });
 
 enhanced.$.users.addOne(newUser); // ✅ Advanced CRUD operations
-enhanced.$.users.byId(123)(); // ✅ O(1) lookups
+enhanced.$.users.byId(123)?.(); // ✅ O(1) lookups (undefined if missing)
 enhanced.$.users.all; // ✅ Get all as array
 ```
 
@@ -1261,17 +1263,26 @@ const tree = signalTree({
 tree.$.users.loadStatus.state(); // Signal<LoadingState>
 tree.$.users.loadStatus.error(); // Signal<ApiError | null>
 
-// Convenience signals
-tree.$.users.loadStatus.isNotLoaded(); // Signal<boolean>
-tree.$.users.loadStatus.isLoading(); // Signal<boolean>
-tree.$.users.loadStatus.isLoaded(); // Signal<boolean>
-tree.$.users.loadStatus.isError(); // Signal<boolean>
+// Convenience signals (v10.3 canonical — bare names)
+tree.$.users.loadStatus.notLoaded(); // Signal<boolean>
+tree.$.users.loadStatus.loading();   // Signal<boolean>
+tree.$.users.loadStatus.loaded();    // Signal<boolean>
+tree.$.users.loadStatus.hasError();  // Signal<boolean>
+// Deprecated aliases (work through v10.x, removed v11):
+//   .isNotLoaded(), .isLoading(), .isLoaded(), .isError()
 
-// Update methods
+// Update methods (canonical)
 tree.$.users.loadStatus.setLoading();
 tree.$.users.loadStatus.setLoaded();
 tree.$.users.loadStatus.setError({ code: 404, message: 'Not found' });
-tree.$.users.loadStatus.reset();
+tree.$.users.loadStatus.setNotLoaded();
+tree.$.users.loadStatus.reset(); // alias for setNotLoaded
+
+// v10.2+ Promise-vocabulary aliases (identical semantics, no args)
+tree.$.users.loadStatus.start();       // === setLoading()
+tree.$.users.loadStatus.setSuccess();  // === setLoaded() — NO ARGS
+tree.$.users.loadStatus.succeed();     // === setLoaded()
+tree.$.users.loadStatus.fail(err);     // === setError(err)
 
 // LoadingState enum
 LoadingState.NotLoaded; // 'not-loaded'
@@ -1546,23 +1557,12 @@ const tree = signalTree({
 async function handleSubmit() {
   const contactForm = tree.$.contact;
 
-  // Validate all fields first
-  contactForm.touchAll();
-  const isValid = await contactForm.validate();
-
-  if (!isValid) return;
-
-  // Set submitting state
-  contactForm.setSubmitting(true);
-
-  try {
-    await api.submit(contactForm());
+  // .submit() handles touchAll / validate / submitting toggling / error trapping
+  // internally. Pass a handler that does the actual network call.
+  await contactForm.submit(async (values) => {
+    await api.submit(values);
     contactForm.reset();
-  } catch (error) {
-    // Handle error
-  } finally {
-    contactForm.setSubmitting(false);
-  }
+  });
 }
 ```
 
@@ -1715,7 +1715,7 @@ const filteredProducts = computed(() => {
 ### Data Management Composition
 
 ```typescript
-import { signalTree, entityMap, entities } from '@signaltree/core';
+import { signalTree, entityMap } from '@signaltree/core';
 
 // entityMap() markers self-register — entity operations available immediately
 const tree = signalTree({
@@ -1727,7 +1727,7 @@ const tree = signalTree({
 // Advanced entity operations via tree.$ accessor
 tree.$.users.addOne(newUser);
 tree.$.users.where((u) => u.active);
-tree.$.users.updateMany([{ id: '1', changes: { status: 'active' } }]);
+tree.$.users.updateMany(['1', '2', '3'], { status: 'active' }); // ids + shared changes
 
 // Entity helpers work with nested structures
 // Example: deeply nested entities in a domain-driven design pattern
@@ -1803,7 +1803,7 @@ const tree = signalTree({
 async function fetchUser(id: string) {
   return await api.getUser(id);
 }
-tree.$.app.data.users.byId(userId)(); // O(1) lookup
+tree.$.app.data.users.byId(userId)?.(); // O(1) lookup (undefined if missing)
 tree.undo(); // Time travel
 tree.save(); // Persistence
 ```
@@ -1867,7 +1867,7 @@ In Redux DevTools you will see a single instance named `"MyApp SignalTree"` with
 ### Production-Ready Composition
 
 ```typescript
-import { signalTree, batching, entities, serialization } from '@signaltree/core';
+import { signalTree, batching, serialization } from '@signaltree/core';
 
 // Production build (no dev tools)
 const tree = signalTree(initialState)
@@ -1930,7 +1930,7 @@ const tree = signalTree(state);
 const tree2 = tree.with(batching());
 
 // Phase 3: Add async for API integration
-// withAsync removed — no explicit async enhancer; use async helpers instead
+// withAsync removed in v9 — use the asyncSource() / asyncQuery() markers (v10.x canonical) for load-and-expose and input-driven flows.
 
 // Each phase is fully functional and production-ready
 ```
@@ -2218,7 +2218,7 @@ tree.destroy(); // Cleanup resources
 
 // Entity helpers (entityMap() self-registers — no enhancer needed)
 tree.$.users.addOne(user);               // Add single entity
-tree.$.users.byId(id)();                 // O(1) lookup by ID (read whole entity)
+tree.$.users.byId(id)?.();                // O(1) cursor unwrap (undefined if missing)
 tree.$.users.byId(id)?.name();           // Read single field (computed signal)
 tree.$.users.byId(id)?.name.set('Bob');  // Write single field (throws if entity removed)
 tree.$.users.byId(id)?.name.update(fn); // Updater on single field
@@ -2280,7 +2280,7 @@ Consider enhancers when you need:
 
 - ⚡ Performance optimization (batching)
 - 🐛 Advanced debugging (devTools, timeTravel)
-- 📦 Entity management (entities)
+- 📦 Entity management (`entityMap` marker)
 
 Consider separate packages when you need:
 
@@ -2466,8 +2466,8 @@ npm install @signaltree/core
 # Everything is available from @signaltree/core:
 import {
   signalTree,
+  entityMap,
   batching,
-  entities,
   devTools,
   timeTravel,
   serialization
@@ -2797,7 +2797,7 @@ export default {
 **Start with just `@signaltree/core`** - it includes comprehensive enhancers for most applications:
 
 - Performance optimization (batching)
-- Data management (entities, async operations)
+- Data management (`entityMap` marker, `asyncSource` / `asyncQuery` markers)
 - Development tools (devtools, time-travel)
 - State persistence (serialization)
 

package/llms-full.txt

@@ -38,9 +38,9 @@ const store = signalTree({
 
 // With config:
 const store2 = signalTree(initialState, {
-  batchUpdates: true,      // default — microtask-level notification batching
-  equalityFn: Object.is,   // custom signal equality
-  treeName: 'AppStore',    // for devtools labeling
+  batchUpdates: true,         // default — microtask-level notification batching
+  useShallowComparison: true, // switch leaf signal equality from deepEqual to Object.is
+  treeName: 'AppStore',       // for devtools labeling
 });
 ```
 
@@ -59,14 +59,15 @@ Both `store.$` and `store.state` point to the same TreeNode. Use whichever reads
 ```typescript
 store.$.user.name.set('Bob');
 store.$.user.age.update((n) => n + 1);
-store.$.user({ name: 'Carol', age: 25 });   // replace a whole branch
-store({ user: { name: 'Dave', age: 40 }, settings: { theme: 'dark' } }); // replace full state
+store.$.user({ name: 'Carol', age: 25 });   // partial deep-merge update; sibling keys preserved
+store({ user: { name: 'Dave', age: 40 }, settings: { theme: 'dark' } }); // partial deep-merge of root; keys not in payload preserved
+store();                                    // no-arg call returns the current snapshot
 ```
 
 ### Lifecycle
 
 ```typescript
-store.destroy();                       // tears down all enhancer resources in reverse order
+store.destroy();                       // runs registered cleanup hooks in registration order
 store.destroyed();                     // Signal<boolean>
 store.registerCleanup(() => ws.close()); // custom hook called during destroy
 ```
@@ -95,7 +96,7 @@ store.$.users.setAll(users);
 store.$.users.upsertOne(user);
 store.$.users.upsertMany(users);
 store.$.users.updateOne(id, changes);
-store.$.users.updateMany([{ id, changes }, ...]);
+store.$.users.updateMany([id1, id2, id3], { active: false }); // shared Partial<E> applied to every id — NOT NgRx-style [{id, changes}]
 store.$.users.updateWhere(pred, changes);
 store.$.users.removeOne(id);
 store.$.users.removeMany(ids);
@@ -104,7 +105,7 @@ store.$.users.clear();
 
 // Queries (all return signals)
 store.$.users.all();              // Signal<User[]>
-store.$.users.byId(id);           // Signal<User | undefined>
+store.$.users.byId(id);           // EntityNode<User> | undefined — invoke: .byId(id)?.() → User | undefined
 store.$.users.count();            // Signal<number>
 store.$.users.has(id);            // Signal<boolean>
 store.$.users.ids();              // Signal<number[]>
@@ -128,20 +129,28 @@ const store = signalTree({
   },
 });
 
-// Read
-store.$.users.loading.state();      // Signal<LoadingState>
-store.$.users.loading.error();      // Signal<ApiError | null>
-store.$.users.loading.isLoading();  // Signal<boolean>
-store.$.users.loading.isLoaded();
-store.$.users.loading.isError();
-store.$.users.loading.isNotLoaded();
-
-// Mutate
+// Read — v10.3 canonical (bare names)
+store.$.users.loading.state();      // LoadingState (calling Signal<LoadingState>)
+store.$.users.loading.error();      // ApiError | null
+store.$.users.loading.loading();    // boolean
+store.$.users.loading.loaded();     // boolean
+store.$.users.loading.hasError();   // boolean
+store.$.users.loading.notLoaded();  // boolean
+// Deprecated through v10.x, removed v11: .isLoading, .isLoaded, .isError, .isNotLoaded
+// (same Signal instance — both work; canonical preferred in new code)
+
+// Mutate — canonical methods
 store.$.users.loading.setLoading();
 store.$.users.loading.setLoaded();
 store.$.users.loading.setError(err);
 store.$.users.loading.setNotLoaded();
 store.$.users.loading.reset();
+
+// v10.2+ Promise-vocabulary aliases (identical semantics, no args)
+store.$.users.loading.start();      // === setLoading()
+store.$.users.loading.setSuccess(); // === setLoaded() — NO ARGS
+store.$.users.loading.succeed();    // === setLoaded()
+store.$.users.loading.fail(err);    // === setError(err)
 ```
 
 ### `stored(key, defaultValue, options?)`
@@ -166,9 +175,9 @@ store.$.settings.theme.reload();  // re-read from localStorage
 
 Supports versioning and migration functions via the third argument. Use for individual per-leaf persistence; use the `persistence()` enhancer for tree-wide persistence with storage adapters.
 
-### `form<T>(config)` (from `@signaltree/ng-forms` integration)
+### `form<T>(config: FormConfig<T>)`
 
-Tree-integrated form with validation, wizard, and persistence. Materializes into a form signal exposing field state, validation status, and submit/reset helpers. See `@signaltree/ng-forms` documentation for full config schema.
+Tree-integrated form marker, **exported from `@signaltree/core`** (not from `@signaltree/ng-forms`). Materializes into a form signal exposing field state, validation status, and submit/reset helpers. Requires `{ initial: T, validators?, asyncValidators?, wizard? }`. `@signaltree/ng-forms` is a separate **bridge** that binds these markers to Angular `FormGroup` — useful but not required.
 
 ### Custom markers via `registerMarkerProcessor(spec)`
 
@@ -278,7 +287,7 @@ const store = signalTree({ count: 0, items: [] })
 
 store.batch(() => {
   store.$.count.set(10);
-  store.$.items.push({ id: 1 });
+  store.$.items.update((arr) => [...arr, { id: 1 }]); // .push() doesn't exist — arrays live in a WritableSignal
 });
 
 store.undo();
@@ -303,6 +312,8 @@ store.$.count((n) => n + 1);            // → store.$.count.update((n) => n + 1
 
 **This is not a runtime proxy.** The transform runs at build time and disappears in production — there is no wrapper function, no `Proxy` object, no runtime overhead. Install as a dev dependency, register the Vite or Webpack plugin, and the transform compiles away.
 
+> **Configure `rootIdentifiers`**: the plugin's default is `['tree']`. If your tree variable is named `store` or `state` (common in service facades), pass `{ rootIdentifiers: ['tree', 'store', 'state'] }` to the plugin options — variables not in this list are silently skipped.
+
 ---
 
 ## Subpath imports
@@ -310,12 +321,13 @@ store.$.count((n) => n + 1);            // → store.$.count.update((n) => n + 1
 Specialized APIs live in subpaths to keep the main barrel small:
 
 ```typescript
-import { TREE_PRESETS, createDevTree, createProdTree } from '@signaltree/core/presets';
 import { SecurityValidator, SecurityPresets } from '@signaltree/core/security';
-import { createEditSession } from '@signaltree/core/edit-session';
+import { createEditSession, createTreeEditSession } from '@signaltree/core/edit-session';
 import { createStorageAdapter, createIndexedDBAdapter } from '@signaltree/core/storage';
 ```
 
+The only published subpaths in `@signaltree/core` are `./security`, `./edit-session`, and `./storage`. The main barrel (`@signaltree/core`) re-exports everything; modern bundlers tree-shake unused symbols regardless.
+
 ### Async — `asyncSource` and `asyncQuery` markers (canonical, v9.5+)
 
 Async state belongs **at the tree path it describes**. Two markers cover the two main async patterns and compose with the rest of the marker family:
@@ -531,7 +543,7 @@ This is the pattern enforced in production migrations. The `$` access stays read
 | `status` | `.notLoaded` | `.isNotLoaded` |
 | `status` | `.hasError` | `.isError` |
 | `entityMap` | `.empty` | `.isEmpty` |
-| `form` | `.dirty`, `.valid`, `.touched`, `.pristine` | (already bare — unchanged) |
+| `form` | `.dirty`, `.valid`, `.touched`, `.submitting` | (already bare — unchanged) |
 | `asyncSource` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 | `asyncQuery` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 
@@ -591,7 +603,7 @@ For **input-driven queries** (debounced search, filtered fetch), use `asyncQuery
 | "Markers must live at the tree root." | Comparison to NgRx `with*` features. | Markers attach at **any node, any depth**. The walker tracks the path. |
 | "Derived state must live in a separate file, breaking the single-tree illusion." | Mixing up `derivedFrom` (file-org helper) with the actual `.derived($)` method. | `.derived()` merges computed signals **into the tree at arbitrary paths**, alongside source properties. The "single tree" is preserved. |
 | "`derivedFrom(tree, fn)` returns a read-only projection." | Hallucinated signature. | Real signature: `derivedFrom<TTree>()(fn)`. Curried. Zero runtime cost. Pure file-org helper for multi-file derived. |
-| "SignalTree has explicit subpath isolation as a built-in feature." | Misreading the docs. | No subpath-isolation API exists. `createEditSession(initial)` is a value-level undo/redo primitive (NOT tree-bound — that's planned for v10.1). For write encapsulation use `@signaltree/events` or a service facade. |
+| "SignalTree has explicit subpath isolation as a built-in feature." | Misreading the docs. | No subpath-isolation API exists. `createEditSession(initial)` is a value-level undo/redo primitive; for path-bound drafts use `createTreeEditSession(accessor)` (v10.1+, in `@signaltree/core/edit-session`). For write encapsulation use `@signaltree/events` or a service facade. |
 | "Time-travel is in `@signaltree/time-travel`." | Made-up package name. | Import `timeTravel` from `@signaltree/core`. No such separate package. |
 | "Persistence is in `@signaltree/storage`." | Made-up package name. | Use `stored()` marker (per-leaf) or `persistence()` enhancer (tree-wide) from `@signaltree/core`. |
 | "Batching is opt-in only." | Conflating automatic notification batching with the `batching()` enhancer. | Automatic microtask notification batching is built into core (default on). The enhancer adds explicit `.batch(fn)` / `.coalesce(fn)`. |
@@ -603,7 +615,7 @@ For **input-driven queries** (debounced search, filtered fetch), use `asyncQuery
 | "`tree.$` and `tree.state` are different objects." | Plausible-sounding inference. | Both are typed `TreeNode<T>` and reference the same reactive proxy. `state` is an alias for `$`. For a non-reactive full snapshot, call `tree()`. |
 | "The `form()` marker lives in `@signaltree/ng-forms`." | Package-boundary inference. | `form()` ships in `@signaltree/core`. `@signaltree/ng-forms` is a *bridge* for binding tree nodes to Angular `FormGroup`. |
 | "entityMap exposes `.entities()` as the read accessor." | Reasonable guess. | Real accessor is `.all()`. Other reads: `.byId(id)`, `.where(pred)`, `.find(pred)`, `.count()`, `.has(id)`, `.ids()`. |
-| "status exposes `.setSuccess()`." | NgRx/Redux convention bleed. | Real methods: `.setLoading()`, `.setLoaded()`, `.setError(err)`, `.setNotLoaded()`, `.reset()`. There is no `.setSuccess()`. |
+| "status exposes `.setSuccess()`." | NgRx/Redux convention bleed. | Canonical methods are `.setLoading()`, `.setLoaded()`, `.setError(err)`, `.setNotLoaded()`, `.reset()`. As of v10.2, Promise-vocabulary aliases `.start()` / `.setSuccess()` / `.succeed()` / `.fail(err)` also work — same semantics, no second source of truth. |
 | ".derived('$.path', derivedFn)' is a two-arg subpath form." | Hallucinated overload. | `.derived($ => ({...}))` is single-arg. The shape of the returned object determines which paths the computed signals attach to via deep-merge. |
 | "NgRx SignalStore mutations are impossible from components by design." | Overstating defaults. | Components can mutate when `protectedState: false` is set on the store, or when the store exposes a method that mutates. Both libraries are guarded-by-default but unlockable. |
 

package/llms.txt

@@ -1,6 +1,6 @@
 # SignalTree
 
-> Reactive JSON for Angular. Turn a plain object into a tree of signals — no actions, no reducers, no selectors. Markers and derived state attach at any depth in the tree.
+> Reactive JSON for Angular. State as shape. Signals at every path. Markers and derived state attach at any depth in the tree.
 
 SignalTree is a state-management library for Angular 17+. The mental model is: your state is a typed JSON object; reading and writing use ordinary signal calls along the JSON path. Markers (`entityMap`, `status`, `stored`, `form`) and derived state (`.derived(...)`) attach **at any node, at any depth** — they are processed by a recursive walker, not composed at the store root. This is the load-bearing difference from `@ngrx/signals` (NgRx SignalStore), whose `with*` features compose at the store root only.
 
@@ -20,7 +20,7 @@ const store = signalTree({
   settings: {
     theme: stored('app-theme', 'light'),         // marker at depth 2
     profileForm: {
-      data: form<Profile>({ name: '', email: '' }), // marker at depth 3
+      data: form<Profile>({ initial: { name: '', email: '' } }), // marker at depth 3
     },
   },
   loading: status<ApiError>(),                   // marker at depth 1
@@ -46,7 +46,7 @@ const store = signalTree({
 // Read — leaves, derived, async-marker accessors all uniform
 store.$.users.all();                            // Signal<User[]>
 store.$.users.current();                        // Signal<User | null> (derived)
-store.$.settings.theme();                       // 'light' (auto-loaded from localStorage)
+store.$.settings.theme();                       // 'light' (default; replaced by any value previously persisted to localStorage)
 store.$.reports();                              // Report[] (asyncSource current value)
 store.$.reports.loading();                      // boolean
 store.$.search.input.set('alice');              // drives debounced query
@@ -91,17 +91,17 @@ store.$.reports.refresh();                      // reload async source
 - **Create:** `signalTree(initialState, config?)` → tree with `.$` accessor
 - **Read leaf:** `tree.$.path.to.leaf()` — returns the value
 - **Write leaf:** `tree.$.path.to.leaf.set(v)` / `.update(fn)`
-- **Replace full state:** `tree(newState)`
+- **Partial / deep-merge update:** `tree(partialUpdate)` — keys not in the payload are preserved. The root has no `.set` method; the root accessor itself is callable.
 - **Markers:** `entityMap<E, K>()`, `status<E>()`, `stored(key, default)`, `form<T>(config)`, `asyncSource<T>(config)`, `asyncQuery<TIn, TOut>(config)` — place at any node
 - **Derived state:** `.derived($ => ({ ... }))` — definitions deep-merged into existing tree paths
 - **Enhancers:** `.with(batching())`, `.with(devTools())`, `.with(timeTravel())`, `.with(persistence())`, `.with(serialization())`
-- **Lifecycle:** `tree.destroy()` tears down all resources in reverse enhancer order; `tree.destroyed()` is a signal; `tree.registerCleanup(fn)` for custom hooks
-- **Edit sessions:** `createEditSession(initial)` from `@signaltree/core/edit-session` — wraps any value with `applyChanges` / `undo` / `redo` / `reset` / `setOriginal` for form-wizard and draft-and-cancel workflows. Independent of the tree; bridge by syncing `session.modified()` ↔ tree leaves when appropriate.
-- **Async:** `asyncSource(config)` for load-and-expose, `asyncQuery(config)` for input-driven debounced queries. Both attach at any tree path and auto-expose `data`/`loading`/`error`/`refresh`. For migrating from `@ngrx/signals`, see [`docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md`](https://github.com/JBorgia/signaltree/blob/main/docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md).
+- **Lifecycle:** `tree.destroy()` runs all registered cleanup callbacks in registration order; `tree.destroyed()` is a signal; `tree.registerCleanup(fn)` for custom hooks. Built-in enhancers register their own cleanup automatically.
+- **Edit sessions:** Two primitives in `@signaltree/core/edit-session`. `createEditSession(initial)` is value-level (single arg, no tree binding) — wraps any value with `applyChanges` / `undo` / `redo`. `createTreeEditSession(accessor)` (v10.1+) is **path-bound** to a writable tree branch — `applyChanges` / `undo` / `commit` (write draft back) / `cancel` (discard draft). Use the tree-bound form for form-wizard and draft-and-cancel workflows over a real tree path.
+- **Async:** `asyncSource(config)` for load-and-expose — auto-exposes `data` (call the accessor itself: `tree.$.users()`) / `loading` / `error` / `refresh`. `asyncQuery(config)` for input-driven debounced queries — auto-exposes `data` / `loading` / `error`, driven by setting `.input.set(value)` and optionally `.rerun()` to re-execute with the same input. Both attach at any tree path. For migrating from `@ngrx/signals`, see [`docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md`](https://github.com/JBorgia/signaltree/blob/main/docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md).
 
 ## ⚠️ Disambiguation — if you think SignalTree uses X, you're confusing it with Y
 
-This table catches the most common cross-library hallucinations. **Every "Wrong" pattern below was observed in a recent reproducible benchmark of frontier AI models (Claude, GPT-5.4, Gemini, Perplexity) asked to generate SignalTree code.** None of these patterns are or ever have been part of SignalTree.
+This table catches the most common cross-library hallucinations. **Most "Wrong" patterns below were observed in a reproducible 720-cell benchmark (6 agents × 8 prompts × 5 libraries × 3 priming modes) of frontier and cost-tier AI agents (Claude, GPT, Gemini, Perplexity, Haiku, GPT-mini) asked to generate SignalTree code.** A few rows (notably `rxMethod`) describe APIs SignalTree itself once shipped and has since removed — agents still emit them.
 
 | Wrong pattern (NOT SignalTree) | Where it actually comes from | Correct SignalTree |
 |---|---|---|
@@ -111,7 +111,7 @@ This table catches the most common cross-library hallucinations. **Every "Wrong"
 | `signalStore(withState(...), withMethods(...))` | **`@ngrx/signals`** | `signalTree({...})` — your state literal IS the API |
 | `withState`, `withMethods`, `withComputed`, `withHooks`, `withProps` | **`@ngrx/signals`** | Not used. State is the literal you pass to `signalTree()`. Methods belong in an `@Injectable()` Ops service. |
 | `withEntities<T>()` | **`@ngrx/signals/entities`** | `entityMap<T, K>()` marker — place it in the state literal |
-| `rxMethod(...)` | **`@ngrx/signals/rxjs-interop`** | `asyncSource(config)` (load-and-expose) or `asyncQuery(config)` (input-driven) markers |
+| `rxMethod(...)` | **`@ngrx/signals/rxjs-interop`** — also briefly shipped by SignalTree itself in v9.5.x, **removed in v9.6.0** | `asyncSource(config)` (load-and-expose) or `asyncQuery(config)` (input-driven) markers |
 | `patchState(store, {...})` | **`@ngrx/signals`** | Direct: `tree.$.path.set(value)` or branch update `tree.$.user({...})` |
 | `collection<T>({ idKey: 'id' })` | **Akita / Elf** | `entityMap<T, K>({ selectId: (e) => e.id })` marker |
 | `createStore`, `withProps`, `setProps` | **Elf** | Not used. SignalTree state is the literal. |
@@ -133,7 +133,7 @@ This table catches the most common cross-library hallucinations. **Every "Wrong"
 | `status` | `.notLoaded` | `.isNotLoaded` |
 | `status` | `.hasError` | `.isError` |
 | `entityMap` | `.empty` | `.isEmpty` |
-| `form` | `.dirty`, `.valid`, `.touched`, `.pristine` | (already bare — unchanged) |
+| `form` | `.dirty`, `.valid`, `.touched`, `.submitting` | (already bare — unchanged) |
 | `asyncSource` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 | `asyncQuery` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaltree/core",
-  "version": "10.3.0",
-  "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
+  "version": "10.3.2",
+  "description": "Reactive JSON for Angular. State as shape. Signals at every path.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,