@adea-ai/ui 0.125.0 → 0.128.0

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/theme.json

@@ -2,7 +2,7 @@
   "name": "theme",
   "type": "registry:style",
   "title": "Adea theme",
-  "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack.",
+  "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack, plus the pre-paint stylesheet that carries every catalogue theme.",
   "dependencies": [
     "@fontsource-variable/geist@^5.3.0",
     "@fontsource-variable/geist-mono@^5.3.0",
@@ -22,6 +22,11 @@
       "type": "registry:style",
       "target": "styles/theme.css"
     },
+    {
+      "path": "src/styles/theme-variants.css",
+      "type": "registry:style",
+      "target": "styles/theme-variants.css"
+    },
     {
       "path": "src/styles/base.css",
       "type": "registry:style",

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.128.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",
@@ -68,6 +68,7 @@
     },
     "./globals.css": "./src/styles/globals.css",
     "./theme.css": "./src/styles/theme.css",
+    "./theme-variants.css": "./src/styles/theme-variants.css",
     "./base.css": "./src/styles/base.css",
     "./appearance-font-settings.css": "./src/styles/appearance-font-settings.css",
     "./fonts.css": "./src/styles/fonts.css",

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",
@@ -2595,7 +2600,7 @@
       "name": "theme",
       "type": "registry:style",
       "title": "Adea theme",
-      "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack.",
+      "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack, plus the pre-paint stylesheet that carries every catalogue theme.",
       "dependencies": [
         "@fontsource-variable/geist@^5.3.0",
         "@fontsource-variable/geist-mono@^5.3.0",
@@ -2615,6 +2620,11 @@
           "type": "registry:style",
           "target": "styles/theme.css"
         },
+        {
+          "path": "src/styles/theme-variants.css",
+          "type": "registry:style",
+          "target": "styles/theme-variants.css"
+        },
         {
           "path": "src/styles/base.css",
           "type": "registry:style",
@@ -2674,6 +2684,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 +2704,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 +2719,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,
@@ -16,11 +17,17 @@ export {
   themeScript,
   useOptionalTheme,
   useTheme,
+  type EditorRolesMode,
   type ThemeContextValue,
   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,15 @@ import {
 } from '#lib/appearance-font-settings'
 import {
   accentVariables,
+  isCatalogueVariant,
+  terminalCssVariables,
   themeCssVariables,
+  type EditorRolesMode,
   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 +31,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 +56,52 @@ 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'
+  /**
+   * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet
+   * syntax roles, which is what `theme-variants.css` carries; `floor` holds every
+   * editor role to 4.5:1 on the canvas, as hex.
+   *
+   * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue
+   * variant still gets: the stylesheet is generated for the default projection, so
+   * the sixteen `--editor-*` properties are written inline over it. The rest of the
+   * palette stays in the stylesheet.
+   */
+  editorRoles?: EditorRolesMode
+}
+
+/**
+ * What a catalogue variant still writes inline when its palette is the stylesheet's:
+ * nothing, unless the editor projection is not the one the stylesheet was generated
+ * for.
+ */
+function stylesheetOverrides(
+  variant: ThemeVariant,
+  editorRoles: EditorRolesMode | undefined
+): Record<string, string> {
+  if (editorRoles !== 'floor') return {}
+  return Object.fromEntries(
+    Object.entries(themeCssVariables(variant, { editor: 'floor' })).filter(([name]) =>
+      name.startsWith('--editor-')
+    )
+  )
 }
 
 /**
  * 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 +114,22 @@ 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
+    ? stylesheetOverrides(state.variant, options.editorRoles)
+    : { ...themeCssVariables(state.variant, { editor: options.editorRoles }) }
   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 +175,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.
+      }
+    },
+  }
+}