r-state-tree 0.4.7 → 0.6.0

package/README.md

@@ -42,12 +42,25 @@ TypeScript 5+ supports TC39 Stage 3 decorators.
 - `useDefineForClassFields: true` is recommended with modern toolchains targeting ES2022.
 - The library includes a `Symbol.metadata` polyfill via `@tsmetadata/polyfill`.
 
+### Vite / esbuild config (SSR)
+
+When using Vite or esbuild for SSR, ensure the target is set to `es2022` to support Stage 3 decorators:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+	esbuild: {
+		target: "es2022",
+	},
+});
+```
+
 ## Core concepts
 
 - Stores: application/view state containers. Create with `createStore()`, attach with `mount()`. Compose with `@child` (single or arrays, stable via `{ key }`). React to changes with `effect`/`reaction` and store lifecycles (`storeDidMount`/`storeWillUnmount`). Update reactive `props` via `updateStore()`.
 - Models: domain state containers. Create with `Model.create()`. Persistent via snapshots (`toSnapshot`, `applySnapshot`, `onSnapshot`, diffs via `onSnapshotDiff`). Structure with `@state`, `@child`, identifiers via `@id`, and references via `@modelRef`.
 - Context: pass data through Store/Model trees without prop drilling using `createContext<T>()`, `[Context.provide]`, and `Context.consume(this)`. Context is reactive and can be overridden by descendants.
-- Reactivity: powered by signals. Use `@observable`, `@computed`, `effect`, `reaction`, `batch`, and `untracked` for precise updates.
+- Reactivity: powered by signals. Use `observable()`, `@computed`, `effect`, `reaction`, `batch`, and `untracked` for precise updates.
 
 ## Separation of concerns
 
@@ -339,39 +352,151 @@ class ListStore extends Store {
 
 ## Mutability rules
 
-- Models: prefer in-place mutation for arrays/maps/sets (`push`, `splice`, `set`, etc.). Replace the whole structure only when you intentionally want to swap the instance.
-- Stores: store fields are reactive; in-place mutation is fine. Reassign the entire structure only if you need identity replacement semantics.
+- Models: model fields are shallow-reactive, but values are not auto-wrapped. For raw `@state` arrays/objects, prefer **reassignment** (immutability) so snapshots stay up to date. If you want in-place mutation (`push`, `splice`, `set`, etc.) to trigger updates and snapshot invalidation, store an `observable()` container (or `signal()`) in `@state`.
+- Stores: store fields are shallow-reactive. Use `observable()` containers (or `signal()`) when you want in-place mutations of nested values/collections to trigger updates.
 
 ## Observable classes
 
-For reactive class instances outside the Model/Store system, use `@observable` and `@computed` decorators:
+For reactive class instances outside the Model/Store system, wrap state with `observable()`:
 
 ```ts
-import { Observable, observable, computed, effect } from "r-state-tree";
+import { observable, computed, effect } from "r-state-tree";
 
-class Counter extends Observable {
-	@observable count = 0;
-	@observable step = 1;
+class Counter {
+	state = observable({ count: 0, step: 1 });
 
 	@computed get doubled() {
-		return this.count * 2;
+		return this.state.count * 2;
 	}
 
 	increment() {
-		this.count += this.step;
+		this.state.count += this.state.step;
 	}
 }
 
 const counter = new Counter();
 
 effect(() => {
-	console.log("Count:", counter.count, "Doubled:", counter.doubled);
+	console.log("Count:", counter.state.count, "Doubled:", counter.doubled);
 });
 
 counter.increment(); // Triggers the effect
 ```
 
-**Important:** Class instances require explicit `@observable` and `@computed` decorators. Properties without decorators are **not** reactive.
+### `Observable` base class
+
+For class instances that need to be reactive, extending the `Observable` base class is the supported pattern. This ensures compatibility with ES `#private` fields and built-in brand checks because the Proxy is created in the base constructor, allowing derived field initializers (including `#private`) to run on the Proxy.
+
+```ts
+import { Observable, effect } from "r-state-tree";
+
+class Counter extends Observable {
+	#count = 0; // Correctly works with #private
+
+	get count() {
+		return this.#count;
+	}
+
+	increment() {
+		this.#count++;
+	}
+}
+
+const counter = new Counter();
+effect(() => console.log(counter.count));
+counter.increment();
+```
+
+> [!IMPORTANT] > **Why `extends Observable`?**
+> ES `#private` fields are brand-checked. If you proxy a class instance _after_ it has been created (post-hoc proxying), or if you return a proxy from a standard constructor, the private state is installed on the original `this`, but methods run with the Proxy as `this`, causing `TypeError: Cannot read private member`.
+>
+> `extends Observable` solves this by returning the Proxy from `super()`, so derived classes initialize their private fields directly on the Proxy receiver.
+
+### Limitations of `observable(instance)`
+
+The `observable()` function is selective about what it proxies. It wraps **supported containers** only:
+
+- Plain objects
+- Arrays
+- Maps and Sets
+- Dates
+
+**Functions are not observable containers**. Calling `observable(fn)` returns the function unchanged with a dev-mode warning. However, functions stored as properties on observable objects are still automatically **batched as actions** when called—this existing behavior is preserved, just not via `observable(fn)` directly.
+
+If you pass an arbitrary class instance, built-in (like `URL`, `RegExp`, `Promise`, or DOM objects), or frozen object to `observable()`, it will **return the object unchanged** and emit a warning in development mode.
+
+This design prevents “silent failure” where a proxied object appears to work but throws `TypeError` when accessing private members or internal slots. For your own classes, use `extends Observable`. For third-party or built-in objects, use composition:
+
+```ts
+// ❌ Post-hoc proxying - returns raw URL, not a proxy
+const url = observable(new URL("..."));
+
+// ✅ Composition - wrap a container instead
+const state = observable({ url: new URL("...") });
+```
+
+Wrap values with `observable()` for reactivity. Collections (arrays, maps, sets) track mutations:
+
+```ts
+import { observable, effect, isObservable } from "r-state-tree";
+
+class DataStore {
+	// Wrap state with observable() for reactivity
+	state = observable({ count: 0 });
+
+	// Wrap array with observable() to track push/pop/splice etc.
+	items = observable([]);
+}
+
+const store = new DataStore();
+
+effect(() => {
+	console.log("Items length:", store.items.length);
+});
+
+store.items.push({ value: 1 }); // Triggers effect
+console.log(isObservable(store.items[0])); // false - shallow by default
+```
+
+### Shallow behavior
+
+All observables are **shallow by default**. Only the container's own properties are tracked—nested values are NOT wrapped:
+
+- Collections (Arrays, Maps, Sets) wrapped with `observable()` track mutations
+- Plain objects assigned to properties are NOT wrapped (helps preserve `structuredClone` compatibility for stored values)
+- Nested object properties do NOT trigger effects unless explicitly wrapped
+
+**Mental model: reactive property, explicit reactive value**
+
+- Reading/writing a property on an observable container (including Stores/Models) is reactive.
+- The _value_ you store is not auto-wrapped. If you store a plain object/array, mutating inside it won’t trigger reactions; wrap nested values with `observable()` (or use `signal()`), or use `toObservableTree` for a one-time deep wrap of an existing JSON-like structure.
+
+**What gets tracked in shallow mode:**
+
+| Expression              | Tracked?      | Why                                              |
+| ----------------------- | ------------- | ------------------------------------------------ |
+| `data.nested`           | ✅ Yes        | Property access on the observable container      |
+| `data.nested.value`     | ❌ No         | `data.nested` is a plain object, not observable  |
+| `data.nested = { ... }` | ✅ Triggers   | Reassigns a property on the observable container |
+| `data.nested.value = 2` | ❌ No trigger | Mutates a plain object; container unchanged      |
+
+```ts
+const data = observable({ nested: { value: 1 } });
+
+effect(() => {
+	data.nested.value; // Reads `data.nested` (tracked), then reads `.value` (not tracked)
+});
+
+data.nested.value = 2; // Does NOT trigger — mutating a plain object
+data.nested = { value: 3 }; // DOES trigger — reassigning a property on the observable
+```
+
+To make `nested` reactive, wrap it explicitly:
+
+```ts
+const data = observable({ nested: observable({ value: 1 }) });
+data.nested.value = 2; // Now triggers — `nested` is also observable
+```
 
 ### Plain objects (implicit reactivity)
 
@@ -393,15 +518,27 @@ state.count++; // Triggers the effect
 
 Create reactive structures outside Stores/Models. Supported: Objects, Arrays, Map, Set, WeakMap, WeakSet.
 
-- Track reads with `effect`/`reaction`. Nested values are tracked when you access them inside your effects.
-- Access raw values via `source(observable)`; check if something is reactive with `isObservable(value)`.
+- Track reads with `effect`/`reaction`. Observables are **shallow**: reads are tracked on the observable container, but nested object mutations do **not** trigger unless you explicitly wrap nested values with `observable()` (or use signals).
+- Access backing values via `source(value)`; check if something is reactive with `isObservable(value)`.
+- Rule of thumb: `source(...)` returns the backing data, **not** a sanitizer—it's only proxy-free if you didn't manually seed proxies into the backing source.
 - Arrays: reading specific indices (`arr[i]`) or `length` tracks those; common mutators (`push/pop/shift/unshift/splice/reverse/sort/fill`) are reactive; non-index and symbol keys are not reactive.
 
+### `source()` and structuredClone
+
+`source(x)` returns the backing value behind an observable proxy/container. It is **not** a “proxy stripper”.
+
+**One-way rule (important):**
+
+- If you mutate through the observable wrapper (e.g. `obj.prop = observable(child)`), r-state-tree stores the **raw backing value** in `source(obj).prop` (unwrap-on-write).
+- If you manually mutate backing sources yourself (e.g. `source(obj).prop = observable(child)`), r-state-tree does **not** sanitize or rewrite your data. In that case, `source(...)` may contain proxies.
+
+If you need to pass values to APIs that require cloneable data (e.g. `structuredClone`, `postMessage`), avoid seeding observable proxies into backing sources. Prefer reading via `source(...)` and keep your stored values plain/cloneable.
+
 ```ts
 import { observable, effect, computed, reaction } from "r-state-tree";
 
 // Object
-const state = observable({ count: 0, nested: { value: 1 } });
+const state = observable({ count: 0, nested: observable({ value: 1 }) });
 
 effect(() => {
 	// tracks reads
@@ -444,10 +581,86 @@ reaction(
 state.count++;
 ```
 
+### Derived collections and identity preservation
+
+Native methods that return copies of a collection—such as `Array.prototype.slice`, `filter`, and `concat`, or `Set.prototype.union` and `intersection`—behave according to the **Explicit Architecture**:
+
+- **Raw Return**: The returned container is a plain JavaScript object (raw, non-observable).
+- **Identity Preservation**: Each element in the returned container maintains the same identity it had in the observable source. If an element was a proxy (because it was explicitly owned), it remains a proxy in the raw result.
+
+This ensures that "derived" state is not automatically made reactive, while still allowing observers to maintain reference stability with existing objects in your state tree.
+
+```ts
+const item = observable({ id: 1 });
+const arr = observable([item, { id: 2 }]);
+
+// slice() returns a plain array
+const sliced = arr.slice();
+isObservable(sliced); // false
+
+// Identity is preserved
+sliced[0] === item; // true (same proxy identity)
+
+// If you want the result to be reactive, wrap it explicitly
+const reactiveSlice = observable(arr.slice());
+```
+
+### Recursively wrapping nested values (`toObservableTree`)
+
+By default, `observable()` is **shallow**: only the top-level container is wrapped, and nested objects/arrays are not. This is intentional for performance and `structuredClone` compatibility.
+
+`toObservableTree` performs a **one-time initial pass** that wraps all existing nested plain objects and arrays with `observable()`. After the initial wrap, the returned observables behave exactly like normal shallow observables — new assignments are **not** auto-wrapped.
+
+```ts
+import { toObservableTree, effect, source, isObservable } from "r-state-tree";
+
+// Initial pass wraps all existing nested plain objects/arrays
+const tree = toObservableTree({
+	user: { name: "Alice", tags: ["admin", "active"] },
+	settings: { theme: "dark" },
+});
+
+effect(() => {
+	// Existing nested values are observable and tracked
+	console.log(tree.user.name);
+	console.log(tree.user.tags[0]);
+});
+
+// Mutations to initially-wrapped values trigger effects
+tree.user.name = "Bob"; // triggers
+tree.user.tags[0] = "superadmin"; // triggers
+
+// NEW assignments are NOT auto-wrapped (normal shallow behavior)
+tree.newProp = { foo: 1 };
+isObservable(tree.newProp); // false — not wrapped
+
+// Source is proxy-free and clonable *as long as you don't manually seed proxies*
+// into backing data structures. r-state-tree unwraps proxies on writes performed
+// through observable containers, but it does not sanitize user-mutated backing sources.
+const snapshot = structuredClone(source(tree));
+```
+
+**Key behavior:**
+
+- **One-time pass**: Only values present at call time are wrapped. New assignments afterward behave like normal `observable()` (shallow).
+- **Not MobX-style "deep"**: This does NOT change the observable's behavior. It's just a convenience for wrapping an existing structure upfront.
+
+**When to use:**
+
+- Hydrating API/JSON responses where you want all nested values observable from the start
+- Cases where manually wrapping each nested object would be tedious
+
+**Constraints:**
+
+- Input must be JSON-like and **acyclic** (no circular references)
+- Only plain objects and arrays are wrapped; other types (Map, Set, Date, class instances, RegExp, Error, etc.) are left as-is and not traversed
+
 ## Models and snapshots
 
 Models capture persistent state with snapshot utilities.
 
+**Important:** `@state` is **shallow-reactive** at the property level (assignments track), but values are **not auto-wrapped**. If you need nested mutations to be reactive (and to invalidate snapshot caches on in-place mutation), store `observable()` containers or `signal()` values inside `@state`.
+
 ```ts
 import {
 	Model,
@@ -474,6 +687,94 @@ todo.title = "Learn r-state-tree";
 stop();
 ```
 
+### Snapshot data contract
+
+**Snapshots are JSON-only**: they contain primitives, arrays, plain objects, and Dates (serialized as ISO strings).
+
+- **Primitives**: `string`, `number`, `boolean`, `null`, `undefined` pass through.
+- **Arrays**: recursively cloned.
+- **Plain objects**: recursively cloned (prototype must be `Object.prototype` or `null`).
+- **Dates**: serialize to ISO strings (e.g., `"2024-01-15T10:30:00.000Z"`).
+- **Signals**: serialize to their current `.value` (recursively cloned).
+- **Map/Set/WeakMap/WeakSet and other non-plain objects are rejected** with a descriptive error. Convert them to plain structures before storing in `@state`.
+
+```ts
+class Event extends Model {
+	@state title = "Meeting";
+	@state createdAt = new Date(); // Date → ISO string in snapshot
+}
+
+const event = Event.create();
+toSnapshot(event);
+// { title: "Meeting", createdAt: "2024-01-15T10:30:00.000Z" }
+```
+
+If you store a `Map` or class instance in `@state`, snapshotting will throw:
+
+```ts
+class M extends Model {
+	@state cache = new Map(); // ❌ Will throw on toSnapshot()
+}
+// Error: r-state-tree: snapshots do not support Map at path "cache". ...
+```
+
+Convert to a plain structure instead:
+
+```ts
+class M extends Model {
+	@state cache: Record<string, unknown> = {}; // ✅ Plain object
+}
+```
+
+### Snapshot invalidation rules
+
+Snapshots are **memoized computeds**. Once a snapshot is observed (via `onSnapshot`, `onSnapshotDiff`, or `toSnapshot`), subsequent calls return the cached value unless a reactive dependency changes.
+
+Because snapshots are **memoized computeds** and observables are **shallow**, the snapshot cache is invalidated only by:
+
+1. **Reassigning** the `@state` field itself.
+2. **Mutating observable containers** (`observable()`) or **signals** (`signal()`) stored in the field.
+
+**Rule:** Treat raw `@state` values (plain objects/arrays) as immutable. If you mutate them in place without reassignment, the snapshot cache goes stale—`onSnapshot` won't fire and `toSnapshot` returns the old cached value.
+
+```ts
+class M extends Model {
+	@state tags: string[] = [];
+
+	// ❌ In-place mutation — snapshot cache goes stale
+	addTagBroken(tag: string) {
+		this.tags.push(tag);
+	}
+
+	// ✅ Reassign — invalidates cache, onSnapshot fires
+	addTagReassign(tag: string) {
+		this.tags = [...this.tags, tag];
+	}
+}
+```
+
+If you need in-place mutations **and** snapshot updates, wrap the value in `observable()` or use `signal()`:
+
+```ts
+class M extends Model {
+	// ✅ observable() container — in-place mutations invalidate cache
+	@state items: { id: number }[] = observable([]);
+
+	addItem(id: number) {
+		this.items.push({ id }); // onSnapshot fires
+	}
+}
+
+class Counter extends Model {
+	// ✅ signal() — .value updates invalidate cache
+	@state count = signal(0);
+
+	increment() {
+		this.count.value++; // onSnapshot fires
+	}
+}
+```
+
 ### Snapshots and persistence
 
 - Snapshots capture Models (not Stores).
@@ -623,8 +924,10 @@ class ContainerModel extends Model {
 - Context
   - `createContext`, type `Context`
 - Reactivity and observables
-  - `observable`, `computed`, `effect`, `reaction`, `batch`, `untracked`, `Observable`
+  - `observable`, `computed`, `effect`, `reaction`, `batch`, `untracked`
   - Utilities: `isObservable`, `source`, `reportObserved`, `reportChanged`
+- Advanced
+  - `toObservableTree` — recursively wrap nested values in a JSON-like structure
 - Signals interop
   - `signal`, `getSignal`, types `Signal`, `ReadonlySignal`
 
@@ -632,7 +935,7 @@ class ContainerModel extends Model {
 
 r-state-tree is built on `@preact/signals-core`. You can interoperate with signals directly:
 
-- Per-property signals via `$prop` on observable objects (including Stores/Models), or `getSignal(obj, key)`.
+- Per-property signals via `getSignal(obj, key)`.
 - Re-exported utilities: `signal`, `computed`, `effect`, `batch`, `untracked`, and types `Signal`, `ReadonlySignal`.
 
 ```ts
@@ -640,17 +943,14 @@ import { observable, effect, getSignal } from "r-state-tree";
 
 const state = observable({ count: 0 });
 
-// Either form returns a Signal<number>
-const s1 = state.$count;
-const s2 = getSignal(state, "count");
+const countSignal = getSignal(state, "count");
 
 effect(() => {
-	// Use s1.value (or s2.value) in your UI binding
-	console.log("count:", s1.value);
+	console.log("count:", countSignal.value);
 });
 
 // Update via signal or through the object
-s1.value = 1;
+countSignal.value = 1;
 state.count = 2;
 ```
 
@@ -662,18 +962,20 @@ state.count = 2;
 ```ts
 // Preact
 function TodoView({ store }: { store: TodoStore }) {
-	return <h1>{store.$title.value}</h1>;
+	const titleSignal = getSignal(store, "title");
+	return <h1>{titleSignal.value}</h1>;
 }
 
 // React
 import { useSignals } from "@preact/signals-react/runtime";
 function TodoView({ store }: { store: TodoStore }) {
 	useSignals();
-	return <h1>{store.$title.value}</h1>;
+	const titleSignal = getSignal(store, "title");
+	return <h1>{titleSignal.value}</h1>;
 }
 ```
 
-You can also use `getSignal(store, "title")` instead of `$title`. Use the observers/renderers provided by the signals bindings for your UI library; r-state-tree will participate automatically because Stores/Models are signal-backed.
+Use the observers/renderers provided by the signals bindings for your UI library; r-state-tree will participate automatically because Stores/Models are signal-backed.
 
 ### Identifier and reference rules
 
@@ -736,7 +1038,8 @@ Do:
 - Delegate from Stores to Models for domain changes
 - Use `@child` for child stores (getter-based)
 - Use stable `key` values for child stores
-- Mutate model arrays/maps/sets in place
+- Mutate **`@child` model collections** and **`observable()` containers** in place (push/splice/set/add/etc.)
+- Treat **raw `@state` arrays/objects** as immutable: use reassignment so snapshots stay up to date (or store an `observable()` container / `signal()` inside `@state`)
 
 Don’t:
 
@@ -822,8 +1125,35 @@ const off = onSnapshot(m, (snap) =>
 ## Common pitfalls
 
 - Forgetting stable keys for `@child` arrays causes identity churn.
-- Assuming deep reactivity on undecorated fields of plain classes; use `@observable` for `Observable` classes, or use Stores/Models.
+- Assuming **deep** reactivity: nested plain objects/arrays are not reactive unless you explicitly wrap them (or use `toObservableTree` for initial hydration).
+- Mutating raw `@state` arrays/objects in place (`push`, `obj.x = 1`) and expecting snapshots to update. Snapshots are memoized; use reassignment or store `observable()` containers / `signal()` values in `@state`.
+- Passing observable proxies to third‑party APIs that expect cloneable/serializable values (e.g. `structuredClone`). Use `source(value)` to get the backing value. It will be proxy-free for values written via r-state-tree’s observable APIs (unwrap-on-write), but `source(...)` is **not** guaranteed proxy-free if you manually seed proxies into backing sources.
 - Creating child stores in constructors: `@child` must be on getters so identity and lifecycle can be managed by the framework.
+- Passing `models` into child stores during mount can create a recursive mount loop. If a child needs parent models, create the child store/model inside `storeDidMount` instead of wiring it through `models` during the mount cycle.
+
+### Circular store/model creation
+
+When child stores are created during mount with `models` that point back into the parent, it is easy to trigger an endless mount loop. The runtime now guards this by throwing a descriptive error (for example, `detected circular store/model creation while mounting ParentStore -> ChildStore.loop -> ...`). If you see this, move child creation into `storeDidMount` or break the cycle so that models are produced after the parent finishes mounting.
+
+## LLM implementation checklist
+
+- Do not thread context data via props. Provide contexts at the parent and consume them in children. Passing `getX` callbacks for resource/page/video/skill is a red flag—consume contexts instead.
+- Avoid aggregating contexts into a single `ctx` object; consume where needed or expose small, focused getters.
+- Only create stores in three places: root, `@child` getters, or immediately before mounting. Avoid standalone factory helpers; inline `createStore` in `@child` getters.
+- Do not wrap `createStore` calls with `as Record<string, unknown>`; fix typing instead.
+- Domain/persistent state belongs in Models; UI/app orchestration in Stores. Keep UI terms out of domain models—name domain concepts (e.g., `ChatThreadsModel`).
+- If state is persistent/rehydratable, model it and derive stores from the model; keep purely view/ephemeral state in stores.
+- Use r-state-tree snapshots (`toSnapshot`/`applySnapshot`) instead of hand-rolled `serialize`/`rehydrate` unless a different shape is required.
+- Keep `onPersist` only when syncing store state into a backing model; otherwise prefer snapshot listeners.
+- Pure, stateless helpers belong in utility modules, not as store methods. If a method does not touch `this`, extract it; keep coupled helpers in the store.
+- Provide stable, rarely changing resource/view/video/page data via context (resourceId, resourceType, totalPages, current page/display mode, page offsets, document title, skill/detail, video info). Children should consume context directly.
+- Use `@child` getters to create child stores with stable keys; avoid constructor creation. Pass only what the child needs; avoid prop drilling context.
+- Eliminate blanket casts; fix types and let inference work. Avoid `any`.
+- For `createStore` props, extend `Record<string, unknown>` only if needed; otherwise rely on proper prop types and context.
+- Avoid barrel files if they cause import confusion; prefer direct imports.
+- Keep file boundaries clean: one model per file; avoid piling multiple models together.
+- Do not shadow `props` or use constructors for work better suited to `storeDidMount`.
+- Use `@model` for injected models; `@child` for child stores; stable keys for arrays.
 
 ## Typing recipes
 

package/dist/index.d.ts

@@ -3,8 +3,9 @@ import Store, { createStore, updateStore } from "./store/Store";
 import Model from "./model/Model";
 import { mount, unmount, onSnapshot, toSnapshot, applySnapshot, onSnapshotDiff } from "./api";
 import { createContext } from "./context";
-export { createStore, Store, Model, mount, unmount, updateStore, onSnapshot, onSnapshotDiff, toSnapshot, applySnapshot, createContext, };
-export { observable, computed, source, reportChanged, reportObserved, getSignal, isObservable, reaction, Signal, type ReadonlySignal, batch, untracked, effect, Observable, signal, } from "./observables";
+import { toObservableTree } from "./toObservableTree";
+export { createStore, Store, Model, mount, unmount, updateStore, onSnapshot, onSnapshotDiff, toSnapshot, applySnapshot, createContext, toObservableTree, };
+export { observable, computed, source, reportChanged, reportObserved, getSignal, isObservable, reaction, Signal, type ReadonlySignal, batch, untracked, effect, signal, Observable, } from "./observables";
 export * from "./decorators";
-export type { Configuration, Snapshot, IdType, SnapshotDiff } from "./types";
+export type { Configuration, Snapshot, SnapshotValue, IdType, SnapshotDiff, } from "./types";
 export type { Context } from "./context";

package/dist/model/ChildModelsAdministration.d.ts

@@ -29,7 +29,7 @@ declare class ObservableListener<T> {
     notify(ev: MutationEvent<T>): void;
 }
 export declare class ChildModelsAdministration<T> extends ArrayAdministration<T> {
-    set(index: number, newValue: T): void;
+    set(index: number, newValue: T): boolean;
     spliceWithArray(index: number, deleteCount?: number | undefined, newItems?: T[] | undefined): T[];
 }
 export {};

package/dist/model/ModelAdministration.d.ts

@@ -16,9 +16,11 @@ export declare class ModelAdministration extends PreactObjectAdministration<any>
     private modelsTraceUnsub;
     private writeInProgress;
     private computedSnapshot;
+    private snapshotAtom;
     private snapshotMap;
     private contextCache;
     parentName: PropertyKey | null;
+    private observeSnapshotValue;
     get parent(): ModelAdministration | null;
     set parent(value: ModelAdministration | null);
     setConfiguration(configurationGetter: () => ModelConfiguration<any>): void;

package/dist/observables/array.d.ts

@@ -4,17 +4,19 @@ import { SignalMap } from "./internal/NodeMap";
 export declare class ArrayAdministration<T> extends Administration<T[]> {
     valuesMap: SignalMap<number>;
     keysAtom: AtomNode;
+    private explicitObservables;
+    private syncExplicitObservablesFromSource;
     static proxyTraps: ProxyHandler<Array<unknown>>;
     static methods: Partial<{
         [K in keyof typeof Array.prototype as (typeof Array.prototype)[K] extends Function ? K : never]: (typeof Array.prototype)[K];
     }>;
     constructor(source?: T[]);
-    protected reportObserveDeep(): void;
     getNode(key?: number): unknown;
     get(index: number): T | undefined;
-    set(index: number, newValue: T): void;
+    private _getEffectiveValue;
+    set(index: number, newValue: T): boolean;
     getArrayLength(): number;
-    setArrayLength(newLength: number): void;
+    setArrayLength(input: unknown): boolean;
     spliceWithArray(index: number, deleteCount?: number, newItems?: T[]): T[];
     spliceItemsIntoValues(index: number, deleteCount: number, newItems: T[]): T[];
     onArrayChanged(lengthChanged?: boolean, index?: number, count?: number): void;

package/dist/observables/collection.d.ts

@@ -7,30 +7,26 @@ export declare class CollectionAdministration<K, V = K> extends Administration<C
     hasMap: AtomMap<K>;
     valuesMap: SignalMap<K>;
     keysAtom: AtomNode;
+    private isWeak;
+    private strongTracking;
+    private weakTracking;
     static proxyTraps: ProxyHandler<Set<unknown> | Map<unknown, unknown>>;
-    static methods: {
-        clear: (this: any) => unknown;
-        forEach: (this: any) => unknown;
-        has: (this: any) => unknown;
-        add: (this: any) => unknown;
-        set: (this: any) => unknown;
-        get: (this: any) => unknown;
-        delete: (this: any) => unknown;
-        entries: (this: any) => unknown;
-        keys: (this: any) => unknown;
-        values: (this: any) => unknown;
-        [Symbol.iterator]: (this: any) => unknown;
-    };
+    static methods: Record<PropertyKey, Function>;
     constructor(source: Collection<K, V>);
+    private trackExplicitObservable;
+    private untrackExplicitObservable;
+    private hasExplicitObservable;
+    private getProxyVariant;
+    private getExistingKey;
     private hasEntry;
     private onCollectionChange;
-    protected reportObserveDeep(): void;
     getNode(key?: K): unknown;
     clear(): void;
     forEach(callbackFn: (value: V, key: K, collection: Collection<K, V>) => void, thisArg?: unknown): void;
     get size(): number;
     add(value: K): this;
     delete(value: K): boolean;
+    private wrapSetValue;
     has(value: K): boolean;
     entries(): IterableIterator<[K, V]>;
     keys(): IterableIterator<K>;

package/dist/observables/index.d.ts

@@ -1,6 +1,6 @@
-export { getAdministration, getSource, isObservable, getObservable, getObservableClassInstance, getInternalNode, createObservableWithCustomAdministration, } from "./internal/lookup";
+export { getAdministration, getSource, isObservable, getObservable, getInternalNode, createObservableWithCustomAdministration, Observable, } from "./internal/lookup";
 export { ArrayAdministration } from "./array";
 export { CollectionAdministration } from "./collection";
 export { DateAdministration } from "./date";
 export { ObjectAdministration } from "./object";
-export { type AtomNode, reaction, type SignalNode, createAtom, batch, createComputed, createSignal, untracked, type ListenerNode, createListener, type ComputedNode, PreactObjectAdministration, getSignal, source, reportChanged, reportObserved, observable, computed, Signal, type ReadonlySignal, effect, signal, Observable, } from "./preact";
+export { type AtomNode, reaction, type SignalNode, createAtom, batch, createComputed, createSignal, untracked, type ListenerNode, createListener, type ComputedNode, PreactObjectAdministration, getSignal, source, reportChanged, reportObserved, observable, computed, Signal, type ReadonlySignal, effect, signal, } from "./preact";

package/dist/observables/internal/Administration.d.ts

@@ -7,11 +7,10 @@ export declare class Administration<T extends object = any> {
     readonly atom: ObservedAtomNode;
     protected valuesMap?: SignalMap;
     protected isObserved: boolean;
-    private forceObservedAtoms?;
+    private forceObservedAtom?;
     constructor(source: T);
     protected flushChange(): void;
     getNode(): unknown;
     reportChanged(): void;
-    protected reportObserveDeep(): void;
-    reportObserved(deep?: boolean): void;
+    reportObserved(): void;
 }

package/dist/observables/internal/NodeMap.d.ts

@@ -13,6 +13,7 @@ declare class NodeMap<K = unknown, GraphNode extends AtomNode | SignalNode<unkno
     getOrCreate(key: K, value?: unknown): GraphNode;
     reportObserved(key: K, value?: unknown): void;
     reportChanged(key: K, value?: unknown): void;
+    keys(): Iterable<unknown>;
 }
 export declare class AtomMap<K = unknown> extends NodeMap<K, AtomNode> {
     protected createNode(): AtomNode;

package/dist/observables/internal/lookup.d.ts

@@ -7,6 +7,9 @@ export declare function getAdministration<T extends object>(obj: T): T extends S
 export declare function getSource<T>(obj: T): T;
 export declare function getAction<T extends Function>(fn: T): T;
 export declare function getObservableClassInstance<T extends object>(value: T): T;
+export declare class Observable {
+    constructor();
+}
 export declare function getObservableIfExists<T>(value: T): T | undefined;
 export declare function createObservableWithCustomAdministration<T>(value: T, Adm: new (obj: any) => Administration): T;
 export declare function getObservable<T>(value: T): T;