@xingwangzhe/stalux 1.43.1 → 1.44.0

package/src/scripts/background.ts

@@ -1,133 +1,74 @@
 /**
- * 双层随机背景 — 纯客户端实现
+ * 每个完整文档只随机选择一次的会话背景。
  *
- * SVG 以静态 URL（/background/pattern-N.min.svg）硬编码，由集成在
- * config:setup 时复制到用户项目 public/background/。不经过 Astro 资源
- * 管线（import.meta.glob 会给 SVG 打上每次构建随机的 __ASTRO_ASSET_IMAGE__
- * 占位符，破坏增量构建依赖图 hash），也不做任何构建期扫描。
- *
- * 背景行为：
- * - SSR 只渲染灰墙底色（--stalux-bg-color），不渲染任何背景图，构建产物确定。
- * - 首次加载与 VT 软导航每次都会随机选一张背景：astro:page-load 在
- *   window load（首访）与 swap 完成后、过渡动画期间（软导航）触发，
- *   先低优先级解码目标背景，等待内容过渡完成后再淡入，不与内容快照争抢绘制。
+ * SSR 保持确定的深色底和原有双层 DOM，不内联背景 URL。文档解析完成即
+ * 低优先级请求并异步解码一张无损 WebP，无需等待 window.load。首次成功时从暗底
+ * 用 200ms opacity 淡显；减少动态效果时直接显示。解码慢或失败仍保持暗底。
+ * Swup 只替换 main，背景沿用同一张，不按软导航重选/解码或再次交叉淡入。
+ * 自定义 __STALUX_BG_URLS__ 继续生效；saveData 下保留暗底，不请求装饰图片。
  */
 import { createClientLogger } from "./logger";
-import { prepareRouteMotion, type RouteMotionEvent } from "./route-motion";
 
 const logger = createClientLogger("background");
 
 declare global {
     interface Window {
         __STALUX_BG_URLS__?: string[];
+        __STALUX_BG_LISTENER__?: boolean;
     }
 }
 
-/** 背景 SVG 静态 URL 列表（与主题包 public/background/ 的 1-42 号一一对应） */
 const BACKGROUND_URLS: string[] = Array.from(
     { length: 42 },
-    (_, i) => `/background/pattern-${i + 1}.min.svg`,
+    (_, i) => `/background/pattern-${i + 1}.min.webp`,
 );
 
-/** 优先使用注入列表（若用户自定义），否则用内置硬编码列表 */
-const backgroundImages: string[] = window.__STALUX_BG_URLS__?.length
-    ? window.__STALUX_BG_URLS__
-    : BACKGROUND_URLS;
-
-function getLayerEl(layer: "a" | "b"): HTMLElement | null {
-    return document.querySelector(`[data-stalux-background="${layer}"]`);
-}
-
-function setLayerOpacity(layer: "a" | "b", opacity: number): void {
-    const el = getLayerEl(layer);
-    if (el) el.style.opacity = String(opacity);
-}
-
-function getActiveLayer(): "a" | "b" {
-    const aOpacity = Number(getLayerEl("a")?.style.opacity ?? 0);
-    const bOpacity = Number(getLayerEl("b")?.style.opacity ?? 0);
-    return bOpacity > aOpacity ? "b" : "a";
-}
-
-function pickBackgroundIndex(previous: number): number {
-    if (backgroundImages.length < 2) return 0;
-    let index = Math.floor(Math.random() * backgroundImages.length);
-    while (index === previous) {
-        index = Math.floor(Math.random() * backgroundImages.length);
-    }
-    return index;
-}
-
-function crossfadeBackground(index: number): void {
-    const activeLayer = getActiveLayer();
-    const nextLayer: "a" | "b" = activeLayer === "a" ? "b" : "a";
-    const next = getLayerEl(nextLayer);
-    if (!next || !backgroundImages[index]) {
-        logger.debug("background layer unavailable; skipped");
-        return;
-    }
-    logger.debug(`crossfade layer=${nextLayer}; index=${index}`);
-
-    next.style.backgroundImage = `url('${backgroundImages[index]}')`;
-    setLayerOpacity(nextLayer, 1);
-    setLayerOpacity(activeLayer, 0);
-    document.body.dataset.staluxBgIndex = String(index);
-    document.body.dataset.staluxBgLayer = nextLayer;
-}
-
-let generation = 0;
-let prepared: Promise<number | undefined> | undefined;
-let transitionFinished: Promise<unknown> = Promise.resolve();
-
-function prepareBackground(): Promise<number | undefined> {
-    const previousIndex = Number(document.body.dataset.staluxBgIndex ?? -1);
-    const index = pickBackgroundIndex(previousIndex);
-    const image = new Image();
-    image.decoding = "async";
-    image.fetchPriority = "low";
-    image.src = backgroundImages[index] ?? "";
-    return image.decode().then(
-        () => index,
-        () => undefined,
-    );
-}
-
-let firstCommitStarted = false;
-
-function initializeBackground(): void {
-    const active = getLayerEl(getActiveLayer());
-    if (!prepared && active?.style.backgroundImage) return;
-    // 首访的早提交已经发起，但解码还没落地：此时 window.load 上的 page-load
-    // 不是新页面，不能再解码并淡入第二张。
-    if (!prepared && firstCommitStarted) return;
-    if (!prepared) firstCommitStarted = true;
-    const current = generation;
-    const ready = prepared ?? prepareBackground();
-    prepared = undefined;
-    // Decode off the navigation path, and keep the full-screen background repaint
-    // out of the content's View Transition. A superseded navigation never commits.
-    void Promise.all([ready, transitionFinished]).then(([index]) => {
-        if (current === generation && index !== undefined) crossfadeBackground(index);
-    });
-}
-
-// 背景层跨页保留；before-swap 只记录过渡完成信号，不阻塞或修改内容快照。
-// page-load 再提交已解码的背景，非 VT 浏览器也采用同一清理/去重流程。
-if (!(window as Window & { __STALUX_BG_LISTENER__?: boolean }).__STALUX_BG_LISTENER__) {
-    (window as Window & { __STALUX_BG_LISTENER__?: boolean }).__STALUX_BG_LISTENER__ = true;
-    document.addEventListener("astro:before-preparation", () => {
-        generation++;
+/** Install once per full document; this module is also harmless during SSR. */
+export function installSessionBackground(): void {
+    if (typeof window === "undefined" || typeof document === "undefined") return;
+    if (window.__STALUX_BG_LISTENER__) return;
+    window.__STALUX_BG_LISTENER__ = true;
+    const start = () => {
         const connection = (navigator as Navigator & { connection?: { saveData?: boolean } })
             .connection;
-        prepared = connection?.saveData ? undefined : prepareBackground();
-    });
-    document.addEventListener("astro:before-swap", (event) => {
-        transitionFinished = prepareRouteMotion(event as RouteMotionEvent).finished;
-    });
-    document.addEventListener("astro:page-load", initializeBackground);
-    // 首访的 page-load 由 window.load 派发，任何慢图片或卡死的第三方资源都会把首屏背景
-    // 拖成一片纯色；文档解析完就提交首张背景，软导航仍由 page-load 负责。
-    const readyState = document.readyState;
-    if (readyState === "interactive" || readyState === "complete") initializeBackground();
-    else document.addEventListener("DOMContentLoaded", initializeBackground, { once: true });
+        if (connection?.saveData) return;
+        const a = document.querySelector<HTMLElement>('[data-stalux-background="a"]');
+        const b = document.querySelector<HTMLElement>('[data-stalux-background="b"]');
+        if (!a || !b || a.style.backgroundImage || b.style.backgroundImage) return;
+        const custom = Boolean(window.__STALUX_BG_URLS__?.length);
+        const urls = window.__STALUX_BG_URLS__?.length
+            ? window.__STALUX_BG_URLS__
+            : BACKGROUND_URLS;
+        const index = Math.floor(Math.random() * urls.length);
+        const source = urls[index];
+        if (!source) return;
+        const image = new Image();
+        image.decoding = "async";
+        image.fetchPriority = "low";
+        image.src = source;
+        void image.decode().then(
+            () => {
+                // These two shell nodes retain their identities during Swup visits.
+                // No navigation event can start another image or reset this result.
+                if (!a.isConnected || !b.isConnected) return;
+                // Original SVGs have only a viewBox: auto sizes them as contain.
+                // Raster files have intrinsic dimensions, so retain that sizing
+                // explicitly. Custom URLs keep the existing auto semantics.
+                if (!custom) b.style.backgroundSize = "contain";
+                b.style.backgroundImage = `url('${source}')`;
+                b.style.opacity = "1";
+                a.style.opacity = "0";
+                document.body.dataset.staluxBgIndex = String(index);
+                document.body.dataset.staluxBgLayer = "b";
+            },
+            () => {
+                logger.debug("session background failed to decode; keeping dark canvas");
+            },
+        );
+    };
+    if (document.readyState === "loading")
+        document.addEventListener("DOMContentLoaded", start, { once: true });
+    else start();
 }
+
+installSessionBackground();

package/src/scripts/module-motion.ts

@@ -0,0 +1,70 @@
+import { registerPageLifecycle } from "./page-runtime";
+
+const SELECTOR =
+    '[data-stalux-module="summary"], [data-stalux-module="license"], [data-stalux-module="comments"], [data-stalux-module="sidebar"], [data-stalux-module="post-navigation"]';
+const MAX_REGIONS = 12;
+
+/** Bounded secondary cues. Text is visible even without observers or animation. */
+export function mountModuleMotion(): (() => void) | undefined {
+    if (
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches ||
+        typeof IntersectionObserver !== "function"
+    )
+        return;
+    const elements = [...document.querySelectorAll<HTMLElement>(SELECTOR)].slice(0, MAX_REGIONS);
+    if (!elements.length) return;
+    const active = new Set<Animation>();
+    const motionPreference = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const cancel = () => {
+        for (const animation of active) animation.cancel();
+        active.clear();
+    };
+    const observer = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                const element = entry.target as HTMLElement;
+                observer.unobserve(element);
+                // The router owns a single bounded lead region. Do not layer an
+                // observer entry over that motion or make long comments slide.
+                if (
+                    document.hidden ||
+                    motionPreference.matches ||
+                    document.documentElement.classList.contains("is-changing") ||
+                    document.documentElement.dataset.staluxVtPreset ||
+                    element.closest("[data-stalux-motion-region]") ||
+                    entry.boundingClientRect.height > Math.min(420, window.innerHeight * 0.6) ||
+                    typeof element.animate !== "function"
+                )
+                    continue;
+                try {
+                    const animation = element.animate(
+                        { opacity: [0.88, 1] },
+                        {
+                            duration: 140,
+                            easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
+                        },
+                    );
+                    active.add(animation);
+                    const release = () => {
+                        active.delete(animation);
+                        animation.cancel();
+                    };
+                    void animation.finished.then(release, release);
+                } catch {
+                    /* Unsupported effects leave the authored visible state. */
+                }
+            }
+        },
+        { threshold: 0.08 },
+    );
+    for (const element of elements) observer.observe(element);
+    motionPreference.addEventListener("change", cancel);
+    return () => {
+        observer.disconnect();
+        motionPreference.removeEventListener("change", cancel);
+        cancel();
+    };
+}
+
+registerPageLifecycle("module-motion", mountModuleMotion);

package/src/scripts/random-posts.ts

@@ -3,21 +3,6 @@ import { registerPageLifecycle } from "./page-runtime";
 
 const logger = createClientLogger("random-posts");
 
-const sleep = (ms: number, signal: AbortSignal) =>
-    new Promise<void>((resolve) => {
-        const finish = () => {
-            signal.removeEventListener("abort", aborted);
-            resolve();
-        };
-        const timer = window.setTimeout(finish, ms);
-        const aborted = () => {
-            window.clearTimeout(timer);
-            finish();
-        };
-        if (signal.aborted) aborted();
-        else signal.addEventListener("abort", aborted, { once: true });
-    });
-
 function shuffle<T extends object>(items: T[]): T[] {
     const result = [...items];
     const bytes = new Uint32Array(1);
@@ -47,45 +32,95 @@ function render(posts: { abbrlink: string; title: string }[]) {
         .join("");
 }
 
-async function refresh(container: HTMLElement, fallback: string, signal: AbortSignal) {
-    const list = container.querySelector<HTMLElement>("#random-posts-list");
-    if (!list) return;
-    list.style.opacity = "0.5";
-    await sleep(300, signal);
-    if (signal.aborted) return;
-    try {
-        logger.debug("refresh started");
-        const posts = shuffle(await fetchPosts(signal)).slice(
-            0,
-            Number(container.dataset.count ?? 5),
-        );
-        if (signal.aborted) return;
-        logger.debug(`refresh completed; posts=${posts.length}`);
-        list.innerHTML = posts.length
-            ? render(posts)
-            : `<li class="no-posts">${container.dataset.noPosts ?? fallback}</li>`;
-    } catch (error) {
-        if (signal.aborted) return;
-        logger.error("refresh failed; showing fallback", error);
-        list.innerHTML = `<li class="error">${container.dataset.loadFailed ?? fallback}</li>`;
-    } finally {
-        if (!signal.aborted) list.style.opacity = "1";
-    }
-}
-
-registerPageLifecycle("random-posts", () => {
+export function mountRandomPosts(): (() => void) | undefined {
     const container = document.querySelector<HTMLElement>("[data-stalux-random-posts]");
-    if (!container) return;
+    const list = container?.querySelector<HTMLElement>("#random-posts-list");
+    if (!container || !list) return;
     const controller = new AbortController();
+    const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
     const fallback = container.dataset.loadError ?? "Failed to load posts";
+    let request: AbortController | undefined;
+    let animation: Animation | undefined;
+    let revision = 0;
+    let disposed = false;
+    const cancelAnimation = () => {
+        const previous = animation;
+        animation = undefined;
+        previous?.cancel();
+    };
+    const reveal = () => {
+        if (reducedMotion.matches || document.hidden || typeof list.animate !== "function") return;
+        try {
+            // Real titles can wrap the sidebar beyond the same bounded-region
+            // budget used for route effects. Keep that result immediately readable.
+            if (list.getBoundingClientRect().height > Math.min(420, window.innerHeight * 0.6))
+                return;
+            const current = list.animate(
+                { opacity: [0.82, 1] },
+                { duration: 100, easing: "ease-out" },
+            );
+            animation = current;
+            const release = () => {
+                // A completed old effect cannot release a newer refresh cue.
+                if (animation === current) animation = undefined;
+                current.cancel();
+            };
+            void current.finished.then(release, release);
+        } catch {
+            // The authored list stays fully readable when animation is unavailable.
+        }
+    };
+    const refresh = async () => {
+        // Latest click wins, including fetch implementations whose pending JSON
+        // decoding cannot be interrupted by AbortSignal.
+        request?.abort();
+        const current = new AbortController();
+        request = current;
+        const token = ++revision;
+        const isCurrent = () => !disposed && token === revision && !current.signal.aborted;
+        cancelAnimation();
+        container.setAttribute("aria-busy", "true");
+        try {
+            logger.debug("refresh started");
+            const posts = shuffle(await fetchPosts(current.signal)).slice(
+                0,
+                Number(container.dataset.count ?? 5),
+            );
+            if (!isCurrent()) return;
+            logger.debug(`refresh completed; posts=${posts.length}`);
+            list.innerHTML = posts.length
+                ? render(posts)
+                : `<li class="no-posts">${container.dataset.noPosts ?? fallback}</li>`;
+            reveal();
+        } catch (error) {
+            if (!isCurrent()) return;
+            logger.error("refresh failed; showing fallback", error);
+            list.innerHTML = `<li class="error">${container.dataset.loadFailed ?? fallback}</li>`;
+        } finally {
+            if (isCurrent()) {
+                request = undefined;
+                container.removeAttribute("aria-busy");
+            }
+        }
+    };
     container.querySelector("#refresh-random-posts")?.addEventListener(
         "click",
         (event) => {
             event.preventDefault();
-            void refresh(container, fallback, controller.signal);
+            void refresh();
         },
         { signal: controller.signal },
     );
-    void refresh(container, fallback, controller.signal);
-    return () => controller.abort();
-});
+    reducedMotion.addEventListener("change", cancelAnimation, { signal: controller.signal });
+    void refresh();
+    return () => {
+        disposed = true;
+        revision++;
+        request?.abort();
+        controller.abort();
+        cancelAnimation();
+        container.removeAttribute("aria-busy");
+    };
+}
+
+registerPageLifecycle("random-posts", mountRandomPosts);

package/src/scripts/route-motion.ts

@@ -12,6 +12,7 @@ export interface RouteMotionEvent {
 
 export interface RouteMotionOptions {
     skip?: boolean;
+    /** Use a bounded introductory region around the marked heading. */
     content?: boolean;
     preset?: RouteMotionPreset;
     browserMotion?: boolean;
@@ -62,21 +63,42 @@ function completion() {
     return { promise, resolve };
 }
 
-/** A deep history restore must not scroll to or animate an off-screen title. */
-function isVisibleHeading(heading: HTMLElement): boolean {
-    if (!heading.isConnected || !heading.hasAttribute("data-stalux-motion-focus")) return false;
-    const rect = heading.getBoundingClientRect();
-    return (
-        rect.width > 0 &&
-        rect.height > 0 &&
-        rect.height <= Math.min(320, window.innerHeight / 2) &&
-        rect.top < window.innerHeight &&
-        rect.bottom > 0 &&
-        rect.left < window.innerWidth &&
-        rect.right > 0
-    );
+/** A route transition never captures a long article, list, or off-screen heading. */
+export function getRouteMotionTarget(focus: HTMLElement | null): HTMLElement | null {
+    if (!focus?.isConnected || !focus.hasAttribute("data-stalux-motion-focus")) return null;
+    const visible = (element: HTMLElement, maxHeight: number) => {
+        const rect = element.getBoundingClientRect();
+        return (
+            rect.width > 0 &&
+            rect.height > 0 &&
+            rect.height <= maxHeight &&
+            rect.top < window.innerHeight &&
+            rect.bottom > 0 &&
+            rect.left < window.innerWidth &&
+            rect.right > 0
+        );
+    };
+    if (!visible(focus, Math.min(320, window.innerHeight / 2))) return null;
+    const region = focus.closest?.<HTMLElement>("[data-stalux-motion-region]");
+    return region?.isConnected && visible(region, Math.min(420, window.innerHeight * 0.6))
+        ? region
+        : focus;
 }
 
+const regionMotions: Record<Exclude<RouteMotionPreset, "none">, HeadingMotion> = {
+    glide: { opacity: 0.72, duration: 160 },
+    article: { opacity: 0.72, duration: 180, y: 4 },
+    enter: { opacity: 0.72, duration: 180, y: 6 },
+    up: { opacity: 0.8, duration: 160, y: -4 },
+    taxonomy: { opacity: 0.72, duration: 160, x: 6 },
+    previous: { opacity: 0.76, duration: 180, x: -8 },
+    next: { opacity: 0.76, duration: 180, x: 8 },
+    panel: { opacity: 0.76, duration: 160, y: 4 },
+    home: { opacity: 0.76, duration: 180, y: 4 },
+    restore: { opacity: 1, duration: 0 },
+    error: { opacity: 0.85, duration: 100 },
+};
+
 /** Share Swup's actual content animation with background and analytics consumers. */
 export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
     const native = event.viewTransition;
@@ -130,35 +152,33 @@ export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
             try {
                 const preset = options?.preset ?? "glide";
                 const mobile = window.matchMedia?.("(max-width: 768px)").matches;
+                const target = getRouteMotionTarget(heading);
                 if (
-                    !heading ||
+                    !target ||
                     preset === "none" ||
                     (options?.content && preset === "restore") ||
                     options?.skip ||
                     options?.browserMotion ||
                     document.hidden ||
                     window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ||
-                    typeof heading.animate !== "function" ||
-                    !(options?.content ? heading.isConnected : isVisibleHeading(heading)) ||
+                    typeof target.animate !== "function" ||
                     (mobile && preset === "restore")
                 ) {
                     animationDone.resolve();
                     return;
                 }
-                const spec = options?.content
-                    ? { opacity: 0, duration: mobile ? 180 : 220, y: mobile ? 8 : 16 }
-                    : headingMotions[preset];
+                const spec = options?.content ? regionMotions[preset] : headingMotions[preset];
                 const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
-                // Content uses a short vertical entry on both breakpoints. Legacy
-                // heading cues retain their motionless phone fallback.
-                if ((options?.content || !mobile) && (spec.x || spec.y)) {
+                // Phones use a pure fade. Explicit previous/next alone imply a
+                // lateral reading direction; history never replays the entry.
+                if (!mobile && (spec.x || spec.y)) {
                     keyframes.transform = [
                         `translate3d(${spec.x ?? 0}px, ${spec.y ?? 0}px, 0)`,
                         "translate3d(0px, 0px, 0)",
                     ];
                 }
-                animation = heading.animate(keyframes, {
-                    duration: options?.content ? spec.duration : mobile ? 80 : spec.duration,
+                animation = target.animate(keyframes, {
+                    duration: mobile ? (options?.content ? 120 : 80) : spec.duration,
                     easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
                     fill: "both",
                 });

package/src/scripts/route-out.ts

@@ -1,3 +1,5 @@
+import { getRouteMotionTarget } from "./route-motion";
+
 /** Fade the old content only after destination assets are ready. */
 export async function animateRouteOut(
     element: HTMLElement | null,
@@ -10,16 +12,21 @@ export async function animateRouteOut(
         window.matchMedia("(prefers-reduced-motion: reduce)").matches
     )
         return () => {};
+    const target = getRouteMotionTarget(element);
+    if (!target || typeof target.animate !== "function") return () => {};
     let animation: Animation | undefined;
     const cancel = () => animation?.cancel();
+    const mobile = window.matchMedia("(max-width: 768px)").matches;
     try {
-        animation = element.animate(
-            { opacity: [1, 0], transform: ["translateY(0)", "translateY(-8px)"] },
-            { duration: 140, easing: "cubic-bezier(0.4, 0, 1, 1)", fill: "forwards" },
+        animation = target.animate(
+            mobile
+                ? { opacity: [1, 0.82] }
+                : { opacity: [1, 0.82], transform: ["translateY(0)", "translateY(-4px)"] },
+            { duration: 80, easing: "cubic-bezier(0.4, 0, 1, 1)", fill: "forwards" },
         );
         signal.addEventListener("abort", cancel, { once: true });
         await animation.finished;
-        // Keep the old page hidden until swap, but release effects on abort.
+        // Keep the bounded outgoing cue until swap; the body stays readable.
         // Swup detaches this node; no persistent shell is animated.
     } catch {
         /* Cancellation and unsupported animation must not block a visit. */

package/src/scripts/swup-router.ts

@@ -125,12 +125,15 @@ export function installSwupRouter(): Swup {
                         in: async (_done, { visit }) => {
                             const context = contexts.get(visit);
                             if (!context?.motion) return;
-                            context.motion.start(document.querySelector<HTMLElement>(MAIN), {
-                                preset: context.preset,
-                                content: true,
-                                browserMotion: context.browserMotion,
-                                skip: context.controller.signal.aborted,
-                            });
+                            context.motion.start(
+                                document.querySelector<HTMLElement>("[data-stalux-motion-focus]"),
+                                {
+                                    preset: context.preset,
+                                    content: true,
+                                    browserMotion: context.browserMotion,
+                                    skip: context.controller.signal.aborted,
+                                },
+                            );
                             await context.motion.finished;
                         },
                     },
@@ -251,7 +254,7 @@ export function installSwupRouter(): Swup {
         // Keep the old page readable until HTML, styles and fonts are ready.
         if (context.navigationType !== "traverse" && context.preset !== "none") {
             context.releaseOutgoing = await animateRouteOut(
-                document.querySelector<HTMLElement>(MAIN),
+                document.querySelector<HTMLElement>("[data-stalux-motion-focus]"),
                 context.controller.signal,
             );
             if (context.controller.signal.aborted || visit !== swup.visit) {
@@ -266,8 +269,6 @@ export function installSwupRouter(): Swup {
         html.dataset.staluxVtPreset = context.preset;
         context.motion = prepareRouteMotion(dispatchNavigation("astro:before-swap", context, next));
         if (context.controller.signal.aborted) return;
-        if (context.navigationType !== "traverse" && context.preset !== "none")
-            html.dataset.staluxMotionPending = "";
         await replace(visit, args);
         context.releaseOutgoing?.();
         if (context.controller.signal.aborted) return;
@@ -327,7 +328,7 @@ export function installSwupRouter(): Swup {
         const context = contexts.get(visit);
         if (!context || context !== activeContext || visit !== swup.visit) return;
         delete document.documentElement.dataset.staluxMotionPending;
-        context?.motion?.start(document.querySelector<HTMLElement>(MAIN), {
+        context?.motion?.start(document.querySelector<HTMLElement>("[data-stalux-motion-focus]"), {
             preset: context.preset,
             content: true,
             skip: !visit.animation.animate || context.controller.signal.aborted,

package/src/scripts/tags-cloud.ts

@@ -35,16 +35,18 @@ function parseTags(value: string | undefined): LinkTag[] {
     }
 }
 
-registerPageLifecycle("tags-cloud", () => {
+export function mountTagsCloud(): (() => void) | undefined {
     const container = document.getElementById("tags-canvas");
     if (!container) return;
     const desktop = window.matchMedia("(min-width: 769px)");
+    const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
     const controller = new AbortController();
     let cloud: import("@xingwangzhe/tags-cloud").TagCloud | undefined;
     let visible = false;
     let loading = false;
     let disposed = false;
-    const active = () => !disposed && desktop.matches && visible && !document.hidden;
+    const active = () =>
+        !disposed && desktop.matches && !reducedMotion.matches && visible && !document.hidden;
     const update = async () => {
         if (!active()) {
             // destroy also cancels the library's rAF; pause() only skips drawing.
@@ -94,6 +96,7 @@ registerPageLifecycle("tags-cloud", () => {
     );
     observer.observe(container);
     desktop.addEventListener("change", update, { signal: controller.signal });
+    reducedMotion.addEventListener("change", update, { signal: controller.signal });
     document.addEventListener("visibilitychange", update, { signal: controller.signal });
     return () => {
         disposed = true;
@@ -101,4 +104,6 @@ registerPageLifecycle("tags-cloud", () => {
         observer.disconnect();
         cloud?.destroy();
     };
-});
+}
+
+registerPageLifecycle("tags-cloud", mountTagsCloud);

package/src/styles/base.css

@@ -272,7 +272,7 @@
         background: #2a2a2a;
     }
 
-    /* 背景层 - 双层随机背景，在路由切换时交叉淡入淡出 */
+    /* 持久背景层：完整文档首次解码后淡显，软导航保持原图。 */
     .bg-layer {
         position: fixed;
         inset: 0;
@@ -284,7 +284,7 @@
         filter: var(--stalux-bg-filter, none);
         pointer-events: none;
         opacity: 0;
-        transition: opacity 650ms ease-in-out;
+        transition: opacity 200ms ease-out;
         /* 禁止浏览器强制色彩模式（高对比度/暗黑模式）调整背景图颜色 */
         forced-color-adjust: none;
         /* 关键：防止 Safari/WebKit 在暗色模式下自动调整 SVG 背景图颜色 */