@openfairygui/functions 0.3.0-alpha.4 → 0.3.1

package/dist/{atlas-C6tbl7nn.d.ts → atlas-BtWa1DwO.d.ts}

@@ -61,6 +61,9 @@ type AtlasRasterInput = string | Uint8Array | {
  */
 interface AtlasRasterPipeline {
   ensureAlpha(): AtlasRasterPipeline;
+  removeAlpha(): AtlasRasterPipeline;
+  extractChannel(channel: 'alpha'): AtlasRasterPipeline;
+  joinChannel(images: Uint8Array[]): AtlasRasterPipeline;
   resize(options: {
     width: number;
     height: number;
@@ -114,6 +117,9 @@ interface AtlasOptions {
   padding?: number;
   /** Constrain atlas dimensions to powers of two. Default: false. */
   powerOfTwo?: boolean;
+  /** Highest fixed atlas page index accepted from resource textureSetMode. Default: 10. */
+  maxAtlasIndex?: number;
+  multipleOfFour?: boolean;
   /** Force square atlas (width === height). Default: false. */
   square?: boolean;
   /** Allow spilling into multiple atlas pages. Default: true. */

package/dist/{atlas-CHsu2Y8i.d.cts → atlas-CSqHsG0X.d.cts}

@@ -61,6 +61,9 @@ type AtlasRasterInput = string | Uint8Array | {
  */
 interface AtlasRasterPipeline {
   ensureAlpha(): AtlasRasterPipeline;
+  removeAlpha(): AtlasRasterPipeline;
+  extractChannel(channel: 'alpha'): AtlasRasterPipeline;
+  joinChannel(images: Uint8Array[]): AtlasRasterPipeline;
   resize(options: {
     width: number;
     height: number;
@@ -114,6 +117,9 @@ interface AtlasOptions {
   padding?: number;
   /** Constrain atlas dimensions to powers of two. Default: false. */
   powerOfTwo?: boolean;
+  /** Highest fixed atlas page index accepted from resource textureSetMode. Default: 10. */
+  maxAtlasIndex?: number;
+  multipleOfFour?: boolean;
   /** Force square atlas (width === height). Default: false. */
   square?: boolean;
   /** Allow spilling into multiple atlas pages. Default: true. */

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_publish = require("./publish-C7qHwEiP.cjs");
-const require_restore = require("./restore-LXbDQqmT.cjs");
+const require_publish = require("./publish-DhMv_lEP.cjs");
+const require_restore = require("./restore-n61oZ4nw.cjs");
 const require_uam_transaction = require("./uam-transaction.cjs");
 //#region src/inspect.ts
 function mapResource(resource) {

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as AtlasRasterInput, c as AtlasRasterResolvedBuffer, d as PublishSourceFileSystem, i as AtlasRasterCompositeInput, l as PublishFileSystem, n as atlas, o as AtlasRasterMetadata, r as AtlasRasterBackend, s as AtlasRasterPipeline, t as AtlasOptions, u as PublishOutputFileSystem } from "./atlas-CHsu2Y8i.cjs";
-import { A as ExtrasMap, B as ResolvedPublishOptions, C as MaybePromise, D as CliAtlasSettings, E as PluginModule, F as RootProjectSettings, I as publish, L as PublishOptions, M as HasOptionalSrc, N as HasOptionalUrl, O as CliCodeGenerationSettings, P as PublishDependency, R as ResolvePublishOptionsOverrides, S as LoadedPlugin, T as PluginManifest, V as resolvePublishOptions, _ as encodeText, a as RestoreImageExtractor, b as CodeWriter, c as restore, d as CodegenMember, f as CodegenReferencedComponent, g as decodeText, h as buildCodegenClasses, i as RestoreImageExtractInput, j as HasOptionalFont, k as CliPublishSettings, l as AUTO_GENERATED_CODE_MARK, m as ResolvedPackageCodegenPlan, n as RestoreImageCropInput, o as RestoreOptions, p as PublishCodeGenerationOptions, r as RestoreImageCropper, s as RestoreResult, t as RestoreFileSystem, u as CodegenClass, v as publishCodeGeneration, w as Plugin, x as ICodeWriterConfig, y as resolvePackageCodegenPlan, z as ResolvedPublishAtlasOptions } from "./restore-BeWaJNjR.cjs";
+import { a as AtlasRasterInput, c as AtlasRasterResolvedBuffer, d as PublishSourceFileSystem, i as AtlasRasterCompositeInput, l as PublishFileSystem, n as atlas, o as AtlasRasterMetadata, r as AtlasRasterBackend, s as AtlasRasterPipeline, t as AtlasOptions, u as PublishOutputFileSystem } from "./atlas-CSqHsG0X.cjs";
+import { A as ExtrasMap, B as ResolvedPublishOptions, C as MaybePromise, D as CliAtlasSettings, E as PluginModule, F as RootProjectSettings, I as publish, L as PublishOptions, M as HasOptionalSrc, N as HasOptionalUrl, O as CliCodeGenerationSettings, P as PublishDependency, R as ResolvePublishOptionsOverrides, S as LoadedPlugin, T as PluginManifest, V as resolvePublishOptions, _ as encodeText, a as RestoreImageExtractor, b as CodeWriter, c as restore, d as CodegenMember, f as CodegenReferencedComponent, g as decodeText, h as buildCodegenClasses, i as RestoreImageExtractInput, j as HasOptionalFont, k as CliPublishSettings, l as AUTO_GENERATED_CODE_MARK, m as ResolvedPackageCodegenPlan, n as RestoreImageCropInput, o as RestoreOptions, p as PublishCodeGenerationOptions, r as RestoreImageCropper, s as RestoreResult, t as RestoreFileSystem, u as CodegenClass, v as publishCodeGeneration, w as Plugin, x as ICodeWriterConfig, y as resolvePackageCodegenPlan, z as ResolvedPublishAtlasOptions } from "./restore-k3oX26Fs.cjs";
 import { ApplyUamTransactionAppDiagnostic, ApplyUamTransactionAppError, ApplyUamTransactionAppInput, ApplyUamTransactionAppResult, applyUamTransactionApp, applyUamTransactionAppAsync } from "./uam-transaction.cjs";
 import { Document, ProjectDiagnostic, ProjectValidationReport, Transform, UamProject } from "@openfairygui/core";
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AtlasRasterInput, c as AtlasRasterResolvedBuffer, d as PublishSourceFileSystem, i as AtlasRasterCompositeInput, l as PublishFileSystem, n as atlas, o as AtlasRasterMetadata, r as AtlasRasterBackend, s as AtlasRasterPipeline, t as AtlasOptions, u as PublishOutputFileSystem } from "./atlas-C6tbl7nn.js";
-import { A as ExtrasMap, B as ResolvedPublishOptions, C as MaybePromise, D as CliAtlasSettings, E as PluginModule, F as RootProjectSettings, I as publish, L as PublishOptions, M as HasOptionalSrc, N as HasOptionalUrl, O as CliCodeGenerationSettings, P as PublishDependency, R as ResolvePublishOptionsOverrides, S as LoadedPlugin, T as PluginManifest, V as resolvePublishOptions, _ as encodeText, a as RestoreImageExtractor, b as CodeWriter, c as restore, d as CodegenMember, f as CodegenReferencedComponent, g as decodeText, h as buildCodegenClasses, i as RestoreImageExtractInput, j as HasOptionalFont, k as CliPublishSettings, l as AUTO_GENERATED_CODE_MARK, m as ResolvedPackageCodegenPlan, n as RestoreImageCropInput, o as RestoreOptions, p as PublishCodeGenerationOptions, r as RestoreImageCropper, s as RestoreResult, t as RestoreFileSystem, u as CodegenClass, v as publishCodeGeneration, w as Plugin, x as ICodeWriterConfig, y as resolvePackageCodegenPlan, z as ResolvedPublishAtlasOptions } from "./restore-Dh0-Nvms.js";
+import { a as AtlasRasterInput, c as AtlasRasterResolvedBuffer, d as PublishSourceFileSystem, i as AtlasRasterCompositeInput, l as PublishFileSystem, n as atlas, o as AtlasRasterMetadata, r as AtlasRasterBackend, s as AtlasRasterPipeline, t as AtlasOptions, u as PublishOutputFileSystem } from "./atlas-BtWa1DwO.js";
+import { A as ExtrasMap, B as ResolvedPublishOptions, C as MaybePromise, D as CliAtlasSettings, E as PluginModule, F as RootProjectSettings, I as publish, L as PublishOptions, M as HasOptionalSrc, N as HasOptionalUrl, O as CliCodeGenerationSettings, P as PublishDependency, R as ResolvePublishOptionsOverrides, S as LoadedPlugin, T as PluginManifest, V as resolvePublishOptions, _ as encodeText, a as RestoreImageExtractor, b as CodeWriter, c as restore, d as CodegenMember, f as CodegenReferencedComponent, g as decodeText, h as buildCodegenClasses, i as RestoreImageExtractInput, j as HasOptionalFont, k as CliPublishSettings, l as AUTO_GENERATED_CODE_MARK, m as ResolvedPackageCodegenPlan, n as RestoreImageCropInput, o as RestoreOptions, p as PublishCodeGenerationOptions, r as RestoreImageCropper, s as RestoreResult, t as RestoreFileSystem, u as CodegenClass, v as publishCodeGeneration, w as Plugin, x as ICodeWriterConfig, y as resolvePackageCodegenPlan, z as ResolvedPublishAtlasOptions } from "./restore-CbscKkNw.js";
 import { ApplyUamTransactionAppDiagnostic, ApplyUamTransactionAppError, ApplyUamTransactionAppInput, ApplyUamTransactionAppResult, applyUamTransactionApp, applyUamTransactionAppAsync } from "./uam-transaction.js";
 import { Document, ProjectDiagnostic, ProjectValidationReport, Transform, UamProject } from "@openfairygui/core";
 

package/dist/index.js

@@ -1,5 +1,5 @@
-import { _ as validateProject, a as decodeText, g as createTransform, h as atlas, i as buildCodegenClasses, l as resolvePackageCodegenPlan, n as resolvePublishOptions, o as encodeText, r as AUTO_GENERATED_CODE_MARK, s as publishCodeGeneration, t as publish } from "./publish-CyBj2o7n.js";
-import { t as restore } from "./restore-DVo1hXpN.js";
+import { _ as validateProject, a as decodeText, g as createTransform, h as atlas, i as buildCodegenClasses, l as resolvePackageCodegenPlan, n as resolvePublishOptions, o as encodeText, r as AUTO_GENERATED_CODE_MARK, s as publishCodeGeneration, t as publish } from "./publish-Cy09yjfn.js";
+import { t as restore } from "./restore-DB_L_xq4.js";
 import { applyUamTransactionApp, applyUamTransactionAppAsync } from "./uam-transaction.js";
 //#region src/inspect.ts
 function mapResource(resource) {

package/dist/node.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_publish = require("./publish-C7qHwEiP.cjs");
-const require_restore = require("./restore-LXbDQqmT.cjs");
+const require_publish = require("./publish-DhMv_lEP.cjs");
+const require_restore = require("./restore-n61oZ4nw.cjs");
 let _openfairygui_core = require("@openfairygui/core");
 let _openfairygui_core_node = require("@openfairygui/core/node");
 //#region src/adapters/node/plugins.ts
@@ -19,16 +19,33 @@ async function loadPlugins(doc, pluginsDir) {
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
 		const pluginDir = path.join(pluginsDir, entry.name);
+		let manifest;
+		try {
+			manifest = await readPluginManifest(fs, path, pluginDir);
+		} catch (error) {
+			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${require_publish.formatPluginError(error)}`);
+			continue;
+		}
+		if (!manifest) continue;
+		if (!manifest.main) {
+			const error = /* @__PURE__ */ new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
+			if (manifest.required) throw error;
+			doc.getLogger().warn(`publish: Plugin "${manifest.name}" was skipped: ${error.message}`);
+			continue;
+		}
 		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
+				plugin,
+				failureMode: manifest.required ? "abort" : manifest.failureMode
 			});
 		} catch (error) {
-			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${require_publish.formatPluginError(error)}`);
+			if (!manifest.required && manifest.failureMode === "warn") {
+				doc.getLogger().warn(`publish: Plugin "${manifest.name}" was skipped: ${require_publish.formatPluginError(error)}`);
+				continue;
+			}
+			throw new Error(`publish: Failed to load plugin "${manifest.name}": ${require_publish.formatPluginError(error)}`);
 		}
 	}
 	return plugins;
@@ -38,7 +55,6 @@ async function readPluginManifest(fs, path, pluginDir) {
 	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) {
@@ -103,6 +119,77 @@ async function loadNodePublishPlugins(document, assetsPath) {
 	if (!projectDir) return [];
 	return loadPlugins(document, (await importNative$2("node:path")).join(projectDir, "plugins"));
 }
+async function publishToStagedOutput(output, run) {
+	const [fs, path, { randomUUID }] = await Promise.all([
+		importNative$2("node:fs/promises"),
+		importNative$2("node:path"),
+		importNative$2("node:crypto")
+	]);
+	const target = path.resolve(output);
+	const parent = path.dirname(target);
+	const name = path.basename(target);
+	const staging = path.join(parent, `.${name}.publish-${randomUUID()}`);
+	const backup = path.join(parent, `.${name}.publish-backup-${randomUUID()}`);
+	await fs.mkdir(parent, { recursive: true });
+	let existed = false;
+	try {
+		const stat = await fs.lstat(target);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`publishNode: output must be a regular directory: ${target}`);
+		await assertNoSymlinks(fs, path, target);
+		existed = true;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	try {
+		if (existed) await fs.cp(target, staging, {
+			recursive: true,
+			errorOnExist: true,
+			force: false
+		});
+		else await fs.mkdir(staging);
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	try {
+		await run(staging);
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	if (!existed) {
+		await fs.rename(staging, target);
+		return;
+	}
+	await fs.rename(target, backup);
+	try {
+		await fs.rename(staging, target);
+	} catch (error) {
+		await fs.rename(backup, target);
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	await fs.rm(backup, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+}
+async function assertNoSymlinks(fs, path, directory) {
+	for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isSymbolicLink()) throw new Error(`publishNode: symbolic links are not supported in output directories: ${entryPath}`);
+		if (entry.isDirectory()) await assertNoSymlinks(fs, path, entryPath);
+	}
+}
 /**
 * Publish a FairyGUI project through the standard Node host adapter.
 *
@@ -115,17 +202,25 @@ async function publishNode(options) {
 	const [fileSystem, assetsPath] = await Promise.all([createNodePublishFileSystem(), resolveNodeAssetsPath(document, configuredAssetsPath)]);
 	const [encoder, plugins] = await Promise.all([configuredEncoder === void 0 ? loadSharpBackend() : Promise.resolve(configuredEncoder), configuredPlugins === void 0 ? loadNodePublishPlugins(document, assetsPath) : Promise.resolve(configuredPlugins)]);
 	if (!encoder) throw new Error("publishNode: Sharp is required for a complete publish. Install sharp or provide an encoder.");
-	await document.transform(require_publish.publish({
-		...publishOptions,
-		basePath: assetsPath,
-		encoder,
-		atlas: {
-			...atlas,
-			readFileRaw: fileSystem.readFileRaw
-		},
-		fs: fileSystem,
-		plugins
-	}));
+	const run = async (output) => {
+		await document.transform(require_publish.publish({
+			...publishOptions,
+			output,
+			basePath: assetsPath,
+			encoder,
+			atlas: {
+				...atlas,
+				readFileRaw: fileSystem.readFileRaw
+			},
+			fs: fileSystem,
+			plugins
+		}));
+	};
+	if (publishOptions.output) {
+		await publishToStagedOutput(publishOptions.output, run);
+		return;
+	}
+	await run(void 0);
 }
 //#endregion
 //#region src/adapters/node/restore.ts
@@ -302,18 +397,21 @@ async function validateProjectNode(projectPath) {
 	}
 	const decodedPaths = new Set(images.map(({ packageIndex, resourceIndex }) => `packages[${packageIndex}].resources[${resourceIndex}]`));
 	diagnostics = diagnostics.filter((diagnostic) => diagnostic.code !== "decode_capability_unavailable" || !decodedPaths.has(diagnostic.path));
-	for (const { pkg, packageIndex, resource, resourceIndex } of images) try {
-		await sharp(resource.sourceBytes).raw().toBuffer();
-	} catch (error) {
-		diagnostics.push({
-			severity: "error",
-			code: "corrupt_source",
-			path: `packages[${packageIndex}].resources[${resourceIndex}]`,
-			message: `Image source cannot be decoded: ${error instanceof Error ? error.message : String(error)}`,
-			packageId: pkg.id,
-			resourceId: resource.id,
-			sourcePath: sourceName(resource)
-		});
+	for (const { pkg, packageIndex, resource, resourceIndex } of images) {
+		if (resource.kind !== "image") continue;
+		try {
+			await sharp(resource.sourceBytes).raw().toBuffer();
+		} catch (error) {
+			diagnostics.push({
+				severity: "error",
+				code: "corrupt_source",
+				path: `packages[${packageIndex}].resources[${resourceIndex}]`,
+				message: `Image source cannot be decoded: ${error instanceof Error ? error.message : String(error)}`,
+				packageId: pkg.id,
+				resourceId: resource.id,
+				sourcePath: sourceName(resource)
+			});
+		}
 	}
 	return (0, _openfairygui_core.createProjectValidationReport)(diagnostics, read.complete && !diagnostics.some((diagnostic) => diagnostic.code === "decode_capability_unavailable"));
 }

package/dist/node.d.cts

@@ -1,5 +1,5 @@
-import { r as AtlasRasterBackend } from "./atlas-CHsu2Y8i.cjs";
-import { L as PublishOptions, S as LoadedPlugin, o as RestoreOptions, s as RestoreResult } from "./restore-BeWaJNjR.cjs";
+import { r as AtlasRasterBackend } from "./atlas-CSqHsG0X.cjs";
+import { L as PublishOptions, S as LoadedPlugin, o as RestoreOptions, s as RestoreResult } from "./restore-k3oX26Fs.cjs";
 import { Document, ProjectValidationReport } from "@openfairygui/core";
 
 //#region src/adapters/node/publish.d.ts

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { r as AtlasRasterBackend } from "./atlas-C6tbl7nn.js";
-import { L as PublishOptions, S as LoadedPlugin, o as RestoreOptions, s as RestoreResult } from "./restore-Dh0-Nvms.js";
+import { r as AtlasRasterBackend } from "./atlas-BtWa1DwO.js";
+import { L as PublishOptions, S as LoadedPlugin, o as RestoreOptions, s as RestoreResult } from "./restore-CbscKkNw.js";
 import { Document, ProjectValidationReport } from "@openfairygui/core";
 
 //#region src/adapters/node/publish.d.ts

package/dist/node.js

@@ -1,5 +1,5 @@
-import { _ as validateProject, m as formatPluginError, t as publish, u as resolveProjectBasePath } from "./publish-CyBj2o7n.js";
-import { t as restore } from "./restore-DVo1hXpN.js";
+import { _ as validateProject, m as formatPluginError, t as publish, u as resolveProjectBasePath } from "./publish-Cy09yjfn.js";
+import { t as restore } from "./restore-DB_L_xq4.js";
 import { createProjectValidationReport, liftDocumentToUamProject } from "@openfairygui/core";
 import { NodeIO } from "@openfairygui/core/node";
 //#region src/adapters/node/plugins.ts
@@ -18,16 +18,33 @@ async function loadPlugins(doc, pluginsDir) {
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
 		const pluginDir = path.join(pluginsDir, entry.name);
+		let manifest;
+		try {
+			manifest = await readPluginManifest(fs, path, pluginDir);
+		} catch (error) {
+			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+			continue;
+		}
+		if (!manifest) continue;
+		if (!manifest.main) {
+			const error = /* @__PURE__ */ new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
+			if (manifest.required) throw error;
+			doc.getLogger().warn(`publish: Plugin "${manifest.name}" was skipped: ${error.message}`);
+			continue;
+		}
 		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
+				plugin,
+				failureMode: manifest.required ? "abort" : manifest.failureMode
 			});
 		} catch (error) {
-			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+			if (!manifest.required && manifest.failureMode === "warn") {
+				doc.getLogger().warn(`publish: Plugin "${manifest.name}" was skipped: ${formatPluginError(error)}`);
+				continue;
+			}
+			throw new Error(`publish: Failed to load plugin "${manifest.name}": ${formatPluginError(error)}`);
 		}
 	}
 	return plugins;
@@ -37,7 +54,6 @@ async function readPluginManifest(fs, path, pluginDir) {
 	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) {
@@ -102,6 +118,77 @@ async function loadNodePublishPlugins(document, assetsPath) {
 	if (!projectDir) return [];
 	return loadPlugins(document, (await importNative$2("node:path")).join(projectDir, "plugins"));
 }
+async function publishToStagedOutput(output, run) {
+	const [fs, path, { randomUUID }] = await Promise.all([
+		importNative$2("node:fs/promises"),
+		importNative$2("node:path"),
+		importNative$2("node:crypto")
+	]);
+	const target = path.resolve(output);
+	const parent = path.dirname(target);
+	const name = path.basename(target);
+	const staging = path.join(parent, `.${name}.publish-${randomUUID()}`);
+	const backup = path.join(parent, `.${name}.publish-backup-${randomUUID()}`);
+	await fs.mkdir(parent, { recursive: true });
+	let existed = false;
+	try {
+		const stat = await fs.lstat(target);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`publishNode: output must be a regular directory: ${target}`);
+		await assertNoSymlinks(fs, path, target);
+		existed = true;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	try {
+		if (existed) await fs.cp(target, staging, {
+			recursive: true,
+			errorOnExist: true,
+			force: false
+		});
+		else await fs.mkdir(staging);
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	try {
+		await run(staging);
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	if (!existed) {
+		await fs.rename(staging, target);
+		return;
+	}
+	await fs.rename(target, backup);
+	try {
+		await fs.rename(staging, target);
+	} catch (error) {
+		await fs.rename(backup, target);
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	await fs.rm(backup, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+}
+async function assertNoSymlinks(fs, path, directory) {
+	for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isSymbolicLink()) throw new Error(`publishNode: symbolic links are not supported in output directories: ${entryPath}`);
+		if (entry.isDirectory()) await assertNoSymlinks(fs, path, entryPath);
+	}
+}
 /**
 * Publish a FairyGUI project through the standard Node host adapter.
 *
@@ -114,17 +201,25 @@ async function publishNode(options) {
 	const [fileSystem, assetsPath] = await Promise.all([createNodePublishFileSystem(), resolveNodeAssetsPath(document, configuredAssetsPath)]);
 	const [encoder, plugins] = await Promise.all([configuredEncoder === void 0 ? loadSharpBackend() : Promise.resolve(configuredEncoder), configuredPlugins === void 0 ? loadNodePublishPlugins(document, assetsPath) : Promise.resolve(configuredPlugins)]);
 	if (!encoder) throw new Error("publishNode: Sharp is required for a complete publish. Install sharp or provide an encoder.");
-	await document.transform(publish({
-		...publishOptions,
-		basePath: assetsPath,
-		encoder,
-		atlas: {
-			...atlas,
-			readFileRaw: fileSystem.readFileRaw
-		},
-		fs: fileSystem,
-		plugins
-	}));
+	const run = async (output) => {
+		await document.transform(publish({
+			...publishOptions,
+			output,
+			basePath: assetsPath,
+			encoder,
+			atlas: {
+				...atlas,
+				readFileRaw: fileSystem.readFileRaw
+			},
+			fs: fileSystem,
+			plugins
+		}));
+	};
+	if (publishOptions.output) {
+		await publishToStagedOutput(publishOptions.output, run);
+		return;
+	}
+	await run(void 0);
 }
 //#endregion
 //#region src/adapters/node/restore.ts
@@ -301,18 +396,21 @@ async function validateProjectNode(projectPath) {
 	}
 	const decodedPaths = new Set(images.map(({ packageIndex, resourceIndex }) => `packages[${packageIndex}].resources[${resourceIndex}]`));
 	diagnostics = diagnostics.filter((diagnostic) => diagnostic.code !== "decode_capability_unavailable" || !decodedPaths.has(diagnostic.path));
-	for (const { pkg, packageIndex, resource, resourceIndex } of images) try {
-		await sharp(resource.sourceBytes).raw().toBuffer();
-	} catch (error) {
-		diagnostics.push({
-			severity: "error",
-			code: "corrupt_source",
-			path: `packages[${packageIndex}].resources[${resourceIndex}]`,
-			message: `Image source cannot be decoded: ${error instanceof Error ? error.message : String(error)}`,
-			packageId: pkg.id,
-			resourceId: resource.id,
-			sourcePath: sourceName(resource)
-		});
+	for (const { pkg, packageIndex, resource, resourceIndex } of images) {
+		if (resource.kind !== "image") continue;
+		try {
+			await sharp(resource.sourceBytes).raw().toBuffer();
+		} catch (error) {
+			diagnostics.push({
+				severity: "error",
+				code: "corrupt_source",
+				path: `packages[${packageIndex}].resources[${resourceIndex}]`,
+				message: `Image source cannot be decoded: ${error instanceof Error ? error.message : String(error)}`,
+				packageId: pkg.id,
+				resourceId: resource.id,
+				sourcePath: sourceName(resource)
+			});
+		}
 	}
 	return createProjectValidationReport(diagnostics, read.complete && !diagnostics.some((diagnostic) => diagnostic.code === "decode_capability_unavailable"));
 }