@xingwangzhe/stalux 1.56.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.56.0",
+    "version": "1.58.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -22,6 +22,8 @@
     "engines": {
         "bun": ">=1.4.0"
     },
+    "// browserslist": "现代基线，与 src/internal/modern-css.ts 的 lightningcss targets 保持一致；当前构建不使用 autoprefixer/postcss，此字段用于声明目标并约束后续工具链。",
+    "browserslist": ["chrome >= 154", "firefox >= 157", "safari >= 26.6"],
     "bin": {
         "stalux": ".release/cli.mjs"
     },
@@ -110,17 +112,7 @@
         "@lucide/astro": "^1.71.0",
         "@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",
+        "@swup/astro": "^1.8.0",
         "@takumi-rs/core": "^2.20.0",
         "@w3c/webmcp-polyfill": "^0.1.0",
         "@waline/client": "^3.16.2",

package/src/components/stalux/archives/archivesList.astro

@@ -98,7 +98,7 @@ const archiveYears = [...archivesByYearMonth.entries()]
                                                 )}
                                             </time>
                                             <a
-                                                href={`/posts/${post.data.abbrlink}/`}
+                                                href={`/posts/${post.data.abbrlink}`}
                                                 class="stalux-archive-post-link"
                                                 data-archive-description={post.data.desc || ""}
                                             >

package/src/components/stalux/categories/categoriesCard.astro

@@ -23,7 +23,7 @@ const { t } = createTranslator((siteConfig.lang as string) || "zh-CN");
 <!-- Modern Web Guidance (html): 分类卡本身即 <article>；外层曾经的 <div class="stalux-category-shell">
      已上移到列表的 <li>（见 categoriesList.astro），避免多一层无语义容器。 -->
 <article class="stalux-category-card" data-stalux-control="category-card">
-    <a href={`/categories/${props.category.name}/`} class="stalux-categoryheader a-none">
+    <a href={`/categories/${props.category.name}`} class="stalux-categoryheader a-none">
         <span class="stalux-category-icon">
             <svg
                 aria-hidden="true"

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

@@ -51,7 +51,7 @@ const cfg = {
         <ul class={cfg.listClass} data-stalux-reveal>
             {items.map((item) => (
                 <li data-stalux-reveal-item>
-                    <a href={`${cfg.prefix}${item}/`} class={`${cfg.itemClass} a-none`}>
+                    <a href={`${cfg.prefix}${item}`} class={`${cfg.itemClass} a-none`}>
                         {item}
                     </a>
                 </li>

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

@@ -27,7 +27,7 @@ const description = post.data.desc || "";
     class="stalux-post-card-shell stalux-post-card h-full text-inherit no-underline stalux-u-flex stalux-u-flex-col stalux-u-w-full stalux-u-min-w-0"
 >
     {post.data.cover && (
-        <a href={`/posts/${post.data.abbrlink}/`} class="a-none" aria-label={post.data.title}>
+        <a href={`/posts/${post.data.abbrlink}`} class="a-none" aria-label={post.data.title}>
             <span class="stalux-card-post-cover stalux-u-w-full stalux-u-min-w-0">
                 <img
                     src={post.data.cover}
@@ -43,7 +43,7 @@ const description = post.data.desc || "";
         </a>
     )}
     <h2 class="stalux-card-post-title">
-        <a href={`/posts/${post.data.abbrlink}/`} class="a-none">
+        <a href={`/posts/${post.data.abbrlink}`} class="a-none">
             {post.data.title}
         </a>
     </h2>
@@ -90,5 +90,5 @@ const description = post.data.desc || "";
             ))}
         </ul>
     </footer>
-    <a href={`/posts/${post.data.abbrlink}/`} class="stalux-card-read-more a-none"> Read More </a>
+    <a href={`/posts/${post.data.abbrlink}`} class="stalux-card-read-more a-none"> Read More </a>
 </article>

package/src/components/stalux/tags/tagHeader.astro

@@ -21,9 +21,9 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
 const typeKey = props.typeKey || props.type;
 let typeUrl = "";
 if (typeKey === "category" || typeKey === "categories" || typeKey === "分类") {
-    typeUrl = "/categories/";
+    typeUrl = "/categories";
 } else if (typeKey === "tag" || typeKey === "tags" || typeKey === "标签") {
-    typeUrl = "/tags/";
+    typeUrl = "/tags";
 }
 ---
 

package/src/components/stalux/tags/tagsCloud.astro

@@ -17,7 +17,7 @@ const cloudDensity = Math.sqrt(Math.max(tagList.length, 100) / 100);
 const tagLinks = tagList.map((t) => ({
     type: "link" as const,
     text: t.name,
-    url: `/tags/${t.name}/`,
+    url: `/tags/${t.name}`,
 }));
 ---
 
@@ -36,7 +36,7 @@ const tagLinks = tagList.map((t) => ({
                 {group.map(({ name, count }) => (
                     <li data-stalux-reveal-item>
                         <a
-                            href={`/tags/${name}/`}
+                            href={`/tags/${name}`}
                             class="stalux-cloud-tag-card"
                             data-stalux-card
                             data-stalux-tag-card

package/src/index.ts

@@ -4,6 +4,7 @@ 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";
+import { SWUP_OPTIONS } from "./internal/swup-options.ts";
 /**
  * Stalux — Astro 博客主题集成入口
  *
@@ -18,6 +19,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import sitemap from "@astrojs/sitemap";
+import swup from "@swup/astro";
 import { mermaidHast, mermaidMdast } from "@xingwangzhe/satteri-mermaid";
 import { photoswipe } from "@xingwangzhe/satteri-photoswipe";
 import type { AstroIntegration } from "astro";
@@ -53,6 +55,7 @@ import { createPageOutputCache } from "./internal/page-output-cache";
 import { loadCoverEncoder, restoreCoverFiles, upgradeCoverImages } from "./internal/post-cover";
 import { isPluginProject } from "./internal/project-mode";
 import { syncBackgroundSvgs, syncFontAssets } from "./internal/public-assets";
+import { normalizeRouteHrefs } from "./internal/route-hrefs";
 import { createRuntimeCacheKey } from "./internal/runtime-cache-key";
 import {
     appendUniquePlugin,
@@ -180,17 +183,20 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             // Vite re-optimization would otherwise reload the
                             // entire document midway through a Swup navigation.
                             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",
-                                "@swup/scroll-plugin",
+                                // The router and its plugins are assembled by
+                                // @swup/astro and imported through its client
+                                // entry points, so those are the specifiers Vite
+                                // has to see up front.
+                                "@swup/astro/serialise",
+                                "@swup/astro/client/Swup",
+                                "@swup/astro/client/SwupA11yPlugin",
+                                "@swup/astro/client/SwupBodyClassPlugin",
+                                "@swup/astro/client/SwupFragmentPlugin",
+                                "@swup/astro/client/SwupHeadPlugin",
+                                "@swup/astro/client/SwupPreloadPlugin",
+                                "@swup/astro/client/SwupProgressPlugin",
+                                "@swup/astro/client/SwupRouteNamePlugin",
+                                "@swup/astro/client/SwupScrollPlugin",
                                 "@microsoft/clarity",
                                 "@pagefind/component-ui",
                                 "@waline/client",
@@ -244,6 +250,12 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 // 2. 注入全局 CSS
                 injectScript("page-ssr", `import "${srcDir}/styles/generated.css";`);
                 injectScript("page", `import "${srcDir}/scripts/core-runtime.ts";`);
+                // 路由层：@swup/astro 负责装配实例与插件，这里只挂三个护栏
+                // （脚本去重执行、过期 visit 中止、过期样式剪枝）。
+                injectScript(
+                    "page",
+                    `import { installRouteGuards } from "${srcDir}/scripts/route-guards.ts"; installRouteGuards();`,
+                );
 
                 // 3. 注入所有页面路由（仅插件模式，源码模式下使用文件路由）
                 if (isPluginMode) {
@@ -529,6 +541,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     promoteCodeStyles(document);
                     containMermaidSvgs(document);
                     removePageFontStyles(document);
+                    // 正文里手写的 /posts/x/ 也统一成路由器实际提供的形态
+                    normalizeRouteHrefs(document);
                     const images = findHtmlImages(before, document);
                     await updateLocalImageDimensions(images, outDir, {
                         cache: dimensionsCache,
@@ -676,8 +690,10 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
     };
 
     // 打包内置集成：Astro 的 integrations 配置支持嵌套数组并自动展平（schema 里 val.flat(Infinity)），
-    // 因此这里返回 [coreIntegration, sitemap, expressiveCode]，让消费方一行 `integrations: [stalux()]` 即可完成配置。
-    const bundled: AstroIntegration[] = [coreIntegration];
+    // 因此这里返回 [swup, coreIntegration, sitemap, expressiveCode]，让消费方一行 `integrations: [stalux()]` 即可完成配置。
+    // 路由器必须排在第一位：@swup/astro 先注入初始化脚本，主题的护栏脚本才能在同一轮
+    // 模块求值里直接拿到 window.swup。
+    const bundled: AstroIntegration[] = [swup(SWUP_OPTIONS), coreIntegration];
 
     if (opt.sitemap !== false) {
         const userSitemap = opt.sitemap === true ? undefined : opt.sitemap;
@@ -740,6 +756,16 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 ...userSitemap,
                 customPages,
                 filter,
+                // Page routes are served without a trailing slash; keep the root
+                // and real files (`.md`, `.json`, `.xml`, images) exactly as built.
+                async serialize(item) {
+                    const next = userSitemap?.serialize ? await userSitemap.serialize(item) : item;
+                    if (!next) return next;
+                    const url = new URL(next.url);
+                    if (url.pathname !== "/") url.pathname = url.pathname.replace(/\/+$/u, "");
+                    next.url = url.href;
+                    return next;
+                },
             }),
             {
                 name: "stalux/sitemap-alias",

package/src/internal/html-output.ts

@@ -1,4 +1,5 @@
 import { type DefaultTreeAdapterMap, serialize, serializeOuter } from "parse5";
+import { normalizeRouteHref } from "./route-hrefs";
 
 type Element = DefaultTreeAdapterMap["element"];
 
@@ -17,6 +18,9 @@ export function createHtmlMutationEmitter(
         attrs: Element["attrs"];
         text: string[];
     }> = [];
+    // Anchor hrefs are rewritten by value range only: reserializing the whole
+    // element would re-escape attribute text the emitter never touched.
+    const hrefSnapshots: Array<{ node: Element; start: number; end: number }> = [];
     let head: Element | undefined;
     function visit(node: DefaultTreeAdapterMap["node"]) {
         if ("tagName" in node) {
@@ -37,6 +41,10 @@ export function createHtmlMutationEmitter(
                     attrs: node.attrs.map((attribute) => ({ ...attribute })),
                     text: node.childNodes.map((child) => ("value" in child ? child.value : "")),
                 });
+            } else if (node.tagName === "a") {
+                const href = location?.attrs?.href;
+                if (href)
+                    hrefSnapshots.push({ node, start: href.startOffset, end: href.endOffset });
             }
         }
         if ("childNodes" in node) for (const child of node.childNodes) visit(child);
@@ -45,6 +53,16 @@ export function createHtmlMutationEmitter(
 
     return () => {
         const edits: Array<{ start: number; end: number; value: string }> = [];
+        for (const { node, start, end } of hrefSnapshots) {
+            const current = node.attrs.find((attribute) => attribute.name === "href")?.value;
+            if (current === undefined) continue;
+            const raw = source.slice(start, end);
+            const parsed = /^(href\s*=\s*["'])([^"']*)(["'])$/u.exec(raw);
+            if (!parsed) continue;
+            const next = normalizeRouteHref(parsed[2] ?? "");
+            if (next === parsed[2]) continue;
+            edits.push({ start, end, value: `${parsed[1]}${next}${parsed[3]}` });
+        }
         for (const snapshot of snapshots) {
             const { node, start, end, attrs, text } = snapshot;
             if (!node.parentNode) {

package/src/internal/modern-css.ts

@@ -1,5 +1,6 @@
 // Modern CSS output floor for the 1.35 release. Older fallback expansions are unnecessary.
 // Acceptance uses current stable browser engines; targets intentionally retain native nesting.
+// Keep in sync with the `browserslist` field in package.json (documentation for other tools).
 export const modernCssTargets = {
     chrome: 154 << 16,
     firefox: 157 << 16,

package/src/internal/route-hrefs.ts

@@ -0,0 +1,47 @@
+import type { DefaultTreeAdapterMap } from "parse5";
+
+type Document = DefaultTreeAdapterMap["document"];
+
+/** Endpoints that are real files: the extension identifies them, never a slash. */
+const REAL_FILE =
+    /\.(?:md|json|xml|txt|html?|pdf|png|webp|avif|svg|jpe?g|gif|ico|css|js|mjs|map|zip|mp4|webm|woff2?|ttf|otf)$/iu;
+
+/**
+ * Rewrite a site-absolute href to the form the router actually serves.
+ *
+ * Page routes carry no trailing slash (`/posts/x`, `/archives`), while real
+ * files keep theirs (`/posts/x.md`, `/api/posts.json`). Only rooted paths are
+ * touched: relative links, protocol-relative URLs and anchors pass through.
+ */
+export function normalizeRouteHref(href: string): string {
+    if (!href.startsWith("/") || href.startsWith("//")) return href;
+    const match = /^([^?#]*)([?#].*)?$/u.exec(href);
+    const path = match?.[1] ?? href;
+    const suffix = match?.[2] ?? "";
+    if (path === "/" || !path.endsWith("/") || REAL_FILE.test(path)) return href;
+    return `${path.replace(/\/+$/u, "")}${suffix}`;
+}
+
+/**
+ * Content-authored links still use the old trailing-slash form. Normalising the
+ * parsed document here keeps hand-written Markdown from reintroducing a URL
+ * shape the router no longer serves, without touching the author's source.
+ */
+export function normalizeRouteHrefs(document: Document): number {
+    let changed = 0;
+    const visit = (node: DefaultTreeAdapterMap["node"]): void => {
+        if ("tagName" in node && node.tagName === "a") {
+            for (const attribute of node.attrs) {
+                if (attribute.name !== "href") continue;
+                const next = normalizeRouteHref(attribute.value);
+                if (next !== attribute.value) {
+                    attribute.value = next;
+                    changed++;
+                }
+            }
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child);
+    };
+    visit(document);
+    return changed;
+}

package/src/internal/social-card-data.ts

@@ -22,7 +22,7 @@ export function createSocialCardData(
         siteTitle: site.title,
         author: author.name,
         host: siteUrl.host,
-        postUrl: new URL(`/posts/${encodeURIComponent(post.abbrlink)}/`, siteUrl).href,
+        postUrl: new URL(`/posts/${encodeURIComponent(post.abbrlink)}`, siteUrl).href,
         tags: post.tags ?? [],
         date: formatInTimeZone(
             parseDate(post.date, site.timezone || "Asia/Shanghai"),

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

@@ -247,101 +247,94 @@ export const styleNames: { classes: Record<string, string>; variables: Record<st
         "--border-thick": "--sh",
         "--border-thin": "--si",
         "--card-bg": "--sj",
-        "--card-border": "--sk",
-        "--card-box-shadow": "--sl",
-        "--card-box-shadow-hover": "--sm",
-        "--category-bg": "--sn",
-        "--category-bg-hover": "--so",
-        "--cloud-base-diameter": "--sp",
-        "--cloud-density": "--sq",
-        "--date-bg": "--sr",
-        "--date-border": "--ss",
-        "--dot": "--st",
-        "--easing-bounce": "--su",
-        "--font-size-base": "--sv",
-        "--font-size-small": "--sw",
-        "--font-size-smaller": "--sx",
-        "--font-size-subtitle": "--sy",
-        "--font-size-tiny": "--sz",
-        "--muted-text": "--s10",
-        "--nav-scale": "--s11",
-        "--radius-full": "--s12",
-        "--radius-lg": "--s13",
-        "--radius-md": "--s14",
-        "--radius-sm": "--s15",
-        "--shadow-dark": "--s16",
-        "--shadow-lg": "--s17",
-        "--shadow-md": "--s18",
-        "--shadow-raised-hover": "--s19",
-        "--shadow-sidebar": "--s1a",
-        "--shadow-sm": "--s1b",
-        "--shadow-xl": "--s1c",
-        "--space-2xl": "--s1d",
-        "--space-2xs": "--s1e",
-        "--space-3xl": "--s1f",
-        "--space-lg": "--s1g",
-        "--space-md": "--s1h",
-        "--space-sm": "--s1i",
-        "--space-xl": "--s1j",
-        "--space-xs": "--s1k",
-        "--stalux-accent-color": "--s1l",
-        "--stalux-accent-rgb": "--s1m",
-        "--stalux-bg-color": "--s1n",
-        "--stalux-bg-filter": "--s1o",
-        "--stalux-nav-offset": "--s1p",
-        "--stalux-scrollbar-thumb": "--s1q",
-        "--stalux-scrollbar-thumb-hover": "--s1r",
-        "--stalux-scrollbar-track": "--s1s",
-        "--stalux-site-header-height": "--s1t",
-        "--stalux-site-header-min-height": "--s1u",
-        "--stalux-text-shadow": "--s1v",
-        "--surface-glass": "--s1w",
-        "--surface-glass-shadow": "--s1x",
-        "--tag-bg": "--s1y",
-        "--tag-bg-hover": "--s1z",
-        "--tl-line": "--s20",
-        "--tl-pad": "--s21",
-        "--transition-fast": "--s22",
-        "--transition-medium": "--s23",
-        "--transition-normal": "--s24",
-        "--transition-slow": "--s25",
-        "--transition-slower": "--s26",
-        "--transition-slowest": "--s27",
-        "--un-rotate": "--s28",
-        "--un-rotate-x": "--s29",
-        "--un-rotate-y": "--s2a",
-        "--un-rotate-z": "--s2b",
-        "--un-scale-x": "--s2c",
-        "--un-scale-y": "--s2d",
-        "--un-scale-z": "--s2e",
-        "--un-skew-x": "--s2f",
-        "--un-skew-y": "--s2g",
-        "--un-translate-x": "--s2h",
-        "--un-translate-y": "--s2i",
-        "--un-translate-z": "--s2j",
-        "--updated-bg": "--s2k",
-        "--updated-border": "--s2l",
-        "--white-05p": "--s2m",
-        "--white-10p": "--s2n",
-        "--white-15p": "--s2o",
-        "--white-20p": "--s2p",
-        "--white-30p": "--s2q",
-        "--white-50p": "--s2r",
-        "--white-60p": "--s2s",
-        "--white-70p": "--s2t",
-        "--white-75p": "--s2u",
-        "--white-78p": "--s2v",
-        "--white-80p": "--s2w",
-        "--white-85p": "--s2x",
-        "--white-90p": "--s2y",
-        "--white-95p": "--s2z",
-        "--white-full": "--s30"
+        "--card-box-shadow": "--sk",
+        "--card-box-shadow-hover": "--sl",
+        "--category-bg": "--sm",
+        "--category-bg-hover": "--sn",
+        "--cloud-base-diameter": "--so",
+        "--cloud-density": "--sp",
+        "--date-bg": "--sq",
+        "--date-border": "--sr",
+        "--dot": "--ss",
+        "--font-size-base": "--st",
+        "--font-size-small": "--su",
+        "--font-size-smaller": "--sv",
+        "--font-size-subtitle": "--sw",
+        "--font-size-tiny": "--sx",
+        "--muted-text": "--sy",
+        "--nav-scale": "--sz",
+        "--radius-full": "--s10",
+        "--radius-lg": "--s11",
+        "--radius-md": "--s12",
+        "--radius-sm": "--s13",
+        "--shadow-dark": "--s14",
+        "--shadow-lg": "--s15",
+        "--shadow-md": "--s16",
+        "--shadow-sidebar": "--s17",
+        "--shadow-sm": "--s18",
+        "--shadow-xl": "--s19",
+        "--space-2xl": "--s1a",
+        "--space-2xs": "--s1b",
+        "--space-3xl": "--s1c",
+        "--space-lg": "--s1d",
+        "--space-md": "--s1e",
+        "--space-sm": "--s1f",
+        "--space-xl": "--s1g",
+        "--space-xs": "--s1h",
+        "--stalux-accent-color": "--s1i",
+        "--stalux-accent-rgb": "--s1j",
+        "--stalux-bg-color": "--s1k",
+        "--stalux-bg-filter": "--s1l",
+        "--stalux-nav-offset": "--s1m",
+        "--stalux-scrollbar-thumb": "--s1n",
+        "--stalux-scrollbar-thumb-hover": "--s1o",
+        "--stalux-scrollbar-track": "--s1p",
+        "--stalux-site-header-height": "--s1q",
+        "--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",
+        "--un-rotate": "--s23",
+        "--un-rotate-x": "--s24",
+        "--un-rotate-y": "--s25",
+        "--un-rotate-z": "--s26",
+        "--un-scale-x": "--s27",
+        "--un-scale-y": "--s28",
+        "--un-scale-z": "--s29",
+        "--un-skew-x": "--s2a",
+        "--un-skew-y": "--s2b",
+        "--un-translate-x": "--s2c",
+        "--un-translate-y": "--s2d",
+        "--un-translate-z": "--s2e",
+        "--updated-bg": "--s2f",
+        "--updated-border": "--s2g",
+        "--white-05p": "--s2h",
+        "--white-10p": "--s2i",
+        "--white-15p": "--s2j",
+        "--white-20p": "--s2k",
+        "--white-30p": "--s2l",
+        "--white-50p": "--s2m",
+        "--white-60p": "--s2n",
+        "--white-70p": "--s2o",
+        "--white-75p": "--s2p",
+        "--white-78p": "--s2q",
+        "--white-80p": "--s2r",
+        "--white-85p": "--s2s",
+        "--white-90p": "--s2t",
+        "--white-95p": "--s2u",
+        "--white-full": "--s2v"
     },
     "animations": {
-        "spin": "k0",
-        "stalux-cursor-blink": "k1",
-        "stalux-link-avatar-spin": "k2",
-        "stalux-random-spin": "k3",
-        "stalux-social-stalux-social-arrive": "k4"
+        "stalux-cursor-blink": "k0",
+        "stalux-random-spin": "k1",
+        "stalux-social-stalux-social-arrive": "k2"
     }
 };

package/src/internal/swup-options.ts

@@ -0,0 +1,98 @@
+/**
+ * Swup configuration handed to `@swup/astro`.
+ *
+ * `@swup/astro` owns construction of the Swup instance and all plugin
+ * assembly; the theme only describes *which* behaviour it wants. Anything that
+ * cannot be expressed here lives in `src/scripts/route-guards.ts`.
+ */
+import type { Options, Route } from "@swup/astro";
+
+/** Named routes shared by the router and the route classifier. */
+export const SWUP_ROUTES: Route[] = [
+    { 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" },
+];
+
+/**
+ * Real files are never pages. `@swup/astro` builds `ignoreVisit` itself and
+ * only lets `ignore` extend it, so this list is the whole hook.
+ */
+export const SWUP_IGNORE_FILES = /\.(?:md|json|xml|txt|html?|pdf|png|webp|avif|svg|jpe?g)$/iu;
+
+/**
+ * Paths the theme renders as soft-navigable pages.
+ *
+ * `@swup/astro` cannot express "only these routes" as a predicate: `ignore`
+ * accepts regexes, and a regex is the only form that survives serialisation
+ * into the init script. Keeping the alternation here also keeps the rule next
+ * to `SWUP_ROUTES` above, which is the same set of pages.
+ */
+const SOFT_NAV_PATHS =
+    /^\/(?:|archives|links|words|about|404|tags(?:\/[^/?#]+)?|categories(?:\/[^/?#]+)?|posts\/[^/?#]+)\/?(?:[?#].*)?$/u;
+
+/** Every path the theme itself renders; anything else is left to the browser. */
+export const SWUP_IGNORE_UNKNOWN_ROUTES = new RegExp(`^(?!${SOFT_NAV_PATHS.source})`, "u");
+
+/**
+ * `@swup/astro` types most plugin options as booleans, but forwards any object
+ * it is given straight into the plugin constructor. Two of these need their
+ * real plugin options (body-class prefix, head persistence, scroll behaviour),
+ * so the object form is used deliberately and the cast is made once here.
+ */
+export const SWUP_OPTIONS = {
+    containers: ["#swup-main"],
+    // No route animation: no theme, and no `[class*="transition-"]` selector to
+    // wait on. The swap is a plain, synchronous DOM replacement.
+    theme: false,
+    animationClass: false,
+    // The init script must run while the first document is still parsing; on
+    // idle the first click can arrive before the router is listening.
+    loadOnIdle: false,
+    // The guard script needs the instance; route-prefetch already reads it.
+    globalInstance: true,
+    // Page scripts are re-executed by the theme's own once-per-session runner
+    // (see route-guards.ts). The plugin's whole-document pass would replay
+    // analytics SDKs on every visit.
+    reloadScripts: false,
+    cache: true,
+    native: false,
+    morph: false,
+    forms: false,
+    preload: { hover: true, visible: false },
+    progress: { delay: 80, transition: 200 },
+    accessibility: true,
+    updateBodyClass: { prefix: "page-", attributes: [/^data-stalux-(?!bg-)/u] },
+    updateHead: {
+        awaitAssets: true,
+        // Keep old CSS readable while the incoming sheet loads; route-guards
+        // removes the styles the new page does not use once it is in place.
+        persistTags: "link[rel=stylesheet], script[src], style",
+    },
+    routes: SWUP_ROUTES,
+    fragments: [
+        {
+            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,
+        },
+    ],
+    smoothScrolling: {
+        doScrollingRightAway: false,
+        animateScroll: { betweenPages: false, samePageWithHash: true, samePage: true },
+    },
+    ignore: [SWUP_IGNORE_FILES, SWUP_IGNORE_UNKNOWN_ROUTES],
+} as unknown as Partial<Options>;

package/src/layouts/Stalux.astro

@@ -74,7 +74,6 @@ const routeKind = getRouteKind(Astro.url.pathname);
     />
     <script>
     import "../scripts/background.ts";
-    import "../scripts/view-transitions.ts";
     // Every page type has at least one list, so the unroll cue is registered
     // once in the shared layout instead of per page. Page-runtime dedupes it
     // against the article and archive components that also request it.