@windcoder/astro-theme-orchid 0.3.0 → 0.4.1

package/src/utils/gallery.ts

@@ -7,6 +7,8 @@ import path from "node:path";
  */
 
 const IMAGE_RE = /\.(jpe?g|png|webp|avif|gif)$/i;
+/* §4.106：.thumb.webp 是 generate-lqips.mjs 的缩略图产物，不是照片本体 */
+const THUMB_RE = /\.thumb\.webp$/i;
 const COVER_RE = /^cover\./i;
 
 export interface GalleryAlbumMeta {
@@ -31,7 +33,7 @@ export function scanAlbumPhotos(albumId: string): string[] {
 
 	const files = fs
 		.readdirSync(dir)
-		.filter((f) => IMAGE_RE.test(f))
+		.filter((f) => IMAGE_RE.test(f) && !THUMB_RE.test(f))
 		.sort();
 	const coverIdx = files.findIndex((f) => COVER_RE.test(f));
 	if (coverIdx > 0) {

package/src/utils/image.ts

@@ -0,0 +1,90 @@
+/**
+ * 站点图片路径三格式解析（§4.97，对齐参考站 ImageWrapper 能力）：
+ * 1. `/` 开头 → 站点 public 静态资源，原样输出（不经构建管线优化）；
+ * 2. `http(s)://` / `//` / `data:` → 外链或内联，原样输出；
+ * 3. 其余相对路径（如 "assets/images/avatar.png"）→ 相对站点项目 src/ 目录
+ *    构建期解析，且经 sharp image service 重编码（默认 webp + 压缩，
+ *    §4.106 升级），返回优化产物 URL（唯一被优化的格式）。
+ *
+ * 解析机制：import.meta.glob 匹配站点根下 src 全目录的媒体扩展名，`/` 前缀
+ * 相对 Vite 项目根，主题包组件运行在站点构建管线中，因此命中站点项目的 src/
+ * （§4.108：不写死 assets/ 前缀，src 下任意目录的图片/视频均可解析；
+ * ⚠️ 本段注释不可出现 glob 的双星斜杠字面量——含块注释终止符子串会提前闭合）；
+ * 非 eager 按需 await，仅实际用到的媒体进入构建产物。
+ * svg（矢量）与 gif（动图）不做 sharp 编码——转码会破坏矢量/动画，原样输出。
+ * ico 不参与 glob（favicon 走 public / 远程，无优化需求）。
+ */
+
+import { getImage, type ImageMetadata } from "astro:assets";
+
+/** glob 命中的资源元数据：图片为 ImageMetadata，视频等为产物 URL 字符串 */
+type AssetMeta = ImageMetadata | string;
+
+/** 三格式判定：true = 相对 src/ 的本地媒体资源（需构建期解析） */
+export function isLocalImagePath(src: string): boolean {
+	if (!src) return false;
+	return !(
+		src.startsWith("/") ||
+		src.startsWith("http://") ||
+		src.startsWith("https://") ||
+		src.startsWith("//") ||
+		src.startsWith("data:")
+	);
+}
+
+/**
+ * 相对路径 → glob key：不写死 assets/ 前缀（§4.108），相对路径不加 `/` 即
+ * 相对站点 src/ 目录——"assets/images/avatar.png" → /src/assets/images/avatar.png，
+ * "styles/x.svg" → /src/styles/x.svg，src 下任意目录均可解析。
+ */
+export function toAssetKey(src: string): string {
+	return `/src/${src.replace(/^\.?\//, "")}`;
+}
+
+type AssetModules = Record<string, () => Promise<AssetMeta>>;
+
+/**
+ * 解析单张站点静态媒体（图片/视频）为可直接引用的 URL。
+ * public / 外链原样返回；相对路径查 glob 表，命中则 await 产物元数据；
+ * 未命中（文件不存在）时 console.warn 并原样返回，页面不断构建。
+ *
+ * §4.106：位图（png/jpg/webp/avif）额外经 getImage() 走 sharp image service
+ * 构建期重编码（默认转 webp + 质量压缩，Astro 同图同参有编码缓存）；
+ * svg/gif 保持原始产物 URL 不转码。失败时降级原样返回，页面不断构建。
+ * §4.108：视频（mp4/webm/mov）glob 导出为产物 URL 字符串，直接返回。
+ *
+ * 注意：import.meta.glob 第一参数必须是字符串字面量（vite 编译期静态分析，
+ * 变量/常量在 dev 下直接报 Invalid glob import syntax），模式不能提取为常量。
+ */
+export async function resolveSiteImage(src: string): Promise<string> {
+	if (!isLocalImagePath(src)) return src;
+	const modules = import.meta.glob(
+		"/src/**/*.{png,jpg,jpeg,webp,avif,gif,svg,mp4,webm,mov}",
+		{ import: "default" },
+	) as unknown as AssetModules;
+	const loader = modules[toAssetKey(src)];
+	if (!loader) {
+		console.warn(
+			`[orchid-theme] 媒体文件未找到: ${toAssetKey(src)}（相对路径不带 / 时相对站点 src/ 目录解析）`,
+		);
+		return src;
+	}
+	const meta = await loader();
+	if (typeof meta === "string") return meta;
+	if (meta.format === "svg" || meta.format === "gif") return meta.src;
+	try {
+		const encoded = await getImage({ src: meta });
+		return encoded.src;
+	} catch (err) {
+		console.warn(
+			`[orchid-theme] 图片优化失败，回退原图: ${toAssetKey(src)}`,
+			err,
+		);
+		return meta.src;
+	}
+}
+
+/** 数组批量解析（banner/壁纸多图、歌单封面等），顺序保持 */
+export async function resolveSiteImages(srcs: string[]): Promise<string[]> {
+	return Promise.all(srcs.map((src) => resolveSiteImage(src)));
+}

package/src/utils/lqip.ts

@@ -1,18 +1,27 @@
 /**
- * LQIP 占位渐变（M3b-b9，P1-14）：构建期从 virtual:theme/lqips 查表，
- * 返回内联渐变样式。查不到（外链 / data URL / 未生成 lqips.json）时
- * 返回纯色兜底，功能自然降级，无需配置开关。
+ * LQIP 占位渐变（M3b-b9，P1-14；§4.107 扩展外链）：
+ * 构建期从 virtual:theme/lqips 查表返回内联渐变样式。两类键——
+ * `public:<posix 路径>`（本地 public 图）与 `url:<完整外链 URL>`（§4.107 构建期
+ * 抓取采样的外链图）。查不到（未收录外链 / data URL / 未生成 lqips.json）时
+ * 兜底为主题色柔和渐变（color-mix 跟随明暗主题），不再是灰色纯色。
  */
 import lqips from "virtual:theme/lqips";
 
-/** 图片 public 路径（/assets/x.jpg）→ 18 字符 compact hex 三段渐变背景 */
+/** 18 字符 compact hex → 三段 135° 渐变背景样式 */
+function hexToStyle(hex: string): string {
+	return `background:linear-gradient(135deg, #${hex.slice(0, 6)} 0%, #${hex.slice(6, 12)} 50%, #${hex.slice(12, 18)} 100%)`;
+}
+
+/**
+ * 图片 src（本地 / 开头 public 路径，或完整外链 URL）→ LQIP 渐变背景。
+ * 键规则与 scripts/generate-lqips.mjs 一致：外链 URL 须与渲染期逐字符一致
+ * （randomCoverUrl / urls.txt / frontmatter image 或首图原样）。
+ */
 export function getLqipStyle(src: string): string {
-	const hex = lqips[`public:${src.replace(/^\//, "")}`];
-	if (hex && /^[0-9a-f]{18}$/i.test(hex)) {
-		const c1 = `#${hex.slice(0, 6)}`;
-		const c2 = `#${hex.slice(6, 12)}`;
-		const c3 = `#${hex.slice(12, 18)}`;
-		return `background:linear-gradient(135deg, ${c1} 0%, ${c2} 50%, ${c3} 100%)`;
-	}
-	return "background:var(--muted)";
+	const key = src.startsWith("/")
+		? `public:${src.replace(/^\//, "")}`
+		: `url:${src}`;
+	const hex = lqips[key];
+	if (hex && /^[0-9a-f]{18}$/i.test(hex)) return hexToStyle(hex);
+	return `background:linear-gradient(135deg, color-mix(in srgb, var(--accent) 20%, var(--surface)) 0%, color-mix(in srgb, var(--accent) 9%, var(--surface)) 100%)`;
 }

package/src/utils/thumb.ts

@@ -0,0 +1,31 @@
+/**
+ * 缩略图查表（§4.106）：构建期从 virtual:theme/thumbs 查表，把列表封面
+ * public 原图路径换成 generate-lqips.mjs 预生成的 480 宽 webp 缩略图 URL，
+ * 并携带原图宽高（灯箱打开原图时用，详见 app.ts itemData filter）。
+ * 查不到（外链 / data URL / 未生成 thumbs.json）时全部回退原图，自然降级。
+ */
+import thumbs from "virtual:theme/thumbs";
+
+export interface ThumbInfo {
+	/** 原图 URL（即传入 src，灯箱大图通道） */
+	full: string;
+	/** 列表展示 URL：命中缩略图时为 `<原图去 .thumb 前缀目录>/<名>.thumb.webp`，否则同 full */
+	src: string;
+	/** 原图宽高（未命中/无数据时缺省） */
+	width?: number;
+	height?: number;
+}
+
+/** public 路径 → 缩略图信息；非 public 路径或查表未命中时 src === full */
+export function getThumbInfo(src: string): ThumbInfo {
+	const hit = thumbs[`public:${src.replace(/^\//, "")}`];
+	if (hit?.thumb && hit.width > 0 && hit.height > 0) {
+		return {
+			full: src,
+			src: `/${hit.thumb}`,
+			width: hit.width,
+			height: hit.height,
+		};
+	}
+	return { full: src, src };
+}

package/src/vite.ts

@@ -68,17 +68,21 @@ export function themeConfigPlugin(config: ResolvedThemeConfig) {
 }
 
 /**
- * LQIP 虚拟模块（M3b-b9，P1-14）：读取站点根 lqips.json
- * （generate-lqips.mjs 产物，键 `public:<路径>` → 18 字符 compact hex），
- * 以 `virtual:theme/lqips` 暴露给构建期内联占位渐变（utils/lqip.ts）。
- * 文件缺失（未跑生成脚本）时导出空对象，消费端自然降级纯色，不阻塞构建。
+ * LQIP + 缩略图虚拟模块（M3b-b9，P1-14；§4.106 扩展双产物）：读取站点根
+ * lqips.json（键 `public:<路径>` → 18 字符 compact hex）与 thumbs.json
+ * （键 `public:<路径>` → { thumb, width, height }），分别以
+ * `virtual:theme/lqips`（utils/lqip.ts 构建期内联占位渐变）与
+ * `virtual:theme/thumbs`（utils/thumb.ts 列表封面换缩略图 URL）暴露。
+ * 文件缺失（未跑生成脚本）时导出空对象，消费端自然降级（纯色/原图），不阻塞构建。
  * 注意：本插件必须注册在 overridesPlugin 之前——后者的 resolveId 会兜住
  * 所有 virtual:theme/* 并返回一个不存在的文件路径。
  */
 export function themeLqipsPlugin() {
-	const virtualId = "virtual:theme/lqips";
-	const resolvedId = "\0" + virtualId;
+	type ThumbMeta = { thumb: string; width: number; height: number };
+	const lqipsId = "virtual:theme/lqips";
+	const thumbsId = "virtual:theme/thumbs";
 	let lqips: Record<string, string> = {};
+	let thumbs: Record<string, ThumbMeta> = {};
 	return {
 		name: "@windcoder/astro-theme-orchid:lqips",
 		enforce: "pre" as const,
@@ -94,12 +98,95 @@ export function themeLqipsPlugin() {
 			} catch {
 				lqips = {};
 			}
+			try {
+				thumbs = JSON.parse(
+					fs.readFileSync(path.join(rootDir, "thumbs.json"), "utf8"),
+				);
+			} catch {
+				thumbs = {};
+			}
 		},
 		resolveId(id: string) {
-			return id === virtualId ? resolvedId : null;
+			if (id === lqipsId) return "\0" + lqipsId;
+			if (id === thumbsId) return "\0" + thumbsId;
+			return null;
 		},
 		load(id: string) {
-			if (id === resolvedId) return `export default ${JSON.stringify(lqips)};`;
+			if (id === "\0" + lqipsId)
+				return `export default ${JSON.stringify(lqips)};`;
+			if (id === "\0" + thumbsId)
+				return `export default ${JSON.stringify(thumbs)};`;
+			return undefined;
+		},
+	};
+}
+
+/**
+ * Pagefind dev 中间件（§4.104）：dev 下为搜索提供构建期索引。
+ * Vite 禁止以模块 import 引用 public 内的 JS（"should not be imported
+ * from source code"），把索引同步进 public 行不通；故与社区标准方案
+ * astro-pagefind 同款——前置中间件把构建产物 dist/pagefind 直接静态服务。
+ * dist/pagefind 不存在（未跑过 build）时放行，app.ts 的 loadPagefind
+ * 捕获失败后降级为「索引不可用」提示。仅 dev 生效（configureServer 只在
+ * dev server 调用）；build/preview 的索引由 pagefind --site dist 原地产出。
+ */
+const PAGEFIND_MIME: Record<string, string> = {
+	".js": "text/javascript",
+	".mjs": "text/javascript",
+	".css": "text/css",
+	".json": "application/json",
+	".wasm": "application/wasm",
+};
+
+export function pagefindDevPlugin() {
+	let distPagefind = "";
+	return {
+		name: "@windcoder/astro-theme-orchid:pagefind-dev",
+		enforce: "pre" as const,
+		configResolved(resolvedConfig: {
+			root: URL | string;
+			build: { outDir: string };
+		}) {
+			const rootDir =
+				typeof resolvedConfig.root === "string"
+					? resolvedConfig.root
+					: fileURLToPath(resolvedConfig.root);
+			distPagefind = path.resolve(
+				rootDir,
+				resolvedConfig.build.outDir,
+				"pagefind",
+			);
+		},
+		configureServer(server: {
+			middlewares: {
+				use: (
+					fn: (
+						req: { url?: string },
+						res: {
+							setHeader: (name: string, value: string) => void;
+							end: (data: Buffer) => void;
+						},
+						next: () => void,
+					) => void,
+				) => void;
+			};
+		}) {
+			server.middlewares.use((req, res, next) => {
+				const url = (req.url || "").split("?")[0];
+				if (!url.startsWith("/pagefind/")) return next();
+				// 剥掉 "/pagefind/" 前缀后再拼接，避免 pagefind 二次重复；
+				// resolve + 前缀校验防目录穿越；读不到（未 build）时放行走 404
+				const file = path.resolve(distPagefind, url.slice("/pagefind/".length));
+				if (!file.startsWith(distPagefind + path.sep)) return next();
+				fs.readFile(file, (err, buf) => {
+					if (err) return next();
+					res.setHeader(
+						"Content-Type",
+						PAGEFIND_MIME[path.extname(file)] ?? "application/octet-stream",
+					);
+					res.end(buf);
+				});
+			});
 		},
 	};
 }