@xingwangzhe/stalux 1.43.1 → 1.44.0

package/README.md

@@ -18,9 +18,9 @@ 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.
 
-Swup owns soft navigation and transition timing. Astro renders the static documents; the browser runtime replaces only `main[data-stalux-route]`, keeping the header, footer, scroll sentinel and two background layers alive. The incoming visible heading receives a brief opacity or directional hint selected by the route policy: entering an article can move 6px vertically, explicit previous/next article links use opposite 8px horizontal hints, and returning to a list uses a 4px upward hint. Other article links and taxonomy changes fade without inventing a reading direction. Desktop effects last 80–140ms; phones use an 80ms fade without translation. The article body and long lists stay immediately readable. Reduced motion and browser-provided history gestures skip content motion; same-page anchors use their scrolling behavior and same-URL clicks preserve the reading position. Standalone HTML and exported data use document navigation. See the [Swup transition architecture and route policy](docs/view-transitions-swup.md).
+Swup owns soft navigation and motion timing. Astro renders static documents; only `main[data-stalux-route]` is replaced, while navigation, footer, scroll sentinel and background retain their DOM identities. After destination assets are ready, a visible height-bounded heading or introductory region receives a short exit and entry: up to 6px vertically for reading entry, 8px horizontally for explicit previous/next, 4px vertically for a neutral article change, and 6px horizontally within one taxonomy dimension. Cross-category/tag changes use a neutral fade. Desktop entry lasts 100–180ms with an 80ms exit; phones use a 120ms pure entry fade. Long documents remain directly readable without whole-main motion or hiding. History restoration, reduced motion, native browser gestures and same-page anchors skip page motion. Independent HTML and exported data use document navigation. See [Modules and view transitions](docs/MOTION.md) for the complete inventory and timing contract.
 
-The runtime uses Swup's Head, Accessibility, Preload, Scroll and JS plugins with Stalux lifecycle handlers. It waits for incoming stylesheets and gives the destination font a bounded 150ms head start, disposes old interactions before replacement, loads first-seen page scripts, then dispatches the Astro-compatible page lifecycle events used by comments, counters, tag clouds and WebMCP. Backgrounds decode independently and crossfade after the content animation finishes; stale navigation work cannot replace the current background. History positions are restored by the Swup runtime, including reduced-motion visits. This requires no new configuration or telemetry. Animation duration describes the effect itself, not total navigation time or a measured performance improvement.
+The runtime uses Swup's Head, Accessibility, Preload, Scroll and JS plugins with Stalux lifecycle handlers. It waits for incoming stylesheets and gives the destination font a bounded 150ms head start, disposes old interactions before replacement, loads first-seen page scripts, then dispatches the Astro-compatible page lifecycle events used by comments, counters, tag clouds and WebMCP. Each full document randomly selects and asynchronously decodes one background, revealing it from the stable dark canvas over 200ms. Swup soft navigations retain that image without selecting, decoding, or crossfading another SVG. Reduced motion reveals it immediately; saveData keeps the dark canvas without requesting decorative SVGs. Custom `window.__STALUX_BG_URLS__` remains supported, and slow or failed decoding never blocks reading. History positions are restored by the Swup runtime, including reduced-motion visits. This requires no new configuration or telemetry. Animation duration describes the effect itself, not total navigation time or a measured performance improvement.
 
 ---
 
@@ -371,4 +371,6 @@ og:image: /images/custom-social-card.png
 
 Local covers are read from the final `publicDir`. Remote covers are requested by the build machine, with an 8-second timeout and an 8 MiB limit (remote bytes are cached for 24 hours); unreadable or undecodable artwork emits a warning and falls back to a title card. No remote image-generation service is used. WebP and PNG outputs are cached in `stalux-social-cards/` under Astro's cache directory and copied into each build output. Explicit sharing images are fetched by social platforms, so they must be publicly accessible images. Platforms maintain their own preview caches and may not refresh an existing share immediately after deployment.
 
-Content transitions follow Fuwari’s fade and vertical movement: keep the old content readable until destination assets are ready, fade it out over 140ms, then reveal the new content over 220ms (180ms on phones). The header and background persist. History restores the reading position without an outgoing animation. Same-page anchors use interruptible native smooth scrolling; reduced motion uses instant positioning. Cross-page scroll resets happen while content is hidden. No configuration is required.
+Motion is specified for 55 visible semantic modules in [Modules and view transitions](docs/MOTION.md). Swup animates one visible, height-bounded heading or introductory region after destination assets are ready, with cues for reading, returning, filtering and previous/next articles. Long documents stay readable and the header, footer and dark canvas remain stable. Phones use a short fade; history restores the reading position; same-page anchors use interruptible native scrolling. Module hover, focus, press and asynchronous update feedback complement bounded secondary entry cues. Reduced motion and print remain static and readable. No new configuration is required.
+
+Built-in background artwork uses committed lossless WebP companions. Ratio-only SVG sizing is preserved with `contain`; custom background URLs retain their existing sizing. Regenerate companions after changing the SVG originals with `bun run backgrounds:build`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.43.1",
+    "version": "1.44.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -98,7 +98,8 @@
         "styles:watch": "node scripts/build-styles.ts --watch",
         "benchmark:performance": "node scripts/benchmark-performance.ts",
         "benchmark:builds": "python3 scripts/benchmark-builds.py",
-        "analyze": "SONDA=1 bun run build"
+        "analyze": "SONDA=1 bun run build",
+        "backgrounds:build": "bun run scripts/build-backgrounds.ts"
     },
     "dependencies": {
         "@astrojs/compiler": "^4.0.0",
@@ -145,6 +146,7 @@
         "@vitest/coverage-v8": "^5.0.4",
         "astro": "^7.4.2",
         "knip": "^6.41.0",
+        "sharp": "0.35.5",
         "sonda": "^0.14.0",
         "typescript": "npm:@typescript/typescript6@6.0.2",
         "unocss": "^66.11.0",

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

@@ -10,5 +10,5 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
 ---
 
 <div id={"stalux-to-archive-archs"}>
-    <a href="/archives" data-astro-prefetch>{t("archives.viewAll")}</a>
+    <a data-stalux-control="button" href="/archives" data-astro-prefetch>{t("archives.viewAll")}</a>
 </div>

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

@@ -21,7 +21,7 @@ const { t } = createTranslator((siteConfig.lang as string) || "zh-CN");
 ---
 
 <div class="stalux-category-shell">
-    <article class="stalux-category-card">
+    <article class="stalux-category-card" data-stalux-control="category-card">
         <a
             href={`/categories/${props.category.name}/`}
             class="stalux-categoryheader a-none"

package/src/components/stalux/common/author.astro

@@ -21,7 +21,7 @@ const navigationHref = isHomePage ? "/about" : "/";
     <figure
         class={`stalux-author-figure ${props.iscolum ? "stalux-author-figure-column stalux-u-flex-col" : ""}`}
     >
-        <a href={navigationHref} class="a-none" data-astro-prefetch>
+        <a data-stalux-control="avatar" href={navigationHref} class="a-none" data-astro-prefetch>
             <Image src={authorConfig.avatar} alt={authorConfig.name} width={100} height={100} />
         </a>
         <figcaption>{authorConfig.name}</figcaption>

package/src/components/stalux/footer/FooterBadges.astro

@@ -36,7 +36,11 @@ function badgeImg(opts: BadgeOptions) {
             if (isBadgeGroup(item)) {
                 const groupId = `badge-group-${idx}`;
                 return (
-                    <details class="stalux-badge-group stalux-u-w-full badge-group" id={groupId}>
+                    <details
+                        data-stalux-module="badge-group"
+                        class="stalux-badge-group stalux-u-w-full badge-group"
+                        id={groupId}
+                    >
                         <summary class="stalux-badge-group-summary stalux-u-flex stalux-u-items-center stalux-u-justify-center">
                             <span class="stalux-badge-group-arrow">&#9654;</span>
                             <span class="stalux-badge-group-title">{item.title}</span>

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

@@ -7,7 +7,7 @@ interface Props {
 const { heading, description } = Astro.props;
 ---
 
-<>
+<div data-stalux-motion-region>
     <h1 class="stalux-page-title stalux-u-text-center" data-stalux-motion-focus>
         {heading}
     </h1>
@@ -16,4 +16,4 @@ const { heading, description } = Astro.props;
             {description}
         </div>
     )}
-</>
+</div>

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

@@ -51,7 +51,11 @@ const totalWordCount = await getTotalWordCount(Astro.logger);
 const formattedWordCount = formatWordCount(totalWordCount, siteConfig.lang || "zh-CN");
 ---
 
-<footer class="stalux-footer stalux-u-w-full stalux-u-text-center" data-stalux-font-group="footer">
+<footer
+    class="stalux-footer stalux-u-w-full stalux-u-text-center"
+    data-stalux-font-group="footer"
+    data-stalux-module="footer"
+>
     <div class="stalux-footer-content stalux-u-flex stalux-u-flex-col">
         <!-- 版权信息 -->
         {footerConfig?.copyright?.enabled && (

package/src/components/stalux/links/linkCard.astro

@@ -29,7 +29,13 @@ const desc = link.description ?? "";
 const icon = link.icon ?? link.avatar ?? "/favicon.ico";
 ---
 
-<a class="stalux-link-shell a-none" href={href} target="_blank" rel="noopener">
+<a
+    data-stalux-control="link-card"
+    class="stalux-link-shell a-none"
+    href={href}
+    target="_blank"
+    rel="noopener"
+>
     <div class="stalux-link-card">
         <div class="stalux-link-card-avatar">
             <img

package/src/components/stalux/links/socialMedia.astro

@@ -40,6 +40,7 @@ function getIconByTitle(iconName: string): SimpleIcon | undefined {
             return (
                 <li class="social_icon">
                     <a
+                        data-stalux-control="social"
                         href={item.link}
                         target="_blank"
                         aria-label={item.icon}

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

@@ -9,7 +9,12 @@ const summary = description?.trim();
 ---
 
 {summary && (
-    <aside class="stalux-article-summary" data-stalux-motion-content aria-label={label}>
+    <aside
+        class="stalux-article-summary"
+        data-stalux-motion-content
+        data-stalux-module="summary"
+        aria-label={label}
+    >
         <p class="stalux-article-summary-label">{label}</p>
         <p class="stalux-article-summary-text">{summary}</p>
     </aside>

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

@@ -44,6 +44,7 @@ const walineConfig = {
 {walineConfig.serverURL && (
     <section
         id="waline-container"
+        data-stalux-module="comments"
         class="waline-comment-container"
         aria-label={t("comment.title")}
         data-waline-config={

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

@@ -26,7 +26,7 @@ const licenseLink = buildCCLink(cc);
 const licenseName = buildCCName(cc, t);
 ---
 
-<div class="stalux-license-box">
+<div class="stalux-license-box" data-stalux-module="license">
     <div class="stalux-license-content">
         <p class="stalux-license-title">{title}</p>
         <p class="stalux-license-author">{t("post.author")}{author}</p>

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

@@ -19,7 +19,10 @@ const timezone = siteConfig.timezone;
 const description = post.data.desc || "";
 ---
 
-<article class="stalux-post-card-shell block h-full text-inherit no-underline">
+<article
+    data-stalux-control="post-card"
+    class="stalux-post-card-shell block h-full text-inherit no-underline"
+>
     <div class="stalux-post-card stalux-u-flex stalux-u-flex-col stalux-u-w-full stalux-u-min-w-0">
         {post.data.cover && (
             <a

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

@@ -40,7 +40,7 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/, "")}.md` : "
 
 <article class="stalux-article" data-stalux-gallery={props.hasImage ? "true" : undefined}>
     <!-- Article Header -->
-    <header class="stalux-post-article-header">
+    <header class="stalux-post-article-header" data-stalux-motion-region>
         <h1 class="stalux-post-title" data-stalux-motion-focus>
             {props.title}
         </h1>

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

@@ -6,7 +6,7 @@ import RandomPost from "@components/stalux/posts/randomPost.astro";
 ---
 
 <aside class="stalux-sidebar">
-    <div class="stalux-sidebar-container">
+    <div class="stalux-sidebar-container" data-stalux-module="sidebar">
         <PostAuthor />
     </div>
     <div class="stalux-sidebar-container">

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

@@ -19,7 +19,11 @@ const { t } = createTranslator((siteConfig.lang as string) || "zh-CN");
 ---
 
 {(props.prev || props.next) && (
-    <nav class="stalux-pagination" aria-label={t("post.navigation")}>
+    <nav
+        data-stalux-module="post-navigation"
+        class="stalux-pagination"
+        aria-label={t("post.navigation")}
+    >
         <div class="stalux-pagination-inner">
             {props.prev ? (
                 <a

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

@@ -15,7 +15,7 @@ const { headings = [], tags = [], categories = [] } = Astro.props;
 ---
 
 <aside class="stalux-sidebar-right" data-stalux-scroll-pane>
-    <div class="stalux-sidebar-container">
+    <div class="stalux-sidebar-container" data-stalux-module="sidebar">
         <PostDate />
         <Weather />
     </div>

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

@@ -27,7 +27,7 @@ if (typeKey === "category" || typeKey === "categories" || typeKey === "分类")
 }
 ---
 
-<header class="stalux-tag-header">
+<header class="stalux-tag-header" data-stalux-motion-region>
     <h1 class="stalux-tag-page-title" data-stalux-motion-focus>
         <span class="stalux-tag-category-icon">
             <svg

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

@@ -22,7 +22,7 @@ const tagLinks = tagList.map((t) => ({
 ---
 
 <!-- 移动端：SSR 卡片 -->
-<div class="stalux-cloud-cards" id="tags-cards" data-stalux-motion-content>
+<div class="stalux-cloud-cards" id="tags-cards" data-stalux-tag-cards data-stalux-motion-content>
     {tagList.length > 0 ? (
         tagGroups.map((group) => (
             <div class="stalux-cloud-tag-group">
@@ -32,6 +32,7 @@ const tagLinks = tagList.map((t) => ({
                         class="stalux-cloud-tag-card"
                         data-stalux-card
                         data-stalux-tag-card
+                        data-stalux-control="tag-card"
                         data-count={count}
                         data-astro-prefetch
                     >
@@ -49,6 +50,7 @@ const tagLinks = tagList.map((t) => ({
 <!-- 桌面端：Canvas 标签云 -->
 <div
     class="stalux-cloud-canvas-frame"
+    data-stalux-tag-canvas
     style={{ "--cloud-density": cloudDensity }}
     data-stalux-motion-content
 >

package/src/components/stalux/words/wordCard.astro

@@ -19,7 +19,11 @@ const { source, link, sourceDate, date, abbrlink } = entry.data;
 const machineDate = date && timezone ? toMachineDateTime(date, timezone) : date;
 ---
 
-<article class="stalux-word-card" id={abbrlink ? `word-${abbrlink}` : undefined}>
+<article
+    data-stalux-module="word"
+    class="stalux-word-card"
+    id={abbrlink ? `word-${abbrlink}` : undefined}
+>
     <Quote class="stalux-word-mark" size={28} stroke-width={1.4} aria-hidden="true" />
     <div class="stalux-word-body stalux-prose" data-pagefind-body>
         <Content />

package/src/internal/public-assets.ts

@@ -2,11 +2,11 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "
 import path from "node:path";
 
 // ---------------------------------------------------------------------------
-// 背景 SVG 判别式同步
+// 背景资源判别式同步
 // ---------------------------------------------------------------------------
 
 /**
- * 把主题包的 public/background/*.svg 同步到用户项目 public/background/。
+ * 把主题包的 public/background/ SVG 原图及 WebP 同步到用户 public/background/。
  *
  * 判别式（非无条件覆盖）：
  * - 同名文件：内容一致则跳过（幂等）；内容不同才覆盖（主题更新了 SVG）
@@ -26,7 +26,7 @@ export function syncBackgroundSvgs(
     let copied = 0;
     let skipped = 0;
     for (const name of readdirSync(srcBg)) {
-        if (!name.endsWith(".svg")) continue;
+        if (!/\.(?:svg|webp)$/u.test(name)) continue;
         const srcFile = path.join(srcBg, name);
         const destFile = path.join(destBg, name);
         if (existsSync(destFile)) {

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

@@ -333,27 +333,25 @@ export const styleNames: { classes: Record<string, string>; variables: Record<st
         "--white-full": "--s2x"
     },
     "animations": {
-        "fadeInUpComment": "k0",
-        "spin": "k1",
-        "stalux-article-enter": "k2",
-        "stalux-article-enter-back": "k3",
-        "stalux-cursor-blink": "k4",
-        "stalux-link-avatar-spin": "k5",
-        "stalux-page-enter": "k6",
-        "stalux-page-enter-back": "k7",
-        "stalux-page-exit": "k8",
-        "stalux-random-spin": "k9",
-        "stalux-sidebar-left-back-in": "ka",
-        "stalux-sidebar-left-back-out": "kb",
-        "stalux-sidebar-left-in": "kc",
-        "stalux-sidebar-left-out": "kd",
-        "stalux-sidebar-right-back-in": "ke",
-        "stalux-sidebar-right-back-out": "kf",
-        "stalux-sidebar-right-in": "kg",
-        "stalux-sidebar-right-out": "kh",
-        "stalux-social-stalux-social-arrive": "ki",
-        "stalux-taxonomy-enter": "kj",
-        "stalux-taxonomy-enter-back": "kk",
-        "stalux-word-word-glow": "kl"
+        "spin": "k0",
+        "stalux-article-enter": "k1",
+        "stalux-article-enter-back": "k2",
+        "stalux-cursor-blink": "k3",
+        "stalux-link-avatar-spin": "k4",
+        "stalux-page-enter": "k5",
+        "stalux-page-enter-back": "k6",
+        "stalux-page-exit": "k7",
+        "stalux-random-spin": "k8",
+        "stalux-sidebar-left-back-in": "k9",
+        "stalux-sidebar-left-back-out": "ka",
+        "stalux-sidebar-left-in": "kb",
+        "stalux-sidebar-left-out": "kc",
+        "stalux-sidebar-right-back-in": "kd",
+        "stalux-sidebar-right-back-out": "ke",
+        "stalux-sidebar-right-in": "kf",
+        "stalux-sidebar-right-out": "kg",
+        "stalux-social-stalux-social-arrive": "kh",
+        "stalux-taxonomy-enter": "ki",
+        "stalux-taxonomy-enter-back": "kj"
     }
 };

package/src/layouts/Stalux.astro

@@ -1,4 +1,5 @@
 ---
+import "../styles/module-motion.css";
 import { getCollection } from "astro:content";
 import Footer from "@components/stalux/layout/footer.astro";
 import Head from "@components/stalux/layout/head.astro";
@@ -41,7 +42,7 @@ const htmlLang = siteConfig.lang || "zh-CN";
 // 背景 SVG 以静态 URL 硬编码在 background.ts（纯客户端），
 // 集成在 config:done 时把 SVG 复制到用户项目最终的 publicDir/background/。
 // SSR 不渲染背景图，默认露出 .bg-layer 的灰墙底色（--stalux-bg-color），
-// 客户端运行时随机选图；不经过 import.meta.glob 资源管线，
+// 每个完整文档首次客户端随机选图，同一 Swup 会话复用；不经过 import.meta.glob 资源管线，
 // 保证增量构建依赖图 hash 稳定。
 const llmPromoteRaw = promoteConfig?.llm_promote ?? "";
 const llmPromote = llmPromoteRaw
@@ -73,6 +74,7 @@ const routeKind = getRouteKind(Astro.url.pathname);
     />
     <script>
     import "../scripts/background.ts";
+    import "../scripts/module-motion.ts";
     import "../scripts/view-transitions.ts";
     </script>
     {aiConfig?.conformance !== "disabled" && <script>import "../scripts/webmcp.ts";</script>}

package/src/pages/404.astro

@@ -17,7 +17,7 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
         class="stalux-404-error-container stalux-u-flex stalux-u-items-center stalux-u-justify-center stalux-u-text-center"
         data-pagefind-ignore
     >
-        <div class="stalux-404-error-content">
+        <div class="stalux-404-error-content" data-stalux-motion-region>
             <h1 data-stalux-motion-focus>404</h1>
             <p data-stalux-motion-content>{t("page404.pageNotFound")}</p>
             <p class="agent-recovery" data-stalux-motion-content>
@@ -38,6 +38,7 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
             <a
                 href="/"
                 class="stalux-404-home-btn home-btn"
+                data-stalux-control="button"
                 data-astro-prefetch
                 data-stalux-motion-content
                 >{t("page404.backHome")}</a

package/src/pages/index.astro

@@ -20,7 +20,11 @@ import { getSiteData } from "@utils/config-utils";
 
 <Stalux title={siteTitle} description={siteDescription}>
     <div class="stalux-home-body stalux-u-flex stalux-u-items-center stalux-u-flex-col">
-        <h1 class="stalux-home-title stalux-u-text-center" data-stalux-motion-focus>
+        <h1
+            class="stalux-home-title stalux-u-text-center"
+            data-stalux-motion-region
+            data-stalux-motion-focus
+        >
             {siteTitle}
         </h1>
         <h2