@adea-ai/ui 0.125.0 → 0.128.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

@@ -37,6 +37,7 @@ import {
   ACCENTS,
   accentForeground,
   chartSeries,
+  editorRolesHex,
   getAccent,
   getTheme,
   hasTheme,
@@ -613,6 +614,97 @@ export function accentRolesForSelection(
   })
 }
 
+/**
+ * Which projection fills the `--editor-*` ramp.
+ *
+ *   - `syntax` (the default) is the catalogue's quiet syntax roles, as `ThemeVariant.editor`
+ *     holds them: a comment may sit below body-text contrast, because in a code view
+ *     it is meant to recede.
+ *   - `floor` holds every editor role to 4.5:1 on the canvas (`editorRolesHex`), for a
+ *     host that renders code as content rather than as decoration. It is hex, where
+ *     `syntax` is `oklch()`.
+ */
+export type EditorRolesMode = 'syntax' | 'floor'
+
+/** Options for {@link themeCssVariables}. */
+export type ThemeCssVariableOptions = {
+  /** The `--editor-*` projection. Default `syntax`: absent, the output is unchanged. */
+  editor?: EditorRolesMode
+}
+
+/**
+ * True for the catalogue's own variant, not a host's copy that merely shares its id.
+ *
+ * Identity rather than id, because a host's imported theme may reuse a catalogue id
+ * with different colours, and projecting the catalogue's record for it would paint
+ * the wrong palette.
+ */
+export function isCatalogueVariant(variant: ThemeVariant): boolean {
+  return themeById(variant.id) === variant
+}
+
+/**
+ * The editor palette held to 4.5:1, or `fallback` for a record that cannot reach it.
+ *
+ * Some palettes (an imported one, most often) cannot be repaired to the floor from
+ * their own ramp within the catalogue's lightness budget, and `editorRolesHex` says
+ * so by throwing. A palette that paints nothing is worse than one that paints its
+ * quiet roles, so the throw is the cue to fall back rather than to fail. `project` is
+ * a parameter so that path can be exercised: no catalogue theme takes it.
+ */
+export function floorEditorPalette(
+  record: AdeaTheme,
+  fallback: ThemeEditorPalette,
+  project: (theme: AdeaTheme) => Record<keyof ThemeEditorPalette, string> = editorRolesHex
+): ThemeEditorPalette {
+  try {
+    const roles = project(record)
+    return {
+      keyword: roles.keyword,
+      string: roles.string,
+      number: roles.number,
+      comment: roles.comment,
+      function: roles.function,
+      variable: roles.variable,
+      type: roles.type,
+      tag: roles.tag,
+      attribute: roles.attribute,
+      operator: roles.operator,
+      heading: roles.heading,
+      link: roles.link,
+      diffAdd: roles.diffAdd,
+      diffDelete: roles.diffDelete,
+      diffHunk: roles.diffHunk,
+      searchMatch: roles.searchMatch,
+    }
+  } catch {
+    return fallback
+  }
+}
+
+const floorEditorCache = new Map<string, ThemeEditorPalette>()
+
+/**
+ * The editor palette a variant paints under a projection.
+ *
+ * `floor` applies to the catalogue's own variants, whose record the catalogue holds.
+ * A variant it does not hold (a host's imported theme) has no record to project and
+ * keeps its own `editor`; such a theme normally carries its roles in `tokens`, which
+ * win over either projection anyway. Computed once per theme: the repair is a search.
+ */
+export function editorPaletteFor(
+  theme: ThemeVariant,
+  mode: EditorRolesMode = 'syntax'
+): ThemeEditorPalette {
+  if (mode !== 'floor' || !isCatalogueVariant(theme)) return theme.editor
+  const cached = floorEditorCache.get(theme.id)
+  if (cached) return cached
+  const record = getTheme(theme.id)
+  const palette = record ? floorEditorPalette(record, theme.editor) : theme.editor
+  floorEditorCache.set(theme.id, palette)
+  return palette
+}
+
 /**
  * The roles a variant sets, as CSS custom properties.
  *
@@ -620,11 +712,18 @@ export function accentRolesForSelection(
  * names. A provider applies this; nothing else repeats it. The `--terminal-*` and
  * `--editor-*` ramps are presentations of the catalogue's ANSI and syntax data rather
  * than separate roles, which is why they are built here and not in the catalogue.
+ *
+ * `options.editor` picks the `--editor-*` projection ({@link EditorRolesMode}).
+ * Absent it, the result is what it has always been; the generated `theme-variants.css`
+ * and the design-system artifact are built without it.
  */
-export function themeCssVariables(theme: ThemeVariant): Record<string, string> {
+export function themeCssVariables(
+  theme: ThemeVariant,
+  options: ThemeCssVariableOptions = {}
+): Record<string, string> {
   const c = theme.colors
   const t = theme.terminal
-  const e = theme.editor
+  const e = editorPaletteFor(theme, options.editor)
   const derived = {
     '--background': c.background,
     '--foreground': c.foreground,
@@ -733,6 +832,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
   {