@xingwangzhe/stalux 1.55.2 → 1.55.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.55.2",
+    "version": "1.55.4",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/scripts/swup-router.ts

@@ -438,25 +438,20 @@ export function installSwupRouter(): Swup {
         // then watch it jump to the entry offset and slide back, which reads as
         // the page shaking. Put the scroll at its final position and start the
         // cue in this same synchronous block, before the scripts run, so the
-        // compositor already owns the cue while the main thread is busy. A visit
-        // with a hash or a history traversal keeps the deferred path, because its
-        // scroll is not decided yet.
-        if (
-            // A history traversal restores a position that is only known later,
-            // and a hash target is decided by the anchor.
-            !visit.history.popstate &&
-            context.navigationType !== "traverse" &&
-            !context.to.hash &&
-            context.preset !== "none" &&
-            // ScrollPlugin owns visit.scroll; a bare visit has no reset flag.
-            visit.scroll?.reset !== false
-        ) {
-            const position = scroll.getCachedScrollPositions?.(visit.to.url)?.window;
-            const top = position?.top ?? 0;
-            const left = position?.left ?? 0;
-            if (window.scrollY !== top || window.scrollX !== left)
-                window.scrollTo({ top, left, behavior: "instant" });
-            startMotion(visit);
+        // compositor already owns the cue while the main thread is busy. Hash
+        // targets and history traversals are settled in content:scroll below.
+        // Entering a new document from a link always starts at its top. The
+        // motion preset (reduced motion / hidden tab) and the ScrollPlugin's
+        // reset flag are visual concerns, not navigation ones; neither may opt
+        // out of the reset. A cached offset belongs to history traversals only
+        // (handled in content:scroll) and must never pull a fresh page back
+        // into the middle of the previous article.
+        const startsFresh =
+            !visit.history.popstate && context.navigationType !== "traverse" && !context.to.hash;
+        if (startsFresh) {
+            if (window.scrollY !== 0 || window.scrollX !== 0)
+                window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+            if (context.preset !== "none" && visit.scroll?.reset !== false) startMotion(visit);
         }
         context.scriptsReady = context.executeScripts?.(context.controller.signal);
     });
@@ -464,15 +459,16 @@ export function installSwupRouter(): Swup {
     swup.hooks.replace(
         "content:scroll",
         async (visit, args, defaultScroll) => {
+            const context = contexts.get(visit);
             const saved = visit.history.popstate
                 ? historyPositions.get(Number(window.history.state?.index))
                 : undefined;
             if (visit.history.popstate) {
-                // ScrollPlugin defers unanimated popstate to the browser, but Swup
-                // uses manual restoration even for reduced motion and native swipes.
-                const position = saved ??
-                    scroll.getCachedScrollPositions(visit.to.url)?.window ?? { top: 0, left: 0 };
-                window.scrollTo({ top: position.top, left: position.left, behavior: "instant" });
+                // Every route change starts at the top. Restoring the exact
+                // mid-article offset on back/forward reads as "the navigation
+                // never scrolled"; keep only the focused link so keyboard users
+                // retain their place in the navigation.
+                window.scrollTo({ top: 0, left: 0, behavior: "instant" });
                 scroll.restoreScrollContainers(visit.to.url);
                 if (saved?.focus) {
                     const link = [...document.querySelectorAll<HTMLAnchorElement>("a[href]")].find(
@@ -487,6 +483,14 @@ export function installSwupRouter(): Swup {
             // ScrollPlugin scrolls in rAF; finish it before heading visibility checks.
             if (!document.hidden)
                 await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+            // That deferred frame may have restored a cached mid-article offset.
+            // A link navigation always wins: land the new document at its top.
+            if (
+                context?.navigationType !== "traverse" &&
+                !context?.to.hash &&
+                (window.scrollY !== 0 || window.scrollX !== 0)
+            )
+                window.scrollTo({ top: 0, left: 0, behavior: "instant" });
             startMotion(visit);
             return true;
         },

package/src/scripts/toc-scrollspy.ts

@@ -1,8 +1,36 @@
 import { initTocScrollSpy } from "../utils/toc-scrollspy";
 import { registerPageLifecycle } from "./page-runtime";
 
+/**
+ * 目录高亮初始化会读取全部标题位置，强制一次完整布局：线上文章页实测
+ * 226ms 长任务（JS 仅 21ms，其余是 Style & Layout），正好落在 TBT 统计窗口内。
+ * 而读者进入文章后通常先看开头，滚到需要高亮的时机远晚于首屏，
+ * 因此把它放到空闲时段；2s 兜底保证页面持续繁忙时仍会初始化。
+ */
 registerPageLifecycle("toc-scrollspy", () => {
     const container = document.querySelector<HTMLElement>("[data-toc-active-class]");
     const activeClass = container?.dataset.tocActiveClass;
-    return activeClass ? initTocScrollSpy(activeClass) : undefined;
+    if (!activeClass) return;
+    let cleanup: (() => void) | undefined;
+    let disposed = false;
+    const run = () => {
+        if (!disposed) cleanup = initTocScrollSpy(activeClass);
+    };
+    // 通过可选属性读取，避免 TS 把初始化值收窄成「必定存在」而报常真判断。
+    const idle = (
+        globalThis as {
+            requestIdleCallback?: (
+                callback: IdleRequestCallback,
+                options?: IdleRequestOptions,
+            ) => number;
+        }
+    ).requestIdleCallback;
+    const handle = idle ? idle(run, { timeout: 2000 }) : setTimeout(run, 300);
+    return () => {
+        disposed = true;
+        // requestIdleCallback 与 cancelIdleCallback 在支持后者的实现里总是成对出现。
+        if (idle) globalThis.cancelIdleCallback(handle as number);
+        else clearTimeout(handle as unknown as ReturnType<typeof setTimeout>);
+        cleanup?.();
+    };
 });