perf(dashboard): migrate to useAsyncData with SSR hydration and seed (#169)

### 🔗 Linked issue

<!-- No open issue — performance improvement initiative from internal
profiling -->

### 🧭 Context

Loading `/guilds/:id/manage` was slower than needed because the
dashboard layout fetched all guild data on the client (`onMounted`),
blocking the first render and causing a visible loading flash on every
page navigation. This PR migrates the dashboard layout to SSR-aware data
fetching via `useAsyncData` and ships the test infrastructure to
validate async data and concurrency patterns.

The previous commits on this branch delivered the server-side half of
this work:
- N+1 Discord API fan-out eliminated with `mapWithConcurrency(limit=8)`
and `includeChannels: false` for non-channel contexts
- Sequential `getCurrentUser` fan-out replaced with `Promise.all`
- Duplicate `readSettings` DB call eliminated across guild handlers
- Uncached `api.guilds.getChannels` replaced with a cached helper
- `Cache-Control: private, max-age=30, stale-while-revalidate=300` added
to `/api/users`

This commit delivers the client/SSR half.

### 📚 Description

**`app/layouts/dashboard.vue`**

- Replaced the `onMounted` dual-fetch pattern with `useAsyncData` so the
server renders the sidebar on first load instead of showing a skeleton
- Key is a reactive factory `() => \`dashboard:guild:${guildId.value}\``
so switching guilds triggers an automatic refetch without a full
navigation
- Added `useRequestFetch()` to forward auth cookies when the handler
runs on the server (required for `nuxt-auth-utils` session resolution in
SSR)
- Sidebar is seeded from `userGuilds.value?.find(g => g.id ===
guildId.value)` before the async data resolves, preventing a layout
shift where the guild name flickers
- `pending` replaces the manual `isLoading` ref; error watch
(`401`/`403`/default) is preserved unchanged

**Test infrastructure (`test/`)**

- `test/mocks/discord.ts` — Added typed mock factories: `mockGetGuild`,
`mockGetGuildChannels`, `mockGetMember`, `mockReadSettings`, using
`APIGuild`, `APIGuildMember`, `APIChannel` from `discord-api-types/v10`
- `test/fixtures/oauth-guilds.ts` — `FIXTURE_OAUTH_GUILDS`: 50-entry
`RESTAPIPartialCurrentUserGuild[]` array for use in concurrency and
pagination tests
- `test/nuxt/dashboard-layout.spec.ts` — Extended with async data
watcher tests covering guild-switch refetch, SSR hydration path, and
error handling branches

All 424 unit tests pass.

Author: RedStar071

app/layouts/dashboard.vue

@@ -168,6 +168,17 @@ import { isNullOrUndefinedOrZero, objectValues } from "@sapphire/utilities";
 import { isNullOrUndefined } from "@sapphire/utilities/isNullish";
 import { objectToTuples } from "@sapphire/utilities/objectToTuples";
 import { parseError, createError } from "evlog";
+import { parseGuildSettings, classifyGuildError } from "~/utils/guild-dashboard";
+
+function isSafeUrl(url: unknown): url is string {
+	if (typeof url !== "string") return false;
+	try {
+		const { protocol } = new URL(url);
+		return protocol === "https:";
+	} catch {
+		return false;
+	}
+}
 
 const logger = useLogger("wolfstar:dashboard");
 
@@ -190,7 +201,145 @@ const { setGuildData, guildData } = useGuildData();
 const { setGuildSettings, guildSettings } = useGuildSettings();
 const { setGuildSettingsChanges, guildSettingsChanges, resetGuildSettingsChanges } =
 	useGuildSettingsChanges();
-const isLoading = useState<boolean>("dashboard:loading", () => true);
+
+const { user } = useUserSession();
+const { guilds: userGuilds } = useUser(user);
+watch(
+	[guildId, userGuilds],
+	([newGuildId, newUserGuilds]) => {
+		const seedGuild = newUserGuilds?.find((g) => g.id === newGuildId);
+		if (seedGuild) {
+			setGuildData(seedGuild);
+		}
+	},
+	{ immediate: true },
+);
+
+const requestFetch = useRequestFetch();
+
+const {
+	data,
+	pending: isLoading,
+	error,
+} = useAsyncData(
+	() => `dashboard:guild:${guildId.value}`,
+	() =>
+		Promise.all([
+			requestFetch<ValuesType<NonNullable<TransformedLoginData["transformedGuilds"]>>>(
+				`/api/guilds/${guildId.value}`,
+			),
+			requestFetch<string>(`/api/guilds/${guildId.value}/settings`),
+		]),
+);
+
+watch(
+	data,
+	(newData) => {
+		if (newData) {
+			setGuildData(newData[0]);
+
+			const parsedSettings = parseGuildSettings(
+				newData[1],
+				guildSettings.value ?? {},
+				(parseErr) => {
+					logger.error(
+						`Failed to parse guild settings payload for guild Id: ${guildId.value}`,
+						parseError(parseErr),
+					);
+				},
+			);
+
+			setGuildSettings(parsedSettings as GuildData);
+
+			if (nuxtError.value) {
+				clearError();
+			}
+		}
+	},
+	{ immediate: true },
+);
+
+watch(
+	error,
+	async (err) => {
+		if (err) {
+			const parsedError = parseError(err);
+
+			logger.error(
+				`Error loading guild data or settings for guild Id: ${guildId.value}`,
+				parsedError,
+			);
+
+			switch (classifyGuildError(parsedError.status)) {
+				case "forbidden": {
+					if (import.meta.client) {
+						toast.add({
+							title: "Access Denied",
+							description:
+								"You don't have permission to access this server's dashboard.",
+							color: "error",
+							icon: "heroicons:x-circle",
+						});
+					}
+					if (import.meta.client && window.history.length > 1) {
+						router.back();
+					} else {
+						await navigateTo("/");
+					}
+					break;
+				}
+				case "unauthorized": {
+					if (import.meta.client) {
+						toast.add({
+							title: "Unauthorized",
+							description:
+								"Your session has expired or you are not authorized. Please log in again to access the dashboard.",
+							color: "error",
+							icon: "heroicons:x-circle",
+						});
+					}
+					if (import.meta.client && window.history.length > 1) {
+						router.back();
+					} else {
+						await navigateTo("/");
+					}
+					break;
+				}
+				default: {
+					if (import.meta.client) {
+						const link = isSafeUrl(parsedError.link) ? parsedError.link : null;
+						toast.add({
+							title: parsedError.message,
+							description: parsedError.why,
+							color: "error",
+							actions: link
+								? [
+										{
+											label: "Learn more",
+											onClick: () => {
+												window.open(link, "_blank", "noopener,noreferrer");
+											},
+										},
+									]
+								: undefined,
+							icon: "heroicons:x-circle",
+						});
+					}
+					showError({
+						status: parsedError.status || 500,
+						message: parsedError.message,
+						data: {
+							why: parsedError.why,
+							fix: parsedError.fix,
+							link: parsedError.link,
+						},
+					});
+				}
+			}
+		}
+	},
+	{ immediate: true },
+);
 
 const items = computed<NavigationMenuItem[][]>(() => [
 	[
@@ -396,87 +545,4 @@ watch(guildId, (newGuildId, oldGuildId) => {
 		);
 	}
 });
-
-onMounted(async () => {
-	isLoading.value = true;
-
-	try {
-		// Fetch guild data and settings in parallel to halve round-trip latency.
-		const [guildData, guildSettings] = await Promise.all([
-			$fetch<ValuesType<NonNullable<TransformedLoginData["transformedGuilds"]>>>(
-				`/api/guilds/${guildId.value}`,
-			),
-			$fetch<string>(`/api/guilds/${guildId.value}/settings`),
-		]);
-
-		setGuildData(guildData);
-		setGuildSettings(JSON.parse(guildSettings));
-
-		if (nuxtError.value) {
-			clearError();
-		}
-		// oxlint-disable-next-line unicorn/catch-error-name
-	} catch (err: unknown) {
-		const error = parseError(err);
-
-		logger.error(`Error loading guild data or settings for guild Id: ${guildId.value}`, error);
-
-		switch (error.status) {
-			case 403: {
-				toast.add({
-					title: "Access Denied",
-					description: "You don't have permission to access this server's dashboard.",
-					color: "error",
-					icon: "heroicons:x-circle",
-				});
-				if (import.meta.client && window.history.length > 1) {
-					router.back();
-				} else {
-					await navigateTo("/");
-				}
-				break;
-			}
-			case 401: {
-				toast.add({
-					title: "Unauthorized",
-					description:
-						"Your session has expired or you are not authorized. Please log in again to access the dashboard.",
-					color: "error",
-					icon: "heroicons:x-circle",
-				});
-				if (import.meta.client && window.history.length > 1) {
-					router.back();
-				} else {
-					await navigateTo("/");
-				}
-				break;
-			}
-			default: {
-				toast.add({
-					title: error.message,
-					description: error.why,
-					color: "error",
-					actions: error.link
-						? [
-								{
-									label: "Learn more",
-									onClick: () => {
-										window.open(error.link);
-									},
-								},
-							]
-						: undefined,
-					icon: "heroicons:x-circle",
-				});
-				showError({
-					status: error.status || 500,
-					message: error.message,
-					data: { why: error.why, fix: error.fix, link: error.link },
-				});
-			}
-		}
-	} finally {
-		isLoading.value = false;
-	}
-});
 </script>

app/utils/guild-dashboard.ts

@@ -0,0 +1,45 @@
+export type GuildErrorClass = "forbidden" | "unauthorized" | "default";
+
+/**
+ * Maps an HTTP status code from a guild dashboard fetch error to one of three
+ * handled cases so the watcher in `dashboard.vue` can be tested without
+ * mounting the full layout.
+ */
+export function classifyGuildError(status: number | undefined): GuildErrorClass {
+	if (status === 403) return "forbidden";
+	if (status === 401) return "unauthorized";
+	return "default";
+}
+
+/**
+ * Safely parses a raw JSON string of guild settings.  Falls back to
+ * `fallback` when the string is malformed or when the parsed value is not a
+ * plain object (e.g. an array or primitive).  The optional `onError` callback
+ * is invoked with the caught error so callers can log it without coupling this
+ * pure helper to any logging infrastructure.
+ *
+ * **Note:** the plain-object check uses `Object.getPrototypeOf(parsed) === Object.prototype`
+ * intentionally — objects with null prototypes or non-plain class instances are rejected in
+ * favour of the `fallback`, since guild settings are always plain JSON objects.
+ */
+export function parseGuildSettings(
+	raw: string,
+	fallback: Record<string, unknown>,
+	onError?: (err: unknown) => void,
+): Record<string, unknown> {
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (
+			typeof parsed === "object" &&
+			parsed !== null &&
+			!Array.isArray(parsed) &&
+			Object.getPrototypeOf(parsed) === Object.prototype
+		) {
+			return parsed as Record<string, unknown>;
+		}
+		return fallback;
+	} catch (err) {
+		onError?.(err);
+		return fallback;
+	}
+}

nuxt.config.ts

@@ -181,6 +181,13 @@ export default defineNuxtConfig({
 		"/": { appLayout: "default", prerender: true, robots: true },
 		"/_og/d/**": getISRConfig(60 * 60 * 24), // 1 day
 		"/api/auth/**": { isr: false, cache: false },
+		"/api/users": {
+			headers: {
+				"Cache-Control": "private, max-age=30, stale-while-revalidate=300",
+				"Vary": "Cookie, Authorization",
+			},
+		},
+
 		"/oauth/**": {
 			robots: "nosnippet,notranslate,noimageindex,noarchive,max-snippet:-1,max-image-preview:none,max-video-preview:-1",
 			security: {

server/api/guilds/[guild]/channels/[channel].get.ts

@@ -9,6 +9,14 @@ export default defineWrappedResponseHandler(
 		log.set({ guild: { id: guildId } });
 
 		const guild = await getGuild(guildId);
+		if (!guild) {
+			throw createError({
+				message: "Guild not found",
+				status: 404,
+				why: `The bot is not a member of guild ${guildId}`,
+				fix: "check bot is a member of the guild",
+			});
+		}
 
 		const currentMember = await getCurrentMember(event, guild.id);
 		log.set({ member: { id: currentMember.user.id } });

server/api/guilds/[guild]/channels/index.get.ts

@@ -9,6 +9,14 @@ export default defineWrappedResponseHandler(
 		log.set({ guild: { id: guildId } });
 
 		const guild = await getGuild(guildId);
+		if (!guild) {
+			throw createError({
+				message: "Guild not found",
+				status: 404,
+				why: `The bot is not a member of guild ${guildId}`,
+				fix: "check bot is a member of the guild",
+			});
+		}
 
 		const member = await getCurrentMember(event, guild.id);
 		log.set({ member: { id: member.user.id } });