leafer-x-psd 0.0.1-beta.0 → 0.0.1-beta.1

package/README.md

@@ -327,6 +327,7 @@ for (const { key, kind, layer, width, height } of getResources(frame)) {
 | `semantic-fallback` | 语义化适配器失败，已降级到下一个适配器（通常是位图） |
 | `text-unsupported` | 文字图层的某项属性尚无对应能力（字符级样式、文字变形、水平缩放、段间距） |
 | `text-leading-suspect` | 文字图层的 `leading` 数值不可信，已退回自动行高 |
+| `vector-unsupported` | 形状图层的填充/描边样式尚无对应能力（图案、噪声渐变、angle 类渐变、反相形状等） |
 | `mask-skipped` | 蒙版的部分参数（如羽化、反相）未映射 |
 | `empty-layer` | 图层没有可渲染内容，已跳过 |
 | `filtered` | 被你自己的 `filter` 跳过 |
@@ -390,24 +391,43 @@ setCanvasLimits({ maxSide: 30000 })                // 确实要处理 30000px
 | 文字图层 | `Text`（默认 `text: 'editable'`） | ✅ 亚像素级贴合（见下） |
 | 文字图层（竖排/旋转） | 竖排模拟；旋转来自 `transform` | ✅ |
 | 字体名 | 内置 PS 全名 → 字体族名映射 | ✅ 见下 |
-| 形状图层 | 烘焙成位图 | ❌ 无法矢量化，见下 |
+| 形状图层 | `vmsk` 几何 + `vectorFill`/`vectorStroke` → **`Path`** | ✅ 矢量；样式映射不了时退回位图，见下 |
 | 智能对象 | 烘焙成位图 | ❌ 不展开原始内容 |
 | 调整图层 | — | ❌ 跳过并报 `effect-unsupported`（见下） |
 
 > **当前进度**：M0 ~ M6 均已完成，三个真实样例的还原度都进入个位数误差并锁定为回归基线。
-> 剩余的已知缺口只有 ag-psd 本身不提供数据的部分（形状路径、智能对象内容、CMYK），
-> 以及斜面浮雕/光泽/图案叠加这三类 Leafer 没有等价能力的效果。
+> 剩余的已知缺口只有 ag-psd 本身不提供数据的部分（智能对象内容、CMYK），
+> Leafer 没有等价能力的效果（斜面浮雕/光泽/图案叠加），
+> 以及形状图层里那几类样式（图案填充、噪声渐变、angle 类渐变、反相形状）。
 
-### 为什么形状图层不能矢量化
+### 形状图层的几何在 `vmsk` 里
 
-ag-psd 的 `LayerAdditionalInfo.pathList` 至今仍是 `// TODO: ...` —— **形状图层的几何路径没有暴露**，
-只有 `vectorFill` / `vectorStroke`（填充与描边样式）而没有路径本身。
+`LayerAdditionalInfo.pathList` 至今仍是 `// TODO: ...`，但**那条路不是唯一的路**：
+PSD 里形状图层的几何就存在**矢量蒙版的槽位**（`vmsk` + `vscg` / `vstk`），
+ag-psd 把它报成 `layer.vectorMask`，填充与描边样式报成 `vectorFill` / `vectorStroke`。
 
-所以「形状层 → `Path`」这条路的输入数据根本不存在，只能烘焙。唯一例外是**矢量蒙版**，
-它的路径数据（`layer.vectorMask.paths`）是完整可用的，本插件已经用它实现了可编辑的路径遮罩。
+所以形状图层会直接还原成一个 **Leafer `Path`**（`adapter/vector.ts`）：几何来自
+`vectorMask.paths`，填充来自 `vectorFill`，形状自己的描边来自 `vectorStroke`。
+`vmsk` 的锚点是**文档绝对坐标**（与真矢量蒙版同源），因此 `Path` 的原点落在文档 `(0, 0)`。
 
-出于同样的原因，`content: 'editable'` 目前做不到任何事，本插件不会假装它生效，
-而是给出 `semantic-fallback` 诊断说清楚原因。
+三条实测事实（`test-1.psd` 的「多边形 1」，采样自 `regions.test.ts` 的同一套比对）：
+
+1. **形状层的 `canvas` 已经按形状光栅化过**（四角 alpha 全 0），
+   所以以前"位图 + 矢量蒙版再裁一次"是**重复裁剪**：二次抗锯齿让该层区域差从
+   **0.937 劣化到 1.316**（整图 1.020 → 1.039）；
+2. 改成矢量 `Path` 之后比"只用位图"还要准：该层区域差 0.937（位图）→ 矢量渲染后
+   整图从 1.039 降到 **1.006**（`text: 'editable'` 下 0.990 → **0.957**）；
+3. 因此 `decorator/mask.ts` 对形状图层**不再套那层矢量蒙版** —— 那个 `vmsk` 是几何本身，
+   不是裁剪。
+
+**映射不了就退回位图，不硬撑**：图案填充、噪声渐变、`angle`/`reflected`/`diamond`
+渐变、反相形状（`invert`）都会报 `vector-unsupported` 并交给位图适配器
+（PS 自己光栅化的像素），因为"画一个错的矢量"比"用一张对的位图"更糟。
+形状层自己的描边与**图层效果里的描边**是两回事：前者映射到 `Path` 的 `stroke`，
+后者走效果路径（两者同时启用时的叠加顺序见 [TODO.md](../../TODO.md)）。
+
+出于历史原因说明一句：`content: 'editable'` 目前仍然做不到任何事（形状层已经改走
+`Path` 适配器，不再依赖这个选项），本插件不会假装它生效，而是给出 `semantic-fallback` 诊断。
 
 ### 为什么不烘焙调整图层
 
@@ -619,17 +639,20 @@ npm test
 
 | 样例 | 内容 | `text: 'raster'` | `text: 'editable'` |
 | --- | --- | --- | --- |
-| `test-1.psd` | 像素层、位图+矢量双蒙版、横排/竖排文字、图层组、形状层、负坐标超界 | 1.039 | **0.990** |
+| `test-1.psd` | 像素层、位图+矢量双蒙版、横排/竖排文字、图层组、**形状层**、负坐标超界 | 1.006 | **0.957** |
 | `test-2.psd` | 剪贴蒙版、正片叠底/变亮、投影、双描边、内阴影、内发光、双蒙版 | 3.022 | 3.022 |
 | `test-text.psd` | 横排、旋转 45°、旋转 -31.79°、竖排、微软雅黑、楷体、三行段落 | **1.200** | 1.773 |
 
 **全部样例最优位移都是 (0,0)** —— 任何 1px 平移都会让差异明显劣化，说明不存在
 系统性偏移。位移诊断很关键：整体偏移也会让差异只出现在边缘上，从统计数字里看不出来。
 
-注意 `test-1` 上**语义化文字模式比烘焙模式更准**（0.990 vs 1.039）：用真字体清晰渲染，
+注意 `test-1` 上**语义化文字模式比烘焙模式更准**（0.957 vs 1.006）：用真字体清晰渲染，
 比复用 PS 烘焙的位图更贴合参考图。`test-text` 反过来（1.773 vs 1.200），因为它是纯文字
 样例，烘焙模式直接复用了 PS 自己的文字位图，而语义化模式要重排一遍。
 
+> `test-1` 的数字在形状图层改成矢量 `Path` 之后有所改善（1.039 → 1.006 / 0.990 → 0.957），
+> 原因见「形状图层的几何在 `vmsk` 里」。
+
 ### 文字逐层精度
 
 ```
@@ -691,7 +714,7 @@ ag-psd 解码 : 34 ms  (91%)
 
 ```sh
 npm run dev             # 启动调试台（http://localhost:5173）
-npm test                # 186 个测试（含跑构建产物的冒烟测试）
+npm test                # 197 个测试（含跑构建产物的冒烟测试）
 npm run typecheck
 npm run build           # 打包 ESM + UMD，并生成 types/
 npm run verify:artifact # 构建 + 校验产物（npm publish 前会自动跑）
@@ -699,10 +722,41 @@ npm run pack            # 构建 + 校验 + npm pack，检查会发布哪些文
 
 # 命令行查看一个 PSD 的图层结构（排查偏差的第一手段）
 node packages/psd/scripts/inspect-psd.mjs samples/test-1.psd
+
+# 把每个图层的 canvas 导出成图片 + manifest（要看像素时用它）
+node packages/psd/scripts/export-layers.mjs samples/test-1.psd --composite --with-masks
 ```
 
 只在插件包内工作的话，也可以 `cd packages/psd` 后直接跑上述命令（去掉 `-w` 相关的部分）。
 
+### 两个命令行工具
+
+排查"某个区域和 PS 不一致"时的顺序是：先用 `inspect-psd` 看**结构**（谁是谁、蒙版/矢量/
+效果的原始数据），再用 `export-layers` 看**像素**（PS 自己给每一层的画布长什么样）。
+
+| 工具 | 作用 |
+| --- | --- |
+| `scripts/inspect-psd.mjs` | 打印图层树：盒子、混合模式、蒙版框、`realMask`、矢量路径与首个锚点、`vectorFill`、文字 `transform`、启用中的效果 |
+| `scripts/export-layers.mjs` | 把每个图层的 canvas 导出成图片（默认 PNG，可 `webp`/`jpeg`），目录结构 = 图层树，并写一份 `manifest.json` |
+
+```sh
+node scripts/export-layers.mjs design.psd                 # → ./psd-layers/design/
+node scripts/export-layers.mjs design.psd --flat --format webp --quality 0.9
+node scripts/export-layers.mjs design.psd --with-masks --composite --skip-hidden
+```
+
+导出的 `manifest.json` 里带着每个图层的名字、盒子、混合模式、不透明度、隐藏/剪贴标记、
+启用中的效果、蒙版与矢量信息，可以直接和插件的解析结果逐项对照。
+
+> ⚠️ 导出的 `layer.canvas` 是**图层自身的像素通道，不包含图层效果** ——
+> 效果在 PSD 里只是 `lfx2` 参数，ag-psd 不做渲染（要带效果的参考图，
+> 那是 `--composite` 导出的整幅合成图，Photoshop 自己烘焙的）。
+> 这也解释了为什么插件对位图图层必须自己烘焙效果：
+> 实测拿未烘焙的 canvas 直接顶替，`test-2.psd` 该层区域差会从 3.31 变成 14.81。
+>
+> 文件名会做净化（图层名是文件内容，可能带 `../`、控制字符、Windows 非法字符），
+> 并会断言不会写到输出目录之外。
+
 > **`dist/` 与 `types/` 不提交进 git**，它们是 `npm run build` 的产物。
 > 因此发布前必须先构建 —— 这件事由包里的 `prepublishOnly` 钩子自动完成，
 > 并且会顺带跑一遍 `test:artifact`（校验 `main`/`module`/`types`/`unpkg`/`exports`
@@ -742,6 +796,7 @@ import { psdToFrame } from 'leafer-x-psd'
 | `__tests__/regions.test.ts` | 分图层区域比对，输出「参考 \| 渲染 \| 差异」并排图 |
 | `__tests__/runtime.test.ts` | 分批切片、规模基准、耗时拆解、取消、资源回收、蒙版裁剪收益 |
 | `__tests__/limits.test.ts` | 配额与不可信输入：画布上限、效果参数钳制、超限降级、URL 来源已移除 |
+| `__tests__/vector.test.ts` | 形状图层 → `Path`：几何/填充/描边、组内坐标、无像素不再丢失、退回位图、真矢量蒙版不回归 |
 | `__tests__/package.test.ts` | **消费 `dist/` 构建产物**：ESM 导入、UMD 的 `LeaferX.psd` 全局、包元信息 |
 
 `package.test.ts` 刻意与源码测试分开：只有真正去用发布出去的东西，才会暴露
@@ -785,10 +840,24 @@ import { psdToFrame } from 'leafer-x-psd'
 - **文字的水平缩放与文字变形**（`horizontalScale` / `warp`）尚未映射，会报 `text-unsupported`。
 - **斜面浮雕 / 光泽 / 图案叠加**在 Leafer 中没有对应能力，会报 `effect-unsupported` 并丢弃。
 - **效果烘焙的近似之处**：膨胀/腐蚀是用「沿圆周多次绘制」逼近的（最多 24 次），
-  大半径下有轻微多边形锯齿；不过效果本身通常带模糊，视觉上不明显。
-- **形状图层无法矢量化**：ag-psd 没有暴露形状路径（见上）。
+  大半径下有轻微多边形锯齿；`shadowBlurScale` 是**全局**一个系数，而投影/外发光/内阴影/
+  内发光在 canvas 上走的是三条不同实现路径；PS 的 `contour` 等高线 / `noise` / `jitter` /
+  `technique` 完全没有表达（用自定义等高线的文件会有系统性偏差）。这些都记在
+  [TODO.md](../../TODO.md) 的 B 节。
+- **形状图层的样式覆盖不完整**：几何与纯色/linear·radial 渐变填充可以矢量化，
+  但图案填充、噪声渐变、`angle`/`reflected`/`diamond` 渐变、反相形状（`invert`）
+  会报 `vector-unsupported` 并退回位图；形状自己的描边与图层效果里的描边同时启用时，
+  叠加顺序尚未处理。
+- **位图图层的效果必须由插件自己烘焙**：`layer.canvas` **不含**图层效果
+  （效果只是 PSD 里的参数），所以"直接用 ag-psd 的画布"等于丢掉效果
+  （实测 `test-2.psd` 该层区域差 3.31 → 14.81）。
 - **智能对象不展开**：只烘焙外观，不解析内嵌的原始文档。
 
+## 待办
+
+已知但尚未做的事（保真度优化、合成图模式、CI 等）统一记在
+[`TODO.md`](../../TODO.md)，`CODE_REVIEW.md` 里是评审结论与当前状态。
+
 ## License
 
 MIT