@windcoder/astro-theme-orchid 0.3.0 → 0.4.1

package/src/components/MusicWidget.astro

@@ -0,0 +1,265 @@
+---
+/**
+ * 侧栏音乐 widget（§4.100）：与 MusicPlayer（悬浮播放器）共用 config.music 歌单，
+ * 经 CustomEvent 联动——本组件点击发 orchid:music-cmd，播放器广播 orchid:music-state。
+ * 播放内核仍在 MusicPlayer（transition:persist 跨页常驻），本组件纯遥控 + 状态展示。
+ * 首载时序：播放器于 DOMContentLoaded 初始化，本组件在 astro:page-load 初始化
+ * （晚于播放器），初始化后发 sync 补拉当前状态。
+ */
+import config from "virtual:theme/config";
+import { t } from "../i18n/index.js";
+import { resolveSiteImage } from "../utils/image.js";
+
+interface Props {
+	/** 移动端（<768px）隐藏（widgets 数组项 hideOnMobile） */
+	hideMobile?: boolean;
+}
+
+const { hideMobile = false } = Astro.props;
+
+// 封面三格式解析（§4.97）：构建期解析整份歌单，data-playlist 与 SSR 首曲共用
+const playlist = await Promise.all(
+	config.music.playlist.map(
+		async (tr: { name: string; artist: string; cover?: string }) => ({
+			name: tr.name,
+			artist: tr.artist,
+			cover: tr.cover ? await resolveSiteImage(tr.cover) : "",
+		}),
+	),
+);
+
+const labels = {
+	play: t("musicPlay"),
+	pause: t("musicPause"),
+	prev: t("musicPrev"),
+	next: t("musicNext"),
+};
+---
+
+<section
+	class:list={["side-card", "card", "reveal", "music-widget", { "side-hide-m": hideMobile }]}
+	id="orchid-music-widget"
+	data-playlist={JSON.stringify(playlist)}
+	data-labels={JSON.stringify(labels)}
+>
+	<h3>{t("musicWidget")}</h3>
+	<div class="mw-body">
+		<div class="mw-cover">
+			{playlist[0]?.cover ? (
+				<img class="mw-cover-img" src={playlist[0].cover} alt="" loading="lazy" />
+			) : (
+				<svg class="mw-cover-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
+			)}
+		</div>
+		<div class="mw-meta">
+			<span class="mw-name">{playlist[0]?.name ?? ""}</span>
+			<span class="mw-artist">{playlist[0]?.artist ?? ""}</span>
+		</div>
+		<div class="mw-controls">
+			<button class="mw-btn mw-prev" type="button" aria-label={labels.prev} title={labels.prev}>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 8 12l10 6V6Z" fill="currentColor" stroke="none"/><path d="M6 5v14"/></svg>
+			</button>
+			<button class="mw-btn mw-play" type="button" aria-label={labels.play} title={labels.play}>
+				<svg class="ic-play" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M8 5.5v13l11-6.5-11-6.5Z"/></svg>
+				<svg class="ic-pause" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><rect x="6.5" y="5" width="3.5" height="14" rx="1"/><rect x="14" y="5" width="3.5" height="14" rx="1"/></svg>
+			</button>
+			<button class="mw-btn mw-next" type="button" aria-label={labels.next} title={labels.next}>
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 6 10 6L6 18V6Z" fill="currentColor" stroke="none"/><path d="M18 5v14"/></svg>
+			</button>
+		</div>
+	</div>
+</section>
+
+<style>
+	.mw-body {
+		display: flex;
+		align-items: center;
+		gap: 12px;
+	}
+	.mw-cover {
+		width: 52px;
+		height: 52px;
+		flex: none;
+		border-radius: 50%;
+		overflow: hidden;
+		display: grid;
+		place-items: center;
+		background: color-mix(in srgb, var(--accent) 12%, transparent);
+		color: var(--accent);
+	}
+	.mw-cover img {
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+	}
+	.mw-cover svg {
+		width: 22px;
+		height: 22px;
+	}
+	.music-widget.playing .mw-cover img {
+		animation: mw-spin 12s linear infinite;
+	}
+	@keyframes mw-spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+	.mw-meta {
+		flex: 1;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 2px;
+	}
+	.mw-name {
+		font-size: 14px;
+		font-weight: 600;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+	.mw-artist {
+		font-size: 12px;
+		color: var(--muted);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+	.mw-controls {
+		display: flex;
+		align-items: center;
+		gap: 2px;
+		flex: none;
+	}
+	.mw-btn {
+		display: grid;
+		place-items: center;
+		width: 28px;
+		height: 28px;
+		padding: 0;
+		border: none;
+		border-radius: 50%;
+		background: transparent;
+		color: inherit;
+		cursor: pointer;
+	}
+	.mw-btn:hover {
+		background: color-mix(in srgb, var(--accent) 12%, transparent);
+		color: var(--accent);
+	}
+	.mw-btn svg {
+		width: 16px;
+		height: 16px;
+	}
+	.mw-play svg {
+		width: 18px;
+		height: 18px;
+	}
+	/* 播放/暂停图标切换：playing class 由客户端 applyState 维护 */
+	.mw-play .ic-pause {
+		display: none;
+	}
+	.music-widget.playing .mw-play .ic-play {
+		display: none;
+	}
+	.music-widget.playing .mw-play .ic-pause {
+		display: block;
+	}
+</style>
+
+<script>
+	// 模块级单例：状态缓存跨 VT 换页保留；document 级 state 监听只绑一次
+	// （widget DOM 随页面重建，每次 page-load 重查 DOM 重绑按钮），避免监听器累积
+	type MusicState = { idx: number; playing: boolean };
+	let state: MusicState = { idx: 0, playing: false };
+	let docBound = false;
+
+	function sendCmd(detail: Record<string, unknown>) {
+		document.dispatchEvent(new CustomEvent("orchid:music-cmd", { detail }));
+	}
+
+	// 把当前状态应用到本页 widget DOM（换页后由 init 重新调用）
+	function applyState() {
+		const root = document.getElementById("orchid-music-widget");
+		if (!root) return;
+		let playlist: { name: string; artist: string; cover: string }[] = [];
+		try {
+			playlist = JSON.parse(root.dataset.playlist || "[]");
+		} catch {
+			/* 歌单数据异常时保留 SSR 首曲内容 */
+		}
+		const tr = playlist[state.idx];
+		if (tr) {
+			const nameEl = root.querySelector(".mw-name");
+			const artistEl = root.querySelector(".mw-artist");
+			if (nameEl) nameEl.textContent = tr.name;
+			if (artistEl) artistEl.textContent = tr.artist;
+			let coverImg = root.querySelector<HTMLImageElement>(".mw-cover-img");
+			const coverSvg = root.querySelector(".mw-cover-svg");
+			// SSR 只渲染了首曲封面：当前曲有封面而 DOM 里是图标时动态补 img
+			if (tr.cover && !coverImg && coverSvg) {
+				const img = document.createElement("img");
+				img.className = "mw-cover-img";
+				img.alt = "";
+				coverSvg.replaceWith(img);
+				coverImg = img;
+			}
+			if (coverImg instanceof HTMLImageElement) {
+				if (tr.cover) coverImg.src = tr.cover;
+				coverImg.toggleAttribute("hidden", !tr.cover);
+			}
+			coverSvg?.toggleAttribute("hidden", !!tr.cover);
+		}
+		root.classList.toggle("playing", state.playing);
+		let labels: Record<string, string> = {};
+		try {
+			labels = JSON.parse(root.dataset.labels || "{}");
+		} catch {
+			/* labels 异常时沿用 SSR aria */
+		}
+		const playBtn = root.querySelector<HTMLElement>(".mw-play");
+		if (playBtn) {
+			const label = state.playing ? labels.pause : labels.play;
+			if (label) {
+				playBtn.setAttribute("aria-label", label);
+				playBtn.title = label;
+			}
+		}
+	}
+
+	function initMusicWidget() {
+		const root = document.getElementById("orchid-music-widget");
+		if (!root) return;
+
+		// document 级监听仅绑一次；按钮随 DOM 重建每次绑定
+		if (!docBound) {
+			docBound = true;
+			document.addEventListener("orchid:music-state", (e) => {
+				state = (e as CustomEvent<MusicState>).detail;
+				applyState();
+			});
+		}
+
+		root
+			.querySelector(".mw-play")
+			?.addEventListener("click", () => sendCmd({ type: "toggle" }));
+		root
+			.querySelector(".mw-next")
+			?.addEventListener("click", () => sendCmd({ type: "next" }));
+		root
+			.querySelector(".mw-prev")
+			?.addEventListener("click", () => sendCmd({ type: "prev" }));
+		// 点封面/曲名区 = 播放当前 widget 正显示的曲目
+		root.querySelector(".mw-body")?.addEventListener("click", (e) => {
+			if ((e.target as HTMLElement).closest(".mw-btn")) return;
+			sendCmd({ type: "playIndex", index: state.idx });
+		});
+
+		// 先应用缓存状态再向播放器补拉（播放器 DOM persist 常驻，先于本组件就绪）
+		applyState();
+		sendCmd({ type: "sync" });
+	}
+
+	// ClientRouter 下 astro:page-load 首载与每次导航都会触发
+	document.addEventListener("astro:page-load", initMusicWidget);
+</script>

package/src/components/PhotoCard.astro

@@ -6,6 +6,7 @@
  * showDecrypted → initLightbox 重预置生效）。
  */
 import { getLqipStyle } from "../utils/lqip.js";
+import { getThumbInfo } from "../utils/thumb.js";
 
 interface Props {
 	src: string;
@@ -13,10 +14,21 @@ interface Props {
 }
 
 const { src, alt = "" } = Astro.props;
+/* §4.106：列表瀑布流用 480 宽缩略图，data-full-* 供灯箱打开原图（原图宽高） */
+const thumb = getThumbInfo(src);
 ---
 
 <figure class="gallery-photo" data-lightbox-item>
   {/* LQIP 占位渐变（b9.5）：src 支持外链，getLqipStyle 查不到时降级纯色 */}
   <div class="qy-lqip" style={getLqipStyle(src)} aria-hidden="true"></div>
-  <img src={src} alt={alt} loading="lazy" decoding="async" data-lqip />
+  <img
+    src={thumb.src}
+    alt={alt}
+    loading="lazy"
+    decoding="async"
+    data-lqip
+    data-full-src={thumb.full}
+    data-full-width={thumb.width}
+    data-full-height={thumb.height}
+  />
 </figure>

package/src/components/PostCard.astro

@@ -1,7 +1,9 @@
 ---
 import config from "virtual:theme/config";
 import { t } from "../i18n/index.js";
+import { resolveSiteImage } from "../utils/image.js";
 import { getLqipStyle } from "../utils/lqip.js";
+import { getThumbInfo } from "../utils/thumb.js";
 import { formatDate, type PostLike, resolveCover } from "../utils.js";
 
 interface Props {
@@ -24,7 +26,12 @@ const { cover: rawCover, retries } = resolveCover(
 	config.postList.randomCover.apis,
 	post.id,
 );
-const cover = config.postList.showCover ? rawCover : null;
+/* §4.110：封面三格式统一语义（对齐 §4.108 其余消费点）——相对路径（站点 src/
+   下）构建期解析为产物 URL，public / 外链原样直通 */
+const resolvedCover = rawCover ? await resolveSiteImage(rawCover) : rawCover;
+const cover = config.postList.showCover ? resolvedCover : null;
+/* §4.106：列表封面用缩略图（外链/未命中自动回退原图；点击进文章页看正文原图） */
+const thumb = cover ? getThumbInfo(cover) : null;
 const classes = [
 	"post-card",
 	featured ? "featured" : "",
@@ -47,7 +54,7 @@ const excerpt = d.excerpt || d.description;
         {/* LQIP 占位渐变（b9.5）：绝对定位盖在 img 上，加载完成后由 app.ts 淡出 */}
         <div class="qy-lqip" style={getLqipStyle(cover)} aria-hidden="true"></div>
         <img
-          src={cover}
+          src={thumb ? thumb.src : cover}
           alt={d.title}
           loading="lazy"
           data-lqip

package/src/components/SakuraEffect.astro

@@ -1,19 +1,39 @@
 ---
 /**
- * 樱花飘落特效（§4.30）：全站 canvas 粒子层，程序化贝塞尔花瓣（零贴图资产）。
+ * 樱花飘落特效（§4.30 / §4.101 八维参数对齐 Firefly）：全站 canvas 粒子层，
+ * 程序化贝塞尔花瓣（零贴图资产）。
  * - prefers-reduced-motion 自动停用
  * - 页签隐藏暂停、可见时恢复
+ * - limitTimes 控制飘落轮数（-1 无限）；配额耗尽后不再重生，花瓣落尽即停帧
  * - VT swap 后 body 重建，经 astro:page-load 重新初始化（模块级单例清理旧动画）
  */
 interface Props {
-	/** 同屏花瓣数（schema sakura.density） */
-	density?: number;
+	/** 完整 sakura 配置（schema 已补全默认值），经 data-cfg JSON 传给客户端 */
+	cfg?: {
+		enabled?: boolean;
+		density: number;
+		limitTimes: number;
+		zIndex: number;
+		size: { min: number; max: number };
+		opacity: { min: number; max: number };
+		speed: {
+			horizontal: { min: number; max: number };
+			vertical: { min: number; max: number };
+			rotation: number;
+			fadeSpeed: number;
+		};
+	};
 }
 
-const { density = 24 } = Astro.props;
+const cfg = Astro.props.cfg;
 ---
 
-<canvas id="sakura-canvas" data-density={density} aria-hidden="true"></canvas>
+<canvas
+	id="sakura-canvas"
+	data-cfg={JSON.stringify(cfg)}
+	style={`z-index:${cfg?.zIndex ?? 100}`}
+	aria-hidden="true"
+></canvas>
 
 <style>
 	#sakura-canvas {
@@ -22,7 +42,6 @@ const { density = 24 } = Astro.props;
 		width: 100%;
 		height: 100%;
 		pointer-events: none;
-		z-index: 90;
 	}
 </style>
 
@@ -39,11 +58,41 @@ const { density = 24 } = Astro.props;
 		) as HTMLCanvasElement | null;
 		if (!canvas) return;
 		if (matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+		/* §4.103：显示设置面板关闭樱花（html[data-wp-sakura="off"]）时不启动 */
+		if (document.documentElement.dataset.wpSakura === "off") return;
 
 		const ctx = canvas.getContext("2d");
 		if (!ctx) return;
 
-		const count = Number(canvas.dataset.density) || 24;
+		// 八维参数（§4.101）：缺省回退与 schema 默认一致（防 data-cfg 解析失败）
+		let cfg: {
+			density?: number;
+			limitTimes?: number;
+			size?: { min: number; max: number };
+			opacity?: { min: number; max: number };
+			speed?: {
+				horizontal: { min: number; max: number };
+				vertical: { min: number; max: number };
+				rotation: number;
+				fadeSpeed: number;
+			};
+		};
+		try {
+			cfg = JSON.parse(canvas.dataset.cfg || "{}");
+		} catch {
+			cfg = {};
+		}
+		const count = Math.max(1, Number(cfg.density) || 24);
+		const sizeR = cfg.size ?? { min: 0.5, max: 1.1 };
+		const opaR = cfg.opacity ?? { min: 0.3, max: 0.9 };
+		const spd = cfg.speed ?? {
+			horizontal: { min: -1.7, max: -1.2 },
+			vertical: { min: 1.5, max: 2.2 },
+			rotation: 0.03,
+			fadeSpeed: 0.03,
+		};
+		const rand = (min: number, max: number) => min + Math.random() * (max - min);
+
 		const dpr = Math.min(window.devicePixelRatio || 1, 2);
 
 		let w = 0;
@@ -60,19 +109,24 @@ const { density = 24 } = Astro.props;
 
 		// 3 档粉调色板（对齐参考站观感）
 		const colors = ["#ffd7e2", "#ffc0d0", "#fdaec5"];
+		// 花瓣基准尺寸（px）：size 配置为其倍数区间
+		const BASE_SIZE = 14;
 
 		interface Petal {
 			x: number;
 			y: number;
 			size: number;
-			speedY: number;
-			swayAmp: number;
-			swayFreq: number;
-			phase: number;
+			/** 水平漂移速度（负值向左，§4.101 speed.horizontal） */
+			vx: number;
+			/** 下落速度（§4.101 speed.vertical） */
+			vy: number;
 			rot: number;
-			rotSpeed: number;
 			color: string;
-			opacity: number;
+			alpha: number;
+			/** 生命帧数：超过后进入临终淡出（fadeSpeed），alpha 耗尽即重生 */
+			life: number;
+			age: number;
+			dead: boolean;
 		}
 
 		const spawn = (randomY = false): Petal => {
@@ -80,18 +134,25 @@ const { density = 24 } = Astro.props;
 			return {
 				x: Math.random() * w,
 				y: randomY ? Math.random() * h : -20,
-				size: 6 + Math.random() * 8,
-				speedY: 0.6 + Math.random() * 1.2,
-				swayAmp: 20 + Math.random() * 40,
-				swayFreq: 0.005 + Math.random() * 0.01,
-				phase: Math.random() * Math.PI * 2,
+				size: BASE_SIZE * rand(sizeR.min, sizeR.max),
+				vx: rand(spd.horizontal.min, spd.horizontal.max),
+				vy: rand(spd.vertical.min, spd.vertical.max),
 				rot: Math.random() * Math.PI * 2,
-				rotSpeed: (Math.random() - 0.5) * 0.03,
 				color: colors[i] ?? colors[0]!,
-				opacity: 0.5 + Math.random() * 0.4,
+				alpha: rand(opaR.min, opaR.max),
+				life: 480 + Math.random() * 720,
+				age: 0,
+				dead: false,
 			};
 		};
 
+		// limitTimes 飘落轮数（§4.101）：-1 无限；>=1 时总重生配额 = 轮数 × 花瓣数，
+		// 耗尽后不再重生，花瓣落尽即停止动画
+		let quota =
+			cfg.limitTimes === undefined || cfg.limitTimes < 0
+				? Number.POSITIVE_INFINITY
+				: cfg.limitTimes * count;
+
 		const petals: Petal[] = Array.from({ length: count }, () => spawn(true));
 
 		// 程序化花瓣：两段贝塞尔拼出泪滴形
@@ -100,7 +161,7 @@ const { density = 24 } = Astro.props;
 			ctx.save();
 			ctx.translate(p.x, p.y);
 			ctx.rotate(p.rot);
-			ctx.globalAlpha = p.opacity;
+			ctx.globalAlpha = p.alpha;
 			ctx.fillStyle = p.color;
 			ctx.beginPath();
 			ctx.moveTo(0, -s);
@@ -110,19 +171,40 @@ const { density = 24 } = Astro.props;
 			ctx.restore();
 		};
 
+		// 重生：消耗配额；配额耗尽标记 dead（不再绘制）
+		const respawn = (p: Petal) => {
+			if (quota > 0) {
+				quota--;
+				Object.assign(p, spawn());
+			} else {
+				p.dead = true;
+			}
+		};
+
 		let paused = false;
-		let frame = 0;
 		const tick = () => {
 			if (paused) return;
-			frame++;
 			ctx.clearRect(0, 0, w, h);
+			let alive = 0;
 			for (const p of petals) {
-				p.y += p.speedY;
-				p.x += Math.sin(frame * p.swayFreq + p.phase) * (p.swayAmp / 60);
-				p.rot += p.rotSpeed;
-				if (p.y > h + 30) Object.assign(p, spawn());
-				drawPetal(p);
+				if (p.dead) continue;
+				alive++;
+				p.age++;
+				// 临终淡出（fadeSpeed）：寿命耗尽后 alpha 递减至 0 重生
+				if (p.age > p.life) {
+					p.alpha -= spd.fadeSpeed;
+					if (p.alpha <= 0) {
+						respawn(p);
+						continue;
+					}
+				}
+				p.y += p.vy;
+				p.x += p.vx;
+				p.rot += spd.rotation;
+				if (p.y > h + 30 || p.x < -40 || p.x > w + 40) respawn(p);
+				else drawPetal(p);
 			}
+			if (alive === 0) return; // 配额耗尽且花瓣落尽：停止循环
 			raf = requestAnimationFrame(tick);
 		};
 
@@ -140,6 +222,7 @@ const { density = 24 } = Astro.props;
 		raf = requestAnimationFrame(tick);
 
 		cleanup = () => {
+			paused = true;
 			cancelAnimationFrame(raf);
 			window.removeEventListener("resize", resize);
 			document.removeEventListener("visibilitychange", onVisibility);
@@ -149,4 +232,19 @@ const { density = 24 } = Astro.props;
 
 	// ClientRouter 下 astro:page-load 首载与每次导航都会触发
 	document.addEventListener("astro:page-load", startSakura);
+
+	/* §4.103：显示设置面板樱花开关（app.ts applyDsSwitch 派发）；
+	   off 立即停动画并清画布，on 重启（startSakura 内部先清理旧实例） */
+	document.addEventListener("orchid:sakura-toggle", (e) => {
+		const on = (e as CustomEvent).detail !== "off";
+		if (on) {
+			startSakura();
+		} else {
+			cleanup?.();
+			const canvas = document.getElementById(
+				"sakura-canvas",
+			) as HTMLCanvasElement | null;
+			canvas?.getContext("2d")?.clearRect(0, 0, canvas.width, canvas.height);
+		}
+	});
 </script>