docs: clarify when $effect.pre runs relative to DOM updates

.changeset/witty-donuts-explain.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+chore: clarify when `$effect.pre` runs relative to DOM updates

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

@@ -205,6 +205,8 @@ In rare cases, you may need to run code _before_ the DOM updates. For this we ca
 </div>
 ```
 
+Effects — including `$effect.pre` — run in tree order, interleaved with template updates. `$effect.pre` therefore runs before DOM updates that are scheduled after it in the same flush (its own component's template, and its children), but effects in ancestor components run earlier and may already have updated the DOM by the time it runs. It is not a phase that runs before every DOM mutation. When using [await expressions](await-expressions), block updates like `{#if ...}` and `{#each ...}` in the same component also run before `$effect.pre`.
+
 Apart from the timing, `$effect.pre` works exactly like `$effect`.
 
 ## `$effect.tracking`

documentation/docs/06-runtime/03-lifecycle-hooks.md

@@ -102,7 +102,7 @@ To implement a chat window that autoscrolls to the bottom when new messages appe
 
 In Svelte 4, we do this with `beforeUpdate`, but this is a flawed approach — it fires before _every_ update, whether it's relevant or not. In the example below, we need to introduce checks like `updatingMessages` to make sure we don't mess with the scroll position when someone toggles dark mode.
 
-With runes, we can use `$effect.pre`, which behaves the same as `$effect` but runs before the DOM is updated. As long as we explicitly reference `messages` inside the effect body, it will run whenever `messages` changes, but _not_ when `theme` changes.
+With runes, we can use `$effect.pre`, which behaves the same as `$effect` but runs before DOM updates scheduled after it (see [$effect.pre]($effect#$effect.pre) for the exact ordering). As long as we explicitly reference `messages` inside the effect body, it will run whenever `messages` changes, but _not_ when `theme` changes.
 
 `beforeUpdate`, and its equally troublesome counterpart `afterUpdate`, are therefore deprecated in Svelte 5.
 

packages/svelte/src/ambient.d.ts

@@ -261,7 +261,7 @@ declare function $effect(fn: () => void | (() => void)): void;
 declare namespace $effect {
 	/**
 	 * Runs code right before a component is mounted to the DOM, and then whenever its dependencies change, i.e. `$state` or `$derived` values.
-	 * The timing of the execution is right before the DOM is updated.
+	 * The timing of the execution is right before DOM updates scheduled after it in the same flush — effects in ancestor components run earlier and may already have updated the DOM.
 	 *
 	 * Example:
 	 * ```ts

packages/svelte/types/index.d.ts

@@ -3466,7 +3466,7 @@ declare function $effect(fn: () => void | (() => void)): void;
 declare namespace $effect {
 	/**
 	 * Runs code right before a component is mounted to the DOM, and then whenever its dependencies change, i.e. `$state` or `$derived` values.
-	 * The timing of the execution is right before the DOM is updated.
+	 * The timing of the execution is right before DOM updates scheduled after it in the same flush — effects in ancestor components run earlier and may already have updated the DOM.
 	 *
 	 * Example:
 	 * ```ts