r-state-tree 0.4.7 → 0.5.0

package/README.md

@@ -42,6 +42,19 @@ 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()`.
@@ -389,6 +402,55 @@ effect(() => {
 state.count++; // Triggers the effect
 ```
 
+### Shallow and signal observables
+
+Control the depth of reactivity with `@observable.shallow` and `@observable.signal`:
+
+| 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 |
+
+```ts
+import { Observable, observable, effect, isObservable } from "r-state-tree";
+
+class DataStore extends Observable {
+	// Deep observable - items pushed are also observable
+	@observable deepItems: { value: number }[] = [];
+
+	// Shallow - container is observable, but pushed items are NOT
+	@observable.shallow shallowItems: { value: number }[] = [];
+
+	// Signal - only assignment triggers, mutations do not
+	@observable.signal signalItems: number[] = [];
+}
+
+const store = new DataStore();
+
+// Shallow: items pushed are NOT observable (safe for structuredClone)
+store.shallowItems.push({ value: 1 });
+console.log(isObservable(store.shallowItems[0])); // false
+
+// 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
+```
+
+**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
+
+Models support the same modifiers with `@state`:
+
+```ts
+class M extends Model {
+	@state.shallow items: { value: number }[] = []; // Container tracked, items not
+	@state.signal data: SomeType = null; // Only assignment tracked
+}
+```
+
 ## Observables (low‑level)
 
 Create reactive structures outside Stores/Models. Supported: Objects, Arrays, Map, Set, WeakMap, WeakSet.
@@ -824,6 +886,31 @@ const off = onSnapshot(m, (snap) =>
 - 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.
 - 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/observables/internal/lookup.d.ts

@@ -10,5 +10,7 @@ export declare function getObservableClassInstance<T extends object>(value: T):
 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;

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

@@ -2,7 +2,7 @@ import type { AtomNode, ComputedNode, SignalNode } from "../preact";
 export declare function defaultEquals<T>(a: T, b: T): boolean;
 export declare function isNonPrimitive(val: unknown): val is object;
 export declare function isPropertyKey(val: unknown): val is string | number | symbol;
-export type PropertyType = "action" | "computed" | "observable";
+export type PropertyType = "action" | "computed" | "observable" | "observableShallow" | "observableSignal";
 export declare function getPropertyType(key: PropertyKey, obj: object): PropertyType | null;
 export declare function getPropertyDescriptor(obj: object, key: PropertyKey): PropertyDescriptor | undefined;
 export declare function isPlainObject(value: unknown): value is object;

package/dist/observables/preact.d.ts

@@ -56,8 +56,14 @@ export type PreactObservable<T> = T extends Function ? T : T extends Map<infer K
 } & {
     readonly [key in keyof T as T[key] extends object ? never : `$${string & key}`]?: Signal<T[key]>;
 };
-export declare function observable<T>(obj: T): PreactObservable<T>;
-export declare function observable(value: undefined, context: ClassFieldDecoratorContext): void;
+declare function observableImpl<T>(obj: T): PreactObservable<T>;
+declare function observableImpl(value: undefined, context: ClassFieldDecoratorContext): void;
+declare function shallowDecorator(value: any, context: ClassFieldDecoratorContext): any;
+declare function signalDecorator(value: any, context: ClassFieldDecoratorContext): any;
+export declare const observable: typeof observableImpl & {
+    shallow: typeof shallowDecorator;
+    signal: typeof signalDecorator;
+};
 export declare function computed<T>(value: () => T, context: ClassGetterDecoratorContext): void;
 export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
 export declare function source<T>(obj: PreactObservable<T> | T): T;

package/dist/r-state-tree.cjs

@@ -17,6 +17,8 @@ var CommonCfgTypes = /* @__PURE__ */ ((CommonCfgTypes2) => {
 })(CommonCfgTypes || {});
 var ModelCfgTypes = /* @__PURE__ */ ((ModelCfgTypes2) => {
   ModelCfgTypes2["state"] = "state";
+  ModelCfgTypes2["stateShallow"] = "stateShallow";
+  ModelCfgTypes2["stateSignal"] = "stateSignal";
   ModelCfgTypes2["id"] = "id";
   ModelCfgTypes2["modelRef"] = "modelRef";
   return ModelCfgTypes2;
@@ -27,6 +29,8 @@ var StoreCfgTypes = /* @__PURE__ */ ((StoreCfgTypes2) => {
 })(StoreCfgTypes || {});
 var ObservableCfgTypes = /* @__PURE__ */ ((ObservableCfgTypes2) => {
   ObservableCfgTypes2["observable"] = "observable";
+  ObservableCfgTypes2["observableShallow"] = "observableShallow";
+  ObservableCfgTypes2["observableSignal"] = "observableSignal";
   ObservableCfgTypes2["computed"] = "computed";
   return ObservableCfgTypes2;
 })(ObservableCfgTypes || {});
@@ -43,6 +47,14 @@ const stateType = {
   type: "state"
   /* state */
 };
+const stateShallowType = {
+  type: "stateShallow"
+  /* stateShallow */
+};
+const stateSignalType = {
+  type: "stateSignal"
+  /* stateSignal */
+};
 const modelRefType = Object.assign(
   function(childType2) {
     return { type: "modelRef", childType: childType2 };
@@ -85,6 +97,12 @@ function getPropertyType(key, obj) {
     switch (config.type) {
       case ObservableCfgTypes.computed:
         return "computed";
+      case ObservableCfgTypes.observableShallow:
+      case ModelCfgTypes.stateShallow:
+        return "observableShallow";
+      case ObservableCfgTypes.observableSignal:
+      case ModelCfgTypes.stateSignal:
+        return "observableSignal";
       case ModelCfgTypes.state:
       case ObservableCfgTypes.observable:
       case ModelCfgTypes.id:
@@ -353,6 +371,7 @@ class ObjectAdministration extends Administration {
     }
     switch (type) {
       case "observable":
+      case "observableShallow":
       case "action": {
         if (key in this.source) {
           this.valuesMap.reportObserved(key, this.source[key]);
@@ -364,8 +383,21 @@ class ObjectAdministration extends Administration {
         if (type === "observable") {
           return getObservable(this.get(key));
         }
+        if (type === "observableShallow") {
+          return getShallowObservable(this.get(key));
+        }
         return getAction(this.get(key));
       }
+      case "observableSignal": {
+        if (key in this.source) {
+          this.valuesMap.reportObserved(key, this.source[key]);
+        }
+        this.atom.reportObserved();
+        if (this.atom.observing) {
+          this.hasMap.reportObserved(key);
+        }
+        return this.get(key);
+      }
       case "computed": {
         return this.callComputed(key);
       }
@@ -573,13 +605,31 @@ function createComputed(fn, context = null) {
     }
   };
 }
-function observable(value, context) {
+function observableImpl(value, context) {
   if (context && typeof context === "object" && "kind" in context) {
     context.metadata[context.name] = { type: "observable" };
     return value;
   }
   return getObservable(value);
 }
+function shallowDecorator(value, context) {
+  if (context && typeof context === "object" && "kind" in context) {
+    context.metadata[context.name] = { type: "observableShallow" };
+    return value;
+  }
+  throw new Error("observable.shallow can only be used as a decorator");
+}
+function signalDecorator(value, context) {
+  if (context && typeof context === "object" && "kind" in context) {
+    context.metadata[context.name] = { type: "observableSignal" };
+    return value;
+  }
+  throw new Error("observable.signal can only be used as a decorator");
+}
+const observable = Object.assign(observableImpl, {
+  shallow: shallowDecorator,
+  signal: signalDecorator
+});
 function computed(value, context) {
   if (context && typeof context === "object" && "kind" in context) {
     context.metadata[context.name] = { type: "computed" };
@@ -791,6 +841,9 @@ class CollectionAdministration extends Administration {
     const value = sourceMap.get(targetKey) ?? sourceMap.get(key);
     if (has) {
       this.valuesMap.reportObserved(key, value);
+      if (isShallowObservable(this.proxy)) {
+        return value;
+      }
       return getObservable(value);
     }
     return void 0;
@@ -979,6 +1032,9 @@ class ArrayAdministration extends Administration {
   get(index) {
     this.atom.reportObserved();
     this.valuesMap.reportObserved(index, this.source[index]);
+    if (isShallowObservable(this.proxy)) {
+      return this.source[index];
+    }
     return getObservable(this.source[index]);
   }
   set(index, newValue) {
@@ -1244,6 +1300,39 @@ function getObservable(value) {
   }
   return value;
 }
+const shallowObservables = /* @__PURE__ */ new WeakSet();
+function isShallowObservable(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  return shallowObservables.has(obj);
+}
+function getShallowObservable(value) {
+  if (!value) {
+    return value;
+  }
+  const existingAdm = getAdministration(value);
+  if (existingAdm) {
+    return existingAdm.proxy;
+  }
+  if ((typeof value === "object" || typeof value === "function") && !Object.isFrozen(value)) {
+    const obj = value;
+    let Adm = null;
+    if (Array.isArray(obj)) {
+      Adm = ArrayAdministration;
+    } else if (obj instanceof Map || obj instanceof WeakMap) {
+      Adm = CollectionAdministration;
+    } else if (obj instanceof Set || obj instanceof WeakSet) {
+      Adm = CollectionAdministration;
+    }
+    if (Adm) {
+      const adm = new Adm(obj);
+      administrationMap.set(adm.proxy, adm);
+      administrationMap.set(adm.source, adm);
+      shallowObservables.add(adm.proxy);
+      return adm.proxy;
+    }
+  }
+  return value;
+}
 function isObservable(obj) {
   if (!obj || typeof obj !== "object") return false;
   const adm = getAdministration(obj);
@@ -1317,6 +1406,33 @@ function getDiff(o1, o2, getConfig) {
   }
   return Object.keys(diff).length > 0 ? diff : null;
 }
+const MAX_MOUNT_DEPTH = 100;
+const mountingStack = [];
+function formatMountFrame(frame) {
+  const childSegment = frame.childName === void 0 ? "" : `.${String(frame.childName)}`;
+  return `${frame.storeName}${childSegment}`;
+}
+function formatMountChain(frame) {
+  const chain = [...mountingStack, frame];
+  const maxParts = 6;
+  if (chain.length > maxParts) {
+    const start = chain.slice(0, 3);
+    const end = chain.slice(-2);
+    return [
+      ...start,
+      { storeName: "...", modelsKeys: [], childName: void 0 },
+      ...end
+    ].map(formatMountFrame).join(" -> ");
+  }
+  return chain.map(formatMountFrame).join(" -> ");
+}
+function createCircularMountError(frame) {
+  const chain = formatMountChain(frame);
+  const models = frame.modelsKeys.length === 0 ? "no models provided" : `models: ${frame.modelsKeys.join(", ")}`;
+  return new Error(
+    `r-state-tree: detected circular store/model creation while mounting ${chain} (using ${models}). Passing models into child stores during mount can create recursive wiring. Move child store/model creation into storeDidMount or break the cycle.`
+  );
+}
 function updateProps(props, newProps) {
   signalsCore.untracked(() => {
     signalsCore.batch(() => {
@@ -1336,6 +1452,35 @@ function updateProps(props, newProps) {
 function getStoreAdm(store) {
   return getAdministration(store);
 }
+function validateStoreChildValue(value, propertyName) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const invalidItem = value.find(
+      (item) => item !== null && (typeof item !== "object" || !("Type" in item) || !("props" in item) || typeof item.Type !== "function" || typeof item.props !== "object")
+    );
+    if (invalidItem !== void 0) {
+      throw new Error(
+        `r-state-tree: child property '${String(
+          propertyName
+        )}' must be a StoreElement ({ Type, props, key }), an array of StoreElements, or null/undefined. Found invalid array item: ${typeof invalidItem}`
+      );
+    }
+    return;
+  }
+  if (typeof value === "object" && value !== null && "Type" in value && "props" in value) {
+    const element = value;
+    if (typeof element.Type === "function" && typeof element.props === "object") {
+      return;
+    }
+  }
+  throw new Error(
+    `r-state-tree: child property '${String(
+      propertyName
+    )}' must be a StoreElement ({ Type, props, key }), an array of StoreElements, or null/undefined. Found: ${typeof value}`
+  );
+}
 class StoreAdministration extends PreactObjectAdministration {
   static proxyTraps = Object.assign(
     {},
@@ -1403,7 +1548,7 @@ class StoreAdministration extends PreactObjectAdministration {
         }
       });
       childStoreData.value.set(stores);
-      stores.forEach((s) => getStoreAdm(s).mount(this));
+      stores.forEach((s) => getStoreAdm(s).mount(this, name));
       return stores;
     }
     const newStores = /* @__PURE__ */ new Set();
@@ -1454,7 +1599,7 @@ class StoreAdministration extends PreactObjectAdministration {
       signalsCore.batch(() => childStoreData.value.set(stores));
     }
     removedStores.forEach((s) => getStoreAdm(s).unmount());
-    newStores.forEach((s) => getStoreAdm(s).mount(this));
+    newStores.forEach((s) => getStoreAdm(s).mount(this, name));
     return stores;
   }
   setSingleStore(name, element) {
@@ -1473,7 +1618,7 @@ class StoreAdministration extends PreactObjectAdministration {
       }
       const childStore = this.createChildStore(element);
       signalsCore.batch(() => childStoreData.value.set(childStore));
-      getStoreAdm(childStore).mount(this);
+      getStoreAdm(childStore).mount(this, name);
       return childStore;
     } else {
       signalsCore.batch(() => updateProps(oldStore.props, props));
@@ -1485,6 +1630,7 @@ class StoreAdministration extends PreactObjectAdministration {
     const storeElement = childStoreData.listener.track(
       () => childStoreData.computed.get()
     );
+    validateStoreChildValue(storeElement, name);
     Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
   }
   getComputedGetter(name) {
@@ -1505,6 +1651,7 @@ class StoreAdministration extends PreactObjectAdministration {
     const storeElement = childStoreData.listener.track(
       () => childStoreData.computed.get()
     );
+    validateStoreChildValue(storeElement, name);
     Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
     return childStoreData.value.get();
   }
@@ -1514,6 +1661,7 @@ class StoreAdministration extends PreactObjectAdministration {
       return this.initializeStore(name);
     } else {
       const storeElement = signalsCore.untracked(() => childStoreData.computed.get());
+      validateStoreChildValue(storeElement, name);
       Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
       return childStoreData.value.get();
     }
@@ -1562,18 +1710,36 @@ class StoreAdministration extends PreactObjectAdministration {
     this.reactionsUnsub.push(unsub);
     return unsub;
   }
-  mount(parent = null) {
-    this.parent = parent || null;
-    this.childStoreDataMap.forEach(({ value }) => {
-      const stores = value.get();
-      if (Array.isArray(stores)) {
-        stores?.forEach((s) => getStoreAdm(s)?.mount(this));
-      } else if (stores) {
-        getStoreAdm(stores)?.mount(this);
+  mount(parent = null, childName) {
+    const frame = {
+      storeName: this.proxy.constructor.name || "Store",
+      childName,
+      modelsKeys: Object.keys(this.proxy.props?.models ?? {})
+    };
+    if (mountingStack.length + 1 > MAX_MOUNT_DEPTH) {
+      throw createCircularMountError(frame);
+    }
+    mountingStack.push(frame);
+    try {
+      this.parent = parent || null;
+      this.childStoreDataMap.forEach(({ value }, name) => {
+        const stores = value.get();
+        if (Array.isArray(stores)) {
+          stores?.forEach((s) => getStoreAdm(s)?.mount(this, name));
+        } else if (stores) {
+          getStoreAdm(stores)?.mount(this, name);
+        }
+      });
+      this.mounted = true;
+      signalsCore.batch(() => this.proxy.storeDidMount?.());
+    } catch (error) {
+      if (error instanceof RangeError && /call stack/i.test(error.message)) {
+        throw createCircularMountError(frame);
       }
-    });
-    this.mounted = true;
-    signalsCore.batch(() => this.proxy.storeDidMount?.());
+      throw error;
+    } finally {
+      mountingStack.pop();
+    }
   }
   unmount() {
     this.proxy.storeWillUnmount?.();
@@ -1891,6 +2057,30 @@ function getSnapshotRefId(snapshot) {
   }
   return snapshot[keys[0]];
 }
+function validateModelChildValue(value, propertyName) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (value instanceof Model) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const invalidItem = value.find((item) => !(item instanceof Model));
+    if (invalidItem !== void 0) {
+      throw new Error(
+        `r-state-tree: child property '${String(
+          propertyName
+        )}' must be a Model instance, an array of Model instances, or null/undefined. Found invalid array item: ${typeof invalidItem}`
+      );
+    }
+    return;
+  }
+  throw new Error(
+    `r-state-tree: child property '${String(
+      propertyName
+    )}' must be a Model instance, an array of Model instances, or null/undefined. Found: ${typeof value}`
+  );
+}
 class ModelAdministration extends PreactObjectAdministration {
   static proxyTraps = Object.assign(
     {},
@@ -1924,6 +2114,7 @@ class ModelAdministration extends PreactObjectAdministration {
               return true;
             }
             case CommonCfgTypes.child: {
+              validateModelChildValue(value, name);
               if (Array.isArray(value)) {
                 adm.setModels(name, value);
                 return true;
@@ -1936,7 +2127,9 @@ class ModelAdministration extends PreactObjectAdministration {
               adm.setId(name, value);
               break;
             }
-            case ModelCfgTypes.state: {
+            case ModelCfgTypes.state:
+            case ModelCfgTypes.stateShallow:
+            case ModelCfgTypes.stateSignal: {
               adm.setState(name, value);
               break;
             }
@@ -2030,6 +2223,7 @@ class ModelAdministration extends PreactObjectAdministration {
     }
   }
   setModel(name, newModel) {
+    validateModelChildValue(newModel, name);
     const currentValue = this.proxy[name];
     if (currentValue === newModel) {
       return;
@@ -2049,6 +2243,7 @@ class ModelAdministration extends PreactObjectAdministration {
     }
   }
   setModels(name, newModelsSource) {
+    validateModelChildValue(newModelsSource, name);
     const newModels = createObservableWithCustomAdministration(
       [],
       ChildModelsAdministration
@@ -2204,6 +2399,8 @@ class ModelAdministration extends PreactObjectAdministration {
     return Object.keys(this.configuration).reduce((json, key) => {
       switch (this.configuration[key].type) {
         case ModelCfgTypes.state:
+        case ModelCfgTypes.stateShallow:
+        case ModelCfgTypes.stateSignal:
         case ModelCfgTypes.id:
           json[key] = clone(getSource(this.proxy[key]));
           break;
@@ -2269,6 +2466,8 @@ class ModelAdministration extends PreactObjectAdministration {
         const value = snapshot[key];
         switch (type) {
           case ModelCfgTypes.state:
+          case ModelCfgTypes.stateShallow:
+          case ModelCfgTypes.stateSignal:
             this.proxy[key] = value;
             break;
           case ModelCfgTypes.modelRef:
@@ -2484,7 +2683,10 @@ const child = makeChildDecorator(childType);
 const modelRef = makeChildDecorator(modelRefType);
 const model = makeDecorator(modelType);
 const id = makeDecorator(idType);
-const state = makeDecorator(stateType);
+const state = Object.assign(makeDecorator(stateType), {
+  shallow: makeDecorator(stateShallowType),
+  signal: makeDecorator(stateSignalType)
+});
 Object.defineProperty(exports, "Signal", {
   enumerable: true,
   get: () => signalsCore.Signal

package/dist/r-state-tree.js

@@ -16,6 +16,8 @@ var CommonCfgTypes = /* @__PURE__ */ ((CommonCfgTypes2) => {
 })(CommonCfgTypes || {});
 var ModelCfgTypes = /* @__PURE__ */ ((ModelCfgTypes2) => {
   ModelCfgTypes2["state"] = "state";
+  ModelCfgTypes2["stateShallow"] = "stateShallow";
+  ModelCfgTypes2["stateSignal"] = "stateSignal";
   ModelCfgTypes2["id"] = "id";
   ModelCfgTypes2["modelRef"] = "modelRef";
   return ModelCfgTypes2;
@@ -26,6 +28,8 @@ var StoreCfgTypes = /* @__PURE__ */ ((StoreCfgTypes2) => {
 })(StoreCfgTypes || {});
 var ObservableCfgTypes = /* @__PURE__ */ ((ObservableCfgTypes2) => {
   ObservableCfgTypes2["observable"] = "observable";
+  ObservableCfgTypes2["observableShallow"] = "observableShallow";
+  ObservableCfgTypes2["observableSignal"] = "observableSignal";
   ObservableCfgTypes2["computed"] = "computed";
   return ObservableCfgTypes2;
 })(ObservableCfgTypes || {});
@@ -42,6 +46,14 @@ const stateType = {
   type: "state"
   /* state */
 };
+const stateShallowType = {
+  type: "stateShallow"
+  /* stateShallow */
+};
+const stateSignalType = {
+  type: "stateSignal"
+  /* stateSignal */
+};
 const modelRefType = Object.assign(
   function(childType2) {
     return { type: "modelRef", childType: childType2 };
@@ -84,6 +96,12 @@ function getPropertyType(key, obj) {
     switch (config.type) {
       case ObservableCfgTypes.computed:
         return "computed";
+      case ObservableCfgTypes.observableShallow:
+      case ModelCfgTypes.stateShallow:
+        return "observableShallow";
+      case ObservableCfgTypes.observableSignal:
+      case ModelCfgTypes.stateSignal:
+        return "observableSignal";
       case ModelCfgTypes.state:
       case ObservableCfgTypes.observable:
       case ModelCfgTypes.id:
@@ -352,6 +370,7 @@ class ObjectAdministration extends Administration {
     }
     switch (type) {
       case "observable":
+      case "observableShallow":
       case "action": {
         if (key in this.source) {
           this.valuesMap.reportObserved(key, this.source[key]);
@@ -363,8 +382,21 @@ class ObjectAdministration extends Administration {
         if (type === "observable") {
           return getObservable(this.get(key));
         }
+        if (type === "observableShallow") {
+          return getShallowObservable(this.get(key));
+        }
         return getAction(this.get(key));
       }
+      case "observableSignal": {
+        if (key in this.source) {
+          this.valuesMap.reportObserved(key, this.source[key]);
+        }
+        this.atom.reportObserved();
+        if (this.atom.observing) {
+          this.hasMap.reportObserved(key);
+        }
+        return this.get(key);
+      }
       case "computed": {
         return this.callComputed(key);
       }
@@ -572,13 +604,31 @@ function createComputed(fn, context = null) {
     }
   };
 }
-function observable(value, context) {
+function observableImpl(value, context) {
   if (context && typeof context === "object" && "kind" in context) {
     context.metadata[context.name] = { type: "observable" };
     return value;
   }
   return getObservable(value);
 }
+function shallowDecorator(value, context) {
+  if (context && typeof context === "object" && "kind" in context) {
+    context.metadata[context.name] = { type: "observableShallow" };
+    return value;
+  }
+  throw new Error("observable.shallow can only be used as a decorator");
+}
+function signalDecorator(value, context) {
+  if (context && typeof context === "object" && "kind" in context) {
+    context.metadata[context.name] = { type: "observableSignal" };
+    return value;
+  }
+  throw new Error("observable.signal can only be used as a decorator");
+}
+const observable = Object.assign(observableImpl, {
+  shallow: shallowDecorator,
+  signal: signalDecorator
+});
 function computed(value, context) {
   if (context && typeof context === "object" && "kind" in context) {
     context.metadata[context.name] = { type: "computed" };
@@ -790,6 +840,9 @@ class CollectionAdministration extends Administration {
     const value = sourceMap.get(targetKey) ?? sourceMap.get(key);
     if (has) {
       this.valuesMap.reportObserved(key, value);
+      if (isShallowObservable(this.proxy)) {
+        return value;
+      }
       return getObservable(value);
     }
     return void 0;
@@ -978,6 +1031,9 @@ class ArrayAdministration extends Administration {
   get(index) {
     this.atom.reportObserved();
     this.valuesMap.reportObserved(index, this.source[index]);
+    if (isShallowObservable(this.proxy)) {
+      return this.source[index];
+    }
     return getObservable(this.source[index]);
   }
   set(index, newValue) {
@@ -1243,6 +1299,39 @@ function getObservable(value) {
   }
   return value;
 }
+const shallowObservables = /* @__PURE__ */ new WeakSet();
+function isShallowObservable(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  return shallowObservables.has(obj);
+}
+function getShallowObservable(value) {
+  if (!value) {
+    return value;
+  }
+  const existingAdm = getAdministration(value);
+  if (existingAdm) {
+    return existingAdm.proxy;
+  }
+  if ((typeof value === "object" || typeof value === "function") && !Object.isFrozen(value)) {
+    const obj = value;
+    let Adm = null;
+    if (Array.isArray(obj)) {
+      Adm = ArrayAdministration;
+    } else if (obj instanceof Map || obj instanceof WeakMap) {
+      Adm = CollectionAdministration;
+    } else if (obj instanceof Set || obj instanceof WeakSet) {
+      Adm = CollectionAdministration;
+    }
+    if (Adm) {
+      const adm = new Adm(obj);
+      administrationMap.set(adm.proxy, adm);
+      administrationMap.set(adm.source, adm);
+      shallowObservables.add(adm.proxy);
+      return adm.proxy;
+    }
+  }
+  return value;
+}
 function isObservable(obj) {
   if (!obj || typeof obj !== "object") return false;
   const adm = getAdministration(obj);
@@ -1316,6 +1405,33 @@ function getDiff(o1, o2, getConfig) {
   }
   return Object.keys(diff).length > 0 ? diff : null;
 }
+const MAX_MOUNT_DEPTH = 100;
+const mountingStack = [];
+function formatMountFrame(frame) {
+  const childSegment = frame.childName === void 0 ? "" : `.${String(frame.childName)}`;
+  return `${frame.storeName}${childSegment}`;
+}
+function formatMountChain(frame) {
+  const chain = [...mountingStack, frame];
+  const maxParts = 6;
+  if (chain.length > maxParts) {
+    const start = chain.slice(0, 3);
+    const end = chain.slice(-2);
+    return [
+      ...start,
+      { storeName: "...", modelsKeys: [], childName: void 0 },
+      ...end
+    ].map(formatMountFrame).join(" -> ");
+  }
+  return chain.map(formatMountFrame).join(" -> ");
+}
+function createCircularMountError(frame) {
+  const chain = formatMountChain(frame);
+  const models = frame.modelsKeys.length === 0 ? "no models provided" : `models: ${frame.modelsKeys.join(", ")}`;
+  return new Error(
+    `r-state-tree: detected circular store/model creation while mounting ${chain} (using ${models}). Passing models into child stores during mount can create recursive wiring. Move child store/model creation into storeDidMount or break the cycle.`
+  );
+}
 function updateProps(props, newProps) {
   untracked(() => {
     batch(() => {
@@ -1335,6 +1451,35 @@ function updateProps(props, newProps) {
 function getStoreAdm(store) {
   return getAdministration(store);
 }
+function validateStoreChildValue(value, propertyName) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const invalidItem = value.find(
+      (item) => item !== null && (typeof item !== "object" || !("Type" in item) || !("props" in item) || typeof item.Type !== "function" || typeof item.props !== "object")
+    );
+    if (invalidItem !== void 0) {
+      throw new Error(
+        `r-state-tree: child property '${String(
+          propertyName
+        )}' must be a StoreElement ({ Type, props, key }), an array of StoreElements, or null/undefined. Found invalid array item: ${typeof invalidItem}`
+      );
+    }
+    return;
+  }
+  if (typeof value === "object" && value !== null && "Type" in value && "props" in value) {
+    const element = value;
+    if (typeof element.Type === "function" && typeof element.props === "object") {
+      return;
+    }
+  }
+  throw new Error(
+    `r-state-tree: child property '${String(
+      propertyName
+    )}' must be a StoreElement ({ Type, props, key }), an array of StoreElements, or null/undefined. Found: ${typeof value}`
+  );
+}
 class StoreAdministration extends PreactObjectAdministration {
   static proxyTraps = Object.assign(
     {},
@@ -1402,7 +1547,7 @@ class StoreAdministration extends PreactObjectAdministration {
         }
       });
       childStoreData.value.set(stores);
-      stores.forEach((s) => getStoreAdm(s).mount(this));
+      stores.forEach((s) => getStoreAdm(s).mount(this, name));
       return stores;
     }
     const newStores = /* @__PURE__ */ new Set();
@@ -1453,7 +1598,7 @@ class StoreAdministration extends PreactObjectAdministration {
       batch(() => childStoreData.value.set(stores));
     }
     removedStores.forEach((s) => getStoreAdm(s).unmount());
-    newStores.forEach((s) => getStoreAdm(s).mount(this));
+    newStores.forEach((s) => getStoreAdm(s).mount(this, name));
     return stores;
   }
   setSingleStore(name, element) {
@@ -1472,7 +1617,7 @@ class StoreAdministration extends PreactObjectAdministration {
       }
       const childStore = this.createChildStore(element);
       batch(() => childStoreData.value.set(childStore));
-      getStoreAdm(childStore).mount(this);
+      getStoreAdm(childStore).mount(this, name);
       return childStore;
     } else {
       batch(() => updateProps(oldStore.props, props));
@@ -1484,6 +1629,7 @@ class StoreAdministration extends PreactObjectAdministration {
     const storeElement = childStoreData.listener.track(
       () => childStoreData.computed.get()
     );
+    validateStoreChildValue(storeElement, name);
     Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
   }
   getComputedGetter(name) {
@@ -1504,6 +1650,7 @@ class StoreAdministration extends PreactObjectAdministration {
     const storeElement = childStoreData.listener.track(
       () => childStoreData.computed.get()
     );
+    validateStoreChildValue(storeElement, name);
     Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
     return childStoreData.value.get();
   }
@@ -1513,6 +1660,7 @@ class StoreAdministration extends PreactObjectAdministration {
       return this.initializeStore(name);
     } else {
       const storeElement = untracked(() => childStoreData.computed.get());
+      validateStoreChildValue(storeElement, name);
       Array.isArray(storeElement) ? this.setStoreList(name, storeElement) : this.setSingleStore(name, storeElement);
       return childStoreData.value.get();
     }
@@ -1561,18 +1709,36 @@ class StoreAdministration extends PreactObjectAdministration {
     this.reactionsUnsub.push(unsub);
     return unsub;
   }
-  mount(parent = null) {
-    this.parent = parent || null;
-    this.childStoreDataMap.forEach(({ value }) => {
-      const stores = value.get();
-      if (Array.isArray(stores)) {
-        stores?.forEach((s) => getStoreAdm(s)?.mount(this));
-      } else if (stores) {
-        getStoreAdm(stores)?.mount(this);
+  mount(parent = null, childName) {
+    const frame = {
+      storeName: this.proxy.constructor.name || "Store",
+      childName,
+      modelsKeys: Object.keys(this.proxy.props?.models ?? {})
+    };
+    if (mountingStack.length + 1 > MAX_MOUNT_DEPTH) {
+      throw createCircularMountError(frame);
+    }
+    mountingStack.push(frame);
+    try {
+      this.parent = parent || null;
+      this.childStoreDataMap.forEach(({ value }, name) => {
+        const stores = value.get();
+        if (Array.isArray(stores)) {
+          stores?.forEach((s) => getStoreAdm(s)?.mount(this, name));
+        } else if (stores) {
+          getStoreAdm(stores)?.mount(this, name);
+        }
+      });
+      this.mounted = true;
+      batch(() => this.proxy.storeDidMount?.());
+    } catch (error) {
+      if (error instanceof RangeError && /call stack/i.test(error.message)) {
+        throw createCircularMountError(frame);
       }
-    });
-    this.mounted = true;
-    batch(() => this.proxy.storeDidMount?.());
+      throw error;
+    } finally {
+      mountingStack.pop();
+    }
   }
   unmount() {
     this.proxy.storeWillUnmount?.();
@@ -1890,6 +2056,30 @@ function getSnapshotRefId(snapshot) {
   }
   return snapshot[keys[0]];
 }
+function validateModelChildValue(value, propertyName) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (value instanceof Model) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const invalidItem = value.find((item) => !(item instanceof Model));
+    if (invalidItem !== void 0) {
+      throw new Error(
+        `r-state-tree: child property '${String(
+          propertyName
+        )}' must be a Model instance, an array of Model instances, or null/undefined. Found invalid array item: ${typeof invalidItem}`
+      );
+    }
+    return;
+  }
+  throw new Error(
+    `r-state-tree: child property '${String(
+      propertyName
+    )}' must be a Model instance, an array of Model instances, or null/undefined. Found: ${typeof value}`
+  );
+}
 class ModelAdministration extends PreactObjectAdministration {
   static proxyTraps = Object.assign(
     {},
@@ -1923,6 +2113,7 @@ class ModelAdministration extends PreactObjectAdministration {
               return true;
             }
             case CommonCfgTypes.child: {
+              validateModelChildValue(value, name);
               if (Array.isArray(value)) {
                 adm.setModels(name, value);
                 return true;
@@ -1935,7 +2126,9 @@ class ModelAdministration extends PreactObjectAdministration {
               adm.setId(name, value);
               break;
             }
-            case ModelCfgTypes.state: {
+            case ModelCfgTypes.state:
+            case ModelCfgTypes.stateShallow:
+            case ModelCfgTypes.stateSignal: {
               adm.setState(name, value);
               break;
             }
@@ -2029,6 +2222,7 @@ class ModelAdministration extends PreactObjectAdministration {
     }
   }
   setModel(name, newModel) {
+    validateModelChildValue(newModel, name);
     const currentValue = this.proxy[name];
     if (currentValue === newModel) {
       return;
@@ -2048,6 +2242,7 @@ class ModelAdministration extends PreactObjectAdministration {
     }
   }
   setModels(name, newModelsSource) {
+    validateModelChildValue(newModelsSource, name);
     const newModels = createObservableWithCustomAdministration(
       [],
       ChildModelsAdministration
@@ -2203,6 +2398,8 @@ class ModelAdministration extends PreactObjectAdministration {
     return Object.keys(this.configuration).reduce((json, key) => {
       switch (this.configuration[key].type) {
         case ModelCfgTypes.state:
+        case ModelCfgTypes.stateShallow:
+        case ModelCfgTypes.stateSignal:
         case ModelCfgTypes.id:
           json[key] = clone(getSource(this.proxy[key]));
           break;
@@ -2268,6 +2465,8 @@ class ModelAdministration extends PreactObjectAdministration {
         const value = snapshot[key];
         switch (type) {
           case ModelCfgTypes.state:
+          case ModelCfgTypes.stateShallow:
+          case ModelCfgTypes.stateSignal:
             this.proxy[key] = value;
             break;
           case ModelCfgTypes.modelRef:
@@ -2483,7 +2682,10 @@ const child = makeChildDecorator(childType);
 const modelRef = makeChildDecorator(modelRefType);
 const model = makeDecorator(modelType);
 const id = makeDecorator(idType);
-const state = makeDecorator(stateType);
+const state = Object.assign(makeDecorator(stateType), {
+  shallow: makeDecorator(stateShallowType),
+  signal: makeDecorator(stateSignalType)
+});
 export {
   Model,
   Observable,

package/dist/store/StoreAdministration.d.ts

@@ -25,6 +25,6 @@ export declare class StoreAdministration<StoreType extends Store = Store> extend
     getContextValue<T>(contextId: symbol, provideSymbol: symbol, defaultValue: T | undefined, hasDefault: boolean): T;
     private lookupContextValue;
     reaction<T>(track: () => T, callback: (a: T) => void): () => void;
-    mount(parent?: StoreAdministration | null): void;
+    mount(parent?: StoreAdministration | null, childName?: PropertyKey): void;
     unmount(): void;
 }

package/dist/types.d.ts

@@ -34,6 +34,8 @@ export declare enum CommonCfgTypes {
 }
 export declare enum ModelCfgTypes {
     state = "state",
+    stateShallow = "stateShallow",
+    stateSignal = "stateSignal",
     id = "id",
     modelRef = "modelRef"
 }
@@ -42,6 +44,8 @@ export declare enum StoreCfgTypes {
 }
 export declare enum ObservableCfgTypes {
     observable = "observable",
+    observableShallow = "observableShallow",
+    observableSignal = "observableSignal",
     computed = "computed"
 }
 export type ConfigurationTypes = CommonCfgTypes | ModelCfgTypes | StoreCfgTypes | ObservableCfgTypes;
@@ -70,11 +74,15 @@ export declare const childType: ((childType: Function) => ConfigurationType) & {
     type: CommonCfgTypes;
 };
 export declare const stateType: ConfigurationType;
+export declare const stateShallowType: ConfigurationType;
+export declare const stateSignalType: ConfigurationType;
 export declare const modelRefType: ((childType: Function) => ConfigurationType) & {
     type: ModelCfgTypes;
 };
 export declare const idType: ConfigurationType;
 export declare const modelType: ConfigurationType;
 export declare const observableType: ConfigurationType;
+export declare const observableShallowType: ConfigurationType;
+export declare const observableSignalType: ConfigurationType;
 export declare const computedType: ConfigurationType;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "r-state-tree",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "reactive state management library",
   "main": "dist/r-state-tree.cjs",
   "module": "dist/r-state-tree.js",