customforge 0.1.0-alpha.0

package/README.zh-CN.md

@@ -0,0 +1,299 @@
+<div align="center">
+
+# CustomForge
+
+**让二维纹理画布实时呈现在三维产品上**
+
+一个轻量、与前端框架无关的产品定制原型，基于 Fabric.js 和 Three.js 构建浏览器端 2D 到 3D 定制体验
+
+<p>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white">
+  <img alt="Vite" src="https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white">
+  <img alt="Three.js" src="https://img.shields.io/badge/Three.js-r185-111111?logo=threedotjs&logoColor=white">
+  <img alt="Fabric.js" src="https://img.shields.io/badge/Fabric.js-7-DB4D6D">
+  <img alt="License" src="https://img.shields.io/badge/License-Apache%202.0-2F6F9F">
+</p>
+
+<p>
+  <a href="./README.md">English</a> |
+  <strong>中文简体</strong>
+</p>
+
+</div>
+
+---
+
+## 项目能力
+
+CustomForge 将常见的二维设计界面与带 UV 的三维模型连接起来：
+
+- 在二维纹理画布上添加和编辑文字
+- 上传、移动、缩放和旋转图片
+- 将画布的每次变化实时呈现在三维产品上
+- 加载远程 GLB/GLTF 模型和可选的基础纹理
+- 通过 Mesh 名称指定可定制表面
+- 使用 OrbitControls 旋转和缩放三维预览
+- 将合成后的纹理导出为 PNG
+- 通过版本化 Design JSON 保存和恢复可编辑对象
+
+工作台内置了一个程序生成的杯子，无需准备外部资源即可直接运行
+
+## 仓库开发
+
+环境要求：Node.js 22+ 和 pnpm 11+
+
+```bash
+pnpm install
+pnpm dev
+```
+
+打开 Vite 输出的地址
+
+内置演示的左侧是 UV 编辑区，右侧是实时三维预览
+
+## npm Alpha 制品
+
+CustomForge 已准备通过 `alpha` dist-tag 公开发布。不同 alpha 版本之间的 API 和 Design JSON Schema 可能发生变化
+
+首次发布完成后，使用以下命令安装当前 alpha 及其 peer dependencies：
+
+```powershell
+pnpm add customforge@alpha
+pnpm add fabric three
+```
+
+发布前如需进行独立于仓库源码的验证，可在仓库根目录构建并生成本地包：
+
+```powershell
+pnpm pack:local
+```
+
+命令依次生成 JavaScript、TypeScript 声明、核心样式，检查 npm 文件清单，并创建：
+
+```text
+customforge-0.1.0-alpha.0.tgz
+```
+
+在独立 Vite TypeScript 项目中安装该本地制品及其 peer dependencies：
+
+```powershell
+pnpm add D:\project\CustomForge\CustomForge\customforge-0.1.0-alpha.0.tgz
+pnpm add fabric three
+```
+
+仓库中的 `examples/npm-consumer` 提供了一个只通过该 `.tgz` 导入的消费示例。在该目录中使用 `pnpm install --ignore-workspace`，确保 pnpm 将其作为独立于父级 workspace 的项目安装
+
+## 加载你的产品
+
+在演示页面中选择 **Load remote**，然后填写：
+
+| 字段 | 用途 |
+| --- | --- |
+| GLB / GLTF URL | 带 UV 的三维产品模型地址 |
+| Base texture URL | 显示在可编辑对象下方的可选基础纹理 |
+| Customizable mesh | 接收实时画布纹理的 Mesh 名称 |
+| Flip texture vertically | 在模型需要时修正纹理的垂直方向 |
+
+UV 坐标应当保存在三维模型中
+
+可选的纹理图片只是二维编辑器的基础图层，不能替代模型中的 UV 数据
+
+> [!IMPORTANT]
+> 远程模型、纹理、贴图和字体必须提供允许当前页面来源访问的 CORS 响应头
+>
+> 被浏览器阻止或污染 Canvas 的资源可能无法加载，也会导致 PNG 导出失败
+
+## 基本用法
+
+与框架无关的 Library 入口可以挂载到任意两个 DOM 容器中：
+
+CustomForge 仅支持浏览器环境，应在 DOM 挂载容器可用后创建实例
+
+编辑器和查看器必须使用两个不同的容器；页面卸载、组件卸载或不再使用实例时必须调用 `destroy()` 释放 Fabric、WebGL、观察器和事件资源
+
+```html
+<div id="texture-editor"></div>
+<div id="product-viewer"></div>
+```
+
+```ts
+import { createCustomizer } from 'customforge'
+import 'customforge/style.css'
+
+const customizer = await createCustomizer({
+  editor: '#texture-editor',
+  viewer: '#product-viewer',
+  editorWidth: 1024,
+  editorHeight: 512,
+  product: {
+    modelUrl: 'https://example.com/product.glb',
+    textureUrl: 'https://example.com/base-texture.png',
+    surfaceMesh: 'PrintArea',
+    textureFlipY: false,
+  },
+})
+
+customizer.addText({
+  text: 'Hello world',
+  x: 120,
+  y: 180,
+  fontSize: 64,
+  color: '#172126',
+})
+
+await customizer.addImage({
+  src: 'https://example.com/logo.png',
+  x: 720,
+  y: 240,
+  width: 220,
+})
+
+window.addEventListener('beforeunload', () => customizer.destroy(), {
+  once: true,
+})
+```
+
+公开包与本地 `.tgz` 使用相同的根入口和样式入口；需要可重复安装时应固定具体 alpha 版本
+
+## Design JSON
+
+`saveDesign()` 返回由 Library 自身定义、可安全写入 JSON 的文档，不暴露 Fabric.js 序列化格式。`loadDesign()` 校验未知输入，并异步恢复可编辑对象栈：
+
+```ts
+const design = customizer.saveDesign()
+localStorage.setItem('customforge-design', JSON.stringify(design))
+
+const savedDesign = localStorage.getItem('customforge-design')
+if (savedDesign) {
+  await customizer.loadDesign(JSON.parse(savedDesign))
+}
+```
+
+当前 Schema 版本为 `1`。文档保存逻辑画布尺寸，并按从后到前的渲染顺序保存文字和图片对象，包括稳定对象 ID 与基于中心点的变换
+
+Design JSON 有意排除产品模型、目标 Mesh 和基础纹理。文档只能加载到逻辑宽高完全相同的编辑器中
+
+加载具有事务性：只有文档校验通过且全部引用图片成功加载后，当前设计才会被替换。Blob URL 图片会在添加时转换为 Data URL；远程图片仍保留 URL，恢复时必须继续满足浏览器 CORS 要求
+
+该 Schema 目前仍属于 alpha 契约，后续 alpha 版本可能调整
+
+## 实例 API
+
+| 方法 | 说明 |
+| --- | --- |
+| `addText(options)` | 添加并选中文字，自动约束在画布内 |
+| `addImage(options)` | 加载并选中图片，自动约束在画布内 |
+| `deleteSelected()` | 删除当前对象或选区 |
+| `saveDesign()` | 返回当前版本化 Design JSON 文档 |
+| `loadDesign(value)` | 校验并以事务方式恢复 Design JSON |
+| `loadProduct(product)` | 更换模型、基础纹理和目标 Mesh |
+| `exportTexture(filename?)` | 将合成纹理下载为 PNG |
+| `resetView()` | 恢复默认三维相机位置 |
+| `on(event, listener)` | 订阅实例事件，并返回取消订阅函数 |
+| `destroy()` | 释放 DOM 事件、Fabric 状态和 WebGL 资源 |
+
+当前事件包括 `ready`、`change`、`selectionchange`、`status` 和 `error`
+
+首个 alpha 的稳定候选边界只包括上表方法、`createCustomizer`、`ProductCustomizer` 以及从根入口导出的配置、事件和 Design JSON 类型
+
+`ProductCustomizer` 不公开 Fabric.js 编辑器和 Three.js 查看器实例，使用方只通过门面 API 操作定制器
+
+不支持从 `core`、`editor`、`viewer`、`bridge` 或其他未声明的包子路径导入模块
+
+## 架构
+
+```mermaid
+flowchart LR
+    A[文字和图片] --> B[DesignEditor]
+    C[基础纹理] --> B
+    B --> D[HTML Canvas]
+    D --> E[TextureBridge]
+    E --> F[Three.js CanvasTexture]
+    G[GLB / GLTF 模型] --> H[ProductViewer]
+    F --> H
+    H --> I[可定制 Mesh]
+```
+
+```text
+ProductCustomizer
+|-- DesignEditor      Fabric.js 渲染和对象交互
+|-- ProductViewer     Three.js 场景、模型、材质和相机
+`-- TextureBridge     Canvas 到材质的同步
+```
+
+`ProductCustomizer` 负责协调各模块，并将 Fabric.js 和 Three.js 的实现细节隐藏在小型实例 API 后面
+
+演示界面使用原生 TypeScript，核心不依赖 Vue、React 或其他 UI 框架
+
+## 模型约定
+
+当前原型要求：
+
+- GLB 或 GLTF 模型包含有效的 UV 坐标
+- 模型未经压缩，能够由标准 Three.js `GLTFLoader` 直接加载
+- 模型具有一个用于定制表面的命名 Mesh，例如 `PrintArea`
+- 目标纹理位于该 Mesh 的第一个材质槽中
+- 浏览器可以在 CORS 策略下访问远程资源地址
+
+内置演示同样遵循 `PrintArea` Mesh 命名约定
+
+## 项目结构
+
+```text
+src/
+|-- bridge/           Canvas 与 Three.js 纹理同步
+|-- core/             公共类型、配置和 DOM 工具
+|-- customizer/       公共实例编排
+|-- demo/             可运行的工作台界面
+|-- editor/           Fabric.js 设计画布
+|-- style.css         Library 公开样式入口
+|-- styles/           Library 核心样式
+|-- viewer/           Three.js 产品预览
+`-- index.ts          与框架无关的源码入口
+
+examples/
+`-- npm-consumer/     本地 .tgz 独立消费示例
+
+scripts/
+`-- verify-package.mjs  npm 文件和制品边界检查
+```
+
+## 开发命令
+
+```bash
+pnpm check       # TypeScript 项目检查
+pnpm test        # 单元测试
+pnpm build       # 类型检查和生产构建
+pnpm build:lib   # 构建 ESM、类型声明和核心样式
+pnpm verify:package # 检查 dist 和 npm 文件清单
+pnpm pack:local  # 构建、检查并生成本地 .tgz
+pnpm release:check # 执行检查、测试、制品构建、校验和本地打包
+pnpm preview     # 预览生产构建
+```
+
+## 当前范围
+
+这是一个早期技术原型
+
+公共 API 和设计文档格式尚未稳定
+
+当前里程碑有意聚焦于一张纹理和一个可定制 Mesh
+
+在 API 和 Design JSON 契约进入更稳定阶段前，公开 npm 版本统一使用 `alpha` dist-tag
+
+多定制面、撤销与重做和框架适配器仍未实现。撤销与重做是下一阶段计划，并将复用 Design JSON 快照契约
+
+## 技术栈
+
+- [Fabric.js](https://fabricjs.com/)：二维编辑画布
+- [Three.js](https://threejs.org/)：模型加载和实时三维渲染
+- [Vite](https://vite.dev/)：开发环境和应用构建
+- [TypeScript](https://www.typescriptlang.org/)：启用严格类型检查
+
+## 开源协议
+
+CustomForge 依据 Apache License 2.0 开源
+
+完整协议内容请参阅 [LICENSE](./LICENSE)
+
+第三方依赖和资产仍遵循各自的许可条款

package/dist/bridge/TextureBridge.d.ts

@@ -0,0 +1,31 @@
+import { CanvasTexture } from 'three';
+import type { DesignEditor } from '../editor/DesignEditor';
+import type { ProductViewer } from '../viewer/ProductViewer';
+/**
+ * 将二维编辑画布转换为 Three.js 实时纹理
+ *
+ * 多次画布渲染会合并到下一个动画帧，避免重复标记纹理更新
+ */
+export declare class TextureBridge {
+    /** 绑定到三维产品材质的实时 CanvasTexture */
+    readonly texture: CanvasTexture;
+    private readonly stopListening;
+    private updateFrame;
+    /**
+     * @param editor 提供底层 HTML Canvas 和渲染事件的二维编辑器
+     * @param viewer 接收实时纹理的三维查看器
+     * @param flipY 是否垂直翻转纹理
+     */
+    constructor(editor: DesignEditor, viewer: ProductViewer, flipY: boolean);
+    /**
+     * 更新纹理垂直翻转状态并立即标记刷新
+     *
+     * @param flipY 是否垂直翻转纹理
+     */
+    setFlipY(flipY: boolean): void;
+    /** 取消编辑器订阅、动画帧并释放 CanvasTexture */
+    destroy(): void;
+    /** 将同一帧内的多次画布渲染合并为一次纹理更新 */
+    private scheduleUpdate;
+}
+//# sourceMappingURL=TextureBridge.d.ts.map

package/dist/bridge/TextureBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextureBridge.d.ts","sourceRoot":"","sources":["../../src/bridge/TextureBridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,OAAO,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAE5D;;;;GAIG;AACH,qBAAa,aAAa;IACxB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAE/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAY;IAC1C,OAAO,CAAC,WAAW,CAAI;IAEvB;;;;OAIG;IACH,YAAY,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAStE;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAG7B;IAED,mCAAmC;IACnC,OAAO,IAAI,IAAI,CAId;IAED,4BAA4B;IAC5B,OAAO,CAAC,cAAc;CAUvB"}

package/dist/core/config.d.ts

@@ -0,0 +1,26 @@
+import type { ProductConfiguration } from './types';
+/** 默认接收实时纹理的 Mesh 名称 */
+export declare const DEFAULT_SURFACE_MESH = "PrintArea";
+/**
+ * 完成默认值补全后的内部产品配置
+ */
+export interface NormalizedProductConfiguration {
+    /** 清理空白后的模型地址 */
+    modelUrl?: string;
+    /** 清理空白后的基础纹理地址 */
+    textureUrl?: string;
+    /** 接收实时纹理的 Mesh 名称 */
+    surfaceMesh: string;
+    /** 是否垂直翻转 CanvasTexture */
+    textureFlipY: boolean;
+}
+/**
+ * 清理产品配置并补全运行所需的默认值
+ *
+ * 远程模型默认不翻转纹理，内置演示模型默认翻转纹理
+ *
+ * @param product 外部传入的产品配置
+ * @returns 可以直接交给编辑器和查看器使用的完整配置
+ */
+export declare function normalizeProductConfiguration(product?: ProductConfiguration): NormalizedProductConfiguration;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEnD,wBAAwB;AACxB,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,iBAAiB;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,mBAAmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAA;IAEnB,2BAA2B;IAC3B,YAAY,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,oBAAyB,GACjC,8BAA8B,CAWhC"}

package/dist/core/design.d.ts

@@ -0,0 +1,12 @@
+import type { DesignDocument } from './types';
+/** 当前支持的 Design JSON Schema 版本 */
+export declare const DESIGN_SCHEMA_VERSION = 1;
+/**
+ * 校验并净化外部 Design JSON
+ *
+ * @param value JSON.parse 结果或其他未知输入
+ * @returns 只包含当前 Schema 字段的新设计文档
+ * @throws 文档版本、字段类型、对象 ID 或图片来源不符合契约时抛出 TypeError
+ */
+export declare function parseDesignDocument(value: unknown): DesignDocument;
+//# sourceMappingURL=design.d.ts.map

package/dist/core/design.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.d.ts","sourceRoot":"","sources":["../../src/core/design.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,SAAS,CAAA;AAEhB,kCAAkC;AAClC,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAyFtC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA4BlE"}

package/dist/core/dom.d.ts

@@ -0,0 +1,11 @@
+import type { ElementTarget } from './types';
+/**
+ * 将 HTMLElement 或 CSS 选择器解析为挂载容器
+ *
+ * @param target DOM 元素或 CSS 选择器
+ * @param label 错误消息中使用的容器名称
+ * @returns 解析得到的 DOM 元素
+ * @throws CSS 选择器无法找到对应元素时抛出错误
+ */
+export declare function resolveElement(target: ElementTarget, label: string): HTMLElement;
+//# sourceMappingURL=dom.d.ts.map

package/dist/core/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/core/dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAWhF"}

package/dist/core/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * DOM 元素或用于查找元素的 CSS 选择器
+ */
+export type ElementTarget = HTMLElement | string;
+/**
+ * 产品配置
+ */
+export interface ProductConfiguration {
+    /** GLB 或 GLTF 模型的远程地址，不传时使用内置演示模型 */
+    modelUrl?: string;
+    /** 二维编辑器使用的可选基础纹理地址 */
+    textureUrl?: string;
+    /** 接收实时纹理的模型 Mesh 名称，默认为 PrintArea */
+    surfaceMesh?: string;
+    /** 是否在映射到三维模型前垂直翻转纹理 */
+    textureFlipY?: boolean;
+}
+/**
+ * 产品定制器初始化配置
+ */
+export interface CustomizerOptions {
+    /** 二维编辑器的挂载元素或 CSS 选择器 */
+    editor: ElementTarget;
+    /** 三维查看器的挂载元素或 CSS 选择器 */
+    viewer: ElementTarget;
+    /** 二维编辑画布的逻辑宽度，单位为像素，默认为 1024 */
+    editorWidth?: number;
+    /** 二维编辑画布的逻辑高度，单位为像素，默认为 512 */
+    editorHeight?: number;
+    /** 初始化时加载的产品配置 */
+    product?: ProductConfiguration;
+}
+/**
+ * 添加文字时使用的配置
+ *
+ * 创建后和用户变换期间，文字包围盒会自动约束在编辑画布内
+ */
+export interface AddTextOptions {
+    /** 文字内容 */
+    text?: string;
+    /** 文字左上角在画布中的横坐标，单位为像素，越界时自动修正 */
+    x?: number;
+    /** 文字左上角在画布中的纵坐标，单位为像素，越界时自动修正 */
+    y?: number;
+    /** 文字编辑框宽度，单位为像素，包围盒过大时会等比缩小 */
+    width?: number;
+    /** 字体名称 */
+    fontFamily?: string;
+    /** 字体大小，单位为像素 */
+    fontSize?: number;
+    /** 文字颜色，支持 CSS 颜色值 */
+    color?: string;
+}
+/**
+ * 添加图片时使用的配置
+ *
+ * 创建后和用户变换期间，图片包围盒会自动约束在编辑画布内
+ */
+export interface AddImageOptions {
+    /** 图片地址，支持远程地址、Data URL 和 Blob URL */
+    src: string;
+    /** 图片中心在画布中的横坐标，单位为像素，越界时自动修正 */
+    x?: number;
+    /** 图片中心在画布中的纵坐标，单位为像素，越界时自动修正 */
+    y?: number;
+    /** 图片添加到画布后的显示宽度，单位为像素，包围盒过大时会等比缩小 */
+    width?: number;
+}
+/** Design JSON 使用的画布逻辑尺寸 */
+export interface DesignCanvas {
+    /** 画布逻辑宽度，单位为像素 */
+    width: number;
+    /** 画布逻辑高度，单位为像素 */
+    height: number;
+}
+/** Design JSON 中所有可编辑对象共用的变换 */
+export interface DesignObjectTransform {
+    /** 对象中心在画布中的横坐标，单位为像素 */
+    x: number;
+    /** 对象中心在画布中的纵坐标，单位为像素 */
+    y: number;
+    /** 对象相对于原始尺寸的横向缩放倍数 */
+    scaleX: number;
+    /** 对象相对于原始尺寸的纵向缩放倍数 */
+    scaleY: number;
+    /** 对象顺时针旋转角度，单位为度 */
+    rotation: number;
+    /** 是否沿对象自身横轴翻转 */
+    flipX: boolean;
+    /** 是否沿对象自身纵轴翻转 */
+    flipY: boolean;
+}
+/** Design JSON 中的文字对象 */
+export interface TextDesignObject {
+    /** 文档内稳定且唯一的对象标识 */
+    id: string;
+    /** 用于区分联合类型的对象种类 */
+    type: 'text';
+    /** 对象位置和变换 */
+    transform: DesignObjectTransform;
+    /** 文字内容，可以为空字符串 */
+    text: string;
+    /** 未应用缩放前的文字编辑框宽度，单位为像素 */
+    width: number;
+    /** 字体名称，恢复时依赖消费页面提供对应字体 */
+    fontFamily: string;
+    /** 未应用缩放前的字体大小，单位为像素 */
+    fontSize: number;
+    /** 文字颜色，仅保存 CSS 字符串颜色 */
+    color: string;
+}
+/** Design JSON 中的图片对象 */
+export interface ImageDesignObject {
+    /** 文档内稳定且唯一的对象标识 */
+    id: string;
+    /** 用于区分联合类型的对象种类 */
+    type: 'image';
+    /** 对象位置和变换 */
+    transform: DesignObjectTransform;
+    /** 可重新加载的远程 URL 或 Data URL，不允许短生命周期 Blob URL */
+    src: string;
+}
+/** Design JSON 当前支持的可编辑对象 */
+export type DesignObject = TextDesignObject | ImageDesignObject;
+/**
+ * 可持久化并恢复的单画布设计文档
+ *
+ * 只包含二维可编辑对象，不包含产品模型、目标 Mesh 或基础纹理配置
+ */
+export interface DesignDocument {
+    /** Schema 版本，当前固定为 1 */
+    version: 1;
+    /** 保存设计时使用的逻辑画布尺寸 */
+    canvas: DesignCanvas;
+    /** 按渲染层级从后到前排列的可编辑对象 */
+    objects: DesignObject[];
+}
+/**
+ * 产品定制器事件及其载荷
+ */
+export interface CustomizerEventMap {
+    /** 二维设计发生变化 */
+    change: {
+        objectCount: number;
+    };
+    /** 模型、纹理或图片处理失败 */
+    error: {
+        error: Error;
+    };
+    /** 产品模型和纹理完成加载 */
+    ready: {
+        product: ProductConfiguration;
+    };
+    /** 二维编辑器的选中状态发生变化 */
+    selectionchange: {
+        hasSelection: boolean;
+    };
+    /** 加载或运行状态发生变化 */
+    status: {
+        message: string;
+    };
+}
+/**
+ * 产品定制器支持的事件名称
+ */
+export type CustomizerEventName = keyof CustomizerEventMap;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/customizer/ProductCustomizer.d.ts

@@ -0,0 +1,106 @@
+import type { AddImageOptions, AddTextOptions, CustomizerEventMap, CustomizerEventName, CustomizerOptions, DesignDocument, ProductConfiguration } from '../core/types';
+type EventListener<K extends CustomizerEventName> = (detail: CustomizerEventMap[K]) => void;
+/**
+ * 统一管理二维编辑器、三维查看器和实时纹理同步
+ *
+ * 仅支持具有 DOM、Canvas、WebGL 和 ResizeObserver 的浏览器环境
+ * 每个实例独立持有 DOM 事件、Fabric 状态和 WebGL 资源
+ * 不再使用实例时必须调用 `destroy()`
+ */
+export declare class ProductCustomizer {
+    private readonly events;
+    private readonly textureBridge;
+    private readonly editor;
+    private readonly viewer;
+    private product;
+    private readonly stopSelectionListener;
+    private readonly stopRenderListener;
+    private destroyed;
+    private constructor();
+    /**
+     * 创建实例并完成初始产品加载
+     *
+     * @param options 产品定制器初始化配置
+     * @returns 初始化完成的产品定制器实例
+     * @throws DOM 容器无效或初始化失败时释放已创建资源并继续抛出原始错误
+     */
+    static create(options: CustomizerOptions): Promise<ProductCustomizer>;
+    /**
+     * 订阅产品定制器事件
+     *
+     * @param event 事件名称
+     * @param listener 接收对应事件载荷的监听函数
+     * @returns 用于取消本次订阅的函数
+     */
+    on<K extends CustomizerEventName>(event: K, listener: EventListener<K>): () => void;
+    /**
+     * 在二维画布中添加并选中一个文字对象
+     *
+     * 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
+     *
+     * @param options 文字内容、位置和样式配置
+     */
+    addText(options?: AddTextOptions): void;
+    /**
+     * 加载图片并将其添加到二维画布
+     *
+     * 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
+     *
+     * @param options 图片地址、位置和显示宽度
+     * @throws 图片无法访问、加载失败或被 CORS 策略阻止时抛出错误
+     */
+    addImage(options: AddImageOptions): Promise<void>;
+    /**
+     * 删除二维编辑器中的当前对象或选区
+     *
+     * @returns 是否删除了至少一个对象
+     */
+    deleteSelected(): boolean;
+    /**
+     * 创建当前二维设计的版本化 JSON 快照
+     *
+     * 快照不包含产品模型、目标 Mesh 或基础纹理配置
+     * Blob URL 图片会在添加时转换为 Data URL，因此返回值可以跨页面会话保存
+     *
+     * @returns 可以安全传给 JSON.stringify 的 DesignDocument
+     * @throws 设计中存在不支持的对象或文字填充时抛出错误
+     */
+    saveDesign(): DesignDocument;
+    /**
+     * 校验并恢复版本化 Design JSON
+     *
+     * 图片全部加载成功后才替换当前二维对象，产品和基础纹理保持不变
+     * 输入画布尺寸必须与当前编辑器的逻辑尺寸完全一致
+     *
+     * @param value JSON.parse 结果或符合 DesignDocument 的对象
+     * @throws Schema 无效、画布尺寸不匹配或图片加载失败时抛出错误
+     */
+    loadDesign(value: unknown): Promise<void>;
+    /**
+     * 将当前二维设计合成为 PNG 并触发浏览器下载
+     *
+     * @param filename 下载文件名，默认为 `custom-texture.png`
+     * @throws 远程图片污染 Canvas 时可能抛出安全错误
+     */
+    exportTexture(filename?: string): void;
+    /** 恢复三维产品的默认相机位置 */
+    resetView(): void;
+    /**
+     * 更换模型、基础纹理和接收纹理的目标 Mesh
+     *
+     * @param product 新的产品配置
+     * @throws 模型或纹理加载失败、目标 Mesh 不存在时抛出错误
+     */
+    loadProduct(product: ProductConfiguration): Promise<void>;
+    /**
+     * 释放事件监听、Fabric Canvas、纹理和 WebGL 资源
+     *
+     * 重复调用不会再次释放资源，首次调用后不得继续使用其他实例方法
+     */
+    destroy(): void;
+    private initialize;
+    private emit;
+    private reportError;
+}
+export {};
+//# sourceMappingURL=ProductCustomizer.d.ts.map

package/dist/customizer/ProductCustomizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductCustomizer.d.ts","sourceRoot":"","sources":["../../src/customizer/ProductCustomizer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACrB,MAAM,eAAe,CAAA;AAKtB,KAAK,aAAa,CAAC,CAAC,SAAS,mBAAmB,IAAI,CAClD,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAC1B,IAAI,CAAA;AAET;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,OAAO,CAAkD;IACjE,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAY;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAY;IAC/C,OAAO,CAAC,SAAS,CAAQ;IAEzB,OAAO,eA0BN;IAED;;;;;;OAMG;IACH,OAAa,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAS1E;IAED;;;;;;OAMG;IACH,EAAE,CAAC,CAAC,SAAS,mBAAmB,EAC9B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,MAAM,IAAI,CAMZ;IAED;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAEtC;IAED;;;;;;;OAOG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtD;IAED;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAExB;IAED;;;;;;;;OAQG;IACH,UAAU,IAAI,cAAc,CAE3B;IAED;;;;;;;;OAQG;IACG,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9C;IAED;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAErC;IAED,oBAAoB;IACpB,SAAS,IAAI,IAAI,CAEhB;IAED;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9D;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAWd;YAEa,UAAU;IAOxB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,WAAW;CAKpB"}