feat(nitro): convert imported SWF bundles to WebP Lossless

Newly converted .nitro bundles now store their spritesheet as WebP VP8L
instead of PNG, so imports land much smaller without changing a single
pixel. The texture member and spritesheet.meta.image are both labelled
from the actual bytes, never from a caller's assumption.

- encode through sharp with lossless and exact, so colour hidden under
  alpha 0 survives; this mirrors ImageSharp's TransparentColorMode.Preserve
- detect PNG/WebP by magic bytes and reject anything the client cannot
  render, on create, download and upload paths
- keep the source format when deriving size-32 sheets, scaling composites
  and editing metadata, so existing bundles are never silently rewritten
- report fidelity in the studio: the compression panel re-encodes with the
  same options the importer uses, so it cannot drift and invent false
  warnings, and shows PNG/WebP size estimates

convertSwfToNitro and buildSpritesheet are now async, so the worker, the
main-thread fallback and every import call site await them. PNG stays
supported for existing bundles and icon sidecars are untouched.

src/lib/services/effect-import.ts

@@ -113,7 +113,7 @@ export async function importSingleEffect(params: {
 	onProgress?.("converting");
 	try {
 		const swfBuffer = await fs.readFile(/*turbopackIgnore: true*/ swfPath);
-		const result = convertSwfToNitro(swfBuffer, lib);
+		const result = await convertSwfToNitro(swfBuffer, lib);
 		await fs.writeFile(/*turbopackIgnore: true*/ nitroPath, result.bundle);
 		if (result.warnings?.length) warnings.push(...result.warnings);
 	} catch (err) {

src/lib/services/figure-import.ts

@@ -112,7 +112,7 @@ export async function importSingleFigure(params: {
 	onProgress?.("converting");
 	try {
 		const swfBuffer = await fs.readFile(/*turbopackIgnore: true*/ swfPath);
-		const result = convertSwfToNitro(swfBuffer, lib);
+		const result = await convertSwfToNitro(swfBuffer, lib);
 		await fs.writeFile(
 			/*turbopackIgnore: true*/ await nitroPathFor(lib),
 			result.bundle,

src/lib/services/furni-attachment.test.ts

@@ -30,5 +30,5 @@ it("rejects missing texture data", () => {
 			createNitroBundle({ name: "chair" }, Buffer.from("not png"), "chair"),
 			"chair",
 		),
-	).toThrow("not a PNG");
+	).toThrow("PNG or WebP");
 });

src/lib/services/furni-attachment.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { parseNitroBundle } from "@/lib/services/swf/nitro-builder";
+import {
+	detectNitroTextureFormat,
+	parseNitroBundle,
+} from "@/lib/services/swf/nitro-builder";
 import { importRoot, validJobId } from "./furni-job-store";
 export function validateFurnitureAttachment(buffer: Buffer, classname: string) {
 	if (buffer.length > 50 * 1024 * 1024)
@@ -15,12 +18,11 @@ export function validateFurnitureAttachment(buffer: Buffer, classname: string) {
 		(parsed.json.name && parsed.json.name !== base)
 	)
 		throw Error(`This bundle does not belong to ${classname}`);
-	if (
-		!parsed.png
-			.subarray(0, 8)
-			.equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
-	)
-		throw Error("The bundle texture is not a PNG");
+	// The renderer reads WebP Lossless and PNG; parseNitroBundle already
+	// rejects anything else, so this only names the format in the error.
+	const format = detectNitroTextureFormat(parsed.texture);
+	if (!format)
+		throw Error("The bundle texture is neither a PNG nor a WebP image");
 	return buffer;
 }
 export async function stageFurnitureAttachment(

src/lib/services/import/core/download.ts

@@ -1,6 +1,9 @@
 import { promises as fs } from "node:fs";
 import { getByparrCookies } from "@/lib/services/byparr";
-import { parseNitroBundle } from "../../swf/nitro-builder";
+import {
+	detectNitroTextureFormat,
+	parseNitroBundle,
+} from "../../swf/nitro-builder";
 import { browserHeaders } from "./browser-headers";
 import { curlDownload } from "./curl-fetch";
 
@@ -27,7 +30,9 @@ export function validateNitroBytes(buffer: Buffer): boolean {
 			!!bundle.json &&
 			typeof bundle.json === "object" &&
 			!Array.isArray(bundle.json) &&
-			validatePngBytes(bundle.png)
+			// parseNitroBundle already rejects non-PNG/WebP textures, so this
+			// is a cheap re-assertion rather than the real gate.
+			detectNitroTextureFormat(bundle.texture) !== null
 		);
 	} catch {
 		return false;

src/lib/services/pet-import.ts

@@ -78,7 +78,7 @@ export async function importSinglePet(params: {
 	onProgress?.("converting");
 	try {
 		const swfBuffer = await fs.readFile(/*turbopackIgnore: true*/ swfPath);
-		const result = convertSwfToNitro(swfBuffer, lib);
+		const result = await convertSwfToNitro(swfBuffer, lib);
 		await fs.writeFile(
 			/*turbopackIgnore: true*/ nitroPathFor(lib),
 			result.bundle,

src/lib/services/swf/add-size32.ts

@@ -34,7 +34,8 @@ export function nitroHasSize32(json: Record<string, unknown>): boolean {
 export async function addSize32ToBundle(
 	buffer: Buffer,
 ): Promise<Buffer | null> {
-	const { json, png, jsonFileName } = parseNitroBundle(buffer);
+	const { json, texture, textureFormat, jsonFileName } =
+		parseNitroBundle(buffer);
 	if (nitroHasSize32(json)) return null;
 
 	const name = (json.name as string) || jsonFileName.replace(/\.json$/, "");
@@ -68,7 +69,7 @@ export async function addSize32ToBundle(
 	for (const [frameName, frame] of Object.entries(frames)) {
 		const f = frame.frame;
 		if (!f || f.w <= 0 || f.h <= 0) continue;
-		const { data, info } = await sharp(png)
+		const { data, info } = await sharp(texture)
 			.extract({ left: f.x, top: f.y, width: f.w, height: f.h })
 			.raw()
 			.ensureAlpha()
@@ -95,7 +96,7 @@ export async function addSize32ToBundle(
 		const f = frame.frame;
 		if (f.w <= 0 || f.h <= 0) continue;
 
-		const src = await sharp(png)
+		const src = await sharp(texture)
 			.extract({ left: f.x, top: f.y, width: f.w, height: f.h })
 			.raw()
 			.ensureAlpha()
@@ -131,7 +132,12 @@ export async function addSize32ToBundle(
 
 	if (Object.keys(newAssets).length === 0) return null;
 
-	const { png: newPng, frames: newFrames } = buildSpritesheet(images);
+	// Preserve the source bundle's texture format: regenerating a scale must
+	// not silently downgrade a WebP bundle back to PNG.
+	const { texture: newTexture, frames: newFrames } = await buildSpritesheet(
+		images,
+		{ format: textureFormat },
+	);
 
 	// Update existing frame coordinates (sheet was rebuilt).
 	for (const [frameName, frame] of Object.entries(frames)) {
@@ -171,5 +177,12 @@ export async function addSize32ToBundle(
 		vis.push({ ...sourceVis, size: 32 });
 	}
 
-	return createNitroBundle(json, newPng, name);
+	// Keep the client-facing image pointer aligned with the member
+	// `createNitroBundle` is about to write.
+	const sheet = (json.spritesheet ?? {}) as Record<string, unknown>;
+	const meta = (sheet.meta ?? {}) as Record<string, unknown>;
+	sheet.meta = { ...meta, image: `${name}.${textureFormat}` };
+	json.spritesheet = sheet;
+
+	return createNitroBundle(json, newTexture, name);
 }

src/lib/services/swf/conversion-pool-recovery.test.ts

@@ -32,7 +32,19 @@ describe("conversion worker recovery", () => {
 		const data = Buffer.from("SWF");
 		const result = await convertSwfToNitroAsync(data, "chair");
 		expect(result.bundle.toString()).toBe("converted");
-		expect(mocks.convert).toHaveBeenCalledWith(data, "chair");
+		expect(mocks.convert).toHaveBeenCalledWith(data, "chair", {
+			textureFormat: undefined,
+		});
+	});
+	it("passes the requested texture format through to the main-thread fallback", async () => {
+		vi.stubEnv("NODE_ENV", "production");
+		vi.stubEnv("VITEST", undefined);
+		const { convertSwfToNitroAsync } = await import("./conversion-pool");
+		const data = Buffer.from("SWF");
+		await convertSwfToNitroAsync(data, "chair", { textureFormat: "webp" });
+		expect(mocks.convert).toHaveBeenCalledWith(data, "chair", {
+			textureFormat: "webp",
+		});
 	});
 	it("recovers icon extraction from a worker startup error", async () => {
 		vi.stubEnv("NODE_ENV", "production");

src/lib/services/swf/conversion-pool.ts

@@ -6,6 +6,7 @@ import {
 	convertSwfToNitro,
 	extractIconFromSwf,
 } from "./index";
+import type { NitroTextureFormat } from "./nitro-builder";
 
 // Offloads the synchronous, CPU-heavy SWF→Nitro conversion (and icon
 // extraction) to a small pool of worker threads so the main Node event loop
@@ -89,28 +90,39 @@ function pump() {
 
 const CONVERSION_TIMEOUT_MS = 60_000;
 
-function run(req: Omit<WorkerRequest, "id">): Promise<WorkerResponse> {
+// `Omit` does not distribute over a union, which would erase `textureFormat`
+// from the convert variant.
+type DistributiveOmit<T, K extends keyof never> = T extends unknown
+	? Omit<T, K>
+	: never;
+
+function run(
+	req: DistributiveOmit<WorkerRequest, "id">,
+): Promise<WorkerResponse> {
 	if (!ensurePool()) {
-		try {
-			if (req.type === "convert") {
+		// No pool available: run on the main thread. Icon extraction stays
+		// synchronous; the conversion is async because it encodes a spritesheet.
+		if (req.type === "icon") {
+			try {
 				return Promise.resolve({
 					id: 0,
 					ok: true,
-					result: convertSwfToNitro(req.buffer, req.classname),
+					icon: extractIconFromSwf(req.buffer, req.classname),
+				});
+			} catch (e) {
+				return Promise.resolve({
+					id: 0,
+					ok: false,
+					error: (e as Error).message,
 				});
 			}
-			return Promise.resolve({
-				id: 0,
-				ok: true,
-				icon: extractIconFromSwf(req.buffer, req.classname),
-			});
-		} catch (e) {
-			return Promise.resolve({
-				id: 0,
-				ok: false,
-				error: (e as Error).message,
-			});
 		}
+		return convertSwfToNitro(req.buffer, req.classname, {
+			textureFormat: req.textureFormat,
+		}).then(
+			(result) => ({ id: 0, ok: true, result }) as WorkerResponse,
+			(e: Error) => ({ id: 0, ok: false, error: e.message }) as WorkerResponse,
+		);
 	}
 	return new Promise<WorkerResponse>((resolve, reject) => {
 		const job: Job = {
@@ -153,13 +165,19 @@ function run(req: Omit<WorkerRequest, "id">): Promise<WorkerResponse> {
 export async function convertSwfToNitroAsync(
 	buffer: Buffer,
 	classname: string,
+	options?: { textureFormat?: NitroTextureFormat },
 ): Promise<ConversionResult> {
-	const res = await run({ type: "convert", buffer, classname }).catch(
-		() => null,
-	);
+	const res = await run({
+		type: "convert",
+		buffer,
+		classname,
+		textureFormat: options?.textureFormat,
+	}).catch(() => null);
 	if (res?.ok && res.result) return res.result;
 	// Worker failed for this item — fall back to the main thread.
-	return convertSwfToNitro(buffer, classname);
+	return convertSwfToNitro(buffer, classname, {
+		textureFormat: options?.textureFormat,
+	});
 }
 
 export async function extractIconFromSwfAsync(

src/lib/services/swf/conversion-worker.ts

@@ -1,11 +1,14 @@
 import { parentPort } from "node:worker_threads";
 import { convertSwfToNitro, extractIconFromSwf } from "./index";
+import type { NitroTextureFormat } from "./nitro-builder";
 
 export interface ConvertRequest {
 	id: number;
 	type: "convert";
 	buffer: Buffer;
 	classname: string;
+	/** Omitted means the default (WebP Lossless). */
+	textureFormat?: NitroTextureFormat;
 }
 
 export interface IconRequest {
@@ -28,28 +31,41 @@ export type WorkerResponse =
 
 if (parentPort) {
 	parentPort.on("message", (msg: WorkerRequest) => {
-		try {
-			if (msg.type === "convert") {
-				const result = convertSwfToNitro(msg.buffer, msg.classname);
-				parentPort?.postMessage({
-					id: msg.id,
-					ok: true,
-					result,
-				} satisfies WorkerResponse);
-			} else {
+		if (msg.type === "icon") {
+			try {
 				const icon = extractIconFromSwf(msg.buffer, msg.classname);
 				parentPort?.postMessage({
 					id: msg.id,
 					ok: true,
 					icon: icon ?? null,
 				} satisfies WorkerResponse);
+			} catch (err) {
+				parentPort?.postMessage({
+					id: msg.id,
+					ok: false,
+					error: (err as Error).message,
+				} satisfies WorkerResponse);
 			}
-		} catch (err) {
-			parentPort?.postMessage({
-				id: msg.id,
-				ok: false,
-				error: (err as Error).message,
-			} satisfies WorkerResponse);
+			return;
 		}
+		// The conversion encodes a spritesheet, which is async (sharp), so it
+		// cannot share the synchronous try/catch above.
+		void convertSwfToNitro(msg.buffer, msg.classname, {
+			textureFormat: msg.textureFormat,
+		})
+			.then((result) => {
+				parentPort?.postMessage({
+					id: msg.id,
+					ok: true,
+					result,
+				} satisfies WorkerResponse);
+			})
+			.catch((err: Error) => {
+				parentPort?.postMessage({
+					id: msg.id,
+					ok: false,
+					error: err.message,
+				} satisfies WorkerResponse);
+			});
 	});
 }

src/lib/services/swf/index.ts

@@ -17,6 +17,7 @@ import {
 	buildSpritesheet,
 	createNitroBundle,
 	encodePng,
+	type NitroTextureFormat,
 } from "./nitro-builder";
 import {
 	decompressSwf,
@@ -56,15 +57,25 @@ export {
 	extractIconFromSwfAsync,
 } from "./conversion-pool";
 // Re-export public API from submodules
-export { createNitroBundle, parseNitroBundle } from "./nitro-builder";
+export {
+	buildSpritesheet,
+	createNitroBundle,
+	detectNitroTextureFormat,
+	encodePng,
+	encodeWebpLossless,
+	NITRO_TEXTURE_LABEL,
+	type NitroTextureFormat,
+	parseNitroBundle,
+} from "./nitro-builder";
 export { computeDefaultDir, extractPartColors } from "./xml-processor";
 
 // ── Main Conversion ────────────────────────────────────────────────
 
-export function convertSwfToNitro(
+export async function convertSwfToNitro(
 	swfBuffer: Buffer,
 	classname: string,
-): ConversionResult {
+	options?: { textureFormat?: NitroTextureFormat },
+): Promise<ConversionResult> {
 	const warnings: string[] = [];
 
 	// 1. Decompress SWF
@@ -241,11 +252,14 @@ export function convertSwfToNitro(
 
 	// 7. Build spritesheet using bin-packing
 	const {
-		png,
+		texture,
+		format: sheetFormat,
 		frames,
 		width: sheetWidth,
 		height: sheetHeight,
-	} = buildSpritesheet(namedImages);
+	} = await buildSpritesheet(namedImages, {
+		format: options?.textureFormat ?? "webp",
+	});
 
 	// 8. Process XML into Nitro JSON structures
 	const { palettes } = processAssetsXml(assetsXml);
@@ -392,7 +406,9 @@ export function convertSwfToNitro(
 		logicType,
 		spritesheet: {
 			meta: {
-				image: `${classname}.png`,
+				// Must match the texture member `createNitroBundle` writes, or
+				// the client resolves a file that is not in the bundle.
+				image: `${classname}.${sheetFormat}`,
 				format: "RGBA8888",
 				size: { w: sheetWidth, h: sheetHeight },
 				scale: 1,
@@ -410,7 +426,7 @@ export function convertSwfToNitro(
 	nitroJson.logic = logicObj;
 
 	// 10. Create .nitro bundle
-	const bundle = createNitroBundle(nitroJson, png, classname);
+	const bundle = createNitroBundle(nitroJson, texture, classname);
 
 	return {
 		bundle,

src/lib/services/swf/nitro-builder.ts

@@ -1,6 +1,74 @@
 import { deflateSync, gunzipSync, inflateSync } from "node:zlib";
+import sharp from "sharp";
 import type { SpriteImage } from "./image-decoder";
 
+// ── Texture Formats ────────────────────────────────────────────────
+
+/**
+ * Image formats a `.nitro` bundle may carry as its spritesheet texture.
+ *
+ * `webp` is the default for newly converted bundles: VP8L is a true lossless
+ * codec, so pixels round-trip bit-for-bit (bar RGB under fully transparent
+ * pixels, which no renderer can observe) while typically weighing 25-40% of the
+ * equivalent PNG. `png` stays supported so existing bundles, official Habbo
+ * gamedata and the PNG-icon sidecar keep parsing unchanged.
+ */
+export type NitroTextureFormat = "png" | "webp";
+
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+/**
+ * Identify a Nitro texture by its magic bytes rather than by its filename, so
+ * the container writer can never label an image with the wrong extension.
+ * Returns `null` for anything that is not a PNG or a RIFF/WEBP image.
+ */
+export function detectNitroTextureFormat(
+	bytes: Buffer,
+): NitroTextureFormat | null {
+	// PNG is identified by its 8-byte signature; WebP additionally needs room
+	// for the "RIFF" size and the "WEBP" fourcc at offset 8.
+	if (bytes.length >= 8 && bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+		return "png";
+	if (
+		bytes.length >= 12 &&
+		bytes.toString("ascii", 0, 4) === "RIFF" &&
+		bytes.toString("ascii", 8, 12) === "WEBP"
+	)
+		return "webp";
+	return null;
+}
+
+/** Human-readable, used by validation error messages. */
+export const NITRO_TEXTURE_LABEL: Record<NitroTextureFormat, string> = {
+	png: "PNG",
+	webp: "WebP",
+};
+
+/**
+ * A RIFF container can also hold a lossy VP8 image, so "this is a WebP" is
+ * not the same claim as "this is WebP Lossless". The verdict comes from the
+ * image chunk: `VP8L` is lossless, `VP8 ` is lossy, and `VP8X` is only an
+ * extended header that defers the answer to a later chunk, so the container
+ * is walked rather than guessed at.
+ */
+export function isLosslessWebp(bytes: Buffer): boolean {
+	if (detectNitroTextureFormat(bytes) !== "webp") return false;
+	// RIFF size covers everything after the first 8 bytes; clamp it so a
+	// truncated file cannot make us read past the buffer.
+	const declared = bytes.readUInt32LE(4) + 8;
+	const end = Math.min(declared, bytes.length);
+	let sawLossy = false;
+	for (let at = 12; at + 8 <= end; ) {
+		const fourcc = bytes.toString("ascii", at, at + 4);
+		// Chunk payloads are padded to an even length.
+		const size = bytes.readUInt32LE(at + 4);
+		if (fourcc === "VP8L") return !sawLossy;
+		if (fourcc === "VP8 ") sawLossy = true;
+		at += 8 + size + (size % 2);
+	}
+	return false;
+}
+
 // ── Minimal PNG Encoder ────────────────────────────────────────────
 
 const CRC_TABLE = (() => {
@@ -68,6 +136,39 @@ export function encodePng(width: number, height: number, rgba: Buffer): Buffer {
 	return Buffer.concat(chunks);
 }
 
+// ── WebP Lossless Encoder ──────────────────────────────────────────
+
+/**
+ * Encode RGBA pixels as a WebP image using the VP8L lossless codec.
+ *
+ * `lossless: true` is what keeps furniture artwork pixel-exact; the remaining
+ * options are pinned so no chroma-subsampling or near-lossless approximation
+ * can creep in. `effort: 6` is libvips' slowest-but-best setting, which is
+ * worth it for a one-off import and keeps spritesheets compact.
+ *
+ * `exact: true` (libvips' "preserve the colour data in transparent pixels")
+ * mirrors ImageSharp's `TransparentColorMode.Preserve`, so a bundle converts
+ * without a single altered texel — not even the RGB hidden under alpha 0.
+ * It costs bytes whenever transparent areas carry non-uniform colour, so the
+ * studio compression report states the size either way.
+ */
+export async function encodeWebpLossless(
+	width: number,
+	height: number,
+	rgba: Buffer,
+	options?: { exact?: boolean },
+): Promise<Buffer> {
+	return sharp(rgba, { raw: { width, height, channels: 4 } })
+		.webp({
+			lossless: true,
+			nearLossless: false,
+			smartSubsample: false,
+			effort: 6,
+			exact: options?.exact ?? true,
+		})
+		.toBuffer();
+}
+
 // ── Bin-Packing Spritesheet Builder ────────────────────────────────
 
 interface PackedRect {
@@ -155,15 +256,37 @@ interface FrameInfo {
 	h: number;
 }
 
-export function buildSpritesheet(images: SpriteImage[]): {
-	png: Buffer;
+export interface Spritesheet {
+	/** Encoded texture bytes, in `format`. */
+	texture: Buffer;
+	format: NitroTextureFormat;
 	frames: Map<string, FrameInfo>;
 	width: number;
 	height: number;
-} {
+}
+
+export async function buildSpritesheet(
+	images: SpriteImage[],
+	options?: { format?: NitroTextureFormat },
+): Promise<Spritesheet> {
+	const format = options?.format ?? "webp";
+	const encode = async (
+		width: number,
+		height: number,
+		rgba: Buffer,
+	): Promise<Buffer> =>
+		format === "webp"
+			? await encodeWebpLossless(width, height, rgba)
+			: encodePng(width, height, rgba);
+
 	if (images.length === 0) {
-		const emptyPng = encodePng(1, 1, Buffer.alloc(4));
-		return { png: emptyPng, frames: new Map(), width: 1, height: 1 };
+		return {
+			texture: await encode(1, 1, Buffer.alloc(4)),
+			format,
+			frames: new Map(),
+			width: 1,
+			height: 1,
+		};
 	}
 
 	const { rects, width: sheetWidth, height: sheetHeight } = binPack(images);
@@ -187,28 +310,59 @@ export function buildSpritesheet(images: SpriteImage[]): {
 		frames.set(rect.name, { x: rect.x, y: rect.y, w: rect.w, h: rect.h });
 	}
 
-	const png = encodePng(sheetWidth, sheetHeight, combined);
-	return { png, frames, width: sheetWidth, height: sheetHeight };
+	const texture = await encode(sheetWidth, sheetHeight, combined);
+	return { texture, format, frames, width: sheetWidth, height: sheetHeight };
 }
 
 // ── .nitro Bundle Creator ──────────────────────────────────────────
 
+/**
+ * The client resolves the spritesheet through `spritesheet.meta.image`, so
+ * that pointer has to name the member we actually write. Editing metadata in
+ * the studio can leave a stale `chair.png` behind, and a bundle whose JSON
+ * disagrees with its own member list silently renders nothing — so the
+ * pointer is corrected here, at the single point where bytes are written,
+ * rather than trusting every call site to remember. The input is not mutated.
+ */
+function withTexturePointer(json: object, textureFileName: string): object {
+	const record = json as Record<string, unknown>;
+	const spritesheet = record.spritesheet as Record<string, unknown> | undefined;
+	const meta = spritesheet?.meta as Record<string, unknown> | undefined;
+	if (!meta || meta.image === textureFileName) return json;
+	return {
+		...record,
+		spritesheet: { ...spritesheet, meta: { ...meta, image: textureFileName } },
+	};
+}
+
 export function createNitroBundle(
 	jsonData: object,
-	pngData: Buffer,
+	textureData: Buffer,
 	name: string,
 ): Buffer {
-	const jsonStr = JSON.stringify(jsonData);
-	const jsonCompressed = deflateSync(Buffer.from(jsonStr, "utf-8"));
-	const pngCompressed = deflateSync(pngData);
+	// Label the member by what the bytes actually are, never by a caller's
+	// assumption, so `parseNitroBundle` and the client both resolve the right
+	// extension.
+	const detected = detectNitroTextureFormat(textureData);
+	if (!detected)
+		throw Error(
+			"Nitro texture must be a PNG or WebP image; the client renderer supports no other format",
+		);
 
 	const jsonFileName = `${name}.json`;
-	const pngFileName = `${name}.png`;
+	const textureFileName = `${name}.${detected}`;
+
+	const jsonStr = JSON.stringify(withTexturePointer(jsonData, textureFileName));
+	const jsonCompressed = deflateSync(Buffer.from(jsonStr, "utf-8"));
+	// The texture arrives already compressed by its own codec (WebP/VP8L or
+	// PNG/DEFLATE), so this layer is mostly a no-op pass-through; it stays
+	// because the container format mandates it and readers inflate it.
+	const textureCompressed = deflateSync(textureData);
 
 	const totalSize =
 		2 +
 		(2 + jsonFileName.length + 4 + jsonCompressed.length) +
-		(2 + pngFileName.length + 4 + pngCompressed.length);
+		(2 + textureFileName.length + 4 + textureCompressed.length);
 
 	const bundle = Buffer.alloc(totalSize);
 	let offset = 0;
@@ -225,28 +379,52 @@ export function createNitroBundle(
 	jsonCompressed.copy(bundle, offset);
 	offset += jsonCompressed.length;
 
-	bundle.writeInt16BE(pngFileName.length, offset);
+	bundle.writeInt16BE(textureFileName.length, offset);
 	offset += 2;
-	bundle.write(pngFileName, offset, pngFileName.length, "utf-8");
-	offset += pngFileName.length;
-	bundle.writeInt32BE(pngCompressed.length, offset);
+	bundle.write(textureFileName, offset, textureFileName.length, "utf-8");
+	offset += textureFileName.length;
+	bundle.writeInt32BE(textureCompressed.length, offset);
 	offset += 4;
-	pngCompressed.copy(bundle, offset);
+	textureCompressed.copy(bundle, offset);
 
 	return bundle;
 }
 
 // ── .nitro Bundle Parser ──────────────────────────────────────────
 
+export interface ParsedNitroBundle {
+	json: Record<string, unknown>;
+	jsonFileName: string;
+	/** Decoded spritesheet bytes. WebP or PNG — sniff the format, don't assume. */
+	texture: Buffer;
+	textureFileName: string;
+	/** Format of `texture`, taken from its filename. */
+	textureFormat: NitroTextureFormat;
+	/**
+	 * @deprecated Historical name for `texture`. Kept so existing callers and
+	 * the emitted client payload stay compatible; the bytes are format-agnostic.
+	 */
+	png: Buffer;
+	/** @deprecated Historical name for `textureFileName`. */
+	pngFileName: string;
+	/** Deflated byte length of each member, as stored in the container. */
+	compressedSizes: { json: number; texture: number };
+	/** Size of the container itself, in bytes. */
+	bundleBytes: number;
+}
+
+/**
+ * Parse a `.nitro` bundle.
+ *
+ * The container stores a filename per member, so the texture format is read
+ * from that name and cross-checked against the bytes. Both PNG and WebP
+ * textures parse; anything else is rejected rather than handed downstream as
+ * an undecodable image.
+ */
 export function parseNitroBundle(
 	buffer: Buffer,
 	options?: { maxOutputLength?: number },
-): {
-	json: Record<string, unknown>;
-	jsonFileName: string;
-	png: Buffer;
-	pngFileName: string;
-} {
+): ParsedNitroBundle {
 	let offset = 0;
 
 	const fileCount = buffer.readInt16BE(offset);
@@ -273,18 +451,41 @@ export function parseNitroBundle(
 	const jsonStr = inflateJsonOrGzip(jsonCompressed, options).toString("utf-8");
 	const json = JSON.parse(jsonStr);
 
-	// File 2: PNG
-	const pngFileNameLen = buffer.readInt16BE(offset);
+	// File 2: texture (PNG or WebP)
+	const textureFileNameLen = buffer.readInt16BE(offset);
 	offset += 2;
-	const pngFileName = buffer.toString("utf-8", offset, offset + pngFileNameLen);
-	offset += pngFileNameLen;
-	const pngCompressedLen = buffer.readInt32BE(offset);
+	const textureFileName = buffer.toString(
+		"utf-8",
+		offset,
+		offset + textureFileNameLen,
+	);
+	offset += textureFileNameLen;
+	const textureCompressedLen = buffer.readInt32BE(offset);
 	offset += 4;
-	const pngCompressed = buffer.subarray(offset, offset + pngCompressedLen);
-	offset += pngCompressedLen;
-	const png = inflateJsonOrGzip(pngCompressed, options);
+	const textureCompressed = buffer.subarray(
+		offset,
+		offset + textureCompressedLen,
+	);
+	offset += textureCompressedLen;
+	const texture = inflateJsonOrGzip(textureCompressed, options);
 
-	return { json, jsonFileName, png, pngFileName };
+	const textureFormat = detectNitroTextureFormat(texture);
+	if (!textureFormat)
+		throw new Error(
+			`Unsupported .nitro texture "${textureFileName}": expected a PNG or WebP image`,
+		);
+
+	return {
+		json,
+		jsonFileName,
+		texture,
+		textureFileName,
+		textureFormat,
+		png: texture,
+		pngFileName: textureFileName,
+		compressedSizes: { json: jsonCompressedLen, texture: textureCompressedLen },
+		bundleBytes: buffer.length,
+	};
 }
 
 /**

src/lib/services/swf/nitro-bundle-limits.test.ts

@@ -4,9 +4,15 @@ import { createNitroBundle, parseNitroBundle } from "./nitro-builder";
 it("honors an explicit decompression limit for imported bundles", () => {
 	const bundle = createNitroBundle(
 		{ name: "chair", value: "a".repeat(4096) },
-		Buffer.from("png"),
+		Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
 		"chair",
 	);
 	expect(() => parseNitroBundle(bundle, { maxOutputLength: 1024 })).toThrow();
 	expect(parseNitroBundle(bundle).json.name).toBe("chair");
 });
+
+it("refuses to write a bundle whose texture is neither PNG nor WebP", () => {
+	expect(() =>
+		createNitroBundle({ name: "chair" }, Buffer.from("not an image"), "chair"),
+	).toThrow(/PNG or WebP/);
+});

src/lib/services/swf/nitro-webp.test.ts

@@ -0,0 +1,266 @@
+import sharp from "sharp";
+import { describe, expect, it } from "vitest";
+import type { SpriteImage } from "./image-decoder";
+import {
+	buildSpritesheet,
+	createNitroBundle,
+	detectNitroTextureFormat,
+	encodePng,
+	encodeWebpLossless,
+	isLosslessWebp,
+	parseNitroBundle,
+} from "./nitro-builder";
+
+/**
+ * Sprites shaped like real SWF DefineBitsLossless2 output: an opaque border
+ * around a body whose interior is fully transparent yet still carries
+ * non-zero palette RGB. That combination is what separates a genuinely
+ * lossless encoder from one that quietly drops hidden colour data.
+ */
+function swfStyleSprite(index: number): SpriteImage {
+	const width = 17 + (index % 5) * 4,
+		height = 13 + (index % 3) * 6,
+		pixels = Buffer.alloc(width * height * 4);
+	for (let y = 0; y < height; y++) {
+		for (let x = 0; x < width; x++) {
+			const o = (y * width + x) * 4;
+			const border = x === 0 || y === 0 || x === width - 1 || y === height - 1;
+			if (border) {
+				pixels[o] = 20 + index;
+				pixels[o + 1] = 140;
+				pixels[o + 2] = 200;
+				pixels[o + 3] = 255;
+			} else {
+				// Transparent, but carrying leftover palette colour.
+				pixels[o] = 9 + index * 3;
+				pixels[o + 1] = 77;
+				pixels[o + 2] = 5;
+				pixels[o + 3] = 0;
+			}
+		}
+	}
+	return { id: index, name: `chair_${index}`, width, height, pixels };
+}
+
+const sprites = () => [0, 1, 2, 3, 4].map(swfStyleSprite);
+
+describe("nitro texture format detection", () => {
+	it("identifies PNG and WebP by magic bytes, not by filename", () => {
+		expect(
+			detectNitroTextureFormat(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])),
+		).toBe("png");
+		expect(
+			detectNitroTextureFormat(
+				Buffer.from("RIFF\x00\x00\x00\x00WEBPVP8L", "latin1"),
+			),
+		).toBe("webp");
+		expect(detectNitroTextureFormat(Buffer.from("GIF89a"))).toBeNull();
+		expect(detectNitroTextureFormat(Buffer.alloc(0))).toBeNull();
+		// A RIFF container that is not WebP (e.g. WAVE) must not pass.
+		expect(
+			detectNitroTextureFormat(
+				Buffer.from("RIFF\x00\x00\x00\x00WAVEfmt ", "latin1"),
+			),
+		).toBeNull();
+	});
+});
+
+describe("WebP lossless encoding", () => {
+	it("round-trips every texel bit-for-bit, including colour hidden under alpha 0", async () => {
+		const sprite = swfStyleSprite(0);
+		const encoded = await encodeWebpLossless(
+			sprite.width,
+			sprite.height,
+			sprite.pixels,
+		);
+		expect(encoded.toString("ascii", 12, 16)).toBe("VP8L");
+		const decoded = await sharp(encoded).raw().ensureAlpha().toBuffer();
+		expect(decoded).toEqual(sprite.pixels);
+	});
+
+	it("keeps partially transparent texels exact as well", async () => {
+		const pixels = Buffer.from([
+			10, 20, 30, 255, 40, 50, 60, 128, 70, 80, 90, 1, 100, 110, 120, 254,
+		]);
+		const encoded = await encodeWebpLossless(4, 1, pixels);
+		expect(await sharp(encoded).raw().ensureAlpha().toBuffer()).toEqual(pixels);
+	});
+
+	it("is far smaller than the equivalent PNG", async () => {
+		const sheet = await buildSpritesheet(sprites(), { format: "png" });
+		const webpSheet = await buildSpritesheet(sprites(), { format: "webp" });
+		expect(webpSheet.texture.length).toBeLessThan(sheet.texture.length);
+	});
+});
+
+describe("WebP losslessness detection", () => {
+	it("confirms a VP8L image is lossless", async () => {
+		const sprite = swfStyleSprite(0);
+		const encoded = await encodeWebpLossless(
+			sprite.width,
+			sprite.height,
+			sprite.pixels,
+		);
+		expect(isLosslessWebp(encoded)).toBe(true);
+	});
+
+	it("rejects a lossy VP8 image even though the container says WebP", async () => {
+		const sprite = swfStyleSprite(0);
+		const lossy = await sharp(sprite.pixels, {
+			raw: { width: sprite.width, height: sprite.height, channels: 4 },
+		})
+			.webp({ quality: 80 })
+			.toBuffer();
+		// The container is still RIFF/WEBP, so only the chunk tells the truth.
+		expect(detectNitroTextureFormat(lossy)).toBe("webp");
+		expect(isLosslessWebp(lossy)).toBe(false);
+	});
+
+	it("is not fooled by a PNG or by a truncated header", () => {
+		expect(isLosslessWebp(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))).toBe(
+			false,
+		);
+		expect(isLosslessWebp(Buffer.from("RIFF"))).toBe(false);
+		expect(isLosslessWebp(Buffer.alloc(0))).toBe(false);
+	});
+
+	it("reports the bytes of an empty sheet as lossless", async () => {
+		const sheet = await buildSpritesheet([], { format: "webp" });
+		expect(isLosslessWebp(sheet.texture)).toBe(true);
+	});
+});
+
+describe("spritesheet encoding", () => {
+	it("defaults to WebP and reports the format it produced", async () => {
+		const sheet = await buildSpritesheet(sprites());
+		expect(sheet.format).toBe("webp");
+		expect(detectNitroTextureFormat(sheet.texture)).toBe("webp");
+		expect(sheet.frames.size).toBe(5);
+	});
+
+	it("still encodes PNG on request for legacy bundles", async () => {
+		const sheet = await buildSpritesheet(sprites(), { format: "png" });
+		expect(sheet.format).toBe("png");
+		expect(detectNitroTextureFormat(sheet.texture)).toBe("png");
+	});
+
+	it("emits a decodable sheet whose frames hold the original pixels", async () => {
+		const source = sprites();
+		const sheet = await buildSpritesheet(source, { format: "webp" });
+		const decoded = await sharp(sheet.texture).raw().ensureAlpha().toBuffer();
+		for (const sprite of source) {
+			const rect = sheet.frames.get(sprite.name);
+			if (!rect) throw new Error(`frame ${sprite.name} is missing`);
+			for (let y = 0; y < sprite.height; y++) {
+				const from = y * sprite.width * 4;
+				const to = ((rect.y + y) * sheet.width + rect.x) * 4;
+				expect(decoded.subarray(to, to + sprite.width * 4)).toEqual(
+					sprite.pixels.subarray(from, from + sprite.width * 4),
+				);
+			}
+		}
+	});
+
+	it("produces a valid empty sheet rather than failing", async () => {
+		const sheet = await buildSpritesheet([], { format: "webp" });
+		expect(sheet.width).toBe(1);
+		expect(sheet.frames.size).toBe(0);
+		expect(detectNitroTextureFormat(sheet.texture)).toBe("webp");
+	});
+});
+
+describe("bundle round-trip", () => {
+	const metadata = (name: string) => ({
+		name,
+		spritesheet: {
+			meta: { image: `${name}.webp`, format: "RGBA8888", size: { w: 1, h: 1 } },
+			frames: { [`${name}_0`]: { frame: { x: 0, y: 0, w: 1, h: 1 } } },
+		},
+		assets: { [`${name}_0`]: { x: 0, y: 0 } },
+	});
+
+	it("names the member after the real encoding and parses it back", async () => {
+		const sheet = await buildSpritesheet(sprites(), { format: "webp" });
+		const bundle = createNitroBundle(metadata("chair"), sheet.texture, "chair");
+		const parsed = parseNitroBundle(bundle);
+		expect(parsed.textureFileName).toBe("chair.webp");
+		expect(parsed.textureFormat).toBe("webp");
+		expect(parsed.texture.toString("ascii", 12, 16)).toBe("VP8L");
+		// The historical aliases must keep pointing at the same bytes.
+		expect(parsed.png).toEqual(parsed.texture);
+		expect(parsed.pngFileName).toBe("chair.webp");
+	});
+
+	it("keeps labelling a PNG texture as .png", () => {
+		const png = encodePng(1, 1, Buffer.from([1, 2, 3, 255]));
+		const parsed = parseNitroBundle(
+			createNitroBundle(metadata("chair"), png, "chair"),
+		);
+		expect(parsed.textureFileName).toBe("chair.png");
+		expect(parsed.textureFormat).toBe("png");
+	});
+
+	it("reports the member sizes the compression report relies on", async () => {
+		const sheet = await buildSpritesheet(sprites(), { format: "webp" });
+		const bundle = createNitroBundle(metadata("chair"), sheet.texture, "chair");
+		const parsed = parseNitroBundle(bundle);
+		expect(parsed.compressedSizes.texture).toBeGreaterThan(0);
+		expect(parsed.compressedSizes.json).toBeGreaterThan(0);
+		expect(parsed.bundleBytes).toBe(bundle.length);
+		// Overhead is the container framing, so members must fit inside it.
+		expect(
+			parsed.compressedSizes.json + parsed.compressedSizes.texture,
+		).toBeLessThan(parsed.bundleBytes);
+	});
+
+	it("repairs a stale .png pointer instead of writing an inconsistent bundle", async () => {
+		const sheet = await buildSpritesheet(sprites(), { format: "webp" });
+		// A studio metadata edit can leave the old pointer behind while the
+		// texture itself stays WebP; the client would then look for a member
+		// that is not in the bundle.
+		const stale = metadata("chair");
+		stale.spritesheet.meta.image = "chair.png";
+		const parsed = parseNitroBundle(
+			createNitroBundle(stale, sheet.texture, "chair"),
+		);
+		expect(parsed.textureFileName).toBe("chair.webp");
+		expect(
+			(parsed.json.spritesheet as { meta: { image: string } }).meta.image,
+		).toBe("chair.webp");
+		// The caller's object must not be mutated in place.
+		expect(stale.spritesheet.meta.image).toBe("chair.png");
+	});
+
+	it("leaves a matching pointer and the rest of the metadata alone", () => {
+		const png = encodePng(1, 1, Buffer.from([1, 2, 3, 255]));
+		const parsed = parseNitroBundle(
+			createNitroBundle(metadata("chair"), png, "chair"),
+		);
+		expect(
+			(parsed.json.spritesheet as { meta: { image: string } }).meta.image,
+		).toBe("chair.png");
+		expect(
+			(parsed.json.spritesheet as { frames: Record<string, unknown> }).frames,
+		).toEqual({ chair_0: { frame: { x: 0, y: 0, w: 1, h: 1 } } });
+	});
+
+	it("tolerates metadata that has no spritesheet at all", () => {
+		const png = encodePng(1, 1, Buffer.from([1, 2, 3, 255]));
+		const parsed = parseNitroBundle(
+			createNitroBundle({ name: "bare" }, png, "bare"),
+		);
+		expect(parsed.textureFileName).toBe("bare.png");
+		expect(parsed.json.name).toBe("bare");
+	});
+
+	it("rejects a bundle whose texture is neither PNG nor WebP", () => {
+		const good = encodePng(1, 1, Buffer.from([1, 2, 3, 255]));
+		expect(() =>
+			createNitroBundle(metadata("chair"), Buffer.from("GIF89a"), "chair"),
+		).toThrow(/PNG or WebP/);
+		// Sanity: the valid case still builds.
+		expect(
+			createNitroBundle(metadata("chair"), good, "chair").length,
+		).toBeGreaterThan(0);
+	});
+});