Merge branch 'main' into $state-invalidate

Author: Ocean-OS

.github/workflows/ci.yml

@@ -28,6 +28,8 @@ jobs:
             os: ubuntu-latest
           - node-version: 22
             os: ubuntu-latest
+          - node-version: 24
+            os: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4

documentation/docs/02-runes/02-$state.md

@@ -20,9 +20,7 @@ Unlike other frameworks you may have encountered, there is no API for interactin
 
 If `$state` is used with an array or a simple object, the result is a deeply reactive _state proxy_. [Proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) allow Svelte to run code when you read or write properties, including via methods like `array.push(...)`, triggering granular updates.
 
-> [!NOTE] Class instances are not proxied. You can create [reactive state fields](#Classes) on classes that you define. Svelte provides reactive implementations of built-ins like `Set` and `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).
-
-State is proxified recursively until Svelte finds something other than an array or simple object. In a case like this...
+State is proxified recursively until Svelte finds something other than an array or simple object (like a class or an object created with `Object.create`). In a case like this...
 
 ```js
 let todos = $state([
@@ -67,16 +65,15 @@ todos[0].done = !todos[0].done;
 
 ### Classes
 
-You can also use `$state` in class fields (whether public or private):
+Class instances are not proxied. Instead, you can use `$state` in class fields (whether public or private), or as the first assignment to a property immediately inside the `constructor`:
 
 ```js
 // @errors: 7006 2554
 class Todo {
 	done = $state(false);
-	text = $state();
 
 	constructor(text) {
-		this.text = text;
+		this.text = $state(text);
 	}
 
 	reset() {
@@ -110,10 +107,9 @@ You can either use an inline function...
 // @errors: 7006 2554
 class Todo {
 	done = $state(false);
-	text = $state();
 
 	constructor(text) {
-		this.text = text;
+		this.text = $state(text);
 	}
 
 	+++reset = () => {+++
@@ -123,6 +119,8 @@ class Todo {
 }
 ```
 
+> Svelte provides reactive implementations of built-in classes like `Set` and `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).
+
 ## `$state.raw`
 
 In cases where you don't want objects and arrays to be deeply reactive you can use `$state.raw`.
@@ -147,6 +145,8 @@ person = {
 
 This can improve performance with large arrays and objects that you weren't planning to mutate anyway, since it avoids the cost of making them reactive. Note that raw state can _contain_ reactive state (for example, a raw array of reactive objects).
 
+As with `$state`, you can declare class fields using `$state.raw`.
+
 ## `$state.snapshot`
 
 To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`:

documentation/docs/02-runes/04-$effect.md

@@ -269,11 +269,11 @@ In general, `$effect` is best considered something of an escape hatch — useful
 
 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)):
+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#H4sIAAAAAAAAE5WRTWrDMBCFryKGLBJoY3fRjWIHeoiu6i6UZBwEY0VE49TB-O6VxrFTSih0qe_Ne_OjHpxpEDS8O7ZMeIAnqC1hAP3RA1990hKI_Fb55v06XJA4sZ0J-IjvT47RcYyBIuzP1vO2chVHHFjxiQ2pUr3k-SZRQlbBx_LIFoEN4zJfzQph_UMQr4hRXmBd456Xy5Uqt6pPKHmkfmzyPAZL2PCnbRpg8qWYu63I7lu4gswOSRYqrPNt3CgeqqzgbNwRK1A76w76YqjFspfcQTWmK3vJHlQm1puSTVSeqdOc_r9GaeCHfUSY26TXry6Br4RSK3C6yMEGT-aqVU3YbUZ2NF6rfP2KzXgbuYzY46czdgyazy0On_FlLH3F-UDXhgIO35UGlA1rAgAA)):
 
 ```svelte
 <script>
-	let total = 100;
+	const total = 100;
 	let spent = $state(0);
 	let left = $state(total);
 
@@ -297,32 +297,26 @@ You might be tempted to do something convoluted with effects to link one value t
 </label>
 ```
 
-Instead, use `oninput` callbacks or — better still — [function bindings](bind#Function-bindings) where possible ([demo](/playground/untitled#H4sIAAAAAAAAE51SsW6DMBT8FcvqABINdOhCIFKXTt06lg4GHpElYyz8iECIf69tcIIipo6-u3f3fPZMJWuBpvRzkBXyTpKSy5rLq6YRbbgATdOfmeKkrMgCBt9GPpQ66RsItFjJNBzhVScRJBobmumq5wovhSxQABLskAmSk7ckOXtMKyM22ItGhhAk4Z0R0OwIN-tIQzd-90HVhvy2HsGNiQFCMltBgd7XoecV2xzXNV7XaEcth7ZfRv7kujnsTX2Qd7USb5rFjwZkJlgJwpWRcakG04cpOS9oz-QVCuoeInXW-RyEJL-sG0b7Wy6kZWM-u7CFxM5tdrIl9qg72vB74H-y7T2iXROHyVb0CLanp1yNk4D1A1jQ91hzrQSbUtIIGLcir0ylJDm9Q7urz42bX4UwIk2xH2D5Xf4A7SeMcMQCAAA=)):
+Instead, use `oninput` callbacks or — better still — [function bindings](bind#Function-bindings) where possible ([demo](/playground/untitled#H4sIAAAAAAAAE5VRvW7CMBB-FcvqECQK6dDFJEgsnfoGTQdDLsjSxVjxhYKivHvPBwFUsXS8774_nwftbQva6I_e78gdvNo6Xzu_j3quG4cQtfkaNJ1DIiWA8atkE8IiHgEpYVsb4Rm-O3gCT2yji7jrXKB15StiOJKiA1lUpXrL81VCEUjFwHTGXiJZgiyf3TYIjSxq6NwR6uyifr0ohMbEZnpHH2rWf7ImS8KZGtK6osl_UqelRIyVL5b3ir5AuwWUtoXzoee6fIWy0p31e6i0XMocLfZQDuI6qtaeykGcR7UU6XWznFAZU9LN_X9B2UyVayk9f3ji0-REugen6U9upDOCcAWcLlS7GNCejWoQTqsLtrfBqHzxDu3DrUTOf0xwIm2o62H85sk6_OHG2jQWI4y_3byXXGMCAAA=)):
 
 ```svelte
 <script>
-	let total = 100;
+	const total = 100;
 	let spent = $state(0);
-	let left = $state(total);
-
-	function updateSpent(value) {
-		spent = value;
-		left = total - spent;
-	}
+	let left = $derived(total - spent);
 
-	function updateLeft(value) {
-		left = value;
++++	function updateLeft(left) {
 		spent = total - left;
-	}
+	}+++
 </script>
 
 <label>
-	<input type="range" bind:value={() => spent, updateSpent} max={total} />
+	<input type="range" bind:value={spent} max={total} />
 	{spent}/{total} spent
 </label>
 
 <label>
-	<input type="range" bind:value={() => left, updateLeft} max={total} />
+	<input type="range" +++bind:value={() => left, updateLeft}+++ max={total} />
 	{left}/{total} left
 </label>
 ```

documentation/docs/03-template-syntax/[email protected]

@@ -2,7 +2,9 @@
 title: {@attach ...}
 ---
 
-Attachments are functions that run when an element is mounted to the DOM. Optionally, they can return a function that is called when the element is later removed from the DOM.
+Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates.
+
+Optionally, they can return a function that is called before the attachment re-runs, or after the element is later removed from the DOM.
 
 > [!NOTE]
 > Attachments are available in Svelte 5.29 and newer.
@@ -55,7 +57,7 @@ A useful pattern is for a function, such as `tooltip` in this example, to _retur
 </button>
 ```
 
-Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes.
+Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs. (If this isn't what you want, see [Controlling when attachments re-run](#Controlling-when-attachments-re-run).)
 
 ## Inline attachments
 
@@ -126,6 +128,39 @@ This allows you to create _wrapper components_ that augment elements ([demo](/pl
 </Button>
 ```
 
+## Controlling when attachments re-run
+
+Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}` will re-run on changes to `foo` _or_ `bar` (or any state read inside `foo`):
+
+```js
+// @errors: 7006 2304 2552
+function foo(bar) {
+	return (node) => {
+		veryExpensiveSetupWork(node);
+		update(node, bar);
+	};
+}
+```
+
+In the rare case that this is a problem (for example, if `foo` does expensive and unavoidable setup work) consider passing the data inside a function and reading it in a child effect:
+
+```js
+// @errors: 7006 2304 2552
+function foo(+++getBar+++) {
+	return (node) => {
+		veryExpensiveSetupWork(node);
+
++++		$effect(() => {
+			update(node, getBar());
+		});+++
+	}
+}
+```
+
 ## Creating attachments programmatically
 
 To add attachments to an object that will be spread onto a component or element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey).
+
+## Converting actions to attachments
+
+If you're using a library that only provides actions, you can convert them to attachments with [`fromAction`](svelte-attachments#fromAction), allowing you to (for example) use them with components.

documentation/docs/03-template-syntax/12-bind.md

@@ -4,7 +4,7 @@ title: bind:
 
 Data ordinarily flows down, from parent to child. The `bind:` directive allows data to flow the other way, from child to parent.
 
-The general syntax is `bind:property={expression}`, where `expression` is an _lvalue_ (i.e. a variable or an object property). When the expression is an identifier with the same name as the property, we can omit the expression — in other words these are equivalent:
+The general syntax is `bind:property={expression}`, where `expression` is an [_lvalue_](https://press.rebus.community/programmingfundamentals/chapter/lvalue-and-rvalue/) (i.e. a variable or an object property). When the expression is an identifier with the same name as the property, we can omit the expression — in other words these are equivalent:
 
 <!-- prettier-ignore -->
 ```svelte
@@ -142,26 +142,27 @@ Checkboxes can be in an [indeterminate](https://developer.mozilla.org/en-US/docs
 
 ## `<input bind:group>`
 
-Inputs that work together can use `bind:group`.
+Inputs that work together can use `bind:group` ([demo](/playground/untitled#H4sIAAAAAAAAE62T32_TMBDH_5XDQkpbrct7SCMGEvCEECDxsO7BSW6L2c227EvbKOv_jp0f6jYhQKJv5_P3PvdL1wstH1Bk4hMSGdgbRzUssFaM9VJciFtF6EV23QvubNRFR_BPUVfWXvodEkdfKT3-zl8Zzag5YETuK6csF1u9ZUIGNo4VkYQNvPYsGRfJF5JKJ8s3QRJE6WoFb2Nq6K-ck13u2Sl9Vxxhlc6QUBIFnz9Brm9ifJ6esun81XoNd860FmtwslYGlLYte5AO4aHlVhJ1gIeKWq92COt1iMtJlkhFPkgh1rHZiiF6K6BUus4G5KafGznCTlIbVUMfQZUWMJh5OrL-C_qjMYSwb1DyiH7iOEuCb1ZpWTUjfHqcwC_GWDVY3ZfmME_SGttSmD9IHaYatvWHIc6xLyqad3mq6KuqcCwnWn9p8p-p71BqP2IH81zc9w2in-od7XORP7ayCpd5YCeXI_-p59mObPF9WmwGpx3nqS2Gzw8TO3zOaS5_GqUXyQUkS3h8hOSz0ZhMESHGc0c4Hm3MAn00t1wrb0l2GZRkqvt4sXwczm6Qh8vnUJzI2LV4vAkvqWgfehTZrSSPx19WiVfFfAQAAA==)):
 
 ```svelte
+<!--- file: BurritoChooser.svelte --->
 <script>
 	let tortilla = $state('Plain');
 
-	/** @type {Array<string>} */
+	/** @type {string[]} */
 	let fillings = $state([]);
 </script>
 
 <!-- grouped radio inputs are mutually exclusive -->
-<input type="radio" bind:group={tortilla} value="Plain" />
-<input type="radio" bind:group={tortilla} value="Whole wheat" />
-<input type="radio" bind:group={tortilla} value="Spinach" />
+<label><input type="radio" bind:group={tortilla} value="Plain" /> Plain</label>
+<label><input type="radio" bind:group={tortilla} value="Whole wheat" /> Whole wheat</label>
+<label><input type="radio" bind:group={tortilla} value="Spinach" /> Spinach</label>
 
 <!-- grouped checkbox inputs populate an array -->
-<input type="checkbox" bind:group={fillings} value="Rice" />
-<input type="checkbox" bind:group={fillings} value="Beans" />
-<input type="checkbox" bind:group={fillings} value="Cheese" />
-<input type="checkbox" bind:group={fillings} value="Guac (extra)" />
+<label><input type="checkbox" bind:group={fillings} value="Rice" /> Rice</label>
+<label><input type="checkbox" bind:group={fillings} value="Beans" /> Beans</label>
+<label><input type="checkbox" bind:group={fillings} value="Cheese" /> Cheese</label>
+<label><input type="checkbox" bind:group={fillings} value="Guac (extra)" /> Guac (extra)</label>
 ```
 
 > [!NOTE] `bind:group` only works if the inputs are in the same Svelte component.

documentation/docs/05-special-elements/04-svelte-body.md

@@ -8,7 +8,7 @@ title: <svelte:body>
 
 Similarly to `<svelte:window>`, this element allows you to add listeners to events on `document.body`, such as `mouseenter` and `mouseleave`, which don't fire on `window`. It also lets you use [actions](use) on the `<body>` element.
 
-As with `<svelte:window>` and `<svelte:document>`, this element may only appear the top level of your component and must never be inside a block or element.
+As with `<svelte:window>` and `<svelte:document>`, this element may only appear at the top level of your component and must never be inside a block or element.
 
 ```svelte
 <svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />

documentation/docs/06-runtime/02-context.md

@@ -125,7 +125,7 @@ In many cases this is perfectly fine, but there is a risk: if you mutate the sta
 ```svelte
 <!--- file: App.svelte ---->
 <script>
-	import { myGlobalState } from 'svelte';
+	import { myGlobalState } from './state.svelte.js';
 
 	let { data } = $props();
 

documentation/docs/07-misc/04-custom-elements.md

@@ -114,6 +114,8 @@ When constructing a custom element, you can tailor several aspects by defining `
 ...
 ```
 
+> [!NOTE] While Typescript is supported in the `extend` function, it is subject to limitations: you need to set `lang="ts"` on one of the scripts AND you can only use [erasable syntax](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly) in it. They are not processed by script preprocessors.
+
 ## Caveats and limitations
 
 Custom elements can be a useful way to package components for consumption in a non-Svelte app, as they will work with vanilla HTML and JavaScript as well as [most frameworks](https://custom-elements-everywhere.com/). There are, however, some important differences to be aware of:

documentation/docs/07-misc/07-v5-migration-guide.md

@@ -833,9 +833,9 @@ Svelte 5 is more strict about the HTML structure and will throw a compiler error
 
 Assignments to destructured parts of a `@const` declaration are no longer allowed. It was an oversight that this was ever allowed.
 
-### :is(...) and :where(...) are scoped
+### :is(...), :has(...), and :where(...) are scoped
 
-Previously, Svelte did not analyse selectors inside `:is(...)` and `:where(...)`, effectively treating them as global. Svelte 5 analyses them in the context of the current component. As such, some selectors may now be treated as unused if they were relying on this treatment. To fix this, use `:global(...)` inside the `:is(...)/:where(...)` selectors.
+Previously, Svelte did not analyse selectors inside `:is(...)`, `:has(...)`, and `:where(...)`, effectively treating them as global. Svelte 5 analyses them in the context of the current component. As such, some selectors may now be treated as unused if they were relying on this treatment. To fix this, use `:global(...)` inside the `:is(...)/:has(...)/:where(...)` selectors.
 
 When using Tailwind's `@apply` directive, add a `:global` selector to preserve rules that use Tailwind-generated `:is(...)` selectors:
 

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

@@ -200,6 +200,19 @@ Consider the following code:
 
 To fix it, either create callback props to communicate changes, or mark `person` as [`$bindable`]($bindable).
 
+### select_multiple_invalid_value
+
+```
+The `value` property of a `<select multiple>` element should be an array, but it received a non-array value. The selection will be kept as is.
+```
+
+When using `<select multiple value={...}>`, Svelte will mark all selected `<option>` elements as selected by iterating over the array passed to `value`. If `value` is not an array, Svelte will emit this warning and keep the selected options as they are.
+
+To silence the warning, ensure that `value`:
+
+- is an array for an explicit selection
+- is `null` or `undefined` to keep the selection as is
+
 ### state_proxy_equality_mismatch
 
 ```