@adea-ai/ui 0.124.0 → 0.127.0

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

@@ -1,6 +1,16 @@
+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'
 
 /**
@@ -67,19 +77,32 @@ function readSelection(storageKey: string): ThemeSelection {
           : defaultDarkThemeId,
       // A theme accent is kept whenever it names a slot, even one the stored pair
       // cannot offer: the id is role-shaped so it survives a theme switch, and an
-      // unoffered slot already resolves to the theme's own primary when applied.
+      // unoffered slot already resolves to the theme's own primary when applied. A
+      // custom `#rrggbb` is kept in its one stored spelling; its readability is
+      // settled when it is painted, not when it is read.
       accent:
         typeof parsed.accent === 'string' &&
         (accentPresets.some((preset) => preset.id === parsed.accent) ||
           isThemeAccentId(parsed.accent))
           ? parsed.accent
-          : defaultThemeSelection.accent,
+          : (normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent),
       font: fonts.ui.family,
       fonts,
       // Every axis has to be read back here, or it is lost twice: the provider's
       // 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
@@ -138,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.
+      }
+    },
+  }
+}

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,
@@ -17,16 +17,28 @@ import {
   type ThemePersistence,
 } from './theme-persistence'
 import {
+  accentRolesForState,
   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,
@@ -111,6 +123,57 @@ export type ThemeProviderProps = {
    * element to `<head>` for two frames on every change.
    */
   disableTransitionOnChange?: boolean
+  /**
+   * The contrast ratio an accent is held to against the variant's background,
+   * repaired to the nearest passing colour when it falls short. Absent, presets
+   * are painted verbatim — the catalogue measured them for its own themes — and
+   * only a custom `#rrggbb` is held to 3:1. A host that adds themes the catalogue
+   * never measured passes 3 to hold the presets to it as well; for the catalogue's
+   * 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) {
@@ -123,6 +186,10 @@ export function ThemeProvider(props: ThemeProviderProps) {
     'themes',
     'transformTokens',
     'disableTransitionOnChange',
+    'accentContrastFloor',
+    'surface',
+    'palette',
+    'fontZoom',
   ])
   const storageKey = () => local.storageKey ?? 'adea-appearance'
   const persistence = local.persistence ?? localStoragePersistence(storageKey)
@@ -175,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(() => {
@@ -183,8 +281,14 @@ 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 options = { transformTokens: local.transformTokens }
     const apply = () => {
       written = applyThemeToRoot(document.documentElement, state, options, written)
     }
@@ -201,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,
@@ -212,6 +334,16 @@ export function ThemeProvider(props: ThemeProviderProps) {
       setDraft(next ? { ...next } : undefined)
     },
     previewing: () => draft() !== undefined,
+    accentRolesFor: (accent, variantId) =>
+      accentRolesForState(accent, variantId, {
+        selection: selection(),
+        variant: variant(),
+        registry: registry(),
+        accentContrastFloor: local.accentContrastFloor,
+      }),
+    effectiveSurface: () => committedSurface()?.surface ?? 'opaque',
+    reduceTransparencyActive: () => committedSurface()?.reduceTransparencyActive ?? false,
+    zoomFonts,
     setSelection(patch) {
       const next = mergeThemeSelection(selection(), patch)
       setSelectionState(next)
@@ -224,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)}`
+}