feat(catalog): store furniture bundles as .hab instead of .nitro

Every bundle the CMS writes — upload, clone, sync, repair and the pet /
effect / figure importers — now lands as `<classname>.hab`, the extension
this deployment's renderer asks for. `.hab` and `.nitro` are the same
container, so an upload of either extension is accepted.

Resolution goes through one module, src/lib/furni/bundle-file.ts, so
nothing has to know the extension twice. Every existence check probes
`.hab` first and falls back to `.nitro`: the on-disk asset set is still
predominantly `.nitro`, and without the fallback Studio would report every
imported item as missing and the cleanup scan would classify 18k live
bundles as fake leftovers. Downloads are unchanged — Habbo's CDN and every
configured clone source still serve `.nitro`, so the conversion happens on
write, not on request.

Deliberately unchanged: the staged-attachment store in furni-attachment.ts
keys on a UUID and never reaches the client, so renaming it would break
in-flight recovery jobs.

Adds scripts/migrate-nitro-to-hab.ts to rename the existing asset set. It
refuses to run without --dry-run or --yes, never overwrites an existing
.hab, never deletes, and is idempotent.

Note: renderer-config.json lives outside this repo and was patched to
.hab separately; that file is served with a 30-day max-age, so returning
clients need a cms-client cache purge to pick the change up.

src/app/admin/import/furni/upload/upload-furni-client.tsx

@@ -282,17 +282,19 @@ export function UploadFurniClient() {
 						<div className="text-sm font-medium">Files</div>
 
 						<div className="space-y-1.5">
-							<Label htmlFor="nitro">.nitro file *</Label>
+							<Label htmlFor="nitro">.hab file *</Label>
 							<Input
 								ref={nitroRef}
 								id="nitro"
 								type="file"
-								accept=".nitro"
+								accept=".hab,.nitro"
 								onChange={(e) => setNitroFile(e.target.files?.[0] ?? null)}
 								required
 							/>
 							<p className="text-xs text-muted-foreground">
-								The .nitro bundle file (max 50MB)
+								The furniture bundle (max 50MB). Stored as{" "}
+								<code className="font-mono">.hab</code>; a{" "}
+								<code className="font-mono">.nitro</code> is accepted too.
 							</p>
 						</div>
 

src/app/admin/studio/upload/page.tsx

@@ -13,10 +13,10 @@ export default async function StudioUploadPage(_props: {
 		<div className="space-y-6 p-4">
 			<div>
 				<h1 className="text-2xl font-bold tracking-tight">
-					Upload .nitro Furniture
+					Upload .hab Furniture
 				</h1>
 				<p className="mt-1 text-muted-foreground">
-					Upload a .nitro bundle and optional icon to import furniture into the
+					Upload a .hab bundle and optional icon to import furniture into the
 					hotel. The database entry, catalog item, and FurnitureData.json will
 					be updated automatically.
 				</p>

src/app/api/admin/import/furni/batch-regen/route.ts

@@ -4,6 +4,10 @@ import { eq } from "drizzle-orm";
 import { apiError } from "@/lib/api";
 import { withAdmin } from "@/lib/api-handler";
 import { db, ItemsBase } from "@/lib/db";
+import {
+	bundleExistsInDir,
+	bundleWritePathInDir,
+} from "@/lib/furni/bundle-file";
 import { PERMS } from "@/lib/permissions";
 import { getFurniAssetDirs } from "@/lib/services/furni-asset-dirs";
 import {
@@ -103,12 +107,12 @@ export const POST = withAdmin(
 							starIdx !== -1
 								? item.classname.substring(0, starIdx)
 								: item.classname;
-						const nitroPath = path.join(
-							/*turbopackIgnore: true*/ nitroDir,
-							`${baseClassname}.nitro`,
-						);
-
-						if (existsSync(/*turbopackIgnore: true*/ nitroPath)) {
+						if (
+							bundleExistsInDir(
+								/*turbopackIgnore: true*/ nitroDir,
+								baseClassname,
+							)
+						) {
 							skipped++;
 							send({
 								type: "regen_progress",
@@ -203,6 +207,10 @@ export const POST = withAdmin(
 								swfBuffer,
 								baseClassname,
 							);
+							const nitroPath = bundleWritePathInDir(
+								/*turbopackIgnore: true*/ nitroDir,
+								baseClassname,
+							);
 							await fs.writeFile(nitroPath, conversion.bundle);
 
 							// Build FurnitureData entry if missing

src/app/api/admin/import/furni/nitro-editor/route.ts

@@ -1,10 +1,10 @@
-import { existsSync, promises as fs } from "node:fs";
-import path from "node:path";
+import { promises as fs } from "node:fs";
 import { eq, sql } from "drizzle-orm";
 import type { NextRequest } from "next/server";
 import { apiError, apiOk } from "@/lib/api";
 import { withAdmin } from "@/lib/api-handler";
 import { db, ItemsBase, queryRows } from "@/lib/db";
+import { resolveBundleInDir } from "@/lib/furni/bundle-file";
 import { PERMS } from "@/lib/permissions";
 import { logAudit } from "@/lib/services/audit";
 import { getFurniAssetDirs } from "@/lib/services/furni-asset-dirs";
@@ -25,7 +25,7 @@ function baseClassname(classname: string): string {
 	return classname.includes("*") ? classname.split("*")[0] : classname;
 }
 
-// ── GET: Read .nitro metadata ──────────────────────────────────────
+// ── GET: Read bundle metadata ──────────────────────────────────────
 
 export const GET = withAdmin(
 	{ permission: PERMS.ASSETS_IMPORT },
@@ -35,13 +35,12 @@ export const GET = withAdmin(
 
 		const base = baseClassname(rawClassname);
 		const { nitroDir } = await getFurniAssetDirs();
-		const nitroPath = path.join(
+		const nitroPath = resolveBundleInDir(
 			/*turbopackIgnore: true*/ nitroDir,
-			`${base}.nitro`,
+			base,
 		);
 
-		if (!existsSync(/*turbopackIgnore: true*/ nitroPath))
-			return apiError("Nitro file not found", 404);
+		if (!nitroPath) return apiError("Bundle file not found", 404);
 
 		try {
 			const buffer = await fs.readFile(/*turbopackIgnore: true*/ nitroPath);
@@ -67,15 +66,15 @@ export const GET = withAdmin(
 			return apiOk({ metadata: json, flags });
 		} catch (err) {
 			console.error(
-				"[nitro-editor] Failed to parse .nitro:",
+				"[nitro-editor] Failed to parse bundle:",
 				(err as Error).message,
 			);
-			return apiError("Failed to parse .nitro file", 500);
+			return apiError("Failed to parse bundle file", 500);
 		}
 	},
 );
 
-// ── PUT: Save .nitro metadata ──────────────────────────────────────
+// ── PUT: Save bundle metadata ──────────────────────────────────────
 
 export const PUT = withAdmin(
 	{ permission: PERMS.ASSETS_IMPORT },
@@ -94,13 +93,15 @@ export const PUT = withAdmin(
 
 		const base = baseClassname(rawClassname);
 		const { nitroDir } = await getFurniAssetDirs();
-		const nitroPath = path.join(
+		// Write back to whichever extension the file already carries, so
+		// editing metadata never migrates a legacy `.nitro` to `.hab` (or the
+		// reverse) as a side effect.
+		const nitroPath = resolveBundleInDir(
 			/*turbopackIgnore: true*/ nitroDir,
-			`${base}.nitro`,
+			base,
 		);
 
-		if (!existsSync(/*turbopackIgnore: true*/ nitroPath))
-			return apiError("Nitro file not found", 404);
+		if (!nitroPath) return apiError("Bundle file not found", 404);
 
 		const saved = await withFurniDataLock(async () => {
 			const existingBuffer = await fs.readFile(nitroPath);

src/app/api/admin/import/furni/route.ts

@@ -5,6 +5,10 @@ import { invalidateCatalogTotals } from "@/features/catalog/server/catalog-total
 import { apiError, apiOk } from "@/lib/api";
 import { withAdmin } from "@/lib/api-handler";
 import { db, ItemsBase, queryRows } from "@/lib/db";
+import {
+	bundleExistsInDir,
+	bundleWritePathInDir,
+} from "@/lib/furni/bundle-file";
 import { isSafeAssetName, normalizeClassname } from "@/lib/furni/classname";
 import { localFurnitureStatus } from "@/lib/furni/local-presence";
 import { PERMS } from "@/lib/permissions";
@@ -723,13 +727,16 @@ export const PATCH = withAdmin(
 			const starIdx = normalised.indexOf("*");
 			const baseClassname =
 				starIdx !== -1 ? normalised.substring(0, starIdx) : normalised;
-			const nitroPath = path.join(
+			// Regeneration writes `.hab`; a legacy `.nitro` counts as present too.
+			const nitroPath = bundleWritePathInDir(
 				/*turbopackIgnore: true*/ nitroDir,
-				`${baseClassname}.nitro`,
+				baseClassname,
 			);
 
-			// Skip if .nitro already exists
-			if (existsSync(/*turbopackIgnore: true*/ nitroPath)) {
+			// Skip if a bundle already exists (`.hab` or legacy `.nitro`).
+			if (
+				bundleExistsInDir(/*turbopackIgnore: true*/ nitroDir, baseClassname)
+			) {
 				results.push({
 					classname: item.classname,
 					ok: true,

src/app/api/admin/import/furni/upload/route.ts

@@ -27,7 +27,9 @@ export const POST = withAdmin(
 			(formData.get("interactionType") as string)?.trim() || "default";
 		const customparams = (formData.get("customparams") as string)?.trim() || "";
 		const generateSql = formData.get("generateSql") === "true";
-		const nitroFile = formData.get("nitro") as File | null;
+		const nitroFile =
+			(formData.get("nitro") as File | null) ??
+			(formData.get("hab") as File | null);
 		const iconFile = formData.get("icon") as File | null;
 
 		if (!classname) return apiError("classname is required", 400);
@@ -35,10 +37,10 @@ export const POST = withAdmin(
 		if (!itemType || !["s", "i"].includes(itemType))
 			return apiError("itemType must be 's' or 'i'", 400);
 		if (!nitroFile || nitroFile.size === 0)
-			return apiError(".nitro file is required", 400);
+			return apiError(".hab file is required", 400);
 
 		if (nitroFile.size > 50 * 1024 * 1024)
-			return apiError(".nitro file too large (max 50MB)", 400);
+			return apiError(".hab file too large (max 50MB)", 400);
 
 		const nitroBuffer = Buffer.from(await nitroFile.arrayBuffer());
 

src/app/api/admin/studio/import-attachment/route.ts

@@ -17,7 +17,7 @@ export const POST = withAdmin(
 			file.size > 50 * 1024 * 1024
 		)
 			return apiError(
-				"Select a .nitro file for this furniture (maximum 50 MB)",
+				"Select a .hab file for this furniture (maximum 50 MB)",
 				400,
 			);
 		try {
@@ -30,7 +30,7 @@ export const POST = withAdmin(
 		} catch (error) {
 			return apiJson(
 				{
-					error: "Invalid original .nitro file",
+					error: "Invalid original .hab file",
 					code:
 						error instanceof Error &&
 						error.message.startsWith("This bundle does not belong")

src/app/api/admin/studio/inspect/route.test.ts

@@ -24,7 +24,12 @@ vi.mock("@/lib/services/furni-asset-dirs", () => ({
 		iconDir: "/assets/icons",
 	}),
 }));
-vi.mock("node:fs", () => ({ promises: { stat: mocks.stat } }));
+vi.mock("node:fs", () => ({
+	// `item-kind` offers both bundle names per classname; existence is still
+	// decided by the mocked stat below.
+	existsSync: () => false,
+	promises: { stat: mocks.stat },
+}));
 
 import { emptyRouteContext } from "@/test/route-context";
 import { POST } from "./route";
@@ -81,7 +86,13 @@ describe("furniture inspection", () => {
 			mocks.stat.mock.calls.map((call) =>
 				String(call[0]).replaceAll("\\", "/"),
 			),
-		).toEqual(["/assets/nitro/chair.nitro", "/assets/icons/chair_2_icon.png"]);
+		).toEqual([
+			// `.hab` is the live convention, so it is probed before the
+			// legacy `.nitro` name for the same classname.
+			"/assets/nitro/chair.hab",
+			"/assets/nitro/chair.nitro",
+			"/assets/icons/chair_2_icon.png",
+		]);
 	});
 	it("distinguishes unreadable data and denied assets from missing files", async () => {
 		mocks.read.mockRejectedValue(new Error("unreadable"));

src/app/api/admin/studio/nitro-quality/route.test.ts

@@ -5,7 +5,12 @@ import { PERMS } from "@/lib/permission-slugs";
 import { createNitroBundle, encodePng } from "@/lib/services/swf/nitro-builder";
 
 const mocks = vi.hoisted(() => ({ read: vi.fn(), guard: vi.fn() }));
-vi.mock("node:fs", () => ({ promises: { readFile: mocks.read } }));
+// `bundle-file` resolves the live bundle (`.hab`, else legacy `.nitro`)
+// through existsSync before the route reads it.
+vi.mock("node:fs", () => ({
+	existsSync: () => true,
+	promises: { readFile: mocks.read },
+}));
 vi.mock("@/lib/api-handler", () => ({
 	withAdmin: (options: unknown, handler: unknown) => {
 		mocks.guard(options);

src/app/api/admin/studio/nitro-quality/route.ts

@@ -1,8 +1,8 @@
 import { promises as fs } from "node:fs";
-import path from "node:path";
 import sharp from "sharp";
 import { apiError, apiOk } from "@/lib/api";
 import { withAdmin } from "@/lib/api-handler";
+import { resolveBundleInDir } from "@/lib/furni/bundle-file";
 import {
 	buildNitroCompressionReport,
 	inspectNitroScales,
@@ -22,9 +22,12 @@ export const GET = withAdmin(
 		const base = String(classname).split("*")[0],
 			{ nitroDir } = await getFurniAssetDirs();
 		try {
-			const parsed = parseNitroBundle(
-				await fs.readFile(path.join(nitroDir, `${base}.nitro`)),
+			const bundlePath = resolveBundleInDir(
+				/*turbopackIgnore: true*/ nitroDir,
+				base,
 			);
+			if (!bundlePath) return apiError("Bundle file not found", 404);
+			const parsed = parseNitroBundle(await fs.readFile(bundlePath));
 			const { json, texture } = parsed;
 			const image = await sharp(texture).metadata();
 			if (!image.width || !image.height)

src/app/api/admin/studio/nitro-scale32/route.test.ts

@@ -11,6 +11,9 @@ const mocks = vi.hoisted(() => ({
 	generate: vi.fn(),
 }));
 vi.mock("node:fs", () => ({
+	// `bundle-file` resolves the live bundle (`.hab`, else legacy `.nitro`)
+	// through existsSync before the route reads it.
+	existsSync: () => true,
 	promises: {
 		readFile: mocks.read,
 		writeFile: mocks.write,

src/app/api/admin/studio/nitro-scale32/route.ts

@@ -3,6 +3,10 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { apiError, apiOk } from "@/lib/api";
 import { withAdmin } from "@/lib/api-handler";
+import {
+	bundleWritePathInDir,
+	resolveBundleInDir,
+} from "@/lib/furni/bundle-file";
 import { generateScale32 } from "@/lib/furni/nitro-scale32";
 import { validateClassnames } from "@/lib/furni/studio-inspection";
 import { PERMS } from "@/lib/permission-slugs";
@@ -33,7 +37,12 @@ export const POST = withAdmin(
 			return apiError("Invalid backup", 400);
 		const { nitroDir } = await getFurniAssetDirs(),
 			base = body.classname.split("*")[0],
-			file = path.join(nitroDir, `${base}.nitro`);
+			// Edits are written back in place, so the file keeps whatever
+			// extension it already has. The `.hab` fallback only exists so a
+			// missing bundle still surfaces as the usual ENOENT 422.
+			file =
+				resolveBundleInDir(/*turbopackIgnore: true*/ nitroDir, base) ??
+				bundleWritePathInDir(/*turbopackIgnore: true*/ nitroDir, base);
 		const execute = () =>
 			withFurniDataLock(async () => {
 				const original = await fs.readFile(file),

src/app/api/nitro-assets/bundled/furniture/[...path]/route.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { type NextRequest, NextResponse } from "next/server";
+import { stripBundleExt } from "@/lib/furni/bundle-file";
 import { getFurniAssetDirs } from "@/lib/services/furni-asset-dirs";
 
 const CORS_HEADERS = {
@@ -17,7 +18,7 @@ export async function GET(
 	if (
 		!filename ||
 		filename !== path.basename(filename) ||
-		!filename.endsWith(".nitro")
+		stripBundleExt(filename) === null
 	) {
 		return new NextResponse(null, { status: 404, headers: CORS_HEADERS });
 	}