i18n-dashboard 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-dashboard",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "A web dashboard to manage vue-i18n translation keys with database persistence",
   "type": "module",
   "bin": {

package/src/app.vue

@@ -1,7 +1,30 @@
+<script setup lang="ts">
+/**
+ * Theme application: update appConfig.ui.colors so the @nuxt/ui colors plugin
+ * regenerates --ui-color-primary-* / --ui-color-neutral-* CSS variables.
+ * The plugin (node_modules/@nuxt/ui/dist/runtime/plugins/colors.js) is reactive —
+ * any change to appConfig.ui.colors triggers an automatic style tag update.
+ *
+ * useFetch is SSR-compatible, so the correct color is applied before the page
+ * reaches the browser (no flash of the default colour).
+ */
+const { theme } = useModuleConfig()
+const appConfig = useAppConfig()
+
+watch(
+  theme,
+  (t) => {
+    if (t?.primary) appConfig.ui.colors.primary = t.primary
+    if (t?.neutral) appConfig.ui.colors.neutral = t.neutral
+  },
+  { immediate: true },
+)
+</script>
+
 <template>
   <UApp>
     <NuxtLoadingIndicator
-      color="rgb(var(--ui-primary))"
+      color="var(--color-primary-500)"
       :height="3"
       :throttle="100"
     />

package/src/assets/locales/en.json

@@ -511,6 +511,7 @@
   "security.session_duration": "Session duration",
   "security.refresh_token_duration": "Refresh token duration",
   "security.reset_link_expiry": "Reset link expiry",
+  "security.nav_label": "Security",
 
   "logs.title": "System logs",
   "logs.description": "Error and warning logs generated by background processes",
@@ -558,5 +559,44 @@
   "smtp.gmail_step2": "If the page shows \"The setting you are looking for is not available\" → you must first enable 2-Step Verification on your Google account",
   "smtp.gmail_step3": "Type a name (e.g. \"i18n-dashboard\") and click Create",
   "smtp.gmail_step4": "Copy the 16-character code shown (e.g. abcd efgh ijkl mnop)",
-  "smtp.gmail_step5": "Paste it in the Password field below — use your Gmail address as Username"
+  "smtp.gmail_step5": "Paste it in the Password field below — use your Gmail address as Username",
+
+  "customization.title": "Customization",
+  "customization.description": "Configure branding, theme and custom widgets",
+  "customization.config_file_active": "Config file is active",
+  "customization.config_file_description": "Values in i18n-dashboard.config.json override these settings.",
+  "customization.branding": "Branding",
+  "customization.app_name": "App name",
+  "customization.app_name_placeholder": "i18n Dashboard",
+  "customization.subtitle": "Subtitle",
+  "customization.subtitle_placeholder": "vue-i18n manager",
+  "customization.logo_url": "Logo URL",
+  "customization.logo_url_placeholder": "https://example.com/logo.png",
+  "customization.logo_url_hint": "URL or base64 data URI. Replaces the default language icon.",
+  "customization.logo_alt": "logo",
+  "customization.default_app_name": "i18n Dashboard",
+  "customization.default_subtitle": "vue-i18n manager",
+  "customization.theme": "Theme",
+  "customization.primary_color": "Primary color",
+  "customization.neutral_color": "Neutral color",
+  "customization.default": "Default",
+  "customization.custom_widgets": "Custom widgets",
+  "customization.no_custom_widgets": "No custom widgets defined",
+  "customization.custom_widgets_hint": "Add iframe-based widgets that appear in the dashboard widget picker",
+  "customization.saved": "Customization saved",
+  "customization.add_widget": "Add custom widget",
+  "customization.edit_widget": "Edit custom widget",
+  "customization.widget_type": "Type ID",
+  "customization.widget_type_placeholder": "my-metrics",
+  "customization.widget_type_hint": "Unique identifier, no spaces",
+  "customization.widget_label": "Label",
+  "customization.widget_label_placeholder": "My Metrics",
+  "customization.widget_description": "Description",
+  "customization.widget_description_placeholder": "Short description shown in the widget picker",
+  "customization.widget_url": "iframe URL",
+  "customization.widget_icon": "Icon",
+  "customization.widget_icon_hint": "Heroicons name, e.g. i-heroicons-chart-bar",
+  "customization.widget_sizes": "Available sizes",
+  "customization.widget_default_size": "Default size",
+  "customization.nav_label": "Customization"
 }

package/src/components/dashboard/ProjectWidgetGrid.vue

@@ -1,6 +1,5 @@
 <script lang="ts" setup>
-import type { TWidgetType } from '../../types/dashboard.type'
-import { WIDGET_REGISTRY, WIDGET_SIZE_CLASSES } from '../../consts/dashboard.const'
+import { WIDGET_SIZE_CLASSES } from '../../consts/dashboard.const'
 
 const props = defineProps<{
   projectId: number
@@ -28,12 +27,13 @@ const showPicker = ref(false)
 const configIndex = ref(-1)
 
 const activeLayout = computed(() => editing.value ? localLayout.value : layout.value)
+const { registry: widgetRegistry, getEntry } = useWidgetRegistry()
 
 function sizeClass(size: string) {
   return WIDGET_SIZE_CLASSES[size as keyof typeof WIDGET_SIZE_CLASSES] ?? 'col-span-1 row-span-1'
 }
 
-function widgetComponent(type: TWidgetType) {
+function widgetComponent(type: string) {
   switch (type) {
     case 'stat-keys':
     case 'stat-coverage':
@@ -49,6 +49,9 @@ function widgetComponent(type: TWidgetType) {
     case 'review-queue':
       return resolveComponent('DashboardWidgetsReviewWidget')
     default:
+      if (getEntry(type)?.isCustom) {
+        return resolveComponent('DashboardWidgetsCustomIframeWidget')
+      }
       return 'div'
   }
 }
@@ -150,7 +153,7 @@ function onSaveConfig(patch: { dataSource?: any; title?: string | undefined }) {
           class="absolute -top-2 right-0 z-10 flex gap-0.5"
         >
           <button
-            v-for="s in WIDGET_REGISTRY[widget.type].sizes"
+            v-for="s in widgetRegistry[widget.type]?.sizes ?? []"
             :key="s"
             class="px-1 py-0.5 text-xs rounded shadow-sm transition-colors"
             :class="widget.size === s
@@ -164,7 +167,7 @@ function onSaveConfig(patch: { dataSource?: any; title?: string | undefined }) {
 
         <!-- Config button -->
         <button
-          v-if="editing && WIDGET_REGISTRY[widget.type].hasDataSource"
+          v-if="editing && widgetRegistry[widget.type]?.hasDataSource"
           class="absolute bottom-1 right-1 z-10 w-6 h-6 bg-gray-600/80 dark:bg-gray-400/80 rounded-full text-white flex items-center justify-center text-xs hover:bg-gray-700 transition-colors"
           @click.stop="configIndex = index"
         >

package/src/components/dashboard/WidgetGrid.vue

@@ -1,6 +1,5 @@
 <script lang="ts" setup>
-import type { TWidgetType } from '../../types/dashboard.type'
-import { WIDGET_REGISTRY, WIDGET_SIZE_CLASSES } from '../../consts/dashboard.const'
+import { WIDGET_SIZE_CLASSES } from '../../consts/dashboard.const'
 
 const { t } = useT()
 const { currentUser } = useAuth()
@@ -25,12 +24,13 @@ const showPicker = ref(false)
 const configIndex = ref(-1)
 
 const activeLayout = computed(() => editing.value ? localLayout.value : layout.value)
+const { registry: widgetRegistry, getEntry } = useWidgetRegistry()
 
 function sizeClass(size: string) {
   return WIDGET_SIZE_CLASSES[size as keyof typeof WIDGET_SIZE_CLASSES] ?? 'col-span-1 row-span-1'
 }
 
-function widgetComponent(type: TWidgetType) {
+function widgetComponent(type: string) {
   switch (type) {
     case 'stat-keys':
     case 'stat-coverage':
@@ -46,6 +46,9 @@ function widgetComponent(type: TWidgetType) {
     case 'review-queue':
       return resolveComponent('DashboardWidgetsReviewWidget')
     default:
+      if (getEntry(type)?.isCustom) {
+        return resolveComponent('DashboardWidgetsCustomIframeWidget')
+      }
       return 'div'
   }
 }
@@ -156,7 +159,7 @@ function onSaveConfig(patch: { dataSource?: any; title?: string | undefined }) {
           class="absolute -top-2 right-0 z-10 flex gap-0.5"
         >
           <button
-            v-for="s in WIDGET_REGISTRY[widget.type].sizes"
+            v-for="s in widgetRegistry[widget.type]?.sizes ?? []"
             :key="s"
             class="px-1 py-0.5 text-xs rounded shadow-sm transition-colors"
             :class="widget.size === s
@@ -169,7 +172,7 @@ function onSaveConfig(patch: { dataSource?: any; title?: string | undefined }) {
         </div>
 
         <button
-          v-if="editing && WIDGET_REGISTRY[widget.type].hasDataSource"
+          v-if="editing && widgetRegistry[widget.type]?.hasDataSource"
           class="absolute bottom-1 right-1 z-10 w-6 h-6 bg-gray-600/80 dark:bg-gray-400/80 rounded-full text-white flex items-center justify-center text-xs hover:bg-gray-700 transition-colors"
           @click.stop="configIndex = index"
         >

package/src/components/dashboard/WidgetPicker.vue

@@ -1,7 +1,6 @@
 <script lang="ts" setup>
 import type { TWidgetSize } from '../../types/dashboard.type'
 import type { IWidgetConfig } from '../../interfaces/dashboard.interface'
-import { WIDGET_REGISTRY } from '../../consts/dashboard.const'
 
 const { t } = useT()
 
@@ -20,20 +19,22 @@ const open = computed({
   set: (v) => emit('update:modelValue', v),
 })
 
+const { registry } = useWidgetRegistry()
+
 const availableWidgets = computed(() =>
-  Object.entries(WIDGET_REGISTRY).filter(([type]) => !props.excludeTypes?.includes(type)),
+  Object.entries(registry.value).filter(([type]) => !props.excludeTypes?.includes(type)),
 )
 
 const selectedSizes = ref<Record<string, TWidgetSize>>({})
 
 function getSelectedSize(type: string): TWidgetSize {
-  return selectedSizes.value[type] ?? WIDGET_REGISTRY[type as keyof typeof WIDGET_REGISTRY].defaultSize
+  return selectedSizes.value[type] ?? registry.value[type]?.defaultSize ?? 'md'
 }
 
 function addWidget(type: string) {
   const size = getSelectedSize(type)
   const id = Date.now().toString(36)
-  emit('add', { id, type: type as IWidgetConfig['type'], size })
+  emit('add', { id, type, size })
   open.value = false
 }
 </script>
@@ -52,16 +53,27 @@ function addWidget(type: string) {
           class="border border-gray-200 dark:border-gray-700 rounded-xl p-4 space-y-3 hover:border-primary-300 dark:hover:border-primary-600 transition-colors"
         >
           <div class="flex items-start gap-3">
-            <div class="w-9 h-9 rounded-lg bg-gray-100 dark:bg-gray-800 flex items-center justify-center shrink-0">
+            <div
+              class="w-9 h-9 rounded-lg flex items-center justify-center shrink-0"
+              :class="config.isCustom ? 'bg-primary-50 dark:bg-primary-950' : 'bg-gray-100 dark:bg-gray-800'"
+            >
               <UIcon
                 :name="config.icon"
-                class="text-gray-600 dark:text-gray-400"
+                :class="config.isCustom ? 'text-primary-500' : 'text-gray-600 dark:text-gray-400'"
               />
             </div>
-            <div class="min-w-0">
-              <p class="text-sm font-semibold text-gray-900 dark:text-white">
-                {{ config.label }}
-              </p>
+            <div class="min-w-0 flex-1">
+              <div class="flex items-center gap-1.5">
+                <p class="text-sm font-semibold text-gray-900 dark:text-white">
+                  {{ config.label }}
+                </p>
+                <span
+                  v-if="config.isCustom"
+                  class="text-[10px] px-1.5 py-0.5 rounded-full bg-primary-100 dark:bg-primary-900 text-primary-600 dark:text-primary-400 font-medium leading-none"
+                >
+                  {{ t('dashboard.custom', 'Custom') }}
+                </span>
+              </div>
               <p class="text-xs text-gray-400 mt-0.5">
                 {{ config.description }}
               </p>

package/src/components/dashboard/widgets/CustomIframeWidget.vue

@@ -0,0 +1,56 @@
+<script lang="ts" setup>
+import type { ICustomWidgetDef } from '../../../interfaces/project-config.interface'
+
+const props = defineProps<{
+  id: string
+  type: string
+  size: string
+  editing?: boolean
+  title?: string
+}>()
+
+const { customWidgets } = useModuleConfig()
+const def = computed<ICustomWidgetDef | undefined>(() =>
+  customWidgets.value.find(w => w.type === props.type),
+)
+const url = computed(() =>
+  def.value?.config?.kind === 'iframe' ? def.value.config.url : null,
+)
+const label = computed(() => props.title || def.value?.label || props.type)
+</script>
+
+<template>
+  <div class="w-full h-full relative rounded-xl overflow-hidden border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900">
+    <!-- Edit-mode overlay -->
+    <div
+      v-if="editing"
+      class="absolute inset-0 z-10 bg-gray-900/30 flex flex-col items-center justify-center gap-2 pointer-events-none"
+    >
+      <UIcon
+        name="i-heroicons-puzzle-piece"
+        class="text-white text-3xl"
+      />
+      <span class="text-white text-xs font-medium">{{ label }}</span>
+    </div>
+
+    <iframe
+      v-if="url"
+      :src="url"
+      :title="label"
+      class="w-full h-full border-0"
+      loading="lazy"
+      sandbox="allow-scripts"
+    />
+    <div
+      v-else
+      class="w-full h-full flex flex-col items-center justify-center text-gray-400 gap-2"
+    >
+      <UIcon
+        name="i-heroicons-puzzle-piece"
+        class="text-3xl"
+      />
+      <span class="text-xs">{{ label }}</span>
+      <span class="text-xs text-gray-300 dark:text-gray-600">No URL configured</span>
+    </div>
+  </div>
+</template>

package/src/composables/useModuleConfig.ts

@@ -0,0 +1,24 @@
+import type { IBrandingConfig, IThemeConfig, ICustomWidgetDef } from '../interfaces/project-config.interface'
+
+interface IAppConfigResponse {
+  branding: IBrandingConfig | null
+  theme: IThemeConfig | null
+  widgets: { custom?: ICustomWidgetDef[] } | null
+}
+
+/**
+ * Fetches branding / theme / custom-widget config from the server.
+ * useFetch deduplicates by key — all callers share the same cached response.
+ */
+export function useModuleConfig() {
+  const { data, refresh } = useFetch<IAppConfigResponse>('/api/app-config', {
+    key: 'module-config',
+    default: () => ({ branding: null, theme: null, widgets: null }),
+  })
+
+  const branding = computed(() => data.value?.branding ?? null)
+  const theme = computed(() => data.value?.theme ?? null)
+  const customWidgets = computed<ICustomWidgetDef[]>(() => data.value?.widgets?.custom ?? [])
+
+  return { branding, theme, customWidgets, refresh }
+}

package/src/composables/useWidgetRegistry.ts

@@ -0,0 +1,38 @@
+import { WIDGET_REGISTRY } from '../consts/dashboard.const'
+import type { TWidgetSize } from '../types/dashboard.type'
+
+export interface IWidgetRegistryEntry {
+  label: string
+  description: string
+  icon: string
+  sizes: TWidgetSize[]
+  defaultSize: TWidgetSize
+  hasDataSource: boolean
+  isCustom?: boolean
+}
+
+export function useWidgetRegistry() {
+  const { customWidgets } = useModuleConfig()
+
+  const registry = computed<Record<string, IWidgetRegistryEntry>>(() => {
+    const base: Record<string, IWidgetRegistryEntry> = { ...WIDGET_REGISTRY }
+    for (const w of customWidgets.value) {
+      base[w.type] = {
+        label: w.label,
+        description: w.description ?? '',
+        icon: w.icon ?? 'i-heroicons-puzzle-piece',
+        sizes: (w.sizes as TWidgetSize[]) ?? ['md', 'lg'],
+        defaultSize: (w.defaultSize as TWidgetSize) ?? 'md',
+        hasDataSource: false,
+        isCustom: true,
+      }
+    }
+    return base
+  })
+
+  function getEntry(type: string): IWidgetRegistryEntry | undefined {
+    return registry.value[type]
+  }
+
+  return { registry, getEntry }
+}

package/src/interfaces/dashboard.interface.ts

@@ -5,7 +5,7 @@ export interface IWidgetDataSource {
 
 export interface IWidgetConfig {
   id: string
-  type: 'stat-keys' | 'stat-coverage' | 'stat-languages' | 'stat-unused' | 'projects' | 'languages-coverage' | 'last-activity' | 'review-queue'
+  type: string  // built-in TWidgetType or any custom widget type defined in config
   size: 'sm' | 'md' | 'lg' | 'wide' | 'xl'
   dataSource?: IWidgetDataSource // default = 'global'
   title?: string // optional custom title override

package/src/interfaces/project-config.interface.ts

@@ -1,9 +1,40 @@
+export interface IBrandingConfig {
+  name?: string        // App name shown in sidebar (default: "i18n Dashboard")
+  subtitle?: string    // Subtitle below name (default: "vue-i18n manager")
+  logoUrl?: string     // URL or base64 data URI for the logo image
+}
+
+export interface IThemeConfig {
+  primary?: string     // Tailwind color name: 'blue' | 'violet' | 'green' | 'red' | 'orange' | 'teal' | 'cyan' | 'indigo' | 'purple' | 'pink' | 'rose' | 'sky' | 'emerald' | 'amber' | 'lime' | 'fuchsia' | 'yellow'
+  neutral?: string     // Tailwind neutral: 'slate' | 'gray' | 'zinc' | 'neutral' | 'stone'
+}
+
+export interface ICustomWidgetDef {
+  type: string                  // Unique identifier (e.g. "my-metric")
+  label: string                 // Display label in widget picker
+  description?: string          // Short description
+  icon?: string                 // Heroicons name (e.g. "i-heroicons-chart-bar")
+  sizes: string[]               // Allowed sizes: sm | md | lg | wide | xl
+  defaultSize: string           // Default size when added
+  config: IIframeWidgetConfig
+}
+
+export interface IIframeWidgetConfig {
+  kind: 'iframe'
+  url: string                   // URL to embed in an iframe
+}
+
 export interface IDashboardConfig {
-	uiLanguages?: string[]        // e.g. ["fr", "en", "es"]
-	defaultUiLanguage?: string    // e.g. "fr"
-	project?: {
-		name?: string
-		localesPath?: string
-		keySeparator?: string
-	}
+  uiLanguages?: string[]        // e.g. ["fr", "en", "es"]
+  defaultUiLanguage?: string    // e.g. "fr"
+  project?: {
+    name?: string
+    localesPath?: string
+    keySeparator?: string
+  }
+  branding?: IBrandingConfig
+  theme?: IThemeConfig
+  widgets?: {
+    custom?: ICustomWidgetDef[]
+  }
 }

package/src/layouts/default.vue

@@ -24,18 +24,25 @@
           to="/"
           class="flex items-center gap-2.5"
         >
-          <div class="w-8 h-8 rounded-lg bg-primary-500 flex items-center justify-center shrink-0">
+          <div class="w-8 h-8 rounded-lg bg-primary-500 flex items-center justify-center shrink-0 overflow-hidden">
+            <img
+              v-if="logoUrl"
+              :src="logoUrl"
+              :alt="appName"
+              class="w-full h-full object-cover"
+            >
             <UIcon
+              v-else
               name="i-heroicons-language"
               class="text-white text-base"
             />
           </div>
           <div>
             <h1 class="text-sm font-bold text-gray-900 dark:text-white leading-tight">
-              i18n Dashboard
+              {{ appName }}
             </h1>
             <p class="text-xs text-gray-400">
-              vue-i18n manager
+              {{ appSubtitle }}
             </p>
           </div>
         </NuxtLink>
@@ -225,7 +232,20 @@
             name="i-heroicons-shield-check"
             class="text-base shrink-0"
           />
-          <span class="flex-1">Sécurité</span>
+          <span class="flex-1">{{ t('security.nav_label', 'Security') }}</span>
+        </NuxtLink>
+        <NuxtLink
+          to="/admin/customization"
+          class="flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-colors"
+          :class="isActive('/admin/customization')
+            ? 'bg-primary-50 dark:bg-primary-900/30 text-primary-600 dark:text-primary-400 font-medium'
+            : 'text-gray-600 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-800'"
+        >
+          <UIcon
+            name="i-heroicons-paint-brush"
+            class="text-base shrink-0"
+          />
+          <span class="flex-1">{{ t('customization.nav_label', 'Customization') }}</span>
         </NuxtLink>
         <NuxtLink
           to="/admin/smtp"
@@ -390,6 +410,10 @@ const route = useRoute()
 const router = useRouter()
 const toast = useToast()
 const colorMode = useColorMode()
+const { branding } = useModuleConfig()
+const appName = computed(() => branding.value?.name || 'i18n Dashboard')
+const appSubtitle = computed(() => branding.value?.subtitle || 'vue-i18n manager')
+const logoUrl = computed(() => branding.value?.logoUrl || null)
 const { currentProject, projects: projectsData, systemProject, fetchProjects, visibleProjects: userProjects, syncing, syncProject, pending } = useProject()
 
 const appReady = ref(false)

package/src/pages/admin/customization.vue

@@ -0,0 +1,567 @@
+<script lang="ts" setup>
+import type { ICustomWidgetDef } from '../../interfaces/project-config.interface'
+
+const { t } = useT()
+const toast = useToast()
+const { refresh: refreshModuleConfig } = useModuleConfig()
+
+const PRIMARY_COLORS = [
+  'red', 'orange', 'amber', 'yellow', 'lime',
+  'green', 'emerald', 'teal', 'cyan', 'sky',
+  'blue', 'indigo', 'violet', 'purple', 'fuchsia',
+  'pink', 'rose',
+]
+
+const NEUTRAL_COLORS = ['slate', 'gray', 'zinc', 'neutral', 'stone']
+
+// Hardcoded palette values (shade 500 for primary, shade 400 for neutral).
+// Tailwind v4 only generates CSS variables for statically-referenced colors,
+// so dynamic `var(--color-${color}-500)` references are undefined at runtime.
+const COLOR_HEX: Record<string, string> = {
+  // primary (500)
+  red: '#ef4444',
+  orange: '#f97316',
+  amber: '#f59e0b',
+  yellow: '#eab308',
+  lime: '#84cc16',
+  green: '#22c55e',
+  emerald: '#10b981',
+  teal: '#14b8a6',
+  cyan: '#06b6d4',
+  sky: '#0ea5e9',
+  blue: '#3b82f6',
+  indigo: '#6366f1',
+  violet: '#8b5cf6',
+  purple: '#a855f7',
+  fuchsia: '#d946ef',
+  pink: '#ec4899',
+  rose: '#f43f5e',
+  // neutral (400)
+  slate: '#94a3b8',
+  gray: '#9ca3af',
+  zinc: '#a1a1aa',
+  neutral: '#a3a3a3',
+  stone: '#a8a29e',
+}
+
+const appConfig = useAppConfig()
+
+// ── State ──────────────────────────────────────────────────────────────────
+
+const pending = ref(true)
+const saving = ref(false)
+const hasConfigFile = ref(false)
+
+const branding = reactive({ name: '', subtitle: '', logoUrl: '' })
+const theme = reactive({ primary: '', neutral: '' })
+
+// Live preview: update appConfig so the @nuxt/ui colors plugin applies
+// changes immediately as the user clicks swatches (before saving to DB)
+watch(() => theme.primary, (color) => { if (color) appConfig.ui.colors.primary = color })
+watch(() => theme.neutral, (color) => { if (color) appConfig.ui.colors.neutral = color })
+const customWidgets = ref<ICustomWidgetDef[]>([])
+
+// Widget editor
+const showWidgetEditor = ref(false)
+const editingWidget = ref<ICustomWidgetDef | null>(null)
+const editingIndex = ref(-1)
+const widgetForm = reactive<ICustomWidgetDef>({
+  type: '',
+  label: '',
+  description: '',
+  icon: 'i-heroicons-puzzle-piece',
+  sizes: ['md', 'lg', 'wide'],
+  defaultSize: 'md',
+  config: { kind: 'iframe', url: '' },
+})
+const WIDGET_SIZES = ['sm', 'md', 'lg', 'wide', 'xl']
+
+// ── Load ───────────────────────────────────────────────────────────────────
+
+const { data, refresh } = await useFetch('/api/admin/customization', { key: 'admin-customization' })
+
+watchEffect(() => {
+  if (!data.value) return
+  hasConfigFile.value = data.value.hasConfigFile ?? false
+  Object.assign(branding, data.value.branding ?? {})
+  Object.assign(theme, data.value.theme ?? {})
+  customWidgets.value = data.value.customWidgets ?? []
+  pending.value = false
+})
+
+// ── Save ───────────────────────────────────────────────────────────────────
+
+async function save() {
+  saving.value = true
+  try {
+    await $fetch('/api/admin/customization', {
+      method: 'POST',
+      body: {
+        branding: { ...branding },
+        theme: { ...theme },
+        customWidgets: customWidgets.value,
+      },
+    })
+    await refreshModuleConfig()
+    toast.add({ title: t('customization.saved', 'Customization saved'), color: 'success' })
+  }
+  catch {
+    toast.add({ title: t('common.error', 'An error occurred'), color: 'error' })
+  }
+  finally {
+    saving.value = false
+  }
+}
+
+// ── Widget editor ──────────────────────────────────────────────────────────
+
+function openAddWidget() {
+  Object.assign(widgetForm, {
+    type: '',
+    label: '',
+    description: '',
+    icon: 'i-heroicons-puzzle-piece',
+    sizes: ['md', 'lg', 'wide'],
+    defaultSize: 'md',
+    config: { kind: 'iframe', url: '' },
+  })
+  editingIndex.value = -1
+  showWidgetEditor.value = true
+}
+
+function openEditWidget(widget: ICustomWidgetDef, index: number) {
+  Object.assign(widgetForm, {
+    ...widget,
+    sizes: [...widget.sizes],
+    config: { ...widget.config },
+  })
+  editingIndex.value = index
+  showWidgetEditor.value = true
+}
+
+function toggleWidgetSize(size: string) {
+  const idx = widgetForm.sizes.indexOf(size)
+  if (idx === -1) {
+    widgetForm.sizes.push(size)
+  }
+  else if (widgetForm.sizes.length > 1) {
+    widgetForm.sizes.splice(idx, 1)
+    if (widgetForm.defaultSize === size) {
+      widgetForm.defaultSize = widgetForm.sizes[0]
+    }
+  }
+}
+
+function saveWidget() {
+  if (!widgetForm.type || !widgetForm.label || !widgetForm.config.url) return
+  const widget: ICustomWidgetDef = {
+    type: widgetForm.type,
+    label: widgetForm.label,
+    description: widgetForm.description,
+    icon: widgetForm.icon,
+    sizes: [...widgetForm.sizes],
+    defaultSize: widgetForm.defaultSize,
+    config: { kind: 'iframe', url: widgetForm.config.url },
+  }
+  if (editingIndex.value === -1) {
+    customWidgets.value.push(widget)
+  }
+  else {
+    customWidgets.value[editingIndex.value] = widget
+  }
+  showWidgetEditor.value = false
+}
+
+function removeWidget(index: number) {
+  customWidgets.value.splice(index, 1)
+}
+</script>
+
+<template>
+  <div class="p-6">
+    <div class="mb-6">
+      <h1 class="text-2xl font-bold text-gray-900 dark:text-white">
+        {{ t('customization.title', 'Customization') }}
+      </h1>
+      <p class="text-gray-500 dark:text-gray-400 mt-1 text-sm">
+        {{ t('customization.description', 'Configure branding, theme and custom widgets') }}
+      </p>
+    </div>
+
+    <!-- Config file override notice -->
+    <UAlert
+      v-if="hasConfigFile"
+      class="mb-6"
+      icon="i-heroicons-information-circle"
+      color="info"
+      :title="t('customization.config_file_active', 'Config file is active')"
+      :description="t('customization.config_file_description', 'Values in i18n-dashboard.config.json override these settings.')"
+    />
+
+    <div class="max-w-3xl space-y-6">
+      <!-- ── Branding ──────────────────────────────────────────────────── -->
+      <UCard>
+        <template #header>
+          <div class="flex items-center gap-2">
+            <UIcon
+              name="i-heroicons-paint-brush"
+              class="text-primary-500"
+            />
+            <h2 class="font-semibold text-gray-900 dark:text-white">
+              {{ t('customization.branding', 'Branding') }}
+            </h2>
+          </div>
+        </template>
+
+        <div class="space-y-4">
+          <UFormField :label="t('customization.app_name', 'App name')">
+            <UInput
+              v-model="branding.name"
+              :placeholder="t('customization.app_name_placeholder', 'i18n Dashboard')"
+              class="w-full"
+            />
+          </UFormField>
+          <UFormField :label="t('customization.subtitle', 'Subtitle')">
+            <UInput
+              v-model="branding.subtitle"
+              :placeholder="t('customization.subtitle_placeholder', 'vue-i18n manager')"
+              class="w-full"
+            />
+          </UFormField>
+          <UFormField :label="t('customization.logo_url', 'Logo URL')">
+            <UInput
+              v-model="branding.logoUrl"
+              :placeholder="t('customization.logo_url_placeholder', 'https://example.com/logo.png')"
+              class="w-full"
+            />
+            <template #help>
+              {{ t('customization.logo_url_hint', 'URL or base64 data URI. Replaces the default language icon.') }}
+            </template>
+          </UFormField>
+
+          <!-- Logo preview -->
+          <div
+            v-if="branding.logoUrl"
+            class="flex items-center gap-3 p-3 rounded-lg bg-gray-50 dark:bg-gray-800"
+          >
+            <div class="w-8 h-8 rounded-lg bg-primary-500 flex items-center justify-center overflow-hidden shrink-0">
+              <img
+                :src="branding.logoUrl"
+                :alt="branding.name || t('customization.logo_alt', 'logo')"
+                class="w-full h-full object-cover"
+              >
+            </div>
+            <div>
+              <p class="text-sm font-bold text-gray-900 dark:text-white">
+                {{ branding.name || t('customization.default_app_name', 'i18n Dashboard') }}
+              </p>
+              <p class="text-xs text-gray-400">
+                {{ branding.subtitle || t('customization.default_subtitle', 'vue-i18n manager') }}
+              </p>
+            </div>
+          </div>
+        </div>
+      </UCard>
+
+      <!-- ── Theme ─────────────────────────────────────────────────────── -->
+      <UCard>
+        <template #header>
+          <div class="flex items-center gap-2">
+            <UIcon
+              name="i-heroicons-swatch"
+              class="text-primary-500"
+            />
+            <h2 class="font-semibold text-gray-900 dark:text-white">
+              {{ t('customization.theme', 'Theme') }}
+            </h2>
+          </div>
+        </template>
+
+        <div class="space-y-5">
+          <!-- Primary color -->
+          <UFormField :label="t('customization.primary_color', 'Primary color')">
+            <div class="flex flex-wrap gap-2 mt-1">
+              <button
+                v-for="color in PRIMARY_COLORS"
+                :key="color"
+                class="w-7 h-7 rounded-full border-2 transition-all"
+                :class="theme.primary === color
+                  ? 'border-gray-900 dark:border-white scale-110'
+                  : 'border-black/10 hover:scale-105'"
+                :style="{ backgroundColor: COLOR_HEX[color] }"
+                :title="color"
+                @click="theme.primary = theme.primary === color ? '' : color"
+              />
+              <button
+                class="w-7 h-7 rounded-full border-2 border-dashed border-gray-300 dark:border-gray-600 flex items-center justify-center text-gray-400 hover:border-gray-400 transition-colors"
+                :class="!theme.primary ? 'border-gray-900 dark:border-white' : ''"
+                :title="t('customization.default', 'Default')"
+                @click="theme.primary = ''"
+              >
+                <UIcon
+                  name="i-heroicons-x-mark"
+                  class="text-xs"
+                />
+              </button>
+            </div>
+            <p
+              v-if="theme.primary"
+              class="mt-1.5 text-xs text-gray-400"
+            >
+              {{ theme.primary }}
+            </p>
+          </UFormField>
+
+          <!-- Neutral color -->
+          <UFormField :label="t('customization.neutral_color', 'Neutral color')">
+            <div class="flex flex-wrap gap-2 mt-1">
+              <button
+                v-for="color in NEUTRAL_COLORS"
+                :key="color"
+                class="w-7 h-7 rounded-full border-2 transition-all"
+                :class="theme.neutral === color
+                  ? 'border-gray-900 dark:border-white scale-110'
+                  : 'border-black/10 hover:scale-105'"
+                :style="{ backgroundColor: COLOR_HEX[color] }"
+                :title="color"
+                @click="theme.neutral = theme.neutral === color ? '' : color"
+              />
+              <button
+                class="w-7 h-7 rounded-full border-2 border-dashed border-gray-300 dark:border-gray-600 flex items-center justify-center text-gray-400 hover:border-gray-400 transition-colors"
+                :class="!theme.neutral ? 'border-gray-900 dark:border-white' : ''"
+                :title="t('customization.default', 'Default')"
+                @click="theme.neutral = ''"
+              >
+                <UIcon
+                  name="i-heroicons-x-mark"
+                  class="text-xs"
+                />
+              </button>
+            </div>
+            <p
+              v-if="theme.neutral"
+              class="mt-1.5 text-xs text-gray-400"
+            >
+              {{ theme.neutral }}
+            </p>
+          </UFormField>
+        </div>
+      </UCard>
+
+      <!-- ── Custom widgets ────────────────────────────────────────────── -->
+      <UCard>
+        <template #header>
+          <div class="flex items-center justify-between">
+            <div class="flex items-center gap-2">
+              <UIcon
+                name="i-heroicons-puzzle-piece"
+                class="text-primary-500"
+              />
+              <h2 class="font-semibold text-gray-900 dark:text-white">
+                {{ t('customization.custom_widgets', 'Custom widgets') }}
+              </h2>
+            </div>
+            <UButton
+              size="xs"
+              icon="i-heroicons-plus"
+              variant="outline"
+              color="neutral"
+              @click="openAddWidget"
+            >
+              {{ t('common.add', 'Add') }}
+            </UButton>
+          </div>
+        </template>
+
+        <div
+          v-if="customWidgets.length === 0"
+          class="text-center py-8 text-gray-400"
+        >
+          <UIcon
+            name="i-heroicons-puzzle-piece"
+            class="text-3xl mb-2"
+          />
+          <p class="text-sm">
+            {{ t('customization.no_custom_widgets', 'No custom widgets defined') }}
+          </p>
+          <p class="text-xs mt-1">
+            {{ t('customization.custom_widgets_hint', 'Add iframe-based widgets that appear in the dashboard widget picker') }}
+          </p>
+        </div>
+
+        <div
+          v-else
+          class="space-y-2"
+        >
+          <div
+            v-for="(widget, index) in customWidgets"
+            :key="widget.type"
+            class="flex items-center gap-3 p-3 rounded-lg border border-gray-200 dark:border-gray-700"
+          >
+            <div class="w-8 h-8 rounded-lg bg-primary-50 dark:bg-primary-950 flex items-center justify-center shrink-0">
+              <UIcon
+                :name="widget.icon || 'i-heroicons-puzzle-piece'"
+                class="text-primary-500"
+              />
+            </div>
+            <div class="flex-1 min-w-0">
+              <p class="text-sm font-semibold text-gray-900 dark:text-white truncate">
+                {{ widget.label }}
+              </p>
+              <p class="text-xs text-gray-400 truncate">
+                {{ widget.config.url }}
+              </p>
+            </div>
+            <div class="flex items-center gap-1 shrink-0">
+              <UButton
+                size="xs"
+                variant="ghost"
+                color="neutral"
+                icon="i-heroicons-pencil"
+                @click="openEditWidget(widget, index)"
+              />
+              <UButton
+                size="xs"
+                variant="ghost"
+                color="error"
+                icon="i-heroicons-trash"
+                @click="removeWidget(index)"
+              />
+            </div>
+          </div>
+        </div>
+      </UCard>
+
+      <!-- Save button -->
+      <div class="flex justify-end">
+        <UButton
+          :loading="saving"
+          icon="i-heroicons-check"
+          @click="save"
+        >
+          {{ t('common.save', 'Save') }}
+        </UButton>
+      </div>
+    </div>
+
+    <!-- ── Widget editor modal ─────────────────────────────────────────── -->
+    <UModal
+      v-model:open="showWidgetEditor"
+      :title="editingIndex === -1
+        ? t('customization.add_widget', 'Add custom widget')
+        : t('customization.edit_widget', 'Edit custom widget')"
+    >
+      <template #body>
+        <div class="space-y-4 p-1">
+          <div class="grid grid-cols-2 gap-4">
+            <UFormField
+              :label="t('customization.widget_type', 'Type ID')"
+              required
+            >
+              <UInput
+                v-model="widgetForm.type"
+                :placeholder="t('customization.widget_type_placeholder', 'my-metrics')"
+                :disabled="editingIndex !== -1"
+                class="w-full"
+              />
+              <template #help>
+                {{ t('customization.widget_type_hint', 'Unique identifier, no spaces') }}
+              </template>
+            </UFormField>
+
+            <UFormField
+              :label="t('customization.widget_label', 'Label')"
+              required
+            >
+              <UInput
+                v-model="widgetForm.label"
+                :placeholder="t('customization.widget_label_placeholder', 'My Metrics')"
+                class="w-full"
+              />
+            </UFormField>
+          </div>
+
+          <UFormField :label="t('customization.widget_description', 'Description')">
+            <UInput
+              v-model="widgetForm.description"
+              :placeholder="t('customization.widget_description_placeholder', 'Short description shown in the widget picker')"
+              class="w-full"
+            />
+          </UFormField>
+
+          <UFormField
+            :label="t('customization.widget_url', 'iframe URL')"
+            required
+          >
+            <UInput
+              v-model="widgetForm.config.url"
+              placeholder="https://example.com/embed"
+              class="w-full"
+            />
+          </UFormField>
+
+          <UFormField :label="t('customization.widget_icon', 'Icon')">
+            <UInput
+              v-model="widgetForm.icon"
+              placeholder="i-heroicons-chart-bar"
+              class="w-full"
+            />
+            <template #help>
+              {{ t('customization.widget_icon_hint', 'Heroicons name, e.g. i-heroicons-chart-bar') }}
+            </template>
+          </UFormField>
+
+          <UFormField :label="t('customization.widget_sizes', 'Available sizes')">
+            <div class="flex gap-2 mt-1">
+              <button
+                v-for="size in WIDGET_SIZES"
+                :key="size"
+                class="px-3 py-1.5 text-xs rounded-lg border transition-colors"
+                :class="widgetForm.sizes.includes(size)
+                  ? 'bg-primary-500 border-primary-500 text-white'
+                  : 'border-gray-300 dark:border-gray-600 text-gray-600 dark:text-gray-400 hover:border-primary-400'"
+                @click="toggleWidgetSize(size)"
+              >
+                {{ size }}
+              </button>
+            </div>
+          </UFormField>
+
+          <UFormField :label="t('customization.widget_default_size', 'Default size')">
+            <div class="flex gap-2 mt-1">
+              <button
+                v-for="size in widgetForm.sizes"
+                :key="size"
+                class="px-3 py-1.5 text-xs rounded-lg border transition-colors"
+                :class="widgetForm.defaultSize === size
+                  ? 'bg-primary-500 border-primary-500 text-white'
+                  : 'border-gray-300 dark:border-gray-600 text-gray-600 dark:text-gray-400 hover:border-primary-400'"
+                @click="widgetForm.defaultSize = size"
+              >
+                {{ size }}
+              </button>
+            </div>
+          </UFormField>
+        </div>
+      </template>
+
+      <template #footer>
+        <div class="flex justify-end gap-2">
+          <UButton
+            variant="ghost"
+            color="neutral"
+            @click="showWidgetEditor = false"
+          >
+            {{ t('common.cancel', 'Cancel') }}
+          </UButton>
+          <UButton
+            :disabled="!widgetForm.type || !widgetForm.label || !widgetForm.config.url"
+            @click="saveWidget"
+          >
+            {{ editingIndex === -1 ? t('common.add', 'Add') : t('common.save', 'Save') }}
+          </UButton>
+        </div>
+      </template>
+    </UModal>
+  </div>
+</template>

package/src/server/api/admin/customization.get.ts

@@ -0,0 +1,51 @@
+import { getDb } from '../../db/index'
+import { readProjectConfig } from '../../utils/project-config.util'
+
+const DB_KEYS = [
+  'branding_name',
+  'branding_subtitle',
+  'branding_logo_url',
+  'theme_primary',
+  'theme_neutral',
+  'custom_widgets',
+] as const
+
+export default defineEventHandler(async (event) => {
+  const user = event.context.user
+  if (!user?.is_super_admin) throw createError({ statusCode: 403, message: 'Forbidden' })
+
+  const db = getDb()
+  const rows = await db('settings').whereIn('key', [...DB_KEYS]).select('key', 'value')
+  const map: Record<string, string> = {}
+  for (const r of rows) map[r.key] = r.value || ''
+
+  let customWidgets: unknown[] = []
+  if (map.custom_widgets) {
+    try {
+      const parsed = JSON.parse(map.custom_widgets)
+      customWidgets = Array.isArray(parsed) ? parsed : []
+    }
+    catch {
+      // DB value is corrupted — return empty array rather than crashing
+      customWidgets = []
+    }
+  }
+
+  // Indicate whether a config file is active (its values override DB)
+  const fileConfig = readProjectConfig()
+  const hasConfigFile = !!(fileConfig.branding || fileConfig.theme || fileConfig.widgets)
+
+  return {
+    hasConfigFile,
+    branding: {
+      name: map.branding_name || '',
+      subtitle: map.branding_subtitle || '',
+      logoUrl: map.branding_logo_url || '',
+    },
+    theme: {
+      primary: map.theme_primary || '',
+      neutral: map.theme_neutral || '',
+    },
+    customWidgets,
+  }
+})

package/src/server/api/admin/customization.post.ts

@@ -0,0 +1,70 @@
+import { getDb } from '../../db/index'
+import type { IBrandingConfig, IThemeConfig, ICustomWidgetDef } from '../../../interfaces/project-config.interface'
+import {
+  validateBranding,
+  validateTheme,
+  validateCustomWidgets,
+} from '../../utils/customization-validation.util'
+
+interface ICustomizationBody {
+  branding?: IBrandingConfig
+  theme?: IThemeConfig
+  customWidgets?: ICustomWidgetDef[]
+}
+
+async function upsert(db: ReturnType<typeof getDb>, key: string, value: string) {
+  const existing = await db('settings').where({ key }).first()
+  if (existing) {
+    await db('settings').where({ key }).update({ value, updated_at: db.fn.now() })
+  }
+  else {
+    await db('settings').insert({ key, value })
+  }
+}
+
+export default defineEventHandler(async (event) => {
+  const user = event.context.user
+  if (!user?.is_super_admin) throw createError({ statusCode: 403, message: 'Forbidden' })
+
+  const body = await readBody<ICustomizationBody>(event)
+  if (!body || typeof body !== 'object')
+    throw createError({ statusCode: 400, message: 'Invalid request body' })
+
+  // ── Validate inputs before touching the DB ────────────────────────────────
+
+  if (body.branding !== undefined) {
+    const err = validateBranding(body.branding)
+    if (err) throw createError({ statusCode: 422, message: err })
+  }
+
+  if (body.theme !== undefined) {
+    const err = validateTheme(body.theme)
+    if (err) throw createError({ statusCode: 422, message: err })
+  }
+
+  if (body.customWidgets !== undefined) {
+    const err = validateCustomWidgets(body.customWidgets)
+    if (err) throw createError({ statusCode: 422, message: err })
+  }
+
+  // ── Persist ───────────────────────────────────────────────────────────────
+
+  const db = getDb()
+
+  if (body.branding !== undefined) {
+    await upsert(db, 'branding_name', body.branding.name ?? '')
+    await upsert(db, 'branding_subtitle', body.branding.subtitle ?? '')
+    await upsert(db, 'branding_logo_url', body.branding.logoUrl ?? '')
+  }
+
+  if (body.theme !== undefined) {
+    await upsert(db, 'theme_primary', body.theme.primary ?? '')
+    await upsert(db, 'theme_neutral', body.theme.neutral ?? '')
+  }
+
+  if (body.customWidgets !== undefined) {
+    await upsert(db, 'custom_widgets', JSON.stringify(body.customWidgets))
+  }
+
+  return { ok: true }
+})

package/src/server/api/app-config.get.ts

@@ -0,0 +1,55 @@
+import { getDb } from '../db/index'
+import { readProjectConfig } from '../utils/project-config.util'
+import type { IBrandingConfig, IThemeConfig, ICustomWidgetDef } from '../../interfaces/project-config.interface'
+
+// This endpoint is intentionally public: branding and theme are needed before login
+// (login page styling, loading indicator colour). Widget *metadata* (type/label/icon/sizes)
+// is safe to expose publicly — widget URLs are only rendered inside the authenticated dashboard.
+
+export default defineEventHandler(async () => {
+  // ── Read DB settings (base values) ─────────────────────────────────────────
+  const db = getDb()
+  const rows = await db('settings')
+    .whereIn('key', ['branding_name', 'branding_subtitle', 'branding_logo_url', 'theme_primary', 'theme_neutral', 'custom_widgets'])
+    .select('key', 'value')
+
+  const map: Record<string, string> = {}
+  for (const r of rows) map[r.key] = r.value || ''
+
+  const dbBranding: IBrandingConfig = {
+    name: map.branding_name || undefined,
+    subtitle: map.branding_subtitle || undefined,
+    logoUrl: map.branding_logo_url || undefined,
+  }
+  const dbTheme: IThemeConfig = {
+    primary: map.theme_primary || undefined,
+    neutral: map.theme_neutral || undefined,
+  }
+  let dbWidgets: ICustomWidgetDef[] = []
+  if (map.custom_widgets) {
+    try {
+      const parsed = JSON.parse(map.custom_widgets)
+      dbWidgets = Array.isArray(parsed) ? parsed : []
+    }
+    catch {
+      // DB value is corrupted — degrade gracefully
+      dbWidgets = []
+    }
+  }
+
+  // ── Merge with config file (file takes priority) ────────────────────────────
+  const fileConfig = readProjectConfig()
+
+  const branding: IBrandingConfig = { ...dbBranding, ...fileConfig.branding }
+  const theme: IThemeConfig = { ...dbTheme, ...fileConfig.theme }
+  const customWidgets: ICustomWidgetDef[] = fileConfig.widgets?.custom ?? dbWidgets
+
+  const hasBranding = Object.values(branding).some(Boolean)
+  const hasTheme = Object.values(theme).some(Boolean)
+
+  return {
+    branding: hasBranding ? branding : null,
+    theme: hasTheme ? theme : null,
+    widgets: customWidgets.length ? { custom: customWidgets } : null,
+  }
+})

package/src/server/utils/customization-validation.util.ts

@@ -0,0 +1,76 @@
+import type { IBrandingConfig, IThemeConfig, ICustomWidgetDef } from '../../interfaces/project-config.interface'
+
+// ── Allowed colour sets ─────────────────────────────────────────────────────
+
+export const ALLOWED_PRIMARY_COLORS = new Set([
+  'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal',
+  'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose',
+])
+
+export const ALLOWED_NEUTRAL_COLORS = new Set(['slate', 'gray', 'zinc', 'neutral', 'stone'])
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+// Only http / https URLs are accepted — blocks javascript:, data:, file:, vbscript:, etc.
+const SAFE_URL_RE = /^https?:\/\/.+/i
+
+export function isSafeUrl(url: string | undefined): boolean {
+  if (!url) return true
+  return SAFE_URL_RE.test(url) && url.length <= 2048
+}
+
+// Widget type must be kebab-case identifiers (e.g. "my-widget", "metrics")
+const WIDGET_TYPE_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
+
+// ── Validators ──────────────────────────────────────────────────────────────
+
+export function validateBranding(branding: IBrandingConfig): string | null {
+  if (branding.name !== undefined && branding.name.length > 100)
+    return 'branding.name must be 100 characters or fewer'
+  if (branding.subtitle !== undefined && branding.subtitle.length > 200)
+    return 'branding.subtitle must be 200 characters or fewer'
+  if (branding.logoUrl && !isSafeUrl(branding.logoUrl))
+    return 'branding.logoUrl must be a valid http/https URL (max 2048 chars)'
+  return null
+}
+
+export function validateTheme(theme: IThemeConfig): string | null {
+  if (theme.primary && !ALLOWED_PRIMARY_COLORS.has(theme.primary))
+    return `theme.primary "${theme.primary}" is not a valid Tailwind color name`
+  if (theme.neutral && !ALLOWED_NEUTRAL_COLORS.has(theme.neutral))
+    return `theme.neutral "${theme.neutral}" is not a valid Tailwind neutral color`
+  return null
+}
+
+export function validateCustomWidgets(widgets: ICustomWidgetDef[]): string | null {
+  if (!Array.isArray(widgets))
+    return 'widgets.custom must be an array'
+  if (widgets.length > 20)
+    return 'Maximum 20 custom widgets allowed'
+
+  const seenTypes = new Set<string>()
+
+  for (const w of widgets) {
+    if (!w.type || !WIDGET_TYPE_RE.test(w.type))
+      return `Widget type "${w.type}" must match pattern [a-z0-9-] (e.g. "my-widget")`
+    if (w.type.length > 64)
+      return `Widget type "${w.type}" exceeds 64 characters`
+    if (seenTypes.has(w.type))
+      return `Duplicate widget type: "${w.type}"`
+    seenTypes.add(w.type)
+
+    if (!w.label || typeof w.label !== 'string' || w.label.length > 100)
+      return `Widget "${w.type}": label must be 1–100 characters`
+    if (w.description !== undefined && w.description.length > 300)
+      return `Widget "${w.type}": description exceeds 300 characters`
+    if (w.icon !== undefined && w.icon.length > 100)
+      return `Widget "${w.type}": icon name exceeds 100 characters`
+
+    if (!w.config || w.config.kind !== 'iframe')
+      return `Widget "${w.type}": only "iframe" kind is supported`
+    if (!w.config.url || !isSafeUrl(w.config.url))
+      return `Widget "${w.type}": URL must be a valid http/https URL (max 2048 chars)`
+  }
+
+  return null
+}