diff --git a/docs/superpowers/specs/2026-06-22-blur-up-images-design.md b/docs/superpowers/specs/2026-06-22-blur-up-images-design.md
new file mode 100644
index 0000000..eaab458
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-22-blur-up-images-design.md
@@ -0,0 +1,313 @@
+# 文章图片 Blur-up 渐进加载设计
+
+## 背景与目标
+
+文章页面的缩略图（卡片封面 `?thumb=400x300`、详情封面 `?w=1200`、正文图 `?w=800`）在加载过程中**没有任何占位**：`![]()
` 裸标签无 width/height/aspect-ratio，加载时区域高度为 0，加载完撑开——导致 CLS（布局跳动）明显，尤其在列表页和长文章里。
+
+本设计的目标：
+- 加载前先显示**低分辨率模糊占位图**（`?w=20`），消除空白与跳动
+- 加载完高清缩略图后，**平滑过渡**到清晰（opacity 淡入）
+- 服务端 SSR 内嵌占位图（渐进增强，JS 禁用也能看到占位）
+- 三处图片位置（卡片封面、详情封面、正文图）统一应用
+
+## 关键决策
+
+| 决策点 | 选择 |
+|--------|------|
+| 占位图来源 | SSR 内嵌（HTML 里 img src 就是占位图 URL，JS 替换高清） |
+| 过渡实现 | 双层叠加 + opacity 淡入（底层占位图常驻，上层高清图淡入覆盖） |
+| 作用范围 | 三处都加（卡片封面、详情封面、正文图） |
+| 占位图尺寸 | 统一 `?w=20` |
+| DOM 生成方式 | 方案 A：SSR 渲染双层结构 + JS 接管高清加载 |
+| aspect-ratio 尺寸来源 | 方案 B2：渲染时实时读图片 header + moka 缓存（零迁移） |
+| 外链图 | 不处理（保持原生 img，无法生成占位图） |
+| dimensions 缓存 TTL | 24h，可通过 `IMAGE_DIMENSIONS_CACHE_TTL_SECS` 环境变量配置 |
+
+## 技术约束（探索结论）
+
+- **服务端图片能力现成**：`/uploads/{path}` 支持 `?w=`/`?thumb=`，已有内存+磁盘两级缓存（`src/api/image.rs`）。`?w=20` 产出 <1KB 的极小图。
+- **sanitizer 约束**：当前 `clean_post_html` 对 img 只放行 `src/alt/width/height/align`，对 span 放行 `class`。双层结构需要额外放行 `data-src`/`class`/`style`（img）和 `style`（span）。评论配置不动。
+- **现有缓存是异步的**：`src/cache.rs` 用 `moka::future::Cache`（`.get().await`），但 `render_markdown_enhanced` 是同步函数。dimensions 缓存需要用 `moka::sync::Cache`（同步版本）。
+- **webp 尺寸读取可行**：`zenwebp::WebPDecoder::build(data)` + `.info()` 只解析 WebP header（RIFF chunk）就能拿到 width/height，**不需要全量解码像素**（见 `src/webp.rs:143-145` 现有代码在 decode 前就读了 info）。开销极小。GIF/PNG/JPEG 走 `image::ImageReader::into_dimensions()`（只读 header）。
+- **上传后磁盘格式**：非 gif/webp 统一转 webp，gif 保持 gif，webp 保持 webp。所以 dimensions 读取要支持 webp + gif/png/jpeg。
+
+## 详细设计
+
+### 架构总览
+
+```
+SSR 渲染文章/封面时
+ ↓
+对每张 /uploads/ 图片:
+ ├─ get_image_dimensions(path) → (w, h) [sync moka cache + 读 header]
+ └─ 产出双层 DOM:
+
+ 
← SSR 内嵌,立即加载
+ ![]()
← JS 懒加载
+
+
+前端 JS (post-content.js / image-viewer 初始化)
+ ├─ IntersectionObserver 监听 .blur-img 进入视口
+ ├─ 把 .blur-img-full 的 data-src 赋给 src → 触发高清图加载
+ └─ 高清图 onload → 加 .is-loaded class → CSS opacity 0→1 淡入
+```
+
+### 1. Dimensions 缓存与读取（新增）
+
+**`src/api/image.rs` 新增**（`#[cfg(feature = "server")]`）：
+
+```rust
+use moka::sync::Cache;
+use std::sync::LazyLock;
+use std::time::Duration;
+
+static IMAGE_DIMENSIONS_CACHE: LazyLock> = LazyLock::new(|| {
+ let ttl = std::env::var("IMAGE_DIMENSIONS_CACHE_TTL_SECS")
+ .ok()
+ .and_then(|s| s.parse::().ok())
+ .map(Duration::from_secs)
+ .unwrap_or(Duration::from_secs(86400)); // 默认 24h
+ Cache::builder().time_to_live(ttl).build()
+});
+
+/// 读取图片真实尺寸（只读 header，不解码像素）。
+/// 路径如 "2026/06/22/xxx.webp"（不含 /uploads/ 前缀）。
+/// 失败返回 None（渲染时回退到不设 aspect-ratio）。
+pub fn get_image_dimensions(rel_path: &str) -> Option<(u32, u32)> {
+ if let Some(dims) = IMAGE_DIMENSIONS_CACHE.get(rel_path) {
+ return Some(dims);
+ }
+ let full_path = std::path::Path::new("uploads").join(rel_path);
+ let data = std::fs::read(&full_path).ok()?;
+ let dims = read_dimensions_from_bytes(&data, rel_path)?;
+ IMAGE_DIMENSIONS_CACHE.insert(rel_path.to_string(), dims);
+ Some(dims)
+}
+
+/// 按扩展名分发：webp 走 zenwebp header，其他走 image crate。
+fn read_dimensions_from_bytes(data: &[u8], path: &str) -> Option<(u32, u32)> {
+ let ext = std::path::Path::new(path).extension()?.to_str()?.to_lowercase();
+ match ext.as_str() {
+ "webp" => {
+ let decoder = zenwebp::WebPDecoder::build(data).ok()?;
+ let info = decoder.info();
+ Some((info.width, info.height))
+ }
+ "gif" | "png" | "jpg" | "jpeg" => {
+ let reader = image::ImageReader::new(std::io::Cursor::new(data))
+ .with_guessed_format().ok()?;
+ reader.into_dimensions().ok()
+ }
+ _ => None,
+ }
+}
+```
+
+**注意**：这是同步函数，在 server function 的异步上下文里同步读文件头。文件头很小（几十到几百字节），开销可接受；moka cache 命中时不读盘。`std::fs::read` 读整个文件——优化点：可改为只读前 N 字节（webp/jpeg/png/gif 的 header 都在前几百字节内），但首版用 `std::fs::read` 保持简单，配合 cache 降低频率。
+
+### 2. 双层 DOM 结构
+
+```html
+
+ 
+ ![...]()
+
+```
+
+- **`span.blur-img`**：相对定位容器，`aspect-ratio: var(--ar)` 预留空间（零 CLS），`overflow: hidden` 裁剪模糊边缘
+- **`img.blur-img-placeholder`**：SSR 内嵌的 `?w=20` 占位图，绝对定位填满容器，CSS 模糊放大
+- **`img.blur-img-full`**：`data-src` 存高清 URL，初始无 src（不立即加载），JS 接管；绝对定位，初始 `opacity: 0`，加载完 `.is-loaded` → `opacity: 1`
+
+`--ar` 由服务端用 `get_image_dimensions` 拿到的真实宽高生成（如 `16/9`）。dimensions 读取失败时不设 `--ar`，退化为无 aspect-ratio（轻微 CLS，但不阻塞渲染）。
+
+### 3. Markdown 渲染器改造（`render_markdown_enhanced`）
+
+正文图转换发生在 Markdown→HTML 阶段。当前用 `pulldown_cmark::html::push_html` 产出 `
`。
+
+**改造**：在 `push_html` 产出 HTML 后、`clean_html` 之前，对字符串里的 `![]()
` 做后处理：
+
+```rust
+fn wrap_images_with_blur(html: &str) -> String {
+ // 用正则/简单解析找到 
标签
+ // 对每个匹配的 img:
+ // 1. 提取 src（如 /uploads/2026/06/22/x.webp）
+ // 2. 从 src 解析出 rel_path（去掉 /uploads/ 前缀和 query）
+ // 3. get_image_dimensions(rel_path) → (w,h)，算 --ar
+ // 4. 生成双层结构替换原 img
+ // 非 /uploads/ 的外链图不处理（保持原样）
+}
+```
+
+**正则选择**：用 `regex` crate（已是 server feature 的 optional 依赖）匹配 `]*src="(/uploads/[^"?]+)[^"]*"[^>]*>`。注意 HTML 用正则有边界情况，但 img 标签由 pulldown-cmark 生成，格式可控（属性顺序固定：src 在前，alt 在后）。
+
+### 4. ImageViewer 改造（卡片封面 / 详情封面）
+
+`ImageViewer` 当前渲染单层 img + 灯箱。改为渲染双层结构：
+
+```rust
+ImageViewer {
+ src: cover.clone(),
+ thumb_params: "?w=1200", // 高清尺寸 → data-src
+ placeholder_params: "?w=20", // 占位图尺寸
+ alt: "封面图片",
+}
+```
+
+ImageViewer 内部：
+- **dimensions 获取**：组件内部调用 `get_image_dimensions`（`#[cfg(feature = "server")]`）。SSR 渲染时组件树在服务端执行，server-only 函数可用；dimensions 有 moka 缓存，命中时是内存查询，miss 时读小文件头。调用方（`post_card.rs`/`post_cover.rs`）无需改动 dimensions 相关逻辑。WASM 端无法调此函数，但图片的 `--ar` 在 SSR 阶段已渲染进 HTML，前端无需再算。
+- 底层 placeholder：`src = {原图}{placeholder_params}`
+- 上层 full：`data-src = {原图}{thumb_params}`
+- `--ar` 由 dimensions 计算，SSR 时写入 `style`
+- 灯箱逻辑不变（点击用原图 src 放大）
+
+`get_image_dimensions` 在组件里调用属于 SSR 渲染时的同步读盘。首版接受这个阻塞（小文件 + cache）；如 SSR 性能成问题，后续可改为 server function 预算 + 模型字段传递。
+
+### 5. post-content.js 改造
+
+当前职责：把 img.src 改成 `?w=800`、加灯箱。
+
+**新职责**：
+- **不再改 src**（渲染器已产出双层结构，placeholder src 已是 `?w=20`）
+- **加载高清图**：用 `IntersectionObserver` 监听 `.blur-img` 进入视口，把 `.blur-img-full` 的 `data-src` 赋给 `src`
+- **触发淡入**：高清 img 的 `onload` 加 `.is-loaded` class，CSS 控制 opacity 过渡
+- **灯箱**：保留现有点击放大。灯箱用 `.blur-img-full` 的 `data-src`（高清图 URL）作为放大图源——灯箱是看大图，应用高清版本而非 20px 占位图。
+
+```javascript
+function initBlurUp(root) {
+ var containers = root.querySelectorAll('.blur-img');
+ if (!('IntersectionObserver' in window)) {
+ // 不支持 IO 的浏览器：直接加载所有
+ containers.forEach(loadFull);
+ return;
+ }
+ var io = new IntersectionObserver(function(entries) {
+ entries.forEach(function(entry) {
+ if (entry.isIntersecting) {
+ loadFull(entry.target);
+ io.unobserve(entry.target);
+ }
+ });
+ }, { rootMargin: '200px' });
+ containers.forEach(function(c) { io.observe(c); });
+}
+
+function loadFull(container) {
+ var full = container.querySelector('.blur-img-full');
+ if (!full || !full.dataset.src) return;
+ full.onload = function() { full.classList.add('is-loaded'); };
+ full.src = full.dataset.src;
+}
+```
+
+### 6. CSS
+
+新增到全局样式（`input.css` 或对应样式入口）：
+
+```css
+.blur-img {
+ position: relative;
+ display: block;
+ overflow: hidden;
+ aspect-ratio: var(--ar);
+ background: var(--color-paper-code-bg, #f5f5f5); /* 加载中灰底 */
+}
+.blur-img-placeholder {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+ filter: blur(20px) saturate(1.2);
+ transform: scale(1.1); /* 放大遮住 blur 边缘 */
+}
+.blur-img-full {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+ opacity: 0;
+ transition: opacity 0.4s ease;
+ z-index: 1;
+}
+.blur-img-full.is-loaded {
+ opacity: 1;
+}
+```
+
+暗色模式：`.blur-img` 的 background 用暗色灰底。
+
+### 7. sanitizer 配置扩展
+
+`clean_post_html`（文章专用）扩展放行属性：
+- img：额外放行 `data-src`、`class`、`style`
+- span：额外放行 `style`（用于 `--ar`）
+
+评论配置（`clean_comment_html`）**不动**（评论无 img）。
+
+## 实现边界与清单
+
+### 服务端（`#[cfg(feature = "server")]`）
+
+| 文件 | 改动 |
+|------|------|
+| `src/api/image.rs` | 新增 `IMAGE_DIMENSIONS_CACHE`（moka sync）+ `get_image_dimensions` + `read_dimensions_from_bytes` |
+| `src/api/markdown.rs` | `render_markdown_enhanced` 增加 `wrap_images_with_blur` 后处理（在 clean_html 前） |
+| `src/api/sanitizer.rs` | `clean_post_html` 扩展 img 放行 `data-src/class/style`、span 放行 `style` |
+
+### 前端（Rust 组件）
+
+| 文件 | 改动 |
+|------|------|
+| `src/components/image_viewer.rs` | 渲染双层结构（placeholder + full），接收 dimensions/aspect-ratio |
+| `src/components/post_card.rs` | 调 ImageViewer 时传入 dimensions（SSR 算好） |
+| `src/components/post/post_cover.rs` | 同上 |
+
+### 前端（JS）
+
+| 文件 | 改动 |
+|------|------|
+| `public/js/post-content.js` | 删除改 src 逻辑；新增 IntersectionObserver 懒加载 + onload 淡入；灯箱改用 data-src |
+
+### 样式
+
+| 文件 | 改动 |
+|------|------|
+| `input.css`（或全局样式入口） | 新增 `.blur-img*` 样式（含暗色模式） |
+
+### 配置
+
+| 文件 | 改动 |
+|------|------|
+| `.env.example` | 新增 `IMAGE_DIMENSIONS_CACHE_TTL_SECS=86400` |
+
+### 不做的事
+
+- 不改评论图片（评论无 img）
+- 不处理外链图（非 `/uploads/` 的图保持原生 img）
+- 不给上传流程加尺寸持久化（B2 方案零迁移，实时读 + 缓存）
+- 不做 LQIP 之外的图片优化（avif 转码、响应式 srcset 等）
+- 不改图片服务端点（`/uploads/{path}` 的 `?w=` 能力现成）
+
+## 实现风险
+
+1. **正则解析 img 标签**：`wrap_images_with_blur` 用正则匹配 img。pulldown-cmark 产出的 img 格式可控（src 在前、alt 在后），但需写测试覆盖各种 src 格式（带/不带 query、外链、相对路径）。
+
+2. **`std::fs::read` 读全文件**：首版 `get_image_dimensions` 读整个文件再解析 header。对大图（几 MB）有内存/IO 开销。优化：改为只读前 N 字节（webp/jpeg/png/gif header 都在前 100 字节内）。首版保持简单，配合 cache 降低频率，后续可优化。
+
+3. **SSR 阶段 ImageViewer 拿 dimensions**：ImageViewer 是通用组件，dimensions 是 server-only。需在 SSR 上层（post_card/post_cover）算好传入，避免组件内部调用 server-only 函数。
+
+## 验收标准
+
+- [ ] 文章正文图片加载时先显示模糊的 `?w=20` 占位图，无布局跳动（aspect-ratio 预留空间）
+- [ ] 高清缩略图加载完后，opacity 平滑淡入覆盖占位图（0.4s 过渡）
+- [ ] 视口外的高清图不加载（IntersectionObserver 懒加载）
+- [ ] 卡片封面、详情封面同样有 blur-up 效果
+- [ ] 外链图（非 /uploads/）保持原生 img，无 blur-up
+- [ ] JS 禁用时，正文图显示 `?w=20` 模糊占位图（渐进增强，可读但模糊）
+- [ ] dimensions 缓存命中时不读盘（二次访问快）
+- [ ] webp/gif/png/jpeg 图片的尺寸都能正确读取
+- [ ] `.env.example` 含 `IMAGE_DIMENSIONS_CACHE_TTL_SECS=86400`
+- [ ] sanitizer 不误删双层结构的 `data-src`/`class`/`style` 属性
+- [ ] 评论图片不受影响（评论无 img，配置不动）
+- [ ] 点击图片放大（灯箱）功能仍正常工作
+