Feat: add persisted account theme settings

Frontend/src/components/app-shell/data/app-shell.context.tsx

@@ -1,14 +1,8 @@
 // Path: Frontend/src/components/app-shell/data/app-shell.context.tsx
 
-import {
-	createContext,
-	createMemo,
-	createSignal,
-	onMount,
-	useContext,
-	type JSX,
-} from "solid-js";
+import { createContext, createMemo, createSignal, onMount, useContext, type JSX } from "solid-js";
 import { resolveAPIBase } from "../../../lib/api";
+import { applyThemePresetById, resolvePreferredThemePresetId } from "../../../helper/themeRuntime";
 import {
 	buildActiveDepartment,
 	buildActiveProject,
@@ -56,7 +50,13 @@ export const AppShellDataProvider = (props: { children: JSX.Element }): JSX.Elem
 				throw new Error(errorMessage || "Failed to load app shell state.");
 			}
 
-			setPayload(normalizeAppShellPayload(body.data));
+			const normalizedPayload = normalizeAppShellPayload(body.data);
+			const persistedThemePresetId = normalizedPayload.admin?.themePresetId?.trim();
+			if (persistedThemePresetId && persistedThemePresetId !== resolvePreferredThemePresetId()) {
+				await applyThemePresetById(persistedThemePresetId);
+			}
+
+			setPayload(normalizedPayload);
 			setStatus("success");
 		} catch (loadError) {
 			setStatus("error");
@@ -72,6 +72,7 @@ export const AppShellDataProvider = (props: { children: JSX.Element }): JSX.Elem
 		status,
 		error,
 		installation: createMemo(() => payload()?.installation),
+		admin: createMemo(() => payload()?.admin),
 		railItems: createMemo(() => buildRailItems(payload())),
 		activeServer: createMemo(() => buildActiveServer(payload())),
 		activeProject: createMemo(() => buildActiveProject(payload())),

Frontend/src/components/app-shell/data/app-shell.types.ts

@@ -30,6 +30,7 @@ export type AppShellAdmin = {
 	displayName: string;
 	isInstanceAdmin: boolean;
 	homeTitle: string;
+	themePresetId?: string;
 };
 
 export type AppShellOrganization = {
@@ -87,6 +88,7 @@ export type AppShellContextValue = {
 	status: Accessor<"idle" | "loading" | "success" | "error">;
 	error: Accessor<string>;
 	installation: Accessor<AppShellInstallation | undefined>;
+	admin: Accessor<AppShellAdmin | undefined>;
 	railItems: Accessor<readonly RailItem[]>;
 	activeServer: Accessor<ActiveServer>;
 	activeProject: Accessor<ActiveProject>;

Frontend/src/components/settings/ThemeSettingsPage/ThemeSettingsPage.module.scss

@@ -0,0 +1,234 @@
+// Path: Frontend/src/components/settings/ThemeSettingsPage/ThemeSettingsPage.module.scss
+
+.viewport {
+	width: 100%;
+	max-width: min(80rem, 100%);
+	min-height: 100%;
+	padding: var(--space-5) var(--space-6) calc(var(--space-7) + env(safe-area-inset-bottom));
+	box-sizing: border-box;
+	display: grid;
+	gap: var(--space-5);
+	align-content: start;
+}
+
+.hero,
+.card,
+.errorBanner {
+	border: 1px solid var(--color-border-subtle);
+	border-radius: var(--radius-xl);
+	background: var(--color-surface-raised);
+	box-shadow: var(--shadow-sm);
+}
+
+.hero {
+	padding: var(--space-6);
+	display: flex;
+	align-items: center;
+	gap: var(--space-4);
+	border-color: color-mix(in srgb, var(--color-accent) 20%, var(--color-border-subtle));
+	box-shadow:
+		0 10px 24px color-mix(in srgb, var(--color-accent) 8%, transparent),
+		var(--shadow-sm);
+}
+
+.heroIcon {
+	width: 3rem;
+	height: 3rem;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: var(--radius-lg);
+	background: linear-gradient(
+		180deg,
+		color-mix(in srgb, var(--color-accent) 14%, transparent),
+		color-mix(in srgb, var(--color-accent-soft) 22%, transparent)
+	);
+	border: 1px solid color-mix(in srgb, var(--color-accent) 16%, var(--color-border-subtle));
+	box-shadow:
+		inset 0 1px 0 color-mix(in srgb, white 8%, transparent),
+		0 6px 14px color-mix(in srgb, var(--color-accent) 7%, transparent);
+	color: var(--color-text-primary);
+	flex: 0 0 auto;
+}
+
+.heroCopy {
+	display: grid;
+	gap: var(--space-2);
+}
+
+.title,
+.cardTitle {
+	margin: 0;
+	color: var(--color-text-primary);
+}
+
+.title {
+	@include text-display;
+	line-height: 1.02;
+	letter-spacing: -0.02em;
+}
+
+.description,
+.cardDescription,
+.errorBanner {
+	margin: 0;
+	color: var(--color-text-secondary);
+	@include text-body;
+}
+
+.errorBanner {
+	padding: var(--space-4) var(--space-5);
+	border-color: color-mix(in srgb, #ef4444 24%, var(--color-border-subtle));
+	color: color-mix(in srgb, #ef4444 64%, var(--color-text-primary));
+}
+
+.grid {
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
+	gap: var(--space-4);
+}
+
+.card {
+	padding: var(--space-4);
+	display: grid;
+	gap: var(--space-4);
+	text-align: left;
+	color: inherit;
+	cursor: pointer;
+	transition:
+		transform 120ms ease,
+		border-color 120ms ease,
+		box-shadow 120ms ease;
+}
+
+.card:hover:not(:disabled) {
+	transform: translateY(-1px);
+	border-color: color-mix(in srgb, var(--color-accent) 28%, var(--color-border-strong));
+	box-shadow:
+		0 10px 22px color-mix(in srgb, var(--color-accent) 8%, transparent),
+		var(--shadow-md);
+}
+
+.card:focus-visible {
+	outline: 2px solid color-mix(in srgb, var(--color-accent) 54%, transparent);
+	outline-offset: 2px;
+}
+
+.card:disabled {
+	cursor: default;
+}
+
+.cardSelected {
+	border-color: color-mix(in srgb, var(--color-accent) 32%, var(--color-border-strong));
+	box-shadow:
+		0 10px 22px color-mix(in srgb, var(--color-accent) 10%, transparent),
+		var(--shadow-md);
+}
+
+.preview {
+	border-radius: var(--radius-lg);
+	overflow: hidden;
+	border: 1px solid var(--color-border-subtle);
+	background: var(--color-surface);
+	min-height: 9.5rem;
+}
+
+.previewCanvas {
+	height: 100%;
+	min-height: 9.5rem;
+	padding: 0.8rem;
+	box-sizing: border-box;
+	display: grid;
+	grid-template-rows: auto 1fr;
+	gap: 0.75rem;
+}
+
+.previewTopbar {
+	height: 0.65rem;
+	border-radius: 999px;
+	opacity: 0.9;
+}
+
+.previewSurface {
+	border-radius: calc(var(--radius-lg) - 0.25rem);
+	padding: 0.9rem;
+	display: grid;
+	align-content: start;
+	gap: 0.55rem;
+	box-shadow: inset 0 1px 0 color-mix(in srgb, white 6%, transparent);
+}
+
+.previewChip {
+	width: 2.8rem;
+	height: 0.55rem;
+	border-radius: 999px;
+	opacity: 0.95;
+}
+
+.previewLine,
+.previewLineShort {
+	height: 0.5rem;
+	border-radius: 999px;
+	background: color-mix(in srgb, var(--color-text-primary) 10%, transparent);
+}
+
+.previewLineShort {
+	width: 58%;
+}
+
+.cardBody {
+	display: grid;
+	gap: var(--space-2);
+}
+
+.cardHeader {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--space-3);
+}
+
+.cardTitle {
+	@include text-title;
+	line-height: 1.1;
+}
+
+.badge {
+	padding: 0.25rem 0.55rem;
+	border-radius: 999px;
+	border: 1px solid color-mix(in srgb, var(--color-accent) 18%, var(--color-border-subtle));
+	background: color-mix(in srgb, var(--color-accent) 10%, transparent);
+	color: color-mix(in srgb, var(--color-accent) 44%, var(--color-text-primary));
+	@include text-label;
+	white-space: nowrap;
+}
+
+@media (max-width: 64rem) {
+	.grid {
+		grid-template-columns: 1fr;
+	}
+}
+
+@media (max-width: 48rem) {
+	.viewport {
+		padding: var(--space-4) var(--space-4) calc(var(--space-8) + env(safe-area-inset-bottom));
+	}
+
+	.hero,
+	.card {
+		padding: var(--space-4);
+	}
+
+	.hero {
+		align-items: flex-start;
+	}
+
+	.title {
+		max-width: none;
+	}
+
+	.cardHeader {
+		align-items: flex-start;
+		flex-direction: column;
+	}
+}

Frontend/src/components/settings/ThemeSettingsPage/ThemeSettingsPage.tsx

@@ -0,0 +1,129 @@
+// Path: Frontend/src/components/settings/ThemeSettingsPage/ThemeSettingsPage.tsx
+
+import { For, Show, createMemo, createSignal, type JSX } from "solid-js";
+import { resolveAPIBase } from "../../../lib/api";
+import { Moon } from "../../../lib/icons";
+import { useAppShellData } from "../../app-shell/data/app-shell.context";
+import { applyThemePresetById, resolvePreferredThemePresetId } from "../../../helper/themeRuntime";
+import { themePresetMetas } from "../../../theme/presets";
+import styles from "./ThemeSettingsPage.module.scss";
+
+type SaveThemeResponse = {
+	data?: {
+		presetId?: string;
+	};
+	error?: { message?: string } | string;
+	message?: string;
+};
+
+export const ThemeSettingsPage = (): JSX.Element => {
+	const appShell = useAppShellData();
+	const [savingPresetId, setSavingPresetId] = createSignal<string | null>(null);
+	const [error, setError] = createSignal("");
+
+	const activePresetId = createMemo(() => {
+		return appShell.admin()?.themePresetId?.trim() || resolvePreferredThemePresetId();
+	});
+
+	const savePreset = async (presetId: string): Promise<void> => {
+		if (savingPresetId() || presetId === activePresetId()) {
+			return;
+		}
+
+		setSavingPresetId(presetId);
+		setError("");
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/settings/theme`, {
+				method: "PUT",
+				headers: {
+					"Content-Type": "application/json",
+					Accept: "application/json",
+				},
+				body: JSON.stringify({ presetId }),
+			});
+
+			const body = (await response.json().catch(() => ({}))) as SaveThemeResponse;
+			const errorMessage =
+				typeof body.message === "string"
+					? body.message
+					: typeof body.error === "string"
+						? body.error
+						: body.error?.message;
+
+			if (!response.ok) {
+				throw new Error(errorMessage || "Failed to save theme preset.");
+			}
+
+			await applyThemePresetById(presetId);
+			await appShell.reload();
+		} catch (saveError) {
+			setError(saveError instanceof Error ? saveError.message : "Failed to save theme preset.");
+		} finally {
+			setSavingPresetId(null);
+		}
+	};
+
+	return (
+		<main class={styles.viewport}>
+			<section class={styles.hero}>
+				<div class={styles.heroIcon}>
+					<Moon size={18} strokeWidth={2} />
+				</div>
+				<div class={styles.heroCopy}>
+					<h1 class={styles.title}>Theme Settings</h1>
+					<p class={styles.description}>Pick the theme preset for your account.</p>
+				</div>
+			</section>
+
+			<Show when={error()}>
+				<div class={styles.errorBanner} role="alert">
+					{error()}
+				</div>
+			</Show>
+
+			<section class={styles.grid}>
+				<For each={themePresetMetas}>
+					{(preset) => {
+						const isSelected = () => activePresetId() === preset.id;
+						const isSaving = () => savingPresetId() === preset.id;
+
+						return (
+							<button
+								type="button"
+								classList={{
+									[styles.card]: true,
+									[styles.cardSelected]: isSelected(),
+								}}
+								onClick={() => void savePreset(preset.id)}
+								disabled={Boolean(savingPresetId())}
+								aria-pressed={isSelected()}
+							>
+								<div class={styles.preview} aria-hidden="true">
+									<div class={styles.previewCanvas} style={{ background: preset.preview.canvas }}>
+										<div class={styles.previewTopbar} style={{ background: preset.preview.accent }} />
+										<div class={styles.previewSurface} style={{ background: preset.preview.surface }}>
+											<div class={styles.previewChip} style={{ background: preset.preview.accent }} />
+											<div class={styles.previewLine} />
+											<div class={styles.previewLineShort} />
+										</div>
+									</div>
+								</div>
+
+								<div class={styles.cardBody}>
+									<div class={styles.cardHeader}>
+										<h2 class={styles.cardTitle}>{preset.name}</h2>
+										<Show when={isSelected() || isSaving()}>
+											<span class={styles.badge}>{isSaving() ? "Saving..." : "Current"}</span>
+										</Show>
+									</div>
+									<p class={styles.cardDescription}>{preset.description}</p>
+								</div>
+							</button>
+						);
+					}}
+				</For>
+			</section>
+		</main>
+	);
+};

Frontend/src/helper/themeRuntime.ts

@@ -36,6 +36,29 @@ const persistThemePreset = (themeDefinition: ThemeDefinition): void => {
 	localStorage.setItem(THEME_PRESET_STORAGE_KEY, themeDefinition.id);
 };
 
+const fetchThemeDefinitionByPresetId = async (presetId: string): Promise<ThemeDefinition | null> => {
+	const themePath = resolveThemePresetPath(presetId) ?? defaultThemePresetPath;
+
+	const response = await fetch(themePath, {
+		headers: {
+			Accept: "application/json",
+		},
+	});
+
+	if (!response.ok) {
+		throw new Error(`Theme preset request failed with status ${response.status}.`);
+	}
+
+	const candidate = (await response.json()) as unknown;
+	const result = validateThemeDefinition(candidate);
+
+	if (!result.success) {
+		throw new Error(result.errors.join(" "));
+	}
+
+	return result.data;
+};
+
 const setDocumentThemeMode = (theme: Theme): void => {
 	const rootElement = getRootElement();
 
@@ -111,6 +134,21 @@ export const resolvePreferredThemePresetPath = (): string => {
 	return resolveThemePresetPath(presetId) ?? defaultThemePresetPath;
 };
 
+export const applyThemePresetById = async (presetId: string, theme: Theme = getDocumentTheme()): Promise<ThemeDefinition | null> => {
+	try {
+		const definition = await fetchThemeDefinitionByPresetId(presetId);
+		if (!definition) {
+			return null;
+		}
+
+		applyThemeDefinition(definition, theme);
+		return definition;
+	} catch (error) {
+		console.error("Failed to apply theme preset.", error);
+		return null;
+	}
+};
+
 export const initializeThemeRuntime = async (): Promise<ThemeDefinition | null> => {
 	if (typeof window === "undefined") {
 		return null;
@@ -124,26 +162,7 @@ export const initializeThemeRuntime = async (): Promise<ThemeDefinition | null>
 	if (!themeInitializationPromise) {
 		themeInitializationPromise = (async (): Promise<ThemeDefinition | null> => {
 			try {
-				const response = await fetch(resolvePreferredThemePresetPath(), {
-					headers: {
-						Accept: "application/json",
-					},
-				});
-
-				if (!response.ok) {
-					throw new Error(`Theme preset request failed with status ${response.status}.`);
-				}
-
-				const candidate = (await response.json()) as unknown;
-				const result = validateThemeDefinition(candidate);
-
-				if (!result.success) {
-					throw new Error(result.errors.join(" "));
-				}
-
-				applyThemeDefinition(result.data, getDocumentTheme());
-
-				return result.data;
+				return await applyThemePresetById(resolvePreferredThemePresetId(), getDocumentTheme());
 			} catch (error) {
 				console.error("Failed to initialize theme runtime.", error);
 				return null;

Frontend/src/routes/settings/theme.tsx

@@ -1,16 +1,10 @@
 // Path: Frontend/src/routes/settings/theme.tsx
 
 import { type JSX } from "solid-js";
-import { SettingsDetailPage } from "../../components/settings/SettingsDetailPage/SettingsDetailPage";
+import { ThemeSettingsPage } from "../../components/settings/ThemeSettingsPage/ThemeSettingsPage";
 
 const SettingsThemeRoute = (): JSX.Element => {
-	return (
-		<SettingsDetailPage
-			title="Theme Settings"
-			description="Choose the visual presentation, density, and theming preferences for the current user."
-			focus={["Theme preset", "Density", "Visual preferences"]}
-		/>
-	);
+	return <ThemeSettingsPage />;
 };
 
 export default SettingsThemeRoute;

Frontend/src/theme/presets.ts

@@ -8,14 +8,31 @@ export const themePresetMetas = [
 		name: "Moku Default",
 		description: "The baseline Moku theme preset, matching the original shell styling tokens.",
 		path: "/themes/moku-default.json",
+		preview: {
+			canvas: "hsl(210 20% 99%)",
+			surface: "hsl(0 0% 100%)",
+			accent: "hsl(221 83% 53%)",
+		},
 	},
 	{
 		id: "moku-midnight",
 		name: "Moku Midnight",
 		description: "The active warm, low-light Moku theme preset inspired by the Midnight Discord palette direction.",
 		path: "/themes/moku-midnight.json",
+		preview: {
+			canvas: "#282828",
+			surface: "hsl(20 8% 16%)",
+			accent: "#d3869b",
+		},
 	},
-] as const satisfies readonly (Pick<ThemeDefinition, "id" | "name" | "description"> & { path: string })[];
+] as const satisfies readonly (Pick<ThemeDefinition, "id" | "name" | "description"> & {
+	path: string;
+	preview: {
+		canvas: string;
+		surface: string;
+		accent: string;
+	};
+})[];
 
 export const defaultThemePresetPath = "/themes/moku-midnight.json";