@openfairygui/functions 0.2.0-alpha.0 → 0.2.0-alpha.11

package/src/publish.ts

@@ -17,7 +17,8 @@ import {
 } from '@openfairygui/core';
 import { createTransform } from './utils.js';
 import { atlas, type AtlasOptions } from './atlas.js';
-import { publishCodeGeneration } from './codegen.js';
+import { publishCodeGeneration, resolveProjectBasePath } from './codegen.js';
+import { formatPluginError, loadPlugins, type LoadedPlugin } from './plugins/loader.js';
 import type {
 	CliPublishSettings,
 	HasOptionalFont,
@@ -28,10 +29,10 @@ import type {
 
 export interface PublishOptions {
 	/**
-	 * Output directory for published files (.fui + atlas PNGs).
-	 * Required.
+	 * Output directory override for published files (.fui + atlas PNGs).
+	 * When omitted, publish uses package-level or project-level publish paths.
 	 */
-	output: string;
+	output?: string;
 
 	/**
 	 * Compress the binary data with zlib raw deflate. Default: false.
@@ -96,6 +97,58 @@ export interface ResolvedPublishOptions {
 	atlas: ResolvedPublishAtlasOptions;
 }
 
+interface ResolvedProjectPublishConfig extends ResolvedPublishOptions {
+	projectType: number;
+	includeBranches: boolean;
+	activeBranch: string;
+	includeHighResolution: number;
+	separatedAtlasForBranch: boolean;
+	globalOutputPath: string;
+	globalBranchOutputPath: string;
+}
+
+interface ResolvedPackagePublishPlan {
+	pkg: Package;
+	outputDir?: string;
+	publishName: string;
+	fileName: string;
+	compressed: boolean;
+	fileExtension: string;
+	includeBranches: boolean;
+	activeBranch: string;
+	includeHighResolution: number;
+	separatedAtlasForBranch: boolean;
+	atlas: ResolvedPublishAtlasOptions;
+}
+
+async function runPublishPluginHook(
+	plugins: LoadedPlugin[],
+	hook: 'onPublishStart' | 'onPublishEnd',
+	doc: Document,
+	options: PublishOptions,
+): Promise<void> {
+	const logger = doc.getLogger();
+	for (const plugin of plugins) {
+		const fn = plugin.plugin[hook];
+		if (typeof fn !== 'function') continue;
+		try {
+			await fn(doc, options);
+		} catch (error) {
+			logger.warn(`publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`);
+		}
+	}
+}
+
+function resolvePublishPluginsDir(doc: Document, options: PublishOptions): string {
+	const fs = options.fs;
+	const projectDir = doc.getProjectDir?.() ?? '';
+	if (projectDir) return fs?.join ? fs.join(projectDir, 'plugins') : `${projectDir.replace(/[/\\]+$/, '')}/plugins`;
+
+	const projectBasePath = resolveProjectBasePath(options.basePath);
+	if (!projectBasePath) return '';
+	return fs?.join ? fs.join(projectBasePath, 'plugins') : `${projectBasePath.replace(/[/\\]+$/, '')}/plugins`;
+}
+
 interface ImageResourceExtras extends Record<string, unknown> {
 	_fileName?: string;
 }
@@ -112,7 +165,9 @@ interface BranchAwarePublishedResource {
 interface PackagePublishContext {
 	referencedIds: Set<string>;
 	publishedResourceIds: Set<string>;
+	exportedResourceIds: Set<string>;
 	pixelHitTestImageIds: Set<string>;
+	highResolutionItemIds: Map<string, Array<string | null>>;
 	effectiveResourceIds: Map<string, string>;
 	includeBranches: boolean;
 }
@@ -138,8 +193,10 @@ interface TransitionWithPublishRefs {
 
 interface ChildWithPublishRefs extends HasOptionalFont {
 	getId?(): string;
+	getPackageId?(): string;
 	getSrc?(): string;
 	getUrl?(): string;
+	getInstanceSound?(): string;
 	getDefaultItem?(): string;
 	getIcon?(): string;
 	getSelectedIcon?(): string;
@@ -273,6 +330,24 @@ export function resolvePublishOptions(
 	};
 }
 
+function trimTrailingSlashes(value: string): string {
+	return value.replace(/[/\\]+$/, '');
+}
+
+function isAbsolutePathLike(value: string): boolean {
+	return /^(?:[a-zA-Z]:[/\\]|[/\\]{1,2})/u.test(value);
+}
+
+function joinPathSegments(left: string, right: string): string {
+	const normalizedLeft = trimTrailingSlashes(left);
+	const normalizedRight = right.replace(/^[/\\]+/, '');
+	if (!normalizedLeft) return normalizedRight;
+	if (!normalizedRight) return normalizedLeft;
+	const separator = normalizedLeft.includes('\\') ? '\\' : '/';
+	return `${normalizedLeft}${separator}${normalizedRight}`;
+}
+
+
 function dirname(filePath: string): string {
 	const trimmed = filePath.replace(/[/\\]+$/, '');
 	const match = trimmed.match(/^(.*)[/\\][^/\\]+$/);
@@ -311,6 +386,10 @@ function isMovieClipResource(resource: ReturnType<Package['listResources']>[numb
 	return resource.propertyType === 'MovieClipResource';
 }
 
+function isHighResolutionResource(resource: ReturnType<Package['listResources']>[number]): resource is ImageResource | MovieClipResource {
+	return isImageResource(resource) || isMovieClipResource(resource);
+}
+
 function isMiscResource(resource: ReturnType<Package['listResources']>[number]): resource is MiscResource {
 	return resource.propertyType === 'MiscResource';
 }
@@ -423,14 +502,15 @@ function extname(fileName: string): string {
 	return normalized.slice(lastDot);
 }
 
-function resolvePublishedMiscFileName(resource: MiscResource): string {
+function resolvePublishedMiscFileName(resource: MiscResource, projectType: number): string {
 	const file = resource.getFile();
+	if (projectType !== UNITY_PROJECT_TYPE) return file;
 	if (file.toLowerCase().endsWith('.atlas')) return `${file}.txt`;
 	return file;
 }
 
-function resolvePublishedSkeletonFileName(resource: SpineResource | DragonBonesResource): string {
-	if (isSpineResource(resource) && resource.getFile().toLowerCase().endsWith('.skel')) {
+function resolvePublishedSkeletonFileName(resource: SpineResource | DragonBonesResource, projectType: number): string {
+	if (projectType === UNITY_PROJECT_TYPE && isSpineResource(resource) && resource.getFile().toLowerCase().endsWith('.skel')) {
 		return `${resource.getFile()}.bytes`;
 	}
 	return resource.getFile();
@@ -481,11 +561,93 @@ function buildBranchResourceKey(resource: {
 	return `${resource.propertyType}|${resource.getPath() ?? ''}|${resource.getName() ?? ''}`;
 }
 
+const HIGH_RESOLUTION_LEVELS = [
+	{ scale: 2, bit: 1, slot: 0 },
+	{ scale: 3, bit: 2, slot: 1 },
+	{ scale: 4, bit: 4, slot: 2 },
+] as const;
+
+function buildHighResolutionResourceKey(resource: {
+	propertyType: string;
+	getPath(): string;
+	getName(): string;
+	getBranch?(): string;
+}, name = resource.getName()): string {
+	return `${resource.propertyType}|${resource.getBranch?.() ?? ''}|${resource.getPath() ?? ''}|${name}`;
+}
+
+function isHighResolutionVariantName(name: string): boolean {
+	return /@(?:2|3|4)x(?:\.[^./\\]+)?$/iu.test(name);
+}
+
+function appendHighResolutionScaleToName(name: string, scale: number): string {
+	const extensionIndex = name.lastIndexOf('.');
+	if (extensionIndex > 0) {
+		return `${name.slice(0, extensionIndex)}@${scale}x${name.slice(extensionIndex)}`;
+	}
+	return `${name}@${scale}x`;
+}
+
+function trimTrailingMissingHighResolutionIds(ids: Array<string | null>): Array<string | null> {
+	while (ids.length > 0 && !ids[ids.length - 1]) {
+		ids.pop();
+	}
+	return ids;
+}
+
+function collectHighResolutionItemIds(
+	resources: ReturnType<Package['listResources']>,
+	publishedResourceIds: Set<string>,
+	includeHighResolution: number,
+): Map<string, Array<string | null>> {
+	const result = new Map<string, Array<string | null>>();
+	if (includeHighResolution <= 0) return result;
+
+	const highResolutionResourceByKey = new Map<string, ImageResource | MovieClipResource>();
+	for (const resource of resources) {
+		if (!isHighResolutionResource(resource)) continue;
+		highResolutionResourceByKey.set(buildHighResolutionResourceKey(resource), resource);
+	}
+
+	for (const resource of resources) {
+		if (!isHighResolutionResource(resource)) continue;
+		if (!publishedResourceIds.has(resource.getId())) continue;
+		if (isHighResolutionVariantName(resource.getName())) continue;
+
+		const ids: Array<string | null> = [];
+		for (const level of HIGH_RESOLUTION_LEVELS) {
+			if ((includeHighResolution & level.bit) === 0) {
+				ids[level.slot] = null;
+				continue;
+			}
+
+			const highResolutionResource = highResolutionResourceByKey.get(
+				buildHighResolutionResourceKey(resource, appendHighResolutionScaleToName(resource.getName(), level.scale)),
+			);
+			if (!highResolutionResource) {
+				ids[level.slot] = null;
+				continue;
+			}
+
+			const highResolutionId = highResolutionResource.getId();
+			publishedResourceIds.add(highResolutionId);
+			ids[level.slot] = highResolutionId;
+		}
+
+		trimTrailingMissingHighResolutionIds(ids);
+		if (ids.length > 0) result.set(resource.getId(), ids);
+	}
+
+	return result;
+}
+
 function collectPackagePublishContext(
 	pkg: Package,
 	options: {
+		projectType: number;
 		includeBranches: boolean;
 		activeBranch: string;
+		includeHighResolution: number;
 	},
 ): PackagePublishContext {
 	const pkgId = pkg.getId();
@@ -494,6 +656,27 @@ function collectPackagePublishContext(
 	const referencedIds = new Set<string>();
 	const pixelHitTestImageIds = new Set<string>();
 	const spriteItemIds = new Set<string>();
+	const collectExportedResourceIds = (
+		sourceResources: ReturnType<Package['listResources']>,
+		sourcePublishedResourceIds: Set<string>,
+	): Set<string> => {
+		const exportedResourceIds = new Set<string>(sourcePublishedResourceIds);
+		const resourcesById = new Map(sourceResources.map((resource) => [resource.getId(), resource] as const));
+		let changed = true;
+		while (changed) {
+			changed = false;
+			for (const resourceId of [...exportedResourceIds]) {
+				const resource = resourcesById.get(resourceId);
+				if (!resource || !isSkeletonResource(resource)) continue;
+				for (const requiredId of resource.getRequireIds()) {
+					if (!requiredId || exportedResourceIds.has(requiredId)) continue;
+					exportedResourceIds.add(requiredId);
+					changed = true;
+				}
+			}
+		}
+		return exportedResourceIds;
+	};
 
 	for (const atlas of pkg.listAtlases()) {
 		for (const sprite of atlas.listSprites()) {
@@ -531,6 +714,7 @@ function collectPackagePublishContext(
 				child.getSelectedIcon?.(),
 				child.getDropdown?.(),
 				child.getSound?.(),
+				child.getInstanceSound?.(),
 				child.getInstanceIcon?.(),
 				child.getInstanceSelectedIcon?.(),
 				child.getVtScrollBarRes?.(),
@@ -608,20 +792,16 @@ function collectPackagePublishContext(
 		}
 	}
 
-	let changed = true;
-	while (changed) {
-		changed = false;
-		for (const resource of resources) {
-			if (!isSkeletonResource(resource)) continue;
-			if (!publishedResourceIds.has(resource.getId())) continue;
-			for (const requiredId of resource.getRequireIds()) {
-				if (!requiredId || publishedResourceIds.has(requiredId)) continue;
-				publishedResourceIds.add(requiredId);
-				changed = true;
-			}
-		}
+	for (const resourceId of collectExportedResourceIds(resources, publishedResourceIds)) {
+		publishedResourceIds.add(resourceId);
 	}
 
+	const highResolutionItemIds = collectHighResolutionItemIds(
+		resources,
+		publishedResourceIds,
+		options.includeHighResolution,
+	);
+
 	if (!options.includeBranches) {
 		const mainByKey = new Map<string, ReturnType<Package['listResources']>[number]>();
 		const activeBranchByKey = new Map<string, ReturnType<Package['listResources']>[number]>();
@@ -685,7 +865,9 @@ function collectPackagePublishContext(
 		return {
 			referencedIds,
 			publishedResourceIds,
+			exportedResourceIds: collectExportedResourceIds(resources, publishedResourceIds),
 			pixelHitTestImageIds,
+			highResolutionItemIds,
 			effectiveResourceIds,
 			includeBranches: false,
 		};
@@ -694,7 +876,9 @@ function collectPackagePublishContext(
 	return {
 		referencedIds,
 		publishedResourceIds,
+		exportedResourceIds: collectExportedResourceIds(resources, publishedResourceIds),
 		pixelHitTestImageIds,
+		highResolutionItemIds,
 		effectiveResourceIds: new Map([...publishedResourceIds].map((resourceId) => [resourceId, resourceId])),
 		includeBranches: true,
 	};
@@ -768,29 +952,42 @@ async function annotatePackagePublishArtifacts(
 	basePath: string | undefined,
 	encoder: PublishEncoder | undefined,
 	options: {
+		projectType: number;
 		includeBranches: boolean;
 		activeBranch: string;
+		includeHighResolution: number;
 	},
 ): Promise<void> {
-	const { publishedResourceIds, pixelHitTestImageIds, effectiveResourceIds, includeBranches } = collectPackagePublishContext(pkg, options);
+	const {
+		publishedResourceIds,
+		exportedResourceIds,
+		pixelHitTestImageIds,
+		highResolutionItemIds,
+		effectiveResourceIds,
+		includeBranches,
+	} = collectPackagePublishContext(pkg, options);
 	for (const resource of pkg.listResources()) {
 		setPublishedIdExtra(resource, effectiveResourceIds.get(resource.getId()) ?? null);
+		if (isHighResolutionResource(resource)) {
+			resource.setHighResolutionItemIds(highResolutionItemIds.get(resource.getId()) ?? []);
+		}
 	}
 	await applyPixelHitTests(pkg, pixelHitTestImageIds, basePath, encoder);
 	const extras = (pkg.getExtras() as PackagePublishArtifactsExtras | undefined) ?? {};
 	pkg.setExtras({
 		...extras,
 		publishedResourceIds: [...publishedResourceIds].sort((a, b) => a.localeCompare(b)),
+		exportedResourceIds: [...exportedResourceIds].sort((a, b) => a.localeCompare(b)),
 		publishedIncludeBranches: includeBranches,
 		publishedEffectiveResourceIds: Object.fromEntries(effectiveResourceIds),
 	});
 	for (const resource of pkg.listResources()) {
 		if (isMiscResource(resource)) {
-			setPublishedFileExtra(resource, resolvePublishedMiscFileName(resource));
+			setPublishedFileExtra(resource, resolvePublishedMiscFileName(resource, options.projectType));
 			continue;
 		}
 		if (isSkeletonResource(resource)) {
-			setPublishedFileExtra(resource, resolvePublishedSkeletonFileName(resource));
+			setPublishedFileExtra(resource, resolvePublishedSkeletonFileName(resource, options.projectType));
 		}
 	}
 }
@@ -800,6 +997,11 @@ function getAnnotatedPublishedResourceIds(pkg: Package): Set<string> {
 	return new Set(extras.publishedResourceIds ?? []);
 }
 
+function getAnnotatedExportedResourceIds(pkg: Package): Set<string> {
+	const extras = (pkg.getExtras() as PackagePublishArtifactsExtras | undefined) ?? {};
+	return new Set(extras.exportedResourceIds ?? []);
+}
+
 function getPublishedSkeletonDependencyImageIds(
 	pkg: Package,
 	publishedResourceIds: Set<string>,
@@ -863,14 +1065,14 @@ async function exportPackageExternalResources(
 	readFileRaw: PublishFileSystem['readFileRaw'] | undefined,
 	logger: Document['getLogger'] extends () => infer T ? T : never,
 ): Promise<void> {
-	const publishedResourceIds = getAnnotatedPublishedResourceIds(pkg);
-	const skeletonDependencyImageIds = getPublishedSkeletonDependencyImageIds(pkg, publishedResourceIds);
-	if (publishedResourceIds.size === 0) return;
+	const exportedResourceIds = getAnnotatedExportedResourceIds(pkg);
+	const skeletonDependencyImageIds = getPublishedSkeletonDependencyImageIds(pkg, exportedResourceIds);
+	if (exportedResourceIds.size === 0) return;
 	if (!basePath || !readFileRaw) {
 		const hasPublishedExternal = pkg.listResources().some((resource) => {
 			return (
 				(isMiscResource(resource) || isSkeletonResource(resource))
-				&& publishedResourceIds.has(resource.getId())
+				&& exportedResourceIds.has(resource.getId())
 			) || skeletonDependencyImageIds.has(resource.getId());
 		});
 		if (hasPublishedExternal) {
@@ -881,7 +1083,7 @@ async function exportPackageExternalResources(
 
 	for (const resource of pkg.listResources()) {
 		const resourceId = resource.getId();
-		const isSkeletonExternal = publishedResourceIds.has(resourceId) && (isMiscResource(resource) || isSkeletonResource(resource));
+		const isSkeletonExternal = exportedResourceIds.has(resourceId) && (isMiscResource(resource) || isSkeletonResource(resource));
 		const isSkeletonImageDependency = skeletonDependencyImageIds.has(resourceId) && isImageResource(resource);
 		if (!isSkeletonExternal && !isSkeletonImageDependency) continue;
 
@@ -932,17 +1134,145 @@ async function exportPackageExternalResources(
  */
 export function publish(options: PublishOptions): Transform {
 	return createTransform('publish', async (doc: Document): Promise<void> => {
+		const resolveConfiguredOutputPath = (value?: string, projectBasePath?: string): string | undefined => {
+			const trimmed = value?.trim();
+			if (!trimmed) return undefined;
+			if (isAbsolutePathLike(trimmed) || !projectBasePath) {
+				return trimTrailingSlashes(trimmed);
+			}
+			return trimTrailingSlashes(options.fs ? options.fs.join(projectBasePath, trimmed) : joinPathSegments(projectBasePath, trimmed));
+		};
+
+		const resolveProjectPublishConfig = (): ResolvedProjectPublishConfig => {
+			const settings = (doc.getRoot().getSettings?.() ?? {}) as RootProjectSettings;
+			const publishSettings: CliPublishSettings = settings.publish ?? {};
+			const resolved = resolvePublishOptions(doc, {
+				compressed: options.compressed,
+				fileExtension: options.fileExtension,
+				packages: options.packages,
+				atlas: options.atlas,
+			});
+			const branchProcessing = publishSettings.branchProcessing ?? 0;
+			const includeBranches = branchProcessing === 0;
+
+			return {
+				...resolved,
+				projectType: doc.getRoot().getProjectType(),
+				includeBranches,
+				activeBranch: includeBranches ? '' : (options.branch ?? ''),
+				includeHighResolution: publishSettings.includeHighResolution ?? 0,
+				separatedAtlasForBranch: includeBranches && publishSettings.seperatedAtlasForBranch === true,
+				globalOutputPath: publishSettings.path?.trim() ?? '',
+				globalBranchOutputPath: publishSettings.branchPath?.trim() ?? '',
+			};
+		};
+
+		const resolvePackagePublishPlan = (pkg: Package, config: ResolvedProjectPublishConfig, projectBasePath?: string): ResolvedPackagePublishPlan => {
+			let outputDir: string | undefined;
+
+			if (options.output) {
+				outputDir = trimTrailingSlashes(options.output);
+			} else {
+				const candidates: Array<string | undefined> = [];
+				if (!config.includeBranches && config.activeBranch) {
+					candidates.push(pkg.getPublishBranchPath(), config.globalBranchOutputPath);
+				}
+				candidates.push(pkg.getPublishPath(), config.globalOutputPath);
+
+				for (const candidate of candidates) {
+					const resolved = resolveConfiguredOutputPath(candidate, projectBasePath);
+					if (!resolved) continue;
+					outputDir = resolved;
+					break;
+				}
+			}
+			const publishName = pkg.getPublishName() || pkg.getName();
+
+			return {
+				pkg,
+				outputDir,
+				publishName,
+				fileName: resolvePublishFileName(publishName, config.fileExtension),
+				compressed: config.compressed,
+				fileExtension: config.fileExtension,
+				includeBranches: config.includeBranches,
+				activeBranch: config.activeBranch,
+				includeHighResolution: config.includeHighResolution,
+				separatedAtlasForBranch: config.separatedAtlasForBranch,
+				atlas: config.atlas,
+			};
+		};
+
+		const createNoopPublishFs = (): PublishFileSystem => ({
+			async writeFileRaw(): Promise<void> {
+				// No-op for layout-only publish flows.
+			},
+			async mkdir(): Promise<void> {
+				// No-op for layout-only publish flows.
+			},
+			join(...paths: string[]): string {
+				return paths.join('/');
+			},
+		});
+
+		const publishPackage = async ( plan: ResolvedPackagePublishPlan, writerFs: FileSystem, packageIndex: number) => {
+			const atlasRuntimeOptions = resolvePublishAtlasRuntimeOptions(plan.fileExtension);
+			await atlas({
+				...plan.atlas,
+				...(options.atlas ?? {}),
+				separatedAtlasForBranch: plan.separatedAtlasForBranch,
+				encoder: options.encoder,
+				basePath: options.basePath,
+				outputPath: options.fs ? plan.outputDir : undefined,
+				mkdir: options.fs ? options.fs.mkdir : undefined,
+				readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
+				packages: [plan.pkg.getName()],
+				...atlasRuntimeOptions,
+			})(doc);
+
+			if (!options.fs) return;
+			if (!plan.outputDir) {
+				throw new Error('publish: no output directory resolved. Provide --output, or configure global publish.path / package publishPath.');
+			}
+
+			await options.fs.mkdir(plan.outputDir);
+
+			const filePath = options.fs.join(plan.outputDir, plan.fileName);
+			const bwOptions: BinaryWriterOptions = {
+				compressed: plan.compressed,
+				packageIndex,
+			};
+
+			const bw = new BinaryWriter(writerFs);
+			await bw.write(doc, filePath, bwOptions);
+			await exportPackageSounds(
+				plan.pkg,
+				plan.outputDir,
+				options.basePath,
+				options.fs,
+				options.atlas?.readFileRaw ?? options.fs.readFileRaw,
+				logger,
+			);
+			await exportPackageExternalResources(
+				plan.pkg,
+				plan.outputDir,
+				options.basePath,
+				options.fs,
+				options.atlas?.readFileRaw ?? options.fs.readFileRaw,
+				logger,
+			);
+
+			logger.info(`publish: Written ${plan.fileName}`);
+		};
+
 		const root = doc.getRoot();
 		const logger = doc.getLogger();
-		const settings = (root.getSettings?.() ?? {}) as RootProjectSettings;
-		const publishSettings: CliPublishSettings = settings.publish ?? {};
-		const resolved = resolvePublishOptions(doc, {
-			compressed: options.compressed,
-			fileExtension: options.fileExtension,
-			packages: options.packages,
-			atlas: options.atlas,
-		});
-		const ext = resolved.fileExtension;
+		const projectBasePath = resolveProjectBasePath(options.basePath) || doc.getProjectDir?.() || '';
+		const pluginsDir = resolvePublishPluginsDir(doc, options);
+		const plugins = pluginsDir ? await loadPlugins(doc, pluginsDir) : [];
+		await runPublishPluginHook(plugins, 'onPublishStart', doc, options);
+
+		const resolved = resolveProjectPublishConfig();
 
 		// Step 1: Determine which packages to publish
 		let allPackages = root.listPackages();
@@ -953,14 +1283,10 @@ export function publish(options: PublishOptions): Transform {
 
 		if (allPackages.length === 0) {
 			logger.warn('publish: No packages to publish.');
+			await runPublishPluginHook(plugins, 'onPublishEnd', doc, options);
 			return;
 		}
 
-		const branchProcessing = publishSettings.branchProcessing ?? 0;
-		const includeBranches = branchProcessing === 0;
-		const activeBranch = includeBranches ? '' : (options.branch ?? '');
-		const atlasRuntimeOptions = resolvePublishAtlasRuntimeOptions(ext);
-
 		const allDocPackages = root.listPackages();
 		// Build a pkgId→name map for dependency resolution
 		const pkgMap = new Map<string, Package>();
@@ -971,82 +1297,61 @@ export function publish(options: PublishOptions): Transform {
 		for (const pkg of allPackages) {
 			// Compute dependency list and selected publish artifacts before atlas packing,
 			// so merged-branch publishes can pack the overridden resources with main IDs.
-			_computeDependencies(pkg, pkgMap);
+			_computeDependencies(doc, pkg, pkgMap);
 			await annotatePackagePublishArtifacts(
 				pkg,
 				options.basePath,
 				options.encoder as PublishEncoder | undefined,
 				{
-					includeBranches,
-					activeBranch,
+					projectType: resolved.projectType,
+					includeBranches: resolved.includeBranches,
+					activeBranch: resolved.activeBranch,
+					includeHighResolution: resolved.includeHighResolution,
 				},
 			);
 		}
 
-		// Step 2: Atlas packing
-		const atlasOpts: AtlasOptions = {
-			...resolved.atlas,
-			...(options.atlas ?? {}),
-			separatedAtlasForBranch: includeBranches && publishSettings.seperatedAtlasForBranch === true,
-			encoder: options.encoder,
-			basePath: options.basePath,
-			outputPath: options.fs ? options.output : undefined,
-			mkdir: options.fs ? options.fs.mkdir : undefined,
-			readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
-			...atlasRuntimeOptions,
-		};
-		await atlas(atlasOpts)(doc);
+		const plans = allPackages.map((pkg) => resolvePackagePublishPlan(pkg, resolved, projectBasePath));
 
-		// Step 3: Write .fui binary per package
 		if (!options.fs) {
 			logger.info(`publish: No fs provided — layout computed for ${allPackages.length} package(s), skipping file output.`);
+			const noopWriterFs = toBinaryWriterFileSystem(createNoopPublishFs());
+			for (const plan of plans) {
+				await publishPackage(plan, noopWriterFs, allDocPackages.indexOf(plan.pkg));
+			}
+			await runPublishPluginHook(plugins, 'onPublishEnd', doc, options);
 			return;
 		}
 
-		await options.fs.mkdir(options.output);
+		const unresolvedPlan = plans.find((plan) => !plan.outputDir);
+		if (unresolvedPlan) {
+			throw new Error(
+				`publish: no output directory resolved for package "${unresolvedPlan.pkg.getName()}". ` +
+					'Provide --output, or configure global publish.path / package publishPath.',
+			);
+		}
 
 		const writerFs = toBinaryWriterFileSystem(options.fs);
 
-		for (const pkg of allPackages) {
-			const pkgIndex = allDocPackages.indexOf(pkg);
-			const publishName = pkg.getPublishName() || pkg.getName();
-			const fileName = resolvePublishFileName(publishName, ext);
-			const filePath = options.fs.join(options.output, fileName);
-
-			const bwOptions: BinaryWriterOptions = {
-				compressed: resolved.compressed,
-				packageIndex: pkgIndex,
-			};
-
-			const bw = new BinaryWriter(writerFs);
-			await bw.write(doc, filePath, bwOptions);
-			await exportPackageSounds(
-				pkg,
-				options.output,
-				options.basePath,
-				options.fs,
-				options.atlas?.readFileRaw ?? options.fs.readFileRaw,
-				logger,
-			);
-			await exportPackageExternalResources(
-				pkg,
-				options.output,
-				options.basePath,
-				options.fs,
-				options.atlas?.readFileRaw ?? options.fs.readFileRaw,
-				logger,
-			);
-
-			logger.info(`publish: Written ${fileName}`);
+		for (const plan of plans) {
+			const pkgIndex = allDocPackages.indexOf(plan.pkg);
+			await publishPackage(plan, writerFs, pkgIndex);
 		}
 
 		await publishCodeGeneration(doc, {
 			basePath: options.basePath,
 			fs: options.fs,
 			packages: allPackages,
+			plugins,
 		});
 
-		logger.info(`publish: Published ${allPackages.length} package(s) to ${options.output}`);
+		const publishedTargets = [...new Set(plans.map((plan) => plan.outputDir).filter((value): value is string => Boolean(value)))];
+		logger.info(
+			publishedTargets.length > 0
+				? `publish: Published ${allPackages.length} package(s) to ${publishedTargets.join(', ')}`
+				: `publish: Published ${allPackages.length} package(s)`,
+		);
+		await runPublishPluginHook(plugins, 'onPublishEnd', doc, options);
 	});
 }
 
@@ -1055,25 +1360,109 @@ export function publish(options: PublishOptions): Transform {
  * The editor only adds dependencies for packages referenced via bitmap font URLs.
  * @internal
  */
-function _computeDependencies(pkg: Package, pkgMap: Map<string, Package>): void {
+function _computeDependencies(doc: Document, pkg: Package, pkgMap: Map<string, Package>): void {
 	const referencedPkgIds = new Set<string>();
-
-	function scanFontUrl(font: string | string[] | null | undefined): void {
-		if (!font) return;
-		const fontStr = Array.isArray(font) ? font[0] : String(font);
-		if (typeof fontStr !== 'string' || !fontStr.startsWith('ui://')) return;
-		const rest = fontStr.slice(5);
+	const pkgId = pkg.getId();
+	const packageOrder = new Map(doc.getRoot().listPackages().map((entry, index) => [entry.getId(), index] as const));
+	const addDependencyPackageId = (dependencyPkgId: string | null | undefined): void => {
+		const normalized = dependencyPkgId?.trim() ?? '';
+		if (!normalized || normalized === pkgId) return;
+		referencedPkgIds.add(normalized);
+	};
+	const extractPackageIdFromUiUrl = (value: string): string | null => {
+		if (!value.startsWith('ui://')) return null;
+		const rest = value.slice(5);
+		if (!rest) return null;
+		const slashIndex = rest.indexOf('/');
+		if (slashIndex >= 0) {
+			return rest.slice(0, slashIndex) || null;
+		}
 		if (rest.length >= 8) {
-			const depPkgId = rest.slice(0, 8);
-			if (depPkgId !== pkg.getId()) referencedPkgIds.add(depPkgId);
+			return rest.slice(0, 8);
 		}
-	}
+		return null;
+	};
+	const addDependencyPackageIdFromUiValue = (value: string | null | undefined): void => {
+		if (!value || typeof value !== 'string') return;
+		addDependencyPackageId(extractPackageIdFromUiUrl(value));
+	};
+	const addDependencyPackageIdsFromText = (value: string | null | undefined): void => {
+		if (!value || typeof value !== 'string') return;
+		const matches = value.matchAll(/ui:\/\/([0-9a-z]{8})/giu);
+		for (const match of matches) {
+			addDependencyPackageId(match[1] ?? '');
+		}
+	};
+	const addDependencyPackageIdsFromUnknown = (value: unknown): void => {
+		if (Array.isArray(value)) {
+			for (const entry of value) addDependencyPackageIdsFromUnknown(entry);
+			return;
+		}
+		if (typeof value === 'string') {
+			addDependencyPackageIdFromUiValue(value);
+			addDependencyPackageIdsFromText(value);
+		}
+	};
+	const addDependencyFontRef = (value: string | string[] | null | undefined): void => {
+		if (Array.isArray(value)) {
+			for (const entry of value) addDependencyPackageIdFromUiValue(entry);
+			return;
+		}
+		addDependencyPackageIdFromUiValue(value ?? undefined);
+	};
 
 	for (const res of pkg.listResources()) {
 		if (res.propertyType !== 'Component') continue;
-		for (const child of res.listChildren?.() ?? []) {
-			// Only font="ui://..." references generate dependencies
-			scanFontUrl((child as HasOptionalFont).getFont?.());
+		const component = res as ComponentWithPublishRefs;
+		for (const child of component.listChildren?.() ?? []) {
+			addDependencyPackageId(child.getPackageId?.());
+			addDependencyFontRef(child.getFont?.());
+			addDependencyPackageIdsFromText(child.getText?.());
+			for (const ref of [
+				child.getUrl?.(),
+				child.getDefaultItem?.(),
+				child.getIcon?.(),
+				child.getSelectedIcon?.(),
+				child.getDropdown?.(),
+				child.getSound?.(),
+				child.getInstanceSound?.(),
+				child.getInstanceIcon?.(),
+				child.getInstanceSelectedIcon?.(),
+				child.getVtScrollBarRes?.(),
+				child.getHzScrollBarRes?.(),
+				child.getHeaderRes?.(),
+				child.getFooterRes?.(),
+			]) {
+				addDependencyPackageIdFromUiValue(ref);
+			}
+			for (const item of child.getInstanceComboItems?.() ?? []) {
+				addDependencyPackageIdFromUiValue(item.icon ?? undefined);
+			}
+			for (const item of child.getListItems?.() ?? []) {
+				addDependencyPackageIdFromUiValue(item.icon ?? undefined);
+				addDependencyPackageIdFromUiValue(item.url ?? undefined);
+			}
+			for (const gear of child.listGears?.() ?? []) {
+				addDependencyPackageIdsFromUnknown(gear.getValues?.());
+				addDependencyPackageIdsFromUnknown(gear.getDefaultValue?.());
+			}
+		}
+		addDependencyFontRef(component.getFont?.());
+		for (const ref of [
+			component.getDropdown?.(),
+			component.getHeaderRes?.(),
+			component.getFooterRes?.(),
+			component.getVtScrollBarRes?.(),
+			component.getHzScrollBarRes?.(),
+			component.getSound?.(),
+		]) {
+			addDependencyPackageIdFromUiValue(ref);
+		}
+		for (const transition of component.listTransitions?.() ?? []) {
+			for (const item of transition.listItems?.() ?? []) {
+				addDependencyPackageIdsFromUnknown(item.getStartValue?.());
+				addDependencyPackageIdsFromUnknown(item.getEndValue?.());
+			}
 		}
 	}
 
@@ -1082,7 +1471,12 @@ function _computeDependencies(pkg: Package, pkgMap: Map<string, Package>): void
 	}
 
 	if (referencedPkgIds.size > 0) {
-		const sortedIds = [...referencedPkgIds].sort((a, b) => a.localeCompare(b));
+		const sortedIds = [...referencedPkgIds].sort((a, b) => {
+			const orderA = packageOrder.get(a) ?? Number.MAX_SAFE_INTEGER;
+			const orderB = packageOrder.get(b) ?? Number.MAX_SAFE_INTEGER;
+			if (orderA !== orderB) return orderA - orderB;
+			return a.localeCompare(b);
+		});
 		for (const refId of sortedIds) {
 			const depPkg = pkgMap.get(refId);
 			if (depPkg) {