@xingwangzhe/stalux 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.16.0",
+    "version": "1.18.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -38,6 +38,7 @@
         "src/plugins/**/*.ts",
         "src/internal/**/*.ts",
         "src/scripts/**/*.ts",
+        "public/background/**",
         "src/assets/**/*",
         "scripts/cli.mjs",
         "!src/content.config.ts"
@@ -89,6 +90,7 @@
         "astro-seo": "^1.1.0",
         "astro-typewriter": "^1.2.0",
         "badge-maker": "^6.0.0",
+        "js-yaml": "^5.2.3",
         "pagefind": "^1.5.2",
         "photoswipe": "^5.4.4",
         "satteri": "^0.9.5",

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

@@ -2,7 +2,6 @@
 import { SEO } from "astro-seo";
 import { ClientRouter } from "astro:transitions";
 import { getCollection } from "astro:content";
-import { Font } from "astro:assets";
 import VerCount from "@components/stalux/common/verCount.astro";
 import GoogleAnalytics from "@components/stalux/analytics/google.astro";
 import BingClarity from "@components/stalux/analytics/clarity.astro";
@@ -175,7 +174,8 @@ const ldJson = JSON.stringify(schema, null, 2).replace(/<\//g, "<\\/");
     }}
   />
   <style set:html={`:root{--font-body:"LXGW WenKai Subset","Noto Sans SC","Noto Sans CJK SC",system-ui,-apple-system,sans-serif}`} />
-  <Font cssVariable="--font-code" />
+  <!-- 代码字体：静态 code.css（font-subset.ts 生成，确定性，不经过 Astro <Font> 管线） -->
+  <link rel="stylesheet" href="/fonts/code.css" />
   {
     (headConfig?.anyhead) && (
       <Fragment set:html={headConfig.anyhead} />

package/src/index.ts

@@ -8,7 +8,7 @@
  * 基于 Astro 7.1.3 Integration API（astro:config:setup / injectRoute / injectScript）
  */
 
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -93,6 +93,45 @@ function getRoutes(baseDir: URL): RouteEntry[] {
     ];
 }
 
+// ---------------------------------------------------------------------------
+// 背景 SVG 判别式同步
+// ---------------------------------------------------------------------------
+
+/**
+ * 把主题包的 public/background/*.svg 同步到用户项目 public/background/。
+ *
+ * 判别式（非无条件覆盖）：
+ * - 同名文件：内容一致则跳过（幂等）；内容不同才覆盖（主题更新了 SVG）
+ * - 用户新增的文件：保留，不删除（避免误删用户自定义背景）
+ * - 不做整目录 force 复制
+ */
+function syncBackgroundSvgs(srcDir: string): { copied: number; skipped: number } {
+    const srcBg = path.join(srcDir, "../public/background");
+    if (!existsSync(srcBg)) return { copied: 0, skipped: 0 };
+
+    const destBg = path.resolve(process.cwd(), "public", "background");
+    mkdirSync(destBg, { recursive: true });
+
+    let copied = 0;
+    let skipped = 0;
+    for (const name of readdirSync(srcBg)) {
+        if (!name.endsWith(".svg")) continue;
+        const srcFile = path.join(srcBg, name);
+        const destFile = path.join(destBg, name);
+        if (existsSync(destFile)) {
+            const srcBuf = readFileSync(srcFile);
+            const destBuf = readFileSync(destFile);
+            if (srcBuf.equals(destBuf)) {
+                skipped++; // 内容一致，跳过
+                continue;
+            }
+        }
+        copyFileSync(srcFile, destFile);
+        copied++;
+    }
+    return { copied, skipped };
+}
+
 // ---------------------------------------------------------------------------
 // Vite 别名配置（供页面使用 @components etc.）
 // ---------------------------------------------------------------------------
@@ -172,6 +211,22 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration {
                 // 2. 注入全局 CSS
                 injectScript("page-ssr", `import "${srcDir}/styles/base/init.css";`);
 
+                // 2.5 同步背景 SVG 到用户项目 public/background/
+                // 纯客户端引入：SVG 以静态 URL（/background/pattern-*.svg）被 background.ts 硬编码引用，
+                // 不经过 Astro 资源管线（import.meta.glob 会打上每次构建随机的 __ASTRO_ASSET_IMAGE__ 占位符，
+                // 破坏增量构建依赖图 hash）。Astro 不会合并集成的 public 目录，这里显式同步一次。
+                // 判别式：内容一致跳过（幂等），内容不同才覆盖，用户新增文件保留。
+                try {
+                    const { copied, skipped } = syncBackgroundSvgs(srcDir);
+                    if (copied > 0) {
+                        logger.info(`Stalux: 同步背景 SVG ${copied} 个（跳过 ${skipped} 个不变）`);
+                    } else if (skipped > 0) {
+                        logger.debug(`Stalux: 背景 SVG 无变化（跳过 ${skipped} 个）`);
+                    }
+                } catch (error) {
+                    logger.warn(`Stalux: 同步背景 SVG 失败: ${String(error)}`);
+                }
+
                 // 3. 注入所有页面路由（仅插件模式，源码模式下使用文件路由）
                 if (isPluginMode) {
                     const routes = getRoutes(new URL(".", import.meta.url));

package/src/internal/font-subset.ts

@@ -27,6 +27,10 @@ import { resolve, basename, extname, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import type { AstroIntegrationLogger } from "astro";
+// 与 Astro 内容集合同款的 YAML 解析器（astro 依赖 js-yaml 解析 frontmatter，
+// 见 node_modules/astro/dist/content/loaders/file.js）。用它解析 frontmatter
+// 得到的结果与 getCollection 的 data 一致：引号剥离、类型还原、结构完整。
+import { load as parseYaml } from "js-yaml";
 import subsetFont from "subset-font";
 
 // ---------------------------------------------------------------------------
@@ -39,6 +43,9 @@ const CONTENT_ROOT = "stalux";
 /** Full font input path (relative to project root or package) */
 const FONT_INPUT = "src/assets/fonts/LXGWWenKai-Regular.ttf";
 
+/** Code font input path (Google Sans Code, deterministic static @font-face) */
+const CODE_FONT_INPUT = "src/assets/fonts/GoogleSansCode.woff2";
+
 /** Output directory for generated subsets */
 const FONT_OUT_DIR = "public/fonts";
 
@@ -97,6 +104,43 @@ interface ContentFile {
     abbrlink?: string;
 }
 
+/**
+ * 用 js-yaml（内容集合同款解析器）解析 frontmatter。
+ *
+ * 结果与 getCollection("posts") 的 data 一致：
+ * - abbrlink：number 转 string、引号剥离（YAML 解析天然处理）
+ * - tags/categories：单行字符串 "Bing" 按 schema preprocess 转 ["Bing"]
+ */
+function parsePostFrontmatter(content: string): {
+    abbrlink?: string;
+    tags: string[];
+    categories: string[];
+} {
+    const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m) return { abbrlink: undefined, tags: [], categories: [] };
+
+    let data: Record<string, unknown>;
+    try {
+        data = (parseYaml(m[1]) as Record<string, unknown>) ?? {};
+    } catch {
+        return { abbrlink: undefined, tags: [], categories: [] };
+    }
+
+    // 复刻 posts schema 的 preprocess：单行字符串转数组
+    const toList = (v: unknown): string[] => {
+        if (Array.isArray(v)) return v.map((x) => String(x));
+        if (typeof v === "string") return v.trim() ? [v.trim()] : [];
+        return [];
+    };
+
+    const abbr = data.abbrlink;
+    return {
+        abbrlink: abbr === undefined || abbr === null ? undefined : String(abbr),
+        tags: toList(data.tags),
+        categories: toList(data.categories),
+    };
+}
+
 function scanContent(projectRoot: string): ContentFile[] {
     const files: ContentFile[] = [];
     const contentRoot = resolve(projectRoot, CONTENT_ROOT);
@@ -114,11 +158,11 @@ function scanContent(projectRoot: string): ContentFile[] {
             if (!f.endsWith(".md") && !f.endsWith(".mdx")) continue;
             const content = readFileSync(join(postsDir, f), "utf-8");
             const isTemplate = f.startsWith("_");
+            const fm = parsePostFrontmatter(content);
 
             // Per-post routes: skip template (_) files
             if (!isTemplate) {
-                const abbrlinkMatch = content.match(/^abbrlink:\s*(.+)$/m);
-                const abbrlink = abbrlinkMatch?.[1]?.trim() ?? basename(f, extname(f));
+                const abbrlink = fm.abbrlink ?? basename(f, extname(f));
                 files.push({
                     route: `posts/${abbrlink}`,
                     filePath: join(postsDir, f),
@@ -128,11 +172,13 @@ function scanContent(projectRoot: string): ContentFile[] {
 
             // Virtual routes (archives/tags/categories): include ALL posts including templates
             // because content collections load them and they render on those pages
-            const abbrlinkMatch = content.match(/^abbrlink:\s*(.+)$/m);
-            const abbrlink = abbrlinkMatch?.[1]?.trim() ?? basename(f, extname(f));
-            const tags = extractYamlList(content, "tags");
-            const categories = extractYamlList(content, "categories");
-            allPostContents.push({ abbrlink, tags, categories, content });
+            const abbrlink = fm.abbrlink ?? basename(f, extname(f));
+            allPostContents.push({
+                abbrlink,
+                tags: fm.tags,
+                categories: fm.categories,
+                content,
+            });
         }
     }
 
@@ -248,23 +294,6 @@ function scanContent(projectRoot: string): ContentFile[] {
     return files;
 }
 
-/** Extract a YAML list value from frontmatter by key */
-function extractYamlList(content: string, key: string): string[] {
-    const lines: string[] = [];
-    const regex = new RegExp(`^${key}:$`, "m");
-    const match = content.match(regex);
-    if (!match) return [];
-    const startIdx = match.index! + match[0].length;
-    const afterKey = content.slice(startIdx);
-    const listMatch = afterKey.match(/^\n((?:\s+-\s+.+\n?)*)/);
-    if (!listMatch) return [];
-    for (const line of listMatch[1].split("\n")) {
-        const item = line.match(/^\s+-\s+(.+)/)?.[1];
-        if (item) lines.push(item.trim());
-    }
-    return lines;
-}
-
 // Cache for virtual route char sets
 const wordCharsCache = new Map<string, string>();
 const virtualRouteCache = new Map<string, string>();
@@ -404,6 +433,47 @@ export async function runFontSubsetting(
         }
     }
 
+    // 1.5 代码字体（Google Sans Code）— 确定性静态 @font-face，不经过 Astro 字体管线
+    // Astro 的 <Font> 组件会在 prerender 阶段启动一个随机端口的 HTTP server，
+    // 端口号会嵌进 font-file-url-resolver 虚拟模块的编译产物，破坏增量构建依赖图 hash。
+    // 这里直接复制 woff2 到 public/fonts/ 并生成静态 code.css，完全绕开该管线。
+    try {
+        const codeFontPaths = [
+            resolve(projectRoot, CODE_FONT_INPUT),
+            resolve(projectRoot, "node_modules", "@xingwangzhe", "stalux", CODE_FONT_INPUT),
+            resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", CODE_FONT_INPUT),
+        ];
+        const codeFontPath = codeFontPaths.find((p) => existsSync(p));
+        if (codeFontPath) {
+            const codeFontBuffer = readFileSync(codeFontPath);
+            const codeFontOut = join(outDir, "GoogleSansCode.woff2");
+            if (!existsSync(codeFontOut) || !readFileSync(codeFontOut).equals(codeFontBuffer)) {
+                writeFileSync(codeFontOut, codeFontBuffer);
+                logger.info(
+                    `  code font: ${codeFontBuffer.length / 1024} KB → GoogleSansCode.woff2`,
+                );
+            }
+            // 静态 CSS：@font-face + --font-code 变量（确定性内容，无 hash）
+            const codeCSS = `/* Auto-generated code font (deterministic, no Astro font pipeline) */
+:root {
+    --font-code: "Google Sans Code", "JetBrains Mono", "Fira Code", "Consolas", "Courier New", monospace;
+}
+@font-face {
+    font-family: "Google Sans Code";
+    src: url("/fonts/GoogleSansCode.woff2") format("woff2");
+    font-display: swap;
+}
+`;
+            writeFileSync(join(outDir, "code.css"), codeCSS);
+        } else {
+            logger.warn(
+                `Code font not found at ${CODE_FONT_INPUT}, --font-code falls back to system monospace`,
+            );
+        }
+    } catch (error) {
+        logger.warn(`Code font setup failed: ${String(error)}`);
+    }
+
     // 2. Scan content files
     const contentFiles = scanContent(projectRoot);
     logger.info(`Font subsetting: found ${contentFiles.length} content files`);

package/src/layouts/Stalux.astro

@@ -34,22 +34,11 @@ const fontSubsetUrl = props.fontSubsetId
   ? `/fonts/subset-${props.fontSubsetId}.css`
   : undefined;
 
-const bgModules = import.meta.glob<{ default: { src: string } }>(
-    "../assets/background/pattern-*.min.svg",
-    { eager: true },
-);
-const bgUrls = Object.values(bgModules)
-    .map((m) => m.default.src)
-    .sort((a, b) => {
-        const na = parseInt(a.match(/pattern-(\d+)/)?.[1] || "0", 10);
-        const nb = parseInt(b.match(/pattern-(\d+)/)?.[1] || "0", 10);
-        return na - nb;
-    });
-// 背景索引固定为 0（确定性）：保证 define:vars 内联脚本在构建间稳定，
-// 使 Astro 增量构建的依赖图 hash 可复用。真正的随机背景由客户端
-// background.ts 在运行时为每个访问者挑选。
-const randomIndex = 0;
-const initialBg = bgUrls[randomIndex] || "";
+// 背景 SVG 以静态 URL 硬编码在 background.ts（纯客户端），
+// 集成在 config:setup 时把 SVG 复制到用户项目 public/background/。
+// 这里只取第一张作为 SSR 初始背景，客户端运行时随机替换。
+// 不经过 import.meta.glob 资源管线，保证增量构建依赖图 hash 稳定。
+const initialBg = "/background/pattern-1.min.svg";
 const llmPromoteRaw = promoteConfig?.llm_promote ?? "";
 const llmPromote = llmPromoteRaw
   ?.replace(/\{author\}/g, authorConfig.name)
@@ -75,9 +64,6 @@ const llmPromote = llmPromoteRaw
   <!-- Per-route font subset (generated at build time) -->
   <link rel="stylesheet" href="/fonts/common.css" />
   {fontSubsetUrl && <link rel="stylesheet" href={fontSubsetUrl} />}
-  <script define:vars={{ bgUrls }}>
-    window.__STALUX_BG_URLS__ = bgUrls;
-  </script>
   <script>
     import "../scripts/background.ts";
   </script>
@@ -108,7 +94,7 @@ const llmPromote = llmPromoteRaw
   <body
     class="stalux-root dark"
     data-stalux-bg-layer="a"
-    data-stalux-bg-index={randomIndex}
+    data-stalux-bg-index="0"
   >
     {llmPromote && <div style="display:none">{llmPromote}</div>}
     <div

package/src/scripts/background.ts

@@ -1,8 +1,12 @@
 /**
- * 双层随机背景 — 客户端运行时随机选图，不做 VT crossfade
- * （去掉 view-transition-name 避免 SVG 全屏瓦片在过渡期间双倍 CPU 光栅化）
- * 背景随机从服务端移到客户端，保证构建产物确定性，
- * 使 Astro 增量构建的依赖图 hash 可跨构建复用。
+ * 双层随机背景 — 纯客户端实现
+ *
+ * SVG 以静态 URL（/background/pattern-N.min.svg）硬编码，由集成在
+ * config:setup 时复制到用户项目 public/background/。不经过 Astro 资源
+ * 管线（import.meta.glob 会给 SVG 打上每次构建随机的 __ASTRO_ASSET_IMAGE__
+ * 占位符，破坏增量构建依赖图 hash），也不做任何构建期扫描。
+ *
+ * 背景随机在客户端运行时执行，构建产物完全确定。
  */
 declare global {
     interface Window {
@@ -10,7 +14,16 @@ declare global {
     }
 }
 
-const backgroundImages: string[] = window.__STALUX_BG_URLS__ || [];
+/** 背景 SVG 静态 URL 列表（与主题包 public/background/ 的 1-42 号一一对应） */
+const BACKGROUND_URLS: string[] = Array.from(
+    { length: 42 },
+    (_, i) => `/background/pattern-${i + 1}.min.svg`,
+);
+
+/** 优先使用注入列表（若用户自定义），否则用内置硬编码列表 */
+const backgroundImages: string[] = window.__STALUX_BG_URLS__?.length
+    ? window.__STALUX_BG_URLS__
+    : BACKGROUND_URLS;
 
 function getLayerEl(layer: "a" | "b"): HTMLElement | null {
     return document.querySelector(`.bg-layer.bg-${layer}`);
@@ -22,8 +35,7 @@ function setLayerOpacity(layer: "a" | "b", opacity: number): void {
 }
 
 function initBackground(): void {
-    // 背景随机在客户端运行时执行，保证构建产物确定性
-    // （SSR 固定索引 → 内联脚本稳定 → Astro 增量构建依赖图可复用）
+    // 客户端运行时随机选图，构建产物保持确定性
     const index = Math.floor(Math.random() * backgroundImages.length);
     const layer: "a" | "b" = "a";
     if (backgroundImages.length > 0) {

package/src/scripts/webmcp.ts

@@ -93,8 +93,10 @@ async function loadPagefind(): Promise<{ search: (q: string) => Promise<unknown>
     if (!pagefindLoadPromise) {
         pagefindLoadPromise = (async () => {
             try {
-                // @vite-ignore: pagefind 索引是构建期产物，不参与依赖打包
-                const mod = await import(/* @vite-ignore */ "/pagefind/pagefind.js");
+                // 用完整 URL 构造，让 Vite 在 dev（vite:import-analysis）与 build 都不解析该路径；
+                // pagefind 索引是构建期产物，运行时从站点根加载。
+                const url = new URL("/pagefind/pagefind.js", location.origin).href;
+                const mod = await import(/* @vite-ignore */ url);
                 return mod.default ?? mod;
             } catch {
                 return null;