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

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,

package/src/publish.ts

@@ -3,16 +3,21 @@ import {
 	type BinaryWriterOptions,
 	type Document,
 	type FileSystem,
+	type MovieClipResource,
 	type Package,
 	type Transform,
 } from '@openfairygui/core';
 import { atlas } from './atlas.js';
+import { prepareMovieClipResource } from './atlas/inputs.js';
+import type { PreparedJtaData } from './atlas/jta.js';
 import { publishCodeGeneration, resolveProjectBasePath } from './codegen.js';
 import { dirname, isAbsolutePathLike, trimTrailingSlashes } from './path-utils.js';
 import { formatPluginError, type LoadedPlugin } from './plugins/types.js';
 import type { PublishFileSystem } from './publish/contracts.js';
 import {
 	annotatePackagePublishArtifacts,
+	getAnnotatedPublishedResourceIds,
+	isMovieClipResource,
 } from './publish/package-context.js';
 import {
 	exportPackageExternalResources,
@@ -217,7 +222,12 @@ export function publish(options: PublishOptions): Transform {
 			},
 		});
 
-		const publishPackage = async (plan: ResolvedPackagePublishPlan, writerFs: FileSystem, packageIndex: number) => {
+		const publishPackage = async (
+			plan: ResolvedPackagePublishPlan,
+			writerFs: FileSystem,
+			packageIndex: number,
+			preparedMovieClips?: ReadonlyMap<MovieClipResource, PreparedJtaData>,
+		) => {
 			if (options.fs && !plan.outputDir) {
 				throw new Error(
 					'publish: no output directory resolved. Provide --output, or configure global publish.path / package publishPath.',
@@ -253,6 +263,7 @@ export function publish(options: PublishOptions): Transform {
 				mkdir: options.fs ? options.fs.mkdir : undefined,
 				readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
 				strictOutput: options.fs !== undefined,
+				preparedMovieClips,
 				packages: [plan.pkg.getName()],
 				...atlasRuntimeOptions,
 			})(doc);
@@ -340,11 +351,43 @@ export function publish(options: PublishOptions): Transform {
 			);
 		}
 
+		// publishPackage starts with mkdir and loose-resource writes. Preflight the complete
+		// selected MovieClip set first so a failure in a later package leaves zero output.
+		const publishedMovieClips = allPackages.flatMap((pkg) => {
+			const publishedResourceIds = getAnnotatedPublishedResourceIds(pkg);
+			return pkg
+				.listResources()
+				.filter((resource): resource is MovieClipResource => {
+					return publishedResourceIds.has(resource.getId()) && isMovieClipResource(resource);
+				})
+				.map((resource) => ({ pkg, resource }));
+		});
+		const preparedMovieClips = new Map<MovieClipResource, PreparedJtaData>();
+		if (publishedMovieClips.length > 0) {
+			if (!options.encoder) {
+				throw new Error('publish: MovieClip output requires an encoder.');
+			}
+			if (!options.basePath) {
+				throw new Error('publish: MovieClip output requires basePath.');
+			}
+			const readFileRaw = options.atlas?.readFileRaw ?? options.fs.readFileRaw;
+			if (!readFileRaw) {
+				throw new Error('publish: MovieClip output requires readFileRaw.');
+			}
+
+			for (const { pkg, resource } of publishedMovieClips) {
+				preparedMovieClips.set(
+					resource,
+					await prepareMovieClipResource(resource, pkg, options.encoder, options.basePath, readFileRaw),
+				);
+			}
+		}
+
 		const writerFs = toBinaryWriterFileSystem(options.fs);
 
 		for (const plan of plans) {
 			const pkgIndex = allDocPackages.indexOf(plan.pkg);
-			await publishPackage(plan, writerFs, pkgIndex);
+			await publishPackage(plan, writerFs, pkgIndex, preparedMovieClips);
 		}
 
 		if (options.codeGeneration !== false) {

package/src/restore.ts

@@ -466,6 +466,16 @@ class RestoreWorkflow {
 				common: {},
 				adaptation: {},
 			});
+		for (const pkg of doc.getRoot().listPackages()) {
+			pkg.setSourceAtlasSettings({
+				...pkg.getSourceAtlasSettings(),
+				atlases: pkg.listAtlases().map((atlas) => ({
+					index: atlas.getIndex(),
+					name: atlas.getIndex() === 0 ? 'Default' : atlas.getName(),
+					compression: false,
+				})),
+			});
+		}
 	}
 
 	private _initializeImageFileNames(doc: Document): void {