@openfairygui/functions 0.2.0-alpha.13 → 0.2.0-alpha.15

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as decodeText, c as resolvePackageCodegenPlan, d as atlas, f as createTransform, i as buildCodegenClasses, n as resolvePublishOptions, o as encodeText, r as AUTO_GENERATED_CODE_MARK, s as publishCodeGeneration, t as publish } from "./publish-Bl-GK9kt.js";
+import { a as decodeText, c as resolvePackageCodegenPlan, d as atlas, f as createTransform, i as buildCodegenClasses, n as resolvePublishOptions, o as encodeText, r as AUTO_GENERATED_CODE_MARK, s as publishCodeGeneration, t as publish } from "./publish-DsPK0SJ1.js";
 import { applyUamTransactionApp } from "./uam-transaction.js";
 import { BinaryReader, ProjectType, ProjectWriter, generateId } from "@openfairygui/core";
 //#region src/inspect.ts
@@ -392,10 +392,16 @@ const TRANSPARENT_PNG_1X1 = Uint8Array.from([
 	96,
 	130
 ]);
+function assertSafeRestoreSegment(value, label) {
+	if (!value || value === "." || value === ".." || value.includes("\0") || /[\\/:]/u.test(value)) throw new Error(`restore: Invalid ${label} "${value}".`);
+}
 function normalizeVirtualPath(path) {
-	const normalized = (path ?? "").replace(/\\/g, "/").trim();
-	if (!normalized || normalized === "/") return "";
-	return normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+	const raw = (path ?? "").trim();
+	if (!raw || raw === "/") return "";
+	if (raw.includes("\0") || raw.startsWith("\\") || raw.startsWith("//") || /^[a-z]:/iu.test(raw)) throw new Error(`restore: Invalid resource path "${raw}".`);
+	const segments = raw.replace(/\\/g, "/").split("/").filter(Boolean);
+	if (segments.some((segment) => segment === "." || segment === ".." || segment.includes(":"))) throw new Error(`restore: Invalid resource path "${raw}".`);
+	return segments.join("/");
 }
 function resourceFileName(resource) {
 	return resource.getFileName?.() || resource.getFile?.() || resource.getName?.() || "";
@@ -579,44 +585,40 @@ function normalizeComparablePath(value) {
 	const joined = segments.join("/");
 	return (drivePrefix ? `${drivePrefix}/${joined}`.replace(/\/$/, "") : hasRoot ? `/${joined}`.replace(/\/$/, "") : joined || ".").toLowerCase();
 }
-function dirname(filePath) {
-	return trimTrailingSlashes(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
+function isPathWithin(root, candidate) {
+	const normalizedRoot = normalizeComparablePath(root);
+	return normalizeComparablePath(candidate).startsWith(`${normalizedRoot}/`);
 }
 function basename(filePath) {
 	return trimTrailingSlashes(filePath).match(/([^/\\]+)$/)?.[1] ?? "";
 }
-function resolveOutputProjectPath(output, fs) {
-	if (/\.fairy$/i.test(output)) return output;
-	const normalizedOutput = trimTrailingSlashes(output);
-	const projectName = basename(normalizedOutput) || "Restored";
-	return fs.join(normalizedOutput, `${projectName}.fairy`);
+function normalizeRestoreOutputDir(output) {
+	const normalized = trimTrailingSlashes(output);
+	const name = basename(normalized);
+	if (!normalized || /\.fairy$/i.test(normalized) || !name || name === "." || name === ".." || /^[a-z]:$/iu.test(name)) throw new Error("restore: Output must be a non-root project directory, not a .fairy file.");
+	return normalized;
 }
-async function prepareRestoreOutputDir(inputDir, outputDir, outputProjectPath, fs, force, outputIsProjectFile) {
-	const [resolvedInputDir, resolvedOutputDir] = await Promise.all([Promise.resolve(fs.resolvePath(inputDir)), Promise.resolve(fs.resolvePath(outputDir))]);
-	if (normalizeComparablePath(resolvedInputDir) === normalizeComparablePath(resolvedOutputDir)) throw new Error("Restore output directory must be different from the published input directory.");
-	if (outputIsProjectFile) {
-		if (!await fs.exists(outputDir)) {
-			await fs.mkdir(outputDir);
-			return;
-		}
-		try {
-			await fs.readdir(outputDir);
-		} catch {
-			throw new Error(`Restore output path is not a directory: ${outputDir}`);
-		}
-		if (!await fs.exists(outputProjectPath)) return;
-		if (!force) throw new Error(`Restore output file already exists: ${outputProjectPath}. Use --force to overwrite it.`);
-		if (!fs.rm) throw new Error("Restore output file already exists and the provided fs does not support rm(...).");
-		await fs.rm(outputProjectPath, {
-			recursive: true,
-			force: true
-		});
-		return;
-	}
-	if (!await fs.exists(outputDir)) {
-		await fs.mkdir(outputDir);
-		return;
+function resolveOutputProjectPath(outputDir, fs) {
+	return fs.join(outputDir, `${basename(outputDir)}.fairy`);
+}
+async function resolvePathForContainment(filePath, fs) {
+	const missingSegments = [];
+	let existingPath = filePath;
+	while (!await fs.exists(existingPath)) {
+		const parentPath = fs.dirname(existingPath);
+		if (!parentPath || parentPath === existingPath) return Promise.resolve(fs.resolvePath(filePath));
+		missingSegments.unshift(basename(existingPath));
+		existingPath = parentPath;
 	}
+	const resolvedExistingPath = await Promise.resolve(fs.resolvePath(existingPath));
+	return missingSegments.reduce((resolvedPath, segment) => fs.join(resolvedPath, segment), resolvedExistingPath);
+}
+async function assertRestoreOutputDir(inputDir, outputDir, fs, force) {
+	const [resolvedInputDir, resolvedOutputDir] = await Promise.all([resolvePathForContainment(inputDir, fs), resolvePathForContainment(outputDir, fs)]);
+	const normalizedInputDir = normalizeComparablePath(resolvedInputDir);
+	const normalizedOutputDir = normalizeComparablePath(resolvedOutputDir);
+	if (normalizedInputDir === normalizedOutputDir || isPathWithin(normalizedInputDir, normalizedOutputDir) || isPathWithin(normalizedOutputDir, normalizedInputDir)) throw new Error("Restore output directory must be independent from the published input directory.");
+	if (!await fs.exists(outputDir)) return;
 	let entries;
 	try {
 		entries = await fs.readdir(outputDir);
@@ -625,23 +627,63 @@ async function prepareRestoreOutputDir(inputDir, outputDir, outputProjectPath, f
 	}
 	if (entries.length === 0) return;
 	if (!force) throw new Error(`Restore output directory is not empty: ${outputDir}. Use --force to overwrite it.`);
-	if (!fs.rm) throw new Error("Restore output directory is not empty and the provided fs does not support rm(...).");
-	await fs.rm(outputDir, {
-		recursive: true,
-		force: true
-	});
-	await fs.mkdir(outputDir);
+}
+async function createRestoreStagingDir(outputDir, fs) {
+	const parentDir = fs.dirname(outputDir) || ".";
+	await fs.mkdir(parentDir);
+	for (let attempt = 0; attempt < 8; attempt += 1) {
+		const stagingDir = fs.join(parentDir, `.${basename(outputDir)}.restore-${generateId()}`);
+		if (await fs.exists(stagingDir)) continue;
+		await fs.mkdir(stagingDir);
+		return stagingDir;
+	}
+	throw new Error(`restore: Could not allocate a staging directory beside ${outputDir}.`);
+}
+async function commitRestoreOutput(stagingDir, outputDir, fs) {
+	if (!await fs.exists(outputDir)) {
+		await fs.rename(stagingDir, outputDir);
+		return null;
+	}
+	const parentDir = fs.dirname(outputDir) || ".";
+	let backupDir = "";
+	for (let attempt = 0; attempt < 8; attempt += 1) {
+		const candidate = fs.join(parentDir, `.${basename(outputDir)}.restore-backup-${generateId()}`);
+		if (!await fs.exists(candidate)) {
+			backupDir = candidate;
+			break;
+		}
+	}
+	if (!backupDir) throw new Error(`restore: Could not allocate a backup directory beside ${outputDir}.`);
+	await fs.rename(outputDir, backupDir);
+	try {
+		await fs.rename(stagingDir, outputDir);
+	} catch (error) {
+		await fs.rename(backupDir, outputDir);
+		throw error;
+	}
+	try {
+		await fs.rm(backupDir, {
+			recursive: true,
+			force: true
+		});
+		return null;
+	} catch {
+		return `restore: Previous output retained at ${backupDir}; remove it after checking the restored project.`;
+	}
 }
 async function restore(options) {
 	const sourceDir = trimTrailingSlashes(options.inputDir);
-	const outputIsProjectFile = /\.fairy$/i.test(options.output);
-	const outputProjectPath = resolveOutputProjectPath(options.output, options.fs);
-	await prepareRestoreOutputDir(sourceDir, dirname(outputProjectPath) || ".", outputProjectPath, options.fs, options.force === true, outputIsProjectFile);
+	const outputDir = normalizeRestoreOutputDir(options.output);
+	const outputProjectPath = resolveOutputProjectPath(outputDir, options.fs);
+	await assertRestoreOutputDir(sourceDir, outputDir, options.fs, options.force === true);
 	const packageFilter = options.packages?.length ? new Set(options.packages) : null;
-	const candidateBinaryPaths = (await options.fs.readdir(sourceDir)).filter((name) => isPublishedBinaryFile(name)).filter((name) => !packageFilter || packageFilter.has(inferPackageName(name))).map((name) => options.fs.join(sourceDir, name)).sort((left, right) => left.localeCompare(right));
+	const binaryNames = (await options.fs.readdir(sourceDir)).filter((name) => isPublishedBinaryFile(name)).filter((name) => !packageFilter || packageFilter.has(inferPackageName(name)));
+	for (const binaryName of binaryNames) assertSafeRestoreSegment(binaryName, "published binary file name");
+	const candidateBinaryPaths = binaryNames.map((name) => options.fs.join(sourceDir, name)).sort((left, right) => left.localeCompare(right));
 	const binaryPaths = (await Promise.all(candidateBinaryPaths.map(async (filePath) => await options.fs.isFile(filePath) ? filePath : null))).filter((filePath) => !!filePath).sort((left, right) => left.localeCompare(right));
 	if (binaryPaths.length === 0) throw new Error(`No FairyGUI published binary files found in ${sourceDir}.`);
-	return new RestoreWorkflow(options.fs).restore({
+	const restorer = new RestoreWorkflow(options.fs);
+	const document = await restorer.prepare({
 		binaryPaths,
 		sourceDir,
 		outputProjectPath,
@@ -649,18 +691,45 @@ async function restore(options) {
 		cropImage: options.cropImage,
 		extractImage: options.extractImage
 	});
+	const stagingDir = await createRestoreStagingDir(outputDir, options.fs);
+	const stagingProjectPath = options.fs.join(stagingDir, basename(outputProjectPath));
+	const warnings = [];
+	try {
+		await restorer.write(document, {
+			binaryPaths,
+			sourceDir,
+			outputProjectPath: stagingProjectPath,
+			projectType: options.projectType,
+			cropImage: options.cropImage,
+			extractImage: options.extractImage
+		}, warnings);
+		const cleanupWarning = await commitRestoreOutput(stagingDir, outputDir, options.fs);
+		if (cleanupWarning) warnings.push(cleanupWarning);
+	} catch (error) {
+		await options.fs.rm(stagingDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		throw error;
+	}
+	return {
+		document,
+		projectPath: outputProjectPath,
+		warnings
+	};
 }
 var RestoreWorkflow = class {
 	_fs;
 	constructor(fs) {
 		this._fs = fs;
 	}
-	async restore(options) {
-		const warnings = [];
+	async prepare(options) {
 		const doc = await new BinaryReader(this._fs).readMany(options.binaryPaths);
+		this._assertDocumentPaths(doc);
 		this._initializeProjectDefaults(doc, options.projectType);
 		this._initializeImageFileNames(doc);
 		this._initializeLooseResourceFileNames(doc);
+		this._assertDocumentPaths(doc);
 		await this._synthesizeLooseSkeletonResources(doc, options.sourceDir);
 		this._initializeRestoredResourceRelations(doc);
 		this._initializePublishedFontTextureIds(doc);
@@ -669,13 +738,27 @@ var RestoreWorkflow = class {
 		this._initializePublishedTextFontResources(doc);
 		this._initializeDisplayObjectFileNames(doc);
 		this._initializePublishedFontDefaults(doc);
+		this._assertDocumentPaths(doc);
+		return doc;
+	}
+	async write(doc, options, warnings) {
 		await new ProjectWriter(this._fs).write(doc, options.outputProjectPath);
 		await this._restoreAssets(doc, options, warnings);
-		return {
-			document: doc,
-			projectPath: options.outputProjectPath,
-			warnings
-		};
+	}
+	_assertDocumentPaths(doc) {
+		for (const pkg of doc.getRoot().listPackages()) {
+			assertSafeRestoreSegment(pkg.getName(), "package name");
+			assertSafeRestoreSegment(pkg.getPublishName() || pkg.getName(), "package publish name");
+			for (const resource of pkg.listResources()) {
+				normalizeVirtualPath(resource.getPath?.());
+				const branch = resource.getBranch?.() ?? "";
+				if (branch) assertSafeRestoreSegment(branch, "branch name");
+				const fileName = resourceFileName(resource);
+				if (fileName) assertSafeRestoreSegment(fileName, "resource file name");
+				const publishedFileName = resourcePublishedFileName(resource);
+				if (publishedFileName) assertSafeRestoreSegment(publishedFileName, "published resource file name");
+			}
+		}
 	}
 	_initializeProjectDefaults(doc, projectType) {
 		doc.getRoot().setProjectId(generateId()).setProjectType(projectType ?? ProjectType.Unity).setVersion("3.0").setSettings({
@@ -1109,27 +1192,40 @@ var RestoreWorkflow = class {
 	}
 	_sourceFileCandidates(pkg, fileName, outputFileName = fileName) {
 		const publishName = pkg.getPublishName() || pkg.getName();
-		return Array.from(new Set([
+		assertSafeRestoreSegment(publishName, "package publish name");
+		assertSafeRestoreSegment(fileName, "published source file name");
+		assertSafeRestoreSegment(outputFileName, "published source file name");
+		const candidates = Array.from(new Set([
 			`${publishName}_${fileName}`,
 			fileName,
 			`${publishName}_${outputFileName}`,
 			outputFileName
 		]));
+		for (const candidate of candidates) assertSafeRestoreSegment(candidate, "published source file name");
+		return candidates;
 	}
 	async _resolveLooseSourceFile(pkg, sourceDir, outputFileName) {
 		const candidates = outputFileName.endsWith(".atlas") ? this._sourceFileCandidates(pkg, `${outputFileName}.txt`, outputFileName) : outputFileName.endsWith(".skel") ? this._sourceFileCandidates(pkg, `${outputFileName}.bytes`, outputFileName) : this._sourceFileCandidates(pkg, outputFileName);
 		return this._resolveSourceFile(sourceDir, candidates);
 	}
 	async _resolveSourceFile(sourceDir, candidates) {
+		const resolvedSourceDir = await Promise.resolve(this._fs.resolvePath(sourceDir));
 		for (const candidate of candidates) {
+			assertSafeRestoreSegment(candidate, "published source file name");
 			const sourcePath = this._fs.join(sourceDir, candidate);
-			if (await this._fs.isFile(sourcePath)) return sourcePath;
+			if (!await this._fs.isFile(sourcePath)) continue;
+			const resolvedSourcePath = await Promise.resolve(this._fs.resolvePath(sourcePath));
+			if (!isPathWithin(resolvedSourceDir, resolvedSourcePath)) throw new Error(`restore: Published source file resolves outside the input directory: ${candidate}.`);
+			return resolvedSourcePath;
 		}
 		return null;
 	}
 	_resourceOutputPath(outputProjectPath, pkg, resource, fileName) {
 		const basePath = this._fs.dirname(outputProjectPath);
 		const branch = resource.getBranch?.() ?? "";
+		assertSafeRestoreSegment(pkg.getName(), "package name");
+		if (branch) assertSafeRestoreSegment(branch, "branch name");
+		assertSafeRestoreSegment(fileName, "resource file name");
 		const assetsDir = branch ? `assets_${branch}` : "assets";
 		const virtualPath = normalizeVirtualPath(resource.getPath?.());
 		const pkgDir = this._fs.join(basePath, assetsDir, pkg.getName());

package/dist/node.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_publish = require("./publish-CtCXsMdj.cjs");
+const require_publish = require("./publish-D7268_u4.cjs");
 //#region src/adapters/node/plugins.ts
 const importNative$1 = new Function("id", "return import(id)");
 async function loadPlugins(doc, pluginsDir) {
@@ -89,8 +89,8 @@ async function resolveNodeAssetsPath(document, assetsPath) {
 }
 async function loadSharpBackend() {
 	try {
-		const sharp = await importNative("sharp");
-		return sharp.default ?? sharp;
+		const loaded = await importNative("sharp");
+		return loaded.default ?? loaded;
 	} catch {
 		return;
 	}
@@ -111,7 +111,7 @@ async function publishNode(options) {
 	const { document, assetsPath: configuredAssetsPath, atlas, encoder: configuredEncoder, plugins: configuredPlugins, ...publishOptions } = 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) document.getLogger().warn("publish: Sharp is unavailable; atlas layout will be generated without PNG output.");
+	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,

package/dist/node.d.cts

@@ -1,5 +1,5 @@
 import { r as AtlasRasterBackend } from "./atlas-CHsu2Y8i.cjs";
-import { O as PublishOptions, m as LoadedPlugin } from "./codegen-C7PPZrB3.cjs";
+import { O as PublishOptions, m as LoadedPlugin } from "./codegen-B8ZM1F4j.cjs";
 import { Document } 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-CDn6TirX.js";
-import { O as PublishOptions, m as LoadedPlugin } from "./codegen-CEnmtjBP.js";
+import { O as PublishOptions, m as LoadedPlugin } from "./codegen-CfbDHuFt.js";
 import { Document } from "@openfairygui/core";
 
 //#region src/adapters/node/publish.d.ts

package/dist/node.js

@@ -1,4 +1,4 @@
-import { l as resolveProjectBasePath, t as publish, u as formatPluginError } from "./publish-Bl-GK9kt.js";
+import { l as resolveProjectBasePath, t as publish, u as formatPluginError } from "./publish-DsPK0SJ1.js";
 //#region src/adapters/node/plugins.ts
 const importNative$1 = new Function("id", "return import(id)");
 async function loadPlugins(doc, pluginsDir) {
@@ -88,8 +88,8 @@ async function resolveNodeAssetsPath(document, assetsPath) {
 }
 async function loadSharpBackend() {
 	try {
-		const sharp = await importNative("sharp");
-		return sharp.default ?? sharp;
+		const loaded = await importNative("sharp");
+		return loaded.default ?? loaded;
 	} catch {
 		return;
 	}
@@ -110,7 +110,7 @@ async function publishNode(options) {
 	const { document, assetsPath: configuredAssetsPath, atlas, encoder: configuredEncoder, plugins: configuredPlugins, ...publishOptions } = 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) document.getLogger().warn("publish: Sharp is unavailable; atlas layout will be generated without PNG output.");
+	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,

package/dist/{publish-CtCXsMdj.cjs → publish-D7268_u4.cjs}

@@ -751,7 +751,8 @@ const ATLAS_DEFAULTS = {
 	preserveInputOrderOnTie: false,
 	directSingleImageOutput: false,
 	extractAlpha: false,
-	separatedAtlasForBranch: false
+	separatedAtlasForBranch: false,
+	strictOutput: false
 };
 function getPublishedItemId(resource) {
 	return (resource.getExtras() ?? {})._publishedId ?? resource.getId();
@@ -908,8 +909,9 @@ function atlas(_options = {}) {
 		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 publishedResourceIds = pkg.getExtras()?.publishedResourceIds;
+			const selectedPublishIds = new Set(publishedResourceIds);
+			const allResources = publishedResourceIds !== void 0 && (options.strictOutput || 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])));
@@ -998,6 +1000,7 @@ function atlas(_options = {}) {
 				await _collectFontTexture(doc, res, pkg, options);
 			}
 			if (inputs.length === 0) continue;
+			if (options.strictOutput && (!encoder || !options.basePath || !options.outputPath)) throw new Error(`atlas: Package "${pkg.getName()}" requires encoder, basePath, and outputPath for complete raster output.`);
 			let totalPageCount = 0;
 			let usedDirectOutput = false;
 			const { autoInputs, fixedPageGroups, standaloneGroups, reservedPageIndexes } = groupStandaloneInputs(doc, inputs, options);
@@ -1095,7 +1098,7 @@ function reserveAutoPageStart(branchPageOffsets, branchOrdinal, reservedPageInde
 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;
+	assertPackedInputCoverage(pages, inputs.length, `package "${pkg.getName()}"`);
 	for (let pageOffset = 0; pageOffset < pages.length; pageOffset += 1) {
 		const page = pages[pageOffset];
 		const pageIndex = context.pageStart + pageOffset;
@@ -1121,7 +1124,7 @@ async function emitStandaloneAtlasGroup(doc, pkg, group, context) {
 		multipleOfFour: true,
 		square: false
 	} : void 0);
-	if (pages.length === 0) return 0;
+	assertPackedInputCoverage(pages, group.inputs.length, `standalone texture in package "${pkg.getName()}"`);
 	for (let pageOffset = 0; pageOffset < pages.length; pageOffset += 1) {
 		const page = pages[pageOffset];
 		const baseFileName = resolveStandaloneAtlasOutputFileName(pkg, group.resource, group.branchName);
@@ -1164,6 +1167,12 @@ function packAtlasPages(inputs, options, forceSinglePage, sizeOverrides) {
 		preserveInputOrderOnTie: options.preserveInputOrderOnTie
 	}).pack(inputs.map((input, index) => inputToCompatRect(input, index))) ?? [];
 }
+function assertPackedInputCoverage(pages, inputCount, label) {
+	const packedIndexes = /* @__PURE__ */ new Set();
+	for (const page of pages) for (const outputRect of page.outputRects) packedIndexes.add(outputRect.index);
+	const hasEveryInput = Array.from({ length: inputCount }, (_, index) => packedIndexes.has(index)).every(Boolean);
+	if (packedIndexes.size !== inputCount || !hasEveryInput) throw new Error(`atlas: Could not pack every input for ${label}.`);
+}
 function attachSpritesToAtlas(doc, allResources, inputs, outputRects, atlasNode) {
 	for (const packedRect of outputRects) {
 		const input = inputs[packedRect.index];
@@ -1223,7 +1232,9 @@ async function writeAtlasPageImage(pkg, inputs, page, atlasFileName, encoder, op
 			} 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.`);
+					const message = `atlas: Non-image input "${input.id}" is missing inline buffer.`;
+					if (options.strictOutput) throw new Error(message);
+					logger.warn(`${message} Skipping compositing.`);
 					continue;
 				}
 				imageBuffer = await encoder(_resolveImagePath(input.resource, pkg, options.basePath)).toBuffer();
@@ -1235,7 +1246,9 @@ async function writeAtlasPageImage(pkg, inputs, page, atlasFileName, encoder, op
 				top: packedRect.y
 			});
 		} catch {
-			logger.warn(`atlas: Could not read image "${input.id}" for compositing.`);
+			const message = `atlas: Could not read image "${input.id}" for compositing.`;
+			if (options.strictOutput) throw new Error(message);
+			logger.warn(message);
 		}
 	}
 	const outputFile = `${options.outputPath}/${atlasFileName}`;
@@ -1352,7 +1365,9 @@ async function emitDirectImageOutput(doc, pkg, input, encoder, options, logger,
 			}]).png().toFile(outputFile);
 		}
 	} catch {
-		logger.warn(`atlas: Could not write direct-output atlas "${atlasFileName}".`);
+		const message = `atlas: Could not write direct-output atlas "${atlasFileName}".`;
+		if (options.strictOutput) throw new Error(message);
+		logger.warn(message);
 	}
 }
 function getInputBranchName(input) {
@@ -1578,6 +1593,7 @@ async function _collectImage(resource, pkg, inputs, encoder, options, doTrim, lo
 				sourceHasAlpha = true;
 			}
 		} catch {
+			if (options.strictOutput) throw new Error(`atlas: Could not read image "${filePath}".`);
 			if (origW === 0 || origH === 0) {
 				logger.warn(`atlas: Could not read image "${filePath}", skipping.`);
 				return;
@@ -1616,7 +1632,11 @@ async function _collectImage(resource, pkg, inputs, encoder, options, doTrim, lo
 }
 /** Collect MovieClip frame textures from a .jta file into the inputs array. */
 async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, options, logger) {
-	if (!options.basePath || !options.readFileRaw) return;
+	if (!options.basePath || !options.readFileRaw) {
+		if (options.strictOutput) throw new Error(`atlas: MovieClip "${resource.getId()}" requires basePath and readFileRaw for complete raster output.`);
+		return;
+	}
+	if (!encoder && options.strictOutput) throw new Error(`atlas: MovieClip "${resource.getId()}" requires an encoder for complete raster output.`);
 	const mcId = resource.getId();
 	const mcName = resource.getName() + ".jta";
 	const mcPath = resource.getPath() ?? "/";
@@ -1639,7 +1659,7 @@ async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, opti
 				const exportFrameIndex = firstFrameIndexByTextureIndex.get(textureIndex);
 				if (exportFrameIndex === void 0) continue;
 				const itemId = `${mcId}_${exportFrameIndex}`;
-				const input = await _createMovieClipFrameInput(jta.frames[textureIndex], itemId, resource, encoder);
+				const input = await _createMovieClipFrameInput(jta.frames[textureIndex], itemId, resource, encoder, options.strictOutput);
 				if (!input) continue;
 				inputs.push(input);
 				spriteIdByTextureIndex.set(textureIndex, itemId);
@@ -1653,7 +1673,7 @@ async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, opti
 			}
 		} else for (let frameIndex = 0; frameIndex < jta.frames.length; frameIndex += 1) {
 			const itemId = `${mcId}_${frameIndex}`;
-			const input = await _createMovieClipFrameInput(jta.frames[frameIndex], itemId, resource, encoder);
+			const input = await _createMovieClipFrameInput(jta.frames[frameIndex], itemId, resource, encoder, options.strictOutput);
 			if (!input) continue;
 			inputs.push(input);
 			const frame = doc.createMovieFrame(itemId);
@@ -1665,10 +1685,12 @@ async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, opti
 			resource.setHeight(jta.meta?.height ?? 0);
 		}
 	} catch {
-		logger.warn(`atlas: Could not parse MovieClip "${filePath}", skipping frames.`);
+		const message = `atlas: Could not parse MovieClip "${filePath}".`;
+		if (options.strictOutput) throw new Error(message);
+		logger.warn(`${message} Skipping frames.`);
 	}
 }
-async function _createMovieClipFrameInput(buffer, itemId, resource, encoder) {
+async function _createMovieClipFrameInput(buffer, itemId, resource, encoder, strictOutput) {
 	if (!encoder || buffer.length === 0) return null;
 	try {
 		const meta = await encoder(buffer).metadata();
@@ -1688,6 +1710,7 @@ async function _createMovieClipFrameInput(buffer, itemId, resource, encoder) {
 			sourceKind: "movieclip-frame"
 		};
 	} catch {
+		if (strictOutput) throw new Error(`atlas: Could not decode MovieClip frame "${itemId}".`);
 		return null;
 	}
 }
@@ -3000,13 +3023,13 @@ function getPublishedSkeletonDependencyImageIds(pkg, publishedResourceIds) {
 	}
 	return imageIds;
 }
-async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw, logger) {
+async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw) {
 	const publishedResourceIds = getAnnotatedPublishedResourceIds(pkg);
 	if (publishedResourceIds.size === 0) return;
 	if (!basePath || !readFileRaw) {
 		if (pkg.listResources().some((resource) => {
 			return isSoundResource(resource) && publishedResourceIds.has(resource.getId());
-		})) logger.warn(`publish: Sound resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`);
+		})) throw new Error(`publish: Sound resources in package "${pkg.getName()}" require basePath and readFileRaw for output.`);
 		return;
 	}
 	for (const resource of pkg.listResources()) {
@@ -3019,18 +3042,18 @@ async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw, lo
 			const data = await readFileRaw(sourcePath);
 			await fs.writeFileRaw(targetPath, data);
 		} catch {
-			logger.warn(`publish: Could not export sound "${resource.getId()}" from package "${pkg.getName()}".`);
+			throw new Error(`publish: Could not export sound "${resource.getId()}" from package "${pkg.getName()}".`);
 		}
 	}
 }
-async function exportPackageExternalResources(pkg, outputDir, basePath, fs, readFileRaw, logger) {
+async function exportPackageExternalResources(pkg, outputDir, basePath, fs, readFileRaw) {
 	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)) && 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.`);
+		})) throw new Error(`publish: External resources in package "${pkg.getName()}" require basePath and readFileRaw for output.`);
 		return;
 	}
 	for (const resource of pkg.listResources()) {
@@ -3052,7 +3075,7 @@ async function exportPackageExternalResources(pkg, outputDir, basePath, fs, read
 			const data = await readFileRaw(sourcePath);
 			await fs.writeFileRaw(targetPath, data);
 		} catch {
-			logger.warn(`publish: Could not export external resource "${resource.getId()}" from package "${pkg.getName()}".`);
+			throw new Error(`publish: Could not export external resource "${resource.getId()}" from package "${pkg.getName()}".`);
 		}
 	}
 }
@@ -3068,18 +3091,17 @@ async function exportPackageExternalResources(pkg, outputDir, basePath, fs, read
 * `publishNode()` or `publishBrowser()` through their dedicated entries.
 *
 * ```ts
-* import sharp from 'sharp';
-* const io = new NodeIO();
-* const doc = await io.readProject('./project.fairy');
+* import { NodeIO } from '@openfairygui/core/node';
+* import { publishNode } from '@openfairygui/functions/node';
+* const doc = await new NodeIO().readProject('./project.fairy');
 *
-* await doc.transform(publish({
+* await publishNode({
+*   document: doc,
 *   output: './release/',
 *   compressed: true,
-*   encoder: sharp,
-*   basePath: './assets/',
+*   assetsPath: './assets/',
 *   fileExtension: 'bytes',
-*   fs: io.createFileSystem(),
-* }));
+* });
 * ```
 */
 function publish(options) {
@@ -3147,6 +3169,12 @@ function publish(options) {
 			}
 		});
 		const publishPackage = async (plan, writerFs, packageIndex) => {
+			if (options.fs && !plan.outputDir) throw new Error("publish: no output directory resolved. Provide --output, or configure global publish.path / package publishPath.");
+			if (options.fs) {
+				await options.fs.mkdir(plan.outputDir);
+				await exportPackageSounds(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw);
+				await exportPackageExternalResources(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw);
+			}
 			const atlasRuntimeOptions = resolvePublishAtlasRuntimeOptions(plan.fileExtension);
 			await atlas({
 				...plan.atlas,
@@ -3157,20 +3185,17 @@ function publish(options) {
 				outputPath: options.fs ? plan.outputDir : void 0,
 				mkdir: options.fs ? options.fs.mkdir : void 0,
 				readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
+				strictOutput: options.fs !== void 0,
 				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 _openfairygui_core.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();
@@ -3203,7 +3228,9 @@ function publish(options) {
 		}
 		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 outputPlan = plans.find((plan) => !!plan.outputDir);
+			if (outputPlan) throw new Error(`publish: Output for package "${outputPlan.pkg.getName()}" requires a filesystem. Omit output and publish paths to run a layout-only transform.`);
+			logger.info(`publish: Layout computed for ${allPackages.length} package(s); no output directory was requested.`);
 			const noopWriterFs = toBinaryWriterFileSystem(createNoopPublishFs());
 			for (const plan of plans) await publishPackage(plan, noopWriterFs, allDocPackages.indexOf(plan.pkg));
 			await runPublishPluginHook(plugins, "onPublishEnd", doc, options);