customforge 0.1.0-alpha.1 → 0.1.0

package/dist/ProductCustomizer-4ytA68eg.js

@@ -0,0 +1,2350 @@
+import { ActiveSelection, Canvas, FabricImage, Point, Textbox } from "fabric";
+import { ACESFilmicToneMapping, AmbientLight, Box3, CanvasTexture, DirectionalLight, MathUtils, Mesh, MeshStandardMaterial, PerspectiveCamera, SRGBColorSpace, Scene, Vector3, WebGLRenderer } from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+/**
+* 清理产品配置并补全运行所需的默认值
+*
+* 远程模型和随包提供的默认 GLB 模型均默认不翻转纹理
+*
+* @param product 外部传入的产品配置
+* @returns 可以直接交给编辑器和查看器使用的完整配置
+*/
+function normalizeProductConfiguration(product = {}) {
+	return {
+		modelUrl: product.modelUrl?.trim() || void 0,
+		textureUrl: product.textureUrl?.trim() || void 0,
+		surfaceMesh: product.surfaceMesh?.trim() || "PrintArea",
+		textureFlipY: product.textureFlipY ?? false
+	};
+}
+//#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 readTextAlignment(value, path) {
+	if (value !== "left" && value !== "center" && value !== "right") throw new TypeError(`${path} must be left, center, or right`);
+	return value;
+}
+function readTextFontStyle(value, path) {
+	if (value !== "normal" && value !== "italic") throw new TypeError(`${path} must be normal or italic`);
+	return value;
+}
+function readTextFontWeight(value, path) {
+	if (value === "normal" || value === "bold") return value;
+	const weight = readFiniteNumber(value, path);
+	if (weight <= 0 || weight > 1e3) throw new TypeError(`${path} must be between 1 and 1000`);
+	return weight;
+}
+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`),
+		...object.fontWeight === void 0 ? {} : { fontWeight: readTextFontWeight(object.fontWeight, `${path}.fontWeight`) },
+		...object.fontStyle === void 0 ? {} : { fontStyle: readTextFontStyle(object.fontStyle, `${path}.fontStyle`) },
+		...object.underline === void 0 ? {} : { underline: readBoolean(object.underline, `${path}.underline`) },
+		...object.textAlign === void 0 ? {} : { textAlign: readTextAlignment(object.textAlign, `${path}.textAlign`) },
+		...object.lineHeight === void 0 ? {} : { lineHeight: readPositiveNumber(object.lineHeight, `${path}.lineHeight`) },
+		...object.charSpacing === void 0 ? {} : { charSpacing: readFiniteNumber(object.charSpacing, `${path}.charSpacing`) },
+		...object.backgroundColor === void 0 ? {} : { backgroundColor: readString(object.backgroundColor, `${path}.backgroundColor`) }
+	};
+	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/uvBounds.ts
+function fullCanvasBounds(width, height) {
+	return {
+		left: 0,
+		top: 0,
+		width,
+		height
+	};
+}
+/**
+* 将 UV 三角形的坐标范围转换为逻辑画布包围框
+*
+* UV 坐标会限制在 0 到 1 之间；布局为空、无效或退化时回退到整张画布
+*
+* @param layout 当前可打印 Mesh 的 UV 布局
+* @param flipY 是否按照垂直翻转后的纹理方向计算
+* @param canvasWidth 逻辑画布宽度
+* @param canvasHeight 逻辑画布高度
+* @returns 当前 UV 可打印区域在逻辑画布中的轴对齐包围框
+*/
+function calculateUvCanvasBounds(layout, flipY, canvasWidth, canvasHeight) {
+	const coordinates = layout.triangleCoordinates;
+	let minimumX = Number.POSITIVE_INFINITY;
+	let minimumY = Number.POSITIVE_INFINITY;
+	let maximumX = Number.NEGATIVE_INFINITY;
+	let maximumY = Number.NEGATIVE_INFINITY;
+	for (let index = 0; index + 1 < coordinates.length; index += 2) {
+		const u = coordinates[index];
+		const v = coordinates[index + 1];
+		if (!Number.isFinite(u) || !Number.isFinite(v)) continue;
+		const x = Math.min(Math.max(u, 0), 1) * canvasWidth;
+		const normalizedY = flipY ? 1 - v : v;
+		const y = Math.min(Math.max(normalizedY, 0), 1) * canvasHeight;
+		minimumX = Math.min(minimumX, x);
+		minimumY = Math.min(minimumY, y);
+		maximumX = Math.max(maximumX, x);
+		maximumY = Math.max(maximumY, y);
+	}
+	const width = maximumX - minimumX;
+	const height = maximumY - minimumY;
+	if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return fullCanvasBounds(canvasWidth, canvasHeight);
+	return {
+		left: minimumX,
+		top: minimumY,
+		width,
+		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
+var EDITOR_DISPLAY_GUTTER = 56;
+function normalizeEditorAppearance(appearance = {}) {
+	const controlSize = appearance.controlSize ?? 8;
+	if (!Number.isFinite(controlSize) || controlSize <= 0) throw new RangeError("appearance.editor.controlSize must be greater than zero");
+	return {
+		selectionFill: appearance.selectionFill?.trim() || "rgba(19, 113, 125, 0.12)",
+		selectionBorder: appearance.selectionBorder?.trim() || "#13717d",
+		controlFill: appearance.controlFill?.trim() || "#ffffff",
+		controlBorder: appearance.controlBorder?.trim() || "#13717d",
+		objectBorder: appearance.objectBorder?.trim() || "#13717d",
+		controlSize,
+		uvFill: appearance.uvFill?.trim() || void 0,
+		uvBoundary: appearance.uvBoundary?.trim() || "#dc2626"
+	};
+}
+/** 将 Fabric 主画布重绘为不含选择框的实时纹理 */
+var DesignCanvas = class extends Canvas {
+	/** 将纯设计内容绘制到稳定的纹理 Canvas */
+	renderTexture(context) {
+		const previousSkipControlsDrawing = this.skipControlsDrawing;
+		this.skipControlsDrawing = true;
+		try {
+			this.renderCanvas(context, this.getObjects());
+		} finally {
+			this.skipControlsDrawing = previousSkipControlsDrawing;
+		}
+	}
+};
+/**
+* 基于 Fabric.js 的二维纹理编辑器
+*
+* 负责基础纹理、UV 区域辅助层、文字、图片、对象选择和 PNG 导出
+* 显示尺寸可以响应容器变化，内部逻辑尺寸保持不变
+*/
+var DesignEditor = class {
+	/** 当前实例使用的 Fabric Canvas */
+	canvas;
+	host;
+	width;
+	height;
+	defaultText;
+	textObjectName;
+	imageObjectName;
+	backgroundObjectName;
+	appearance;
+	editableBounds;
+	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;
+	uvOverlay;
+	textureRenderer;
+	textureCanvasElement;
+	textureContext;
+	historySignature;
+	historyTimer;
+	historyBusy = false;
+	renderingTexture = false;
+	objectIdSequence = 0;
+	/**
+	* @param host 二维编辑器挂载容器
+	* @param options 画布逻辑尺寸和历史容量
+	*/
+	constructor(host, options) {
+		this.host = host;
+		this.width = options.width;
+		this.height = options.height;
+		this.defaultText = options.defaultText ?? "Edit this text";
+		this.textObjectName = options.textObjectName ?? "Text";
+		this.imageObjectName = options.imageObjectName ?? "Image";
+		this.backgroundObjectName = options.backgroundObjectName ?? "Background";
+		this.appearance = normalizeEditorAppearance(options.appearance);
+		this.editableBounds = {
+			left: 0,
+			top: 0,
+			width: this.width,
+			height: this.height
+		};
+		const element = document.createElement("canvas");
+		element.setAttribute("aria-label", options.ariaLabel ?? "UV texture editor");
+		host.replaceChildren(element);
+		const canvas = new DesignCanvas(element, {
+			width: this.width,
+			height: this.height,
+			preserveObjectStacking: true,
+			selectionColor: this.appearance.selectionFill,
+			selectionBorderColor: this.appearance.selectionBorder
+		});
+		this.canvas = canvas;
+		this.textureRenderer = canvas;
+		this.textureCanvasElement = document.createElement("canvas");
+		this.textureCanvasElement.width = this.width;
+		this.textureCanvasElement.height = this.height;
+		const textureContext = this.textureCanvasElement.getContext("2d");
+		if (!textureContext) {
+			canvas.dispose();
+			throw new Error("Unable to create the live texture canvas");
+		}
+		this.textureContext = textureContext;
+		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.uvOverlay = document.createElement("canvas");
+		this.uvOverlay.width = this.width;
+		this.uvOverlay.height = this.height;
+		this.uvOverlay.className = "customforge-uv-layout";
+		this.uvOverlay.setAttribute("aria-hidden", "true");
+		this.uvOverlay.hidden = true;
+		this.canvas.wrapperEl.insertBefore(this.uvOverlay, this.canvas.upperCanvasEl);
+		this.host.dataset.renderState = "pending";
+		this.canvas.on("after:render", () => {
+			if (this.renderingTexture) return;
+			this.renderTextureCanvas();
+			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 的纯设计画布，不包含选择框和变换控件 */
+	get textureCanvas() {
+		return this.textureCanvasElement;
+	}
+	/**
+	* 在交互画布上显示目标 Mesh 的 UV 可打印区域，但不写入实时纹理或导出图片
+	*
+	* @param layout 从当前目标 Mesh 提取的 UV 布局
+	* @param flipY 是否按照垂直翻转后的纹理方向显示
+	*/
+	setUvLayout(layout, flipY) {
+		this.editableBounds = calculateUvCanvasBounds(layout, flipY, this.width, this.height);
+		const context = this.uvOverlay.getContext("2d");
+		if (!context) return;
+		context.clearRect(0, 0, this.width, this.height);
+		const { triangleCoordinates, boundaryCoordinates } = layout;
+		if (triangleCoordinates.length === 0) {
+			this.uvOverlay.hidden = true;
+			return;
+		}
+		this.uvOverlay.hidden = false;
+		const accent = this.appearance.uvFill ?? (getComputedStyle(this.canvas.wrapperEl).getPropertyValue("--cfw-accent").trim() || "#268a4b");
+		const canvasX = (u) => Math.min(Math.max(u * this.width, 1), this.width - 1);
+		const canvasY = (v) => Math.min(Math.max((flipY ? 1 - v : v) * this.height, 1), this.height - 1);
+		context.save();
+		context.beginPath();
+		for (let index = 0; index < triangleCoordinates.length; index += 6) {
+			context.moveTo(canvasX(triangleCoordinates[index]), canvasY(triangleCoordinates[index + 1]));
+			context.lineTo(canvasX(triangleCoordinates[index + 2]), canvasY(triangleCoordinates[index + 3]));
+			context.lineTo(canvasX(triangleCoordinates[index + 4]), canvasY(triangleCoordinates[index + 5]));
+			context.closePath();
+		}
+		context.fillStyle = accent;
+		context.globalAlpha = .012;
+		context.fill();
+		context.beginPath();
+		for (let index = 0; index < boundaryCoordinates.length; index += 4) {
+			context.moveTo(canvasX(boundaryCoordinates[index]), canvasY(boundaryCoordinates[index + 1]));
+			context.lineTo(canvasX(boundaryCoordinates[index + 2]), canvasY(boundaryCoordinates[index + 3]));
+		}
+		context.globalAlpha = .28;
+		context.strokeStyle = this.appearance.uvBoundary;
+		context.lineWidth = 1;
+		context.lineCap = "round";
+		context.lineJoin = "round";
+		context.setLineDash([6, 6]);
+		context.stroke();
+		context.restore();
+	}
+	/** 当前画布中设计对象的数量，不包含产品基础纹理 */
+	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));
+	}
+	/** 返回当前逻辑画布尺寸 */
+	getCanvasSize() {
+		return {
+			width: this.width,
+			height: this.height
+		};
+	}
+	/** 返回当前 UV 可打印区域的独立包围框 */
+	getPrintableBounds() {
+		return { ...this.editableBounds };
+	}
+	/** 当前选中对象的 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) {
+		return this.selectObjects([id]);
+	}
+	/**
+	* 按稳定 ID 同时选中多个可见对象
+	*
+	* 所有 ID 都必须有效且对象可见，否则保持原选区不变
+	*
+	* @param ids 对象 ID，空数组表示清除选区
+	* @returns 是否应用了请求的选区
+	*/
+	selectObjects(ids) {
+		const uniqueIds = [...new Set(ids)];
+		if (uniqueIds.length === 0) return this.clearSelection();
+		const objects = uniqueIds.map((id) => this.objectsById.get(id));
+		if (objects.some((object) => !object || !object.visible)) return false;
+		this.applySelection(objects);
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		return true;
+	}
+	/**
+	* 清除当前画布选区，不修改设计内容或历史记录
+	*
+	* @returns 清除前是否存在选中对象
+	*/
+	clearSelection() {
+		if (!this.canvas.getActiveObject()) return false;
+		this.canvas.discardActiveObject();
+		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;
+	}
+	/**
+	* 将现有图片转换为铺满当前 UV 可打印区域的设计背景
+	*
+	* 转换会替换已有设计背景、重置旋转、锁定对象并移动到最底层
+	*
+	* @param id Design JSON 中的图片对象 ID
+	* @returns 是否找到普通图片并完成转换
+	*/
+	setImageAsBackground(id) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		if (!(object instanceof FabricImage) || this.imageRoles.get(object) === "background") return false;
+		this.removeDesignBackgrounds();
+		this.imageRoles.set(object, "background");
+		this.fitImageToEditableBounds(object);
+		this.applyObjectLock(object, true);
+		this.canvas.moveObjectTo(object, 0);
+		this.canvas.setActiveObject(object);
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		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;
+	}
+	/**
+	* 更新对象中心位置、缩放、旋转和翻转
+	*
+	* 对象最终仍会约束在逻辑画布内，连续调用会合并为一个历史步骤
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param options 要更新的变换字段
+	* @returns 约束后的对象快照，找不到对象时返回 undefined
+	* @throws 数值无效或缩放倍数不大于零时抛出错误
+	*/
+	updateObjectTransform(id, options) {
+		const object = this.objectsById.get(id);
+		if (!object) return;
+		this.validateTransformOptions(options);
+		const selectedIds = this.getSelectedObjectIds();
+		if (object.group instanceof ActiveSelection) this.canvas.discardActiveObject();
+		const current = this.serializeTransform(object);
+		const x = options.x ?? current.x;
+		const y = options.y ?? current.y;
+		object.set({
+			scaleX: options.scaleX ?? current.scaleX,
+			scaleY: options.scaleY ?? current.scaleY,
+			angle: options.rotation ?? current.rotation,
+			flipX: options.flipX ?? current.flipX,
+			flipY: options.flipY ?? current.flipY
+		});
+		object.setPositionByOrigin(new Point(x, y), "center", "center");
+		this.constrainObjectToCanvas(object);
+		const selectedObjects = selectedIds.map((selectedId) => this.objectsById.get(selectedId)).filter((selected) => Boolean(selected?.visible));
+		if (selectedObjects.length > 0) this.applySelection(selectedObjects);
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		this.scheduleHistoryCommit();
+		return this.serializeObject(object);
+	}
+	/**
+	* 修改已有文字对象的内容和排版样式
+	*
+	* 连续调用会在短暂空闲后合并为一个历史步骤
+	* 字体必须由消费页面提前加载，否则浏览器会使用回退字体
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param options 要修改的文字属性，未传字段保持不变
+	* @returns 是否找到并更新了文字对象
+	* @throws 字号、行高、字距、字重或 CSS 颜色不符合约束时抛出错误
+	*/
+	updateText(id, options) {
+		const object = this.objectsById.get(id);
+		if (!(object instanceof Textbox)) return false;
+		if (options.text !== void 0) object.set({ text: options.text });
+		if (options.fontFamily !== void 0) {
+			const fontFamily = options.fontFamily.trim();
+			if (!fontFamily) throw new TypeError("fontFamily must be a non-empty string");
+			object.set({ fontFamily });
+		}
+		if (options.fontSize !== void 0) {
+			if (!Number.isFinite(options.fontSize) || options.fontSize <= 0) throw new RangeError("fontSize must be greater than zero");
+			object.set({ fontSize: options.fontSize });
+		}
+		if (options.color !== void 0) {
+			if (!options.color.trim()) throw new TypeError("color must be a non-empty CSS color");
+			object.set({ fill: options.color });
+		}
+		if (options.fontWeight !== void 0) {
+			if (!(options.fontWeight === "normal" || options.fontWeight === "bold" || typeof options.fontWeight === "number" && Number.isFinite(options.fontWeight) && options.fontWeight > 0 && options.fontWeight <= 1e3)) throw new RangeError("fontWeight must be normal, bold, or between 1 and 1000");
+			object.set({ fontWeight: options.fontWeight });
+		}
+		if (options.fontStyle !== void 0) {
+			if (options.fontStyle !== "normal" && options.fontStyle !== "italic") throw new TypeError("fontStyle must be normal or italic");
+			object.set({ fontStyle: options.fontStyle });
+		}
+		if (options.underline !== void 0) object.set({ underline: options.underline });
+		if (options.textAlign !== void 0) {
+			if (![
+				"left",
+				"center",
+				"right"
+			].includes(options.textAlign)) throw new TypeError("textAlign must be left, center, or right");
+			object.set({ textAlign: options.textAlign });
+		}
+		if (options.lineHeight !== void 0) {
+			if (!Number.isFinite(options.lineHeight) || options.lineHeight <= 0) throw new RangeError("lineHeight must be greater than zero");
+			object.set({ lineHeight: options.lineHeight });
+		}
+		if (options.charSpacing !== void 0) {
+			if (!Number.isFinite(options.charSpacing)) throw new TypeError("charSpacing must be a finite number");
+			object.set({ charSpacing: options.charSpacing });
+		}
+		if (options.backgroundColor !== void 0) {
+			if (options.backgroundColor !== null && !options.backgroundColor.trim()) throw new TypeError("backgroundColor must be a non-empty CSS color or null");
+			object.set({ backgroundColor: options.backgroundColor ?? "" });
+		}
+		object.initDimensions();
+		if (object.group instanceof ActiveSelection) {
+			object.group.triggerLayout();
+			this.constrainObjectToCanvas(object.group);
+		} else this.constrainObjectToCanvas(object);
+		this.canvas.requestRenderAll();
+		this.scheduleHistoryCommit();
+		return true;
+	}
+	/**
+	* 让一个未锁定文字对象进入画布内联编辑状态
+	*
+	* @param id Design JSON 中的对象 ID
+	* @returns 是否找到文字对象并进入编辑状态
+	*/
+	editText(id) {
+		this.flushHistoryCommit();
+		const object = this.objectsById.get(id);
+		if (!(object instanceof Textbox) || !object.visible || (this.objectLocks.get(object) ?? false)) return false;
+		this.canvas.setActiveObject(object);
+		object.enterEditing();
+		object.hiddenTextarea?.focus();
+		this.canvas.requestRenderAll();
+		this.notifySelectionChange();
+		return true;
+	}
+	/**
+	* 设置铺满画布的基础纹理，不传地址时恢复透明背景
+	*
+	* 背景纹理不参与对象选择，但会包含在实时纹理和 PNG 导出中
+	*
+	* @param url 基础纹理地址
+	* @throws 图片加载失败或被 CORS 策略阻止时抛出错误
+	*/
+	async setBackgroundTexture(url) {
+		if (!url) {
+			this.canvas.backgroundImage = void 0;
+			this.canvas.backgroundColor = "";
+			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 创建后的可持久化文字对象快照
+	*/
+	addText(options = {}) {
+		this.flushHistoryCommit();
+		const text = new Textbox(options.text ?? this.defaultText, {
+			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 ?? 22,
+			fontWeight: options.fontWeight ?? 700,
+			fontStyle: options.fontStyle ?? "normal",
+			underline: options.underline ?? false,
+			fill: options.color ?? "#172126",
+			backgroundColor: options.backgroundColor ?? "",
+			originX: "left",
+			originY: "top",
+			textAlign: options.textAlign ?? "center",
+			lineHeight: options.lineHeight ?? 1.16,
+			charSpacing: options.charSpacing ?? 0,
+			editable: true,
+			...this.objectControlAppearance()
+		});
+		this.addAndSelect(text, options.name);
+		return this.serializeObject(text);
+	}
+	/**
+	* 加载、添加并选中一个图片对象
+	*
+	* role 为 background 时替换已有设计背景、铺满当前 UV 可打印区域并默认锁定在最底层
+	* 图片位置使用画布像素坐标，原点位于图片中心
+	* 对象过大时会等比缩小，越界时会自动移回画布
+	* 远程图片必须提供正确的 CORS 响应头才能安全导出 PNG
+	*
+	* @param options 图片地址、中心位置和显示宽度
+	* @returns 创建后的可持久化图片对象快照
+	* @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: options.x ?? this.width * .62,
+			top: options.y ?? this.height * .29,
+			originX: "center",
+			originY: "center",
+			scaleX: scale,
+			scaleY: scale,
+			...this.objectControlAppearance()
+		});
+		if (role === "background") {
+			this.removeDesignBackgrounds();
+			this.fitImageToEditableBounds(image);
+		}
+		this.imageSources.set(image, source);
+		this.addAndSelect(image, options.name, role === "background", role);
+		return this.serializeObject(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") {
+		const anchor = document.createElement("a");
+		anchor.download = filename;
+		anchor.href = this.getTextureDataUrl();
+		anchor.click();
+	}
+	/**
+	* 返回不含选择框和 UV 辅助层的 PNG Data URL
+	*
+	* @returns 与逻辑画布同尺寸的 PNG Data URL
+	* @throws 远程图片污染 Canvas 时抛出安全错误
+	*/
+	getTextureDataUrl() {
+		this.renderTextureCanvas();
+		return this.textureCanvasElement.toDataURL("image/png");
+	}
+	/**
+	* 异步返回不含选择框和 UV 辅助层的 PNG Blob
+	*
+	* @returns 与逻辑画布同尺寸的 PNG Blob
+	* @throws 远程图片污染 Canvas 或浏览器无法编码时抛出错误
+	*/
+	getTextureBlob() {
+		this.renderTextureCanvas();
+		return new Promise((resolve, reject) => {
+			this.textureCanvasElement.toBlob((blob) => {
+				if (blob) resolve(blob);
+				else reject(/* @__PURE__ */ new Error("The texture canvas could not be encoded as PNG"));
+			}, "image/png");
+		});
+	}
+	/** 释放 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,
+				fontWeight: object.fontWeight,
+				fontStyle: object.fontStyle,
+				underline: object.underline,
+				textAlign: object.textAlign,
+				lineHeight: object.lineHeight,
+				charSpacing: object.charSpacing,
+				...object.backgroundColor ? { backgroundColor: object.backgroundColor } : {}
+			};
+		}
+		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,
+			...this.objectControlAppearance()
+		};
+		if (design.type === "text") return new Textbox(design.text, {
+			...common,
+			width: design.width,
+			fontFamily: design.fontFamily,
+			fontSize: design.fontSize,
+			fontWeight: design.fontWeight ?? 700,
+			fontStyle: design.fontStyle ?? "normal",
+			underline: design.underline ?? false,
+			fill: design.color,
+			backgroundColor: design.backgroundColor ?? "",
+			textAlign: design.textAlign ?? "center",
+			lineHeight: design.lineHeight ?? 1.16,
+			charSpacing: design.charSpacing ?? 0,
+			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) || this.textObjectName;
+		if (object instanceof FabricImage) return this.imageRoles.get(object) === "background" ? this.backgroundObjectName : this.imageObjectName;
+		return "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 - EDITOR_DISPLAY_GUTTER, 1);
+		const availableHeight = Math.max(this.host.clientHeight - EDITOR_DISPLAY_GUTTER, 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 });
+	}
+	applySelection(objects) {
+		this.canvas.discardActiveObject();
+		this.canvas.setActiveObject(objects.length === 1 ? objects[0] : new ActiveSelection(objects, { canvas: this.canvas }));
+	}
+	objectControlAppearance() {
+		return {
+			transparentCorners: false,
+			cornerColor: this.appearance.controlFill,
+			cornerStrokeColor: this.appearance.controlBorder,
+			borderColor: this.appearance.objectBorder,
+			cornerSize: this.appearance.controlSize
+		};
+	}
+	validateTransformOptions(options) {
+		for (const [name, value] of [
+			["x", options.x],
+			["y", options.y],
+			["rotation", options.rotation]
+		]) if (value !== void 0 && !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
+		for (const [name, value] of [["scaleX", options.scaleX], ["scaleY", options.scaleY]]) if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) throw new RangeError(`${name} must be greater than zero`);
+		for (const [name, value] of [["flipX", options.flipX], ["flipY", options.flipY]]) if (value !== void 0 && typeof value !== "boolean") throw new TypeError(`${name} must be a boolean`);
+	}
+	fitImageToEditableBounds(image) {
+		const bounds = this.editableBounds;
+		image.set({
+			left: bounds.left + bounds.width / 2,
+			top: bounds.top + bounds.height / 2,
+			angle: 0,
+			scaleX: bounds.width / Math.max(image.width, 1),
+			scaleY: bounds.height / Math.max(image.height, 1)
+		});
+		image.setCoords();
+	}
+	renderTextureCanvas() {
+		this.renderingTexture = true;
+		try {
+			this.textureRenderer.renderTexture(this.textureContext);
+		} finally {
+			this.renderingTexture = false;
+		}
+	}
+	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 提供不含交互控件的纹理 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/assets/cup_decal_small_margins.glb?url&no-inline
+var cup_decal_small_margins_default = "" + new URL("cup_decal_small_margins.glb", import.meta.url).href;
+//#endregion
+//#region src/viewer/uvLayout.ts
+var UV_EDGE_PRECISION = 1e6;
+function createPointKey(u, v) {
+	return `${Math.round(u * UV_EDGE_PRECISION)},${Math.round(v * UV_EDGE_PRECISION)}`;
+}
+function extractBoundaryCoordinates(triangleCoordinates) {
+	const edges = /* @__PURE__ */ new Map();
+	for (let index = 0; index < triangleCoordinates.length; index += 6) {
+		const points = [
+			[triangleCoordinates[index], triangleCoordinates[index + 1]],
+			[triangleCoordinates[index + 2], triangleCoordinates[index + 3]],
+			[triangleCoordinates[index + 4], triangleCoordinates[index + 5]]
+		];
+		for (const [startIndex, endIndex] of [
+			[0, 1],
+			[1, 2],
+			[2, 0]
+		]) {
+			const start = points[startIndex];
+			const end = points[endIndex];
+			const startKey = createPointKey(start[0], start[1]);
+			const endKey = createPointKey(end[0], end[1]);
+			const edgeKey = startKey < endKey ? `${startKey}|${endKey}` : `${endKey}|${startKey}`;
+			const edge = edges.get(edgeKey);
+			if (edge) edge.occurrences += 1;
+			else edges.set(edgeKey, {
+				coordinates: [
+					start[0],
+					start[1],
+					end[0],
+					end[1]
+				],
+				occurrences: 1
+			});
+		}
+	}
+	return new Float32Array([...edges.values()].filter((edge) => edge.occurrences === 1).flatMap((edge) => edge.coordinates));
+}
+/**
+* 提取目标 Mesh 第一个材质槽使用的 UV 三角形
+*
+* @param mesh 接收实时纹理的目标 Mesh
+* @returns 保持模型原始 V 方向的 UV 三角形和外边界布局
+* @throws Mesh 缺少 UV、面数据无效或第一个材质槽没有三角形时抛出错误
+*/
+function extractUvLayout(mesh) {
+	const geometry = mesh.geometry;
+	const uv = geometry.getAttribute("uv");
+	if (!uv) throw new Error(`Customizable mesh does not contain UV coordinates: ${mesh.name}`);
+	const index = geometry.getIndex();
+	const elementCount = index?.count ?? uv.count;
+	const ranges = Array.isArray(mesh.material) && geometry.groups.length > 0 ? geometry.groups.filter((group) => (group.materialIndex ?? 0) === 0).map(({ start, count }) => ({
+		start,
+		count
+	})) : [{
+		start: 0,
+		count: elementCount
+	}];
+	const coordinateCount = ranges.reduce((total, range) => {
+		if (!Number.isInteger(range.start) || !Number.isInteger(range.count) || range.start < 0 || range.count < 0 || range.start + range.count > elementCount || range.count % 3 !== 0) throw new Error(`Customizable mesh has invalid triangle groups: ${mesh.name}`);
+		return total + range.count * 2;
+	}, 0);
+	if (coordinateCount === 0) throw new Error(`Customizable mesh has no triangles in its first material slot: ${mesh.name}`);
+	const triangleCoordinates = new Float32Array(coordinateCount);
+	let targetIndex = 0;
+	for (const range of ranges) for (let offset = range.start; offset < range.start + range.count; offset += 1) {
+		const vertexIndex = index ? index.getX(offset) : offset;
+		const u = uv.getX(vertexIndex);
+		const v = uv.getY(vertexIndex);
+		if (!Number.isFinite(u) || !Number.isFinite(v)) throw new Error(`Customizable mesh has invalid UV coordinates: ${mesh.name}`);
+		triangleCoordinates[targetIndex] = u;
+		triangleCoordinates[targetIndex + 1] = v;
+		targetIndex += 2;
+	}
+	return {
+		triangleCoordinates,
+		boundaryCoordinates: extractBoundaryCoordinates(triangleCoordinates)
+	};
+}
+//#endregion
+//#region src/viewer/ProductViewer.ts
+var DEFAULT_PRODUCT_HEIGHT = 2.35;
+var DEFAULT_PRODUCT_BASE_Y = -1.17;
+var DEFAULT_PRODUCT_ROTATION = MathUtils.degToRad(-72);
+var DEFAULT_CAMERA_AZIMUTH = MathUtils.degToRad(18);
+var DEFAULT_CAMERA_ELEVATION = MathUtils.degToRad(10);
+var CAMERA_VIEWPORT_FILL = .7;
+/**
+* 基于 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;
+	viewChangeListeners = /* @__PURE__ */ new Set();
+	handleControlsChange = () => {
+		const state = this.getViewState();
+		this.viewChangeListeners.forEach((listener) => listener(state));
+	};
+	/**
+	* @param host 三维查看器挂载容器
+	* @param ariaLabel 三维产品画布的无障碍名称
+	* @param appearance WebGL 画布清屏颜色等外观配置
+	*/
+	constructor(host, ariaLabel = "Interactive 3D product preview", appearance = {}) {
+		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;
+		if (appearance.backgroundColor?.trim()) this.renderer.setClearColor(appearance.backgroundColor.trim(), 1);
+		this.renderer.domElement.setAttribute("aria-label", ariaLabel);
+		this.renderer.domElement.classList.add("customforge-viewer-canvas");
+		host.append(this.renderer.domElement);
+		host.dataset.renderState = "pending";
+		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.controls.addEventListener("change", this.handleControlsChange);
+		this.addStudioLighting();
+		this.resizeObserver = new ResizeObserver(() => this.resize());
+		this.resizeObserver.observe(host);
+		this.resize();
+		this.render();
+	}
+	/**
+	* 加载远程模型或随包提供的默认 GLB 模型
+	*
+	* @param product 已完成默认值补全的产品配置
+	* @returns 目标 Mesh 第一个材质槽使用的 UV 三角形布局
+	* @throws 模型加载失败、找不到目标 Mesh 或目标 Mesh 缺少有效 UV 时抛出错误
+	*/
+	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 gltf = await this.loader.loadAsync(cup_decal_small_margins_default);
+			this.productRoot = gltf.scene;
+			this.surface = this.findSurface(gltf.scene, product.surfaceMesh);
+			this.prepareBundledProduct(gltf.scene, this.surface);
+		}
+		const surface = this.surface;
+		if (!surface) throw new Error("Customizable mesh was not initialized");
+		const uvLayout = extractUvLayout(surface);
+		this.scene.add(this.productRoot);
+		if (this.texture) this.attachTexture(this.texture);
+		this.fitCamera(this.productRoot);
+		return uvLayout;
+	}
+	/**
+	* 保存并绑定二维编辑器生成的实时纹理
+	*
+	* 如果模型尚未加载，纹理会在模型加载完成后自动绑定
+	*
+	* @param texture 由二维画布创建的 CanvasTexture
+	*/
+	setTexture(texture) {
+		this.texture = texture;
+		if (this.surface) this.attachTexture(texture);
+	}
+	/** 根据当前模型包围盒恢复默认相机位置 */
+	resetView() {
+		if (this.productRoot) this.fitCamera(this.productRoot);
+	}
+	/** 返回当前相机位置和轨道控制目标点的独立快照 */
+	getViewState() {
+		return {
+			position: this.vectorToValue(this.camera.position),
+			target: this.vectorToValue(this.controls.target)
+		};
+	}
+	/**
+	* 恢复相机位置和轨道控制目标点
+	*
+	* @param state 要恢复的三维观察视角
+	* @returns 应用后的独立视角快照
+	* @throws 坐标不是有限数值或相机与目标点重合时抛出错误
+	*/
+	setViewState(state) {
+		this.validateViewState(state);
+		this.camera.position.set(state.position.x, state.position.y, state.position.z);
+		this.controls.target.set(state.target.x, state.target.y, state.target.z);
+		this.camera.updateProjectionMatrix();
+		this.controls.update();
+		return this.getViewState();
+	}
+	/**
+	* 订阅三维视角变化
+	*
+	* 用户旋转、缩放、平移以及 API 恢复视角时都会触发
+	*
+	* @param listener 接收独立视角快照的监听函数
+	* @returns 用于取消本次订阅的函数
+	*/
+	onViewChange(listener) {
+		this.viewChangeListeners.add(listener);
+		return () => this.viewChangeListeners.delete(listener);
+	}
+	/** 释放动画帧、相机控制、模型材质和 WebGLRenderer */
+	destroy() {
+		cancelAnimationFrame(this.animationFrame);
+		this.resizeObserver.disconnect();
+		this.controls.removeEventListener("change", this.handleControlsChange);
+		this.controls.dispose();
+		this.viewChangeListeners.clear();
+		this.removeProduct();
+		this.renderer.dispose();
+		this.renderer.domElement.remove();
+	}
+	addStudioLighting() {
+		this.scene.add(new AmbientLight("#ffffff", .9));
+		const key = new DirectionalLight("#ffffff", 2.1);
+		key.position.set(4, 5, 6);
+		this.scene.add(key);
+		const fill = new DirectionalLight("#e8f0f2", 1.15);
+		fill.position.set(-5, 2, 4);
+		this.scene.add(fill);
+		const rim = new DirectionalLight("#ffffff", .8);
+		rim.position.set(1, 4, -5);
+		this.scene.add(rim);
+	}
+	prepareBundledProduct(root, surface) {
+		surface.renderOrder = 1;
+		(Array.isArray(surface.material) ? surface.material : [surface.material]).forEach((material) => {
+			material.depthWrite = false;
+			material.polygonOffset = true;
+			material.polygonOffsetFactor = -1;
+			material.polygonOffsetUnits = -1;
+		});
+		const initialHeight = new Box3().setFromObject(root).getSize(new Vector3()).y;
+		if (!Number.isFinite(initialHeight) || initialHeight <= 0) throw new Error("The bundled product has invalid bounds");
+		root.scale.multiplyScalar(DEFAULT_PRODUCT_HEIGHT / initialHeight);
+		root.rotation.y = DEFAULT_PRODUCT_ROTATION;
+		root.updateMatrixWorld(true);
+		const bounds = new Box3().setFromObject(root);
+		const center = bounds.getCenter(new Vector3());
+		root.position.x -= center.x;
+		root.position.y += DEFAULT_PRODUCT_BASE_Y - bounds.min.y;
+		root.position.z -= center.z;
+		root.updateMatrixWorld(true);
+	}
+	/**
+	* 按名称查找接收实时纹理的 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, direction) {
+		const bounds = new Box3().setFromObject(root);
+		const size = bounds.getSize(new Vector3());
+		const center = bounds.getCenter(new Vector3());
+		const diagonal = size.length();
+		if (!Number.isFinite(diagonal) || diagonal <= 0) throw new Error("The product has invalid bounds");
+		const viewDirection = direction?.clone() ?? this.defaultCameraDirection();
+		if (viewDirection.lengthSq() === 0) viewDirection.copy(this.defaultCameraDirection());
+		viewDirection.normalize();
+		const right = new Vector3().crossVectors(this.camera.up, viewDirection);
+		if (right.lengthSq() < 1e-8) right.set(1, 0, 0);
+		else right.normalize();
+		const up = new Vector3().crossVectors(viewDirection, right).normalize();
+		const verticalSlope = Math.tan(MathUtils.degToRad(this.camera.fov / 2)) * CAMERA_VIEWPORT_FILL;
+		const horizontalSlope = verticalSlope * Math.max(this.camera.aspect, .1);
+		let distance = 0;
+		for (const x of [bounds.min.x, bounds.max.x]) for (const y of [bounds.min.y, bounds.max.y]) for (const z of [bounds.min.z, bounds.max.z]) {
+			const offset = new Vector3(x, y, z).sub(center);
+			const depth = offset.dot(viewDirection);
+			distance = Math.max(distance, depth + Math.abs(offset.dot(right)) / horizontalSlope, depth + Math.abs(offset.dot(up)) / verticalSlope);
+		}
+		distance = Math.max(distance, diagonal * .55, .1);
+		this.controls.target.copy(center);
+		this.camera.position.copy(center).addScaledVector(viewDirection, distance);
+		this.camera.near = Math.max(Math.min(distance * .02, diagonal * .01), .01);
+		this.camera.far = Math.max(distance + diagonal * 2, 10);
+		this.camera.updateProjectionMatrix();
+		this.controls.minDistance = Math.max(diagonal * .45, distance * .3, .05);
+		this.controls.maxDistance = Math.max(distance * 4, diagonal * 4);
+		this.controls.update();
+	}
+	defaultCameraDirection() {
+		const horizontal = Math.cos(DEFAULT_CAMERA_ELEVATION);
+		return new Vector3(horizontal * Math.sin(DEFAULT_CAMERA_AZIMUTH), Math.sin(DEFAULT_CAMERA_ELEVATION), horizontal * Math.cos(DEFAULT_CAMERA_AZIMUTH));
+	}
+	vectorToValue(vector) {
+		return {
+			x: vector.x,
+			y: vector.y,
+			z: vector.z
+		};
+	}
+	validateViewState(state) {
+		if (![
+			state.position.x,
+			state.position.y,
+			state.position.z,
+			state.target.x,
+			state.target.y,
+			state.target.z
+		].every(Number.isFinite)) throw new TypeError("View position and target must contain finite numbers");
+		if ((state.position.x - state.target.x) ** 2 + (state.position.y - state.target.y) ** 2 + (state.position.z - state.target.z) ** 2 <= Number.EPSILON) throw new RangeError("View position and target must not be identical");
+	}
+	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);
+		const direction = this.camera.position.clone().sub(this.controls.target);
+		this.renderer.setSize(width, height, false);
+		this.camera.aspect = width / height;
+		if (this.productRoot && direction.lengthSq() > 0) this.fitCamera(this.productRoot, direction);
+		else 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;
+	stopViewListener;
+	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,
+			ariaLabel: options.editorAriaLabel,
+			defaultText: options.defaultText,
+			textObjectName: options.textObjectName,
+			imageObjectName: options.imageObjectName,
+			backgroundObjectName: options.backgroundObjectName,
+			appearance: options.appearance?.editor
+		});
+		this.viewer = new ProductViewer(viewerHost, options.viewerAriaLabel, options.appearance?.viewer);
+		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);
+		});
+		this.stopViewListener = this.viewer.onViewChange((state) => {
+			this.emit("viewchange", 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 文字内容、位置和样式配置
+	* @returns 创建后的可持久化文字对象快照
+	*/
+	addText(options) {
+		return this.editor.addText(options);
+	}
+	/**
+	* 加载图片并将其添加到二维画布
+	*
+	* role 为 background 时会替换已有设计背景、铺满当前 UV 可打印区域并默认锁定在最底层
+	* 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
+	*
+	* @param options 图片地址、位置和显示宽度
+	* @returns 创建后的可持久化图片对象快照
+	* @throws 图片无法访问、加载失败或被 CORS 策略阻止时抛出错误
+	*/
+	async addImage(options) {
+		try {
+			return await this.editor.addImage(options);
+		} catch (error) {
+			this.reportError(error);
+			throw error;
+		}
+	}
+	/** 返回产品、画布、对象、选区、历史和视角的独立状态快照 */
+	getState() {
+		return {
+			product: this.getProduct(),
+			canvas: this.getCanvasSize(),
+			printableBounds: this.getPrintableBounds(),
+			objects: this.getObjects(),
+			selectedObjectIds: this.getSelectedObjectIds(),
+			history: {
+				canUndo: this.canUndo(),
+				canRedo: this.canRedo()
+			},
+			view: this.getViewState()
+		};
+	}
+	/** 返回当前补全默认值后的产品配置独立快照 */
+	getProduct() {
+		return { ...this.product };
+	}
+	/** 返回当前二维逻辑画布尺寸 */
+	getCanvasSize() {
+		return this.editor.getCanvasSize();
+	}
+	/** 返回当前产品 UV 在逻辑画布中的可打印包围框 */
+	getPrintableBounds() {
+		return this.editor.getPrintableBounds();
+	}
+	/**
+	* 返回当前可编辑对象的独立快照
+	*
+	* @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 同时选中多个可见对象
+	*
+	* 所有 ID 都必须有效且可见，否则保持原选区不变；空数组清除选区
+	*
+	* @param ids Design JSON 中的对象 ID
+	* @returns 是否应用了请求的选区
+	*/
+	selectObjects(ids) {
+		return this.editor.selectObjects(ids);
+	}
+	/**
+	* 清除当前画布选区，不修改设计内容或历史记录
+	*
+	* @returns 清除前是否存在选中对象
+	*/
+	clearSelection() {
+		return this.editor.clearSelection();
+	}
+	/**
+	* 按稳定 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);
+	}
+	/**
+	* 将现有图片转换为铺满当前 UV 可打印区域的设计背景
+	*
+	* 转换会替换已有设计背景、重置旋转、锁定对象并移动到最底层
+	*
+	* @param id Design JSON 中的图片对象 ID
+	* @returns 是否找到普通图片并完成转换
+	*/
+	setImageAsBackground(id) {
+		return this.editor.setImageAsBackground(id);
+	}
+	/**
+	* 修改对象在图层面板中的名称
+	*
+	* @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);
+	}
+	/**
+	* 更新对象中心位置、缩放、旋转和翻转
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param options 要更新的变换字段
+	* @returns 约束后的对象快照，找不到对象时返回 undefined
+	* @throws 数值无效或缩放倍数不大于零时抛出错误
+	*/
+	updateObjectTransform(id, options) {
+		return this.editor.updateObjectTransform(id, options);
+	}
+	/**
+	* 修改已有文字对象的内容和排版样式
+	*
+	* 连续调用会在短暂空闲后合并为一个撤销步骤
+	*
+	* @param id Design JSON 中的对象 ID
+	* @param options 要修改的文字属性，未传字段保持不变
+	* @returns 是否找到并更新了文字对象
+	* @throws 字号、行高、字距、字重或 CSS 颜色不符合约束时抛出错误
+	*/
+	updateText(id, options) {
+		return this.editor.updateText(id, options);
+	}
+	/**
+	* 让一个未锁定文字对象进入画布内联编辑状态
+	*
+	* @param id Design JSON 中的对象 ID
+	* @returns 是否找到文字对象并进入编辑状态
+	*/
+	editText(id) {
+		return this.editor.editText(id);
+	}
+	/**
+	* 删除二维编辑器中的当前对象或选区
+	*
+	* @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 Data URL
+	*
+	* 结果与逻辑画布同尺寸，不包含选择框和 UV 辅助层
+	*
+	* @returns PNG Data URL
+	* @throws 远程图片污染 Canvas 时抛出安全错误
+	*/
+	getTextureDataUrl() {
+		return this.editor.getTextureDataUrl();
+	}
+	/**
+	* 异步返回当前合成纹理的 PNG Blob
+	*
+	* 结果与逻辑画布同尺寸，不包含选择框和 UV 辅助层
+	*
+	* @returns PNG Blob
+	* @throws 远程图片污染 Canvas 或浏览器无法编码时抛出错误
+	*/
+	getTextureBlob() {
+		return this.editor.getTextureBlob();
+	}
+	/**
+	* 将当前二维设计合成为 PNG 并触发浏览器下载
+	*
+	* @param filename 下载文件名，默认为 `custom-texture.png`
+	* @throws 远程图片污染 Canvas 时可能抛出安全错误
+	*/
+	exportTexture(filename) {
+		this.editor.exportTexture(filename);
+	}
+	/** 恢复三维产品的默认相机位置 */
+	resetView() {
+		this.viewer.resetView();
+	}
+	/** 返回当前三维相机位置和观察目标点 */
+	getViewState() {
+		return this.viewer.getViewState();
+	}
+	/**
+	* 恢复三维观察视角
+	*
+	* @param state 要恢复的相机位置和观察目标点
+	* @returns 应用后的独立视角快照
+	* @throws 坐标不是有限数值或相机与目标点重合时抛出错误
+	*/
+	setViewState(state) {
+		return this.viewer.setViewState(state);
+	}
+	/**
+	* 更换模型、基础纹理和接收纹理的目标 Mesh
+	*
+	* 成功后保留当前设计对象，并将当前设计设为新的历史起点
+	*
+	* @param product 新的产品配置
+	* @throws 模型或纹理加载失败、目标 Mesh 不存在时抛出错误
+	*/
+	async loadProduct(product) {
+		const nextProduct = normalizeProductConfiguration(product);
+		this.emit("status", { message: "Loading product" });
+		try {
+			const uvLayout = await this.viewer.loadProduct(nextProduct);
+			await this.editor.setBackgroundTexture(nextProduct.textureUrl);
+			this.textureBridge.setFlipY(nextProduct.textureFlipY);
+			this.editor.setUvLayout(uvLayout, nextProduct.textureFlipY);
+			this.product = nextProduct;
+			this.editor.clearHistory();
+			this.emit("ready", { product: this.getProduct() });
+			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.stopViewListener?.();
+		this.textureBridge.destroy();
+		this.editor.destroy();
+		this.viewer.destroy();
+	}
+	async initialize() {
+		const uvLayout = await this.viewer.loadProduct(this.product);
+		await this.editor.setBackgroundTexture(this.product.textureUrl);
+		this.textureBridge.setFlipY(this.product.textureFlipY);
+		this.editor.setUvLayout(uvLayout, this.product.textureFlipY);
+		this.emit("ready", { product: this.getProduct() });
+	}
+	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-4ytA68eg.js.map