fix(imaging): make avatar and badge images resilient to upstream outages

- Add persistent disk cache for rendered avatars/badges (storage/imaging)
  so repeats never touch the flaky local renderer and cached renders
  survive upstream downtime
- Serve cache-first with stale-on-error; cut primary/fallback timeouts
  from 10s/6s to 4s/4s so failing images cannot stall pages
- Avatar proxy now returns a graceful 200 silhouette instead of 502 when
  no renderer can produce a figure, so no broken-image glyphs appear
- Badge endpoint becomes a caching proxy trying configured CDN, public
  Habbo CDN and local /swf copy in order, and drops the fragile IP rate
  limit that could blank badge streams
- Route all site badge images (profile, me, badges, apply pages) through
  the cached proxy instead of hot-linking images.habbo.com

src/lib/imager-upstream.ts

@@ -1,5 +1,11 @@
 import "server-only";
 
+import {
+	avatarCacheDir,
+	imagingCacheKey,
+	readImagingCache,
+	writeImagingCache,
+} from "@/lib/imager-cache";
 import { resolveImagerBase } from "@/lib/runtime-asset-config";
 
 export const FIGURE_RE = /^[a-z]{2}-\d+(?:-\d+)*(?:\.[a-z]{2}-\d+(?:-\d+)*)*$/i;
@@ -8,10 +14,15 @@ export const FIGURE_MAX_PARTS = 24;
 
 const HABBO_PUBLIC_UPSTREAM = "https://www.habbo.com/habbo-imaging/avatarimage";
 
-const PRIMARY_TIMEOUT_MS = 10_000;
-const FALLBACK_TIMEOUT_MS = 6_000;
+const PRIMARY_TIMEOUT_MS = 4_000;
+const FALLBACK_TIMEOUT_MS = 4_000;
 
-export type ImagerSource = "primary" | "fallback";
+export type ImagerSource =
+	| "primary"
+	| "fallback"
+	| "cache"
+	| "cache-stale"
+	| "unavailable";
 
 export interface ImagerResult {
 	body: Uint8Array;
@@ -83,12 +94,28 @@ export async function fetchAvatarImage(
 	params: URLSearchParams,
 ): Promise<ImagerResult> {
 	const primary = resolveImagerBase(origin);
+
+	// Renders are immutable per figure/variant: serve a previously cached
+	// render without touching the upstream at all. This keeps repeated avatar
+	// requests off the local renderer and survives upstream downtime.
+	const cacheKey = imagingCacheKey(`${primary}\n${params.toString()}`);
+	const cached = await readImagingCache(avatarCacheDir(), cacheKey);
+	if (cached) return { ...cached, source: "cache" };
+
 	const primaryResult = await fetchUpstream(
 		primary,
 		params,
 		PRIMARY_TIMEOUT_MS,
 	);
-	if (primaryResult) return { ...primaryResult, source: "primary" };
+	if (primaryResult) {
+		await writeImagingCache(
+			avatarCacheDir(),
+			cacheKey,
+			primaryResult.body,
+			primaryResult.contentType,
+		);
+		return { ...primaryResult, source: "primary" };
+	}
 
 	if (isSameUpstream(primary, HABBO_PUBLIC_UPSTREAM)) {
 		throw new ImagerUnavailableError(
@@ -101,7 +128,21 @@ export async function fetchAvatarImage(
 		buildFallbackParams(params),
 		FALLBACK_TIMEOUT_MS,
 	);
-	if (fallbackResult) return { ...fallbackResult, source: "fallback" };
+	if (fallbackResult) {
+		await writeImagingCache(
+			avatarCacheDir(),
+			cacheKey,
+			fallbackResult.body,
+			fallbackResult.contentType,
+		);
+		return { ...fallbackResult, source: "fallback" };
+	}
+
+	// Both upstreams are down and nothing was cached before. Try once more
+	// against the cache in case a concurrent request just wrote this render,
+	// then give up so the caller can serve a graceful placeholder.
+	const recent = await readImagingCache(avatarCacheDir(), cacheKey);
+	if (recent) return { ...recent, source: "cache-stale" };
 
 	throw new ImagerUnavailableError();
 }