@xingwangzhe/stalux 1.41.5 → 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.5",
+    "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/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"),
+    };
+}