@xingwangzhe/stalux 1.28.4 → 1.29.0

package/.release/cli.mjs

@@ -14,6 +14,7 @@ function getConfigYamls() {
 lang: en
 title: "My Blog"
 description: "A blog built with Stalux theme"
+accentColor: "#EAB308" # Shared theme accent color (six-digit HEX)
 url: "https://example.com"
 timezone: "Asia/Shanghai"
 `,

package/README.md

@@ -40,6 +40,12 @@ export default defineConfig({
 });
 ```
 
+Set the optional `accentColor` in `stalux/config/site.yml` to customize the shared theme and Waline accent. It accepts a six-digit HEX color and defaults to `#EAB308`; choose a color with sufficient contrast against your background.
+
+```yaml title="stalux/config/site.yml"
+accentColor: "#EAB308"
+```
+
 To customize the bundled integrations, pass options (or disable them with `false`):
 
 ```ts

package/package.json

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

package/src/components/stalux/analytics/umami.astro

@@ -1,19 +1 @@
----
-import { getCollection } from "astro:content";
-import { getHeadData } from "@utils/config-utils";
-
-const configEntries = await getCollection("config");
-const headConfig = getHeadData(configEntries);
-const umamiConfig = headConfig?.umami;
-const umamiID = umamiConfig?.id;
-const umamiURL = umamiConfig?.url;
----
-
-<script
-    is:inline
-    defer
-    src={umamiURL}
-    data-website-id={umamiID}
-    type="text/javascript"
-    transition:persist="stalux-umami"
-></script>
+<script src="../../../scripts/umami.ts"></script>

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

@@ -58,18 +58,18 @@ const archiveYears = [...archivesByYearMonth.entries()]
             {archiveYears.length > 0 ? (
     archiveYears.map((archiveYear) => (
         <div class={styles.yearSection} data-year={String(archiveYear.year)}>
-            <div class={styles.yearHeader} data-year-header style="opacity:0">
+            <div class={styles.yearHeader}>
                 <h2 class={styles.yearTitle}>{archiveYear.year}</h2>
                 <div class={styles.yearCount}>
                     {t("archives.postCount", { n: archiveYear.count })}
                 </div>
             </div>
             {archiveYear.months.map(({ month, posts: monthPosts }) => (
-                <div class={styles.monthSection} data-month-section style="opacity:0">
+                <div class={styles.monthSection}>
                     <h3 class={styles.monthTitle}>{t("archives.month", { n: month })}</h3>
                     <ul class={styles.postList}>
                         {monthPosts.map((post) => (
-                            <li class={styles.postItem} data-post-item style="opacity:0">
+                            <li class={styles.postItem}>
                                 <time class={styles.postDate} datetime={post.data.date}>
                                     {format(parseDate(post.data.date), "yyyy-MM-dd")}
                                 </time>

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

@@ -8,7 +8,7 @@ const categoryList = await getCategoryCountList(Astro.logger);
 
 <ul class={`${styles.categoriesList} stagger-children`}>
     {categoryList.map((category) => (
-    <li class={styles.item} style="opacity:0">
+    <li class={styles.item}>
         <CategoriesCard category={category} />
     </li>
 ))}

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

@@ -6,3 +6,24 @@ import styles from "@styles/components/common/date.module.css";
     <time id={styles.date} data-ref="date" datetime=""></time>
     <time id={styles.time} data-ref="time" datetime=""></time>
 </div>
+
+<script is:inline>
+(() => {
+    const dateElement = document.querySelector('[data-ref="date"]');
+    const timeElement = document.querySelector('[data-ref="time"]');
+    if (!dateElement || !timeElement) return;
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    const lang = document.documentElement.lang || "zh-CN";
+    dateElement.textContent = lang.startsWith("zh")
+        ? `${now.getFullYear()}年${pad(now.getMonth() + 1)}月${pad(now.getDate())}日`
+        : new Intl.DateTimeFormat("en-US", {
+              year: "numeric",
+              month: "short",
+              day: "2-digit",
+          }).format(now);
+    dateElement.dateTime = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    timeElement.textContent = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+    timeElement.dateTime = timeElement.textContent;
+})();
+</script>

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

@@ -1,6 +1,5 @@
 ---
 import { getCollection } from "astro:content";
-import { fade } from "astro:transitions";
 import style from "@styles/components/posts/postTaxonomy.module.css";
 import { getSiteData } from "@utils/config-utils";
 import { createTranslator } from "@utils/i18n";
@@ -46,11 +45,7 @@ const cfg = {
 <nav class={style.container} transition:name={cfg.containerName} aria-label={title ?? cfg.heading}>
     {items.length > 0 && <h3 class={style.title}>{title ?? cfg.heading}</h3>}
     {items.length > 0 ? (
-    <div
-        class={cfg.listClass}
-        transition:name={cfg.contentName}
-        transition:animate={fade({ duration: "0.3s" })}
-    >
+    <div class={cfg.listClass} transition:name={cfg.contentName}>
         {items.map((item) => (
             <a href={`${cfg.prefix}${item}/`} class={`${cfg.itemClass} a-none`} data-astro-prefetch>
                 {item}

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

@@ -4,6 +4,7 @@ import { getCollection } from "astro:content";
 import style from "@styles/components/posts/postCard.module.css";
 import { getSiteData } from "@utils/config-utils";
 import { toMachineDateTime } from "@utils/semantic-time";
+import { getPostTitleTransitionName } from "@utils/view-transitions";
 
 interface Props {
     post: CollectionEntry<"posts">;
@@ -41,7 +42,10 @@ const description = post.data.desc || "";
         </div>
     </a>
 )}
-        <h2 class={style.postTitle}>
+        <h2
+            class={style.postTitle}
+            transition:name={priority ? getPostTitleTransitionName(post.data.abbrlink) : undefined}
+        >
             <a href={`/posts/${post.data.abbrlink}/`} class="a-none" data-astro-prefetch="viewport">
                 {post.data.title}
             </a>

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

@@ -1,5 +1,4 @@
 ---
-import { fade } from "astro:transitions";
 import "photoswipe/dist/photoswipe.css";
 import style from "@styles/components/posts/postContent.module.css";
 import "@styles/components/markdown.css";
@@ -11,6 +10,7 @@ import { toMachineDateTime } from "@utils/semantic-time";
 interface Props {
     title: string;
     transitionName?: string;
+    titleTransitionName?: string;
     date?: string;
     updated?: string;
     readingMinutes?: number;
@@ -35,12 +35,11 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/, "")}.md` : "
 <article
     class={style.articleContent}
     data-stalux-gallery={props.hasImage ? "true" : undefined}
-    transition:name={props.transitionName ?? "post-content"}
-    transition:animate={fade({ duration: "0.45s" })}
+    transition:name={props.transitionName}
 >
     <!-- Article Header -->
     <header class={style.articleHeader}>
-        <h1 class={style.title}>{props.title}</h1>
+        <h1 class={style.title} transition:name={props.titleTransitionName}>{props.title}</h1>
         <div class={style.metadata}>
             {props.date && (
     <time

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

@@ -1,6 +1,5 @@
 ---
 import { getCollection } from "astro:content";
-import { fade } from "astro:transitions";
 import style from "@styles/components/posts/postToc.module.css";
 import { getSiteData } from "@utils/config-utils";
 import { createTranslator } from "@utils/i18n";
@@ -36,11 +35,7 @@ const tocItems = headings
 >
     <h3 class={style.title}>{title}</h3>
     {tocItems.length > 0 ? (
-    <ul
-        class={style.list}
-        transition:name="toc-content"
-        transition:animate={fade({ duration: "0.3s" })}
-    >
+    <ul class={style.list} transition:name="toc-content">
         {tocItems.map((heading) => (
             <li>
                 <a

package/src/index.ts

@@ -36,6 +36,7 @@ import {
     resolveFontInputs,
     writePageFontSubset,
 } from "./internal/font-slices";
+import { addLocalImageDimensions } from "./internal/image-dimensions";
 import { createInjectedRoutes } from "./internal/injected-routes";
 import { createRuntimeCacheKey } from "./internal/runtime-cache-key";
 import {
@@ -376,7 +377,11 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                         /<style data-stalux-page-font>[\s\S]*?<\/style>/gi,
                         "",
                     );
-                    let after = applyHtmlImageLoadingPolicy(withoutPageFont);
+                    const withImageDimensions = await addLocalImageDimensions(
+                        withoutPageFont,
+                        outDir,
+                    );
+                    let after = applyHtmlImageLoadingPolicy(withImageDimensions);
                     if (pageFontData) {
                         const linkedStylesheetText = readLinkedStylesheetText(
                             after,

package/src/internal/image-dimensions.ts

@@ -0,0 +1,122 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export type ImageDimensions = { width: number; height: number };
+
+/** Read intrinsic dimensions for common public image formats without loading an image library. */
+export function readImageDimensions(data: Buffer): ImageDimensions | undefined {
+    if (data.length >= 24 && data.toString("hex", 0, 8) === "89504e470d0a1a0a") {
+        return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+    }
+
+    if (
+        data.length >= 10 &&
+        (data.toString("ascii", 0, 6) === "GIF87a" || data.toString("ascii", 0, 6) === "GIF89a")
+    ) {
+        return { width: data.readUInt16LE(6), height: data.readUInt16LE(8) };
+    }
+
+    if (
+        data.length >= 30 &&
+        data.toString("ascii", 0, 4) === "RIFF" &&
+        data.toString("ascii", 8, 12) === "WEBP"
+    ) {
+        const chunk = data.toString("ascii", 12, 16);
+        if (chunk === "VP8X") {
+            return {
+                width: 1 + data.readUIntLE(24, 3),
+                height: 1 + data.readUIntLE(27, 3),
+            };
+        }
+        if (chunk === "VP8 " && data[23] === 0x9d && data[24] === 0x01 && data[25] === 0x2a) {
+            return {
+                width: data.readUInt16LE(26) & 0x3fff,
+                height: data.readUInt16LE(28) & 0x3fff,
+            };
+        }
+        if (chunk === "VP8L" && data[20] === 0x2f) {
+            const b1 = data[21] ?? 0;
+            const b2 = data[22] ?? 0;
+            const b3 = data[23] ?? 0;
+            const b4 = data[24] ?? 0;
+            return {
+                width: 1 + b1 + ((b2 & 0x3f) << 8),
+                height: 1 + (b2 >> 6) + (b3 << 2) + ((b4 & 0x0f) << 10),
+            };
+        }
+    }
+
+    if (data.length >= 4 && data[0] === 0xff && data[1] === 0xd8) {
+        let offset = 2;
+        while (offset + 4 <= data.length) {
+            if (data[offset] !== 0xff) break;
+            const marker = data[offset + 1] ?? 0;
+            const size = data.readUInt16BE(offset + 2);
+            if (size < 7 || offset + 2 + size > data.length) break;
+            if (
+                [
+                    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+                ].includes(marker)
+            ) {
+                return {
+                    width: data.readUInt16BE(offset + 7),
+                    height: data.readUInt16BE(offset + 5),
+                };
+            }
+            offset += size + 2;
+        }
+    }
+
+    return undefined;
+}
+
+/** Add width/height to same-origin emitted images so their space is reserved before download. */
+export async function addLocalImageDimensions(html: string, outputDir: string): Promise<string> {
+    const dimensionsCache = new Map<string, Promise<ImageDimensions | undefined>>();
+    const root = path.resolve(outputDir);
+    const tags = [...html.matchAll(/<img\b[^>]*>/gi)];
+
+    for (const match of tags) {
+        const tag = match[0];
+        if (!tag || (/\swidth=/i.test(tag) && /\sheight=/i.test(tag))) continue;
+        const src = tag.match(/\ssrc="([^"]+)"/i)?.[1];
+        if (!src) continue;
+
+        let filePath: string;
+        try {
+            const url = new URL(src, "https://stalux.invalid");
+            if (url.origin !== "https://stalux.invalid") continue;
+            filePath = path.resolve(root, `.${decodeURIComponent(url.pathname)}`);
+        } catch {
+            continue;
+        }
+        if (filePath !== root && !filePath.startsWith(`${root}${path.sep}`)) continue;
+
+        let dimensions = dimensionsCache.get(filePath);
+        if (!dimensions) {
+            dimensions = readFile(filePath)
+                .then(readImageDimensions)
+                .catch(() => undefined);
+            dimensionsCache.set(filePath, dimensions);
+        }
+        const size = await dimensions;
+        if (!size || size.width <= 0 || size.height <= 0) continue;
+
+        const hasWidth = /\swidth=/i.test(tag);
+        const hasHeight = /\sheight=/i.test(tag);
+        const updated =
+            hasWidth && !hasHeight
+                ? tag.replace(/\s*\/?\s*>$/, (ending) => ` height="${size.height}"${ending}`)
+                : hasHeight && !hasWidth
+                  ? tag.replace(
+                        /\sheight="[^"]*"/i,
+                        ` width="${size.width}" height="${size.height}"`,
+                    )
+                  : tag.replace(
+                        /\s*\/?\s*>$/,
+                        (ending) => ` width="${size.width}" height="${size.height}"${ending}`,
+                    );
+        html = html.replace(tag, updated);
+    }
+    return html;
+}

package/src/layouts/PostLayout.astro

@@ -7,12 +7,14 @@ import PostNavigation from "@components/stalux/posts/postNavigation.astro";
 import PostRight from "@components/stalux/posts/postRight.astro";
 import WalineComment from "@components/stalux/posts/WalineComment.astro";
 import { getCommentData } from "@utils/config-utils";
+import { getPostTitleTransitionName } from "@utils/view-transitions";
 import { buildWalineProps } from "@utils/waline";
 import "@styles/base/math.css";
 import layoutStyle from "@styles/components/posts/postLayout.module.css";
 
 interface Props {
     title: string;
+    postId?: string | number;
     date?: string;
     updated?: string;
     readingMinutes?: number;
@@ -57,6 +59,7 @@ const walineConfig = walineSection?.serverURL
         <!-- Main Content -->
         <PostContent
             title={props.title}
+            titleTransitionName={props.postId === undefined ? undefined : getPostTitleTransitionName(props.postId)}
             date={props.date}
             updated={props.updated}
             readingMinutes={props.readingMinutes}

package/src/layouts/Stalux.astro

@@ -8,6 +8,7 @@ import "@pagefind/component-ui/css";
 import "@styles/base/init.css";
 import "@styles/shared/stagger.css";
 import "@styles/shared/view-transitions.css";
+import { getAccentColorStyle } from "@utils/accent-color";
 import {
     getAiDiscoveryData,
     getAuthorData,
@@ -56,7 +57,7 @@ const routeAnimation = getRouteAnimation(routeKind);
 ---
 
 <!doctype html>
-<html lang={htmlLang}>
+<html lang={htmlLang} style={getAccentColorStyle(siteConfig.accentColor)}>
     <Head
         title={props.title}
         description={props.description}
@@ -84,6 +85,8 @@ const routeAnimation = getRouteAnimation(routeKind);
         data-stalux-site-lang={siteConfig.lang}
         data-stalux-ga-id={headConfig?.googleAnalyticsId}
         data-stalux-clarity-id={headConfig?.bingClarityId}
+        data-stalux-umami-id={headConfig?.umami?.id}
+        data-stalux-umami-url={headConfig?.umami?.url}
     >
         {llmPromote && (
     <section class="stalux-ai-prompt" data-stalux-ai-prompt aria-label="AI site context">

package/src/pages/posts/[post].astro

@@ -69,6 +69,7 @@ export async function getStaticPaths() {
     <div style="height:3em"></div>
     <PostLayout
         title={props.post.data.title}
+        postId={props.post.data.abbrlink}
         date={props.post.data.date}
         updated={props.post.data.updated}
         readingMinutes={flags.readingMinutes}

package/src/schemas/config.ts

@@ -16,6 +16,11 @@ export const siteSchema = z.object({
     title: z.string().min(1, "site.title is required"),
     url: z.url("site.url must be a valid URL"),
     description: z.string().min(1, "site.description is required"),
+    accentColor: z
+        .string()
+        .regex(/^#[\da-fA-F]{6}$/, "site.accentColor must be a six-digit HEX color such as #EAB308")
+        .optional()
+        .default("#EAB308"),
     seoTitle: z.string().min(1).optional(),
     timezone: z.string().optional().default("Asia/Shanghai"),
     canonical: z.url("site.canonical must be a valid URL").optional(),

package/src/scripts/after-load.ts

@@ -0,0 +1,27 @@
+type IdleWindow = Window & {
+    requestIdleCallback?: (callback: () => void, options?: { timeout: number }) => number;
+};
+
+/** Run non-essential work after the initial page load and during an idle period. */
+export function afterLoadAndIdle(callback: () => void): void {
+    let scheduled = false;
+    const schedule = () => {
+        if (scheduled) return;
+        scheduled = true;
+        const idleWindow = window as IdleWindow;
+        if (idleWindow.requestIdleCallback) {
+            idleWindow.requestIdleCallback(callback, { timeout: 2_000 });
+        } else {
+            window.setTimeout(callback, 0);
+        }
+    };
+
+    if (document.readyState === "complete") {
+        schedule();
+        return;
+    }
+
+    window.addEventListener("load", schedule, { once: true });
+    // Still load analytics if a third-party resource prevents the load event.
+    window.setTimeout(schedule, 5_000);
+}

package/src/scripts/clarity.ts

@@ -1,3 +1,4 @@
+import { afterLoadAndIdle } from "./after-load";
 import { createClientLogger } from "./logger";
 
 const logger = createClientLogger("clarity");
@@ -14,22 +15,28 @@ function load() {
     const id = document.body?.dataset.staluxClarityId;
     if (!id || window.__staluxClarityLoaded || document.getElementById("stalux-clarity-script"))
         return;
-    window.__staluxClarityLoaded = true;
-    window.clarity =
-        window.clarity ||
-        Object.assign((...args: unknown[]) => window.clarity?.q?.push(args), { q: [] });
-    const script = document.createElement("script");
-    script.id = "stalux-clarity-script";
-    script.async = true;
-    script.src = `https://www.clarity.ms/tag/${encodeURIComponent(id)}`;
-    script.addEventListener("load", () => logger.debug("external script loaded"), { once: true });
-    script.addEventListener(
-        "error",
-        () => logger.warn("external script failed to load (network or content blocker)"),
-        { once: true },
-    );
-    logger.debug("loading external script");
-    document.head.appendChild(script);
+    afterLoadAndIdle(() => {
+        if (window.__staluxClarityLoaded || document.getElementById("stalux-clarity-script"))
+            return;
+        window.__staluxClarityLoaded = true;
+        window.clarity =
+            window.clarity ||
+            Object.assign((...args: unknown[]) => window.clarity?.q?.push(args), { q: [] });
+        const script = document.createElement("script");
+        script.id = "stalux-clarity-script";
+        script.async = true;
+        script.src = `https://www.clarity.ms/tag/${encodeURIComponent(id)}`;
+        script.addEventListener("load", () => logger.debug("external script loaded"), {
+            once: true,
+        });
+        script.addEventListener(
+            "error",
+            () => logger.warn("external script failed to load (network or content blocker)"),
+            { once: true },
+        );
+        logger.debug("loading external script after page load and idle time");
+        document.head.appendChild(script);
+    });
 }
 
 if (!window.__staluxClarityPageLoadListener) {

package/src/scripts/umami.ts

@@ -0,0 +1,28 @@
+import { afterLoadAndIdle } from "./after-load";
+import { createClientLogger } from "./logger";
+
+const logger = createClientLogger("umami");
+
+const id = document.body?.dataset.staluxUmamiId;
+const url = document.body?.dataset.staluxUmamiUrl;
+
+if (id && url) {
+    afterLoadAndIdle(() => {
+        if (document.querySelector("script[data-stalux-umami]")) return;
+        const script = document.createElement("script");
+        script.async = true;
+        script.dataset.staluxUmami = "true";
+        script.dataset.websiteId = id;
+        script.src = url;
+        script.addEventListener("load", () => logger.debug("external script loaded"), {
+            once: true,
+        });
+        script.addEventListener(
+            "error",
+            () => logger.warn("external script failed to load (network or content blocker)"),
+            { once: true },
+        );
+        logger.debug("loading external script after page load and idle time");
+        document.head.appendChild(script);
+    });
+}

package/src/scripts/vercount.ts

@@ -1,3 +1,4 @@
+import { afterLoadAndIdle } from "./after-load";
 import { createClientLogger } from "./logger";
 
 const logger = createClientLogger("vercount");
@@ -10,19 +11,25 @@ declare global {
 
 function load() {
     if (document.querySelector("script[data-stalux-vercount]")) return;
-    window.__staluxVerCountLoaded = true;
-    const script = document.createElement("script");
-    script.defer = true;
-    script.dataset.staluxVercount = "true";
-    script.src = "https://events.vercount.one/js";
-    script.addEventListener("load", () => logger.debug("external script loaded"), { once: true });
-    script.addEventListener(
-        "error",
-        () => logger.warn("external script failed to load (network or content blocker)"),
-        { once: true },
-    );
-    logger.debug("loading external script");
-    document.head.appendChild(script);
+    afterLoadAndIdle(() => {
+        if (window.__staluxVerCountLoaded || document.querySelector("script[data-stalux-vercount]"))
+            return;
+        window.__staluxVerCountLoaded = true;
+        const script = document.createElement("script");
+        script.async = true;
+        script.dataset.staluxVercount = "true";
+        script.src = "https://events.vercount.one/js";
+        script.addEventListener("load", () => logger.debug("external script loaded"), {
+            once: true,
+        });
+        script.addEventListener(
+            "error",
+            () => logger.warn("external script failed to load (network or content blocker)"),
+            { once: true },
+        );
+        logger.debug("loading external script after page load and idle time");
+        document.head.appendChild(script);
+    });
 }
 
 document.addEventListener("astro:page-load", load);

package/src/scripts/waline-client.ts

@@ -0,0 +1,23 @@
+import { init, type WalineInitOptions } from "@waline/client";
+import walineCss from "@waline/client/style?inline";
+import staluxWalineCss from "../styles/components/posts/waline.css?inline";
+
+export function mountWaline(config: Record<string, unknown>, element: HTMLElement): () => void {
+    const style = document.createElement("style");
+    style.dataset.staluxWaline = "true";
+    style.textContent = `${walineCss}\n${staluxWalineCss}`;
+    document.head.append(style);
+
+    const options = {
+        ...config,
+        el: element,
+        serverURL: config.serverURL,
+        path: typeof config.path === "string" ? config.path : window.location.pathname,
+    } as WalineInitOptions;
+    const instance = init(options);
+
+    return () => {
+        instance?.destroy();
+        style.remove();
+    };
+}