From d3008e75e924cdf156c4dd628f2888522cc376df Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 09:21:06 -0400
Subject: [PATCH 1/8] feat: make deriveds writable

---
 .changeset/clever-terms-tell.md               |  5 ++
 documentation/docs/02-runes/03-$derived.md    |  4 ++
 .../phases/2-analyze/visitors/shared/utils.js | 31 +------------
 .../runes-no-derived-assignment/_config.js    |  8 ----
 .../runes-no-derived-assignment/main.svelte   |  5 --
 .../runes-no-derived-binding/_config.js       |  8 ----
 .../runes-no-derived-binding/main.svelte      |  6 ---
 .../_config.js                                |  8 ----
 .../main.svelte                               | 10 ----
 .../_config.js                                |  8 ----
 .../main.svelte                               | 10 ----
 .../runes-no-derived-update/_config.js        |  8 ----
 .../runes-no-derived-update/main.svelte       |  5 --
 .../samples/writable-derived/_config.js       | 46 +++++++++++++++++++
 .../samples/writable-derived/main.svelte      |  9 ++++
 .../reassign-derived-literal/errors.json      | 14 ------
 .../reassign-derived-literal/input.svelte     |  9 ----
 .../errors.json                               | 14 ------
 .../input.svelte                              |  9 ----
 .../reassign-derived-public-field/errors.json | 14 ------
 .../input.svelte                              |  9 ----
 21 files changed, 65 insertions(+), 175 deletions(-)
 create mode 100644 .changeset/clever-terms-tell.md
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte
 create mode 100644 packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js
 create mode 100644 packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte

diff --git a/.changeset/clever-terms-tell.md b/.changeset/clever-terms-tell.md
new file mode 100644
index 000000000000..606868bce39c
--- /dev/null
+++ b/.changeset/clever-terms-tell.md
@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: make deriveds writable
diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index 24ab643b68f6..ab9234c9327a 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -52,6 +52,10 @@ Anything read synchronously inside the `$derived` expression (or `$derived.by` f
 
 To exempt a piece of state from being treated as a dependency, use [`untrack`](svelte#untrack).
 
+## Overriding derived values
+
+Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them. This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user.
+
 ## Update propagation
 
 Svelte uses something called _push-pull reactivity_ — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull').
diff --git a/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js b/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js
index 04f4347a40bb..d6c74eddb6f0 100644
--- a/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js
+++ b/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js
@@ -21,10 +21,6 @@ export function validate_assignment(node, argument, state) {
 		const binding = state.scope.get(argument.name);
 
 		if (state.analysis.runes) {
-			if (binding?.kind === 'derived') {
-				e.constant_assignment(node, 'derived state');
-			}
-
 			if (binding?.node === state.analysis.props_id) {
 				e.constant_assignment(node, '$props.id()');
 			}
@@ -38,25 +34,6 @@ export function validate_assignment(node, argument, state) {
 			e.snippet_parameter_assignment(node);
 		}
 	}
-	if (
-		argument.type === 'MemberExpression' &&
-		argument.object.type === 'ThisExpression' &&
-		(((argument.property.type === 'PrivateIdentifier' || argument.property.type === 'Identifier') &&
-			state.derived_state.some(
-				(derived) =>
-					derived.name === /** @type {PrivateIdentifier | Identifier} */ (argument.property).name &&
-					derived.private === (argument.property.type === 'PrivateIdentifier')
-			)) ||
-			(argument.property.type === 'Literal' &&
-				argument.property.value &&
-				typeof argument.property.value === 'string' &&
-				state.derived_state.some(
-					(derived) =>
-						derived.name === /** @type {Literal} */ (argument.property).value && !derived.private
-				)))
-	) {
-		e.constant_assignment(node, 'derived state');
-	}
 }
 
 /**
@@ -81,7 +58,6 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 	} else if (argument.type === 'Identifier') {
 		const binding = scope.get(argument.name);
 		if (
-			binding?.kind === 'derived' ||
 			binding?.declaration_kind === 'import' ||
 			(binding?.declaration_kind === 'const' && binding.kind !== 'each')
 		) {
@@ -96,12 +72,7 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 			// );
 
 			// TODO have a more specific error message for assignments to things like `{:then foo}`
-			const thing =
-				binding.declaration_kind === 'import'
-					? 'import'
-					: binding.kind === 'derived'
-						? 'derived state'
-						: 'constant';
+			const thing = binding.declaration_kind === 'import' ? 'import' : 'constant';
 
 			if (is_binding) {
 				e.constant_binding(node, thing);
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js
deleted file mode 100644
index 94985a99397a..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte
deleted file mode 100644
index 3bf836f6c586..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte
+++ /dev/null
@@ -1,5 +0,0 @@
-<script>
-	const a = $state(0);
-	let b = $derived(a);
-	b = 1;
-</script>
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js
deleted file mode 100644
index 87b88d79cc26..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_binding',
-		message: 'Cannot bind to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte
deleted file mode 100644
index 6c198dc068fe..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte
+++ /dev/null
@@ -1,6 +0,0 @@
-<script>
-	let a = $state(0);
-	let b = $derived({ a });
-</script>
-
-<input type="number" bind:value={b} />
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js
deleted file mode 100644
index 94985a99397a..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte
deleted file mode 100644
index d44806757e6c..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte
+++ /dev/null
@@ -1,10 +0,0 @@
-<script>
-	class Counter {
-		count = $state();
-		#doubled = $derived(this.count * 2);
-
-		nope() {
-			this.#doubled += 1;
-		}
-	}
-</script>
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js
deleted file mode 100644
index 94985a99397a..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte
deleted file mode 100644
index e4ee2e86356d..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte
+++ /dev/null
@@ -1,10 +0,0 @@
-<script>
-	class Counter {
-		count = $state();
-		#doubled = $derived(this.count * 2);
-
-		nope() {
-			this.#doubled++;
-		}
-	}
-</script>
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js
deleted file mode 100644
index 94985a99397a..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte
deleted file mode 100644
index d266c95bb872..000000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte
+++ /dev/null
@@ -1,5 +0,0 @@
-<script>
-	const a = $state(0);
-	let b = $derived(a);
-	b++;
-</script>
diff --git a/packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js b/packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js
new file mode 100644
index 000000000000..b48ccbdfd004
--- /dev/null
+++ b/packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js
@@ -0,0 +1,46 @@
+import { flushSync } from 'svelte';
+import { test } from '../../test';
+
+export default test({
+	html: `
+		<input type="range"><input type="range"><p>0 * 2 = 0</p>
+	`,
+
+	ssrHtml: `
+		<input type="range" value="0"><input type="range" value="0"><p>0 * 2 = 0</p>
+	`,
+
+	test({ assert, target, window }) {
+		const [input1, input2] = target.querySelectorAll('input');
+
+		flushSync(() => {
+			input1.value = '10';
+			input1.dispatchEvent(new window.Event('input', { bubbles: true }));
+		});
+
+		assert.htmlEqual(
+			target.innerHTML,
+			`<input type="range"><input type="range"><p>10 * 2 = 20</p>`
+		);
+
+		flushSync(() => {
+			input2.value = '99';
+			input2.dispatchEvent(new window.Event('input', { bubbles: true }));
+		});
+
+		assert.htmlEqual(
+			target.innerHTML,
+			`<input type="range"><input type="range"><p>10 * 2 = 99</p>`
+		);
+
+		flushSync(() => {
+			input1.value = '20';
+			input1.dispatchEvent(new window.Event('input', { bubbles: true }));
+		});
+
+		assert.htmlEqual(
+			target.innerHTML,
+			`<input type="range"><input type="range"><p>20 * 2 = 40</p>`
+		);
+	}
+});
diff --git a/packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte b/packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte
new file mode 100644
index 000000000000..ab1dde0b9bba
--- /dev/null
+++ b/packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte
@@ -0,0 +1,9 @@
+<script>
+	let count = $state(0);
+	let double = $derived(count * 2);
+</script>
+
+<input type="range" bind:value={count} />
+<input type="range" bind:value={double} />
+
+<p>{count} * 2 = {double}</p>
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json b/packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json
deleted file mode 100644
index 8681d84ab227..000000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-	{
-		"code": "constant_assignment",
-		"message": "Cannot assign to derived state",
-		"start": {
-			"column": 3,
-			"line": 6
-		},
-		"end": {
-			"column": 29,
-			"line": 6
-		}
-	}
-]
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte b/packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte
deleted file mode 100644
index 8f109c9e1fe8..000000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte
+++ /dev/null
@@ -1,9 +0,0 @@
-<script>
-	class Test{
-		der = $derived({ test: 0 });
-
-		set test(v){
-			this["der"] = { test: 45 };
-		}
-	}
-</script>
\ No newline at end of file
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json b/packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json
deleted file mode 100644
index c211aa460895..000000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-	{
-		"code": "constant_assignment",
-		"message": "Cannot assign to derived state",
-		"start": {
-			"column": 3,
-			"line": 6
-		},
-		"end": {
-			"column": 27,
-			"line": 6
-		}
-	}
-]
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte b/packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte
deleted file mode 100644
index 62e2317e033f..000000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte
+++ /dev/null
@@ -1,9 +0,0 @@
-<script>
-	class Test{
-		#der = $derived({ test: 0 });
-
-		set test(v){
-			this.#der = { test: 45 };
-		}
-	}
-</script>
\ No newline at end of file
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json b/packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json
deleted file mode 100644
index 98837589ac80..000000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-	{
-		"code": "constant_assignment",
-		"message": "Cannot assign to derived state",
-		"start": {
-			"column": 3,
-			"line": 6
-		},
-		"end": {
-			"column": 26,
-			"line": 6
-		}
-	}
-]
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte b/packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte
deleted file mode 100644
index e2c4693e86b7..000000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte
+++ /dev/null
@@ -1,9 +0,0 @@
-<script>
-	class Test{
-		der = $derived({ test: 0 });
-
-		set test(v){
-			this.der = { test: 45 };
-		}
-	}
-</script>
\ No newline at end of file

From 374729a420cf1e368dd8c7241a77a6588c40789c Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 10:05:48 -0400
Subject: [PATCH 2/8] add optimistic UI example

---
 documentation/docs/02-runes/03-$derived.md | 27 +++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index ab9234c9327a..f69e1705d7e1 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -54,7 +54,32 @@ To exempt a piece of state from being treated as a dependency, use [`untrack`](s
 
 ## Overriding derived values
 
-Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them. This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user.
+Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them. This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user:
+
+```svelte
+<script>
+	let { post, like } = $props();
+
+	let likes = $derived(post.likes);
+</script>
+
+<button
+	onclick={() => {
+		// increment the `likes` count immediately...
+		likes += 1;
+
+		// and tell the server, which will eventually update `post`
+		try {
+			await like();
+		} catch {
+			// failed! roll back the change
+			likes -= 1;
+		}
+	}}
+>
+	🧡 {likes}
+</button>
+```
 
 ## Update propagation
 

From 9f5df6fa47e09180d3a2bc8814c990c5db3b3289 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 10:11:45 -0400
Subject: [PATCH 3/8] add note to when-not-to-use-effect

---
 documentation/docs/02-runes/03-$derived.md | 2 ++
 documentation/docs/02-runes/04-$effect.md  | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index f69e1705d7e1..d09f37be203a 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -81,6 +81,8 @@ Derived expressions are recalculated when their dependencies change, but you can
 </button>
 ```
 
+> [!NOTE] Prior to Svelte 5.25, deriveds were read-only.
+
 ## Update propagation
 
 Svelte uses something called _push-pull reactivity_ — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull').
diff --git a/documentation/docs/02-runes/04-$effect.md b/documentation/docs/02-runes/04-$effect.md
index 6a2b565aeaa2..3ce1f7f63a54 100644
--- a/documentation/docs/02-runes/04-$effect.md
+++ b/documentation/docs/02-runes/04-$effect.md
@@ -252,6 +252,8 @@ In general, `$effect` is best considered something of an escape hatch — useful
 
 > [!NOTE] For things that are more complicated than a simple expression like `count * 2`, you can also use `$derived.by`.
 
+If you're using an effect because you want to be able to reassign the derived value (to build an optimistic UI, for example) note that [deriveds can be directly overridden]($derived#Overriding-derived-values) as of Svelte 5.25.
+
 You might be tempted to do something convoluted with effects to link one value to another. The following example shows two inputs for "money spent" and "money left" that are connected to each other. If you update one, the other should update accordingly. Don't use effects for this ([demo](/playground/untitled#H4sIAAAAAAAACpVRy26DMBD8FcvKgUhtoIdeHBwp31F6MGSJkBbHwksEQvx77aWQqooq9bgzOzP7mGTdIHipPiZJowOpGJAv0po2VmfnDv4OSBErjYdneHWzBJaCjcx91TWOToUtCIEE3cig0OIty44r5l1oDtjOkyFIsv3GINQ_CNYyGegd1DVUlCR7oU9iilDUcP8S8roYs9n8p2wdYNVFm4csTx872BxNCcjr5I11fdgonEkXsjP2CoUUZWMv6m6wBz2x7yxaM-iJvWeRsvSbSVeUy5i0uf8vKA78NIeJLSZWv1I8jQjLdyK4XuTSeIdmVKJGGI4LdjVOiezwDu1yG74My8PLCQaSiroe5s_5C2PHrkVGAgAA)):
 
 ```svelte

From 43376e74a00f9ef5e7cdf8ca9348fc8470799c60 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 11:18:15 -0400
Subject: [PATCH 4/8] add section on deep reactivity

---
 documentation/docs/02-runes/03-$derived.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index d09f37be203a..7b0967c199be 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -83,6 +83,19 @@ Derived expressions are recalculated when their dependencies change, but you can
 
 > [!NOTE] Prior to Svelte 5.25, deriveds were read-only.
 
+## Deriveds and reactivity
+
+Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](https://svelte.dev/playground/b0d5cb9ecb6c463fafb8976e06c9335f)...
+
+```svelte
+let items = $state([...]);
+
+let index = $state(0);
+let selected = $derived(items[index]);
+```
+
+...you can change (or `bind:` to) properties of `selected` and it will affect the underlying `items` array. If `items` was _not_ deeply reactive, mutating `selected` would have no effect.
+
 ## Update propagation
 
 Svelte uses something called _push-pull reactivity_ — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull').

From dccc34da62e2d81d1d2dd4adee347f9bd2311374 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 11:23:15 -0400
Subject: [PATCH 5/8] root-relative URL

---
 documentation/docs/02-runes/03-$derived.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index 7b0967c199be..0f0e681a5091 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -85,7 +85,7 @@ Derived expressions are recalculated when their dependencies change, but you can
 
 ## Deriveds and reactivity
 
-Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](https://svelte.dev/playground/b0d5cb9ecb6c463fafb8976e06c9335f)...
+Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](/playground/b0d5cb9ecb6c463fafb8976e06c9335f)...
 
 ```svelte
 let items = $state([...]);

From ea6b1e364ed0ad4283486df9f5274ff2ef54ac41 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 11:39:11 -0400
Subject: [PATCH 6/8] use hash URL

---
 documentation/docs/02-runes/03-$derived.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index 0f0e681a5091..bc749c00ed54 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -85,7 +85,7 @@ Derived expressions are recalculated when their dependencies change, but you can
 
 ## Deriveds and reactivity
 
-Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](/playground/b0d5cb9ecb6c463fafb8976e06c9335f)...
+Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](/playground/untitled#H4sIAAAAAAAAE4VU22rjMBD9lUHd3aaQi9PdstS1A3t5XvpQ2Ic4D7I1iUUV2UjjNMX431eS7TRdSosxgjMzZ45mjt0yzffIYibvy0ojFJWqDKCQVBk2ZVup0LJ43TJ6rn2aBxw-FP2o67k9oCKP5dziW3hRaUJNjoYltjCyplWmM1JIIAn3FlL4ZIkTTtYez6jtj4w8WwyXv9GiIXiQxLVs9pfTMR7EuoSLIuLFbX7Z4930bZo_nBrD1bs834tlfvsBz9_SyX6PZXu9XaL4gOWn4sXjeyzftv4ZWfyxubpzxzg6LfD4MrooxELEosKCUPigQCMPKCZh0OtQE1iSxcsmdHuBvCiHZXALLXiN08EL3RRkaJ_kDVGle0HcSD5TPEeVtj67O4Nrg9aiSNtBY5oODJkrL5QsHtN2cgXp6nSJMWzpWWGasdlsGEMbzi5jPr5KFr0Ep7pdeM2-TCelCddIhDxAobi1jqF3cMaC1RKp64bAW9iFAmXGIHfd4wNXDabtOLN53w8W53VvJoZLh7xk4Rr3CoL-UNoLhWHrT1JQGcM17u96oES5K-kc2XOzkzqGCKL5De79OUTyyrg1zgwXsrEx3ESfx4Bz0M5UjVMHB24mw9SuXtXFoN13fYKOM1tyUT3FbvbWmSWCZX2Er-41u5xPoml45svRahl9Wb9aasbINJixDZwcPTbyTLZSUsAvrg_cPuCR7s782_WU8343Y72Qtlb8OYatwuOQvuN13M_hJKNfxann1v1U_B1KZ_D_mzhzhz24fw85CSz2irtN9w9HshBK7AQAAA==)...
 
 ```svelte
 let items = $state([...]);

From 64e33e8ffaca960824d173ce1d7b5de799d47d7d Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 11:39:51 -0400
Subject: [PATCH 7/8] mention const

---
 documentation/docs/02-runes/03-$derived.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index bc749c00ed54..430c87489bb8 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -54,7 +54,7 @@ To exempt a piece of state from being treated as a dependency, use [`untrack`](s
 
 ## Overriding derived values
 
-Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them. This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user:
+Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them (unless they are declared with `const`). This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user:
 
 ```svelte
 <script>

From b5fed42a3aeb297bd82c48b6e1b70cd0fbc74256 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 11:41:42 -0400
Subject: [PATCH 8/8] make handler async, move into script block

---
 documentation/docs/02-runes/03-$derived.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index 430c87489bb8..2464aa929550 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -61,10 +61,8 @@ Derived expressions are recalculated when their dependencies change, but you can
 	let { post, like } = $props();
 
 	let likes = $derived(post.likes);
-</script>
 
-<button
-	onclick={() => {
+	async function onclick() {
 		// increment the `likes` count immediately...
 		likes += 1;
 
@@ -75,10 +73,10 @@ Derived expressions are recalculated when their dependencies change, but you can
 			// failed! roll back the change
 			likes -= 1;
 		}
-	}}
->
-	🧡 {likes}
-</button>
+	}
+</script>
+
+<button {onclick}>🧡 {likes}</button>
 ```
 
 > [!NOTE] Prior to Svelte 5.25, deriveds were read-only.