From e313292ccf554ea4dace1eedd8d969e48d25046f Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Tue, 15 Jul 2025 10:44:41 -0400
Subject: [PATCH] WIP async docs

---
 .../docs/03-template-syntax/19-await.md       | 54 +++++++++++++++++++
 .../05-special-elements/01-svelte-boundary.md | 16 ++++++
 2 files changed, 70 insertions(+)
 create mode 100644 documentation/docs/03-template-syntax/19-await.md

diff --git a/documentation/docs/03-template-syntax/19-await.md b/documentation/docs/03-template-syntax/19-await.md
new file mode 100644
index 0000000000..34dcf0441f
--- /dev/null
+++ b/documentation/docs/03-template-syntax/19-await.md
@@ -0,0 +1,54 @@
+---
+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](https://svelte.dev/docs/kit/configuration) Svelte, usually `svelte.config.js`:
+
+```js
+/// file: svelte.config.js
+export default {
+	compilerOptions: {
+		experimenntal: {
+			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.
+
+> 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
+
+TODO
+
+## Caveats
+
+TODO
+
+## Breaking changes
+
+TODO
diff --git a/documentation/docs/05-special-elements/01-svelte-boundary.md b/documentation/docs/05-special-elements/01-svelte-boundary.md
index f5439b4b83..32066b7a72 100644
--- a/documentation/docs/05-special-elements/01-svelte-boundary.md
+++ b/documentation/docs/05-special-elements/01-svelte-boundary.md
@@ -42,6 +42,22 @@ If a `failed` snippet is provided, it will be rendered with the error that was t
 >
 > ...or implicitly by declaring it directly inside the boundary, as in the example above.
 
+### `pending`
+
+As of Svelte 5.36, boundaries with a `pending` snippet can contain [`await`](await) 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>
+```
+
+> 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.
+
 ### `onerror`
 
 If an `onerror` function is provided, it will be called with the same two `error` and `reset` arguments. This is useful for tracking the error with an error reporting service...