r-state-tree 0.5.0 → 0.6.1

package/README.md

@@ -60,7 +60,7 @@ export default defineConfig({
 - 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
 
@@ -352,118 +352,172 @@ 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
+### `Observable` base class
 
-For reactive class instances outside the Model/Store system, use `@observable` and `@computed` decorators:
+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 observable is created in the base constructor, allowing derived field initializers (including `#private`) to run on the observable.
 
 ```ts
-import { Observable, observable, computed, effect } from "r-state-tree";
+import { Observable, effect } from "r-state-tree";
 
 class Counter extends Observable {
-	@observable count = 0;
-	@observable step = 1;
+	count = 0; // Public fields are automatically reactive
+	#internal = 0; // Private fields also work perfectly
 
-	@computed get doubled() {
-		return this.count * 2;
+	get total() {
+		return this.count + this.#internal;
 	}
 
 	increment() {
-		this.count += this.step;
+		this.count++;
+		this.#internal++;
 	}
 }
 
 const counter = new Counter();
 
+// Use an effect to track and react to property changes
 effect(() => {
-	console.log("Count:", counter.count, "Doubled:", counter.doubled);
+	console.log(`Visible: ${counter.count}, Total: ${counter.total}`);
 });
 
-counter.increment(); // Triggers the effect
+counter.increment();
 ```
 
-**Important:** Class instances require explicit `@observable` and `@computed` decorators. Properties without decorators are **not** reactive.
+> [!IMPORTANT] > **Why `extends Observable`?**
+> ES `#private` fields are brand-checked. If you wrap a class instance with `observable()` _after_ it has been created (post-hoc wrapping), or if you return an observable from a standard constructor, the private state is installed on the original `this`, but methods run with the observable as `this`, causing `TypeError: Cannot read private member`.
+>
+> `extends Observable` solves this by returning the observable from `super()`, so derived classes initialize their private fields directly on the observable receiver.
 
-### Plain objects (implicit reactivity)
+### Limitations of `observable(instance)`
 
-Plain objects wrapped with `observable()` use implicit reactivity:
+The `observable()` function is selective about what it makes observable. 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 an observable 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
-import { observable, effect } from "r-state-tree";
+// ❌ Post-hoc wrapping - returns raw URL, not an observable
+const url = observable(new URL("..."));
 
-const state = observable({ count: 0 });
+// ✅ 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(state.count); // All properties are reactive
+	console.log("Items length:", store.items.length);
 });
 
-state.count++; // Triggers the effect
+store.items.push({ value: 1 }); // Triggers effect
+console.log(isObservable(store.items[0])); // false - shallow by default
 ```
 
-### Shallow and signal observables
+### Shallow behavior
 
-Control the depth of reactivity with `@observable.shallow` and `@observable.signal`:
+All observables are **shallow by default**. Only the container's own properties are tracked—nested values are NOT wrapped:
 
-| Decorator | Container Observable? | Values Observable? | Triggers on... |
-|-----------|----------------------|-------------------|----------------|
-| `@observable` | ✅ Yes | ✅ Yes (deep) | mutations + assignment |
-| `@observable.shallow` | ✅ Yes | ❌ No | mutations + assignment |
-| `@observable.signal` | ❌ No | ❌ No | assignment only |
+- 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
 
-```ts
-import { Observable, observable, effect, isObservable } from "r-state-tree";
+**Mental model: reactive property, explicit reactive value**
 
-class DataStore extends Observable {
-	// Deep observable - items pushed are also observable
-	@observable deepItems: { value: number }[] = [];
+- 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.
 
-	// Shallow - container is observable, but pushed items are NOT
-	@observable.shallow shallowItems: { value: number }[] = [];
+**What gets tracked in shallow mode:**
 
-	// Signal - only assignment triggers, mutations do not
-	@observable.signal signalItems: number[] = [];
-}
+| 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      |
 
-const store = new DataStore();
+```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
+```
 
-// Shallow: items pushed are NOT observable (safe for structuredClone)
-store.shallowItems.push({ value: 1 });
-console.log(isObservable(store.shallowItems[0])); // false
+To make `nested` reactive, wrap it explicitly:
 
-// Signal: mutations don't trigger effects
-effect(() => store.signalItems.length);
-store.signalItems.push(1); // Does NOT trigger effect
-store.signalItems = [1, 2]; // DOES trigger effect
+```ts
+const data = observable({ nested: observable({ value: 1 }) });
+data.nested.value = 2; // Now triggers — `nested` is also observable
 ```
 
-**Use cases:**
-- `@observable.shallow`: Store external data that may need `structuredClone()`, or when you want change detection on the container but not deep reactivity
-- `@observable.signal`: Maximum performance when you're replacing values rather than mutating them
+### Plain objects (implicit reactivity)
 
-Models support the same modifiers with `@state`:
+Plain objects wrapped with `observable()` use implicit reactivity:
 
 ```ts
-class M extends Model {
-	@state.shallow items: { value: number }[] = []; // Container tracked, items not
-	@state.signal data: SomeType = null; // Only assignment tracked
-}
+import { observable, effect } from "r-state-tree";
+
+const state = observable({ count: 0 });
+
+effect(() => {
+	console.log(state.count); // All properties are reactive
+});
+
+state.count++; // Triggers the effect
 ```
 
 ## Observables (low‑level)
 
 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 observable-free if you didn't manually seed observables 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. It is **not** a “observable 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 observables.
+
+If you need to pass values to APIs that require cloneable data (e.g. `structuredClone`, `postMessage`), avoid seeding observables 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
@@ -506,10 +560,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 an observable (because it was explicitly owned), it remains an observable 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 observable 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 observable-free and clonable *as long as you don't manually seed observables*
+// into backing data structures. r-state-tree unwraps observables 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,
@@ -536,6 +666,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).
@@ -685,8 +903,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`
 
@@ -694,7 +914,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
@@ -702,17 +922,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;
 ```
 
@@ -724,18 +941,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
 
@@ -798,7 +1017,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:
 
@@ -884,7 +1104,9 @@ 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 observables to third‑party APIs that expect cloneable/serializable values (e.g. `structuredClone`). Use `source(value)` to get the backing value. It will be observable-free for values written via r-state-tree’s observable APIs (unwrap-on-write), but `source(...)` is **not** guaranteed observable-free if you manually seed observables 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.
 

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/observables/array.d.ts

@@ -4,17 +4,20 @@ import { SignalMap } from "./internal/NodeMap";
 export declare class ArrayAdministration<T> extends Administration<T[]> {
     valuesMap: SignalMap<number>;
     keysAtom: AtomNode;
+    private observableSources;
+    private rawSources;
+    private trackValue;
     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,10 +7,11 @@ 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;
-export declare function isShallowObservable(obj: unknown): boolean;
-export declare function getShallowObservable<T>(value: T): T;
 export declare function isObservable(obj: unknown): boolean;
 export declare function getInternalNode(obj: object, key?: PropertyKey): any;