fix: detect and error on non-idempotent each block keys in dev mode (#17732)

## Summary

Fixes #17721

In dev mode, detect when a keyed each block has a key function that
returns different values when called multiple times for the same item
(non-idempotent). This catches the common mistake of using array
literals like `[thing.group, thing.id]` as keys, which creates a new
array object each time and will never match by reference.

- Adds new `each_key_volatile` error with helpful message explaining the
issue
- Checks key idempotency in the each block loop during dev mode
- Provides a clear error instead of the cryptic "Cannot read properties
of undefined" that occurred previously

---------

Co-authored-by: 7nik <kifiranet@gmail.com>

.changeset/volatile-each-key.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+fix: detect and error on non-idempotent each block keys in dev mode

documentation/docs/98-reference/.generated/client-errors.md

@@ -62,6 +62,14 @@ Keyed each block has duplicate key at indexes %a% and %b%
 Keyed each block has duplicate key `%value%` at indexes %a% and %b%
 ```
 
+### each_key_volatile
+
+```
+Keyed each block has key that is not idempotent — the key for item at index %index% was `%a%` but is now `%b%`. Keys must be the same each time for a given item
+```
+
+The key expression in a keyed each block must return the same value when called multiple times for the same item. Using expressions like `[item.a, item.b]` creates a new array each time, which will never be equal to itself. Instead, use a primitive value or create a stable key like `item.a + '-' + item.b`.
+
 ### effect_in_teardown
 
 ```

packages/svelte/messages/client-errors/errors.md

@@ -42,6 +42,12 @@ See the [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-long
 
 > Keyed each block has duplicate key `%value%` at indexes %a% and %b%
 
+## each_key_volatile
+
+> Keyed each block has key that is not idempotent — the key for item at index %index% was `%a%` but is now `%b%`. Keys must be the same each time for a given item
+
+The key expression in a keyed each block must return the same value when called multiple times for the same item. Using expressions like `[item.a, item.b]` creates a new array each time, which will never be equal to itself. Instead, use a primitive value or create a stable key like `item.a + '-' + item.b`.
+
 ## effect_in_teardown
 
 > `%rune%` cannot be used inside an effect cleanup function

packages/svelte/src/internal/client/dom/blocks/each.js

@@ -250,6 +250,14 @@ export function each(node, flags, get_collection, get_key, render_fn, fallback_f
 			var value = array[index];
 			var key = get_key(value, index);
 
+			if (DEV) {
+				// Check that the key function is idempotent (returns the same value when called twice)
+				var key_again = get_key(value, index);
+				if (key !== key_again) {
+					e.each_key_volatile(String(index), String(key), String(key_again));
+				}
+			}
+
 			var item = first_run ? null : items.get(key);
 
 			if (item) {

packages/svelte/src/internal/client/errors.js

@@ -147,6 +147,25 @@ export function each_key_duplicate(a, b, value) {
 	}
 }
 
+/**
+ * Keyed each block has key that is not idempotent — the key for item at index %index% was `%a%` but is now `%b%`. Keys must be the same each time for a given item
+ * @param {string} index
+ * @param {string} a
+ * @param {string} b
+ * @returns {never}
+ */
+export function each_key_volatile(index, a, b) {
+	if (DEV) {
+		const error = new Error(`each_key_volatile\nKeyed each block has key that is not idempotent — the key for item at index ${index} was \`${a}\` but is now \`${b}\`. Keys must be the same each time for a given item\nhttps://svelte.dev/e/each_key_volatile`);
+
+		error.name = 'Svelte error';
+
+		throw error;
+	} else {
+		throw new Error(`https://svelte.dev/e/each_key_volatile`);
+	}
+}
+
 /**
  * `%rune%` cannot be used inside an effect cleanup function
  * @param {string} rune

packages/svelte/tests/runtime-runes/samples/each-key-volatile/_config.js

@@ -0,0 +1,11 @@
+import { test } from '../../test';
+
+export default test({
+	compileOptions: {
+		dev: true
+	},
+
+	mode: ['client'],
+
+	error: 'each_key_volatile'
+});

packages/svelte/tests/runtime-runes/samples/each-key-volatile/main.svelte

@@ -0,0 +1,10 @@
+<script>
+	let things = $state([
+		{ group: 'a', id: 1 },
+		{ group: 'b', id: 2 }
+	]);
+</script>
+
+{#each things as thing ([thing.group, thing.id])}
+	<p>{thing.group}-{thing.id}</p>
+{/each}