@xingwangzhe/stalux 1.52.1 → 1.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.52.1",
+    "version": "1.54.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -112,9 +112,15 @@
         "@microsoft/clarity": "1.0.2",
         "@pagefind/component-ui": "^1.6.0",
         "@swup/a11y-plugin": "^5.2.1",
+        "@swup/body-class-plugin": "^3.3.0",
+        "@swup/fragment-plugin": "^1.3.1",
         "@swup/head-plugin": "^2.3.1",
         "@swup/js-plugin": "^3.2.0",
+        "@swup/parallel-plugin": "^0.4.0",
         "@swup/preload-plugin": "^3.2.12",
+        "@swup/progress-plugin": "^3.2.0",
+        "@swup/route-name-plugin": "^4.1.0",
+        "@swup/scripts-plugin": "^2.1.0",
         "@swup/scroll-plugin": "^4.0.0",
         "@takumi-rs/core": "2.19.0",
         "@waline/client": "^3.16.2",
@@ -139,23 +145,24 @@
     },
     "devDependencies": {
         "@astrojs/check": "^0.9.12",
-        "@biomejs/biome": "^2.6.4",
+        "@biomejs/biome": "^2.6.5",
+        "@swup/debug-plugin": "^4.1.0",
         "@types/bun": "1.4.4",
         "@types/css-tree": "^3.2.0",
         "@unocss/astro": "^66.12.0",
         "@vitest/coverage-v8": "^5.1.0",
-        "astro": "^7.4.5",
+        "astro": "^7.4.7",
         "happy-dom": "^21.0.4",
         "knip": "^6.44.1",
         "sharp": "0.35.5",
         "sonda": "^0.14.0",
         "typescript": "npm:@typescript/typescript6@6.0.2",
         "unocss": "^66.12.0",
-        "vite": "^8.3.5",
+        "vite": "^8.3.6",
         "vitest": "^5.1.0"
     },
     "peerDependencies": {
-        "astro": "^7.4.5"
+        "astro": "^7.4.7"
     },
     "overrides": {
         "satteri": "0.11.6"

package/src/components/stalux/posts/postContent.astro

@@ -40,6 +40,7 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/u, "")}.md` :
 ---
 
 <article
+    id="swup-article"
     class="stalux-article"
     data-stalux-motion-stage
     data-stalux-gallery={props.hasImage ? "true" : undefined}

package/src/env.d.ts

@@ -12,3 +12,8 @@ declare module "virtual:stalux-social-card-paths" {
     const paths: import("./internal/social-card-renderer").SocialCardPaths;
     export default paths;
 }
+
+declare module "virtual:stalux-swup-debug" {
+    const Debug: (new () => import("swup").Plugin) | null;
+    export default Debug;
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import { forEachBounded } from "./internal/bounded-tasks.ts";
 import { compactStylesPlugin } from "./internal/compact-styles.ts";
 import { modernCssTargets } from "./internal/modern-css.ts";
 import { styleNames } from "./internal/style-names.generated.ts";
+import { swupDebugPlugin } from "./internal/swup-debug-plugin.ts";
 /**
  * Stalux — Astro 博客主题集成入口
  *
@@ -182,6 +183,11 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             include: [
                                 "swup",
                                 "@swup/a11y-plugin",
+                                "@swup/body-class-plugin",
+                                "@swup/fragment-plugin",
+                                "@swup/parallel-plugin",
+                                "@swup/route-name-plugin",
+                                "@swup/scripts-plugin",
                                 "@swup/head-plugin",
                                 "@swup/js-plugin",
                                 "@swup/preload-plugin",
@@ -216,6 +222,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                                         ? `export default ${JSON.stringify(socialCardPaths)}`
                                         : undefined,
                             },
+                            swupDebugPlugin(command === "dev"),
                             searchStylePlugin(command === "dev", config.base),
                             webMcpMutationsPlugin(),
                             ...(command === "build"

package/src/internal/swup-debug-plugin.ts

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+import type { Plugin } from "vite";
+
+/** Keep a source-only devDependency optional in published consumer projects. */
+export function swupDebugPlugin(development: boolean): Plugin {
+    const id = "virtual:stalux-swup-debug";
+    let entry: string | undefined;
+    if (development) {
+        try {
+            entry = createRequire(import.meta.url).resolve("@swup/debug-plugin");
+        } catch {
+            // Consumers can install @swup/debug-plugin as their own devDependency.
+        }
+    }
+    return {
+        name: "stalux:swup-debug",
+        resolveId: (source) => (source === id ? `\0${id}` : undefined),
+        load: (source) =>
+            source === `\0${id}`
+                ? entry
+                    ? `export { default } from ${JSON.stringify(entry)};`
+                    : "export default null;"
+                : undefined,
+    };
+}

package/src/layouts/Stalux.astro

@@ -86,7 +86,7 @@ const routeKind = getRouteKind(Astro.url.pathname);
     </script>
     {aiConfig?.conformance !== "disabled" && <script>import "../scripts/webmcp.ts";</script>}
     <body
-        class="stalux-root dark"
+        class={`stalux-root dark page-${routeKind}`}
         data-stalux-bg-layer="a"
         data-stalux-bg-index="0"
         data-stalux-site-title={siteConfig.title}
@@ -116,7 +116,7 @@ const routeKind = getRouteKind(Astro.url.pathname);
             aria-hidden="true"
         ></div>
         <div class="bg-layer bg-b" data-stalux-background="b" aria-hidden="true"></div>
-        <main class="stalux-main" data-stalux-route={routeKind}>
+        <main id="swup-main" class="stalux-main" data-stalux-route={routeKind}>
             <slot />
         </main>
         <Footer />

package/src/pages/categories/[category].astro

@@ -32,6 +32,8 @@ const props = Astro.props as Props;
         count: props.count,
     })}
 >
-    <TagHeader type={t("taxonomy.category")} name={props.category} count={props.count} />
-    <PostList posts={props.posts} />
+    <div id="swup-taxonomy">
+        <TagHeader type={t("taxonomy.category")} name={props.category} count={props.count} />
+        <PostList posts={props.posts} />
+    </div>
 </Stalux>

package/src/pages/tags/[tag].astro

@@ -34,6 +34,8 @@ const props = Astro.props as Props;
     })}
     noindex={props.count < 3}
 >
-    <TagHeader type={t("taxonomy.tag")} name={props.tag} count={props.count} />
-    <PostList posts={props.posts} />
+    <div id="swup-taxonomy">
+        <TagHeader type={t("taxonomy.tag")} name={props.tag} count={props.count} />
+        <PostList posts={props.posts} />
+    </div>
 </Stalux>

package/src/scripts/navigation-scripts.ts

@@ -1,84 +1,10 @@
+import SwupScriptsPlugin from "@swup/scripts-plugin";
 import { createClientLogger } from "./logger";
 
 const logger = createClientLogger("navigation-scripts");
 const executions = new Map<string, Promise<void>>();
-const executedNodes = new WeakSet<HTMLScriptElement>();
 let seeded = false;
-
-interface NavigationScript {
-    attributes: { name: string; value: string }[];
-    content: string;
-    source?: string;
-    type: string;
-    key: string;
-    rerun: boolean;
-    head: boolean;
-    original: HTMLScriptElement;
-}
-
-const JAVASCRIPT_TYPES = new Set([
-    "",
-    "module",
-    "text/javascript",
-    "application/javascript",
-    "text/ecmascript",
-    "application/ecmascript",
-]);
-
-function describeScript(script: HTMLScriptElement, base: string): NavigationScript | undefined {
-    const type = (script.getAttribute("type") ?? "").trim().toLowerCase();
-    if (!JAVASCRIPT_TYPES.has(type) || script.hasAttribute("data-swup-ignore-script")) return;
-    if (script.hasAttribute("nomodule") && "noModule" in document.createElement("script")) return;
-    const rawSource = script.getAttribute("src");
-    let source: string | undefined;
-    if (rawSource !== null) {
-        try {
-            source = new URL(rawSource, base).href;
-        } catch {
-            return;
-        }
-    }
-    const content = script.textContent ?? "";
-    return {
-        attributes: [...script.attributes].map(({ name, value }) => ({ name, value })),
-        content,
-        source,
-        type,
-        key: source ? `src:${source}` : `inline:${type}:${content}`,
-        rerun: script.hasAttribute("data-astro-rerun"),
-        head: script.parentElement?.tagName === "HEAD",
-        original: script,
-    };
-}
-
-function seedCurrentScripts(): void {
-    if (seeded) return;
-    seeded = true;
-    for (const script of document.querySelectorAll<HTMLScriptElement>("script")) {
-        const descriptor = describeScript(script, document.baseURI);
-        if (descriptor) {
-            executions.set(descriptor.key, Promise.resolve());
-            executedNodes.add(script);
-        }
-    }
-}
-
-function waitForScript(script: HTMLScriptElement, timeoutMs: number): Promise<boolean> {
-    return new Promise((resolve) => {
-        let timer: ReturnType<typeof setTimeout>;
-        const finish = (loaded: boolean) => {
-            clearTimeout(timer);
-            script.removeEventListener("load", loadedHandler);
-            script.removeEventListener("error", failedHandler);
-            resolve(loaded);
-        };
-        const loadedHandler = () => finish(true);
-        const failedHandler = () => finish(false);
-        script.addEventListener("load", loadedHandler, { once: true });
-        script.addEventListener("error", failedHandler, { once: true });
-        timer = setTimeout(failedHandler, timeoutMs);
-    });
-}
+const executedNodes = new WeakSet<HTMLScriptElement>();
 
 function abortable(promise: Promise<void>, signal?: AbortSignal): Promise<void> {
     if (!signal) return promise;
@@ -92,100 +18,141 @@ function abortable(promise: Promise<void>, signal?: AbortSignal): Promise<void>
         void promise.then(finish, finish);
     });
 }
+const javascript = new Set([
+    "",
+    "module",
+    "text/javascript",
+    "application/javascript",
+    "text/ecmascript",
+    "application/ecmascript",
+]);
 
-function executeScript(descriptor: NavigationScript, timeoutMs: number): Promise<void> {
-    // HeadPlugin clones incoming head nodes before container replacement. Those
-    // scripts are inert, but are different nodes from the parsed document we
-    // captured. Replace that clone rather than appending a second head script.
-    const inertCopies = [...document.querySelectorAll<HTMLScriptElement>("script")].filter(
-        (candidate) =>
-            !executedNodes.has(candidate) &&
-            describeScript(candidate, document.baseURI)?.key === descriptor.key,
-    );
-    const existing = executions.get(descriptor.key);
-    if (existing && !descriptor.rerun) {
-        for (const copy of inertCopies) copy.remove();
-        return existing;
-    }
-
-    const script = document.createElement("script");
-    // Dynamic scripts are async by default. Preserve document order, including
-    // the module barrier used below, before copying the page's attributes.
-    script.async = false;
-    for (const { name, value } of descriptor.attributes) {
-        if (name !== "src" && name !== "data-astro-exec") script.setAttribute(name, value);
-    }
-    if (descriptor.source) script.setAttribute("src", descriptor.source);
-    script.textContent = descriptor.content;
-    script.setAttribute("data-astro-exec", "");
-    executedNodes.add(script);
-
-    let observed = script;
-    if (!descriptor.source && descriptor.type === "module") {
-        // Inline module load events are not portable. Astro uses the same
-        // ordered external module barrier to wait for deferred inline modules.
-        observed = document.createElement("script");
-        observed.type = "module";
-        observed.async = false;
-        observed.src = "data:application/javascript,";
-        observed.setAttribute("data-swup-ignore-script", "");
-        if (script.nonce) observed.nonce = script.nonce;
-    }
-    const loaded =
-        descriptor.source || descriptor.type === "module"
-            ? waitForScript(observed, timeoutMs)
-            : Promise.resolve(true);
-    const execution = loaded.then((success) => {
-        if (observed !== script) observed.remove();
-        if (!success) {
-            // Failed fetches may succeed on a subsequent visit. Do not turn a
-            // transient offline response into a session-long disabled feature.
-            if (executions.get(descriptor.key) === execution) executions.delete(descriptor.key);
-            script.remove();
-            logger.warn(`page script failed to load: ${descriptor.source ?? "inline module"}`);
-        }
-    });
-    executions.set(descriptor.key, execution);
+/**
+ * Scripts Plugin owns script recreation. Astro's page-load event additionally
+ * needs an ordered completion barrier and once-per-session module semantics.
+ * Disable the plugin's automatic whole-document pass: that would also replay
+ * analytics SDKs and scripts in retained shells on every navigation.
+ */
+export const navigationScripts = new SwupScriptsPlugin({ head: false, body: false });
 
-    const parent = descriptor.head ? document.head : document.body;
-    const original =
-        descriptor.original.isConnected && descriptor.original.ownerDocument === document
-            ? descriptor.original
-            : inertCopies[0];
-    if (original) {
-        original.replaceWith(script);
-    } else {
-        parent.append(script);
-    }
-    for (const copy of inertCopies) if (copy !== original) copy.remove();
-    if (observed !== script) parent.append(observed);
-    return execution;
+function describeScript(script: HTMLScriptElement, base: string) {
+    const type = (script.getAttribute("type") ?? "").trim().toLowerCase();
+    if (!javascript.has(type) || script.hasAttribute("data-swup-ignore-script")) return;
+    if (script.hasAttribute("nomodule")) return;
+    const source = script.getAttribute("src");
+    const src = source === null ? undefined : new URL(source, base).href;
+    return {
+        script,
+        src,
+        type,
+        key: src ? `src:${src}` : `inline:${type}:${script.textContent ?? ""}`,
+        rerun:
+            script.hasAttribute("data-astro-rerun") ||
+            script.hasAttribute("data-swup-reload-script"),
+        head: script.parentElement?.tagName === "HEAD",
+    };
 }
 
-/**
- * Capture both head and body before Swup replaces the document's containers.
- * Call the returned function after replacement, before astro:page-load. Bundled
- * modules and ordinary inline scripts retain Astro's once-per-session behavior;
- * data-astro-rerun opts a script into every visit. SDK scripts already present in
- * the first document are never reinserted merely because head metadata changed.
- */
+/** Capture before Parallel moves incoming containers out of the parsed document. */
 export function prepareNavigationScripts(
-    nextDocument: Document,
+    next: Document,
     options: { timeoutMs?: number; baseUrl?: string } = {},
-): (signal?: AbortSignal) => Promise<void> {
-    seedCurrentScripts();
-    const base = options.baseUrl ?? nextDocument.baseURI ?? document.baseURI;
-    const scripts = [...nextDocument.querySelectorAll<HTMLScriptElement>("script")]
-        .map((script) => describeScript(script, base))
-        .filter((script): script is NavigationScript => script !== undefined);
-    let executed: Promise<void> | undefined;
-    return (signal) => {
-        executed ??= (async () => {
-            for (const script of scripts) {
+) {
+    if (!seeded) {
+        seeded = true;
+        for (const script of document.querySelectorAll<HTMLScriptElement>("script")) {
+            const item = describeScript(script, document.baseURI);
+            if (item) {
+                executions.set(item.key, Promise.resolve());
+                executedNodes.add(script);
+            }
+        }
+    }
+    const scripts = [...next.querySelectorAll<HTMLScriptElement>("script")]
+        .map((script) =>
+            describeScript(script, options.baseUrl ?? next.baseURI ?? document.baseURI),
+        )
+        .filter((item) => item !== undefined)
+        .map((item) => ({
+            ...item,
+            original: item.script,
+            script: item.script.cloneNode(true) as HTMLScriptElement,
+        }));
+    let execution: Promise<void> | undefined;
+    return (signal?: AbortSignal): Promise<void> => {
+        execution ??= (async () => {
+            for (const item of scripts) {
                 if (signal?.aborted) return;
-                await abortable(executeScript(script, options.timeoutMs ?? 15_000), signal);
+                const existing = executions.get(item.key);
+                if (existing && !item.rerun) {
+                    for (const copy of document.querySelectorAll<HTMLScriptElement>("script")) {
+                        if (
+                            !executedNodes.has(copy) &&
+                            describeScript(copy, document.baseURI)?.key === item.key
+                        )
+                            copy.remove();
+                    }
+                    await abortable(existing, signal);
+                    continue;
+                }
+                const inert = item.script.cloneNode(true) as HTMLScriptElement;
+                if (item.src) inert.setAttribute("src", item.src);
+                inert.async = false;
+                inert.setAttribute("data-astro-exec", "");
+                // Reuse HeadPlugin's inert clone, or the inserted body script.
+                // Scripts outside replaced fragments are staged only if new.
+                const copy =
+                    (item.original.isConnected && item.original.ownerDocument === document
+                        ? item.original
+                        : undefined) ??
+                    [...document.querySelectorAll<HTMLScriptElement>("script")].find(
+                        (script) =>
+                            !executedNodes.has(script) &&
+                            describeScript(script, document.baseURI)?.key === item.key,
+                    );
+                if (copy) copy.replaceWith(inert);
+                else (item.head ? document.head : document.body).append(inert);
+                const script = navigationScripts.runScript(inert);
+                script.async = false;
+                executedNodes.add(script);
+                let observed = script;
+                if (!item.src && item.type === "module") {
+                    observed = document.createElement("script");
+                    observed.type = "module";
+                    observed.async = false;
+                    observed.src = "data:application/javascript,";
+                    observed.setAttribute("data-swup-ignore-script", "");
+                    if (script.nonce) observed.nonce = script.nonce;
+                    document.body.append(observed);
+                }
+                const ready =
+                    item.src || item.type === "module"
+                        ? new Promise<void>((resolve) => {
+                              const finish = (failed = false) => {
+                                  clearTimeout(timer);
+                                  observed.removeEventListener("load", loaded);
+                                  observed.removeEventListener("error", failedHandler);
+                                  if (observed !== script) observed.remove();
+                                  if (failed) {
+                                      executions.delete(item.key);
+                                      script.remove();
+                                      logger.warn(
+                                          `page script failed to load: ${item.src ?? "inline module"}`,
+                                      );
+                                  }
+                                  resolve();
+                              };
+                              const loaded = () => finish();
+                              const failedHandler = () => finish(true);
+                              const timer = setTimeout(failedHandler, options.timeoutMs ?? 15_000);
+                              observed.addEventListener("load", loaded, { once: true });
+                              observed.addEventListener("error", failedHandler, { once: true });
+                          })
+                        : Promise.resolve();
+                executions.set(item.key, ready);
+                await abortable(ready, signal);
             }
         })();
-        return executed;
+        return execution;
     };
 }

package/src/scripts/swup-router.ts

@@ -1,7 +1,12 @@
 import SwupA11yPlugin from "@swup/a11y-plugin";
+import SwupBodyClassPlugin from "@swup/body-class-plugin";
+import SwupFragmentPlugin from "@swup/fragment-plugin";
 import SwupHeadPlugin from "@swup/head-plugin";
 import SwupJsPlugin from "@swup/js-plugin";
+import SwupParallelPlugin from "@swup/parallel-plugin";
 import SwupPreloadPlugin from "@swup/preload-plugin";
+import SwupProgressPlugin from "@swup/progress-plugin";
+import SwupRouteNamePlugin from "@swup/route-name-plugin";
 import SwupScrollPlugin from "@swup/scroll-plugin";
 import Swup, { type Visit } from "swup";
 import { getRouteKind } from "../utils/public-routes";
@@ -9,7 +14,7 @@ import { getRouteMotionPreset, type RouteMotionPreset } from "../utils/route-mot
 import { installBackToTop } from "./back-to-top";
 import { prepareNavigationFont } from "./navigation-font";
 import "./navigation-client";
-import { prepareNavigationScripts } from "./navigation-scripts";
+import { navigationScripts, prepareNavigationScripts } from "./navigation-scripts";
 import { prepareRouteMotion, type RouteMotion } from "./route-motion";
 import { animateRouteOut } from "./route-out";
 import { hydrateShells, markRetainedShells } from "./shell-hydration";
@@ -27,13 +32,16 @@ interface NavigationContext {
     motion?: RouteMotion;
     executeScripts?: (signal?: AbortSignal) => Promise<void>;
     scriptsReady?: Promise<void>;
+    outgoingReady?: Promise<void>;
+    incomingDocument?: Document;
+    removeOutgoing?: () => void;
     obsoleteStyles: Element[];
     glide?: PageGlide;
     releaseOutgoing?: () => void;
 }
 
 type Position = { top: number; left: number; focus?: string };
-const MAIN = "main[data-stalux-route]";
+const MAIN = "#swup-main";
 
 function abortObsoleteVisit(visit: Visit): void {
     // `abort()` is @internal in swup 4.10.0 and stripped from the published
@@ -82,6 +90,7 @@ export function installSwupRouter(): Swup {
     let activeContext: NavigationContext | undefined;
     let visibleHistoryIndex = Number(window.history.state?.index ?? 1);
     let browserMotion = false;
+    const progress = new SwupProgressPlugin();
     const scroll = new SwupScrollPlugin({
         doScrollingRightAway: false,
         animateScroll: { betweenPages: false, samePageWithHash: true, samePage: true },
@@ -117,6 +126,42 @@ export function installSwupRouter(): Swup {
             );
         },
         plugins: [
+            navigationScripts,
+            new SwupBodyClassPlugin({
+                prefix: "page-",
+                attributes: [/^data-stalux-(?!bg-)/u],
+            }),
+            new SwupRouteNamePlugin({
+                routes: [
+                    { name: "home", path: "/" },
+                    { name: "article", path: "/posts/:post" },
+                    { name: "archive", path: "/archives" },
+                    { name: "tags-index", path: "/tags" },
+                    { name: "tags-detail", path: "/tags/:tag" },
+                    { name: "categories-index", path: "/categories" },
+                    { name: "categories-detail", path: "/categories/:category" },
+                    ...["about", "links", "words"].map((name) => ({ name, path: "/" + name })),
+                    { name: "not-found", path: "/404" },
+                ],
+            }),
+            new SwupFragmentPlugin({
+                rules: [
+                    {
+                        from: ["/tags/:slug", "/categories/:slug"],
+                        to: ["/tags/:slug", "/categories/:slug"],
+                        containers: ["#swup-taxonomy"],
+                        scroll: true,
+                    },
+                    {
+                        from: "/posts/:post",
+                        to: "/posts/:post",
+                        containers: ["#swup-article"],
+                        scroll: true,
+                    },
+                ],
+            }),
+            new SwupParallelPlugin({ containers: [MAIN, "#swup-article", "#swup-taxonomy"] }),
+            progress,
             new SwupHeadPlugin({
                 awaitAssets: true,
                 // Keep old CSS readable until replacement, then prune authored
@@ -151,13 +196,18 @@ export function installSwupRouter(): Swup {
                                     releaseOutgoing: context.releaseOutgoing,
                                 },
                             );
-                            await context.motion.finished;
+                            await Promise.all([context.motion.finished, context.outgoingReady]);
                         },
                     },
                 ],
             }),
         ],
     });
+    if (import.meta.env.DEV) {
+        void import("virtual:stalux-swup-debug").then(({ default: Debug }) => {
+            if (Debug) swup.use(new Debug());
+        });
+    }
     window.swup = swup;
     document.documentElement.dataset.staluxRouter = "swup";
     document.documentElement.dataset.staluxRoute = getRouteKind(window.location.pathname);
@@ -219,6 +269,7 @@ export function installSwupRouter(): Swup {
         contexts.set(visit, context);
         activeContext = context;
         visit.animation.wait = true;
+        if (context.preset === "none" || visit.history.popstate) visit.animation.parallel = false;
         visit.a11y.focus = visit.history.popstate ? false : { selector: MAIN, wait: true };
         if (dispatchNavigation("astro:before-preparation", context).defaultPrevented)
             visit.ignore();
@@ -232,6 +283,52 @@ export function installSwupRouter(): Swup {
             abortObsoleteVisit(visit);
     });
 
+    swup.hooks.before("content:insert", (visit, { containers }) => {
+        const context = contexts.get(visit);
+        if (!context) return;
+        context.motion = prepareRouteMotion(
+            dispatchNavigation("astro:before-swap", context, context.incomingDocument),
+        );
+        markRetainedShells();
+        const animations: Animation[] = [];
+        for (const { previous } of containers) {
+            const rect = previous.getBoundingClientRect();
+            previous.inert = true;
+            // The incoming document owns IDs and focus as soon as it is inserted.
+            // Persisted shells are moved by Swup and retain their original IDs.
+            for (const element of [previous, ...previous.querySelectorAll("[id]")]) {
+                if (!element.closest("[data-swup-persist]")) element.removeAttribute("id");
+            }
+            Object.assign(previous.style, {
+                position: "fixed",
+                top: rect.top + "px",
+                left: rect.left + "px",
+                width: rect.width + "px",
+                height: rect.height + "px",
+                // Clip the visible slice without truncating a deeply scrolled article.
+                clipPath: `inset(${Math.max(0, -rect.top)}px 0 ${Math.max(0, rect.bottom - window.innerHeight)}px 0)`,
+                overflow: "hidden",
+                pointerEvents: "none",
+                zIndex: "1",
+            });
+            animations.push(
+                previous.animate(
+                    { opacity: [1, 0], transform: ["translateY(0)", "translateY(-12px)"] },
+                    { duration: 160, easing: "ease-out", fill: "forwards" },
+                ),
+            );
+        }
+        const remove = () => {
+            for (const animation of animations) animation.cancel();
+            for (const { previous } of containers) previous.remove();
+        };
+        context.removeOutgoing = once(remove);
+        context.controller.signal.addEventListener("abort", context.removeOutgoing, { once: true });
+        context.outgoingReady = Promise.all(
+            animations.map((animation) => animation.finished.catch(() => {})),
+        ).then(() => context.removeOutgoing?.());
+    });
+
     swup.hooks.before(
         "content:replace",
         async (visit) => {
@@ -250,6 +347,7 @@ export function installSwupRouter(): Swup {
                 abortObsoleteVisit(visit);
                 return;
             }
+            context.incomingDocument = next.cloneNode(true) as Document;
             const incoming = [...next.head.querySelectorAll("style,link[rel=stylesheet]")];
             context.obsoleteStyles = authoredStyles.filter(
                 (el) => !incoming.some((other) => el.isEqualNode(other)),
@@ -273,7 +371,11 @@ export function installSwupRouter(): Swup {
         // Two cues overlap on the outgoing document: the content stage leaving,
         // and the page walking back to the top. Persisted sidebars, the header
         // and the frame are never part of either one.
-        if (context.navigationType !== "traverse" && context.preset !== "none") {
+        if (
+            !visit.animation.parallel &&
+            context.navigationType !== "traverse" &&
+            context.preset !== "none"
+        ) {
             const outgoing = animateRouteOut(context.preset, context.controller.signal);
             if (!context.to.hash) context.glide = glideToTop();
             await context.glide?.promise;
@@ -288,8 +390,12 @@ export function installSwupRouter(): Swup {
         html.dataset.staluxVtTo = getRouteKind(context.to.pathname);
         html.dataset.staluxVtDirection = context.direction;
         html.dataset.staluxVtPreset = context.preset;
-        context.motion = prepareRouteMotion(dispatchNavigation("astro:before-swap", context, next));
         if (context.controller.signal.aborted) return;
+        if (!visit.animation.parallel) {
+            context.motion = prepareRouteMotion(
+                dispatchNavigation("astro:before-swap", context, next),
+            );
+        }
         // Remember which shells exist now: after the swap only those slots need
         // refilling, because only those nodes came from the previous document.
         markRetainedShells();
@@ -306,20 +412,13 @@ export function installSwupRouter(): Swup {
         );
         // Main alone is replaced: header/footer/sentinel and background layers
         // keep their node identities. Never reset live background state to SSR 0.
-        for (const { name, value } of [...next.body.attributes]) {
-            if (
-                name.startsWith("data-stalux-") &&
-                name !== "data-stalux-bg-index" &&
-                name !== "data-stalux-bg-layer"
-            )
-                document.body.setAttribute(name, value);
-        }
-        html.dataset.staluxRoute = getRouteKind(context.to.pathname);
+        html.dataset.staluxRoute = visit.to.route ?? getRouteKind(context.to.pathname);
+        document.querySelector(MAIN)?.setAttribute("data-stalux-route", html.dataset.staluxRoute);
         visibleHistoryIndex = Number(window.history.state?.index ?? visibleHistoryIndex);
         // Kept shells whose contents belong to the page (the article sidebars'
         // lists) take their children from the incoming document now, before any
         // page module mounts, so nothing needs to re-render or re-measure later.
-        hydrateShells(next);
+        hydrateShells(context.incomingDocument ?? next);
         dispatchNavigation("astro:after-swap", context, next);
         // The entry cue has to own the first painted frame of the new document.
         // content:scroll is an await and a rAF away, and running the incoming
@@ -375,7 +474,8 @@ export function installSwupRouter(): Swup {
             }
             await defaultScroll?.(visit, args);
             // ScrollPlugin scrolls in rAF; finish it before heading visibility checks.
-            await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+            if (!document.hidden)
+                await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
             startMotion(visit);
             return true;
         },
@@ -407,8 +507,12 @@ export function installSwupRouter(): Swup {
     swup.hooks.replace("link:self", () => undefined);
 
     const cancel = (visit: Visit) => {
+        // A cancelled/failed visit never reaches page:view. Clear its delayed
+        // indicator without allowing a stale visit to hide a newer one.
+        if (visit === swup.visit) progress.stopShowingProgress();
         const context = contexts.get(visit);
         context?.controller.abort();
+        context?.removeOutgoing?.();
         context?.glide?.cancel();
         // An aborted visit keeps no exit fill: without this the stage would stay
         // transparent until the next successful navigation.

package/src/styles/module-motion.css

@@ -172,3 +172,16 @@ pagefind-modal dialog::backdrop {
         animation: none !important;
     }
 }
+
+/* The official plugin prepends its defaults; keep theme color authoritative. */
+html .swup-progress-bar {
+    height: 3px;
+    background-color: var(--stalux-accent-color);
+    pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    html .swup-progress-bar {
+        transition: none;
+    }
+}