Skip to content

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

🧬 test: Pin Built-In Theme Output to the Cache Epoch (#16875)

Marco Beretta5d26de6d86b3
diff --git a/client/src/Providers/__tests__/themeCache.spec.ts b/client/src/Providers/__tests__/themeCache.spec.ts
index e1e0bc951f..3bbe882899 100644
--- a/client/src/Providers/__tests__/themeCache.spec.ts
+++ b/client/src/Providers/__tests__/themeCache.spec.ts
@@ -1,5 +1,17 @@
-import { clickHouseTheme } from '@librechat/client';
-import { themeRoleFingerprint } from 'librechat-data-provider';
+import {
+ THEME_VERSION,
+ themeRoleFingerprint,
+ themeAppearanceTokens,
+} from 'librechat-data-provider';
+import {
+ themeBrandTokens,
+ themeColorTokens,
+ resolveTheme,
+ libreChatTheme,
+ clickHouseTheme,
+ validateThemeDefinition,
+} from '@librechat/client';
+import type { ThemeDefinition, ResolvedThemeStyle } from '@librechat/client';
import type { ThemeCacheEntry } from '../themeCache';
import {
themeOwner,
@@ -153,3 +165,287 @@ describe('theme cache storage', () => {
expect(localStorage.getItem(THEME_CACHE_KEY)).toBeNull();
});
});
+
+/**
+ * The baseline the cache's persisted output is pinned to. The cache version keys on the role set
+ * and a hand-bumped `THEME_CACHE_EPOCH`, so a release that changes what a cacheable theme
+ * resolves to without adding a role would replay stale styling at boot. The digest covers what
+ * the cache persists (`buildThemeCache(...).modes`, with the property order canonicalized) for
+ * `librechat` and `clickhouse`, the definitions that can enter the cache (the boot script never
+ * replays one under high contrast), and for generated definitions:
+ * - every color, brand and appearance role overridden alone, theme-wide, in light only and in
+ * dark only (the other mode absent), plus a `none` sample for each shadow-like role;
+ * - every role the resolver derives from others, found by diffing its resolved output against the
+ * bare theme, with all of its sources named together and again with the role named as well, theme-wide and per mode, so
+ * fallback precedence and opting out are covered without listing the chains by hand;
+ * - every brand set theme-wide, in light and in dark with conflicting values;
+ * - definitions with one or both mode blocks absent.
+ * A new role, or a new fallback, joins by construction.
+ */
+const PIN = { fingerprint: '1.2.leqd1k', digest: '1fm6x5m' };
+
+const digestOf = (text: string): string => {
+ let hash = 5381;
+ for (let i = 0; i < text.length; i++) {
+ hash = ((hash * 33) ^ text.charCodeAt(i)) >>> 0;
+ }
+ return hash.toString(36);
+};
+
+/** Locale-independent, so the digest does not depend on the collation Jest runs under. */
+const byCodePoint = (a: string, b: string): number => (a < b ? -1 : Number(a > b));
+
+const APPEARANCE_CANDIDATES = [
+ '0.5rem',
+ '1.25rem',
+ 'soft',
+ 'dim',
+ 'fill',
+ '600',
+ '0.5',
+ '150ms',
+ '9rem',
+ '0 1px 2px 0 rgb(0 0 0 / 0.2)',
+ 'ui-sans-serif, sans-serif',
+ '1.5',
+ 'ring',
+ 'border',
+ 'none',
+];
+
+type Scope = 'both' | 'light' | 'dark';
+type Mode = 'light' | 'dark';
+type Overrides = {
+ colors?: Record<string, string>;
+ appearance?: Record<string, string>;
+ brands?: Record<string, string>;
+};
+type Fixture = { key: string; theme: ThemeDefinition };
+
+const SCOPES: Scope[] = ['both', 'light', 'dark'];
+const MODES: Mode[] = ['light', 'dark'];
+const COLOR_SENTINEL: Record<Mode, (index: number) => string> = {
+ light: (index) => `${10 + index} 20 30`,
+ dark: (index) => `${200 - index} 210 220`,
+};
+
+/** A definition whose inactive mode block is absent, not empty. */
+const define = (
+ name: string,
+ overrides: (mode: Mode) => Overrides,
+ scope: Scope,
+ wideBrands?: Record<string, string>,
+): ThemeDefinition =>
+ ({
+ version: THEME_VERSION,
+ name,
+ ...(wideBrands && { brands: wideBrands }),
+ modes: Object.fromEntries(
+ MODES.filter((mode) => scope === 'both' || scope === mode).map((mode) => [
+ mode,
+ overrides(mode),
+ ]),
+ ),
+ }) as ThemeDefinition;
+
+const BARE = define('bare', () => ({}), 'both');
+const isValid = (theme: ThemeDefinition): boolean => validateThemeDefinition(theme).length === 0;
+
+/** Every candidate the validator accepts for each appearance role, pinned so a narrowing or widening shows. */
+const ACCEPTED: Record<string, string[]> = Object.fromEntries(
+ themeAppearanceTokens.map((token) => [
+ token,
+ APPEARANCE_CANDIDATES.filter((value) =>
+ isValid(define(token, () => ({ appearance: { [token]: value } }), 'both')),
+ ),
+ ]),
+);
+
+/** The first sample the validator accepts for an appearance role, and `none` when it takes it. */
+function appearanceSamples(token: string): string[] {
+ const accepted = ACCEPTED[token];
+ if (accepted.length === 0) {
+ throw new Error(`Add a valid sample for the appearance role ${token} to APPEARANCE_CANDIDATES`);
+ }
+ return [...new Set([accepted[0], ...accepted.filter((value) => value === 'none')])];
+}
+
+const SAMPLES = Object.fromEntries(
+ themeAppearanceTokens.map((token) => [token, appearanceSamples(token)]),
+);
+
+const colorOverrides = (tokens: readonly string[], mode: Mode): Record<string, string> =>
+ Object.fromEntries(tokens.map((token, index) => [token, COLOR_SENTINEL[mode](index)]));
+
+const appearanceOverrides = (tokens: readonly string[]): Record<string, string> =>
+ Object.fromEntries(tokens.map((token) => [token, SAMPLES[token][0]]));
+
+/** Role to the roles whose single override changes it, read from the resolver. */
+function derivedRoles(): { colors: Map<string, string[]>; appearance: Map<string, string[]> } {
+ const base = MODES.map((mode) => resolveTheme(BARE, mode));
+ const found = {
+ colors: new Map<string, Set<string>>(),
+ appearance: new Map<string, Set<string>>(),
+ };
+ const note = (kind: 'colors' | 'appearance', source: string, theme: ThemeDefinition) =>
+ MODES.forEach((mode, index) => {
+ const resolved = resolveTheme(theme, mode);
+ const before = base[index][kind] as Record<string, unknown>;
+ const after = resolved[kind] as Record<string, unknown>;
+ Object.keys(after)
+ .filter((key) => key !== source && after[key] !== before[key])
+ .forEach((key) => found[kind].set(key, (found[kind].get(key) ?? new Set()).add(source)));
+ });
+ themeColorTokens.forEach((token) =>
+ note(
+ 'colors',
+ token,
+ define(token, (mode) => ({ colors: colorOverrides([token], mode) }), 'both'),
+ ),
+ );
+ themeAppearanceTokens.forEach((token) =>
+ note(
+ 'appearance',
+ token,
+ define(token, () => ({ appearance: appearanceOverrides([token]) }), 'both'),
+ ),
+ );
+ const sorted = (map: Map<string, Set<string>>) =>
+ new Map([...map].map(([key, sources]) => [key, [...sources].sort()] as [string, string[]]));
+ return { colors: sorted(found.colors), appearance: sorted(found.appearance) };
+}
+
+function roleFixtures(): Fixture[] {
+ const colors = themeColorTokens.flatMap((token) =>
+ SCOPES.map((scope) => ({
+ key: `color:${token}:${scope}`,
+ theme: define(token, (mode) => ({ colors: colorOverrides([token], mode) }), scope),
+ })),
+ );
+ const brands = themeBrandTokens.flatMap((token) => [
+ {
+ key: `brand:${token}:wide`,
+ theme: define(token, () => ({}), 'both', { [token]: '#123456' }),
+ },
+ ...MODES.map((mode) => ({
+ key: `brand:${token}:${mode}`,
+ theme: define(token, () => ({ brands: { [token]: '#123456' } }), mode),
+ })),
+ {
+ key: `brand:${token}:conflict`,
+ theme: define(
+ token,
+ (mode) => ({ brands: { [token]: mode === 'light' ? '#aa0000' : '#00aa00' } }),
+ 'both',
+ { [token]: '#0000aa' },
+ ),
+ },
+ ]);
+ const appearance = themeAppearanceTokens.flatMap((token) =>
+ SAMPLES[token].flatMap((value, index) =>
+ SCOPES.map((scope) => ({
+ key: `appearance:${token}:${index}:${scope}`,
+ theme: define(token, () => ({ appearance: { [token]: value } }), scope),
+ })),
+ ),
+ );
+ return [...colors, ...brands, ...appearance];
+}
+
+/** Each derived role with all of its sources named together, then with the role named as well. */
+function derivedFixtures(): Fixture[] {
+ const { colors, appearance } = derivedRoles();
+ const fixtures = (
+ kind: 'color' | 'appearance',
+ chains: Map<string, string[]>,
+ overrides: (tokens: string[], mode: Mode) => Overrides,
+ ) =>
+ [...chains].flatMap(([target, sources]) =>
+ SCOPES.flatMap((scope) => [
+ {
+ key: `derived:${kind}:${target}:sources:${scope}`,
+ theme: define(target, (mode) => overrides(sources, mode), scope),
+ },
+ {
+ key: `derived:${kind}:${target}:named:${scope}`,
+ theme: define(target, (mode) => overrides([...sources, target], mode), scope),
+ },
+ ]),
+ );
+ return [
+ ...fixtures('color', colors, (tokens, mode) => ({ colors: colorOverrides(tokens, mode) })),
+ ...fixtures('appearance', appearance, (tokens) => ({
+ appearance: appearanceOverrides(tokens),
+ })),
+ ];
+}
+
+/** Mode blocks that are missing or empty, on a bare theme and on a bundled one. */
+function modeFixtures(): Fixture[] {
+ const without = (theme: ThemeDefinition, mode: Mode): ThemeDefinition => {
+ const modes = { ...theme.modes };
+ delete modes[mode];
+ return { ...theme, modes };
+ };
+ return [
+ { key: 'modes:none', theme: { version: THEME_VERSION, name: 'none', modes: {} } },
+ { key: 'modes:empty', theme: define('empty', () => ({}), 'both') },
+ { key: 'modes:clickhouse:no-light', theme: without(clickHouseTheme, 'light') },
+ { key: 'modes:clickhouse:no-dark', theme: without(clickHouseTheme, 'dark') },
+ ];
+}
+
+/** Property order is positional in the cache entry and means nothing to the page. */
+const canonical = ({ properties, attributes }: ResolvedThemeStyle) => ({
+ properties: [...properties].sort(([a], [b]) => byCodePoint(a, b)),
+ attributes: Object.fromEntries(Object.entries(attributes).sort(([a], [b]) => byCodePoint(a, b))),
+});
+
+const persistedOutput = () => {
+ const fixtures: Fixture[] = [
+ { key: 'a:librechat', theme: libreChatTheme },
+ { key: 'a:clickhouse', theme: clickHouseTheme },
+ ...roleFixtures(),
+ ...derivedFixtures(),
+ ...modeFixtures(),
+ ].sort((a, b) => byCodePoint(a.key, b.key));
+ return fixtures.map(({ key, theme }) => {
+ const { light, dark } = buildThemeCache(OWNER, key, theme).modes;
+ return [key, canonical(light), canonical(dark)];
+ });
+};
+
+/** What the contributor has to do, or an empty string when the pin is current. */
+function pinStatus(actual: typeof PIN): string {
+ const refreshed = JSON.stringify(actual);
+ if (actual.fingerprint !== PIN.fingerprint) {
+ return `The cache version changed (role set, theme version or epoch), which already retires cached entries: set PIN to ${refreshed}.`;
+ }
+ if (actual.digest !== PIN.digest) {
+ return `The persisted output or the accepted appearance values changed without a version change: bump THEME_CACHE_EPOCH in packages/data-provider/src/theme.ts, then set PIN to the refreshed fingerprint and digest (digest ${actual.digest}).`;
+ }
+ return '';
+}
+
+describe('resolver output pin', () => {
+ it('matches the persisted output of every cacheable definition and generated fixture', () => {
+ const status = pinStatus({
+ fingerprint: themeRoleFingerprint(),
+ digest: digestOf(JSON.stringify({ accepted: ACCEPTED, output: persistedOutput() })),
+ });
+ expect(status).toBe('');
+ });
+
+ it('finds the fallback chains in the resolver, not in a list', () => {
+ const { colors, appearance } = derivedRoles();
+ expect(colors.get('rgb-surface-code')).toContain('rgb-surface-primary-alt');
+ expect(colors.get('rgb-link-prose')).toContain('rgb-link');
+ expect(appearance.get('menuShadow')).toContain('shadowLg');
+ });
+
+ it('tells a version change from an output change', () => {
+ expect(pinStatus({ ...PIN, fingerprint: 'other' })).toMatch(/cache version changed/);
+ expect(pinStatus({ ...PIN, digest: 'other' })).toMatch(/bump THEME_CACHE_EPOCH/);
+ expect(pinStatus(PIN)).toBe('');
+ });
+});