@openfairygui/functions 0.3.0 → 0.3.1

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_publish = require("./publish-CxKatE3e.cjs");
-const require_restore = require("./restore-QScbHJ7Y.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-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-D6F1ELdM.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-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-BOfsCM47.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-BBoK-yeR.js";
-import { t as restore } from "./restore-DOcyfc0b.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-CxKatE3e.cjs");
-const require_restore = require("./restore-QScbHJ7Y.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

package/dist/node.d.cts

@@ -1,5 +1,5 @@
 import { r as AtlasRasterBackend } from "./atlas-CSqHsG0X.cjs";
-import { L as PublishOptions, S as LoadedPlugin, o as RestoreOptions, s as RestoreResult } from "./restore-D6F1ELdM.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-BtWa1DwO.js";
-import { L as PublishOptions, S as LoadedPlugin, o as RestoreOptions, s as RestoreResult } from "./restore-BOfsCM47.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-BBoK-yeR.js";
-import { t as restore } from "./restore-DOcyfc0b.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

package/dist/{publish-BBoK-yeR.js → publish-Cy09yjfn.js}

@@ -2439,6 +2439,9 @@ const FGUI_TYPESCRIPT_BINDER_TEMPLATE = `{{generatedMark}}
 function formatPluginError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function shouldAbortPluginFailure(plugin) {
+	return plugin.failureMode !== "warn";
+}
 //#endregion
 //#region src/path-utils.ts
 function trimTrailingSlashes(value) {
@@ -2524,7 +2527,9 @@ async function publishCodeGeneration(doc, 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)}`);
+				const message = `publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`;
+				if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+				logger.warn(message);
 			}
 		}
 		if (handled) return;
@@ -2995,7 +3000,9 @@ async function runPublishPluginHook(plugins, hook, doc, options) {
 		try {
 			await fn(doc, options);
 		} catch (error) {
-			logger.warn(`publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`);
+			const message = `publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`;
+			if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+			logger.warn(message);
 		}
 	}
 }

package/dist/{publish-CxKatE3e.cjs → publish-DhMv_lEP.cjs}

@@ -2439,6 +2439,9 @@ const FGUI_TYPESCRIPT_BINDER_TEMPLATE = `{{generatedMark}}
 function formatPluginError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function shouldAbortPluginFailure(plugin) {
+	return plugin.failureMode !== "warn";
+}
 //#endregion
 //#region src/path-utils.ts
 function trimTrailingSlashes(value) {
@@ -2524,7 +2527,9 @@ async function publishCodeGeneration(doc, 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)}`);
+				const message = `publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`;
+				if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+				logger.warn(message);
 			}
 		}
 		if (handled) return;
@@ -2995,7 +3000,9 @@ async function runPublishPluginHook(plugins, hook, doc, options) {
 		try {
 			await fn(doc, options);
 		} catch (error) {
-			logger.warn(`publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`);
+			const message = `publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`;
+			if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+			logger.warn(message);
 		}
 	}
 }

package/dist/{restore-BOfsCM47.d.ts → restore-CbscKkNw.d.ts}

@@ -166,6 +166,8 @@ interface PluginManifest {
   };
   icon?: string;
   main: string;
+  required?: boolean;
+  failureMode?: 'abort' | 'warn';
 }
 interface ICodeWriterConfig {
   blockStart?: string;
@@ -194,6 +196,7 @@ interface Plugin {
 interface LoadedPlugin {
   name: string;
   plugin: Plugin;
+  failureMode?: 'abort' | 'warn';
 }
 type PluginModule = Plugin & {
   default?: Plugin;

package/dist/{restore-DOcyfc0b.js → restore-DB_L_xq4.js}

@@ -1,4 +1,4 @@
-import { d as basename, f as normalizeComparablePath, p as trimTrailingSlashes } from "./publish-BBoK-yeR.js";
+import { d as basename, f as normalizeComparablePath, p as trimTrailingSlashes } from "./publish-Cy09yjfn.js";
 import { BinaryReader, ProjectType, ProjectWriter, generateId } from "@openfairygui/core";
 //#region src/restore-internals/output-transaction.ts
 function isPathWithin(root, candidate) {

package/dist/{restore-D6F1ELdM.d.cts → restore-k3oX26Fs.d.cts}

@@ -166,6 +166,8 @@ interface PluginManifest {
   };
   icon?: string;
   main: string;
+  required?: boolean;
+  failureMode?: 'abort' | 'warn';
 }
 interface ICodeWriterConfig {
   blockStart?: string;
@@ -194,6 +196,7 @@ interface Plugin {
 interface LoadedPlugin {
   name: string;
   plugin: Plugin;
+  failureMode?: 'abort' | 'warn';
 }
 type PluginModule = Plugin & {
   default?: Plugin;

package/dist/{restore-QScbHJ7Y.cjs → restore-n61oZ4nw.cjs}

@@ -1,4 +1,4 @@
-const require_publish = require("./publish-CxKatE3e.cjs");
+const require_publish = require("./publish-DhMv_lEP.cjs");
 let _openfairygui_core = require("@openfairygui/core");
 //#region src/restore-internals/output-transaction.ts
 function isPathWithin(root, candidate) {

package/dist/web.cjs

@@ -1,32 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_publish = require("./publish-CxKatE3e.cjs");
+const require_publish = require("./publish-DhMv_lEP.cjs");
 let _openfairygui_core = require("@openfairygui/core");
 let fast_xml_parser = require("fast-xml-parser");
 //#region src/adapters/web/raster.ts
-const MAX_SVG_SOURCE_BYTES = 8 * 1024 * 1024;
 const MAX_SVG_DIMENSION = 16384;
 const MAX_SVG_PIXELS = 64 * 1024 * 1024;
-const MAX_SVG_NODES = 5e4;
-const UNSAFE_SVG_ELEMENTS = new Set([
-	"a",
-	"animate",
-	"animatecolor",
-	"animatemotion",
-	"animatetransform",
-	"audio",
-	"canvas",
-	"discard",
-	"embed",
-	"feimage",
-	"foreignobject",
-	"iframe",
-	"image",
-	"object",
-	"script",
-	"set",
-	"style",
-	"video"
-]);
 function unsafeSvg(message) {
 	throw new Error(`publishBrowser: unsafe SVG input (${message}).`);
 }
@@ -41,47 +19,14 @@ function parseSvgLength(value, name) {
 	if (!Number.isFinite(parsed) || parsed <= 0 || parsed > MAX_SVG_DIMENSION) unsafeSvg(`${name} exceeds the supported dimensions`);
 	return parsed;
 }
-function validateSvgAttribute(name, value) {
-	const normalizedName = name.toLowerCase();
-	if (normalizedName === "xmlns" || normalizedName.startsWith("xmlns:")) return;
-	const localName = svgLocalName(name);
-	const text = String(value);
-	if (localName.startsWith("on")) unsafeSvg(`event attribute "${name}" is not allowed`);
-	if (localName === "style" || localName === "src") unsafeSvg(`attribute "${name}" is not allowed`);
-	if (localName === "href" && !/^#[A-Za-z_][\w:.-]*$/u.test(text)) unsafeSvg(`external reference in "${name}" is not allowed`);
-	if (/(?:^|[\s("'=])(?:https?:|file:|javascript:|data:|\/\/)/iu.test(text)) unsafeSvg(`external URL in "${name}" is not allowed`);
-	for (const match of text.matchAll(/url\s*\(([^)]*)\)/giu)) {
-		const reference = (match[1] ?? "").trim().replace(/^(['"])(.*)\1$/u, "$2");
-		if (!/^#[A-Za-z_][\w:.-]*$/u.test(reference)) unsafeSvg(`external url() in "${name}" is not allowed`);
-	}
-}
-function visitSvgEntry(entry) {
-	const pending = [entry];
-	let nodeCount = 0;
-	while (pending.length > 0) {
-		const current = pending.pop();
-		for (const [name, value] of Object.entries(current)) {
-			if (name === ":@" || name.startsWith("#") || name.startsWith("?")) continue;
-			if (++nodeCount > MAX_SVG_NODES) unsafeSvg("node count exceeds the supported limit");
-			const localName = svgLocalName(name);
-			if (UNSAFE_SVG_ELEMENTS.has(localName)) unsafeSvg(`element <${name}> is not allowed`);
-			for (const [attributeName, attributeValue] of Object.entries(current[":@"] ?? {})) validateSvgAttribute(attributeName, attributeValue);
-			if (Array.isArray(value)) {
-				for (const child of value) if (child && typeof child === "object" && !Array.isArray(child)) pending.push(child);
-			}
-		}
-	}
-}
 function validateSvg(bytes) {
-	if (bytes.byteLength === 0 || bytes.byteLength > MAX_SVG_SOURCE_BYTES) unsafeSvg("source size is unsupported");
-	let source;
 	try {
-		source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-	} catch {
-		unsafeSvg("source is not valid UTF-8");
+		validateSvgDimensions((0, _openfairygui_core.validateSafeSvgSource)(bytes));
+	} catch (error) {
+		unsafeSvg(error instanceof Error ? error.message : String(error));
 	}
-	if (/<!\s*(?:doctype|entity)\b|<\?xml-stylesheet\b/iu.test(source)) unsafeSvg("DTD, entities, and stylesheets are not allowed");
-	if (fast_xml_parser.XMLValidator.validate(source, { allowBooleanAttributes: false }) !== true) unsafeSvg("source is not well-formed XML");
+}
+function validateSvgDimensions(source) {
 	const roots = new fast_xml_parser.XMLParser({
 		preserveOrder: true,
 		ignoreAttributes: false,
@@ -95,9 +40,7 @@ function validateSvg(bytes) {
 		name
 	})));
 	if (roots.length !== 1 || svgLocalName(roots[0].name) !== "svg") unsafeSvg("a single <svg> root is required");
-	const root = roots[0].entry;
-	visitSvgEntry(root);
-	const attributes = root[":@"] ?? {};
+	const attributes = roots[0].entry[":@"] ?? {};
 	const width = parseSvgLength(attributes.width, "width");
 	const height = parseSvgLength(attributes.height, "height");
 	let viewBoxWidth;

package/dist/web.js

@@ -1,31 +1,9 @@
-import { _ as validateProject, c as resolveCodeGenerationSettings, n as resolvePublishOptions, t as publish } from "./publish-BBoK-yeR.js";
-import { ProjectType, createProjectValidationReport } from "@openfairygui/core";
-import { XMLParser, XMLValidator } from "fast-xml-parser";
+import { _ as validateProject, c as resolveCodeGenerationSettings, n as resolvePublishOptions, t as publish } from "./publish-Cy09yjfn.js";
+import { ProjectType, createProjectValidationReport, validateSafeSvgSource } from "@openfairygui/core";
+import { XMLParser } from "fast-xml-parser";
 //#region src/adapters/web/raster.ts
-const MAX_SVG_SOURCE_BYTES = 8 * 1024 * 1024;
 const MAX_SVG_DIMENSION = 16384;
 const MAX_SVG_PIXELS = 64 * 1024 * 1024;
-const MAX_SVG_NODES = 5e4;
-const UNSAFE_SVG_ELEMENTS = new Set([
-	"a",
-	"animate",
-	"animatecolor",
-	"animatemotion",
-	"animatetransform",
-	"audio",
-	"canvas",
-	"discard",
-	"embed",
-	"feimage",
-	"foreignobject",
-	"iframe",
-	"image",
-	"object",
-	"script",
-	"set",
-	"style",
-	"video"
-]);
 function unsafeSvg(message) {
 	throw new Error(`publishBrowser: unsafe SVG input (${message}).`);
 }
@@ -40,47 +18,14 @@ function parseSvgLength(value, name) {
 	if (!Number.isFinite(parsed) || parsed <= 0 || parsed > MAX_SVG_DIMENSION) unsafeSvg(`${name} exceeds the supported dimensions`);
 	return parsed;
 }
-function validateSvgAttribute(name, value) {
-	const normalizedName = name.toLowerCase();
-	if (normalizedName === "xmlns" || normalizedName.startsWith("xmlns:")) return;
-	const localName = svgLocalName(name);
-	const text = String(value);
-	if (localName.startsWith("on")) unsafeSvg(`event attribute "${name}" is not allowed`);
-	if (localName === "style" || localName === "src") unsafeSvg(`attribute "${name}" is not allowed`);
-	if (localName === "href" && !/^#[A-Za-z_][\w:.-]*$/u.test(text)) unsafeSvg(`external reference in "${name}" is not allowed`);
-	if (/(?:^|[\s("'=])(?:https?:|file:|javascript:|data:|\/\/)/iu.test(text)) unsafeSvg(`external URL in "${name}" is not allowed`);
-	for (const match of text.matchAll(/url\s*\(([^)]*)\)/giu)) {
-		const reference = (match[1] ?? "").trim().replace(/^(['"])(.*)\1$/u, "$2");
-		if (!/^#[A-Za-z_][\w:.-]*$/u.test(reference)) unsafeSvg(`external url() in "${name}" is not allowed`);
-	}
-}
-function visitSvgEntry(entry) {
-	const pending = [entry];
-	let nodeCount = 0;
-	while (pending.length > 0) {
-		const current = pending.pop();
-		for (const [name, value] of Object.entries(current)) {
-			if (name === ":@" || name.startsWith("#") || name.startsWith("?")) continue;
-			if (++nodeCount > MAX_SVG_NODES) unsafeSvg("node count exceeds the supported limit");
-			const localName = svgLocalName(name);
-			if (UNSAFE_SVG_ELEMENTS.has(localName)) unsafeSvg(`element <${name}> is not allowed`);
-			for (const [attributeName, attributeValue] of Object.entries(current[":@"] ?? {})) validateSvgAttribute(attributeName, attributeValue);
-			if (Array.isArray(value)) {
-				for (const child of value) if (child && typeof child === "object" && !Array.isArray(child)) pending.push(child);
-			}
-		}
-	}
-}
 function validateSvg(bytes) {
-	if (bytes.byteLength === 0 || bytes.byteLength > MAX_SVG_SOURCE_BYTES) unsafeSvg("source size is unsupported");
-	let source;
 	try {
-		source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-	} catch {
-		unsafeSvg("source is not valid UTF-8");
+		validateSvgDimensions(validateSafeSvgSource(bytes));
+	} catch (error) {
+		unsafeSvg(error instanceof Error ? error.message : String(error));
 	}
-	if (/<!\s*(?:doctype|entity)\b|<\?xml-stylesheet\b/iu.test(source)) unsafeSvg("DTD, entities, and stylesheets are not allowed");
-	if (XMLValidator.validate(source, { allowBooleanAttributes: false }) !== true) unsafeSvg("source is not well-formed XML");
+}
+function validateSvgDimensions(source) {
 	const roots = new XMLParser({
 		preserveOrder: true,
 		ignoreAttributes: false,
@@ -94,9 +39,7 @@ function validateSvg(bytes) {
 		name
 	})));
 	if (roots.length !== 1 || svgLocalName(roots[0].name) !== "svg") unsafeSvg("a single <svg> root is required");
-	const root = roots[0].entry;
-	visitSvgEntry(root);
-	const attributes = root[":@"] ?? {};
+	const attributes = roots[0].entry[":@"] ?? {};
 	const width = parseSvgLength(attributes.width, "width");
 	const height = parseSvgLength(attributes.height, "height");
 	let viewBoxWidth;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/functions",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "FairyGUI Headless Authoring SDK — composable transform functions.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -13,6 +13,9 @@
   "bugs": {
     "url": "https://github.com/OpenFairyGUI/OpenFairyGUI/issues"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.cjs",
@@ -75,7 +78,7 @@
   "dependencies": {
     "fast-xml-parser": "^5.0.0",
     "jiti": "^2.6.1",
-    "@openfairygui/core": "0.3.0"
+    "@openfairygui/core": "0.3.1"
   },
   "optionalDependencies": {
     "sharp": ">=0.33.0"

package/src/adapters/node/plugins.ts

@@ -7,10 +7,7 @@ import {
 	type PluginModule,
 } from '../../plugins/types.js';
 
-interface PluginPackageJson extends Partial<PluginManifest> {
-	name?: string;
-	main?: string;
-}
+interface PluginPackageJson extends Partial<PluginManifest> {}
 
 // Keep Node builtins out of the neutral bundle resolver while still loading plugins in Node.
 const importNative = new Function('id', 'return import(id)') as <T>(id: string) => Promise<T>;
@@ -31,15 +28,35 @@ export async function loadPlugins(doc: Document, pluginsDir: string): Promise<Lo
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
 		const pluginDir = path.join(pluginsDir, entry.name);
+		let manifest: PluginManifest | null;
 		try {
-			const manifest = await readPluginManifest(fs, path, pluginDir);
-			if (!manifest) continue;
+			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 = 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 mainPath = resolvePluginMain(path, pluginDir, manifest);
 			const plugin = await loadPlugin(mainPath);
-			plugins.push({ name: manifest.name, plugin });
+			plugins.push({
+				name: manifest.name,
+				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)}`);
 		}
 	}
 
@@ -55,7 +72,6 @@ async function readPluginManifest(
 	const content = await fs.readFile(manifestPath, 'utf-8');
 	const manifest = JSON.parse(content) as PluginPackageJson;
 	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 as PluginManifest;
 }
 

package/src/adapters/node/publish.ts

@@ -83,6 +83,70 @@ async function loadNodePublishPlugins(document: Document, assetsPath: string | u
 	return loadPlugins(document, path.join(projectDir, 'plugins'));
 }
 
+async function publishToStagedOutput(output: string, run: (staging: string) => Promise<void>): Promise<void> {
+	const [fs, path, { randomUUID }] = await Promise.all([
+		importNative<typeof import('node:fs/promises')>('node:fs/promises'),
+		importNative<typeof import('node:path')>('node:path'),
+		importNative<typeof import('node:crypto')>('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 as NodeJS.ErrnoException).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;
+	}
+
+	// ponytail: two-step rename preserves rollback; use directory exchange if zero reader gap becomes required.
+	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(() => undefined);
+}
+
+async function assertNoSymlinks(
+	fs: typeof import('node:fs/promises'),
+	path: typeof import('node:path'),
+	directory: string,
+): Promise<void> {
+	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,9 +178,10 @@ export async function publishNode(options: PublishNodeOptions): Promise<void> {
 		throw new Error('publishNode: Sharp is required for a complete publish. Install sharp or provide an encoder.');
 	}
 
-	await document.transform(
-		publish({
+	const run = async (output: string | undefined): Promise<void> => {
+		await document.transform(publish({
 			...publishOptions,
+			output,
 			basePath: assetsPath,
 			encoder,
 			atlas: {
@@ -125,6 +190,11 @@ export async function publishNode(options: PublishNodeOptions): Promise<void> {
 			},
 			fs: fileSystem,
 			plugins,
-		}),
-	);
+		}));
+	};
+	if (publishOptions.output) {
+		await publishToStagedOutput(publishOptions.output, run);
+		return;
+	}
+	await run(undefined);
 }

package/src/adapters/web/raster.ts

@@ -6,7 +6,8 @@ import type {
 	PublishFileSystem,
 	PublishSourceFileSystem,
 } from '../../publish/contracts.js';
-import { XMLParser, XMLValidator } from 'fast-xml-parser';
+import { validateSafeSvgSource } from '@openfairygui/core';
+import { XMLParser } from 'fast-xml-parser';
 
 type BrowserCanvas = OffscreenCanvas | HTMLCanvasElement;
 
@@ -41,30 +42,8 @@ interface BrowserRaster {
 	height: number;
 }
 
-const MAX_SVG_SOURCE_BYTES = 8 * 1024 * 1024;
 const MAX_SVG_DIMENSION = 16_384;
 const MAX_SVG_PIXELS = 64 * 1024 * 1024;
-const MAX_SVG_NODES = 50_000;
-const UNSAFE_SVG_ELEMENTS = new Set([
-	'a',
-	'animate',
-	'animatecolor',
-	'animatemotion',
-	'animatetransform',
-	'audio',
-	'canvas',
-	'discard',
-	'embed',
-	'feimage',
-	'foreignobject',
-	'iframe',
-	'image',
-	'object',
-	'script',
-	'set',
-	'style',
-	'video',
-]);
 
 type ParsedSvgEntry = Record<string, unknown> & { ':@'?: Record<string, unknown> };
 
@@ -87,57 +66,16 @@ function parseSvgLength(value: unknown, name: string): number | undefined {
 	return parsed;
 }
 
-function validateSvgAttribute(name: string, value: unknown): void {
-	const normalizedName = name.toLowerCase();
-	if (normalizedName === 'xmlns' || normalizedName.startsWith('xmlns:')) return;
-	const localName = svgLocalName(name);
-	const text = String(value);
-	if (localName.startsWith('on')) unsafeSvg(`event attribute "${name}" is not allowed`);
-	if (localName === 'style' || localName === 'src') unsafeSvg(`attribute "${name}" is not allowed`);
-	if (localName === 'href' && !/^#[A-Za-z_][\w:.-]*$/u.test(text)) {
-		unsafeSvg(`external reference in "${name}" is not allowed`);
-	}
-	if (/(?:^|[\s("'=])(?:https?:|file:|javascript:|data:|\/\/)/iu.test(text)) {
-		unsafeSvg(`external URL in "${name}" is not allowed`);
-	}
-	for (const match of text.matchAll(/url\s*\(([^)]*)\)/giu)) {
-		const reference = (match[1] ?? '').trim().replace(/^(['"])(.*)\1$/u, '$2');
-		if (!/^#[A-Za-z_][\w:.-]*$/u.test(reference)) unsafeSvg(`external url() in "${name}" is not allowed`);
-	}
-}
-
-function visitSvgEntry(entry: ParsedSvgEntry): void {
-	const pending = [entry];
-	let nodeCount = 0;
-	while (pending.length > 0) {
-		const current = pending.pop()!;
-		for (const [name, value] of Object.entries(current)) {
-			if (name === ':@' || name.startsWith('#') || name.startsWith('?')) continue;
-			if (++nodeCount > MAX_SVG_NODES) unsafeSvg('node count exceeds the supported limit');
-			const localName = svgLocalName(name);
-			if (UNSAFE_SVG_ELEMENTS.has(localName)) unsafeSvg(`element <${name}> is not allowed`);
-			for (const [attributeName, attributeValue] of Object.entries(current[':@'] ?? {})) {
-				validateSvgAttribute(attributeName, attributeValue);
-			}
-			if (Array.isArray(value)) {
-				for (const child of value) {
-					if (child && typeof child === 'object' && !Array.isArray(child)) pending.push(child as ParsedSvgEntry);
-				}
-			}
-		}
-	}
-}
-
 function validateSvg(bytes: Uint8Array): void {
-	if (bytes.byteLength === 0 || bytes.byteLength > MAX_SVG_SOURCE_BYTES) unsafeSvg('source size is unsupported');
-	let source: string;
 	try {
-		source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
-	} catch {
-		unsafeSvg('source is not valid UTF-8');
+		const source = validateSafeSvgSource(bytes);
+		validateSvgDimensions(source);
+	} catch (error) {
+		unsafeSvg(error instanceof Error ? error.message : String(error));
 	}
-	if (/<!\s*(?:doctype|entity)\b|<\?xml-stylesheet\b/iu.test(source)) unsafeSvg('DTD, entities, and stylesheets are not allowed');
-	if (XMLValidator.validate(source, { allowBooleanAttributes: false }) !== true) unsafeSvg('source is not well-formed XML');
+}
+
+function validateSvgDimensions(source: string): void {
 	const parsed = new XMLParser({
 		preserveOrder: true,
 		ignoreAttributes: false,
@@ -152,7 +90,6 @@ function validateSvg(bytes: Uint8Array): void {
 		.map((name) => ({ entry, name })));
 	if (roots.length !== 1 || svgLocalName(roots[0]!.name) !== 'svg') unsafeSvg('a single <svg> root is required');
 	const root = roots[0]!.entry;
-	visitSvgEntry(root);
 	const attributes = root[':@'] ?? {};
 	const width = parseSvgLength(attributes.width, 'width');
 	const height = parseSvgLength(attributes.height, 'height');

package/src/codegen.ts

@@ -12,7 +12,7 @@ import {
 	UNITY_BINDER_TEMPLATE,
 	UNITY_COMPONENT_TEMPLATE,
 } from './codegen-templates.js';
-import { formatPluginError, type LoadedPlugin } from './plugins/types.js';
+import { formatPluginError, type LoadedPlugin, shouldAbortPluginFailure } from './plugins/types.js';
 import { dirname, isAbsolutePathLike, trimTrailingSlashes } from './path-utils.js';
 import type { PublishFileSystem } from './publish/contracts.js';
 import type { CliCodeGenerationSettings, RootProjectSettings } from './shared-types.js';
@@ -119,7 +119,9 @@ export async function publishCodeGeneration(doc: Document, options: PublishCodeG
 				handled = true;
 				logger.info(`publish: Generated code using plugin "${plugin.name}"`);
 			} catch (error) {
-				logger.warn(`publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`);
+				const message = `publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`;
+				if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+				logger.warn(message);
 			}
 		}
 		if (handled) {

package/src/plugins/types.ts

@@ -15,6 +15,8 @@ export interface PluginManifest {
 	};
 	icon?: string;
 	main: string;
+	required?: boolean;
+	failureMode?: 'abort' | 'warn';
 }
 
 export interface ICodeWriterConfig {
@@ -47,6 +49,7 @@ export interface Plugin {
 export interface LoadedPlugin {
 	name: string;
 	plugin: Plugin;
+	failureMode?: 'abort' | 'warn';
 }
 
 export type PluginModule = Plugin & { default?: Plugin };
@@ -54,3 +57,7 @@ export type PluginModule = Plugin & { default?: Plugin };
 export function formatPluginError(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
+
+export function shouldAbortPluginFailure(plugin: LoadedPlugin): boolean {
+	return plugin.failureMode !== 'warn';
+}

package/src/publish.ts

@@ -13,7 +13,7 @@ import { prepareMovieClipResource } from './atlas/inputs.js';
 import type { PreparedJtaData } from './atlas/jta.js';
 import { publishCodeGeneration, resolveProjectBasePath } from './codegen.js';
 import { dirname, isAbsolutePathLike, trimTrailingSlashes } from './path-utils.js';
-import { formatPluginError, type LoadedPlugin } from './plugins/types.js';
+import { formatPluginError, type LoadedPlugin, shouldAbortPluginFailure } from './plugins/types.js';
 import type { PublishFileSystem } from './publish/contracts.js';
 import {
 	annotatePackagePublishArtifacts,
@@ -75,7 +75,9 @@ async function runPublishPluginHook(
 		try {
 			await fn(doc, options);
 		} catch (error) {
-			logger.warn(`publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`);
+			const message = `publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`;
+			if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+			logger.warn(message);
 		}
 	}
 }