@adea-ai/ui 0.125.0 → 0.128.0

package/dist/NOTICE

@@ -336,6 +336,46 @@ provider are Adea behaviour that port retains.
 Zeron's MIT notice, reproduced in full under "Appearance editor translated from
 Zeron" above, applies to the translated portion.
 
+## Surface policy and font-zoom chords translated from Zeron
+
+`packages/ui/src/lib/theme-surface.ts` and `packages/ui/src/lib/font-zoom.ts`
+are moved from Adea's accepted port of Zeron (https://github.com/zeronsh/zeron),
+`packages/ui/src/components/appearance.ts` and `packages/ui/src/components/font-zoom.ts`,
+so the shared provider and Adea run one implementation. The first carries Zeron's
+`SurfacePreference.resolve` as that port extends it: the translucent capability
+gate (a request the host cannot render paints the tokenized frosted surface) and
+the reduced-transparency policy (the operating system's setting or the user's own
+forces the opaque surface), plus the opacity each surface paints. The second maps
+the platform zoom chords (Cmd or Ctrl with `=`, `+`, `-`, `0`) onto the three text
+sizes. The frost rule and `--surface-*` tokens in `packages/ui/src/styles/theme.css`
+are Adea's, written for that port, and introduce no further upstream source.
+
+    Copyright (c) 2026 Wing
+    Licensed under the MIT License.
+
+Both files retain that header. Zeron's MIT notice, reproduced in full under
+"Appearance editor translated from Zeron" above, applies to the translated portion.
+
+## Preference store recovery translated from Zeron
+
+`packages/ui/src/lib/preference-store.ts` is moved from Adea's accepted port of
+Zeron (https://github.com/zeronsh/zeron), `packages/ui/src/components/appearance.ts`,
+so the shared provider and Adea run one implementation. It carries the recovery
+behaviour of that port: an unreadable or unsupported stored document is quarantined
+byte for byte into a recovery envelope at read time, before any write can touch the
+main key; the legacy single-key value is read only while the main key is absent and
+is never deleted; and blocked storage reads as nothing stored. The envelope shape is
+unchanged. The no-flash boot script in `packages/ui/src/components/theme/theme-script.ts`
+is rewritten from that port's `appearanceThemeScript` to read the same document, and
+introduces no further upstream source.
+
+    Copyright (c) 2026 Wing
+    Licensed under the MIT License.
+
+`preference-store.ts` retains that header. Zeron's MIT notice, reproduced in full
+under "Appearance editor translated from Zeron" above, applies to the translated
+portion.
+
 ## Strict binary layout extracted from the accepted Adea donor port
 
 `packages/ui/src/components/layout/split-layout/model.ts` is extracted from

package/dist/components/theme/index.d.ts

@@ -1,6 +1,6 @@
 export { AppearancePanel, type AppearancePanelProps } from './appearance-panel';
 export { ThemePicker, ThemePreview, ThemeSwatch, type ThemePickerProps, type ThemePreviewProps, type ThemeSwatchProps, } from './theme-picker';
-export { ThemeProvider, defaultThemeSelection, inlineScriptLiteral, localStoragePersistence, resolvedDensity, themeScript, useOptionalTheme, useTheme, type ThemeContextValue, type ThemeDensity, type ThemePersistence, type ThemeProviderProps, type ThemeSelection, } from './theme-provider';
+export { ThemeProvider, createVersionedPersistence, defaultThemeSelection, inlineScriptLiteral, localStoragePersistence, resolvedDensity, themeScript, useOptionalTheme, useTheme, type EditorRolesMode, type ThemeContextValue, type ThemeDensity, type ThemePersistence, type ThemeProviderProps, type ThemeScriptOptions, type ThemeSelection, type ThemeStorageSchema, type ThemeSurface, type VersionedCodec, type VersionedPersistenceOptions, } from './theme-provider';
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle';
 export { ThemeModeToggle, type ThemeModeToggleProps } from './theme-mode-toggle';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,2BAA2B,GACjC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/components/theme/index.js

@@ -1,9 +1,10 @@
 import { ThemePicker, ThemePreview, ThemeSwatch } from "./theme-picker.js";
 import { useOptionalTheme, useTheme } from "./theme-context.js";
 import { defaultThemeSelection, resolvedDensity } from "./theme-state.js";
-import { localStoragePersistence } from "./theme-persistence.js";
-import { ThemeProvider, inlineScriptLiteral, themeScript } from "./theme-provider.js";
+import { createVersionedPersistence, localStoragePersistence } from "./theme-persistence.js";
+import { inlineScriptLiteral, themeScript } from "./theme-script.js";
+import { ThemeProvider } from "./theme-provider.js";
 import { AppearancePanel } from "./appearance-panel.js";
 import { ThemeToggle } from "./theme-toggle.js";
 import { ThemeModeToggle } from "./theme-mode-toggle.js";
-export { AppearancePanel, ThemeModeToggle, ThemePicker, ThemePreview, ThemeProvider, ThemeSwatch, ThemeToggle, defaultThemeSelection, inlineScriptLiteral, localStoragePersistence, resolvedDensity, themeScript, useOptionalTheme, useTheme };
+export { AppearancePanel, ThemeModeToggle, ThemePicker, ThemePreview, ThemeProvider, ThemeSwatch, ThemeToggle, createVersionedPersistence, defaultThemeSelection, inlineScriptLiteral, localStoragePersistence, resolvedDensity, themeScript, useOptionalTheme, useTheme };

package/dist/components/theme/theme-document.d.ts

@@ -1,4 +1,5 @@
-import { type ThemeAppearance, type ThemeVariant } from '#lib/themes';
+import { type EditorRolesMode, type ThemeAppearance, type ThemeVariant } from '#lib/themes';
+import { type SurfaceState } from '#lib/theme-surface';
 import { type ThemeSelection } from './theme-state';
 /**
  * The document half of the theme provider: the single writer of `<html>`.
@@ -12,6 +13,16 @@ export type ThemeDocumentState = {
     selection: ThemeSelection;
     appearance: ThemeAppearance;
     variant: ThemeVariant;
+    /**
+     * The variant whose terminal palette is pinned over the interface variant's.
+     * Absent, the terminal follows the interface theme.
+     */
+    terminalVariant?: ThemeVariant;
+    /**
+     * The resolved surface axis. Absent, the axis is off: no attribute and no
+     * `--surface-alpha` is written, and any this writer wrote before is removed.
+     */
+    surface?: SurfaceState;
 };
 export type ThemeDocumentOptions = {
     /**
@@ -26,10 +37,34 @@ export type ThemeDocumentOptions = {
      * only a custom `#rrggbb` is held to the default floor of 3:1.
      */
     accentContrastFloor?: number;
+    /**
+     * Where a catalogue variant's palette comes from. `inline` (the default) writes
+     * every role onto the root. `stylesheet` writes none for a catalogue variant,
+     * because the host loads a stylesheet that carries a `[data-theme]` block for it;
+     * a variant the catalogue does not hold (a host's imported theme) is still written
+     * inline, since no stylesheet can know it. The accent, the terminal pin, the
+     * surface alpha and the fonts are written the same in both.
+     *
+     * Switching from an imported variant back to a catalogue one removes what the
+     * imported one wrote, so nothing inline outlives it to beat the stylesheet.
+     */
+    palette?: 'inline' | 'stylesheet';
+    /**
+     * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet
+     * syntax roles, which is what `theme-variants.css` carries; `floor` holds every
+     * editor role to 4.5:1 on the canvas, as hex.
+     *
+     * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue
+     * variant still gets: the stylesheet is generated for the default projection, so
+     * the sixteen `--editor-*` properties are written inline over it. The rest of the
+     * palette stays in the stylesheet.
+     */
+    editorRoles?: EditorRolesMode;
 };
 /**
  * The custom properties a state paints: the variant's roles, with the accent
- * selection laid over them, then `transformTokens`.
+ * selection laid over them, the pinned terminal palette over that, the surface
+ * alpha, then `transformTokens`.
  *
  * The accent is applied *here* rather than left to the `[data-accent]` blocks in
  * `theme.css`, because the properties are written inline and an inline declaration

package/dist/components/theme/theme-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-document.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-document.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAC1B,WAAW,EACX,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,iBAAiB,GAAG,cAAc,CACvE,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,mFAAmF;IACnF,SAAS,EAAE,cAAc,CAAA;IACzB,UAAU,EAAE,eAAe,CAAA;IAC3B,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5E;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,oBAAyB,GACjC;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAYvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,oBAAyB,EAClC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,WAAW,CAAC,MAAM,CAAC,CAsCrB;AAED,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE;QAAE,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAA;IAC7C,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG;QAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,MAAM,IAAI,IAAI,CAAA;KACf,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,IAAI,EACjB,QAAQ,GAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAsB,GACzD,MAAM,IAAI,CAqBZ"}
+{"version":3,"file":"theme-document.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-document.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACpE,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAC1B,WAAW,EACX,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,iBAAiB,GAAG,cAAc,CACvE,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,mFAAmF;IACnF,SAAS,EAAE,cAAc,CAAA;IACzB,UAAU,EAAE,eAAe,CAAA;IAC3B,OAAO,EAAE,YAAY,CAAA;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,YAAY,CAAA;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5E;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IACjC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,eAAe,CAAA;CAC9B,CAAA;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,oBAAyB,GACjC;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAqBvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,oBAAyB,EAClC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,WAAW,CAAC,MAAM,CAAC,CAiDrB;AAED,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE;QAAE,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAA;IAC7C,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG;QAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,MAAM,IAAI,IAAI,CAAA;KACf,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,IAAI,EACjB,QAAQ,GAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAsB,GACzD,MAAM,IAAI,CAqBZ"}

package/dist/components/theme/theme-document.js

@@ -1,11 +1,22 @@
 import { isCustomAccent } from "../../lib/accent-roles.js";
-import { accentVariables, themeCssVariables } from "../../lib/themes.js";
+import { accentVariables, isCatalogueVariant, terminalCssVariables, themeCssVariables } from "../../lib/themes.js";
 import { applyAppearanceFontSettings, normalizeAppearanceEditorFontSettings } from "../../lib/appearance-font-settings.js";
+import { surfaceAlpha } from "../../lib/theme-surface.js";
 import { resolvedDensity } from "./theme-state.js";
 //#region src/components/theme/theme-document.ts
 /**
+* What a catalogue variant still writes inline when its palette is the stylesheet's:
+* nothing, unless the editor projection is not the one the stylesheet was generated
+* for.
+*/
+function stylesheetOverrides(variant, editorRoles) {
+	if (editorRoles !== "floor") return {};
+	return Object.fromEntries(Object.entries(themeCssVariables(variant, { editor: "floor" })).filter(([name]) => name.startsWith("--editor-")));
+}
+/**
 * The custom properties a state paints: the variant's roles, with the accent
-* selection laid over them, then `transformTokens`.
+* selection laid over them, the pinned terminal palette over that, the surface
+* alpha, then `transformTokens`.
 *
 * The accent is applied *here* rather than left to the `[data-accent]` blocks in
 * `theme.css`, because the properties are written inline and an inline declaration
@@ -15,13 +26,15 @@ import { resolvedDensity } from "./theme-state.js";
 * set, the rules were present, and nothing changed on screen.
 */
 function themeDocumentTokens(state, options = {}) {
-	const properties = { ...themeCssVariables(state.variant) };
+	const properties = options.palette === "stylesheet" && isCatalogueVariant(state.variant) ? stylesheetOverrides(state.variant, options.editorRoles) : { ...themeCssVariables(state.variant, { editor: options.editorRoles }) };
 	const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {
 		background: state.variant.colors.background,
 		floor: options.accentContrastFloor,
 		variantId: state.variant.id
 	});
 	if (accent) Object.assign(properties, accent);
+	if (state.terminalVariant) Object.assign(properties, terminalCssVariables(state.terminalVariant));
+	if (state.surface) properties["--surface-alpha"] = surfaceAlpha[state.surface.surface];
 	return {
 		tokens: options.transformTokens ? options.transformTokens(properties) : properties,
 		accented: accent !== void 0
@@ -48,6 +61,13 @@ function applyThemeToRoot(root, state, options = {}, previous) {
 	root.style.colorScheme = state.appearance;
 	if (!accented) root.removeAttribute("data-accent");
 	else root.dataset["accent"] = isCustomAccent(state.selection.accent) ? "custom" : state.selection.accent;
+	if (state.surface) {
+		root.dataset["surface"] = state.surface.surface;
+		root.dataset["reduceTransparency"] = state.surface.reduceTransparencyActive ? "true" : "false";
+	} else {
+		root.removeAttribute("data-surface");
+		root.removeAttribute("data-reduce-transparency");
+	}
 	applyAppearanceFontSettings(root, normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings);
 	if (resolvedDensity(state.selection) === "comfortable") root.removeAttribute("data-density");
 	else root.dataset["density"] = resolvedDensity(state.selection);

package/dist/components/theme/theme-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme-document.js","names":[],"sources":["../../../src/components/theme/theme-document.ts"],"sourcesContent":["import {\n  applyAppearanceFontSettings,\n  normalizeAppearanceEditorFontSettings,\n} from '#lib/appearance-font-settings'\nimport {\n  accentVariables,\n  themeCssVariables,\n  type ThemeAppearance,\n  type ThemeVariant,\n} from '#lib/themes'\nimport { isCustomAccent } from '#lib/accent-roles'\nimport { resolvedDensity, type ThemeSelection } from './theme-state'\n\n/**\n * The document half of the theme provider: the single writer of `<html>`.\n *\n * Written against the few members of an element it uses, so the rules can be tested\n * on a stand-in and the provider's effect stays a one-line call.\n */\nexport type ThemeRoot = Pick<\n  HTMLElement,\n  'classList' | 'dataset' | 'style' | 'removeAttribute' | 'setAttribute'\n>\n\nexport type ThemeDocumentState = {\n  /** What the document shows: the committed selection, or a preview laid over it. */\n  selection: ThemeSelection\n  appearance: ThemeAppearance\n  variant: ThemeVariant\n}\n\nexport type ThemeDocumentOptions = {\n  /**\n   * Rewrites the custom properties just before they are written: the variant's\n   * roles with the accent laid over them. It sees every property of the pass and\n   * must return the full map; a name it drops is not written.\n   */\n  transformTokens?: (tokens: Record<string, string>) => Record<string, string>\n  /**\n   * The contrast an accent is held to against the variant's background. Absent, a\n   * preset is painted verbatim (the catalogue measured it for its own themes) and\n   * only a custom `#rrggbb` is held to the default floor of 3:1.\n   */\n  accentContrastFloor?: number\n}\n\n/**\n * The custom properties a state paints: the variant's roles, with the accent\n * selection laid over them, then `transformTokens`.\n *\n * The accent is applied *here* rather than left to the `[data-accent]` blocks in\n * `theme.css`, because the properties are written inline and an inline declaration\n * outranks every stylesheet selector however specific it is. The blocks still exist\n * and are still correct — they are what styles the window before this runs — but\n * they cannot win from here, so leaving the accent to them meant the attribute was\n * set, the rules were present, and nothing changed on screen.\n */\nexport function themeDocumentTokens(\n  state: ThemeDocumentState,\n  options: ThemeDocumentOptions = {}\n): { tokens: Record<string, string>; accented: boolean } {\n  const properties = { ...themeCssVariables(state.variant) }\n  const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {\n    background: state.variant.colors.background,\n    floor: options.accentContrastFloor,\n    variantId: state.variant.id,\n  })\n  if (accent) Object.assign(properties, accent)\n  return {\n    tokens: options.transformTokens ? options.transformTokens(properties) : properties,\n    accented: accent !== undefined,\n  }\n}\n\n/**\n * Write a state onto a root and report which custom properties it owns.\n *\n * Pass the previous call's return as `previous` and any palette property that pass\n * wrote and this one does not is removed. For the catalogue the two sets are the\n * same, so nothing is ever removed; it matters for a host variant that carries\n * `tokens` the catalogue does not, which would otherwise stay inline, beating the\n * stylesheet, after the user switched away from it.\n */\nexport function applyThemeToRoot(\n  root: ThemeRoot,\n  state: ThemeDocumentState,\n  options: ThemeDocumentOptions = {},\n  previous?: ReadonlySet<string>\n): ReadonlySet<string> {\n  const { tokens, accented } = themeDocumentTokens(state, options)\n\n  for (const [name, value] of Object.entries(tokens)) {\n    root.style.setProperty(name, value)\n  }\n  if (previous) {\n    for (const name of previous) {\n      if (!(name in tokens)) root.style.removeProperty(name)\n    }\n  }\n\n  root.classList.toggle('dark', state.appearance === 'dark')\n  root.dataset['theme'] = state.variant.id\n  root.dataset['appearance'] = state.appearance\n  root.style.colorScheme = state.appearance\n\n  // A custom colour has no stylesheet block to select, and its value is the\n  // attribute's worst possible content, so it is reported as `custom`.\n  if (!accented) root.removeAttribute('data-accent')\n  else\n    root.dataset['accent'] = isCustomAccent(state.selection.accent)\n      ? 'custom'\n      : state.selection.accent\n\n  applyAppearanceFontSettings(\n    root,\n    normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings\n  )\n\n  // Density is a pure token shift, so unlike the colour axes there is nothing to\n  // compute: the attribute selects a block in `theme.css`. It is applied here for\n  // the same reason as the others — this is the one place that knows what the\n  // current selection is, and it is the only writer of these attributes.\n  if (resolvedDensity(state.selection) === 'comfortable') root.removeAttribute('data-density')\n  else root.dataset['density'] = resolvedDensity(state.selection)\n\n  return new Set(Object.keys(tokens))\n}\n\n/** What {@link applyWithoutTransitions} needs of a document. */\nexport type TransitionDocument = {\n  head: { appendChild(node: unknown): unknown }\n  createElement(tag: 'style'): {\n    textContent: string | null\n    offsetHeight?: number\n    remove(): void\n  }\n}\n\n/**\n * Run `apply` with every CSS transition switched off for the frame that carries\n * it, so a theme switch cannot animate page-wide.\n *\n * Without this, flipping the custom properties on `<html>` starts a transition on\n * every element that declares one, and each fades from the old palette to the new\n * over its own duration: a theme change that looks like a rendering fault. The\n * rule is removed two frames later, after the browser has committed the new styles\n * with transitions off, and `restore` runs it early (the provider calls it when it\n * is disposed mid-switch).\n *\n * `schedule` is the frame source; it defaults to `requestAnimationFrame` and falls\n * back to running at once where there is none, which leaves transitions on rather\n * than off.\n */\nexport function applyWithoutTransitions(\n  doc: TransitionDocument,\n  apply: () => void,\n  schedule: (callback: () => void) => void = defaultSchedule\n): () => void {\n  const style = doc.createElement('style')\n  style.textContent = '*{transition:none !important}'\n  doc.head.appendChild(style)\n  // Reading a layout property forces the browser to commit the rule before the\n  // properties change; without it the two can be batched into one style recalc.\n  void style.offsetHeight\n  let removed = false\n  const restore = () => {\n    if (removed) return\n    removed = true\n    style.remove()\n  }\n  try {\n    apply()\n  } catch (error) {\n    restore()\n    throw error\n  }\n  schedule(() => schedule(restore))\n  return restore\n}\n\nfunction defaultSchedule(callback: () => void): void {\n  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(callback)\n  else callback()\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyDA,SAAgB,oBACd,OACA,UAAgC,CAAC,GACsB;CACvD,MAAM,aAAa,EAAE,GAAG,kBAAkB,MAAM,OAAO,EAAE;CACzD,MAAM,SAAS,gBAAgB,MAAM,UAAU,QAAQ,MAAM,YAAY,MAAM,WAAW;EACxF,YAAY,MAAM,QAAQ,OAAO;EACjC,OAAO,QAAQ;EACf,WAAW,MAAM,QAAQ;CAC3B,CAAC;CACD,IAAI,QAAQ,OAAO,OAAO,YAAY,MAAM;CAC5C,OAAO;EACL,QAAQ,QAAQ,kBAAkB,QAAQ,gBAAgB,UAAU,IAAI;EACxE,UAAU,WAAW,KAAA;CACvB;AACF;;;;;;;;;;AAWA,SAAgB,iBACd,MACA,OACA,UAAgC,CAAC,GACjC,UACqB;CACrB,MAAM,EAAE,QAAQ,aAAa,oBAAoB,OAAO,OAAO;CAE/D,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,GAC/C,KAAK,MAAM,YAAY,MAAM,KAAK;CAEpC,IAAI,UACG;OAAA,MAAM,QAAQ,UACjB,IAAI,EAAE,QAAQ,SAAS,KAAK,MAAM,eAAe,IAAI;CAAA;CAIzD,KAAK,UAAU,OAAO,QAAQ,MAAM,eAAe,MAAM;CACzD,KAAK,QAAQ,WAAW,MAAM,QAAQ;CACtC,KAAK,QAAQ,gBAAgB,MAAM;CACnC,KAAK,MAAM,cAAc,MAAM;CAI/B,IAAI,CAAC,UAAU,KAAK,gBAAgB,aAAa;MAE/C,KAAK,QAAQ,YAAY,eAAe,MAAM,UAAU,MAAM,IAC1D,WACA,MAAM,UAAU;CAEtB,4BACE,MACA,sCAAsC,MAAM,UAAU,OAAO,MAAM,UAAU,IAAI,CAAC,CAAC,QACrF;CAMA,IAAI,gBAAgB,MAAM,SAAS,MAAM,eAAe,KAAK,gBAAgB,cAAc;MACtF,KAAK,QAAQ,aAAa,gBAAgB,MAAM,SAAS;CAE9D,OAAO,IAAI,IAAI,OAAO,KAAK,MAAM,CAAC;AACpC;;;;;;;;;;;;;;;;AA2BA,SAAgB,wBACd,KACA,OACA,WAA2C,iBAC/B;CACZ,MAAM,QAAQ,IAAI,cAAc,OAAO;CACvC,MAAM,cAAc;CACpB,IAAI,KAAK,YAAY,KAAK;CAG1B,MAAW;CACX,IAAI,UAAU;CACd,MAAM,gBAAgB;EACpB,IAAI,SAAS;EACb,UAAU;EACV,MAAM,OAAO;CACf;CACA,IAAI;EACF,MAAM;CACR,SAAS,OAAO;EACd,QAAQ;EACR,MAAM;CACR;CACA,eAAe,SAAS,OAAO,CAAC;CAChC,OAAO;AACT;AAEA,SAAS,gBAAgB,UAA4B;CACnD,IAAI,OAAO,0BAA0B,YAAY,sBAAsB,QAAQ;MAC1E,SAAS;AAChB"}
+{"version":3,"file":"theme-document.js","names":[],"sources":["../../../src/components/theme/theme-document.ts"],"sourcesContent":["import {\n  applyAppearanceFontSettings,\n  normalizeAppearanceEditorFontSettings,\n} from '#lib/appearance-font-settings'\nimport {\n  accentVariables,\n  isCatalogueVariant,\n  terminalCssVariables,\n  themeCssVariables,\n  type EditorRolesMode,\n  type ThemeAppearance,\n  type ThemeVariant,\n} from '#lib/themes'\nimport { isCustomAccent } from '#lib/accent-roles'\nimport { surfaceAlpha, type SurfaceState } from '#lib/theme-surface'\nimport { resolvedDensity, type ThemeSelection } from './theme-state'\n\n/**\n * The document half of the theme provider: the single writer of `<html>`.\n *\n * Written against the few members of an element it uses, so the rules can be tested\n * on a stand-in and the provider's effect stays a one-line call.\n */\nexport type ThemeRoot = Pick<\n  HTMLElement,\n  'classList' | 'dataset' | 'style' | 'removeAttribute' | 'setAttribute'\n>\n\nexport type ThemeDocumentState = {\n  /** What the document shows: the committed selection, or a preview laid over it. */\n  selection: ThemeSelection\n  appearance: ThemeAppearance\n  variant: ThemeVariant\n  /**\n   * The variant whose terminal palette is pinned over the interface variant's.\n   * Absent, the terminal follows the interface theme.\n   */\n  terminalVariant?: ThemeVariant\n  /**\n   * The resolved surface axis. Absent, the axis is off: no attribute and no\n   * `--surface-alpha` is written, and any this writer wrote before is removed.\n   */\n  surface?: SurfaceState\n}\n\nexport type ThemeDocumentOptions = {\n  /**\n   * Rewrites the custom properties just before they are written: the variant's\n   * roles with the accent laid over them. It sees every property of the pass and\n   * must return the full map; a name it drops is not written.\n   */\n  transformTokens?: (tokens: Record<string, string>) => Record<string, string>\n  /**\n   * The contrast an accent is held to against the variant's background. Absent, a\n   * preset is painted verbatim (the catalogue measured it for its own themes) and\n   * only a custom `#rrggbb` is held to the default floor of 3:1.\n   */\n  accentContrastFloor?: number\n  /**\n   * Where a catalogue variant's palette comes from. `inline` (the default) writes\n   * every role onto the root. `stylesheet` writes none for a catalogue variant,\n   * because the host loads a stylesheet that carries a `[data-theme]` block for it;\n   * a variant the catalogue does not hold (a host's imported theme) is still written\n   * inline, since no stylesheet can know it. The accent, the terminal pin, the\n   * surface alpha and the fonts are written the same in both.\n   *\n   * Switching from an imported variant back to a catalogue one removes what the\n   * imported one wrote, so nothing inline outlives it to beat the stylesheet.\n   */\n  palette?: 'inline' | 'stylesheet'\n  /**\n   * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet\n   * syntax roles, which is what `theme-variants.css` carries; `floor` holds every\n   * editor role to 4.5:1 on the canvas, as hex.\n   *\n   * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue\n   * variant still gets: the stylesheet is generated for the default projection, so\n   * the sixteen `--editor-*` properties are written inline over it. The rest of the\n   * palette stays in the stylesheet.\n   */\n  editorRoles?: EditorRolesMode\n}\n\n/**\n * What a catalogue variant still writes inline when its palette is the stylesheet's:\n * nothing, unless the editor projection is not the one the stylesheet was generated\n * for.\n */\nfunction stylesheetOverrides(\n  variant: ThemeVariant,\n  editorRoles: EditorRolesMode | undefined\n): Record<string, string> {\n  if (editorRoles !== 'floor') return {}\n  return Object.fromEntries(\n    Object.entries(themeCssVariables(variant, { editor: 'floor' })).filter(([name]) =>\n      name.startsWith('--editor-')\n    )\n  )\n}\n\n/**\n * The custom properties a state paints: the variant's roles, with the accent\n * selection laid over them, the pinned terminal palette over that, the surface\n * alpha, then `transformTokens`.\n *\n * The accent is applied *here* rather than left to the `[data-accent]` blocks in\n * `theme.css`, because the properties are written inline and an inline declaration\n * outranks every stylesheet selector however specific it is. The blocks still exist\n * and are still correct — they are what styles the window before this runs — but\n * they cannot win from here, so leaving the accent to them meant the attribute was\n * set, the rules were present, and nothing changed on screen.\n */\nexport function themeDocumentTokens(\n  state: ThemeDocumentState,\n  options: ThemeDocumentOptions = {}\n): { tokens: Record<string, string>; accented: boolean } {\n  const fromStylesheet = options.palette === 'stylesheet' && isCatalogueVariant(state.variant)\n  const properties = fromStylesheet\n    ? stylesheetOverrides(state.variant, options.editorRoles)\n    : { ...themeCssVariables(state.variant, { editor: options.editorRoles }) }\n  const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {\n    background: state.variant.colors.background,\n    floor: options.accentContrastFloor,\n    variantId: state.variant.id,\n  })\n  if (accent) Object.assign(properties, accent)\n  // Written after the variant and the accent, so it wins over the interface\n  // variant's own terminal ramp (and over the stylesheet's, which it outranks as an\n  // inline declaration). Dropping the pin needs no removal of its own: the ramp is\n  // then rewritten by the variant, or swept back to the stylesheet.\n  if (state.terminalVariant) Object.assign(properties, terminalCssVariables(state.terminalVariant))\n  if (state.surface) properties['--surface-alpha'] = surfaceAlpha[state.surface.surface]\n  return {\n    tokens: options.transformTokens ? options.transformTokens(properties) : properties,\n    accented: accent !== undefined,\n  }\n}\n\n/**\n * Write a state onto a root and report which custom properties it owns.\n *\n * Pass the previous call's return as `previous` and any palette property that pass\n * wrote and this one does not is removed. For the catalogue the two sets are the\n * same, so nothing is ever removed; it matters for a host variant that carries\n * `tokens` the catalogue does not, which would otherwise stay inline, beating the\n * stylesheet, after the user switched away from it.\n */\nexport function applyThemeToRoot(\n  root: ThemeRoot,\n  state: ThemeDocumentState,\n  options: ThemeDocumentOptions = {},\n  previous?: ReadonlySet<string>\n): ReadonlySet<string> {\n  const { tokens, accented } = themeDocumentTokens(state, options)\n\n  for (const [name, value] of Object.entries(tokens)) {\n    root.style.setProperty(name, value)\n  }\n  if (previous) {\n    for (const name of previous) {\n      if (!(name in tokens)) root.style.removeProperty(name)\n    }\n  }\n\n  root.classList.toggle('dark', state.appearance === 'dark')\n  root.dataset['theme'] = state.variant.id\n  root.dataset['appearance'] = state.appearance\n  root.style.colorScheme = state.appearance\n\n  // A custom colour has no stylesheet block to select, and its value is the\n  // attribute's worst possible content, so it is reported as `custom`.\n  if (!accented) root.removeAttribute('data-accent')\n  else\n    root.dataset['accent'] = isCustomAccent(state.selection.accent)\n      ? 'custom'\n      : state.selection.accent\n\n  // The surface axis is opt-in, so its absence removes rather than defaults: a host\n  // that never enables it keeps an `<html>` with neither attribute, and one that\n  // turns it off leaves nothing behind. (`--surface-alpha` is swept with the tokens.)\n  if (state.surface) {\n    root.dataset['surface'] = state.surface.surface\n    root.dataset['reduceTransparency'] = state.surface.reduceTransparencyActive ? 'true' : 'false'\n  } else {\n    root.removeAttribute('data-surface')\n    root.removeAttribute('data-reduce-transparency')\n  }\n\n  applyAppearanceFontSettings(\n    root,\n    normalizeAppearanceEditorFontSettings(state.selection.fonts, state.selection.font).settings\n  )\n\n  // Density is a pure token shift, so unlike the colour axes there is nothing to\n  // compute: the attribute selects a block in `theme.css`. It is applied here for\n  // the same reason as the others — this is the one place that knows what the\n  // current selection is, and it is the only writer of these attributes.\n  if (resolvedDensity(state.selection) === 'comfortable') root.removeAttribute('data-density')\n  else root.dataset['density'] = resolvedDensity(state.selection)\n\n  return new Set(Object.keys(tokens))\n}\n\n/** What {@link applyWithoutTransitions} needs of a document. */\nexport type TransitionDocument = {\n  head: { appendChild(node: unknown): unknown }\n  createElement(tag: 'style'): {\n    textContent: string | null\n    offsetHeight?: number\n    remove(): void\n  }\n}\n\n/**\n * Run `apply` with every CSS transition switched off for the frame that carries\n * it, so a theme switch cannot animate page-wide.\n *\n * Without this, flipping the custom properties on `<html>` starts a transition on\n * every element that declares one, and each fades from the old palette to the new\n * over its own duration: a theme change that looks like a rendering fault. The\n * rule is removed two frames later, after the browser has committed the new styles\n * with transitions off, and `restore` runs it early (the provider calls it when it\n * is disposed mid-switch).\n *\n * `schedule` is the frame source; it defaults to `requestAnimationFrame` and falls\n * back to running at once where there is none, which leaves transitions on rather\n * than off.\n */\nexport function applyWithoutTransitions(\n  doc: TransitionDocument,\n  apply: () => void,\n  schedule: (callback: () => void) => void = defaultSchedule\n): () => void {\n  const style = doc.createElement('style')\n  style.textContent = '*{transition:none !important}'\n  doc.head.appendChild(style)\n  // Reading a layout property forces the browser to commit the rule before the\n  // properties change; without it the two can be batched into one style recalc.\n  void style.offsetHeight\n  let removed = false\n  const restore = () => {\n    if (removed) return\n    removed = true\n    style.remove()\n  }\n  try {\n    apply()\n  } catch (error) {\n    restore()\n    throw error\n  }\n  schedule(() => schedule(restore))\n  return restore\n}\n\nfunction defaultSchedule(callback: () => void): void {\n  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(callback)\n  else callback()\n}\n"],"mappings":"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"}

package/dist/components/theme/theme-persistence.d.ts

@@ -1,3 +1,4 @@
+import { type PreferenceStorage } from '#lib/preference-store';
 import { type ThemeSelection } from './theme-state';
 /**
  * Where a selection is kept between sessions.
@@ -47,4 +48,90 @@ export declare function localStoragePersistence(key: string | (() => string)): T
 export declare function readPersisted(persistence: ThemePersistence): Partial<ThemeSelection> | undefined;
 /** Hand a selection to the store; a store that throws loses the preference, not the switch. */
 export declare function writePersisted(persistence: ThemePersistence, next: ThemeSelection): void;
+/**
+ * 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 declare function createVersionedPersistence<Doc>(schema: ThemeStorageSchema, codec: VersionedCodec<Doc>, options?: VersionedPersistenceOptions): ThemePersistence;
 //# sourceMappingURL=theme-persistence.d.ts.map

package/dist/components/theme/theme-persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-persistence.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-persistence.ts"],"names":[],"mappings":"AAIA,OAAO,EAA0C,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAE3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAAA;IAC3C,KAAK,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAA;CAClC,CAAA;AA8DD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,gBAAgB,CAatF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAMhG;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,WAAW,EAAE,gBAAgB,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAOxF"}
+{"version":3,"file":"theme-persistence.d.ts","sourceRoot":"","sources":["../../../src/components/theme/theme-persistence.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAA0C,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAE3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAAA;IAC3C,KAAK,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAA;CAClC,CAAA;AAyED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,gBAAgB,CAatF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAMhG;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,WAAW,EAAE,gBAAgB,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAOxF;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;IACvC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,CAAC,GAAG,IAAI;IAChC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC1E;;;OAGG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAAA;IAC/D;;;OAGG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAAA;IAChD;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,GAAG,CAAA;CAChF,CAAA;AAED,0EAA0E;AAC1E,MAAM,MAAM,2BAA2B,GAAG;IACxC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAA;IAC7C,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAC5C,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,EAC1B,OAAO,GAAE,2BAAgC,GACxC,gBAAgB,CAqDlB"}

package/dist/components/theme/theme-persistence.js

@@ -3,7 +3,9 @@ import { normalizeCustomAccent } from "../../lib/accent-roles.js";
 import { isThemeAccentId } from "../../lib/theme-accents.js";
 import { defaultDarkThemeId, defaultLightThemeId, themeById } from "../../lib/themes.js";
 import { normalizeAppearanceEditorFontSettings } from "../../lib/appearance-font-settings.js";
+import { normalizeSurface } from "../../lib/theme-surface.js";
 import { defaultThemeSelection, resolvedDensity } from "./theme-state.js";
+import { defaultPreferenceStorage, readLegacyValue, readVersionedRecord, recoveryKeyFor, writeVersionedRecord } from "../../lib/preference-store.js";
 //#region src/components/theme/theme-persistence.ts
 /**
 * The preference store, or nothing.
@@ -31,7 +33,10 @@ function readSelection(storageKey) {
 			accent: typeof parsed.accent === "string" && (accentPresets.some((preset) => preset.id === parsed.accent) || isThemeAccentId(parsed.accent)) ? parsed.accent : normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent,
 			font: fonts.ui.family,
 			fonts,
-			density: resolvedDensity(parsed)
+			density: resolvedDensity(parsed),
+			terminalThemeId: typeof parsed.terminalThemeId === "string" && parsed.terminalThemeId.trim() !== "" ? parsed.terminalThemeId : void 0,
+			surface: normalizeSurface(parsed.surface),
+			reduceTransparency: typeof parsed.reduceTransparency === "boolean" ? parsed.reduceTransparency : void 0
 		};
 	} catch {
 		return defaultThemeSelection;
@@ -81,7 +86,63 @@ function writePersisted(persistence, next) {
 		persistence.write(next);
 	} catch {}
 }
+/**
+* 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.
+*/
+function createVersionedPersistence(schema, codec, options = {}) {
+	const storageOf = options.storage ?? defaultPreferenceStorage;
+	const recordSchema = {
+		key: schema.key,
+		version: schema.version,
+		recoveryKey: recoveryKeyFor(schema)
+	};
+	let previous;
+	const fallback = () => {
+		try {
+			return codec.defaults?.();
+		} catch {
+			return;
+		}
+	};
+	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 ? void 0 : codec.fromLegacy(legacy);
+					if (migrated) return migrated;
+				}
+			} catch {}
+			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 : void 0;
+			} catch {}
+		}
+	};
+}
 //#endregion
-export { localStoragePersistence, readPersisted, writePersisted };
+export { createVersionedPersistence, localStoragePersistence, readPersisted, writePersisted };
 
 //# sourceMappingURL=theme-persistence.js.map

package/dist/components/theme/theme-persistence.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme-persistence.js","names":[],"sources":["../../../src/components/theme/theme-persistence.ts"],"sourcesContent":["import { normalizeCustomAccent } from '#lib/accent-roles'\nimport { accentPresets } from '#lib/tokens'\nimport { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'\nimport { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'\nimport { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state'\n\n/**\n * Where a selection is kept between sessions.\n *\n * The provider never touches storage itself; it asks a `ThemePersistence`. The\n * default is {@link localStoragePersistence}, which is what the provider always did.\n * A host that stores the preference in a different shape, under a versioned\n * envelope, or somewhere that is not `localStorage` supplies its own and the\n * resolution and application rules stay the shared ones.\n *\n * The contract is deliberately narrow, so that an implementation cannot make the\n * provider less safe than it was:\n *\n *   - `read` is synchronous and runs once, when the provider is created. It may\n *     repair or quarantine what it finds, and it must not throw: the provider\n *     treats a throw as \"nothing stored\" and starts from the defaults.\n *   - `write` runs only from `setSelection`. Never on mount, never from `preview`,\n *     never as a side effect of reading, so the first write to a store is always a\n *     user's decision. A throw is swallowed, because a full or blocked store must\n *     not break the switch.\n */\nexport type ThemePersistence = {\n  read(): Partial<ThemeSelection> | undefined\n  write(next: ThemeSelection): void\n}\n\n/**\n * The preference store, or nothing.\n *\n * Only ever called inside a `try`: where storage is blocked — a sandboxed iframe, a\n * privacy mode, a denied site-data permission — merely *reading* the `localStorage`\n * global throws (\"Access is denied\", `SecurityError`), so even the `typeof` guard\n * has to sit inside the `try` rather than in front of it. Without a store the\n * preference lives only in the provider's signal for the session.\n */\nfunction preferenceStore(): Storage | undefined {\n  return typeof localStorage === 'undefined' ? undefined : localStorage\n}\n\n/** The stored preference, validated against the catalogue. */\nfunction readSelection(storageKey: string): ThemeSelection {\n  try {\n    const raw = preferenceStore()?.getItem(storageKey)\n    if (!raw) return defaultThemeSelection\n    const parsed = JSON.parse(raw) as Partial<ThemeSelection>\n    const fonts = normalizeAppearanceEditorFontSettings(parsed.fonts, parsed.font).settings\n    return {\n      appearance:\n        parsed.appearance === 'light' ||\n        parsed.appearance === 'dark' ||\n        parsed.appearance === 'system'\n          ? parsed.appearance\n          : defaultThemeSelection.appearance,\n      // An unknown id would leave the document with no theme at all, so a stale\n      // preference from an older catalogue falls back rather than applying nothing.\n      lightThemeId:\n        themeById(parsed.lightThemeId ?? '')?.appearance === 'light'\n          ? (parsed.lightThemeId as string)\n          : defaultLightThemeId,\n      darkThemeId:\n        themeById(parsed.darkThemeId ?? '')?.appearance === 'dark'\n          ? (parsed.darkThemeId as string)\n          : defaultDarkThemeId,\n      // A theme accent is kept whenever it names a slot, even one the stored pair\n      // cannot offer: the id is role-shaped so it survives a theme switch, and an\n      // unoffered slot already resolves to the theme's own primary when applied. A\n      // custom `#rrggbb` is kept in its one stored spelling; its readability is\n      // settled when it is painted, not when it is read.\n      accent:\n        typeof parsed.accent === 'string' &&\n        (accentPresets.some((preset) => preset.id === parsed.accent) ||\n          isThemeAccentId(parsed.accent))\n          ? parsed.accent\n          : (normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent),\n      font: fonts.ui.family,\n      fonts,\n      // Every axis has to be read back here, or it is lost twice: the provider's\n      // document effect removes the `data-density` that `themeScript` set for the first paint, and\n      // the next `setSelection` rewrites the store without it.\n      density: resolvedDensity(parsed as ThemeSelection),\n    }\n  } catch {\n    return defaultThemeSelection\n  }\n}\n\n/**\n * The default persistence: one JSON document in `localStorage` under `key`.\n *\n * `read` is the provider's original `readSelection`, moved here unchanged — every\n * stored id is validated against the catalogue, so a stale preference falls back to\n * a default rather than reaching the document. `key` may be a function so a\n * provider whose `storageKey` prop changes writes to the key it is now given.\n *\n * Blocked, full or absent storage is survivable in both directions: a read answers\n * with the defaults and a write is dropped, so the preference simply lasts the\n * session.\n */\nexport function localStoragePersistence(key: string | (() => string)): ThemePersistence {\n  const keyOf = () => (typeof key === 'function' ? key() : key)\n  return {\n    read: () => readSelection(keyOf()),\n    write(next) {\n      try {\n        preferenceStore()?.setItem(keyOf(), JSON.stringify(next))\n      } catch {\n        // A full, blocked or unavailable store must not break the switch: the\n        // preference simply does not survive the reload.\n      }\n    },\n  }\n}\n\n/**\n * What a persistence knows, or nothing.\n *\n * The seam's `read` must not throw, and the provider does not rely on that: a host\n * persistence is code the design system has not seen, and a theme provider that\n * fails to mount because a store misbehaved has turned a lost preference into a\n * blank application.\n */\nexport function readPersisted(persistence: ThemePersistence): Partial<ThemeSelection> | undefined {\n  try {\n    return persistence.read()\n  } catch {\n    return undefined\n  }\n}\n\n/** Hand a selection to the store; a store that throws loses the preference, not the switch. */\nexport function writePersisted(persistence: ThemePersistence, next: ThemeSelection): void {\n  try {\n    persistence.write(next)\n  } catch {\n    // Same contract as a full or blocked `localStorage`: the choice holds for the\n    // session and does not survive the reload.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwCA,SAAS,kBAAuC;CAC9C,OAAO,OAAO,iBAAiB,cAAc,KAAA,IAAY;AAC3D;;AAGA,SAAS,cAAc,YAAoC;CACzD,IAAI;EACF,MAAM,MAAM,gBAAgB,CAAC,EAAE,QAAQ,UAAU;EACjD,IAAI,CAAC,KAAK,OAAO;EACjB,MAAM,SAAS,KAAK,MAAM,GAAG;EAC7B,MAAM,QAAQ,sCAAsC,OAAO,OAAO,OAAO,IAAI,CAAC,CAAC;EAC/E,OAAO;GACL,YACE,OAAO,eAAe,WACtB,OAAO,eAAe,UACtB,OAAO,eAAe,WAClB,OAAO,aACP,sBAAsB;GAG5B,cACE,UAAU,OAAO,gBAAgB,EAAE,CAAC,EAAE,eAAe,UAChD,OAAO,eACR;GACN,aACE,UAAU,OAAO,eAAe,EAAE,CAAC,EAAE,eAAe,SAC/C,OAAO,cACR;GAMN,QACE,OAAO,OAAO,WAAW,aACxB,cAAc,MAAM,WAAW,OAAO,OAAO,OAAO,MAAM,KACzD,gBAAgB,OAAO,MAAM,KAC3B,OAAO,SACN,sBAAsB,OAAO,MAAM,KAAK,sBAAsB;GACrE,MAAM,MAAM,GAAG;GACf;GAIA,SAAS,gBAAgB,MAAwB;EACnD;CACF,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;AAcA,SAAgB,wBAAwB,KAAgD;CACtF,MAAM,cAAe,OAAO,QAAQ,aAAa,IAAI,IAAI;CACzD,OAAO;EACL,YAAY,cAAc,MAAM,CAAC;EACjC,MAAM,MAAM;GACV,IAAI;IACF,gBAAgB,CAAC,EAAE,QAAQ,MAAM,GAAG,KAAK,UAAU,IAAI,CAAC;GAC1D,QAAQ,CAGR;EACF;CACF;AACF;;;;;;;;;AAUA,SAAgB,cAAc,aAAoE;CAChG,IAAI;EACF,OAAO,YAAY,KAAK;CAC1B,QAAQ;EACN;CACF;AACF;;AAGA,SAAgB,eAAe,aAA+B,MAA4B;CACxF,IAAI;EACF,YAAY,MAAM,IAAI;CACxB,QAAQ,CAGR;AACF"}
+{"version":3,"file":"theme-persistence.js","names":[],"sources":["../../../src/components/theme/theme-persistence.ts"],"sourcesContent":["import { normalizeCustomAccent } from '#lib/accent-roles'\nimport { accentPresets } from '#lib/tokens'\nimport { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'\nimport { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'\nimport { normalizeSurface } from '#lib/theme-surface'\nimport {\n  defaultPreferenceStorage,\n  readLegacyValue,\n  readVersionedRecord,\n  recoveryKeyFor,\n  writeVersionedRecord,\n  type PreferenceStorage,\n} from '#lib/preference-store'\nimport { defaultThemeSelection, resolvedDensity, type ThemeSelection } from './theme-state'\n\n/**\n * Where a selection is kept between sessions.\n *\n * The provider never touches storage itself; it asks a `ThemePersistence`. The\n * default is {@link localStoragePersistence}, which is what the provider always did.\n * A host that stores the preference in a different shape, under a versioned\n * envelope, or somewhere that is not `localStorage` supplies its own and the\n * resolution and application rules stay the shared ones.\n *\n * The contract is deliberately narrow, so that an implementation cannot make the\n * provider less safe than it was:\n *\n *   - `read` is synchronous and runs once, when the provider is created. It may\n *     repair or quarantine what it finds, and it must not throw: the provider\n *     treats a throw as \"nothing stored\" and starts from the defaults.\n *   - `write` runs only from `setSelection`. Never on mount, never from `preview`,\n *     never as a side effect of reading, so the first write to a store is always a\n *     user's decision. A throw is swallowed, because a full or blocked store must\n *     not break the switch.\n */\nexport type ThemePersistence = {\n  read(): Partial<ThemeSelection> | undefined\n  write(next: ThemeSelection): void\n}\n\n/**\n * The preference store, or nothing.\n *\n * Only ever called inside a `try`: where storage is blocked — a sandboxed iframe, a\n * privacy mode, a denied site-data permission — merely *reading* the `localStorage`\n * global throws (\"Access is denied\", `SecurityError`), so even the `typeof` guard\n * has to sit inside the `try` rather than in front of it. Without a store the\n * preference lives only in the provider's signal for the session.\n */\nfunction preferenceStore(): Storage | undefined {\n  return typeof localStorage === 'undefined' ? undefined : localStorage\n}\n\n/** The stored preference, validated against the catalogue. */\nfunction readSelection(storageKey: string): ThemeSelection {\n  try {\n    const raw = preferenceStore()?.getItem(storageKey)\n    if (!raw) return defaultThemeSelection\n    const parsed = JSON.parse(raw) as Partial<ThemeSelection>\n    const fonts = normalizeAppearanceEditorFontSettings(parsed.fonts, parsed.font).settings\n    return {\n      appearance:\n        parsed.appearance === 'light' ||\n        parsed.appearance === 'dark' ||\n        parsed.appearance === 'system'\n          ? parsed.appearance\n          : defaultThemeSelection.appearance,\n      // An unknown id would leave the document with no theme at all, so a stale\n      // preference from an older catalogue falls back rather than applying nothing.\n      lightThemeId:\n        themeById(parsed.lightThemeId ?? '')?.appearance === 'light'\n          ? (parsed.lightThemeId as string)\n          : defaultLightThemeId,\n      darkThemeId:\n        themeById(parsed.darkThemeId ?? '')?.appearance === 'dark'\n          ? (parsed.darkThemeId as string)\n          : defaultDarkThemeId,\n      // A theme accent is kept whenever it names a slot, even one the stored pair\n      // cannot offer: the id is role-shaped so it survives a theme switch, and an\n      // unoffered slot already resolves to the theme's own primary when applied. A\n      // custom `#rrggbb` is kept in its one stored spelling; its readability is\n      // settled when it is painted, not when it is read.\n      accent:\n        typeof parsed.accent === 'string' &&\n        (accentPresets.some((preset) => preset.id === parsed.accent) ||\n          isThemeAccentId(parsed.accent))\n          ? parsed.accent\n          : (normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent),\n      font: fonts.ui.family,\n      fonts,\n      // Every axis has to be read back here, or it is lost twice: the provider's\n      // document effect removes the `data-density` that `themeScript` set for the first paint, and\n      // the next `setSelection` rewrites the store without it.\n      density: resolvedDensity(parsed as ThemeSelection),\n      // The newer axes are read back only when the store holds a usable value and are\n      // otherwise left `undefined`, never defaulted: `JSON.stringify` drops them, so a\n      // consumer that never sets one writes the bytes it always did. An id is kept as\n      // stored, known or not, for the same reason a theme id the registry lacks is.\n      terminalThemeId:\n        typeof parsed.terminalThemeId === 'string' && parsed.terminalThemeId.trim() !== ''\n          ? parsed.terminalThemeId\n          : undefined,\n      surface: normalizeSurface(parsed.surface),\n      reduceTransparency:\n        typeof parsed.reduceTransparency === 'boolean' ? parsed.reduceTransparency : undefined,\n    }\n  } catch {\n    return defaultThemeSelection\n  }\n}\n\n/**\n * The default persistence: one JSON document in `localStorage` under `key`.\n *\n * `read` is the provider's original `readSelection`, moved here unchanged — every\n * stored id is validated against the catalogue, so a stale preference falls back to\n * a default rather than reaching the document. `key` may be a function so a\n * provider whose `storageKey` prop changes writes to the key it is now given.\n *\n * Blocked, full or absent storage is survivable in both directions: a read answers\n * with the defaults and a write is dropped, so the preference simply lasts the\n * session.\n */\nexport function localStoragePersistence(key: string | (() => string)): ThemePersistence {\n  const keyOf = () => (typeof key === 'function' ? key() : key)\n  return {\n    read: () => readSelection(keyOf()),\n    write(next) {\n      try {\n        preferenceStore()?.setItem(keyOf(), JSON.stringify(next))\n      } catch {\n        // A full, blocked or unavailable store must not break the switch: the\n        // preference simply does not survive the reload.\n      }\n    },\n  }\n}\n\n/**\n * What a persistence knows, or nothing.\n *\n * The seam's `read` must not throw, and the provider does not rely on that: a host\n * persistence is code the design system has not seen, and a theme provider that\n * fails to mount because a store misbehaved has turned a lost preference into a\n * blank application.\n */\nexport function readPersisted(persistence: ThemePersistence): Partial<ThemeSelection> | undefined {\n  try {\n    return persistence.read()\n  } catch {\n    return undefined\n  }\n}\n\n/** Hand a selection to the store; a store that throws loses the preference, not the switch. */\nexport function writePersisted(persistence: ThemePersistence, next: ThemeSelection): void {\n  try {\n    persistence.write(next)\n  } catch {\n    // Same contract as a full or blocked `localStorage`: the choice holds for the\n    // session and does not survive the reload.\n  }\n}\n\n/**\n * Where a host's versioned preference document lives. One schema describes the\n * document to both halves of the system: {@link createVersionedPersistence} reads and\n * writes it, and `themeScript(options)` reads it before first paint, so the two\n * cannot disagree about a key or a version.\n */\nexport type ThemeStorageSchema = {\n  /** The storage key of the document. */\n  key: string\n  /**\n   * The only top-level `version` read. Absent, the document is unversioned. A record\n   * of any other version is quarantined (see `recoveryKey`), not interpreted.\n   */\n  version?: number\n  /**\n   * The document field that holds the appearance preference (`system`, `light`,\n   * `dark`). Read by `themeScript`; the persistence leaves field names to the codec.\n   * Default `appearance`.\n   */\n  appearanceField?: 'appearance' | 'mode'\n  /**\n   * An older single-value key (`light` | `dark` | `system`) read only while `key` is\n   * absent, and never deleted. The persistence hands it to the codec's `fromLegacy`.\n   */\n  legacyAppearanceKey?: string\n  /**\n   * The stored library of imported themes, for `themeScript` only: an imported\n   * theme's id and verbatim tokens, so the first paint can use the right variant. The\n   * persistence neither reads nor writes it.\n   */\n  libraryKey?: string\n  /** Where an unreadable document is kept. Default `${key}.recovery`. */\n  recoveryKey?: string\n}\n\n/**\n * How a host's document maps to and from the shared {@link ThemeSelection}.\n *\n * The codec is the product schema: it decides which fields a document has, how an\n * unknown value is corrected, and what a fresh install looks like. The engine decides\n * everything about *storage*: what is quarantined, when the legacy key is read, and\n * that nothing is written until `setSelection` asks.\n */\nexport type VersionedCodec<Doc> = {\n  /**\n   * A readable record (the right JSON shape and version) as a selection patch. Fields\n   * it leaves `undefined` fall back to the provider's defaults. It may keep an id the\n   * catalogue lacks; the provider resolves it, it does not rewrite it.\n   */\n  decode(record: Readonly<Record<string, unknown>>): Partial<ThemeSelection>\n  /**\n   * The legacy key's value (never `null`) as a selection patch, or `undefined` for a\n   * value it does not recognise. Called only when the main key is absent.\n   */\n  fromLegacy?(value: string): Partial<ThemeSelection> | undefined\n  /**\n   * What a store with nothing readable answers: a fresh install, an unreadable\n   * document, a blocked store. Absent, the provider's own defaults apply.\n   */\n  defaults?(): Partial<ThemeSelection> | undefined\n  /**\n   * The document to store for a selection. `previous` is the record last read or\n   * written, so a codec can carry a field the selection does not model.\n   */\n  encode(next: ThemeSelection, previous?: Readonly<Record<string, unknown>>): Doc\n}\n\n/** Seams for the storage and the clock; both default to the real ones. */\nexport type VersionedPersistenceOptions = {\n  /** The store, or nothing. Called per access; default is `localStorage` (blocked-safe). */\n  storage?: () => PreferenceStorage | undefined\n  /** The clock for the recovery envelope's `capturedAt`. */\n  now?: () => Date\n}\n\n/**\n * A {@link ThemePersistence} over a versioned document and a host codec.\n *\n * `read` follows the engine's rules (`lib/preference-store.ts`): the main key first;\n * an unreadable or unsupported document is quarantined byte for byte into the\n * recovery key and the codec's `defaults` answer; the legacy key only when the main\n * key is absent. It never writes the main key, so the first write is a user's\n * decision. `write` stores `codec.encode(next, previous)` as JSON and swallows a\n * failure.\n *\n * Neither method throws. The stored bytes are exactly what the codec encodes, so a\n * host keeps its keys, field names and bytes by keeping its codec.\n */\nexport function createVersionedPersistence<Doc>(\n  schema: ThemeStorageSchema,\n  codec: VersionedCodec<Doc>,\n  options: VersionedPersistenceOptions = {}\n): ThemePersistence {\n  const storageOf = options.storage ?? defaultPreferenceStorage\n  const recordSchema = {\n    key: schema.key,\n    version: schema.version,\n    recoveryKey: recoveryKeyFor(schema),\n  }\n  let previous: Readonly<Record<string, unknown>> | undefined\n\n  const fallback = () => {\n    try {\n      return codec.defaults?.()\n    } catch {\n      return undefined\n    }\n  }\n\n  return {\n    read() {\n      const storage = storageOf()\n      if (!storage) return fallback()\n      try {\n        const found = readVersionedRecord(storage, recordSchema, options.now)\n        if (found.status === 'record') {\n          previous = found.record\n          return codec.decode(found.record)\n        }\n        if (found.status === 'absent' && schema.legacyAppearanceKey && codec.fromLegacy) {\n          const legacy = readLegacyValue(storage, schema.legacyAppearanceKey)\n          const migrated = legacy === null ? undefined : codec.fromLegacy(legacy)\n          if (migrated) return migrated\n        }\n      } catch {\n        // A codec that throws on a record it cannot read is an unreadable store.\n      }\n      return fallback()\n    },\n    write(next) {\n      const storage = storageOf()\n      if (!storage) return\n      try {\n        const document = codec.encode(next, previous)\n        if (writeVersionedRecord(storage, schema.key, document)) {\n          previous =\n            typeof document === 'object' && document !== null\n              ? (document as Readonly<Record<string, unknown>>)\n              : undefined\n        }\n      } catch {\n        // An encoder that throws loses the preference, not the switch.\n      }\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiDA,SAAS,kBAAuC;CAC9C,OAAO,OAAO,iBAAiB,cAAc,KAAA,IAAY;AAC3D;;AAGA,SAAS,cAAc,YAAoC;CACzD,IAAI;EACF,MAAM,MAAM,gBAAgB,CAAC,EAAE,QAAQ,UAAU;EACjD,IAAI,CAAC,KAAK,OAAO;EACjB,MAAM,SAAS,KAAK,MAAM,GAAG;EAC7B,MAAM,QAAQ,sCAAsC,OAAO,OAAO,OAAO,IAAI,CAAC,CAAC;EAC/E,OAAO;GACL,YACE,OAAO,eAAe,WACtB,OAAO,eAAe,UACtB,OAAO,eAAe,WAClB,OAAO,aACP,sBAAsB;GAG5B,cACE,UAAU,OAAO,gBAAgB,EAAE,CAAC,EAAE,eAAe,UAChD,OAAO,eACR;GACN,aACE,UAAU,OAAO,eAAe,EAAE,CAAC,EAAE,eAAe,SAC/C,OAAO,cACR;GAMN,QACE,OAAO,OAAO,WAAW,aACxB,cAAc,MAAM,WAAW,OAAO,OAAO,OAAO,MAAM,KACzD,gBAAgB,OAAO,MAAM,KAC3B,OAAO,SACN,sBAAsB,OAAO,MAAM,KAAK,sBAAsB;GACrE,MAAM,MAAM,GAAG;GACf;GAIA,SAAS,gBAAgB,MAAwB;GAKjD,iBACE,OAAO,OAAO,oBAAoB,YAAY,OAAO,gBAAgB,KAAK,MAAM,KAC5E,OAAO,kBACP,KAAA;GACN,SAAS,iBAAiB,OAAO,OAAO;GACxC,oBACE,OAAO,OAAO,uBAAuB,YAAY,OAAO,qBAAqB,KAAA;EACjF;CACF,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;AAcA,SAAgB,wBAAwB,KAAgD;CACtF,MAAM,cAAe,OAAO,QAAQ,aAAa,IAAI,IAAI;CACzD,OAAO;EACL,YAAY,cAAc,MAAM,CAAC;EACjC,MAAM,MAAM;GACV,IAAI;IACF,gBAAgB,CAAC,EAAE,QAAQ,MAAM,GAAG,KAAK,UAAU,IAAI,CAAC;GAC1D,QAAQ,CAGR;EACF;CACF;AACF;;;;;;;;;AAUA,SAAgB,cAAc,aAAoE;CAChG,IAAI;EACF,OAAO,YAAY,KAAK;CAC1B,QAAQ;EACN;CACF;AACF;;AAGA,SAAgB,eAAe,aAA+B,MAA4B;CACxF,IAAI;EACF,YAAY,MAAM,IAAI;CACxB,QAAQ,CAGR;AACF;;;;;;;;;;;;;;AA0FA,SAAgB,2BACd,QACA,OACA,UAAuC,CAAC,GACtB;CAClB,MAAM,YAAY,QAAQ,WAAW;CACrC,MAAM,eAAe;EACnB,KAAK,OAAO;EACZ,SAAS,OAAO;EAChB,aAAa,eAAe,MAAM;CACpC;CACA,IAAI;CAEJ,MAAM,iBAAiB;EACrB,IAAI;GACF,OAAO,MAAM,WAAW;EAC1B,QAAQ;GACN;EACF;CACF;CAEA,OAAO;EACL,OAAO;GACL,MAAM,UAAU,UAAU;GAC1B,IAAI,CAAC,SAAS,OAAO,SAAS;GAC9B,IAAI;IACF,MAAM,QAAQ,oBAAoB,SAAS,cAAc,QAAQ,GAAG;IACpE,IAAI,MAAM,WAAW,UAAU;KAC7B,WAAW,MAAM;KACjB,OAAO,MAAM,OAAO,MAAM,MAAM;IAClC;IACA,IAAI,MAAM,WAAW,YAAY,OAAO,uBAAuB,MAAM,YAAY;KAC/E,MAAM,SAAS,gBAAgB,SAAS,OAAO,mBAAmB;KAClE,MAAM,WAAW,WAAW,OAAO,KAAA,IAAY,MAAM,WAAW,MAAM;KACtE,IAAI,UAAU,OAAO;IACvB;GACF,QAAQ,CAER;GACA,OAAO,SAAS;EAClB;EACA,MAAM,MAAM;GACV,MAAM,UAAU,UAAU;GAC1B,IAAI,CAAC,SAAS;GACd,IAAI;IACF,MAAM,WAAW,MAAM,OAAO,MAAM,QAAQ;IAC5C,IAAI,qBAAqB,SAAS,OAAO,KAAK,QAAQ,GACpD,WACE,OAAO,aAAa,YAAY,aAAa,OACxC,WACD,KAAA;GAEV,QAAQ,CAER;EACF;CACF;AACF"}

package/dist/components/theme/theme-provider.d.ts

@@ -1,9 +1,12 @@
 import type { JSX } from 'solid-js';
-import { type ThemeVariant } from '#lib/themes';
+import { type EditorRolesMode, type ThemeVariant } from '#lib/themes';
 import { type ThemePersistence } from './theme-persistence';
 import { 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 type { EditorRolesMode } from '#lib/themes';
+export { inlineScriptLiteral, themeScript, type ThemeScriptOptions } from './theme-script';
 export { defaultThemeSelection, resolvedDensity, type ThemeContextValue, type ThemeDensity, type ThemeSelection, } from './theme-state';
 /**
  * ThemeProvider.
@@ -90,45 +93,56 @@ 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';
+    /**
+     * The projection behind the `--editor-*` ramp. `syntax` (the default) is the
+     * catalogue's quiet syntax roles, a comment among them deliberately below
+     * body-text contrast. `floor` holds all sixteen roles to 4.5:1 on the canvas, as
+     * hex, for a host that renders code as content (a diff, a file view) rather than
+     * as decoration.
+     *
+     * Applies to catalogue variants; a host's own `themes` keep their `editor` and
+     * their `tokens`. With `palette="stylesheet"` it is the one palette property a
+     * catalogue variant still writes inline, because `theme-variants.css` is generated
+     * for `syntax`. Absent, nothing changes.
+     */
+    editorRoles?: EditorRolesMode;
+    /**
+     * 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;
 };
 export declare function ThemeProvider(props: ThemeProviderProps): JSX.Element;
-/**
- * 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 declare function inlineScriptLiteral(value: string): string;
-/**
- * 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 declare function themeScript(storageKey?: string): string;
 //# sourceMappingURL=theme-provider.d.ts.map