@openfairygui/cli 0.2.0-alpha.10 → 0.2.0-alpha.11

package/dist/cli.mjs

@@ -1,10 +1,178 @@
 import { createRequire } from "node:module";
+import { Command } from "commander";
 import { createNodeBackendRuntime } from "@openfairygui/backend/node";
-import * as fs$1 from "node:fs/promises";
-import fs from "node:fs/promises";
 import * as path$1 from "node:path";
 import path from "node:path";
-import { parseArgs } from "node:util";
+import { createJiti } from "jiti";
+import * as fs$1 from "node:fs/promises";
+import fs from "node:fs/promises";
+//#region src/commands/backend-capabilities.ts
+function registerBackendCapabilitiesCommand(program) {
+	program.command("backend-capabilities").description("Open a backend session, print runtime capabilities, then close it").argument("<project-dir>", "Project root directory").action(async (projectDir) => {
+		const runtime = createNodeBackendRuntime();
+		const opened = await runtime.openSession({ projectPath: path.resolve(projectDir) });
+		if (!opened.ok) throw new Error(`backend-capabilities: ${opened.error.message}`);
+		const capabilities = runtime.getCapabilities();
+		if (!capabilities.ok) {
+			await runtime.closeSession({ sessionId: opened.data.sessionId });
+			throw new Error("backend-capabilities: failed to read capabilities");
+		}
+		console.log(`Session: ${opened.data.sessionId}`);
+		console.log(`Project: ${opened.data.canonicalProjectPath}`);
+		console.log(`Revision: ${opened.data.revision}`);
+		console.log(`Runtime owner: ${capabilities.data.runtimeOwner}`);
+		console.log(`Transaction owner: ${capabilities.data.transactionKernelOwner}`);
+		console.log(`App seam owner: ${capabilities.data.appSeamOwner}`);
+		const closed = await runtime.closeSession({ sessionId: opened.data.sessionId });
+		if (!closed.ok) throw new Error(`backend-capabilities: ${closed.error.message}`);
+	});
+}
+//#endregion
+//#region ../functions/src/inspect.ts
+function mapResource(resource) {
+	return {
+		name: resource.getName(),
+		id: resource.getId(),
+		path: resource.getPath?.() ?? "/",
+		exported: resource.getExported?.() ?? false
+	};
+}
+function mapComponentDetail(component, totals) {
+	const children = component.listChildren();
+	const controllers = component.listControllers();
+	const transitions = component.listTransitions();
+	totals.displayObjects += children.length;
+	totals.controllers += controllers.length;
+	totals.transitions += transitions.length;
+	for (const child of children) totals.gears += child.listGears().length;
+	return {
+		name: component.getName(),
+		id: component.getId(),
+		childCount: children.length,
+		controllerCount: controllers.length,
+		transitionCount: transitions.length
+	};
+}
+/**
+* Generates a detailed report of the project contents.
+*
+* Unlike other transforms, `inspect()` does NOT modify the document —
+* it returns a structured report.
+*
+* ```ts
+* const report = inspect(doc);
+* console.log(`${report.totals.packages} packages, ${report.totals.components} components`);
+* ```
+*/
+function inspect(doc) {
+	const root = doc.getRoot();
+	const totals = {
+		packages: 0,
+		images: 0,
+		sounds: 0,
+		fonts: 0,
+		movieClips: 0,
+		components: 0,
+		displayObjects: 0,
+		gears: 0,
+		controllers: 0,
+		transitions: 0
+	};
+	const packages = root.listPackages().map((pkg) => {
+		totals.packages++;
+		const resources = pkg.listResources();
+		const images = resources.filter((r) => r.propertyType === "ImageResource");
+		const sounds = resources.filter((r) => r.propertyType === "SoundResource");
+		const fonts = resources.filter((r) => r.propertyType === "FontResource");
+		const movieClips = resources.filter((r) => r.propertyType === "MovieClipResource");
+		const components = pkg.listComponents();
+		totals.images += images.length;
+		totals.sounds += sounds.length;
+		totals.fonts += fonts.length;
+		totals.movieClips += movieClips.length;
+		totals.components += components.length;
+		const componentDetails = components.map((component) => mapComponentDetail(component, totals));
+		return {
+			name: pkg.getName(),
+			id: pkg.getId(),
+			publishName: pkg.getPublishName() || pkg.getName(),
+			resources: {
+				images: {
+					count: images.length,
+					details: images.map(mapResource)
+				},
+				sounds: {
+					count: sounds.length,
+					details: sounds.map(mapResource)
+				},
+				fonts: {
+					count: fonts.length,
+					details: fonts.map(mapResource)
+				},
+				movieClips: {
+					count: movieClips.length,
+					details: movieClips.map(mapResource)
+				},
+				components: {
+					count: components.length,
+					details: components.map(mapResource)
+				}
+			},
+			componentDetails
+		};
+	});
+	return {
+		projectId: root.getProjectId(),
+		projectType: root.getProjectType(),
+		version: root.getVersion(),
+		packages,
+		totals
+	};
+}
+//#endregion
+//#region ../functions/src/utils.ts
+/**
+* Wraps a transform function, assigning it a name for the transform stack.
+*/
+function createTransform(name, fn) {
+	Object.defineProperty(fn, "name", { value: name });
+	return fn;
+}
+function parseTextureSetMode(value) {
+	const raw = value?.trim() ?? "";
+	if (!raw) return {
+		kind: "auto",
+		raw: ""
+	};
+	if (raw === "alone") return {
+		kind: "standalone",
+		raw,
+		sizeMode: "default"
+	};
+	if (raw === "alone_npot") return {
+		kind: "standalone",
+		raw,
+		sizeMode: "npot"
+	};
+	if (raw === "alone_mof") return {
+		kind: "standalone",
+		raw,
+		sizeMode: "multipleOf4"
+	};
+	if (/^\d+$/.test(raw)) {
+		const pageIndex = Number(raw);
+		if (pageIndex >= 0 && pageIndex <= 10) return {
+			kind: "page",
+			raw,
+			pageIndex
+		};
+	}
+	return {
+		kind: "auto",
+		raw
+	};
+}
+//#endregion
 //#region ../../node_modules/.pnpm/property-graph@4.1.0/node_modules/property-graph/dist/index.mjs
 var EventDispatcher = class {
 	_listeners = {};
@@ -1688,6 +1856,7 @@ var MovieClipResource = class extends ExtensibleProperty {
 			highResolutionItemIds: [],
 			fileName: "",
 			exported: false,
+			textureSetMode: "",
 			width: 0,
 			height: 0,
 			interval: 0,
@@ -1739,6 +1908,12 @@ var MovieClipResource = class extends ExtensibleProperty {
 	setExported(v) {
 		return this.set("exported", v);
 	}
+	getTextureSetMode() {
+		return this.get("textureSetMode");
+	}
+	setTextureSetMode(v) {
+		return this.set("textureSetMode", v);
+	}
 	getWidth() {
 		return this.get("width");
 	}
@@ -4451,6 +4626,8 @@ var GComponent = class extends GObject {
 			instanceController: "",
 			instancePage: "",
 			instanceChecked: false,
+			instanceSound: "",
+			instanceSoundVolumeScale: 1,
 			instancePromptText: "",
 			instanceSelectionController: "",
 			instanceVisibleItemCount: 0,
@@ -4723,6 +4900,18 @@ var GComponent = class extends GObject {
 	setInstanceChecked(v) {
 		return this.setComponentProp("instanceChecked", v);
 	}
+	getInstanceSound() {
+		return firstString$1(this.getComponentProp("instanceSound"));
+	}
+	setInstanceSound(v) {
+		return this.setComponentProp("instanceSound", v);
+	}
+	getInstanceSoundVolumeScale() {
+		return this.getComponentProp("instanceSoundVolumeScale");
+	}
+	setInstanceSoundVolumeScale(v) {
+		return this.setComponentProp("instanceSoundVolumeScale", v);
+	}
 	getInstancePromptText() {
 		return firstString$1(this.getComponentProp("instancePromptText"));
 	}
@@ -9081,6 +9270,7 @@ var Document = class Document {
 	_graph = new Graph();
 	_root = new Root(this._graph);
 	_logger = Logger.DEFAULT_INSTANCE;
+	_projectDir = "";
 	static _GRAPH_DOCUMENTS = /* @__PURE__ */ new WeakMap();
 	static fromGraph(graph) {
 		return Document._GRAPH_DOCUMENTS.get(graph) || null;
@@ -9102,6 +9292,13 @@ var Document = class Document {
 		this._logger = logger;
 		return this;
 	}
+	getProjectDir() {
+		return this._projectDir;
+	}
+	setProjectDir(projectDir) {
+		this._projectDir = projectDir;
+		return this;
+	}
 	async transform(...transforms) {
 		const stack = transforms.map((fn) => fn.name);
 		for (const transform of transforms) await transform(this, { stack });
@@ -9282,6 +9479,7 @@ const PACKAGE_FONT_RESOURCE_ATTRS = {
 	renderMode: { canonical: "renderMode" },
 	samplePointSize: { canonical: "samplePointSize" }
 };
+const PACKAGE_MOVIE_CLIP_RESOURCE_ATTRS = { atlas: { canonical: "atlas" } };
 const PACKAGE_SKELETON_RESOURCE_ATTRS = {
 	width: { canonical: "width" },
 	height: { canonical: "height" },
@@ -9518,7 +9716,10 @@ const LIST_PANEL_ATTRS = {
 const BUTTON_EXTENSION_ATTRS = {
 	mode: { canonical: "mode" },
 	sound: { canonical: "sound" },
-	soundVolumeScale: { canonical: "soundVolumeScale" },
+	soundVolumeScale: {
+		canonical: "soundVolumeScale",
+		aliases: ["volume"]
+	},
 	downEffect: { canonical: "downEffect" },
 	downEffectValue: { canonical: "downEffectValue" },
 	title: { canonical: "title" },
@@ -9644,6 +9845,7 @@ const PACKAGE_PUBLISH_NODE = defineNode(PACKAGE_PUBLISH_ATTRS, { atlas: PACKAGE_
 const PACKAGE_RESOURCE_NODE = defineNode(PACKAGE_RESOURCE_BASE_ATTRS);
 const PACKAGE_IMAGE_RESOURCE_NODE = defineNode(PACKAGE_IMAGE_RESOURCE_ATTRS);
 const PACKAGE_FONT_RESOURCE_NODE = defineNode(PACKAGE_FONT_RESOURCE_ATTRS);
+const PACKAGE_MOVIE_CLIP_RESOURCE_NODE = defineNode(PACKAGE_MOVIE_CLIP_RESOURCE_ATTRS);
 const PACKAGE_SKELETON_RESOURCE_NODE = defineNode(PACKAGE_SKELETON_RESOURCE_ATTRS);
 const DISPLAY_OBJECT_NODE = defineNode(DISPLAY_OBJECT_IDENTITY_ATTRS);
 const BUTTON_EXTENSION_NODE = defineNode(BUTTON_EXTENSION_ATTRS);
@@ -9734,6 +9936,7 @@ const PROJECT_XML_PROTOCOL = {
 	packageResource: PACKAGE_RESOURCE_NODE,
 	packageImageResource: PACKAGE_IMAGE_RESOURCE_NODE,
 	packageFontResource: PACKAGE_FONT_RESOURCE_NODE,
+	packageMovieClipResource: PACKAGE_MOVIE_CLIP_RESOURCE_NODE,
 	packageSkeletonResource: PACKAGE_SKELETON_RESOURCE_NODE,
 	displayObject: DISPLAY_OBJECT_NODE,
 	image: IMAGE_NODE,
@@ -10177,6 +10380,7 @@ var ProjectReader = class {
 		const fs = this._fs;
 		const doc = new Document();
 		const basePath = getProjectBasePath(fs, projectPath);
+		doc.setProjectDir(basePath);
 		const ctx = new ReaderContext(doc, basePath);
 		const projDesc = getXmlNode(parseXML(await fs.readFile(projectPath)).projectDescription);
 		if (projDesc) {
@@ -10493,6 +10697,8 @@ var ProjectReader = class {
 				res.setBranch(branchName);
 				res.setFileName(name);
 				res.setExported(exported);
+				const textureSetMode = readXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageMovieClipResource.attrs.atlas);
+				if (textureSetMode !== void 0) res.setTextureSetMode(textureSetMode);
 				pkg.addResource(res);
 				ctx.registerResource(pkg.getId(), id, res);
 				return res;
@@ -11752,6 +11958,10 @@ var ProjectReader = class {
 				if (page !== void 0) componentObj.setInstancePage?.(page);
 				const checked = extSpecs.checked ? readXmlAttr(extAttrs, extSpecs.checked) : void 0;
 				if (checked !== void 0) componentObj.setInstanceChecked?.(parseBool(checked));
+				const sound = extSpecs.sound ? readXmlAttr(extAttrs, extSpecs.sound) : void 0;
+				if (sound !== void 0) componentObj.setInstanceSound?.(sound);
+				const soundVolumeScale = extSpecs.soundVolumeScale ? readXmlAttr(extAttrs, extSpecs.soundVolumeScale) : void 0;
+				if (soundVolumeScale !== void 0) componentObj.setInstanceSoundVolumeScale?.(parseFloat2(soundVolumeScale, 1));
 				const prompt = extSpecs.prompt ? readXmlAttr(extAttrs, extSpecs.prompt) : void 0;
 				if (prompt !== void 0) componentObj.setInstancePromptText?.(prompt);
 				const selectionController = extSpecs.selectionController ? readXmlAttr(extAttrs, extSpecs.selectionController) : void 0;
@@ -12418,6 +12628,10 @@ var ProjectWriter = class {
 				const samplePointSize = fontRes.getSamplePointSize?.() ?? 0;
 				if (samplePointSize !== 0) writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageFontResource.attrs.samplePointSize, String(samplePointSize));
 			}
+			if (res.propertyType === "MovieClipResource") {
+				const textureSetMode = res.getTextureSetMode?.() ?? "";
+				if (textureSetMode) writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageMovieClipResource.attrs.atlas, textureSetMode);
+			}
 			if (res.propertyType === "SpineResource" || res.propertyType === "DragonBonesResource") {
 				const skeletonRes = res;
 				writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageSkeletonResource.attrs.width, String(skeletonRes.getWidth?.() ?? 0));
@@ -13099,6 +13313,8 @@ var ProjectWriter = class {
 				if (typedObj.getInstanceController?.() && extSpecs.controller) writeXmlAttr(extAttrs, extSpecs.controller, typedObj.getInstanceController?.());
 				if (typedObj.getInstancePage?.() && extSpecs.page) writeXmlAttr(extAttrs, extSpecs.page, typedObj.getInstancePage?.());
 				if (typedObj.getInstanceChecked?.() && extSpecs.checked) writeXmlAttr(extAttrs, extSpecs.checked, "1");
+				if (typedObj.getInstanceSound?.() && extSpecs.sound) writeXmlAttr(extAttrs, extSpecs.sound, typedObj.getInstanceSound?.());
+				if ((typedObj.getInstanceSoundVolumeScale?.() ?? 1) !== 1 && extSpecs.soundVolumeScale) writeXmlAttr(extAttrs, extSpecs.soundVolumeScale, String(typedObj.getInstanceSoundVolumeScale?.() ?? 1));
 				if (typedObj.getInstancePromptText?.() && extSpecs.prompt) writeXmlAttr(extAttrs, extSpecs.prompt, typedObj.getInstancePromptText?.());
 				if (typedObj.getInstanceSelectionController?.() && extSpecs.selectionController) writeXmlAttr(extAttrs, extSpecs.selectionController, typedObj.getInstanceSelectionController?.());
 				if ((typedObj.getInstanceVisibleItemCount?.() ?? 0) > 0 && extSpecs.visibleItemCount) writeXmlAttr(extAttrs, extSpecs.visibleItemCount, String(typedObj.getInstanceVisibleItemCount?.() ?? 0));
@@ -17569,8 +17785,8 @@ function decodeChildBlock6(resource, child, childBuf) {
 						if (relatedControllerIndex >= 0) component.setInstanceController(resource.listControllers()[relatedControllerIndex]?.getName() ?? "");
 					}
 					component.setInstancePage(childBuf.readS() ?? "");
-					childBuf.readS();
-					if (childBuf.readBool() && remainingBytes(childBuf) >= 4) childBuf.getFloat32();
+					component.setInstanceSound(childBuf.readS() ?? "");
+					if (childBuf.readBool() && remainingBytes(childBuf) >= 4) component.setInstanceSoundVolumeScale(childBuf.getFloat32());
 					if (remainingBytes(childBuf) >= 1) component.setInstanceChecked(childBuf.readBool());
 					break;
 				case "Label":
@@ -18144,8 +18360,9 @@ const BinItemType$1 = {
 	Font: 5,
 	Swf: 6,
 	Misc: 7,
-	Spine: 8,
-	DragonBones: 9
+	Unknown: 8,
+	Spine: 9,
+	DragonBones: 10
 };
 function normalizePackageResourcePath(path) {
 	const normalized = path.replace(/\\/g, "/").trim();
@@ -19983,8 +20200,13 @@ function _writeExtensionInstanceData(buf, extType, child, comp, pkg, version) {
 				buf.writeInt16(ctrlIdx >= 0 ? ctrlIdx : -1);
 			} else buf.writeInt16(-1);
 			buf.writeS(child.getInstancePage?.() ?? null);
-			buf.writeSEx(null, false, false);
-			buf.writeBool(false);
+			const sound = child.getInstanceSound?.() ?? null;
+			buf.writeSEx(remapLocalUiUrl(pkg, sound) ?? null, false, false);
+			const soundVolume = child.getInstanceSoundVolumeScale?.();
+			if (soundVolume !== void 0 && soundVolume !== null && soundVolume !== 1) {
+				buf.writeBool(true);
+				buf.writeFloat32(soundVolume);
+			} else buf.writeBool(false);
 			buf.writeBool(child.getInstanceChecked?.() ?? false);
 			break;
 		}
@@ -20165,8 +20387,9 @@ const BinItemType = {
 	Atlas: 4,
 	Font: 5,
 	Misc: 7,
-	Spine: 8,
-	DragonBones: 9
+	Unknown: 8,
+	Spine: 9,
+	DragonBones: 10
 };
 /**
 * Maps our PropertyType to the editor's type string used for sorting.
@@ -20825,228 +21048,60 @@ var PlatformIO = class {
 	}
 };
 //#endregion
-//#region ../core/src/io/node-io.ts
-/**
-* Node.js I/O implementation for reading and writing FairyGUI projects.
-*
-* Usage:
-*
-* ```ts
-* import { NodeIO } from '@openfairygui/core/node';
-*
-* const io = new NodeIO();
-* const doc = await io.readProject('./path/to/project.fairy');
-* await io.writeProject(doc, './path/to/output.fairy');
-* const doc2 = await io.readBinary('./path/to/package_fui.bytes');
-* ```
-*
-* @category I/O
-*/
-var NodeIO = class extends PlatformIO {
-	createFileSystem() {
-		return {
-			async readFile(filePath) {
-				return fs$1.readFile(filePath, "utf-8");
-			},
-			async readFileRaw(filePath) {
-				const buf = await fs$1.readFile(filePath);
-				return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-			},
-			async writeFile(filePath, content) {
-				await fs$1.writeFile(filePath, content, "utf-8");
-			},
-			async writeFileRaw(filePath, data) {
-				await fs$1.writeFile(filePath, data);
-			},
-			async mkdir(dirPath) {
-				await fs$1.mkdir(dirPath, { recursive: true });
-			},
-			async readdir(dirPath) {
-				return (await fs$1.readdir(dirPath, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
-			},
-			async exists(filePath) {
-				try {
-					await fs$1.access(filePath);
-					return true;
-				} catch {
-					return false;
-				}
-			},
-			join(...paths) {
-				return path$1.join(...paths);
-			},
-			dirname(filePath) {
-				return path$1.dirname(filePath);
-			}
-		};
-	}
-};
-//#endregion
-//#region ../functions/src/inspect.ts
-function mapResource(resource) {
-	return {
-		name: resource.getName(),
-		id: resource.getId(),
-		path: resource.getPath?.() ?? "/",
-		exported: resource.getExported?.() ?? false
-	};
-}
-function mapComponentDetail(component, totals) {
-	const children = component.listChildren();
-	const controllers = component.listControllers();
-	const transitions = component.listTransitions();
-	totals.displayObjects += children.length;
-	totals.controllers += controllers.length;
-	totals.transitions += transitions.length;
-	for (const child of children) totals.gears += child.listGears().length;
-	return {
-		name: component.getName(),
-		id: component.getId(),
-		childCount: children.length,
-		controllerCount: controllers.length,
-		transitionCount: transitions.length
-	};
-}
-/**
-* Generates a detailed report of the project contents.
-*
-* Unlike other transforms, `inspect()` does NOT modify the document —
-* it returns a structured report.
-*
-* ```ts
-* const report = inspect(doc);
-* console.log(`${report.totals.packages} packages, ${report.totals.components} components`);
-* ```
-*/
-function inspect(doc) {
-	const root = doc.getRoot();
-	const totals = {
-		packages: 0,
-		images: 0,
-		sounds: 0,
-		fonts: 0,
-		movieClips: 0,
-		components: 0,
-		displayObjects: 0,
-		gears: 0,
-		controllers: 0,
-		transitions: 0
-	};
-	const packages = root.listPackages().map((pkg) => {
-		totals.packages++;
-		const resources = pkg.listResources();
-		const images = resources.filter((r) => r.propertyType === "ImageResource");
-		const sounds = resources.filter((r) => r.propertyType === "SoundResource");
-		const fonts = resources.filter((r) => r.propertyType === "FontResource");
-		const movieClips = resources.filter((r) => r.propertyType === "MovieClipResource");
-		const components = pkg.listComponents();
-		totals.images += images.length;
-		totals.sounds += sounds.length;
-		totals.fonts += fonts.length;
-		totals.movieClips += movieClips.length;
-		totals.components += components.length;
-		const componentDetails = components.map((component) => mapComponentDetail(component, totals));
-		return {
-			name: pkg.getName(),
-			id: pkg.getId(),
-			publishName: pkg.getPublishName() || pkg.getName(),
-			resources: {
-				images: {
-					count: images.length,
-					details: images.map(mapResource)
-				},
-				sounds: {
-					count: sounds.length,
-					details: sounds.map(mapResource)
-				},
-				fonts: {
-					count: fonts.length,
-					details: fonts.map(mapResource)
-				},
-				movieClips: {
-					count: movieClips.length,
-					details: movieClips.map(mapResource)
-				},
-				components: {
-					count: components.length,
-					details: components.map(mapResource)
-				}
-			},
-			componentDetails
-		};
-	});
-	return {
-		projectId: root.getProjectId(),
-		projectType: root.getProjectType(),
-		version: root.getVersion(),
-		packages,
-		totals
-	};
-}
-//#endregion
-//#region ../functions/src/utils.ts
-/**
-* Wraps a transform function, assigning it a name for the transform stack.
-*/
-function createTransform(name, fn) {
-	Object.defineProperty(fn, "name", { value: name });
-	return fn;
-}
-//#endregion
-//#region ../functions/src/max-rects-compat.ts
-const NO_ROTATION = 2;
-const MAX_SCORE = 2147483647;
-const MAX_RECTS_METHOD = {
-	BestShortSideFit: 0,
-	BestLongSideFit: 1,
-	BestAreaFit: 2,
-	BottomLeftRule: 3,
-	ContactPointRule: 4
-};
-const COMPAT_NODE_RECT_FLAGS = {
-	DUPLICATE_PADDING: 1,
-	NO_ROTATION
-};
-var MaxRectsCompat = class MaxRectsCompat {
-	static helperRect = createNodeRect();
-	binWidth = 0;
-	binHeight = 0;
-	allowRotations = false;
-	usedRectangles = [];
-	freeRectangles = [];
-	init(width, height, allowRotations = false) {
-		this.binWidth = width;
-		this.binHeight = height;
-		this.allowRotations = allowRotations;
-		this.usedRectangles.length = 0;
-		this.freeRectangles.length = 0;
-		this.freeRectangles.push({
-			...createNodeRect(),
-			x: 0,
-			y: 0,
-			width,
-			height
-		});
-	}
-	insert(rect, method) {
-		const newNode = this.scoreRect(rect, method);
-		if (newNode.height === 0) return null;
-		const placed = cloneNodeRect(newNode);
-		this.placeRect(placed);
-		return placed;
-	}
-	pack(rects, method) {
-		const remaining = rects.map(cloneNodeRect);
-		while (remaining.length > 0) {
-			let bestIndex = -1;
-			const bestNode = createNodeRect();
-			bestNode.score1 = MAX_SCORE;
-			bestNode.score2 = MAX_SCORE;
-			for (let index = 0; index < remaining.length; index += 1) {
-				const candidate = this.scoreRect(remaining[index], method);
-				if (candidate.score1 < bestNode.score1 || candidate.score1 === bestNode.score1 && candidate.score2 < bestNode.score2) {
-					copyNodeRect(bestNode, candidate);
-					bestIndex = index;
+//#region ../functions/src/max-rects-compat.ts
+const NO_ROTATION = 2;
+const MAX_SCORE = 2147483647;
+const MAX_RECTS_METHOD = {
+	BestShortSideFit: 0,
+	BestLongSideFit: 1,
+	BestAreaFit: 2,
+	BottomLeftRule: 3,
+	ContactPointRule: 4
+};
+const COMPAT_NODE_RECT_FLAGS = {
+	DUPLICATE_PADDING: 1,
+	NO_ROTATION
+};
+var MaxRectsCompat = class MaxRectsCompat {
+	static helperRect = createNodeRect();
+	binWidth = 0;
+	binHeight = 0;
+	allowRotations = false;
+	usedRectangles = [];
+	freeRectangles = [];
+	init(width, height, allowRotations = false) {
+		this.binWidth = width;
+		this.binHeight = height;
+		this.allowRotations = allowRotations;
+		this.usedRectangles.length = 0;
+		this.freeRectangles.length = 0;
+		this.freeRectangles.push({
+			...createNodeRect(),
+			x: 0,
+			y: 0,
+			width,
+			height
+		});
+	}
+	insert(rect, method) {
+		const newNode = this.scoreRect(rect, method);
+		if (newNode.height === 0) return null;
+		const placed = cloneNodeRect(newNode);
+		this.placeRect(placed);
+		return placed;
+	}
+	pack(rects, method) {
+		const remaining = rects.map(cloneNodeRect);
+		while (remaining.length > 0) {
+			let bestIndex = -1;
+			const bestNode = createNodeRect();
+			bestNode.score1 = MAX_SCORE;
+			bestNode.score2 = MAX_SCORE;
+			for (let index = 0; index < remaining.length; index += 1) {
+				const candidate = this.scoreRect(remaining[index], method);
+				if (candidate.score1 < bestNode.score1 || candidate.score1 === bestNode.score1 && candidate.score2 < bestNode.score2) {
+					copyNodeRect(bestNode, candidate);
+					bestIndex = index;
 				}
 			}
 			if (bestIndex === -1) break;
@@ -21707,6 +21762,19 @@ const ATLAS_DEFAULTS = {
 function getPublishedItemId(resource) {
 	return (resource.getExtras() ?? {})._publishedId ?? resource.getId();
 }
+function getSelectedSkeletonDependencyImageIds(resources) {
+	const imageIds = /* @__PURE__ */ new Set();
+	const resourcesById = new Map(resources.map((resource) => [resource.getId(), resource]));
+	for (const resource of resources) {
+		if (!isSkeletonResource$1(resource)) continue;
+		for (const requiredId of resource.getRequireIds()) {
+			if (!requiredId) continue;
+			const required = resourcesById.get(requiredId);
+			if (required && isImageResource$1(required)) imageIds.add(requiredId);
+		}
+	}
+	return imageIds;
+}
 function resolveFontFileName(fontName) {
 	return /\.fnt$/i.test(fontName) ? fontName : `${fontName}.fnt`;
 }
@@ -21843,12 +21911,18 @@ function atlas(_options = {}) {
 		const logger = doc.getLogger();
 		const encoder = options.encoder;
 		const doTrim = options.trimImage && !!encoder && !!options.basePath;
+		const packageFilter = options.packages ? new Set(options.packages) : null;
 		for (const pkg of root.listPackages()) {
+			if (packageFilter && !packageFilter.has(pkg.getName())) continue;
 			const selectedPublishIds = new Set((pkg.getExtras() ?? {}).publishedResourceIds ?? []);
 			const allResources = selectedPublishIds.size > 0 ? pkg.listResources().filter((resource) => selectedPublishIds.has(resource.getId())) : pkg.listResources();
+			const skeletonDependencyImageIds = getSelectedSkeletonDependencyImageIds(allResources);
 			const orderedResources = await resolveEditorCompatibleResourceOrder(pkg, allResources, options);
 			const orderedAllResources = sortResourcesByOrder(allResources, new Map(orderedResources.map((resource, index) => [resource.getId(), index])), new Map(allResources.map((resource, index) => [resource.getId(), index])));
-			if (!allResources.some((resource) => isPackableResource(resource))) continue;
+			if (!allResources.some((resource) => {
+				if (isImageResource$1(resource) && skeletonDependencyImageIds.has(resource.getId())) return false;
+				return isPackableResource(resource);
+			})) continue;
 			const inputs = [];
 			const referencedIds = /* @__PURE__ */ new Set();
 			const resourceMap = /* @__PURE__ */ new Map();
@@ -21917,6 +21991,7 @@ function atlas(_options = {}) {
 			}
 			for (const res of orderedAllResources) if (isImageResource$1(res)) {
 				const resId = res.getId();
+				if (skeletonDependencyImageIds.has(resId)) continue;
 				if (selectedPublishIds.size === 0 && !res.getExported() && referencedIds.size > 0 && !referencedIds.has(resId)) continue;
 				await _collectImage(res, pkg, inputs, encoder, options, doTrim, logger);
 			} else if (isMovieClipResource$1(res)) {
@@ -21929,137 +22004,59 @@ function atlas(_options = {}) {
 				await _collectFontTexture(doc, res, pkg, options);
 			}
 			if (inputs.length === 0) continue;
-			const branchGroups = buildBranchAtlasGroups(doc, inputs, options);
 			let totalPageCount = 0;
 			let usedDirectOutput = false;
+			const { autoInputs, fixedPageGroups, standaloneGroups, reservedPageIndexes } = groupStandaloneInputs(doc, inputs, options);
+			const branchGroups = buildBranchAtlasGroups(doc, autoInputs, options);
+			const branchPageOffsets = /* @__PURE__ */ new Map();
 			for (const group of branchGroups) {
-				const directOutput = resolveDirectImageOutput(group.inputs, options);
+				const directOutput = fixedPageGroups.length === 0 && standaloneGroups.length === 0 ? resolveDirectImageOutput(group.inputs, options) : null;
 				if (directOutput) {
 					await emitDirectImageOutput(doc, pkg, directOutput, encoder, options, logger, group.branchName, group.branchOrdinal);
 					usedDirectOutput = true;
 					totalPageCount += 1;
 					continue;
 				}
-				const hasDuplicatePadding = group.inputs.some((i) => {
-					return isImageResource$1(i.resource) && i.resource.getDuplicatePadding?.() === true;
+				const pageStart = reserveAutoPageStart(branchPageOffsets, group.branchOrdinal, reservedPageIndexes);
+				const emittedPageCount = await emitPagedAtlasGroup(doc, pkg, allResources, group.inputs, {
+					branchName: group.branchName,
+					branchOrdinal: group.branchOrdinal,
+					pageStart,
+					fileNameAt: (pageIndex) => resolveAtlasOutputFileName(pkg, pageIndex, group.branchName),
+					options,
+					encoder,
+					logger
 				});
-				const pages = new MaxRectsPackerCompat({
-					pot: options.powerOfTwo,
-					mof: !options.powerOfTwo,
-					padding: options.padding,
-					rotation: options.allowRotation,
-					minWidth: 16,
-					minHeight: 16,
-					maxWidth: options.maxSize,
-					maxHeight: options.maxSize,
-					square: options.square,
-					fast: options.fast,
-					edgePadding: false,
-					duplicatePadding: hasDuplicatePadding,
-					multiPage: options.multiPage,
-					preserveInputOrderOnTie: options.preserveInputOrderOnTie
-				}).pack(group.inputs.map((input, index) => inputToCompatRect(input, index)));
-				if (!pages || pages.length === 0) continue;
-				totalPageCount += pages.length;
-				for (let p = 0; p < pages.length; p++) {
-					const page = pages[p];
-					const atlasNode = doc.createAtlas(`atlas${resolveAtlasIndex(group.branchOrdinal, p)}`);
-					atlasNode.setIndex(resolveAtlasIndex(group.branchOrdinal, p));
-					atlasNode.setFile(resolveAtlasOutputFileName(pkg, p, group.branchName));
-					atlasNode.setWidth(page.width);
-					atlasNode.setHeight(page.height);
-					pkg.addAtlas(atlasNode);
-					for (const pr of page.outputRects) {
-						const input = group.inputs[pr.index];
-						if (!input) continue;
-						const packedSize = resolvePackedRectSize(input, pr.width, pr.height, pr.rotated);
-						const rotated = pr.rotated;
-						const sprite = doc.createSprite();
-						sprite.setItemId(input.id);
-						sprite.setRectX(pr.x);
-						sprite.setRectY(pr.y);
-						sprite.setRectWidth(packedSize.width);
-						sprite.setRectHeight(packedSize.height);
-						sprite.setRotated(rotated);
-						sprite.setOffsetX(input.offsetX);
-						sprite.setOffsetY(input.offsetY);
-						sprite.setOriginalWidth(input.originalWidth);
-						sprite.setOriginalHeight(input.originalHeight);
-						sprite.setAtlas(atlasNode);
-						atlasNode.addSprite(sprite);
-					}
-					for (const res of allResources) {
-						if (!isFontResource$1(res)) continue;
-						const alias = res.getExtras()?._fontSpriteAlias;
-						if (!alias) continue;
-						const imgSprite = page.outputRects.find((result) => group.inputs[result.index]?.id === alias.textureId);
-						if (!imgSprite) continue;
-						const imgInput = group.inputs[imgSprite.index];
-						const fontSprite = doc.createSprite();
-						fontSprite.setItemId(alias.fontId);
-						fontSprite.setRectX(imgSprite.x);
-						fontSprite.setRectY(imgSprite.y);
-						fontSprite.setRectWidth(imgSprite.width);
-						fontSprite.setRectHeight(imgSprite.height);
-						fontSprite.setRotated(imgSprite.rotated);
-						if (imgInput) {
-							fontSprite.setOffsetX(imgInput.offsetX);
-							fontSprite.setOffsetY(imgInput.offsetY);
-							fontSprite.setOriginalWidth(imgInput.originalWidth);
-							fontSprite.setOriginalHeight(imgInput.originalHeight);
-						}
-						fontSprite.setAtlas(atlasNode);
-						atlasNode.addSprite(fontSprite);
-					}
-				}
-				if (encoder && options.outputPath) {
-					if (options.mkdir) await options.mkdir(options.outputPath);
-					for (let p = 0; p < pages.length; p++) {
-						const page = pages[p];
-						const compositeInputs = [];
-						for (const pr of page.outputRects) {
-							const input = group.inputs[pr.index];
-							if (!input) continue;
-							if (pr.width <= 0 || pr.height <= 0 || input.width <= 0 || input.height <= 0) continue;
-							try {
-								let imgBuffer;
-								if (input.trimBuffer) {
-									imgBuffer = input.trimBuffer;
-									if (imgBuffer.length === 0) continue;
-								} else if (input.rasterizedBuffer) imgBuffer = input.rasterizedBuffer;
-								else {
-									if (!isImageResource$1(input.resource)) {
-										logger.warn(`atlas: Non-image input "${input.id}" is missing inline buffer, skipping compositing.`);
-										continue;
-									}
-									imgBuffer = await encoder(_resolveImagePath(input.resource, pkg, options.basePath)).toBuffer();
-								}
-								if (pr.rotated) imgBuffer = await encoder(imgBuffer).rotate(270).toBuffer();
-								compositeInputs.push({
-									input: imgBuffer,
-									left: pr.x,
-									top: pr.y
-								});
-							} catch {
-								logger.warn(`atlas: Could not read image "${input.id}" for compositing.`);
-							}
-						}
-						const atlasFileName = resolveAtlasOutputFileName(pkg, p, group.branchName);
-						const outputFile = `${options.outputPath}/${atlasFileName}`;
-						await encoder({ create: {
-							width: page.width,
-							height: page.height,
-							channels: 4,
-							background: {
-								r: 0,
-								g: 0,
-								b: 0,
-								alpha: 0
-							}
-						} }).composite(compositeInputs).png().toFile(outputFile);
-						logger.info(`atlas: Generated ${atlasFileName} (${page.width}x${page.height}, ${page.outputRects.length} sprites)`);
-					}
-				}
+				totalPageCount += emittedPageCount;
+				branchPageOffsets.set(group.branchOrdinal, pageStart + emittedPageCount);
+			}
+			for (const group of fixedPageGroups) {
+				const emittedPageCount = await emitPagedAtlasGroup(doc, pkg, allResources, group.inputs, {
+					branchName: group.branchName,
+					branchOrdinal: group.branchOrdinal,
+					pageStart: group.pageIndex,
+					forceSinglePage: true,
+					fileNameAt: () => resolveAtlasOutputFileName(pkg, group.pageIndex, group.branchName),
+					options,
+					encoder,
+					logger
+				});
+				totalPageCount += emittedPageCount;
+			}
+			const standalonePageOffsets = new Map(branchPageOffsets);
+			for (const group of fixedPageGroups) {
+				const nextPageIndex = group.pageIndex + 1;
+				if (nextPageIndex > (standalonePageOffsets.get(group.branchOrdinal) ?? 0)) standalonePageOffsets.set(group.branchOrdinal, nextPageIndex);
+			}
+			for (const group of standaloneGroups) {
+				const emittedPageCount = await emitStandaloneAtlasGroup(doc, pkg, group, {
+					atlasIndexStart: standalonePageOffsets.get(group.branchOrdinal) ?? 0,
+					options,
+					encoder,
+					logger
+				});
+				totalPageCount += emittedPageCount;
+				standalonePageOffsets.set(group.branchOrdinal, (standalonePageOffsets.get(group.branchOrdinal) ?? 0) + emittedPageCount);
 			}
 			if (usedDirectOutput) logger.info(`atlas: Direct output for single image package "${pkg.getName()}".`);
 			logger.info(`atlas: Packed ${inputs.length} images into ${totalPageCount} atlas(es) for package "${pkg.getName()}".`);
@@ -22096,6 +22093,171 @@ function buildBranchAtlasGroups(doc, inputs, options) {
 		inputs: groups.get(branchName) ?? []
 	}));
 }
+function reserveAutoPageStart(branchPageOffsets, branchOrdinal, reservedPageIndexes) {
+	let pageIndex = branchPageOffsets.get(branchOrdinal) ?? 0;
+	while (branchOrdinal === 0 && reservedPageIndexes.has(pageIndex)) pageIndex += 1;
+	return pageIndex;
+}
+async function emitPagedAtlasGroup(doc, pkg, allResources, inputs, context) {
+	if (inputs.length === 0) return 0;
+	const pages = packAtlasPages(inputs, context.options, context.forceSinglePage === true);
+	if (pages.length === 0) return 0;
+	for (let pageOffset = 0; pageOffset < pages.length; pageOffset += 1) {
+		const page = pages[pageOffset];
+		const pageIndex = context.pageStart + pageOffset;
+		const atlasNode = doc.createAtlas(`atlas${resolveAtlasIndex(context.branchOrdinal, pageIndex)}`);
+		atlasNode.setIndex(resolveAtlasIndex(context.branchOrdinal, pageIndex));
+		atlasNode.setFile(context.fileNameAt(pageIndex));
+		atlasNode.setWidth(page.width);
+		atlasNode.setHeight(page.height);
+		pkg.addAtlas(atlasNode);
+		attachSpritesToAtlas(doc, allResources, inputs, page.outputRects, atlasNode);
+		await writeAtlasPageImage(pkg, inputs, page, atlasNode.getFile(), context.encoder, context.options, context.logger);
+	}
+	return pages.length;
+}
+async function emitStandaloneAtlasGroup(doc, pkg, group, context) {
+	if (group.inputs.length === 0) return 0;
+	const pages = packAtlasPages(group.inputs, context.options, true, group.sizeMode === "npot" ? {
+		powerOfTwo: false,
+		multipleOfFour: false,
+		square: false
+	} : group.sizeMode === "multipleOf4" ? {
+		powerOfTwo: false,
+		multipleOfFour: true,
+		square: false
+	} : void 0);
+	if (pages.length === 0) return 0;
+	for (let pageOffset = 0; pageOffset < pages.length; pageOffset += 1) {
+		const page = pages[pageOffset];
+		const baseFileName = resolveStandaloneAtlasOutputFileName(pkg, group.resource, group.branchName);
+		const atlasFileName = pages.length <= 1 ? baseFileName : insertFileNameSuffix(baseFileName, `_${pageOffset}`);
+		const atlasIndex = context.atlasIndexStart + pageOffset;
+		const atlasNode = doc.createAtlas(`atlas${resolveAtlasIndex(group.branchOrdinal, atlasIndex)}`);
+		atlasNode.setIndex(resolveAtlasIndex(group.branchOrdinal, atlasIndex));
+		atlasNode.setFile(atlasFileName);
+		const standaloneSize = resolveStandaloneAtlasSize(page.width, page.height, group.sizeMode, context.options);
+		atlasNode.setWidth(standaloneSize.width);
+		atlasNode.setHeight(standaloneSize.height);
+		pkg.addAtlas(atlasNode);
+		attachSpritesToAtlas(doc, [], group.inputs, page.outputRects, atlasNode);
+		await writeAtlasPageImage(pkg, group.inputs, {
+			...page,
+			width: standaloneSize.width,
+			height: standaloneSize.height
+		}, atlasFileName, context.encoder, context.options, context.logger);
+	}
+	return pages.length;
+}
+function packAtlasPages(inputs, options, forceSinglePage, sizeOverrides) {
+	const hasDuplicatePadding = inputs.some((input) => {
+		return isImageResource$1(input.resource) && input.resource.getDuplicatePadding?.() === true;
+	});
+	return new MaxRectsPackerCompat({
+		pot: sizeOverrides?.powerOfTwo ?? options.powerOfTwo,
+		mof: sizeOverrides?.multipleOfFour ?? !options.powerOfTwo,
+		padding: options.padding,
+		rotation: options.allowRotation,
+		minWidth: 16,
+		minHeight: 16,
+		maxWidth: options.maxSize,
+		maxHeight: options.maxSize,
+		square: sizeOverrides?.square ?? options.square,
+		fast: options.fast,
+		edgePadding: false,
+		duplicatePadding: hasDuplicatePadding,
+		multiPage: forceSinglePage ? false : options.multiPage,
+		preserveInputOrderOnTie: options.preserveInputOrderOnTie
+	}).pack(inputs.map((input, index) => inputToCompatRect(input, index))) ?? [];
+}
+function attachSpritesToAtlas(doc, allResources, inputs, outputRects, atlasNode) {
+	for (const packedRect of outputRects) {
+		const input = inputs[packedRect.index];
+		if (!input) continue;
+		const packedSize = resolvePackedRectSize(input, packedRect.width, packedRect.height, packedRect.rotated);
+		const sprite = doc.createSprite();
+		sprite.setItemId(input.id);
+		sprite.setRectX(packedRect.x);
+		sprite.setRectY(packedRect.y);
+		sprite.setRectWidth(packedSize.width);
+		sprite.setRectHeight(packedSize.height);
+		sprite.setRotated(packedRect.rotated);
+		sprite.setOffsetX(input.offsetX);
+		sprite.setOffsetY(input.offsetY);
+		sprite.setOriginalWidth(input.originalWidth);
+		sprite.setOriginalHeight(input.originalHeight);
+		sprite.setAtlas(atlasNode);
+		atlasNode.addSprite(sprite);
+	}
+	for (const resource of allResources) {
+		if (!isFontResource$1(resource)) continue;
+		const alias = resource.getExtras()?._fontSpriteAlias;
+		if (!alias) continue;
+		const imageSprite = outputRects.find((result) => inputs[result.index]?.id === alias.textureId);
+		if (!imageSprite) continue;
+		const imageInput = inputs[imageSprite.index];
+		const fontSprite = doc.createSprite();
+		fontSprite.setItemId(alias.fontId);
+		fontSprite.setRectX(imageSprite.x);
+		fontSprite.setRectY(imageSprite.y);
+		fontSprite.setRectWidth(imageSprite.width);
+		fontSprite.setRectHeight(imageSprite.height);
+		fontSprite.setRotated(imageSprite.rotated);
+		if (imageInput) {
+			fontSprite.setOffsetX(imageInput.offsetX);
+			fontSprite.setOffsetY(imageInput.offsetY);
+			fontSprite.setOriginalWidth(imageInput.originalWidth);
+			fontSprite.setOriginalHeight(imageInput.originalHeight);
+		}
+		fontSprite.setAtlas(atlasNode);
+		atlasNode.addSprite(fontSprite);
+	}
+}
+async function writeAtlasPageImage(pkg, inputs, page, atlasFileName, encoder, options, logger) {
+	if (!encoder || !options.outputPath) return;
+	if (options.mkdir) await options.mkdir(options.outputPath);
+	const compositeInputs = [];
+	for (const packedRect of page.outputRects) {
+		const input = inputs[packedRect.index];
+		if (!input) continue;
+		if (packedRect.width <= 0 || packedRect.height <= 0 || input.width <= 0 || input.height <= 0) continue;
+		try {
+			let imageBuffer;
+			if (input.trimBuffer) {
+				imageBuffer = input.trimBuffer;
+				if (imageBuffer.length === 0) continue;
+			} else if (input.rasterizedBuffer) imageBuffer = input.rasterizedBuffer;
+			else {
+				if (!isImageResource$1(input.resource)) {
+					logger.warn(`atlas: Non-image input "${input.id}" is missing inline buffer, skipping compositing.`);
+					continue;
+				}
+				imageBuffer = await encoder(_resolveImagePath(input.resource, pkg, options.basePath)).toBuffer();
+			}
+			if (packedRect.rotated) imageBuffer = await encoder(imageBuffer).rotate(270).toBuffer();
+			compositeInputs.push({
+				input: imageBuffer,
+				left: packedRect.x,
+				top: packedRect.y
+			});
+		} catch {
+			logger.warn(`atlas: Could not read image "${input.id}" for compositing.`);
+		}
+	}
+	const outputFile = `${options.outputPath}/${atlasFileName}`;
+	await encoder({ create: {
+		width: page.width,
+		height: page.height,
+		channels: 4,
+		background: {
+			r: 0,
+			g: 0,
+			b: 0,
+			alpha: 0
+		}
+	} }).composite(compositeInputs).toFile(outputFile);
+	logger.info(`atlas: Generated ${atlasFileName} (${page.width}x${page.height}, ${page.outputRects.length} sprites)`);
+}
 function inputToCompatRect(input, index) {
 	const duplicatePadding = isImageResource$1(input.resource) && input.resource.getDuplicatePadding?.() === true;
 	return {
@@ -22210,14 +22372,47 @@ function resolveAtlasOutputFileName(pkg, pageIndex, branchName) {
 	const suffix = branchName ? `_${branchName}` : "";
 	return `${pkg.getPublishName() || pkg.getName()}_atlas${pageIndex}${suffix}.png`;
 }
+function resolveStandaloneAtlasOutputFileName(pkg, resource, branchName) {
+	const baseName = `${pkg.getPublishName() || pkg.getName()}_atlas_${getPublishedItemId(resource)}`;
+	const suffix = branchName ? `_${branchName}` : "";
+	if (isImageResource$1(resource)) return `${baseName}${suffix}${extname$1(resolveImageFileName$1(resource)) || ".png"}`;
+	return `${baseName}${suffix}.png`;
+}
+function resolveStandaloneAtlasSize(width, height, sizeMode, options) {
+	if (sizeMode === "npot") return {
+		width,
+		height
+	};
+	if (sizeMode === "multipleOf4") return {
+		width: roundUpToMultiple(width, 4),
+		height: roundUpToMultiple(height, 4)
+	};
+	return resolveDirectOutputAtlasSize(width, height, options);
+}
 function resolveImageFileName$1(resource) {
 	const extras = resource.getExtras();
 	return resource.getFileName() || extras._fileName || resource.getName();
 }
+function extname$1(fileName) {
+	const normalized = fileName.replace(/\\/g, "/");
+	const lastSlash = normalized.lastIndexOf("/");
+	const lastDot = normalized.lastIndexOf(".");
+	if (lastDot <= lastSlash) return "";
+	return normalized.slice(lastDot);
+}
+function insertFileNameSuffix(fileName, suffix) {
+	const extension = extname$1(fileName);
+	if (!extension) return `${fileName}${suffix}`;
+	return `${fileName.slice(0, -extension.length)}${suffix}${extension}`;
+}
 function nextPow2(value) {
 	if (value <= 1) return 1;
 	return 2 ** Math.ceil(Math.log2(value));
 }
+function roundUpToMultiple(value, base) {
+	if (value <= 0) return 0;
+	return Math.ceil(value / base) * base;
+}
 function sortResourcesByOrder(resources, orderMap, inputOrderMap) {
 	const ordered = [...resources];
 	ordered.sort((left, right) => {
@@ -22233,6 +22428,63 @@ function sortResourcesByOrder(resources, orderMap, inputOrderMap) {
 	});
 	return ordered;
 }
+function getResourceTextureSetMode(resource) {
+	if (isImageResource$1(resource)) return parseTextureSetMode(resource.getTextureSetMode?.());
+	return parseTextureSetMode(resource.getTextureSetMode?.());
+}
+function groupStandaloneInputs(doc, inputs, options) {
+	const autoInputs = [];
+	const fixedInputsByPage = /* @__PURE__ */ new Map();
+	const standaloneGroups = /* @__PURE__ */ new Map();
+	const reservedPageIndexes = /* @__PURE__ */ new Set();
+	const discoveredBranchNames = [...new Set(inputs.map((input) => getInputBranchName(input)).filter((branchName) => !!branchName))];
+	const orderedBranchNames = doc.getRoot().listBranches().filter((branchName) => discoveredBranchNames.includes(branchName));
+	for (const branchName of discoveredBranchNames) if (!orderedBranchNames.includes(branchName)) orderedBranchNames.push(branchName);
+	const branchOrdinalByName = /* @__PURE__ */ new Map();
+	branchOrdinalByName.set("", 0);
+	if (options.separatedAtlasForBranch) {
+		let ordinal = 1;
+		for (const branchName of orderedBranchNames) branchOrdinalByName.set(branchName, ordinal++);
+	} else for (const branchName of orderedBranchNames) branchOrdinalByName.set(branchName, 0);
+	for (const input of inputs) {
+		const branchName = getInputBranchName(input);
+		const branchOrdinal = branchOrdinalByName.get(branchName) ?? 0;
+		const mode = getResourceTextureSetMode(input.resource);
+		if (mode.kind === "standalone") {
+			const key = `${branchName}\u0000${getPublishedItemId(input.resource)}`;
+			const existing = standaloneGroups.get(key);
+			if (existing) existing.inputs.push(input);
+			else standaloneGroups.set(key, {
+				resource: input.resource,
+				branchName,
+				branchOrdinal,
+				sizeMode: mode.sizeMode,
+				inputs: [input]
+			});
+			continue;
+		}
+		if (mode.kind === "page") {
+			reservedPageIndexes.add(mode.pageIndex);
+			const key = `${branchName}\u0000${mode.pageIndex}`;
+			const existing = fixedInputsByPage.get(key);
+			if (existing) existing.inputs.push(input);
+			else fixedInputsByPage.set(key, {
+				pageIndex: mode.pageIndex,
+				branchName,
+				branchOrdinal,
+				inputs: [input]
+			});
+			continue;
+		}
+		autoInputs.push(input);
+	}
+	return {
+		autoInputs,
+		fixedPageGroups: [...fixedInputsByPage.values()].sort((left, right) => left.branchOrdinal - right.branchOrdinal || left.pageIndex - right.pageIndex),
+		standaloneGroups: [...standaloneGroups.values()].sort((left, right) => left.branchOrdinal - right.branchOrdinal || getPublishedItemId(left.resource).localeCompare(getPublishedItemId(right.resource))),
+		reservedPageIndexes
+	};
+}
 /**
 * Trim transparent edges from an image using sharp.
 * Returns the trimmed buffer, dimensions, and offsets.
@@ -22793,6 +23045,62 @@ const FGUI_TYPESCRIPT_BINDER_TEMPLATE = `{{generatedMark}}
 }
 `;
 //#endregion
+//#region ../functions/src/plugins/loader.ts
+const importNative = new Function("id", "return import(id)");
+async function loadPlugins(doc, pluginsDir) {
+	if (!pluginsDir) return [];
+	const fs = await importNative("node:fs/promises");
+	const path = await importNative("node:path");
+	let entries;
+	try {
+		entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const plugins = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const pluginDir = path.join(pluginsDir, entry.name);
+		try {
+			const manifest = await readPluginManifest(fs, path, pluginDir);
+			if (!manifest) continue;
+			const plugin = await loadPlugin(resolvePluginMain(path, pluginDir, manifest));
+			plugins.push({
+				name: manifest.name,
+				plugin
+			});
+		} catch (error) {
+			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+		}
+	}
+	return plugins;
+}
+function formatPluginError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+async function readPluginManifest(fs, path, pluginDir) {
+	const manifestPath = path.join(pluginDir, "package.json");
+	const content = await fs.readFile(manifestPath, "utf-8");
+	const manifest = JSON.parse(content);
+	if (!manifest.name) throw new Error(`Codegen plugin at ${pluginDir} is missing package.json name.`);
+	if (!manifest.main) throw new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
+	return manifest;
+}
+function resolvePluginMain(path, pluginDir, manifest) {
+	const mainPath = path.resolve(pluginDir, manifest.main);
+	const relative = path.relative(pluginDir, mainPath);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Codegen plugin "${manifest.name}" main must resolve inside its plugin directory.`);
+	return mainPath;
+}
+async function loadPlugin(mainPath) {
+	const mod = await createJiti(import.meta.url).import(mainPath);
+	const defaultExport = mod.default;
+	return isObject(defaultExport) ? defaultExport : mod;
+}
+function isObject(value) {
+	return value !== null && typeof value === "object";
+}
+//#endregion
 //#region ../functions/src/codegen.ts
 const AUTO_GENERATED_CODE_MARK = "/** This is an automatically generated class by FairyGUI. Please do not modify it. **/";
 const DEFAULT_CLASS_NAME_PREFIX = "UI_";
@@ -22828,6 +23136,18 @@ async function publishCodeGeneration(doc, options) {
 	const logger = doc.getLogger();
 	const settings = resolveCodeGenerationSettings(doc);
 	if (!settings.allowGenCode) return;
+	const plugins = options.plugins?.filter((plugin) => typeof plugin.plugin.genCode === "function") ?? [];
+	if (plugins.length > 0) {
+		let handled = false;
+		for (const plugin of plugins) try {
+			await plugin.plugin.genCode(doc, settings, options);
+			handled = true;
+			logger.info(`publish: Generated code using plugin "${plugin.name}"`);
+		} catch (error) {
+			logger.warn(`publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`);
+		}
+		if (handled) return;
+	}
 	for (const pkg of options.packages) {
 		if (!pkg.getGenCode()) continue;
 		const plan = resolvePackageCodegenPlan(pkg, settings, options);
@@ -22926,9 +23246,9 @@ async function cleanupGeneratedFiles(directory, fs, extension = ".cs") {
 	}
 }
 function buildCodegenClasses(doc, pkg, plan) {
-	const exportedComponents = pkg.listComponents().filter((component) => component.getExported()).sort((left, right) => left.getId().localeCompare(right.getId()));
+	const codegenComponents = pkg.listComponents().sort((left, right) => left.getId().localeCompare(right.getId()));
 	const generatedById = /* @__PURE__ */ new Map();
-	for (const component of exportedComponents) {
+	for (const component of codegenComponents) {
 		const encodedClassName = `${plan.settings.classNamePrefix}${normalizeTypeName(component.getName()) || "Component"}`;
 		generatedById.set(component.getId(), {
 			classId: component.getId(),
@@ -22941,7 +23261,13 @@ function buildCodegenClasses(doc, pkg, plan) {
 			members: []
 		});
 	}
-	for (const component of exportedComponents) {
+	for (const component of codegenComponents) {
+		const classInfo = generatedById.get(component.getId());
+		if (!classInfo) continue;
+		classInfo.members = buildCodegenMembers(doc, pkg, component, plan, generatedById);
+	}
+	for (const [componentId, classInfo] of generatedById) if (classInfo.members.every((member) => member.ignored)) generatedById.delete(componentId);
+	for (const component of codegenComponents) {
 		const classInfo = generatedById.get(component.getId());
 		if (!classInfo) continue;
 		classInfo.members = buildCodegenMembers(doc, pkg, component, plan, generatedById);
@@ -22955,7 +23281,12 @@ function buildCodegenMembers(doc, pkg, component, plan, generatedById) {
 	let childIndex = 0;
 	let transitionIndex = 0;
 	for (const controller of component.listControllers()) members.push(createMember(ownerType, "controller", "Controller", controller.getName(), controllerIndex++, plan));
-	for (const child of component.listChildren()) members.push(createMember(ownerType, "child", resolveChildType(doc, pkg, child, generatedById), child.getName(), childIndex++, plan));
+	for (const child of component.listChildren()) {
+		if (!isRuntimeChild(child)) continue;
+		const index = childIndex++;
+		const resolvedChild = resolveChildType(doc, pkg, child, generatedById);
+		members.push(createMember(ownerType, "child", resolvedChild.type, child.getName(), index, plan, resolvedChild.referencedComponent));
+	}
 	for (const transition of component.listTransitions()) members.push(createMember(ownerType, "transition", "Transition", transition.getName(), transitionIndex++, plan));
 	const usedNames = /* @__PURE__ */ new Map();
 	for (const member of members) {
@@ -22967,7 +23298,10 @@ function buildCodegenMembers(doc, pkg, component, plan, generatedById) {
 	}
 	return members;
 }
-function createMember(ownerType, kind, type, originalName, index, plan) {
+function isRuntimeChild(child) {
+	return child.propertyType !== "GGroup" || child.getAdvanced?.() === true;
+}
+function createMember(ownerType, kind, type, originalName, index, plan, referencedComponent) {
 	const ignored = plan.settings.ignoreNoname && isDefaultMemberName(ownerType, kind, originalName);
 	return {
 		index,
@@ -22975,30 +23309,41 @@ function createMember(ownerType, kind, type, originalName, index, plan) {
 		name: applyMemberNamePrefix(originalName, plan.settings.memberNamePrefix),
 		originalName,
 		type,
-		ignored
+		ignored,
+		referencedComponent
 	};
 }
 function resolveChildType(doc, pkg, child, generatedById) {
 	const src = child.getSrc?.();
 	if (src) {
-		const localResource = resolveChildSourceComponent(doc, pkg, src);
-		if (localResource) return generatedById.get(localResource.getId())?.encodedClassName ?? resolveComponentBaseType(localResource);
+		let referencedComponent = null;
+		if (src.startsWith("ui://")) {
+			const rest = src.slice(5);
+			const pkgId = rest.slice(0, 8);
+			const resourceId = rest.slice(8);
+			const targetPackage = doc.getRoot().listPackages().find((candidate) => candidate.getId() === pkgId);
+			const targetResource = targetPackage?.getResourceById(resourceId);
+			if (targetPackage && targetResource?.propertyType === "Component") referencedComponent = {
+				component: targetResource,
+				package: targetPackage
+			};
+		} else {
+			const packageId = child.getPackageId?.();
+			const targetPackage = packageId ? doc.getRoot().listPackages().find((candidate) => candidate.getId() === packageId) : pkg;
+			const targetResource = targetPackage?.getResourceById(src);
+			if (targetPackage && targetResource?.propertyType === "Component") referencedComponent = {
+				component: targetResource,
+				package: targetPackage
+			};
+		}
+		if (referencedComponent) return {
+			type: (referencedComponent.package === pkg ? generatedById.get(referencedComponent.component.getId()) : void 0)?.encodedClassName ?? resolveComponentBaseType(referencedComponent.component),
+			referencedComponent
+		};
 	}
 	const instanceExtType = child.getInstanceExtType?.();
-	if (instanceExtType) return `G${instanceExtType}`;
-	return child.propertyType;
-}
-function resolveChildSourceComponent(doc, pkg, src) {
-	if (!src) return null;
-	if (src.startsWith("ui://")) {
-		const rest = src.slice(5);
-		const pkgId = rest.slice(0, 8);
-		const resourceId = rest.slice(8);
-		const targetResource = doc.getRoot().listPackages().find((candidate) => candidate.getId() === pkgId)?.getResourceById(resourceId);
-		return targetResource?.propertyType === "Component" ? targetResource : null;
-	}
-	const localResource = pkg.getResourceById(src);
-	return localResource?.propertyType === "Component" ? localResource : null;
+	if (instanceExtType) return { type: `G${instanceExtType}` };
+	return { type: child.propertyType };
 }
 function resolveComponentBaseType(component) {
 	const extensionType = component.getExtensionType();
@@ -23069,21 +23414,21 @@ function renderFguiTypescriptMemberAssignment(member, getMemberByName, variant)
 	return getMemberByName ? `\t\tthis.${member.name} = <${translatedType}><any>(this.getChild("${escapeTypeScriptString(member.originalName)}"));` : `\t\tthis.${member.name} = <${translatedType}><any>(this.getChildAt(${member.index}));`;
 }
 function resolveCodePath(codePath, basePath, fs) {
-	if (isAbsolutePath(codePath)) return trimTrailingSlashes$1(codePath);
+	if (isAbsolutePath(codePath)) return trimTrailingSlashes$2(codePath);
 	const projectBasePath = resolveProjectBasePath(basePath);
-	return projectBasePath ? trimTrailingSlashes$1(fs.join(projectBasePath, codePath)) : trimTrailingSlashes$1(codePath);
+	return projectBasePath ? trimTrailingSlashes$2(fs.join(projectBasePath, codePath)) : trimTrailingSlashes$2(codePath);
 }
 function resolveProjectBasePath(basePath) {
 	if (!basePath) return "";
-	const normalized = trimTrailingSlashes$1(basePath);
+	const normalized = trimTrailingSlashes$2(basePath);
 	const assetsMatch = normalized.match(/^(.*)[/\\]assets(?:_[^/\\]+)?$/i);
 	if (assetsMatch?.[1]) return assetsMatch[1];
 	return dirname$2(normalized);
 }
 function dirname$2(filePath) {
-	return trimTrailingSlashes$1(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
+	return trimTrailingSlashes$2(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
 }
-function trimTrailingSlashes$1(value) {
+function trimTrailingSlashes$2(value) {
 	return value.replace(/[/\\]+$/, "");
 }
 function isAbsolutePath(value) {
@@ -23092,9 +23437,15 @@ function isAbsolutePath(value) {
 function isDefaultMemberName(ownerType, kind, name) {
 	if (kind === "controller") return (ownerType === "GButton" || ownerType === "GComboBox") && name === "button";
 	if (kind === "transition") return false;
-	if (ownerType === "GButton" || ownerType === "GLabel" || ownerType === "GComboBox") return name === "title" || name === "icon";
-	if (ownerType === "GProgressBar") return name === "bar" || name === "bar_v" || name === "title" || name === "ani";
-	if (ownerType === "GSlider") return name === "bar" || name === "bar_v" || name === "grip" || name === "title" || name === "ani";
+	if (ownerType === "GButton" || ownerType === "GLabel" || ownerType === "GComboBox") {
+		if (name === "title" || name === "icon") return true;
+	}
+	if (ownerType === "GProgressBar") {
+		if (name === "bar" || name === "bar_v" || name === "title" || name === "ani") return true;
+	}
+	if (ownerType === "GSlider") {
+		if (name === "bar" || name === "bar_v" || name === "grip" || name === "title" || name === "ani") return true;
+	}
 	return /^n\d+(?:_.*)?$/i.test(name);
 }
 function applyMemberNamePrefix(name, prefix) {
@@ -23383,11 +23734,11 @@ function inferPackageName(fileName) {
 	if (/\.fui$/i.test(fileName)) return fileName.replace(/\.fui$/i, "");
 	return fileName.replace(/\.bin$/i, "");
 }
-function trimTrailingSlashes(value) {
+function trimTrailingSlashes$1(value) {
 	return value.replace(/[/\\]+$/, "");
 }
 function normalizeComparablePath(value) {
-	const normalized = trimTrailingSlashes(value).replace(/\\/g, "/");
+	const normalized = trimTrailingSlashes$1(value).replace(/\\/g, "/");
 	const driveMatch = normalized.match(/^([a-z]:)(?:\/(.*))?$/i);
 	const drivePrefix = driveMatch?.[1].toLowerCase() ?? "";
 	const remainder = driveMatch ? driveMatch[2] ?? "" : normalized;
@@ -23407,14 +23758,14 @@ function normalizeComparablePath(value) {
 	return (drivePrefix ? `${drivePrefix}/${joined}`.replace(/\/$/, "") : hasRoot ? `/${joined}`.replace(/\/$/, "") : joined || ".").toLowerCase();
 }
 function dirname$1(filePath) {
-	return trimTrailingSlashes(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
+	return trimTrailingSlashes$1(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
 }
 function basename(filePath) {
-	return trimTrailingSlashes(filePath).match(/([^/\\]+)$/)?.[1] ?? "";
+	return trimTrailingSlashes$1(filePath).match(/([^/\\]+)$/)?.[1] ?? "";
 }
 function resolveOutputProjectPath(output, fs) {
 	if (/\.fairy$/i.test(output)) return output;
-	const normalizedOutput = trimTrailingSlashes(output);
+	const normalizedOutput = trimTrailingSlashes$1(output);
 	const projectName = basename(normalizedOutput) || "Restored";
 	return fs.join(normalizedOutput, `${projectName}.fairy`);
 }
@@ -23460,7 +23811,7 @@ async function prepareRestoreOutputDir(inputDir, outputDir, outputProjectPath, f
 	await fs.mkdir(outputDir);
 }
 async function restore(options) {
-	const sourceDir = trimTrailingSlashes(options.inputDir);
+	const sourceDir = trimTrailingSlashes$1(options.inputDir);
 	const outputIsProjectFile = /\.fairy$/i.test(options.output);
 	const outputProjectPath = resolveOutputProjectPath(options.output, options.fs);
 	await prepareRestoreOutputDir(sourceDir, dirname$1(outputProjectPath) || ".", outputProjectPath, options.fs, options.force === true, outputIsProjectFile);
@@ -23602,16 +23953,23 @@ var RestoreWorkflow = class {
 	async _ensureLooseImageResource(doc, pkg, owner, sourceDir, fileName) {
 		const resources = pkg.listResources();
 		const existing = this._findResourceByFile(resources, owner, "ImageResource", fileName);
-		if (existing) return existing;
 		const sourcePath = await this._resolveLooseSourceFile(pkg, sourceDir, fileName);
-		if (!sourcePath) return null;
+		if (!sourcePath) return existing ?? null;
+		if (existing) {
+			existing.setExtras?.({
+				...existing.getExtras?.() ?? {},
+				_publishedFile: fileBaseName(sourcePath),
+				_restoreAsLooseImage: true
+			});
+			return existing;
+		}
 		const resource = doc.createImageResource(stripExtension(fileName));
 		resource.setId(generateId()).setPath(owner.getPath?.() ?? "/").setBranch(owner.getBranch?.() ?? "").setBranchItemIds(owner.getBranchItemIds?.() ?? []).setExported(false).setFileName(fileName);
 		resource.setExtras?.({
 			...resource.getExtras?.() ?? {},
 			_publishedFile: fileBaseName(sourcePath),
 			_suppressPackageSize: true,
-			_syntheticLooseImage: true
+			_restoreAsLooseImage: true
 		});
 		pkg.addResource(resource);
 		return resource;
@@ -23785,13 +24143,13 @@ var RestoreWorkflow = class {
 	}
 	async _copyLooseResources(pkg, options, warnings) {
 		for (const resource of pkg.listResources()) {
-			const syntheticLooseImage = resource.getExtras?.()?._syntheticLooseImage === true;
+			const restoreAsLooseImage = resource.getExtras?.()?._restoreAsLooseImage === true;
 			if (![
 				"SoundResource",
 				"MiscResource",
 				"SpineResource",
 				"DragonBonesResource"
-			].includes(resource.propertyType) && !syntheticLooseImage) continue;
+			].includes(resource.propertyType) && !restoreAsLooseImage) continue;
 			const fileName = resourceFileName(resource);
 			if (!fileName) continue;
 			const sourcePath = await this._resolveSourceFile(options.sourceDir, this._sourceFileCandidates(pkg, resourcePublishedFileName(resource), fileName));
@@ -23961,6 +24319,26 @@ var RestoreWorkflow = class {
 };
 //#endregion
 //#region ../functions/src/publish.ts
+async function runPublishPluginHook(plugins, hook, doc, options) {
+	const logger = doc.getLogger();
+	for (const plugin of plugins) {
+		const fn = plugin.plugin[hook];
+		if (typeof fn !== "function") continue;
+		try {
+			await fn(doc, options);
+		} catch (error) {
+			logger.warn(`publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`);
+		}
+	}
+}
+function resolvePublishPluginsDir(doc, options) {
+	const fs = options.fs;
+	const projectDir = doc.getProjectDir?.() ?? "";
+	if (projectDir) return fs?.join ? fs.join(projectDir, "plugins") : `${projectDir.replace(/[/\\]+$/, "")}/plugins`;
+	const projectBasePath = resolveProjectBasePath(options.basePath);
+	if (!projectBasePath) return "";
+	return fs?.join ? fs.join(projectBasePath, "plugins") : `${projectBasePath.replace(/[/\\]+$/, "")}/plugins`;
+}
 const UNITY_PROJECT_TYPE = ProjectType.Unity;
 const COCOS_CREATOR_PROJECT_TYPE = ProjectType.CocosCreator;
 function resolveDefaultPublishFileExtension(projectType, publishSettings) {
@@ -24010,6 +24388,19 @@ function resolvePublishOptions(doc, overrides = {}) {
 		atlas: atlasOptions
 	};
 }
+function trimTrailingSlashes(value) {
+	return value.replace(/[/\\]+$/, "");
+}
+function isAbsolutePathLike(value) {
+	return /^(?:[a-zA-Z]:[/\\]|[/\\]{1,2})/u.test(value);
+}
+function joinPathSegments(left, right) {
+	const normalizedLeft = trimTrailingSlashes(left);
+	const normalizedRight = right.replace(/^[/\\]+/, "");
+	if (!normalizedLeft) return normalizedRight;
+	if (!normalizedRight) return normalizedLeft;
+	return `${normalizedLeft}${normalizedLeft.includes("\\") ? "\\" : "/"}${normalizedRight}`;
+}
 function dirname(filePath) {
 	return filePath.replace(/[/\\]+$/, "").match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
 }
@@ -24125,13 +24516,14 @@ function extname(fileName) {
 	if (lastDot <= lastSlash) return "";
 	return normalized.slice(lastDot);
 }
-function resolvePublishedMiscFileName(resource) {
+function resolvePublishedMiscFileName(resource, projectType) {
 	const file = resource.getFile();
+	if (projectType !== UNITY_PROJECT_TYPE) return file;
 	if (file.toLowerCase().endsWith(".atlas")) return `${file}.txt`;
 	return file;
 }
-function resolvePublishedSkeletonFileName(resource) {
-	if (isSpineResource(resource) && resource.getFile().toLowerCase().endsWith(".skel")) return `${resource.getFile()}.bytes`;
+function resolvePublishedSkeletonFileName(resource, projectType) {
+	if (projectType === UNITY_PROJECT_TYPE && isSpineResource(resource) && resource.getFile().toLowerCase().endsWith(".skel")) return `${resource.getFile()}.bytes`;
 	return resource.getFile();
 }
 function setPublishedFileExtra(resource, fileName) {
@@ -24234,6 +24626,24 @@ function collectPackagePublishContext(pkg, options) {
 	const referencedIds = /* @__PURE__ */ new Set();
 	const pixelHitTestImageIds = /* @__PURE__ */ new Set();
 	const spriteItemIds = /* @__PURE__ */ new Set();
+	const collectExportedResourceIds = (sourceResources, sourcePublishedResourceIds) => {
+		const exportedResourceIds = new Set(sourcePublishedResourceIds);
+		const resourcesById = new Map(sourceResources.map((resource) => [resource.getId(), resource]));
+		let changed = true;
+		while (changed) {
+			changed = false;
+			for (const resourceId of [...exportedResourceIds]) {
+				const resource = resourcesById.get(resourceId);
+				if (!resource || !isSkeletonResource(resource)) continue;
+				for (const requiredId of resource.getRequireIds()) {
+					if (!requiredId || exportedResourceIds.has(requiredId)) continue;
+					exportedResourceIds.add(requiredId);
+					changed = true;
+				}
+			}
+		}
+		return exportedResourceIds;
+	};
 	for (const atlas of pkg.listAtlases()) for (const sprite of atlas.listSprites()) spriteItemIds.add(sprite.getItemId());
 	for (const resource of resources) {
 		if (!isComponentResource(resource)) continue;
@@ -24260,6 +24670,7 @@ function collectPackagePublishContext(pkg, options) {
 				child.getSelectedIcon?.(),
 				child.getDropdown?.(),
 				child.getSound?.(),
+				child.getInstanceSound?.(),
 				child.getInstanceIcon?.(),
 				child.getInstanceSelectedIcon?.(),
 				child.getVtScrollBarRes?.(),
@@ -24317,19 +24728,7 @@ function collectPackagePublishContext(pkg, options) {
 		}
 		if (resource.getExported() || referencedIds.has(resourceId)) publishedResourceIds.add(resourceId);
 	}
-	let changed = true;
-	while (changed) {
-		changed = false;
-		for (const resource of resources) {
-			if (!isSkeletonResource(resource)) continue;
-			if (!publishedResourceIds.has(resource.getId())) continue;
-			for (const requiredId of resource.getRequireIds()) {
-				if (!requiredId || publishedResourceIds.has(requiredId)) continue;
-				publishedResourceIds.add(requiredId);
-				changed = true;
-			}
-		}
-	}
+	for (const resourceId of collectExportedResourceIds(resources, publishedResourceIds)) publishedResourceIds.add(resourceId);
 	const highResolutionItemIds = collectHighResolutionItemIds(resources, publishedResourceIds, options.includeHighResolution);
 	if (!options.includeBranches) {
 		const mainByKey = /* @__PURE__ */ new Map();
@@ -24378,6 +24777,7 @@ function collectPackagePublishContext(pkg, options) {
 		return {
 			referencedIds,
 			publishedResourceIds,
+			exportedResourceIds: collectExportedResourceIds(resources, publishedResourceIds),
 			pixelHitTestImageIds,
 			highResolutionItemIds,
 			effectiveResourceIds,
@@ -24387,6 +24787,7 @@ function collectPackagePublishContext(pkg, options) {
 	return {
 		referencedIds,
 		publishedResourceIds,
+		exportedResourceIds: collectExportedResourceIds(resources, publishedResourceIds),
 		pixelHitTestImageIds,
 		highResolutionItemIds,
 		effectiveResourceIds: new Map([...publishedResourceIds].map((resourceId) => [resourceId, resourceId])),
@@ -24437,7 +24838,7 @@ async function applyPixelHitTests(pkg, imageIds, basePath, encoder) {
 	}
 }
 async function annotatePackagePublishArtifacts(pkg, basePath, encoder, options) {
-	const { publishedResourceIds, pixelHitTestImageIds, highResolutionItemIds, effectiveResourceIds, includeBranches } = collectPackagePublishContext(pkg, options);
+	const { publishedResourceIds, exportedResourceIds, pixelHitTestImageIds, highResolutionItemIds, effectiveResourceIds, includeBranches } = collectPackagePublishContext(pkg, options);
 	for (const resource of pkg.listResources()) {
 		setPublishedIdExtra(resource, effectiveResourceIds.get(resource.getId()) ?? null);
 		if (isHighResolutionResource(resource)) resource.setHighResolutionItemIds(highResolutionItemIds.get(resource.getId()) ?? []);
@@ -24447,21 +24848,26 @@ async function annotatePackagePublishArtifacts(pkg, basePath, encoder, options)
 	pkg.setExtras({
 		...extras,
 		publishedResourceIds: [...publishedResourceIds].sort((a, b) => a.localeCompare(b)),
+		exportedResourceIds: [...exportedResourceIds].sort((a, b) => a.localeCompare(b)),
 		publishedIncludeBranches: includeBranches,
 		publishedEffectiveResourceIds: Object.fromEntries(effectiveResourceIds)
 	});
 	for (const resource of pkg.listResources()) {
 		if (isMiscResource(resource)) {
-			setPublishedFileExtra(resource, resolvePublishedMiscFileName(resource));
+			setPublishedFileExtra(resource, resolvePublishedMiscFileName(resource, options.projectType));
 			continue;
 		}
-		if (isSkeletonResource(resource)) setPublishedFileExtra(resource, resolvePublishedSkeletonFileName(resource));
+		if (isSkeletonResource(resource)) setPublishedFileExtra(resource, resolvePublishedSkeletonFileName(resource, options.projectType));
 	}
 }
 function getAnnotatedPublishedResourceIds(pkg) {
 	const extras = pkg.getExtras() ?? {};
 	return new Set(extras.publishedResourceIds ?? []);
 }
+function getAnnotatedExportedResourceIds(pkg) {
+	const extras = pkg.getExtras() ?? {};
+	return new Set(extras.exportedResourceIds ?? []);
+}
 function getPublishedSkeletonDependencyImageIds(pkg, publishedResourceIds) {
 	const imageIds = /* @__PURE__ */ new Set();
 	const resourcesById = new Map(pkg.listResources().map((resource) => [resource.getId(), resource]));
@@ -24500,18 +24906,18 @@ async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw, lo
 	}
 }
 async function exportPackageExternalResources(pkg, outputDir, basePath, fs, readFileRaw, logger) {
-	const publishedResourceIds = getAnnotatedPublishedResourceIds(pkg);
-	const skeletonDependencyImageIds = getPublishedSkeletonDependencyImageIds(pkg, publishedResourceIds);
-	if (publishedResourceIds.size === 0) return;
+	const exportedResourceIds = getAnnotatedExportedResourceIds(pkg);
+	const skeletonDependencyImageIds = getPublishedSkeletonDependencyImageIds(pkg, exportedResourceIds);
+	if (exportedResourceIds.size === 0) return;
 	if (!basePath || !readFileRaw) {
 		if (pkg.listResources().some((resource) => {
-			return (isMiscResource(resource) || isSkeletonResource(resource)) && publishedResourceIds.has(resource.getId()) || skeletonDependencyImageIds.has(resource.getId());
+			return (isMiscResource(resource) || isSkeletonResource(resource)) && exportedResourceIds.has(resource.getId()) || skeletonDependencyImageIds.has(resource.getId());
 		})) logger.warn(`publish: External resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`);
 		return;
 	}
 	for (const resource of pkg.listResources()) {
 		const resourceId = resource.getId();
-		const isSkeletonExternal = publishedResourceIds.has(resourceId) && (isMiscResource(resource) || isSkeletonResource(resource));
+		const isSkeletonExternal = exportedResourceIds.has(resourceId) && (isMiscResource(resource) || isSkeletonResource(resource));
 		const isSkeletonImageDependency = skeletonDependencyImageIds.has(resourceId) && isImageResource(resource);
 		if (!isSkeletonExternal && !isSkeletonImageDependency) continue;
 		let sourcePath;
@@ -24557,16 +24963,102 @@ async function exportPackageExternalResources(pkg, outputDir, basePath, fs, read
 */
 function publish(options) {
 	return createTransform("publish", async (doc) => {
+		const resolveConfiguredOutputPath = (value, projectBasePath) => {
+			const trimmed = value?.trim();
+			if (!trimmed) return void 0;
+			if (isAbsolutePathLike(trimmed) || !projectBasePath) return trimTrailingSlashes(trimmed);
+			return trimTrailingSlashes(options.fs ? options.fs.join(projectBasePath, trimmed) : joinPathSegments(projectBasePath, trimmed));
+		};
+		const resolveProjectPublishConfig = () => {
+			const publishSettings = (doc.getRoot().getSettings?.() ?? {}).publish ?? {};
+			const resolved = resolvePublishOptions(doc, {
+				compressed: options.compressed,
+				fileExtension: options.fileExtension,
+				packages: options.packages,
+				atlas: options.atlas
+			});
+			const includeBranches = (publishSettings.branchProcessing ?? 0) === 0;
+			return {
+				...resolved,
+				projectType: doc.getRoot().getProjectType(),
+				includeBranches,
+				activeBranch: includeBranches ? "" : options.branch ?? "",
+				includeHighResolution: publishSettings.includeHighResolution ?? 0,
+				separatedAtlasForBranch: includeBranches && publishSettings.seperatedAtlasForBranch === true,
+				globalOutputPath: publishSettings.path?.trim() ?? "",
+				globalBranchOutputPath: publishSettings.branchPath?.trim() ?? ""
+			};
+		};
+		const resolvePackagePublishPlan = (pkg, config, projectBasePath) => {
+			let outputDir;
+			if (options.output) outputDir = trimTrailingSlashes(options.output);
+			else {
+				const candidates = [];
+				if (!config.includeBranches && config.activeBranch) candidates.push(pkg.getPublishBranchPath(), config.globalBranchOutputPath);
+				candidates.push(pkg.getPublishPath(), config.globalOutputPath);
+				for (const candidate of candidates) {
+					const resolved = resolveConfiguredOutputPath(candidate, projectBasePath);
+					if (!resolved) continue;
+					outputDir = resolved;
+					break;
+				}
+			}
+			const publishName = pkg.getPublishName() || pkg.getName();
+			return {
+				pkg,
+				outputDir,
+				publishName,
+				fileName: resolvePublishFileName(publishName, config.fileExtension),
+				compressed: config.compressed,
+				fileExtension: config.fileExtension,
+				includeBranches: config.includeBranches,
+				activeBranch: config.activeBranch,
+				includeHighResolution: config.includeHighResolution,
+				separatedAtlasForBranch: config.separatedAtlasForBranch,
+				atlas: config.atlas
+			};
+		};
+		const createNoopPublishFs = () => ({
+			async writeFileRaw() {},
+			async mkdir() {},
+			join(...paths) {
+				return paths.join("/");
+			}
+		});
+		const publishPackage = async (plan, writerFs, packageIndex) => {
+			const atlasRuntimeOptions = resolvePublishAtlasRuntimeOptions(plan.fileExtension);
+			await atlas({
+				...plan.atlas,
+				...options.atlas ?? {},
+				separatedAtlasForBranch: plan.separatedAtlasForBranch,
+				encoder: options.encoder,
+				basePath: options.basePath,
+				outputPath: options.fs ? plan.outputDir : void 0,
+				mkdir: options.fs ? options.fs.mkdir : void 0,
+				readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
+				packages: [plan.pkg.getName()],
+				...atlasRuntimeOptions
+			})(doc);
+			if (!options.fs) return;
+			if (!plan.outputDir) throw new Error("publish: no output directory resolved. Provide --output, or configure global publish.path / package publishPath.");
+			await options.fs.mkdir(plan.outputDir);
+			const filePath = options.fs.join(plan.outputDir, plan.fileName);
+			const bwOptions = {
+				compressed: plan.compressed,
+				packageIndex
+			};
+			await new BinaryWriter(writerFs).write(doc, filePath, bwOptions);
+			await exportPackageSounds(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw, logger);
+			await exportPackageExternalResources(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw, logger);
+			logger.info(`publish: Written ${plan.fileName}`);
+		};
 		const root = doc.getRoot();
 		const logger = doc.getLogger();
-		const publishSettings = (root.getSettings?.() ?? {}).publish ?? {};
-		const resolved = resolvePublishOptions(doc, {
-			compressed: options.compressed,
-			fileExtension: options.fileExtension,
-			packages: options.packages,
-			atlas: options.atlas
-		});
-		const ext = resolved.fileExtension;
+		const projectBasePath = resolveProjectBasePath(options.basePath) || doc.getProjectDir?.() || "";
+		const pluginsDir = resolvePublishPluginsDir(doc, options);
+		const plugins = pluginsDir ? await loadPlugins(doc, pluginsDir) : [];
+		await runPublishPluginHook(plugins, "onPublishStart", doc, options);
+		const resolved = resolveProjectPublishConfig();
 		let allPackages = root.listPackages();
 		if (resolved.packages && resolved.packages.length > 0) {
 			const names = new Set(resolved.packages);
@@ -24574,59 +25066,42 @@ function publish(options) {
 		}
 		if (allPackages.length === 0) {
 			logger.warn("publish: No packages to publish.");
+			await runPublishPluginHook(plugins, "onPublishEnd", doc, options);
 			return;
 		}
-		const includeBranches = (publishSettings.branchProcessing ?? 0) === 0;
-		const activeBranch = includeBranches ? "" : options.branch ?? "";
-		const includeHighResolution = publishSettings.includeHighResolution ?? 0;
-		const atlasRuntimeOptions = resolvePublishAtlasRuntimeOptions(ext);
 		const allDocPackages = root.listPackages();
 		const pkgMap = /* @__PURE__ */ new Map();
 		for (const p of allDocPackages) pkgMap.set(p.getId(), p);
 		for (const pkg of allPackages) {
-			_computeDependencies(pkg, pkgMap);
+			_computeDependencies(doc, pkg, pkgMap);
 			await annotatePackagePublishArtifacts(pkg, options.basePath, options.encoder, {
-				includeBranches,
-				activeBranch,
-				includeHighResolution
+				projectType: resolved.projectType,
+				includeBranches: resolved.includeBranches,
+				activeBranch: resolved.activeBranch,
+				includeHighResolution: resolved.includeHighResolution
 			});
 		}
-		await atlas({
-			...resolved.atlas,
-			...options.atlas ?? {},
-			separatedAtlasForBranch: includeBranches && publishSettings.seperatedAtlasForBranch === true,
-			encoder: options.encoder,
-			basePath: options.basePath,
-			outputPath: options.fs ? options.output : void 0,
-			mkdir: options.fs ? options.fs.mkdir : void 0,
-			readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
-			...atlasRuntimeOptions
-		})(doc);
+		const plans = allPackages.map((pkg) => resolvePackagePublishPlan(pkg, resolved, projectBasePath));
 		if (!options.fs) {
 			logger.info(`publish: No fs provided — layout computed for ${allPackages.length} package(s), skipping file output.`);
+			const noopWriterFs = toBinaryWriterFileSystem(createNoopPublishFs());
+			for (const plan of plans) await publishPackage(plan, noopWriterFs, allDocPackages.indexOf(plan.pkg));
+			await runPublishPluginHook(plugins, "onPublishEnd", doc, options);
 			return;
 		}
-		await options.fs.mkdir(options.output);
+		const unresolvedPlan = plans.find((plan) => !plan.outputDir);
+		if (unresolvedPlan) throw new Error(`publish: no output directory resolved for package "${unresolvedPlan.pkg.getName()}". Provide --output, or configure global publish.path / package publishPath.`);
 		const writerFs = toBinaryWriterFileSystem(options.fs);
-		for (const pkg of allPackages) {
-			const pkgIndex = allDocPackages.indexOf(pkg);
-			const fileName = resolvePublishFileName(pkg.getPublishName() || pkg.getName(), ext);
-			const filePath = options.fs.join(options.output, fileName);
-			const bwOptions = {
-				compressed: resolved.compressed,
-				packageIndex: pkgIndex
-			};
-			await new BinaryWriter(writerFs).write(doc, filePath, bwOptions);
-			await exportPackageSounds(pkg, options.output, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw, logger);
-			await exportPackageExternalResources(pkg, options.output, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw, logger);
-			logger.info(`publish: Written ${fileName}`);
-		}
+		for (const plan of plans) await publishPackage(plan, writerFs, allDocPackages.indexOf(plan.pkg));
 		await publishCodeGeneration(doc, {
 			basePath: options.basePath,
 			fs: options.fs,
-			packages: allPackages
+			packages: allPackages,
+			plugins
 		});
-		logger.info(`publish: Published ${allPackages.length} package(s) to ${options.output}`);
+		const publishedTargets = [...new Set(plans.map((plan) => plan.outputDir).filter((value) => Boolean(value)))];
+		logger.info(publishedTargets.length > 0 ? `publish: Published ${allPackages.length} package(s) to ${publishedTargets.join(", ")}` : `publish: Published ${allPackages.length} package(s)`);
+		await runPublishPluginHook(plugins, "onPublishEnd", doc, options);
 	});
 }
 /**
@@ -24634,25 +25109,104 @@ function publish(options) {
 * The editor only adds dependencies for packages referenced via bitmap font URLs.
 * @internal
 */
-function _computeDependencies(pkg, pkgMap) {
+function _computeDependencies(doc, pkg, pkgMap) {
 	const referencedPkgIds = /* @__PURE__ */ new Set();
-	function scanFontUrl(font) {
-		if (!font) return;
-		const fontStr = Array.isArray(font) ? font[0] : String(font);
-		if (typeof fontStr !== "string" || !fontStr.startsWith("ui://")) return;
-		const rest = fontStr.slice(5);
-		if (rest.length >= 8) {
-			const depPkgId = rest.slice(0, 8);
-			if (depPkgId !== pkg.getId()) referencedPkgIds.add(depPkgId);
+	const pkgId = pkg.getId();
+	const packageOrder = new Map(doc.getRoot().listPackages().map((entry, index) => [entry.getId(), index]));
+	const addDependencyPackageId = (dependencyPkgId) => {
+		const normalized = dependencyPkgId?.trim() ?? "";
+		if (!normalized || normalized === pkgId) return;
+		referencedPkgIds.add(normalized);
+	};
+	const extractPackageIdFromUiUrl = (value) => {
+		if (!value.startsWith("ui://")) return null;
+		const rest = value.slice(5);
+		if (!rest) return null;
+		const slashIndex = rest.indexOf("/");
+		if (slashIndex >= 0) return rest.slice(0, slashIndex) || null;
+		if (rest.length >= 8) return rest.slice(0, 8);
+		return null;
+	};
+	const addDependencyPackageIdFromUiValue = (value) => {
+		if (!value || typeof value !== "string") return;
+		addDependencyPackageId(extractPackageIdFromUiUrl(value));
+	};
+	const addDependencyPackageIdsFromText = (value) => {
+		if (!value || typeof value !== "string") return;
+		const matches = value.matchAll(/ui:\/\/([0-9a-z]{8})/giu);
+		for (const match of matches) addDependencyPackageId(match[1] ?? "");
+	};
+	const addDependencyPackageIdsFromUnknown = (value) => {
+		if (Array.isArray(value)) {
+			for (const entry of value) addDependencyPackageIdsFromUnknown(entry);
+			return;
 		}
-	}
+		if (typeof value === "string") {
+			addDependencyPackageIdFromUiValue(value);
+			addDependencyPackageIdsFromText(value);
+		}
+	};
+	const addDependencyFontRef = (value) => {
+		if (Array.isArray(value)) {
+			for (const entry of value) addDependencyPackageIdFromUiValue(entry);
+			return;
+		}
+		addDependencyPackageIdFromUiValue(value ?? void 0);
+	};
 	for (const res of pkg.listResources()) {
 		if (res.propertyType !== "Component") continue;
-		for (const child of res.listChildren?.() ?? []) scanFontUrl(child.getFont?.());
+		const component = res;
+		for (const child of component.listChildren?.() ?? []) {
+			addDependencyPackageId(child.getPackageId?.());
+			addDependencyFontRef(child.getFont?.());
+			addDependencyPackageIdsFromText(child.getText?.());
+			for (const ref of [
+				child.getUrl?.(),
+				child.getDefaultItem?.(),
+				child.getIcon?.(),
+				child.getSelectedIcon?.(),
+				child.getDropdown?.(),
+				child.getSound?.(),
+				child.getInstanceSound?.(),
+				child.getInstanceIcon?.(),
+				child.getInstanceSelectedIcon?.(),
+				child.getVtScrollBarRes?.(),
+				child.getHzScrollBarRes?.(),
+				child.getHeaderRes?.(),
+				child.getFooterRes?.()
+			]) addDependencyPackageIdFromUiValue(ref);
+			for (const item of child.getInstanceComboItems?.() ?? []) addDependencyPackageIdFromUiValue(item.icon ?? void 0);
+			for (const item of child.getListItems?.() ?? []) {
+				addDependencyPackageIdFromUiValue(item.icon ?? void 0);
+				addDependencyPackageIdFromUiValue(item.url ?? void 0);
+			}
+			for (const gear of child.listGears?.() ?? []) {
+				addDependencyPackageIdsFromUnknown(gear.getValues?.());
+				addDependencyPackageIdsFromUnknown(gear.getDefaultValue?.());
+			}
+		}
+		addDependencyFontRef(component.getFont?.());
+		for (const ref of [
+			component.getDropdown?.(),
+			component.getHeaderRes?.(),
+			component.getFooterRes?.(),
+			component.getVtScrollBarRes?.(),
+			component.getHzScrollBarRes?.(),
+			component.getSound?.()
+		]) addDependencyPackageIdFromUiValue(ref);
+		for (const transition of component.listTransitions?.() ?? []) for (const item of transition.listItems?.() ?? []) {
+			addDependencyPackageIdsFromUnknown(item.getStartValue?.());
+			addDependencyPackageIdsFromUnknown(item.getEndValue?.());
+		}
 	}
 	for (const dep of pkg.listDependencies()) pkg.removeDependency(dep);
 	if (referencedPkgIds.size > 0) {
-		const sortedIds = [...referencedPkgIds].sort((a, b) => a.localeCompare(b));
+		const sortedIds = [...referencedPkgIds].sort((a, b) => {
+			const orderA = packageOrder.get(a) ?? Number.MAX_SAFE_INTEGER;
+			const orderB = packageOrder.get(b) ?? Number.MAX_SAFE_INTEGER;
+			if (orderA !== orderB) return orderA - orderB;
+			return a.localeCompare(b);
+		});
 		for (const refId of sortedIds) {
 			const depPkg = pkgMap.get(refId);
 			if (depPkg) pkg.addDependency(depPkg);
@@ -24660,98 +25214,238 @@ function _computeDependencies(pkg, pkgMap) {
 	}
 }
 //#endregion
-//#region src/cli.ts
-const HELP = `
-ofgui — FairyGUI Headless Authoring CLI
-
-Alias:
-  openfairygui
-
-Commands:
-  inspect <project-dir>                          Show project contents report
-  publish <project-dir> --output <dir> [options]  Publish project to binary outputs and configured generated code
-  restore <release-dir> --output <dir> [options]  Restore a FairyGUI project from published binaries
-  backend-capabilities <project-dir>            Open a backend session, print runtime capabilities, then close it
-
-Publish options:
-  --output, -o <dir>     Output directory (required)
-  --compressed           Compress binary data (overrides project setting)
-  --packages <a,b,c>     Only publish specific packages (comma-separated)
-  --branch <name>        Active branch used by "主干合并活跃分支"; omit for main branch
-  --project-type <name|id>  Override project type (for example: unity, layabox, cocoscreator, 0, 4, 3)
-
-Restore options:
-  --output, -o <dir>     Output project directory (required)
-  --packages <a,b,c>     Only restore specific packages (comma-separated)
-  --force                Overwrite a non-empty output directory
-  --project-type <name|id>  Override restored project type; default is unity
-
-Options:
-  --help, -h     Show this help
-  --version, -v  Show version
-
-Input can be a .fairy file or a project root directory (auto-discovers .fairy file).
-File extension and binary format are read from project settings.
-`;
-const require = createRequire(import.meta.url);
-function getInjectedPackageVersion() {
-	const version = import.meta.env?.PACKAGE_VERSION;
-	return typeof version === "string" && version.length > 0 ? version : null;
-}
-function readPackageVersion() {
-	const injectedVersion = getInjectedPackageVersion();
-	if (injectedVersion) return injectedVersion;
-	try {
-		const pkg = require("../package.json");
-		if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
-	} catch {}
-	return "0.0.0-dev";
-}
-const PACKAGE_VERSION = readPackageVersion();
+//#region ../core/src/io/node-io.ts
+/**
+* Node.js I/O implementation for reading and writing FairyGUI projects.
+*
+* Usage:
+*
+* ```ts
+* import { NodeIO } from '@openfairygui/core/node';
+*
+* const io = new NodeIO();
+* const doc = await io.readProject('./path/to/project.fairy');
+* await io.writeProject(doc, './path/to/output.fairy');
+* const doc2 = await io.readBinary('./path/to/package_fui.bytes');
+* ```
+*
+* @category I/O
+*/
+var NodeIO = class extends PlatformIO {
+	createFileSystem() {
+		return {
+			async readFile(filePath) {
+				return fs$1.readFile(filePath, "utf-8");
+			},
+			async readFileRaw(filePath) {
+				const buf = await fs$1.readFile(filePath);
+				return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+			},
+			async writeFile(filePath, content) {
+				await fs$1.writeFile(filePath, content, "utf-8");
+			},
+			async writeFileRaw(filePath, data) {
+				await fs$1.writeFile(filePath, data);
+			},
+			async mkdir(dirPath) {
+				await fs$1.mkdir(dirPath, { recursive: true });
+			},
+			async readdir(dirPath) {
+				const entries = await fs$1.readdir(dirPath, { withFileTypes: true });
+				return (await Promise.all(entries.map(async (entry) => {
+					if (entry.isDirectory()) return entry.name;
+					if (!entry.isSymbolicLink()) return null;
+					try {
+						return (await fs$1.stat(path$1.join(dirPath, entry.name))).isDirectory() ? entry.name : null;
+					} catch {
+						return null;
+					}
+				}))).filter((entry) => entry !== null);
+			},
+			async exists(filePath) {
+				try {
+					await fs$1.access(filePath);
+					return true;
+				} catch {
+					return false;
+				}
+			},
+			join(...paths) {
+				return path$1.join(...paths);
+			},
+			dirname(filePath) {
+				return path$1.dirname(filePath);
+			}
+		};
+	}
+};
+//#endregion
+//#region src/utils/project-input.ts
 /** Resolve input to a .fairy file path. Accepts a directory or a .fairy file. */
 async function resolveFairyPath(input) {
 	const resolved = path.resolve(input);
 	const stat = await fs.stat(resolved);
 	if (stat.isFile() && resolved.endsWith(".fairy")) return resolved;
 	if (stat.isDirectory()) {
-		const fairyFiles = (await fs.readdir(resolved)).filter((e) => e.endsWith(".fairy"));
+		const fairyFiles = (await fs.readdir(resolved)).filter((entry) => entry.endsWith(".fairy"));
 		if (fairyFiles.length === 1) return path.join(resolved, fairyFiles[0]);
 		if (fairyFiles.length > 1) throw new Error(`Multiple .fairy files found in ${resolved}: ${fairyFiles.join(", ")}. Please specify one.`);
 		throw new Error(`No .fairy file found in ${resolved}`);
 	}
 	throw new Error(`Input is not a .fairy file or directory: ${resolved}`);
 }
-async function main() {
-	const args = process.argv.slice(2);
-	if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-		console.log(HELP);
-		return;
-	}
-	if (args.includes("--version") || args.includes("-v")) {
-		console.log(PACKAGE_VERSION);
-		return;
-	}
-	const command = args[0];
-	const rest = args.slice(1);
-	switch (command) {
-		case "inspect":
-			await cmdInspect(rest);
-			break;
-		case "publish":
-			await cmdPublish(rest);
-			break;
-		case "restore":
-			await cmdRestore(rest);
-			break;
-		case "backend-capabilities":
-			await cmdBackendCapabilities(rest);
-			break;
-		default:
-			console.error(`Unknown command: ${command}\n`);
-			console.log(HELP);
-			process.exit(1);
+//#endregion
+//#region src/commands/inspect.ts
+function registerInspectCommand(program) {
+	program.command("inspect").description("Show project contents report").argument("<project-dir>", "Project root directory or .fairy file").action(async (projectDir) => {
+		const fairyPath = await resolveFairyPath(projectDir);
+		console.log(`Project: ${fairyPath}\n`);
+		printReport(inspect(await new NodeIO().readProject(fairyPath)));
+	});
+}
+function printReport(report) {
+	console.log(`ID: ${report.projectId}`);
+	console.log(`Type: ${report.projectType}, Version: ${report.version}`);
+	console.log(`\nPackages: ${report.totals.packages}`);
+	console.log(`  Images:       ${report.totals.images}`);
+	console.log(`  Sounds:       ${report.totals.sounds}`);
+	console.log(`  Fonts:        ${report.totals.fonts}`);
+	console.log(`  MovieClips:   ${report.totals.movieClips}`);
+	console.log(`  Components:   ${report.totals.components}`);
+	console.log(`  DisplayObjs:  ${report.totals.displayObjects}`);
+	console.log(`  Gears:        ${report.totals.gears}`);
+	console.log(`  Controllers:  ${report.totals.controllers}`);
+	console.log(`  Transitions:  ${report.totals.transitions}`);
+	console.log("\nPackage details:");
+	for (const pkg of report.packages) {
+		const res = pkg.resources;
+		console.log(`  ${pkg.name} (${pkg.id}): ${res.images.count} img, ${res.sounds.count} snd, ${res.fonts.count} font, ${res.components.count} comp`);
 	}
 }
+//#endregion
+//#region src/utils/project-type.ts
+function parseProjectType(value) {
+	if (!value) return void 0;
+	const trimmed = value.trim();
+	if (trimmed === "") return void 0;
+	if (/^\d+$/u.test(trimmed)) return Number(trimmed);
+	const normalized = trimmed.toLowerCase();
+	const map = {
+		unity: ProjectType.Unity,
+		flash: ProjectType.Flash,
+		starling: ProjectType.Starling,
+		cocoscreator: ProjectType.CocosCreator,
+		cocos: ProjectType.CocosCreator,
+		layabox: ProjectType.LayaBox,
+		laya: ProjectType.LayaBox,
+		egret: ProjectType.Egret,
+		haxe: ProjectType.Haxe,
+		pixi: ProjectType.Pixi,
+		libgdx: ProjectType.LibGDX,
+		unreal: ProjectType.Unreal,
+		cryengine: ProjectType.CryEngine,
+		monogame: ProjectType.MonoGame,
+		vision: ProjectType.Vision
+	};
+	const resolved = map[normalized];
+	if (resolved === void 0) throw new Error(`Unknown project type: ${value}. Use a numeric id or one of: ${Object.keys(map).join(", ")}`);
+	return resolved;
+}
+//#endregion
+//#region src/commands/publish.ts
+function registerPublishCommand(program) {
+	program.command("publish").description("Publish project to binary outputs and configured generated code").argument("<project-dir>", "Project root directory or .fairy file").option("-o, --output <dir>", "Override project or package publish output directory").option("-c, --compressed", "Compress binary data (overrides project setting)").option("-p, --packages <a,b,c>", "Only publish specific packages (comma-separated)").option("-b, --branch <name>", "Active branch used by \"主干合并活跃分支\"; omit for main branch").option("-t, --project-type <name|id>", "Override project type (for example: unity, layabox, cocoscreator, 0, 4, 3)").action(async (projectDir, options) => {
+		const fairyPath = await resolveFairyPath(projectDir);
+		const projectRootDir = path.dirname(fairyPath);
+		const outputDir = options.output ? path.resolve(options.output) : void 0;
+		console.log(`Reading project: ${fairyPath}`);
+		const doc = await new NodeIO().readProject(fairyPath);
+		const projectType = parseProjectType(options.projectType);
+		if (projectType !== void 0) doc.getRoot().setProjectType(projectType);
+		const pkgFilter = options.packages?.split(",").map((value) => value.trim());
+		const resolved = resolvePublishOptions(doc, {
+			compressed: options.compressed,
+			packages: pkgFilter
+		});
+		console.log(`Settings: ext=${resolved.fileExtension}, compressed=${resolved.compressed}`);
+		if (options.branch) console.log(`Active branch: ${options.branch}`);
+		const atlasConfig = {
+			...resolved.atlas,
+			readFileRaw: async (filePath) => {
+				const buf = await fs.readFile(filePath);
+				return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+			}
+		};
+		let encoder;
+		try {
+			const sharp = await import("sharp");
+			encoder = sharp.default ?? sharp;
+			console.log("Sharp loaded — atlas PNGs will be generated.");
+		} catch {
+			console.log("Sharp not available — atlas PNGs will NOT be generated (layout only).");
+			console.log("  Install sharp to enable: pnpm add sharp");
+		}
+		await doc.transform(publish({
+			output: outputDir,
+			compressed: resolved.compressed,
+			fileExtension: resolved.fileExtension,
+			packages: resolved.packages,
+			fs: {
+				async readFileRaw(filePath) {
+					const buf = await fs.readFile(filePath);
+					return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+				},
+				async writeFileRaw(filePath, data) {
+					await fs.mkdir(path.dirname(filePath), { recursive: true });
+					await fs.writeFile(filePath, data);
+				},
+				async mkdir(dirPath) {
+					await fs.mkdir(dirPath, { recursive: true });
+				},
+				async readdir(dirPath) {
+					return fs.readdir(dirPath);
+				},
+				async deleteFile(filePath) {
+					await fs.rm(filePath, { force: true });
+				},
+				join(...paths) {
+					return path.join(...paths);
+				}
+			},
+			encoder,
+			basePath: path.join(projectRootDir, "assets"),
+			atlas: atlasConfig,
+			branch: options.branch
+		}));
+		console.log(`\nDone!${outputDir ? ` Output override: ${outputDir}` : ""}`);
+	});
+}
+//#endregion
+//#region src/commands/restore.ts
+function registerRestoreCommand(program) {
+	program.command("restore").description("Restore a FairyGUI project from published binaries").argument("<release-dir>", "Published release directory").requiredOption("-o, --output <dir>", "Output project directory").option("-p, --packages <a,b,c>", "Only restore specific packages (comma-separated)").option("-f, --force", "Overwrite a non-empty output directory").option("-t, --project-type <name|id>", "Override restored project type; default is unity").action(async (releaseDir, options) => {
+		const inputDir = path.resolve(releaseDir);
+		const outputDir = path.resolve(options.output);
+		const pkgFilter = options.packages ? options.packages.split(",").map((value) => value.trim()).filter(Boolean) : void 0;
+		const projectType = parseProjectType(options.projectType);
+		const { cropImage, extractImage } = await createRestoreImageProcessors();
+		console.log(`Restoring published FairyGUI project: ${inputDir}`);
+		const result = await restore({
+			inputDir,
+			output: outputDir,
+			fs: createNodeRestoreFs(),
+			packages: pkgFilter,
+			force: options.force,
+			projectType,
+			cropImage,
+			extractImage
+		});
+		const packages = result.document.getRoot().listPackages();
+		console.log(`\nDone! Output: ${result.projectPath}`);
+		console.log(`Packages: ${packages.map((pkg) => pkg.getName()).join(", ")}`);
+		for (const warning of result.warnings) console.warn(`Warning: ${warning}`);
+	});
+}
 function createNodeRestoreFs() {
 	return {
 		async readFile(filePath) {
@@ -24860,214 +25554,47 @@ async function createRestoreImageProcessors() {
 		}
 	};
 }
-async function cmdInspect(args) {
-	if (args.length === 0) {
-		console.error("Usage: ofgui inspect <project-dir>");
-		process.exit(1);
-	}
-	const fairyPath = await resolveFairyPath(args[0]);
-	console.log(`Project: ${fairyPath}\n`);
-	printReport(inspect(await new NodeIO().readProject(fairyPath)));
+//#endregion
+//#region src/utils/package-version.ts
+const require = createRequire(import.meta.url);
+function getInjectedPackageVersion() {
+	const version = import.meta.env?.PACKAGE_VERSION;
+	return typeof version === "string" && version.length > 0 ? version : null;
 }
-function printReport(report) {
-	console.log(`ID: ${report.projectId}`);
-	console.log(`Type: ${report.projectType}, Version: ${report.version}`);
-	console.log(`\nPackages: ${report.totals.packages}`);
-	console.log(`  Images:       ${report.totals.images}`);
-	console.log(`  Sounds:       ${report.totals.sounds}`);
-	console.log(`  Fonts:        ${report.totals.fonts}`);
-	console.log(`  MovieClips:   ${report.totals.movieClips}`);
-	console.log(`  Components:   ${report.totals.components}`);
-	console.log(`  DisplayObjs:  ${report.totals.displayObjects}`);
-	console.log(`  Gears:        ${report.totals.gears}`);
-	console.log(`  Controllers:  ${report.totals.controllers}`);
-	console.log(`  Transitions:  ${report.totals.transitions}`);
-	console.log("\nPackage details:");
-	for (const pkg of report.packages) {
-		const res = pkg.resources;
-		console.log(`  ${pkg.name} (${pkg.id}): ${res.images.count} img, ${res.sounds.count} snd, ${res.fonts.count} font, ${res.components.count} comp`);
-	}
+function readPackageVersion() {
+	const injectedVersion = getInjectedPackageVersion();
+	if (injectedVersion) return injectedVersion;
+	try {
+		const pkg = require("../../package.json");
+		if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+	} catch {}
+	return "0.0.0-dev";
 }
-function parseProjectType(value) {
-	if (!value) return void 0;
-	const trimmed = value.trim();
-	if (trimmed === "") return void 0;
-	if (/^\d+$/u.test(trimmed)) return Number(trimmed);
-	const normalized = trimmed.toLowerCase();
-	const map = {
-		unity: ProjectType.Unity,
-		flash: ProjectType.Flash,
-		starling: ProjectType.Starling,
-		cocoscreator: ProjectType.CocosCreator,
-		cocos: ProjectType.CocosCreator,
-		layabox: ProjectType.LayaBox,
-		laya: ProjectType.LayaBox,
-		egret: ProjectType.Egret,
-		haxe: ProjectType.Haxe,
-		pixi: ProjectType.Pixi,
-		libgdx: ProjectType.LibGDX,
-		unreal: ProjectType.Unreal,
-		cryengine: ProjectType.CryEngine,
-		monogame: ProjectType.MonoGame,
-		vision: ProjectType.Vision
-	};
-	const resolved = map[normalized];
-	if (resolved === void 0) throw new Error(`Unknown project type: ${value}. Use a numeric id or one of: ${Object.keys(map).join(", ")}`);
-	return resolved;
+//#endregion
+//#region src/cli.ts
+const PACKAGE_VERSION = readPackageVersion();
+function createProgram() {
+	const program = new Command("ofgui");
+	program.description("FairyGUI Headless Authoring CLI").version(PACKAGE_VERSION).showHelpAfterError();
+	registerInspectCommand(program);
+	registerPublishCommand(program);
+	registerRestoreCommand(program);
+	registerBackendCapabilitiesCommand(program);
+	program.addHelpText("after", [
+		"",
+		"Alias:",
+		"  openfairygui",
+		"",
+		"Input can be a .fairy file or a project root directory (auto-discovers .fairy file).",
+		"File extension and binary format are read from project settings."
+	].join("\n"));
+	return program;
 }
-async function cmdRestore(args) {
-	const { values, positionals } = parseArgs({
-		args,
-		options: {
-			output: {
-				type: "string",
-				short: "o"
-			},
-			packages: { type: "string" },
-			force: { type: "boolean" },
-			"project-type": { type: "string" }
-		},
-		allowPositionals: true
-	});
-	if (positionals.length === 0 || !values.output) {
-		console.error("Usage: ofgui restore <release-dir> --output <dir> [--packages a,b,c] [--force]");
-		process.exit(1);
-	}
-	const releaseDir = path.resolve(positionals[0]);
-	const outputDir = path.resolve(values.output);
-	const pkgFilter = values.packages ? values.packages.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
-	const projectType = parseProjectType(values["project-type"]);
-	const { cropImage, extractImage } = await createRestoreImageProcessors();
-	console.log(`Restoring published FairyGUI project: ${releaseDir}`);
-	const result = await restore({
-		inputDir: releaseDir,
-		output: outputDir,
-		fs: createNodeRestoreFs(),
-		packages: pkgFilter,
-		force: values.force,
-		projectType,
-		cropImage,
-		extractImage
-	});
-	const packages = result.document.getRoot().listPackages();
-	console.log(`\nDone! Output: ${result.projectPath}`);
-	console.log(`Packages: ${packages.map((pkg) => pkg.getName()).join(", ")}`);
-	for (const warning of result.warnings) console.warn(`Warning: ${warning}`);
-}
-async function cmdPublish(args) {
-	const { values, positionals } = parseArgs({
-		args,
-		options: {
-			output: {
-				type: "string",
-				short: "o"
-			},
-			compressed: { type: "boolean" },
-			packages: { type: "string" },
-			branch: { type: "string" },
-			"project-type": { type: "string" }
-		},
-		allowPositionals: true
-	});
-	if (positionals.length === 0 || !values.output) {
-		console.error("Usage: ofgui publish <project-dir> --output <dir> [--compressed] [--packages a,b,c] [--branch name]");
-		process.exit(1);
-	}
-	const fairyPath = await resolveFairyPath(positionals[0]);
-	const projectDir = path.dirname(fairyPath);
-	const outputDir = path.resolve(values.output);
-	console.log(`Reading project: ${fairyPath}`);
-	const doc = await new NodeIO().readProject(fairyPath);
-	const projectType = parseProjectType(values["project-type"]);
-	if (projectType !== void 0) doc.getRoot().setProjectType(projectType);
-	const pkgFilter = values.packages ? values.packages.split(",").map((s) => s.trim()) : void 0;
-	const resolved = resolvePublishOptions(doc, {
-		compressed: values.compressed,
-		packages: pkgFilter
-	});
-	console.log(`Settings: ext=${resolved.fileExtension}, compressed=${resolved.compressed}`);
-	if (values.branch) console.log(`Active branch: ${values.branch}`);
-	const atlasConfig = {
-		...resolved.atlas,
-		readFileRaw: async (filePath) => {
-			const buf = await fs.readFile(filePath);
-			return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-		}
-	};
-	let encoder;
-	try {
-		const sharp = await import("sharp");
-		encoder = sharp.default ?? sharp;
-		console.log("Sharp loaded — atlas PNGs will be generated.");
-	} catch {
-		console.log("Sharp not available — atlas PNGs will NOT be generated (layout only).");
-		console.log("  Install sharp to enable: pnpm add sharp");
-	}
-	await doc.transform(publish({
-		output: outputDir,
-		compressed: resolved.compressed,
-		fileExtension: resolved.fileExtension,
-		packages: resolved.packages,
-		fs: {
-			async readFileRaw(filePath) {
-				const buf = await fs.readFile(filePath);
-				return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-			},
-			async writeFileRaw(filePath, data) {
-				await fs.mkdir(path.dirname(filePath), { recursive: true });
-				await fs.writeFile(filePath, data);
-			},
-			async mkdir(dirPath) {
-				await fs.mkdir(dirPath, { recursive: true });
-			},
-			async readdir(dirPath) {
-				return fs.readdir(dirPath);
-			},
-			async deleteFile(filePath) {
-				await fs.rm(filePath, { force: true });
-			},
-			join(...paths) {
-				return path.join(...paths);
-			}
-		},
-		encoder,
-		basePath: path.join(projectDir, "assets"),
-		atlas: atlasConfig,
-		branch: values.branch
-	}));
-	console.log(`\nDone! Output: ${outputDir}`);
-}
-async function cmdBackendCapabilities(args) {
-	if (args.length === 0) {
-		console.error("Usage: ofgui backend-capabilities <project-dir>");
-		process.exit(1);
-	}
-	const runtime = createNodeBackendRuntime();
-	const opened = await runtime.openSession({ projectPath: path.resolve(args[0]) });
-	if (!opened.ok) {
-		console.error(`backend-capabilities: ${opened.error.message}`);
-		process.exit(1);
-	}
-	const capabilities = runtime.getCapabilities();
-	if (!capabilities.ok) {
-		console.error("backend-capabilities: failed to read capabilities");
-		await runtime.closeSession({ sessionId: opened.data.sessionId });
-		process.exit(1);
-	}
-	console.log(`Session: ${opened.data.sessionId}`);
-	console.log(`Project: ${opened.data.canonicalProjectPath}`);
-	console.log(`Revision: ${opened.data.revision}`);
-	console.log(`Runtime owner: ${capabilities.data.runtimeOwner}`);
-	console.log(`Transaction owner: ${capabilities.data.transactionKernelOwner}`);
-	console.log(`App seam owner: ${capabilities.data.appSeamOwner}`);
-	const closed = await runtime.closeSession({ sessionId: opened.data.sessionId });
-	if (!closed.ok) {
-		console.error(`backend-capabilities: ${closed.error.message}`);
-		process.exit(1);
-	}
+async function main() {
+	await createProgram().parseAsync(process.argv);
 }
 main().catch((err) => {
-	console.error(err);
+	console.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);
 });
 //#endregion