@windcoder/astro-theme-orchid 0.0.0-stage → 0.2.0

package/src/components/comments/Giscus.astro

@@ -0,0 +1,50 @@
+---
+/**
+ * Giscus 评论实现（orchid-blog components/comment/Giscus.astro 移植）。
+ * 官方 Web Component 用法（esm.sh 动态 import，零 npm 依赖，静态输出兼容）。
+ * VT 兼容：合并进单个 inline module 并 data-astro-rerun——外部 identical 脚本
+ * 换页不重跑，observer 不会重建；await import 幂等（模块缓存，customElements
+ * 不会重复 define）。旧 MutationObserver 经 window 句柄清理，防泄漏。
+ */
+import config from "virtual:theme/config";
+
+const g = config.comment.giscus;
+---
+
+<giscus-widget
+  id="comments"
+  repo={g.repo}
+  repoId={g.repoId}
+  category={g.category}
+  categoryId={g.categoryId}
+  mapping={g.mapping}
+  strict={g.strict}
+  reactionsEnabled={g.reactionsEnabled}
+  emitMetadata={g.emitMetadata}
+  inputPosition={g.inputPosition}
+  theme="light"
+  lang={g.lang}
+  loading={g.loading}
+/>
+
+<script is:inline type="module" data-astro-rerun>
+  await import("https://esm.sh/giscus");
+
+  // 换页重跑时清理旧观察器，避免泄漏
+  if (window.__orchidGiscusObserver) window.__orchidGiscusObserver.disconnect();
+
+  function updateGiscusTheme() {
+    const widget = document.querySelector("giscus-widget");
+    if (widget) {
+      widget.setAttribute(
+        "theme",
+        document.documentElement.classList.contains("dark") ? "dark" : "light",
+      );
+    }
+  }
+  updateGiscusTheme();
+
+  const observer = new MutationObserver(updateGiscusTheme);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+  window.__orchidGiscusObserver = observer;
+</script>

package/src/components/comments/Twikoo.astro

@@ -0,0 +1,65 @@
+---
+/**
+ * Twikoo 评论实现（orchid-blog components/comment/Twikoo.astro 移植）。
+ * path 口径与 Artalk 一致（/posts/<id>、/guestbook，无尾斜杠），迁移后既有评论数据无缝延续。
+ * VT 兼容：identical inline 脚本换页不重跑，data-astro-rerun 强制重执行；
+ * 脚本加载失败时的 500ms 重试链经 window 句柄清理，防重入叠加。
+ */
+import config from "virtual:theme/config";
+
+interface Props {
+	path: string;
+}
+
+const { path } = Astro.props;
+const tw = config.comment.twikoo;
+const twikooConfig = {
+	el: "#tcomment",
+	envId: tw.envId,
+	path,
+};
+---
+
+<div class="relative w-full">
+  <div id="tcomment"></div>
+
+  {tw.cssUrl && <link rel="stylesheet" href={tw.cssUrl} />}
+
+  <script is:inline src={tw.jsUrl}></script>
+
+  <script is:inline data-astro-rerun define:vars={{ twikooConfig }}>
+    // 换页重跑时清掉上次执行遗留的重试定时器，防叠加
+    if (window.__orchidTwikooTimer) {
+      clearTimeout(window.__orchidTwikooTimer);
+      window.__orchidTwikooTimer = undefined;
+    }
+
+    function initTwikoo() {
+      const el = document.getElementById("tcomment");
+      if (!el) return;
+      if (typeof twikoo === "undefined") {
+        // 脚本尚在加载，稍后重试
+        window.__orchidTwikooTimer = setTimeout(initTwikoo, 500);
+        return;
+      }
+      el.innerHTML = "";
+      twikoo.init(twikooConfig);
+      // meta 区浏览量（§4.14）：getCommentsCount 填充头部 #twikoo_visitors（与 orchid-blog 口径一致）
+      var pv = document.getElementById("twikoo_visitors");
+      if (pv) {
+        twikoo
+          .getCommentsCount({
+            envId: twikooConfig.envId,
+            urls: [twikooConfig.path],
+            includeReply: false,
+          })
+          .then(function (r) {
+            pv.textContent = String((r && r[0] && r[0].count) || 0);
+          })
+          .catch(function () {});
+      }
+    }
+
+    initTwikoo();
+  </script>
+</div>

package/src/components/comments/Waline.astro

@@ -0,0 +1,36 @@
+---
+/**
+ * Waline 评论实现（orchid-blog components/comment/Waline.astro 移植）。
+ * dark: 'html.dark' 由 Waline 自身监听根元素 class，无需 MutationObserver。
+ * VT 兼容：identical module 脚本换页不重跑（评论区 DOM 已随 swap 重建），
+ * data-astro-rerun 强制重新 init。
+ */
+import config from "virtual:theme/config";
+
+interface Props {
+	path: string;
+}
+
+const { path } = Astro.props;
+const w = config.comment.waline;
+const walineConfig = {
+	el: "#waline",
+	serverURL: w.serverURL,
+	path,
+	lang: w.lang,
+	dark: "html.dark",
+	wordLimit: [2, 300],
+	...(w.visitorCount ? { pageview: true } : {}),
+};
+---
+
+<div class="relative w-full">
+  <div id="waline"></div>
+
+  <link rel="stylesheet" href="https://unpkg.com/@waline/client@v3/dist/waline.css" />
+
+  <script is:inline type="module" data-astro-rerun define:vars={{ walineConfig }}>
+    const { init } = await import("https://unpkg.com/@waline/client@v3/dist/waline.js");
+    init(walineConfig);
+  </script>
+</div>

package/src/i18n/en.ts

@@ -0,0 +1,164 @@
+/**
+ * 英文语言包：Record<UiKey, string> 强制与中文键源一一对应，缺译会在编译期报错。
+ */
+import type { UiKey } from "./zh-CN.js";
+
+const en: Record<UiKey, string> = {
+	skipToContent: "Skip to content",
+	backToTop: "Back to top",
+	mainNav: "Main navigation",
+	toggleMode: "Toggle dark mode",
+	menu: "Menu",
+	palette: "Theme color",
+	paletteTitle: "Accent color",
+	reset: "Reset",
+	hueValue: "Hue {n}",
+	pinned: "Pinned",
+	wordsCount: "{n} words",
+	minutesCount: "{n} min read",
+	prevNext: "Previous / Next",
+	prevPost: "Previous",
+	nextPost: "Next",
+	firstPost: "This is the earliest post",
+	lastPost: "This is the latest post",
+	relatedPosts: "Related Posts",
+	randomPosts: "Random Posts",
+	smartRecommend: "Smart",
+	randomRecommend: "Random",
+	noRelatedPosts: "No related posts",
+	noRandomPosts: "No random posts",
+	licensePrefix: "This post is licensed under",
+	licenseSuffix: ". Please credit the author when reposting.",
+	toc: "Table of contents",
+	tocTitle: "Contents",
+	pagination: "Pagination",
+	prevPage: "Previous",
+	nextPage: "Next",
+	pageOf: "Page {current} of {total}",
+	closeAnnouncement: "Close announcement",
+	closeAd: "Close ad",
+	categories: "Categories",
+	tags: "Tags",
+	friendLinks: "Friends",
+	siteInfo: "Site info",
+	posts: "Posts",
+	running: "Running for",
+	daysCount: "{n} days",
+	dayPostsCount: "{n} posts",
+	heatWeekTip: "Week {w} of {m} · {n}",
+	/* §4.47 calendar head / §4.48 tags more entry */
+	tagsMore: "… more",
+	calendarHome: "This month",
+	calendarPick: "Pick year & month",
+	layoutSwitch: "Switch list / grid view",
+	layoutList: "List view",
+	layoutGrid: "Grid view",
+	emptyPosts: "No posts yet. Write one in content/posts.",
+	pageN: "Page {n}",
+	archive: "Archive",
+	home: "Home",
+	categoryNav: "Category navigation",
+	more: "More",
+	totalPosts: "{n} posts in total",
+	postsInYear: "{n} posts",
+	yearUnit: "{n}",
+	totalTags: "{n} tags in total",
+	tagTitle: "Tag: {tag}",
+	totalCategories: "{n} categories in total",
+	categoryTitle: "Category: {category}",
+	publishedOn: "Published on {date}",
+	updatedOn: "Updated on {date}",
+	pageviews: "Page views",
+	notFound: "Page not found",
+	notFoundDesc: "The page does not exist or has been moved.",
+	backHome: "Back to home",
+	about: "About",
+	aboutEmpty: "Write this page in src/content/spec/about.md",
+	avatarAlt: "Avatar of {name}",
+	noFriends: "No friend links yet",
+	applyFriend: "Apply for a link",
+	guestbook: "Guestbook",
+	guestbookSub: "Leave your trace here",
+	commentComingSoon: "Comments are coming soon. Stay tuned.",
+	qrAlt: "QR code of {name}",
+	goSponsor: "Donate",
+	qrPlaceholder: "QR code placeholder",
+	sponsorList: "Sponsors",
+	noSponsors: "Be the first to sponsor",
+	search: "Search",
+	searchShortcut: "Press / or Ctrl+K to search",
+	searchLoading: "Searching…",
+	searchNoResults: "No results found",
+	searchUnavailable: "Search index available after build",
+	searchTypeSomething: "Type to search",
+	galleryPhotos: "{n} photos",
+	backToAlbums: "Back to albums",
+	searchAlbums: "Search albums…",
+	allTags: "All",
+	galleryNoAlbums: "No albums yet. Add one in theme config gallery.albums.",
+	galleryNoPhotos: "No photos in this album",
+	encryptedAlbum: "Encrypted album",
+	searchAlbumNoResults: "No matching albums",
+	postEncrypted: "Encrypted",
+	passwordProtected: "Password Protected",
+	passwordProtectedDesc:
+		"This content is password protected. Enter the password to view.",
+	passwordHint: "Hint",
+	passwordPlaceholder: "Enter password",
+	passwordSubmit: "Unlock",
+	passwordError: "Wrong password, please try again.",
+	close: "Close",
+	prevImage: "Previous image",
+	nextImage: "Next image",
+	copied: "Copied",
+	fullscreen: "Fullscreen",
+	slideshow: "Slideshow",
+	thumbs: "Thumbnails",
+	sharePoster: "Generate share poster",
+	generatingPoster: "Generating poster…",
+	copyLink: "Copy link",
+	savePoster: "Save poster",
+	scanToRead: "Scan to read",
+	author: "Author",
+	supportTitle: "Support",
+	supportDesc: "If this post helped you, consider sponsoring or sharing it.",
+	sponsorMe: "Sponsor",
+	lastModifiedPrefix: "Last updated on ",
+	lastModifiedDaysAgo: ", {days} days ago",
+	lastModifiedOutdated: "Some content may be outdated.",
+	series: "Series",
+	seriesTotal: "{n} series in total",
+	seriesPostsCount: "{n} posts",
+	seriesUpdated: "Updated on {date}",
+	seriesEmpty:
+		"No series yet. Add a series field to a post's frontmatter to create one.",
+	seriesProgress: "{cur} / {total}",
+	seriesCatalog: "Series catalog",
+	/* Music player (§4.36) */
+	musicOpen: "Music player",
+	musicClose: "Collapse player",
+	musicPlay: "Play",
+	musicPause: "Pause",
+	musicPrev: "Previous track",
+	musicNext: "Next track",
+	musicModeList: "List loop",
+	musicModeOne: "Repeat one",
+	musicModeRandom: "Shuffle",
+	musicLyrics: "Lyrics",
+	musicPlaylist: "Playlist",
+	musicNoLyrics: "No lyrics",
+	musicEmpty: "Playlist is empty",
+	musicSeek: "Playback progress",
+	musicVolume: "Volume",
+	l2dHome: "Home",
+	l2dScrollTop: "Back to top",
+	l2dSleep: "Take a nap",
+	l2dSwitchModel: "Switch model",
+	/* Code folding (§4.61): Expressive Code pluginCollapsible option texts (node-side) */
+	codeFoldExpand: "Expand code",
+	codeFoldCollapse: "Collapse code",
+	codeFoldExpanded: "Code block expanded",
+	codeFoldCollapsed: "Code block collapsed",
+};
+
+export default en;

package/src/i18n/index.ts

@@ -0,0 +1,18 @@
+/**
+ * i18n 入口（构建期 only）：语言在构建时由 themeConfig.lang 确定并注入产物，
+ * 不做客户端语言切换。缺译时回退中文键源，保证渲染永不落空。
+ * 客户端动态文案（复制按钮/灯箱 aria）经 BaseLayout 输出的 #qy-ui-labels JSON 载体带入。
+ *
+ * 注意：本模块顶层 import virtual:theme/config，只能被 dev/build 运行期的
+ * vite 管线模块（.astro 路由/组件）引用；astro.config 静态 import 链上的
+ * node 侧代码（rehype 插件等）请改用 ./resolve.js 的 resolveLabel(lang, key)。
+ */
+import config from "virtual:theme/config";
+import { resolveLabel, type UiKey } from "./resolve.js";
+
+/** 取 UI 文案；vars 替换 {name} 占位符；缺译回退中文 */
+export function t(key: UiKey, vars?: Record<string, string | number>): string {
+	return resolveLabel(config.lang, key, vars);
+}
+
+export type { UiKey };

package/src/i18n/resolve.ts

@@ -0,0 +1,49 @@
+/**
+ * 语言包解析（纯函数，无 virtual:theme/config 依赖）。
+ *
+ * 独立成模块的原因：astro.config 的静态 import 链（index.ts → plugins/rehype.ts）
+ * 在 astro 配置加载期求值，彼时 virtual:theme/config 尚未注册，顶层 import 会直接
+ * 报 "Cannot find module"。需要 lang 的调用方（路由/组件走 i18n/index.ts 的 t()；
+ * node 侧插件走本模块的 resolveLabel + 显式传入的 config.lang）。
+ */
+
+import en from "./en.js";
+import zhCN, { type UiKey } from "./zh-CN.js";
+
+type Pack = Partial<Record<UiKey, string>>;
+
+/** 已内置语言包（键为归一化 lang：小写、下划线转连字符） */
+const packs: Record<string, Pack> = {
+	en: en,
+	"en-us": en,
+	"en-gb": en,
+};
+
+function norm(lang: string): string {
+	return lang.toLowerCase().replace(/_/g, "-");
+}
+
+function resolvePack(lang: string): Pack {
+	const l = norm(lang);
+	if (packs[l]) return packs[l];
+	const base = l.split("-")[0];
+	if (packs[base]) return packs[base];
+	return zhCN;
+}
+
+/** 取 UI 文案；vars 替换 {name} 占位符；缺译回退中文键源 */
+export function resolveLabel(
+	lang: string,
+	key: UiKey,
+	vars?: Record<string, string | number>,
+): string {
+	let s: string = resolvePack(lang)[key] ?? zhCN[key];
+	if (vars) {
+		for (const [k, v] of Object.entries(vars)) {
+			s = s.replaceAll(`{${k}}`, String(v));
+		}
+	}
+	return s;
+}
+
+export type { UiKey };

package/src/i18n/zh-CN.ts

@@ -0,0 +1,184 @@
+/**
+ * 中文语言包（键源）：UiKey 由本文件的键推导。
+ * 约定：占位符用 {name} 形式，t(key, vars) 调用处替换。
+ * 新增文案先在这里加键，再同步 en.ts（类型会强制检查完整性）。
+ */
+const zhCN = {
+	/* 全局框架（BaseLayout） */
+	skipToContent: "跳到主要内容",
+	backToTop: "回到顶部",
+	/* Header */
+	mainNav: "主导航",
+	toggleMode: "切换深浅模式",
+	menu: "菜单",
+	palette: "调色",
+	paletteTitle: "主题色",
+	reset: "重置",
+	hueValue: "色相 {n}",
+	/* PostCard / 文章元信息 */
+	pinned: "置顶",
+	wordsCount: "{n} 字",
+	minutesCount: "约 {n} 分钟",
+	/* PostNav */
+	prevNext: "上下篇",
+	prevPost: "上一篇",
+	nextPost: "下一篇",
+	firstPost: "已经是最早的一篇",
+	lastPost: "已经是最新的一篇",
+	/* 相关/随机文章推荐（M3b-b9）：noRandomPosts 经 data-empty-html 带入客户端 */
+	relatedPosts: "相关文章",
+	randomPosts: "随机文章",
+	smartRecommend: "智能推荐",
+	randomRecommend: "随机推荐",
+	noRelatedPosts: "暂无相关文章",
+	noRandomPosts: "暂无随机文章",
+	/* License */
+	licensePrefix: "本文采用",
+	licenseSuffix: "许可，转载请注明出处与作者。",
+	/* Toc */
+	toc: "目录",
+	tocTitle: "目 录",
+	/* Pagination */
+	pagination: "分页",
+	prevPage: "上一页",
+	nextPage: "下一页",
+	pageOf: "第 {current} / {total} 页",
+	/* Sidebar */
+	closeAnnouncement: "关闭公告",
+	closeAd: "关闭广告",
+	categories: "分类",
+	tags: "标签",
+	friendLinks: "友链",
+	siteInfo: "站点信息",
+	posts: "文章",
+	running: "已运行",
+	daysCount: "{n} 天",
+	dayPostsCount: "{n} 篇",
+	heatWeekTip: "{m}第{w}周 · {n}",
+	/* §4.47 日历头改造 / §4.48 标签卡更多入口 */
+	tagsMore: "…更多",
+	calendarHome: "回到本月",
+	calendarPick: "选择年月",
+	/* 列表 / 聚合页 */
+	/* 列表形态切换（§4.34） */
+	layoutSwitch: "切换列表 / 网格视图",
+	layoutList: "列表视图",
+	layoutGrid: "网格视图",
+	emptyPosts: "还没有文章，去 content/posts 里写一篇吧。",
+	pageN: "第 {n} 页",
+	archive: "归档",
+	home: "首页",
+	categoryNav: "分类导航",
+	more: "更多",
+	totalPosts: "共 {n} 篇文章",
+	postsInYear: "{n} 篇",
+	yearUnit: "{n} 年",
+	totalTags: "共 {n} 个标签",
+	tagTitle: "标签：{tag}",
+	totalCategories: "共 {n} 个分类",
+	categoryTitle: "分类：{category}",
+	publishedOn: "{date} 发布",
+	updatedOn: "{date} 更新",
+	pageviews: "浏览量",
+	/* 404 */
+	notFound: "页面不存在",
+	notFoundDesc: "页面不存在，或已被移动到别处。",
+	backHome: "返回首页",
+	/* 独立页 */
+	about: "关于",
+	aboutEmpty: "在 src/content/spec/about.md 中编写本页内容",
+	avatarAlt: "{name} 的头像",
+	noFriends: "还没有友链",
+	applyFriend: "申请友链",
+	guestbook: "留言板",
+	guestbookSub: "欢迎留下你的足迹",
+	commentComingSoon: "评论区即将开放，敬请期待。",
+	qrAlt: "{name} 收款码",
+	goSponsor: "前往打赏",
+	qrPlaceholder: "收款码占位",
+	sponsorList: "打赏名单",
+	noSponsors: "还没有打赏，快来做第一个吧",
+	/* 搜索（M3b-b6）：search 用于 placeholder（服务端渲染），其余经 #qy-ui-labels 带入客户端 */
+	search: "搜索",
+	searchShortcut: "按 / 或 Ctrl+K 快速搜索",
+	searchLoading: "搜索中…",
+	searchNoResults: "没有找到相关结果",
+	searchUnavailable: "搜索索引需构建后可用",
+	searchTypeSomething: "输入关键词开始搜索",
+	/* 画廊（M3b-b8）：title/description 走主题配置，这里只放 UI 通用文案 */
+	galleryPhotos: "{n} 张照片",
+	backToAlbums: "返回相册",
+	searchAlbums: "搜索相册…",
+	allTags: "全部",
+	galleryNoAlbums: "还没有相册，在主题配置 gallery.albums 中添加。",
+	galleryNoPhotos: "相册里还没有照片",
+	encryptedAlbum: "加密相册",
+	searchAlbumNoResults: "没有匹配的相册",
+	/* 加密文章（M3b-b7）：postEncrypted 用于列表/文章 meta 标记，其余构建期渲染进锁 UI */
+	postEncrypted: "已加密",
+	passwordProtected: "密码保护",
+	passwordProtectedDesc: "此内容已被密码保护，请输入密码查看。",
+	passwordHint: "提示",
+	passwordPlaceholder: "请输入密码",
+	passwordSubmit: "解锁",
+	passwordError: "密码错误，请重试。",
+	/* 客户端动态文案（构建期经 BaseLayout 的 #qy-ui-labels JSON 载体带入；close/prevImage/nextImage/fullscreen/slideshow/thumbs 供 PhotoSwipe，§4.69-§4.71） */
+	close: "关闭",
+	prevImage: "上一张",
+	nextImage: "下一张",
+	copied: "已复制",
+	fullscreen: "全屏",
+	slideshow: "自动播放",
+	thumbs: "缩略图条",
+	/* 分享海报（M3b-b9.6） */
+	sharePoster: "生成分享海报",
+	generatingPoster: "海报生成中…",
+	copyLink: "复制链接",
+	savePoster: "保存海报",
+	scanToRead: "扫码阅读全文",
+	author: "作者",
+	/* 文章页支持卡（打赏入口 + 分享海报） */
+	supportTitle: "支持一下",
+	supportDesc: "如果这篇文章对你有帮助，欢迎打赏或分享。",
+	sponsorMe: "打赏支持",
+	/* 文章过时提醒 */
+	lastModifiedPrefix: "最后更新于 ",
+	lastModifiedDaysAgo: "，距今已过 {days} 天",
+	lastModifiedOutdated: "部分内容可能已过时，请注意信息时效。",
+	/* 专题（§4.31）：frontmatter series 聚合页与文章页专题导航 */
+	series: "专题",
+	seriesTotal: "共 {n} 个专题",
+	seriesPostsCount: "{n} 篇",
+	seriesUpdated: "更新于 {date}",
+	seriesEmpty: "还没有专题，在文章 frontmatter 中填写 series 字段即可创建。",
+	seriesProgress: "{cur} / {total}",
+	seriesCatalog: "专题目录",
+	/* 音乐播放器（§4.36）：data-labels 经组件 data-labels 属性带入客户端 */
+	musicOpen: "音乐播放器",
+	musicClose: "收起播放器",
+	musicPlay: "播放",
+	musicPause: "暂停",
+	musicPrev: "上一首",
+	musicNext: "下一首",
+	musicModeList: "列表循环",
+	musicModeOne: "单曲循环",
+	musicModeRandom: "随机播放",
+	musicLyrics: "歌词",
+	musicPlaylist: "播放列表",
+	musicNoLyrics: "暂无歌词",
+	musicEmpty: "播放列表为空",
+	musicSeek: "播放进度",
+	musicVolume: "音量",
+	l2dHome: "回到主页",
+	l2dScrollTop: "回到顶部",
+	l2dSleep: "休息一下",
+	l2dSwitchModel: "换个模型",
+	/* 代码折叠（§4.61）：Expressive Code pluginCollapsible 选项文案（node 侧消费） */
+	codeFoldExpand: "展开代码",
+	codeFoldCollapse: "收起代码",
+	codeFoldExpanded: "代码已展开",
+	codeFoldCollapsed: "代码已收起",
+} as const;
+
+export type UiKey = keyof typeof zhCN;
+export default zhCN;

package/src/icons.ts

@@ -0,0 +1,71 @@
+/**
+ * 社交图标解析（§4.65 标准化迁移）：自研 SVG 表退役，改走 astro-icon + Iconify
+ * 标准生态——构建期内联渲染、无运行时请求，语义与参考项目一致。
+ *
+ * icon 字段解析优先级（Sidebar 资料卡）：
+ *   1. "<" 开头 → 内联 SVG 字符串（§4.59 向后兼容，调用方 set:html 直出）
+ *   2. 含 ":" → Iconify 全名（如 "tabler:home"），直接透传 <Icon>；
+ *      站点装任意 @iconify-json/* 集合包即可扩展
+ *   3. 内置简名 → 查 NAMED_ICONS 映射表（下方）
+ *   4. 标准库未收录品牌 → 查 FALLBACK_ICONS 内联兜底（仅 douyin）
+ *   5. 未命中 → 返回 null，调用方跳过图标只渲染文字
+ *
+ * 简名映射的数据来源与许可：
+ *   - 线性图标 → lucide（ISC）：github/email/rss，与原内置 SVG 同源，视觉零变化
+ *   - 品牌图标 → simple-icons（CC0）：微博在其中的规范名为 sinaweibo
+ */
+export interface ResolvedIcon {
+	/** Iconify 全名（"collection:name"），交给 astro-icon 的 <Icon> 渲染 */
+	name?: string;
+	/** 标准库未收录品牌的内联 SVG 兜底，调用方 set:html 直出 */
+	html?: string;
+}
+
+/** 内置简名 → Iconify 全名 */
+const NAMED_ICONS: Record<string, string> = {
+	github: "lucide:github",
+	email: "lucide:mail",
+	rss: "lucide:rss",
+	qq: "simple-icons:qq",
+	wechat: "simple-icons:wechat",
+	weibo: "simple-icons:sinaweibo",
+	bilibili: "simple-icons:bilibili",
+	xiaohongshu: "simple-icons:xiaohongshu",
+	x: "simple-icons:x",
+	telegram: "simple-icons:telegram",
+	youtube: "simple-icons:youtube",
+	instagram: "simple-icons:instagram",
+	linkedin: "simple-icons:linkedin",
+	discord: "simple-icons:discord",
+	steam: "simple-icons:steam",
+	zhihu: "simple-icons:zhihu",
+	gitee: "simple-icons:gitee",
+	juejin: "simple-icons:juejin",
+	csdn: "simple-icons:csdn",
+};
+
+/** 常用别名 → 规范名（如微信拼音/旧称） */
+const ALIASES: Record<string, string> = { weixin: "wechat", twitter: "x" };
+
+// simple-icons 未收录抖音官方形（tiktok 为国际版），保留 CC0 单色内联兜底；
+// 上游收录后可将该条并入 NAMED_ICONS
+const FALLBACK_ICONS: Record<string, string> = {
+	douyin:
+		'<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path fill="currentColor" d="M12.525.02c1.31-.02 2.61-.01 3.91-.02c.08 1.53.63 3.09 1.75 4.17c1.12 1.11 2.7 1.62 4.24 1.79v4.03c-1.44-.05-2.89-.35-4.2-.97c-.57-.26-1.1-.59-1.62-.93c-.01 2.92.01 5.84-.02 8.75c-.08 1.4-.54 2.79-1.35 3.94c-1.31 1.92-3.58 3.17-5.91 3.21c-1.43.08-2.86-.31-4.08-1.03c-2.02-1.19-3.44-3.37-3.65-5.71c-.02-.5-.03-1-.01-1.49c.18-1.9 1.12-3.72 2.58-4.96c1.66-1.44 3.98-2.13 6.15-1.72c.02 1.48-.04 2.96-.04 4.44c-.99-.32-2.15-.23-3.02.37c-.63.41-1.11 1.04-1.36 1.75c-.21.51-.15 1.07-.14 1.61c.24 1.64 1.82 3.02 3.5 2.87c1.12-.01 2.19-.66 2.77-1.61c.19-.33.4-.67.41-1.06c.1-1.79.06-3.57.07-5.36c.01-4.03-.01-8.05.02-12.07"/></svg>',
+};
+
+/**
+ * 按图标名解析（§4.59/§4.65）：trim + 小写 + 别名归一，
+ * 命中返回 { name }（Iconify 全名）或 { html }（内联兜底），
+ * 未命中返回 null（调用方跳过图标、只渲染文字）。
+ */
+export function resolveThemeIcon(raw: string): ResolvedIcon | null {
+	const key = raw.trim().toLowerCase();
+	if (!key) return null;
+	// Iconify 全名直接透传（扩展点）
+	if (key.includes(":")) return { name: key };
+	const canonical = ALIASES[key] ?? key;
+	if (NAMED_ICONS[canonical]) return { name: NAMED_ICONS[canonical] };
+	if (FALLBACK_ICONS[canonical]) return { html: FALLBACK_ICONS[canonical] };
+	return null;
+}