leafer-x-psd 0.0.1-beta.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "leafer-x-psd",
+  "version": "0.0.1-beta.0",
+  "description": "Parse PSD files into leaferjs Frames - a leafer-x plugin.",
+  "author": "Tian",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/psd.umd.cjs",
+  "module": "./dist/psd.mjs",
+  "types": "./types/index.d.ts",
+  "unpkg": "./dist/psd.umd.cjs",
+  "jsdelivr": "./dist/psd.umd.cjs",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/psd.mjs",
+      "require": "./dist/psd.umd.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run build:types && vite build",
+    "build:types": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:artifact": "vitest run __tests__/package.test.ts",
+    "typecheck": "tsc --noEmit",
+    "inspect": "node scripts/inspect-psd.mjs",
+    "verify:artifact": "npm run build && npm run test:artifact",
+    "prepublishOnly": "npm run verify:artifact"
+  },
+  "keywords": [
+    "leafer",
+    "leafer-x",
+    "leaferjs",
+    "psd",
+    "photoshop",
+    "parser"
+  ],
+  "comment:dependencies": "ag-psd 已被打包进 dist（保证 UMD/CDN 全局用法可用），因此不再声明为运行时依赖，避免消费者多装一份用不到的东西。",
+  "peerDependencies": {
+    "@leafer-ui/core": "^2.2.11",
+    "@leafer-ui/interface": "^2.2.11"
+  },
+  "devDependencies": {
+    "@leafer-ui/core": "^2.2.11",
+    "@leafer-ui/interface": "^2.2.11",
+    "@leafer-ui/node": "^2.2.11",
+    "@napi-rs/canvas": "^1.0.9",
+    "@types/node": "^26.6.1",
+    "ag-psd": "^31.0.2",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  }
+}

package/types/adapter/common.d.ts

@@ -0,0 +1,33 @@
+import type { Layer } from 'ag-psd';
+import type { IUI, IUIInputData } from '@leafer-ui/interface';
+import type { BuildContext } from '../context';
+import type { AnyCanvas, PsdElementRole } from '../types';
+/**
+ * 图层内容元素的公共输入数据。
+ *
+ * 位置一律用 `measureLayer` 得到的文档绝对盒换算到父容器局部坐标，
+ * 这是避免组内子层双重偏移的唯一入口。
+ */
+export declare function buildBaseData(layer: Layer, ctx: BuildContext, role: PsdElementRole): IUIInputData;
+/** 图层的尺寸（文档绝对盒的宽高）。 */
+export declare function layerSize(layer: Layer): {
+    width: number;
+    height: number;
+};
+/**
+ * 包装容器的输入数据。
+ *
+ * 包装器（遮罩、剪贴蒙版）与被包装的内容**共用同一个原点**：包装器放在内容
+ * 原本的位置上，内容被移到 (0, 0)。这样蒙版元素可以用 `0,0` 起算的局部坐标，
+ * 整棵子树的绝对位置不变。
+ */
+export declare function buildWrapperData(layer: Layer, ctx: BuildContext, role: PsdElementRole, x: number, y: number): IUIInputData;
+/**
+ * 把图层像素统一取成一张画布。
+ *
+ * `readPsd` 默认产出 `layer.canvas`；如果宿主传了 `useImageData: true`，
+ * 这里负责把裸像素还原成画布。
+ */
+export declare function layerCanvas(layer: Layer): AnyCanvas | undefined;
+/** 把元素沿自身原点平移，用于放进与自身同原点的包装容器。 */
+export declare function moveToOrigin(element: IUI): void;

package/types/adapter/group.d.ts

@@ -0,0 +1,8 @@
+import type { LayerAdapter } from './types';
+/**
+ * 图层组适配器。
+ *
+ * 组自身不设宽高，边界由子树推导；位置取子层递归求并集得到的原点，
+ * 子层坐标在 tree 里会减去这个原点（ag-psd 给的是文档绝对坐标）。
+ */
+export declare const groupAdapter: LayerAdapter;

package/types/adapter/image.d.ts

@@ -0,0 +1,11 @@
+import type { LayerAdapter } from './types';
+/**
+ * 像素图层适配器：把 `layer.canvas` 烘焙成 `Image`。
+ *
+ * 走 `Resource.setImage` 把画布直接注册为资源，`Image.url` 用资源符引用，
+ * 全程没有 base64 编解码。同时登记一份资源记录（key → 图层信息），
+ * 供 `exportResources()` 之后把这些资源换成真实 URL。
+ *
+ * 优先级最低，作为所有无法语义化还原的图层的兜底。
+ */
+export declare const imageAdapter: LayerAdapter;

package/types/adapter/index.d.ts

@@ -0,0 +1,36 @@
+import type { Layer } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import type { BuildContext } from '../context';
+import type { LayerAdapter } from './types';
+/**
+ * 注册图层适配器。同名会覆盖，按 `priority` 降序匹配。
+ * 宿主可以注册自己的适配器来接管特定图层（例如 PSD 里的智能对象）。
+ */
+export declare function registerAdapter(adapter: LayerAdapter): void;
+export declare function unregisterAdapter(name: string): void;
+export declare function listAdapters(): readonly LayerAdapter[];
+/** 返回第一个匹配上的适配器（不尝试创建）。 */
+export declare function resolveAdapter(layer: Layer, ctx: BuildContext): LayerAdapter | undefined;
+export interface AdapterResolution {
+    /** 成功创建的图层内容 */
+    element?: IUI;
+    /** 实际生效的适配器 */
+    adapter?: LayerAdapter;
+    /** 优先级更高但创建失败的适配器，用于给出降级诊断 */
+    degraded?: {
+        adapter: LayerAdapter;
+        error?: unknown;
+    };
+}
+/**
+ * 按优先级依次尝试适配器，直到某一层成功创建出元素。
+ *
+ * 这是「语义化优先、失败降级」的落点：例如文字适配器认领了图层却没能还原，
+ * 就会继续往下试，最终由兜底的位图适配器接手，同时把降级的事实报出去，
+ * 而不是让整个解析失败或静默产生错误结果。
+ *
+ * 适配器抛出的异常也会被吞掉并记为降级原因 —— 单个图层的数据异常不应该
+ * 让整份 PSD 解析崩掉。
+ */
+export declare function createLayerContent(layer: Layer, ctx: BuildContext): AdapterResolution;
+export type { LayerAdapter };

package/types/adapter/text.d.ts

@@ -0,0 +1,12 @@
+import type { LayerAdapter } from './types';
+/**
+ * 文字图层适配器。
+ *
+ * 定位模型：把 Leafer `Text` 的**首行基线**对齐到 PS 的基线。
+ *
+ * Leafer 内部算出首行基线距盒子顶部的偏移是
+ * `__baseLine = lineHeight - (lineHeight - fontSize * 0.7) / 2 = lineHeight / 2 + 0.35 * fontSize`
+ * （见 `@leafer-ui/draw` 的文本样式计算），再把 `around` 设为 `{ x: 0, y: 基线偏移 }`，
+ * 就能让「元素内部的基线起点」正好落在元素的 `(x, y)` 上，旋转也自然绕基线进行。
+ */
+export declare const textAdapter: LayerAdapter;

package/types/adapter/types.d.ts

@@ -0,0 +1,17 @@
+import type { Layer } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import type { BuildContext } from '../context';
+/**
+ * 图层适配器：把一类 PSD 图层还原成 Leafer 元素。
+ *
+ * 按 `priority` 从高到低匹配，第一个 `match` 返回 true 的适配器负责创建内容。
+ * 语义化还原失败时应返回 `undefined`，由调用方降级到下一个适配器。
+ */
+export interface LayerAdapter {
+    /** 适配器名，用于诊断。 */
+    readonly name: string;
+    /** 匹配优先级，越大越先尝试。 */
+    readonly priority: number;
+    match(layer: Layer, ctx: BuildContext): boolean;
+    create(layer: Layer, ctx: BuildContext): IUI | undefined;
+}

package/types/context.d.ts

@@ -0,0 +1,37 @@
+import type { Layer, Psd } from 'ag-psd';
+import type { ResourceCollector } from './resources';
+import type { PsdWarningCode, ResolvedOptions } from './types';
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * 构建期的共享上下文。
+ *
+ * 里面最要紧的是 `origin`：它是**当前父容器在文档坐标系中的原点**。
+ * ag-psd 给出的图层坐标全是文档绝对坐标，所以每往下进一层容器，
+ * 都要用 `localX/localY` 把绝对坐标换算成父容器局部坐标，否则就会
+ * 出现层级越深偏得越多的双重偏移。
+ */
+export interface BuildContext {
+    readonly psd: Psd;
+    readonly options: ResolvedOptions;
+    /** 当前父容器原点（文档绝对坐标） */
+    readonly origin: Point;
+    /**
+     * 本次解析登记的资源记录（key → 图层信息 + 画布）。
+     *
+     * `Resource` 是全局表且不会自动回收，把记录挂在这里，解析完成后可以交给
+     * `releaseResources()` / `exportResources()` 统一处理，避免反复加载 PSD 时
+     * 内存持续增长。收集器在所有派生上下文之间共享。
+     */
+    readonly resources: ResourceCollector;
+    /** 文档 X 绝对坐标 → 父容器局部坐标 */
+    localX(absolute: number): number;
+    /** 文档 Y 绝对坐标 → 父容器局部坐标 */
+    localY(absolute: number): number;
+    warn(code: PsdWarningCode, message: string, layer?: Layer): void;
+}
+export declare function createContext(psd: Psd, options: ResolvedOptions, resources: ResourceCollector): BuildContext;
+/** 进入子容器时派生一个新上下文，原点切换为该容器的绝对原点。 */
+export declare function withOrigin(ctx: BuildContext, origin: Point): BuildContext;

package/types/decorator/bake.d.ts

@@ -0,0 +1,14 @@
+import type { LayerEffectsInfo } from 'ag-psd';
+import type { AnyCanvas } from '../types';
+export interface BakedEffects {
+    canvas: AnyCanvas;
+    /** 烘焙画布原点相对原图层盒原点的偏移（≤ 0） */
+    offsetX: number;
+    offsetY: number;
+}
+/**
+ * 把图层效果烘焙进位图。
+ *
+ * @returns 新的画布与偏移；没有任何可烘焙的效果时返回 `undefined`。
+ */
+export declare function bakeRasterEffects(source: AnyCanvas, effects: LayerEffectsInfo, blurScale: number): BakedEffects | undefined;

package/types/decorator/clipping.d.ts

@@ -0,0 +1,34 @@
+import type { Layer } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import type { BuildContext } from '../context';
+/**
+ * 一个剪贴蒙版组。
+ *
+ * PS 的剪贴蒙版在 ag-psd 的图层数组里表现为：基底层（`clipping: false`）
+ * 后面紧跟连续的若干个 `clipping: true` 的图层。数组顺序是**自下而上**的，
+ * 所以「后面紧跟」正好对应 PS 里「压在基底上面的那些层」。
+ */
+export interface ClippingRun {
+    /** 基底层，决定裁剪形状与整个组的透明度 */
+    base: Layer;
+    /** 被基底裁剪的图层，自下而上 */
+    contents: Layer[];
+    /** 该剪贴组结束的下标（不含） */
+    end: number;
+}
+/**
+ * 从 `start` 开始探测一个剪贴蒙版组。
+ *
+ * 孤立出现的 `clipping: true`（下方没有基底层）会返回 `undefined`，
+ * 交由普通图层逻辑处理，避免把无效数据放大成错误结构。
+ */
+export declare function findClippingRun(layers: Layer[], start: number): ClippingRun | undefined;
+/**
+ * 把基底层与被裁剪层组装成 Leafer 的剪贴遮罩。
+ *
+ * Leafer 的 `mask: 'clipping'` 官方描述就是「和 PS 中的剪贴蒙版一样的效果：
+ * 使用每个像素的透明度，并会显示自身」，所以语义完全对齐，不需要自己合成。
+ *
+ * 结构上：Group 内第一个子元素是带 `mask: 'clipping'` 的基底层，其余层压在它上面。
+ */
+export declare function buildClippingGroup(run: ClippingRun, baseElement: IUI, contentElements: IUI[], ctx: BuildContext): IUI;

package/types/decorator/effects.d.ts

@@ -0,0 +1,25 @@
+import type { Layer } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import type { BuildContext } from '../context';
+/**
+ * 应用图层效果。
+ *
+ * 分两条路径，因为 PS 与 Leafer 的能力边界不同：
+ *
+ * 1. **位图图层（`Image`）→ 自己烘焙进位图**。
+ *    PS 的描边、颜色叠加、内发光等都是沿图层 **alpha 轮廓** 生效的，而 Leafer 的
+ *    `stroke` / `fill` 对 `Image` 要么作用在包围盒上、要么被图片画笔占用
+ *    （`Image` 内部就用 `fill` 承载图片）。所以这类图层必须按 alpha 合成，
+ *    见 `bake.ts`。
+ *
+ * 2. **文字与形状图层 → 映射成 Leafer 属性**。
+ *    这类元素自身的形状就是内容形状，`stroke` / `fill` 语义与 PS 一致，直接映射即可，
+ *    而且保持了可编辑性。
+ *
+ * 无法映射的（斜面浮雕 / 光泽 / 图案叠加）一律丢弃并告警，绝不静默产生错误画面。
+ *
+ * ⚠️ 文件里带着离谱的效果参数（`size` / `choke` 超出 PS 的正常量级）时，
+ * 数值会被钳制并报 `limit-exceeded`；需要临时画布的效果若因此超出画布配额，
+ * 则保留未烘焙的内容并报同一条诊断 —— 都不让整份 PSD 解析失败。
+ */
+export declare function applyEffects(layer: Layer, content: IUI, ctx: BuildContext): IUI;

package/types/decorator/mask.d.ts

@@ -0,0 +1,17 @@
+import type { Layer } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import type { BuildContext } from '../context';
+/**
+ * 给图层内容套上图层蒙版。
+ *
+ * 两个容易被忽略的点：
+ *
+ * 1. **PS 的矢量蒙版与像素图层蒙版可以同时存在，两者取交集。**
+ *    所以这里不是「矢量优先、否则位图」，而是把可用的蒙版**逐个嵌套**套上去
+ *    （Leafer 每个容器只认一个遮罩元素，嵌套容器天然求交）。
+ *    实测样例 `图层 1 拷贝 2` 就属于这种双蒙版图层。
+ *
+ * 2. 遮罩元素必须是**同一父 Group 下的兄弟节点**，并且自身不渲染，
+ *    因此每个蒙版都要包一层容器，把遮罩放在内容下面。
+ */
+export declare function decorateWithMask(layer: Layer, content: IUI, ctx: BuildContext): IUI;

package/types/exporter.d.ts

@@ -0,0 +1,37 @@
+import type { IUI } from '@leafer-ui/interface';
+import type { PsdExportOptions, PsdExportResult } from './types';
+/**
+ * 把解析结果里的会话内资源符（`RESOURCE_PREFIX` 开头的那些）换成真实 URL，
+ * 让 Frame 变成**可持久化**的。
+ *
+ * 为什么要有这一步：解析出来的 `Image.url` 是会话内的资源符
+ * （Leafer `Resource` 表里的一个 key），`frame.toJSON()` 会把它原样序列化 ——
+ * 存进数据库、换个客户端、分享链接，图片全都加载不出来。
+ *
+ * 为什么是独立的一步、而不是塞进 `psdToFrame`：
+ *
+ * - 解析目前全程**零编码**（画布直通），这是它最大的性能优势。一旦要求上传就必须先编码，
+ *   这个优势就没了。
+ * - 上传会慢、会失败、需要并发限流与重试 —— 那是存储与网络问题，不是解析问题。
+ *   混在一起会让 `psdToFrame` 的语义变浑（到底是「解析」还是「解析并上传」）。
+ * - 有些用户根本不需要（只在当前会话里编辑，最后导出一张图），强制走编码是纯损失。
+ *
+ * ```ts
+ * const frame = await psdToFrame(file)
+ *
+ * await exportResources(frame, {
+ *   resolve: async (canvas, info) => {
+ *     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
+ *   },
+ *   onProgress: (done, total) => console.log(`${done}/${total}`),
+ * })
+ *
+ * const json = frame.toJSON()   // 这时候才是可持久化的
+ * ```
+ *
+ * 成功替换后会把旧的 `leafer://` 从 Leafer `Resource` 表里**摘掉** —— 那张画布
+ * 已经没人引用了，摘掉能立刻省下一份内存。
+ */
+export declare function exportResources(target: IUI, options: PsdExportOptions): Promise<PsdExportResult>;

package/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * leafer-x-psd —— 把 PSD 文件解析成 leaferjs 的 `Frame`。
+ *
+ * 设计取向是「混合路线」：
+ * - 图层结构、图层蒙版、剪贴蒙版、混合模式尽量**语义化**还原成 Leafer 原生能力；
+ * - 像素图层与形状图层烘焙成位图（ag-psd 没有暴露形状路径数据，做不到矢量还原）；
+ * - 无法映射的部分不静默失败，而是通过 `onWarning` 报出来。
+ */
+export { DEFAULT_SHADOW_BLUR_SCALE, PsdParser, psdToContainer, psdToFrame, releaseAllResources, resolveOptions, } from './parser';
+export { readPsdFromSource } from './reader';
+export { ResourceCollector, attachCollector, getCollector, getResources, registerResource, releaseResources, unregisterResource, } from './resources';
+export { exportResources } from './exporter';
+export { RESOURCE_PREFIX, canvasToBlob, canvasToBuffer } from './platform';
+export { listAdapters, registerAdapter, resolveAdapter, unregisterAdapter, } from './adapter';
+export type { LayerAdapter } from './adapter/types';
+export { toLeaferBlendMode } from './utils/blendMode';
+export { boxHeight, boxWidth, countLayers, measureLayer, ownBox, unionBox } from './utils/box';
+export { DEFAULT_CANVAS_LIMITS, PsdCanvasLimitError, describeCanvasLimits, getCanvasLimits, setCanvasLimits, } from './utils/limits';
+export type { CanvasLimits } from './utils/limits';
+export { bezierPathsToSvg, bezierWindingRule } from './utils/geometry';
+export { colorToString } from './utils/color';
+export { hasFontAlias, toFontFamily } from './utils/font';
+export type { Box } from './utils/box';
+export type * from './types';

package/types/parser.d.ts

@@ -0,0 +1,67 @@
+import { Frame } from '@leafer-ui/core';
+import type { Psd } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import { releaseAllResources } from './platform';
+import type { PsdParseOptions, PsdSource, ResolvedOptions } from './types';
+/**
+ * PS 投影/内阴影的 `size` 与画布 `shadowBlur` 之间的换算系数。
+ *
+ * 对着真实 PSD 的参考合成图扫描出来的：0.55 ~ 0.75 是一个平坦的谷底，取 0.70。
+ * 手算也吻合 —— 参考图的投影衰减曲线拟合出 σ ≈ 6.33px，而画布 `shadowBlur = 2σ ≈ 12.66`，
+ * `12.66 / 17(PS size) ≈ 0.745`。两条独立路径落在同一个区间，不是过拟合。
+ */
+export declare const DEFAULT_SHADOW_BLUR_SCALE = 0.7;
+export declare function resolveOptions(options?: PsdParseOptions): ResolvedOptions;
+/** 把一个已解码的 `Psd` 构建成 Leafer 元素树。 */
+export declare function psdToContainer(psd: Psd, root: IUI, options?: PsdParseOptions): Promise<IUI>;
+/** 清空本插件注册过的全部资源（不知道具体清单时的兜底，例如热重载）。 */
+export { releaseAllResources };
+/**
+ * 解析 PSD 文件，返回一个 Leafer `Frame`。
+ *
+ * ```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)
+ * ```
+ */
+export declare function psdToFrame(source: PsdSource, options?: PsdParseOptions): Promise<Frame>;
+/**
+ * 解析器。相比 `psdToFrame`，它把「解码」与「构建」拆开，
+ * 于是可以复用同一份 `Psd` 反复构建，也可以中途取消。
+ *
+ * ```ts
+ * const parser = new PsdParser(file)
+ * const psd = await parser.ready          // 只解码，拿到文档尺寸/图层树
+ * const frame = await parser.toFrame()    // 需要时再构建
+ * parser.abort()                          // 取消
+ * ```
+ */
+export declare class PsdParser {
+    private _psd;
+    private failure;
+    private readonly controller;
+    private readonly options;
+    private built;
+    /** 解码完成的 `Psd`，未完成时抛错。 */
+    get psd(): Psd;
+    get isReady(): boolean;
+    get width(): number;
+    get height(): number;
+    /** 顶层图层数组（自下而上） */
+    get layers(): import("ag-psd").Layer[];
+    /** 解码完成的 Promise，可安全地重复 await。 */
+    readonly ready: Promise<Psd>;
+    constructor(source: PsdSource, options?: PsdParseOptions);
+    private decode;
+    /** 构建 `Frame`。可传入已有容器以复用。 */
+    toFrame(root?: Frame): Promise<Frame>;
+    /** 是否已经构建过 Frame。 */
+    get isBuilt(): boolean;
+    /** 解析失败时的原始错误。 */
+    get error(): unknown;
+    /** 取消进行中的解析。 */
+    abort(reason?: unknown): void;
+}

package/types/platform.d.ts

@@ -0,0 +1,89 @@
+import type { AnyCanvas, PsdResourceFormat } from './types';
+/** 注册到 Leafer `Resource` 里的资源符前缀，用于识别与回收本插件产生的资源。 */
+export declare const RESOURCE_PREFIX = "leafer://psd-plugin-resource-";
+/**
+ * 确保 ag-psd 有可用的画布工厂。
+ *
+ * ag-psd 是在**模块求值时**检测 `typeof document !== 'undefined'` 来决定画布工厂的
+ * （见 `ag-psd/dist/helpers.js`），所以浏览器里开箱即用，Node / 小程序里则必须显式
+ * 调用 `initializeCanvas`。
+ *
+ * 关键点：ag-psd 被本插件打包进产物后，产物里有**自己的一份副本**，宿主对独立安装的
+ * `ag-psd` 调用 `initializeCanvas` 影响不到它。所以这里直接从 Leafer 的平台适配
+ * （`Platform.origin.createCanvas`）取工厂自动接上 —— 宿主既然已经能跑 Leafer，
+ * 这一步就不该再让用户操心。
+ *
+ * ⚠️ 解码期的画布同样要过配额（`utils/limits.ts`）：这里的尺寸**全部来自文件内容**
+ * （文档尺寸、图层尺寸、蒙版尺寸），而解码又是整个流程里内存占用最大的一步。
+ * 超限时抛 `PsdCanvasLimitError`，由 `reader.ts` 转成可读的错误信息。
+ */
+export declare function ensureCanvasFactory(): void;
+/**
+ * 手动指定 ag-psd 的画布工厂。
+ *
+ * 只有在自动接管不适用时才需要（例如小程序里用自定义离屏画布）。
+ *
+ * ```ts
+ * useCanvas(
+ *   (width, height) => myCreateCanvas(width, height),
+ *   (width, height) => myCreateImageData(width, height),
+ * )
+ * ```
+ */
+export declare function useCanvas(createCanvasMethod: (width: number, height: number) => AnyCanvas, createImageDataMethod?: (width: number, height: number) => ImageData): void;
+/**
+ * 创建一张画布。优先走 Leafer 平台适配，其次回退到 DOM。
+ *
+ * ⚠️ **这是本插件唯一分配画布的地方，也是配额（`utils/limits.ts`）的唯一收口点。**
+ * PSD 里的图层尺寸、蒙版框、效果半径都会变成本函数的入参，所以在这里校验一次，
+ * 就等于所有分配路径都挡上了。超限抛 `PsdCanvasLimitError`；调用方（蒙版、烘焙、
+ * 图片适配器）负责把它降级成 `limit-exceeded` 告警，而不是让整份 PSD 解析失败。
+ */
+export declare function createCanvas(width: number, height: number): AnyCanvas;
+/**
+ * 把画布注册成 Leafer 资源，返回可以直接喂给 `Image.url` 的资源符。
+ *
+ * 这是本插件性能上最关键的一步：`Resource.setImage` 内部把画布存成
+ * `{ url, view }`，Leafer 渲染时**直接使用这张画布**，没有编码、
+ * 没有 base64、没有二次解码。相比之下 `canvas.toDataURL()` 会做一次
+ * 完整的 PNG 编码 + base64 展开，再在渲染时解码回来 —— 对大 PSD 是灾难。
+ *
+ * 资源记录（key → 图层信息）由 `resources.ts` 的 `registerResource` 负责，
+ * 这里只管 Leafer 那一侧。
+ */
+export declare function registerCanvas(canvas: AnyCanvas): string;
+/** 取得 2D 上下文，失败时抛出可读的错误。 */
+export declare function get2dContext(canvas: AnyCanvas): any;
+/**
+ * 回收一批资源符。
+ *
+ * `Resource` 是一张全局表，本插件注册进去的画布**不会**自动释放。
+ * 反复加载 PSD（例如做一个能来回切换文件的预览器）时，旧画布会一直留在
+ * 表里，内存持续增长。所以解析结果上记了一份资源清单，用完调这里清掉。
+ */
+export declare function releaseResourceKeys(keys: readonly string[]): number;
+/**
+ * 清空本插件注册过的全部资源（不知道具体清单时的兜底，例如热重载）。
+ *
+ * `Resource.map` 是 Leafer **公开**的资源表（`IResource.map`，只是声明成了 `any`，
+ * 形如 `{ [key]: { url, view } }`），所以这里直接给它一个具体类型即可 ——
+ * 不需要绕过类型系统去猜内部结构。
+ */
+export declare function releaseAllResources(): number;
+/**
+ * 把画布编码成字节。
+ *
+ * 依次尝试：`toBuffer`（node-canvas / @napi-rs）→ `convertToBlob`（@napi-rs）
+ * → `toBlob`（浏览器）→ `toDataURL` 手工解 base64。
+ *
+ * @param format 默认 `'png'`；照片类图层用 `'webp'` 体积小很多
+ * @param quality 0~1，仅对 `webp` / `jpeg` 有效，默认 0.92
+ */
+export declare function canvasToBuffer(canvas: AnyCanvas, format?: PsdResourceFormat, quality?: number): Promise<Uint8Array>;
+/**
+ * 把画布编码成 `Blob`（浏览器上传首选：比 dataURL 少 33% 的 base64 膨胀）。
+ *
+ * 依次尝试：`convertToBlob`（@napi-rs）→ `toBlob`（浏览器）→ `toBuffer` 包一层
+ * → `toDataURL` 手工解 base64。
+ */
+export declare function canvasToBlob(canvas: AnyCanvas, format?: PsdResourceFormat, quality?: number): Promise<Blob>;

package/types/reader.d.ts

@@ -0,0 +1,13 @@
+import type { Psd, ReadOptions } from 'ag-psd';
+import type { PsdSource } from './types';
+/**
+ * 解码 PSD 二进制。
+ *
+ * ⚠️ `readPsd` 是**同步阻塞**的：文件越大卡得越久。本插件不做 Worker 隔离
+ * （按既定方案），但宿主如果处理很大的 PSD，建议自己在 Worker 里调用本函数，
+ * 再把得到的 `Psd` 传进来构建元素树（画布对象可跨 Worker 传输 ImageBitmap）。
+ *
+ * 解码期的画布分配同样受配额约束（`utils/limits.ts`）：文件声明的文档尺寸/图层尺寸
+ * 超出上限时会抛 `PsdCanvasLimitError`（被包装成可读信息），而不是去申请一张巨图。
+ */
+export declare function readPsdFromSource(source: PsdSource, options?: ReadOptions): Promise<Psd>;

package/types/resources.d.ts

@@ -0,0 +1,62 @@
+import type { Layer } from 'ag-psd';
+import type { IUI } from '@leafer-ui/interface';
+import type { AnyCanvas, PsdResource, PsdResourceKind } from './types';
+/**
+ * 本次解析登记的资源记录。
+ *
+ * 每张注册进 Leafer `Resource` 表的画布都会记一条，把「资源符」和「它来自哪个 PSD 图层」
+ * 关联起来 —— `exportResources()` 靠它决定把哪张画布交给回调、以及回调能拿到什么元数据。
+ *
+ * 生命周期是「一次解析一份」：会连同被替换掉的条目一起维护，不残留脏数据。
+ */
+export declare class ResourceCollector {
+    private readonly entries;
+    private readonly byKey;
+    add(entry: PsdResource): void;
+    get(key: string): PsdResource | undefined;
+    remove(key: string): void;
+    list(): readonly PsdResource[];
+    keys(): string[];
+    clear(): void;
+    get size(): number;
+}
+/**
+ * 注册一张画布，并登记它的来源。
+ *
+ * 兜底走 dataURL 的情况（平台没适配 canvas 资源）**不登记** —— 那种 url 本身
+ * 就是可直接使用的，不需要再被 `exportResources` 处理。
+ */
+export declare function registerResource(collector: ResourceCollector, canvas: AnyCanvas, kind: PsdResourceKind, layer?: Layer): string;
+/** 撤掉一张资源：同时从记录里和 Leafer 的 `Resource` 表里摘掉。 */
+export declare function unregisterResource(collector: ResourceCollector, key: string): number;
+export declare function attachCollector(target: IUI, collector: ResourceCollector): void;
+/** 从任意元素向上找到解析结果的根，取出它的资源记录。 */
+export declare function getCollector(target: IUI): ResourceCollector | undefined;
+/**
+ * 读出解析结果登记的全部资源。
+ *
+ * 传 `Frame` 或它的任意子元素都可以。
+ *
+ * ```ts
+ * for (const { key, kind, layer, width, height } of getResources(frame)) {
+ *   console.log(kind, layer?.name, `${width}x${height}`, key)
+ * }
+ * ```
+ */
+export declare function getResources(target: IUI): readonly PsdResource[];
+/**
+ * 释放某次解析注册进 Leafer `Resource` 的画布。
+ *
+ * `Resource` 是一张全局表，本插件注册进去的画布**不会自动释放**。做「能反复打开不同
+ * PSD」的界面时，旧画布会一直留在表里，内存持续增长。所以处理完一份 PSD
+ * （比如用户切换了文件）就调用一次：
+ *
+ * ```ts
+ * const frame = await psdToFrame(file)
+ * // ... 用户打开另一份文件时
+ * releaseResources(frame)      // 返回实际释放的数量
+ * ```
+ *
+ * @returns 实际释放的资源数量
+ */
+export declare function releaseResources(target: IUI): number;