@nocobase/app-template-default 1.0.0-beta.86 → 1.0.0-beta.87

package/.agents/rules/shell.md

@@ -20,6 +20,8 @@ Navigation groups retain their expanded or collapsed state while the navigation
 
 ## Account menu and session
 
+Theme lives in the account menu as a submenu beside Language, rather than a separate header action. `client/theme/theme-settings.tsx` renders menu radio groups for color mode and theme preset; the existing theme providers own selection, persistence and restoration. Keep it inside `DropdownMenuContent` for pointer, touch and keyboard navigation.
+
 The account menu checks Better Auth sign-out results before refreshing the session and shows a localized error toast for API or network failures. Preserve this behavior when upgrading the shell; navigation alone does not revoke a session.
 
 The authorization provider clears the permission snapshot before rendering a new session. Route navigation and page guards subscribe to the authorization revision; preserve these checks when customizing the shell so account changes and permission updates take effect without a reload. Pending checks hide protected content, and failed checks deny access.

package/client/extensions/nocobase-file-component-ui/components/previewers/file-preview-content.tsx

@@ -158,7 +158,7 @@ function ImagePreview(inputProps: {
     <img
       src={url}
       alt={file.filename}
-      className='max-h-[70vh] max-w-full object-contain'
+      className='mx-auto block max-h-[70vh] max-w-full object-contain'
       onError={() => setFailedUrl(url)}
     />
   );

package/client/layouts/components/header-actions.tsx

@@ -1,7 +1,6 @@
 import type { ReactElement } from 'react';
 import { TooltipProvider } from '#components/ui/tooltip';
 
-import { ThemeSettings } from '../../theme/index.js';
 import { UserMenu } from './user-menu.js';
 
 /** The header's right-hand actions, shared by every authenticated page. */
@@ -9,7 +8,6 @@ export function HeaderActions(): ReactElement {
   return (
     <TooltipProvider>
       <div className='flex shrink-0 items-center gap-2'>
-        <ThemeSettings />
         <UserMenu />
       </div>
     </TooltipProvider>

package/client/layouts/components/user-menu.tsx

@@ -1,5 +1,5 @@
 import { useAuthenticationErrorResolver } from '@nocobase/app-plugin-authentication/client/actions';
-import { useToaster } from '@nocobase/app-client';
+import { getAvatarInitials, useToaster } from '@nocobase/app-client';
 import { useTranslation } from '@nocobase/i18n/client';
 import { useAuthentication } from '@nocobase/app-plugin-authentication/client';
 import { LogOut, UserRound } from 'lucide-react';
@@ -13,6 +13,7 @@ import {
   DropdownMenuTrigger,
 } from '#components/ui/dropdown-menu';
 
+import { ThemeSettings } from '../../theme/index.js';
 import { LanguageSwitcher } from './language-switcher.js';
 
 export function UserMenu(): ReactElement {
@@ -39,7 +40,9 @@ export function UserMenu(): ReactElement {
     identity?.fullName ||
     identity?.email ||
     t('account.fallback', { defaultValue: 'Account' });
-  const initials = getInitials(name);
+  const initials = getAvatarInitials(name, {
+    cjk: Boolean(identity?.fullName),
+  });
 
   return (
     <DropdownMenu>
@@ -74,6 +77,7 @@ export function UserMenu(): ReactElement {
         </div>
         <DropdownMenuSeparator />
         <LanguageSwitcher />
+        <ThemeSettings />
         <DropdownMenuSeparator />
         <DropdownMenuItem
           disabled={isLoggingOut}
@@ -120,14 +124,3 @@ export function UserMenu(): ReactElement {
     </DropdownMenu>
   );
 }
-
-function getInitials(name: string): string {
-  const words = name.trim().split(/\s+/).filter(Boolean);
-  if (words.length === 0) {
-    return '?';
-  }
-  return words
-    .slice(0, 2)
-    .map((word) => word[0]?.toUpperCase() ?? '')
-    .join('');
-}

package/client/locales/system/en-US.ts

@@ -367,7 +367,7 @@ const systemEnUS = {
   },
 
   appearance: {
-    title: 'Appearance',
+    title: 'Theme',
     mode: 'Color mode',
     preset: 'Theme',
     light: 'Light',

package/client/locales/system/zh-CN.ts

@@ -344,7 +344,7 @@ const systemZhCN: SystemResource = {
   },
 
   appearance: {
-    title: '外观',
+    title: '主题',
     mode: '颜色模式',
     preset: '主题',
     light: '浅色',

package/client/routing/standalone-page-layout.tsx

@@ -1,14 +1,9 @@
 import type { ReactElement } from 'react';
 import { Outlet } from 'react-router';
 
-import { ThemeSettings } from '../theme/index.js';
-
 export function StandalonePageLayout(): ReactElement {
   return (
     <div className='relative min-h-svh'>
-      <div className='fixed top-4 right-4 z-50'>
-        <ThemeSettings />
-      </div>
       <Outlet />
     </div>
   );

package/client/theme/theme-settings.tsx

@@ -1,16 +1,16 @@
-import { Check, Monitor, Moon, Palette, Sun } from 'lucide-react';
+import { Monitor, Moon, Palette, Sun } from 'lucide-react';
 import { useTheme } from 'next-themes';
 import { useTranslation } from '@nocobase/i18n/client';
-import { useId, type ReactElement } from 'react';
-import { Button } from '#components/ui/button';
-import { RadioGroup, RadioGroupItem } from '#components/ui/radio-group';
+import type { ReactElement } from 'react';
 import {
-  Popover,
-  PopoverTrigger,
-  PopoverContent,
-  PopoverTitle,
-} from '#components/ui/popover';
-import { cn } from 'cn';
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+} from '#components/ui/dropdown-menu';
 import { useThemePreset } from './theme-context';
 import { themePresets } from './theme-presets';
 
@@ -20,164 +20,62 @@ const COLOR_MODES = [
   { id: 'system', icon: Monitor },
 ] as const;
 
+/** Account-menu appearance choices; the existing providers own persistence. */
 export function ThemeSettings(): ReactElement {
   const { theme, setTheme } = useTheme();
   const { preset, setPreset } = useThemePreset();
   const { t } = useTranslation();
-  const id = useId();
-  const title = t('appearance.title', { defaultValue: 'Appearance' });
-  return (
-    <Popover>
-      <PopoverTrigger
-        openOnHover
-        delay={0}
-        render={
-          <Button
-            aria-label={title}
-            size='icon'
-            variant='outline'
-            className='size-10 rounded-xl border-border bg-background/60 hover:bg-accent/50'
-          />
-        }
-      >
-        <Palette aria-hidden='true' className='size-5' />
-      </PopoverTrigger>
-      {/* Keep the panel width independent of density; its content still uses theme tokens. */}
-      <PopoverContent
-        align='end'
-        className='w-xs max-w-[calc(100vw-2rem)] gap-4 p-4'
-      >
-        <div className='flex items-center justify-between'>
-          <PopoverTitle className='text-sm font-semibold text-foreground'>
-            {title}
-          </PopoverTitle>
-        </div>
 
-        <fieldset className='space-y-2'>
-          <legend className='text-xs font-medium text-muted-foreground'>
+  return (
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger className='gap-2'>
+        <Palette aria-hidden='true' className='size-4' />
+        {t('appearance.title', { defaultValue: 'Theme' })}
+      </DropdownMenuSubTrigger>
+      <DropdownMenuSubContent className='min-w-44'>
+        <DropdownMenuRadioGroup
+          value={theme}
+          onValueChange={(value) => setTheme(String(value))}
+          aria-label={t('appearance.mode', { defaultValue: 'Color mode' })}
+        >
+          <DropdownMenuLabel>
             {t('appearance.mode', { defaultValue: 'Color mode' })}
-          </legend>
-          <RadioGroup
-            name={id + '-mode'}
-            value={theme}
-            onValueChange={(value) => setTheme(String(value))}
-            aria-label={t('appearance.mode', { defaultValue: 'Color mode' })}
-            className='grid-cols-3 gap-1 rounded-lg bg-muted/70 p-1'
-          >
-            {COLOR_MODES.map(({ id: mode, icon: ModeIcon }) => {
-              const isSelected = theme === mode;
-              return (
-                <label
-                  key={mode}
-                  className={cn(
-                    'relative flex min-w-0 cursor-pointer items-center justify-center gap-1.5 rounded-md px-2 py-1.5 text-xs font-medium transition-colors select-none',
-                    isSelected
-                      ? 'bg-background text-foreground shadow-xs'
-                      : 'text-muted-foreground hover:bg-background/40 hover:text-foreground',
-                  )}
-                >
-                  {/* `absolute` over the primitive's `relative`, which would keep
-                      the hidden radio in the row and push the words aside. */}
-                  <RadioGroupItem value={mode} className='absolute sr-only' />
-                  <ModeIcon aria-hidden='true' className='size-3.5 shrink-0' />
-                  <span className='whitespace-nowrap'>
-                    {t('appearance.' + mode, {
-                      defaultValue: mode[0].toUpperCase() + mode.slice(1),
-                    })}
-                  </span>
-                </label>
-              );
-            })}
-          </RadioGroup>
-        </fieldset>
-
-        <fieldset className='space-y-2'>
-          <legend className='text-xs font-medium text-muted-foreground'>
+          </DropdownMenuLabel>
+          {COLOR_MODES.map(({ id: mode, icon: ModeIcon }) => (
+            <DropdownMenuRadioItem key={mode} value={mode} closeOnClick={false}>
+              <ModeIcon aria-hidden='true' className='size-4' />
+              {t('appearance.' + mode, {
+                defaultValue: mode[0].toUpperCase() + mode.slice(1),
+              })}
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuRadioGroup
+          value={preset}
+          onValueChange={(value) => {
+            const selected = themePresets.find((item) => item.id === value);
+            if (selected) setPreset(selected.id);
+          }}
+          aria-label={t('appearance.preset', { defaultValue: 'Theme' })}
+        >
+          <DropdownMenuLabel>
             {t('appearance.preset', { defaultValue: 'Theme' })}
-          </legend>
-          <RadioGroup
-            name={id + '-preset'}
-            value={preset}
-            onValueChange={(value) => {
-              const selected = themePresets.find((item) => item.id === value);
-              if (selected) setPreset(selected.id);
-            }}
-            aria-label={t('appearance.preset', { defaultValue: 'Theme' })}
-            className='grid-cols-2 gap-2.5'
-          >
-            {themePresets.map((item) => {
-              const isSelected = preset === item.id;
-              return (
-                <label
-                  key={item.id}
-                  className={cn(
-                    'group relative flex cursor-pointer flex-col rounded-xl border p-2 text-left transition-all select-none',
-                    isSelected
-                      ? 'border-primary ring-2 ring-primary/20 bg-primary/5 shadow-xs'
-                      : 'border-border hover:bg-muted/30',
-                  )}
-                >
-                  <RadioGroupItem
-                    value={item.id}
-                    className='absolute sr-only'
-                  />
-                  <div className='mb-2 h-16 w-full'>
-                    <div
-                      aria-hidden='true'
-                      data-theme={item.id}
-                      className='theme-preview relative flex h-full overflow-hidden rounded-lg border border-border bg-background shadow-2xs'
-                    >
-                      {/* Mini Sidebar */}
-                      <div className='flex w-6 flex-col gap-1 border-r border-sidebar-border/50 bg-sidebar p-1'>
-                        <div className='size-2 rounded-xs bg-sidebar-primary-foreground' />
-                        <div className='h-1 w-full rounded-xs bg-sidebar-foreground/30' />
-                        <div className='h-1 w-full rounded-xs bg-sidebar-foreground/20' />
-                      </div>
-                      {/* Mini Main Content Area */}
-                      <div className='flex flex-1 flex-col p-1.5'>
-                        <div className='mb-1 flex items-center justify-between border-b border-border/40 pb-1'>
-                          <div className='h-1 w-7 rounded-xs bg-foreground/70' />
-                          <div className='size-1.5 rounded-full bg-primary' />
-                        </div>
-                        <div className='flex flex-1 flex-col justify-between'>
-                          <div className='h-1 w-full rounded-xs bg-muted' />
-                          <div className='flex items-center justify-between pt-1'>
-                            <div className='h-1 w-6 rounded-xs bg-muted' />
-                            <div className='h-3 w-5 rounded-xs bg-primary shadow-xs' />
-                          </div>
-                        </div>
-                      </div>
-                    </div>
-                  </div>
-                  <div className='mt-auto flex min-h-5 items-center justify-between gap-2 px-0.5'>
-                    <span
-                      className={cn(
-                        'text-xs transition-colors',
-                        isSelected
-                          ? 'font-medium text-foreground'
-                          : 'text-muted-foreground group-hover:text-foreground',
-                      )}
-                    >
-                      {t(item.labelKey, {
-                        defaultValue:
-                          item.id.charAt(0).toUpperCase() + item.id.slice(1),
-                      })}
-                    </span>
-                    {isSelected && (
-                      <span
-                        aria-hidden='true'
-                        className='flex size-3.5 shrink-0 items-center justify-center rounded-full bg-primary text-primary-foreground'
-                      >
-                        <Check className='size-2 stroke-[3]' />
-                      </span>
-                    )}
-                  </div>
-                </label>
-              );
-            })}
-          </RadioGroup>
-        </fieldset>
-      </PopoverContent>
-    </Popover>
+          </DropdownMenuLabel>
+          {themePresets.map((item) => (
+            <DropdownMenuRadioItem
+              key={item.id}
+              value={item.id}
+              closeOnClick={false}
+            >
+              {t(item.labelKey, {
+                defaultValue:
+                  item.id.charAt(0).toUpperCase() + item.id.slice(1),
+              })}
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
   );
 }

package/config.example.yml

@@ -69,27 +69,56 @@ secrets:
     - version: 1
       key: replace-with-a-unique-secret
 
+# Optional shared sender for Auth, Users invitations and email notification channels. This example is commented out;
+# server/config/mailers.ts defaults to an empty configuration, so example values do not enable mail delivery.
+# `system` is only this template's sample name. Values are literal: ${NAME} is not expanded. The mapping explicitly
+# declares MAILERS_SYSTEM_* variables; inject the password through MAILERS_SYSTEM_PASSWORD.
+# mailers:
+#   default: system
+#   system:
+#     provider: smtp
+#     host: smtp.example.com
+#     port: 587
+#     secure: false
+#     auth:
+#       user: notifications@example.com
+#     from: App <notifications@example.com>
+
+# For Resend, use a separate entry with provider: resend, apiKey and from; do not mix provider fields:
+# mailers:
+#   default: system
+#   system:
+#     provider: resend
+#     apiKey: replace-with-the-api-key
+#     from: "Studio <notifications@example.com>"
+#
+# Equivalent SMTP .env example (use the Resend alternative below instead of its provider-specific SMTP fields):
+# MAILERS_DEFAULT=system
+# MAILERS_SYSTEM_PROVIDER=smtp
+# MAILERS_SYSTEM_HOST=smtp.example.com
+# MAILERS_SYSTEM_PORT=587
+# MAILERS_SYSTEM_SECURE=false
+# MAILERS_SYSTEM_USER=notifications@example.com
+# MAILERS_SYSTEM_PASSWORD=replace-with-the-password
+# MAILERS_SYSTEM_FROM=Studio <notifications@example.com>
+# MAILERS_SYSTEM_REPLY_TO=support@example.com
+# MAILERS_SYSTEM_ENABLED=true
+#
+# Resend .env alternative:
+# MAILERS_DEFAULT=system
+# MAILERS_SYSTEM_PROVIDER=resend
+# MAILERS_SYSTEM_API_KEY=replace-with-the-api-key
+# MAILERS_SYSTEM_FROM=Studio <notifications@example.com>
+# MAILERS_SYSTEM_REPLY_TO=support@example.com
+# MAILERS_SYSTEM_ENABLED=true
+
 auth:
-  # Authentication owns this sender; notification and mailbox configuration are independent.
-  # Set app.publicOrigin (or APP_PUBLIC_ORIGIN) before enabling automatic recovery.
+  # Set app.publicOrigin before explicitly enabling automatic password recovery.
   # passwordReset:
   #   enabled: true
   # email:
-  #   provider: smtp
-  #   host: smtp.example.com
-  #   port: 587
-  #   secure: false
-  #   auth:
-  #     user: noreply@example.com
-  #     pass: replace-with-the-smtp-password
-  #   from: App <noreply@example.com>
-  #   replyTo: support@example.com
-  # For Resend, replace the entire email block with these fields; do not mix SMTP fields:
-  # email:
-  #   provider: resend
-  #   apiKey: replace-with-the-resend-api-key
-  #   from: App <noreply@example.com>
-  # AUTH_EMAIL_PROVIDER/HOST/PORT/SECURE/USER/PASSWORD/FROM/REPLY_TO/API_KEY override auth.email.
+  #   mailer: system # omit to use mailers.default
+  # Existing inline auth.email and AUTH_EMAIL_* remain supported for compatibility.
   emailAndPassword:
     enabled: true
     autoSignIn: false
@@ -102,21 +131,11 @@ notification:
     inbox:
       type: in-app
 
-    # Uncomment and configure independent email Channels.
-    # Values are read as written: ${NAME} is not expanded. To take a secret from the environment instead, map a
-    # variable onto its path in env of server/config/notification.ts, such as SMTP_PASSWORD.
+    # Configuring mailers alone does not create a notification channel.
     # system-email:
-    #   type: smtp
-    #   host: smtp.example.com
-    #   port: 587
-    #   auth:
-    #     user: notifications@example.com
-    #     pass: replace-with-the-smtp-password
-    #   from: notifications@example.com
-    # marketing-email:
-    #   type: resend
-    #   apiKey: replace-with-the-resend-api-key
-    #   from: marketing@example.com
+    #   type: email
+    #   mailer: system # omit to use mailers.default
+    # Legacy type: smtp/resend inline channels and SMTP_PASSWORD/RESEND_API_KEY remain supported.
 
     # ops-feishu:
     #   type: feishu-webhook

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nocobase/app-template-default",
   "displayName": "Default Template",
-  "version": "1.0.0-beta.86",
+  "version": "1.0.0-beta.87",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -9,7 +9,7 @@
   },
   "nocobase": {
     "templateKind": "app",
-    "defaultTemplateVersion": "1.0.0-beta.86"
+    "defaultTemplateVersion": "1.0.0-beta.87"
   },
   "devDependencies": {
     "@ai-sdk/react": "4.0.131",
@@ -74,10 +74,10 @@
     "elkjs": "^0.10.2",
     "@types/jsdom": "^30.0.0",
     "@noble/hashes": "2.3.0",
-    "@nocobase/app-client": "^4.0.0-beta.6",
+    "@nocobase/app-client": "^4.0.0-beta.7",
     "@nocobase/app-plugin-template-print": "0.0.2-beta.2",
-    "@nocobase/app-skills": "0.1.0-beta.56",
-    "@nocobase/app-testing": "0.1.0-beta.7",
+    "@nocobase/app-skills": "0.1.0-beta.58",
+    "@nocobase/app-testing": "0.1.0-beta.8",
     "@nocobase/app-websocket": "^0.1.0-beta.1",
     "@nocobase/dev-config": "0.1.0-beta.25",
     "@nocobase/drive": "^0.1.0-beta.7",
@@ -143,39 +143,39 @@
     "better-auth": "1.7.5",
     "hono": "^4.13.2",
     "@nocobase/concurrency": "^0.1.0-beta.1",
-    "@nocobase/app-plugin-concurrency": "^0.1.0-beta.1",
-    "@nocobase/app-plugin-agents": "^2.0.0-beta.1",
-    "@nocobase/app-plugin-api-keys": "^1.0.0-beta.20",
-    "@nocobase/app-plugin-authentication": "^2.0.0-beta.17",
-    "@nocobase/app-plugin-authorization": "^1.0.0-beta.34",
-    "@nocobase/app-plugin-database-explorer": "^1.0.0-beta.18",
-    "@nocobase/app-plugin-file": "^1.0.0-beta.28",
-    "@nocobase/app-plugin-foundation": "^0.1.0-beta.11",
-    "@nocobase/app-plugin-i18n": "^1.0.0-beta.19",
-    "@nocobase/app-plugin-knowledge": "^0.1.0-beta.16",
-    "@nocobase/app-plugin-mail": "^1.0.0-beta.19",
-    "@nocobase/app-plugin-notification": "^2.0.0-beta.3",
-    "@nocobase/app-plugin-notification-in-app": "^2.0.0-beta.1",
-    "@nocobase/app-plugin-notification-providers": "^1.0.0-beta.17",
-    "@nocobase/app-plugin-scheduler": "^1.0.0-beta.22",
-    "@nocobase/app-plugin-users": "^2.0.0-beta.12",
-    "@nocobase/app-server": "^4.0.0-beta.0",
+    "@nocobase/app-plugin-concurrency": "^0.1.0-beta.2",
+    "@nocobase/app-plugin-agents": "^2.0.0-beta.3",
+    "@nocobase/app-plugin-api-keys": "^1.0.0-beta.21",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.18",
+    "@nocobase/app-plugin-authorization": "^1.0.0-beta.35",
+    "@nocobase/app-plugin-database-explorer": "^1.0.0-beta.19",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.29",
+    "@nocobase/app-plugin-foundation": "^0.1.0-beta.13",
+    "@nocobase/app-plugin-i18n": "^1.0.0-beta.20",
+    "@nocobase/app-plugin-knowledge": "^0.1.0-beta.17",
+    "@nocobase/app-plugin-mail": "^1.0.0-beta.21",
+    "@nocobase/app-plugin-notification": "^2.0.0-beta.4",
+    "@nocobase/app-plugin-notification-in-app": "^2.0.0-beta.2",
+    "@nocobase/app-plugin-notification-providers": "^1.0.0-beta.18",
+    "@nocobase/app-plugin-scheduler": "^1.0.0-beta.23",
+    "@nocobase/app-plugin-users": "^2.0.0-beta.14",
+    "@nocobase/app-server": "^5.0.0-beta.0",
     "@nocobase/config": "^0.1.0-beta.3",
-    "@nocobase/db": "^1.0.0-beta.24",
+    "@nocobase/db": "^1.0.0-beta.25",
     "@nocobase/db-sqlite": "^0.1.0-beta.6",
     "@nocobase/service-provider": "^0.0.2-beta.2",
     "@nocobase/snowflake": "^1.0.0-beta.4",
-    "@nocobase/app-plugin-authz-default-access": "^1.0.0-beta.18",
-    "@nocobase/app-plugin-authz-sharing-rules": "^1.0.0-beta.17",
-    "@nocobase/app-plugin-authz-restriction-rules": "^1.0.0-beta.16",
+    "@nocobase/app-plugin-authz-default-access": "^1.0.0-beta.19",
+    "@nocobase/app-plugin-authz-sharing-rules": "^1.0.0-beta.18",
+    "@nocobase/app-plugin-authz-restriction-rules": "^1.0.0-beta.17",
     "@nocobase/authorization": "^1.0.0-beta.16",
     "@nocobase/queue": "^1.0.0-beta.10",
     "@nocobase/jobs": "^1.0.0-beta.5",
     "@nocobase/lifecycle": "^0.1.0-beta.4",
     "@nocobase/i18n": "^2.0.0-beta.1",
-    "@nocobase/caching": "^0.1.0-beta.3",
+    "@nocobase/caching": "^1.0.0-beta.4",
     "@nocobase/repository-input": "^0.1.0-beta.3",
-    "@nocobase/app-cli": "^1.0.0-beta.31",
+    "@nocobase/app-cli": "^1.0.0-beta.32",
     "@nocobase/realtime": "^1.0.0-beta.0"
   },
   "description": "NocoBase 3 application template with the standard product capabilities.",

package/server/config/auth.ts

@@ -12,7 +12,7 @@ import { bearer, deviceAuthorization, username } from 'better-auth/plugins';
  */
 const CLI_CLIENT_IDS: readonly string[] = ['nocobase-cli'];
 
-// defineAuthConfig supplies AUTH_EMAIL_* mappings and validates the private auth.email sender.
+// Use mailers for shared sending; defineAuthConfig retains AUTH_EMAIL_* for legacy inline senders.
 // Automatic recovery requires passwordReset.enabled: true; leave the switch absent for custom callback compatibility.
 const auth: AppConfigFactory<AuthConfig> = defineAuthConfig({
   defaults: {

package/server/config/index.ts

@@ -1,3 +1,4 @@
+import mailers from './mailers.js';
 import {
   defaultAppConfigs,
   type AppConfigFactory,
@@ -26,6 +27,7 @@ import users from './users.js';
 import knowledge from './knowledge.js';
 
 const defaultConfigs: AppConfigFactory<{
+  mailers: ReturnType<typeof mailers>;
   auth: ReturnType<typeof auth>;
   authorization: ReturnType<typeof authorization>;
   notification: ReturnType<typeof notification>;
@@ -49,6 +51,7 @@ const defaultConfigs: AppConfigFactory<{
   users: ReturnType<typeof users>;
   knowledge: ReturnType<typeof knowledge>;
 }> = defaultAppConfigs({
+  mailers,
   auth,
   authorization,
   notification,

package/server/config/mailers.ts

@@ -0,0 +1,11 @@
+import {
+  defineMailersConfig,
+  mailerEnvironment,
+} from '@nocobase/app-server/mailers/config';
+
+// These mappings are explicit and discoverable through `nocobase config env`.
+// An empty section leaves email unavailable until an operator configures a named service.
+export default defineMailersConfig({
+  defaults: {},
+  env: { ...mailerEnvironment('system', 'MAILERS_SYSTEM') },
+});

package/tests/client/client-shell.test.tsx

@@ -83,7 +83,9 @@ describe('application shell', () => {
     expect(
       await screen.findByRole('button', { name: 'Open account menu' }),
     ).not.toHaveAttribute('title');
-    expect(screen.getByRole('button', { name: 'Appearance' })).toBeVisible();
+    expect(
+      screen.queryByRole('button', { name: 'Theme' }),
+    ).not.toBeInTheDocument();
     expect(
       screen.queryByRole('link', { name: 'Settings' }),
     ).not.toBeInTheDocument();
@@ -261,7 +263,9 @@ describe('application shell', () => {
     expect(
       screen.queryByRole('navigation', { name: 'Application navigation' }),
     ).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: 'Appearance' })).toBeVisible();
+    expect(
+      screen.queryByRole('button', { name: 'Theme' }),
+    ).not.toBeInTheDocument();
   });
 });
 

package/tests/client/client-theme.test.tsx

@@ -16,10 +16,27 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import {
   AppThemeProvider,
-  ThemeSettings,
+  ThemeSettings as ThemeMenu,
   useTheme,
 } from '../../client/theme/index.ts';
 
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+} from '../../client/components/ui/dropdown-menu';
+
+function ThemeSettings(): ReactElement {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger>Account</DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <ThemeMenu />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
 /**
  * Renders the client configuration the server would, mounted at `/crm` so the theme's storage keys are
  * `nocobase:crm:*`. It replaces any block already on the page, since the client reads the first one it finds.
@@ -38,19 +55,65 @@ function renderClientConfig(
   document.head.append(element);
 }
 
-/**
- * Opens the appearance popover from the keyboard. Its trigger opens on hover, and a pointer press landing more than
- * Base UI's 500 ms patient-click threshold after that, as on a loaded runner, closes it again.
- */
-async function openAppearance(name = 'Appearance'): Promise<void> {
-  act(() => screen.getByRole('button', { name }).focus());
+/** Opens the account menu and its Theme submenu using the keyboard. */
+async function openTheme(name = 'Theme'): Promise<void> {
+  act(() => screen.getByRole('button', { name: 'Account' }).focus());
   await userEvent.keyboard('{Enter}');
+  act(() => screen.getByRole('menuitem', { name }).focus());
+  await userEvent.keyboard('{ArrowRight}');
 }
 
 describe('app client theme', () => {
   it.each([
-    ['en-US', 'Appearance', 'Spacious'],
-    ['zh-CN', '外观', '宽松'],
+    ['Light', 'light', 'Compact', 'compact'],
+    ['Dark', 'dark', 'Compact', 'compact'],
+    ['System', 'system', 'Compact', 'compact'],
+    ['Light', 'light', 'Default', 'default'],
+    ['Dark', 'dark', 'Default', 'default'],
+    ['System', 'system', 'Default', 'default'],
+  ])(
+    'saves and restores %s mode with %s / %s density',
+    async (modeLabel, mode, presetLabel, preset) => {
+      const settings = (
+        <AppThemeProvider>
+          <ThemeSettings />
+        </AppThemeProvider>
+      );
+      const view = render(settings);
+      await openTheme();
+      await userEvent.click(
+        screen.getByRole('menuitemradio', { name: modeLabel }),
+      );
+      await userEvent.click(
+        screen.getByRole('menuitemradio', { name: presetLabel }),
+      );
+      expect(localStorage.getItem('nocobase:crm:theme:color-scheme')).toBe(
+        mode,
+      );
+      expect(localStorage.getItem('nocobase:crm:theme:preset')).toBe(preset);
+      view.unmount();
+      initializeTheme(
+        '/crm/',
+        themePresets.map(({ id }) => id),
+      );
+      render(settings);
+      await openTheme();
+      expect(document.documentElement).toHaveClass(
+        mode === 'light' ? 'light' : 'dark',
+      );
+      expect(document.documentElement).toHaveAttribute('data-theme', preset);
+      expect(
+        screen.getByRole('menuitemradio', { name: modeLabel }),
+      ).toHaveAttribute('aria-checked', 'true');
+      expect(
+        screen.getByRole('menuitemradio', { name: presetLabel }),
+      ).toHaveAttribute('aria-checked', 'true');
+    },
+  );
+
+  it.each([
+    ['en-US', 'Theme', 'Spacious'],
+    ['zh-CN', '主题', '宽松'],
   ])(
     'labels the default preset without implying default selection (%s)',
     async (locale, appearance, label) => {
@@ -68,28 +131,32 @@ describe('app client theme', () => {
           </AppThemeProvider>
         </I18nProvider>,
       );
-      await openAppearance(appearance);
-      const option = await screen.findByRole('radio', { name: label });
+      await openTheme(appearance);
+      const option = await screen.findByRole('menuitemradio', { name: label });
       await userEvent.click(option);
-      expect(option).toBeChecked();
+      expect(option).toHaveAttribute('aria-checked', 'true');
       expect(localStorage.getItem('nocobase:crm:theme:preset')).toBe('default');
     },
   );
 
-  it('changes presets with arrow keys and returns focus on Escape', async () => {
+  it('selects a preset by keyboard and returns focus on Escape', async () => {
     render(
       <AppThemeProvider>
         <ThemeSettings />
       </AppThemeProvider>,
     );
-    await openAppearance();
-    const compact = await screen.findByRole('radio', { name: 'Compact' });
+    await openTheme();
+    const compact = await screen.findByRole('menuitemradio', {
+      name: 'Compact',
+    });
     act(() => compact.focus());
-    await userEvent.keyboard('{ArrowRight}');
-    expect(screen.getByRole('radio', { name: 'Default' })).toBeChecked();
+    await userEvent.keyboard('{ArrowDown}{Enter}');
+    expect(
+      screen.getByRole('menuitemradio', { name: 'Default' }),
+    ).toHaveAttribute('aria-checked', 'true');
     expect(localStorage.getItem('nocobase:crm:theme:preset')).toBe('default');
     await userEvent.keyboard('{Escape}');
-    expect(screen.getByRole('button', { name: 'Appearance' })).toHaveFocus();
+    expect(screen.getByRole('menuitem', { name: 'Theme' })).toHaveFocus();
   });
 
   it('falls back from the removed Ant Design preset without changing mode', async () => {
@@ -100,11 +167,13 @@ describe('app client theme', () => {
         <ThemeSettings />
       </AppThemeProvider>,
     );
-    await openAppearance();
+    await openTheme();
     expect(
-      screen.queryByRole('radio', { name: 'Ant-design' }),
+      screen.queryByRole('menuitemradio', { name: 'Ant-design' }),
     ).not.toBeInTheDocument();
-    expect(await screen.findByRole('radio', { name: 'Compact' })).toBeChecked();
+    expect(
+      await screen.findByRole('menuitemradio', { name: 'Compact' }),
+    ).toHaveAttribute('aria-checked', 'true');
     expect(document.documentElement).toHaveAttribute('data-theme', 'compact');
     expect(document.documentElement).toHaveClass('light');
   });
@@ -115,13 +184,15 @@ describe('app client theme', () => {
         <ThemeSettings />
       </AppThemeProvider>,
     );
-    await openAppearance();
+    await openTheme();
     expect(
-      screen.queryByRole('radio', { name: 'Ocean' }),
+      screen.queryByRole('menuitemradio', { name: 'Ocean' }),
     ).not.toBeInTheDocument();
-    expect(await screen.findByRole('radio', { name: 'Compact' })).toBeChecked();
     expect(
-      await screen.findByRole('radio', { name: 'Default' }),
+      await screen.findByRole('menuitemradio', { name: 'Compact' }),
+    ).toHaveAttribute('aria-checked', 'true');
+    expect(
+      await screen.findByRole('menuitemradio', { name: 'Default' }),
     ).toBeInTheDocument();
     expect(document.documentElement).toHaveAttribute('data-theme', 'compact');
   });
@@ -218,12 +289,12 @@ describe('app client theme', () => {
           <ThemeSettings />
         </AppThemeProvider>,
       );
-      await openAppearance();
+      await openTheme();
       expect(
-        await screen.findByRole('radio', {
+        await screen.findByRole('menuitemradio', {
           name: expected === 'compact' ? 'Compact' : 'Default',
         }),
-      ).toBeChecked();
+      ).toHaveAttribute('aria-checked', 'true');
       expect(document.documentElement).toHaveAttribute('data-theme', expected);
       expect(localStorage.getItem(key)).toBe(saved ?? null);
     },
@@ -334,14 +405,16 @@ describe('app client theme', () => {
       </AppThemeProvider>,
     );
 
-    await openAppearance();
+    await openTheme();
     await userEvent.click(
-      await screen.findByRole('radio', { name: 'Compact' }),
+      await screen.findByRole('menuitemradio', { name: 'Compact' }),
     );
     expect(document.documentElement).toHaveAttribute('data-theme', 'compact');
     expect(document.documentElement).toHaveClass('dark');
     expect(localStorage.getItem('nocobase:crm:theme:preset')).toBe('compact');
-    await userEvent.click(await screen.findByRole('radio', { name: 'Light' }));
+    await userEvent.click(
+      await screen.findByRole('menuitemradio', { name: 'Light' }),
+    );
     expect(document.documentElement).toHaveClass('light');
     expect(document.documentElement).toHaveAttribute('data-theme', 'compact');
     fireEvent(
@@ -359,10 +432,12 @@ describe('app client theme', () => {
         newValue: 'default',
       }),
     );
-    expect(await screen.findByRole('radio', { name: 'Default' })).toBeChecked();
+    expect(
+      await screen.findByRole('menuitemradio', { name: 'Default' }),
+    ).toHaveAttribute('aria-checked', 'true');
     await userEvent.keyboard('{Escape}');
     await waitFor(() =>
-      expect(screen.getByRole('button', { name: 'Appearance' })).toHaveFocus(),
+      expect(screen.getByRole('menuitem', { name: 'Theme' })).toHaveFocus(),
     );
   });
 
@@ -395,11 +470,13 @@ describe('app client theme', () => {
         <ThemeSettings />
       </AppThemeProvider>,
     );
-    await openAppearance();
+    await openTheme();
+    await userEvent.click(
+      await screen.findByRole('menuitemradio', { name: 'Default' }),
+    );
     await userEvent.click(
-      await screen.findByRole('radio', { name: 'Default' }),
+      await screen.findByRole('menuitemradio', { name: 'Light' }),
     );
-    await userEvent.click(await screen.findByRole('radio', { name: 'Light' }));
     expect(document.documentElement).toHaveAttribute('data-theme', 'default');
     expect(document.documentElement).toHaveClass('light');
   });
@@ -410,9 +487,9 @@ describe('app client theme', () => {
         <ThemeSettings />
       </AppThemeProvider>,
     );
-    await openAppearance();
+    await openTheme();
     await userEvent.click(
-      await screen.findByRole('radio', { name: 'Default' }),
+      await screen.findByRole('menuitemradio', { name: 'Default' }),
     );
     fireEvent(
       window,
@@ -438,7 +515,9 @@ describe('app client theme', () => {
       }),
     );
     await waitFor(() => expect(document.documentElement).toHaveClass('dark'));
-    expect(await screen.findByRole('radio', { name: 'System' })).toBeChecked();
+    expect(
+      await screen.findByRole('menuitemradio', { name: 'System' }),
+    ).toHaveAttribute('aria-checked', 'true');
   });
 });
 

package/tests/client/header-hover.test.tsx

@@ -2,7 +2,7 @@ import { fireEvent, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { afterEach, beforeEach, expect, it, vi } from 'vitest';
 import { AppThemeProvider } from '../../client/theme/theme-provider';
-import { ThemeSettings } from '../../client/theme/theme-settings';
+import { HeaderActions } from '../../client/layouts/components/header-actions';
 import { UserMenu } from '../../client/layouts/components/user-menu';
 
 import { renderAuthenticatedClient } from '../helpers/authenticated-client.js';
@@ -24,10 +24,7 @@ afterEach(() => {
   document.documentElement.removeAttribute('data-theme');
 });
 
-const panels = [
-  ['Appearance', ThemeSettings, 'dialog'],
-  ['Open account menu', UserMenu, 'menu'],
-] as const;
+const panels = [['Open account menu', UserMenu, 'menu']] as const;
 
 it.each(panels)(
   'opens and closes %s on hover',
@@ -75,3 +72,34 @@ it.each(panels)(
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   },
 );
+
+it('offers appearance only inside the account menu with keyboard selection', async () => {
+  const user = userEvent.setup();
+  await renderAuthenticatedClient(
+    <AppThemeProvider>
+      <HeaderActions />
+    </AppThemeProvider>,
+  );
+  expect(
+    screen.queryByRole('button', { name: 'Theme' }),
+  ).not.toBeInTheDocument();
+  await user.tab();
+  await user.keyboard('{Enter}');
+  const appearance = screen.getByRole('menuitem', { name: 'Theme' });
+  appearance.focus();
+  await user.keyboard('{ArrowRight}');
+  expect(screen.getAllByRole('menuitemradio')).toHaveLength(5);
+  await user.keyboard('{ArrowDown}{Enter}');
+  expect(document.documentElement).toHaveClass('dark');
+  expect(screen.getByRole('menuitemradio', { name: 'Dark' })).toHaveAttribute(
+    'aria-checked',
+    'true',
+  );
+  await user.keyboard('{Escape}');
+  expect(appearance).toHaveFocus();
+  expect(screen.getByRole('menuitem', { name: 'Sign out' })).toBeVisible();
+  await user.keyboard('{Escape}');
+  expect(
+    screen.getByRole('button', { name: 'Open account menu' }),
+  ).toHaveFocus();
+});

package/tests/client/standalone-page-layout.test.tsx

@@ -0,0 +1,45 @@
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter, Route, Routes } from 'react-router';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+import { StandalonePageLayout } from '../../client/routing/standalone-page-layout.js';
+import { AppThemeProvider } from '../../client/theme/index.js';
+
+beforeEach(() => {
+  // jsdom does not implement the media queries used by the real theme provider.
+  vi.stubGlobal('matchMedia', () => ({
+    matches: false,
+    addListener() {},
+    removeListener() {},
+  }));
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.documentElement.removeAttribute('class');
+  document.documentElement.removeAttribute('style');
+  document.documentElement.removeAttribute('data-theme');
+});
+
+it.each(['/login', '/device'])(
+  'renders standalone content at %s without an account menu',
+  (path) => {
+    render(
+      <AppThemeProvider>
+        <MemoryRouter initialEntries={[path]}>
+          <Routes>
+            <Route element={<StandalonePageLayout />}>
+              <Route path={path} element={<h1>Standalone page</h1>} />
+            </Route>
+          </Routes>
+        </MemoryRouter>
+      </AppThemeProvider>,
+    );
+    expect(
+      screen.getByRole('heading', { name: 'Standalone page' }),
+    ).toBeVisible();
+    expect(
+      screen.queryByRole('button', { name: 'Theme' }),
+    ).not.toBeInTheDocument();
+  },
+);

package/tests/client/user-menu-sign-out.test.tsx

@@ -1,9 +1,19 @@
+import { AppThemeProvider } from '../../client/theme/index.js';
 import { act, fireEvent, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { UserMenu } from '../../client/layouts/components/user-menu.tsx';
 import { renderAuthenticatedClient } from '../helpers/authenticated-client.js';
 
+// jsdom has no media queries; the real account menu includes the theme provider.
+beforeEach(() => {
+  vi.stubGlobal('matchMedia', () => ({
+    matches: false,
+    addListener() {},
+    removeListener() {},
+  }));
+});
+
 async function openAccountMenu(): Promise<void> {
   act(() => screen.getByRole('button', { name: 'Open account menu' }).focus());
   await userEvent.keyboard('{Enter}');
@@ -15,7 +25,11 @@ async function signOutFromMenu() {
 
 describe('account menu sign out', () => {
   it('ends the server session and refreshes the displayed identity', async () => {
-    const view = await renderAuthenticatedClient(<UserMenu />);
+    const view = await renderAuthenticatedClient(
+      <AppThemeProvider>
+        <UserMenu />
+      </AppThemeProvider>,
+    );
     await signOutFromMenu();
     await waitFor(() => expect(view.identity().session).toBeNull());
     expect(
@@ -26,13 +40,18 @@ describe('account menu sign out', () => {
     expect(screen.queryByText(view.session.user.email)).not.toBeInTheDocument();
   });
   it('reports a rejected origin without pretending the session ended', async () => {
-    const view = await renderAuthenticatedClient(<UserMenu />, {
-      beforeRequest(request) {
-        // Exercise the real origin guard and error resolver, not a fabricated authentication result.
-        if (request.url.endsWith('/sign-out'))
-          request.headers.set('origin', 'https://untrusted.example');
+    const view = await renderAuthenticatedClient(
+      <AppThemeProvider>
+        <UserMenu />
+      </AppThemeProvider>,
+      {
+        beforeRequest(request) {
+          // Exercise the real origin guard and error resolver, not a fabricated authentication result.
+          if (request.url.endsWith('/sign-out'))
+            request.headers.set('origin', 'https://untrusted.example');
+        },
       },
-    });
+    );
     await signOutFromMenu();
     await waitFor(() => expect(view.toasts()).toHaveLength(1));
     expect(view.toasts()[0]).toMatchObject({
@@ -50,13 +69,18 @@ describe('account menu sign out', () => {
   });
   it('reports a network failure and successfully retries sign-out', async () => {
     let offline = true;
-    const view = await renderAuthenticatedClient(<UserMenu />, {
-      beforeRequest(request) {
-        // Network loss cannot be produced by the in-process server.
-        if (offline && request.url.endsWith('/sign-out'))
-          throw new TypeError('Failed to fetch');
+    const view = await renderAuthenticatedClient(
+      <AppThemeProvider>
+        <UserMenu />
+      </AppThemeProvider>,
+      {
+        beforeRequest(request) {
+          // Network loss cannot be produced by the in-process server.
+          if (offline && request.url.endsWith('/sign-out'))
+            throw new TypeError('Failed to fetch');
+        },
       },
-    });
+    );
     await signOutFromMenu();
     await waitFor(() => expect(view.toasts()).toHaveLength(1));
     expect(view.toasts()[0]).toMatchObject({

package/tests/client/user-menu.test.tsx

@@ -0,0 +1,65 @@
+import { AppThemeProvider } from '../../client/theme/index.js';
+import { act, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+import { UserMenu } from '../../client/layouts/components/user-menu.js';
+import { renderAuthenticatedClient } from '../helpers/authenticated-client.js';
+
+// jsdom has no media queries; the real account menu includes the theme provider.
+beforeEach(() => {
+  vi.stubGlobal('matchMedia', () => ({
+    matches: false,
+    addListener() {},
+    removeListener() {},
+  }));
+});
+
+it('uses CJK name endings in the avatar while retaining the full account name and picture', async () => {
+  const view = await renderAuthenticatedClient(
+    <AppThemeProvider>
+      <UserMenu />
+    </AppThemeProvider>,
+  );
+  const user = userEvent.setup();
+  const trigger = screen.getByRole('button', { name: 'Open account menu' });
+  await user.tab();
+  for (const [name, expected] of [
+    ['周建国', '建国'],
+    ['欧阳娜娜', '娜娜'],
+    ['李雷', '李雷'],
+    ['周 建国', '建国'],
+    ['Li Lei', 'LL'],
+    ['周', '周'],
+  ] as const) {
+    await act(async () => {
+      const response = await view.identity().client.updateUser({ name });
+      expect(response.error).toBeNull();
+      await view.identity().refresh();
+    });
+    expect(trigger).toHaveTextContent(expected);
+    await user.keyboard('{Enter}');
+    expect(
+      within(screen.getByRole('menu')).getByText(name, { exact: true }),
+    ).toBeVisible();
+    await user.keyboard('{Escape}');
+  }
+  await act(async () => {
+    const response = await view.identity().client.updateUser({ name: '' });
+    expect(response.error).toBeNull();
+    await view.identity().refresh();
+  });
+  expect(trigger).toHaveTextContent(view.session.user.email[0]!.toUpperCase());
+  await act(async () => {
+    const response = await view
+      .identity()
+      .client.updateUser({ image: 'https://example.test/avatar.png' });
+    expect(response.error).toBeNull();
+    await view.identity().refresh();
+  });
+  expect(trigger.querySelector('img')).toHaveAttribute(
+    'src',
+    'https://example.test/avatar.png',
+  );
+  expect(trigger).not.toHaveTextContent('周');
+});

package/tests/fixtures/theme-tokens.tsx

@@ -1,3 +1,8 @@
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+} from '../../client/components/ui/dropdown-menu';
 import {
   createAppSidebarPreferenceStore,
   SidebarPreferenceProvider,
@@ -35,7 +40,14 @@ export default function Fixture() {
           </AppSidebar>
           <main className='min-w-0 flex-1 space-y-6 overflow-y-auto p-6'>
             <div className='flex flex-wrap gap-2'>
-              <ThemeSettings />
+              <DropdownMenu>
+                <DropdownMenuTrigger render={<Button />}>
+                  Account
+                </DropdownMenuTrigger>
+                <DropdownMenuContent>
+                  <ThemeSettings />
+                </DropdownMenuContent>
+              </DropdownMenu>
               <AppSidebarToggle />
             </div>
             <h1 className='text-3xl'>Theme tokens · 主题样式</h1>

package/tests/server/auth-email-config.test.ts

@@ -10,6 +10,7 @@ import {
   buildVariablesManifest,
 } from '@nocobase/app-server/config';
 import auth from '../../server/config/auth.js';
+import mailers from '../../server/config/mailers.js';
 
 it('inherits private authentication sender mappings without changing other mail consumers', async () => {
   const defaults = defaultAppConfigs({ auth });
@@ -50,30 +51,63 @@ it('inherits private authentication sender mappings without changing other mail
   ).toBe(true);
 });
 
-it('ships separate, valid SMTP and Resend authentication examples', async () => {
+it('ships a valid shared mailer example with private mapped credentials', async () => {
   const example = await readFile(
     new URL('../../config.example.yml', import.meta.url),
     'utf8',
   );
-  const blocks = [...example.matchAll(/^ {2}# email:\n(?: {2}# {3}.*\n)+/gm)];
-  expect(blocks).toHaveLength(2);
-  const directory = await mkdtemp(
-    path.join(os.tmpdir(), 'auth-email-example-'),
-  );
+  const block = example.match(/^# mailers:\n(?:#.*\n)+/m)?.[0];
+  expect(block).toBeTruthy();
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'mailers-example-'));
   try {
-    for (const block of blocks) {
-      const text = 'auth:\n' + block[0].replace(/^ {2}# /gm, '  ');
-      const file = path.join(directory, 'config.yml');
-      await writeFile(file, text);
-      const config = new AppConfig().loadFile(file);
-      await config.loadAll();
-      const defaults = defaultAppConfigs({ auth });
-      config.mergeDefaults(defaults({} as never));
-      config.defineSections(defaults.sections!);
-      expect(await config.validate()).toEqual([]);
-    }
+    const file = path.join(directory, 'config.yml');
+    await writeFile(file, block!.replace(/^# ?/gm, ''));
+    const config = new AppConfig().loadFile(file);
+    await config.loadAll();
+    const defaults = defaultAppConfigs({ auth, mailers });
+    config.mergeDefaults(defaults({} as never));
+    config.defineSections(defaults.sections!);
+    await config.loadSectionEnvironment({
+      MAILERS_SYSTEM_PASSWORD: 'synthetic-password',
+    });
+    expect(await config.validate()).toEqual([]);
+    expect(config.get('mailers.default')).toBe('system');
+    expect(config.get('mailers.system.auth.pass')).toBe('synthetic-password');
+    expect(JSON.stringify(config.publicValues())).not.toContain(
+      'synthetic-password',
+    );
+    expect(config.get('auth.passwordReset.enabled')).toBeUndefined();
   } finally {
     await rm(directory, { recursive: true, force: true });
   }
   expect(example).not.toContain('emailChannel:');
 });
+
+it('accepts an entirely environment-configured shared sender without enabling recovery', async () => {
+  const config = new AppConfig();
+  await config.loadAll();
+  const defaults = defaultAppConfigs({ auth, mailers });
+  config.mergeDefaults(defaults({} as never));
+  config.defineSections(defaults.sections!);
+  await config.loadSectionEnvironment({
+    MAILERS_DEFAULT: 'system',
+    MAILERS_SYSTEM_PROVIDER: 'smtp',
+    MAILERS_SYSTEM_HOST: 'localhost',
+    MAILERS_SYSTEM_PORT: '2525',
+    MAILERS_SYSTEM_SECURE: 'false',
+  });
+  expect(await config.validate()).toEqual([]);
+  expect(config.get('mailers.system')).toMatchObject({
+    provider: 'smtp',
+    port: 2525,
+    secure: false,
+  });
+  expect(config.get('auth.passwordReset.enabled')).toBeUndefined();
+  expect(config.environmentVariableMappings()).toMatchObject({
+    MAILERS_DEFAULT: { path: 'mailers.default' },
+    MAILERS_SYSTEM_PASSWORD: {
+      path: 'mailers.system.auth.pass',
+      secret: true,
+    },
+  });
+});