feat(dev): 主题生成器——选图/拖位置/导出 zip

- dev/theme-builder/index.html：单文件、不联网、图片本地转 WebP
- 预览与线上同机制（pattern + 6 槽 deco + page-image），拖拽反解 calc(50% - Npx)
- 导出 CSS + 图片 + 安装说明，CSS 通过 TestThemeCSSComplete
- 自检：?selftest=1 吐 CSS/zip 字节，?demo=1 载入示例

dev/theme-builder/README.md

@@ -0,0 +1,43 @@
+# 主题生成器（本地单文件）
+
+`index.html` 双击即用，不联网、不起服务、不传图片——所有处理都在浏览器本地完成。
+
+## 用法
+
+1. 打开 `dev/theme-builder/index.html`（推荐 Chrome / Edge）。
+2. 填 slug（= css 文件名，小写字母/数字/连字符）。
+3. 传图：
+   - **背景图**：任意尺寸，会按 `cover` 裁成 1920×1080；
+   - **人物**：透明底 PNG/WebP，会按高度 1.5× 输出；
+   - **道具**（可选）：透明底，会自动在底部烘一层接触阴影。
+4. 拖预览里的虚线框调位置，或右侧滑杆微调；切 1512 / 1280 / 1024 看不同视口。
+5. 点「导出 zip」→ 解压到项目根目录 → 按 zip 里的 `INSTALL-<slug>.txt` 做三步（登记 `[theme] available`、`StaticVersion` +1、重新编译）。
+
+## 它做了什么
+
+- 用**和线上同一套机制**渲染预览：`background-image: pattern, deco(6 层), page-image`，
+  `background-size` / `background-position` 一一对应，不是另画一张示意图。
+- 位置数学和 CSS 一致：`background-position` 的百分比是相对 **(容器宽 − 图宽)**，
+  所以工具里拖出来的「左沿像素」会被反解成 `calc(50% - Npx)`，换视口不会跑位。
+- 图片全部转 WebP 并按目标尺寸重采样，导出前就能看到 KB 数。
+- 生成的 CSS 同时写浅色/深色两块（项目测试 `TestThemeCSSComplete` 要求），
+  10 个必需令牌齐全。
+
+## 它不做什么
+
+- **不抠图**。人物/道具必须是透明底；白底图导出的主题会带一块白。
+- **不做调色**。想统一"雾度"（人物压白 16%、场景 30~38%）得在生成端做，
+  或用 `docs/theme-shiroko-assets-spec.md` 里的公式自己处理。
+- **不写 `[theme] available`**。配置在 `conf/app.ini`，导出包里只给了要粘贴的那一行。
+- **不改代码**。素材是编译期 embed，必须重新 `go build` 才会生效。
+
+## 自检
+
+```
+chrome --headless=old --dump-dom "file:///.../dev/theme-builder/index.html?selftest=1"
+```
+
+会把生成的 CSS 与 zip 字节以 JSON 塞进 `<pre id="selftest">`，可用于回归：
+把 `css` 写成 `static/css/themes/<slug>.css`，跑 `go test ./internal/theme -run TestThemeCSSComplete`。
+
+`?demo=1` 会直接载入示例素材（纯 canvas 画的渐变背景 + 一个剪影），没有图也能先看布局。