VT event lifecycle docs

src/content/docs/en/guides/view-transitions.mdx

@@ -465,20 +465,109 @@ If you have code that sets up global state, this state will need to take into ac
 
 Module scripts are only ever executed once because the browser keeps track of which modules are already loaded. For these scripts, you do not need to worry about re-execution.
 
-### `astro:page-load`
+## Lifecycle events
 
-An event that fires at the end of page navigation, after the new page is visible to the user and blocking styles and scripts are loaded. You can listen to this event on the `document`.
+The `<ViewTransition />` router fires a number events on the `document` during navigation. These events provide hooks into the lifecycle of navigation, allowing to you do things like showing indicators that a new page is loading, override default behavior, and restore state as navigation is completing.
 
-The `<ViewTransitions />` component fires this event both on initial page navigation (MPA) and any subsequent navigation, either forwards or backwards.
+The navigation process involves a **preparation** phase, when new content is loaded; a **DOM swap** phase, where the old page's content is replaced by the new page's content; and a **completion** phase where the new page is loaded, scripts are executed and clean-up work is carried out. 
 
-You can use this event to run code on every page navigation, or only once ever:
+Astro's View Transition API lifecycle events in order are:
+- [`astro:before-preparation`](#astrobefore-preparation)
+- [`astro:after-preparation`](#astroafter-preparation)
+- [`astro:before-swap`](#astrobefore-swap)
+- [`astro:after-swap`](#astroafter-swap)
+- [`astro:page-load`](#astropage-load)
 
-```astro "{ once: true }"
-<script>
-  document.addEventListener('astro:page-load', () => {
-    // This only runs once.
-    setupStuff();
-  }, { once: true });
+:::tip
+`before-` events allow you to influence and modify actions that are about to take place, and `after-` events are notifications that a phase is complete.
+:::
+
+While some actions can be triggered during any event, some tasks can only be performed during a specific event for best results, such as displaying a loading spinner before preparation or overriding animation pairs before swapping content.
+
+### `astro:before-preparation`
+
+<Since v="3.6.0" />
+
+An event that fires at the beginning of the preparation phase, after navigation has started (e.g. after the user has clicked a link), but before content is loaded.
+
+This event is used:
+
+- To do something before loading has started, such as showing an a loading spinner.
+- To alter loading, such as loading content you've defined in a template rather than from the external URL.
+- To change the `direction` of the navigation (which is usually either `forward` or `backward`) for custom animation.
+
+Here is an example of using the `astro:before-preparation` event to load a spinner before the content is loaded.
+
+```js
+<script is:inline>
+  document.addEventListener('astro:before-preparation', ev => {
+    const originalLoader = ev.loader;
+    ev.loader = async function() {
+      const { startSpinner } = await import('./spinner.js');
+      const stop = startSpinner();
+      await originalLoader();
+      stop();
+    };
+  });
+</script>
+```
+
+### `astro:after-preparation`
+
+<Since v="3.6.0" />
+
+An event that fires at the end of the preparation phase, after the new page's content has been loaded and parsed into a document. This event occurs before the view transitions phase.
+
+This example uses the `astro:before-preparation` event to start a loading indicator and the `astro:after-preparation` event to stop it:
+
+```astro
+<script is:inline>
+  document.addEventListener('astro:before-preparation', () => {
+    document.querySelector('#loading').classList.add('show');
+  });
+  document.addEventListener('astro:after-preparation', () => {
+    document.querySelector('#loading').classList.remove('show');
+  });
+</script>
+```
+
+### `astro:before-swap`
+
+<Since v="3.6.0" />
+
+An event that fires befores the new document, populated during the preparation phase, replaces the current document. This event occurs inside of the view transition, where the user is still seeing a snapshot of the old page.
+
+This event can be used to make changes before the swap occurs. The `newDocument` property on the event represents the incoming document. Here is an example of ensuring the browser's light or dark mode preference in `localStorage` is carried over to the new page:
+
+```astro
+<script is:inline>
+  function setDarkMode(document) {
+    let theme = localStorage.darkMode ? 'dark' : 'light';
+    document.documentElement.dataset.theme = theme;
+  }
+
+  setDarkMode(document);
+
+  document.addEventListener('astro:before-swap', ev => {
+    // Pass the incoming document to set the theme on it
+    setDarkMode(ev.newDocument);
+  });
+</script>
+```
+
+
+
+The `astro:before-swap` event can also be used to change the *implementation* of the swap. The default swap implementation diffs head content, moves __persistent__ elements from the old document to the `newDocument`, and then replaces the entire `body` with the body of the new document.
+
+At this point of the lifecycle, you could choose to define your own swap implementation, for example to diff the entire contents of the existing document (which some other routers do):
+
+```astro
+<script is:inline>
+  document.addEventListener('astro:before-swap', ev => {
+    ev.swap = () => {
+      diff(document, ev.newDocument);
+    };
+  });
 </script>
 ```
 
@@ -488,20 +577,24 @@ An event that fires immediately after the new page replaces the old page. You ca
 
 This event, when listened to on the **outgoing page**, is useful to pass along and restore any state on the DOM that needs to transfer over to the new page.
 
-For example, if you are implementing dark mode support, this event can be used to restore state across page loads:
+This is the latest point in the lifecyle where it is still safe to, for example, add a dark mode class name (`<html class="dark-mode">`), though you may wish to do so in an earlier event.
 
-```astro
+As the `astro:after-swap` event occurs immediately before the view transition ends, it's a good time to stop any loading indicators that might be running.
+
+### `astro:page-load`
+
+An event that fires at the end of page navigation, after the new page is visible to the user and blocking styles and scripts are loaded. You can listen to this event on the `document`.
+
+The `<ViewTransitions />` component fires this event both on initial page navigation for a pre-rendered page and on any subsequent navigation, either forwards or backwards.
+
+You can use this event to run code on every page navigation, or only once ever:
+
+```astro "{ once: true }"
 <script>
-	const setDarkMode = () => {
-		if (localStorage.darkMode) {
-			document.documentElement.dataset.dark = '';
-		}
-	};
-
-  // Runs on initial navigation
-	setDarkMode();
-  // Runs on view transitions navigation
-	document.addEventListener('astro:after-swap', setDarkMode);
+  document.addEventListener('astro:page-load', () => {
+    // This only runs once.
+    setupStuff();
+  }, { once: true });
 </script>
 ```