@xingwangzhe/stalux 1.38.0 → 1.39.1

package/README.md

@@ -18,6 +18,10 @@ Standalone images written as `![Image description](url)` receive a `figure` and
 
 Code blocks default to the single `dark-plus` theme, with system color-scheme switching and theme selectors disabled. To opt into another theme or switching behavior, explicitly override `themes`, `useDarkModeMediaQuery`, and `themeCssSelector` through `expressiveCode`. This only changes generated code styles and adds no telemetry.
 
+Route changes automatically show a 2px accent-colored progress bar at the top of the viewport, with no configuration. Its length follows actual milestones, with slow visual growth toward a bounded ceiling while waiting: loading begins, document/font preparation finishes, the DOM swaps, and page scripts finish; completion waits for the visual transition as well. It only reaches the end when loading and the transition both complete, and does not represent download/time percentages. It handles superseded or canceled navigation, history traversal, and reduced motion without additional requests or telemetry.
+
+The sticky header stays at the top while the body grows with long content. Route transitions use a 100ms native Web Animations API fade on the new content, with the persisted header and footer stationary. Page-sized View Transition snapshots and geometry interpolation are disabled; Astro still handles document preparation, history, scroll restoration and scripts. Progress and background updates wait for the real content animation to finish. Reduced motion and browser-provided history gestures skip this extra animation. Navigation batches layout reads in one frame and carries the persisted header's measured dimensions across swaps, reducing style recalculation, rasterization and compositing work on mobile devices. Content, lightboxes, search, comments and analytics keep their existing behavior.
+
 ---
 
 ## 🚀 Quick Start
@@ -191,11 +195,11 @@ id: head
 bingClarityId: "YOUR_CLARITY_PROJECT_ID"
 ```
 
-Google Analytics, Clarity, and Umami use low-priority native asynchronous scripts. Each SDK loads once per session, and failures do not block reading or navigation. Vercount rebinds visible counters after each `astro:page-load`. GA sends explicit pageviews. Umami disables automatic pageviews while retaining click tracking, capturing each page's URL, title, and referrer before the SDK resolves so rapid navigation cannot mix visits. An existing legacy Partytown session performs one full reload when it encounters the new runtime to prevent duplicate listeners and tracking.
+Google Analytics, Clarity, and Umami use low-priority native asynchronous scripts. Each SDK loads once per session, and failures do not block reading or navigation. Vercount rebinds visible counters after each `astro:page-load`. GA captures each URL, title, and referrer, then sends pageviews in visit order through separate background tasks after the native transition releases rendering, the content animation is installed and a paint has been yielded. A bounded timer handles task starvation; hiding or leaving the document flushes pending views immediately. The SDK still runs on the main thread; this scheduling reduces synchronous work on the route's first frame. Umami disables automatic pageviews while retaining click tracking and captures page information before the SDK resolves so rapid navigation cannot mix visits. An existing older runtime or legacy Partytown session performs one full reload when it encounters the new runtime to prevent duplicate listeners and tracking.
 
 For Google Analytics, turn off **Page changes based on browser history events** under **Admin → Data streams → Enhanced measurement → Page views → Advanced settings**. Stalux sets `send_page_view: false` and sends the URL and title for each navigation explicitly. GA's history tracking must also be disabled in the property to prevent duplicate soft-navigation pageviews. Other enhanced measurement options can remain enabled. See [Google's pageview documentation](https://developers.google.com/analytics/devguides/collection/ga4/views).
 
-`bingClarityId` is the historical Stalux field name for a Microsoft Clarity Project ID. Get the ID from the Clarity project under **Settings → Setup → Get tracking code**. Stalux loads the tracking code asynchronously and preserves one loader across soft navigation. The SDK handles history navigation itself. Do not install the same project again through `anyhead`, a tag manager, or another plugin.
+`bingClarityId` is the historical Stalux field name for a Microsoft Clarity Project ID. Get the ID from the Clarity project under **Settings → Setup → Get tracking code**. Stalux includes the official `@microsoft/clarity` npm dependency, imports it dynamically in the browser, and calls `Clarity.init()` once across soft navigation. Consumer projects such as myblog only configure the ID and upgrade the theme; no separate Clarity installation or script is needed. The theme observes tag loading failures and allows a later page to retry. Tag load, recorder readiness and successful collection are verified separately. The official npm package still loads the hosted recording engine and does not move DOM capture into a Worker. The SDK handles history navigation itself. Do not install the same project again through `anyhead`, a tag manager, or another plugin.
 
 The Project ID is a public browser identifier. Never put a Clarity Data Export API token in this YAML or in client-side code. If the site uses a strict CSP, consent banner, or CMP, configure those host-site policies and signals separately; this theme does not make legal compliance decisions for the site.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.38.0",
+    "version": "1.39.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -107,6 +107,7 @@
         "@expressive-code/plugin-line-numbers": "^0.44.2",
         "@lucide/astro": "^1.56.0",
         "@mcp-b/webmcp-polyfill": "^5.1.0",
+        "@microsoft/clarity": "1.0.2",
         "@pagefind/component-ui": "^1.5.2",
         "@waline/client": "^3.16.1",
         "@xingwangzhe/cjk-font-split-native": "^0.4.10",

package/src/components/stalux/layout/head.astro

@@ -42,7 +42,7 @@ const ldJson = JSON.stringify(seo.schema).replace(/<\//g, "<\\/");
 
 <head>
     <meta charset="utf-8">
-    <ClientRouter fallback="animate" />
+    <ClientRouter fallback="swap" />
     <SEO
         title={seo.title}
         description={seo.description}

package/src/components/stalux/layout/navigationProgress.astro

@@ -0,0 +1,55 @@
+<div
+    data-stalux-navigation-progress
+    aria-hidden="true"
+    transition:persist="stalux-navigation-progress"
+    transition:name="stalux-navigation-progress"
+    transition:animate="none"
+></div>
+
+<style is:global>
+[data-stalux-navigation-progress] {
+    position: fixed;
+    inset: 0 0 auto;
+    height: 2px;
+    z-index: 2147483647;
+    pointer-events: none;
+    background: var(--stalux-accent-color, #eab308);
+    transform: scaleX(0);
+    transform-origin: left;
+    opacity: 0;
+    transition:
+        transform 450ms ease-out,
+        opacity 120ms ease-out;
+}
+[data-stalux-navigation-progress][data-stage] {
+    opacity: 1;
+}
+[data-stalux-navigation-progress][data-stage="complete"] {
+    transition:
+        transform 160ms ease-out,
+        opacity 120ms ease-out;
+}
+[data-stalux-navigation-progress]:not([data-stage]) {
+    transition: opacity 120ms ease-out;
+}
+::view-transition-group(stalux-navigation-progress) {
+    z-index: 2147483647;
+}
+::view-transition-old(stalux-navigation-progress) {
+    display: none;
+}
+::view-transition-new(stalux-navigation-progress) {
+    animation: none;
+}
+@media (prefers-reduced-motion: reduce) {
+    [data-stalux-navigation-progress],
+    [data-stalux-navigation-progress][data-stage] {
+        transition: none;
+    }
+}
+@media print {
+    [data-stalux-navigation-progress] {
+        display: none;
+    }
+}
+</style>

package/src/internal/style-names.generated.ts

@@ -288,48 +288,49 @@ export const styleNames: { classes: Record<string, string>; variables: Record<st
         "--stalux-bg-filter": "--s1o",
         "--stalux-nav-offset": "--s1p",
         "--stalux-site-header-height": "--s1q",
-        "--stalux-text-shadow": "--s1r",
-        "--surface-glass": "--s1s",
-        "--surface-glass-shadow": "--s1t",
-        "--tag-bg": "--s1u",
-        "--tag-bg-hover": "--s1v",
-        "--tl-line": "--s1w",
-        "--tl-pad": "--s1x",
-        "--transition-fast": "--s1y",
-        "--transition-medium": "--s1z",
-        "--transition-normal": "--s20",
-        "--transition-slow": "--s21",
-        "--transition-slower": "--s22",
-        "--transition-slowest": "--s23",
-        "--un-rotate": "--s24",
-        "--un-rotate-x": "--s25",
-        "--un-rotate-y": "--s26",
-        "--un-rotate-z": "--s27",
-        "--un-scale-x": "--s28",
-        "--un-scale-y": "--s29",
-        "--un-scale-z": "--s2a",
-        "--un-skew-x": "--s2b",
-        "--un-skew-y": "--s2c",
-        "--un-translate-x": "--s2d",
-        "--un-translate-y": "--s2e",
-        "--un-translate-z": "--s2f",
-        "--updated-bg": "--s2g",
-        "--updated-border": "--s2h",
-        "--white-05p": "--s2i",
-        "--white-10p": "--s2j",
-        "--white-15p": "--s2k",
-        "--white-20p": "--s2l",
-        "--white-30p": "--s2m",
-        "--white-50p": "--s2n",
-        "--white-60p": "--s2o",
-        "--white-70p": "--s2p",
-        "--white-75p": "--s2q",
-        "--white-78p": "--s2r",
-        "--white-80p": "--s2s",
-        "--white-85p": "--s2t",
-        "--white-90p": "--s2u",
-        "--white-95p": "--s2v",
-        "--white-full": "--s2w"
+        "--stalux-site-header-min-height": "--s1r",
+        "--stalux-text-shadow": "--s1s",
+        "--surface-glass": "--s1t",
+        "--surface-glass-shadow": "--s1u",
+        "--tag-bg": "--s1v",
+        "--tag-bg-hover": "--s1w",
+        "--tl-line": "--s1x",
+        "--tl-pad": "--s1y",
+        "--transition-fast": "--s1z",
+        "--transition-medium": "--s20",
+        "--transition-normal": "--s21",
+        "--transition-slow": "--s22",
+        "--transition-slower": "--s23",
+        "--transition-slowest": "--s24",
+        "--un-rotate": "--s25",
+        "--un-rotate-x": "--s26",
+        "--un-rotate-y": "--s27",
+        "--un-rotate-z": "--s28",
+        "--un-scale-x": "--s29",
+        "--un-scale-y": "--s2a",
+        "--un-scale-z": "--s2b",
+        "--un-skew-x": "--s2c",
+        "--un-skew-y": "--s2d",
+        "--un-translate-x": "--s2e",
+        "--un-translate-y": "--s2f",
+        "--un-translate-z": "--s2g",
+        "--updated-bg": "--s2h",
+        "--updated-border": "--s2i",
+        "--white-05p": "--s2j",
+        "--white-10p": "--s2k",
+        "--white-15p": "--s2l",
+        "--white-20p": "--s2m",
+        "--white-30p": "--s2n",
+        "--white-50p": "--s2o",
+        "--white-60p": "--s2p",
+        "--white-70p": "--s2q",
+        "--white-75p": "--s2r",
+        "--white-78p": "--s2s",
+        "--white-80p": "--s2t",
+        "--white-85p": "--s2u",
+        "--white-90p": "--s2v",
+        "--white-95p": "--s2w",
+        "--white-full": "--s2x"
     },
     "animations": {
         "fadeInUpComment": "k0",

package/src/layouts/Stalux.astro

@@ -2,6 +2,7 @@
 import { getCollection } from "astro:content";
 import Footer from "@components/stalux/layout/footer.astro";
 import Head from "@components/stalux/layout/head.astro";
+import NavigationProgress from "@components/stalux/layout/navigationProgress.astro";
 import Navs from "@components/stalux/layout/navs.astro";
 import { getAccentColorStyle } from "@utils/accent-color";
 import {
@@ -11,7 +12,7 @@ import {
     getPromoteData,
     getSiteData,
 } from "@utils/config-utils";
-import { getRouteAnimation, getRouteKind } from "@utils/view-transitions";
+import { getRouteKind } from "@utils/view-transitions";
 
 const props = Astro.props as Props;
 
@@ -48,11 +49,14 @@ const llmPromote = llmPromoteRaw
     ?.replace(/\{title\}/g, siteConfig.title)
     ?.replace(/\{cc\}/g, "CC-BY-NC-SA-4.0");
 const routeKind = getRouteKind(Astro.url.pathname);
-const routeAnimation = getRouteAnimation(routeKind);
 ---
 
 <!doctype html>
-<html lang={htmlLang} style={getAccentColorStyle(siteConfig.accentColor)}>
+<html
+    lang={htmlLang}
+    style={getAccentColorStyle(siteConfig.accentColor)}
+    data-stalux-route={routeKind}
+>
     <Head
         title={props.title}
         description={props.description}
@@ -85,6 +89,7 @@ const routeAnimation = getRouteAnimation(routeKind);
         data-stalux-umami-id={headConfig?.umami?.id}
         data-stalux-umami-url={headConfig?.umami?.url}
     >
+        <NavigationProgress />
         <header
             class="stalux-site-header"
             data-stalux-font-group="header"
@@ -115,10 +120,8 @@ const routeAnimation = getRouteAnimation(routeKind);
         <main
             class="stalux-main"
             data-stalux-route={routeKind}
-            transition:name={routeKind === "article" ? "stalux-article-page" : "stalux-page"}
-            transition:animate={routeKind === "home" || routeKind === "article"
-                ? "none"
-                : routeAnimation}
+            transition:name="stalux-page"
+            transition:animate="none"
         >
             <slot />
         </main>

package/src/scripts/analytics-runtime.ts

@@ -1,6 +1,7 @@
 /** Async native SDKs keep live DOM events out of worker proxies during Astro swaps. */
 
 import { createClientLogger } from "./logger";
+import { prepareRouteMotion, type RouteMotionEvent } from "./route-motion";
 
 const logger = createClientLogger("analytics");
 
@@ -22,7 +23,7 @@ declare global {
 type AnalyticsHost = Window & {
     dataLayer?: unknown[];
     gtag?: (...args: unknown[]) => void;
-    clarity?: ((...args: unknown[]) => void) & { q: unknown[] };
+    clarity?: ((...args: unknown[]) => void) & { v?: string };
     umami?: { track: (payload: Record<string, unknown>) => unknown };
 };
 const host = window as AnalyticsHost;
@@ -30,17 +31,101 @@ window.__staluxAnalyticsRuntime ??= {};
 const state = window.__staluxAnalyticsRuntime;
 state.scripts ??= new Map();
 
-/** Never await analytics in a router callback; failed loads can retry on a later page. */
-function loadTrackerScript(src: string, attributes: Record<string, string> = {}): Promise<void> {
-    const existing = state.scripts?.get(src);
-    if (existing) return existing;
-    const script = document.createElement("script");
-    script.async = true;
-    script.fetchPriority = "low";
-    script.src = src;
-    for (const [name, value] of Object.entries(attributes)) script.setAttribute(name, value);
-    const loaded = new Promise<void>((resolve, reject) => {
+type GooglePage = {
+    ready: Promise<unknown>;
+    payload: {
+        page_location: string;
+        page_path: string;
+        page_title: string;
+        page_referrer: string;
+    };
+};
+const googlePages: GooglePage[] = [];
+let transitionReady: Promise<unknown> = Promise.resolve();
+let googleScheduled = false;
+let googleSchedule = 0;
+let googleTimer: ReturnType<typeof setTimeout> | undefined;
+let googleFrames: number[] = [];
+
+function cancelGoogleSchedule(): void {
+    googleSchedule++;
+    googleScheduled = false;
+    clearTimeout(googleTimer);
+    for (const frame of googleFrames) window.cancelAnimationFrame(frame);
+    googleFrames = [];
+}
+
+function sendGooglePage(page: GooglePage): void {
+    try {
+        host.gtag?.("event", "page_view", page.payload);
+    } catch {
+        logger.debug("Google page view unavailable; navigation remains usable");
+    }
+}
+
+/** The loaded Google SDK processes dataLayer.push synchronously and can read layout. */
+function scheduleGooglePages(): void {
+    const page = googlePages[0];
+    if (!page || googleScheduled) return;
+    googleScheduled = true;
+    const schedule = ++googleSchedule;
+    const run = () => {
+        if (schedule !== googleSchedule) return;
+        cancelGoogleSchedule();
+        const next = googlePages.shift();
+        if (next) sendGooglePage(next);
+        // A burst of visits stays FIFO, with a separate task for each SDK call.
+        scheduleGooglePages();
+    };
+    // A queued visit can outlive its own transition. Also wait for whichever
+    // incoming snapshot is current when this task is scheduled.
+    void Promise.all([page.ready, transitionReady]).then(() => {
+        if (schedule !== googleSchedule) return;
+        // Let the routed content paint after native rendering resumes and its own
+        // motion is installed. The timer also covers throttled/background frames.
+        googleTimer = setTimeout(run, 1000);
+        googleFrames.push(
+            window.requestAnimationFrame(() => {
+                if (schedule !== googleSchedule) return;
+                googleFrames.push(
+                    window.requestAnimationFrame(() => {
+                        if (schedule !== googleSchedule) return;
+                        const scheduler = (
+                            window as Window & {
+                                scheduler?: {
+                                    postTask: (
+                                        callback: () => void,
+                                        options: { priority: "background" },
+                                    ) => Promise<unknown>;
+                                };
+                            }
+                        ).scheduler;
+                        if (scheduler?.postTask) {
+                            void scheduler.postTask(run, { priority: "background" }).catch(() => {
+                                if (schedule === googleSchedule) setTimeout(run, 0);
+                            });
+                        } else setTimeout(run, 0);
+                    }),
+                );
+            }),
+        );
+    });
+}
+
+function flushGooglePages(): void {
+    cancelGoogleSchedule();
+    // Native gtag remains on the main thread for GA's own pagehide/engagement work.
+    // Do not leave a queued view behind when the document is hidden or unloaded.
+    for (const page of googlePages.splice(0)) sendGooglePage(page);
+}
+
+/** Monitor only a script created by this integration; a loaded tag stays intact. */
+function monitorTrackerScript(script: HTMLScriptElement, append = false): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        let settled = false;
         const finish = (error?: Error) => {
+            if (settled) return;
+            settled = true;
             clearTimeout(timer);
             script.onload = null;
             script.onerror = null;
@@ -52,8 +137,20 @@ function loadTrackerScript(src: string, attributes: Record<string, string> = {})
         const timer = setTimeout(() => finish(new Error("Analytics SDK load timed out")), 15_000);
         script.onload = () => finish();
         script.onerror = () => finish(new Error("Analytics SDK load failed"));
-        document.head.appendChild(script);
+        if (append) document.head.appendChild(script);
     });
+}
+
+/** Never await analytics in a router callback; failed loads can retry on a later page. */
+function loadTrackerScript(src: string, attributes: Record<string, string> = {}): Promise<void> {
+    const existing = state.scripts?.get(src);
+    if (existing) return existing;
+    const script = document.createElement("script");
+    script.async = true;
+    script.fetchPriority = "low";
+    script.src = src;
+    for (const [name, value] of Object.entries(attributes)) script.setAttribute(name, value);
+    const loaded = monitorTrackerScript(script, true);
     state.scripts?.set(src, loaded);
     void loaded.catch(() => {
         if (state.scripts?.get(src) === loaded) state.scripts.delete(src);
@@ -61,6 +158,50 @@ function loadTrackerScript(src: string, attributes: Record<string, string> = {})
     return loaded;
 }
 
+const CLARITY_SCRIPT_ID = "clarity-script";
+const CLARITY_LOADER_KEY = "clarity:npm";
+
+function hasExistingClarity(): boolean {
+    return Boolean(
+        host.clarity?.v ||
+            document.getElementById(CLARITY_SCRIPT_ID) ||
+            document.querySelector(
+                'script[data-stalux-clarity],script[src^="https://www.clarity.ms/tag/"]',
+            ),
+    );
+}
+
+function initializeClarity(id: string): void {
+    if (state.clarityId === id || state.scripts?.has(CLARITY_LOADER_KEY)) return;
+    state.clarityId = id;
+    // A preceding SDK or user-provided tag owns its own lifecycle. Never create
+    // a second loader or attach destructive retry handlers to that script.
+    if (hasExistingClarity()) return;
+    const initialized = import("@microsoft/clarity").then(({ default: clarity }) => {
+        // Another integration may have installed its tag while this chunk loaded.
+        if (hasExistingClarity()) return;
+        clarity.init(id);
+        const script = document.getElementById(CLARITY_SCRIPT_ID);
+        // Official init returns void and catches its own exceptions. Its inserted
+        // element is the observable loader, not the return value of init().
+        if (script?.tagName !== "SCRIPT") {
+            throw new Error("Clarity did not create its loader");
+        }
+        const tracker = script as HTMLScriptElement;
+        tracker.dataset.staluxClarity = "true";
+        tracker.fetchPriority = "low";
+        // Tag load does not establish that its remote core or collector is ready.
+        return monitorTrackerScript(tracker);
+    });
+    state.scripts?.set(CLARITY_LOADER_KEY, initialized);
+    void initialized.catch(() => {
+        if (state.scripts?.get(CLARITY_LOADER_KEY) !== initialized) return;
+        state.scripts.delete(CLARITY_LOADER_KEY);
+        if (state.clarityId === id) state.clarityId = undefined;
+        logger.debug("Clarity loader unavailable; a later navigation can retry");
+    });
+}
+
 function initializeTrackers(): void {
     const config = document.body?.dataset;
     if (!config) return;
@@ -82,32 +223,23 @@ function initializeTrackers(): void {
             { "data-stalux-google": "true" },
         ).catch(() => logger.debug("Google SDK unavailable; queued events retained"));
     }
-    if (config.staluxClarityId && state.clarityId !== config.staluxClarityId) {
-        host.clarity ??= Object.assign(
-            function (..._args: unknown[]) {
-                // biome-ignore lint/complexity/noArguments: Match the official Clarity queue format.
-                host.clarity?.q.push(arguments);
-            },
-            { q: [] as unknown[] },
-        );
-        const id = config.staluxClarityId;
-        state.clarityId = id;
-        void loadTrackerScript(`https://www.clarity.ms/tag/${encodeURIComponent(id)}`, {
-            "data-stalux-clarity": "true",
-        }).catch(() => {
-            if (state.clarityId === id) state.clarityId = undefined;
-            logger.debug("Clarity SDK unavailable; a later navigation can retry");
-        });
-    }
+    if (config.staluxClarityId) initializeClarity(config.staluxClarityId);
 }
 
 function trackGooglePage(): void {
     if (!state.googleId) return;
-    host.gtag?.("event", "page_view", {
-        page_location: window.location.href,
-        page_path: window.location.pathname + window.location.search,
-        page_title: document.title,
+    // Capture the visit before yielding: another navigation must not replace its
+    // URL, title or virtual referrer while the SDK is waiting for its task.
+    googlePages.push({
+        ready: transitionReady,
+        payload: {
+            page_location: window.location.href,
+            page_path: window.location.pathname + window.location.search,
+            page_title: document.title,
+            page_referrer: state.previousPage ?? document.referrer,
+        },
     });
+    scheduleGooglePages();
 }
 
 function trackUmamiPage(): void {
@@ -142,14 +274,26 @@ function trackVercountPage(): void {
     document.head.appendChild(script);
 }
 
-if (state.installed && (!state.native || state.revision !== 2)) {
+if (state.installed && (!state.native || state.revision !== 4)) {
+    // Revision 4 replaces synchronous Google page views and the motion policy.
     // An open tab can cross a deployment boundary. Its old anonymous worker
     // listeners cannot be detached safely; reload once to install the new runtime.
     window.location.reload();
 } else if (!state.installed) {
     state.native = true;
-    state.revision = 2;
+    state.revision = 4;
     state.installed = true;
+    document.addEventListener("astro:before-swap", (event) => {
+        transitionReady = prepareRouteMotion(event as Event & RouteMotionEvent).ready;
+        // Invalidate an older page's frames, timer and posted task before this
+        // incoming snapshot starts. Its captured visit remains in the FIFO.
+        cancelGoogleSchedule();
+        scheduleGooglePages();
+    });
+    window.addEventListener("pagehide", flushGooglePages);
+    document.addEventListener("visibilitychange", () => {
+        if (document.hidden) flushGooglePages();
+    });
     document.addEventListener("astro:page-load", () => {
         initializeTrackers();
         trackGooglePage();

package/src/scripts/background.ts

@@ -13,6 +13,7 @@
  *   先低优先级解码目标背景，等待内容过渡完成后再淡入，不与内容快照争抢绘制。
  */
 import { createClientLogger } from "./logger";
+import { prepareRouteMotion, type RouteMotionEvent } from "./route-motion";
 
 const logger = createClientLogger("background");
 
@@ -115,8 +116,7 @@ if (!(window as Window & { __STALUX_BG_LISTENER__?: boolean }).__STALUX_BG_LISTE
         prepared = connection?.saveData ? undefined : prepareBackground();
     });
     document.addEventListener("astro:before-swap", (event) => {
-        const transition = (event as Event & { viewTransition?: ViewTransition }).viewTransition;
-        transitionFinished = transition?.finished.catch(() => undefined) ?? Promise.resolve();
+        transitionFinished = prepareRouteMotion(event as RouteMotionEvent).finished;
     });
     document.addEventListener("astro:page-load", initializeBackground);
 }