@openfairygui/functions 0.2.0-alpha.34 → 0.2.0-alpha.35

package/src/adapters/web/publish.ts

@@ -1,11 +1,13 @@
 import { type Document, type ILogger, ProjectType } from '@openfairygui/core';
 import type { AtlasOptions } from '../../atlas.js';
+import { resolveCodeGenerationSettings } from '../../codegen.js';
 import { publish } from '../../publish.js';
 import type {
 	PublishFileSystem,
 	PublishOutputFileSystem,
 	PublishSourceFileSystem,
 } from '../../publish/contracts.js';
+import { resolvePublishOptions } from '../../publish/options.js';
 import { assertBrowserImageSupport, createBrowserImageEncoder } from './raster.js';
 
 export type BrowserPublishProjectType = 'layabox';
@@ -42,6 +44,9 @@ export interface BrowserPublishOptions {
 export interface BrowserPublishDiagnostic {
 	level: 'debug' | 'info' | 'warning' | 'error';
 	message: string;
+	code?: 'unsupported_publish_setting' | 'publish_failed';
+	setting?: string;
+	path?: string;
 }
 
 export interface BrowserPublishedFile {
@@ -103,6 +108,10 @@ function toResult(
 	};
 }
 
+function unsupportedSetting(setting: string, path: string, message: string): BrowserPublishDiagnostic {
+	return { level: 'error', code: 'unsupported_publish_setting', setting, path, message };
+}
+
 /**
  * Publish a loaded FairyGUI project to browser-provided storage.
  *
@@ -121,16 +130,43 @@ export async function publishBrowser(options: BrowserPublishOptions): Promise<Br
 		if (options.projectType !== 'layabox') {
 			throw new Error(`publishBrowser: unsupported project type "${String(options.projectType)}".`);
 		}
-		assertBrowserImageSupport();
 		root.setProjectType(ProjectType.LayaBox);
+		const resolved = resolvePublishOptions(options.document, {
+			compressed: options.compressed,
+			packages: options.packages,
+			atlas: options.atlas,
+		});
+		if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(resolved.fileExtension)) {
+			diagnostics.push(unsupportedSetting(
+				'fileExtension',
+				'settings.publish.fileExtension',
+				`publishBrowser: unsupported fileExtension "${resolved.fileExtension}".`,
+			));
+			return toResult(false, files, diagnostics);
+		}
+		const selectedPackageNames = options.packages?.length ? new Set(options.packages) : null;
+		const selectedPackages = root.listPackages().filter((pkg) => !selectedPackageNames || selectedPackageNames.has(pkg.getName()));
+		if (resolveCodeGenerationSettings(options.document).allowGenCode) {
+			const packageIndex = selectedPackages.findIndex((pkg) => pkg.getGenCode());
+			if (packageIndex >= 0) {
+				const pkg = selectedPackages[packageIndex]!;
+				diagnostics.push(unsupportedSetting(
+					'codeGeneration',
+					`packages[${root.listPackages().indexOf(pkg)}].publish.genCode`,
+					`publishBrowser: code generation requested by package "${pkg.getName()}" is not supported.`,
+				));
+				return toResult(false, files, diagnostics);
+			}
+		}
+		assertBrowserImageSupport();
 		const outputFileSystem = createTrackingFileSystem(options.outputFileSystem, files);
 		const sourceAssetsPath = options.sourceFileSystem.join(options.document.getProjectDir(), 'assets');
 
 		await options.document.transform(
 			publish({
 				output: options.output,
-				compressed: options.compressed,
-				fileExtension: 'fui',
+				compressed: resolved.compressed,
+				fileExtension: resolved.fileExtension,
 				packages: options.packages,
 				branch: options.branch,
 				basePath: sourceAssetsPath,
@@ -149,6 +185,7 @@ export async function publishBrowser(options: BrowserPublishOptions): Promise<Br
 	} catch (error) {
 		diagnostics.push({
 			level: 'error',
+			code: 'publish_failed',
 			message: error instanceof Error ? error.message : String(error),
 		});
 		return toResult(false, files, diagnostics);

package/src/atlas/inputs.ts

@@ -21,7 +21,7 @@ import {
 } from '../publish/package-context.js';
 import type { ExtrasMap } from '../shared-types.js';
 import { parseFnt } from './font.js';
-import { extractJtaFrames } from './jta.js';
+import { prepareJtaForPublish, type PreparedJtaData } from './jta.js';
 
 /** Trim info for a single image. */
 interface TrimInfo {
@@ -181,6 +181,36 @@ export interface PagedAtlasGroup {
 	inputs: InputItem[];
 }
 
+export function resolveMovieClipSourcePath(resource: MovieClipResource, pkg: Package, basePath: string): string {
+	const fileName = `${resource.getName()}.jta`;
+	const resourcePath = resource.getPath() ?? '/';
+	return `${basePath}/${pkg.getName()}${resourcePath}${fileName}`;
+}
+
+export async function prepareMovieClipResource(
+	resource: MovieClipResource,
+	pkg: Package,
+	encoder: AtlasRasterBackend | undefined,
+	basePath: string,
+	readFileRaw: (path: string) => Promise<Uint8Array>,
+): Promise<PreparedJtaData> {
+	const filePath = resolveMovieClipSourcePath(resource, pkg, basePath);
+	let raw: Uint8Array;
+	try {
+		raw = await readFileRaw(filePath);
+	} catch {
+		throw new Error(`atlas: Could not read MovieClip "${filePath}".`);
+	}
+
+	try {
+		return await prepareJtaForPublish(raw, encoder, filePath);
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith('atlas:')) throw error;
+		const detail = error instanceof Error ? ` ${error.message}` : '';
+		throw new Error(`atlas: Could not parse MovieClip "${filePath}".${detail}`);
+	}
+}
+
 /** Collect a single ImageResource into the inputs array. */
 export async function collectImage(
 	resource: ImageResource,
@@ -285,130 +315,62 @@ export async function collectMovieClipFrames(
 	}
 
 	const mcId = resource.getId();
-	const mcName = resource.getName() + '.jta';
-	const mcPath = resource.getPath() ?? '/';
-	const filePath = `${options.basePath}/${pkg.getName()}${mcPath}${mcName}`;
+	const filePath = resolveMovieClipSourcePath(resource, pkg, options.basePath);
 
 	try {
-		const raw = await options.readFileRaw(filePath);
-		const jta = extractJtaFrames(raw);
-		if (jta.frames.length === 0) return;
-
-		const frameMetas = jta.meta?.frames ?? [];
+		const jta =
+			options.preparedMovieClips?.get(resource) ??
+			(await prepareMovieClipResource(resource, pkg, encoder, options.basePath, options.readFileRaw));
 		for (const frame of resource.listFrames()) {
 			resource.removeFrame(frame);
 		}
 		resource
-			.setInterval(jta.meta?.interval ?? 100)
-			.setSwing(jta.meta?.swing ?? false)
-			.setRepeatDelay(jta.meta?.repeatDelay ?? 0);
-
-		if (frameMetas.length > 0) {
-			const firstFrameIndexByTextureIndex = new Map<number, number>();
-			for (let frameIndex = 0; frameIndex < frameMetas.length; frameIndex += 1) {
-				const meta = frameMetas[frameIndex];
-				const textureIndex = Number.isFinite(meta.textureIndex) ? meta.textureIndex : frameIndex;
-				if (!firstFrameIndexByTextureIndex.has(textureIndex)) {
-					firstFrameIndexByTextureIndex.set(textureIndex, frameIndex);
-				}
-			}
-
-			const spriteIdByTextureIndex = new Map<number, string>();
-			for (let textureIndex = 0; textureIndex < jta.frames.length; textureIndex += 1) {
-				const exportFrameIndex = firstFrameIndexByTextureIndex.get(textureIndex);
-				if (exportFrameIndex === undefined) continue;
-				const itemId = `${mcId}_${exportFrameIndex}`;
-			const input = await createMovieClipFrameInput(
-				jta.frames[textureIndex],
-				itemId,
+			.setInterval(jta.meta.interval)
+			.setSwing(jta.meta.swing)
+			.setRepeatDelay(jta.meta.repeatDelay);
+		const spriteIdByTextureIndex = new Map<number, string>();
+		for (const texture of jta.referencedTextures) {
+			if (texture.width <= 0 || texture.height <= 0) continue;
+			const itemId = `${mcId}_${texture.firstFrameIndex}`;
+			inputs.push({
+				id: itemId,
+				width: texture.width,
+				height: texture.height,
+				originalWidth: texture.width,
+				originalHeight: texture.height,
+				offsetX: 0,
+				offsetY: 0,
 				resource,
-				encoder,
-				options.strictOutput,
-			);
-				if (!input) continue;
-				inputs.push(input);
-				spriteIdByTextureIndex.set(textureIndex, itemId);
-			}
+				trimBuffer: texture.buffer,
+				sourceKind: 'movieclip-frame',
+			});
+			spriteIdByTextureIndex.set(texture.textureIndex, itemId);
+		}
 
-			for (let frameIndex = 0; frameIndex < frameMetas.length; frameIndex += 1) {
-				const meta = frameMetas[frameIndex];
-				const textureIndex = Number.isFinite(meta.textureIndex) ? meta.textureIndex : frameIndex;
-				const frame = doc.createMovieFrame(`${mcId}_${frameIndex}`);
-				frame
-					.setRectX(meta.offsetX)
-					.setRectY(meta.offsetY)
-					.setRectWidth(meta.width)
-					.setRectHeight(meta.height)
-					.setAddDelay(meta.addDelay)
-					.setSpriteId(spriteIdByTextureIndex.get(textureIndex) ?? '');
-				resource.addFrame(frame);
-			}
-		} else {
-			for (let frameIndex = 0; frameIndex < jta.frames.length; frameIndex += 1) {
-				const itemId = `${mcId}_${frameIndex}`;
-				const input = await createMovieClipFrameInput(
-					jta.frames[frameIndex],
-					itemId,
-					resource,
-					encoder,
-					options.strictOutput,
-				);
-				if (!input) continue;
-				inputs.push(input);
-				const frame = doc.createMovieFrame(itemId);
-				frame
-					.setRectX(0)
-					.setRectY(0)
-					.setRectWidth(input.originalWidth)
-					.setRectHeight(input.originalHeight)
-					.setAddDelay(0)
-					.setSpriteId(itemId);
-				resource.addFrame(frame);
-			}
+		for (let frameIndex = 0; frameIndex < jta.meta.frames.length; frameIndex += 1) {
+			const meta = jta.meta.frames[frameIndex]!;
+			const frame = doc.createMovieFrame(`${mcId}_${frameIndex}`);
+			frame
+				.setRectX(meta.offsetX)
+				.setRectY(meta.offsetY)
+				.setRectWidth(meta.width)
+				.setRectHeight(meta.height)
+				.setAddDelay(meta.addDelay)
+				.setSpriteId(meta.textureIndex === -1 ? '' : (spriteIdByTextureIndex.get(meta.textureIndex) ?? ''));
+			resource.addFrame(frame);
 		}
 
-		if ((jta.meta?.width ?? 0) > 0 && (jta.meta?.height ?? 0) > 0) {
-			resource.setWidth(jta.meta?.width ?? 0);
-			resource.setHeight(jta.meta?.height ?? 0);
+		if (jta.meta.width > 0 && jta.meta.height > 0) {
+			resource.setWidth(jta.meta.width);
+			resource.setHeight(jta.meta.height);
 		}
-	} catch {
-		const message = `atlas: Could not parse MovieClip "${filePath}".`;
-		if (options.strictOutput) throw new Error(message);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : `atlas: Could not parse MovieClip "${filePath}".`;
+		if (options.strictOutput) throw error;
 		logger.warn(`${message} Skipping frames.`);
 	}
 }
 
-async function createMovieClipFrameInput(
-	buffer: Uint8Array,
-	itemId: string,
-	resource: MovieClipResource,
-	encoder: AtlasRasterBackend | undefined,
-	strictOutput: boolean,
-): Promise<InputItem | null> {
-	if (!encoder || buffer.length === 0) return null;
-	try {
-		const meta = await encoder(buffer).metadata();
-		const width = meta.width ?? 0;
-		const height = meta.height ?? 0;
-		if (width <= 0 || height <= 0) return null;
-		return {
-			id: itemId,
-			width,
-			height,
-			originalWidth: width,
-			originalHeight: height,
-			offsetX: 0,
-			offsetY: 0,
-			resource,
-			trimBuffer: buffer,
-			sourceKind: 'movieclip-frame',
-		};
-	} catch {
-		if (strictOutput) throw new Error(`atlas: Could not decode MovieClip frame "${itemId}".`);
-		return null;
-	}
-}
-
 /** Collect a Bitmap Font's texture image, packed under the font's ID. */
 export async function collectFontTexture(
 	doc: Document,

package/src/atlas/jta.ts

@@ -1,3 +1,11 @@
+import {
+	deriveMovieClipModel,
+	parseJta,
+	probeRasterImage,
+	type RasterImageFormat,
+} from '@openfairygui/core';
+import type { AtlasRasterBackend } from '../publish/contracts.js';
+
 export interface JtaFrameMeta {
 	addDelay: number;
 	offsetX: number;
@@ -18,194 +26,132 @@ export interface JtaMeta {
 
 export interface ExtractedJtaData {
 	frames: Uint8Array[];
-	meta?: JtaMeta;
+	meta: JtaMeta;
 }
 
-const PNG_SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-
-export function extractJtaFrames(data: Uint8Array): ExtractedJtaData {
-	const frames: Uint8Array[] = [];
-	let offset = 0;
-	let firstPngOffset = -1;
-
-	while (offset < data.length) {
-		const signatureIndex = findPngSignature(data, offset);
-		if (signatureIndex === -1) break;
-		if (firstPngOffset === -1) firstPngOffset = signatureIndex;
-		const end = findPngEnd(data, signatureIndex);
-		if (end === -1) break;
-		frames.push(data.subarray(signatureIndex, end));
-		offset = end;
-	}
+export interface PreparedJtaTexture {
+	textureIndex: number;
+	firstFrameIndex: number;
+	/** PNG bytes validated during preflight and reused by atlas compositing. */
+	buffer: Uint8Array;
+	width: number;
+	height: number;
+}
 
-	if (firstPngOffset === -1 || frames.length === 0) {
-		return { frames: [] };
-	}
+export interface PreparedJtaData extends ExtractedJtaData {
+	referencedTextures: PreparedJtaTexture[];
+}
 
+export function extractJtaFrames(data: Uint8Array): ExtractedJtaData {
+	const parsed = parseJta(data);
+	const derived = deriveMovieClipModel(parsed);
 	return {
-		frames,
-		meta: parseJtaHeader(data, firstPngOffset, frames.length),
+		frames: parsed.textures.map((texture) => texture.raw),
+		meta: {
+			interval: derived.interval,
+			repeatDelay: derived.repeatDelay,
+			swing: derived.swing,
+			width: derived.dimensions.width,
+			height: derived.dimensions.height,
+			frames: derived.frames.map((frame) => ({
+				addDelay: frame.addDelay,
+				offsetX: frame.rectX,
+				offsetY: frame.rectY,
+				width: frame.rectWidth,
+				height: frame.rectHeight,
+				textureIndex: frame.textureIndex,
+			})),
+		},
 	};
 }
 
-function findPngSignature(data: Uint8Array, fromIndex: number): number {
-	for (let index = fromIndex; index <= data.length - PNG_SIGNATURE.length; index += 1) {
-		let matched = true;
-		for (let signatureIndex = 0; signatureIndex < PNG_SIGNATURE.length; signatureIndex += 1) {
-			if (data[index + signatureIndex] !== PNG_SIGNATURE[signatureIndex]) {
-				matched = false;
-				break;
-			}
-		}
-		if (matched) return index;
+function detectSupportedRasterFormat(data: Uint8Array): RasterImageFormat | null {
+	if (
+		data.length >= 8 &&
+		data[0] === 0x89 &&
+		data[1] === 0x50 &&
+		data[2] === 0x4e &&
+		data[3] === 0x47 &&
+		data[4] === 0x0d &&
+		data[5] === 0x0a &&
+		data[6] === 0x1a &&
+		data[7] === 0x0a
+	) {
+		return 'png';
 	}
-	return -1;
+	if (data.length >= 2 && data[0] === 0xff && data[1] === 0xd8) return 'jpeg';
+	return null;
 }
 
-function findPngEnd(data: Uint8Array, start: number): number {
-	let position = start + PNG_SIGNATURE.length;
-	while (position + 8 <= data.length) {
-		const length = readUint32BE(data, position);
-		position += 8;
-		if (position + length + 4 > data.length) return -1;
-		const isEnd =
-			data[position - 4] === 0x49 &&
-			data[position - 3] === 0x45 &&
-			data[position - 2] === 0x4e &&
-			data[position - 1] === 0x44;
-		position += length + 4;
-		if (isEnd) return position;
-	}
-	return -1;
+function couldNotDecode(filePath: string, frameIndex: number, textureIndex: number): Error {
+	return new Error(
+		`atlas: Could not decode MovieClip "${filePath}" frame ${frameIndex} (texture ${textureIndex}).`,
+	);
 }
 
-function parseJtaHeader(data: Uint8Array, firstPngOffset: number, frameCount: number): JtaMeta | undefined {
-	if (data.length < 10) return undefined;
-
-	const state = { offset: 0 };
-	const end = Math.min(firstPngOffset, data.length);
-	const mark = readUtfBE(data, state, end);
-	if (!mark) return undefined;
-
-	const version = readInt32BEAt(data, state, end);
-	if (version == null) return undefined;
-
-	const fpsRaw = readInt8At(data, state, end);
-	if (fpsRaw == null) return undefined;
-	const fps = fpsRaw > 0 ? fpsRaw : 24;
-
-	if (state.offset + 3 > end) return undefined;
-	state.offset += 3;
-
-	if (version < 102) return undefined;
-
-	readUint16BEAt(data, state, end);
-	readUint16BEAt(data, state, end);
-	const width = readUint16BEAt(data, state, end);
-	const height = readUint16BEAt(data, state, end);
-	if (width == null || height == null) return undefined;
+export async function prepareJtaForPublish(
+	data: Uint8Array,
+	encoder: AtlasRasterBackend | undefined,
+	filePath: string,
+): Promise<PreparedJtaData> {
+	const extracted = extractJtaFrames(data);
+	const firstFrameIndexByTextureIndex = new Map<number, number>();
+
+	for (let frameIndex = 0; frameIndex < extracted.meta.frames.length; frameIndex += 1) {
+		const textureIndex = extracted.meta.frames[frameIndex]!.textureIndex;
+		if (textureIndex >= 0 && !firstFrameIndexByTextureIndex.has(textureIndex)) {
+			firstFrameIndexByTextureIndex.set(textureIndex, frameIndex);
+		}
+	}
 
-	const speedRaw = readUint8At(data, state, end);
-	const repeatDelayRaw = readUint8At(data, state, end);
-	const swingRaw = readInt8At(data, state, end);
-	const frameTableCount = readInt16BEAt(data, state, end);
-	if (speedRaw == null || repeatDelayRaw == null || swingRaw == null || frameTableCount == null) return undefined;
+	const referencedTextures: PreparedJtaTexture[] = [];
+	for (let textureIndex = 0; textureIndex < extracted.frames.length; textureIndex += 1) {
+		const firstFrameIndex = firstFrameIndexByTextureIndex.get(textureIndex);
+		if (firstFrameIndex === undefined) continue;
+		const raw = extracted.frames[textureIndex]!;
+		if (raw.byteLength === 0) {
+			throw new Error(
+				`atlas: MovieClip "${filePath}" frame ${firstFrameIndex} references empty texture ${textureIndex}.`,
+			);
+		}
+		const detectedFormat = detectSupportedRasterFormat(raw);
+		if (!detectedFormat) {
+			throw new Error(
+				`atlas: MovieClip "${filePath}" frame ${firstFrameIndex} (texture ${textureIndex}) uses an unsupported ` +
+					'raster format; only PNG and JPEG are supported.',
+			);
+		}
+		const imageInfo = probeRasterImage(raw);
+		if (!imageInfo || imageInfo.format !== detectedFormat) {
+			throw couldNotDecode(filePath, firstFrameIndex, textureIndex);
+		}
 
-	const frames: JtaFrameMeta[] = [];
-	for (let index = 0; index < frameTableCount; index += 1) {
-		const delayRaw = readInt16BEAt(data, state, end);
-		const offsetX = readInt16BEAt(data, state, end);
-		const offsetY = readInt16BEAt(data, state, end);
-		const frameWidth = readInt16BEAt(data, state, end);
-		const frameHeight = readInt16BEAt(data, state, end);
-		const textureIndex = readInt16BEAt(data, state, end);
-		if (
-			delayRaw == null ||
-			offsetX == null ||
-			offsetY == null ||
-			frameWidth == null ||
-			frameHeight == null ||
-			textureIndex == null
-		) {
-			break;
+		let buffer = raw;
+		if (encoder) {
+			try {
+				buffer = await encoder(raw).png().toBuffer();
+			} catch {
+				throw couldNotDecode(filePath, firstFrameIndex, textureIndex);
+			}
+			const normalizedInfo = probeRasterImage(buffer);
+			if (
+				!normalizedInfo ||
+				normalizedInfo.format !== 'png' ||
+				normalizedInfo.width !== imageInfo.width ||
+				normalizedInfo.height !== imageInfo.height
+			) {
+				throw couldNotDecode(filePath, firstFrameIndex, textureIndex);
+			}
 		}
-		frames.push({
-			addDelay: Math.trunc((1000 / fps) * delayRaw),
-			offsetX,
-			offsetY,
-			width: frameWidth,
-			height: frameHeight,
+
+		referencedTextures.push({
 			textureIndex,
+			firstFrameIndex,
+			buffer,
+			width: imageInfo.width,
+			height: imageInfo.height,
 		});
 	}
 
-	return {
-		interval: Math.trunc((1000 / fps) * (speedRaw || 1)),
-		repeatDelay: Math.trunc((1000 / fps) * repeatDelayRaw),
-		swing: swingRaw === 1,
-		width,
-		height,
-		frames: frames.length === 0 && frameCount > 0 ? [] : frames,
-	};
-}
-
-function readUtfBE(data: Uint8Array, state: { offset: number }, end: number): string | null {
-	const length = readUint16BEAt(data, state, end);
-	if (length == null || state.offset + length > end) return null;
-	const value = new TextDecoder().decode(data.subarray(state.offset, state.offset + length));
-	state.offset += length;
-	return value;
-}
-
-function readUint8At(data: Uint8Array, state: { offset: number }, end: number): number | null {
-	if (state.offset + 1 > end) return null;
-	const value = data[state.offset];
-	state.offset += 1;
-	return value ?? 0;
-}
-
-function readInt8At(data: Uint8Array, state: { offset: number }, end: number): number | null {
-	if (state.offset + 1 > end) return null;
-	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-	const value = view.getInt8(state.offset);
-	state.offset += 1;
-	return value;
-}
-
-function readUint16BEAt(data: Uint8Array, state: { offset: number }, end: number): number | null {
-	if (state.offset + 2 > end) return null;
-	const value = readUint16BE(data, state.offset);
-	state.offset += 2;
-	return value;
-}
-
-function readInt16BEAt(data: Uint8Array, state: { offset: number }, end: number): number | null {
-	if (state.offset + 2 > end) return null;
-	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-	const value = view.getInt16(state.offset, false);
-	state.offset += 2;
-	return value;
-}
-
-function readInt32BEAt(data: Uint8Array, state: { offset: number }, end: number): number | null {
-	if (state.offset + 4 > end) return null;
-	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-	const value = view.getInt32(state.offset, false);
-	state.offset += 4;
-	return value;
-}
-
-function readUint16BE(data: Uint8Array, offset: number): number {
-	if (offset + 1 >= data.length) return 0;
-	return (data[offset] << 8) | data[offset + 1];
-}
-
-function readUint32BE(data: Uint8Array, offset: number): number {
-	if (offset + 3 >= data.length) return 0;
-	return (
-		data[offset] * 0x1000000 +
-		((data[offset + 1] ?? 0) << 16) +
-		((data[offset + 2] ?? 0) << 8) +
-		(data[offset + 3] ?? 0)
-	);
+	return { ...extracted, referencedTextures };
 }

package/src/atlas.ts

@@ -3,6 +3,7 @@ import {
 	type Document,
 	GearType,
 	type Package,
+	type MovieClipResource,
 	type Transform,
 	TransitionActionType,
 } from '@openfairygui/core';
@@ -27,6 +28,7 @@ import {
 	type PackageResource,
 } from './atlas/inputs.js';
 import { emitAtlasInputs, sortResourcesByOrder } from './atlas/packing.js';
+import type { PreparedJtaData } from './atlas/jta.js';
 
 export interface AtlasOptions {
 	/**
@@ -106,6 +108,12 @@ export interface AtlasOptions {
 	 */
 	readFileRaw?: (path: string) => Promise<Uint8Array>;
 
+	/**
+	 * MovieClip parse/decode results prepared by publish() before output begins.
+	 * @internal
+	 */
+	preparedMovieClips?: ReadonlyMap<MovieClipResource, PreparedJtaData>;
+
 	/**
 	 * Keep original input order when MaxRects tie-break scores are equal.
 	 * This is an internal publish detail used to mirror editor/CLI behavior.
@@ -133,7 +141,10 @@ export interface AtlasOptions {
 }
 
 const ATLAS_DEFAULTS: Required<
-	Omit<AtlasOptions, 'packages' | 'encoder' | 'basePath' | 'outputPath' | 'mkdir' | 'readFileRaw'>
+	Omit<
+		AtlasOptions,
+		'packages' | 'encoder' | 'basePath' | 'outputPath' | 'mkdir' | 'readFileRaw' | 'preparedMovieClips'
+	>
 > = {
 	maxSize: 2048,
 	fast: true,