@reopt-ai/opt-ui 1.4.1 → 1.5.0

package/dist/theme/server.cjs

@@ -0,0 +1,281 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/theme-server.ts
+var theme_server_exports = {};
+__export(theme_server_exports, {
+  ALL_COMPOUND_THEMES: () => ALL_COMPOUND_THEMES,
+  DARK_MQ: () => DARK_MQ,
+  FORCE_LIGHT_PRESETS: () => FORCE_LIGHT_PRESETS,
+  LEGACY_THEME_STORAGE_KEY: () => LEGACY_THEME_STORAGE_KEY,
+  THEME_MODE_STORAGE_KEY: () => THEME_MODE_STORAGE_KEY,
+  THEME_MODE_VALUES: () => THEME_MODE_VALUES,
+  THEME_PRESET_STORAGE_KEY: () => THEME_PRESET_STORAGE_KEY,
+  THEME_PRESET_VALUES: () => THEME_PRESET_VALUES,
+  coerceThemeMode: () => coerceThemeMode,
+  createThemeBootScript: () => createThemeBootScript,
+  getCompoundTheme: () => getCompoundTheme,
+  isThemeMode: () => isThemeMode,
+  isThemePreset: () => isThemePreset,
+  readStoredTheme: () => readStoredTheme,
+  resolveThemeMode: () => resolveThemeMode
+});
+module.exports = __toCommonJS(theme_server_exports);
+
+// src/lib/theme/presets/index.ts
+var DEFAULT_DESCRIPTOR = {
+  id: "default",
+  label: "Default",
+  description: "Blue accent, balanced radius & shadow",
+  palette: {
+    seed: "#2563eb",
+    harmony: "split-complementary",
+    radiusScale: "medium",
+    shadowIntensity: "subtle",
+    neutralTemperature: "cool"
+  },
+  switcherSwatches: ["hsl(221 83% 53%)", "hsl(142 71% 45%)", "hsl(38 92% 50%)"]
+};
+var MINIMAL_DESCRIPTOR = {
+  id: "minimal",
+  label: "Minimal",
+  description: "Monochrome, no shadow, sharp edges",
+  palette: {
+    seed: "#333333",
+    harmony: "analogous",
+    radiusScale: "sharp",
+    shadowIntensity: "none",
+    neutralTemperature: "cool"
+  },
+  switcherSwatches: ["hsl(0 0% 20%)", "hsl(0 0% 45%)", "hsl(0 0% 70%)"]
+};
+var NATURAL_DESCRIPTOR = {
+  id: "natural",
+  label: "Natural",
+  description: "Always light \u2014 sage accent, warm cream",
+  forceLightOnly: true,
+  palette: {
+    seed: "#5a9376",
+    harmony: "complementary",
+    radiusScale: "medium",
+    shadowIntensity: "subtle",
+    neutralTemperature: "warm"
+  },
+  switcherSwatches: ["hsl(155 38% 45%)", "hsl(25 65% 55%)", "hsl(45 75% 50%)"]
+};
+var PRO_DESCRIPTOR = {
+  id: "pro",
+  label: "Pro",
+  description: "Neon blue accent, mono headings, ultra-dense",
+  palette: {
+    seed: "#0080ff",
+    harmony: "tetradic",
+    radiusScale: "sharp",
+    shadowIntensity: "subtle",
+    neutralTemperature: "cool"
+  },
+  switcherSwatches: [
+    "hsl(210 100% 55%)",
+    "hsl(170 90% 48%)",
+    "hsl(290 85% 60%)"
+  ]
+};
+var MONO_DARK_DESCRIPTOR = {
+  id: "mono-dark",
+  label: "Mono Dark",
+  description: "OLED-friendly black, neon cyan accent, mono headings",
+  palette: {
+    seed: "#00d4ff",
+    harmony: "tetradic",
+    radiusScale: "sharp",
+    shadowIntensity: "subtle",
+    neutralTemperature: "cool"
+  },
+  switcherSwatches: ["hsl(190 100% 50%)", "hsl(0 0% 8%)", "hsl(280 90% 65%)"]
+};
+var THEME_REGISTRY = {
+  default: DEFAULT_DESCRIPTOR,
+  minimal: MINIMAL_DESCRIPTOR,
+  natural: NATURAL_DESCRIPTOR,
+  pro: PRO_DESCRIPTOR,
+  "mono-dark": MONO_DARK_DESCRIPTOR
+};
+var THEME_PRESET_IDS = Object.keys(THEME_REGISTRY);
+function isThemePresetId(id) {
+  return id in THEME_REGISTRY;
+}
+var FORCE_LIGHT_PRESET_IDS = new Set(
+  THEME_PRESET_IDS.filter((id) => THEME_REGISTRY[id].forceLightOnly)
+);
+var DEPRECATED_PRESET_MIGRATIONS = Object.freeze({
+  corporate: "default",
+  playful: "default"
+});
+function migrateDeprecatedPresetId(id) {
+  if (!id) return null;
+  if (isThemePresetId(id)) return id;
+  if (id in DEPRECATED_PRESET_MIGRATIONS) {
+    return DEPRECATED_PRESET_MIGRATIONS[id];
+  }
+  return null;
+}
+
+// src/lib/theme/theme-serialize.ts
+var import_opt_palette = require("@reopt-ai/opt-palette");
+var GLOBAL_THEME_STYLE_ID = "opt-global-theme";
+var THEME_SPEC_STORAGE_KEY = "opt-theme-spec";
+var THEME_TOKENS_STORAGE_KEY = "opt-theme-tokens";
+
+// src/lib/theme/theme-resolution.ts
+var THEME_PRESET_VALUES = THEME_PRESET_IDS;
+var THEME_MODE_VALUES = ["light", "dark", "system"];
+var LEGACY_THEME_STORAGE_KEY = "opt-theme";
+var THEME_PRESET_STORAGE_KEY = "opt-preset";
+var THEME_MODE_STORAGE_KEY = "opt-mode";
+var DARK_MQ = "(prefers-color-scheme: dark)";
+var FORCE_LIGHT_PRESETS = FORCE_LIGHT_PRESET_IDS;
+var ALL_COMPOUND_THEMES = THEME_PRESET_IDS.flatMap(
+  (id) => FORCE_LIGHT_PRESET_IDS.has(id) ? [id] : [id, `${id}-dark`]
+);
+function hasStorageMutation(storage) {
+  return typeof storage.setItem === "function" && typeof storage.removeItem === "function";
+}
+function isThemePreset(value) {
+  return typeof value === "string" && THEME_PRESET_VALUES.includes(value);
+}
+function isThemeMode(value) {
+  return typeof value === "string" && THEME_MODE_VALUES.includes(value);
+}
+function getCompoundTheme(preset, resolvedMode) {
+  if (FORCE_LIGHT_PRESETS.has(preset)) return preset;
+  return resolvedMode === "dark" ? `${preset}-dark` : preset;
+}
+function resolveThemeMode(preset, mode, systemDark) {
+  if (FORCE_LIGHT_PRESETS.has(preset)) return "light";
+  if (mode === "system") return systemDark ? "dark" : "light";
+  return mode;
+}
+function readStoredTheme(storage, defaultPreset, defaultMode, options = {}) {
+  const legacy = storage.getItem(LEGACY_THEME_STORAGE_KEY);
+  const storedPreset = storage.getItem(THEME_PRESET_STORAGE_KEY);
+  const storedMode = storage.getItem(THEME_MODE_STORAGE_KEY);
+  let preset = defaultPreset;
+  if (typeof legacy === "string") {
+    const migratedLegacy = migrateDeprecatedPresetId(legacy);
+    if (migratedLegacy) {
+      if (options.migrateLegacy && hasStorageMutation(storage)) {
+        storage.setItem(THEME_PRESET_STORAGE_KEY, migratedLegacy);
+        storage.removeItem(LEGACY_THEME_STORAGE_KEY);
+      }
+      preset = migratedLegacy;
+    }
+  } else if (typeof storedPreset === "string") {
+    const migrated = migrateDeprecatedPresetId(storedPreset);
+    if (migrated) {
+      preset = migrated;
+      if (hasStorageMutation(storage) && migrated !== storedPreset && storedPreset in DEPRECATED_PRESET_MIGRATIONS) {
+        storage.setItem(THEME_PRESET_STORAGE_KEY, migrated);
+      }
+    }
+  }
+  const mode = isThemeMode(storedMode) ? storedMode : defaultMode;
+  return { preset, mode };
+}
+function coerceThemeMode(mode, allowedModes, fallback = "system") {
+  var _a;
+  if (!allowedModes || allowedModes.length === 0) return mode;
+  if (allowedModes.includes(mode)) return mode;
+  if (allowedModes.includes(fallback)) return fallback;
+  return (_a = allowedModes[0]) != null ? _a : fallback;
+}
+function createThemeBootScript(defaultPreset = "default", defaultMode = "system", options = {}) {
+  var _a, _b;
+  const presetValues = JSON.stringify(THEME_PRESET_VALUES);
+  const modeValues = JSON.stringify(THEME_MODE_VALUES);
+  const allowedModes = ((_a = options.allowedModes) == null ? void 0 : _a.length) ? options.allowedModes : THEME_MODE_VALUES;
+  const allowedModeValues = JSON.stringify(allowedModes);
+  const forceLightPresets = JSON.stringify(Array.from(FORCE_LIGHT_PRESETS));
+  const deprecatedMap = JSON.stringify(DEPRECATED_PRESET_MIGRATIONS);
+  const lockedPreset = options.lockedPreset;
+  const resolvedDefaultPreset = lockedPreset != null ? lockedPreset : defaultPreset;
+  const defaultPresetLiteral = JSON.stringify(resolvedDefaultPreset);
+  const defaultModeLiteral = JSON.stringify(
+    coerceThemeMode(defaultMode, allowedModes, (_b = allowedModes[0]) != null ? _b : "system")
+  );
+  const lockedPresetLiteral = JSON.stringify(lockedPreset != null ? lockedPreset : null);
+  const styleId = JSON.stringify(GLOBAL_THEME_STYLE_ID);
+  const specKey = JSON.stringify(THEME_SPEC_STORAGE_KEY);
+  const tokensKey = JSON.stringify(THEME_TOKENS_STORAGE_KEY);
+  const presetKey = JSON.stringify(THEME_PRESET_STORAGE_KEY);
+  const modeKey = JSON.stringify(THEME_MODE_STORAGE_KEY);
+  const legacyKey = JSON.stringify(LEGACY_THEME_STORAGE_KEY);
+  const darkMq = JSON.stringify(DARK_MQ);
+  const source = `
+try {
+  var pv=${presetValues},mv=${modeValues},am=${allowedModeValues},fp=${forceLightPresets},dm=${deprecatedMap},lk=${lockedPresetLiteral};
+  function mp(v){if(typeof v!=="string")return null;if(pv.indexOf(v)>=0)return v;return Object.prototype.hasOwnProperty.call(dm,v)?dm[v]:null;}
+  var p=${defaultPresetLiteral};
+  if(!lk){
+    var lp=localStorage.getItem(${legacyKey}),sp=localStorage.getItem(${presetKey});
+    var lpm=mp(lp),spm=mp(sp);
+    p=lpm||spm||${defaultPresetLiteral};
+    if(lpm){localStorage.setItem(${presetKey},lpm);localStorage.removeItem(${legacyKey});}
+    else if(sp&&spm&&sp!==spm){localStorage.setItem(${presetKey},spm);}
+  }
+  var sm=localStorage.getItem(${modeKey});
+  var m=(typeof sm==="string"&&mv.indexOf(sm)>=0&&am.indexOf(sm)>=0)?sm:${defaultModeLiteral};
+  var spec=null,tk=null;
+  if(!lk){try{var sj=localStorage.getItem(${specKey});if(sj)spec=JSON.parse(sj);}catch(e){}}
+  if(!lk){try{var tj=localStorage.getItem(${tokensKey});if(tj)tk=JSON.parse(tj);}catch(e){}}
+  if(!lk&&spec&&spec.kind==="generated"&&tk&&typeof tk.id==="string"&&tk.light&&typeof tk.light==="object"){
+    var fld=spec.forceLightOnly===true;
+    var dk=!fld&&(m==="dark"||(m==="system"&&matchMedia(${darkMq}).matches));
+    var tt=(dk&&tk.dark)?tk.dark:tk.light;
+    var cid=(dk&&tk.dark)?(tk.id+"-dark"):tk.id;
+    var css="";
+    for(var k in tt){if(Object.prototype.hasOwnProperty.call(tt,k))css+=k+":"+tt[k]+";"}
+    var st=document.getElementById(${styleId});
+    if(!st){st=document.createElement("style");st.id=${styleId};document.head.appendChild(st);}
+    st.textContent='[data-theme="'+cid+'"]{'+css+'}';
+    document.documentElement.setAttribute("data-theme",cid);
+  } else {
+    var d=fp.indexOf(p)<0&&(m==="dark"||(m==="system"&&matchMedia(${darkMq}).matches));
+    document.documentElement.setAttribute("data-theme",d?p+"-dark":p);
+  }
+} catch(e){}`;
+  return source.replace(/\n\s*/g, "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALL_COMPOUND_THEMES,
+  DARK_MQ,
+  FORCE_LIGHT_PRESETS,
+  LEGACY_THEME_STORAGE_KEY,
+  THEME_MODE_STORAGE_KEY,
+  THEME_MODE_VALUES,
+  THEME_PRESET_STORAGE_KEY,
+  THEME_PRESET_VALUES,
+  coerceThemeMode,
+  createThemeBootScript,
+  getCompoundTheme,
+  isThemeMode,
+  isThemePreset,
+  readStoredTheme,
+  resolveThemeMode
+});

package/dist/theme/server.d.cts

@@ -0,0 +1,129 @@
+import { PaletteConfig } from '@reopt-ai/opt-palette';
+
+/**
+ * presets/index.ts
+ *
+ * Single registry of theme preset metadata. Each entry pairs a stable id
+ * (used in `<html data-theme>` and localStorage) with display metadata and an
+ * optional `PaletteConfig` that approximates the preset's seed for the
+ * ThemeSwitcher swatch row and "clone to custom" workflow.
+ *
+ * Token values themselves currently live in the sibling `*.css` files. A
+ * follow-up sub-phase will migrate the full token tables into this file and
+ * have a codegen step emit the CSS, but the metadata layer is enough to
+ * unblock dynamic ThemeSwitcher rendering and type-safe preset id unions.
+ */
+
+interface ThemeDescriptor {
+    /** Stable id used in `<html data-theme="...">` and localStorage. */
+    readonly id: string;
+    /** Human-readable label shown in ThemeSwitcher. */
+    readonly label: string;
+    /** Short description shown under the label. */
+    readonly description: string;
+    /**
+     * Optional engine input that approximates this preset. Used by
+     * ThemeSwitcher to derive swatches when `switcherSwatches` is omitted, and
+     * as the starting point when a user clones a preset into a custom palette.
+     * Codegen does NOT consume this in the current phase — the static `*.css`
+     * file remains the source of token values.
+     */
+    readonly palette?: PaletteConfig;
+    /**
+     * Three CSS color strings for the ThemeSwitcher swatch row. Falls back to
+     * the live `--opt-accent` / `--opt-surface` / `--opt-text` tokens when
+     * omitted.
+     */
+    readonly switcherSwatches?: readonly [string, string, string];
+    /** Disable dark variant generation entirely. */
+    readonly forceLightOnly?: boolean;
+}
+declare const THEME_REGISTRY: {
+    readonly default: ThemeDescriptor;
+    readonly minimal: ThemeDescriptor;
+    readonly natural: ThemeDescriptor;
+    readonly pro: ThemeDescriptor;
+    readonly "mono-dark": ThemeDescriptor;
+};
+/** Compile-time-derived union of registered preset ids. */
+type ThemePresetId = keyof typeof THEME_REGISTRY;
+
+/**
+ * Registered preset id list. Preferred for runtime iteration.
+ * @deprecated Prefer `THEME_PRESET_IDS` from `./presets`.
+ */
+declare const THEME_PRESET_VALUES: readonly ThemePresetId[];
+/** Theme preset id — alias of `ThemePresetId` from the registry. */
+type ThemePreset = ThemePresetId;
+declare const THEME_MODE_VALUES: readonly ["light", "dark", "system"];
+/** Type definition for theme mode. */
+type ThemeMode = (typeof THEME_MODE_VALUES)[number];
+/** Runtime constraints for apps that expose only a subset of opt-ui theming. */
+interface ThemeRuntimeOptions {
+    /**
+     * Force the root theme to one preset regardless of stored preset/generated
+     * theme state. Mode is still resolved normally unless constrained.
+     */
+    lockedPreset?: ThemePreset;
+    /**
+     * Restrict mode reads/writes to a smaller set, e.g. `["light", "dark"]`.
+     * The first value becomes the fallback when the stored/default mode is not
+     * allowed.
+     */
+    allowedModes?: readonly ThemeMode[];
+}
+/**
+ * Compound theme value applied to `<html data-theme>`. Derived from the
+ * registered preset ids: `<id>` (light) or `<id>-dark` (dark). Force-light
+ * presets only emit the bare id form.
+ */
+type CompoundTheme = `${ThemePreset}` | `${ThemePreset}-dark`;
+declare const LEGACY_THEME_STORAGE_KEY = "opt-theme";
+declare const THEME_PRESET_STORAGE_KEY = "opt-preset";
+declare const THEME_MODE_STORAGE_KEY = "opt-mode";
+declare const DARK_MQ = "(prefers-color-scheme: dark)";
+/**
+ * Presets that force light mode regardless of system dark/light preference.
+ * Mirrors `FORCE_LIGHT_PRESET_IDS` from `./presets` — kept as alias for
+ * existing imports.
+ */
+declare const FORCE_LIGHT_PRESETS: ReadonlySet<ThemePreset>;
+/** All valid compound theme names. Useful for static enumeration. */
+declare const ALL_COMPOUND_THEMES: CompoundTheme[];
+interface ThemeStorageReader {
+    getItem(key: string): string | null;
+}
+/** Handles is theme preset. */
+declare function isThemePreset(value: string | null): value is ThemePreset;
+/** Handles is theme mode. */
+declare function isThemeMode(value: string | null): value is ThemeMode;
+/** Compute compound theme name from preset + resolved mode. */
+declare function getCompoundTheme(preset: ThemePreset, resolvedMode: "light" | "dark"): CompoundTheme;
+/** Handles resolve theme mode. */
+declare function resolveThemeMode(preset: ThemePreset, mode: ThemeMode, systemDark: boolean): "light" | "dark";
+/** Handles read stored theme. */
+declare function readStoredTheme(storage: ThemeStorageReader, defaultPreset: ThemePreset, defaultMode: ThemeMode, options?: {
+    migrateLegacy?: boolean;
+}): {
+    preset: ThemePreset;
+    mode: ThemeMode;
+};
+/** Normalize a mode against an optional allowed-mode list. */
+declare function coerceThemeMode(mode: ThemeMode, allowedModes: readonly ThemeMode[] | undefined, fallback?: ThemeMode): ThemeMode;
+/**
+ * Build the inline `<head>` boot script that paints the correct theme before
+ * React mounts. Two paths:
+ *
+ * 1. **Generated** — when both `opt-theme-spec` (kind: "generated") and
+ *    `opt-theme-tokens` are present and well-formed, a `<style id="…">` tag
+ *    is inserted with the cached tokens and `<html data-theme>` is set to the
+ *    generated id (with optional `-dark` suffix). This bypasses opt-palette
+ *    at startup so first paint is instant.
+ * 2. **Preset (legacy)** — falls through to the existing preset selector,
+ *    including legacy `opt-theme` → `opt-preset` migration.
+ *
+ * Returned as a single minified line; intended for `dangerouslySetInnerHTML`.
+ */
+declare function createThemeBootScript(defaultPreset?: ThemePreset, defaultMode?: ThemeMode, options?: ThemeRuntimeOptions): string;
+
+export { ALL_COMPOUND_THEMES, type CompoundTheme, DARK_MQ, FORCE_LIGHT_PRESETS, LEGACY_THEME_STORAGE_KEY, THEME_MODE_STORAGE_KEY, THEME_MODE_VALUES, THEME_PRESET_STORAGE_KEY, THEME_PRESET_VALUES, type ThemeMode, type ThemePreset, type ThemeRuntimeOptions, coerceThemeMode, createThemeBootScript, getCompoundTheme, isThemeMode, isThemePreset, readStoredTheme, resolveThemeMode };

package/dist/theme/server.d.ts

@@ -0,0 +1,129 @@
+import { PaletteConfig } from '@reopt-ai/opt-palette';
+
+/**
+ * presets/index.ts
+ *
+ * Single registry of theme preset metadata. Each entry pairs a stable id
+ * (used in `<html data-theme>` and localStorage) with display metadata and an
+ * optional `PaletteConfig` that approximates the preset's seed for the
+ * ThemeSwitcher swatch row and "clone to custom" workflow.
+ *
+ * Token values themselves currently live in the sibling `*.css` files. A
+ * follow-up sub-phase will migrate the full token tables into this file and
+ * have a codegen step emit the CSS, but the metadata layer is enough to
+ * unblock dynamic ThemeSwitcher rendering and type-safe preset id unions.
+ */
+
+interface ThemeDescriptor {
+    /** Stable id used in `<html data-theme="...">` and localStorage. */
+    readonly id: string;
+    /** Human-readable label shown in ThemeSwitcher. */
+    readonly label: string;
+    /** Short description shown under the label. */
+    readonly description: string;
+    /**
+     * Optional engine input that approximates this preset. Used by
+     * ThemeSwitcher to derive swatches when `switcherSwatches` is omitted, and
+     * as the starting point when a user clones a preset into a custom palette.
+     * Codegen does NOT consume this in the current phase — the static `*.css`
+     * file remains the source of token values.
+     */
+    readonly palette?: PaletteConfig;
+    /**
+     * Three CSS color strings for the ThemeSwitcher swatch row. Falls back to
+     * the live `--opt-accent` / `--opt-surface` / `--opt-text` tokens when
+     * omitted.
+     */
+    readonly switcherSwatches?: readonly [string, string, string];
+    /** Disable dark variant generation entirely. */
+    readonly forceLightOnly?: boolean;
+}
+declare const THEME_REGISTRY: {
+    readonly default: ThemeDescriptor;
+    readonly minimal: ThemeDescriptor;
+    readonly natural: ThemeDescriptor;
+    readonly pro: ThemeDescriptor;
+    readonly "mono-dark": ThemeDescriptor;
+};
+/** Compile-time-derived union of registered preset ids. */
+type ThemePresetId = keyof typeof THEME_REGISTRY;
+
+/**
+ * Registered preset id list. Preferred for runtime iteration.
+ * @deprecated Prefer `THEME_PRESET_IDS` from `./presets`.
+ */
+declare const THEME_PRESET_VALUES: readonly ThemePresetId[];
+/** Theme preset id — alias of `ThemePresetId` from the registry. */
+type ThemePreset = ThemePresetId;
+declare const THEME_MODE_VALUES: readonly ["light", "dark", "system"];
+/** Type definition for theme mode. */
+type ThemeMode = (typeof THEME_MODE_VALUES)[number];
+/** Runtime constraints for apps that expose only a subset of opt-ui theming. */
+interface ThemeRuntimeOptions {
+    /**
+     * Force the root theme to one preset regardless of stored preset/generated
+     * theme state. Mode is still resolved normally unless constrained.
+     */
+    lockedPreset?: ThemePreset;
+    /**
+     * Restrict mode reads/writes to a smaller set, e.g. `["light", "dark"]`.
+     * The first value becomes the fallback when the stored/default mode is not
+     * allowed.
+     */
+    allowedModes?: readonly ThemeMode[];
+}
+/**
+ * Compound theme value applied to `<html data-theme>`. Derived from the
+ * registered preset ids: `<id>` (light) or `<id>-dark` (dark). Force-light
+ * presets only emit the bare id form.
+ */
+type CompoundTheme = `${ThemePreset}` | `${ThemePreset}-dark`;
+declare const LEGACY_THEME_STORAGE_KEY = "opt-theme";
+declare const THEME_PRESET_STORAGE_KEY = "opt-preset";
+declare const THEME_MODE_STORAGE_KEY = "opt-mode";
+declare const DARK_MQ = "(prefers-color-scheme: dark)";
+/**
+ * Presets that force light mode regardless of system dark/light preference.
+ * Mirrors `FORCE_LIGHT_PRESET_IDS` from `./presets` — kept as alias for
+ * existing imports.
+ */
+declare const FORCE_LIGHT_PRESETS: ReadonlySet<ThemePreset>;
+/** All valid compound theme names. Useful for static enumeration. */
+declare const ALL_COMPOUND_THEMES: CompoundTheme[];
+interface ThemeStorageReader {
+    getItem(key: string): string | null;
+}
+/** Handles is theme preset. */
+declare function isThemePreset(value: string | null): value is ThemePreset;
+/** Handles is theme mode. */
+declare function isThemeMode(value: string | null): value is ThemeMode;
+/** Compute compound theme name from preset + resolved mode. */
+declare function getCompoundTheme(preset: ThemePreset, resolvedMode: "light" | "dark"): CompoundTheme;
+/** Handles resolve theme mode. */
+declare function resolveThemeMode(preset: ThemePreset, mode: ThemeMode, systemDark: boolean): "light" | "dark";
+/** Handles read stored theme. */
+declare function readStoredTheme(storage: ThemeStorageReader, defaultPreset: ThemePreset, defaultMode: ThemeMode, options?: {
+    migrateLegacy?: boolean;
+}): {
+    preset: ThemePreset;
+    mode: ThemeMode;
+};
+/** Normalize a mode against an optional allowed-mode list. */
+declare function coerceThemeMode(mode: ThemeMode, allowedModes: readonly ThemeMode[] | undefined, fallback?: ThemeMode): ThemeMode;
+/**
+ * Build the inline `<head>` boot script that paints the correct theme before
+ * React mounts. Two paths:
+ *
+ * 1. **Generated** — when both `opt-theme-spec` (kind: "generated") and
+ *    `opt-theme-tokens` are present and well-formed, a `<style id="…">` tag
+ *    is inserted with the cached tokens and `<html data-theme>` is set to the
+ *    generated id (with optional `-dark` suffix). This bypasses opt-palette
+ *    at startup so first paint is instant.
+ * 2. **Preset (legacy)** — falls through to the existing preset selector,
+ *    including legacy `opt-theme` → `opt-preset` migration.
+ *
+ * Returned as a single minified line; intended for `dangerouslySetInnerHTML`.
+ */
+declare function createThemeBootScript(defaultPreset?: ThemePreset, defaultMode?: ThemeMode, options?: ThemeRuntimeOptions): string;
+
+export { ALL_COMPOUND_THEMES, type CompoundTheme, DARK_MQ, FORCE_LIGHT_PRESETS, LEGACY_THEME_STORAGE_KEY, THEME_MODE_STORAGE_KEY, THEME_MODE_VALUES, THEME_PRESET_STORAGE_KEY, THEME_PRESET_VALUES, type ThemeMode, type ThemePreset, type ThemeRuntimeOptions, coerceThemeMode, createThemeBootScript, getCompoundTheme, isThemeMode, isThemePreset, readStoredTheme, resolveThemeMode };