@windcoder/astro-theme-orchid 0.3.0 → 0.4.0

package/src/scripts/app.ts

@@ -104,16 +104,15 @@ function applySavedHue() {
 applySavedHue();
 doc.addEventListener("astro:after-swap", applySavedHue);
 
-/* 同步面板 UI：滑杆 / 徽章 / swatch 激活态（差值 <1° 判定，含 0/360 环绕） */
+/* 同步面板 UI：滑杆 / 徽章 / swatch 激活态（差值 <1° 判定，含 0/360 环绕）。
+   swatch 可能在旧 palette-pop 或显示设置面板（§4.103 外观 Tab）内，全局查询 */
 function syncPaletteUI(h: number) {
-	const pop = doc.getElementById("palettePop");
-	if (!pop) return;
 	const rounded = Math.round(((h % 360) + 360) % 360) % 360;
 	const slider = doc.getElementById("hueSlider") as HTMLInputElement | null;
 	if (slider) slider.value = String(rounded);
 	const badge = doc.getElementById("hueBadge");
 	if (badge) badge.textContent = String(rounded);
-	pop.querySelectorAll<HTMLElement>(".swatch").forEach((sw) => {
+	doc.querySelectorAll<HTMLElement>(".swatch[data-hue]").forEach((sw) => {
 		const dh = Math.abs(parseFloat(sw.dataset.hue || "0") - rounded);
 		sw.classList.toggle("is-active", dh < 1 || dh > 359);
 	});
@@ -133,11 +132,11 @@ function closePalette() {
 	if (toggle) toggle.setAttribute("aria-expanded", "false");
 }
 
-/* 每次导航后同步面板状态并复位收起（面板 DOM 会随 swap 重建） */
+/* 每次导航后同步面板状态并复位收起（面板 DOM 会随 swap 重建）；
+   显示设置面板形态（§4.103）无 palettePop，仍需同步 hue 控件 */
 function initPalette() {
 	const pop = doc.getElementById("palettePop");
-	if (!pop) return;
-	closePalette();
+	if (pop) closePalette();
 	syncPaletteUI(currentHue());
 }
 
@@ -193,7 +192,15 @@ async function initLightbox() {
 		const img = el instanceof HTMLImageElement ? el : el?.querySelector("img");
 		if (!img) return itemData;
 		if (!itemData.src) itemData.src = img.currentSrc || img.src;
-		if (img.naturalWidth > 0) {
+		/* §4.106：列表 img 可能是缩略图（data-full-* 携带原图 URL 与尺寸）——
+		   优先打开原图；无数据时沿用 img 自身 src 与 natural 尺寸 */
+		if (img.dataset.fullSrc) {
+			itemData.src = img.dataset.fullSrc;
+			if (Number(img.dataset.fullWidth) > 0 && Number(img.dataset.fullHeight) > 0) {
+				itemData.width = Number(img.dataset.fullWidth);
+				itemData.height = Number(img.dataset.fullHeight);
+			}
+		} else if (img.naturalWidth > 0) {
 			itemData.width = img.naturalWidth;
 			itemData.height = img.naturalHeight;
 		}
@@ -484,12 +491,15 @@ window.addEventListener(
 	() => {
 		updateBackTop();
 		updateReadProgress();
+		updateWallpaperScroll();
 	},
 	{ passive: true },
 );
 window.addEventListener("resize", updateReadProgress, { passive: true });
 
-/* ---------- 搜索浮层（M3b-b6）：Pagefind 构建期索引，运行时惰性加载 ---------- */
+/* ---------- 搜索（M3b-b6 → §4.104）：Pagefind 构建期索引，标准动态 import 接入。
+   导航浮层：输入即搜，最多 8 条，超出时尾部「查看全部」链接进独立搜索页；
+   独立搜索页（/search/）：URL ?q= 关键词 + ?page= 页码，客户端分页渲染 ---------- */
 type PagefindResultData = {
 	url: string;
 	excerpt: string;
@@ -504,15 +514,14 @@ type Pagefind = {
 
 /* undefined=未加载 null=不可用（dev 无索引/加载失败）；模块级缓存，VT 换页不重复加载 */
 let pagefind: Pagefind | null | undefined;
-let searchSeq = 0;
 
 async function loadPagefind(): Promise<Pagefind | null> {
 	if (pagefind !== undefined) return pagefind;
 	try {
 		const src = "/pagefind/pagefind.js";
-		const res = await fetch(src, { method: "HEAD" });
-		if (!res.ok) throw new Error("no index");
-		// 变量形式 + @vite-ignore：构建产物不存在时（dev/无索引）不做静态解析，运行时才加载
+		// 标准 Pagefind 接入（官方推荐）：运行时直接动态 import 构建期索引入口。
+		// 变量形式 + @vite-ignore：索引是 build 后才存在的产物，构建期不做静态解析，
+		// dev 无索引时 import 失败走 catch 降级提示
 		const pf = (await import(/* @vite-ignore */ src)) as unknown as Pagefind;
 		if (pf.options) await pf.options({ excerptLength: 20 });
 		pagefind = pf;
@@ -522,6 +531,25 @@ async function loadPagefind(): Promise<Pagefind | null> {
 	return pagefind;
 }
 
+/* 浮层最多展示 8 条（§4.56 视口内条数），超出引导进独立搜索页（§4.104） */
+const SEARCH_POP_MAX = 8;
+
+/* 结果项（浮层与搜索页共用）：标题 + pagefind 受限高亮摘要 */
+function searchItemEl(item: PagefindResultData): HTMLAnchorElement {
+	const a = doc.createElement("a");
+	a.className = "search-item";
+	a.href = item.url;
+	const title = doc.createElement("div");
+	title.className = "search-item-title";
+	title.textContent = item.meta?.title || item.url;
+	const excerpt = doc.createElement("div");
+	excerpt.className = "search-item-excerpt";
+	/* pagefind 产出的受限高亮片段（<mark>/<strong>），非用户输入 */
+	excerpt.innerHTML = item.excerpt;
+	a.append(title, excerpt);
+	return a;
+}
+
 function setSearchHint(text: string) {
 	const box = doc.getElementById("searchResults");
 	if (!box) return;
@@ -533,23 +561,24 @@ function setSearchHint(text: string) {
 	box.hidden = false;
 }
 
-function renderSearchResults(items: PagefindResultData[]) {
+/* 请求序号：只接受最后一次输入的响应，防乱序覆盖 */
+let searchSeq = 0;
+
+function renderSearchResults(
+	items: PagefindResultData[],
+	more?: { keyword: string; total: number },
+) {
 	const box = doc.getElementById("searchResults");
 	if (!box) return;
 	box.replaceChildren();
-	for (const item of items) {
-		const a = doc.createElement("a");
-		a.className = "search-item";
-		a.href = item.url;
-		const title = doc.createElement("div");
-		title.className = "search-item-title";
-		title.textContent = item.meta?.title || item.url;
-		const excerpt = doc.createElement("div");
-		excerpt.className = "search-item-excerpt";
-		/* pagefind 产出的受限高亮片段（<mark>/<strong>），非用户输入 */
-		excerpt.innerHTML = item.excerpt;
-		a.append(title, excerpt);
-		box.appendChild(a);
+	for (const item of items) box.appendChild(searchItemEl(item));
+	if (more) {
+		/* §4.104 超出浮层上限：尾部「查看全部 N 条结果」链接进独立搜索页 */
+		const link = doc.createElement("a");
+		link.className = "search-more";
+		link.href = "/search/?q=" + encodeURIComponent(more.keyword);
+		link.textContent = ui("searchMore").replace("{n}", String(more.total));
+		box.appendChild(link);
 	}
 	box.hidden = false;
 }
@@ -611,18 +640,168 @@ function runSearch(keyword: string) {
 		}
 		try {
 			const res = await pf.search(keyword);
+			/* res.results.length 即命中总数（惰性 API）；浮层只取前 SEARCH_POP_MAX 条加载详情 */
+			const total = res.results.length;
 			const items = await Promise.all(
-				res.results.slice(0, 8).map((r) => r.data()),
+				res.results.slice(0, SEARCH_POP_MAX).map((r) => r.data()),
 			);
 			if (seq !== searchSeq) return;
-			if (items.length) renderSearchResults(items);
-			else setSearchHint(ui("searchNoResults"));
+			if (total > SEARCH_POP_MAX) {
+				renderSearchResults(items, { keyword, total });
+			} else if (items.length) {
+				renderSearchResults(items);
+			} else {
+				setSearchHint(ui("searchNoResults"));
+			}
 		} catch {
 			if (seq === searchSeq) setSearchHint(ui("searchNoResults"));
 		}
 	}, 300);
 }
 
+/* ---------- 独立搜索页（§4.104，/search/）：URL ?q= 关键词 + ?page= 页码。
+   静态外壳 + 客户端查询分页；输入即时刷新（replaceState 不经换页），
+   翻页走真实链接经 VT 换页后由 astro:page-load 重新渲染 ---------- */
+const SEARCH_PAGE_SIZE = 10;
+let searchPageSeq = 0;
+let searchPageTimer = 0;
+
+/* 页码窗口：恒含首末页与当前页±2，间隙以省略号占位（与 Pagination.astro 同规则） */
+function pagerNums(page: number, total: number): Array<number | "ellipsis"> {
+	const set = new Set<number>([1, total]);
+	for (let p = page - 2; p <= page + 2; p++) {
+		if (p >= 1 && p <= total) set.add(p);
+	}
+	const nums = [...set].sort((a, b) => a - b);
+	const out: Array<number | "ellipsis"> = [];
+	let prev = 0;
+	for (const n of nums) {
+		if (prev && n - prev > 1) out.push("ellipsis");
+		out.push(n);
+		prev = n;
+	}
+	return out;
+}
+
+function searchPageHref(q: string, page: number): string {
+	return (
+		"/search/?q=" +
+		encodeURIComponent(q) +
+		(page > 1 ? "&page=" + page : "")
+	);
+}
+
+function renderSearchPager(pager: HTMLElement, q: string, cur: number, pages: number) {
+	if (pages <= 1) {
+		pager.hidden = true;
+		return;
+	}
+	pager.hidden = false;
+	const nums = doc.createElement("div");
+	nums.className = "pg-nums";
+	const mk = (href: string, label: string, cls: string) => {
+		const a = doc.createElement("a");
+		a.className = cls;
+		a.href = href;
+		a.textContent = label;
+		return a;
+	};
+	const span = (label: string) => {
+		const s = doc.createElement("span");
+		s.className = "page-item disabled";
+		s.textContent = label;
+		return s;
+	};
+	if (cur > 1) nums.appendChild(mk(searchPageHref(q, cur - 1), "‹", "page-item"));
+	else nums.appendChild(span("‹"));
+	for (const n of pagerNums(cur, pages)) {
+		if (n === "ellipsis") {
+			const gap = doc.createElement("span");
+			gap.className = "pg-gap";
+			gap.textContent = "…";
+			nums.appendChild(gap);
+		} else if (n === cur) {
+			const s = doc.createElement("span");
+			s.className = "page-item current";
+			s.setAttribute("aria-current", "page");
+			s.textContent = String(n);
+			nums.appendChild(s);
+		} else {
+			nums.appendChild(mk(searchPageHref(q, n), String(n), "page-item"));
+		}
+	}
+	if (cur < pages) nums.appendChild(mk(searchPageHref(q, cur + 1), "›", "page-item"));
+	else nums.appendChild(span("›"));
+
+	const adj = doc.createElement("div");
+	adj.className = "pg-adj";
+	if (cur > 1) adj.appendChild(mk(searchPageHref(q, cur - 1), ui("prevPage"), "pg-prev"));
+	else adj.appendChild(span(ui("prevPage")));
+	const mid = doc.createElement("span");
+	mid.textContent = ui("pageOf")
+		.replace("{current}", String(cur))
+		.replace("{total}", String(pages));
+	adj.appendChild(mid);
+	if (cur < pages) adj.appendChild(mk(searchPageHref(q, cur + 1), ui("nextPage"), "pg-next"));
+	else adj.appendChild(span(ui("nextPage")));
+
+	pager.replaceChildren(nums, adj);
+}
+
+async function renderSearchPage() {
+	const seq = ++searchPageSeq;
+	const input = doc.getElementById("searchPageInput") as HTMLInputElement | null;
+	const meta = doc.getElementById("searchPageMeta");
+	const box = doc.getElementById("searchPageResults");
+	const pager = doc.getElementById("searchPagePager");
+	if (!input || !meta || !box || !pager) return;
+
+	const params = new URLSearchParams(location.search);
+	const q = (params.get("q") || "").trim();
+	const page = Math.max(1, parseInt(params.get("page") || "1", 10) || 1);
+	input.value = q;
+	pager.hidden = true;
+
+	if (!q) {
+		box.replaceChildren();
+		meta.textContent = ui("searchTypeSomething");
+		return;
+	}
+	meta.textContent = ui("searchLoading");
+
+	const pf = await loadPagefind();
+	if (seq !== searchPageSeq) return;
+	if (!pf) {
+		meta.textContent = ui("searchUnavailable");
+		box.replaceChildren();
+		return;
+	}
+	try {
+		const res = await pf.search(q);
+		const total = res.results.length;
+		if (seq !== searchPageSeq) return;
+		if (!total) {
+			box.replaceChildren();
+			meta.textContent = ui("searchNoResults");
+			return;
+		}
+		const pages = Math.ceil(total / SEARCH_PAGE_SIZE);
+		const cur = Math.min(page, pages);
+		const items = await Promise.all(
+			res.results
+				.slice((cur - 1) * SEARCH_PAGE_SIZE, cur * SEARCH_PAGE_SIZE)
+				.map((r) => r.data()),
+		);
+		if (seq !== searchPageSeq) return;
+		box.replaceChildren();
+		for (const item of items) box.appendChild(searchItemEl(item));
+		meta.textContent = ui("searchResultsTotal").replace("{n}", String(total));
+		renderSearchPager(pager, q, cur, pages);
+	} catch {
+		if (seq === searchPageSeq) meta.textContent = ui("searchNoResults");
+	}
+}
+
 /* ---------- 加密文章（M3b-b7）：Web Crypto 解密（与 utils/crypto.ts 构建期参数对齐） ---------- */
 const PW_KEY_PREFIX = "qy-pw:";
 const ENC_SALT_LEN = 16;
@@ -741,7 +920,7 @@ doc.addEventListener("click", (e) => {
 	const target = e.target as Element;
 	if (!target || typeof target.closest !== "function") return;
 
-	/* 点击调色面板/搜索浮层外部时先收起（不拦截后续点击行为） */
+	/* 点击调色面板/搜索浮层/显示设置面板外部时先收起（不拦截后续点击行为） */
 	if (!target.closest(".palette-wrap")) {
 		const pop = doc.getElementById("palettePop");
 		if (pop && !pop.hidden) closePalette();
@@ -750,6 +929,13 @@ doc.addEventListener("click", (e) => {
 		const pop = doc.getElementById("searchPop");
 		if (pop && !pop.hidden) closeSearch();
 	}
+	if (
+		!target.closest(".ds-panel") &&
+		!target.closest("#displaySettingsToggle")
+	) {
+		const panel = doc.getElementById("displaySettingsPanel");
+		if (panel && !panel.hidden) closeDsPanel();
+	}
 
 	/* 搜索浮层开关（§4.56 移动端 icon 按钮；桌面内联框输入即搜，无开关） */
 	if (target.closest("#searchToggle")) {
@@ -768,8 +954,8 @@ doc.addEventListener("click", (e) => {
 		return;
 	}
 
-	/* 搜索结果点击：收起浮层后放行默认导航（VT 接管换页） */
-	if (target.closest(".search-item")) {
+	/* 搜索结果/查看全部点击：浮层收起后放行默认导航（VT 接管换页；search-more 进独立搜索页） */
+	if (target.closest(".search-item, .search-more")) {
 		closeSearch();
 	}
 
@@ -787,8 +973,8 @@ doc.addEventListener("click", (e) => {
 		return;
 	}
 
-	/* 预设色板 */
-	const swatch = target.closest<HTMLElement>(".palette-pop .swatch");
+	/* 预设色板（旧 palette-pop 与显示设置面板外观 Tab 共用同组 swatch） */
+	const swatch = target.closest<HTMLElement>(".swatch[data-hue]");
 	if (swatch) {
 		const h = parseFloat(swatch.dataset.hue || "");
 		if (Number.isFinite(h)) applyHue(h);
@@ -814,6 +1000,36 @@ doc.addEventListener("click", (e) => {
 		return;
 	}
 
+	/* 壁纸模式循环切换（§4.98）：banner→fullscreen→overlay→none，localStorage 持久化 */
+	if (target.closest("#wallpaperModeToggle")) {
+		const cur = WP_MODES.indexOf(root.dataset.wallpaperMode || "banner");
+		setWallpaperMode(WP_MODES[(cur + 1) % WP_MODES.length]!);
+		return;
+	}
+
+	/* 显示设置面板（§4.103）：齿轮开合 / Tab 切换 / 模式与布局按钮 / 开关 / 组重置 */
+	if (handleDsPanelClick(target)) return;
+
+	/* 壁纸视频播放/暂停（§4.98） */
+	if (target.closest("#wpPlayerToggle")) {
+		const video = doc.querySelector<HTMLVideoElement>(".wp-video");
+		if (video) {
+			if (video.paused) video.play().catch(() => {});
+			else video.pause();
+		}
+		return;
+	}
+
+	/* 壁纸视频上一段/下一段 */
+	if (target.closest("#wpPlayerPrev")) {
+		switchWallpaperVideo(-1);
+		return;
+	}
+	if (target.closest("#wpPlayerNext")) {
+		switchWallpaperVideo(1);
+		return;
+	}
+
 	/* burger 导航 */
 	if (target.closest("#navToggle")) {
 		const nav = doc.getElementById("siteNav");
@@ -909,7 +1125,7 @@ doc.addEventListener(
 	true,
 );
 
-/* input 委托（VT 安全）：hue 滑杆 + 搜索输入 */
+/* input 委托（VT 安全）：hue 滑杆 + 搜索输入 + 显示设置面板透明滑块（§4.103） */
 doc.addEventListener("input", (e) => {
 	const el = e.target as Element | null;
 	if (el && el.id === "hueSlider") {
@@ -919,16 +1135,37 @@ doc.addEventListener("input", (e) => {
 	if (el && (el.id === "searchInput" || el.id === "searchInputM")) {
 		runSearch((el as HTMLInputElement).value.trim());
 	}
+	/* 独立搜索页输入（§4.104）：300ms 防抖 + replaceState 同步 URL，客户端即时刷新不经换页 */
+	if (el && el.id === "searchPageInput") {
+		const q = (el as HTMLInputElement).value.trim();
+		window.clearTimeout(searchPageTimer);
+		searchPageTimer = window.setTimeout(() => {
+			const url = new URL(location.href);
+			if (q) url.searchParams.set("q", q);
+			else url.searchParams.delete("q");
+			url.searchParams.delete("page");
+			history.replaceState(null, "", url);
+			renderSearchPage();
+		}, 300);
+	}
+	if (el instanceof HTMLInputElement && el.dataset.dsSlider) {
+		handleDsSliderInput(el);
+	}
 });
 
 doc.addEventListener("keydown", (e) => {
-	/* 搜索浮层：Esc 关闭 */
+	/* 搜索浮层/显示设置面板：Esc 关闭 */
 	if (e.key === "Escape") {
 		const pop = doc.getElementById("searchPop");
 		if (pop && !pop.hidden) {
 			closeSearch();
 			return;
 		}
+		const panel = doc.getElementById("displaySettingsPanel");
+		if (panel && !panel.hidden) {
+			closeDsPanel();
+			return;
+		}
 	}
 	/* 搜索快捷键（§4.12）：/ 或 ⌘/Ctrl+K；输入中、灯箱（PhotoSwipe）打开时不触发 */
 	if (
@@ -1021,6 +1258,534 @@ function initSeriesNav() {
 	}
 }
 
+/* ---------- 壁纸（§4.98）：模式切换 / 图片轮播 / 打字机 / 视频播放器 ---------- */
+const WP_KEY = "qy-wallpaper";
+const WP_MODES = ["banner", "fullscreen", "overlay", "none"];
+// 模块级定时器/游标：VT 换页重复 initWallpaper 时先清后建防泄漏
+let wpCarouselTimer: number | undefined;
+let wpTyperTimer: number | undefined;
+let wpVideoIdx = 0;
+
+function savedWallpaperMode(): string | null {
+	try {
+		const m = localStorage.getItem(WP_KEY);
+		return m && WP_MODES.includes(m) ? m : null;
+	} catch {
+		return null;
+	}
+}
+
+/* 导航栏形态联动：banner/fullscreen 走配置的透明档，overlay/none 回实底 */
+function syncWallpaperNav(mode: string) {
+	root.dataset.wallpaperNav =
+		mode === "banner" || mode === "fullscreen"
+			? root.dataset.wpNavConfig || "solid"
+			: "solid";
+}
+
+/* 壁纸模式统一切换入口（§4.98 循环按钮与 §4.103 面板模式宫格共用）：
+   banner/fullscreen 解除 homeOnly 隐藏，overlay/none 停视频并回实底导航；
+   data-wp-stage-hidden 同步供 hero 布局取消首屏下推 */
+function setWallpaperMode(next: string) {
+	root.dataset.wallpaperMode = next;
+	syncWallpaperNav(next);
+	const stage = doc.querySelector<HTMLElement>(".wp-stage");
+	if (stage) {
+		if (next === "banner" || next === "fullscreen") {
+			delete stage.dataset.wallpaperHidden;
+			delete root.dataset.wpStageHidden;
+		} else {
+			stage.setAttribute("data-wallpaper-hidden", "");
+			root.dataset.wpStageHidden = "true";
+		}
+	}
+	if (next === "overlay" || next === "none") pauseWallpaperVideo();
+	try {
+		localStorage.setItem(WP_KEY, next);
+	} catch {
+		/* ignore */
+	}
+	syncDsPanelState();
+}
+
+function pauseWallpaperVideo() {
+	const video = doc.querySelector<HTMLVideoElement>(".wp-video");
+	if (video && !video.paused) video.pause();
+}
+
+/* 恢复访客保存的壁纸模式（after-swap 与 initWallpaper 双入口，幂等）：
+   boot 脚本负责首帧，这里兜底 VT 换页；显式偏好解除 homeOnly 的非首页隐藏；
+   §4.103：面板开启时追加恢复布局/开关/透明三件套（html style 随 swap 重建需重应用）。
+   注意：即使保存模式与 SSR 模式相同，也必须同步 data-wallpaper-hidden，否则
+   非首页刷新时 SSR 渲染的隐藏标记不会被清除（banner/fullscreen 应始终可见） */
+function applySavedWallpaper() {
+	const m =
+		root.dataset.wpSwitchable === "true"
+			? savedWallpaperMode() || root.dataset.wallpaperMode
+			: root.dataset.wallpaperMode;
+	if (m && m !== root.dataset.wallpaperMode) {
+		root.dataset.wallpaperMode = m;
+		syncWallpaperNav(m);
+	}
+	const stage = doc.querySelector<HTMLElement>(".wp-stage");
+	if (stage) {
+		if (m === "banner" || m === "fullscreen") {
+			delete stage.dataset.wallpaperHidden;
+			delete root.dataset.wpStageHidden;
+		} else {
+			stage.setAttribute("data-wallpaper-hidden", "");
+			root.dataset.wpStageHidden = "true";
+		}
+	}
+	if (root.dataset.dsEnable === "true") applyDsPrefs();
+}
+
+/* 图片轮播：desktop/mobile 两组独立游标，--wp-interval 供 kenburns/zoom 动画时长对齐；
+   §4.103：访客经面板关闭轮播（html[data-wp-carousel="off"]）时不建定时器 */
+function initWallpaperCarousel() {
+	const stage = doc.querySelector<HTMLElement>(".wp-stage");
+	if (!stage || stage.dataset.carousel !== "true") return;
+	if (root.dataset.wpCarousel === "off") return;
+	const groups = Array.from(stage.querySelectorAll<HTMLElement>(".wp-images"));
+	if (groups.length === 0) return;
+	const interval =
+		Math.max(1000, parseInt(stage.dataset.carouselInterval || "5000", 10)) ||
+		5000;
+	stage.style.setProperty("--wp-interval", `${(interval / 1000).toFixed(2)}s`);
+	const cursors = groups.map(() => 0);
+	wpCarouselTimer = window.setInterval(() => {
+		groups.forEach((group, gi) => {
+			const imgs = group.querySelectorAll(".wp-img");
+			if (imgs.length < 2) return;
+			imgs[cursors[gi]].classList.remove("active");
+			cursors[gi] = (cursors[gi] + 1) % imgs.length;
+			imgs[cursors[gi]].classList.add("active");
+		});
+	}, interval);
+}
+
+/* 逐字素切分（中文/emoji 安全），环境不支持时退回码元切分 */
+function splitGraphemes(text: string): string[] {
+	try {
+		const seg = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+		return Array.from(seg.segment(text), (s) => s.segment);
+	} catch {
+		return Array.from(text);
+	}
+}
+
+/* 首页打字机：多条副标题循环（打完→停顿→删完→下一条），单条打完驻留 */
+function initWallpaperTyper() {
+	const el = doc.getElementById("wpTyper");
+	if (!el) return;
+	let subs: string[] = [];
+	try {
+		subs = JSON.parse(el.dataset.subtitles || "[]");
+	} catch {
+		/* ignore */
+	}
+	subs = subs.filter(Boolean);
+	if (subs.length === 0) return;
+	const speed = parseInt(el.dataset.speed || "100", 10) || 100;
+	const delSpeed = parseInt(el.dataset.deleteSpeed || "50", 10) || 50;
+	const pause = parseInt(el.dataset.pauseTime || "2000", 10) || 2000;
+	const chars = subs.map(splitGraphemes);
+	let si = 0;
+	let ci = 0;
+	let deleting = false;
+	const tick = () => {
+		const cur = chars[si];
+		if (!deleting) {
+			ci += 1;
+			el.textContent = cur.slice(0, ci).join("");
+			if (ci >= cur.length) {
+				if (subs.length === 1) return;
+				deleting = true;
+				wpTyperTimer = window.setTimeout(tick, pause);
+			} else {
+				wpTyperTimer = window.setTimeout(tick, speed);
+			}
+		} else {
+			ci -= 1;
+			el.textContent = cur.slice(0, ci).join("");
+			if (ci <= 0) {
+				deleting = false;
+				si = (si + 1) % subs.length;
+				wpTyperTimer = window.setTimeout(tick, 300);
+			} else {
+				wpTyperTimer = window.setTimeout(tick, delSpeed);
+			}
+		}
+	};
+	wpTyperTimer = window.setTimeout(tick, speed);
+}
+
+/* 视频壁纸：初始源依 order/random 选取，自动播放（muted+playsinline 免手势），
+   play/pause 事件同步按钮图标（is-playing）与 stage 播放态（data-video-playing） */
+function initWallpaperVideo() {
+	const video = doc.querySelector<HTMLVideoElement>(".wp-video");
+	if (!video) return;
+	let urls: string[] = [];
+	try {
+		urls = JSON.parse(video.dataset.playerUrls || "[]");
+	} catch {
+		/* ignore */
+	}
+	urls = urls.filter(Boolean);
+	if (urls.length === 0) return;
+	wpVideoIdx =
+		video.dataset.playerMode === "random"
+			? Math.floor(Math.random() * urls.length)
+			: 0;
+	video.src = urls[wpVideoIdx];
+	video.loop = true;
+	const sync = () => {
+		const btn = doc.getElementById("wpPlayerToggle");
+		if (btn) {
+			btn.classList.toggle("is-playing", !video.paused);
+			const label = video.paused ? ui("wpPlay") : ui("wpPause");
+			btn.setAttribute("aria-label", label);
+			btn.title = label;
+		}
+		doc
+			.querySelector(".wp-stage")
+			?.toggleAttribute("data-video-playing", !video.paused);
+	};
+	video.addEventListener("play", sync);
+	video.addEventListener("pause", sync);
+	sync();
+	video.play().catch(() => sync()); // 自动播放被策略拦截时保持暂停态
+}
+
+/* 上一段/下一段视频（初始 idx 由 order/random 决定，此后线性切换） */
+function switchWallpaperVideo(dir: 1 | -1) {
+	const video = doc.querySelector<HTMLVideoElement>(".wp-video");
+	if (!video) return;
+	let urls: string[] = [];
+	try {
+		urls = JSON.parse(video.dataset.playerUrls || "[]");
+	} catch {
+		return;
+	}
+	if (urls.length === 0) return;
+	wpVideoIdx = (wpVideoIdx + dir + urls.length) % urls.length;
+	video.src = urls[wpVideoIdx];
+	video.play().catch(() => {});
+}
+
+/* 导航栏滚动实底（html.wp-scrolled）：顶部走半透明档，滚过阈值回实底 */
+function updateWallpaperScroll() {
+	root.classList.toggle("wp-scrolled", (window.scrollY || 0) > 40);
+}
+
+function initWallpaper() {
+	if (wpCarouselTimer !== undefined) {
+		window.clearInterval(wpCarouselTimer);
+		wpCarouselTimer = undefined;
+	}
+	if (wpTyperTimer !== undefined) {
+		window.clearTimeout(wpTyperTimer);
+		wpTyperTimer = undefined;
+	}
+	applySavedWallpaper();
+	updateWallpaperScroll();
+	if (!doc.querySelector(".wp-stage")) return;
+	initWallpaperCarousel();
+	initWallpaperTyper();
+	initWallpaperVideo();
+}
+
+/* VT swap 替换 <html> 属性后立即恢复偏好模式（不等 page-load，防默认形态闪帧） */
+doc.addEventListener("astro:after-swap", applySavedWallpaper);
+
+/* ---------- 显示设置面板（§4.103，对齐 Firefly） ----------
+   齿轮入口三 Tab 浮层（外观/壁纸/特效）；localStorage 键表见 design.md §4.103。
+   应用机制：html data 属性（显隐类）+ html style CSS 变量（透明三件套），
+   boot 内联脚本（BaseLayout）首帧应用，applyDsPrefs 为 after-swap/初始化双入口 */
+const DS_KEY = {
+	fsLayout: "qy-wp-fs-layout",
+	homeText: "qy-wp-home-text",
+	carousel: "qy-wp-carousel",
+	waves: "qy-wp-waves",
+	gradient: "qy-wp-gradient",
+	opacity: "qy-wp-opacity",
+	blur: "qy-wp-blur",
+	cardOpacity: "qy-wp-card-opacity",
+	sakura: "qy-sakura",
+} as const;
+/* 开关键 ↔ html data 属性 ↔ localStorage 键 映射（on/off 语义） */
+const DS_SWITCH_MAP = {
+	"home-text": { ls: DS_KEY.homeText, attr: "wpHomeText" },
+	carousel: { ls: DS_KEY.carousel, attr: "wpCarousel" },
+	waves: { ls: DS_KEY.waves, attr: "wpWaves" },
+	gradient: { ls: DS_KEY.gradient, attr: "wpGradient" },
+	sakura: { ls: DS_KEY.sakura, attr: "wpSakura" },
+} as const;
+type DsSwitchId = keyof typeof DS_SWITCH_MAP;
+
+function lsGet(key: string): string | null {
+	try {
+		return localStorage.getItem(key);
+	} catch {
+		return null;
+	}
+}
+function lsSet(key: string, val: string | null) {
+	try {
+		if (val === null) localStorage.removeItem(key);
+		else localStorage.setItem(key, val);
+	} catch {
+		/* ignore */
+	}
+}
+
+/* 透明三件套应用到 html style（boot 同款逻辑；null 表示清除覆写回落配置默认） */
+function applyOverlayOpacity(v: number | null) {
+	if (v === null) root.style.removeProperty("--wp-overlay-opacity");
+	else root.style.setProperty("--wp-overlay-opacity", String(v));
+}
+function applyOverlayBlur(v: number | null) {
+	if (v === null) {
+		root.style.removeProperty("--wp-overlay-blur");
+		root.style.removeProperty("--wp-overlay-scale");
+	} else {
+		root.style.setProperty("--wp-overlay-blur", `${v}px`);
+		root.style.setProperty("--wp-overlay-scale", (1 + v / 100).toFixed(3));
+	}
+}
+function applyCardOpacity(v: number | null) {
+	if (v === null) root.style.removeProperty("--wp-card-opacity");
+	else root.style.setProperty("--wp-card-opacity", `${Math.round(v * 100)}%`);
+}
+
+/* 开关应用：html data 属性 + 副作用（轮播定时器清/建、樱花停/启） */
+function applyDsSwitch(id: DsSwitchId, on: boolean) {
+	const { ls, attr } = DS_SWITCH_MAP[id];
+	root.dataset[attr] = on ? "on" : "off";
+	lsSet(ls, on ? "1" : "0");
+	if (id === "carousel") {
+		if (wpCarouselTimer !== undefined) {
+			window.clearInterval(wpCarouselTimer);
+			wpCarouselTimer = undefined;
+		}
+		if (on) initWallpaperCarousel();
+	}
+	if (id === "sakura") {
+		doc.dispatchEvent(
+			new CustomEvent("orchid:sakura-toggle", { detail: on ? "on" : "off" }),
+		);
+	}
+}
+
+/* 恢复面板全部访客偏好（boot 负责首帧，这里兜底 VT swap 与初始化） */
+function applyDsPrefs() {
+	const l = lsGet(DS_KEY.fsLayout);
+	if (l === "classic" || l === "hero") root.dataset.wpFsLayout = l;
+	for (const id of Object.keys(DS_SWITCH_MAP) as DsSwitchId[]) {
+		const v = lsGet(DS_SWITCH_MAP[id].ls);
+		if (v === "0" || v === "1")
+			root.dataset[DS_SWITCH_MAP[id].attr] = v === "1" ? "on" : "off";
+	}
+	const op = parseFloat(lsGet(DS_KEY.opacity) || "");
+	if (Number.isFinite(op)) applyOverlayOpacity(op);
+	const bl = parseFloat(lsGet(DS_KEY.blur) || "");
+	if (Number.isFinite(bl)) applyOverlayBlur(bl);
+	const co = parseFloat(lsGet(DS_KEY.cardOpacity) || "");
+	if (Number.isFinite(co)) applyCardOpacity(co);
+}
+
+/* 面板根节点配置默认值（DisplaySettings.astro 输出的 data-def-*） */
+function dsPanel(): HTMLElement | null {
+	return doc.getElementById("displaySettingsPanel");
+}
+function dsDef(key: string, fallback: number): number {
+	const v = parseFloat(dsPanel()?.dataset[key] || "");
+	return Number.isFinite(v) ? v : fallback;
+}
+
+/* 同步面板控件态：模式/布局按钮激活、组显隐（data-modes）、开关、滑块与徽章。
+   模式或布局切换、面板打开、组重置、VT 换页后调用 */
+function syncDsPanelState() {
+	const panel = dsPanel();
+	if (!panel) return;
+	const mode = root.dataset.wallpaperMode || "none";
+	const layout = root.dataset.wpFsLayout || "classic";
+	/* 当前生效的模式 token：fullscreen+hero 组合单独成一个虚拟模式 */
+	const tokens = [mode];
+	if (mode === "fullscreen" && layout === "hero")
+		tokens.push("fullscreen-hero");
+	panel.querySelectorAll<HTMLElement>("[data-modes]").forEach((el) => {
+		const modes = (el.dataset.modes || "").split(/\s+/).filter(Boolean);
+		const visible = tokens.some((tok) => modes.includes(tok));
+		if (el.classList.contains("ds-group"))
+			el.classList.toggle("is-hidden", !visible);
+		else el.classList.toggle("ds-row-hidden", !visible);
+	});
+	panel
+		.querySelectorAll<HTMLElement>(".ds-mode-btn[data-mode]")
+		.forEach((b) => {
+			b.classList.toggle("is-active", b.dataset.mode === mode);
+		});
+	panel
+		.querySelectorAll<HTMLElement>(".ds-mode-btn[data-fs-layout]")
+		.forEach((b) => {
+			b.classList.toggle("is-active", b.dataset.fsLayout === layout);
+		});
+	/* 开关态：html data 属性为当前生效值（boot/applyDsPrefs 已写入，默认 on） */
+	for (const id of Object.keys(DS_SWITCH_MAP) as DsSwitchId[]) {
+		const sw = panel.querySelector<HTMLElement>(`[data-ds-switch="${id}"]`);
+		if (sw)
+			sw.setAttribute(
+				"aria-checked",
+				root.dataset[DS_SWITCH_MAP[id].attr] === "off" ? "false" : "true",
+			);
+	}
+	/* 滑块与徽章：localStorage 覆写优先，否则面板 data-def-*（配置默认） */
+	const opSaved = parseFloat(lsGet(DS_KEY.opacity) || "");
+	const op = Number.isFinite(opSaved) ? opSaved : dsDef("defOpacity", 0.8);
+	const blSaved = parseFloat(lsGet(DS_KEY.blur) || "");
+	const bl = Number.isFinite(blSaved) ? blSaved : dsDef("defBlur", 0);
+	const coSaved = parseFloat(lsGet(DS_KEY.cardOpacity) || "");
+	const co = Number.isFinite(coSaved) ? coSaved : dsDef("defCardOpacity", 0.5);
+	const setSlider = (id: string, val: number, text: string) => {
+		const s = panel.querySelector<HTMLInputElement>(`[data-ds-slider="${id}"]`);
+		if (s) s.value = String(val);
+		const badge = panel.querySelector<HTMLElement>(`[data-ds-badge="${id}"]`);
+		if (badge) badge.textContent = text;
+	};
+	setSlider("opacity", Math.round(op * 100), `${Math.round(op * 100)}%`);
+	setSlider("blur", bl, `${bl}px`);
+	setSlider("card-opacity", Math.round(co * 100), `${Math.round(co * 100)}%`);
+}
+
+function closeDsPanel() {
+	const panel = dsPanel();
+	if (panel) panel.hidden = true;
+	doc
+		.getElementById("displaySettingsToggle")
+		?.setAttribute("aria-expanded", "false");
+}
+
+/* 面板 click 委托（document 级）：命中面板内控件返回 true 拦截后续处理 */
+function handleDsPanelClick(target: Element): boolean {
+	/* 齿轮开合 */
+	if (target.closest("#displaySettingsToggle")) {
+		const panel = dsPanel();
+		if (panel) {
+			const open = panel.hidden;
+			panel.hidden = !open;
+			target
+				.closest("#displaySettingsToggle")
+				?.setAttribute("aria-expanded", open ? "true" : "false");
+			if (open) syncDsPanelState();
+		}
+		return true;
+	}
+	/* Tab 切换 */
+	const tab = target.closest<HTMLElement>(".ds-tab[data-tab]");
+	if (tab) {
+		const panel = dsPanel();
+		if (panel) {
+			panel.querySelectorAll(".ds-tab").forEach((b) => {
+				b.classList.toggle("is-active", b === tab);
+				b.setAttribute("aria-selected", b === tab ? "true" : "false");
+			});
+			panel.querySelectorAll<HTMLElement>(".ds-page").forEach((p) => {
+				p.classList.toggle("is-active", p.dataset.page === tab.dataset.tab);
+			});
+		}
+		return true;
+	}
+	/* 壁纸模式四选一（复用统一切换入口） */
+	const modeBtn = target.closest<HTMLElement>("[data-mode]");
+	if (modeBtn && dsPanel()?.contains(modeBtn)) {
+		const m = modeBtn.dataset.mode || "";
+		if (WP_MODES.includes(m)) setWallpaperMode(m);
+		return true;
+	}
+	/* 全屏布局切换 */
+	const layoutBtn = target.closest<HTMLElement>("[data-fs-layout]");
+	if (layoutBtn) {
+		const l = layoutBtn.dataset.fsLayout || "";
+		if (l === "classic" || l === "hero") {
+			root.dataset.wpFsLayout = l;
+			lsSet(DS_KEY.fsLayout, l);
+			syncDsPanelState();
+		}
+		return true;
+	}
+	/* 开关行 */
+	const sw = target.closest<HTMLElement>("[data-ds-switch]");
+	if (sw) {
+		const id = sw.dataset.dsSwitch as DsSwitchId;
+		if (id in DS_SWITCH_MAP) {
+			const on = sw.getAttribute("aria-checked") !== "true";
+			applyDsSwitch(id, on);
+			sw.setAttribute("aria-checked", on ? "true" : "false");
+		}
+		return true;
+	}
+	/* 组重置（↺）：清本组 localStorage，回落配置默认并重应用 */
+	const resetBtn = target.closest<HTMLElement>("[data-reset-group]");
+	if (resetBtn) {
+		if (resetBtn.dataset.resetGroup === "wallpaper") {
+			lsSet(DS_KEY.homeText, null);
+			lsSet(DS_KEY.carousel, null);
+			lsSet(DS_KEY.waves, null);
+			lsSet(DS_KEY.gradient, null);
+			delete root.dataset.wpHomeText;
+			delete root.dataset.wpCarousel;
+			delete root.dataset.wpWaves;
+			delete root.dataset.wpGradient;
+			/* 轮播回到配置默认（开）：先清后建 */
+			if (wpCarouselTimer !== undefined) {
+				window.clearInterval(wpCarouselTimer);
+				wpCarouselTimer = undefined;
+			}
+			initWallpaperCarousel();
+		}
+		if (resetBtn.dataset.resetGroup === "overlay") {
+			lsSet(DS_KEY.opacity, null);
+			lsSet(DS_KEY.blur, null);
+			lsSet(DS_KEY.cardOpacity, null);
+			applyOverlayOpacity(null);
+			applyOverlayBlur(null);
+			applyCardOpacity(null);
+		}
+		syncDsPanelState();
+		return true;
+	}
+	return false;
+}
+
+/* 滑块 input（input 委托调用）：实时应用 + 持久化 + 徽章 */
+function handleDsSliderInput(el: HTMLInputElement) {
+	const id = el.dataset.dsSlider;
+	const v = parseFloat(el.value);
+	if (!Number.isFinite(v)) return;
+	if (id === "opacity") {
+		applyOverlayOpacity(v / 100);
+		lsSet(DS_KEY.opacity, String(v / 100));
+	} else if (id === "blur") {
+		applyOverlayBlur(v);
+		lsSet(DS_KEY.blur, String(v));
+	} else if (id === "card-opacity") {
+		applyCardOpacity(v / 100);
+		lsSet(DS_KEY.cardOpacity, String(v / 100));
+	} else return;
+	const panel = dsPanel();
+	const badge = panel?.querySelector<HTMLElement>(`[data-ds-badge="${id}"]`);
+	if (badge) badge.textContent = id === "blur" ? `${v}px` : `${Math.round(v)}%`;
+}
+
+/* 每次导航后重绑面板（DOM 随 swap 重建）：复位收起 + 控件态同步 */
+function initDisplaySettings() {
+	const panel = dsPanel();
+	if (!panel) return;
+	closeDsPanel();
+	syncDsPanelState();
+}
+
 /* ---------- 生命周期 ---------- */
 function initPage() {
 	initLightbox();
@@ -1036,6 +1801,9 @@ function initPage() {
 	initCategoryBar();
 	initPostListLayout();
 	initSeriesNav();
+	initWallpaper();
+	initDisplaySettings();
+	renderSearchPage();
 }
 initPage();
 doc.addEventListener("astro:page-load", initPage);