docs: clarify `$derived` `await` behavior and dependency tracking (#17696)

Closes #17660

### Before submitting the PR, please make sure you do the following

- [x] It's really useful if your PR references an issue where it is
discussed ahead of time. In many cases, features are absent for a
reason. For large changes, please create an RFC:
https://github.com/sveltejs/rfcs
- [x] Prefix your PR title with `feat:`, `fix:`, `chore:`, or `docs:`.
- [x] This message body should clearly illustrate what problems it
solves.
- [ ] Ideally, include a test that fails without this PR but passes with
it.
- [ ] If this PR changes code within `packages/svelte/src`, add a
changeset (`npx changeset`).

### Tests and linting

- [ ] Run the tests with `pnpm test` and lint the project with `pnpm
lint`

---------

Co-authored-by: Rich Harris <rich.harris@vercel.com>

documentation/docs/02-runes/03-$derived.md

@@ -51,6 +51,17 @@ In essence, `$derived(expression)` is equivalent to `$derived.by(() => expressio
 
 Anything read synchronously inside the `$derived` expression (or `$derived.by` function body) is considered a _dependency_ of the derived state. When the state changes, the derived will be marked as _dirty_ and recalculated when it is next read.
 
+In addition, if an expression contains an [`await`](await-expressions), Svelte transforms it such that any state _after_ the `await` is also tracked — in other words, in a case like this...
+
+```js
+let a = Promise.resolve(1);
+let b = 2;
+// ---cut---
+let total = $derived(await a + b);
+```
+
+...both `a` and `b` are tracked, even though `b` is only read once `a` has resolved, after the initial execution. (This does not apply to `await` in functions that are called by the expression, only the expression itself.)
+
 To exempt a piece of state from being treated as a dependency, use [`untrack`](svelte#untrack).
 
 ## Overriding derived values

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

@@ -59,8 +59,8 @@ Updates can overlap — a fast update will be reflected in the UI while an earli
 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 one(x)}</p>
-<p>{await two()}</p>
+<p>{await two(y)}</p>
 ```
 
 ...both functions will run at the same time, as they are independent expressions, even though they are _visually_ sequential.
@@ -68,13 +68,18 @@ Svelte will do as much asynchronous work as it can in parallel. For example if y
 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; }
+/** @param {number} x */
-async function two() { return 2; }
+async function one(x) { return x; }
+/** @param {number} y */
+async function two(y) { return y; }
+let x = $state(1);
+let y = $state(2);
 // ---cut---
-// these will run sequentially the first time,
+// `b` will not be created until `a` has resolved,
-// but will update independently
+// but once created they will update independently
-let a = $derived(await one());
+// even if `x` and `y` update simultaneously
-let b = $derived(await two());
+let a = $derived(await one(x));
+let b = $derived(await two(y));
 ```
 
 > [!NOTE] If you write code like this, expect Svelte to give you an [`await_waterfall`](runtime-warnings#Client-warnings-await_waterfall) warning