Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🎨 fix: Fall Back From an Invalid Theme in librechat.yaml Instead of Exiting (#16462)
Marco Beretta15142ab90745
diff --git a/client/src/Providers/DeploymentTheme.tsx b/client/src/Providers/DeploymentTheme.tsxindex fadafaeb2b..d34b310417 100644--- a/client/src/Providers/DeploymentTheme.tsx+++ b/client/src/Providers/DeploymentTheme.tsx@@ -8,8 +8,8 @@ import {createContext,useLayoutEffect,} from 'react';-import { QueryKeys } from 'librechat-data-provider';import { notifyManager, useQueryClient } from '@tanstack/react-query';+import { QueryKeys, isBundledThemeName } from 'librechat-data-provider';import {ThemeProvider,clickHouseTheme,@@ -17,15 +17,15 @@ import {fromLegacyTheme,validateThemeDefinition,} from '@librechat/client';+import type { TInterfaceConfig, BundledThemeName } from 'librechat-data-provider';import type { IThemeRGB, ThemeDefinition } from '@librechat/client';-import type { TInterfaceConfig } from 'librechat-data-provider';import type { ComponentProps } from 'react';import { getThemeFromEnv } from '~/utils/getThemeFromEnv';import { useGetStartupConfig } from '~/data-provider';type DeploymentThemeValue = TInterfaceConfig['theme'];-const bundledThemes: Readonly<Record<string, ThemeDefinition>> = {+const bundledThemes: Readonly<Record<BundledThemeName, ThemeDefinition>> = {librechat: libreChatTheme,clickhouse: clickHouseTheme,};@@ -41,7 +41,7 @@ export function resolveDeploymentTheme(theme: DeploymentThemeValue): ThemeDefini}if (typeof theme === 'string') {- const definition = Object.hasOwn(bundledThemes, theme) ? bundledThemes[theme] : undefined;+ const definition = isBundledThemeName(theme) ? bundledThemes[theme] : undefined;if (!definition) {console.warn(`[DeploymentTheme] Ignoring unknown interface.theme "${theme}"`);}diff --git a/e2e/specs/mock/scenarios/yaml-theme-fallback.spec.ts b/e2e/specs/mock/scenarios/yaml-theme-fallback.spec.tsnew file mode 100644index 0000000000..66c07213b8--- /dev/null+++ b/e2e/specs/mock/scenarios/yaml-theme-fallback.spec.ts@@ -0,0 +1,129 @@+import { resolve } from 'node:path';+import { expect, test } from '@playwright/test';+import { inOneProject, repoRoot, run } from './lint.helpers';++/**+ * A mistake in `interface.theme` used to fail the whole librechat.yaml and stop the server. The+ * config loader that `/api` wires up now drops only the theme, names each problem by its path, and+ * loads everything else. The mock lane serves one shared yaml, so these load their own fixtures+ * through that same loader in a child process, the way the server does at startup and on reload.+ */+test.describe.configure({ timeout: 120_000 });++const fixtures = resolve(repoRoot, 'packages/api/src/app/__fixtures__/theme');+const RESULT = '__THEME_SCENARIO_RESULT__';+/** The logger colours its console output. */+const ANSI_COLOR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');++const loadScript = `+const load = require('./server/services/Config/loadCustomConfig');+process.exit = (code) => {+ console.log('${RESULT}' + JSON.stringify({ exited: code }));+ process.reallyExit(0);+};+load(false, { mode: process.argv[1] }).then(+ (config) => {+ console.log('${RESULT}' + JSON.stringify({ interface: config && config.interface }));+ process.reallyExit(0);+ },+ (error) => {+ console.log('${RESULT}' + JSON.stringify({ rejected: error.name }));+ process.reallyExit(0);+ },+);+`;++type LoadOutcome = {+ interface?: { theme?: unknown; modelSelect?: boolean };+ exited?: number;+ rejected?: string;+};++function loadFixture(name: string, mode: 'startup' | 'reload' = 'startup') {+ process.env.CONFIG_PATH = resolve(fixtures, `${name}.yaml`);+ const result = run('node', ['-e', loadScript, mode], { cwd: resolve(repoRoot, 'api') });+ const log = result.output.replace(ANSI_COLOR, '');+ const line = log.split('\n').find((entry) => entry.startsWith(RESULT));+ if (!line) {+ throw new Error(`The loader printed no result:\n${log}`);+ }+ return { outcome: JSON.parse(line.slice(RESULT.length)) as LoadOutcome, log };+}++test.describe('interface.theme in librechat.yaml', () => {+ test.beforeEach(() => inOneProject());+ test.afterEach(() => {+ delete process.env.CONFIG_PATH;+ });++ test('a typo in a theme token leaves the server running on the default theme @scenario:yaml-theme-typo-falls-back', () => {+ const { outcome, log } = loadFixture('unknown-token');++ expect(outcome.exited).toBeUndefined();+ expect(outcome.interface).toEqual({ modelSelect: true });+ expect(log).toContain('the default theme applies instead');+ expect(log).toContain(+ 'interface.theme.modes.light.colors.rgb-surfce-secondary: Unknown color token: rgb-surfce-secondary',+ );+ expect(log).toContain(+ 'interface.theme.modes.light.colors.surface-tertiary: Unknown color token: surface-tertiary',+ );+ });++ test('a bad token value is reported with its path and the theme is dropped @scenario:yaml-theme-bad-value-reported', () => {+ const { outcome, log } = loadFixture('bad-value');++ expect(outcome.exited).toBeUndefined();+ expect(outcome.interface).toEqual({ modelSelect: true });+ expect(log).toContain(+ 'interface.theme.modes.dark.colors.rgb-surface-primary: Invalid RGB value for rgb-surface-primary: 300 16 32',+ );+ expect(log).toContain(+ 'interface.theme.modes.dark.appearance.controlRadius: Invalid appearance value for controlRadius: 4 pixels',+ );+ });++ test('a misspelled bundled theme name falls back with a warning @scenario:yaml-theme-unknown-name-falls-back', () => {+ const { outcome, log } = loadFixture('unknown-name');++ expect(outcome.exited).toBeUndefined();+ expect(outcome.interface).toEqual({ modelSelect: true });+ expect(log).toContain(+ 'interface.theme: Unknown bundled theme "clickhous", expected one of: librechat, clickhouse',+ );+ expect(loadFixture('bundled').outcome.interface?.theme).toBe('clickhouse');+ });++ test('a valid inline theme loads exactly as written @scenario:yaml-theme-valid-unchanged', () => {+ const { outcome, log } = loadFixture('valid');++ expect(outcome.interface?.theme).toEqual({+ version: 1,+ name: 'acme',+ modes: {+ light: {+ colors: { 'rgb-surface-primary': '240 244 255' },+ appearance: { controlRadius: '0.25rem' },+ },+ dark: { colors: { 'rgb-surface-primary': '12 16 32' } },+ },+ brands: { 'provider-openai': '#10a37f' },+ });+ expect(log).not.toContain('interface.theme');+ });++ test('a config reload with a broken theme applies the same fallback @scenario:yaml-theme-reload-falls-back', () => {+ const { outcome, log } = loadFixture('unknown-token', 'reload');++ expect(outcome.rejected).toBeUndefined();+ expect(outcome.interface).toEqual({ modelSelect: true });+ expect(log).toContain('interface.theme.modes.light.colors.rgb-surfce-secondary');+ });++ test('an invalid key outside the theme still stops startup @scenario:yaml-theme-other-errors-still-exit', () => {+ const { outcome } = loadFixture('unrelated-error');++ expect(outcome.exited).toBe(1);+ expect(loadFixture('unrelated-error', 'reload').outcome.rejected).toBe('ConfigReloadError');+ });+});diff --git a/packages/api/src/app/__fixtures__/theme/bad-value.yaml b/packages/api/src/app/__fixtures__/theme/bad-value.yamlnew file mode 100644index 0000000000..1dd4e4704e--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/bad-value.yaml@@ -0,0 +1,13 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ version: 1+ name: acme+ modes:+ dark:+ colors:+ rgb-surface-primary: '300 16 32'+ appearance:+ controlRadius: 4 pixelsdiff --git a/packages/api/src/app/__fixtures__/theme/bundled.yaml b/packages/api/src/app/__fixtures__/theme/bundled.yamlnew file mode 100644index 0000000000..7e3a6c8ebb--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/bundled.yaml@@ -0,0 +1,5 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme: clickhousediff --git a/packages/api/src/app/__fixtures__/theme/malformed.yaml b/packages/api/src/app/__fixtures__/theme/malformed.yamlnew file mode 100644index 0000000000..e1ac0b825e--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/malformed.yaml@@ -0,0 +1,7 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ - acme+ - clickhousediff --git a/packages/api/src/app/__fixtures__/theme/spacing.yaml b/packages/api/src/app/__fixtures__/theme/spacing.yamlnew file mode 100644index 0000000000..9f8da1036f--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/spacing.yaml@@ -0,0 +1,11 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ version: 1+ name: acme+ modes:+ light:+ colors:+ rgb-surface-primary: '240 244 255'diff --git a/packages/api/src/app/__fixtures__/theme/unknown-appearance.yaml b/packages/api/src/app/__fixtures__/theme/unknown-appearance.yamlnew file mode 100644index 0000000000..690277e45e--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/unknown-appearance.yaml@@ -0,0 +1,12 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ version: 1+ name: acme+ modes:+ light:+ appearance:+ controlRadius: 2px+ futureSpacing: 3remdiff --git a/packages/api/src/app/__fixtures__/theme/unknown-name.yaml b/packages/api/src/app/__fixtures__/theme/unknown-name.yamlnew file mode 100644index 0000000000..7881ecb482--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/unknown-name.yaml@@ -0,0 +1,5 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme: clickhousdiff --git a/packages/api/src/app/__fixtures__/theme/unknown-token.yaml b/packages/api/src/app/__fixtures__/theme/unknown-token.yamlnew file mode 100644index 0000000000..c8cdec00ba--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/unknown-token.yaml@@ -0,0 +1,13 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ version: 1+ name: acme+ modes:+ light:+ colors:+ rgb-surface-primary: '240 244 255'+ rgb-surfce-secondary: '250 250 250'+ surface-tertiary: '245 245 245'diff --git a/packages/api/src/app/__fixtures__/theme/unrelated-error.yaml b/packages/api/src/app/__fixtures__/theme/unrelated-error.yamlnew file mode 100644index 0000000000..353ecee547--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/unrelated-error.yaml@@ -0,0 +1,12 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ version: 1+ name: acme+ modes:+ light:+ colors:+ rgb-surfce-primary: '240 244 255'+notAConfigKey: truediff --git a/packages/api/src/app/__fixtures__/theme/valid.yaml b/packages/api/src/app/__fixtures__/theme/valid.yamlnew file mode 100644index 0000000000..e01463685a--- /dev/null+++ b/packages/api/src/app/__fixtures__/theme/valid.yaml@@ -0,0 +1,18 @@+version: 1.3.17+cache: true+interface:+ modelSelect: true+ theme:+ version: 1+ name: acme+ modes:+ light:+ colors:+ rgb-surface-primary: '240 244 255'+ appearance:+ controlRadius: 0.25rem+ dark:+ colors:+ rgb-surface-primary: '12 16 32'+ brands:+ provider-openai: '#10a37f'diff --git a/packages/api/src/app/loader.spec.ts b/packages/api/src/app/loader.spec.tsnew file mode 100644index 0000000000..d0c523c6f2--- /dev/null+++ b/packages/api/src/app/loader.spec.ts@@ -0,0 +1,165 @@+import path from 'path';+import { logger } from '@librechat/data-schemas';+import type { TCustomConfig } from 'librechat-data-provider';+import { createCustomConfigLoader, ConfigReloadError } from './loader';+import { loadYaml } from '~/utils/yaml';++const fixture = (name: string) => path.join(__dirname, '__fixtures__', 'theme', `${name}.yaml`);++const raw = (name: string) => loadYaml(fixture(name)) as TCustomConfig;++const createLoader = () =>+ createCustomConfigLoader({+ loadLocal: loadYaml,+ defaultConfigPath: fixture('valid'),+ redactConfig: (config: TCustomConfig) => config,+ });++const warnings = (spy: jest.SpyInstance): string =>+ spy.mock.calls.map(([message]) => String(message)).join('\n');++describe('createCustomConfigLoader interface.theme', () => {+ const originalConfigPath = process.env.CONFIG_PATH;+ let warn: jest.SpyInstance;+ let exit: jest.SpyInstance;++ beforeEach(() => {+ warn = jest.spyOn(logger, 'warn');+ jest.spyOn(logger, 'error').mockImplementation(() => logger);+ jest.spyOn(logger, 'info').mockImplementation(() => logger);+ exit = jest.spyOn(process, 'exit').mockImplementation((code) => {+ throw new Error(`process.exit(${code})`);+ });+ });++ afterEach(() => {+ jest.restoreAllMocks();+ if (originalConfigPath === undefined) {+ delete process.env.CONFIG_PATH;+ } else {+ process.env.CONFIG_PATH = originalConfigPath;+ }+ });++ const load = async (name: string, mode: 'startup' | 'reload' = 'startup') => {+ process.env.CONFIG_PATH = fixture(name);+ return createLoader()(false, { mode });+ };++ it('returns a valid theme exactly as written, without warnings', async () => {+ const config = await load('valid');++ expect(config?.interface?.theme).toEqual(raw('valid').interface?.theme);+ expect(config?.interface?.modelSelect).toBe(true);+ expect(warn).not.toHaveBeenCalled();+ expect(exit).not.toHaveBeenCalled();+ });++ it('drops a theme naming an unknown color token and keeps the rest of the config', async () => {+ const config = await load('unknown-token');++ expect(exit).not.toHaveBeenCalled();+ expect(config).not.toBeNull();+ expect(config?.interface).not.toHaveProperty('theme');+ expect(config?.interface?.modelSelect).toBe(true);+ expect(config?.cache).toBe(true);+ expect(warnings(warn)).toContain(+ 'interface.theme.modes.light.colors.rgb-surfce-secondary: Unknown color token: rgb-surfce-secondary',+ );+ expect(warnings(warn)).toContain(+ 'interface.theme.modes.light.colors.surface-tertiary: Unknown color token: surface-tertiary',+ );+ expect(warnings(warn)).toContain('the default theme applies instead');+ });++ it('reports every bad value with its path and drops the theme', async () => {+ const config = await load('bad-value');++ expect(exit).not.toHaveBeenCalled();+ expect(config?.interface).not.toHaveProperty('theme');+ const logged = warnings(warn);+ expect(logged).toContain(+ 'interface.theme.modes.dark.colors.rgb-surface-primary: Invalid RGB value for rgb-surface-primary: 300 16 32',+ );+ expect(logged).toContain(+ 'interface.theme.modes.dark.appearance.controlRadius: Invalid appearance value for controlRadius: 4 pixels',+ );+ });++ it('drops a theme that is neither a name nor a definition', async () => {+ const config = await load('malformed');++ expect(exit).not.toHaveBeenCalled();+ expect(config?.interface).not.toHaveProperty('theme');+ expect(config?.interface?.modelSelect).toBe(true);+ expect(warnings(warn)).toContain(+ 'interface.theme: Expected a bundled theme name or an inline theme definition',+ );+ });++ it('drops a value the client reads but the config schema rejects, citing the schema path', async () => {+ const config = await load('spacing');++ expect(exit).not.toHaveBeenCalled();+ expect(config?.interface).not.toHaveProperty('theme');+ expect(warnings(warn)).toContain('interface.theme.modes.light.colors.rgb-surface-primary:');+ });++ it('drops a bundled theme name that does not exist', async () => {+ const config = await load('unknown-name');++ expect(exit).not.toHaveBeenCalled();+ expect(config?.interface).not.toHaveProperty('theme');+ expect(config?.interface?.modelSelect).toBe(true);+ expect(warnings(warn)).toContain(+ 'interface.theme: Unknown bundled theme "clickhous", expected one of: librechat, clickhouse',+ );+ });++ it('keeps a bundled theme name', async () => {+ const config = await load('bundled');++ expect(config?.interface?.theme).toBe('clickhouse');+ expect(warn).not.toHaveBeenCalled();+ });++ it('keeps a theme whose only problem is an appearance token this version ignores', async () => {+ const config = await load('unknown-appearance');++ expect(config?.interface?.theme).toEqual(raw('unknown-appearance').interface?.theme);+ expect(warnings(warn)).toContain(+ 'interface.theme.modes.light.appearance.futureSpacing: Unknown light appearance token ignored: futureSpacing',+ );+ expect(warnings(warn)).not.toContain('the default theme applies instead');+ });++ it('still exits at startup when something other than the theme is invalid', async () => {+ await expect(load('unrelated-error')).rejects.toThrow('process.exit(1)');+ expect(exit).toHaveBeenCalledWith(1);+ expect(warnings(warn)).toContain('interface.theme.modes.light.colors.rgb-surfce-primary');+ });++ describe('reload mode', () => {+ it('applies the same fallback instead of rejecting the reload', async () => {+ const config = await load('unknown-token', 'reload');++ expect(config?.interface).not.toHaveProperty('theme');+ expect(config?.interface?.modelSelect).toBe(true);+ expect(warnings(warn)).toContain(+ 'interface.theme.modes.light.colors.rgb-surfce-secondary: Unknown color token',+ );+ });++ it('returns a valid theme unchanged', async () => {+ const config = await load('valid', 'reload');++ expect(config?.interface?.theme).toEqual(raw('valid').interface?.theme);+ expect(warn).not.toHaveBeenCalled();+ });++ it('still rejects a reload whose other keys are invalid', async () => {+ await expect(load('unrelated-error', 'reload')).rejects.toBeInstanceOf(ConfigReloadError);+ expect(exit).not.toHaveBeenCalled();+ });+ });+});diff --git a/packages/api/src/app/loader.ts b/packages/api/src/app/loader.tsindex 6365450c4e..25cdad6cdc 100644--- a/packages/api/src/app/loader.ts+++ b/packages/api/src/app/loader.ts@@ -14,6 +14,7 @@ import {} from 'librechat-data-provider';import type { TCustomConfig, TEndpoint } from 'librechat-data-provider';import type { ZodIssue } from 'zod';+import { checkConfigTheme } from './theme';type CustomParams = NonNullable<TEndpoint['customParams']>;type CustomParamDefinition = NonNullable<CustomParams['paramDefinitions']>[number];@@ -154,6 +155,21 @@ function isRemoteConfigPath(configPath: string): boolean {return /^https?:\/\//.test(configPath);}+function reportThemeCheck(configPath: string, errors: string[], warnings: string[]): void {+ if (errors.length > 0) {+ logger.warn(+ `Ignoring interface.theme in ${configPath}; the default theme applies instead:\n` ++ errors.map((error) => `- ${error}`).join('\n'),+ );+ }+ if (warnings.length > 0) {+ logger.warn(+ `interface.theme in ${configPath} names tokens this version ignores:\n` ++ warnings.map((warning) => `- ${warning}`).join('\n'),+ );+ }+}+/** Creates one process-local custom-config reader. */export function createCustomConfigLoader({defaultConfigPath,@@ -242,6 +258,10 @@ export function createCustomConfigLoader({}}+ const themeCheck = checkConfigTheme(loadedConfig);+ loadedConfig = themeCheck.config;+ reportThemeCheck(configPath, themeCheck.errors, themeCheck.warnings);+setMaxSubagents(getConfiguredMaxSubagents(loadedConfig));const result = configSchema.strict().safeParse(loadedConfig);if (diff --git a/packages/api/src/app/theme.ts b/packages/api/src/app/theme.tsnew file mode 100644index 0000000000..f604e99078--- /dev/null+++ b/packages/api/src/app/theme.ts@@ -0,0 +1,77 @@+import {+ bundledThemeNames,+ collectThemeIssues,+ isBundledThemeName,+ isPlainThemeRecord,+ deploymentThemeSchema,+ collectThemeWarningIssues,+} from 'librechat-data-provider';+import type { ThemeIssue } from 'librechat-data-provider';++const THEME_PATH = ['interface', 'theme'];++export interface ConfigThemeCheck {+ /** The config to validate and return: the input itself unless the theme had to be dropped. */+ config: unknown;+ /** Why the theme was dropped, one `path: reason` line per problem. */+ errors: string[];+ /** Tokens the client will ignore while still applying the rest of the theme. */+ warnings: string[];+}++const formatIssue = ({ path, message }: ThemeIssue): string =>+ `${[...THEME_PATH, ...path].join('.')}: ${message}`;++function collectErrors(theme: unknown): ThemeIssue[] {+ if (typeof theme !== 'string' && !isPlainThemeRecord(theme)) {+ return [{ path: [], message: 'Expected a bundled theme name or an inline theme definition' }];+ }+ if (typeof theme === 'string') {+ return isBundledThemeName(theme)+ ? []+ : [+ {+ path: [],+ message: `Unknown bundled theme "${theme}", expected one of: ${bundledThemeNames.join(', ')}`,+ },+ ];+ }+ const issues = collectThemeIssues(theme);+ if (issues.length > 0) {+ return issues;+ }+ const result = deploymentThemeSchema.safeParse(theme);+ if (result.success) {+ return [];+ }+ return result.error.errors.map(({ path, message }) => ({+ path: path.map(String),+ message,+ }));+}++/**+ * Checks `interface.theme` with the rules the client applies before painting it. A theme the+ * client would reject is removed, so the deployment falls back to the default theme and the rest+ * of the config still loads; unknown appearance tokens, which the client drops on its own, only+ * warn. A config without a theme, or with a valid one, is returned as the same object.+ */+export function checkConfigTheme(config: unknown): ConfigThemeCheck {+ const unchanged: ConfigThemeCheck = { config, errors: [], warnings: [] };+ if (!isPlainThemeRecord(config) || !isPlainThemeRecord(config.interface)) {+ return unchanged;+ }+ const interfaceConfig = config.interface;+ if (!('theme' in interfaceConfig) || interfaceConfig.theme === undefined) {+ return unchanged;+ }++ const theme = interfaceConfig.theme;+ const errors = collectErrors(theme).map(formatIssue);+ if (errors.length === 0) {+ return { config, errors, warnings: collectThemeWarningIssues(theme).map(formatIssue) };+ }++ const { theme: _dropped, ...rest } = interfaceConfig;+ return { config: { ...config, interface: rest }, errors, warnings: [] };+}diff --git a/packages/client/src/theme/registry.ts b/packages/client/src/theme/registry.tsindex 3c8fac068e..5a45609723 100644--- a/packages/client/src/theme/registry.ts+++ b/packages/client/src/theme/registry.ts@@ -1,3 +1,17 @@+import {+ THEME_VERSION,+ isThemeRGB,+ collectThemeIssues,+ isThemeAppearanceToken,+ collectThemeWarningIssues,+ themeColorTokens as sharedColorTokens,+ themeBrandTokens as sharedBrandTokens,+} from 'librechat-data-provider';+import type {+ ThemeColorToken,+ ThemeBrandToken,+ ThemeAppearanceToken,+} from 'librechat-data-provider';import type {IThemeAppearance,IThemeBrands,@@ -11,7 +25,8 @@ import type {import { highContrastDarkTheme, highContrastLightTheme } from './themes/highContrast';import { defaultTheme } from './themes/default';import { darkTheme } from './themes/dark';-export const THEME_VERSION = 1 as const;++export { THEME_VERSION };/*** Compile-time guard: the categorical series scale is declared across three@@ -28,9 +43,21 @@ export type SeriesTokensAreDeclared = [Assert<DeclaredIn<`series-${SeriesSlot}`, IThemeColors>>,];-export const themeColorTokens: readonly (keyof IThemeRGB)[] = Object.freeze(- Object.keys(defaultTheme) as Array<keyof IThemeRGB>,-);+type SameKeys<A extends PropertyKey, B extends PropertyKey> = [A] extends [B]+ ? [B] extends [A]+ ? true+ : false+ : false;++/** The token lists live in `librechat-data-provider` so the server validates against the same+ * set; these fail the build when the client types drift from them. */+export type SharedTokensMatchTypes = [+ Assert<SameKeys<ThemeColorToken, keyof IThemeRGB>>,+ Assert<SameKeys<ThemeAppearanceToken, keyof IThemeAppearance>>,+ Assert<SameKeys<ThemeBrandToken, keyof IThemeBrands>>,+];++export const themeColorTokens: readonly (keyof IThemeRGB)[] = sharedColorTokens;/*** What the verified mark is measured against: the fill it wore before it had a@@ -120,15 +147,7 @@ export const defaultAppearance: IThemeAppearance = Object.freeze({motionNormal: '200ms',});-export const themeBrandTokens: readonly (keyof IThemeBrands)[] = Object.freeze([- 'provider-openai',- 'provider-openai-gpt4',- 'provider-openai-reasoning',- 'provider-anthropic',- 'provider-azure',- 'provider-bedrock',- 'provider-foreground',-]);+export const themeBrandTokens: readonly (keyof IThemeBrands)[] = sharedBrandTokens;export const defaultBrands: IThemeBrands = Object.freeze({'provider-openai': '#19C37D',@@ -195,295 +214,16 @@ export const highContrastTheme: ThemeDefinition = Object.freeze({},});-const rgbPattern = /^(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})$/;-const cssLengthPattern = /^(0|\d*\.?\d+(px|rem|em))$/;-const cssLengthDifferencePattern =- /^calc\(\s*\d*\.?\d+(px|rem|em)\s+[-+]\s+\d*\.?\d+(px|rem|em)\s*\)$/;-const cssDurationPattern = /^\d*\.?\d+(ms|s)$/;-const hexColorPattern = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;-const shadowLengthPattern = /^(-?(0|\d*\.?\d+[a-z]+)|(calc|min|max|clamp)\(.*\))$/i;-const shadowColorPattern = /^(#[0-9a-f]{3,8}|[a-z]+|[a-z-]+\(.*\))$/i;/** Tailwind composes `--tw-shadow` into one list with the ring layers, where `none` is invalid. */const disabledShadow = '0 0 #0000';-function isLinearGradient(value: string): boolean {- if (!value.startsWith('linear-gradient(') || /url\s*\(|image-set/i.test(value)) {- return false;- }- let depth = 0;- for (let i = 0; i < value.length; i++) {- const char = value[i];- if (char === '(') {- depth += 1;- } else if (char === ')') {- depth -= 1;- if (depth === 0) {- return i === value.length - 1;- }- if (depth < 0) {- return false;- }- }- }- return false;-}--const isRGB = (value: unknown): value is string => {- if (typeof value !== 'string') {- return false;- }- const match = value.match(rgbPattern);- return match !== null && match.slice(1).every((channel) => Number(channel) <= 255);-};--/** The bare form, or one `calc()` of two unit-bearing lengths (a bare `0` is a number there):- * the small radius defaults keep a px offset. */-const isLength = (value: unknown): value is string =>- typeof value === 'string' &&- (cssLengthPattern.test(value) || cssLengthDifferencePattern.test(value));-const isFontFamily = (value: unknown): value is string =>- typeof value === 'string' && value.trim().length > 0 && !/[;{}]/.test(value);-/** Splits on `separator` outside parentheses, so `rgb(0, 0, 0)` stays one part. Empty parts are- * kept, so a stray comma stays visible to the caller. */-function splitTopLevel(value: string, separator: RegExp): string[] {- const parts: string[] = [];- let depth = 0;- let current = '';- for (const char of value) {- if (char === '(') {- depth += 1;- } else if (char === ')') {- depth -= 1;- }- if (depth === 0 && separator.test(char)) {- parts.push(current);- current = '';- continue;- }- current += char;- }- parts.push(current);- return parts.map((part) => part.trim());-}--/** A named color is indistinguishable from any other word without the browser's color parser. */-const isShadowColor = (token: string): boolean =>- globalThis.CSS?.supports?.('color', token) ?? shadowColorPattern.test(token);--/** One layer: two to four lengths, optionally `inset` and one color, per the box-shadow grammar. */-function isShadowLayer(layer: string): boolean {- const tokens = splitTopLevel(layer, /\s/).filter((token) => token.length > 0);- const lengths = tokens.filter((token) => shadowLengthPattern.test(token)).length;- const insets = tokens.filter((token) => token.toLowerCase() === 'inset').length;- const colors = tokens.filter(- (token) => !shadowLengthPattern.test(token) && token.toLowerCase() !== 'inset',- );- return (- lengths >= 2 && lengths <= 4 && insets <= 1 && colors.length <= 1 && colors.every(isShadowColor)- );-}--/**- * A shadow must be concrete: a browser defers its check of any value holding `var()`, `env()` or- * `attr()` until substitution, so such a value could never be validated before it reaches the- * ring layers.- */-const isShadow = (value: unknown): value is string => {- if (typeof value !== 'string' || /[;{}]|url\s*\(|(var|env|attr)\s*\(/i.test(value)) {- return false;- }- if (value.trim().toLowerCase() === 'none') {- return true;- }- const layers = splitTopLevel(value, /,/);- if (layers.some((layer) => layer.length === 0) || !layers.every(isShadowLayer)) {- return false;- }- return globalThis.CSS?.supports?.('box-shadow', value) ?? true;-};-const isDuration = (value: unknown): value is string =>- typeof value === 'string' && cssDurationPattern.test(value);--const isPlainRecord = (value: unknown): value is Record<string, unknown> => {- if (typeof value !== 'object' || value === null || Array.isArray(value)) {- return false;- }- try {- const prototype = Object.getPrototypeOf(value);- return prototype === null || prototype.constructor?.name === 'Object';- } catch {- return false;- }-};--const appearanceValidators: Record<keyof IThemeAppearance, (value: unknown) => boolean> = {- controlRadius: isLength,- roundControlRadius: isLength,- surfaceRadius: isLength,- largeSurfaceRadius: isLength,- radiusSm: isLength,- radiusMd: isLength,- radiusLg: isLength,- radiusXl: isLength,- radius2xl: isLength,- radius3xl: isLength,- controlHeight: isLength,- spaceCompact: isLength,- spaceNormal: isLength,- fontFamily: isFontFamily,- monoFontFamily: isFontFamily,- /** Released themes may hold `var()` here, so this role keeps its original, looser check. */- elevationSurface: (value) =>- typeof value === 'string' && value.trim().length > 0 && !/[;{}]|url\s*\(/i.test(value),- shadow2xs: isShadow,- shadowXs: isShadow,- shadowSm: isShadow,- shadowMd: isShadow,- shadowLg: isShadow,- shadowXl: isShadow,- shadow2xl: isShadow,- motionFast: isDuration,- motionNormal: isDuration,-};--const isAppearanceKey = (key: string): key is keyof IThemeAppearance =>- Object.prototype.hasOwnProperty.call(appearanceValidators, key);--/**- * A token added after this reader shipped is ignored rather than rejected, so a newer definition- * degrades to the defaults for what this version cannot paint instead of losing every value it- * can. It never reaches the DOM, but it must still look like a token: a camelCase name and a- * plain CSS value, never a declaration or rule break.- */-const isFutureAppearance = (key: string, value: unknown): boolean =>- /^[a-z][a-zA-Z0-9]*$/.test(key) && typeof value === 'string' && !/[;{}<>]|url\s*\(/i.test(value);-/** The appearance tokens this reader does not know, which `resolveTheme` leaves out. */export function collectThemeWarnings(theme: ThemeDefinition): string[] {- if (!isPlainRecord(theme) || !isPlainRecord(theme.modes)) {- return [];- }- return (['light', 'dark'] as const).flatMap((mode) => {- const appearance: unknown = isPlainRecord(theme.modes[mode])- ? theme.modes[mode]?.appearance- : undefined;- if (!isPlainRecord(appearance)) {- return [];- }- return Object.keys(appearance)- .filter((key) => !isAppearanceKey(key))- .map((key) => `Unknown ${mode} appearance token ignored: ${key}`);- });-}--/** Shared by the theme-wide `brands` and each mode's override block. */-function collectBrandErrors(brands: unknown): string[] {- if (!isPlainRecord(brands)) {- return [];- }-- return Object.entries(brands).flatMap(([key, value]) => {- if (!themeBrandTokens.includes(key as keyof IThemeBrands)) {- return [`Unknown brand token: ${key}`];- }- /** Only the glyph is a flat colour; a fill may also be a gradient. */- const isColorOnly = key === 'provider-foreground';- const isValidBrand =- typeof value === 'string' &&- (isColorOnly- ? hexColorPattern.test(value)- : hexColorPattern.test(value) || isLinearGradient(value));- return value !== undefined && !isValidBrand ? [`Invalid brand value for ${key}: ${value}`] : [];- });+ return collectThemeWarningIssues(theme).map(({ message }) => message);}export function validateThemeDefinition(theme: ThemeDefinition): string[] {- const errors: string[] = [];-- if (!isPlainRecord(theme)) {- return ['Theme definition must be an object'];- }-- Object.keys(theme).forEach((key) => {- if (key !== 'version' && key !== 'name' && key !== 'modes' && key !== 'brands') {- errors.push(`Unknown theme field: ${key}`);- }- });-- if (theme.version !== THEME_VERSION) {- errors.push(`Unsupported theme version: ${theme.version}`);- }- if (typeof theme.name !== 'string' || !theme.name.trim()) {- errors.push('Theme name is required');- }- if (!isPlainRecord(theme.modes)) {- errors.push('Theme modes must be an object');- return errors;- }-- Object.keys(theme.modes).forEach((mode) => {- if (mode !== 'light' && mode !== 'dark') {- errors.push(`Unknown theme mode: ${mode}`);- }- });-- (['light', 'dark'] as const).forEach((mode) => {- const definition = theme.modes[mode];- if (definition === undefined) {- return;- }-- if (!isPlainRecord(definition)) {- errors.push(`Theme mode ${mode} must be an object`);- return;- }-- Object.keys(definition).forEach((key) => {- if (key !== 'colors' && key !== 'appearance' && key !== 'brands') {- errors.push(`Unknown ${mode} theme field: ${key}`);- }- });-- if (definition.colors !== undefined && !isPlainRecord(definition.colors)) {- errors.push(`Theme colors for ${mode} must be an object`);- } else {- Object.entries(definition.colors ?? {}).forEach(([key, value]) => {- if (!themeColorTokens.includes(key as keyof IThemeRGB)) {- errors.push(`Unknown color token: ${key}`);- return;- }- if (value !== undefined && !isRGB(value)) {- errors.push(`Invalid RGB value for ${key}: ${value}`);- }- });- }-- if (definition.appearance !== undefined && !isPlainRecord(definition.appearance)) {- errors.push(`Theme appearance for ${mode} must be an object`);- } else {- Object.entries(definition.appearance ?? {}).forEach(([key, value]) => {- const isKnown = isAppearanceKey(key);- const isValid = isKnown ? appearanceValidators[key](value) : isFutureAppearance(key, value);- if (value !== undefined && !isValid) {- errors.push(`Invalid appearance value for ${key}: ${value}`);- }- });- }-- if (definition.brands !== undefined && !isPlainRecord(definition.brands)) {- errors.push(`Theme brands for ${mode} must be an object`);- } else {- errors.push(...collectBrandErrors(definition.brands));- }- });-- if (theme.brands !== undefined && !isPlainRecord(theme.brands)) {- errors.push('Theme brands must be an object');- } else {- errors.push(...collectBrandErrors(theme.brands));- }-- return errors;+ return collectThemeIssues(theme).map(({ message }) => message);}/**@@ -503,7 +243,7 @@ function definedEntries<T extends object>(values?: Partial<T>): Partial<T> {function knownAppearance(appearance?: Partial<IThemeAppearance>): Partial<IThemeAppearance> {return Object.fromEntries(- Object.entries(definedEntries(appearance)).filter(([key]) => isAppearanceKey(key)),+ Object.entries(definedEntries(appearance)).filter(([key]) => isThemeAppearanceToken(key)),);}@@ -679,7 +419,7 @@ export function fromLegacyTheme(colors: IThemeRGB, name = 'custom'): ThemeDefiniconst legacyName = name.trim() || 'custom';const sanitizedColors = themeColorTokens.reduce<IThemeRGB>((result, token) => {const value = colors[token];- if (isRGB(value)) {+ if (isThemeRGB(value)) {result[token] = value;}return result;diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.tsindex c6caeccb91..3d18c331fc 100644--- a/packages/data-provider/src/index.ts+++ b/packages/data-provider/src/index.ts@@ -4,6 +4,7 @@ export * from './bedrock';export * from './balance';export * from './config';export * from './footer';+export * from './theme';export * from './langchain';export * from './filters';export * from './file-config';diff --git a/packages/data-provider/src/theme.ts b/packages/data-provider/src/theme.tsnew file mode 100644index 0000000000..e1b321dea5--- /dev/null+++ b/packages/data-provider/src/theme.ts@@ -0,0 +1,442 @@+/**+ * The theme token contract shared by the client registry, which paints a definition, and the+ * server, which checks `interface.theme` when librechat.yaml loads. Both read these lists, so a+ * token added here is accepted everywhere at once.+ */+export const THEME_VERSION = 1 as const;++/** The names `interface.theme` may give instead of an inline definition. */+export const bundledThemeNames = Object.freeze(['librechat', 'clickhouse'] as const);++export type BundledThemeName = (typeof bundledThemeNames)[number];++export const isBundledThemeName = (value: string): value is BundledThemeName =>+ (bundledThemeNames as readonly string[]).includes(value);++export const themeColorTokens = Object.freeze([+ 'rgb-text-primary',+ 'rgb-text-secondary',+ 'rgb-text-secondary-alt',+ 'rgb-text-tertiary',+ 'rgb-text-muted',+ 'rgb-text-warning',+ 'rgb-text-destructive',+ 'rgb-shimmer-base',+ 'rgb-shimmer-dip',+ 'rgb-link',+ 'rgb-link-hover',+ 'rgb-link-visited',+ 'rgb-accent-primary',+ 'rgb-accent-primary-hover',+ 'rgb-ring-primary',+ 'rgb-header-primary',+ 'rgb-header-hover',+ 'rgb-header-button-hover',+ 'rgb-surface-active',+ 'rgb-surface-active-alt',+ 'rgb-surface-hover',+ 'rgb-surface-hover-alt',+ 'rgb-surface-composer-hover',+ 'rgb-surface-primary',+ 'rgb-chart-widget-surface',+ 'rgb-chart-widget-stroke',+ 'rgb-surface-primary-alt',+ 'rgb-surface-primary-contrast',+ 'rgb-surface-secondary',+ 'rgb-surface-secondary-alt',+ 'rgb-surface-tertiary',+ 'rgb-surface-tertiary-alt',+ 'rgb-surface-dialog',+ 'rgb-surface-overlay',+ 'rgb-surface-submit',+ 'rgb-surface-submit-hover',+ 'rgb-surface-destructive',+ 'rgb-surface-destructive-hover',+ 'rgb-surface-chat',+ 'rgb-surface-code',+ 'rgb-surface-code-body',+ 'rgb-surface-inverted',+ 'rgb-surface-inverted-hover',+ 'rgb-text-inverted',+ 'rgb-surface-fixed',+ 'rgb-surface-fixed-hover',+ 'rgb-text-fixed',+ 'rgb-border-light',+ 'rgb-border-medium',+ 'rgb-border-medium-alt',+ 'rgb-border-heavy',+ 'rgb-border-xheavy',+ 'rgb-border-destructive',+ 'rgb-border-control',+ 'rgb-status-success',+ 'rgb-status-success-subtle',+ 'rgb-status-success-border',+ 'rgb-status-success-strong',+ 'rgb-status-info',+ 'rgb-status-info-subtle',+ 'rgb-status-info-border',+ 'rgb-status-info-strong',+ 'rgb-status-warning',+ 'rgb-status-warning-subtle',+ 'rgb-status-warning-border',+ 'rgb-status-warning-strong',+ 'rgb-status-error',+ 'rgb-status-error-subtle',+ 'rgb-status-error-border',+ 'rgb-status-error-strong',+ 'rgb-status-neutral',+ 'rgb-status-neutral-subtle',+ 'rgb-status-neutral-border',+ 'rgb-status-verified',+ 'rgb-text-on-status',+ 'rgb-brand-purple',+ 'rgb-syntax-text',+ 'rgb-syntax-comment',+ 'rgb-syntax-meta',+ 'rgb-syntax-builtin',+ 'rgb-syntax-keyword',+ 'rgb-syntax-string',+ 'rgb-syntax-attr',+ 'rgb-syntax-title',+ 'rgb-series-1',+ 'rgb-series-2',+ 'rgb-series-3',+ 'rgb-series-4',+ 'rgb-series-5',+ 'rgb-series-6',+ 'rgb-series-7',+ 'rgb-series-8',+ 'rgb-switch-unchecked',+ 'rgb-presentation',+] as const);++export type ThemeColorToken = (typeof themeColorTokens)[number];++export const themeBrandTokens = Object.freeze([+ 'provider-openai',+ 'provider-openai-gpt4',+ 'provider-openai-reasoning',+ 'provider-anthropic',+ 'provider-azure',+ 'provider-bedrock',+ 'provider-foreground',+] as const);++export type ThemeBrandToken = (typeof themeBrandTokens)[number];++/** One problem in a theme definition: where it is, relative to the definition, and what it is. */+export interface ThemeIssue {+ path: string[];+ message: string;+}++const rgbPattern = /^(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})$/;+const cssLengthPattern = /^(0|\d*\.?\d+(px|rem|em))$/;+const cssLengthDifferencePattern =+ /^calc\(\s*\d*\.?\d+(px|rem|em)\s+[-+]\s+\d*\.?\d+(px|rem|em)\s*\)$/;+const cssDurationPattern = /^\d*\.?\d+(ms|s)$/;+const hexColorPattern = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;+const shadowLengthPattern = /^(-?(0|\d*\.?\d+[a-z]+)|(calc|min|max|clamp)\(.*\))$/i;+const shadowColorPattern = /^(#[0-9a-f]{3,8}|[a-z]+|[a-z-]+\(.*\))$/i;++function isLinearGradient(value: string): boolean {+ if (!value.startsWith('linear-gradient(') || /url\s*\(|image-set/i.test(value)) {+ return false;+ }+ let depth = 0;+ for (let i = 0; i < value.length; i++) {+ const char = value[i];+ if (char === '(') {+ depth += 1;+ } else if (char === ')') {+ depth -= 1;+ if (depth === 0) {+ return i === value.length - 1;+ }+ if (depth < 0) {+ return false;+ }+ }+ }+ return false;+}++export const isThemeRGB = (value: unknown): value is string => {+ if (typeof value !== 'string') {+ return false;+ }+ const match = value.match(rgbPattern);+ return match !== null && match.slice(1).every((channel) => Number(channel) <= 255);+};++/** The bare form, or one `calc()` of two unit-bearing lengths (a bare `0` is a number there):+ * the small radius defaults keep a px offset. */+const isLength = (value: unknown): value is string =>+ typeof value === 'string' &&+ (cssLengthPattern.test(value) || cssLengthDifferencePattern.test(value));+const isFontFamily = (value: unknown): value is string =>+ typeof value === 'string' && value.trim().length > 0 && !/[;{}]/.test(value);++/** Splits on `separator` outside parentheses, so `rgb(0, 0, 0)` stays one part. Empty parts are+ * kept, so a stray comma stays visible to the caller. */+function splitTopLevel(value: string, separator: RegExp): string[] {+ const parts: string[] = [];+ let depth = 0;+ let current = '';+ for (let i = 0; i < value.length; i++) {+ const char = value[i];+ if (char === '(') {+ depth += 1;+ } else if (char === ')') {+ depth -= 1;+ }+ if (depth === 0 && separator.test(char)) {+ parts.push(current);+ current = '';+ continue;+ }+ current += char;+ }+ parts.push(current);+ return parts.map((part) => part.trim());+}++/** A named color is indistinguishable from any other word without the browser's color parser,+ * so outside a browser the pattern decides. */+const isShadowColor = (token: string): boolean =>+ globalThis.CSS?.supports?.('color', token) ?? shadowColorPattern.test(token);++/** One layer: two to four lengths, optionally `inset` and one color, per the box-shadow grammar. */+function isShadowLayer(layer: string): boolean {+ const tokens = splitTopLevel(layer, /\s/).filter((token) => token.length > 0);+ const lengths = tokens.filter((token) => shadowLengthPattern.test(token)).length;+ const insets = tokens.filter((token) => token.toLowerCase() === 'inset').length;+ const colors = tokens.filter(+ (token) => !shadowLengthPattern.test(token) && token.toLowerCase() !== 'inset',+ );+ return (+ lengths >= 2 && lengths <= 4 && insets <= 1 && colors.length <= 1 && colors.every(isShadowColor)+ );+}++/**+ * A shadow must be concrete: a browser defers its check of any value holding `var()`, `env()` or+ * `attr()` until substitution, so such a value could never be validated before it reaches the+ * ring layers.+ */+const isShadow = (value: unknown): value is string => {+ if (typeof value !== 'string' || /[;{}]|url\s*\(|(var|env|attr)\s*\(/i.test(value)) {+ return false;+ }+ if (value.trim().toLowerCase() === 'none') {+ return true;+ }+ const layers = splitTopLevel(value, /,/);+ if (layers.some((layer) => layer.length === 0) || !layers.every(isShadowLayer)) {+ return false;+ }+ return globalThis.CSS?.supports?.('box-shadow', value) ?? true;+};+const isDuration = (value: unknown): value is string =>+ typeof value === 'string' && cssDurationPattern.test(value);++export const isPlainThemeRecord = (value: unknown): value is Record<string, unknown> => {+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {+ return false;+ }+ try {+ const prototype = Object.getPrototypeOf(value);+ return prototype === null || prototype.constructor?.name === 'Object';+ } catch {+ return false;+ }+};++const appearanceValidators = {+ controlRadius: isLength,+ roundControlRadius: isLength,+ surfaceRadius: isLength,+ largeSurfaceRadius: isLength,+ radiusSm: isLength,+ radiusMd: isLength,+ radiusLg: isLength,+ radiusXl: isLength,+ radius2xl: isLength,+ radius3xl: isLength,+ controlHeight: isLength,+ spaceCompact: isLength,+ spaceNormal: isLength,+ fontFamily: isFontFamily,+ monoFontFamily: isFontFamily,+ /** Released themes may hold `var()` here, so this role keeps its original, looser check. */+ elevationSurface: (value: unknown) =>+ typeof value === 'string' && value.trim().length > 0 && !/[;{}]|url\s*\(/i.test(value),+ shadow2xs: isShadow,+ shadowXs: isShadow,+ shadowSm: isShadow,+ shadowMd: isShadow,+ shadowLg: isShadow,+ shadowXl: isShadow,+ shadow2xl: isShadow,+ motionFast: isDuration,+ motionNormal: isDuration,+} satisfies Record<string, (value: unknown) => boolean>;++export type ThemeAppearanceToken = keyof typeof appearanceValidators;++export const themeAppearanceTokens = Object.freeze(+ Object.keys(appearanceValidators) as ThemeAppearanceToken[],+);++export const isThemeAppearanceToken = (key: string): key is ThemeAppearanceToken =>+ Object.prototype.hasOwnProperty.call(appearanceValidators, key);++const colorTokenSet: ReadonlySet<string> = new Set<string>(themeColorTokens);+const brandTokenSet: ReadonlySet<string> = new Set<string>(themeBrandTokens);+const themeModes = ['light', 'dark'] as const;++/**+ * A token added after this reader shipped is ignored rather than rejected, so a newer definition+ * degrades to the defaults for what this version cannot paint instead of losing every value it+ * can. It never reaches the DOM, but it must still look like a token: a camelCase name and a+ * plain CSS value, never a declaration or rule break.+ */+const isFutureAppearance = (key: string, value: unknown): boolean =>+ /^[a-z][a-zA-Z0-9]*$/.test(key) && typeof value === 'string' && !/[;{}<>]|url\s*\(/i.test(value);++const issue = (path: string[], message: string): ThemeIssue => ({ path, message });++/** The appearance tokens this reader does not know, which a resolved theme leaves out. */+export function collectThemeWarningIssues(theme: unknown): ThemeIssue[] {+ if (!isPlainThemeRecord(theme) || !isPlainThemeRecord(theme.modes)) {+ return [];+ }+ const modes = theme.modes;+ return themeModes.flatMap((mode) => {+ const definition = modes[mode];+ const appearance = isPlainThemeRecord(definition) ? definition.appearance : undefined;+ if (!isPlainThemeRecord(appearance)) {+ return [];+ }+ return Object.keys(appearance)+ .filter((key) => !isThemeAppearanceToken(key))+ .map((key) =>+ issue(+ ['modes', mode, 'appearance', key],+ `Unknown ${mode} appearance token ignored: ${key}`,+ ),+ );+ });+}++/** Shared by the theme-wide `brands` and each mode's override block. */+function collectBrandIssues(brands: unknown, path: string[]): ThemeIssue[] {+ if (!isPlainThemeRecord(brands)) {+ return [];+ }++ return Object.entries(brands).flatMap(([key, value]) => {+ if (!brandTokenSet.has(key)) {+ return [issue([...path, key], `Unknown brand token: ${key}`)];+ }+ /** Only the glyph is a flat colour; a fill may also be a gradient. */+ const isColorOnly = key === 'provider-foreground';+ const isValidBrand =+ typeof value === 'string' &&+ (isColorOnly+ ? hexColorPattern.test(value)+ : hexColorPattern.test(value) || isLinearGradient(value));+ return value !== undefined && !isValidBrand+ ? [issue([...path, key], `Invalid brand value for ${key}: ${value}`)]+ : [];+ });+}++function collectModeIssues(mode: 'light' | 'dark', definition: unknown): ThemeIssue[] {+ const base = ['modes', mode];+ if (definition === undefined) {+ return [];+ }+ if (!isPlainThemeRecord(definition)) {+ return [issue(base, `Theme mode ${mode} must be an object`)];+ }++ const issues: ThemeIssue[] = Object.keys(definition)+ .filter((key) => key !== 'colors' && key !== 'appearance' && key !== 'brands')+ .map((key) => issue([...base, key], `Unknown ${mode} theme field: ${key}`));++ const { colors, appearance, brands } = definition;+ if (colors !== undefined && !isPlainThemeRecord(colors)) {+ issues.push(issue([...base, 'colors'], `Theme colors for ${mode} must be an object`));+ } else {+ Object.entries(colors ?? {}).forEach(([key, value]) => {+ const path = [...base, 'colors', key];+ if (!colorTokenSet.has(key)) {+ issues.push(issue(path, `Unknown color token: ${key}`));+ return;+ }+ if (value !== undefined && !isThemeRGB(value)) {+ issues.push(issue(path, `Invalid RGB value for ${key}: ${value}`));+ }+ });+ }++ if (appearance !== undefined && !isPlainThemeRecord(appearance)) {+ issues.push(issue([...base, 'appearance'], `Theme appearance for ${mode} must be an object`));+ } else {+ Object.entries(appearance ?? {}).forEach(([key, value]) => {+ const isValid = isThemeAppearanceToken(key)+ ? appearanceValidators[key](value)+ : isFutureAppearance(key, value);+ if (value !== undefined && !isValid) {+ issues.push(+ issue([...base, 'appearance', key], `Invalid appearance value for ${key}: ${value}`),+ );+ }+ });+ }++ if (brands !== undefined && !isPlainThemeRecord(brands)) {+ issues.push(issue([...base, 'brands'], `Theme brands for ${mode} must be an object`));+ } else {+ issues.push(...collectBrandIssues(brands, [...base, 'brands']));+ }+ return issues;+}++/** Every reason a definition cannot be painted; empty when it can. */+export function collectThemeIssues(theme: unknown): ThemeIssue[] {+ if (!isPlainThemeRecord(theme)) {+ return [issue([], 'Theme definition must be an object')];+ }++ const issues: ThemeIssue[] = Object.keys(theme)+ .filter((key) => key !== 'version' && key !== 'name' && key !== 'modes' && key !== 'brands')+ .map((key) => issue([key], `Unknown theme field: ${key}`));++ if (theme.version !== THEME_VERSION) {+ issues.push(issue(['version'], `Unsupported theme version: ${theme.version}`));+ }+ if (typeof theme.name !== 'string' || !theme.name.trim()) {+ issues.push(issue(['name'], 'Theme name is required'));+ }+ const modes = theme.modes;+ if (!isPlainThemeRecord(modes)) {+ issues.push(issue(['modes'], 'Theme modes must be an object'));+ return issues;+ }++ Object.keys(modes)+ .filter((mode) => mode !== 'light' && mode !== 'dark')+ .forEach((mode) => issues.push(issue(['modes', mode], `Unknown theme mode: ${mode}`)));++ themeModes.forEach((mode) => issues.push(...collectModeIssues(mode, modes[mode])));++ if (theme.brands !== undefined && !isPlainThemeRecord(theme.brands)) {+ issues.push(issue(['brands'], 'Theme brands must be an object'));+ } else {+ issues.push(...collectBrandIssues(theme.brands, ['brands']));+ }++ return issues;+}