主题生成器：素材尺寸按视口自适应 + 导出画质可调

- 尺寸单位 4 档：fit(按高)/fitw(按宽)/px/vh，输出 auto clamp(min(calc(100vh-24px),55%),基准,上限)，下限让位视口 → 自适应单位永不把图撑出屏幕
- fitw 补上宽幅素材：fit 只按高度缩，16:9 素材在 390 竖屏仍出 1001px 宽（照裁）
- 视口预设带高度（含 390×844）；layerMetrics 统一出 CSS/预览框/溢出检测，图层编辑区显示实测尺寸并报越界，可一键按当前视口修好
- 窄屏每层策略（原样/缩小/隐藏）+ 缩放系数；修 @media 只覆盖全局、独立配置页面在手机上从不生效的特异性 bug
- 导出画质：质量滑块（上限 0.95，Skia 在 q=1 切无损会反常）+ 长边上限，改动后从原图重算
- base.css 新增 --tb-page-position（默认 center center，旧主题不受影响），StaticVersion +1
- 新增 ?dump=fit / ?dump=quality 自检，README 与 _scaffold.css 同步

dev/theme-builder/README.md

@@ -63,12 +63,45 @@ http://127.0.0.1:8777/dev/theme-builder/
 
 **装饰图层** —— 每个作用域最多 10 层，三种类型：
 
-- **图片**：从图片池选，按高度定尺寸（宽度自动等比），选中后可直接在画板上拖动；
+- **图片**：从图片池选，选中后可直接在画板上拖动；
 - **光斑**：`radial-gradient`，给空白一点体积，不占位、不会变成贴纸；
 - **线性光**：`linear-gradient`，做窗光/压深。
 
 锚点用 9 宫格 + 像素偏移，生成 `calc(0% + 40px) calc(100% - 36px)` 这种两值形式。
 
+### 尺寸单位 × 视口（「换个屏幕就被裁」的根因）
+
+装饰层是**视口固定层**（`background-attachment: fixed`），所以同一个 `400px` 在 900 高的屏幕上占
+44%、在 768 的旧笔电上占 52%，窄屏上直接被切掉。尺寸单位就是回答「屏幕变小的时候这张图怎么办」：
+
+| 单位 | 生成 | 适合 | 低于 100% 视口时的兜底 |
+| --- | --- | --- | --- |
+| `fit` 自适应·按高度 | `auto clamp(min(calc(100vh - 24px), 231px), 46.67vh, 420px)` | 人物立绘、竖幅道具 | 下限让位给视口，永远不纵向溢出 |
+| `fitw` 自适应·按宽度 | `clamp(min(calc(100vw - 24px), 587px), 70.57vw, 1067px) auto` | 横幅、整屏插画 | 下限让位给视口，永远不横向溢出 |
+| `px` 固定 | `auto 420px` | 需要绝对尺寸（如对齐某个 UI 元素） | 不缩，会裁 |
+| `vh` 视口比例 | `auto 46.67vh` | 一定要占同样屏高的元素 | 无下限 |
+
+**为什么必须有两种自适应**：`fit` 只按高度缩，宽度跟着比例涨 —— 一张 16:9 场景 `h=600` 在 1024 宽下
+是 910px 刚好，在 390 的竖屏上按高度缩完还有 1001px，照样裁两侧。宽幅素材只能按宽度缩。
+`fitw` 就是干这个的。实测同一张 1920×1080 素材：
+
+| 视口 | `px 600` | `fit`（按高） | `fitw`（按宽） |
+| --- | --- | --- | --- |
+| 1512×900 | 1067 宽 | 1067 宽 | 1067 宽 |
+| 1024×768 | 1067 宽 | 910 宽 | 723 宽 |
+| 390×844 | 1067 宽（裁） | 1001 宽（裁） | 366 宽（完整） |
+
+`min(calc(100vh - 24px), 231px)` 这一段是关键：`clamp()` 的下限如果固定成「基准的 55%」，
+屏幕小到连 55% 都放不下时还是会溢出。让下限与视口取小值，自适应单位就不会把图撑出屏幕。
+
+**每个图层底部有一行实测**：`1512×900 下显示 131×420，完整可见（源 300×960）`，
+溢出时会变成橙色 `⚠ 1024×768：左 88px / 右 88px 越界`，并给一个「按 1024×768 修好」按钮
+（改成固定 px 并算出刚好放下的尺寸）。视口栏可以切 1512/1280/1024/820/390 五档 —— 都是真视口高，
+不是只改宽度，因为裁切几乎全由高度决定。
+
+导出前还会再扫一遍，把「哪些层在哪些视口下越界」附在结果里（只提醒，不阻止 ——
+故意让插画出血也是合法设计）。
+
 **每一行都能直接换图**：行里带缩略图 + 「图片」下拉，一眼看到这层用的是哪张。
 之前换图的下拉只出现在「选中那一层」的编辑器里，加上新层又默认绑第一张素材，
 连加三层就全是同一张图，看起来像「每层只能显示这张、换不了」。
@@ -77,13 +110,31 @@ http://127.0.0.1:8777/dev/theme-builder/
 **↑ / ↓ 调层级**。顺序就是层级：`background-image` 的第一层画在最上面，
 所以「谁挡住谁」是靠顺序定的（shiroko 里自行车被人挡住就是这么来的）。
 
-**窄屏** —— 手机上卡片几乎占满屏幕，桌面那套 16:9 场景会被 `cover` 裁成一条无意义纹理，
-固定 px 的人物会被卡片盖住。这一栏可以：指定一张竖版背景图、决定装饰是否退场、
-改断点（默认 900px）。导出时生成对应的 `@media` 块，只写浅色规则
+**窄屏** —— 手机上卡片几乎占满屏幕，桌面那套 16:9 场景会被 `cover` 裁成一条无意义纹理。
+三段优先级从高到低：
+
+1. **隐藏全部装饰层（急停）** —— 一键全关，最省事；
+2. **每层的窄屏策略**：原样 / 缩小到 N%（缩放系数默认 62%）/ 隐藏。缩小是把高度与偏移
+   一起乘系数，锚点不变，所以「贴底靠左」的构图缩完还在原位；
+3. **尺寸单位**：`fit` / `fitw` 的层浏览器会自己按视口缩，**不依赖这段规则**。
+
+这一栏还能指定竖版背景图、改断点（默认 900px）。导出时生成 `@media` 块，只写浅色规则
 （深色块特异性更高，本来就压住它）。
 
-**图片池** —— 上传任意张，浏览器本地转 WebP，画布尺寸 = 原图尺寸（不缩放、不留透明边）。
-导出时只打包实际用到的图。每张图左上角有 `fx` 按钮，进处理面板（处理过的会高亮）。
+⚠️ `@media` 里**每个独立配置的页面都要各写一条** `html[data-theme-style][data-page-scope="x"]`：
+页面覆盖块特异性是 (0,2,1)，只写 `html[data-theme-style]`（0,1,1）的话，
+独立配置的页面在手机上根本不生效（旧版本就是这个 bug）。
+
+⚠️ 竖版图只替换**本来就有背景图**的页面。某页故意配成纯色（`--tb-page-image: none`），
+手机上新塞一张竖图等于改了他的设计。
+
+**整页背景 · 焦点** —— 背景图是 `cover`，宽高比不匹配就必裁。九宫格焦点决定裁哪一边：
+16:9 场景在竖屏上只剩中间一条，人物偏一侧时把焦点挪过去才不会裁到脸。
+生成 `--tb-page-position`（`base.css` 里以 `var(--tb-page-position, center center)` 兜底，
+旧主题不写这个令牌也不会坏）。
+
+**图片池** —— 上传任意张，浏览器本地转 WebP。导出时只打包实际用到的图。
+每张图左上角有 `fx` 按钮，进处理面板（处理过的会高亮）。
 
 ### 图片处理
 
@@ -107,6 +158,29 @@ http://127.0.0.1:8777/dev/theme-builder/
 - **容差别贪**：背景常见 253，白袜子 237，只差 16。容差 16 保得住袜子，30 就吃穿了。
   实测白底立绘去白底后透明占比 46.3%，与手写 floodfill 抠出来的 46.6% 差 0.3%。
 
+## 导出画质
+
+WebP 体积 ≈ 像素数 × 质量。**真正的大头是像素**：CSS 里只显示 400px 高的立绘，
+2 倍屏也只要 800px，上传 3000px 的图纯属白扛。所以顺序是：先砍长边，再降质量。
+
+| 设置 | 默认 | 说明 |
+| --- | --- | --- |
+| 质量 | 0.88 | 0.85~0.9 肉眼几乎看不出差别，低于 0.8 才明显糊 |
+| 长边上限 | 1600 | 只缩不放。整页背景建议 1920/不限制；装饰人物 1200 够用 |
+
+面板底部实时显示 `3 张，共 19KB；最大一张 bg.webp 7KB（1920×1080）`。
+改完立刻按「原图 + fx 参数」重编码全部素材，并报出省了多少 —— 与图片处理同一条非破坏原则，
+来回试不会叠加压缩。
+
+⚠️ 两个反直觉的实测结论（都在 `?dump=quality` 里做了断言）：
+
+- **`quality = 1` 不能用**。Skia 在这个值会切到 WebP 无损模式，输出反常：同一张噪声图
+  q=1 只有 52KB，q=0.95 是 440KB。滑块上限卡 0.95，`canvasAsset` 里也夹一道。
+- **平涂/线稿降质量可能变大**。有损编码对纯色会引入噪点，噪声图 q 从 0.6 到 0.95 体积涨 75%，
+  而平涂图怎么调都是 1KB —— 不能承诺「降 q 一定更小」。这类素材优先调长边。
+
+缩小走 `imageSmoothingQuality = 'high'`，一次缩太多也不会糊成一团。
+
 ## 工程文件与草稿
 
 调主题是连续几十次的活，所以配置必须留得住：
@@ -133,6 +207,9 @@ INSTALL-<slug>.txt
 装饰是否超过 10 层、生成出来的 CSS 每处装饰是不是真的 10 个值），有问题直接列出来，
 不会让你导出后再去等 `go test`。
 
+导出结果会报「几个文件 / 总共多大 / 其中几张图共多大」，并附上「哪些层在哪些视口下越界」——
+看到 `其中 4 张图共 3.2MB` 就该回去调长边上限了。
+
 解压到项目根，然后按 `INSTALL-<slug>.txt` 做三步：
 
 1. `conf/app.ini` 的 `[theme] available` 加上 slug；
@@ -164,6 +241,8 @@ INSTALL-<slug>.txt
 ?dump=fx           跑处理算法自检（13 个断言，输出 JSON）
 ?dump=fxpipe       跑弹窗链路冒烟（打开→改参→预览→落盘→无改动不重编码）
 ?dump=layers       图层/作用域回归（加层默认不绑图、行内换图、自动切独立、新建清空）
+?dump=fit          尺寸自适应回归（五档视口占用、溢出检测、fitw、旧工程兼容、@media 覆盖各作用域）
+?dump=quality      画质回归（q 单调性、q=1 被夹到 0.95、长边上限真的压像素）
 ?dump=fxkey        端到端去白底：载入白底图，统计透明像素比例
 ?loadurl=/static/images/x.webp&fx=x
                    直接把项目里的图当素材载入（不必先下载再上传），fx= 打开处理面板