@xingwangzhe/stalux 1.49.0 → 1.51.0

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

@@ -1,322 +1,185 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, 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";
+import { Resvg } from "@resvg/resvg-js";
+import satori from "satori";
+import { type SocialCardData, socialCardFormat } from "../utils/social-image";
+import { loadSharp, type SharpPipeline, type SharpRawBuffer } from "./sharp-loader";
+import { coverDataUri, loadCover, prepareCover, type SocialCardPaths } from "./social-card-cover";
+import {
+    CARD_FONT_FAMILY,
+    CARD_FONT_WEIGHT,
+    CARD_HEIGHT,
+    CARD_WIDTH,
+    COVER_LEFT,
+    socialCardTree,
+} from "./social-card-layout";
 
-export interface SocialCardPaths {
-    publicDir: string;
-    cacheDir: string;
-    base: string;
-    fontPath: string;
-}
+export type { SocialCardPaths } from "./social-card-cover";
+export { localCoverPath } from "./social-card-cover";
+export { socialCardTree } from "./social-card-layout";
+
+/** Bump when the layout changes so every cached render is replaced. */
+const TEMPLATE = "stalux-mono-v1";
+
+type SatoriInput = Parameters<typeof satori>[0];
 
-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;
+function encodeWithSharp(
+    pipeline: SharpPipeline,
+    format: "jpg" | "png",
+    panel?: SharpRawBuffer,
+): Promise<Buffer> {
+    if (format === "jpg") {
+        // The artwork keeps its colour. Without artwork the whole frame is
+        // black and white, so the smaller true grayscale JPEG is used.
+        const composed = panel
+            ? pipeline.composite([
+                  {
+                      input: panel.data,
+                      raw: {
+                          width: panel.info.width,
+                          height: panel.info.height,
+                          channels: panel.info.channels,
+                      },
+                      left: COVER_LEFT,
+                      top: 0,
+                  },
+              ])
+            : pipeline.greyscale().toColourspace("b-w");
+        return composed.jpeg({ quality: 80, mozjpeg: true }).toBuffer();
+    }
+    return pipeline
+        .greyscale()
+        .png({ compressionLevel: 9, palette: true, colours: 256, effort: 3 })
+        .toBuffer();
 }
 
 /**
- * Font identity for the render cache.
- *
- * The key used to carry the font's size and mtime, so re-installing the theme,
- * restoring a checkout, or copying the package to a build machine changed every
- * card's key at once and re-rendered all of them (about 8s each). Hashing the
- * bytes keeps the key stable for identical font content and still changes when
- * the font really is different.
+ * Rasterize with Resvg, then let Sharp compose and encode in a single pass.
+ * System-font discovery is disabled because Satori already converted every
+ * glyph to a path; leaving it on made each Resvg instance scan all installed
+ * fonts, costing about 500ms per card.
  */
-let fontDigestPromise: Promise<string> | undefined;
-function getFontDigest(fontPath: string): Promise<string> {
-    fontDigestPromise ??= readFile(fontPath).then((bytes) =>
-        createHash("sha256").update(bytes).digest("hex"),
-    );
-    return fontDigestPromise;
-}
-
-/** 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;
+async function renderCardBytes(
+    svg: string,
+    format: "jpg" | "png",
+    panel?: SharpRawBuffer,
+): Promise<Buffer> {
+    const png = new Resvg(svg, {
+        fitTo: { mode: "width", value: CARD_WIDTH },
+        background: "#ffffff",
+        font: { loadSystemFonts: false },
+    })
+        .render()
+        .asPng();
+    const sharp = loadSharp();
+    if (!sharp) {
+        if (format === "jpg") throw new Error("JPEG encoding requires sharp");
+        return png;
+    }
     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;
+        return await encodeWithSharp(sharp(png), format, panel);
+    } catch (error) {
+        if (format === "jpg") throw error;
+        return png;
     }
 }
 
-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);
+const fonts = new Map<string, Promise<Buffer>>();
+function readFont(fontPath: string): Promise<Buffer> {
+    let pending = fonts.get(fontPath);
     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 ?? "");
+        pending = readFile(fontPath);
+        fonts.set(fontPath, pending);
     }
     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,
-    };
+let fontDigestPromise: Promise<string> | undefined;
+function getFontDigest(fontPath: string): Promise<string> {
+    fontDigestPromise ??= readFile(fontPath).then((bytes) =>
+        createHash("sha256").update(bytes).digest("hex"),
+    );
+    return fontDigestPromise;
 }
 
 export async function renderSocialCard(
     data: SocialCardData,
     paths: SocialCardPaths,
     warn: (message: string) => void,
-    format: "webp" | "png" = "webp",
 ): Promise<Buffer> {
-    let cover: Buffer | undefined;
+    const format = socialCardFormat(data);
+    const sharpAvailable = Boolean(loadSharp());
+    let coverBytes: Buffer | undefined;
     if (data.cover) {
         try {
-            cover = await loadCover(data.cover, paths);
+            coverBytes = await loadCover(data.cover, paths);
         } catch {
             warn(`分享封面不可用，已回退标题卡片：${data.title}`);
         }
     }
     // Content-only key: identical card data + identical font + identical cover
     // always reuses the cached render, whatever the filesystem timestamps say.
+    // It is checked before cropping artwork so a warm build does no image work.
     const fontDigest = await getFontDigest(paths.fontPath);
     const key = createHash("sha256")
-        .update(JSON.stringify(["v3", format, data, fontDigest]))
-        .update(cover ?? "")
+        .update(
+            JSON.stringify([TEMPLATE, format, data, fontDigest, sharpAvailable ? "panel" : "flat"]),
+        )
+        .update(coverBytes ?? "")
         .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("")}…`;
+
+    let panel: SharpRawBuffer | undefined;
+    let inlineCover: string | undefined;
+    if (coverBytes) {
+        if (sharpAvailable) {
+            try {
+                panel = await prepareCover(coverBytes);
+            } catch {
+                warn(`分享封面不可用，已回退标题卡片：${data.title}`);
+            }
+        } else {
+            // Without sharp there is no compositor, so the original bytes go
+            // through Satori instead (PNG/JPEG only, and no palette encoding).
+            inlineCover = coverDataUri(coverBytes);
         }
-        return socialCardTree(data, withCover, size, title);
+    }
+
+    const withCover = Boolean(panel || inlineCover);
+    const renderTree = async (hasCover: boolean) => {
+        const svg = await satori(
+            socialCardTree(
+                data,
+                hasCover,
+                hasCover ? inlineCover : undefined,
+            ) as unknown as SatoriInput,
+            {
+                width: CARD_WIDTH,
+                height: CARD_HEIGHT,
+                fonts: [
+                    {
+                        name: CARD_FONT_FAMILY,
+                        data: await readFont(paths.fontPath),
+                        weight: CARD_FONT_WEIGHT,
+                        style: "normal",
+                    },
+                ],
+            },
+        );
+        return renderCardBytes(svg, format, hasCover ? panel : undefined);
     };
     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 }] : [],
-        });
+        bytes = await renderTree(withCover);
     } catch (error) {
-        if (!cover) throw error;
+        if (!withCover) throw error;
         warn(`分享封面解码失败，已回退标题卡片：${data.title}`);
-        bytes = await renderer.render(await layout(false), {
-            width: 1200,
-            height: 630,
-            format,
-            quality: 86,
-        });
+        // Do not cache the fallback under the artwork key: a later build should
+        // retry the cover instead of inheriting a short-lived decode failure.
+        return renderTree(false);
     }
     await mkdir(paths.cacheDir, { recursive: true });
     await writeFile(cacheFile, bytes);

package/src/layouts/Stalux.astro

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

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

@@ -5,7 +5,12 @@ 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";
+import {
+    isSocialImageUrl,
+    type SocialCardData,
+    type SocialCardFormat,
+    socialCardPath,
+} from "../../utils/social-image";
 
 export async function getStaticPaths() {
     const entries = await getCollection("config");
@@ -17,34 +22,28 @@ export async function getStaticPaths() {
             (post) =>
                 !(post.data["og:image"]?.trim() && isSocialImageUrl(post.data["og:image"].trim())),
         )
-        .flatMap((post) => {
+        .map((post) => {
             const card = createSocialCardData(post.data, site, author);
-            // PNG only. og:image must stay PNG because several platforms refuse
-            // WebP and AVIF in share previews, and a second format per post
-            // doubled the render work (about 8s each) for no visible gain.
-            return (["png"] as const).map((format) => ({
+            // The extension is part of the metadata contract: artwork cards are
+            // photographic JPEG, plain cards are palette PNG.
+            const file = socialCardPath(card).split("/").at(-1) ?? "";
+            const dot = file.lastIndexOf(".");
+            return {
                 params: {
-                    image: socialCardPath(card)
-                        .split("/")
-                        .at(-1)
-                        ?.replace(/\.png$/u, ""),
-                    format,
+                    image: file.slice(0, dot),
+                    format: file.slice(dot + 1) as SocialCardFormat,
                 },
-                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.
-            }));
+                props: { card, format: file.slice(dot + 1) as SocialCardFormat },
+            };
         });
 }
 
 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",
+    const bytes = await renderSocialCard(props.card as SocialCardData, paths, (message) =>
+        logger.warn(message),
     );
+    const type = props.format === "jpg" ? "image/jpeg" : "image/png";
     return new Response(new Uint8Array(bytes), {
-        headers: { "Content-Type": `image/${props.format}` },
+        headers: { "Content-Type": type },
     });
 };

package/src/scripts/route-prefetch.ts

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