@adea-ai/ui 0.124.0 → 0.127.0

package/dist/r/src/lib/theme-surface.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2026 Wing
+ * Licensed under the MIT License.
+ *
+ * `resolveSurface` is Zeron's `SurfacePreference.resolve` (https://github.com/zeronsh/zeron),
+ * extended by Adea's accepted port of it (`packages/ui/src/components/appearance.ts`)
+ * with the translucent capability gate and the reduced-transparency policy. Moved
+ * here so the shared provider and Adea run one implementation. See NOTICE.
+ */
+
+/**
+ * The surface axis, and the policy that decides what it paints.
+ *
+ * A surface is how opaque the window's elevated panels are: `opaque` is the plain
+ * canvas, `frosted` is a tokenized translucent fill over a blur (works everywhere,
+ * in CSS alone), and `translucent` asks for the host window's own vibrancy, which only
+ * a desktop shell can honour.
+ *
+ * Nothing here touches the document or a signal. The provider reads the operating
+ * system and the host's capability, calls {@link resolveSurface}, and
+ * `theme-document.ts` writes the answer; the rule itself is a function of its four
+ * inputs, which is what makes it testable.
+ */
+export type ThemeSurface = 'opaque' | 'frosted' | 'translucent'
+
+/** Every surface, in the order a picker offers them. */
+export const themeSurfaces: readonly ThemeSurface[] = ['opaque', 'frosted', 'translucent']
+
+/** The media query the operating system's Reduce Transparency setting answers. */
+export const REDUCED_TRANSPARENCY_QUERY = '(prefers-reduced-transparency: reduce)'
+
+/**
+ * What the world says about transparency, as opposed to what the user prefers.
+ */
+export type SurfaceEnvironment = Readonly<{
+  /** The operating system asks for less transparency. */
+  osReducedTransparency: boolean
+  /** The user turned reduced transparency on inside the application. */
+  userReducedTransparency: boolean
+  /** The host window can render OS translucency (vibrancy, acrylic). */
+  nativeTranslucency: boolean
+}>
+
+/**
+ * A stored value as a surface, or nothing.
+ *
+ * `undefined` rather than `opaque` for an unreadable value: the selection field is
+ * optional, and an absent field is how a store that never chose a surface stays
+ * byte-identical to what it was before the axis existed.
+ */
+export function normalizeSurface(value: unknown): ThemeSurface | undefined {
+  return value === 'opaque' || value === 'frosted' || value === 'translucent' ? value : undefined
+}
+
+/**
+ * The surface to paint: the preference, after the accessibility override and the
+ * host's capability.
+ *
+ * The OS setting or the user's own flag forces an accessible opaque fallback. A
+ * translucent request on a host without native translucency renders the tokenized
+ * frosted surface instead of pretending to OS vibrancy.
+ */
+export function resolveSurface(
+  preference: ThemeSurface,
+  environment: SurfaceEnvironment
+): ThemeSurface {
+  if (environment.osReducedTransparency || environment.userReducedTransparency) return 'opaque'
+  if (preference === 'translucent' && !environment.nativeTranslucency) return 'frosted'
+  return preference
+}
+
+/**
+ * The fill opacity each surface paints, written as `--surface-alpha`.
+ *
+ * These are the values `--surface-frost` and `--surface-translucent` declare in
+ * `theme.css` (the stylesheet is the readable copy; `tests/theme-surface.test.ts`
+ * fails when the two disagree). They are numbers rather than `var()` references so
+ * the property reads the same to a script, a test and the stylesheet, whichever
+ * wrote it.
+ */
+export const surfaceAlpha: Readonly<Record<ThemeSurface, string>> = {
+  opaque: '1',
+  frosted: '0.92',
+  translucent: '0.8',
+}
+
+/** What a selection paints for the surface axis. */
+export type SurfaceState = Readonly<{
+  /** The surface after the accessibility override and capability gate. */
+  surface: ThemeSurface
+  /** True while the OS or the user forces opaque surfaces. */
+  reduceTransparencyActive: boolean
+}>
+
+/**
+ * The surface state for a preference and an environment.
+ *
+ * A preference of `undefined` is `opaque`: the axis is optional on a selection, and
+ * a host that never set it gets the plain canvas.
+ */
+export function resolveSurfaceState(
+  preference: ThemeSurface | undefined,
+  environment: SurfaceEnvironment
+): SurfaceState {
+  return {
+    surface: resolveSurface(preference ?? 'opaque', environment),
+    reduceTransparencyActive:
+      environment.osReducedTransparency || environment.userReducedTransparency,
+  }
+}

package/dist/r/src/lib/themes.ts

@@ -36,7 +36,6 @@
 import {
   ACCENTS,
   accentForeground,
-  accentRoles,
   chartSeries,
   getAccent,
   getTheme,
@@ -58,6 +57,7 @@ import {
 } from '@adea-ai/themes'
 import { shadcnVariables } from '@adea-ai/themes/adapters/shadcn'
 import { oklchToHex, parseColor } from '@adea-ai/themes/oklch'
+import { accentOverrideVariables, resolveAccentRoles, type AccentRoles } from './accent-roles'
 import { isThemeAccentId } from './theme-accents'
 
 export { isThemeAccentId } from './theme-accents'
@@ -566,26 +566,51 @@ export function accentVariables(
   pair: { lightThemeId: string; darkThemeId: string } = {
     lightThemeId: defaultLightThemeId,
     darkThemeId: defaultDarkThemeId,
-  }
+  },
+  options: AccentVariableOptions = {}
 ): Record<string, string> | undefined {
+  const roles = accentRolesForSelection(accentId, appearance, pair, options)
+  return roles ? accentOverrideVariables(roles) : undefined
+}
+
+/** What an accent is held to when it is resolved against a surface. */
+export type AccentVariableOptions = {
+  /** The surface the accent must read on: the variant's `colors.background`. */
+  background?: string
+  /**
+   * The contrast floor against `background`. Absent, a preset is painted verbatim
+   * and only a custom `#rrggbb` is held to the default floor.
+   */
+  floor?: number
+  /** The variant the accent is applied to, so the tint takes its measured strength. */
+  variantId?: string
+}
+
+/**
+ * An accent selection resolved to the full {@link AccentRoles}, against a theme
+ * pair. {@link accentVariables} is the document half of this; an element-scoped
+ * paint (`paintAccentRoles`) wants all of it, including the tint.
+ */
+export function accentRolesForSelection(
+  accentId: string,
+  appearance: ThemeAppearance,
+  pair: { lightThemeId: string; darkThemeId: string } = {
+    lightThemeId: defaultLightThemeId,
+    darkThemeId: defaultDarkThemeId,
+  },
+  options: AccentVariableOptions = {}
+): AccentRoles | undefined {
   if (accentId === 'theme') return undefined
-  const { light, dark } = recordPair(pair.lightThemeId, pair.darkThemeId)
-  const preset = resolveAccentPreset(accentId, light, dark)
-  if (!preset) return undefined
-
-  // `--primary-subtle` is deliberately not here. It is a `color-mix()` over
-  // `var(--primary)`, so the theme's own declaration (`themeCssVariables`, or the
-  // default block in `theme.css`) already follows the accent; and its strength is the
-  // *theme's*, measured by `primarySubtleAlpha` to hold body text at 4.5:1 for every
-  // accent the theme offers. Writing one here would replace that measured strength
-  // with whatever this function was given, which is how an accent used to undo it.
-  const roles = accentRoles(preset, appearance)
-  return {
-    '--primary': roles.primary,
-    '--primary-foreground': roles.primaryForeground,
-    '--primary-hover': roles.primaryHover,
-    '--ring': roles.ring,
-  }
+  const record = options.variantId ? getTheme(options.variantId) : undefined
+  return resolveAccentRoles(accentId, {
+    target: record ?? appearance,
+    background: options.background,
+    floor: options.floor,
+    // Only an `ansi-*` id needs the pair's offering, and measuring it is not free.
+    themeAccents: isThemeAccentId(accentId)
+      ? themeAccentsFor(pair.lightThemeId, pair.darkThemeId)
+      : undefined,
+  })
 }
 
 /**
@@ -708,6 +733,20 @@ export function themeCssVariables(theme: ThemeVariant): Record<string, string> {
   return theme.tokens ? { ...derived, ...theme.tokens } : derived
 }
 
+/**
+ * The `--terminal-*` properties of a variant: the palette a terminal paints.
+ *
+ * What a pinned terminal theme writes over the interface variant's own. Taken from
+ * {@link themeCssVariables} rather than rebuilt, so the names, and a custom
+ * variant's verbatim `tokens`, can never drift from what the interface variant
+ * would have written for the same palette.
+ */
+export function terminalCssVariables(theme: ThemeVariant): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(themeCssVariables(theme)).filter(([name]) => name.startsWith('--terminal-'))
+  )
+}
+
 /**
  * Token values with every `oklch()` colour written as `#rrggbb`.
  *

package/dist/r/src/lib/tokens.ts

@@ -122,6 +122,23 @@ export const colorTokens: TokenDefinition[] = [
     themed: true,
     description: 'Opacity of the chrome fill behind a blur.',
   },
+  {
+    name: 'surface-alpha',
+    kind: 'number',
+    description:
+      "The opacity a frosted dialog's fill keeps, written by the provider's surface axis. 1 is opaque and never matches the frost rule.",
+  },
+  {
+    name: 'surface-frost',
+    kind: 'number',
+    description: 'The fill opacity `--surface-alpha` takes for the frosted surface: 0.92.',
+  },
+  {
+    name: 'surface-translucent',
+    kind: 'number',
+    description:
+      'The fill opacity `--surface-alpha` takes for the translucent surface: 0.8. A host without native translucency paints frosted instead.',
+  },
 
   // The brand action
   {

package/dist/r/src/styles/theme.css

@@ -637,6 +637,15 @@
   --z-menu: 140;
   --z-tooltip: 160;
   --z-toast: 180;
+
+  /* Surface glass. `--surface-alpha` is what the provider's surface axis writes: the
+     opacity a frosted dialog's fill keeps (1 = opaque, so the default never matches
+     the frost rule's blur). `--surface-frost` and `--surface-translucent` are the two
+     amounts it chooses between; `lib/theme-surface.ts` writes the same numbers, and
+     `tests/theme-surface.test.ts` fails when they disagree. */
+  --surface-alpha: 1;
+  --surface-frost: 0.92;
+  --surface-translucent: 0.8;
 }
 
 /* Compact density: the standard control ladder one rung tighter.
@@ -687,6 +696,35 @@
   --shadow-xl: 0 20px 44px oklch(0 0 0 / 0.45);
 }
 
+/* The OS-level backstop for the surface axis. The provider resolves the effective
+   surface and the reduced-transparency policy and writes `--surface-alpha` inline,
+   which outranks this rule; this is what keeps a frost amount from outliving the
+   system's Reduce Transparency setting for a document the provider has not
+   reached yet (a server-rendered one, before hydration). */
+@media (prefers-reduced-transparency: reduce) {
+  :root {
+    --surface-alpha: 1;
+  }
+}
+
+/* Tokenized frost: while the resolved surface asks for glass, a modal dialog goes
+   translucent and blurs the content behind it. The opaque default and both
+   reduced-transparency paths resolve `--surface-alpha` to 1 and never write
+   `data-surface='frosted'`, so frost only ever applies when the user chose it and
+   the platform can honour it. Native window vibrancy (a desktop shell's translucent
+   surface) remains the shell's work; this is the frost the surface preference
+   promises everywhere else.
+
+   Modal dialogs only: a sheet carries `data-variant` and keeps its own bands. */
+[data-surface='frosted'] [role='dialog']:not([data-variant]) {
+  background-color: color-mix(
+    in srgb,
+    var(--background) calc(var(--surface-alpha) * 100%),
+    transparent
+  );
+  backdrop-filter: blur(1.25rem) saturate(140%);
+}
+
 /* ---------------------------------------------------------------------------
  * 4b. Named CSS hooks
  *

package/dist/r/theming.json

@@ -58,6 +58,11 @@
       "type": "registry:ui",
       "target": "components/theming/theme-provider.tsx"
     },
+    {
+      "path": "src/components/theme/theme-script.ts",
+      "type": "registry:ui",
+      "target": "components/theming/theme-script.ts"
+    },
     {
       "path": "src/components/theme/theme-state.ts",
       "type": "registry:ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.124.0",
+  "version": "0.127.0",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",

package/registry.json

@@ -2557,6 +2557,11 @@
           "type": "registry:ui",
           "target": "components/theming/theme-provider.tsx"
         },
+        {
+          "path": "src/components/theme/theme-script.ts",
+          "type": "registry:ui",
+          "target": "components/theming/theme-script.ts"
+        },
         {
           "path": "src/components/theme/theme-state.ts",
           "type": "registry:ui",
@@ -2644,6 +2649,11 @@
       ],
       "registryDependencies": [],
       "files": [
+        {
+          "path": "src/lib/accent-roles.ts",
+          "type": "registry:lib",
+          "target": "lib/accent-roles.ts"
+        },
         {
           "path": "src/lib/appearance-font-settings.ts",
           "type": "registry:lib",
@@ -2669,6 +2679,11 @@
           "type": "registry:lib",
           "target": "lib/font-catalog.ts"
         },
+        {
+          "path": "src/lib/font-zoom.ts",
+          "type": "registry:lib",
+          "target": "lib/font-zoom.ts"
+        },
         {
           "path": "src/lib/form-field.ts",
           "type": "registry:lib",
@@ -2684,6 +2699,11 @@
           "type": "registry:lib",
           "target": "lib/overlay.ts"
         },
+        {
+          "path": "src/lib/preference-store.ts",
+          "type": "registry:lib",
+          "target": "lib/preference-store.ts"
+        },
         {
           "path": "src/lib/safe-script.ts",
           "type": "registry:lib",
@@ -2694,6 +2714,11 @@
           "type": "registry:lib",
           "target": "lib/theme-accents.ts"
         },
+        {
+          "path": "src/lib/theme-surface.ts",
+          "type": "registry:lib",
+          "target": "lib/theme-surface.ts"
+        },
         {
           "path": "src/lib/themes.ts",
           "type": "registry:lib",

package/src/components/theme/index.ts

@@ -9,6 +9,7 @@ export {
 } from './theme-picker'
 export {
   ThemeProvider,
+  createVersionedPersistence,
   defaultThemeSelection,
   inlineScriptLiteral,
   localStoragePersistence,
@@ -20,7 +21,12 @@ export {
   type ThemeDensity,
   type ThemePersistence,
   type ThemeProviderProps,
+  type ThemeScriptOptions,
   type ThemeSelection,
+  type ThemeStorageSchema,
+  type ThemeSurface,
+  type VersionedCodec,
+  type VersionedPersistenceOptions,
 } from './theme-provider'
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
 export { ThemeModeToggle, type ThemeModeToggleProps } from './theme-mode-toggle'

package/src/components/theme/theme-document.ts

@@ -4,10 +4,14 @@ import {
 } from '#lib/appearance-font-settings'
 import {
   accentVariables,
+  terminalCssVariables,
+  themeById,
   themeCssVariables,
   type ThemeAppearance,
   type ThemeVariant,
 } from '#lib/themes'
+import { isCustomAccent } from '#lib/accent-roles'
+import { surfaceAlpha, type SurfaceState } from '#lib/theme-surface'
 import { resolvedDensity, type ThemeSelection } from './theme-state'
 
 /**
@@ -26,6 +30,16 @@ export type ThemeDocumentState = {
   selection: ThemeSelection
   appearance: ThemeAppearance
   variant: ThemeVariant
+  /**
+   * The variant whose terminal palette is pinned over the interface variant's.
+   * Absent, the terminal follows the interface theme.
+   */
+  terminalVariant?: ThemeVariant
+  /**
+   * The resolved surface axis. Absent, the axis is off: no attribute and no
+   * `--surface-alpha` is written, and any this writer wrote before is removed.
+   */
+  surface?: SurfaceState
 }
 
 export type ThemeDocumentOptions = {
@@ -35,11 +49,35 @@ export type ThemeDocumentOptions = {
    * must return the full map; a name it drops is not written.
    */
   transformTokens?: (tokens: Record<string, string>) => Record<string, string>
+  /**
+   * The contrast an accent is held to against the variant's background. Absent, a
+   * preset is painted verbatim (the catalogue measured it for its own themes) and
+   * only a custom `#rrggbb` is held to the default floor of 3:1.
+   */
+  accentContrastFloor?: number
+  /**
+   * Where a catalogue variant's palette comes from. `inline` (the default) writes
+   * every role onto the root. `stylesheet` writes none for a catalogue variant,
+   * because the host loads a stylesheet that carries a `[data-theme]` block for it;
+   * a variant the catalogue does not hold (a host's imported theme) is still written
+   * inline, since no stylesheet can know it. The accent, the terminal pin, the
+   * surface alpha and the fonts are written the same in both.
+   *
+   * Switching from an imported variant back to a catalogue one removes what the
+   * imported one wrote, so nothing inline outlives it to beat the stylesheet.
+   */
+  palette?: 'inline' | 'stylesheet'
+}
+
+/** True for the catalogue's own variant, not a host's copy that merely shares its id. */
+function isCatalogueVariant(variant: ThemeVariant): boolean {
+  return themeById(variant.id) === variant
 }
 
 /**
  * The custom properties a state paints: the variant's roles, with the accent
- * selection laid over them, then `transformTokens`.
+ * selection laid over them, the pinned terminal palette over that, the surface
+ * alpha, then `transformTokens`.
  *
  * The accent is applied *here* rather than left to the `[data-accent]` blocks in
  * `theme.css`, because the properties are written inline and an inline declaration
@@ -52,9 +90,20 @@ export function themeDocumentTokens(
   state: ThemeDocumentState,
   options: ThemeDocumentOptions = {}
 ): { tokens: Record<string, string>; accented: boolean } {
-  const properties = { ...themeCssVariables(state.variant) }
-  const accent = accentVariables(state.selection.accent, state.appearance, state.selection)
+  const fromStylesheet = options.palette === 'stylesheet' && isCatalogueVariant(state.variant)
+  const properties = fromStylesheet ? {} : { ...themeCssVariables(state.variant) }
+  const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {
+    background: state.variant.colors.background,
+    floor: options.accentContrastFloor,
+    variantId: state.variant.id,
+  })
   if (accent) Object.assign(properties, accent)
+  // Written after the variant and the accent, so it wins over the interface
+  // variant's own terminal ramp (and over the stylesheet's, which it outranks as an
+  // inline declaration). Dropping the pin needs no removal of its own: the ramp is
+  // then rewritten by the variant, or swept back to the stylesheet.
+  if (state.terminalVariant) Object.assign(properties, terminalCssVariables(state.terminalVariant))
+  if (state.surface) properties['--surface-alpha'] = surfaceAlpha[state.surface.surface]
   return {
     tokens: options.transformTokens ? options.transformTokens(properties) : properties,
     accented: accent !== undefined,
@@ -92,8 +141,24 @@ export function applyThemeToRoot(
   root.dataset['appearance'] = state.appearance
   root.style.colorScheme = state.appearance
 
+  // A custom colour has no stylesheet block to select, and its value is the
+  // attribute's worst possible content, so it is reported as `custom`.
   if (!accented) root.removeAttribute('data-accent')
-  else root.dataset['accent'] = state.selection.accent
+  else
+    root.dataset['accent'] = isCustomAccent(state.selection.accent)
+      ? 'custom'
+      : state.selection.accent
+
+  // The surface axis is opt-in, so its absence removes rather than defaults: a host
+  // that never enables it keeps an `<html>` with neither attribute, and one that
+  // turns it off leaves nothing behind. (`--surface-alpha` is swept with the tokens.)
+  if (state.surface) {
+    root.dataset['surface'] = state.surface.surface
+    root.dataset['reduceTransparency'] = state.surface.reduceTransparencyActive ? 'true' : 'false'
+  } else {
+    root.removeAttribute('data-surface')
+    root.removeAttribute('data-reduce-transparency')
+  }
 
   applyAppearanceFontSettings(
     root,