@xingwangzhe/stalux 1.41.4 → 1.42.0

package/README.md

@@ -356,3 +356,17 @@ Theme code is **MIT**; the root [LICENSE](LICENSE) contains the standard text fo
 | Font copyrights, reserved names and modification notices | Each font’s original license | [LICENSE-FONT-NOTICES.txt](LICENSES/LICENSE-FONT-NOTICES.txt) |
 
 The npm package includes `LICENSES/` and font-specific texts in `public/fonts/`; builds synchronize font notices to the consumer’s public font directory alongside the served WOFF2 files. Native subsetting dependencies retain their [separate license inventory](https://github.com/xingwangzhe/cjk-font-split-native/blob/main/README.en.md#licenses-and-scope) and packaged `THIRD_PARTY_LICENSES.txt`. GitHub’s primary-license display identifies theme code; fonts and other third-party components retain the scopes listed above.
+
+
+### Article social sharing cards
+
+Image priority is **explicit `og:image` → a card with a valid `cover` → an automatic title card**. The article list continues to use `cover`. An explicit `og:image` is used as-is and accepts HTTP(S), protocol-relative URLs, or site-root paths; PNG/JPEG at 1200×630 is recommended. Omit it or leave it empty to generate a card automatically. Existing posts need no changes.
+
+```yaml title="Article sharing images"
+cover: /images/article-cover.webp
+og:image: /images/custom-social-card.png
+```
+
+`@takumi-rs/core` renders a static 1200×630 WebP at `/og/<metadata-hash>.webp` using the bundled LXGW WenKai font. Cards include the title, summary, site identity, author, category, accent color and date in the site timezone. No renderer JavaScript is sent to the browser. Static `og:image`, `twitter:image` and BlogPosting `image` use the same absolute URL; generated images also declare dimensions and MIME type. Articles use `summary_large_image`. A second `og:image` points to a PNG fallback; platforms choose which format they can read. WebP quality is 86; AVIF is not the default.
+
+Local covers are read from the final `publicDir`. Remote covers are requested by the build machine, with an 8-second timeout and an 8 MiB limit (remote bytes are cached for 24 hours); unreadable or undecodable artwork emits a warning and falls back to a title card. No remote image-generation service is used. WebP and PNG outputs are cached in `stalux-social-cards/` under Astro's cache directory and copied into each build output. Explicit sharing images are fetched by social platforms, so they must be publicly accessible images. Platforms maintain their own preview caches and may not refresh an existing share immediately after deployment.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.41.4",
+    "version": "1.42.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -50,7 +50,7 @@
         "LICENSES"
     ],
     "type": "module",
-    "packageManager": "bun@1.4.0",
+    "packageManager": "bun@1.4.4",
     "exports": {
         ".": "./src/index.ts",
         "./config": "./src/config.ts",
@@ -97,7 +97,8 @@
         "styles:build": "node scripts/build-styles.ts && node scripts/build-style-names.ts",
         "styles:watch": "node scripts/build-styles.ts --watch",
         "benchmark:performance": "node scripts/benchmark-performance.ts",
-        "benchmark:builds": "python3 scripts/benchmark-builds.py"
+        "benchmark:builds": "python3 scripts/benchmark-builds.py",
+        "analyze": "SONDA=1 bun run build"
     },
     "dependencies": {
         "@astrojs/compiler": "^4.0.0",
@@ -109,6 +110,7 @@
         "@mcp-b/webmcp-polyfill": "^5.1.0",
         "@microsoft/clarity": "1.0.2",
         "@pagefind/component-ui": "^1.5.2",
+        "@takumi-rs/core": "2.17.1",
         "@waline/client": "^3.16.1",
         "@xingwangzhe/cjk-font-split-native": "^0.4.10",
         "@xingwangzhe/satteri-mermaid": "^0.8.2",
@@ -137,6 +139,7 @@
         "@vitest/coverage-v8": "^5.0.4",
         "astro": "^7.4.2",
         "knip": "^6.41.0",
+        "sonda": "^0.14.0",
         "typescript": "npm:@typescript/typescript6@6.0.2",
         "unocss": "^66.11.0",
         "vite": "^8.3.4",

package/src/components/stalux/layout/head.astro

@@ -68,6 +68,15 @@ const ldJson = JSON.stringify(seo.schema).replace(/<\//g, "<\\/");
             meta: seo.meta,
         }}
     />
+    {seo.fallbackImage && (
+        <>
+            <meta property="og:image" content={seo.fallbackImage} />
+            <meta property="og:image:type" content="image/png" />
+            <meta property="og:image:width" content="1200" />
+            <meta property="og:image:height" content="630" />
+            <meta property="og:image:alt" content={seo.openGraph.basic.title} />
+        </>
+    )}
     <!-- 代码字体由 Astro Fonts API 注入；正文按页面生成 native CJK 子集。 -->
     <Font cssVariable="--font-code" />
     <link rel="prefetch" as="style" href={pagefindStyles} data-stalux-search-style>

package/src/env.d.ts

@@ -7,3 +7,8 @@ declare module "virtual:stalux-search-style" {
     const href: string;
     export default href;
 }
+
+declare module "virtual:stalux-social-card-paths" {
+    const paths: import("./internal/social-card-renderer").SocialCardPaths;
+    export default paths;
+}

package/src/index.ts

@@ -120,6 +120,8 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
         ...options,
     };
 
+    const socialCardPaths = { publicDir: "", cacheDir: "", base: "/", fontPath: "" };
+
     let pageFontData: { fontBuffer: Buffer; outputDir: string; cacheDir: string } | undefined;
 
     const coreIntegration: AstroIntegration = {
@@ -166,12 +168,24 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                         build: {
                             target: config.vite.build?.target ?? "esnext",
                             cssMinify: "lightningcss",
-                            sourcemap: false,
+                            // 默认不产出 sourcemap；消费方显式开启时（如 SONDA=1 做体积分析）尊重其设置
+                            sourcemap: config.vite.build?.sourcemap ?? false,
                         },
                         resolve: {
                             alias: createViteAliases(srcDir),
                         },
                         plugins: [
+                            {
+                                name: "stalux:social-card-paths",
+                                resolveId: (id) =>
+                                    id === "virtual:stalux-social-card-paths"
+                                        ? `\0${id}`
+                                        : undefined,
+                                load: (id) =>
+                                    id === "\0virtual:stalux-social-card-paths"
+                                        ? `export default ${JSON.stringify(socialCardPaths)}`
+                                        : undefined,
+                            },
                             searchStylePlugin(command === "dev", config.base),
                             webMcpMutationsPlugin(),
                             ...(command === "build"
@@ -339,6 +353,12 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
             "astro:config:done": ({ config, logger }) => {
                 const srcDir = fileURLToPath(new URL(".", import.meta.url));
                 const publicDir = fileURLToPath(config.publicDir);
+                Object.assign(socialCardPaths, {
+                    publicDir,
+                    cacheDir: fileURLToPath(new URL("stalux-social-cards/", config.cacheDir)),
+                    base: config.base,
+                    fontPath: path.join(srcDir, "assets/fonts/LXGWWenKai-Regular.ttf"),
+                });
                 const assetsLogger = logger.fork("stalux/assets");
                 if (pageFontData) {
                     pageFontData.outputDir = path.join(

package/src/internal/social-card-data.ts

@@ -0,0 +1,34 @@
+import type { AuthorData, SiteData } from "../schemas/config";
+import { formatInTimeZone, parseDate } from "../utils/dayjs";
+import type { SocialCardData } from "../utils/social-image";
+
+interface PostData {
+    title: string;
+    desc: string;
+    date: string;
+    cover?: string;
+    categories?: string[];
+}
+
+export function createSocialCardData(
+    post: PostData,
+    site: SiteData,
+    author: AuthorData,
+): SocialCardData {
+    return {
+        title: post.title,
+        description: post.desc,
+        siteTitle: site.title,
+        author: author.name,
+        host: new URL(site.canonical ?? site.url).host,
+        lang: site.lang || "zh-CN",
+        accent: site.accentColor || "#EAB308",
+        date: formatInTimeZone(
+            parseDate(post.date, site.timezone || "Asia/Shanghai"),
+            site.timezone || "Asia/Shanghai",
+            "yyyy-MM-dd",
+        ),
+        category: post.categories?.[0] ?? "",
+        ...(post.cover?.trim() ? { cover: post.cover.trim() } : {}),
+    };
+}

package/src/internal/social-card-renderer.ts

@@ -0,0 +1,307 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { type Node, Renderer } from "@takumi-rs/core";
+import { imageSize } from "image-size";
+import type { SocialCardData } from "../utils/social-image";
+
+export interface SocialCardPaths {
+    publicDir: string;
+    cacheDir: string;
+    base: string;
+    fontPath: string;
+}
+
+const MAX_COVER_BYTES = 8 * 1024 * 1024;
+let rendererPromise: Promise<Renderer> | undefined;
+function getRenderer(fontPath: string): Promise<Renderer> {
+    rendererPromise ??= (async () => {
+        const renderer = new Renderer({ cacheMaxBytes: 32 * 1024 * 1024 });
+        await renderer.registerFont({ name: "Stalux Card", data: await readFile(fontPath) });
+        return renderer;
+    })();
+    return rendererPromise;
+}
+
+/** Resolve only assets inside the final public directory, including encoded Chinese paths. */
+export function localCoverPath(cover: string, paths: SocialCardPaths): string | undefined {
+    if (!cover.startsWith("/") || cover.startsWith("//")) return undefined;
+    try {
+        let pathname = decodeURIComponent(cover.split(/[?#]/u)[0] ?? "");
+        const base = paths.base.replace(/\/$/u, "");
+        if (base && pathname.startsWith(`${base}/`)) pathname = pathname.slice(base.length);
+        const target = path.resolve(paths.publicDir, `.${pathname}`);
+        if (!target.startsWith(`${path.resolve(paths.publicDir)}${path.sep}`)) return undefined;
+        return target;
+    } catch {
+        return undefined;
+    }
+}
+
+const coverRequests = new Map<string, Promise<Buffer>>();
+
+async function loadCover(cover: string, paths: SocialCardPaths): Promise<Buffer> {
+    const key = `${paths.publicDir}|${cover}`;
+    let pending = coverRequests.get(key);
+    if (!pending) {
+        pending = loadCoverUncached(cover, paths);
+        coverRequests.set(key, pending);
+        // Bound memory while sharing requests and failures between WebP and PNG renders.
+        if (coverRequests.size > 8) coverRequests.delete(coverRequests.keys().next().value ?? "");
+    }
+    return pending;
+}
+
+async function loadCoverUncached(cover: string, paths: SocialCardPaths): Promise<Buffer> {
+    const local = localCoverPath(cover, paths);
+    let bytes: Buffer;
+    if (local) {
+        if ((await stat(local)).size > MAX_COVER_BYTES) throw new Error("cover exceeds 8 MiB");
+        bytes = await readFile(local);
+    } else {
+        const url = new URL(cover.startsWith("//") ? `https:${cover}` : cover);
+        if (!["https:", "http:"].includes(url.protocol)) throw new Error("invalid cover URL");
+        const remoteCache = path.join(
+            paths.cacheDir,
+            "covers",
+            createHash("sha256").update(url.href).digest("hex"),
+        );
+        const cachedStat = await stat(remoteCache).catch(() => undefined);
+        if (cachedStat && Date.now() - cachedStat.mtimeMs < 86_400_000)
+            return readFile(remoteCache);
+        const response = await fetch(url, { signal: AbortSignal.timeout(8000) });
+        if (!response.ok || !response.headers.get("content-type")?.startsWith("image/"))
+            throw new Error(`cover returned HTTP ${response.status} or non-image content`);
+        const chunks: Uint8Array[] = [];
+        let size = 0;
+        if (!response.body) throw new Error("empty cover");
+        for await (const chunk of response.body) {
+            size += chunk.length;
+            if (size > MAX_COVER_BYTES) throw new Error("cover exceeds 8 MiB");
+            chunks.push(chunk);
+        }
+        bytes = Buffer.concat(chunks);
+        const dimensions = imageSize(bytes);
+        if (
+            !dimensions.width ||
+            !dimensions.height ||
+            dimensions.width * dimensions.height > 32_000_000
+        )
+            throw new Error("invalid cover dimensions");
+        await mkdir(path.dirname(remoteCache), { recursive: true });
+        await writeFile(remoteCache, bytes);
+    }
+    const dimensions = imageSize(bytes);
+    if (
+        !dimensions.width ||
+        !dimensions.height ||
+        dimensions.width * dimensions.height > 32_000_000
+    )
+        throw new Error("invalid or oversized cover dimensions");
+    return bytes;
+}
+
+function text(value: string, style: Node["style"]): Node {
+    return { type: "text", text: value, style };
+}
+
+/** A fixed editorial layout: site identity, readable title, optional artwork, quiet footer. */
+export function socialCardTree(
+    data: SocialCardData,
+    hasCover: boolean,
+    titleSize = 60,
+    title = data.title,
+): Node {
+    const titleWidth = hasCover ? 650 : 1056;
+    const accent = /^#[\da-f]{6}$/iu.test(data.accent) ? data.accent : "#EAB308";
+    const children: Node[] = [
+        {
+            type: "container",
+            style: {
+                position: "absolute",
+                right: -120,
+                top: -200,
+                width: 650,
+                height: 650,
+                borderRadius: "50%",
+                border: `1px solid ${accent}35`,
+                background: `radial-gradient(circle, ${accent}18, transparent 70%)`,
+            },
+        },
+        {
+            type: "container",
+            style: {
+                position: "absolute",
+                left: 0,
+                top: 0,
+                width: 1200,
+                height: 6,
+                backgroundColor: accent,
+            },
+        },
+        text(data.siteTitle, {
+            position: "absolute",
+            left: 72,
+            top: 48,
+            width: 820,
+            height: 46,
+            fontSize: 28,
+            color: accent,
+            overflow: "hidden",
+        }),
+        text(data.category || "ARTICLE", {
+            position: "absolute",
+            right: 72,
+            top: 54,
+            width: 240,
+            height: 36,
+            textAlign: "right",
+            fontSize: 21,
+            color: "#a9b5c6",
+            overflow: "hidden",
+        }),
+        text(title, {
+            position: "absolute",
+            left: 72,
+            top: 142,
+            width: titleWidth,
+            height: 260,
+            fontSize: titleSize,
+            lineHeight: 1.24,
+            color: "#f5f7fb",
+            overflow: "hidden",
+            overflowWrap: "anywhere",
+        }),
+        text([...data.description.replace(/\s+/gu, " ")].slice(0, hasCover ? 65 : 100).join(""), {
+            position: "absolute",
+            left: 72,
+            top: 421,
+            width: titleWidth,
+            height: 76,
+            fontSize: 25,
+            lineHeight: 1.45,
+            color: "#a9b5c6",
+            overflow: "hidden",
+        }),
+        {
+            type: "container",
+            style: {
+                position: "absolute",
+                left: 72,
+                top: 535,
+                width: 1056,
+                height: 1,
+                backgroundColor: "#ffffff22",
+            },
+        },
+        text(data.host, { position: "absolute", left: 72, top: 560, fontSize: 23, color: accent }),
+        text(`${data.author}  /  ${data.date}`, {
+            position: "absolute",
+            right: 72,
+            top: 560,
+            width: 650,
+            textAlign: "right",
+            fontSize: 23,
+            color: "#b9c4d3",
+        }),
+    ];
+    if (hasCover)
+        children.push({
+            type: "image",
+            src: "stalux-cover",
+            style: {
+                position: "absolute",
+                right: 72,
+                top: 142,
+                width: 350,
+                height: 354,
+                objectFit: "cover",
+                borderRadius: 20,
+            },
+        });
+    return {
+        type: "container",
+        lang: data.lang,
+        style: {
+            width: 1200,
+            height: 630,
+            position: "relative",
+            backgroundColor: "#101722",
+            fontFamily: "Stalux Card",
+            overflow: "hidden",
+        },
+        children,
+    };
+}
+
+export async function renderSocialCard(
+    data: SocialCardData,
+    paths: SocialCardPaths,
+    warn: (message: string) => void,
+    format: "webp" | "png" = "webp",
+): Promise<Buffer> {
+    let cover: Buffer | undefined;
+    if (data.cover) {
+        try {
+            cover = await loadCover(data.cover, paths);
+        } catch {
+            warn(`分享封面不可用，已回退标题卡片：${data.title}`);
+        }
+    }
+    const font = await stat(paths.fontPath);
+    const key = createHash("sha256")
+        .update(JSON.stringify(["v2", format, data, font.size, font.mtimeMs]))
+        .update(cover ?? "")
+        .digest("hex");
+    const cacheFile = path.join(paths.cacheDir, `${key}.${format}`);
+    const hit = await readFile(cacheFile).catch(() => undefined);
+    if (hit) return hit;
+    const renderer = await getRenderer(paths.fontPath);
+    const layout = async (withCover: boolean) => {
+        const width = withCover ? 650 : 1056;
+        let title = [...data.title].slice(0, 150).join("");
+        let size = 66;
+        while (true) {
+            const measured = await renderer.measure(
+                {
+                    type: "text",
+                    text: title,
+                    style: {
+                        width,
+                        fontSize: size,
+                        lineHeight: 1.24,
+                        fontFamily: "Stalux Card",
+                        overflowWrap: "anywhere",
+                    },
+                },
+                { width },
+            );
+            if (measured.height <= 250) break;
+            if (size > 30) size -= 2;
+            else title = `${[...title].slice(0, -3).join("")}…`;
+        }
+        return socialCardTree(data, withCover, size, title);
+    };
+    let bytes: Buffer;
+    try {
+        bytes = await renderer.render(await layout(Boolean(cover)), {
+            width: 1200,
+            height: 630,
+            format,
+            quality: 86,
+            images: cover ? [{ src: "stalux-cover", data: cover }] : [],
+        });
+    } catch (error) {
+        if (!cover) throw error;
+        warn(`分享封面解码失败，已回退标题卡片：${data.title}`);
+        bytes = await renderer.render(await layout(false), {
+            width: 1200,
+            height: 630,
+            format,
+            quality: 86,
+        });
+    }
+    await mkdir(paths.cacheDir, { recursive: true });
+    await writeFile(cacheFile, bytes);
+    return bytes;
+}

package/src/layouts/Stalux.astro

@@ -11,6 +11,7 @@ import {
     getPromoteData,
     getSiteData,
 } from "@utils/config-utils";
+import type { SocialImage } from "@utils/social-image";
 import { getRouteKind } from "@utils/view-transitions";
 
 const props = Astro.props as Props;
@@ -19,6 +20,7 @@ interface Props {
     title: string;
     description: string;
     cover?: string;
+    socialImage?: SocialImage;
     isArticle?: boolean;
     date?: string;
     updated?: string;
@@ -60,6 +62,7 @@ const routeKind = getRouteKind(Astro.url.pathname);
         title={props.title}
         description={props.description}
         cover={props.cover}
+        socialImage={props.socialImage}
         isArticle={props.isArticle}
         date={props.date}
         updated={props.updated}

package/src/pages/og/[image].[format].ts

@@ -0,0 +1,47 @@
+import { getCollection } from "astro:content";
+import paths from "virtual:stalux-social-card-paths";
+import type { APIRoute } from "astro";
+import { createSocialCardData } from "../../internal/social-card-data";
+import { renderSocialCard } from "../../internal/social-card-renderer";
+import { getAuthorData, getSiteData } from "../../utils/config-utils";
+import { getPostContentIndex } from "../../utils/content-index";
+import { isSocialImageUrl, type SocialCardData, socialCardPath } from "../../utils/social-image";
+
+export async function getStaticPaths() {
+    const entries = await getCollection("config");
+    const site = getSiteData(entries);
+    const author = getAuthorData(entries);
+    const { posts } = await getPostContentIndex();
+    return posts
+        .filter(
+            (post) =>
+                !post.data["og:image"]?.trim() || !isSocialImageUrl(post.data["og:image"].trim()),
+        )
+        .flatMap((post) => {
+            const card = createSocialCardData(post.data, site, author);
+            return (["webp", "png"] as const).map((format) => ({
+                params: {
+                    image: socialCardPath(card)
+                        .split("/")
+                        .at(-1)
+                        ?.replace(/\.webp$/u, ""),
+                    format,
+                },
+                props: { card, format },
+                // Covers may change independently of Markdown. Always recheck them; the renderer
+                // has its own content cache and writes outputs even after Astro cleans dist.
+            }));
+        });
+}
+
+export const GET: APIRoute = async ({ props, logger }) => {
+    const bytes = await renderSocialCard(
+        props.card as SocialCardData,
+        paths,
+        (message) => logger.warn(message),
+        props.format as "webp" | "png",
+    );
+    return new Response(new Uint8Array(bytes), {
+        headers: { "Content-Type": `image/${props.format}` },
+    });
+};

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

@@ -1,11 +1,13 @@
 ---
 import { type CollectionEntry, getCollection, render } from "astro:content";
 import { getRuntimeCacheKey } from "@internal/runtime-cache-key";
+import { createSocialCardData } from "@internal/social-card-data";
 import PostLayout from "@layouts/PostLayout.astro";
 import Stalux from "@layouts/Stalux.astro";
 import { analyzeFeatureFlags } from "@plugins/feature-flags";
 import { getAuthorData, getSiteData } from "@utils/config-utils";
 import { getPostContentIndex } from "@utils/content-index";
+import { resolvePostSocialImage } from "@utils/social-image";
 
 interface Props {
     post: CollectionEntry<"posts">;
@@ -33,6 +35,7 @@ export async function getStaticPaths() {
             post.data.updated ?? post.data.date,
             prevPost ? (prevPost.data.updated ?? prevPost.data.date) : "",
             nextPost ? (nextPost.data.updated ?? nextPost.data.date) : "",
+            JSON.stringify(post.data),
             getRuntimeCacheKey(),
         ].join("|");
         return {
@@ -56,6 +59,11 @@ export async function getStaticPaths() {
     title={`${props.post.data.title} | ${siteConfig.title}`}
     description={autoDesc}
     cover={props.post.data.cover}
+    socialImage={resolvePostSocialImage(
+        props.post.data["og:image"],
+        createSocialCardData(props.post.data, siteConfig, authorConfig),
+        import.meta.env.BASE_URL,
+    )}
     isArticle={true}
     date={props.post.data.date}
     updated={props.post.data.updated}

package/src/pages/posts/[post].md.ts

@@ -39,7 +39,7 @@ export const getStaticPaths = (async () => {
     const posts = await getCollection("posts", ({ data }) => !data.draft);
     return posts.map((post) => ({
         params: { post: String(post.data.abbrlink) },
-        cacheKey: `${post.data.updated ?? post.data.date}|${getRuntimeCacheKey()}`,
+        cacheKey: `${post.data.updated ?? post.data.date}|${JSON.stringify(post.data)}|${getRuntimeCacheKey()}`,
         props: { post },
     }));
 }) satisfies GetStaticPaths;

package/src/schemas/collections.ts

@@ -19,6 +19,7 @@ import { defineCollection } from "astro:content";
 import { glob, type Loader } from "astro/loaders";
 import { z } from "astro/zod";
 
+import { isSocialImageUrl } from "../utils/social-image";
 import { configSchema } from "./config";
 
 /** Preserve glob's name, watch behavior and incremental store; only trace the load boundary. */
@@ -98,6 +99,14 @@ const postSchema = z.object({
     desc: z.string({ error: "desc must be a string" }).min(1, "desc is required"),
     cc: z.string().optional().default("CC-BY-NC-SA-4.0"),
     cover: z.string().optional(),
+    "og:image": z
+        .string()
+        .trim()
+        .refine(
+            (value) => value === "" || isSocialImageUrl(value),
+            "og:image must be an HTTP(S) URL or site-root image path",
+        )
+        .optional(),
 });
 
 // ---------------------------------------------------------------------------

package/src/scripts/analytics-runtime.ts

@@ -274,6 +274,57 @@ function trackVercountPage(): void {
     document.head.appendChild(script);
 }
 
+/** 文档是否已解析完、DOM 可查询（`loading` 之外的两种状态都算）。 */
+function documentIsParsed(): boolean {
+    const readyState = document.readyState;
+    return readyState === "interactive" || readyState === "complete";
+}
+
+let pendingEarlyView = 0;
+let earlyViewPending = false;
+let viewedEarly = false;
+
+function dispatchPageView(): void {
+    initializeTrackers();
+    trackGooglePage();
+    trackUmamiPage();
+    trackVercountPage();
+    state.previousPage = window.location.href;
+}
+
+/**
+ * 首访在文档解析完成后就上报一次，不等 window.load。
+ * `astro:page-load` 首访时由 window.load 派发，要等完所有图片、字体和第三方资源，
+ * 慢资源或卡死的请求会让页脚统计一直停在 Loading...。上报必须按页去重，
+ * 否则同一次访问会被重复计入、Vercount 也会重复追加脚本。
+ */
+function dispatchEarlyView(): void {
+    const token = ++pendingEarlyView;
+    earlyViewPending = true;
+    queueMicrotask(() => {
+        if (token !== pendingEarlyView || !earlyViewPending) return;
+        earlyViewPending = false;
+        viewedEarly = true;
+        dispatchPageView();
+    });
+}
+
+function handlePageLoad(): void {
+    if (earlyViewPending) {
+        // page-load 属于当前页，由它立即上报，作废排队中的早派发。
+        pendingEarlyView++;
+        earlyViewPending = false;
+        viewedEarly = true;
+        dispatchPageView();
+        return;
+    }
+    if (viewedEarly) {
+        viewedEarly = false;
+        return;
+    }
+    dispatchPageView();
+}
+
 if (state.installed && (!state.native || state.revision !== 4)) {
     // Revision 4 replaces synchronous Google page views and the motion policy.
     // An open tab can cross a deployment boundary. Its old anonymous worker
@@ -284,6 +335,9 @@ if (state.installed && (!state.native || state.revision !== 4)) {
     state.revision = 4;
     state.installed = true;
     document.addEventListener("astro:before-swap", (event) => {
+        pendingEarlyView++;
+        earlyViewPending = false;
+        viewedEarly = false;
         transitionReady = prepareRouteMotion(event as Event & RouteMotionEvent).ready;
         // Invalidate an older page's frames, timer and posted task before this
         // incoming snapshot starts. Its captured visit remains in the FIFO.
@@ -294,11 +348,7 @@ if (state.installed && (!state.native || state.revision !== 4)) {
     document.addEventListener("visibilitychange", () => {
         if (document.hidden) flushGooglePages();
     });
-    document.addEventListener("astro:page-load", () => {
-        initializeTrackers();
-        trackGooglePage();
-        trackUmamiPage();
-        trackVercountPage();
-        state.previousPage = window.location.href;
-    });
+    document.addEventListener("astro:page-load", handlePageLoad);
+    if (documentIsParsed()) dispatchEarlyView();
+    else document.addEventListener("DOMContentLoaded", dispatchEarlyView, { once: true });
 }

package/src/scripts/background.ts

@@ -92,9 +92,15 @@ function prepareBackground(): Promise<number | 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;
@@ -119,4 +125,9 @@ if (!(window as Window & { __STALUX_BG_LISTENER__?: boolean }).__STALUX_BG_LISTE
         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 });
 }

package/src/scripts/page-runtime.ts

@@ -31,10 +31,21 @@ function getBrowserEnvironment(): PageRuntimeEnvironment | undefined {
     };
 }
 
+/** 文档是否已解析完、DOM 可查询（`loading` 之外的两种状态都算）。 */
+function isDocumentParsed(readyState: string | undefined): boolean {
+    return readyState === "interactive" || readyState === "complete";
+}
+
 /**
  * Mount one page-scoped behavior for the current DOM and dispose it before Astro swaps the body.
  * The key is global for the browser session, so a bundled module can be encountered repeatedly
  * without accumulating document-level listeners.
+ *
+ * 首访不能只等 `astro:page-load`：Astro 在首次加载时从 `window.load` 派发该事件，而
+ * `window.load` 要等完所有图片、字体与第三方 iframe。首访一旦有子资源变慢或卡死
+ * （国内访问外部资源时的常态），事件就迟迟不来甚至永不到达，评论与统计整页空白，
+ * 此时 `document.readyState` 停在 `interactive`，只判 `complete` 的兜底也救不回来。
+ * 因此文档解析完成即接管本页；`astro:page-load` 只负责软导航后的新页面与重复信号。
  */
 export function registerPageLifecycle(
     key: string,
@@ -55,7 +66,13 @@ export function registerPageLifecycle(
     logger.debug("lifecycle registered");
 
     let active = true;
-    let pageGeneration = 0;
+    // 已安排但尚未执行的早挂载。自增即作废：早挂载一旦被 page-load 或换页接管，
+    // 排队中的任务不能再挂到已被替换的 DOM 上。
+    let pendingEarlyMount = 0;
+    let earlyMountPending = false;
+    // 早挂载已经覆盖当前页。此时 window.load 上的 page-load 只是同一页的重复信号，
+    // 再挂一次会造出第二份观察器或第二个评论实例。
+    let mountedEarly = false;
     const registration: RuntimeRegistration = {
         unregister: () => undefined,
     };
@@ -73,7 +90,6 @@ export function registerPageLifecycle(
     };
     const mountPage = () => {
         if (!active) return;
-        pageGeneration++;
         disposePage();
         const started = performance.now();
         logger.debug("mount started");
@@ -87,11 +103,41 @@ export function registerPageLifecycle(
             throw error;
         }
     };
-    const handlePageLoad = () => mountPage();
+    const handlePageLoad = () => {
+        if (earlyMountPending) {
+            // page-load 属于当前页，由它立即挂载，作废排队中的早挂载。
+            pendingEarlyMount++;
+            earlyMountPending = false;
+            mountedEarly = true;
+            mountPage();
+            return;
+        }
+        if (mountedEarly) {
+            mountedEarly = false;
+            logger.debug("page-load after early mount; keeping the live instance");
+            return;
+        }
+        mountPage();
+    };
     const handleBeforeSwap = () => {
-        pageGeneration++;
+        pendingEarlyMount++;
+        earlyMountPending = false;
+        mountedEarly = false;
         disposePage();
     };
+    const mountEarlyPage = () => {
+        const token = ++pendingEarlyMount;
+        earlyMountPending = true;
+        // 微任务：模块脚本执行时 DOM 已完整，但要等模块自身求值结束再调用 mount()
+        // （模块顶层的后置绑定可能仍在 TDZ）。
+        queueTask(() => {
+            if (!active || token !== pendingEarlyMount || !earlyMountPending) return;
+            earlyMountPending = false;
+            mountedEarly = true;
+            mountPage();
+        });
+    };
+    const handleDomReady = () => mountEarlyPage();
 
     target.addEventListener("astro:page-load", handlePageLoad);
     target.addEventListener("astro:before-swap", handleBeforeSwap);
@@ -104,19 +150,14 @@ export function registerPageLifecycle(
         } finally {
             target.removeEventListener("astro:page-load", handlePageLoad);
             target.removeEventListener("astro:before-swap", handleBeforeSwap);
+            target.removeEventListener("DOMContentLoaded", handleDomReady);
             registry.delete(key);
         }
     };
     registry.set(key, registration);
 
-    // Late-loaded modules can miss Astro's initial page-load event.
-    if (target.readyState === "complete") {
-        const scheduledGeneration = pageGeneration;
-        queueTask(() => {
-            // A real page-load or swap supersedes this late-module fallback.
-            if (pageGeneration === scheduledGeneration) mountPage();
-        });
-    }
+    if (isDocumentParsed(target.readyState)) mountEarlyPage();
+    else target.addEventListener("DOMContentLoaded", handleDomReady, { once: true });
 
     return registration.unregister;
 }

package/src/utils/post-markdown.ts

@@ -11,6 +11,7 @@ interface MarkdownPostData {
     draft?: boolean;
     cc?: string;
     cover?: string;
+    "og:image"?: string;
 }
 
 /** Serialize the collection's parsed metadata as YAML AST; preserve the original Markdown body. */
@@ -26,6 +27,7 @@ export function reconstructMarkdown(data: MarkdownPostData, body = ""): string {
         ...(data.draft ? { draft: true } : {}),
         ...(data.cc && data.cc !== "CC-BY-NC-SA-4.0" ? { cc: data.cc } : {}),
         ...(data.cover ? { cover: data.cover } : {}),
+        ...(data["og:image"] ? { "og:image": data["og:image"] } : {}),
     });
     return `---\n${frontmatter.toString({ lineWidth: 0 })}---\n${body}${body.endsWith("\n") ? "" : "\n"}`;
 }

package/src/utils/route-catalog.ts

@@ -16,6 +16,7 @@ export const ROUTE_DEFINITIONS: readonly RouteDefinition[] = [
     { pattern: "/tags/[tag]", source: "./pages/tags/[tag].astro" },
     { pattern: "/categories/", source: "./pages/categories/index.astro" },
     { pattern: "/categories/[category]", source: "./pages/categories/[category].astro" },
+    { pattern: "/og/[image].[format]", source: "./pages/og/[image].[format].ts" },
     { pattern: "/rss.xml", source: "./pages/rss.xml.ts" },
     { pattern: "/atom.xml", source: "./pages/atom.xml.ts" },
     { pattern: "/llms.txt", source: "./pages/llms.txt.ts" },

package/src/utils/seo-document.ts

@@ -1,8 +1,8 @@
 import type { AuthorData, SiteData } from "@schemas/config";
 import type { SEOProps } from "astro-seo";
-
 import { langToOpenGraphLocale } from "./i18n";
 import { getMarkdownPath, getRouteKind, normalizePublicPath } from "./public-routes";
+import type { SocialImage } from "./social-image";
 
 export type TwitterCardType = "summary" | "summary_large_image";
 
@@ -10,6 +10,7 @@ export interface SeoPageInput {
     title: string;
     description: string;
     cover?: string;
+    socialImage?: SocialImage;
     isArticle?: boolean;
     date?: string;
     updated?: string;
@@ -41,6 +42,7 @@ export interface SeoDocument {
     links: NonNullable<NonNullable<SEOProps["extend"]>["link"]>;
     meta: NonNullable<NonNullable<SEOProps["extend"]>["meta"]>;
     schema: Record<string, unknown>;
+    fallbackImage?: string;
 }
 
 function normalizeSiteUrl(value: string): string {
@@ -70,7 +72,11 @@ export function buildSeoDocument(input: SeoDocumentInput): SeoDocument {
     const noindex = Boolean(site.noindex) || notFound || Boolean(page.noindex);
     const nofollow = Boolean(site.nofollow) || notFound;
     const favicon = site.favicon;
-    const image = absoluteUrl(page.cover ?? author.avatar, siteUrl, input.protocol);
+    const image = absoluteUrl(
+        page.socialImage?.url ?? page.cover ?? author.avatar,
+        siteUrl,
+        input.protocol,
+    );
     const isArticle = page.isArticle ?? false;
     const isCollection = routeKind.endsWith("-index") || routeKind.endsWith("-detail");
 
@@ -86,7 +92,13 @@ export function buildSeoDocument(input: SeoDocumentInput): SeoDocument {
             locale: langToOpenGraphLocale(site.lang),
             siteName,
         },
-        image: { url: image, alt: contentTitle },
+        image: {
+            url: image,
+            alt: contentTitle,
+            ...(page.socialImage?.width ? { width: page.socialImage.width } : {}),
+            ...(page.socialImage?.height ? { height: page.socialImage.height } : {}),
+            ...(page.socialImage?.type ? { type: page.socialImage.type } : {}),
+        },
     };
     if (isArticle) {
         openGraph.article = {
@@ -99,7 +111,9 @@ export function buildSeoDocument(input: SeoDocumentInput): SeoDocument {
     }
 
     const twitter = {
-        card: (page.cover ? "summary_large_image" : "summary") as TwitterCardType,
+        card: (page.socialImage?.url || page.cover
+            ? "summary_large_image"
+            : "summary") as TwitterCardType,
         title: contentTitle,
         description: page.description,
         image,
@@ -268,5 +282,8 @@ export function buildSeoDocument(input: SeoDocumentInput): SeoDocument {
         links,
         meta,
         schema,
+        ...(page.socialImage?.fallbackUrl
+            ? { fallbackImage: absoluteUrl(page.socialImage.fallbackUrl, siteUrl, input.protocol) }
+            : {}),
     };
 }

package/src/utils/social-image.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+
+export interface SocialCardData {
+    title: string;
+    description: string;
+    siteTitle: string;
+    author: string;
+    host: string;
+    lang: string;
+    accent: string;
+    date: string;
+    category: string;
+    cover?: string;
+}
+
+export interface SocialImage {
+    url: string;
+    width?: number;
+    height?: number;
+    type?: string;
+    fallbackUrl?: string;
+}
+
+/** Explicit sharing images accept web URLs and site-root paths, never executable schemes. */
+export function isSocialImageUrl(value: string): boolean {
+    if (!value.trim() || /\s/u.test(value)) return false;
+    if (value.startsWith("/") && !value.startsWith("//")) return true;
+    try {
+        return (
+            ["http:", "https:"].includes(new URL(value, "https://example.invalid").protocol) &&
+            /^(?:https?:)?\/\//iu.test(value)
+        );
+    } catch {
+        return false;
+    }
+}
+
+export function socialCardPath(data: SocialCardData, base = "/"): string {
+    // Bump the template revision when layout changes. Metadata changes get a fresh URL.
+    const hash = createHash("sha256")
+        .update(JSON.stringify(["stalux-takumi-v2", data]))
+        .digest("hex")
+        .slice(0, 20);
+    return `${base.replace(/\/$/u, "")}/og/${hash}.webp`;
+}
+
+export function resolvePostSocialImage(
+    explicit: string | undefined,
+    data: SocialCardData,
+    base = "/",
+): SocialImage {
+    if (explicit?.trim() && isSocialImageUrl(explicit.trim())) return { url: explicit.trim() };
+    return {
+        url: socialCardPath(data, base),
+        width: 1200,
+        height: 630,
+        type: "image/webp",
+        fallbackUrl: socialCardPath(data, base).replace(/\.webp$/u, ".png"),
+    };
+}