@xingwangzhe/stalux 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.17.0",
+    "version": "1.19.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",
@@ -90,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/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";
 
 // ---------------------------------------------------------------------------
@@ -100,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);
@@ -117,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),
@@ -131,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,
+            });
         }
     }
 
@@ -251,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>();

package/src/layouts/Stalux.astro

@@ -36,9 +36,9 @@ const fontSubsetUrl = props.fontSubsetId
 
 // 背景 SVG 以静态 URL 硬编码在 background.ts（纯客户端），
 // 集成在 config:setup 时把 SVG 复制到用户项目 public/background/。
-// 这里只取第一张作为 SSR 初始背景，客户端运行时随机替换。
-// 不经过 import.meta.glob 资源管线，保证增量构建依赖图 hash 稳定。
-const initialBg = "/background/pattern-1.min.svg";
+// SSR 不渲染背景图，默认露出 .bg-layer 的灰墙底色（--stalux-bg-color），
+// 客户端运行时随机选图；不经过 import.meta.glob 资源管线，
+// 保证增量构建依赖图 hash 稳定。
 const llmPromoteRaw = promoteConfig?.llm_promote ?? "";
 const llmPromote = llmPromoteRaw
   ?.replace(/\{author\}/g, authorConfig.name)
@@ -97,12 +97,7 @@ const llmPromote = llmPromoteRaw
     data-stalux-bg-index="0"
   >
     {llmPromote && <div style="display:none">{llmPromote}</div>}
-    <div
-      class="bg-layer bg-a"
-      style={`background-image: url('${initialBg}'); opacity: 1;`}
-      aria-hidden="true"
-    >
-    </div>
+    <div class="bg-layer bg-a" style="opacity: 1;" aria-hidden="true"></div>
     <div class="bg-layer bg-b" aria-hidden="true"></div>
     <main class="stalux-main">
       <slot />

package/src/scripts/background.ts

@@ -6,7 +6,11 @@
  * 管线（import.meta.glob 会给 SVG 打上每次构建随机的 __ASTRO_ASSET_IMAGE__
  * 占位符，破坏增量构建依赖图 hash），也不做任何构建期扫描。
  *
- * 背景随机在客户端运行时执行，构建产物完全确定。
+ * 背景行为：
+ * - SSR 只渲染灰墙底色（--stalux-bg-color），不渲染任何背景图，构建产物确定。
+ * - 首次加载与 VT 软导航每次都会随机选一张背景：astro:page-load 在
+ *   window load（首访）与 swap 完成后、过渡动画期间（软导航）触发，
+ *   此时设置背景，过渡动画中旧图淡出、新图淡入，自然 crossfade 无跳变。
  */
 declare global {
     interface Window {
@@ -34,11 +38,11 @@ function setLayerOpacity(layer: "a" | "b", opacity: number): void {
     if (el) el.style.opacity = String(opacity);
 }
 
-function initBackground(): void {
+function applyBackground(): void {
     // 客户端运行时随机选图，构建产物保持确定性
     const index = Math.floor(Math.random() * backgroundImages.length);
     const layer: "a" | "b" = "a";
-    if (backgroundImages.length > 0) {
+    if (backgroundImages.length > 0 && backgroundImages[index]) {
         const el = getLayerEl(layer);
         if (el) el.style.backgroundImage = `url('${backgroundImages[index]}')`;
     }
@@ -48,16 +52,13 @@ function initBackground(): void {
     document.body.dataset.staluxBgLayer = layer;
 }
 
-// 初始化（首次加载 + VT 软导航都走这里）
-document.addEventListener("astro:page-load", () => {
-    const layer = document.body.dataset.staluxBgLayer as "a" | "b" | undefined;
-    const indexStr = document.body.dataset.staluxBgIndex;
-
-    if (layer && indexStr !== undefined) {
-        // View Transition 后：新页面服务端已渲染正确的背景，直接同步状态
-        setLayerOpacity(layer, 1);
-        setLayerOpacity(layer === "a" ? "b" : "a", 0);
-    } else {
-        initBackground();
-    }
-});
+// 首次加载与 VT 软导航都触发 astro:page-load：
+// - 首次加载：window load 后触发（router.js addEventListener("load", onPageLoad)）。
+// - VT 软导航：swap 完成后、过渡动画期间触发（router.js onPageLoad()），
+//   此时设置随机背景，过渡中旧图淡出、新图淡入，无跳变闪变。
+// 注意：软导航不会重新执行打包的 module 脚本（监听器仍是首访注册的），
+// 所以这里不能做“只执行一次”的去重，每次 page-load 都必须随机；
+// 若软导航后新脚本被重新执行，重复监听导致随机两次也无妨（仍是随机图）。
+// body 的 data-stalux-bg-* 是 SSR 固定占位（a/0，为了构建确定性），
+// 不能再用它判断“服务端已渲染正确背景”，否则随机逻辑永不执行。
+document.addEventListener("astro:page-load", applyBackground);