@adea-ai/ui 0.125.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

@@ -733,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.125.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",
@@ -2674,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",
@@ -2689,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",
@@ -2699,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,11 +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'
 
 /**
@@ -27,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 = {
@@ -42,11 +55,29 @@ export type ThemeDocumentOptions = {
    * 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
@@ -59,13 +90,20 @@ export function themeDocumentTokens(
   state: ThemeDocumentState,
   options: ThemeDocumentOptions = {}
 ): { tokens: Record<string, string>; accented: boolean } {
-  const properties = { ...themeCssVariables(state.variant) }
+  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,
@@ -111,6 +149,17 @@ export function applyThemeToRoot(
       ? '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,
     normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings

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

@@ -2,6 +2,15 @@ import { normalizeCustomAccent } from '#lib/accent-roles'
 import { accentPresets } from '#lib/tokens'
 import { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'
 import { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'
+import { normalizeSurface } from '#lib/theme-surface'
+import {
+  defaultPreferenceStorage,
+  readLegacyValue,
+  readVersionedRecord,
+  recoveryKeyFor,
+  writeVersionedRecord,
+  type PreferenceStorage,
+} from '#lib/preference-store'
 import { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state'
 
 /**
@@ -83,6 +92,17 @@ function readSelection(storageKey: string): ThemeSelection {
       // document effect removes the `data-density` that `themeScript` set for the first paint, and
       // the next `setSelection` rewrites the store without it.
       density: resolvedDensity(parsed as ThemeSelection),
+      // The newer axes are read back only when the store holds a usable value and are
+      // otherwise left `undefined`, never defaulted: `JSON.stringify` drops them, so a
+      // consumer that never sets one writes the bytes it always did. An id is kept as
+      // stored, known or not, for the same reason a theme id the registry lacks is.
+      terminalThemeId:
+        typeof parsed.terminalThemeId === 'string' && parsed.terminalThemeId.trim() !== ''
+          ? parsed.terminalThemeId
+          : undefined,
+      surface: normalizeSurface(parsed.surface),
+      reduceTransparency:
+        typeof parsed.reduceTransparency === 'boolean' ? parsed.reduceTransparency : undefined,
     }
   } catch {
     return defaultThemeSelection
@@ -141,3 +161,150 @@ export function writePersisted(persistence: ThemePersistence, next: ThemeSelecti
     // session and does not survive the reload.
   }
 }
+
+/**
+ * Where a host's versioned preference document lives. One schema describes the
+ * document to both halves of the system: {@link createVersionedPersistence} reads and
+ * writes it, and `themeScript(options)` reads it before first paint, so the two
+ * cannot disagree about a key or a version.
+ */
+export type ThemeStorageSchema = {
+  /** The storage key of the document. */
+  key: string
+  /**
+   * The only top-level `version` read. Absent, the document is unversioned. A record
+   * of any other version is quarantined (see `recoveryKey`), not interpreted.
+   */
+  version?: number
+  /**
+   * The document field that holds the appearance preference (`system`, `light`,
+   * `dark`). Read by `themeScript`; the persistence leaves field names to the codec.
+   * Default `appearance`.
+   */
+  appearanceField?: 'appearance' | 'mode'
+  /**
+   * An older single-value key (`light` | `dark` | `system`) read only while `key` is
+   * absent, and never deleted. The persistence hands it to the codec's `fromLegacy`.
+   */
+  legacyAppearanceKey?: string
+  /**
+   * The stored library of imported themes, for `themeScript` only: an imported
+   * theme's id and verbatim tokens, so the first paint can use the right variant. The
+   * persistence neither reads nor writes it.
+   */
+  libraryKey?: string
+  /** Where an unreadable document is kept. Default `${key}.recovery`. */
+  recoveryKey?: string
+}
+
+/**
+ * How a host's document maps to and from the shared {@link ThemeSelection}.
+ *
+ * The codec is the product schema: it decides which fields a document has, how an
+ * unknown value is corrected, and what a fresh install looks like. The engine decides
+ * everything about *storage*: what is quarantined, when the legacy key is read, and
+ * that nothing is written until `setSelection` asks.
+ */
+export type VersionedCodec<Doc> = {
+  /**
+   * A readable record (the right JSON shape and version) as a selection patch. Fields
+   * it leaves `undefined` fall back to the provider's defaults. It may keep an id the
+   * catalogue lacks; the provider resolves it, it does not rewrite it.
+   */
+  decode(record: Readonly<Record<string, unknown>>): Partial<ThemeSelection>
+  /**
+   * The legacy key's value (never `null`) as a selection patch, or `undefined` for a
+   * value it does not recognise. Called only when the main key is absent.
+   */
+  fromLegacy?(value: string): Partial<ThemeSelection> | undefined
+  /**
+   * What a store with nothing readable answers: a fresh install, an unreadable
+   * document, a blocked store. Absent, the provider's own defaults apply.
+   */
+  defaults?(): Partial<ThemeSelection> | undefined
+  /**
+   * The document to store for a selection. `previous` is the record last read or
+   * written, so a codec can carry a field the selection does not model.
+   */
+  encode(next: ThemeSelection, previous?: Readonly<Record<string, unknown>>): Doc
+}
+
+/** Seams for the storage and the clock; both default to the real ones. */
+export type VersionedPersistenceOptions = {
+  /** The store, or nothing. Called per access; default is `localStorage` (blocked-safe). */
+  storage?: () => PreferenceStorage | undefined
+  /** The clock for the recovery envelope's `capturedAt`. */
+  now?: () => Date
+}
+
+/**
+ * A {@link ThemePersistence} over a versioned document and a host codec.
+ *
+ * `read` follows the engine's rules (`lib/preference-store.ts`): the main key first;
+ * an unreadable or unsupported document is quarantined byte for byte into the
+ * recovery key and the codec's `defaults` answer; the legacy key only when the main
+ * key is absent. It never writes the main key, so the first write is a user's
+ * decision. `write` stores `codec.encode(next, previous)` as JSON and swallows a
+ * failure.
+ *
+ * Neither method throws. The stored bytes are exactly what the codec encodes, so a
+ * host keeps its keys, field names and bytes by keeping its codec.
+ */
+export function createVersionedPersistence<Doc>(
+  schema: ThemeStorageSchema,
+  codec: VersionedCodec<Doc>,
+  options: VersionedPersistenceOptions = {}
+): ThemePersistence {
+  const storageOf = options.storage ?? defaultPreferenceStorage
+  const recordSchema = {
+    key: schema.key,
+    version: schema.version,
+    recoveryKey: recoveryKeyFor(schema),
+  }
+  let previous: Readonly<Record<string, unknown>> | undefined
+
+  const fallback = () => {
+    try {
+      return codec.defaults?.()
+    } catch {
+      return undefined
+    }
+  }
+
+  return {
+    read() {
+      const storage = storageOf()
+      if (!storage) return fallback()
+      try {
+        const found = readVersionedRecord(storage, recordSchema, options.now)
+        if (found.status === 'record') {
+          previous = found.record
+          return codec.decode(found.record)
+        }
+        if (found.status === 'absent' && schema.legacyAppearanceKey && codec.fromLegacy) {
+          const legacy = readLegacyValue(storage, schema.legacyAppearanceKey)
+          const migrated = legacy === null ? undefined : codec.fromLegacy(legacy)
+          if (migrated) return migrated
+        }
+      } catch {
+        // A codec that throws on a record it cannot read is an unreadable store.
+      }
+      return fallback()
+    },
+    write(next) {
+      const storage = storageOf()
+      if (!storage) return
+      try {
+        const document = codec.encode(next, previous)
+        if (writeVersionedRecord(storage, schema.key, document)) {
+          previous =
+            typeof document === 'object' && document !== null
+              ? (document as Readonly<Record<string, unknown>>)
+              : undefined
+        }
+      } catch {
+        // An encoder that throws loses the preference, not the switch.
+      }
+    },
+  }
+}