@adea-ai/ui 0.124.0 → 0.127.0

package/src/lib/preference-store.ts

@@ -0,0 +1,216 @@
+/*
+ * Copyright (c) 2026 Wing
+ * Licensed under the MIT License.
+ *
+ * The recovery behaviour here (quarantine before any write, the envelope shape, the
+ * legacy key that is read once and never deleted) is Adea's accepted port of Zeron's
+ * preference store (https://github.com/zeronsh/zeron),
+ * `packages/ui/src/components/appearance.ts`, moved here so the shared provider and
+ * Adea run one implementation. See NOTICE.
+ */
+
+/**
+ * A versioned preference store: read one JSON document, refuse to guess about what
+ * it cannot read, and keep what it refused.
+ *
+ * Nothing here knows what a preference *is*. A host hands the engine a key, a
+ * version and (through `createVersionedPersistence`) a codec; the engine owns only
+ * the part every versioned store gets wrong the same way, which is what happens to
+ * a document that is not the one the code expects:
+ *
+ *   - A document that is not JSON, or not a record, or carries a version the code
+ *     does not know (usually a newer build's) is **quarantined, byte for byte, into a
+ *     recovery key** before anything else happens. The store then answers as if
+ *     nothing were stored. Because the quarantine runs at read time, ahead of any
+ *     write, saving valid preferences later cannot destroy the unread original.
+ *   - A legacy key is consulted only when the main key is *absent*, never when it is
+ *     unreadable: a corrupt main document is not "no preference", and falling back to
+ *     an older, staler key would quietly restore a choice the user has since changed.
+ *     The legacy key is never deleted.
+ *   - Blocked storage (a sandboxed iframe, a privacy mode) throws on the mere access
+ *     of the `localStorage` global. Every path here treats that as "nothing stored".
+ *
+ * The reads and writes are against a {@link PreferenceStorage}, so the rules run in a
+ * test without a DOM.
+ */
+
+/** The part of `Storage` the engine uses. */
+export type PreferenceStorage = Pick<Storage, 'getItem' | 'setItem'>
+
+/** Why an unread document was quarantined. */
+export type RecoveryReason = 'corrupt_json' | 'unsupported_record'
+
+/**
+ * What is written to the recovery key.
+ *
+ * The shape is a compatibility surface: Adea's stored envelopes already have it, and
+ * a tool that inspects a user's storage reads it. Do not rename a field.
+ */
+export type RecoveryEnvelope = Readonly<{
+  schemaVersion: 1
+  reason: RecoveryReason
+  /** An ISO-8601 timestamp of the capture; refreshed by each read of the same bytes. */
+  capturedAt: string
+  /** The document exactly as it was stored. */
+  raw: string
+}>
+
+/**
+ * The preference store, or nothing.
+ *
+ * The `typeof` guard sits inside the `try` for a reason: where storage is blocked,
+ * merely *reading* the `localStorage` global throws, so a guard in front of the `try`
+ * is itself the crash.
+ */
+export function defaultPreferenceStorage(): PreferenceStorage | undefined {
+  try {
+    return typeof localStorage === 'undefined' ? undefined : localStorage
+  } catch {
+    return undefined
+  }
+}
+
+/** The envelope for a document, stamped with `now`. */
+export function recoveryEnvelope(
+  raw: string,
+  reason: RecoveryReason,
+  now: Date = new Date()
+): RecoveryEnvelope {
+  return { schemaVersion: 1, reason, capturedAt: now.toISOString(), raw }
+}
+
+/**
+ * Quarantine an unread document into `recoveryKey`.
+ *
+ * Idempotent, so re-reading the same unread value refreshes the capture without
+ * losing it. Best effort: a store that cannot be written leaves the caller to fail
+ * closed on the defaults, which is the same outcome as not having a recovery key at
+ * all. Never throws.
+ *
+ * Exported so a host quarantines its *other* documents (a theme library, say) with
+ * the same envelope. Give each document its own `recoveryKey`: two documents that
+ * share one overwrite each other's capture.
+ */
+export function quarantineRecord(
+  storage: PreferenceStorage,
+  recoveryKey: string,
+  raw: string,
+  reason: RecoveryReason,
+  now: () => Date = () => new Date()
+): void {
+  try {
+    storage.setItem(recoveryKey, JSON.stringify(recoveryEnvelope(raw, reason, now())))
+  } catch {
+    // Quarantine is best effort; the active preference still fails closed.
+  }
+}
+
+/** Where a versioned document lives and which version the code understands. */
+export type VersionedRecordSchema = {
+  /** The storage key of the document. */
+  key: string
+  /**
+   * The only `version` the code reads. Absent, the document is unversioned and any
+   * JSON object is accepted; present, a record whose top-level `version` is not
+   * exactly this number is unsupported (newer or older), not "close enough".
+   */
+  version?: number
+  /** Where an unread document is kept. Default `${key}.recovery`. */
+  recoveryKey?: string
+}
+
+/**
+ * What reading the document found.
+ *
+ *   - `absent`: nothing is stored under the key.
+ *   - `record`: a JSON object this code can read; `raw` is the stored text.
+ *   - `quarantined`: something was stored and cannot be read. It has already been
+ *     written to the recovery key.
+ *   - `unavailable`: the store itself could not be read.
+ */
+export type VersionedRead =
+  | { status: 'absent' }
+  | { status: 'record'; record: Readonly<Record<string, unknown>>; raw: string }
+  | { status: 'quarantined'; reason: RecoveryReason; raw: string }
+  | { status: 'unavailable' }
+
+/** The default recovery key for a document key. */
+export function recoveryKeyFor(schema: VersionedRecordSchema): string {
+  return schema.recoveryKey ?? `${schema.key}.recovery`
+}
+
+/**
+ * Read the document under `schema.key`.
+ *
+ * The classification is the contract: a value that is not valid JSON, or is JSON but
+ * not an object (`null`, a number, a string), is `corrupt_json`; an object (or array)
+ * that is not a record of the supported version is `unsupported_record`. Both are
+ * quarantined before this returns. An empty string is a stored value, so it is
+ * corrupt rather than absent.
+ */
+export function readVersionedRecord(
+  storage: PreferenceStorage,
+  schema: VersionedRecordSchema,
+  now?: () => Date
+): VersionedRead {
+  let raw: string | null
+  try {
+    raw = storage.getItem(schema.key)
+  } catch {
+    return { status: 'unavailable' }
+  }
+  if (raw === null) return { status: 'absent' }
+
+  const recoveryKey = recoveryKeyFor(schema)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    quarantineRecord(storage, recoveryKey, raw, 'corrupt_json', now)
+    return { status: 'quarantined', reason: 'corrupt_json', raw }
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    quarantineRecord(storage, recoveryKey, raw, 'corrupt_json', now)
+    return { status: 'quarantined', reason: 'corrupt_json', raw }
+  }
+  if (
+    Array.isArray(parsed) ||
+    (schema.version !== undefined && (parsed as { version?: unknown }).version !== schema.version)
+  ) {
+    quarantineRecord(storage, recoveryKey, raw, 'unsupported_record', now)
+    return { status: 'quarantined', reason: 'unsupported_record', raw }
+  }
+  return { status: 'record', record: parsed as Record<string, unknown>, raw }
+}
+
+/**
+ * The legacy single-key value, or `null`.
+ *
+ * Only the caller decides whether to look: the engine's rule is to ask when the main
+ * key is `absent`, not when it was quarantined.
+ */
+export function readLegacyValue(storage: PreferenceStorage, legacyKey: string): string | null {
+  try {
+    return storage.getItem(legacyKey)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write `document` to `key` as JSON. Returns whether it was stored; a full or blocked
+ * store returns `false` and never throws, because losing a preference must not break
+ * the switch that tried to save it.
+ */
+export function writeVersionedRecord(
+  storage: PreferenceStorage,
+  key: string,
+  document: unknown
+): boolean {
+  try {
+    storage.setItem(key, JSON.stringify(document))
+    return true
+  } catch {
+    return false
+  }
+}

package/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/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/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/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
  *