@tenphi/glaze 0.19.0 → 1.1.0

package/dist/index.d.cts

@@ -280,8 +280,8 @@ interface RegularColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -346,8 +346,8 @@ interface ShadowColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -393,8 +393,8 @@ interface MixColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -493,13 +493,6 @@ interface GlazeConfig {
    * falls back to the originally requested tone).
    */
   autoFlip?: boolean;
-  /**
-   * If true, uses a hue-independent "safe" chroma limit across all colors
-   * so that scaling saturation never exceeds the sRGB boundary at any hue
-   * for the given lightness.
-   * @default false
-   */
-  pastel?: boolean;
   /**
    * If true (default), infer a color's `role` from its name when no explicit
    * `role` is set. Set to `false` to opt out of name-based inference (the
@@ -519,13 +512,19 @@ interface GlazeConfigResolved {
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
+  /**
+   * Instance-level pastel default (`def.pastel ?? config.pastel`).
+   * Not set via `glaze.configure()` — only via per-theme / per-token
+   * `GlazeConfigOverride` (default `false`).
+   */
   pastel: boolean;
   inferRole: boolean;
 }
 /**
  * Per-instance config override for `glaze.color()` and `glaze()` themes.
  * Fields that are set take priority over the live global config. Fields
- * that are omitted fall through to the live global at resolve time.
+ * that are omitted fall through to the live global at resolve time
+ * (`pastel` is instance-only and defaults to `false` when omitted).
  *
  * `false` for a tone window disables clamping (full range at reference eps).
  */
@@ -539,9 +538,9 @@ interface GlazeConfigOverride {
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
   /**
-   * If true, uses a hue-independent "safe" chroma limit across all colors
-   * so that scaling saturation never exceeds the sRGB boundary at any hue
-   * for the given lightness.
+   * Instance-level pastel default for colors that omit per-color `pastel`.
+   * Not available on `glaze.configure()` — set here or per-color.
+   * @default false
    */
   pastel?: boolean;
   /**
@@ -555,12 +554,29 @@ interface GlazeConfigOverride {
    */
   shadowTuning?: ShadowTuning;
 }
+/**
+ * Current authoring-export schema version. Bump when the export shape
+ * changes in a non-compatible way. Written on every `.export()` snapshot.
+ */
+declare const GLAZE_EXPORT_VERSION: 1;
+/** Literal type of {@link GLAZE_EXPORT_VERSION}. */
+type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
+/** Discriminator for authoring export snapshots. */
+type GlazeExportKind = 'theme' | 'color' | 'palette';
 /** Serialized theme configuration (no resolved values). */
 interface GlazeThemeExport {
+  /** Snapshot kind. Always written by `theme.export()`; optional on legacy hand-written configs. */
+  kind?: 'theme';
+  /** Schema version. Always written by `theme.export()`; optional on legacy configs. */
+  version?: number;
   hue: number;
   saturation: number;
   colors: ColorMap;
-  /** Per-theme config override, if any. */
+  /**
+   * Effective config freeze from `.export()` —
+   * `getConfig() ∪ instance local ∪ exportArg`. May be sparse on legacy
+   * snapshots (omitted fields fall through to the live global at restore).
+   */
   config?: GlazeConfigOverride;
 }
 /** Input for `glaze.shadow()` standalone factory. */
@@ -616,8 +632,8 @@ interface GlazeColorInput {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -668,11 +684,11 @@ interface GlazeColorOverrides {
   /**
    * Adaptation mode. Defaults to `'auto'` for every input form, so
    * colors automatically adapt between light and dark like an ordinary
-   * theme color. All value-shorthand inputs (strings and literal objects)
-   * preserve light tone (`lightTone: false`) and snapshot
-   * `globalConfig.darkTone` on the dark side. Only the structured
-   * `{ hue, saturation, tone }` form also snapshots
-   * `globalConfig.lightTone`.
+   * theme color. Value-shorthand inputs (strings and literal objects)
+   * preserve light tone via a local `lightTone: false` default; other
+   * omitted config fields fall through to the live global at resolve
+   * time. Structured `{ hue, saturation, tone }` form also falls
+   * through for both tone windows unless overridden.
    *
    * Pass `'fixed'` explicitly to opt back into the linear, non-
    * inverting mapping; pass `'static'` to pin the same tone
@@ -731,8 +747,8 @@ interface GlazeColorOverrides {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -815,14 +831,19 @@ interface GlazeColorToken {
    * Serialize the token as a JSON-safe object. Captures the original
    * input value, overrides, and config so it can be rehydrated via
    * `glaze.colorFrom(...)`. `base` is recursively serialized.
+   * Optional `override` is merged over the instance local at export time.
    */
-  export(): GlazeColorTokenExport;
+  export(override?: GlazeConfigOverride): GlazeColorTokenExport;
 }
 /**
  * JSON-safe serialization of a `glaze.color()` token. Pass to
  * `glaze.colorFrom(...)` to rehydrate.
  */
 interface GlazeColorTokenExport {
+  /** Snapshot kind. Always written by `token.export()`; optional on legacy snapshots. */
+  kind?: 'color';
+  /** Schema version. Always written by `token.export()`; optional on legacy snapshots. */
+  version?: number;
   /**
    * Discriminator for the source overload that created the token.
    * - `'value'`: created via `glaze.color(value)` or `glaze.color({ from, ...overrides })`.
@@ -837,14 +858,26 @@ interface GlazeColorTokenExport {
    */
   overrides?: GlazeColorOverridesExport;
   /**
-   * Effective config snapshot at creation time — captures the merged
-   * result of the global config + any per-call override at the moment
-   * the token was created. Only fields that differ from their
-   * post-merge defaults are present. Used by `glaze.colorFrom()` to
-   * reproduce deterministic behavior across `configure()` calls.
+   * Effective config freeze from `.export()` — `getConfig() ∪ local ∪
+   * exportArg` at call time. Used by `glaze.colorFrom()` to pin
+   * deterministic behavior across later `configure()` calls.
    */
   config?: GlazeConfigOverride;
 }
+/**
+ * JSON-safe serialization of a `glaze.palette()` composition.
+ * Pass to `glaze.paletteFrom(...)` to rehydrate.
+ */
+interface GlazePaletteExport {
+  /** Snapshot kind. Always written by `palette.export()`. */
+  kind?: 'palette';
+  /** Schema version. Always written by `palette.export()`. */
+  version?: number;
+  /** Per-theme authoring snapshots keyed by theme name. */
+  themes: Record<string, GlazeThemeExport>;
+  /** Primary theme name, if set on the palette. */
+  primary?: string;
+}
 /**
  * Serializable shape of a structured `glaze.color({...})` input.
  * Differs from `GlazeColorInput` only in that `base` is replaced by an
@@ -904,7 +937,7 @@ interface GlazeTheme {
   /** Clear all color definitions. */
   reset(): void;
   /** Export the theme configuration as a JSON-safe object. */
-  export(): GlazeThemeExport;
+  export(override?: GlazeConfigOverride): GlazeThemeExport;
   /** Create a child theme inheriting all color definitions. */
   extend(options: GlazeExtendOptions): GlazeTheme;
   /** Resolve all colors and return the result map. */
@@ -1224,6 +1257,24 @@ interface GlazePaletteExportOptions {
   splitHue?: boolean;
 }
 interface GlazePalette {
+  /** Theme names in insertion order. */
+  list(): string[];
+  /** Primary theme name, if set at palette creation. */
+  readonly primary: string | undefined;
+  /** Get a theme by name. Returns the live instance held by the palette. */
+  theme(name: string): GlazeTheme | undefined;
+  /**
+   * Shallow copy of the theme map (same instances the palette holds).
+   * Mutating a returned theme affects subsequent palette exports.
+   */
+  themes(): Record<string, GlazeTheme>;
+  /**
+   * Export the palette authoring configuration as a JSON-safe object.
+   * Restorable via `glaze.paletteFrom(...)`. Distinct from `json()`, which
+   * emits resolved color strings. Optional `override` is forwarded to each
+   * nested `theme.export(override)`.
+   */
+  export(override?: GlazeConfigOverride): GlazePaletteExport;
   /**
    * Export all themes as a flat token map grouped by scheme variant.
    * Prefix defaults to `true` — all tokens are prefixed with the theme name.
@@ -1270,6 +1321,14 @@ interface GlazePalette {
   tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
 }
 //#endregion
+//#region src/serialize.d.ts
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+declare function isThemeExport(data: unknown): data is GlazeThemeExport;
+/** Type guard for color-token authoring snapshots. */
+declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
+//#endregion
 //#region src/glaze.d.ts
 type PaletteInput = Record<string, GlazeTheme>;
 /**
@@ -1297,6 +1356,7 @@ declare function glaze(hueOrOptions: number | {
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
+  var themeFrom: (data: GlazeThemeExport) => GlazeTheme;
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
@@ -1304,6 +1364,10 @@ declare namespace glaze {
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
+  var paletteFrom: (data: GlazePaletteExport) => GlazePalette;
+  var isThemeExport: typeof isThemeExport;
+  var isColorTokenExport: typeof isColorTokenExport;
+  var isPaletteExport: typeof isPaletteExport;
   var getConfig: () => GlazeConfigResolved;
   var resetConfig: () => void;
 }
@@ -1567,5 +1631,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -280,8 +280,8 @@ interface RegularColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -346,8 +346,8 @@ interface ShadowColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -393,8 +393,8 @@ interface MixColorDef {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -493,13 +493,6 @@ interface GlazeConfig {
    * falls back to the originally requested tone).
    */
   autoFlip?: boolean;
-  /**
-   * If true, uses a hue-independent "safe" chroma limit across all colors
-   * so that scaling saturation never exceeds the sRGB boundary at any hue
-   * for the given lightness.
-   * @default false
-   */
-  pastel?: boolean;
   /**
    * If true (default), infer a color's `role` from its name when no explicit
    * `role` is set. Set to `false` to opt out of name-based inference (the
@@ -519,13 +512,19 @@ interface GlazeConfigResolved {
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
+  /**
+   * Instance-level pastel default (`def.pastel ?? config.pastel`).
+   * Not set via `glaze.configure()` — only via per-theme / per-token
+   * `GlazeConfigOverride` (default `false`).
+   */
   pastel: boolean;
   inferRole: boolean;
 }
 /**
  * Per-instance config override for `glaze.color()` and `glaze()` themes.
  * Fields that are set take priority over the live global config. Fields
- * that are omitted fall through to the live global at resolve time.
+ * that are omitted fall through to the live global at resolve time
+ * (`pastel` is instance-only and defaults to `false` when omitted).
  *
  * `false` for a tone window disables clamping (full range at reference eps).
  */
@@ -539,9 +538,9 @@ interface GlazeConfigOverride {
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
   /**
-   * If true, uses a hue-independent "safe" chroma limit across all colors
-   * so that scaling saturation never exceeds the sRGB boundary at any hue
-   * for the given lightness.
+   * Instance-level pastel default for colors that omit per-color `pastel`.
+   * Not available on `glaze.configure()` — set here or per-color.
+   * @default false
    */
   pastel?: boolean;
   /**
@@ -555,12 +554,29 @@ interface GlazeConfigOverride {
    */
   shadowTuning?: ShadowTuning;
 }
+/**
+ * Current authoring-export schema version. Bump when the export shape
+ * changes in a non-compatible way. Written on every `.export()` snapshot.
+ */
+declare const GLAZE_EXPORT_VERSION: 1;
+/** Literal type of {@link GLAZE_EXPORT_VERSION}. */
+type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
+/** Discriminator for authoring export snapshots. */
+type GlazeExportKind = 'theme' | 'color' | 'palette';
 /** Serialized theme configuration (no resolved values). */
 interface GlazeThemeExport {
+  /** Snapshot kind. Always written by `theme.export()`; optional on legacy hand-written configs. */
+  kind?: 'theme';
+  /** Schema version. Always written by `theme.export()`; optional on legacy configs. */
+  version?: number;
   hue: number;
   saturation: number;
   colors: ColorMap;
-  /** Per-theme config override, if any. */
+  /**
+   * Effective config freeze from `.export()` —
+   * `getConfig() ∪ instance local ∪ exportArg`. May be sparse on legacy
+   * snapshots (omitted fields fall through to the live global at restore).
+   */
   config?: GlazeConfigOverride;
 }
 /** Input for `glaze.shadow()` standalone factory. */
@@ -616,8 +632,8 @@ interface GlazeColorInput {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -668,11 +684,11 @@ interface GlazeColorOverrides {
   /**
    * Adaptation mode. Defaults to `'auto'` for every input form, so
    * colors automatically adapt between light and dark like an ordinary
-   * theme color. All value-shorthand inputs (strings and literal objects)
-   * preserve light tone (`lightTone: false`) and snapshot
-   * `globalConfig.darkTone` on the dark side. Only the structured
-   * `{ hue, saturation, tone }` form also snapshots
-   * `globalConfig.lightTone`.
+   * theme color. Value-shorthand inputs (strings and literal objects)
+   * preserve light tone via a local `lightTone: false` default; other
+   * omitted config fields fall through to the live global at resolve
+   * time. Structured `{ hue, saturation, tone }` form also falls
+   * through for both tone windows unless overridden.
    *
    * Pass `'fixed'` explicitly to opt back into the linear, non-
    * inverting mapping; pass `'static'` to pin the same tone
@@ -731,8 +747,8 @@ interface GlazeColorOverrides {
   /**
    * Per-color override for the hue-independent "safe" chroma limit used in
    * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
-   * Falls through to the global / per-theme `pastel` config when omitted.
-   * @see GlazeConfig.pastel
+   * Falls through to the per-theme / per-token `pastel` override when omitted.
+   * @see GlazeConfigOverride.pastel
    */
   pastel?: boolean;
   /**
@@ -815,14 +831,19 @@ interface GlazeColorToken {
    * Serialize the token as a JSON-safe object. Captures the original
    * input value, overrides, and config so it can be rehydrated via
    * `glaze.colorFrom(...)`. `base` is recursively serialized.
+   * Optional `override` is merged over the instance local at export time.
    */
-  export(): GlazeColorTokenExport;
+  export(override?: GlazeConfigOverride): GlazeColorTokenExport;
 }
 /**
  * JSON-safe serialization of a `glaze.color()` token. Pass to
  * `glaze.colorFrom(...)` to rehydrate.
  */
 interface GlazeColorTokenExport {
+  /** Snapshot kind. Always written by `token.export()`; optional on legacy snapshots. */
+  kind?: 'color';
+  /** Schema version. Always written by `token.export()`; optional on legacy snapshots. */
+  version?: number;
   /**
    * Discriminator for the source overload that created the token.
    * - `'value'`: created via `glaze.color(value)` or `glaze.color({ from, ...overrides })`.
@@ -837,14 +858,26 @@ interface GlazeColorTokenExport {
    */
   overrides?: GlazeColorOverridesExport;
   /**
-   * Effective config snapshot at creation time — captures the merged
-   * result of the global config + any per-call override at the moment
-   * the token was created. Only fields that differ from their
-   * post-merge defaults are present. Used by `glaze.colorFrom()` to
-   * reproduce deterministic behavior across `configure()` calls.
+   * Effective config freeze from `.export()` — `getConfig() ∪ local ∪
+   * exportArg` at call time. Used by `glaze.colorFrom()` to pin
+   * deterministic behavior across later `configure()` calls.
    */
   config?: GlazeConfigOverride;
 }
+/**
+ * JSON-safe serialization of a `glaze.palette()` composition.
+ * Pass to `glaze.paletteFrom(...)` to rehydrate.
+ */
+interface GlazePaletteExport {
+  /** Snapshot kind. Always written by `palette.export()`. */
+  kind?: 'palette';
+  /** Schema version. Always written by `palette.export()`. */
+  version?: number;
+  /** Per-theme authoring snapshots keyed by theme name. */
+  themes: Record<string, GlazeThemeExport>;
+  /** Primary theme name, if set on the palette. */
+  primary?: string;
+}
 /**
  * Serializable shape of a structured `glaze.color({...})` input.
  * Differs from `GlazeColorInput` only in that `base` is replaced by an
@@ -904,7 +937,7 @@ interface GlazeTheme {
   /** Clear all color definitions. */
   reset(): void;
   /** Export the theme configuration as a JSON-safe object. */
-  export(): GlazeThemeExport;
+  export(override?: GlazeConfigOverride): GlazeThemeExport;
   /** Create a child theme inheriting all color definitions. */
   extend(options: GlazeExtendOptions): GlazeTheme;
   /** Resolve all colors and return the result map. */
@@ -1224,6 +1257,24 @@ interface GlazePaletteExportOptions {
   splitHue?: boolean;
 }
 interface GlazePalette {
+  /** Theme names in insertion order. */
+  list(): string[];
+  /** Primary theme name, if set at palette creation. */
+  readonly primary: string | undefined;
+  /** Get a theme by name. Returns the live instance held by the palette. */
+  theme(name: string): GlazeTheme | undefined;
+  /**
+   * Shallow copy of the theme map (same instances the palette holds).
+   * Mutating a returned theme affects subsequent palette exports.
+   */
+  themes(): Record<string, GlazeTheme>;
+  /**
+   * Export the palette authoring configuration as a JSON-safe object.
+   * Restorable via `glaze.paletteFrom(...)`. Distinct from `json()`, which
+   * emits resolved color strings. Optional `override` is forwarded to each
+   * nested `theme.export(override)`.
+   */
+  export(override?: GlazeConfigOverride): GlazePaletteExport;
   /**
    * Export all themes as a flat token map grouped by scheme variant.
    * Prefix defaults to `true` — all tokens are prefixed with the theme name.
@@ -1270,6 +1321,14 @@ interface GlazePalette {
   tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
 }
 //#endregion
+//#region src/serialize.d.ts
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+declare function isThemeExport(data: unknown): data is GlazeThemeExport;
+/** Type guard for color-token authoring snapshots. */
+declare function isColorTokenExport(data: unknown): data is GlazeColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+declare function isPaletteExport(data: unknown): data is GlazePaletteExport;
+//#endregion
 //#region src/glaze.d.ts
 type PaletteInput = Record<string, GlazeTheme>;
 /**
@@ -1297,6 +1356,7 @@ declare function glaze(hueOrOptions: number | {
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
+  var themeFrom: (data: GlazeThemeExport) => GlazeTheme;
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
@@ -1304,6 +1364,10 @@ declare namespace glaze {
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
   var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
+  var paletteFrom: (data: GlazePaletteExport) => GlazePalette;
+  var isThemeExport: typeof isThemeExport;
+  var isColorTokenExport: typeof isColorTokenExport;
+  var isPaletteExport: typeof isPaletteExport;
   var getConfig: () => GlazeConfigResolved;
   var resetConfig: () => void;
 }
@@ -1567,5 +1631,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map