leafer-x-psd 0.0.1-beta.0

package/README.md

@@ -0,0 +1,794 @@
+# leafer-x-psd
+
+把 **PSD 文件解析成 leaferjs 的 `Frame`** —— leafer-x 生态插件。
+
+只依赖 `@leafer-ui/core` 与 `@leafer-ui/interface`（作为 peer dependency，不打包），
+PSD 解码交给 [ag-psd](https://github.com/Agamnentzar/ag-psd)。
+
+```ts
+import { Leafer } from 'leafer-ui'
+import { psdToFrame } from 'leafer-x-psd'
+
+const frame = await psdToFrame(fileInput.files[0])
+new Leafer({ view: window }).add(frame)
+```
+
+---
+
+## 安装
+
+```sh
+npm i leafer-x-psd
+```
+
+运行时依赖为零 —— `ag-psd` 已经打包进产物，不需要宿主再装（这也让 CDN 全局用法可用）。
+
+宿主环境需要先有 Leafer 平台：
+
+::: code-group
+
+```ts [web]
+import { Leafer } from 'leafer-ui'        // 引入即完成平台初始化
+import { psdToFrame } from 'leafer-x-psd'
+```
+
+```ts [node]
+import { useCanvas } from '@leafer-ui/node'
+import { Canvas, loadImage } from '@napi-rs/canvas'
+import { psdToFrame } from 'leafer-x-psd'
+
+useCanvas('napi', { Canvas, loadImage })  // 初始化 Leafer 的 Node 平台适配
+const frame = await psdToFrame(fs.readFileSync('design.psd'))
+```
+
+:::
+
+> **Node 端为什么必须初始化 Leafer 平台？** ag-psd 是在模块求值时检测 `document`
+> 来决定画布工厂的，浏览器里开箱即用，其他环境则需要有画布来源。而 ag-psd 被打包进
+> 产物后宿主对独立安装的 `ag-psd` 调 `initializeCanvas` 是**无效的**（产物里是另一份
+> 副本）。所以本插件直接从 Leafer 的平台适配 `Platform.origin.createCanvas` 取工厂自动
+> 接上 —— 宿主既然已经能跑 Leafer，这一步就不该再让你操心。
+> 只有自动接管不适用时（例如小程序自定义离屏画布）才需要手动调用插件的
+> [`useCanvas()`](#usecanvas)。
+
+CDN 用法（UMD 全局变量遵循 leafer 插件规范 `LeaferX.插件名`）：
+
+```html
+<script src="https://unpkg.com/leafer-ui"></script>
+<script src="https://unpkg.com/leafer-x-psd"></script>
+<script>
+  const { Leafer } = LeaferUI
+  const { psdToFrame } = LeaferX.psd
+</script>
+```
+
+---
+
+## API
+
+### `psdToFrame(source, options?) => Promise<Frame>`
+
+一步到位：解码 + 构建，返回一个尺寸等于文档、`overflow: 'hide'` 的 `Frame`。
+
+`source` 可以是 `File` / `Blob` / `ArrayBuffer` / `Uint8Array` / `Buffer`。
+
+**不接受 URL 字符串** —— 插件不发任何网络请求，先自己加载成二进制再传进来：
+
+```ts
+const frame = await psdToFrame(await (await fetch('/design.psd')).arrayBuffer())
+```
+
+#### 为什么没有 URL 来源
+
+早期版本接受 URL 字符串并在内部 `fetch`，把它去掉是因为那件事**不属于解析**：
+
+- **取消语义会变浑**。`options.signal` 本该只管「构建到一半停下来」，一旦内部发请求，
+  它就得同时管一个可能已经跑了一半、无法回滚的下载；不接上去又会让「点了取消但还在下载」
+  成为默认行为。
+- **超时与重试是宿主的策略**。1 秒超时还是 30 秒、失败重试几次、要不要带鉴权头、
+  走不走 Service Worker 缓存 —— 插件给不出通用答案，猜一个只会和宿主的 HTTP 层打架。
+- **少一个 SSRF 面**。宿主常把用户输入直接当参数传下去；插件内部持有 `fetch` 时，
+  一句 `psdToFrame(userInput)` 就等于对外开放了一个任意 URL 请求原语。
+- **收益极小**。上面那行 `fetch(...).arrayBuffer()` 已经把这件事说完了。
+
+`Blob` / `File` 仍然直接支持，所以浏览器里从 `<input type="file">`、
+拖放、`URL.createObjectURL` 拿到的对象都不用先读成 `ArrayBuffer`。
+
+### `new PsdParser(source, options?)`
+
+把「解码」与「构建」拆开，适合需要复用或中途取消的场景。
+
+```ts
+const parser = new PsdParser(file)
+
+await parser.ready      // 只解码；可拿到 psd / width / height / layers
+await parser.toFrame()  // 需要时再构建，可传入已有 Frame 复用
+parser.abort()          // 取消
+```
+
+### `psdToContainer(psd, container, options?) => Promise<IUI>`
+
+如果你已经在别处（比如 Worker 里）解码好了 `Psd`，直接用这个把元素树挂到任意容器上。
+
+### 自定义图层适配器
+
+```ts
+import { registerAdapter } from 'leafer-x-psd'
+
+registerAdapter({
+  name: 'my-smart-object',
+  priority: 500,           // 越大越先匹配
+  match: (layer) => !!layer.placedLayer,
+  create: (layer, ctx) => /* 返回 IUI 或 undefined 表示放弃 */,
+})
+```
+
+适配器是**按优先级逐个尝试**的：某一层认领了图层却没能创建出元素（返回
+`undefined` 或抛异常），就会继续往下试，最终由兜底的位图适配器接手，同时报出
+`semantic-fallback` 诊断。单个图层的数据异常不会让整份 PSD 解析崩掉。
+
+### 可编辑性
+
+默认解析结果**只读**。两个选项分别对应两种能力，**互相独立** —— 可以只开一个，也可以都开：
+
+| 选项 | 依赖 | 设置的属性 | 能力 |
+| --- | --- | --- | --- |
+| `editable: true` | `@leafer-in/editor` + `@leafer-in/resize` | `editable` | 选中、缩放、旋转、编组；双击进组 |
+| `draggable: true` | 无（`leafer-ui` 自带交互） | `draggable` | 直接拖动元素 |
+
+> ⚠️ **`editable` 不会连带设置 `draggable`** —— 实测装了编辑器插件也一样：
+>
+> ```
+> editable:true   →  draggable = false
+> editable:true   →  draggable = false   （加载 @leafer-in/editor 之后）
+> ```
+>
+> 文档里「editable 包含了 draggable」指的是编辑器自己有拖动实现，而不是这个属性被连带设置。
+> 所以要把解析结果**同时**用在编辑器和纯 `leafer-ui` 里，就得两个选项都开：
+>
+> ```ts
+> psdToFrame(file, { editable: true, draggable: true })
+> ```
+
+#### 只要可拖动
+
+```ts
+import { Leafer } from 'leafer-ui'
+import { psdToFrame } from 'leafer-x-psd'
+
+const leafer = new Leafer({ view: window })
+leafer.add(await psdToFrame(file, { draggable: true }))
+```
+
+#### 完整编辑器
+
+```sh
+npm i @leafer-in/editor @leafer-in/resize
+```
+
+```ts
+import { App } from 'leafer-ui'
+import '@leafer-in/editor'
+import '@leafer-in/resize'
+import { psdToFrame } from 'leafer-x-psd'
+
+const app = new App({ view: window, editor: {} })
+app.tree.add(await psdToFrame(file, { editable: true }))
+```
+
+于是：**单击选中图层 · 拖动移动 · 拖控制点缩放旋转 · 双击进组**。
+再装上 [`@leafer-in/text-editor`](https://www.npmjs.com/package/@leafer-in/text-editor)
+就能双击文字直接改字（文字层要用默认的 `text: 'editable'`）。
+
+#### 交互单元怎么划分
+
+两个选项共用同一条规则：**可交互性只挂在每个图层最外层的那个元素上**，
+所以一层就是一个单元。容器还会关掉 `hitChildren`。
+
+| 图层 | 谁成为交互单元 |
+| --- | --- |
+| 普通像素层 / 文字层 | 该元素本身 |
+| 带蒙版的图层 | 外层包装容器（遮罩与内容不可单独选中） |
+| 剪贴蒙版组 | 整个剪贴组（基底与被裁剪层不可单独选中） |
+| 图层组 | 整个组；拖/选都是整组 |
+
+容器关掉 `hitChildren` 是与 leafer 编辑器自己编组时的约定一致的 ——
+`editor.group()` 产出的组同样是 `editable = true` + `hitChildren = false`。
+
+> ⚠️ 随之而来的一个差别：`editable` 模式下有编辑器的**双击进组**，所以组内子层仍能被选到；
+> `draggable` 模式没有这个机制，`hitChildren: false` 会把组内子层彻底挡住 ——
+> **拖组就是整组一起动，够不到里面**。需要逐层操作就用 `editable`。
+
+配合 `options.meta`（默认开启），每个元素上都带着 `ui.data.psd` 元数据，
+选中后可以直接反查它是哪个 PS 图层。调试台就是这么做的。
+
+### 资源与持久化
+
+解析出来的每张画布都注册进 Leafer 的全局 `Resource` 表，`Image.url` 是**会话内的资源符**
+（形如 `leafer://psd-plugin-resource-1.png`）。这意味着 **`frame.toJSON()` 出来的结果是不可持久化的** ——
+存库、换个客户端、分享链接，图片全都加载不出来。
+
+这是一个真实存在的限制，不是 bug。要在别的会话里用，必须先把资源符换成真实 URL：
+
+```ts
+import { psdToFrame, exportResources, canvasToBlob } from 'leafer-x-psd'
+
+const frame = await psdToFrame(file)
+
+await exportResources(frame, {
+  resolve: async (canvas, info) => {
+    // info: { key, kind, layer: { id, name, box, isGroup }, width, height }
+    const blob = await canvasToBlob(canvas, 'webp', 0.9)
+    const name = `${info.layer?.name ?? 'unnamed'}-${info.kind}.webp`
+    return (await myOss.put(`psd/${name}`, blob)).url
+  },
+  concurrency: 4,
+  onProgress: (done, total) => console.log(`${done}/${total}`),
+})
+
+const json = frame.toJSON()   // 到这一步才可持久化
+```
+
+`resolve` 是**唯一必需的**回调 —— 上传到对象存储、转 dataURL、配合 zip 写相对路径，
+都由它决定，插件不预设「上传」这件事：
+
+```ts
+// 转 dataURL（小文件、想完全自包含）
+resolve: (canvas) => canvas.toDataURL?.('image/png') ?? ''
+
+// 写进 zip 包，url 用包内相对路径
+resolve: async (canvas, info) => {
+  const name = `${info.layer?.name ?? 'layer'}.png`
+  zip.file(name, Buffer.from(await canvasToBuffer(canvas, 'png')))
+  return `./assets/${name}`
+}
+```
+
+**为什么这是独立的一步、而不是 `psdToFrame` 的选项：** 解析目前全程**零编码**
+（画布直通），这是它最大的性能优势；一旦要求上传就必须先编码，优势就没了。
+而且上传会慢、会失败、需要并发限流与重试 —— 那是存储与网络问题，不是解析问题。
+
+成功替换后会把旧的 `leafer://` 从 `Resource` 表里**摘掉**，立刻省下一份内存。
+
+#### 附带：画布编码工具
+
+插件自身不做编码，这两个小工具是给 `resolve` 用的，抹平浏览器与 Node 的差异
+（`toBlob` / `toBuffer` / `convertToBlob` / `toDataURL` 里挑一个能用的）：
+
+```ts
+canvasToBlob(canvas, 'webp', 0.9)    // → Blob（浏览器上传首选，比 dataURL 少 33% 开销）
+canvasToBuffer(canvas, 'png')        // → Uint8Array（Node 写文件 / 传 SDK）
+```
+
+`format` 支持 `'png' | 'webp' | 'jpeg'`，`quality` 是 0~1、只对后两者有效。
+照片类图层用 `webp` 比 `png` 小很多；蒙版是灰度图，`png` 就够了。
+
+### 资源回收
+
+`Resource` 是一张全局表，本插件注册进去的画布**不会自动释放**。做「能反复打开不同
+PSD」的界面时，旧画布会一直留在表里，内存持续增长。处理完一份 PSD 就释放：
+
+```ts
+const frame = await psdToFrame(file)
+// ... 用户切换到另一份文件时
+releaseResources(frame)      // 返回实际释放的数量
+
+releaseAllResources()        // 不知道具体清单时的兜底（例如热重载）
+```
+
+`getResources(frame)` 可以读出当前还挂着的资源记录（`exportResources` 用的就是它）：
+
+```ts
+for (const { key, kind, layer, width, height } of getResources(frame)) {
+  console.log(kind, layer?.name, `${width}x${height}`, key)
+}
+```
+
+> ⚠️ 资源记录是挂在 `WeakMap` 上的，**不写进 `ui.data`** —— 记录里带着画布引用，
+> 而 `ui.data` 会被 `toJSON()` 序列化，塞进去会把整张位图吐出来。
+
+### `useCanvas(createCanvas, createImageData?)`
+
+手动指定 ag-psd 的画布工厂。只在自动接管不适用时才需要（小程序自定义离屏画布等）。
+
+### 解析选项
+
+| 选项 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `content` | `'raster' \| 'editable'` | `'raster'` | 像素层/形状层内容模式（`'editable'` 目前等价于 `'raster'`，见下） |
+| `text` | `'raster' \| 'editable'` | `'editable'` | 文字层是否还原成可编辑 `Text` |
+| `fontFamily` | `(psdFontName, builtin) => string \| undefined` | 内置别名表 | 覆盖/补充 PS 字体全名到族名的映射 |
+| `shadowBlurScale` | `number` | `0.7` | PS 投影 `size` 与画布 `shadowBlur` 的换算系数（已按真实样例校准） |
+| `mask` | `boolean` | `true` | 图层蒙版（位图 + 矢量） |
+| `vectorMask` | `boolean` | `true` | 矢量蒙版还原成 `Path` 遮罩；关掉则退回 ag-psd 光栅化结果 |
+| `clipping` | `boolean` | `true` | 剪贴蒙版 |
+| `effects` | `boolean` | `true` | 图层效果 |
+| `blendMode` | `boolean` | `true` | 混合模式 |
+| `meta` | `boolean` | `true` | 把 PSD 元数据挂到 `ui.data.psd` |
+| `editable` | `boolean` | `false` | 把元素设为可编辑，配合编辑器插件可直接改（见下） |
+| `draggable` | `boolean` | `false` | 让元素可拖动，**不需要**编辑器插件（见下） |
+| `skipHidden` | `boolean` | `false` | 跳过隐藏图层（否则保留但置为不可见） |
+| `filter` | `(layer) => boolean` | — | 返回 `false` 跳过该图层及其子树 |
+| `fitRoot` | `boolean` | `true` | 根 `Frame` 是否设为文档尺寸并裁剪溢出 |
+| `sliceBudget` | `number` | `12` | 分批构建的时间片预算(ms)，`0` 表示不切分 |
+| `onProgress` | `(p) => void` | — | 进度回调 |
+| `onWarning` | `(w) => void` | — | 诊断回调 |
+| `signal` | `AbortSignal` | — | 取消信号 |
+| `readOptions` | `ReadOptions` | — | 透传给 ag-psd `readPsd` |
+
+### 诊断回调
+
+不支持的 PS 能力不会静默失败，而是通过 `onWarning` 报出来：
+
+| code | 含义 |
+| --- | --- |
+| `blend-mode-unsupported` | 该 PS 混合模式在 Leafer 中没有对应实现，已降级 |
+| `effect-unsupported` | 该图层效果无法映射，已丢弃 |
+| `semantic-fallback` | 语义化适配器失败，已降级到下一个适配器（通常是位图） |
+| `text-unsupported` | 文字图层的某项属性尚无对应能力（字符级样式、文字变形、水平缩放、段间距） |
+| `text-leading-suspect` | 文字图层的 `leading` 数值不可信，已退回自动行高 |
+| `mask-skipped` | 蒙版的部分参数（如羽化、反相）未映射 |
+| `empty-layer` | 图层没有可渲染内容，已跳过 |
+| `filtered` | 被你自己的 `filter` 跳过 |
+| `limit-exceeded` | 文件声明的尺寸/效果参数超出配额，该图层或该效果被跳过（见[安全与配额](#安全与配额)） |
+| `read-error` | 读取 PSD 失败 |
+
+### 安全与配额
+
+**PSD 是不可信输入。** 图层尺寸、蒙版框、图层效果半径全都来自文件内容，而解析发生在
+宿主进程的主线程上、以宿主的权限运行。不加限制的话，一个构造过的文件就能让插件去申请一张
+几万像素见方的画布 —— 那是几百 MB 到几 GB 的一次性分配，进程会直接被打爆。
+
+所以**所有画布分配都过一道配额**，收口点在 `platform.createCanvas`（插件自己算出来的画布）
+与解码期的 ag-psd 画布工厂（那些尺寸同样来自文件）：
+
+| 配额 | 默认 | 说明 |
+| --- | --- | --- |
+| `maxSide` | `16384` | 单边最大像素 —— 浏览器 canvas 的安全上限就是 16384×16384 |
+| `maxPixels` | `32 * 1024 * 1024` | 单张画布最大总像素（约 128MB RGBA） |
+
+效果参数另有量级钳制：`size` 上限 1000px（PS 自己的 UI 上限是 250px）、
+`choke` / spread 上限 100%。
+
+```ts
+import { getCanvasLimits, setCanvasLimits, PsdCanvasLimitError } from 'leafer-x-psd'
+
+getCanvasLimits()                                  // { maxSide: 16384, maxPixels: 33554432 }
+setCanvasLimits({ maxSide: 30000 })                // 确实要处理 30000px 的巨幅海报时放宽
+```
+
+超限时的行为分两种，**都不会让整份 PSD 解析失败**：
+
+- **单个图层/蒙版/效果超限** → 跳过它并报 `limit-exceeded`，其余内容照常渲染
+  （例如蒙版画布超限就只丢蒙版、内容还在）；
+- **解码期就超限**（文件声明的文档/图层尺寸本身越界）→ 抛 `PsdCanvasLimitError`，
+  `readPsdFromSource` 会把它包装成带说明的错误信息，而不是去赌分配能成功。
+
+配额是**进程级**设置（`setCanvasLimits` 影响之后的所有解析），因为解码期的画布工厂拿不到
+单次解析的选项。非法值（`NaN`、负数、0）会被忽略，不会把配额设成"什么都不挡"。
+
+---
+
+## 还原能力矩阵
+
+这是本插件最重要的一张表 —— 哪些能真的还原，哪些做不到。
+
+| PS 概念 | 还原方式 | 状态 |
+| --- | --- | --- |
+| 图层顺序 | 直接对应 Leafer 子元素顺序 | ✅ |
+| 像素图层 | 烘焙成 `Image` | ✅ 像素级一致 |
+| 图层组 | `Group`，原点取子层并集 | ✅ |
+| 图层蒙版（位图） | 灰度图 + `mask: 'grayscale'` | ✅ |
+| 矢量蒙版 | 贝塞尔路径 → `Path` + `mask: 'path'` | ✅ 可编辑 |
+| 剪贴蒙版 | Leafer 原生 `mask: 'clipping'` | ✅ |
+| 混合模式 | 映射表转 Leafer 命名 | ⚠️ 见下 |
+| 图层不透明度 / 可见性 | `opacity` / `visible` | ✅ |
+| 图层效果：投影/内阴影 | 位图层**烘焙进位图**；文字/形状层 → `shadow`/`innerShadow` | ✅ |
+| 图层效果：描边/颜色叠加/渐变叠加 | 位图层烘焙；文字/形状层 → `stroke`/`fill` | ✅ |
+| 图层效果：外发光/内发光 | 位图层烘焙 | ✅ |
+| 图层效果：斜面浮雕/光泽/图案叠加 | — | ❌ 报 `effect-unsupported` |
+| 文字图层 | `Text`（默认 `text: 'editable'`） | ✅ 亚像素级贴合（见下） |
+| 文字图层（竖排/旋转） | 竖排模拟；旋转来自 `transform` | ✅ |
+| 字体名 | 内置 PS 全名 → 字体族名映射 | ✅ 见下 |
+| 形状图层 | 烘焙成位图 | ❌ 无法矢量化，见下 |
+| 智能对象 | 烘焙成位图 | ❌ 不展开原始内容 |
+| 调整图层 | — | ❌ 跳过并报 `effect-unsupported`（见下） |
+
+> **当前进度**：M0 ~ M6 均已完成，三个真实样例的还原度都进入个位数误差并锁定为回归基线。
+> 剩余的已知缺口只有 ag-psd 本身不提供数据的部分（形状路径、智能对象内容、CMYK），
+> 以及斜面浮雕/光泽/图案叠加这三类 Leafer 没有等价能力的效果。
+
+### 为什么形状图层不能矢量化
+
+ag-psd 的 `LayerAdditionalInfo.pathList` 至今仍是 `// TODO: ...` —— **形状图层的几何路径没有暴露**，
+只有 `vectorFill` / `vectorStroke`（填充与描边样式）而没有路径本身。
+
+所以「形状层 → `Path`」这条路的输入数据根本不存在，只能烘焙。唯一例外是**矢量蒙版**，
+它的路径数据（`layer.vectorMask.paths`）是完整可用的，本插件已经用它实现了可编辑的路径遮罩。
+
+出于同样的原因，`content: 'editable'` 目前做不到任何事，本插件不会假装它生效，
+而是给出 `semantic-fallback` 诊断说清楚原因。
+
+### 为什么不烘焙调整图层
+
+调整图层（色阶 / 曲线 / 色相饱和度…）自身没有像素，作用是对**下方内容**做处理。
+Leafer 没有等价的图层混合调整能力，而 ag-psd 给它带的 `canvas` 也**不是**「本层该显示
+什么」。照本位图烘焙会画出错误画面，所以宁可跳过并报诊断，也不产出错的像素。
+
+### Leafer 没有的混合模式
+
+这些 PS 模式会被降级为 `normal` 并报 `blend-mode-unsupported`：
+
+`dissolve` `linear burn` `linear dodge` `darker color` `lighter color`
+`vivid light` `linear light` `pin light` `hard mix` `subtract` `divide`
+
+其余模式都能映射 —— 注意 ag-psd 用**空格**命名（`'color burn'`），Leafer 用**连字符**
+（`'color-burn'`），直接强转一定失败，本插件走映射表。
+
+---
+
+## 实现要点
+
+解析 PSD 的坑大多集中在坐标、顺序和蒙版上。以下是经过实测确认的事实，
+也是本插件与「看起来能跑」的实现的区别所在：
+
+### 1. 图层数组顺序不需要反转
+
+`psd.children` 是**自下而上**的，正好等于 Leafer 的绘制顺序（先 `add` 的在下面）。
+不需要 `reverse()`，也不需要为了排序去摆弄 `zIndex`。
+
+### 2. 所有图层的坐标都是文档绝对坐标 —— 包括组内子层
+
+把带绝对坐标的子层直接塞进一个带 `x/y` 的 `Group`，会产生 `group.x + child.x`
+的**双重偏移，层级越深偏得越多**。
+
+本插件让每个元素的原点等于「自己那个盒的左上角」，进一层容器就重设一次原点，
+保证绝对坐标只被换算一次。
+
+### 3. 图层组的 `right/bottom` 不可信
+
+实测：写入 `(40,55,155,165)` 的组读回来会塌缩成 `(40,55,40,55)`（宽高为 0）。
+真实样例里也见到 `组 1` 的盒是 `[0,0,0,0]` 而子层在 `(138,98)` 和 `(280,49)`。
+
+所以组边界一律由**子层递归求并集**得到，绝不使用组自身的 `right/bottom`。
+
+### 4. 矢量蒙版与位图蒙版可以同时存在
+
+PS 允许一个图层同时有矢量蒙版和像素图层蒙版，两者**取交集**。
+按「矢量优先，否则位图」写会静默丢掉一个。本插件把可用的蒙版逐个嵌套套上去
+（Leafer 每个容器只认一个遮罩元素，嵌套容器天然求交）。
+
+### 5. `canvas.toDataURL()` 是性能陷阱
+
+Leafer 的 `Resource.setImage(key, canvas)` 会把画布存成 `{ url, view }`，
+渲染时**直接使用这张画布**，没有编码、没有 base64、没有二次解码。
+而 `toDataURL()` 每层都要做一次完整 PNG 编码 + base64 展开，再在渲染时解码回来。
+
+### 6. 图片 `mask` 用 `grayscale`，不需要逐像素转换
+
+Leafer 的 `grayscale` 遮罩语义与 PS 图层蒙版完全一致（白=不透明，黑=透明），
+可以直接把灰度图喂进去，省掉一次全画布的 `getImageData`/`putImageData` 往返。
+
+### 7. 分批不能用 `setTimeout(..., 0)`
+
+定时器最小间隔约 4ms，1000 层就是 4 秒以上的纯等待，比同步还慢。
+本插件按**时间片预算**分批（默认 12ms 处理满才让出一帧）。
+
+### 8. Leafer 的 `writingMode` 只有声明，没有实现
+
+`IWritingMode` 是公开类型（`'x' | 'y' | 'x-reverse' | 'y-reverse'`），但 Leafer 2.2 里
+它**只被装饰器注册了属性，没有任何消费它的布局代码**。实测：
+
+```
+默认                    w=68.91  h=30
+writingMode:'y'         w=68.91  h=30   ← 完全一样
+writingMode:'y-reverse' w=68.91  h=30   ← 完全一样
+writingMode:'y' + width w=30     h=90   ← 只是普通折行
+```
+
+所以竖排文字得自己模拟：
+
+- **拉丁文**：PS 的直排就是整段顺时针旋转 90°（`L` 在顶、`M` 在底），
+  所以渲染成横向文本再 `rotation: 90` 即可。
+- **中日韩**：字形保持正向、逐字堆叠，用 `Array.from(text).join('\n')`。
+
+还有一个细节：PS 的竖排基线是**列的中线**，而 Leafer 旋转后的基线不在列中间
+（Leafer 的行盒对基线不对称），所以还要沿交叉轴补一个
+`lineHeight / 2 − (lineHeight / 2 + 0.35 × fontSize)` 的偏移，把列心挪回基线。
+
+### 9. 文字定位锚在基线上，而不是包围盒上
+
+Leafer 的首行基线距盒子顶部的偏移是固定的：
+
+```js
+// @leafer-ui/draw 的文本样式计算
+data.__baseLine = lineHeight - (lineHeight - fontSize * 0.7) / 2
+//              = lineHeight / 2 + 0.35 * fontSize
+```
+
+把 `around` 设为 `{ x: 0, y: 该偏移 }`，就能让「元素内部的基线起点」正好落在元素的
+`(x, y)` 上（Leafer 的 `around` 语义就是「把元素内部的 around 点移动到元素的 x/y」），
+旋转也自然绕基线进行。PS 那边 `text.transform` 的平移量正是基线起点，
+`bounds.left` 是文本起点，两边一对就能精确对齐。
+
+### 10. 打包 ag-psd 会让宿主配不上画布
+
+ag-psd 是在**模块求值时**检测 `typeof document !== 'undefined'` 来决定画布工厂的：
+
+```js
+// ag-psd/dist/helpers.js
+if (typeof document !== 'undefined') {
+  exports.createCanvas = (width, height) => { ... document.createElement('canvas') ... }
+}
+```
+
+浏览器里这就够了，Node / 小程序里则必须显式 `initializeCanvas`。但 **ag-psd 被本插件
+打包进产物后，产物里有自己的一份副本**，宿主对独立安装的 `ag-psd` 调用
+`initializeCanvas` 影响不到它 —— 表现为「源码里跑得好好的，装成包就报 Canvas not
+initialized」。
+
+所以本插件在读取前从 Leafer 的平台适配 `Platform.origin.createCanvas` 自动接管；
+浏览器下直接跳过，交给 ag-psd 自己的 `document` 检测。
+
+这个问题只有真正去消费构建产物才会暴露，所以仓库里有一组专门跑 `dist/` 的测试。
+
+### 11. 蒙版画布能裁就裁
+
+Leafer 的遮罩只在**遮罩元素自身的世界边界内**参与合成（见 `__renderMask` 里的
+`useMask(canvas, maskWorld)`），边界之外的内容是看不见的。
+
+而 PS 图层蒙版的 `defaultColor` 表示蒙版框**之外**的默认值：`0` = 黑 = 完全遮住。
+既然框外本来就该看不见，就没必要铺满整张图层 —— 直接把遮罩画布裁到
+「蒙版框 ∩ 图层框」即可。实测 1000×1000 的图层配 200×200 的蒙版：
+
+```
+蒙版像素: defaultColor=0 → 40000    （裁剪后）
+          defaultColor=255 → 1000000  （框外是白色，必须铺满）
+```
+
+`defaultColor` 为 `255` 时框外是可见的，遮罩必须覆盖整个图层，此时不做裁剪。
+
+### 12. PS 的 `choke` / spread 是百分比，不是像素
+
+ag-psd 把 `LayerEffectShadow.choke` 的 `units` 标成了 `Pixels`，**但那是错的** ——
+真实 PSD 里存的是 0~100 的百分比。
+
+实测代价很大：把 24 当像素用，投影的扩散范围大 4 倍以上，`test-2.psd` 里
+「img 拷贝」区域的像素差从 **8.2 劣化到 37.0**，整图从 **3.02 劣化到 17.43**。
+
+```ts
+// 正确
+spread = size * choke / 100
+```
+
+### 13. 位图图层的效果只能自己烘焙
+
+PS 的描边、颜色叠加、内阴影、内发光都是沿图层 **alpha 轮廓** 生效的。
+Leafer 这边只有 `shadow` 对 `Image` 会跟随轮廓（实测确认），而：
+
+- `stroke` 对 `Image` 描的是**包围盒**，不是轮廓
+- `fill` 对 `Image` **根本不能用** —— `Image` 内部就用 `fill` 承载图片画笔
+
+所以对像素图层，效果必须按 alpha 自己合成（见 `decorator/bake.ts`）。
+canvas 提供的三件工具刚好够用：`shadowBlur`/`shadowOffset`、`source-in` /
+`destination-in` / `destination-out` 合成、以及 `ctx.filter = 'blur(Npx)'`。
+
+两处容易写错的地方（都踩过）：
+
+- **腐蚀 ≠ 膨胀**。向内描边要的是 `内容 − erode(内容)`，而腐蚀是「所有平移副本的
+  **交集**」；用并集（膨胀）去挖空会把整层填成描边色。
+- **补白与内容是两套坐标系**。叠加层若返回补白尺寸的画布，内容会被推移一个 padding。
+
+### 14. 模糊半径系数是对着参考图量出来的
+
+PS 的 `size` 是高斯模糊半径，画布 `shadowBlur` 则满足 σ = `shadowBlur` / 2，
+两者物理含义不等价，各处的经验换算说法相差很大（约 0.67× ~ 2×）。
+
+所以直接做参数扫描：把烘焙结果叠到白底上，与参考合成图逐像素比较，扫遍
+`0.35 ~ 1.0`。结果是 **0.55 ~ 0.75 一个平坦的谷底，取 0.70**。
+
+手算也吻合：参考图的投影衰减曲线拟合出 σ ≈ 6.33px，`2σ / 17(PS size) ≈ 0.745`。
+两条独立路径落在同一区间，不是过拟合。扫描有回归护栏（`__tests__/calibrate.test.ts`）。
+
+### 15. 字体必须先归一化，否则等于没设字体
+
+PS 存的是字体**全名**（`AdobeHeitiStd-Regular`、`MicrosoftYaHei`），系统认的是
+**字体族名**（`Adobe Heiti Std`、`Microsoft YaHei`）。全名匹配不上会静默回退到默认字体。
+
+实测这台机器上**装了 `Adobe Heiti Std`**，但用全名 `AdobeHeitiStd-Regular` 仍然回退，
+文字宽度差 **16.42px**；换成族名后降到 **0.42px**。旋转 45° 的那层从
+`dw=+10.98` 降到 **`dw=-0.02`**。
+
+所以内置了一张别名表（`utils/font.ts`），并导出 `toFontFamily()` 供宿主复用。
+这里刻意**不做通用的驼峰拆词**：`MicrosoftYaHei` 拆成 `Microsoft Ya Hei` 是错的
+（`YaHei` 是一个词），猜错会命中一个完全无关的字体，比回退到系统默认更糟。
+查不到就原样返回，不猜。
+
+---
+
+## 验证
+
+还原度用真实 PSD 对着 **ag-psd 合成的参考图**做像素级比对，而不是靠肉眼。
+`__tests__/fidelity.test.ts` 会自动遍历仓库根 `samples/` 下的全部样例。
+
+```sh
+npm test
+```
+
+三个样例的实测结果（平均通道差 / 255，越小越好）：
+
+| 样例 | 内容 | `text: 'raster'` | `text: 'editable'` |
+| --- | --- | --- | --- |
+| `test-1.psd` | 像素层、位图+矢量双蒙版、横排/竖排文字、图层组、形状层、负坐标超界 | 1.039 | **0.990** |
+| `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）：用真字体清晰渲染，
+比复用 PS 烘焙的位图更贴合参考图。`test-text` 反过来（1.773 vs 1.200），因为它是纯文字
+样例，烘焙模式直接复用了 PS 自己的文字位图，而语义化模式要重排一遍。
+
+### 文字逐层精度
+
+```
+样例 test-text.psd（全部 7 个文字层）：
+  图层「Lorem Ipsum」              rotation=0°       dx=-0.06 dy=0.09   dw=+0.42 dh=-0.19
+  图层「…旋转45.00」                rotation=45°      dx=-0.47 dy=0.34   dw=-0.02 dh=-0.02
+  图层「…竖排文字」                 vertical          dx=+0.61 dy=-0.06  dw=-0.19 dh=+0.42
+  图层「…微软雅黑」                 rotation=0°       dx=-1.00 dy=-1.00  dw=+1.22 dh=+1.00
+  图层「…微软雅黑; 旋转-31.79」      rotation=-31.79°  dx=-0.82 dy=-1.04  dw=+1.56 dh=+1.12
+  图层「…楷体」                     rotation=0°       dx=-0.27 dy=-0.22  dw=+0.53 dh=-0.47
+  图层「Lorem Ipsu...段落」         3 行段落           dx=-0.27 dy=-0.22  dw=+0.53 dh=-0.47
+```
+
+定位普遍在 **1px 以内**；旋转 45° 的那层尺寸误差只有 **0.02px**，负角度（-31.79°）也在
+1px 出头。竖排是靠「整段旋转 90°」模拟的（Leafer 的 `writingMode` 没有实现）。
+
+最后一行是**三行段落**（`Lorem Ipsum\nLorem Ipsum\nLorem Ipsum`，楷体）：尺寸误差
+`dh=-0.47`，说明行高这条路径在真实多行样例上也是贴合的，哪怕它的 `leading` 数值同样
+被判为不可信、走的是自动行高分支（见「已知限制」）。
+
+### 效果逐区域精度（test-2.psd）
+
+```
+整图                            3.02
+  「img 拷贝」   投影+双描边       4.77     ← 修复前 45.26
+  「正片叠底」   正片叠底          1.74
+  「变亮」       变亮              2.37
+  「img 拷贝 2」 内阴影+内发光     2.89
+  「img 拷贝 3」 位图+矢量双蒙版   2.61
+  「img」        剪贴蒙版          2.59
+```
+
+测试输出（渲染图 / 参考图 / 差异可视化 / 分区域并排图）写在 `__tests__/__output__/`。
+
+### 性能
+
+瓶颈在 ag-psd 解码，不在本插件。真实样例（500×500，7 个顶层图层）的拆解：
+
+```
+ag-psd 解码 : 34 ms  (91%)
+元素树构建  :  3 ms  ( 9%)
+```
+
+元素树构建本身极便宜（合成基准里 500 个图层约 5 ms，合 **0.010 ms/层**），
+所以本插件没有引入额外的规模瓶颈。
+
+> ⚠️ `readPsd` 是同步阻塞的，那 91% 会实打实卡住主线程。本插件不做 Worker 隔离
+> （按既定方案），但你可以自己在 Worker 里调用 `readPsdFromSource` /
+> `psdToContainer` 来规避。
+
+---
+
+## 开发
+
+这个仓库是 npm workspace：插件包在 `packages/psd`，调试台在 `playground`，
+真实 PSD 样例在仓库根的 `samples/`（测试与调试台共用一份）。
+
+命令建议在**仓库根**执行：
+
+```sh
+npm run dev             # 启动调试台（http://localhost:5173）
+npm test                # 186 个测试（含跑构建产物的冒烟测试）
+npm run typecheck
+npm run build           # 打包 ESM + UMD，并生成 types/
+npm run verify:artifact # 构建 + 校验产物（npm publish 前会自动跑）
+npm run pack            # 构建 + 校验 + npm pack，检查会发布哪些文件
+
+# 命令行查看一个 PSD 的图层结构（排查偏差的第一手段）
+node packages/psd/scripts/inspect-psd.mjs samples/test-1.psd
+```
+
+只在插件包内工作的话，也可以 `cd packages/psd` 后直接跑上述命令（去掉 `-w` 相关的部分）。
+
+> **`dist/` 与 `types/` 不提交进 git**，它们是 `npm run build` 的产物。
+> 因此发布前必须先构建 —— 这件事由包里的 `prepublishOnly` 钩子自动完成，
+> 并且会顺带跑一遍 `test:artifact`（校验 `main`/`module`/`types`/`unpkg`/`exports`
+> 指向的文件真实存在、ESM 与 UMD 两条消费路径可用）。
+> 详见仓库根 README 的「发布」一节。
+
+### 调试台怎么引用这个包
+
+调试台里写的是**真实包名**：
+
+```ts
+import { psdToFrame } from 'leafer-x-psd'
+```
+
+解析由 `playground/vite.config.ts` 的 alias 决定：
+
+| 模式 | 命令 | 解析到 | 需要 build |
+| --- | --- | --- | --- |
+| 默认（源码） | `npm run dev` | `packages/psd/src/index.ts` | 不需要，改一行立刻生效 |
+| 产物 | `PSD_USE_DIST=1 npm run dev` | `packages/psd/dist/psd.mjs` | 需要先 `npm run build` |
+
+两条路径的 specifier 完全一样，所以调试台代码一个字都不用改。
+产物模式用来验证「真实发布出去的形态」（走 `exports`、走 dist）。
+
+### 测试分层
+
+| 文件 | 覆盖 |
+| --- | --- |
+| `__tests__/unit.test.ts` | 纯逻辑：包围盒、混合模式映射、颜色转换、贝塞尔路径、剪贴组探测 |
+| `__tests__/tree.test.ts` | 元素树结构：顺序、坐标归一化、蒙版、剪贴、文字、适配器降级 |
+| `__tests__/effects.test.ts` | 效果两条路径的分工（位图烘焙 vs 属性映射）与能力边界 |
+| `__tests__/bake.test.ts` | 烘焙本身：补白、`choke` 百分比、腐蚀/膨胀、坐标系不串位 |
+| `__tests__/capability.test.ts` | 底层能力探针：Leafer shadow 跟随轮廓、canvas 合成与 filter |
+| `__tests__/text.test.ts` | 文字定位：渲染着墨范围 vs PS 包围盒，含竖排/旋转朝向断言 |
+| `__tests__/fidelity.test.ts` | 整图还原度：遍历全部样例与 ag-psd 合成图做像素对比 + 位移诊断 |
+| `__tests__/calibrate.test.ts` | 参数扫描校准 `shadowBlurScale`，并护栏住默认值 |
+| `__tests__/regions.test.ts` | 分图层区域比对，输出「参考 \| 渲染 \| 差异」并排图 |
+| `__tests__/runtime.test.ts` | 分批切片、规模基准、耗时拆解、取消、资源回收、蒙版裁剪收益 |
+| `__tests__/limits.test.ts` | 配额与不可信输入：画布上限、效果参数钳制、超限降级、URL 来源已移除 |
+| `__tests__/package.test.ts` | **消费 `dist/` 构建产物**：ESM 导入、UMD 的 `LeaferX.psd` 全局、包元信息 |
+
+`package.test.ts` 刻意与源码测试分开：只有真正去用发布出去的东西，才会暴露
+「打包后 ag-psd 副本配不上画布」这类问题。
+
+调试台支持拖放或一键载入 `samples/` 里的样例、逐项开关解析选项（含文字烘焙/语义化切换）、
+查看进度与诊断；点击元素可查看它的 `ui.data.psd` 元数据。
+
+---
+
+## 已知限制
+
+- **解析结果是会话内的，默认不可持久化**。`Image.url` 是形如
+  `leafer://psd-plugin-resource-N.png` 的资源符（前缀见导出的 `RESOURCE_PREFIX`），
+  `frame.toJSON()` 会把它原样序列化 —— 存库后再加载、换个客户端渲染、
+  分享链接，图片全都出不来。要持久化必须先跑
+  [`exportResources()`](#资源与持久化) 把资源符换成真实 URL。
+  插件**不预设上传**，URL 从哪来由你的回调决定。
+- **画布资源需要宿主主动回收**。`Resource` 是全局表，插件注册进去的画布不会自动释放，
+  反复加载 PSD 会持续占用内存。用完调用 `releaseResources(frame)`。
+  （`exportResources()` 替换成功时也会顺手摘掉对应资源。）
+- **`readPsd` 是同步阻塞的**（占端到端耗时的约 90%）。很大的 PSD 会卡住主线程。
+  本插件不做 Worker 隔离，但你可以自己在 Worker 里调用 `readPsdFromSource` /
+  `psdToContainer` 来规避。
+- **CMYK 色彩模式不支持**（ag-psd 的限制），会给出明确错误提示，请先转为 RGB。
+- **不接受 URL 字符串**。插件不发网络请求，请先自行加载成二进制
+  （见[为什么没有 URL 来源](#为什么没有-url-来源)）。
+- **有画布配额**。单边 `16384`、单张 `32M` 像素，效果 `size` 钳在 `1000px`。超限的
+  图层/蒙版/效果会被跳过并报 `limit-exceeded`，解码期超限则直接抛
+  `PsdCanvasLimitError`。确实需要更大的画布时用 `setCanvasLimits()` 放宽
+  （见[安全与配额](#安全与配额)）。
+- **字体别名表是有限的**。内置表覆盖常见的中英文字体；表外的全名会原样透传，
+  匹配不上就回退到系统默认。用 `fontFamily` 回调补充你自己的字体，
+  并确保宿主真的加载了它。
+- **文字多行行距**：PS 的 `leading` 单位在 ag-psd 里是原样透传的引擎值（实测样例里
+  `leading / fontSize` 恰好是 6.0，作为多行行高明显不合理），所以只在比值落在 `[0.5, 4]`
+  时才采用，否则退回 PS 的自动行高倍数并报 `text-leading-suspect`。
+  样例里的三行段落层（`Lorem Ipsu...段落`）走的就是这条降级分支，实测高度误差
+  `dh=-0.47px` —— 说明降级在真实多行数据上是贴合参考图的，但**`leading` 字段本身的语义
+  仍未查清**，遇到行距明显偏离的 PSD 请优先怀疑这里。
+- **文字的水平缩放与文字变形**（`horizontalScale` / `warp`）尚未映射，会报 `text-unsupported`。
+- **斜面浮雕 / 光泽 / 图案叠加**在 Leafer 中没有对应能力，会报 `effect-unsupported` 并丢弃。
+- **效果烘焙的近似之处**：膨胀/腐蚀是用「沿圆周多次绘制」逼近的（最多 24 次），
+  大半径下有轻微多边形锯齿；不过效果本身通常带模糊，视觉上不明显。
+- **形状图层无法矢量化**：ag-psd 没有暴露形状路径（见上）。
+- **智能对象不展开**：只烘焙外观，不解析内嵌的原始文档。
+
+## License
+
+MIT