@xingwangzhe/stalux 1.48.0 → 1.49.0

package/README.md

@@ -14,7 +14,9 @@ All HTML routes include a circular back-to-top button in the footer. It appears
 
 The homepage typewriter is built into Stalux and continues to use the `items` string list in `stalux/config/typetexts.yml`, with no new configuration. Defaults are 100ms per typed grapheme, 33ms per deleted grapheme, a 1500ms hold, and a 500ms pause after deletion. It pauses outside the viewport or in background tabs and cleans up on soft navigation. Reduced motion displays whole messages without a blinking cursor. Without JavaScript, the first message remains visible; screen readers and print receive the complete list.
 
-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.
+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.
 
 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.48.0",
+    "version": "1.49.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

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

@@ -39,9 +39,13 @@ const icon = link.icon ?? link.avatar ?? "/favicon.ico";
     <div class="stalux-link-card">
         <div class="stalux-link-card-avatar">
             <img
-                src={icon}
+                src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
+                data-src={icon}
+                data-stalux-link-icon
                 alt={t("links.iconAlt", { name: title })}
                 loading="lazy"
+                decoding="async"
+                fetchpriority="low"
                 width="80"
                 height="80"
             >

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

@@ -17,3 +17,5 @@ const links = linksConfig?.sites ?? [];
         </li>
     ))}
 </ul>
+
+<script src="../../../scripts/link-icons.ts"></script>

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

@@ -128,6 +128,7 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/, "")}.md` : "
     <!-- Article Body -->
     <section
         class="stalux-post-body stalux-prose"
+        data-stalux-gallery-body
         data-stalux-motion-content
         data-pagefind-body
         data-stalux-post-id={props.postId === undefined ? undefined : String(props.postId)}

package/src/index.ts

@@ -64,6 +64,7 @@ import { createViteAliases } from "./internal/vite-aliases";
 import { webMcpMutationsPlugin } from "./internal/webmcp-mutations";
 import { featureFlagsHast, featureFlagsMdast } from "./plugins/feature-flags";
 import { imageCaptions } from "./plugins/image-captions";
+import { imageDimensions } from "./plugins/image-dimensions";
 import { temml } from "./plugins/satteri-temml";
 import { describeError } from "./utils/diagnostics";
 
@@ -293,6 +294,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             }),
                             seen,
                         );
+                        // Dimensions must land before PhotoSwipe copies them onto the link.
+                        appendUniquePlugin(processorOptions.hastPlugins, imageDimensions, seen);
                         appendUniquePlugin(processorOptions.hastPlugins, photoswipe(), seen);
                         appendUniquePlugin(processorOptions.hastPlugins, imageCaptions, seen);
                         appendUniquePlugin(processorOptions.hastPlugins, featureFlagsHast, seen);

package/src/plugins/image-dimensions.ts

@@ -0,0 +1,34 @@
+import { defineHastPlugin } from "satteri";
+
+/**
+ * Markdown 图片标题里的 `宽x高` 是外部图片的尺寸声明，不是给读者看的提示。
+ *
+ * 外部图片无法在构建期读取像素尺寸，浏览器只能等下载完才知道比例，正文会被
+ * 推开（CLS）。写成 `![alt](https://… "532x200")` 后，这里在 HAST 阶段补上
+ * width/height，PhotoSwipe 也能拿到 data-pswp-width/height；标题本身随即移除。
+ */
+const DIMENSION_TITLE = /^(\d{1,6})\s*[x×]\s*(\d{1,6})$/u;
+
+export const imageDimensions = defineHastPlugin({
+    name: "stalux-image-dimensions",
+    element: {
+        filter: ["img"],
+        visit(node, ctx) {
+            const title = node.properties?.title;
+            if (typeof title !== "string") return;
+            const match = DIMENSION_TITLE.exec(title.trim());
+            if (!match) return;
+            const width = Number(match[1]);
+            const height = Number(match[2]);
+            if (!(width > 0 && height > 0)) return;
+            if (node.properties?.width === undefined) {
+                ctx.setProperty(node, "width", String(width));
+            }
+            if (node.properties?.height === undefined) {
+                ctx.setProperty(node, "height", String(height));
+            }
+            // 尺寸声明已转成属性，不再让浏览器把它当成悬浮提示。
+            ctx.setProperty(node, "title", undefined);
+        },
+    },
+});

package/src/scripts/analytics-runtime.ts

@@ -202,6 +202,105 @@ function initializeClarity(id: string): void {
     });
 }
 
+/**
+ * GA's SDK is 195 KB compressed / ~610 KB parsed, larger than every first-party
+ * asset combined. The dataLayer queue and the page_view snapshot do not need it:
+ * events are pushed immediately and consumed when the SDK finally arrives.
+ * Loading is gated on the same signals that mean "first paint is done" instead
+ * of `window.load`, which slow third-party resources can postpone forever.
+ */
+const GOOGLE_SDK_FLOOR_MS = 1200;
+const GOOGLE_SDK_LCP_QUIET_MS = 600;
+const GOOGLE_SDK_CEILING_MS = 6000;
+let googleSdkStarted = false;
+let googleGateInstalled = false;
+let googleGateOpen = false;
+
+function runBackgroundTask(callback: () => void): void {
+    const scheduler = (
+        window as Window & {
+            scheduler?: {
+                postTask: (
+                    task: () => void,
+                    options: { priority: "background" },
+                ) => Promise<unknown>;
+            };
+        }
+    ).scheduler;
+    if (scheduler?.postTask) {
+        void scheduler
+            .postTask(callback, { priority: "background" })
+            .catch(() => setTimeout(callback, 0));
+        return;
+    }
+    setTimeout(callback, 0);
+}
+
+function startGoogleSdk(): void {
+    if (googleSdkStarted || !state.googleId) return;
+    googleSdkStarted = true;
+    void loadTrackerScript(
+        `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(state.googleId)}`,
+        { "data-stalux-google": "true" },
+    ).catch(() => logger.debug("Google SDK unavailable; queued events retained"));
+}
+
+/** Three independent doors: first input, LCP quiet, and a hard ceiling after parsing. */
+function installGoogleGate(): void {
+    if (googleGateInstalled) return;
+    googleGateInstalled = true;
+    const startedAt = performance.now();
+    const floorAt = startedAt + GOOGLE_SDK_FLOOR_MS;
+    const ceilingAt = startedAt + GOOGLE_SDK_CEILING_MS;
+    let quietTimer: ReturnType<typeof setTimeout> | undefined;
+    let ceilingTimer: ReturnType<typeof setTimeout> | undefined;
+    let observer: PerformanceObserver | undefined;
+
+    const cleanup = () => {
+        for (const type of ["pointerdown", "keydown", "wheel", "touchstart"]) {
+            window.removeEventListener(type, handleInteraction);
+        }
+        if (quietTimer !== undefined) clearTimeout(quietTimer);
+        if (ceilingTimer !== undefined) clearTimeout(ceilingTimer);
+        observer?.disconnect();
+        observer = undefined;
+    };
+    const open = () => {
+        if (googleGateOpen) return;
+        googleGateOpen = true;
+        cleanup();
+        // Never compete with the input that just opened the gate.
+        runBackgroundTask(startGoogleSdk);
+    };
+    function handleInteraction(): void {
+        open();
+    }
+    const scheduleQuiet = () => {
+        if (googleGateOpen) return;
+        if (quietTimer !== undefined) clearTimeout(quietTimer);
+        const wait = Math.max(GOOGLE_SDK_LCP_QUIET_MS, floorAt - performance.now());
+        quietTimer = setTimeout(() => {
+            quietTimer = undefined;
+            if (performance.now() >= floorAt) open();
+            else scheduleQuiet();
+        }, wait);
+    };
+
+    if ("PerformanceObserver" in window) {
+        try {
+            observer = new window.PerformanceObserver(scheduleQuiet);
+            observer.observe({ type: "largest-contentful-paint", buffered: true });
+        } catch {
+            // Older engines may know the constructor but not this entry type.
+        }
+    }
+    for (const type of ["pointerdown", "keydown", "wheel", "touchstart"]) {
+        window.addEventListener(type, handleInteraction, { passive: true, once: true });
+    }
+    ceilingTimer = setTimeout(open, Math.max(0, ceilingAt - startedAt));
+    if (document.hidden) open();
+}
+
 function initializeTrackers(): void {
     const config = document.body?.dataset;
     if (!config) return;
@@ -218,10 +317,10 @@ function initializeTrackers(): void {
             host.gtag("js", new Date());
             host.gtag("config", state.googleId, { send_page_view: false });
         }
-        void loadTrackerScript(
-            `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(state.googleId)}`,
-            { "data-stalux-google": "true" },
-        ).catch(() => logger.debug("Google SDK unavailable; queued events retained"));
+        installGoogleGate();
+        // A navigation can expose the measurement ID after the first document
+        // already opened its gate; in that case load immediately.
+        if (googleGateOpen) startGoogleSdk();
     }
     if (config.staluxClarityId) initializeClarity(config.staluxClarityId);
 }

package/src/scripts/link-icons.ts

@@ -0,0 +1,54 @@
+/**
+ * Link-page icons come from arbitrary third-party hosts. Native lazy loading
+ * still fetches everything within the browser's large lazy threshold (up to
+ * 3000px), and a single link list therefore pulled several megabytes of
+ * avatars that the reader never reached. Load only icons near the viewport.
+ */
+import { createClientLogger } from "./logger";
+import { registerPageLifecycle } from "./page-runtime";
+
+const logger = createClientLogger("link-icons");
+
+function reveal(image: HTMLImageElement): void {
+    const source = image.dataset.src;
+    if (!source) return;
+    delete image.dataset.src;
+    image.addEventListener(
+        "error",
+        () => {
+            // Keep the reserved box; the stylesheet draws a neutral disc instead.
+            image.removeAttribute("src");
+            image.dataset.staluxLinkIconFailed = "true";
+            logger.debug("link icon failed to load; placeholder retained");
+        },
+        { once: true },
+    );
+    image.src = source;
+}
+
+export function mountLinkIcons(): (() => void) | undefined {
+    const images = Array.from(
+        document.querySelectorAll<HTMLImageElement>("img[data-stalux-link-icon]"),
+    );
+    if (!images.length) return;
+
+    if (!("IntersectionObserver" in window)) {
+        for (const image of images) reveal(image);
+        return;
+    }
+
+    const observer = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                observer.unobserve(entry.target);
+                reveal(entry.target as HTMLImageElement);
+            }
+        },
+        { rootMargin: "400px 0px" },
+    );
+    for (const image of images) observer.observe(image);
+    return () => observer.disconnect();
+}
+
+registerPageLifecycle("link-icons", mountLinkIcons);

package/src/scripts/photoswipe.ts

@@ -6,6 +6,9 @@ import { createRetryableInitializer } from "./retryable-initializer";
 const logger = createClientLogger("photoswipe");
 
 const GALLERY_SELECTOR = "a.pswp-gallery-item";
+// The article header, summary and keyword span also carry data-pagefind-body.
+// Selecting the first of those gave PhotoSwipe an empty gallery (counter "1 / 0").
+const GALLERY_CONTAINER_SELECTOR = "[data-stalux-gallery='true'] [data-stalux-gallery-body]";
 
 async function enrichPhotoSwipeData(container: Element, signal: AbortSignal): Promise<void> {
     const links = container.querySelectorAll<HTMLAnchorElement>(GALLERY_SELECTOR);
@@ -40,9 +43,7 @@ async function enrichPhotoSwipeData(container: Element, signal: AbortSignal): Pr
 }
 
 registerPageLifecycle("photoswipe", () => {
-    const container = document.querySelector<HTMLElement>(
-        "[data-stalux-gallery='true'] [data-pagefind-body]",
-    );
+    const container = document.querySelector<HTMLElement>(GALLERY_CONTAINER_SELECTOR);
     if (!container) return;
 
     const controller = new AbortController();

package/src/scripts/random-posts.ts

@@ -106,21 +106,47 @@ export function mountRandomPosts(): (() => void) | undefined {
             }
         }
     };
+    let started = false;
+    let observer: IntersectionObserver | undefined;
+    const start = () => {
+        if (started || disposed) return;
+        started = true;
+        observer?.disconnect();
+        observer = undefined;
+        void refresh();
+    };
     container.querySelector("#refresh-random-posts")?.addEventListener(
         "click",
         (event) => {
             event.preventDefault();
+            if (!started) {
+                start();
+                return;
+            }
             void refresh();
         },
         { signal: controller.signal },
     );
     reducedMotion.addEventListener("change", cancelAnimation, { signal: controller.signal });
-    void refresh();
+    if ("IntersectionObserver" in window) {
+        // The sidebar sits below the article on phones; do not fetch its index
+        // until the reader is close enough to see it.
+        observer = new IntersectionObserver(
+            (entries) => {
+                if (entries.some((entry) => entry.isIntersecting)) start();
+            },
+            { rootMargin: "300px 0px" },
+        );
+        observer.observe(container);
+    } else {
+        start();
+    }
     return () => {
         disposed = true;
         revision++;
         request?.abort();
         controller.abort();
+        observer?.disconnect();
         cancelAnimation();
         container.removeAttribute("aria-busy");
     };

package/src/styles/generated-links.css

@@ -1,3 +1,3 @@
 @layer theme, base, components, utilities;
-@layer components{.stalux-link-card{color:#fff;box-sizing:border-box;background:var(--surface-glass);width:100%;min-width:0;min-height:200px;box-shadow:var(--card-box-shadow);border-radius:10px;flex-direction:column;padding:16px;text-decoration:none;transition:transform .22s,background-color .22s,border-color .22s;display:flex;overflow:visible}.stalux-link-card-content{text-align:center;flex-direction:column;flex:1;display:flex}.stalux-links{box-sizing:border-box;grid-template-columns:repeat(auto-fill,minmax(min(180px,100%),1fr));gap:20px;width:100%;max-width:1600px;margin:30px auto;padding:0 1rem;list-style-type:none;display:grid}.stalux-link-card-avatar{justify-content:center;margin-bottom:12px;display:flex}.stalux-link-list-item{width:100%;min-width:0;display:flex}.stalux-link-shell{width:100%;min-width:0}.stalux-link-card-content{transition:transform .2s}.stalux-link-card-avatar img{object-fit:cover;border:2px solid var(--accent-60p);transform-origin:50%;border-radius:9999px;width:80px;height:80px;transition:transform .22s,border-color .22s}.stalux-link-card-title{white-space:nowrap;background:linear-gradient(90deg, var(--white-95p), var(--accent-90p));color:#0000;text-overflow:ellipsis;background-clip:text;margin:0 0 8px;font-size:1.1rem;overflow:hidden}.stalux-link-card-description{color:var(--white-78p);-webkit-line-clamp:3;text-overflow:ellipsis;-webkit-box-orient:vertical;margin:0;font-size:.95rem;line-height:1.45;display:-webkit-box;overflow:hidden}@media (1100px<=width<=1399px){.stalux-links{grid-template-columns:repeat(4,minmax(0,1fr))}}@media (480px<=width<=767px){.stalux-links{grid-template-columns:repeat(2,minmax(0,1fr));gap:16px}}@media (768px<=width<=1099px){.stalux-links{grid-template-columns:repeat(3,minmax(0,1fr))}}@media (hover:hover) and (pointer:fine){.stalux-link-shell:hover .stalux-link-card-content{transform:translateY(-2px)}.stalux-link-shell:hover .stalux-link-card{background:var(--white-05p);box-shadow:var(--card-box-shadow-hover)}.stalux-link-card-avatar:hover img{border-color:var(--accent-85p);transform:rotate(3deg)}}@media (width>=1400px){.stalux-links{grid-template-columns:repeat(5,minmax(0,1fr))}}@media (width<=480px){.stalux-link-card{padding:14px}.stalux-link-card-avatar img{width:70px;height:70px}.stalux-link-card-title{font-size:1rem}.stalux-link-card-description{font-size:.9rem}}@media (width<=479px){.stalux-links{grid-template-columns:1fr;gap:14px;margin:20px auto}}@media (prefers-reduced-motion:reduce) and (hover:hover) and (pointer:fine){.stalux-link-card-avatar:hover img{transition:none;animation:none;transform:none}}}@layer utilities,theme,base;
+@layer components{.stalux-link-card{color:#fff;box-sizing:border-box;background:var(--surface-glass);width:100%;min-width:0;min-height:200px;box-shadow:var(--card-box-shadow);border-radius:10px;flex-direction:column;padding:16px;text-decoration:none;transition:transform .22s,background-color .22s,border-color .22s;display:flex;overflow:visible}.stalux-link-card-content{text-align:center;flex-direction:column;flex:1;display:flex}.stalux-links{box-sizing:border-box;grid-template-columns:repeat(auto-fill,minmax(min(180px,100%),1fr));gap:20px;width:100%;max-width:1600px;margin:30px auto;padding:0 1rem;list-style-type:none;display:grid}.stalux-link-card-avatar{justify-content:center;margin-bottom:12px;display:flex}.stalux-link-list-item{width:100%;min-width:0;display:flex}.stalux-link-shell{width:100%;min-width:0}.stalux-link-card-content{transition:transform .2s}.stalux-link-card-avatar img{object-fit:cover;border:2px solid var(--accent-60p);transform-origin:50%;border-radius:9999px;width:80px;height:80px;transition:transform .22s,border-color .22s}.stalux-link-card-avatar img[data-src],.stalux-link-card-avatar img[data-stalux-link-icon-failed]{background:var(--white-05p)}.stalux-link-card-title{white-space:nowrap;background:linear-gradient(90deg, var(--white-95p), var(--accent-90p));color:#0000;text-overflow:ellipsis;background-clip:text;margin:0 0 8px;font-size:1.1rem;overflow:hidden}.stalux-link-card-description{color:var(--white-78p);-webkit-line-clamp:3;text-overflow:ellipsis;-webkit-box-orient:vertical;margin:0;font-size:.95rem;line-height:1.45;display:-webkit-box;overflow:hidden}@media (1100px<=width<=1399px){.stalux-links{grid-template-columns:repeat(4,minmax(0,1fr))}}@media (480px<=width<=767px){.stalux-links{grid-template-columns:repeat(2,minmax(0,1fr));gap:16px}}@media (768px<=width<=1099px){.stalux-links{grid-template-columns:repeat(3,minmax(0,1fr))}}@media (hover:hover) and (pointer:fine){.stalux-link-shell:hover .stalux-link-card-content{transform:translateY(-2px)}.stalux-link-shell:hover .stalux-link-card{background:var(--white-05p);box-shadow:var(--card-box-shadow-hover)}.stalux-link-card-avatar:hover img{border-color:var(--accent-85p);transform:rotate(3deg)}}@media (width>=1400px){.stalux-links{grid-template-columns:repeat(5,minmax(0,1fr))}}@media (width<=480px){.stalux-link-card{padding:14px}.stalux-link-card-avatar img{width:70px;height:70px}.stalux-link-card-title{font-size:1rem}.stalux-link-card-description{font-size:.9rem}}@media (width<=479px){.stalux-links{grid-template-columns:1fr;gap:14px;margin:20px auto}}@media (prefers-reduced-motion:reduce) and (hover:hover) and (pointer:fine){.stalux-link-card-avatar:hover img{transition:none;animation:none;transform:none}}}@layer utilities,theme,base;
 /*$vite$:1*/