@adea-ai/ui 0.125.0 → 0.127.0

package/src/components/theme/theme-provider.tsx

@@ -1,7 +1,7 @@
 import type { JSX } from 'solid-js'
-import { createEffect, createMemo, createSignal, onCleanup, splitProps } from 'solid-js'
-import { safeScriptStringLiteral } from '#lib/safe-script'
-import { fontSettingsBootstrapScript } from '#lib/appearance-font-settings'
+import { createEffect, createMemo, createSignal, onCleanup, splitProps, untrack } from 'solid-js'
+import { fontZoomShortcut, type FontZoomIntent } from '#lib/font-zoom'
+import { REDUCED_TRANSPARENCY_QUERY, resolveSurfaceState } from '#lib/theme-surface'
 import {
   builtinThemes,
   themeAccentsFor,
@@ -21,13 +21,24 @@ import {
   initialThemeSelection,
   mergeRegistry,
   mergeThemeSelection,
+  resolveTerminalVariant,
   resolveThemeState,
+  zoomedFontSettings,
   type ThemeContextValue,
   type ThemeSelection,
 } from './theme-state'
 
 export { useOptionalTheme, useTheme } from './theme-context'
-export { localStoragePersistence, type ThemePersistence } from './theme-persistence'
+export {
+  createVersionedPersistence,
+  localStoragePersistence,
+  type ThemePersistence,
+  type ThemeStorageSchema,
+  type VersionedCodec,
+  type VersionedPersistenceOptions,
+} from './theme-persistence'
+export type { ThemeSurface } from '#lib/theme-surface'
+export { inlineScriptLiteral, themeScript, type ThemeScriptOptions } from './theme-script'
 export {
   defaultThemeSelection,
   resolvedDensity,
@@ -121,6 +132,48 @@ export type ThemeProviderProps = {
    * own themes the floor changes no preset.
    */
   accentContrastFloor?: number
+  /**
+   * Turns the surface axis on: `selection.surface` and `selection.reduceTransparency`
+   * are resolved against the operating system's Reduce Transparency setting and the
+   * host's capability, and `data-surface`, `data-reduce-transparency` and
+   * `--surface-alpha` are written to `<html>` (the frost rule in `theme.css` reads
+   * them). Off by default: a provider that never opts in writes none of them, adds no
+   * media-query listener, and stores nothing new.
+   *
+   * An object also states the host's capability. `nativeTranslucency` is whether the
+   * window can render the OS's own translucency; without it a `translucent`
+   * preference paints the tokenized `frosted` surface instead of pretending to
+   * vibrancy. A function is read inside the provider's reactive scope, for a
+   * capability that is learned after mount.
+   *
+   * A selection that already carries a `surface` turns the axis on for itself, so a
+   * host that stores the field gets the same document without the prop.
+   */
+  surface?: boolean | { nativeTranslucency?: boolean | (() => boolean) }
+  /**
+   * Where a catalogue variant's palette comes from. `inline` (the default) writes
+   * every role onto `<html>`. `stylesheet` leaves a catalogue variant to the host's
+   * `[data-theme]` stylesheet and writes inline only what no stylesheet can know: a
+   * host's own `themes`, the accent, the pinned terminal palette, the surface alpha
+   * and the fonts. Switching from a host variant back to a catalogue one removes the
+   * properties the host variant wrote.
+   */
+  palette?: 'inline' | 'stylesheet'
+  /**
+   * Bind the platform zoom chords (Cmd or Ctrl with `=`, `+`, `-`, `0`) to the three
+   * text sizes instead of the browser's page zoom: stepping them together is zoom
+   * inside the persisted type system. Off by default: it adds a capturing `keydown`
+   * listener to `window`, and an event already handled elsewhere is left alone.
+   * `zoomFonts` on the context does the same from a menu or a host's own binding.
+   */
+  fontZoom?: boolean
+}
+
+/** The operating system's Reduce Transparency query, where there is a window to ask. */
+function reducedTransparencyMedia(): MediaQueryList | undefined {
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    ? window.matchMedia(REDUCED_TRANSPARENCY_QUERY)
+    : undefined
 }
 
 export function ThemeProvider(props: ThemeProviderProps) {
@@ -134,6 +187,9 @@ export function ThemeProvider(props: ThemeProviderProps) {
     'transformTokens',
     'disableTransitionOnChange',
     'accentContrastFloor',
+    'surface',
+    'palette',
+    'fontZoom',
   ])
   const storageKey = () => local.storageKey ?? 'adea-appearance'
   const persistence = local.persistence ?? localStoragePersistence(storageKey)
@@ -186,6 +242,37 @@ export function ThemeProvider(props: ThemeProviderProps) {
     draft() ? resolveThemeState(shownSelection(), systemAppearance(), registry()) : committed()
   )
 
+  // The surface axis. Off, none of this reads the operating system: the media query
+  // is subscribed only while the axis is on, so a provider that never opts in adds no
+  // listener and no repaint.
+  const surfaceOn = (candidate: ThemeSelection) =>
+    local.surface === true || typeof local.surface === 'object' || candidate.surface !== undefined
+  const nativeTranslucency = () => {
+    const capability = typeof local.surface === 'object' ? local.surface.nativeTranslucency : false
+    return (typeof capability === 'function' ? capability() : capability) === true
+  }
+  const [osReducedTransparency, setOsReducedTransparency] = createSignal(
+    surfaceOn(untrack(shownSelection)) ? (reducedTransparencyMedia()?.matches ?? false) : false
+  )
+  const axisOn = createMemo(() => surfaceOn(shownSelection()))
+  createEffect(() => {
+    const query = axisOn() ? reducedTransparencyMedia() : undefined
+    setOsReducedTransparency(query?.matches ?? false)
+    if (!query) return
+    const onChange = (event: MediaQueryListEvent) => setOsReducedTransparency(event.matches)
+    query.addEventListener('change', onChange)
+    onCleanup(() => query.removeEventListener('change', onChange))
+  })
+  const surfaceStateOf = (candidate: ThemeSelection) =>
+    resolveSurfaceState(candidate.surface, {
+      osReducedTransparency: osReducedTransparency(),
+      userReducedTransparency: candidate.reduceTransparency === true,
+      nativeTranslucency: nativeTranslucency(),
+    })
+  const committedSurface = createMemo(() =>
+    surfaceOn(selection()) ? surfaceStateOf(selection()) : undefined
+  )
+
   let written: ReadonlySet<string> | undefined
   let restoreTransitions: (() => void) | undefined
   createEffect(() => {
@@ -194,10 +281,13 @@ export function ThemeProvider(props: ThemeProviderProps) {
       selection: shownSelection(),
       appearance: shown().appearance,
       variant: shown().variant,
+      terminalVariant: resolveTerminalVariant(shownSelection().terminalThemeId, registry()),
+      surface: axisOn() ? surfaceStateOf(shownSelection()) : undefined,
     }
     const options = {
       transformTokens: local.transformTokens,
       accentContrastFloor: local.accentContrastFloor,
+      palette: local.palette,
     }
     const apply = () => {
       written = applyThemeToRoot(document.documentElement, state, options, written)
@@ -215,6 +305,24 @@ export function ThemeProvider(props: ThemeProviderProps) {
     themeAccentsFor(selection().lightThemeId, selection().darkThemeId)
   )
 
+  const zoomFonts = (intent: FontZoomIntent) =>
+    value.setSelection({ fonts: zoomedFontSettings(selection(), intent) })
+
+  // The platform zoom chords drive the three text sizes, captured like the other
+  // global chords; an event something else already handled never double-steps.
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.defaultPrevented) return
+    const intent = fontZoomShortcut(event)
+    if (!intent) return
+    event.preventDefault()
+    zoomFonts(intent)
+  }
+  createEffect(() => {
+    if (!local.fontZoom || typeof window === 'undefined') return
+    window.addEventListener('keydown', onKeyDown, { capture: true })
+    onCleanup(() => window.removeEventListener('keydown', onKeyDown, { capture: true }))
+  })
+
   const value: ThemeContextValue = {
     selection,
     resolvedAppearance,
@@ -233,6 +341,9 @@ export function ThemeProvider(props: ThemeProviderProps) {
         registry: registry(),
         accentContrastFloor: local.accentContrastFloor,
       }),
+    effectiveSurface: () => committedSurface()?.surface ?? 'opaque',
+    reduceTransparencyActive: () => committedSurface()?.reduceTransparencyActive ?? false,
+    zoomFonts,
     setSelection(patch) {
       const next = mergeThemeSelection(selection(), patch)
       setSelectionState(next)
@@ -245,49 +356,3 @@ export function ThemeProvider(props: ThemeProviderProps) {
   const Context = themeContext()
   return <Context.Provider value={value}>{local.children}</Context.Provider>
 }
-
-/**
- * A string as a JavaScript literal that is also safe inside an inline `<script>`.
- *
- * `JSON.stringify` produces a correct JavaScript literal, and it is **not** safe
- * here: it leaves `<` and `>` alone, so a value containing `</script>` ends the tag
- * early and everything after it is parsed as HTML. That is the classic inline-script
- * injection, and it is a real one even though the value is a developer-supplied prop
- * rather than user input — a prop can come from configuration, and a key that happens
- * to contain a closing tag should not be able to execute.
- *
- * The escape is also correct JavaScript: `\u003c` is `<` to the parser, so the value
- * is byte-identical at runtime and inert to the HTML tokenizer. `\u2028` and `\u2029`
- * are escaped for the neighbouring reason — they are legal inside a JSON string and
- * were, before ES2019, line terminators to a JavaScript parser.
- *
- * CodeQL flags the unescaped form as `js/bad-code-sanitization`, which is how this
- * was found; `tests/theme-script.test.ts` pins it so it cannot come back.
- */
-export function inlineScriptLiteral(value: string): string {
-  return safeScriptStringLiteral(value)
-}
-
-/**
- * The no-flash script.
- *
- * Rendered inline in `<head>` before any stylesheet that matters. Without it a dark
- * preference paints the light theme first and then swaps, which is the flash every
- * themed application has to solve and the one thing a provider cannot do from
- * inside the body.
- *
- * Deliberately tiny and dependency-free: it reads the stored preference, resolves
- * `system`, and sets the class. It does not apply the variant's roles — the default
- * theme in `theme.css` covers the first paint, and the provider writes the rest on
- * mount.
- *
- * The script reads two values out of `localStorage` and writes them to `dataset`,
- * which is a *property* assignment rather than code: a stored accent or font id can
- * set an attribute and cannot execute. The one value that reaches the source as text
- * is `storageKey`, and it goes through {@link inlineScriptLiteral} for the reason
- * documented there.
- */
-export function themeScript(storageKey = 'adea-appearance'): string {
-  const script = `(function(){try{var s=localStorage.getItem(${inlineScriptLiteral(storageKey)});var p=s?JSON.parse(s):{};var a=p.appearance||'system';var d=a==='dark'||(a==='system'&&window.matchMedia('(prefers-color-scheme: dark)').matches);var r=document.documentElement;if(d)r.classList.add('dark');r.style.colorScheme=d?'dark':'light';if(p.accent&&p.accent!=='theme')r.dataset.accent=p.accent;if(p.density==='compact')r.dataset.density='compact';}catch(e){}})();`
-  return `${script}${fontSettingsBootstrapScript(storageKey)}`
-}

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

@@ -0,0 +1,201 @@
+import { fontSettingsBootstrapScript } from '#lib/appearance-font-settings'
+import { isCustomAccent } from '#lib/accent-roles'
+import { safeScriptStringLiteral } from '#lib/safe-script'
+import { REDUCED_TRANSPARENCY_QUERY, surfaceAlpha } from '#lib/theme-surface'
+import { accentPresets } from '#lib/tokens'
+import { builtinThemes, defaultDarkThemeId, defaultLightThemeId } from '#lib/themes'
+import type { ThemeStorageSchema } from './theme-persistence'
+
+/**
+ * A string as a JavaScript literal that is also safe inside an inline `<script>`.
+ *
+ * `JSON.stringify` produces a correct JavaScript literal, and it is **not** safe
+ * here: it leaves `<` and `>` alone, so a value containing `</script>` ends the tag
+ * early and everything after it is parsed as HTML. That is the classic inline-script
+ * injection, and it is a real one even though the value is a developer-supplied prop
+ * rather than user input — a prop can come from configuration, and a key that happens
+ * to contain a closing tag should not be able to execute.
+ *
+ * The escape is also correct JavaScript: `\u003c` is `<` to the parser, so the value
+ * is byte-identical at runtime and inert to the HTML tokenizer. `\u2028` and `\u2029`
+ * are escaped for the neighbouring reason — they are legal inside a JSON string and
+ * were, before ES2019, line terminators to a JavaScript parser.
+ *
+ * CodeQL flags the unescaped form as `js/bad-code-sanitization`, which is how this
+ * was found; `tests/theme-script.test.ts` pins it so it cannot come back.
+ */
+export function inlineScriptLiteral(value: string): string {
+  return safeScriptStringLiteral(value)
+}
+
+/**
+ * Options for the host-shaped no-flash script: the document's {@link ThemeStorageSchema}
+ * plus what the script paints from it.
+ */
+export type ThemeScriptOptions = ThemeStorageSchema & {
+  /**
+   * The accent painted when the document has none, an unrecognised one, or the
+   * legacy `theme` spelling — the host's default (adea: `violet`). Without it those
+   * cases paint no `data-accent`, which is what the provider writes for `theme`.
+   * Setting it means the `[data-accent]` block of the default preset paints on the
+   * first frame instead of after hydration.
+   */
+  defaultAccent?: string
+  /**
+   * Also resolve the surface axis (`data-surface`, `data-reduce-transparency`,
+   * `--surface-alpha`) from the document and the operating system's Reduce
+   * Transparency setting. A `translucent` preference resolves to `frosted`: the
+   * host's translucency capability is not known until the provider mounts, and the
+   * provider re-resolves it then. Match the provider's `surface` prop.
+   */
+  surface?: boolean
+  /**
+   * Match the provider's `palette` prop. The attributes written are the same either
+   * way: a catalogue variant's palette is the host stylesheet's job (`stylesheet`) or
+   * the provider's, at mount (`inline`), and a stored theme's own tokens are written
+   * inline in both.
+   */
+  palette?: 'inline' | 'stylesheet'
+  /** The only `version` of the library document read. Default `1`. */
+  libraryVersion?: number
+}
+
+/**
+ * The no-flash script.
+ *
+ * Rendered inline in `<head>` before any stylesheet that matters. Without it a dark
+ * preference paints the light theme first and then swaps, which is the flash every
+ * themed application has to solve and the one thing a provider cannot do from
+ * inside the body.
+ *
+ * ## The string form
+ *
+ * `themeScript('key')` serves a provider that stores an unversioned
+ * `localStorage[key]` document. Deliberately tiny and dependency-free: it reads the
+ * stored preference, resolves `system`, and sets the class. It does not apply the
+ * variant's roles — the default theme in `theme.css` covers the first paint, and the
+ * provider writes the rest on mount. Its output is a compatibility surface (a
+ * consumer may have it in a snapshot), so it does not change.
+ *
+ * ## The options form
+ *
+ * `themeScript({ key, ... })` serves a host with a versioned document (see
+ * `createVersionedPersistence`) and writes what the provider will write, so mounting
+ * repaints nothing:
+ *
+ *   - `class="dark"`, `color-scheme`, `data-theme`, `data-appearance` and, for a
+ *     compact document, `data-density`;
+ *   - `data-accent`: a preset id as stored, `custom` for a `#rrggbb` (never the hex
+ *     itself, which is the worst possible attribute content), `defaultAccent` when the
+ *     document has none, nothing for a theme-derived `ansi-*` accent (it has no
+ *     stylesheet block; the provider paints it inline);
+ *   - the theme: the stored id when the catalogue or the stored library holds it, else
+ *     the default of the resolved appearance, exactly as the provider resolves it. A
+ *     library theme's own tokens are written inline, so an imported theme paints on the
+ *     first frame;
+ *   - the surface axis, when `surface` is set;
+ *   - the font settings, guarded to the document's `version`.
+ *
+ * The document's `version`, when the schema names one, must match exactly. The legacy
+ * key is read only while the main key is absent: an unreadable main document is not
+ * "no preference", so it does not resurrect an older value.
+ *
+ * The script reads values out of `localStorage` and writes them to `dataset` and
+ * `style`, which are *property* assignments rather than code: a stored id, accent or
+ * token can set an attribute and cannot execute. The values that reach the source as
+ * text (keys, ids, the default accent) go through {@link inlineScriptLiteral} for the
+ * reason documented there.
+ */
+export function themeScript(storageKey?: string): string
+export function themeScript(options: ThemeScriptOptions): string
+export function themeScript(input: string | ThemeScriptOptions = 'adea-appearance'): string {
+  if (typeof input === 'string') return stringFormScript(input)
+  return optionsFormScript(input)
+}
+
+function stringFormScript(storageKey: string): string {
+  const script = `(function(){try{var s=localStorage.getItem(${inlineScriptLiteral(storageKey)});var p=s?JSON.parse(s):{};var a=p.appearance||'system';var d=a==='dark'||(a==='system'&&window.matchMedia('(prefers-color-scheme: dark)').matches);var r=document.documentElement;if(d)r.classList.add('dark');r.style.colorScheme=d?'dark':'light';if(p.accent&&p.accent!=='theme')r.dataset.accent=p.accent;if(p.density==='compact')r.dataset.density='compact';}catch(e){}})();`
+  return `${script}${fontSettingsBootstrapScript(storageKey)}`
+}
+
+const literal = safeScriptStringLiteral
+
+function optionsFormScript(options: ThemeScriptOptions): string {
+  const field = options.appearanceField ?? 'appearance'
+  const versionGuard =
+    options.version === undefined ? '' : `&&x.version===${Number(options.version)}`
+  const presets = accentPresets
+    .filter((preset) => preset.id !== 'theme')
+    .map((preset) => literal(preset.id))
+  const defaultAccent =
+    options.defaultAccent === undefined
+      ? ''
+      : isCustomAccent(options.defaultAccent)
+        ? 'custom'
+        : options.defaultAccent
+
+  const parts: string[] = []
+  parts.push(
+    `(function(){try{`,
+    `var r=document.documentElement,s=r.style;`,
+    `var q=function(m){try{return window.matchMedia(m).matches}catch(e){return false}};`,
+    `var get=function(k){try{return localStorage.getItem(k)}catch(e){return null}};`,
+    // The main document. `raw !== null` rather than truthiness: an empty string is a
+    // stored (corrupt) value, so it does not fall through to the legacy key.
+    `var raw=get(${literal(options.key)}),doc=null,legacy=null;`,
+    `if(raw!==null){try{var x=JSON.parse(raw);if(x&&typeof x==='object'&&!Array.isArray(x)${versionGuard})doc=x}catch(e){}}`
+  )
+  if (options.legacyAppearanceKey !== undefined) {
+    parts.push(`else legacy=get(${literal(options.legacyAppearanceKey)});`)
+  }
+  parts.push(
+    `var m=doc?doc[${literal(field)}]:legacy;`,
+    `var mode=m==='light'||m==='dark'?m:'system';`,
+    `var dark=mode==='dark'||(mode==='system'&&q('(prefers-color-scheme: dark)'));`,
+    `var fallback=dark?${literal(defaultDarkThemeId)}:${literal(defaultLightThemeId)};`,
+    `var want=doc?(dark?doc.darkThemeId:doc.lightThemeId):null;`,
+    `if(typeof want!=='string')want=fallback;`,
+    `var ids=[${builtinThemes.map((theme) => literal(theme.id)).join(',')}];`,
+    `var id=ids.indexOf(want)!==-1?want:null,tokens=null;`
+  )
+  if (options.libraryKey !== undefined) {
+    parts.push(
+      `if(id===null){try{var lib=JSON.parse(get(${literal(options.libraryKey)})||'null');`,
+      `if(lib&&typeof lib==='object'&&lib.version===${Number(options.libraryVersion ?? 1)}&&Array.isArray(lib.themes)){`,
+      `for(var i=0;i!==lib.themes.length;i++){var t=lib.themes[i];`,
+      `if(t&&t.id===want&&t.flatTokens&&typeof t.flatTokens==='object'){id=want;tokens=t.flatTokens;break}}}}catch(e){}}`
+    )
+  }
+  parts.push(
+    `if(id===null)id=fallback;`,
+    `r.classList.toggle('dark',dark);`,
+    `s.colorScheme=dark?'dark':'light';`,
+    `r.dataset.theme=id;`,
+    `r.dataset.appearance=dark?'dark':'light';`
+  )
+  if (options.libraryKey !== undefined) {
+    parts.push(
+      `if(tokens){for(var n in tokens){if(Object.prototype.hasOwnProperty.call(tokens,n)&&n.slice(0,2)==='--'&&typeof tokens[n]==='string')s.setProperty(n,tokens[n])}}`
+    )
+  }
+  parts.push(
+    `var a=doc&&typeof doc.accent==='string'?doc.accent:'';`,
+    `var accent=[${presets.join(',')}].indexOf(a)!==-1?a:/^#[0-9a-fA-F]{6}$/.test(a)?'custom':a.slice(0,5)==='ansi-'?'':${literal(defaultAccent)};`,
+    `if(accent)r.dataset.accent=accent;`,
+    `if(doc&&doc.density==='compact')r.dataset.density='compact';`
+  )
+  if (options.surface) {
+    parts.push(
+      // Reduce Transparency forces the opaque surface; a translucent request resolves
+      // to frosted because the host's capability is unknown before the provider mounts.
+      `var reduce=q(${literal(REDUCED_TRANSPARENCY_QUERY)})||!!(doc&&doc.reduceTransparency===true);`,
+      `var surface=reduce?'opaque':doc&&(doc.surface==='frosted'||doc.surface==='translucent')?'frosted':'opaque';`,
+      `r.dataset.surface=surface;`,
+      `r.dataset.reduceTransparency=reduce?'true':'false';`,
+      `s.setProperty('--surface-alpha',${JSON.stringify(surfaceAlpha)}[surface]);`
+    )
+  }
+  parts.push(`}catch(e){}})();`)
+
+  return `${parts.join('')}${fontSettingsBootstrapScript(options.key, options.version)}`
+}

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

@@ -5,6 +5,8 @@ import {
 } from '#lib/appearance-font-settings'
 import type { AccentPreset } from '@adea-ai/themes'
 import { normalizeCustomAccent, type AccentRoles } from '#lib/accent-roles'
+import { stepAppearanceFontSizes, type FontZoomIntent } from '#lib/font-zoom'
+import type { ThemeSurface } from '#lib/theme-surface'
 import {
   accentRolesForSelection,
   defaultDarkThemeId,
@@ -63,6 +65,30 @@ export type ThemeSelection = {
    * keeps working and `ThemeSelection` stays assignable without it.
    */
   density?: ThemeDensity
+  /**
+   * The terminal either follows the interface theme (`theme`, or absent) or is pinned
+   * to another theme's terminal palette by that theme's id. The pin is written over
+   * the interface variant's own `--terminal-*` properties, so a light interface can
+   * carry a dark terminal.
+   *
+   * An id the registry does not hold paints the interface palette and stays in the
+   * selection, the same rule as an unknown theme id.
+   *
+   * Optional and not defaulted: see {@link defaultThemeSelection}.
+   */
+  terminalThemeId?: string
+  /**
+   * How opaque elevated panels are. Written to `<html>` only when the provider's
+   * `surface` prop is on or this is set; absent, a host paints no surface axis at
+   * all. Resolved against the OS and the host's capability before it is painted —
+   * see `resolveSurface` — so the value stored is a preference, never the outcome.
+   */
+  surface?: ThemeSurface
+  /**
+   * The user's own Reduce Transparency switch, which forces the `opaque` surface the
+   * same way the operating system's setting does.
+   */
+  reduceTransparency?: boolean
 }
 
 /**
@@ -143,6 +169,24 @@ export type ThemeContextValue = {
    * registry does not hold: each means "keep the inherited accent".
    */
   accentRolesFor: (accent: string | null, variantId?: string) => AccentRoles | undefined
+  /**
+   * The surface the committed selection paints, after Reduce Transparency and the
+   * host's translucency capability. `opaque` when the axis is off. Follows the
+   * committed selection, not a preview, like {@link ThemeContextValue.variant}.
+   */
+  effectiveSurface: () => ThemeSurface
+  /**
+   * True while the operating system or the selection's `reduceTransparency` forces
+   * opaque surfaces. Always false when the surface axis is off, because nothing is
+   * then listening to the operating system.
+   */
+  reduceTransparencyActive: () => boolean
+  /**
+   * Step the three text sizes together, or put them back to the defaults: what the
+   * `fontZoom` prop's chords do, for a host that binds its own keys or a menu. Goes
+   * through {@link ThemeContextValue.setSelection}, so it persists and ends a preview.
+   */
+  zoomFonts: (intent: FontZoomIntent) => void
 }
 
 /** A selection with the `undefined` keys of a patch left out. */
@@ -231,6 +275,34 @@ export function resolveThemeState(
   }
 }
 
+/**
+ * The variant whose terminal palette is pinned, or `undefined` when the terminal
+ * follows the interface theme.
+ *
+ * `theme`, an absent id and an id the registry does not hold all mean the interface
+ * palette: a terminal must never resolve to a blank or half-painted palette because a
+ * theme was deleted after it was pinned.
+ */
+export function resolveTerminalVariant(
+  terminalThemeId: string | undefined,
+  registry: readonly ThemeVariant[]
+): ThemeVariant | undefined {
+  if (terminalThemeId === undefined || terminalThemeId === 'theme') return undefined
+  return registry.find((candidate) => candidate.id === terminalThemeId)
+}
+
+/**
+ * The font settings a zoom chord asks for: one pixel up or down on every axis, or
+ * the defaults for `reset`.
+ */
+export function zoomedFontSettings(
+  selection: ThemeSelection,
+  intent: FontZoomIntent
+): AppearanceEditorFontSettings {
+  if (intent === 'reset') return { ...DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS }
+  return stepAppearanceFontSizes(selection.fonts, intent === 'in' ? 1 : -1)
+}
+
 /**
  * The registry a provider resolves against: the catalogue, then the host's extras.
  *

package/src/index.ts

@@ -144,6 +144,7 @@ export {
   isThemeAccentId,
   resolveAccentPreset,
   resolveVariant,
+  terminalCssVariables,
   themeAccentsFor,
   themeById,
   themeCssVariables,
@@ -164,6 +165,31 @@ export {
   type ThemeTerminalPalette,
   type ThemeVariant,
 } from './lib/themes'
+export { fontZoomShortcut, stepAppearanceFontSizes, type FontZoomIntent } from './lib/font-zoom'
+export {
+  REDUCED_TRANSPARENCY_QUERY,
+  normalizeSurface,
+  resolveSurface,
+  resolveSurfaceState,
+  surfaceAlpha,
+  themeSurfaces,
+  type SurfaceEnvironment,
+  type SurfaceState,
+} from './lib/theme-surface'
+export {
+  defaultPreferenceStorage,
+  quarantineRecord,
+  readLegacyValue,
+  readVersionedRecord,
+  recoveryEnvelope,
+  recoveryKeyFor,
+  writeVersionedRecord,
+  type PreferenceStorage,
+  type RecoveryEnvelope,
+  type RecoveryReason,
+  type VersionedRead,
+  type VersionedRecordSchema,
+} from './lib/preference-store'
 export { keyedRows, type KeyedRow } from './lib/keyed-rows'
 export { writeClipboardText } from './lib/clipboard'
 export { formatBytes, formatReleaseDate, plainTextFromMarkdown } from './lib/version-notes'

package/src/lib/font-zoom.ts

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2026 Wing
+ * Licensed under the MIT License.
+ *
+ * The platform zoom chords, mapped onto Adea's three text roles.
+ *
+ * macOS (and Windows/Linux) zoom shortcuts — Cmd/Ctrl with `=`, `+`, `-`, or
+ * `0` — normally scale the browser's page zoom. In Adea every text element is
+ * already tied to one of the three appearance font tiers (the UI tier drives
+ * the whole `text-*` scale through `--font-ui-scale`; content and code roles
+ * scale through their own tokens), so stepping those tiers reproduces zoom
+ * while keeping the app inside its tokenized, persisted type system: the page
+ * layout, menus, sheets, and terminals reflow live from the same projection
+ * the appearance editor writes.
+ *
+ * Translated from Adea's accepted port (`packages/ui/src/components/font-zoom.ts`) so
+ * the shared provider and Adea run one implementation. See NOTICE.
+ */
+import {
+  APPEARANCE_EDITOR_FONT_AXES,
+  APPEARANCE_EDITOR_FONT_SIZE_MAX,
+  APPEARANCE_EDITOR_FONT_SIZE_MIN,
+  normalizeAppearanceEditorFontSettings,
+  type AppearanceEditorFontSettings,
+} from '#lib/appearance-font-settings'
+
+/** What the user's zoom chord asked for. */
+export type FontZoomIntent = 'in' | 'out' | 'reset'
+
+/**
+ * Classify the platform zoom chord: Cmd (macOS) or Ctrl (other platforms)
+ * with `=`/`+` zooming in, `-` zooming out, and `0` resetting to the System
+ * defaults. Unmodified keys, Alt-modified chords, and IME composition never
+ * count, so typing and text editing are untouched.
+ */
+export function fontZoomShortcut(event: {
+  key: string
+  metaKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  isComposing?: boolean
+}): FontZoomIntent | undefined {
+  if (event.isComposing || event.altKey) return undefined
+  if (!(event.metaKey || event.ctrlKey)) return undefined
+  if (event.key === '=' || event.key === '+') return 'in'
+  if (event.key === '-') return 'out'
+  if (event.key === '0') return 'reset'
+  return undefined
+}
+
+/** Clamp a pixel size to the shared range the appearance editor enforces. */
+function clampFontSize(size: number): number {
+  return Math.min(APPEARANCE_EDITOR_FONT_SIZE_MAX, Math.max(APPEARANCE_EDITOR_FONT_SIZE_MIN, size))
+}
+
+/**
+ * Step every text tier by `delta` pixels, clamped to that range. The axes move
+ * together — that is what makes the chord read as zoom — and each keeps its
+ * own family choice.
+ */
+export function stepAppearanceFontSizes(
+  fonts: unknown,
+  delta: 1 | -1
+): AppearanceEditorFontSettings {
+  const current = normalizeAppearanceEditorFontSettings(fonts).settings
+  return {
+    ui: { ...current.ui, size: clampFontSize(current.ui.size + delta) },
+    content: { ...current.content, size: clampFontSize(current.content.size + delta) },
+    code: { ...current.code, size: clampFontSize(current.code.size + delta) },
+  }
+}
+
+/** Every axis name, for callers that want to report or test the stepping. */
+export const FONT_ZOOM_AXES = APPEARANCE_EDITOR_FONT_AXES