@openfairygui/functions 0.2.0-alpha.1 → 0.2.0-alpha.12

package/src/publish.ts

@@ -17,21 +17,22 @@ 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, type LoadedPlugin } from './plugins/types.js';
+import type { AtlasRasterBackend, PublishFileSystem } from './publish/contracts.js';
 import type {
 	CliPublishSettings,
 	HasOptionalFont,
 	PackagePublishArtifactsExtras,
-	PublishFileSystem,
 	RootProjectSettings,
 } from './shared-types.js';
 
 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.
@@ -45,10 +46,10 @@ export interface PublishOptions {
 	fileExtension?: string;
 
 	/**
-	 * Sharp module instance for atlas image compositing.
+	 * Raster backend for atlas image compositing.
 	 * If not provided, atlas packing only computes layout (no PNGs generated).
 	 */
-	encoder?: unknown;
+	encoder?: AtlasRasterBackend;
 
 	/**
 	 * Base path for reading source images (project assets root).
@@ -78,9 +79,33 @@ export interface PublishOptions {
 	 * Empty or omitted means publishing the main branch.
 	 */
 	branch?: string;
+
+	/**
+	 * Publish hooks supplied by the host adapter.
+	 *
+	 * Node adapters load project plugins. Browser adapters pass an empty list.
+	 */
+	plugins?: LoadedPlugin[];
+
+	/**
+	 * Run generic code generation after runtime artifacts. Default: true.
+	 */
+	codeGeneration?: boolean;
 }
 
-export interface ResolvedPublishAtlasOptions extends Pick<AtlasOptions, 'maxSize' | 'fast' | 'allowRotation' | 'padding' | 'powerOfTwo' | 'square' | 'multiPage' | 'trimImage' | 'extractAlpha'> {}
+export interface ResolvedPublishAtlasOptions
+	extends Pick<
+		AtlasOptions,
+		| 'maxSize'
+		| 'fast'
+		| 'allowRotation'
+		| 'padding'
+		| 'powerOfTwo'
+		| 'square'
+		| 'multiPage'
+		| 'trimImage'
+		| 'extractAlpha'
+	> {}
 
 export interface ResolvePublishOptionsOverrides {
 	compressed?: boolean;
@@ -96,6 +121,48 @@ 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)}`);
+		}
+	}
+}
+
 interface ImageResourceExtras extends Record<string, unknown> {
 	_fileName?: string;
 }
@@ -112,7 +179,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 +207,10 @@ interface TransitionWithPublishRefs {
 
 interface ChildWithPublishRefs extends HasOptionalFont {
 	getId?(): string;
+	getPackageId?(): string;
 	getSrc?(): string;
 	getUrl?(): string;
+	getInstanceSound?(): string;
 	getDefaultItem?(): string;
 	getIcon?(): string;
 	getSelectedIcon?(): string;
@@ -172,27 +243,6 @@ interface ComponentWithPublishRefs {
 	listTransitions?(): TransitionWithPublishRefs[];
 }
 
-interface PublishEncoderMetadata {
-	width?: number;
-	height?: number;
-	channels?: number;
-}
-
-interface PublishEncoderResolvedBuffer {
-	data: Uint8Array;
-	info: Required<Pick<PublishEncoderMetadata, 'width' | 'height' | 'channels'>> & PublishEncoderMetadata;
-}
-
-interface PublishEncoderPipeline {
-	ensureAlpha(): PublishEncoderPipeline;
-	resize(options: { width: number; height: number; fit: 'fill' }): PublishEncoderPipeline;
-	raw(): PublishEncoderPipeline;
-	toBuffer(options: { resolveWithObject: true }): Promise<PublishEncoderResolvedBuffer>;
-	metadata(): Promise<PublishEncoderMetadata>;
-}
-
-type PublishEncoder = (input: string | Uint8Array) => PublishEncoderPipeline;
-
 const UNITY_PROJECT_TYPE = ProjectType.Unity;
 const COCOS_CREATOR_PROJECT_TYPE = ProjectType.CocosCreator;
 
@@ -245,8 +295,7 @@ export function resolvePublishOptions(
 	const atlasSetting = publishSettings.atlasSetting ?? {};
 	const projectType = root.getProjectType();
 
-	const fileExtension = overrides.fileExtension
-		?? resolveDefaultPublishFileExtension(projectType, publishSettings);
+	const fileExtension = overrides.fileExtension ?? resolveDefaultPublishFileExtension(projectType, publishSettings);
 
 	let compressed = overrides.compressed ?? publishSettings.compressDesc ?? false;
 	if (projectType === UNITY_PROJECT_TYPE) {
@@ -273,6 +322,23 @@ 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 +377,12 @@ 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';
 }
@@ -327,7 +399,9 @@ function isSpineResource(resource: ReturnType<Package['listResources']>[number])
 	return resource.propertyType === 'SpineResource';
 }
 
-function isDragonBonesResource(resource: ReturnType<Package['listResources']>[number]): resource is DragonBonesResource {
+function isDragonBonesResource(
+	resource: ReturnType<Package['listResources']>[number],
+): resource is DragonBonesResource {
 	return resource.propertyType === 'DragonBonesResource';
 }
 
@@ -374,10 +448,7 @@ function addLocalFontRef(target: Set<string>, pkgId: string, value: string | str
 	addLocalUiResourceRef(target, pkgId, value ?? undefined);
 }
 
-function resolvePackageAssetsBasePath(
-	basePath: string,
-	resource: BranchAwarePublishedResource | undefined,
-): string {
+function resolvePackageAssetsBasePath(basePath: string, resource: BranchAwarePublishedResource | undefined): string {
 	const branchName = resource?.getBranch?.() ?? '';
 	if (!branchName) return basePath;
 	const normalized = basePath.replace(/[/\\]+$/, '');
@@ -423,14 +494,19 @@ 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();
@@ -448,7 +524,11 @@ function setPublishedFileExtra(
 }
 
 function setPublishedIdExtra(
-	resource: { getId(): string; getExtras(): Record<string, unknown> | undefined; setExtras(value: Record<string, unknown>): unknown },
+	resource: {
+		getId(): string;
+		getExtras(): Record<string, unknown> | undefined;
+		setExtras(value: Record<string, unknown>): unknown;
+	},
 	effectiveId: string | null,
 ): void {
 	const extras = (resource.getExtras() as PublishFileExtras | undefined) ?? {};
@@ -473,19 +553,103 @@ function getBranchName(resource: BranchAwarePublishedResource | undefined): stri
 	return resource?.getBranch?.() ?? '';
 }
 
-function buildBranchResourceKey(resource: {
-	propertyType: string;
-	getPath(): string;
-	getName(): string;
-}): string {
+function buildBranchResourceKey(resource: { propertyType: string; getPath(): string; getName(): string }): string {
 	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 +658,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 +716,7 @@ function collectPackagePublishContext(
 				child.getSelectedIcon?.(),
 				child.getDropdown?.(),
 				child.getSound?.(),
+				child.getInstanceSound?.(),
 				child.getInstanceIcon?.(),
 				child.getInstanceSelectedIcon?.(),
 				child.getVtScrollBarRes?.(),
@@ -583,7 +769,12 @@ function collectPackagePublishContext(
 			continue;
 		}
 		if (isImageResource(resource)) {
-			if (resource.getExported() || referencedIds.has(resourceId) || spriteItemIds.has(resourceId) || pixelHitTestImageIds.has(resourceId)) {
+			if (
+				resource.getExported() ||
+				referencedIds.has(resourceId) ||
+				spriteItemIds.has(resourceId) ||
+				pixelHitTestImageIds.has(resourceId)
+			) {
 				publishedResourceIds.add(resourceId);
 			}
 			continue;
@@ -608,20 +799,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 +872,9 @@ function collectPackagePublishContext(
 		return {
 			referencedIds,
 			publishedResourceIds,
+			exportedResourceIds: collectExportedResourceIds(resources, publishedResourceIds),
 			pixelHitTestImageIds,
+			highResolutionItemIds,
 			effectiveResourceIds,
 			includeBranches: false,
 		};
@@ -694,7 +883,9 @@ function collectPackagePublishContext(
 	return {
 		referencedIds,
 		publishedResourceIds,
+		exportedResourceIds: collectExportedResourceIds(resources, publishedResourceIds),
 		pixelHitTestImageIds,
+		highResolutionItemIds,
 		effectiveResourceIds: new Map([...publishedResourceIds].map((resourceId) => [resourceId, resourceId])),
 		includeBranches: true,
 	};
@@ -704,7 +895,7 @@ async function applyPixelHitTests(
 	pkg: Package,
 	imageIds: Set<string>,
 	basePath: string | undefined,
-	encoder: PublishEncoder | undefined,
+	encoder: AtlasRasterBackend | undefined,
 ): Promise<void> {
 	const images = pkg.listImageResources();
 	for (const image of images) {
@@ -766,31 +957,44 @@ async function applyPixelHitTests(
 async function annotatePackagePublishArtifacts(
 	pkg: Package,
 	basePath: string | undefined,
-	encoder: PublishEncoder | undefined,
+	encoder: AtlasRasterBackend | 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,10 +1004,12 @@ function getAnnotatedPublishedResourceIds(pkg: Package): Set<string> {
 	return new Set(extras.publishedResourceIds ?? []);
 }
 
-function getPublishedSkeletonDependencyImageIds(
-	pkg: Package,
-	publishedResourceIds: Set<string>,
-): Set<string> {
+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>): Set<string> {
 	const imageIds = new Set<string>();
 	const resourcesById = new Map(pkg.listResources().map((resource) => [resource.getId(), resource] as const));
 	for (const resource of pkg.listResources()) {
@@ -833,7 +1039,9 @@ async function exportPackageSounds(
 			return isSoundResource(resource) && publishedResourceIds.has(resource.getId());
 		});
 		if (hasPublishedSound) {
-			logger.warn(`publish: Sound resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`);
+			logger.warn(
+				`publish: Sound resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`,
+			);
 		}
 		return;
 	}
@@ -863,25 +1071,29 @@ 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())
-			) || skeletonDependencyImageIds.has(resource.getId());
+				((isMiscResource(resource) || isSkeletonResource(resource)) &&
+					exportedResourceIds.has(resource.getId())) ||
+				skeletonDependencyImageIds.has(resource.getId())
+			);
 		});
 		if (hasPublishedExternal) {
-			logger.warn(`publish: External resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`);
+			logger.warn(
+				`publish: External resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`,
+			);
 		}
 		return;
 	}
 
 	for (const resource of pkg.listResources()) {
 		const resourceId = resource.getId();
-		const isSkeletonExternal = publishedResourceIds.has(resourceId) && (isMiscResource(resource) || isSkeletonResource(resource));
+		const isSkeletonExternal =
+			exportedResourceIds.has(resourceId) && (isMiscResource(resource) || isSkeletonResource(resource));
 		const isSkeletonImageDependency = skeletonDependencyImageIds.has(resourceId) && isImageResource(resource);
 		if (!isSkeletonExternal && !isSkeletonImageDependency) continue;
 
@@ -892,7 +1104,8 @@ async function exportPackageExternalResources(
 			targetName = resolveImageFileName(resource);
 		} else if (isMiscResource(resource) || isSkeletonResource(resource)) {
 			sourcePath = resolveGenericResourcePath(resource, pkg, basePath);
-			targetName = ((resource.getExtras() as PublishFileExtras | undefined) ?? {})._publishedFile ?? resource.getFile();
+			targetName =
+				((resource.getExtras() as PublishFileExtras | undefined) ?? {})._publishedFile ?? resource.getFile();
 		} else {
 			continue;
 		}
@@ -902,7 +1115,9 @@ async function exportPackageExternalResources(
 			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()}".`);
+			logger.warn(
+				`publish: Could not export external resource "${resource.getId()}" from package "${pkg.getName()}".`,
+			);
 		}
 	}
 }
@@ -911,10 +1126,13 @@ async function exportPackageExternalResources(
  * Publishes a FairyGUI project.
  *
  * Orchestrates:
- * 1. Atlas packing (MaxRects layout + optional sharp compositing)
+ * 1. Atlas packing (MaxRects layout + optional raster compositing)
  * 2. Per-package .fui binary serialization
  * 3. File writing to the output directory
  *
+ * This is the capability-injected core. Standard hosts should use
+ * `publishNode()` or `publishBrowser()` through their dedicated entries.
+ *
  * ```ts
  * import sharp from 'sharp';
  * const io = new NodeIO();
@@ -932,17 +1150,152 @@ 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 plugins = options.plugins ?? [];
+		await runPublishPluginHook(plugins, 'onPublishStart', doc, options);
+
+		const resolved = resolveProjectPublishConfig();
 
 		// Step 1: Determine which packages to publish
 		let allPackages = root.listPackages();
@@ -953,14 +1306,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 +1320,62 @@ 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);
-			await annotatePackagePublishArtifacts(
-				pkg,
-				options.basePath,
-				options.encoder as PublishEncoder | undefined,
-				{
-					includeBranches,
-					activeBranch,
-				},
-			);
+			_computeDependencies(doc, pkg, pkgMap);
+			await annotatePackagePublishArtifacts(pkg, options.basePath, options.encoder, {
+				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.`);
+			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,
-		});
+		if (options.codeGeneration !== false) {
+			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 +1384,114 @@ 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 +1500,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) {