From 0a23e85b337dfea7779d6db9878a450f4d9debf8 Mon Sep 17 00:00:00 2001
From: Dominic Gannaway <dg@domgan.com>
Date: Tue, 23 Jul 2024 12:26:00 +0100
Subject: [PATCH] feedback

---
 documentation/docs/03-runes/01-state.md       | 27 +++++++++++++++++++
 .../routes/docs/content/01-api/02-runes.md    |  2 ++
 2 files changed, 29 insertions(+)

diff --git a/documentation/docs/03-runes/01-state.md b/documentation/docs/03-runes/01-state.md
index c8b6b4d204..66a2a417fb 100644
--- a/documentation/docs/03-runes/01-state.md
+++ b/documentation/docs/03-runes/01-state.md
@@ -68,6 +68,32 @@ Objects and arrays are made deeply reactive by wrapping them with [`Proxies`](ht
 
 > Only POJOs (plain old JavaScript objects) are made deeply reactive. Reactivity will stop at class boundaries and leave those alone
 
+## `$state.link`
+
+State declared with `$state.link` behaves like `$state`, with the key difference being that rather than take an initial value, the value passed into `$state.link` maintains and persistant one-way link. Updating the `$state.link` directly will temporarily override the value until the linked state next updates.
+
+```svelte
+<script>
+	let { parent_value = $bindable() } = $props();
+
+	// `child_value` is linked to `parent_value`
+	let child_value = $state.link(parent_value);
+
+	parent_value = 10;
+
+	console.log(child_value); // 10
+
+	child_value = 20;
+
+	console.log(child_value); // 20
+
+	// `parent_value` remains the same
+	console.log(parent_value); // 10
+</script>
+```
+
+> The linked value will be proxied like `$state`, use `$state.snapshot` to clone the object if you want to avoid mutating the linked value directly.
+
 ## `$state.frozen`
 
 State declared with `$state.frozen` cannot be mutated; it can only be _reassigned_. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it:
@@ -94,6 +120,7 @@ In development mode, the argument to `$state.frozen` will be shallowly frozen wi
 
 > Objects and arrays passed to `$state.frozen` will have a `Symbol` property added to them to signal to Svelte that they are frozen. If you don't want this, pass in a clone of the object or array instead. The argument cannot be an existing state proxy created with `$state(...)`.
 
+
 ## `$state.snapshot`
 
 To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`:
diff --git a/sites/svelte-5-preview/src/routes/docs/content/01-api/02-runes.md b/sites/svelte-5-preview/src/routes/docs/content/01-api/02-runes.md
index 865e5f0cfb..0009576560 100644
--- a/sites/svelte-5-preview/src/routes/docs/content/01-api/02-runes.md
+++ b/sites/svelte-5-preview/src/routes/docs/content/01-api/02-runes.md
@@ -88,6 +88,8 @@ State declared with `$state.link` behaves like `$state`, with the key difference
 </script>
 ```
 
+> The linked value will be proxied like `$state`, use `$state.snapshot` to clone the object if you want to avoid mutating the linked value directly.
+
 ## `$state.frozen`
 
 State declared with `$state.frozen` cannot be mutated; it can only be _reassigned_. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it: