customforge 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/ProductCustomizer-rMRyWe7L.js

@@ -0,0 +1,1624 @@
+import { Canvas, FabricImage, Textbox } from "fabric";
+import { ACESFilmicToneMapping, Box3, CanvasTexture, CircleGeometry, Color, CylinderGeometry, DirectionalLight, Group, HemisphereLight, MathUtils, Mesh, MeshStandardMaterial, PerspectiveCamera, PlaneGeometry, SRGBColorSpace, Scene, TorusGeometry, Vector3, WebGLRenderer } from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+/**
+* 清理产品配置并补全运行所需的默认值
+*
+* 远程模型默认不翻转纹理，内置演示模型默认翻转纹理
+*
+* @param product 外部传入的产品配置
+* @returns 可以直接交给编辑器和查看器使用的完整配置
+*/
+function normalizeProductConfiguration(product = {}) {
+	const modelUrl = product.modelUrl?.trim() || void 0;
+	return {
+		modelUrl,
+		textureUrl: product.textureUrl?.trim() || void 0,
+		surfaceMesh: product.surfaceMesh?.trim() || "PrintArea",
+		textureFlipY: product.textureFlipY ?? !modelUrl
+	};
+}
+//#endregion
+//#region src/core/dom.ts
+/**
+* 将 HTMLElement 或 CSS 选择器解析为挂载容器
+*
+* @param target DOM 元素或 CSS 选择器
+* @param label 错误消息中使用的容器名称
+* @returns 解析得到的 DOM 元素
+* @throws CSS 选择器无法找到对应元素时抛出错误
+*/
+function resolveElement(target, label) {
+	if (target instanceof HTMLElement) return target;
+	const element = document.querySelector(target);
+	if (!element) throw new Error(`${label} element was not found: ${target}`);
+	return element;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readRecord(value, path) {
+	if (!isRecord(value)) throw new TypeError(`${path} must be an object`);
+	return value;
+}
+function readString(value, path, allowEmpty = false) {
+	if (typeof value !== "string" || !allowEmpty && value.trim().length === 0) throw new TypeError(`${path} must be ${allowEmpty ? "a string" : "a non-empty string"}`);
+	return value;
+}
+function readFiniteNumber(value, path) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${path} must be a finite number`);
+	return value;
+}
+function readPositiveNumber(value, path) {
+	const number = readFiniteNumber(value, path);
+	if (number <= 0) throw new TypeError(`${path} must be greater than zero`);
+	return number;
+}
+function readBoolean(value, path) {
+	if (typeof value !== "boolean") throw new TypeError(`${path} must be a boolean`);
+	return value;
+}
+function readImageRole(value, path) {
+	if (value !== "element" && value !== "background") throw new TypeError(`${path} must be element or background`);
+	return value;
+}
+function parseObjectState(object, path) {
+	return {
+		...object.name === void 0 ? {} : { name: readString(object.name, `${path}.name`).trim() },
+		visible: object.visible === void 0 ? true : readBoolean(object.visible, `${path}.visible`),
+		locked: object.locked === void 0 ? false : readBoolean(object.locked, `${path}.locked`)
+	};
+}
+function parseTransform(value, path) {
+	const transform = readRecord(value, path);
+	return {
+		x: readFiniteNumber(transform.x, `${path}.x`),
+		y: readFiniteNumber(transform.y, `${path}.y`),
+		scaleX: readPositiveNumber(transform.scaleX, `${path}.scaleX`),
+		scaleY: readPositiveNumber(transform.scaleY, `${path}.scaleY`),
+		rotation: readFiniteNumber(transform.rotation, `${path}.rotation`),
+		flipX: readBoolean(transform.flipX, `${path}.flipX`),
+		flipY: readBoolean(transform.flipY, `${path}.flipY`)
+	};
+}
+function parseObject(value, index) {
+	const path = `design.objects[${index}]`;
+	const object = readRecord(value, path);
+	const id = readString(object.id, `${path}.id`);
+	const transform = parseTransform(object.transform, `${path}.transform`);
+	const state = parseObjectState(object, path);
+	if (object.type === "text") return {
+		id,
+		type: "text",
+		...state,
+		transform,
+		text: readString(object.text, `${path}.text`, true),
+		width: readPositiveNumber(object.width, `${path}.width`),
+		fontFamily: readString(object.fontFamily, `${path}.fontFamily`),
+		fontSize: readPositiveNumber(object.fontSize, `${path}.fontSize`),
+		color: readString(object.color, `${path}.color`)
+	};
+	if (object.type === "image") {
+		const src = readString(object.src, `${path}.src`);
+		if (src.startsWith("blob:")) throw new TypeError(`${path}.src must not use a Blob URL`);
+		return {
+			id,
+			type: "image",
+			...state,
+			transform,
+			src,
+			...object.role === void 0 ? {} : { role: readImageRole(object.role, `${path}.role`) }
+		};
+	}
+	throw new TypeError(`${path}.type is not supported`);
+}
+/**
+* 校验并净化外部 Design JSON
+*
+* @param value JSON.parse 结果或其他未知输入
+* @returns 只包含当前 Schema 字段的新设计文档
+* @throws 文档版本、字段类型、对象 ID 或图片来源不符合契约时抛出 TypeError
+*/
+function parseDesignDocument(value) {
+	const design = readRecord(value, "design");
+	if (design.version !== 1) throw new TypeError(`design.version must be 1`);
+	const canvas = readRecord(design.canvas, "design.canvas");
+	if (!Array.isArray(design.objects)) throw new TypeError("design.objects must be an array");
+	const objects = design.objects.map(parseObject);
+	const ids = /* @__PURE__ */ new Set();
+	let backgroundCount = 0;
+	for (const object of objects) {
+		if (ids.has(object.id)) throw new TypeError(`design object id is duplicated: ${object.id}`);
+		ids.add(object.id);
+		if (object.type === "image" && object.role === "background") {
+			backgroundCount += 1;
+			if (backgroundCount > 1) throw new TypeError("design must not contain more than one background");
+			if (objects.indexOf(object) !== 0) throw new TypeError("design background must be the first object");
+		}
+	}
+	return {
+		version: 1,
+		canvas: {
+			width: readPositiveNumber(canvas.width, "design.canvas.width"),
+			height: readPositiveNumber(canvas.height, "design.canvas.height")
+		},
+		objects
+	};
+}
+//#endregion
+//#region src/editor/DesignHistory.ts
+/** 固定容量的设计快照历史 */
+var DesignHistory = class {
+	limit;
+	entries;
+	index = 0;
+	/**
+	* @param initial 初始设计快照
+	* @param limit 最多保留的撤销步骤数量
+	*/
+	constructor(initial, limit) {
+		this.limit = limit;
+		if (!Number.isInteger(limit) || limit < 1) throw new RangeError("History limit must be a positive integer");
+		this.entries = [initial];
+	}
+	/** 当前撤销与重做可用状态 */
+	get state() {
+		return {
+			canUndo: this.index > 0,
+			canRedo: this.index < this.entries.length - 1
+		};
+	}
+	/** 当前步骤之前的快照 */
+	peekUndo() {
+		return this.entries[this.index - 1];
+	}
+	/** 当前步骤之后的快照 */
+	peekRedo() {
+		return this.entries[this.index + 1];
+	}
+	/** 添加新快照并丢弃当前步骤之后的重做分支 */
+	push(snapshot) {
+		this.entries.splice(this.index + 1);
+		this.entries.push(snapshot);
+		if (this.entries.length > this.limit + 1) this.entries.splice(0, this.entries.length - this.limit - 1);
+		this.index = this.entries.length - 1;
+	}
+	/** 在目标快照成功恢复后确认一次撤销 */
+	confirmUndo() {
+		if (this.index > 0) this.index -= 1;
+	}
+	/** 在目标快照成功恢复后确认一次重做 */
+	confirmRedo() {
+		if (this.index < this.entries.length - 1) this.index += 1;
+	}
+	/** 以当前快照重新开始历史记录 */
+	reset(snapshot) {
+		this.entries = [snapshot];
+		this.index = 0;
+	}
+};
+//#endregion
+//#region src/editor/objectBounds.ts
+/**
+* 计算对象完整进入画布所需的最大等比缩放系数
+*
+* @param bounds 对象当前的轴对齐包围盒
+* @param canvasWidth 画布逻辑宽度
+* @param canvasHeight 画布逻辑高度
+* @returns 不大于 1 的缩放系数，对象已经可容纳时返回 1
+*/
+function calculateContainmentScale(bounds, canvasWidth, canvasHeight) {
+	const widthScale = bounds.width > canvasWidth ? canvasWidth / bounds.width : 1;
+	const heightScale = bounds.height > canvasHeight ? canvasHeight / bounds.height : 1;
+	return Math.min(widthScale, heightScale, 1);
+}
+/**
+* 计算可容纳对象移回画布所需的平移距离
+*
+* 调用前应先确保包围盒不大于画布，否则无法同时满足两侧边界
+*
+* @param bounds 对象当前的轴对齐包围盒
+* @param canvasWidth 画布逻辑宽度
+* @param canvasHeight 画布逻辑高度
+* @returns 应叠加到对象位置的画布坐标偏移量
+*/
+function calculateContainmentOffset(bounds, canvasWidth, canvasHeight) {
+	return {
+		x: bounds.left < 0 ? -bounds.left : Math.min(0, canvasWidth - bounds.left - bounds.width),
+		y: bounds.top < 0 ? -bounds.top : Math.min(0, canvasHeight - bounds.top - bounds.height)
+	};
+}
+//#endregion
+//#region src/editor/imageSource.ts
+function readBlobAsDataUrl(blob) {
+	return new Promise((resolve, reject) => {
+		const reader = new FileReader();
+		reader.addEventListener("load", () => {
+			if (typeof reader.result === "string") resolve(reader.result);
+			else reject(/* @__PURE__ */ new Error("Blob image could not be converted to a Data URL"));
+		});
+		reader.addEventListener("error", () => {
+			reject(reader.error ?? /* @__PURE__ */ new Error("Blob image could not be read"));
+		});
+		reader.readAsDataURL(blob);
+	});
+}
+/**
+* 将短生命周期 Blob URL 转换为可写入 Design JSON 的 Data URL
+*
+* 远程 URL 和已有 Data URL 会保持不变
+*
+* @param src 图片来源
+* @returns 可跨页面会话重新加载的图片来源
+* @throws Blob URL 已失效或浏览器无法读取对应 Blob 时抛出错误
+*/
+async function resolvePersistentImageSource(src) {
+	if (!src.startsWith("blob:")) return src;
+	const response = await fetch(src);
+	if (!response.ok) throw new Error(`Blob image could not be loaded: ${response.status}`);
+	return readBlobAsDataUrl(await response.blob());
+}
+//#endregion
+//#region src/editor/DesignEditor.ts
+/**
+* 基于 Fabric.js 的二维纹理编辑器
+*
+* 负责基础纹理、文字、图片、对象选择和 PNG 导出
+* 显示尺寸可以响应容器变化，内部逻辑尺寸保持不变
+*/
+var DesignEditor = class {
+	/** 当前实例使用的 Fabric Canvas */
+	canvas;
+	host;
+	width;
+	height;
+	renderListeners = /* @__PURE__ */ new Set();
+	selectionListeners = /* @__PURE__ */ new Set();
+	historyListeners = /* @__PURE__ */ new Set();
+	objectIds = /* @__PURE__ */ new WeakMap();
+	objectsById = /* @__PURE__ */ new Map();
+	objectNames = /* @__PURE__ */ new WeakMap();
+	objectLocks = /* @__PURE__ */ new WeakMap();
+	usedObjectIds = /* @__PURE__ */ new Set();
+	imageSources = /* @__PURE__ */ new WeakMap();
+	imageRoles = /* @__PURE__ */ new WeakMap();
+	resizeObserver;
+	history;
+	historySignature;
+	historyTimer;
+	historyBusy = false;
+	objectIdSequence = 0;
+	/**
+	* @param host 二维编辑器挂载容器
+	* @param options 画布逻辑尺寸和历史容量
+	*/
+	constructor(host, options) {
+		this.host = host;
+		this.width = options.width;
+		this.height = options.height;
+		const element = document.createElement("canvas");
+		element.setAttribute("aria-label", "UV texture editor");
+		host.replaceChildren(element);
+		this.canvas = new Canvas(element, {
+			width: this.width,
+			height: this.height,
+			backgroundColor: "#f7f7f5",
+			preserveObjectStacking: true,
+			selectionColor: "rgba(19, 113, 125, 0.12)",
+			selectionBorderColor: "#13717d"
+		});
+		const initialDesign = this.saveDesign();
+		this.history = new DesignHistory(initialDesign, options.historyLimit);
+		this.historySignature = JSON.stringify(initialDesign);
+		this.canvas.wrapperEl.classList.add("customforge-design-canvas");
+		this.host.dataset.renderState = "pending";
+		this.canvas.on("after:render", () => {
+			this.markRenderState();
+			this.renderListeners.forEach((listener) => listener());
+		});
+		const notifySelection = () => this.notifySelectionChange();
+		this.canvas.on("selection:created", notifySelection);
+		this.canvas.on("selection:updated", notifySelection);
+		this.canvas.on("selection:cleared", notifySelection);
+		const constrainTarget = ({ target }) => {
+			this.constrainObjectToCanvas(target);
+		};
+		this.canvas.on("object:moving", constrainTarget);
+		this.canvas.on("object:scaling", constrainTarget);
+		this.canvas.on("object:rotating", constrainTarget);
+		this.canvas.on("object:skewing", constrainTarget);
+		this.canvas.on("object:resizing", constrainTarget);
+		this.canvas.on("object:modified", ({ target }) => {
+			this.constrainObjectToCanvas(target);
+			this.commitHistory();
+		});
+		this.canvas.on("text:changed", ({ target }) => {
+			this.constrainObjectToCanvas(target);
+			this.scheduleHistoryCommit();
+		});
+		this.resizeObserver = new ResizeObserver(() => this.resizeDisplay());
+		this.resizeObserver.observe(host);
+		this.resizeDisplay();
+	}
+	/** 供 Three.js 创建 CanvasTexture 的底层 HTML Canvas */
+	get textureCanvas() {
+		return this.canvas.getElement();
+	}
+	/** 当前画布中设计对象的数量，不包含产品基础纹理 */
+	get objectCount() {
+		return this.canvas.getObjects().length;
+	}
+	/**
+	* 订阅 Fabric Canvas 完成渲染事件
+	*
+	* @param listener 每次画布完成渲染后调用的函数
+	* @returns 用于取消本次订阅的函数
+	*/
+	onRender(listener) {
+		this.renderListeners.add(listener);
+		return () => this.renderListeners.delete(listener);
+	}
+	/**
+	* 订阅画布选中状态变化
+	*
+	* @param listener 接收当前选中对象 ID 的函数
+	* @returns 用于取消本次订阅的函数
+	*/
+	onSelectionChange(listener) {
+		this.selectionListeners.add(listener);
+		return () => this.selectionListeners.delete(listener);
+	}
+	/**
+	* 订阅撤销与重做可用状态变化
+	*
+	* @param listener 接收最新历史状态的函数
+	* @returns 用于取消本次订阅的函数
+	*/
+	onHistoryChange(listener) {
+		this.historyListeners.add(listener);
+		return () => this.historyListeners.delete(listener);
+	}
+	/** 当前是否存在可以撤销的设计快照 */
+	get canUndo() {
+		return this.history.state.canUndo;
+	}
+	/** 当前是否存在可以重做的设计快照 */
+	get canRedo() {
+		return this.history.state.canRedo;
+	}
+	/**
+	* 返回当前对象的独立 Design JSON 快照
+	*
+	* @returns 按画布层级从后到前排列的对象数组
+	*/
+	getObjects() {
+		return this.canvas.getObjects().map((object) => this.serializeObject(object));
+	}
+	/** 当前选中对象的 ID，按画布层级从后到前排列 */
+	getSelectedObjectIds() {
+		return this.canvas.getActiveObjects().map((object) => this.objectIds.get(object)).filter((id) => Boolean(id));
+	}
+	/**
+	* 按稳定 ID 选中一个可见对象
+	*
+	* @param id Design JSON 中的对象 ID
+	* @returns 是否找到并选中了对象
+	*/
+	selectObject(id) {
+		const object = this.objectsById.get(id);
+		if (!object || !object.visible) return false;
+		this.canvas.setActiveObject(object);
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		return true;
+	}
+	/**
+	* 按稳定 ID 删除一个对象
+	*
+	* @param id Design JSON 中的对象 ID
+	* @returns 是否找到并删除了对象
+	*/
+	removeObject(id) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		if (!object) return false;
+		if (this.canvas.getActiveObjects().includes(object)) this.canvas.discardActiveObject();
+		this.canvas.remove(object);
+		this.unregisterObject(object);
+		object.dispose();
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		this.commitHistory();
+		return true;
+	}
+	/**
+	* 将对象移动到指定图层索引
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param index 从 0 开始的索引，0 表示最底层
+	* @returns 对象层级是否发生变化
+	*/
+	moveObject(id, index) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		const objects = this.canvas.getObjects();
+		if (!object || !Number.isInteger(index) || objects.length === 0) return false;
+		const currentIndex = objects.indexOf(object);
+		const role = object instanceof FabricImage ? this.imageRoles.get(object) ?? "element" : "element";
+		const backgroundCount = objects.filter((entry) => entry instanceof FabricImage && this.imageRoles.get(entry) === "background").length;
+		const minimumIndex = role === "background" ? 0 : backgroundCount;
+		const maximumIndex = role === "background" ? 0 : objects.length - 1;
+		const nextIndex = Math.min(Math.max(index, minimumIndex), maximumIndex);
+		if (currentIndex === nextIndex) return false;
+		this.canvas.moveObjectTo(object, nextIndex);
+		this.canvas.requestRenderAll();
+		this.commitHistory();
+		return true;
+	}
+	/**
+	* 修改对象在图层面板中的名称
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param name 非空图层名称
+	* @returns 是否找到并更新了对象
+	*/
+	renameObject(id, name) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		const normalizedName = name.trim();
+		if (!object || !normalizedName) return false;
+		this.objectNames.set(object, normalizedName);
+		this.canvas.requestRenderAll();
+		this.commitHistory();
+		return true;
+	}
+	/**
+	* 修改对象是否参与渲染
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param visible 是否参与二维画布、三维纹理和 PNG 渲染
+	* @returns 是否找到并更新了对象
+	*/
+	setObjectVisibility(id, visible) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		if (!object || object.visible === visible) return Boolean(object);
+		if (!visible && this.canvas.getActiveObjects().includes(object)) this.canvas.discardActiveObject();
+		object.set({ visible });
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		this.commitHistory();
+		return true;
+	}
+	/**
+	* 修改对象是否允许通过画布控件变换
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param locked 是否锁定移动、缩放、旋转、倾斜和文字编辑
+	* @returns 是否找到并更新了对象
+	*/
+	setObjectLocked(id, locked) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		if (!object) return false;
+		this.applyObjectLock(object, locked);
+		this.canvas.requestRenderAll();
+		this.commitHistory();
+		return true;
+	}
+	/**
+	* 设置铺满画布的基础纹理，不传地址时恢复默认背景色
+	*
+	* 背景纹理不参与对象选择，但会包含在实时纹理和 PNG 导出中
+	*
+	* @param url 基础纹理地址
+	* @throws 图片加载失败或被 CORS 策略阻止时抛出错误
+	*/
+	async setBackgroundTexture(url) {
+		if (!url) {
+			this.canvas.backgroundImage = void 0;
+			this.canvas.backgroundColor = "#f7f7f5";
+			this.canvas.requestRenderAll();
+			return;
+		}
+		const image = await FabricImage.fromURL(url, { crossOrigin: "anonymous" });
+		const scaleX = this.width / Math.max(image.width, 1);
+		const scaleY = this.height / Math.max(image.height, 1);
+		image.set({
+			left: 0,
+			top: 0,
+			originX: "left",
+			originY: "top",
+			scaleX,
+			scaleY,
+			selectable: false,
+			evented: false
+		});
+		this.canvas.backgroundImage = image;
+		this.canvas.requestRenderAll();
+	}
+	/**
+	* 添加并选中一个可编辑文字对象
+	*
+	* 文字位置使用画布像素坐标，原点位于对象左上角
+	* 对象过大时会等比缩小，越界时会自动移回画布
+	*
+	* @param options 文字内容、位置和样式
+	* @returns 创建的 Fabric Textbox
+	*/
+	addText(options = {}) {
+		this.flushHistoryCommit();
+		const text = new Textbox(options.text ?? "Edit this text", {
+			left: options.x ?? this.width * .18,
+			top: options.y ?? this.height * .36,
+			width: options.width ?? this.width * .42,
+			fontFamily: options.fontFamily ?? "Arial",
+			fontSize: options.fontSize ?? Math.round(this.height * .12),
+			fontWeight: 700,
+			fill: options.color ?? "#172126",
+			originX: "left",
+			originY: "top",
+			textAlign: "center",
+			editable: true,
+			transparentCorners: false,
+			cornerColor: "#ffffff",
+			cornerStrokeColor: "#13717d",
+			borderColor: "#13717d",
+			cornerSize: 16
+		});
+		this.addAndSelect(text, options.name);
+		return text;
+	}
+	/**
+	* 加载、添加并选中一个图片对象
+	*
+	* role 为 background 时替换已有设计背景、铺满画布并默认锁定在最底层
+	* 图片位置使用画布像素坐标，原点位于图片中心
+	* 对象过大时会等比缩小，越界时会自动移回画布
+	* 远程图片必须提供正确的 CORS 响应头才能安全导出 PNG
+	*
+	* @param options 图片地址、中心位置和显示宽度
+	* @returns 创建的 FabricImage
+	* @throws 图片加载失败或被 CORS 策略阻止时抛出错误
+	*/
+	async addImage(options) {
+		this.flushHistoryCommit();
+		const source = await resolvePersistentImageSource(options.src);
+		const image = await this.loadImage(source);
+		const role = options.role ?? "element";
+		const scale = (options.width ?? this.width * .22) / Math.max(image.width, 1);
+		image.set({
+			left: role === "background" ? this.width / 2 : options.x ?? this.width * .62,
+			top: role === "background" ? this.height / 2 : options.y ?? this.height * .29,
+			originX: "center",
+			originY: "center",
+			scaleX: role === "background" ? this.width / Math.max(image.width, 1) : scale,
+			scaleY: role === "background" ? this.height / Math.max(image.height, 1) : scale,
+			transparentCorners: false,
+			cornerColor: "#ffffff",
+			cornerStrokeColor: "#13717d",
+			borderColor: "#13717d",
+			cornerSize: 16
+		});
+		if (role === "background") this.removeDesignBackgrounds();
+		this.imageSources.set(image, source);
+		this.addAndSelect(image, options.name, role === "background", role);
+		return image;
+	}
+	/**
+	* 返回与 Fabric.js 无关的当前设计快照
+	*
+	* 文档包含设计背景等设计对象和逻辑画布尺寸，不包含产品基础纹理或模型配置
+	*
+	* @returns 可以安全传给 JSON.stringify 的 Design JSON 文档
+	* @throws 画布包含不支持的对象或非字符串文字填充时抛出错误
+	*/
+	saveDesign() {
+		return {
+			version: 1,
+			canvas: {
+				width: this.width,
+				height: this.height
+			},
+			objects: this.getObjects()
+		};
+	}
+	/**
+	* 校验并恢复 Design JSON，图片全部加载成功后才替换当前对象
+	*
+	* 背景纹理和当前产品保持不变，恢复后不选中任何对象
+	*
+	* @param value JSON.parse 结果或符合 DesignDocument 的对象
+	* @throws Schema 无效、画布尺寸不匹配或图片无法加载时抛出错误
+	*/
+	async loadDesign(value) {
+		this.flushHistoryCommit();
+		await this.replaceDesign(value);
+		this.commitHistory();
+	}
+	async replaceDesign(value) {
+		const design = parseDesignDocument(value);
+		if (design.canvas.width !== this.width || design.canvas.height !== this.height) throw new RangeError(`Design canvas ${design.canvas.width}x${design.canvas.height} does not match editor canvas ${this.width}x${this.height}`);
+		const entries = [];
+		try {
+			for (const object of design.objects) entries.push({
+				id: object.id,
+				object: await this.createObjectFromDesign(object),
+				source: object.type === "image" ? object.src : void 0,
+				name: object.name,
+				locked: object.locked ?? false,
+				role: object.type === "image" ? object.role ?? "element" : "element"
+			});
+		} catch (error) {
+			entries.forEach(({ object }) => object.dispose());
+			throw error;
+		}
+		const previousObjects = this.canvas.getObjects();
+		this.canvas.discardActiveObject();
+		this.canvas.remove(...previousObjects);
+		previousObjects.forEach((object) => object.dispose());
+		this.usedObjectIds.clear();
+		this.objectsById.clear();
+		for (const entry of entries) {
+			this.registerObject(entry.object, entry.id, entry.name, entry.locked, entry.role);
+			if (entry.object instanceof FabricImage && entry.source) this.imageSources.set(entry.object, entry.source);
+			this.canvas.add(entry.object);
+			this.constrainObjectToCanvas(entry.object);
+		}
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+	}
+	/**
+	* 恢复上一个设计快照
+	*
+	* @returns 是否成功恢复了一个历史步骤
+	*/
+	async undo() {
+		this.flushHistoryCommit();
+		const target = this.history.peekUndo();
+		if (!target || this.historyBusy) return false;
+		this.historyBusy = true;
+		try {
+			await this.replaceDesign(target);
+			this.history.confirmUndo();
+			this.historySignature = JSON.stringify(this.saveDesign());
+			this.notifyHistoryChange();
+			return true;
+		} finally {
+			this.historyBusy = false;
+		}
+	}
+	/**
+	* 恢复下一个设计快照
+	*
+	* @returns 是否成功恢复了一个历史步骤
+	*/
+	async redo() {
+		this.flushHistoryCommit();
+		const target = this.history.peekRedo();
+		if (!target || this.historyBusy) return false;
+		this.historyBusy = true;
+		try {
+			await this.replaceDesign(target);
+			this.history.confirmRedo();
+			this.historySignature = JSON.stringify(this.saveDesign());
+			this.notifyHistoryChange();
+			return true;
+		} finally {
+			this.historyBusy = false;
+		}
+	}
+	/** 以当前设计为起点清空撤销与重做历史 */
+	clearHistory() {
+		this.flushHistoryCommit();
+		const current = this.saveDesign();
+		this.history.reset(current);
+		this.historySignature = JSON.stringify(current);
+		this.notifyHistoryChange();
+	}
+	/**
+	* 删除当前对象或多选选区
+	*
+	* @returns 是否删除了至少一个对象
+	*/
+	deleteSelected() {
+		this.flushHistoryCommit();
+		const selection = this.canvas.getActiveObjects();
+		if (selection.length === 0) return false;
+		this.canvas.remove(...selection);
+		selection.forEach((object) => {
+			this.unregisterObject(object);
+			object.dispose();
+		});
+		this.canvas.discardActiveObject();
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		this.commitHistory();
+		return true;
+	}
+	/**
+	* 将当前画布内容导出为 PNG 并触发浏览器下载
+	*
+	* @param filename 下载文件名
+	* @throws 画布被无 CORS 授权的远程图片污染时抛出安全错误
+	*/
+	exportTexture(filename = "custom-texture.png") {
+		this.canvas.discardActiveObject();
+		this.canvas.renderAll();
+		const anchor = document.createElement("a");
+		anchor.download = filename;
+		anchor.href = this.canvas.toDataURL({
+			format: "png",
+			multiplier: 1
+		});
+		anchor.click();
+	}
+	/** 释放 ResizeObserver、事件监听和 Fabric Canvas */
+	destroy() {
+		if (this.historyTimer !== void 0) {
+			clearTimeout(this.historyTimer);
+			this.historyTimer = void 0;
+		}
+		this.resizeObserver.disconnect();
+		this.renderListeners.clear();
+		this.selectionListeners.clear();
+		this.historyListeners.clear();
+		this.objectsById.clear();
+		this.usedObjectIds.clear();
+		this.canvas.dispose();
+		this.host.replaceChildren();
+	}
+	addAndSelect(object, name, locked = false, role = "element") {
+		this.registerObject(object, void 0, name, locked, role);
+		this.canvas.add(object);
+		if (object instanceof FabricImage && role === "background") this.canvas.moveObjectTo(object, 0);
+		this.constrainObjectToCanvas(object);
+		this.canvas.setActiveObject(object);
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		this.commitHistory();
+	}
+	registerObject(object, id = this.createObjectId(), name, locked = false, role = "element") {
+		if (this.usedObjectIds.has(id)) throw new Error(`Design object id is already in use: ${id}`);
+		this.usedObjectIds.add(id);
+		this.objectIds.set(object, id);
+		this.objectsById.set(id, object);
+		if (name) this.objectNames.set(object, name);
+		if (object instanceof FabricImage) this.imageRoles.set(object, role);
+		this.applyObjectLock(object, locked);
+	}
+	unregisterObject(object) {
+		const id = this.objectIds.get(object);
+		if (id) this.objectsById.delete(id);
+	}
+	createObjectId() {
+		let id;
+		do {
+			this.objectIdSequence += 1;
+			id = `object-${this.objectIdSequence}`;
+		} while (this.usedObjectIds.has(id));
+		return id;
+	}
+	serializeObject(object) {
+		const id = this.objectIds.get(object);
+		if (!id) throw new Error("Design object is missing its stable id");
+		const transform = this.serializeTransform(object);
+		const state = {
+			name: this.objectNames.get(object) ?? this.createObjectName(object),
+			visible: object.visible,
+			locked: this.objectLocks.get(object) ?? false
+		};
+		if (object instanceof Textbox) {
+			if (typeof object.fill !== "string") throw new Error(`Text object ${id} uses an unsupported non-string fill`);
+			return {
+				id,
+				type: "text",
+				...state,
+				transform,
+				text: object.text,
+				width: object.width,
+				fontFamily: object.fontFamily,
+				fontSize: object.fontSize,
+				color: object.fill
+			};
+		}
+		if (object instanceof FabricImage) {
+			const src = this.imageSources.get(object) ?? object.getSrc();
+			if (!src || src.startsWith("blob:")) throw new Error(`Image object ${id} does not have a persistent source`);
+			return {
+				id,
+				type: "image",
+				...state,
+				transform,
+				src,
+				role: this.imageRoles.get(object) ?? "element"
+			};
+		}
+		throw new Error(`Design object ${id} has an unsupported type`);
+	}
+	serializeTransform(object) {
+		const center = object.getCenterPoint();
+		return {
+			x: center.x,
+			y: center.y,
+			scaleX: Math.abs(object.scaleX),
+			scaleY: Math.abs(object.scaleY),
+			rotation: object.angle,
+			flipX: object.scaleX < 0 ? !object.flipX : object.flipX,
+			flipY: object.scaleY < 0 ? !object.flipY : object.flipY
+		};
+	}
+	async createObjectFromDesign(design) {
+		const common = {
+			left: design.transform.x,
+			top: design.transform.y,
+			originX: "center",
+			originY: "center",
+			scaleX: design.transform.scaleX,
+			scaleY: design.transform.scaleY,
+			angle: design.transform.rotation,
+			flipX: design.transform.flipX,
+			flipY: design.transform.flipY,
+			visible: design.visible ?? true,
+			transparentCorners: false,
+			cornerColor: "#ffffff",
+			cornerStrokeColor: "#13717d",
+			borderColor: "#13717d",
+			cornerSize: 16
+		};
+		if (design.type === "text") return new Textbox(design.text, {
+			...common,
+			width: design.width,
+			fontFamily: design.fontFamily,
+			fontSize: design.fontSize,
+			fontWeight: 700,
+			fill: design.color,
+			textAlign: "center",
+			editable: true
+		});
+		const image = await this.loadImage(design.src);
+		image.set(common);
+		return image;
+	}
+	loadImage(source) {
+		return FabricImage.fromURL(source, source.startsWith("data:") ? void 0 : { crossOrigin: "anonymous" });
+	}
+	createObjectName(object) {
+		if (object instanceof Textbox) return object.text.trim().slice(0, 48) || "Text";
+		return object instanceof FabricImage ? "Image" : "Object";
+	}
+	applyObjectLock(object, locked) {
+		this.objectLocks.set(object, locked);
+		object.set({
+			hasBorders: !locked,
+			hasControls: !locked,
+			lockMovementX: locked,
+			lockMovementY: locked,
+			lockRotation: locked,
+			lockScalingX: locked,
+			lockScalingY: locked,
+			lockSkewingX: locked,
+			lockSkewingY: locked
+		});
+		if (object instanceof Textbox) object.set({ editable: !locked });
+	}
+	notifySelectionChange() {
+		const objectIds = this.getSelectedObjectIds();
+		this.selectionListeners.forEach((listener) => listener(objectIds));
+	}
+	removeDesignBackgrounds() {
+		const backgrounds = this.canvas.getObjects().filter((object) => object instanceof FabricImage && this.imageRoles.get(object) === "background");
+		if (backgrounds.length === 0) return;
+		if (backgrounds.some((object) => this.canvas.getActiveObjects().includes(object))) this.canvas.discardActiveObject();
+		this.canvas.remove(...backgrounds);
+		backgrounds.forEach((object) => {
+			this.unregisterObject(object);
+			object.dispose();
+		});
+	}
+	scheduleHistoryCommit() {
+		if (this.historyBusy) return;
+		if (this.historyTimer !== void 0) clearTimeout(this.historyTimer);
+		this.historyTimer = setTimeout(() => {
+			this.historyTimer = void 0;
+			this.commitHistory();
+		}, 320);
+	}
+	flushHistoryCommit() {
+		if (this.historyTimer === void 0) return;
+		clearTimeout(this.historyTimer);
+		this.historyTimer = void 0;
+		this.commitHistory();
+	}
+	commitHistory() {
+		if (this.historyBusy) return;
+		if (this.historyTimer !== void 0) {
+			clearTimeout(this.historyTimer);
+			this.historyTimer = void 0;
+		}
+		const snapshot = this.saveDesign();
+		const signature = JSON.stringify(snapshot);
+		if (signature === this.historySignature) return;
+		this.history.push(snapshot);
+		this.historySignature = signature;
+		this.notifyHistoryChange();
+	}
+	notifyHistoryChange() {
+		const state = this.history.state;
+		this.historyListeners.forEach((listener) => listener(state));
+	}
+	constrainObjectToCanvas(object) {
+		object.setCoords();
+		let bounds = object.getBoundingRect();
+		const scale = calculateContainmentScale(bounds, this.width, this.height);
+		if (scale < 1) {
+			object.set({
+				scaleX: object.scaleX * scale,
+				scaleY: object.scaleY * scale
+			});
+			object.setCoords();
+			bounds = object.getBoundingRect();
+		}
+		const offset = calculateContainmentOffset(bounds, this.width, this.height);
+		if (offset.x !== 0 || offset.y !== 0) {
+			object.set({
+				left: object.left + offset.x,
+				top: object.top + offset.y
+			});
+			object.setCoords();
+		}
+	}
+	resizeDisplay() {
+		const availableWidth = Math.max(this.host.clientWidth - 32, 1);
+		const availableHeight = Math.max(this.host.clientHeight - 32, 1);
+		const scale = Math.min(availableWidth / this.width, availableHeight / this.height, 1);
+		this.canvas.setDimensions({
+			width: `${Math.floor(this.width * scale)}px`,
+			height: `${Math.floor(this.height * scale)}px`
+		}, { cssOnly: true });
+	}
+	markRenderState() {
+		if (this.host.dataset.renderState === "nonblank") return;
+		const context = this.canvas.getContext();
+		let minimum = 255;
+		let maximum = 0;
+		let opaqueSamples = 0;
+		for (let row = 1; row < 8; row += 1) for (let column = 1; column < 16; column += 1) {
+			const x = Math.floor(column / 16 * this.width);
+			const y = Math.floor(row / 8 * this.height);
+			const pixel = context.getImageData(x, y, 1, 1).data;
+			const luminance = (pixel[0] + pixel[1] + pixel[2]) / 3;
+			minimum = Math.min(minimum, luminance);
+			maximum = Math.max(maximum, luminance);
+			if (pixel[3] > 0) opaqueSamples += 1;
+		}
+		if (opaqueSamples > 0 && maximum - minimum > 8) this.host.dataset.renderState = "nonblank";
+	}
+};
+//#endregion
+//#region src/bridge/TextureBridge.ts
+/**
+* 将二维编辑画布转换为 Three.js 实时纹理
+*
+* 多次画布渲染会合并到下一个动画帧，避免重复标记纹理更新
+*/
+var TextureBridge = class {
+	/** 绑定到三维产品材质的实时 CanvasTexture */
+	texture;
+	stopListening;
+	updateFrame = 0;
+	/**
+	* @param editor 提供底层 HTML Canvas 和渲染事件的二维编辑器
+	* @param viewer 接收实时纹理的三维查看器
+	* @param flipY 是否垂直翻转纹理
+	*/
+	constructor(editor, viewer, flipY) {
+		this.texture = new CanvasTexture(editor.textureCanvas);
+		this.texture.colorSpace = SRGBColorSpace;
+		this.texture.flipY = flipY;
+		this.texture.anisotropy = 4;
+		viewer.setTexture(this.texture);
+		this.stopListening = editor.onRender(() => this.scheduleUpdate());
+		this.scheduleUpdate();
+	}
+	/**
+	* 更新纹理垂直翻转状态并立即标记刷新
+	*
+	* @param flipY 是否垂直翻转纹理
+	*/
+	setFlipY(flipY) {
+		this.texture.flipY = flipY;
+		this.texture.needsUpdate = true;
+	}
+	/** 取消编辑器订阅、动画帧并释放 CanvasTexture */
+	destroy() {
+		this.stopListening();
+		cancelAnimationFrame(this.updateFrame);
+		this.texture.dispose();
+	}
+	/** 将同一帧内的多次画布渲染合并为一次纹理更新 */
+	scheduleUpdate() {
+		if (this.updateFrame) return;
+		this.updateFrame = requestAnimationFrame(() => {
+			this.updateFrame = 0;
+			this.texture.needsUpdate = true;
+		});
+	}
+};
+//#endregion
+//#region src/viewer/ProductViewer.ts
+/**
+* 基于 Three.js 的三维产品查看器
+*
+* 负责模型加载、目标 Mesh 查找、实时纹理绑定、相机控制和资源释放
+* 当前只将纹理应用到目标 Mesh 的第一个材质槽
+*/
+var ProductViewer = class {
+	host;
+	scene = new Scene();
+	camera = new PerspectiveCamera(35, 1, .05, 100);
+	renderer;
+	controls;
+	loader = new GLTFLoader();
+	resizeObserver;
+	productRoot;
+	surface;
+	texture;
+	animationFrame = 0;
+	/**
+	* @param host 三维查看器挂载容器
+	*/
+	constructor(host) {
+		this.host = host;
+		host.replaceChildren();
+		this.renderer = new WebGLRenderer({
+			antialias: true,
+			alpha: true
+		});
+		this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+		this.renderer.outputColorSpace = SRGBColorSpace;
+		this.renderer.toneMapping = ACESFilmicToneMapping;
+		this.renderer.toneMappingExposure = 1.05;
+		this.renderer.shadowMap.enabled = true;
+		this.renderer.domElement.setAttribute("aria-label", "Interactive 3D product preview");
+		this.renderer.domElement.classList.add("customforge-viewer-canvas");
+		host.append(this.renderer.domElement);
+		host.dataset.renderState = "pending";
+		this.scene.background = new Color("#eef0ef");
+		this.camera.position.set(4.6, 2.8, 5.8);
+		this.controls = new OrbitControls(this.camera, this.renderer.domElement);
+		this.controls.enableDamping = true;
+		this.controls.minDistance = 3.2;
+		this.controls.maxDistance = 11;
+		this.controls.target.set(0, 0, 0);
+		this.addEnvironment();
+		this.resizeObserver = new ResizeObserver(() => this.resize());
+		this.resizeObserver.observe(host);
+		this.resize();
+		this.render();
+	}
+	/**
+	* 加载远程模型或创建内置演示模型
+	*
+	* @param product 已完成默认值补全的产品配置
+	* @throws 模型加载失败或找不到目标 Mesh 时抛出错误
+	*/
+	async loadProduct(product) {
+		this.removeProduct();
+		if (product.modelUrl) {
+			const gltf = await this.loader.loadAsync(product.modelUrl);
+			this.productRoot = gltf.scene;
+			this.surface = this.findSurface(gltf.scene, product.surfaceMesh);
+		} else {
+			const demo = this.createDemoProduct();
+			this.productRoot = demo.root;
+			this.surface = demo.surface;
+		}
+		this.scene.add(this.productRoot);
+		if (this.texture) this.attachTexture(this.texture);
+		this.fitCamera(this.productRoot);
+	}
+	/**
+	* 保存并绑定二维编辑器生成的实时纹理
+	*
+	* 如果模型尚未加载，纹理会在模型加载完成后自动绑定
+	*
+	* @param texture 由二维画布创建的 CanvasTexture
+	*/
+	setTexture(texture) {
+		this.texture = texture;
+		if (this.surface) this.attachTexture(texture);
+	}
+	/** 根据当前模型包围盒恢复默认相机位置 */
+	resetView() {
+		if (this.productRoot) this.fitCamera(this.productRoot);
+	}
+	/** 释放动画帧、相机控制、模型材质和 WebGLRenderer */
+	destroy() {
+		cancelAnimationFrame(this.animationFrame);
+		this.resizeObserver.disconnect();
+		this.controls.dispose();
+		this.removeProduct();
+		this.renderer.dispose();
+		this.renderer.domElement.remove();
+	}
+	addEnvironment() {
+		const sky = new HemisphereLight("#ffffff", "#7c8581", 2.2);
+		this.scene.add(sky);
+		const key = new DirectionalLight("#ffffff", 3.8);
+		key.position.set(4, 6, 5);
+		key.castShadow = true;
+		this.scene.add(key);
+		const fill = new DirectionalLight("#b7dce0", 1.2);
+		fill.position.set(-5, 2, 3);
+		this.scene.add(fill);
+		const floor = new Mesh(new PlaneGeometry(30, 30), new MeshStandardMaterial({
+			color: "#dfe3e1",
+			roughness: .95
+		}));
+		floor.rotation.x = -Math.PI / 2;
+		floor.position.y = -1.34;
+		floor.receiveShadow = true;
+		this.scene.add(floor);
+	}
+	createDemoProduct() {
+		const root = new Group();
+		root.rotation.y = MathUtils.degToRad(-14);
+		const bodyMaterial = new MeshStandardMaterial({
+			color: "#ffffff",
+			roughness: .42,
+			metalness: 0
+		});
+		const surface = new Mesh(new CylinderGeometry(1.28, 1.16, 2.35, 96, 1, true), bodyMaterial);
+		surface.name = "PrintArea";
+		surface.castShadow = true;
+		surface.receiveShadow = true;
+		root.add(surface);
+		const ceramic = new MeshStandardMaterial({
+			color: "#f4f4f1",
+			roughness: .35
+		});
+		const rim = new Mesh(new TorusGeometry(1.28, .08, 20, 96), ceramic);
+		rim.rotation.x = Math.PI / 2;
+		rim.position.y = 1.18;
+		rim.castShadow = true;
+		root.add(rim);
+		const inside = new Mesh(new CircleGeometry(1.2, 96), new MeshStandardMaterial({
+			color: "#29312f",
+			roughness: .7
+		}));
+		inside.rotation.x = -Math.PI / 2;
+		inside.position.y = 1.16;
+		root.add(inside);
+		const bottom = new Mesh(new CircleGeometry(1.15, 96), ceramic);
+		bottom.rotation.x = Math.PI / 2;
+		bottom.position.y = -1.17;
+		root.add(bottom);
+		return {
+			root,
+			surface
+		};
+	}
+	/**
+	* 按名称查找接收实时纹理的 Mesh
+	*
+	* @throws 找不到对象或同名对象不是 Mesh 时抛出错误
+	*/
+	findSurface(root, meshName) {
+		const object = root.getObjectByName(meshName);
+		if (!(object instanceof Mesh)) throw new Error(`Customizable mesh was not found: ${meshName}`);
+		return object;
+	}
+	/**
+	* 将纹理应用到目标 Mesh 的第一个材质槽
+	*
+	* 非 MeshStandardMaterial 会被替换为基础标准材质
+	*/
+	attachTexture(texture) {
+		if (!this.surface) return;
+		const material = (Array.isArray(this.surface.material) ? this.surface.material : [this.surface.material])[0];
+		if (!(material instanceof MeshStandardMaterial)) {
+			const replacement = new MeshStandardMaterial({
+				color: "#ffffff",
+				roughness: .45,
+				map: texture
+			});
+			this.surface.material = replacement;
+			return;
+		}
+		material.map = texture;
+		material.color.set("#ffffff");
+		material.needsUpdate = true;
+	}
+	fitCamera(root) {
+		const bounds = new Box3().setFromObject(root);
+		const size = bounds.getSize(new Vector3());
+		const center = bounds.getCenter(new Vector3());
+		const radius = Math.max(size.x, size.y, size.z) * .5;
+		const distance = Math.max(radius / Math.tan(MathUtils.degToRad(this.camera.fov / 2)), 3);
+		this.controls.target.copy(center);
+		this.camera.position.copy(center).add(new Vector3(distance * .55, distance * .42, distance));
+		this.camera.near = Math.max(distance / 100, .01);
+		this.camera.far = distance * 100;
+		this.camera.updateProjectionMatrix();
+		this.controls.update();
+	}
+	removeProduct() {
+		if (!this.productRoot) return;
+		this.scene.remove(this.productRoot);
+		this.productRoot.traverse((object) => {
+			if (!(object instanceof Mesh)) return;
+			object.geometry.dispose();
+			(Array.isArray(object.material) ? object.material : [object.material]).forEach((material) => material.dispose());
+		});
+		this.productRoot = void 0;
+		this.surface = void 0;
+	}
+	resize() {
+		const width = Math.max(this.host.clientWidth, 1);
+		const height = Math.max(this.host.clientHeight, 1);
+		this.renderer.setSize(width, height, false);
+		this.camera.aspect = width / height;
+		this.camera.updateProjectionMatrix();
+	}
+	render = () => {
+		this.animationFrame = requestAnimationFrame(this.render);
+		this.controls.update();
+		this.renderer.render(this.scene, this.camera);
+		this.markRenderState();
+	};
+	markRenderState() {
+		if (this.host.dataset.renderState === "nonblank") return;
+		const context = this.renderer.getContext();
+		const width = context.drawingBufferWidth;
+		const height = context.drawingBufferHeight;
+		if (width < 2 || height < 2) return;
+		const pixel = /* @__PURE__ */ new Uint8Array(4);
+		let minimum = 255;
+		let maximum = 0;
+		for (const xRatio of [
+			.25,
+			.5,
+			.75
+		]) for (const yRatio of [
+			.25,
+			.5,
+			.75
+		]) {
+			context.readPixels(Math.floor(width * xRatio), Math.floor(height * yRatio), 1, 1, context.RGBA, context.UNSIGNED_BYTE, pixel);
+			const luminance = (pixel[0] + pixel[1] + pixel[2]) / 3;
+			minimum = Math.min(minimum, luminance);
+			maximum = Math.max(maximum, luminance);
+		}
+		if (maximum - minimum > 8) this.host.dataset.renderState = "nonblank";
+	}
+};
+//#endregion
+//#region src/customizer/ProductCustomizer.ts
+/**
+* 统一管理二维编辑器、三维查看器和实时纹理同步
+*
+* 仅支持具有 DOM、Canvas、WebGL 和 ResizeObserver 的浏览器环境
+* 每个实例独立持有 DOM 事件、Fabric 状态和 WebGL 资源
+* 不再使用实例时必须调用 `destroy()`
+*/
+var ProductCustomizer = class ProductCustomizer {
+	events = new EventTarget();
+	textureBridge;
+	editor;
+	viewer;
+	product;
+	stopSelectionListener;
+	stopRenderListener;
+	stopHistoryListener;
+	destroyed = false;
+	constructor(options) {
+		const editorHost = resolveElement(options.editor, "Editor");
+		const viewerHost = resolveElement(options.viewer, "Viewer");
+		if (editorHost === viewerHost) throw new Error("Editor and viewer must use different elements");
+		const historyLimit = options.historyLimit ?? 50;
+		if (!Number.isInteger(historyLimit) || historyLimit < 1) throw new RangeError("historyLimit must be a positive integer");
+		this.product = normalizeProductConfiguration(options.product);
+		this.editor = new DesignEditor(editorHost, {
+			width: options.editorWidth ?? 1024,
+			height: options.editorHeight ?? 512,
+			historyLimit
+		});
+		this.viewer = new ProductViewer(viewerHost);
+		this.textureBridge = new TextureBridge(this.editor, this.viewer, this.product.textureFlipY);
+		this.stopSelectionListener = this.editor.onSelectionChange((objectIds) => {
+			this.emit("selectionchange", {
+				hasSelection: objectIds.length > 0,
+				objectIds
+			});
+		});
+		this.stopRenderListener = this.editor.onRender(() => {
+			this.emit("change", { objectCount: this.editor.objectCount });
+		});
+		this.stopHistoryListener = this.editor.onHistoryChange((state) => {
+			this.emit("historychange", state);
+		});
+	}
+	/**
+	* 创建实例并完成初始产品加载
+	*
+	* @param options 产品定制器初始化配置
+	* @returns 初始化完成的产品定制器实例
+	* @throws DOM 容器无效或初始化失败时释放已创建资源并继续抛出原始错误
+	*/
+	static async create(options) {
+		const customizer = new ProductCustomizer(options);
+		try {
+			await customizer.initialize();
+			return customizer;
+		} catch (error) {
+			customizer.destroy();
+			throw error;
+		}
+	}
+	/**
+	* 订阅产品定制器事件
+	*
+	* @param event 事件名称
+	* @param listener 接收对应事件载荷的监听函数
+	* @returns 用于取消本次订阅的函数
+	*/
+	on(event, listener) {
+		const wrapped = (browserEvent) => {
+			listener(browserEvent.detail);
+		};
+		this.events.addEventListener(event, wrapped);
+		return () => this.events.removeEventListener(event, wrapped);
+	}
+	/**
+	* 在二维画布中添加并选中一个文字对象
+	*
+	* 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
+	*
+	* @param options 文字内容、位置和样式配置
+	*/
+	addText(options) {
+		this.editor.addText(options);
+	}
+	/**
+	* 加载图片并将其添加到二维画布
+	*
+	* role 为 background 时会替换已有设计背景并默认锁定在最底层
+	* 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
+	*
+	* @param options 图片地址、位置和显示宽度
+	* @throws 图片无法访问、加载失败或被 CORS 策略阻止时抛出错误
+	*/
+	async addImage(options) {
+		try {
+			await this.editor.addImage(options);
+		} catch (error) {
+			this.reportError(error);
+			throw error;
+		}
+	}
+	/**
+	* 返回当前可编辑对象的独立快照
+	*
+	* @returns 按画布层级从后到前排列的 Design JSON 对象
+	*/
+	getObjects() {
+		return this.editor.getObjects();
+	}
+	/** 当前选中对象的 ID，按画布层级从后到前排列 */
+	getSelectedObjectIds() {
+		return this.editor.getSelectedObjectIds();
+	}
+	/**
+	* 按稳定 ID 选中一个可见对象
+	*
+	* @param id Design JSON 中的对象 ID
+	* @returns 是否找到并选中了对象
+	*/
+	selectObject(id) {
+		return this.editor.selectObject(id);
+	}
+	/**
+	* 按稳定 ID 删除一个对象
+	*
+	* @param id Design JSON 中的对象 ID
+	* @returns 是否找到并删除了对象
+	*/
+	removeObject(id) {
+		return this.editor.removeObject(id);
+	}
+	/**
+	* 将对象移动到指定图层索引
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param index 从 0 开始的索引，0 表示最底层
+	* @returns 对象层级是否发生变化
+	*/
+	moveObject(id, index) {
+		return this.editor.moveObject(id, index);
+	}
+	/**
+	* 修改对象在图层面板中的名称
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param name 非空图层名称
+	* @returns 是否找到并更新了对象
+	*/
+	renameObject(id, name) {
+		return this.editor.renameObject(id, name);
+	}
+	/**
+	* 修改对象是否参与渲染
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param visible 是否参与二维画布、三维纹理和 PNG 渲染
+	* @returns 是否找到并更新了对象
+	*/
+	setObjectVisibility(id, visible) {
+		return this.editor.setObjectVisibility(id, visible);
+	}
+	/**
+	* 修改对象是否允许通过画布控件变换
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param locked 是否锁定移动、缩放、旋转、倾斜和文字编辑
+	* @returns 是否找到并更新了对象
+	*/
+	setObjectLocked(id, locked) {
+		return this.editor.setObjectLocked(id, locked);
+	}
+	/**
+	* 删除二维编辑器中的当前对象或选区
+	*
+	* @returns 是否删除了至少一个对象
+	*/
+	deleteSelected() {
+		return this.editor.deleteSelected();
+	}
+	/**
+	* 创建当前二维设计的版本化 JSON 快照
+	*
+	* 快照不包含产品模型、目标 Mesh 或基础纹理配置
+	* Blob URL 图片会在添加时转换为 Data URL，因此返回值可以跨页面会话保存
+	*
+	* @returns 可以安全传给 JSON.stringify 的 DesignDocument
+	* @throws 设计中存在不支持的对象或文字填充时抛出错误
+	*/
+	saveDesign() {
+		return this.editor.saveDesign();
+	}
+	/**
+	* 校验并恢复版本化 Design JSON
+	*
+	* 图片全部加载成功后才替换当前二维对象，产品和基础纹理保持不变
+	* 输入画布尺寸必须与当前编辑器的逻辑尺寸完全一致
+	*
+	* @param value JSON.parse 结果或符合 DesignDocument 的对象
+	* @throws Schema 无效、画布尺寸不匹配或图片加载失败时抛出错误
+	*/
+	async loadDesign(value) {
+		this.emit("status", { message: "Loading design" });
+		try {
+			await this.editor.loadDesign(value);
+			this.emit("status", { message: "Design loaded" });
+		} catch (error) {
+			this.reportError(error);
+			throw error;
+		}
+	}
+	/** 当前是否存在可以撤销的设计快照 */
+	canUndo() {
+		return this.editor.canUndo;
+	}
+	/** 当前是否存在可以重做的设计快照 */
+	canRedo() {
+		return this.editor.canRedo;
+	}
+	/**
+	* 恢复上一个设计快照
+	*
+	* @returns 是否成功恢复了一个历史步骤
+	* @throws 历史中的图片无法恢复时抛出错误
+	*/
+	async undo() {
+		try {
+			const changed = await this.editor.undo();
+			if (changed) this.emit("status", { message: "Undo complete" });
+			return changed;
+		} catch (error) {
+			this.reportError(error);
+			throw error;
+		}
+	}
+	/**
+	* 恢复下一个设计快照
+	*
+	* @returns 是否成功恢复了一个历史步骤
+	* @throws 历史中的图片无法恢复时抛出错误
+	*/
+	async redo() {
+		try {
+			const changed = await this.editor.redo();
+			if (changed) this.emit("status", { message: "Redo complete" });
+			return changed;
+		} catch (error) {
+			this.reportError(error);
+			throw error;
+		}
+	}
+	/** 以当前设计为起点清空撤销与重做历史 */
+	clearHistory() {
+		this.editor.clearHistory();
+	}
+	/**
+	* 将当前二维设计合成为 PNG 并触发浏览器下载
+	*
+	* @param filename 下载文件名，默认为 `custom-texture.png`
+	* @throws 远程图片污染 Canvas 时可能抛出安全错误
+	*/
+	exportTexture(filename) {
+		this.editor.exportTexture(filename);
+	}
+	/** 恢复三维产品的默认相机位置 */
+	resetView() {
+		this.viewer.resetView();
+	}
+	/**
+	* 更换模型、基础纹理和接收纹理的目标 Mesh
+	*
+	* 成功后保留当前设计对象，并将当前设计设为新的历史起点
+	*
+	* @param product 新的产品配置
+	* @throws 模型或纹理加载失败、目标 Mesh 不存在时抛出错误
+	*/
+	async loadProduct(product) {
+		const nextProduct = normalizeProductConfiguration(product);
+		this.emit("status", { message: "Loading product" });
+		try {
+			await this.viewer.loadProduct(nextProduct);
+			await this.editor.setBackgroundTexture(nextProduct.textureUrl);
+			this.textureBridge.setFlipY(nextProduct.textureFlipY);
+			this.product = nextProduct;
+			this.editor.clearHistory();
+			this.emit("ready", { product: this.product });
+			this.emit("status", { message: nextProduct.modelUrl ? "Remote product ready" : "Demo product ready" });
+		} catch (error) {
+			this.reportError(error);
+			throw error;
+		}
+	}
+	/**
+	* 释放事件监听、Fabric Canvas、纹理和 WebGL 资源
+	*
+	* 重复调用不会再次释放资源，首次调用后不得继续使用其他实例方法
+	*/
+	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.stopSelectionListener?.();
+		this.stopRenderListener?.();
+		this.stopHistoryListener?.();
+		this.textureBridge.destroy();
+		this.editor.destroy();
+		this.viewer.destroy();
+	}
+	async initialize() {
+		await this.viewer.loadProduct(this.product);
+		await this.editor.setBackgroundTexture(this.product.textureUrl);
+		this.textureBridge.setFlipY(this.product.textureFlipY);
+		this.emit("ready", { product: this.product });
+	}
+	emit(event, detail) {
+		this.events.dispatchEvent(new CustomEvent(event, { detail }));
+	}
+	reportError(error) {
+		const normalized = error instanceof Error ? error : new Error(String(error));
+		this.emit("error", { error: normalized });
+		this.emit("status", { message: normalized.message });
+	}
+};
+//#endregion
+export { resolveElement as n, ProductCustomizer as t };
+
+//# sourceMappingURL=ProductCustomizer-rMRyWe7L.js.map