From 8c6638cf0451d61a0c6c94c1e970e556b5f6fe07 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Tue, 15 Jul 2025 14:27:44 -0400
Subject: [PATCH] docs

---
 documentation/docs/02-runes/04-$effect.md     | 15 +++++
 .../docs/03-template-syntax/19-await.md       | 65 +++++++++++++++++--
 2 files changed, 76 insertions(+), 4 deletions(-)

diff --git a/documentation/docs/02-runes/04-$effect.md b/documentation/docs/02-runes/04-$effect.md
index 0e129973d5..b7169c9226 100644
--- a/documentation/docs/02-runes/04-$effect.md
+++ b/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) 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.
diff --git a/documentation/docs/03-template-syntax/19-await.md b/documentation/docs/03-template-syntax/19-await.md
index f62aa4819a..9fcecd1a49 100644
--- a/documentation/docs/03-template-syntax/19-await.md
+++ b/documentation/docs/03-template-syntax/19-await.md
@@ -37,7 +37,7 @@ Currently, you can only use `await` inside a [`<svelte:boundary>`](svelte-bounda
 </svelte:boundary>
 ```
 
-This restriction will be lifted once Svelte supports asynchronous server-side rendering.
+This restriction will be lifted once Svelte supports asynchronous server-side rendering (see [caveats](#Caveats)).
 
 > 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.
 
@@ -64,9 +64,64 @@ When an `await` expression depends on a particular piece of state, changes to th
 
 ...if you increment `a`, the contents of the `<p>` will _not_ immediately update to read `2 + 2 = 3` — instead, the text will update 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
 
-TODO
+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()`] 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
 
@@ -74,8 +129,10 @@ Errors in `await` expressions will bubble to the nearest [error boundary](svelte
 
 ## Caveats
 
-TODO
+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
 
-TODO
+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).