@xingwangzhe/stalux 1.18.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.18.0",
+    "version": "1.20.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/internal/font-subset.ts

@@ -74,7 +74,8 @@ interface RouteCharSet {
 }
 
 interface FontManifest {
-    common: string; // filename of common subset
+    common: string; // filename of common subset TTF
+    commonCss: string; // filename of common subset CSS (content-addressed)
     routes: Record<string, string>; // route → subset filename
     /** Per-post mapping: abbrlink → subset filename */
     posts: Record<string, string>;
@@ -157,22 +158,19 @@ function scanContent(projectRoot: string): ContentFile[] {
         for (const f of readdirSync(postsDir)) {
             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 abbrlink = fm.abbrlink ?? basename(f, extname(f));
-                files.push({
-                    route: `posts/${abbrlink}`,
-                    filePath: join(postsDir, f),
-                    abbrlink,
-                });
-            }
-
+            // Per-post routes：与内容集合 glob（*.{md,mdx}，含 _ 前缀文件，
+            // 见 schemas/collections.ts）保持一致——这些文件都会生成页面，
+            // 字体子集必须覆盖，否则页面 subset css 缺失 → 404。
+            const abbrlink = fm.abbrlink ?? basename(f, extname(f));
+            files.push({
+                route: `posts/${abbrlink}`,
+                filePath: join(postsDir, f),
+                abbrlink,
+            });
             // Virtual routes (archives/tags/categories): include ALL posts including templates
             // because content collections load them and they render on those pages
-            const abbrlink = fm.abbrlink ?? basename(f, extname(f));
             allPostContents.push({
                 abbrlink,
                 tags: fm.tags,
@@ -423,7 +421,7 @@ export async function runFontSubsetting(
     const outDir = resolve(projectRoot, FONT_OUT_DIR);
     if (existsSync(outDir)) {
         for (const f of readdirSync(outDir)) {
-            if (f.startsWith("common-") || f.startsWith("subset-")) {
+            if (f.startsWith("common-") || f.startsWith("subset-") || f === "common.css") {
                 try {
                     unlinkSync(join(outDir, f));
                 } catch {
@@ -530,7 +528,11 @@ export async function runFontSubsetting(
         }
     }
 
-    // Generate common CSS
+    // Generate common CSS (content-addressed filename: 字符集变化 → hash 变化 →
+    // 文件名变化，浏览器必然拉新 CSS，避免缓存旧 CSS 引用已删除的旧 TTF 导致 404)
+    // dev 模式（skipPerRoute）用固定名 common.css，由 dev 中间件场景复用；
+    // 生产构建用 common-<hash>.css，HTML 从 manifest 读取引用。
+    const commonCssName = skipPerRoute ? "common.css" : `common-${commonHash}.css`;
     const commonCSS = `/* Auto-generated common font subset */
 @font-face {
     font-family: "LXGW WenKai Subset";
@@ -538,7 +540,7 @@ export async function runFontSubsetting(
     font-display: swap;
 }
 `;
-    writeFileSync(join(outDir, "common.css"), commonCSS);
+    writeFileSync(join(outDir, commonCssName), commonCSS);
 
     const groups = deduplicate(routeSets);
     const routeMap: Record<string, string> = {};
@@ -570,8 +572,11 @@ export async function runFontSubsetting(
             }
 
             // Generate per-route CSS (each route gets its own CSS file)
+            // CSS 文件名内容寻址：内容只引用一个 TTF，文件名带上该 TTF 的 hash，
+            // 内容变化 → 文件名变化 → 浏览器必然拉新，避免缓存旧 CSS 引用已删除 TTF。
             // If no unique chars, reference the common TTF as fallback
             const refTtf = existsSync(outPath) ? filename : commonFilename;
+            const refHash = existsSync(outPath) ? hash : commonHash;
             for (const route of routes) {
                 const cssContent = `/* Auto-generated font subset for route: ${route} */
 @font-face {
@@ -581,7 +586,7 @@ export async function runFontSubsetting(
 }
 `;
                 const cssName = route.replace("/", "-");
-                const cssFilename = `subset-${cssName}.css`;
+                const cssFilename = `subset-${cssName}-${refHash}.css`;
                 writeFileSync(join(outDir, cssFilename), cssContent);
                 routeMap[route] = cssFilename;
 
@@ -591,17 +596,24 @@ export async function runFontSubsetting(
                 }
             }
         }
-
-        // 6. Generate manifest
-        const manifest: FontManifest = {
-            common: commonFilename,
-            routes: routeMap,
-            posts: postMap,
-        };
-        writeFileSync(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-
-        logger.info(
-            `Font subsetting done: ${subsetCount} route subsets + common (${(fontBuffer.length / 1024 / 1024).toFixed(1)} MB → variable)`,
-        );
     }
+
+    // 6. Generate manifest（dev 也生成：routes/posts 为空，供 Stalux.astro import）
+    const manifest: FontManifest = {
+        common: commonFilename,
+        commonCss: commonCssName,
+        routes: routeMap,
+        posts: postMap,
+    };
+    writeFileSync(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+    // 副本写入包内 generated/：Stalux.astro import 它，让 manifest 进入 Astro
+    // 依赖图——manifest 变化时页面必然重建，增量构建 restored 的页面不会引用旧资源。
+    const genDir = resolve(dirname(fileURLToPath(import.meta.url)), "generated");
+    mkdirSync(genDir, { recursive: true });
+    writeFileSync(join(genDir, "fonts-manifest.json"), JSON.stringify(manifest));
+
+    logger.info(
+        `Font subsetting done: ${subsetCount} route subsets + common (${(fontBuffer.length / 1024 / 1024).toFixed(1)} MB → variable)`,
+    );
 }

package/src/layouts/Stalux.astro

@@ -5,6 +5,9 @@ import { getCollection } from "astro:content";
 import "@styles/base/init.css";
 import "@styles/shared/stagger.css";
 import { getAuthorData, getAiDiscoveryData, getPromoteData, getSiteData } from "@utils/config-utils";
+// font-subset.ts 构建期生成的 manifest 副本（进入 Astro 依赖图，
+// manifest 变化 → 页面重建 → 增量构建 restored 的页面不会引用旧字体资源）
+import fontsManifest from "../internal/generated/fonts-manifest.json";
 const props = Astro.props as Props;
 
 interface Props {
@@ -29,16 +32,44 @@ const promoteConfig = getPromoteData(configEntries);
 const aiConfig = getAiDiscoveryData(configEntries);
 const htmlLang = siteConfig.lang || "zh-CN";
 
-// Resolve font subset CSS URL
-const fontSubsetUrl = props.fontSubsetId
-  ? `/fonts/subset-${props.fontSubsetId}.css`
-  : undefined;
+// Resolve font subset CSS URLs（内容寻址，避免浏览器缓存旧 CSS 引用已删除 TTF → 404）
+// 生产构建：font-subset.ts 生成带 hash 的 CSS 文件名并写入 manifest（副本 import 至此），
+// 这里从 manifest 取文件名，内容变化必然换名、浏览器自动拉新。
+// dev 模式：manifest 的 routes 为空（skipPerRoute），回退固定名 /fonts/common.css 与
+// /fonts/subset-<id>.css，由 dev 按需中间件生成。
+const fontManifest = fontsManifest as
+    | {
+          commonCss?: string;
+          routes?: Record<string, string>;
+      }
+    | null
+    | undefined;
+
+let commonFontCssUrl = "/fonts/common.css";
+let fontSubsetUrl: string | undefined;
+if (props.fontSubsetId) {
+    fontSubsetUrl = `/fonts/subset-${props.fontSubsetId}.css`;
+}
+if (fontManifest?.commonCss) {
+    commonFontCssUrl = `/fonts/${fontManifest.commonCss}`;
+}
+if (props.fontSubsetId && fontManifest?.routes) {
+    // route 键可能是 posts/xxx（页面对应 posts-xxx）或含原始 unicode（tag/category），
+    // 统一归一化比较：route.replace("/", "-") === decodeURIComponent(fontSubsetId)
+    const want = decodeURIComponent(props.fontSubsetId);
+    for (const [route, cssFile] of Object.entries(fontManifest.routes)) {
+        if (route.replace("/", "-") === want) {
+            fontSubsetUrl = `/fonts/${encodeURIComponent(cssFile)}`;
+            break;
+        }
+    }
+}
 
 // 背景 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)
@@ -62,7 +93,7 @@ const llmPromote = llmPromoteRaw
     noindex={props.noindex}
   />
   <!-- Per-route font subset (generated at build time) -->
-  <link rel="stylesheet" href="/fonts/common.css" />
+  <link rel="stylesheet" href={commonFontCssUrl} />
   {fontSubsetUrl && <link rel="stylesheet" href={fontSubsetUrl} />}
   <script>
     import "../scripts/background.ts";
@@ -97,12 +128,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);