@adea-ai/app-framework 0.29.3 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +6 -3
  2. package/dist/app/application.js +4 -2
  3. package/dist/app/create-application.d.ts +2 -0
  4. package/dist/app/create-application.js +6 -0
  5. package/dist/appearance/appearance-host.js +6 -0
  6. package/dist/appearance/appearance-preferences.js +6 -2
  7. package/dist/appearance/composition.d.ts +1 -1
  8. package/dist/appearance/custom-theme-import.js +12 -19
  9. package/dist/appearance/custom-theme-library.d.ts +5 -4
  10. package/dist/appearance/custom-theme-library.js +20 -2
  11. package/dist/appearance/editor.js +4 -1
  12. package/dist/appearance/legacy-imported-theme-token-projection.d.ts +84 -0
  13. package/dist/appearance/legacy-imported-theme-token-projection.js +142 -0
  14. package/dist/appearance/theme-record-adapter.js +37 -9
  15. package/dist/cli/create-application-cli.js +6 -4
  16. package/dist/framework-source.json +1 -1
  17. package/dist/shell/app-shell.js +76 -48
  18. package/dist/shell/app-utilities.d.ts +5 -3
  19. package/dist/shell/app-utilities.js +15 -7
  20. package/dist/shell/help-shortcuts.d.ts +4 -0
  21. package/dist/shell/help-shortcuts.js +38 -7
  22. package/dist/shell/keyboard-target.d.ts +2 -0
  23. package/dist/shell/keyboard-target.js +54 -0
  24. package/dist/shell/settings-sections.d.ts +5 -0
  25. package/dist/shell/settings-shortcuts.d.ts +10 -0
  26. package/dist/shell/settings-shortcuts.js +67 -0
  27. package/dist/views/app-help.js +2 -1
  28. package/dist/views/app-settings.js +5 -2
  29. package/dist/views/appearance-surface.js +33 -19
  30. package/package.json +6 -4
  31. package/src/app/application.tsx +3 -1
  32. package/src/appearance/appearance-host.tsx +6 -0
  33. package/src/appearance/appearance-preferences.ts +7 -1
  34. package/src/appearance/composition.ts +3 -1
  35. package/src/appearance/custom-theme-import.ts +21 -37
  36. package/src/appearance/custom-theme-library.ts +21 -5
  37. package/src/appearance/editor.ts +7 -6
  38. package/src/appearance/legacy-imported-theme-token-projection.ts +51 -0
  39. package/src/appearance/theme-record-adapter.ts +58 -11
  40. package/src/shell/app-shell.tsx +88 -58
  41. package/src/shell/app-utilities.tsx +29 -17
  42. package/src/shell/help-shortcuts.ts +77 -6
  43. package/src/shell/keyboard-target.ts +74 -0
  44. package/src/shell/settings-sections.ts +5 -0
  45. package/src/shell/settings-shortcuts.ts +116 -0
  46. package/src/views/app-settings.tsx +5 -3
  47. package/src/views/appearance-surface.tsx +63 -27
  48. package/templates/application/.gitlab-ci.yml +19 -0
  49. package/templates/application/README.md +9 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/app-framework",
3
- "version": "0.29.3",
3
+ "version": "0.31.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -361,7 +361,8 @@
361
361
  },
362
362
  "scripts": {
363
363
  "test": "bun test --timeout=${ADEA_TEST_TIMEOUT_MS:-5000} tests/*/*.test.ts && bun run test:ui",
364
- "test:ui": "bun test --timeout=${ADEA_TEST_TIMEOUT_MS:-5000} --conditions=browser --preload @adea-ai/ui/testing/solid-transform tests/*/*.test.tsx",
364
+ "test:ui": "bun test --isolate --timeout=${ADEA_TEST_TIMEOUT_MS:-5000} --conditions=browser --preload @adea-ai/ui/testing/solid-transform tests/*/*.test.tsx",
365
+ "test:sidebar-responsive-matrix": "bash scripts/test-sidebar-responsive-matrix.sh",
365
366
  "test:theme-browser": "bun scripts/test-theme-library-browser.ts",
366
367
  "build": "vp build && tsc -p tsconfig.json --emitDeclarationOnly && bun build src/cli/update-helper-cli.ts --target=bun --outfile dist/update-helper.bundle.js && bun scripts/write-framework-source.ts",
367
368
  "typecheck": "bun check -p tsconfig.test.json",
@@ -377,12 +378,13 @@
377
378
  "tar": "^7.5.22"
378
379
  },
379
380
  "devDependencies": {
380
- "@adea-ai/ui": "0.150.0",
381
+ "@adea-ai/ui": "0.151.12",
381
382
  "@babel/core": "8.0.10",
382
383
  "@babel/preset-typescript": "^8.0.1",
383
384
  "@happy-dom/global-registrator": "^21.0.4",
384
385
  "@playwright/test": "1.64.1",
385
386
  "@shadcn/lint": "^0.2.0",
387
+ "@tailwindcss/vite": "^4.3.3",
386
388
  "@types/bun": "^1.4.4",
387
389
  "@types/node": "^26.0.0",
388
390
  "babel-preset-solid": "^1.9.15",
@@ -398,7 +400,7 @@
398
400
  "vite-plus": "1.4.0"
399
401
  },
400
402
  "peerDependencies": {
401
- "@adea-ai/ui": "^0.146.10 || ^0.147.0 || ^0.148.0 || ^0.149.0 || ^0.150.0 || ^0.151.0",
403
+ "@adea-ai/ui": "^0.151.12",
402
404
  "lucide-solid": "^1.51.0",
403
405
  "solid-js": "^1.9.15"
404
406
  },
@@ -113,8 +113,9 @@ export function Application(props: ApplicationProps) {
113
113
  })
114
114
  const view = createMemo(() => {
115
115
  routerRevision()
116
+ const selected = props.router?.current() ?? localView()
116
117
  return (
117
- props.definition.views.find((item) => item.id === (props.router?.current() ?? localView())) ??
118
+ props.definition.views.find((item) => item.id === selected) ??
118
119
  props.definition.views.find((item) => item.id === props.definition.initialView)!
119
120
  )
120
121
  })
@@ -167,6 +168,7 @@ export function Application(props: ApplicationProps) {
167
168
  props.utilities?.help && {
168
169
  search: Boolean(props.onSearch),
169
170
  ...props.utilities.help,
171
+ searchBinding: Boolean(props.onSearch),
170
172
  }
171
173
  }
172
174
  identity={props.definition.identity}
@@ -25,6 +25,7 @@ import {
25
25
  type ThemeContextValue as UiThemeContextValue,
26
26
  type ThemeProviderProps as UiThemeProviderProps,
27
27
  } from '@adea-ai/ui/components/theme/lazy'
28
+ import { projectThemeTokens as tokenProjector } from '@adea-ai/ui/components/theme/token-projection'
28
29
  import { defaultPreferenceStorage } from '@adea-ai/ui/lib/preference-store'
29
30
  import { tokensAsHex } from '@adea-ai/ui/lib/themes'
30
31
 
@@ -40,6 +41,7 @@ import {
40
41
  readCustomThemeLibrary,
41
42
  subscribeCustomThemes,
42
43
  } from './custom-theme-library'
44
+ import { LEGACY_IMPORTED_THEME_TOKEN_PROJECTION } from './legacy-imported-theme-token-projection'
43
45
 
44
46
  export type {
45
47
  AppearanceMode,
@@ -99,6 +101,10 @@ export function appearanceProviderProps(
99
101
  palette: 'stylesheet',
100
102
  accentContrastFloor: APPEARANCE_ACCENT_CONTRAST_FLOOR,
101
103
  editorRoles: 'floor',
104
+ tokenProjection: {
105
+ rules: LEGACY_IMPORTED_THEME_TOKEN_PROJECTION,
106
+ project: tokenProjector,
107
+ },
102
108
  transformTokens: tokensAsHex,
103
109
  disableTransitionOnChange: true,
104
110
  fontZoom: true,
@@ -11,12 +11,12 @@ import { getAccent } from '@adea-ai/ui/lib/accent-presets'
11
11
 
12
12
  import {
13
13
  createVersionedPersistence,
14
- themeScript,
15
14
  type ThemePersistence,
16
15
  type ThemeSelection,
17
16
  type ThemeStorageSchema,
18
17
  type VersionedCodec,
19
18
  } from '@adea-ai/ui/components/theme/lazy'
19
+ import { themeScript } from '@adea-ai/ui/components/theme/script-projection'
20
20
  import { colorToHex, parseColor } from '@adea-ai/ui/lib/accent-roles'
21
21
  import {
22
22
  DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
@@ -25,6 +25,10 @@ import {
25
25
  } from '@adea-ai/ui/lib/appearance-font-settings'
26
26
  import { normalizeSurface as normalizeThemeSurface } from '@adea-ai/ui/lib/theme-surface'
27
27
  import { isThemeAccentId } from '@adea-ai/ui/lib/themes'
28
+ import {
29
+ LEGACY_IMPORTED_THEME_TOKEN_PROJECTION,
30
+ LEGACY_IMPORTED_THEME_TOKEN_PROJECTION_FALLBACKS,
31
+ } from './legacy-imported-theme-token-projection'
28
32
 
29
33
  /**
30
34
  * The versioned client appearance preference (Dev Runtime spec,
@@ -283,5 +287,7 @@ export function appearanceThemeScript(): string {
283
287
  defaultAccent: DEFAULT_ACCENT_PRESET_ID,
284
288
  surface: true,
285
289
  palette: 'stylesheet',
290
+ tokenProjection: LEGACY_IMPORTED_THEME_TOKEN_PROJECTION,
291
+ tokenProjectionFallbacks: LEGACY_IMPORTED_THEME_TOKEN_PROJECTION_FALLBACKS,
286
292
  })
287
293
  }
@@ -17,7 +17,9 @@ import type { AppearancePreferencesV2 } from './appearance-preferences'
17
17
  * draft so the System split, Light, and Dark cards track unsaved theme picks
18
18
  * the same instant the real chrome does.
19
19
  */
20
- export function draftVariants(preferences: AppearancePreferencesV2): {
20
+ export function draftVariants(
21
+ preferences: Pick<AppearancePreferencesV2, 'lightThemeId' | 'darkThemeId'>
22
+ ): {
21
23
  light: ThemeVariant
22
24
  dark: ThemeVariant
23
25
  } {
@@ -26,6 +26,7 @@ import {
26
26
  syntaxRolesHex,
27
27
  toXtermTheme,
28
28
  } from '@adea-ai/ui/lib/theme-projection'
29
+ import { projectThemeTokens } from '@adea-ai/ui/components/theme/token-projection'
29
30
  import type { AdeaTheme } from '@adea-ai/ui/lib/theme-records'
30
31
  import {
31
32
  mutateCustomThemeLibrary,
@@ -37,6 +38,7 @@ import {
37
38
  type StoredThemeColors as ThemeColors,
38
39
  type StoredThemeVariant as ThemeVariant,
39
40
  } from './custom-theme-library'
41
+ import { LEGACY_IMPORTED_THEME_TOKEN_PROJECTION } from './legacy-imported-theme-token-projection'
40
42
 
41
43
  const CANONICAL_COLOR_KEYS = [
42
44
  'background',
@@ -206,42 +208,6 @@ function repairComponentContrast(variant: ThemeVariant, notes: string[]): ThemeV
206
208
  }
207
209
  }
208
210
 
209
- /** Preserve accessible sidebar pairs that the catalogue record would otherwise re-derive. */
210
- function sidebarTokens(variant: ThemeVariant, notes: string[]): Record<string, string> {
211
- const colors = variant.colors
212
- return {
213
- '--sidebar': colors.card,
214
- '--sidebar-foreground': repairToFloor(
215
- colors.cardForeground,
216
- colors.card,
217
- notes,
218
- 'sidebar foreground'
219
- ),
220
- '--sidebar-muted-foreground': repairToFloor(
221
- colors.mutedForeground,
222
- colors.card,
223
- notes,
224
- 'sidebar muted foreground'
225
- ),
226
- '--sidebar-accent': colors.accent,
227
- '--sidebar-accent-foreground': repairToFloor(
228
- colors.accentForeground,
229
- colors.accent,
230
- notes,
231
- 'sidebar accent foreground'
232
- ),
233
- '--sidebar-border': colors.border,
234
- '--sidebar-primary': colors.primary,
235
- '--sidebar-primary-foreground': repairToFloor(
236
- colors.primaryForeground,
237
- colors.primary,
238
- notes,
239
- 'sidebar primary foreground'
240
- ),
241
- '--sidebar-ring': colors.ring,
242
- }
243
- }
244
-
245
211
  function hexOf(value: string): string {
246
212
  const parsed = parseOklchColor(value)
247
213
  return parsed ? oklchToHex(parsed) : value
@@ -456,13 +422,31 @@ function prepareCustomTheme(
456
422
  const issues = validateThemeRegistry([variant]).filter((issue) => issue.severity === 'error')
457
423
  for (const issue of issues) notes.push(`${issue.variantId}: ${issue.message}`)
458
424
 
425
+ const flatTokens = flatVariantTokens(variant)
426
+ const projectedTokens = projectThemeTokens(flatTokens, LEGACY_IMPORTED_THEME_TOKEN_PROJECTION)
427
+ for (const rule of LEGACY_IMPORTED_THEME_TOKEN_PROJECTION) {
428
+ const sourceValue = flatTokens[rule.source]
429
+ const projectedValue = projectedTokens[rule.target]
430
+ if (
431
+ !('contrast' in rule) ||
432
+ flatTokens[rule.target] !== undefined ||
433
+ sourceValue === undefined ||
434
+ projectedValue === undefined ||
435
+ projectedValue === sourceValue
436
+ ) {
437
+ continue
438
+ }
439
+ const role = rule.target.slice(2).replaceAll('-', ' ')
440
+ notes.push(`“${role}” was adjusted for readable contrast.`)
441
+ }
442
+
459
443
  const stored: CustomThemeStored = {
460
444
  id: variant.id,
461
445
  name: variant.name,
462
446
  appearance,
463
447
  importedAt: new Date().toISOString(),
464
448
  variant,
465
- flatTokens: { ...flatVariantTokens(variant), ...sidebarTokens(variant, notes) },
449
+ flatTokens,
466
450
  notes,
467
451
  }
468
452
  return { ok: true, theme: stored }
@@ -16,6 +16,8 @@ import { defaultVariantFor } from '@adea-ai/ui/lib/theme-defaults'
16
16
  import { variantFromRecord } from '@adea-ai/ui/lib/theme-records'
17
17
  import type { ThemeVariant as UiThemeVariant } from '@adea-ai/ui/lib/themes'
18
18
 
19
+ import { LEGACY_IMPORTED_THEME_TOKEN_PROJECTION_FALLBACKS } from './legacy-imported-theme-token-projection'
20
+
19
21
  /**
20
22
  * The custom theme library: themes the user imported from a file, stored in
21
23
  * `localStorage` and handed to the provider as extra variants. Import and
@@ -25,8 +27,8 @@ import type { ThemeVariant as UiThemeVariant } from '@adea-ai/ui/lib/themes'
25
27
  *
26
28
  * The stored shape is a compatibility surface. Imported themes written by any
27
29
  * earlier build keep resolving: `variant` stays in the host shape below and
28
- * `flatTokens` stays the verbatim token map, so what a user imported is what is
29
- * painted.
30
+ * `flatTokens` stays the verbatim token map. Explicit entries remain authoritative;
31
+ * the sidebar projection recovers only absent source entries from `variant`.
30
32
  */
31
33
 
32
34
  export type StoredThemeAppearance = 'light' | 'dark'
@@ -112,7 +114,7 @@ export type CustomThemeStored = Readonly<{
112
114
  appearance: StoredThemeAppearance
113
115
  importedAt: string
114
116
  variant: StoredThemeVariant
115
- /** The flat token map the no-flash script applies for a stored selection. */
117
+ /** The verbatim imported map; projection may supply absent sources from `variant`. */
116
118
  flatTokens: Readonly<Record<string, string>>
117
119
  /** Non-fatal adjustments made while normalizing the file, for the UI. */
118
120
  notes: readonly string[]
@@ -369,7 +371,8 @@ export function storedVariantRecord(variant: StoredThemeVariant): AdeaThemeRecor
369
371
 
370
372
  /**
371
373
  * The shared-provider variant for a stored theme: derived roles from the
372
- * reconstructed record, then `flatTokens` verbatim.
374
+ * reconstructed record, missing sidebar projection sources from the stored variant,
375
+ * then every stored flat token verbatim.
373
376
  *
374
377
  * A record the shared projection cannot map falls back to the default theme of the
375
378
  * same appearance under the stored identity, so an import that the projection
@@ -397,7 +400,20 @@ export function toUiVariant(stored: CustomThemeStored): UiThemeVariant {
397
400
  },
398
401
  }
399
402
  }
400
- return { ...base, tokens: stored.flatTokens }
403
+ const projectionSources: Record<string, string> = {}
404
+ for (const fallback of LEGACY_IMPORTED_THEME_TOKEN_PROJECTION_FALLBACKS) {
405
+ if (Object.hasOwn(stored.flatTokens, fallback.token)) continue
406
+ let value: unknown = stored
407
+ for (const key of fallback.path) {
408
+ if (!value || typeof value !== 'object' || !Object.hasOwn(value, key)) {
409
+ value = undefined
410
+ break
411
+ }
412
+ value = (value as Record<string, unknown>)[key]
413
+ }
414
+ if (typeof value === 'string') projectionSources[fallback.token] = value
415
+ }
416
+ return { ...base, tokens: { ...projectionSources, ...stored.flatTokens } }
401
417
  }
402
418
 
403
419
  /*
@@ -54,14 +54,15 @@ const scalarFields = Object.keys({
54
54
  } satisfies Record<ScalarPreference, true>) as ScalarPreference[]
55
55
 
56
56
  function samePreferences(left: AppearancePreferencesV2, right: AppearancePreferencesV2): boolean {
57
+ if (left === right) return true
58
+ if (!scalarFields.every((field) => left[field] === right[field])) return false
59
+ if (left.fonts === right.fonts) return true
57
60
  const leftFonts = normalizeAppearanceEditorFontSettings(left.fonts).settings
58
61
  const rightFonts = normalizeAppearanceEditorFontSettings(right.fonts).settings
59
- return (
60
- (['ui', 'content', 'code'] as const).every(
61
- (axis) =>
62
- leftFonts[axis].family === rightFonts[axis].family &&
63
- leftFonts[axis].size === rightFonts[axis].size
64
- ) && scalarFields.every((field) => left[field] === right[field])
62
+ return (['ui', 'content', 'code'] as const).every(
63
+ (axis) =>
64
+ leftFonts[axis].family === rightFonts[axis].family &&
65
+ leftFonts[axis].size === rightFonts[axis].size
65
66
  )
66
67
  }
67
68
 
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Sidebar roles added after Framework first persisted imported theme records.
3
+ *
4
+ * Keep this as serializable data so the shared provider and its pre-paint script
5
+ * apply the same rules when they restore a legacy v1 record. The projection fills
6
+ * only absent sidebar tokens; values already stored in the user's library win.
7
+ */
8
+ export const LEGACY_IMPORTED_THEME_TOKEN_PROJECTION = [
9
+ { target: '--sidebar', source: '--card' },
10
+ {
11
+ target: '--sidebar-foreground',
12
+ source: '--card-foreground',
13
+ contrast: { against: '--sidebar', minimum: 4.5 },
14
+ },
15
+ {
16
+ target: '--sidebar-muted-foreground',
17
+ source: '--muted-foreground',
18
+ contrast: { against: '--sidebar', minimum: 4.5 },
19
+ },
20
+ { target: '--sidebar-accent', source: '--accent' },
21
+ {
22
+ target: '--sidebar-accent-foreground',
23
+ source: '--accent-foreground',
24
+ contrast: { against: '--sidebar-accent', minimum: 4.5 },
25
+ },
26
+ { target: '--sidebar-border', source: '--border' },
27
+ { target: '--sidebar-primary', source: '--primary' },
28
+ {
29
+ target: '--sidebar-primary-foreground',
30
+ source: '--primary-foreground',
31
+ contrast: { against: '--sidebar-primary', minimum: 4.5 },
32
+ },
33
+ { target: '--sidebar-ring', source: '--ring' },
34
+ ] as const
35
+
36
+ /**
37
+ * Older accepted v1 records can omit base flat tokens while retaining their full
38
+ * variant. Both the provider adapter and opt-in prepaint script use these declared
39
+ * paths to recover only those absent projection sources from the unchanged record.
40
+ */
41
+ export const LEGACY_IMPORTED_THEME_TOKEN_PROJECTION_FALLBACKS = [
42
+ { token: '--card', path: ['variant', 'colors', 'card'] },
43
+ { token: '--card-foreground', path: ['variant', 'colors', 'cardForeground'] },
44
+ { token: '--muted-foreground', path: ['variant', 'colors', 'mutedForeground'] },
45
+ { token: '--accent', path: ['variant', 'colors', 'accent'] },
46
+ { token: '--accent-foreground', path: ['variant', 'colors', 'accentForeground'] },
47
+ { token: '--border', path: ['variant', 'colors', 'border'] },
48
+ { token: '--primary', path: ['variant', 'colors', 'primary'] },
49
+ { token: '--primary-foreground', path: ['variant', 'colors', 'primaryForeground'] },
50
+ { token: '--ring', path: ['variant', 'colors', 'ring'] },
51
+ ] as const
@@ -6,7 +6,12 @@
6
6
  * published editor the catalogue's own theme records (the shared ThemeProvider
7
7
  * paints from the same catalogue), plus a record per imported theme.
8
8
  */
9
- import { colorToHex, normalizeAccentValue, parseColor } from '@adea-ai/ui/lib/accent-roles'
9
+ import {
10
+ colorToHex,
11
+ normalizeAccentValue,
12
+ parseColor,
13
+ type AccentRoles,
14
+ } from '@adea-ai/ui/lib/accent-roles'
10
15
  import { getAccent } from '@adea-ai/ui/lib/accent-presets'
11
16
  import { defaultThemeRecord } from '@adea-ai/ui/lib/theme-projection'
12
17
  import type { AdeaTheme, AdeaThemeRecord } from '@adea-ai/ui/lib/theme-records'
@@ -14,6 +19,7 @@ import {
14
19
  accentRolesForSelection,
15
20
  themeRecordById,
16
21
  themeRecords,
22
+ tokensAsHex,
17
23
  type ThemeVariant,
18
24
  } from '@adea-ai/ui/lib/themes'
19
25
 
@@ -22,11 +28,15 @@ import {
22
28
  customThemeVariantById,
23
29
  customThemeVariants,
24
30
  storedVariantRecord,
31
+ type StoredThemeVariant,
25
32
  } from './custom-theme-library'
26
33
  import { themeRegistry } from './theme-registry'
27
34
 
28
35
  const adeaLight = defaultThemeRecord('light')
29
36
  const adeaDark = defaultThemeRecord('dark')
37
+ const MAX_ACCENT_PREVIEWS_PER_THEME = 16
38
+ const accentRolesByTheme = new WeakMap<AdeaTheme, Map<string, AccentRoles | null>>()
39
+ const importedRecordsByVariant = new WeakMap<StoredThemeVariant, AdeaThemeRecord>()
30
40
 
31
41
  /** The published blue preset is the host's default custom accent. */
32
42
  export const DEFAULT_CUSTOM_ACCENT = getAccent('blue')?.light ?? adeaLight.colors.accent
@@ -36,6 +46,35 @@ export function customThemeRecords(): readonly AdeaThemeRecord[] {
36
46
  return customThemeVariants().map(storedVariantRecord)
37
47
  }
38
48
 
49
+ function importedRecordForPreview(variant: StoredThemeVariant): AdeaThemeRecord {
50
+ const cached = importedRecordsByVariant.get(variant)
51
+ if (cached) return cached
52
+ const record = storedVariantRecord(variant)
53
+ importedRecordsByVariant.set(variant, record)
54
+ return record
55
+ }
56
+
57
+ function accentRolesForPreview(
58
+ theme: AdeaTheme,
59
+ key: string | undefined,
60
+ resolve: () => AccentRoles | undefined
61
+ ): AccentRoles | undefined {
62
+ if (!key) return resolve()
63
+ const cached = accentRolesByTheme.get(theme)
64
+ if (cached?.has(key)) return cached.get(key) ?? undefined
65
+
66
+ const roles = resolve()
67
+ const byKey = cached ?? new Map<string, AccentRoles | null>()
68
+ byKey.delete(key)
69
+ byKey.set(key, roles ?? null)
70
+ if (byKey.size > MAX_ACCENT_PREVIEWS_PER_THEME) {
71
+ const oldest = byKey.keys().next().value
72
+ if (oldest !== undefined) byKey.delete(oldest)
73
+ }
74
+ accentRolesByTheme.set(theme, byKey)
75
+ return roles
76
+ }
77
+
39
78
  /** The built-in catalogue led by the published pair; import lives separately. */
40
79
  export const appearanceThemeRecords: readonly AdeaThemeRecord[] = Object.freeze([
41
80
  adeaLight,
@@ -54,14 +93,20 @@ function withAccent(
54
93
  pair: { lightThemeId: string; darkThemeId: string } | undefined
55
94
  ): AdeaTheme {
56
95
  if (accent === 'theme') return theme
57
- const variant = themeRegistry().find((candidate) => candidate.id === theme.id)
58
- // The 3:1 floor needs the variant's background. A record whose variant has
59
- // vanished previews its own accent rather than throwing mid-interaction.
60
- if (!variant) return theme
61
- const roles = accentRolesForSelection(accent, theme.appearance, pair, {
62
- background: variant.colors.background,
63
- floor: APPEARANCE_ACCENT_CONTRAST_FLOOR,
64
- variantId: variant.id,
96
+ // Named presets depend on the immutable preview record. Theme-derived accents
97
+ // also depend on the live light/dark pair and custom hex values can be high
98
+ // cardinality, so neither is cached.
99
+ const cacheKey = getAccent(accent) ? accent : undefined
100
+ const roles = accentRolesForPreview(theme, cacheKey, () => {
101
+ const variant = themeRegistry().find((candidate) => candidate.id === theme.id)
102
+ // The 3:1 floor needs the variant's background. A record whose variant has
103
+ // vanished previews its own accent rather than throwing mid-interaction.
104
+ if (!variant) return undefined
105
+ return accentRolesForSelection(accent, theme.appearance, pair, {
106
+ background: variant.colors.background,
107
+ floor: APPEARANCE_ACCENT_CONTRAST_FLOOR,
108
+ variantId: variant.id,
109
+ })
65
110
  })
66
111
  if (!roles) return theme
67
112
  return {
@@ -91,7 +136,7 @@ export function appearanceThemeForPreview(
91
136
  const record =
92
137
  catalogueRecord ??
93
138
  (importedVariant
94
- ? storedVariantRecord(importedVariant)
139
+ ? importedRecordForPreview(importedVariant)
95
140
  : variant.appearance === 'dark'
96
141
  ? adeaDark
97
142
  : adeaLight)
@@ -105,7 +150,9 @@ type AccentDraftValidation = Readonly<{
105
150
 
106
151
  /** Preserve the host's invalid-input behavior while feeding the pure editor. */
107
152
  export function normalizeCustomAccent(value: string, background: string): AccentDraftValidation {
108
- const normalized = normalizeAccentValue(value, background)
153
+ // The shared accent helper accepts hex, while catalogue themes use OKLCH.
154
+ const canvas = tokensAsHex({ background }).background ?? background
155
+ const normalized = normalizeAccentValue(value, canvas)
109
156
  if (normalized === undefined) {
110
157
  return { error: `“${value}” is not a hex color such as ${DEFAULT_CUSTOM_ACCENT}.` }
111
158
  }