docs(nav[spa]): wrap DOM swap in View Transitions API for smooth crossfade

why: SPA navigation instantly replaces DOM content, causing a jarring
visual jump between pages instead of a smooth transition.
what:
- Wrap swap+reinit in document.startViewTransition() when available
- Add 150ms crossfade animation via ::view-transition pseudo-elements
- Progressive enhancement: unsupported browsers get instant swap

Author: tony

docs/_static/css/custom.css

@@ -198,6 +198,16 @@ article {
  * content-visibility and badge-specific height to prevent CLS.
  * ────────────────────────────────────────────────────────── */
 
+
+/* ── View Transitions (SPA navigation) ────────────────────
+ * Crossfade between pages during SPA navigation.
+ * Browsers without View Transitions API get instant swap.
+ * ────────────────────────────────────────────────────────── */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 150ms;
+}
+
 img {
   content-visibility: auto;
 }

docs/_static/js/spa-nav.js

@@ -160,21 +160,29 @@
       if (!doc.querySelector(".article-container"))
         throw new Error("no article");
 
-      swap(doc);
+      var applySwap = function () {
+        swap(doc);
+
+        if (!isPop) history.pushState({ spa: true }, "", url);
+
+        if (!isPop) {
+          var hash = new URL(url, location.href).hash;
+          if (hash) {
+            var el = document.querySelector(hash);
+            if (el) el.scrollIntoView();
+          } else {
+            window.scrollTo(0, 0);
+          }
+        }
 
-      if (!isPop) history.pushState({ spa: true }, "", url);
+        reinit();
+      };
 
-      if (!isPop) {
-        var hash = new URL(url, location.href).hash;
-        if (hash) {
-          var el = document.querySelector(hash);
-          if (el) el.scrollIntoView();
-        } else {
-          window.scrollTo(0, 0);
-        }
+      if (document.startViewTransition) {
+        document.startViewTransition(applySwap);
+      } else {
+        applySwap();
       }
-
-      reinit();
     } catch (err) {
       if (err.name === "AbortError") return;
       window.location.href = url;