docs: async stuff (#16376)

* WIP async docs

* WIP

* docs

* update $effect namespace

* changeset

* oops

* typo

* fixes

* tweak

* missing link

* fix

* tweak

* Update documentation/docs/03-template-syntax/19-await-expressions.md

Co-authored-by: Conduitry <[email protected]>

---------

Co-authored-by: Conduitry <[email protected]>

Author: Rich-Harris

.changeset/long-drinks-reply.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+fix: add `$effect.pending()` to types

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

@@ -119,7 +119,7 @@ class Todo {
 }
 ```
 
-> Svelte provides reactive implementations of built-in classes like `Set` and `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).
+> [NOTE!] Svelte provides reactive implementations of built-in classes like `Set` and `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).
 
 ## `$state.raw`
 

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

@@ -221,6 +221,21 @@ The `$effect.tracking` rune is an advanced feature that tells you whether or not
 
 It is used to implement abstractions like [`createSubscriber`](/docs/svelte/svelte-reactivity#createSubscriber), which will create listeners to update reactive values but _only_ if those values are being tracked (rather than, for example, read inside an event handler).
 
+## `$effect.pending`
+
+When using [`await`](await-expressions) in components, the `$effect.pending()` rune tells you how many promises are pending in the current [boundary](svelte-boundary), not including child boundaries ([demo](/playground/untitled#H4sIAAAAAAAAE3WRMU_DMBCF_8rJdHDUqilILGkaiY2RgY0yOPYZWbiOFV8IleX_jpMUEAIWS_7u-d27c2ROnJBV7B6t7WDsequAozKEqmAbpo3FwKqnyOjsJ90EMr-8uvN-G97Q0sRaEfAvLjtH6CjbsDrI3nhqju5IFgkEHGAVSBDy62L_SdtvejPTzEU4Owl6cJJM50AoxcUG2gLiVM31URgChyM89N3JBORcF3BoICA9mhN2A3G9gdvdrij2UJYgejLaSCMsKLTivNj0SEOf7WEN7ZwnHV1dfqd2dTsQ5QCdk9bI10PkcxexXqcmH3W51Jt_le2kbH8os9Y3UaTcNLYpDx-Xab6GTHXpZ128MhpWqDVK2np0yrgXXqQpaLa4APDLBkIF8bd2sYql0Sn_DeE7sYr6AdNzvgljR-MUq7SwAdMHeUtgHR4CAAA=)):
+
+```svelte
+<button onclick={() => a++}>a++</button>
+<button onclick={() => b++}>b++</button>
+
+<p>{a} + {b} = {await add(a, b)}</p>
+
+{#if $effect.pending()}
+	<p>pending promises: {$effect.pending()}</p>
+{/if}
+```
+
 ## `$effect.root`
 
 The `$effect.root` rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. This is useful for nested effects that you want to manually control. This rune also allows for the creation of effects outside of the component initialisation phase.

documentation/docs/03-template-syntax/19-await-expressions.md

@@ -0,0 +1,144 @@
+---
+title: await
+---
+
+As of Svelte 5.36, you can use the `await` keyword inside your components in three places where it was previously unavailable:
+
+- at the top level of your component's `<script>`
+- inside `$derived(...)` declarations
+- inside your markup
+
+This feature is currently experimental, and you must opt in by adding the `experimental.async` option wherever you [configure](/docs/kit/configuration) Svelte, usually `svelte.config.js`:
+
+```js
+/// file: svelte.config.js
+export default {
+	compilerOptions: {
+		experimental: {
+			async: true
+		}
+	}
+};
+```
+
+The experimental flag will be removed in Svelte 6.
+
+## Boundaries
+
+Currently, you can only use `await` inside a [`<svelte:boundary>`](svelte-boundary) with a `pending` snippet:
+
+```svelte
+<svelte:boundary>
+	<MyApp />
+
+	{#snippet pending()}
+		<p>loading...</p>
+	{/snippet}
+</svelte:boundary>
+```
+
+This restriction will be lifted once Svelte supports asynchronous server-side rendering (see [caveats](#Caveats)).
+
+> [!NOTE] In the [playground](/playground), your app is rendered inside a boundary with an empty pending snippet, so that you can use `await` without having to create one.
+
+## Synchronized updates
+
+When an `await` expression depends on a particular piece of state, changes to that state will not be reflected in the UI until the asynchronous work has completed, so that the UI is not left in an inconsistent state. In other words, in an example like [this](/playground/untitled#H4sIAAAAAAAAE42QsWrDQBBEf2VZUkhYRE4gjSwJ0qVMkS6XYk9awcFpJe5Wdoy4fw-ycdykSPt2dpiZFYVGxgrf2PsJTlPwPWTcO-U-xwIH5zli9bminudNtwEsbl-v8_wYj-x1Y5Yi_8W7SZRFI1ZYxy64WVsjRj0rEDTwEJWUs6f8cKP2Tp8vVIxSPEsHwyKdukmA-j6jAmwO63Y1SidyCsIneA_T6CJn2ZBD00Jk_XAjT4tmQwEv-32eH6AsgYK6wXWOPPTs6Xy1CaxLECDYgb3kSUbq8p5aaifzorCt0RiUZbQcDIJ10ldH8gs3K6X2Xzqbro5zu1KCHaw2QQPrtclvwVSXc2sEC1T-Vqw0LJy-ClRy_uSkx2ogHzn9ADZ1CubKAQAA)...
+
+```svelte
+<script>
+	let a = $state(1);
+	let b = $state(2);
+
+	async function add(a, b) {
+		await new Promise((f) => setTimeout(f, 500)); // artificial delay
+		return a + b;
+	}
+</script>
+
+<input type="number" bind:value={a}>
+<input type="number" bind:value={b}>
+
+<p>{a} + {b} = {await add(a, b)}</p>
+```
+
+...if you increment `a`, the contents of the `<p>` will _not_ immediately update to read this —
+
+```html
+<p>2 + 2 = 3</p>
+```
+
+— instead, the text will update to `2 + 2 = 4` when `add(a, b)` resolves.
+
+Updates can overlap — a fast update will be reflected in the UI while an earlier slow update is still ongoing.
+
+## Concurrency
+
+Svelte will do as much asynchronous work as it can in parallel. For example if you have two `await` expressions in your markup...
+
+```svelte
+<p>{await one()}</p>
+<p>{await two()}</p>
+```
+
+...both functions will run at the same time, as they are independent expressions, even though they are _visually_ sequential.
+
+This does not apply to sequential `await` expressions inside your `<script>` or inside async functions — these run like any other asynchronous JavaScript. An exception is that independent `$derived` expressions will update independently, even though they will run sequentially when they are first created:
+
+```js
+async function one() { return 1; }
+async function two() { return 2; }
+// ---cut---
+// these will run sequentially the first time,
+// but will update independently
+let a = $derived(await one());
+let b = $derived(await two());
+```
+
+> [!NOTE] If you write code like this, expect Svelte to give you an [`await_waterfall`](runtime-warnings#Client-warnings-await_waterfall) warning
+
+## Indicating loading states
+
+In addition to the nearest boundary's [`pending`](svelte-boundary#Properties-pending) snippet, you can indicate that asynchronous work is ongoing with [`$effect.pending()`]($effect#$effect.pending).
+
+You can also use [`settled()`](svelte#settled) to get a promise that resolves when the current update is complete:
+
+```js
+let color = 'red';
+let answer = -1;
+let updating = false;
+// ---cut---
+import { tick, settled } from 'svelte';
+
+async function onclick() {
+	updating = true;
+
+	// without this, the change to `updating` will be
+	// grouped with the other changes, meaning it
+	// won't be reflected in the UI
+	await tick();
+
+	color = 'octarine';
+	answer = 42;
+
+	await settled();
+
+	// any updates affected by `color` or `answer`
+	// have now been applied
+	updating = false;
+}
+```
+
+## Error handling
+
+Errors in `await` expressions will bubble to the nearest [error boundary](svelte-boundary).
+
+## Caveats
+
+As an experimental feature, the details of how `await` is handled (and related APIs like `$effect.pending()`) are subject to breaking changes outside of a semver major release, though we intend to keep such changes to a bare minimum.
+
+Currently, server-side rendering is synchronous. If a `<svelte:boundary>` with a `pending` snippet is encountered during SSR, only the `pending` snippet will be rendered.
+
+## Breaking changes
+
+Effects run in a slightly different order when the `experimental.async` option is `true`. Specifically, _block_ effects like `{#if ...}` and `{#each ...}` now run before an `$effect.pre` or `beforeUpdate` in the same component, which means that in [very rare situations](/playground/untitled?#H4sIAAAAAAAAE22R3VLDIBCFX2WLvUhnTHsf0zre-Q7WmfwtFV2BgU1rJ5N3F0jaOuoVcPbw7VkYhK4_URTiGYkMnIyjDjLsFGO3EvdCKkIvipdB8NlGXxSCPt96snbtj0gctab2-J_eGs2oOWBE6VunLO_2es-EDKZ5x5ZhC0vPNWM2gHXGouNzAex6hHH1cPHil_Lsb95YT9VQX6KUAbS2DrNsBdsdDFHe8_XSYjH1SrhELTe3MLpsemajweiWVPuxHSbKNd-8eQTdE0EBf4OOaSg2hwNhhE_ABB_ulJzjj9FULvIcqgm5vnAqUB7wWFMfhuugQWkcAr8hVD-mq8D12kOep24J_IszToOXdveGDsuNnZwbJUNlXsKnhJdhUcTo42s41YpOSneikDV5HL8BktM6yRcCAAA=) it is possible to update a block that should no longer exist, but only if you update state inside an effect, [which you should avoid]($effect#When-not-to-use-$effect).

documentation/docs/05-special-elements/01-svelte-boundary.md

@@ -9,19 +9,41 @@ title: <svelte:boundary>
 > [!NOTE]
 > This feature was added in 5.3.0
 
-Boundaries allow you to guard against errors in part of your app from breaking the app as a whole, and to recover from those errors.
+Boundaries allow you to 'wall off' parts of your app, so that you can:
 
-If an error occurs while rendering or updating the children of a `<svelte:boundary>`, or running any [`$effect`]($effect) functions contained therein, the contents will be removed.
+- provide UI that should be shown when [`await`](await-expressions) expressions are first resolving
+- handle errors that occur during rendering or while running effects, and provide UI that should be rendered when an error happens
 
-Errors occurring outside the rendering process (for example, in event handlers or after a `setTimeout` or async work) are _not_ caught by error boundaries.
+If a boundary handles an error (with a `failed` snippet or `onerror` handler, or both) its existing content will be removed.
+
+> [!NOTE] Errors occurring outside the rendering process (for example, in event handlers or after a `setTimeout` or async work) are _not_ caught by error boundaries.
 
 ## Properties
 
-For the boundary to do anything, one or both of `failed` and `onerror` must be provided.
+For the boundary to do anything, one or more of the following must be provided.
+
+### `pending`
+
+As of Svelte 5.36, boundaries with a `pending` snippet can contain [`await`](await-expressions) expressions. This snippet will be shown when the boundary is first created, and will remain visible until all the `await` expressions inside the boundary have resolved ([demo](/playground/untitled#H4sIAAAAAAAAE21QQW6DQAz8ytY9BKQVpFdKkPqDHnorPWzAaSwt3tWugUaIv1eE0KpKD5as8YxnNBOw6RAKKOOAVrA4up5bEy6VGknOyiO3xJ8qMnmPAhpOZDFC8T6BXPyiXADQ258X77P1FWg4moj_4Y1jQZZ49W0CealqruXUcyPkWLVozQXbZDC2R606spYiNo7bqA7qab_fp2paFLUElD6wYhzVa3AdRUySgNHZAVN1qDZaLRHljTp0vSTJ9XJjrSbpX5f0eZXN6zLXXOa_QfmurIVU-moyoyH5ib87o7XuYZfOZe6vnGWmx1uZW7lJOq9upa-sMwuUZdkmmfIbfQ1xZwwaBL8ECgk9zh8axJAdiVsoTsZGnL8Bg4tX_OMBAAA=)):
+
+```svelte
+<svelte:boundary>
+	<p>{await delayed('hello!')}</p>
+
+	{#snippet pending()}
+		<p>loading...</p>
+	{/snippet}
+</svelte:boundary>
+```
+
+The `pending` snippet will _not_ be shown for subsequent async updates — for these, you can use [`$effect.pending()`]($effect#$effect.pending).
+
+> [!NOTE] In the [playground](/playground), your app is rendered inside a boundary with an empty pending snippet, so that you can use `await` without having to create one.
+
 
 ### `failed`
 
-If a `failed` snippet is provided, it will be rendered with the error that was thrown, and a `reset` function that recreates the contents ([demo](/playground/hello-world#H4sIAAAAAAAAE3VRy26DMBD8lS2tFCIh6JkAUlWp39Cq9EBg06CAbdlLArL87zWGKk8ORnhmd3ZnrD1WtOjFXqKO2BDGW96xqpBD5gXerm5QefG39mgQY9EIWHxueRMinLosti0UPsJLzggZKTeilLWgLGc51a3gkuCjKQ7DO7cXZotgJ3kLqzC6hmex1SZnSXTWYHcrj8LJjWTk0PHoZ8VqIdCOKayPykcpuQxAokJaG1dGybYj4gw4K5u6PKTasSbjXKgnIDlA8VvUdo-pzonraBY2bsH7HAl78mKSHZpgIcuHjq9jXSpZSLixRlveKYQUXhQVhL6GPobXAAb7BbNeyvNUs4qfRg3OnELLj5hqH9eQZqCnoBwR9lYcQxuVXeBzc8kMF8yXY4yNJ5oGiUzP_aaf_waTRGJib5_Ad3P_vbCuaYxzeNpbU0eUMPAOKh7Yw1YErgtoXyuYlPLzc10_xo_5A91zkQL_AgAA)):
+If a `failed` snippet is provided, it will be rendered when an error is thrown inside the boundary, with the `error` and a `reset` function that recreates the contents ([demo](/playground/hello-world#H4sIAAAAAAAAE3VRy26DMBD8lS2tFCIh6JkAUlWp39Cq9EBg06CAbdlLArL87zWGKk8ORnhmd3ZnrD1WtOjFXqKO2BDGW96xqpBD5gXerm5QefG39mgQY9EIWHxueRMinLosti0UPsJLzggZKTeilLWgLGc51a3gkuCjKQ7DO7cXZotgJ3kLqzC6hmex1SZnSXTWYHcrj8LJjWTk0PHoZ8VqIdCOKayPykcpuQxAokJaG1dGybYj4gw4K5u6PKTasSbjXKgnIDlA8VvUdo-pzonraBY2bsH7HAl78mKSHZpgIcuHjq9jXSpZSLixRlveKYQUXhQVhL6GPobXAAb7BbNeyvNUs4qfRg3OnELLj5hqH9eQZqCnoBwR9lYcQxuVXeBzc8kMF8yXY4yNJ5oGiUzP_aaf_waTRGJib5_Ad3P_vbCuaYxzeNpbU0eUMPAOKh7Yw1YErgtoXyuYlPLzc10_xo_5A91zkQL_AgAA)):
 
 ```svelte
 <svelte:boundary>

packages/svelte/src/ambient.d.ts

@@ -255,6 +255,13 @@ declare namespace $effect {
 	 */
 	export function pre(fn: () => void | (() => void)): void;
 
+	/**
+	 * Returns the number of promises that are pending in the current boundary, not including child boundaries.
+	 *
+	 * https://svelte.dev/docs/svelte/$effect#$effect.pending
+	 */
+	export function pending(): number;
+
 	/**
 	 * The `$effect.tracking` rune is an advanced feature that tells you whether or not the code is running inside a tracking context, such as an effect or inside your template.
 	 *

packages/svelte/types/index.d.ts

@@ -3325,6 +3325,13 @@ declare namespace $effect {
 	 */
 	export function pre(fn: () => void | (() => void)): void;
 
+	/**
+	 * Returns the number of promises that are pending in the current boundary, not including child boundaries.
+	 *
+	 * https://svelte.dev/docs/svelte/$effect#$effect.pending
+	 */
+	export function pending(): number;
+
 	/**
 	 * The `$effect.tracking` rune is an advanced feature that tells you whether or not the code is running inside a tracking context, such as an effect or inside your template.
 	 *