customforge 0.1.0-alpha.2 → 0.1.0

package/dist/{ProductCustomizer-rMRyWe7L.js → ProductCustomizer-4ytA68eg.js}

@@ -1,22 +1,21 @@
-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 { 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 = {}) {
-	const modelUrl = product.modelUrl?.trim() || void 0;
 	return {
-		modelUrl,
+		modelUrl: product.modelUrl?.trim() || void 0,
 		textureUrl: product.textureUrl?.trim() || void 0,
 		surfaceMesh: product.surfaceMesh?.trim() || "PrintArea",
-		textureFlipY: product.textureFlipY ?? !modelUrl
+		textureFlipY: product.textureFlipY ?? false
 	};
 }
 //#endregion
@@ -63,6 +62,20 @@ 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() },
@@ -97,7 +110,14 @@ function parseObject(value, index) {
 		width: readPositiveNumber(object.width, `${path}.width`),
 		fontFamily: readString(object.fontFamily, `${path}.fontFamily`),
 		fontSize: readPositiveNumber(object.fontSize, `${path}.fontSize`),
-		color: readString(object.color, `${path}.color`)
+		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`);
@@ -230,6 +250,55 @@ function calculateContainmentOffset(bounds, canvasWidth, canvasHeight) {
 	};
 }
 //#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) => {
@@ -261,10 +330,38 @@ async function resolvePersistentImageSource(src) {
 }
 //#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 的二维纹理编辑器
 *
-* 负责基础纹理、文字、图片、对象选择和 PNG 导出
+* 负责基础纹理、UV 区域辅助层、文字、图片、对象选择和 PNG 导出
 * 显示尺寸可以响应容器变化，内部逻辑尺寸保持不变
 */
 var DesignEditor = class {
@@ -273,6 +370,12 @@ var DesignEditor = class {
 	host;
 	width;
 	height;
+	defaultText;
+	textObjectName;
+	imageObjectName;
+	backgroundObjectName;
+	appearance;
+	editableBounds;
 	renderListeners = /* @__PURE__ */ new Set();
 	selectionListeners = /* @__PURE__ */ new Set();
 	historyListeners = /* @__PURE__ */ new Set();
@@ -285,9 +388,14 @@ var DesignEditor = class {
 	imageRoles = /* @__PURE__ */ new WeakMap();
 	resizeObserver;
 	history;
+	uvOverlay;
+	textureRenderer;
+	textureCanvasElement;
+	textureContext;
 	historySignature;
 	historyTimer;
 	historyBusy = false;
+	renderingTexture = false;
 	objectIdSequence = 0;
 	/**
 	* @param host 二维编辑器挂载容器
@@ -297,23 +405,53 @@ var DesignEditor = class {
 		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", "UV texture editor");
+		element.setAttribute("aria-label", options.ariaLabel ?? "UV texture editor");
 		host.replaceChildren(element);
-		this.canvas = new Canvas(element, {
+		const canvas = new DesignCanvas(element, {
 			width: this.width,
 			height: this.height,
-			backgroundColor: "#f7f7f5",
 			preserveObjectStacking: true,
-			selectionColor: "rgba(19, 113, 125, 0.12)",
-			selectionBorderColor: "#13717d"
+			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());
 		});
@@ -341,9 +479,54 @@ var DesignEditor = class {
 		this.resizeObserver.observe(host);
 		this.resizeDisplay();
 	}
-	/** 供 Three.js 创建 CanvasTexture 的底层 HTML Canvas */
+	/** 供 Three.js 创建 CanvasTexture 的纯设计画布，不包含选择框和变换控件 */
 	get textureCanvas() {
-		return this.canvas.getElement();
+		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() {
@@ -395,6 +578,17 @@ var DesignEditor = class {
 	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));
@@ -406,9 +600,34 @@ var DesignEditor = class {
 	* @returns 是否找到并选中了对象
 	*/
 	selectObject(id) {
-		const object = this.objectsById.get(id);
-		if (!object || !object.visible) return false;
-		this.canvas.setActiveObject(object);
+		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;
@@ -457,6 +676,29 @@ var DesignEditor = class {
 		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
@@ -508,7 +750,125 @@ var DesignEditor = class {
 		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 导出中
 	*
@@ -518,7 +878,7 @@ var DesignEditor = class {
 	async setBackgroundTexture(url) {
 		if (!url) {
 			this.canvas.backgroundImage = void 0;
-			this.canvas.backgroundColor = "#f7f7f5";
+			this.canvas.backgroundColor = "";
 			this.canvas.requestRenderAll();
 			return;
 		}
@@ -545,41 +905,42 @@ var DesignEditor = class {
 	* 对象过大时会等比缩小，越界时会自动移回画布
 	*
 	* @param options 文字内容、位置和样式
-	* @returns 创建的 Fabric Textbox
+	* @returns 创建后的可持久化文字对象快照
 	*/
 	addText(options = {}) {
 		this.flushHistoryCommit();
-		const text = new Textbox(options.text ?? "Edit this text", {
+		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 ?? Math.round(this.height * .12),
-			fontWeight: 700,
+			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: "center",
+			textAlign: options.textAlign ?? "center",
+			lineHeight: options.lineHeight ?? 1.16,
+			charSpacing: options.charSpacing ?? 0,
 			editable: true,
-			transparentCorners: false,
-			cornerColor: "#ffffff",
-			cornerStrokeColor: "#13717d",
-			borderColor: "#13717d",
-			cornerSize: 16
+			...this.objectControlAppearance()
 		});
 		this.addAndSelect(text, options.name);
-		return text;
+		return this.serializeObject(text);
 	}
 	/**
 	* 加载、添加并选中一个图片对象
 	*
-	* role 为 background 时替换已有设计背景、铺满画布并默认锁定在最底层
+	* role 为 background 时替换已有设计背景、铺满当前 UV 可打印区域并默认锁定在最底层
 	* 图片位置使用画布像素坐标，原点位于图片中心
 	* 对象过大时会等比缩小，越界时会自动移回画布
 	* 远程图片必须提供正确的 CORS 响应头才能安全导出 PNG
 	*
 	* @param options 图片地址、中心位置和显示宽度
-	* @returns 创建的 FabricImage
+	* @returns 创建后的可持久化图片对象快照
 	* @throws 图片加载失败或被 CORS 策略阻止时抛出错误
 	*/
 	async addImage(options) {
@@ -589,22 +950,21 @@ var DesignEditor = class {
 		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,
+			left: options.x ?? this.width * .62,
+			top: 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
+			scaleX: scale,
+			scaleY: scale,
+			...this.objectControlAppearance()
 		});
-		if (role === "background") this.removeDesignBackgrounds();
+		if (role === "background") {
+			this.removeDesignBackgrounds();
+			this.fitImageToEditableBounds(image);
+		}
 		this.imageSources.set(image, source);
 		this.addAndSelect(image, options.name, role === "background", role);
-		return image;
+		return this.serializeObject(image);
 	}
 	/**
 	* 返回与 Fabric.js 无关的当前设计快照
@@ -744,16 +1104,36 @@ var DesignEditor = class {
 	* @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.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) {
@@ -820,7 +1200,14 @@ var DesignEditor = class {
 				width: object.width,
 				fontFamily: object.fontFamily,
 				fontSize: object.fontSize,
-				color: object.fill
+				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) {
@@ -861,20 +1248,21 @@ var DesignEditor = class {
 			flipX: design.transform.flipX,
 			flipY: design.transform.flipY,
 			visible: design.visible ?? true,
-			transparentCorners: false,
-			cornerColor: "#ffffff",
-			cornerStrokeColor: "#13717d",
-			borderColor: "#13717d",
-			cornerSize: 16
+			...this.objectControlAppearance()
 		};
 		if (design.type === "text") return new Textbox(design.text, {
 			...common,
 			width: design.width,
 			fontFamily: design.fontFamily,
 			fontSize: design.fontSize,
-			fontWeight: 700,
+			fontWeight: design.fontWeight ?? 700,
+			fontStyle: design.fontStyle ?? "normal",
+			underline: design.underline ?? false,
 			fill: design.color,
-			textAlign: "center",
+			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);
@@ -885,8 +1273,9 @@ var DesignEditor = class {
 		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";
+		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);
@@ -970,14 +1359,55 @@ var DesignEditor = class {
 		}
 	}
 	resizeDisplay() {
-		const availableWidth = Math.max(this.host.clientWidth - 32, 1);
-		const availableHeight = Math.max(this.host.clientHeight - 32, 1);
+		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();
@@ -1009,7 +1439,7 @@ var TextureBridge = class {
 	stopListening;
 	updateFrame = 0;
 	/**
-	* @param editor 提供底层 HTML Canvas 和渲染事件的二维编辑器
+	* @param editor 提供不含交互控件的纹理 Canvas 和渲染事件的二维编辑器
 	* @param viewer 接收实时纹理的三维查看器
 	* @param flipY 是否垂直翻转纹理
 	*/
@@ -1047,7 +1477,96 @@ var TextureBridge = class {
 	}
 };
 //#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 的三维产品查看器
 *
@@ -1066,10 +1585,17 @@ var ProductViewer = class {
 	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) {
+	constructor(host, ariaLabel = "Interactive 3D product preview", appearance = {}) {
 		this.host = host;
 		host.replaceChildren();
 		this.renderer = new WebGLRenderer({
@@ -1080,29 +1606,30 @@ var ProductViewer = class {
 		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");
+		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.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.controls.addEventListener("change", this.handleControlsChange);
+		this.addStudioLighting();
 		this.resizeObserver = new ResizeObserver(() => this.resize());
 		this.resizeObserver.observe(host);
 		this.resize();
 		this.render();
 	}
 	/**
-	* 加载远程模型或创建内置演示模型
+	* 加载远程模型或随包提供的默认 GLB 模型
 	*
 	* @param product 已完成默认值补全的产品配置
-	* @throws 模型加载失败或找不到目标 Mesh 时抛出错误
+	* @returns 目标 Mesh 第一个材质槽使用的 UV 三角形布局
+	* @throws 模型加载失败、找不到目标 Mesh 或目标 Mesh 缺少有效 UV 时抛出错误
 	*/
 	async loadProduct(product) {
 		this.removeProduct();
@@ -1111,13 +1638,18 @@ var ProductViewer = class {
 			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;
+			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;
 	}
 	/**
 	* 保存并绑定二维编辑器生成的实时纹理
@@ -1134,71 +1666,82 @@ var ProductViewer = class {
 	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();
 	}
-	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;
+	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("#b7dce0", 1.2);
-		fill.position.set(-5, 2, 3);
+		const fill = new DirectionalLight("#e8f0f2", 1.15);
+		fill.position.set(-5, 2, 4);
 		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 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 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
-		};
+		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
@@ -1231,19 +1774,59 @@ var ProductViewer = class {
 		material.color.set("#ffffff");
 		material.needsUpdate = true;
 	}
-	fitCamera(root) {
+	fitCamera(root, direction) {
 		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);
+		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).add(new Vector3(distance * .55, distance * .42, distance));
-		this.camera.near = Math.max(distance / 100, .01);
-		this.camera.far = distance * 100;
+		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);
@@ -1258,9 +1841,11 @@ var ProductViewer = class {
 	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;
-		this.camera.updateProjectionMatrix();
+		if (this.productRoot && direction.lengthSq() > 0) this.fitCamera(this.productRoot, direction);
+		else this.camera.updateProjectionMatrix();
 	}
 	render = () => {
 		this.animationFrame = requestAnimationFrame(this.render);
@@ -1312,6 +1897,7 @@ var ProductCustomizer = class ProductCustomizer {
 	stopSelectionListener;
 	stopRenderListener;
 	stopHistoryListener;
+	stopViewListener;
 	destroyed = false;
 	constructor(options) {
 		const editorHost = resolveElement(options.editor, "Editor");
@@ -1323,9 +1909,15 @@ var ProductCustomizer = class ProductCustomizer {
 		this.editor = new DesignEditor(editorHost, {
 			width: options.editorWidth ?? 1024,
 			height: options.editorHeight ?? 512,
-			historyLimit
+			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);
+		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", {
@@ -1339,6 +1931,9 @@ var ProductCustomizer = class ProductCustomizer {
 		this.stopHistoryListener = this.editor.onHistoryChange((state) => {
 			this.emit("historychange", state);
 		});
+		this.stopViewListener = this.viewer.onViewChange((state) => {
+			this.emit("viewchange", state);
+		});
 	}
 	/**
 	* 创建实例并完成初始产品加载
@@ -1377,27 +1972,56 @@ var ProductCustomizer = class ProductCustomizer {
 	* 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
 	*
 	* @param options 文字内容、位置和样式配置
+	* @returns 创建后的可持久化文字对象快照
 	*/
 	addText(options) {
-		this.editor.addText(options);
+		return this.editor.addText(options);
 	}
 	/**
 	* 加载图片并将其添加到二维画布
 	*
-	* role 为 background 时会替换已有设计背景并默认锁定在最底层
+	* role 为 background 时会替换已有设计背景、铺满当前 UV 可打印区域并默认锁定在最底层
 	* 创建后和用户变换期间，对象会自动缩放或平移以保持完整可见
 	*
 	* @param options 图片地址、位置和显示宽度
+	* @returns 创建后的可持久化图片对象快照
 	* @throws 图片无法访问、加载失败或被 CORS 策略阻止时抛出错误
 	*/
 	async addImage(options) {
 		try {
-			await this.editor.addImage(options);
+			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();
+	}
 	/**
 	* 返回当前可编辑对象的独立快照
 	*
@@ -1420,6 +2044,25 @@ var ProductCustomizer = class ProductCustomizer {
 		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
@@ -1439,6 +2082,17 @@ var ProductCustomizer = class ProductCustomizer {
 		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
@@ -1469,6 +2123,39 @@ var ProductCustomizer = class ProductCustomizer {
 		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 是否删除了至少一个对象
@@ -1552,6 +2239,28 @@ var ProductCustomizer = class ProductCustomizer {
 		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`
@@ -1564,6 +2273,20 @@ var ProductCustomizer = class ProductCustomizer {
 	resetView() {
 		this.viewer.resetView();
 	}
+	/** 返回当前三维相机位置和观察目标点 */
+	getViewState() {
+		return this.viewer.getViewState();
+	}
+	/**
+	* 恢复三维观察视角
+	*
+	* @param state 要恢复的相机位置和观察目标点
+	* @returns 应用后的独立视角快照
+	* @throws 坐标不是有限数值或相机与目标点重合时抛出错误
+	*/
+	setViewState(state) {
+		return this.viewer.setViewState(state);
+	}
 	/**
 	* 更换模型、基础纹理和接收纹理的目标 Mesh
 	*
@@ -1576,12 +2299,13 @@ var ProductCustomizer = class ProductCustomizer {
 		const nextProduct = normalizeProductConfiguration(product);
 		this.emit("status", { message: "Loading product" });
 		try {
-			await this.viewer.loadProduct(nextProduct);
+			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.product });
+			this.emit("ready", { product: this.getProduct() });
 			this.emit("status", { message: nextProduct.modelUrl ? "Remote product ready" : "Demo product ready" });
 		} catch (error) {
 			this.reportError(error);
@@ -1599,15 +2323,17 @@ var ProductCustomizer = class ProductCustomizer {
 		this.stopSelectionListener?.();
 		this.stopRenderListener?.();
 		this.stopHistoryListener?.();
+		this.stopViewListener?.();
 		this.textureBridge.destroy();
 		this.editor.destroy();
 		this.viewer.destroy();
 	}
 	async initialize() {
-		await this.viewer.loadProduct(this.product);
+		const uvLayout = 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 });
+		this.editor.setUvLayout(uvLayout, this.product.textureFlipY);
+		this.emit("ready", { product: this.getProduct() });
 	}
 	emit(event, detail) {
 		this.events.dispatchEvent(new CustomEvent(event, { detail }));
@@ -1621,4 +2347,4 @@ var ProductCustomizer = class ProductCustomizer {
 //#endregion
 export { resolveElement as n, ProductCustomizer as t };
 
-//# sourceMappingURL=ProductCustomizer-rMRyWe7L.js.map
+//# sourceMappingURL=ProductCustomizer-4ytA68eg.js.map