@openfairygui/functions 0.1.0 → 0.2.0-alpha.0

package/src/atlas.ts

@@ -1,67 +1,67 @@
 import { GearType, TransitionActionType, type Component, type Document, type DragonBonesResource, type FontResource, type ILogger, type ImageResource, type MovieClipResource, type Package, type SpineResource, type Transform } from '@openfairygui/core';
 import { COMPAT_NODE_RECT_FLAGS, type CompatNodeRect } from './max-rects-compat.js';
 import { MaxRectsPackerCompat } from './max-rects-packer-compat.js';
-import type { ExtrasMap, HasOptionalSrc, HasOptionalUrl } from './shared-types.js';
-import { createTransform } from './utils.js';
-
+import type { ExtrasMap, HasOptionalSrc, HasOptionalUrl } from './shared-types.js';
+import { createTransform } from './utils.js';
+
 export interface AtlasOptions {
-	/**
-	 * Sharp module instance, injected by the caller.
-	 * Required for actual image compositing and trimImage.
-	 *
-	 * ```ts
-	 * import sharp from 'sharp';
-	 * await doc.transform(atlas({ encoder: sharp }));
-	 * ```
-	 */
-	encoder?: unknown;
-
+	/**
+	 * Sharp module instance, injected by the caller.
+	 * Required for actual image compositing and trimImage.
+	 *
+	 * ```ts
+	 * import sharp from 'sharp';
+	 * await doc.transform(atlas({ encoder: sharp }));
+	 * ```
+	 */
+	encoder?: unknown;
+
 	/** Maximum atlas texture size (width and height). Default: 2048. */
 	maxSize?: number;
 
 	/** Whether to use the fast editor-compatible packing heuristics. Default: true. */
 	fast?: boolean;
-
-	/** Allow rotating sprites 90° for better packing. Default: true. */
-	allowRotation?: boolean;
-
-	/** Pixel padding between sprites. Default: 1. */
-	padding?: number;
-
-	/** Constrain atlas dimensions to powers of two. Default: false. */
-	powerOfTwo?: boolean;
-
+
+	/** Allow rotating sprites 90° for better packing. Default: true. */
+	allowRotation?: boolean;
+
+	/** Pixel padding between sprites. Default: 1. */
+	padding?: number;
+
+	/** Constrain atlas dimensions to powers of two. Default: false. */
+	powerOfTwo?: boolean;
+
 	/** Force square atlas (width === height). Default: false. */
 	square?: boolean;
 
 	/** Allow spilling into multiple atlas pages. Default: true. */
 	multiPage?: boolean;
-
-	/**
-	 * Trim transparent pixels from image edges before packing.
-	 * Requires encoder (sharp). Stores offset/originalSize in Sprite nodes.
-	 * Default: false.
-	 */
-	trimImage?: boolean;
-
-	/**
-	 * Base path for reading source images. If not set, images must have
-	 * their pixel data stored in extras._imageData as Uint8Array.
-	 */
-	basePath?: string;
-
-	/**
-	 * Output directory for generated atlas PNGs.
-	 * Required when encoder is provided.
-	 */
-	outputPath?: string;
-
-	/**
-	 * Optional mkdir function to ensure output directory exists.
-	 * If not provided, the outputPath directory must already exist.
-	 */
-	mkdir?: (path: string) => Promise<void>;
-
+
+	/**
+	 * Trim transparent pixels from image edges before packing.
+	 * Requires encoder (sharp). Stores offset/originalSize in Sprite nodes.
+	 * Default: false.
+	 */
+	trimImage?: boolean;
+
+	/**
+	 * Base path for reading source images. If not set, images must have
+	 * their pixel data stored in extras._imageData as Uint8Array.
+	 */
+	basePath?: string;
+
+	/**
+	 * Output directory for generated atlas PNGs.
+	 * Required when encoder is provided.
+	 */
+	outputPath?: string;
+
+	/**
+	 * Optional mkdir function to ensure output directory exists.
+	 * If not provided, the outputPath directory must already exist.
+	 */
+	mkdir?: (path: string) => Promise<void>;
+
 	/**
 	 * Optional raw file reader for reading .jta MovieClip files.
 	 * Required for MovieClip frame atlas packing.
@@ -109,34 +109,33 @@ const ATLAS_DEFAULTS: Required<Omit<AtlasOptions, 'encoder' | 'basePath' | 'outp
 	extractAlpha: false,
 	separatedAtlasForBranch: false,
 };
-
-/** Trim info for a single image. */
-interface TrimInfo {
-	/** Trimmed pixel data (PNG). */
-	buffer: Uint8Array;
-	/** Trimmed width. */
-	width: number;
-	/** Trimmed height. */
-	height: number;
-	/** Offset from original left edge. */
-	offsetX: number;
-	/** Offset from original top edge. */
-	offsetY: number;
-	/** Original width before trim. */
-	originalWidth: number;
-	/** Original height before trim. */
-	originalHeight: number;
-}
-
-type PackageResource = ReturnType<Package['listResources']>[number];
-type PackableResource = ImageResource | MovieClipResource | FontResource;
-type PackInputResource = ImageResource | MovieClipResource;
-type ParsedFnt = ReturnType<typeof _parseFnt>;
+
+/** Trim info for a single image. */
+interface TrimInfo {
+	/** Trimmed pixel data (PNG). */
+	buffer: Uint8Array;
+	/** Trimmed width. */
+	width: number;
+	/** Trimmed height. */
+	height: number;
+	/** Offset from original left edge. */
+	offsetX: number;
+	/** Offset from original top edge. */
+	offsetY: number;
+	/** Original width before trim. */
+	originalWidth: number;
+	/** Original height before trim. */
+	originalHeight: number;
+}
+
+type PackageResource = ReturnType<Package['listResources']>[number];
+type PackableResource = ImageResource | MovieClipResource | FontResource;
+type PackInputResource = ImageResource | MovieClipResource;
 
 function getPublishedItemId(resource: { getId(): string; getExtras(): ExtrasMap | undefined }): string {
 	return ((resource.getExtras() as ImageResourceExtras | undefined) ?? {})._publishedId ?? resource.getId();
 }
-
+
 interface AtlasReferenceItem {
 	icon?: string | null;
 	url?: string | null;
@@ -176,12 +175,12 @@ interface ChildWithReferenceUrls extends HasOptionalSrc, HasOptionalUrl {
 	getListItems?(): AtlasReferenceItem[];
 	listGears?(): GearWithAtlasRefs[];
 }
-
+
 interface ImageResourceExtras extends ExtrasMap {
 	_fileName?: string;
 	_publishedId?: string;
 }
-
+
 interface FontSpriteAlias {
 	fontId: string;
 	textureId: string;
@@ -209,18 +208,18 @@ interface AtlasEncoderMetadata {
 	trimOffsetLeft?: number;
 	trimOffsetTop?: number;
 }
-
+
 interface AtlasEncoderResolvedBuffer {
 	data: Uint8Array;
 	info: Required<Pick<AtlasEncoderMetadata, 'width' | 'height' | 'channels'>> & AtlasEncoderMetadata;
 }
-
-interface AtlasCompositeInput {
-	input: Uint8Array;
-	left: number;
-	top: number;
-}
-
+
+interface AtlasCompositeInput {
+	input: Uint8Array;
+	left: number;
+	top: number;
+}
+
 interface AtlasEncoderPipeline {
 	ensureAlpha(): AtlasEncoderPipeline;
 	raw(): AtlasEncoderPipeline;
@@ -228,85 +227,31 @@ interface AtlasEncoderPipeline {
 	toBuffer(options: { resolveWithObject: true }): Promise<AtlasEncoderResolvedBuffer>;
 	toBuffer(options?: { resolveWithObject?: false }): Promise<Uint8Array>;
 	toBuffer(options?: { resolveWithObject?: boolean }): Promise<Uint8Array | AtlasEncoderResolvedBuffer>;
-	png(): AtlasEncoderPipeline;
-	metadata(): Promise<AtlasEncoderMetadata>;
-	rotate(angle: number): AtlasEncoderPipeline;
-	composite(inputs: AtlasCompositeInput[]): AtlasEncoderPipeline;
-	toFile(path: string): Promise<unknown>;
-}
-
-type AtlasEncoderInput =
-	| string
-	| Uint8Array
-	| {
-		create: {
-			width: number;
-			height: number;
-			channels: 4;
-			background: { r: number; g: number; b: number; alpha: number };
-		};
-	};
-
+	png(): AtlasEncoderPipeline;
+	metadata(): Promise<AtlasEncoderMetadata>;
+	rotate(angle: number): AtlasEncoderPipeline;
+	composite(inputs: AtlasCompositeInput[]): AtlasEncoderPipeline;
+	toFile(path: string): Promise<unknown>;
+}
+
+type AtlasEncoderInput =
+	| string
+	| Uint8Array
+	| {
+		create: {
+			width: number;
+			height: number;
+			channels: 4;
+			background: { r: number; g: number; b: number; alpha: number };
+		};
+	};
+
 type AtlasEncoder = (input: AtlasEncoderInput) => AtlasEncoderPipeline;
 
 function resolveFontFileName(fontName: string): string {
 	return /\.fnt$/i.test(fontName) ? fontName : `${fontName}.fnt`;
 }
 
-function addLocalResourceByUiUrl(
-	target: PackageResource[],
-	added: Set<string>,
-	resourceMap: Map<string, PackageResource>,
-	pkgId: string,
-	value: string | null | undefined,
-): void {
-	if (!value || typeof value !== 'string' || !value.startsWith('ui://')) return;
-	const normalized = value.slice(5).split(',')[0] ?? '';
-	if (!normalized) return;
-	let resourceId = '';
-	const slashIndex = normalized.indexOf('/');
-	if (slashIndex >= 0) {
-		const packageToken = normalized.slice(0, slashIndex);
-		if (packageToken !== pkgId) return;
-		resourceId = normalized.slice(slashIndex + 1);
-	} else if (normalized.length > 8) {
-		const packageToken = normalized.slice(0, 8);
-		if (packageToken !== pkgId) return;
-		resourceId = normalized.slice(8);
-	}
-	if (!resourceId) return;
-	const resource = resourceMap.get(resourceId);
-	if (!resource || added.has(resourceId)) return;
-	added.add(resourceId);
-	target.push(resource);
-}
-
-function addLocalResourcesByText(
-	target: PackageResource[],
-	added: Set<string>,
-	resourceMap: Map<string, PackageResource>,
-	pkgId: string,
-	value: string | null | undefined,
-): void {
-	if (!value || typeof value !== 'string') return;
-	for (const match of value.matchAll(/ui:\/\/[0-9a-z]{8}[0-9a-z]+/gi)) {
-		addLocalResourceByUiUrl(target, added, resourceMap, pkgId, match[0]);
-	}
-}
-
-function addResourceById(
-	target: PackageResource[],
-	added: Set<string>,
-	resourceMap: Map<string, PackageResource>,
-	resourceId: string | null | undefined,
-): void {
-	if (!resourceId) return;
-	const resource = resourceMap.get(resourceId);
-	if (!resource || added.has(resourceId)) return;
-	added.add(resourceId);
-	target.push(resource);
-}
-
 async function resolveEditorCompatibleResourceOrder(
 	pkg: Package,
 	allResources: PackageResource[],
@@ -449,38 +394,38 @@ async function resolveEditorCompatibleResourceOrder(
 
 	return ordered;
 }
-
-/**
- * Packs image resources into texture atlases.
- *
- * This transform performs MaxRects bin-packing on all ImageResource items
- * within each package, creating Atlas and Sprite property nodes. When an
- * `encoder` (sharp) is provided, it also composites the actual PNG files.
- *
- * When `trimImage` is enabled and encoder is available, transparent pixels
- * at image edges are trimmed before packing. The trimmed offset and original
- * dimensions are stored in the Sprite nodes for runtime reconstruction.
- *
- * ```ts
- * import sharp from 'sharp';
- * await doc.transform(atlas({
- *   encoder: sharp,
- *   maxSize: 2048,
- *   trimImage: true,
- *   basePath: './assets/',
- *   outputPath: './dist/',
- * }));
- * ```
- */
+
+/**
+ * Packs image resources into texture atlases.
+ *
+ * This transform performs MaxRects bin-packing on all ImageResource items
+ * within each package, creating Atlas and Sprite property nodes. When an
+ * `encoder` (sharp) is provided, it also composites the actual PNG files.
+ *
+ * When `trimImage` is enabled and encoder is available, transparent pixels
+ * at image edges are trimmed before packing. The trimmed offset and original
+ * dimensions are stored in the Sprite nodes for runtime reconstruction.
+ *
+ * ```ts
+ * import sharp from 'sharp';
+ * await doc.transform(atlas({
+ *   encoder: sharp,
+ *   maxSize: 2048,
+ *   trimImage: true,
+ *   basePath: './assets/',
+ *   outputPath: './dist/',
+ * }));
+ * ```
+ */
 export function atlas(_options: AtlasOptions = {}): Transform {
-	const options = { ...ATLAS_DEFAULTS, ..._options };
-
-	return createTransform('atlas', async (doc: Document): Promise<void> => {
-		const root = doc.getRoot();
-		const logger = doc.getLogger();
-		const encoder = options.encoder as AtlasEncoder | undefined;
-		const doTrim = options.trimImage && !!encoder && !!options.basePath;
-
+	const options = { ...ATLAS_DEFAULTS, ..._options };
+
+	return createTransform('atlas', async (doc: Document): Promise<void> => {
+		const root = doc.getRoot();
+		const logger = doc.getLogger();
+		const encoder = options.encoder as AtlasEncoder | undefined;
+		const doTrim = options.trimImage && !!encoder && !!options.basePath;
+
 		for (const pkg of root.listPackages()) {
 			// Respect publish-selected resources when publish() precomputes a merged branch view.
 			const selectedPublishIds = new Set(((pkg.getExtras() as PackageAtlasExtras | undefined) ?? {}).publishedResourceIds ?? []);
@@ -494,30 +439,30 @@ export function atlas(_options: AtlasOptions = {}): Transform {
 			const orderedAllResources = sortResourcesByOrder(allResources, resourceOrder, inputOrder);
 			const hasPackable = allResources.some((resource) => isPackableResource(resource));
 			if (!hasPackable) continue;
-
-			// Collect packable items in declaration order
-			const inputs: InputItem[] = [];
-
-			// Build set of referenced resource IDs (editor only packs referenced images)
-			// Walk component tree recursively to find all image references
-			const referencedIds = new Set<string>();
-			const resourceMap = new Map<string, PackageResource>();
-			for (const res of allResources) {
-				const id = res.getId();
-				if (id) resourceMap.set(id, res);
-			}
-			function collectRefs(component: Component, visited: Set<string>): void {
-				for (const child of component.listChildren()) {
-					const refChild = child as ChildWithReferenceUrls;
-					const src = refChild.getSrc?.();
-					if (src && !visited.has(src)) {
-						referencedIds.add(src);
-						visited.add(src);
-						const srcRes = resourceMap.get(src);
-						if (srcRes && isComponentResource(srcRes)) {
-							collectRefs(srcRes, visited);
-						}
-					}
+
+			// Collect packable items in declaration order
+			const inputs: InputItem[] = [];
+
+			// Build set of referenced resource IDs (editor only packs referenced images)
+			// Walk component tree recursively to find all image references
+			const referencedIds = new Set<string>();
+			const resourceMap = new Map<string, PackageResource>();
+			for (const res of allResources) {
+				const id = res.getId();
+				if (id) resourceMap.set(id, res);
+			}
+			function collectRefs(component: Component, visited: Set<string>): void {
+				for (const child of component.listChildren()) {
+					const refChild = child as ChildWithReferenceUrls;
+					const src = refChild.getSrc?.();
+					if (src && !visited.has(src)) {
+						referencedIds.add(src);
+						visited.add(src);
+						const srcRes = resourceMap.get(src);
+						if (srcRes && isComponentResource(srcRes)) {
+							collectRefs(srcRes, visited);
+						}
+					}
 					for (const ref of [
 						refChild.getIcon?.(),
 						refChild.getSelectedIcon?.(),
@@ -565,23 +510,23 @@ export function atlas(_options: AtlasOptions = {}): Transform {
 				if (isFontResource(res)) {
 					const textureId = res.getTextureId?.() ?? '';
 					if (textureId) referencedIds.add(textureId);
-					// Parse .fnt file for glyph image references
+					// Parse .fnt file for glyph image references
 					if (options.readFileRaw && options.basePath) {
 						const fontName = resolveFontFileName(res.getName());
 						const fontPath = res.getPath() ?? '/';
 						const fntFile = `${options.basePath}/${pkg.getName()}${fontPath}${fontName}`;
-						try {
-							const fntData = await options.readFileRaw(fntFile);
-							const fntText = new TextDecoder().decode(fntData);
-							for (const line of fntText.split(/\r?\n/)) {
-								const match = line.match(/img=(\w+)/);
-								if (match) referencedIds.add(match[1]);
-							}
-						} catch { /* .fnt file not found — OK */ }
-					}
-				}
-			}
-
+						try {
+							const fntData = await options.readFileRaw(fntFile);
+							const fntText = new TextDecoder().decode(fntData);
+							for (const line of fntText.split(/\r?\n/)) {
+								const match = line.match(/img=(\w+)/);
+								if (match) referencedIds.add(match[1]);
+							}
+						} catch { /* .fnt file not found — OK */ }
+					}
+				}
+			}
+
 			for (const res of orderedAllResources) {
 				if (isImageResource(res)) {
 					// Pack referenced images, plus explicitly exported standalone images.
@@ -801,7 +746,7 @@ function buildBranchAtlasGroups(doc: Document, inputs: InputItem[], options: Atl
 			inputs: groups.get(branchName) ?? [],
 		}));
 }
-
+
 function inputToCompatRect(input: InputItem, index: number): CompatNodeRect {
 	const duplicatePadding = isImageResource(input.resource) && input.resource.getDuplicatePadding?.() === true;
 	return {
@@ -983,12 +928,12 @@ interface ExtractedJtaData {
 	frames: Uint8Array[];
 	meta?: ExtractedJtaMeta;
 }
-
-/**
- * Trim transparent edges from an image using sharp.
- * Returns the trimmed buffer, dimensions, and offsets.
- * Falls back to the original image if trim fails (e.g. no alpha channel, no transparent edges).
- */
+
+/**
+ * Trim transparent edges from an image using sharp.
+ * Returns the trimmed buffer, dimensions, and offsets.
+ * Falls back to the original image if trim fails (e.g. no alpha channel, no transparent edges).
+ */
 async function _trimImage(
 	encoder: AtlasEncoder,
 	filePath: string,
@@ -1055,24 +1000,24 @@ async function _trimImage(
 			originalWidth,
 			originalHeight,
 		};
-	} catch {
-		// Trim failed (e.g. JPEG without alpha, nothing to trim) — return original
-		const buf = await encoder(filePath).png().toBuffer();
-		return {
-			buffer: buf,
-			width: originalWidth,
-			height: originalHeight,
-			offsetX: 0,
-			offsetY: 0,
-			originalWidth,
-			originalHeight,
-		};
-	}
-}
-
-/**
- * Resolve an ImageResource to its actual file path on disk.
- */
+	} catch {
+		// Trim failed (e.g. JPEG without alpha, nothing to trim) — return original
+		const buf = await encoder(filePath).png().toBuffer();
+		return {
+			buffer: buf,
+			width: originalWidth,
+			height: originalHeight,
+			offsetX: 0,
+			offsetY: 0,
+			originalWidth,
+			originalHeight,
+		};
+	}
+}
+
+/**
+ * Resolve an ImageResource to its actual file path on disk.
+ */
 function _resolveImagePath(resource: ImageResource, pkg: Package, basePath: string): string {
 	const imgPath = resource.getPath() ?? '/';
 	const fileName = resolveImageFileName(resource);
@@ -1085,7 +1030,7 @@ function _resolveImagePath(resource: ImageResource, pkg: Package, basePath: stri
 			: `${normalizedBasePath}_${branchName}`;
 	return `${packageBasePath}/${pkg.getName()}${imgPath}${fileName}`;
 }
-
+
 type InputItem = {
 	id: string; width: number; height: number;
 	originalWidth: number; originalHeight: number;
@@ -1093,17 +1038,17 @@ type InputItem = {
 	resource: PackInputResource; trimBuffer?: Uint8Array;
 	sourceKind: 'image' | 'movieclip-frame';
 };
-
-/** Collect a single ImageResource into the inputs array. */
+
+/** Collect a single ImageResource into the inputs array. */
 async function _collectImage(
 	resource: ImageResource,
-	pkg: Package,
-	inputs: InputItem[],
-	encoder: AtlasEncoder | undefined,
-	options: AtlasOptions,
-	doTrim: boolean,
-	logger: ILogger,
-): Promise<void> {
+	pkg: Package,
+	inputs: InputItem[],
+	encoder: AtlasEncoder | undefined,
+	options: AtlasOptions,
+	doTrim: boolean,
+	logger: ILogger,
+): Promise<void> {
 	let origW = resource.getWidth() ?? 0;
 	let origH = resource.getHeight() ?? 0;
 	let sourceHasAlpha = false;
@@ -1128,24 +1073,24 @@ async function _collectImage(
 	}
 
 	if (origW <= 0 || origH <= 0) return;
-
-	let packW = origW, packH = origH, offX = 0, offY = 0;
-	let trimBuf: Uint8Array | undefined;
-
+
+	let packW = origW, packH = origH, offX = 0, offY = 0;
+	let trimBuf: Uint8Array | undefined;
+
 	if (doTrim && sourceHasAlpha && options.basePath && encoder) {
 		const filePath = _resolveImagePath(resource, pkg, options.basePath);
 		try {
 			const trimResult = await _trimImage(encoder, filePath, origW, origH);
-			packW = trimResult.width;
-			packH = trimResult.height;
-			offX = trimResult.offsetX;
-			offY = trimResult.offsetY;
-			trimBuf = trimResult.buffer;
-		} catch {
-			logger.warn(`atlas: Could not trim "${filePath}", using original.`);
-		}
-	}
-
+			packW = trimResult.width;
+			packH = trimResult.height;
+			offX = trimResult.offsetX;
+			offY = trimResult.offsetY;
+			trimBuf = trimResult.buffer;
+		} catch {
+			logger.warn(`atlas: Could not trim "${filePath}", using original.`);
+		}
+	}
+
 	inputs.push({
 		id: getPublishedItemId(resource), width: packW, height: packH,
 		originalWidth: origW, originalHeight: origH,
@@ -1155,22 +1100,22 @@ async function _collectImage(
 		sourceKind: 'image',
 	});
 }
-
-/** Collect MovieClip frame textures from a .jta file into the inputs array. */
+
+/** Collect MovieClip frame textures from a .jta file into the inputs array. */
 async function _collectMovieClipFrames(
 	doc: Document,
 	resource: MovieClipResource,
 	pkg: Package,
 	inputs: InputItem[],
-	encoder: AtlasEncoder | undefined,
-	options: AtlasOptions,
-	logger: ILogger,
-): Promise<void> {
-	if (!options.basePath || !options.readFileRaw) return;
-
-	const mcId = resource.getId();
-	const mcName = resource.getName() + '.jta';
-	const mcPath = resource.getPath() ?? '/';
+	encoder: AtlasEncoder | undefined,
+	options: AtlasOptions,
+	logger: ILogger,
+): Promise<void> {
+	if (!options.basePath || !options.readFileRaw) return;
+
+	const mcId = resource.getId();
+	const mcName = resource.getName() + '.jta';
+	const mcPath = resource.getPath() ?? '/';
 	const filePath = `${options.basePath}/${pkg.getName()}${mcPath}${mcName}`;
 
 	try {
@@ -1465,32 +1410,31 @@ function _readUint32BE(data: Uint8Array, offset: number): number {
 		(data[offset + 3] ?? 0)
 	);
 }
-
-/** Collect a Bitmap Font's texture image, packed under the font's ID. */
+
+/** Collect a Bitmap Font's texture image, packed under the font's ID. */
 async function _collectFontTexture(
 	doc: Document,
 	fontRes: FontResource,
 	pkg: Package,
 	options: AtlasOptions,
 ): Promise<void> {
-	const extras = fontRes.getExtras() as FontResourceExtras;
 	const textureId = fontRes.getTextureId?.() ?? '';
-
-	if (textureId) {
-		// Record font→texture mapping so we can add a duplicate sprite entry
-		// after atlas packing. The editor stores both the image ID (jb800) and
-		// the font ID (wa8u2r) as separate sprites at the same atlas position.
-		const fontId = fontRes.getId();
-		fontRes.setExtras({ ...fontRes.getExtras(), _fontSpriteAlias: { fontId, textureId } });
-	}
-
-	// Parse .fnt file for glyph data (needed for binary encoding)
-	// This applies to ALL fonts, not just those with a textureId
+
+	if (textureId) {
+		// Record font→texture mapping so we can add a duplicate sprite entry
+		// after atlas packing. The editor stores both the image ID (jb800) and
+		// the font ID (wa8u2r) as separate sprites at the same atlas position.
+		const fontId = fontRes.getId();
+		fontRes.setExtras({ ...fontRes.getExtras(), _fontSpriteAlias: { fontId, textureId } });
+	}
+
+	// Parse .fnt file for glyph data (needed for binary encoding)
+	// This applies to ALL fonts, not just those with a textureId
 	if (options.readFileRaw && options.basePath) {
 		const fontName = resolveFontFileName(fontRes.getName());
 		const fontPath = fontRes.getPath() ?? '/';
 		const pkgName = pkg.getName();
-		const fntFile = `${options.basePath}/${pkgName}${fontPath}${fontName}`;
+		const fntFile = `${options.basePath}/${pkgName}${fontPath}${fontName}`;
 		try {
 			const fntData = await options.readFileRaw(fntFile);
 			const fntText = new TextDecoder().decode(fntData);
@@ -1526,84 +1470,84 @@ async function _collectFontTexture(
 		} catch { /* .fnt not found */ }
 	}
 }
-
-/** Parse a BMFont .fnt text file into structured data for binary encoding. */
-function _parseFnt(text: string): {
-	hasFace: boolean; colored: boolean; resizable: boolean; hasChannel: boolean;
-	fontSize: number; xadvance: number; lineHeight: number;
-	glyphs: Array<{
-		charId: number; img: string | null;
-		x: number; y: number; xoffset: number; yoffset: number;
-		width: number; height: number; xadvance: number; channel: number;
-	}>;
-} {
-	const lines = text.split(/\r?\n/);
-	let hasFace = false, colored = false, resizable = false, hasChannel = false;
-	let fontSize = 0, globalXadvance = 0, lineHeight = 0;
-	const glyphs: Array<{
-		charId: number; img: string | null;
-		x: number; y: number; xoffset: number; yoffset: number;
-		width: number; height: number; xadvance: number; channel: number;
-	}> = [];
-
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		const parts = trimmed.split(/\s+/);
-		const attrs: Record<string, string> = {};
-		for (let i = 1; i < parts.length; i++) {
-			const eq = parts[i].split('=');
-			if (eq.length === 2) attrs[eq[0]] = eq[1];
-		}
-
-		switch (parts[0]) {
-			case 'info':
-				hasFace = attrs.face != null;
-				colored = hasFace;
-				if (attrs.colored !== undefined) colored = attrs.colored === 'true';
-				fontSize = parseInt(attrs.size, 10) || 0;
-				resizable = attrs.resizable === 'true';
-				break;
-			case 'common':
-				lineHeight = parseInt(attrs.lineHeight, 10) || 0;
-				globalXadvance = parseInt(attrs.xadvance, 10) || 0;
-				if (fontSize === 0) fontSize = lineHeight;
-				else if (lineHeight === 0) lineHeight = fontSize;
-				break;
-			case 'char': {
-				const charId = parseInt(attrs.id, 10) || 0;
-				if (charId === 0) continue;
-				const img = attrs.img || null;
-				if (!hasFace && !img) continue;
-				const chnl = parseInt(attrs.chnl, 10) || 0;
-				if (chnl !== 0 && chnl !== 15) hasChannel = true;
-				glyphs.push({
-					charId, img,
-					x: parseInt(attrs.x, 10) || 0,
-					y: parseInt(attrs.y, 10) || 0,
-					xoffset: parseInt(attrs.xoffset, 10) || 0,
-					yoffset: parseInt(attrs.yoffset, 10) || 0,
-					width: parseInt(attrs.width, 10) || 0,
-					height: parseInt(attrs.height, 10) || 0,
-					xadvance: parseInt(attrs.xadvance, 10) || 0,
-					channel: chnl,
-				});
-				break;
-			}
-		}
-	}
-
-	return { hasFace, colored, resizable: fontSize > 0 ? resizable : false, hasChannel, fontSize, xadvance: globalXadvance, lineHeight, glyphs };
-}
-
-function isComponentResource(resource: PackageResource): resource is Component {
-	return resource.propertyType === 'Component';
-}
-
-function isImageResource(resource: PackageResource): resource is ImageResource {
-	return resource.propertyType === 'ImageResource';
-}
-
+
+/** Parse a BMFont .fnt text file into structured data for binary encoding. */
+function _parseFnt(text: string): {
+	hasFace: boolean; colored: boolean; resizable: boolean; hasChannel: boolean;
+	fontSize: number; xadvance: number; lineHeight: number;
+	glyphs: Array<{
+		charId: number; img: string | null;
+		x: number; y: number; xoffset: number; yoffset: number;
+		width: number; height: number; xadvance: number; channel: number;
+	}>;
+} {
+	const lines = text.split(/\r?\n/);
+	let hasFace = false, colored = false, resizable = false, hasChannel = false;
+	let fontSize = 0, globalXadvance = 0, lineHeight = 0;
+	const glyphs: Array<{
+		charId: number; img: string | null;
+		x: number; y: number; xoffset: number; yoffset: number;
+		width: number; height: number; xadvance: number; channel: number;
+	}> = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const parts = trimmed.split(/\s+/);
+		const attrs: Record<string, string> = {};
+		for (let i = 1; i < parts.length; i++) {
+			const eq = parts[i].split('=');
+			if (eq.length === 2) attrs[eq[0]] = eq[1];
+		}
+
+		switch (parts[0]) {
+			case 'info':
+				hasFace = attrs.face != null;
+				colored = hasFace;
+				if (attrs.colored !== undefined) colored = attrs.colored === 'true';
+				fontSize = parseInt(attrs.size, 10) || 0;
+				resizable = attrs.resizable === 'true';
+				break;
+			case 'common':
+				lineHeight = parseInt(attrs.lineHeight, 10) || 0;
+				globalXadvance = parseInt(attrs.xadvance, 10) || 0;
+				if (fontSize === 0) fontSize = lineHeight;
+				else if (lineHeight === 0) lineHeight = fontSize;
+				break;
+			case 'char': {
+				const charId = parseInt(attrs.id, 10) || 0;
+				if (charId === 0) continue;
+				const img = attrs.img || null;
+				if (!hasFace && !img) continue;
+				const chnl = parseInt(attrs.chnl, 10) || 0;
+				if (chnl !== 0 && chnl !== 15) hasChannel = true;
+				glyphs.push({
+					charId, img,
+					x: parseInt(attrs.x, 10) || 0,
+					y: parseInt(attrs.y, 10) || 0,
+					xoffset: parseInt(attrs.xoffset, 10) || 0,
+					yoffset: parseInt(attrs.yoffset, 10) || 0,
+					width: parseInt(attrs.width, 10) || 0,
+					height: parseInt(attrs.height, 10) || 0,
+					xadvance: parseInt(attrs.xadvance, 10) || 0,
+					channel: chnl,
+				});
+				break;
+			}
+		}
+	}
+
+	return { hasFace, colored, resizable: fontSize > 0 ? resizable : false, hasChannel, fontSize, xadvance: globalXadvance, lineHeight, glyphs };
+}
+
+function isComponentResource(resource: PackageResource): resource is Component {
+	return resource.propertyType === 'Component';
+}
+
+function isImageResource(resource: PackageResource): resource is ImageResource {
+	return resource.propertyType === 'ImageResource';
+}
+
 function isMovieClipResource(resource: PackageResource): resource is MovieClipResource {
 	return resource.propertyType === 'MovieClipResource';
 }
@@ -1611,15 +1555,15 @@ function isMovieClipResource(resource: PackageResource): resource is MovieClipRe
 function isSkeletonResource(resource: PackageResource): resource is SpineResource | DragonBonesResource {
 	return resource.propertyType === 'SpineResource' || resource.propertyType === 'DragonBonesResource';
 }
-
-function isFontResource(resource: PackageResource): resource is FontResource {
-	return resource.propertyType === 'FontResource';
-}
-
-function isPackableResource(resource: PackageResource): resource is PackableResource {
-	return isImageResource(resource) || isMovieClipResource(resource) || isFontResource(resource);
-}
-
+
+function isFontResource(resource: PackageResource): resource is FontResource {
+	return resource.propertyType === 'FontResource';
+}
+
+function isPackableResource(resource: PackageResource): resource is PackableResource {
+	return isImageResource(resource) || isMovieClipResource(resource) || isFontResource(resource);
+}
+
 function addUiResourceRef(target: Set<string>, value: string | undefined | null): void {
 	if (!value?.startsWith('ui://')) return;
 	const refId = value.slice(5).slice(8);
@@ -1645,7 +1589,7 @@ function addUiResourceRefsFromUnknown(target: Set<string>, value: unknown): void
 		addUiResourceRefsFromText(target, value);
 	}
 }
-
-function isResolvedBuffer(value: Uint8Array | AtlasEncoderResolvedBuffer): value is AtlasEncoderResolvedBuffer {
-	return typeof value === 'object' && value !== null && 'data' in value && 'info' in value;
-}
+
+function isResolvedBuffer(value: Uint8Array | AtlasEncoderResolvedBuffer): value is AtlasEncoderResolvedBuffer {
+	return typeof value === 'object' && value !== null && 'data' in value && 'info' in value;
+}