@adea-ai/ui 0.124.0 → 0.127.0

package/dist/r/src/lib/accent-roles.ts

@@ -0,0 +1,338 @@
+/*
+ * Copyright (c) 2026 Wing
+ * SPDX-License-Identifier: MIT
+ *
+ * The colour helpers, the contrast gate and the custom-accent grammar are
+ * substantially translated from Zeron's `Color` and `AccentRoles`
+ * (https://github.com/zeronsh/zeron), as Adea's accepted port of them in
+ * `packages/ui/src/components/appearance.ts` expresses it. Extracted here so the
+ * shared provider and Adea run one implementation; `@adea-ai/themes` owns the
+ * colour engine (parsing, contrast, repair, the preset values and their roles).
+ * See NOTICE.
+ */
+
+import {
+  ACCENTS,
+  accentRoles,
+  accentValue,
+  primarySubtleCss,
+  type AccentPreset,
+  type AccentRoles as CatalogueAccentRoles,
+} from '@adea-ai/themes'
+import {
+  contrastRatio as canonicalContrastRatio,
+  oklchToHex,
+  parseColor as parseCanonicalColor,
+  repairContrast,
+  type Oklch,
+} from '@adea-ai/themes/oklch'
+import type { ThemeAppearance } from './themes'
+
+/**
+ * Accent colour maths and the roles an accent paints.
+ *
+ * Three questions live here, and none of them touches the document or a signal:
+ *
+ *   - **What colour is this?** `parseColor`, `colorToHex`, `contrastRatio` and
+ *     `ensureContrast` are the hex helpers a host needs around an accent (an
+ *     imported theme's colours, a colour field). Hex is the host preference format;
+ *     the catalogue's colour engine does the maths.
+ *   - **Is this accent readable on this surface?** The *contrast floor*. A preset is
+ *     curated, so the catalogue already measured it against its own themes and the
+ *     floor is the identity for it; a custom `#rrggbb` is anyone's choice, so it is
+ *     raised until it clears the floor and can never ship unreadable. A host that
+ *     imports themes (whose backgrounds the catalogue never saw) turns the floor on
+ *     for presets too.
+ *   - **Which custom properties does an accent own?** `AccentRoles`, written on
+ *     `<html>` by the provider and onto one element by {@link paintAccentRoles}.
+ */
+
+/* Hex is the host preference format; the shared Themes package owns colour maths. */
+
+export type RgbColor = Readonly<{ r: number; g: number; b: number; a: number }>
+
+const HEX = /^#([0-9a-fA-F]+)$/
+
+/** Parse a hex colour (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`). `undefined` for anything else. */
+export function parseColor(value: string): RgbColor | undefined {
+  const match = HEX.exec(value.trim())
+  const digits = match?.[1]
+  if (!digits) return undefined
+  if (digits.length === 3 || digits.length === 4) {
+    // Each nibble is doubled: `#abc` is `#aabbcc`.
+    const [r, g, b, a] = [...digits].map((digit) => Number.parseInt(digit + digit, 16))
+    return { r: r!, g: g!, b: b!, a: a ?? 255 }
+  }
+  if (digits.length === 6 || digits.length === 8) {
+    const byte = (index: number) => Number.parseInt(digits.slice(index, index + 2), 16)
+    return { r: byte(0), g: byte(2), b: byte(4), a: digits.length === 8 ? byte(6) : 255 }
+  }
+  return undefined
+}
+
+function toHexByte(value: number): string {
+  return value.toString(16).padStart(2, '0')
+}
+
+/** `#rrggbb`, or `#rrggbbaa` when the colour is not opaque. */
+export function colorToHex(color: RgbColor): string {
+  const opaque = `#${toHexByte(color.r)}${toHexByte(color.g)}${toHexByte(color.b)}`
+  return color.a === 255 ? opaque : `${opaque}${toHexByte(color.a)}`
+}
+
+function blendOver(foreground: RgbColor, background: RgbColor): RgbColor {
+  const alpha = foreground.a / 255
+  const blend = (front: number, back: number) => Math.round(front * alpha + back * (1 - alpha))
+  return {
+    r: blend(foreground.r, background.r),
+    g: blend(foreground.g, background.g),
+    b: blend(foreground.b, background.b),
+    a: 255,
+  }
+}
+
+function toCanonicalColor(color: RgbColor): Oklch | undefined {
+  return parseCanonicalColor(colorToHex({ ...color, a: 255 }))
+}
+
+/** WCAG contrast ratio between two colours. Alpha composites over the background first. */
+export function contrastRatio(
+  foreground: RgbColor | string,
+  background: RgbColor | string
+): number {
+  const front = typeof foreground === 'string' ? parseColor(foreground) : foreground
+  const back = typeof background === 'string' ? parseColor(background) : background
+  if (!front || !back) return 0
+  const opaqueFront = front.a === 255 ? front : blendOver(front, back)
+  const foregroundColor = toCanonicalColor(opaqueFront)
+  const backgroundColor = toCanonicalColor(back)
+  if (!foregroundColor || !backgroundColor) return 0
+  return canonicalContrastRatio(foregroundColor, backgroundColor)
+}
+
+const WHITE: RgbColor = { r: 255, g: 255, b: 255, a: 255 }
+const WHITE_OKLCH: Oklch = { l: 1, c: 0, h: 0 }
+
+/**
+ * The nearest colour to `source` that reaches `minimum` against `canvas`, as hex.
+ *
+ * The catalogue's `repairContrast` is asked for a little more than the floor, in
+ * 0.001 steps up to 0.05, because the result is rounded to 8-bit hex and the
+ * rounded colour is what is measured: asking for exactly the floor can land a hair
+ * under it after rounding. If nothing in that range survives the rounding, white or
+ * black stands in, whichever clears the floor.
+ */
+function repairedHex(source: Oklch, canvas: Oklch, minimum: number): string {
+  for (let margin = 0; margin <= 0.05; margin = Number((margin + 0.001).toFixed(3))) {
+    const repaired = repairContrast(source, canvas, minimum + margin)
+    if (!repaired.satisfied) continue
+    const hex = oklchToHex(repaired.color)
+    const rounded = parseCanonicalColor(hex)
+    if (rounded && canonicalContrastRatio(rounded, canvas) >= minimum) return hex
+  }
+  return canonicalContrastRatio(WHITE_OKLCH, canvas) >= minimum ? '#ffffff' : '#000000'
+}
+
+/** Preserve the host hex shape while delegating contrast repair to the catalogue. */
+export function ensureContrast(color: RgbColor, background: RgbColor, minimum: number): RgbColor {
+  if (contrastRatio(color, background) >= minimum) return color
+
+  const renderedColor = color.a === 255 ? color : blendOver(color, background)
+  const source = toCanonicalColor(renderedColor)
+  const canvas = toCanonicalColor(background)
+  if (!source || !canvas) return color
+  return parseColor(repairedHex(source, canvas, minimum))!
+}
+
+/** The contrast an accent is held to against its surface unless the host sets another. */
+export const DEFAULT_ACCENT_CONTRAST_FLOOR = 3
+
+/**
+ * Normalise a custom accent against a surface: unparseable input is rejected
+ * (`undefined`), and any accepted colour is raised to `minimum` so an accent can
+ * never ship unreadable. Accepts every CSS hex length; for the stored grammar use
+ * {@link normalizeCustomAccent}.
+ */
+export function normalizeAccentValue(
+  value: string,
+  background: string,
+  minimum: number = DEFAULT_ACCENT_CONTRAST_FLOOR
+): string | undefined {
+  const parsed = parseColor(value)
+  if (!parsed) return undefined
+  const backdrop = parseColor(background) ?? WHITE
+  return colorToHex(ensureContrast(parsed, backdrop, minimum))
+}
+
+/**
+ * The stored form of a custom accent: `#rrggbb`, six digits, opaque, lower case.
+ *
+ * Deliberately narrower than {@link parseColor}. A stored accent is compared,
+ * deduplicated and used as an attribute, so it has one spelling; a host that
+ * accepts `#abc` in a field expands it before storing. Anything else — a name, an
+ * `rgb()`, a short or alpha form, a non-string — is not an accent and returns
+ * `undefined`.
+ */
+export function normalizeCustomAccent(value: unknown): string | undefined {
+  return typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value)
+    ? value.toLowerCase()
+    : undefined
+}
+
+/** Whether a selection's accent is the custom `#rrggbb` form (any letter case). */
+export function isCustomAccent(value: unknown): boolean {
+  return normalizeCustomAccent(value) !== undefined
+}
+
+/**
+ * The roles an accent paints, as CSS values: the catalogue's `AccentRoles`, so the
+ * provider, the generated stylesheet and a host's own paint cannot disagree about
+ * what a role is. `primarySubtle` is an expression over `var(--primary)`; the
+ * document writer never sets it (see {@link accentOverrideVariables}), an element
+ * paint must.
+ */
+export type AccentRoles = CatalogueAccentRoles
+
+/** What an accent resolves against: the surface it sits on and the theme it sits in. */
+export type AccentTarget = {
+  /** The theme, or only its appearance. A theme gives the tint its measured strength. */
+  target: Parameters<typeof accentRoles>[1]
+  /** The surface the accent must read on. Without it nothing can be measured or repaired. */
+  background: string | undefined
+  /**
+   * The contrast to hold the accent to against `background`. Absent, a preset is
+   * painted verbatim and a custom colour is held to {@link DEFAULT_ACCENT_CONTRAST_FLOOR}.
+   */
+  floor?: number
+  /**
+   * The accents the selected theme pair carries (`ansi-blue`…), for an id that is
+   * neither a preset nor a colour.
+   */
+  themeAccents?: readonly AccentPreset[]
+}
+
+function appearanceOf(target: AccentTarget['target']): ThemeAppearance {
+  return typeof target === 'string' ? target : target.appearance
+}
+
+/**
+ * `value` raised to `floor` against `background` as hex, or `value` itself when it
+ * already clears the floor, is not a colour, or there is no surface to measure it on.
+ *
+ * Returning the argument itself is what makes the floor the identity for a preset
+ * that already reads: the caller compares and keeps the catalogue's own roles.
+ */
+function gateColor(value: string, background: string | undefined, floor: number): string {
+  const source = parseCanonicalColor(value)
+  const canvas = background ? parseCanonicalColor(background) : undefined
+  if (!source || !canvas) return value
+  if (canonicalContrastRatio(source, canvas) >= floor) return value
+  return repairedHex(source, canvas, floor)
+}
+
+/**
+ * The roles for a preset (or a custom colour made into one), held to the floor.
+ *
+ * A preset that clears the floor keeps the catalogue's roles untouched. One that
+ * does not is repaired to the nearest passing colour and the whole role set is
+ * rebuilt from the repaired value, so the label, hover and ring follow it instead
+ * of describing a colour that is no longer on screen.
+ */
+export function accentRolesForPreset(
+  preset: AccentPreset,
+  context: AccentTarget
+): AccentRoles | undefined {
+  const appearance = appearanceOf(context.target)
+  const requested = accentValue(preset, appearance)
+  if (!parseCanonicalColor(requested)) return undefined
+
+  const floor = context.floor
+  if (floor === undefined) return accentRoles(preset, context.target)
+
+  const gated = gateColor(requested, context.background, floor)
+  if (gated === requested) return accentRoles(preset, context.target)
+
+  const roles = accentRoles({ ...preset, light: gated, dark: gated }, context.target)
+  // The tint's strength is measured against the primary it will sit over, and the
+  // repaired primary is not one the theme's own measurement saw.
+  return { ...roles, primarySubtle: primarySubtleCss(context.target, '--primary', [gated]) }
+}
+
+/**
+ * Resolve an accent selection to its roles, or `undefined` when it overrides nothing.
+ *
+ * `undefined` is "use the theme's own primary": the literal `theme`, an id that is
+ * neither a preset, an offered theme accent nor a colour, and a colour that does not
+ * parse. A host that wants one of those to mean something else decides before
+ * asking (Adea's codec maps a stored `theme` to its default preset when it reads).
+ */
+export function resolveAccentRoles(accent: string, context: AccentTarget): AccentRoles | undefined {
+  if (accent === 'theme') return undefined
+
+  const custom = normalizeCustomAccent(accent)
+  if (custom) {
+    const floor = context.floor ?? DEFAULT_ACCENT_CONTRAST_FLOOR
+    return accentRolesForPreset(
+      { id: 'custom', label: 'Custom', description: '', light: custom, dark: custom },
+      { ...context, floor }
+    )
+  }
+
+  const preset =
+    ACCENTS.find((candidate) => candidate.id === accent) ??
+    context.themeAccents?.find((candidate) => candidate.id === accent)
+  return preset ? accentRolesForPreset(preset, context) : undefined
+}
+
+/**
+ * The custom properties an accent override owns on `<html>`.
+ *
+ * `--primary-subtle` is deliberately not among them. It is a `color-mix()` over
+ * `var(--primary)`, so on the same element it follows an accent by itself, and its
+ * strength is the theme's, measured to keep body text at 4.5:1 on the tint.
+ * Writing one here would replace that measurement with the argument's.
+ */
+export function accentOverrideVariables(roles: AccentRoles): Record<string, string> {
+  return {
+    '--primary': roles.primary,
+    '--primary-foreground': roles.primaryForeground,
+    '--primary-hover': roles.primaryHover,
+    '--ring': roles.ring,
+  }
+}
+
+/** The custom properties {@link paintAccentRoles} writes and clears. */
+export const ACCENT_PAINT_PROPERTIES = [
+  '--primary',
+  '--primary-foreground',
+  '--primary-hover',
+  '--primary-subtle',
+  '--ring',
+] as const
+
+/**
+ * Scope an accent to one element and its descendants.
+ *
+ * Unlike the document, an element must write `--primary-subtle` too. A custom
+ * property that uses `var()` is resolved where it is declared, so the tint inherited
+ * from `<html>` is already a mix over *`<html>`'s* primary and an element that only
+ * overrides `--primary` would keep the old tint. Declared here, the same expression
+ * resolves against this element's primary.
+ *
+ * `undefined` clears every property, and the element inherits the document's accent
+ * again.
+ */
+export function paintAccentRoles(
+  element: { style: Pick<CSSStyleDeclaration, 'setProperty' | 'removeProperty'> },
+  roles: AccentRoles | undefined
+): void {
+  if (!roles) {
+    for (const property of ACCENT_PAINT_PROPERTIES) element.style.removeProperty(property)
+    return
+  }
+  element.style.setProperty('--primary', roles.primary)
+  element.style.setProperty('--primary-foreground', roles.primaryForeground)
+  element.style.setProperty('--primary-hover', roles.primaryHover)
+  element.style.setProperty('--primary-subtle', roles.primarySubtle)
+  element.style.setProperty('--ring', roles.ring)
+}

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
+  }
+}