@xingwangzhe/stalux 1.49.0 → 1.50.0

package/README.md

@@ -16,7 +16,7 @@ The homepage typewriter is built into Stalux and continues to use the `items` st
 
 Standalone images written as `![Image description](url)` receive a `figure` and `figcaption` through a build-time satteri HAST plugin. Captions appear as small, centered gray text below the image, preserving image alt text and the PhotoSwipe lightbox. No configuration or browser script is required. Empty descriptions, inline images, multiple images in one paragraph, and existing figures are left unchanged. Captions are plain text with automatic escaping. External images can declare intrinsic size in the markdown title: `![description](https://example.com/a.webp "1150x439")`. The build turns it into `width`/`height`, removes the tooltip title, and gives PhotoSwipe matching `data-pswp-width/height`; images without a size declaration keep their previous output.
 
-Friend-link icons are requested only when they approach the viewport (400px prefetch margin), instead of the browser's large native lazy window pulling every third-party avatar on the page. A failed icon keeps a placeholder disc and never affects the text content. The Google Analytics SDK loads after the first screen settles (first input, 600ms of stable LCP, or six seconds after parsing), while `page_view` snapshots and the dataLayer queue are still written during navigation without waiting for the SDK. The random-posts sidebar likewise requests its index only near the viewport.
+Friend-link icons are requested only when they approach the viewport (400px prefetch margin), instead of the browser's large native lazy window pulling every third-party avatar on the page. A failed icon keeps a placeholder disc and never affects the text content. The Google Analytics SDK loads after the first screen settles (first input, 600ms of stable LCP, or six seconds after parsing), while `page_view` snapshots and the dataLayer queue are still written during navigation without waiting for the SDK. The random-posts sidebar likewise requests its index only near the viewport. After the homepage settles (about one second after load, with a 2.5-second ceiling), the main navigation routes are warmed one at a time through Swup's preload cache and concurrency limit; saveData, 2G, reduced-data preferences and hidden tabs are skipped, and clicks reuse the cached pages.
 
 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.
 

package/package.json

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

package/src/layouts/Stalux.astro

@@ -80,6 +80,7 @@ const routeKind = getRouteKind(Astro.url.pathname);
     // against the article and archive components that also request it.
     import { mountListReveal } from "../scripts/list-reveal";
     import { registerPageLifecycle } from "../scripts/page-runtime";
+    import "../scripts/route-prefetch";
 
     registerPageLifecycle("list-reveal", mountListReveal);
     </script>

package/src/scripts/route-prefetch.ts

@@ -0,0 +1,120 @@
+/**
+ * Warm the main navigation routes after the homepage has settled.
+ *
+ * Swup already preloads hovered/focused links. This adds a low-priority,
+ * idle-time preload of the visible navigation routes, so the first click from
+ * the homepage can reuse Swup's page cache instead of fetching and parsing the
+ * document during the transition. The preload plugin enforces its own throttle,
+ * skips saveData/2G connections, deduplicates cached pages and ignores routes
+ * the router cannot handle.
+ */
+import { createClientLogger } from "./logger";
+import { registerPageLifecycle } from "./page-runtime";
+
+const logger = createClientLogger("route-prefetch");
+
+const AFTER_LOAD_DELAY_MS = 1000;
+const LOAD_CEILING_MS = 2500;
+const IDLE_TIMEOUT_MS = 2000;
+
+export function collectMainRouteUrls(
+    documentLike: Pick<Document, "querySelectorAll"> = document,
+    current = new URL(window.location.href),
+): string[] {
+    const urls = new Set<string>();
+    for (const anchor of documentLike.querySelectorAll<HTMLAnchorElement>(
+        'a[data-ref="stalux-nav-link"]',
+    )) {
+        let url: URL;
+        try {
+            url = new URL(anchor.href, current);
+        } catch {
+            continue;
+        }
+        if (url.origin !== current.origin) continue;
+        if (url.pathname === current.pathname && url.search === current.search) continue;
+        urls.add(`${url.pathname}${url.search}`);
+    }
+    return [...urls];
+}
+
+export function mountRoutePrefetch(): (() => void) | undefined {
+    if (typeof window === "undefined" || typeof document === "undefined") return;
+    if (document.documentElement.dataset.staluxRoute !== "home") return;
+    const reducedData = window.matchMedia?.("(prefers-reduced-data: reduce)");
+    if (reducedData?.matches) return;
+
+    let cancelled = false;
+    let scheduled = false;
+    let delayTimer: ReturnType<typeof setTimeout> | undefined;
+    let ceilingTimer: ReturnType<typeof setTimeout> | undefined;
+    let idleId: number | undefined;
+
+    const run = () => {
+        if (cancelled || document.hidden) return;
+        const swup = window.swup;
+        if (!swup || typeof swup.preload !== "function") {
+            logger.debug("swup preload API unavailable; skipping route prefetch");
+            return;
+        }
+        const urls = collectMainRouteUrls();
+        if (!urls.length) return;
+        logger.debug(`prefetching ${urls.length} main routes`);
+        // One document at a time: keep the prefetch invisible to the current
+        // page's main thread and network instead of parsing six documents at once.
+        let chain: Promise<unknown> = Promise.resolve();
+        for (const url of urls) {
+            chain = chain
+                .then(() => {
+                    if (cancelled) return;
+                    return swup.preload?.(url, { priority: false });
+                })
+                .catch(() => {
+                    // A failed warm-up must never affect navigation.
+                });
+        }
+        void chain;
+    };
+
+    const requestIdle = () => {
+        if (cancelled) return;
+        const idle = window.requestIdleCallback;
+        if (typeof idle === "function") {
+            idleId = idle(run, { timeout: IDLE_TIMEOUT_MS });
+            return;
+        }
+        idleId = setTimeout(run, 1) as unknown as number;
+    };
+
+    const schedule = () => {
+        if (scheduled || cancelled) return;
+        scheduled = true;
+        delayTimer = setTimeout(requestIdle, AFTER_LOAD_DELAY_MS);
+    };
+
+    if (document.readyState === "complete") {
+        schedule();
+    } else {
+        const onLoad = () => {
+            window.removeEventListener("load", onLoad);
+            schedule();
+        };
+        window.addEventListener("load", onLoad, { once: true });
+        // A slow image or third-party request must not postpone the warm-up forever.
+        ceilingTimer = setTimeout(() => {
+            window.removeEventListener("load", onLoad);
+            schedule();
+        }, LOAD_CEILING_MS);
+    }
+
+    return () => {
+        cancelled = true;
+        if (delayTimer !== undefined) clearTimeout(delayTimer);
+        if (ceilingTimer !== undefined) clearTimeout(ceilingTimer);
+        if (idleId === undefined) return;
+        if (typeof window.cancelIdleCallback === "function") window.cancelIdleCallback(idleId);
+        else clearTimeout(idleId);
+    };
+}
+
+registerPageLifecycle("route-prefetch", mountRoutePrefetch);