docs(website): update docs

Author: unadlib

README.md

@@ -610,6 +610,10 @@ Yes. Unless you have to be compatible with Internet Explorer, Mutative supports
 
 Yes. Mutative supports return values for reducer, and `redux-toolkit` is considering support for [configurable `produce()`](https://github.com/reduxjs/redux-toolkit/pull/3074).
 
+- Does Mutative support shared references?
+
+Yes, Mutative supports shared references, but **each path to a shared object gets its own independent draft**. Modifications to one path do not automatically reflect in others. If you want to preserve shared references in the result, you must explicitly assign them (e.g., `draft.b = draft.a`). [Read more details](https://mutative.js.org/docs/extra-topics/shared-references).
+
 ## Migration from Immer to Mutative
 
 > [mutative-compat](https://github.com/exuanbo/mutative-compat) - Mutative wrapper with full Immer API compatibility, you can use it to quickly migrate from Immer to Mutative.

website/docs/extra-topics/faq.md

@@ -21,3 +21,7 @@ Yes. Unless you have to be compatible with Internet Explorer, Mutative supports
 - Can Mutative be integrated with Redux?
 
 Yes. Mutative supports return values for reducer, and `redux-toolkit` is considering support for [configurable `produce()`](https://github.com/reduxjs/redux-toolkit/pull/3074).
+
+- Does Mutative support shared references?
+
+Yes, Mutative supports shared references, but **each path to a shared object gets its own independent draft**. Modifications to one path do not automatically reflect in others. If you want to preserve shared references in the result, you must explicitly assign them (e.g., `draft.b = draft.a`). [Read more details](./shared-references.md).

website/docs/extra-topics/shared-references.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 4
+title: Shared References
+---
+
+# Shared References Behavior
+
+Mutative supports non-unidirectional trees (DAGs with shared nodes) where there is more than one path from the root to the same node, **as long as there are no cycles**. However, there is an important behavior to understand regarding how drafts handle these shared references.
+
+## Independent Drafts for Multiple Paths
+
+When the same object is referenced from multiple paths in the base state, Mutative creates **independent drafts for each path**. This means modifications to one path will **not** automatically reflect in the other paths.
+
+```javascript
+import { create } from 'mutative';
+
+const obj = {};
+// Same object referenced by two keys
+obj.color1 = obj.color2 = { name: 'Red' };
+
+const result = create(obj, (draft) => {
+  // ⚠️ Different drafts created for each path!
+  console.log(draft.color1 === draft.color2); // false
+
+  draft.color1.name = 'Blue';
+  
+  // color2 remains unchanged because it has a separate draft
+  console.log(draft.color2.name); // 'Red'
+});
+
+console.log(result.color1 === result.color2); // false
+// Result: { color1: { name: 'Blue' }, color2: { name: 'Red' } }
+```
+
+This behavior is **by design** and matches Immer's behavior. Each path through the state tree gets its own independent draft proxy.
+
+## Creating Shared References
+
+If you need to **preserve or create shared references** in the result state, you must do so explicitly within your recipe function by assigning one draft to another.
+
+```javascript
+const result = create(obj, (draft) => {
+  draft.color1.name = 'Blue';
+  
+  // ✅ Explicitly share the reference
+  draft.color2 = draft.color1;
+});
+
+// Now they share the same reference in the result
+console.log(result.color1 === result.color2); // true
+// Result: { color1: { name: 'Blue' }, color2: { name: 'Blue' } }
+```
+
+## Summary
+
+| Scenario | Behavior |
+|----------|----------|
+| **Shared nodes in base state** | Each path gets its own **independent draft**. Mutations through one path do **not** reflect in other paths. |
+| **Manually assigned references** | ✅ **Supported**. Assigning `draft.x = draft.y` creates shared references in the final state. |
+| **Real cycles** | ❌ **Not supported**. Cycles are actively detected in development mode when auto-freeze is enabled. |