@adea-ai/ui 0.125.0 → 0.127.0

package/dist/r/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/dist/r/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/dist/r/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 './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

package/dist/r/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
+  }
+}