@tenphi/glaze 1.0.0 → 1.1.1

package/dist/index.mjs

@@ -673,6 +673,8 @@ function okhslToOklch(h, s, l, pastel = false) {
 /**
 * Build a fresh defaults object. Called from module init and from
 * `resetConfig()` so the two paths can't drift.
+*
+* `pastel: false` is a fixed instance default — not globally configurable.
 */
 function defaultConfig() {
 	return {
@@ -737,7 +739,7 @@ function configure(config) {
 		},
 		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
 		autoFlip: config.autoFlip ?? globalConfig.autoFlip,
-		pastel: config.pastel ?? globalConfig.pastel,
+		pastel: false,
 		inferRole: config.inferRole ?? globalConfig.inferRole
 	};
 }
@@ -750,9 +752,15 @@ function resetConfig() {
 * Only fields present in `override` are replaced; others fall through
 * from `base`. `false` for tone windows passes through as-is
 * (treated as the full range by `activeWindow()` in okhst.ts).
+*
+* `pastel` is instance-only: `override.pastel ?? false`, never inherited
+* from the global base.
 */
 function mergeConfig(base, override) {
-	if (!override) return base;
+	if (!override) return base.pastel === false ? base : {
+		...base,
+		pastel: false
+	};
 	return {
 		lightTone: override.lightTone !== void 0 ? override.lightTone : base.lightTone,
 		darkTone: override.darkTone !== void 0 ? override.darkTone : base.darkTone,
@@ -761,10 +769,99 @@ function mergeConfig(base, override) {
 		modes: base.modes,
 		shadowTuning: override.shadowTuning ?? base.shadowTuning,
 		autoFlip: override.autoFlip ?? base.autoFlip,
-		pastel: override.pastel ?? base.pastel,
+		pastel: override.pastel ?? false,
 		inferRole: override.inferRole ?? base.inferRole
 	};
 }
+/**
+* Freeze `getConfig() ∪ instanceLocal ∪ exportArg` as a plain, resolve-relevant
+* override for authoring export, so restored snapshots pin these fields. Later
+* wins; nested objects (`shadowTuning`) replace wholesale. The final
+* `structuredClone` detaches tone-window / shadow objects that `mergeConfig`
+* may still share with the live global config.
+*/
+function freezeConfigForExport(instanceLocal, exportArg) {
+	const effective = mergeConfig(getConfig(), {
+		...instanceLocal,
+		...exportArg
+	});
+	const out = {
+		lightTone: effective.lightTone,
+		darkTone: effective.darkTone,
+		darkDesaturation: effective.darkDesaturation,
+		autoFlip: effective.autoFlip,
+		pastel: effective.pastel,
+		inferRole: effective.inferRole
+	};
+	if (effective.shadowTuning !== void 0) out.shadowTuning = effective.shadowTuning;
+	return structuredClone(out);
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* Current authoring-export schema version. Bump when the export shape
+* changes in a non-compatible way. Written on every `.export()` snapshot.
+*/
+const GLAZE_EXPORT_VERSION = 1;
+
+//#endregion
+//#region src/serialize.ts
+/**
+* Authoring-export helpers: schema version, type guards, and restore
+* validation shared by `themeFrom` / `colorFrom` / `paletteFrom`.
+*/
+function isPlainObject(data) {
+	return typeof data === "object" && data !== null && !Array.isArray(data);
+}
+/**
+* Reject unknown / invalid schema versions. Missing `version` is allowed
+* (legacy snapshots). Present versions must be an integer in
+* `1..=GLAZE_EXPORT_VERSION`.
+*/
+function assertExportVersion(data, factory) {
+	if (data.version === void 0) return;
+	if (typeof data.version !== "number" || !Number.isInteger(data.version) || data.version < 1) throw new Error(`${factory}: invalid "version" field — expected an integer >= 1 (got ${JSON.stringify(data.version)}).`);
+	if (data.version > GLAZE_EXPORT_VERSION) throw new Error(`${factory}: unsupported export version ${data.version} (this library supports version ${GLAZE_EXPORT_VERSION}). Upgrade @tenphi/glaze to load this snapshot.`);
+}
+/**
+* When `kind` is present, it must match the factory. Missing `kind` is
+* allowed for legacy snapshots.
+*/
+function assertExportKind(data, expected, factory) {
+	if (data.kind === void 0) return;
+	if (data.kind !== expected) throw new Error(`${factory}: expected kind "${expected}", got ${JSON.stringify(data.kind)}.`);
+}
+function hasThemeShape(data) {
+	return typeof data.hue === "number" && typeof data.saturation === "number" && !("form" in data) && !("themes" in data);
+}
+function hasColorTokenShape(data) {
+	return data.form === "value" || data.form === "structured";
+}
+function hasPaletteShape(data) {
+	return isPlainObject(data.themes) && !("form" in data) && typeof data.hue !== "number";
+}
+/** Type guard for theme authoring snapshots (prefers `kind`, falls back to shape). */
+function isThemeExport(data) {
+	if (!isPlainObject(data)) return false;
+	if (data.kind === "theme") return hasThemeShape(data);
+	if (data.kind !== void 0) return false;
+	return hasThemeShape(data);
+}
+/** Type guard for color-token authoring snapshots. */
+function isColorTokenExport(data) {
+	if (!isPlainObject(data)) return false;
+	if (data.kind === "color") return hasColorTokenShape(data);
+	if (data.kind !== void 0) return false;
+	return hasColorTokenShape(data);
+}
+/** Type guard for palette authoring snapshots. */
+function isPaletteExport(data) {
+	if (!isPlainObject(data)) return false;
+	if (data.kind === "palette") return hasPaletteShape(data);
+	if (data.kind !== void 0) return false;
+	return hasPaletteShape(data);
+}
 
 //#endregion
 //#region src/format-guard.ts
@@ -809,7 +906,7 @@ function assertAllPastel(resolved, modes) {
 		}
 	}
 	if (nonPastel.length === 0) return;
-	throw new Error(`glaze: splitHue requires every color to be pastel (hue rotation is only clip-free when chroma is bounded by the hue-independent safe chroma). Non-pastel: ${nonPastel.join(", ")}. Set pastel: true (global or per-color) or drop splitHue.`);
+	throw new Error(`glaze: splitHue requires every color to be pastel (hue rotation is only clip-free when chroma is bounded by the hue-independent safe chroma). Non-pastel: ${nonPastel.join(", ")}. Set pastel: true (per-theme, per-token, or per-color) or drop splitHue.`);
 }
 
 //#endregion
@@ -1880,15 +1977,18 @@ function resolveContrastSpec(spec, isHighContrast, polarity) {
 /**
 * Apply the relative-tone delta against a base, honoring `flip`.
 *
-* When `flip` is on and `base + delta` falls outside `[0, 100]`, mirror the
-* delta to the other side of the base (so an offset that would clamp instead
-* reflects back into range). When off, the caller clamps as usual.
+* When `flip` is on and `base + delta` falls outside `[0, 100]`, try mirroring
+* the delta to the other side of the base. If the mirrored target is also out
+* of range, keep the original delta so the caller clamps on the authored side.
+* When off, the caller clamps as usual.
 */
 function applyToneFlip(delta, baseTone, flip) {
 	if (!flip) return delta;
 	const target = baseTone + delta;
 	if (target >= 0 && target <= 100) return delta;
-	return -delta;
+	const mirrored = baseTone - delta;
+	if (mirrored >= 0 && mirrored <= 100) return -delta;
+	return delta;
 }
 function resolveRootColor(def, isHighContrast) {
 	const rawT = def.tone;
@@ -2650,12 +2750,10 @@ function buildTailwindMap(resolved, themePrefix, cssPrefix, modes, format, darkS
 * `{ l, c, h }`), the structured-input validator, the two factory paths
 * (value vs structured), and the JSON-safe export / rehydration round-trip.
 *
-* Standalone tokens snapshot the full effective config at create time
-* so later `configure()` calls do not retroactively change exported
-* tokens. The snapshot is built eagerly in
-* `buildValueFormConfigOverride()` / `buildStructuredConfigOverride()`.
-* The token's resolved variants are then memoized on first
-* `.resolve()` / `.token()` / ... call.
+* Tokens store a sparse local config override only. Resolve merges the
+* live global config with that local override (invalidated on
+* `configure()`). Authoring `.export(override?)` freezes
+* `getConfig() ∪ local ∪ override` at call time.
 */
 /** Internal name of the user-facing standalone color in the synthesized def map. */
 const STANDALONE_VALUE = "value";
@@ -2670,47 +2768,16 @@ const RESERVED_STANDALONE_NAMES = new Set([
 	STANDALONE_BASE
 ]);
 /**
-* Build the per-token effective config override for a value-form color.
-*
-* Light window defaults to `false` (preserve input tone exactly).
-* All other fields snapshot from global at create time. User override
-* fields win over all defaults.
+* Value-form local override: `lightTone` defaults to `false` (preserve
+* input tone). User override fields win.
 */
-function buildValueFormConfigOverride(userOverride) {
-	const cfg = getConfig();
+function sparseValueFormLocal(userOverride) {
 	return {
-		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : false,
-		darkTone: userOverride?.darkTone !== void 0 ? userOverride.darkTone : cfg.darkTone,
-		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
-		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
-		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
+		...userOverride,
+		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : false
 	};
 }
 /**
-* Build the per-token effective config override for a structured-form color.
-*
-* Both light and dark windows snapshot from global at create time.
-* User override fields win.
-*/
-function buildStructuredConfigOverride(userOverride) {
-	const cfg = getConfig();
-	return {
-		lightTone: userOverride?.lightTone !== void 0 ? userOverride.lightTone : cfg.lightTone,
-		darkTone: userOverride?.darkTone !== void 0 ? userOverride.darkTone : cfg.darkTone,
-		darkDesaturation: userOverride?.darkDesaturation ?? cfg.darkDesaturation,
-		autoFlip: userOverride?.autoFlip ?? cfg.autoFlip,
-		shadowTuning: userOverride?.shadowTuning ?? cfg.shadowTuning
-	};
-}
-/**
-* Build the `GlazeConfigResolved` to pass to `resolveAllColors` from a
-* snapshot override. Uses `defaultConfig()` as the base so all required
-* fields are present; the snapshot fields win.
-*/
-function resolvedConfigFromOverride(override) {
-	return mergeConfig(defaultConfig(), override);
-}
-/**
 * Matches the CSS color functions Glaze itself emits (`rgb()`, `hsl()`,
 * `okhsl()`, `oklch()`) plus their legacy alpha aliases (`rgba()`, `hsla()`).
 *
@@ -3000,12 +3067,30 @@ function buildStandaloneValueDefs(main, options) {
 		primary
 	};
 }
-function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, baseToken, exportData) {
-	let cached;
+function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, configOverride, baseToken, buildExport) {
+	let cache = null;
+	function getEffectiveConfig() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version) return cache.effectiveConfig;
+		const effectiveConfig = mergeConfig(getConfig(), configOverride);
+		cache = {
+			map: null,
+			version,
+			effectiveConfig
+		};
+		return effectiveConfig;
+	}
 	const resolveOnce = () => {
-		if (cached) return cached;
-		cached = resolveAllColors(seedHue, seedSaturation, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
-		return cached;
+		const version = getConfigVersion();
+		if (cache && cache.version === version && cache.map) return cache.map;
+		const effectiveConfig = getEffectiveConfig();
+		const map = resolveAllColors(seedHue, seedSaturation, defs, effectiveConfig, baseToken ? new Map([[STANDALONE_BASE, baseToken.resolve()]]) : void 0);
+		cache = {
+			map,
+			version,
+			effectiveConfig
+		};
+		return map;
 	};
 	const resolveStates = (options) => {
 		const cfg = getConfig();
@@ -3015,7 +3100,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		};
 	};
 	const tokenLike = (options) => {
-		return buildTokenMap(resolveOnce(), "", resolveStates(options), resolveModes(options?.modes), options?.format ?? "oklch", effectiveConfig.pastel)[`#${primary}`];
+		return buildTokenMap(resolveOnce(), "", resolveStates(options), resolveModes(options?.modes), options?.format ?? "oklch", getEffectiveConfig().pastel)[`#${primary}`];
 	};
 	return {
 		resolve() {
@@ -3026,7 +3111,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		json(options) {
 			const format = options?.format ?? "oklch";
 			assertNativeFormat(format, "json");
-			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), format, effectiveConfig.pastel)[primary];
+			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), format, getEffectiveConfig().pastel)[primary];
 		},
 		css(options) {
 			const format = options.format ?? "oklch";
@@ -3045,11 +3130,11 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 					resolvedHue: resolved.light.h
 				};
 			}
-			return buildCssMap(renamed, "", options.suffix ?? "-color", format, effectiveConfig.pastel, channelCtx);
+			return buildCssMap(renamed, "", options.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
 		},
 		dtcg(options) {
 			const modes = resolveModes(options?.modes);
-			const doc = buildDtcgMap(resolveOnce(), "", modes, options?.colorSpace ?? "srgb", effectiveConfig.pastel);
+			const doc = buildDtcgMap(resolveOnce(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
 			const result = { light: doc.light[primary] };
 			if (doc.dark) result.dark = doc.dark[primary];
 			if (doc.lightContrast) result.lightContrast = doc.lightContrast[primary];
@@ -3057,7 +3142,7 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 			return result;
 		},
 		dtcgResolver(options) {
-			const doc = buildDtcgMap(resolveOnce(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", effectiveConfig.pastel);
+			const doc = buildDtcgMap(resolveOnce(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
 			const name = options.name;
 			const result = { light: { [name]: doc.light[primary] } };
 			if (doc.dark) result.dark = { [name]: doc.dark[primary] };
@@ -3068,9 +3153,11 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		tailwind(options) {
 			const format = options.format ?? "oklch";
 			assertNativeFormat(format, "tailwind");
-			return buildTailwindMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.namespace ?? "color-", resolveModes(options?.modes), format, options.darkSelector ?? ".dark", options.highContrastSelector ?? ".high-contrast", effectiveConfig.pastel);
+			return buildTailwindMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.namespace ?? "color-", resolveModes(options?.modes), format, options.darkSelector ?? ".dark", options.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
 		},
-		export: exportData
+		export(override) {
+			return buildExport(override);
+		}
 	};
 }
 /**
@@ -3137,35 +3224,35 @@ function createColorToken(input, configOverride) {
 			mode: "static"
 		};
 	}
-	const effectiveConfigOverride = buildStructuredConfigOverride(configOverride);
-	const effectiveConfig = resolvedConfigFromOverride(effectiveConfigOverride);
-	const exportData = () => ({
+	const localOverride = configOverride;
+	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, localOverride, baseToken, (exportArg) => ({
+		kind: "color",
+		version: GLAZE_EXPORT_VERSION,
 		form: "structured",
-		input: buildStructuredInputExport(input),
-		config: effectiveConfigOverride
-	});
-	return createColorTokenFromDefs(input.hue, input.saturation, defs, primary, effectiveConfig, baseToken, exportData);
+		input: buildStructuredInputExport(input, exportArg),
+		config: freezeConfigForExport(localOverride, exportArg)
+	}));
 }
 function createColorTokenFromValue(value, options, configOverride) {
 	const main = extractOkhslFromValue(value);
 	const linkingBase = toLinkingBase(resolveBaseToken(options?.base));
 	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options);
-	const effectiveConfigOverride = buildValueFormConfigOverride(configOverride);
-	const effectiveConfig = resolvedConfigFromOverride(effectiveConfigOverride);
-	const exportData = () => ({
+	const localOverride = sparseValueFormLocal(configOverride);
+	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, localOverride, linkingBase, (exportArg) => ({
+		kind: "color",
+		version: GLAZE_EXPORT_VERSION,
 		form: "value",
 		input: value,
-		...options !== void 0 ? { overrides: buildOverridesExport(options) } : {},
-		config: effectiveConfigOverride
-	});
-	return createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effectiveConfig, linkingBase, exportData);
+		...options !== void 0 ? { overrides: buildOverridesExport(options, exportArg) } : {},
+		config: freezeConfigForExport(localOverride, exportArg)
+	}));
 }
 /**
 * Build a JSON-safe snapshot of `GlazeColorOverrides`. `base` is
 * recursively serialized when it was originally a token; raw values are
 * preserved as-is so `glaze.colorFrom(...)` round-trips them.
 */
-function buildOverridesExport(options) {
+function buildOverridesExport(options, exportArg) {
 	const out = {};
 	if (options.hue !== void 0) out.hue = options.hue;
 	if (options.saturation !== void 0) out.saturation = options.saturation;
@@ -3178,10 +3265,10 @@ function buildOverridesExport(options) {
 	if (options.name !== void 0) out.name = options.name;
 	if (options.pastel !== void 0) out.pastel = options.pastel;
 	if (options.role !== void 0) out.role = options.role;
-	if (options.base !== void 0) out.base = isGlazeColorToken(options.base) ? options.base.export() : options.base;
+	if (options.base !== void 0) out.base = isGlazeColorToken(options.base) ? options.base.export(exportArg) : options.base;
 	return out;
 }
-function buildStructuredInputExport(input) {
+function buildStructuredInputExport(input, exportArg) {
 	const out = {
 		hue: input.hue,
 		saturation: input.saturation,
@@ -3195,14 +3282,14 @@ function buildStructuredInputExport(input) {
 	if (input.name !== void 0) out.name = input.name;
 	if (input.pastel !== void 0) out.pastel = input.pastel;
 	if (input.role !== void 0) out.role = input.role;
-	if (input.base !== void 0) out.base = isGlazeColorToken(input.base) ? input.base.export() : input.base;
+	if (input.base !== void 0) out.base = isGlazeColorToken(input.base) ? input.base.export(exportArg) : input.base;
 	return out;
 }
 /**
 * Discriminate a `GlazeColorTokenExport` from a raw `GlazeColorValue`.
 */
 function isExportedToken(candidate) {
-	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && "form" in candidate && (candidate.form === "value" || candidate.form === "structured");
+	return isColorTokenExport(candidate);
 }
 function rehydrateOverrides(data) {
 	const out = {};
@@ -3241,12 +3328,14 @@ function rehydrateStructuredInput(data) {
 * Rehydrate a token from its `.export()` snapshot. Recursively rebuilds
 * any base dependency. Inverse of `GlazeColorToken.export()`.
 *
-* The stored `config` field contains the full effective config override
-* snapshotted at creation time, so the rehydrated token is deterministic
-* regardless of subsequent `glaze.configure()` calls.
+* The stored `config` field is the freeze from export time — passed as
+* the instance local override so the rehydrated token stays pinned
+* against later `glaze.configure()` calls.
 */
 function colorFromExport(data) {
 	if (data === null || typeof data !== "object") throw new Error(`glaze.colorFrom: expected an object from token.export(), got ${data === null ? "null" : typeof data}.`);
+	assertExportKind(data, "color", "glaze.colorFrom");
+	assertExportVersion(data, "glaze.colorFrom");
 	if (data.form !== "value" && data.form !== "structured") throw new Error(`glaze.colorFrom: invalid "form" field — expected "value" or "structured" (got ${JSON.stringify(data.form)}).`);
 	if (data.input === void 0) throw new Error(`glaze.colorFrom: missing "input" field — expected the original ${data.form === "value" ? "GlazeColorValue" : "GlazeColorInput"}.`);
 	if (data.form === "value") {
@@ -3256,6 +3345,157 @@ function colorFromExport(data) {
 	return createColorToken(rehydrateStructuredInput(data.input), data.config);
 }
 
+//#endregion
+//#region src/theme.ts
+function createTheme(hue, saturation, initialColors, configOverride) {
+	let colorDefs = initialColors ? { ...initialColors } : {};
+	let cache = null;
+	function getEffectiveConfig() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version) return cache.effectiveConfig;
+		const effectiveConfig = mergeConfig(getConfig(), configOverride);
+		cache = {
+			map: null,
+			version,
+			effectiveConfig
+		};
+		return effectiveConfig;
+	}
+	function resolveCached() {
+		const version = getConfigVersion();
+		if (cache && cache.version === version && cache.map) return cache.map;
+		const effectiveConfig = getEffectiveConfig();
+		const map = resolveAllColors(hue, saturation, colorDefs, effectiveConfig);
+		cache = {
+			map,
+			version,
+			effectiveConfig
+		};
+		return map;
+	}
+	function invalidate() {
+		cache = null;
+	}
+	function channelCtxFor(options, formatDefault, prefix) {
+		const format = options?.format ?? formatDefault;
+		if (!options?.splitHue || format !== "oklch") return void 0;
+		assertAllPastel(resolveCached(), resolveModes(options?.modes));
+		return {
+			seedHue: hue,
+			baseName: options.name ?? "theme",
+			prefix,
+			defs: colorDefs,
+			mode: "theme"
+		};
+	}
+	return {
+		get hue() {
+			return hue;
+		},
+		get saturation() {
+			return saturation;
+		},
+		getConfig() {
+			return getEffectiveConfig();
+		},
+		colors(defs) {
+			colorDefs = {
+				...colorDefs,
+				...defs
+			};
+			invalidate();
+		},
+		color(name, def) {
+			if (def === void 0) return colorDefs[name];
+			colorDefs[name] = def;
+			invalidate();
+		},
+		remove(names) {
+			const list = Array.isArray(names) ? names : [names];
+			for (const name of list) delete colorDefs[name];
+			invalidate();
+		},
+		has(name) {
+			return name in colorDefs;
+		},
+		list() {
+			return Object.keys(colorDefs);
+		},
+		reset() {
+			colorDefs = {};
+			invalidate();
+		},
+		export(override) {
+			return {
+				kind: "theme",
+				version: GLAZE_EXPORT_VERSION,
+				hue,
+				saturation,
+				colors: structuredClone(colorDefs),
+				config: freezeConfigForExport(configOverride, override)
+			};
+		},
+		extend(options) {
+			const newHue = options.hue ?? hue;
+			const newSat = options.saturation ?? saturation;
+			const inheritedColors = {};
+			for (const [name, def] of Object.entries(colorDefs)) if (def.inherit !== false) inheritedColors[name] = def;
+			return createTheme(newHue, newSat, options.colors ? {
+				...inheritedColors,
+				...options.colors
+			} : { ...inheritedColors }, configOverride || options.config ? {
+				...configOverride ?? {},
+				...options.config ?? {}
+			} : void 0);
+		},
+		resolve() {
+			return new Map(resolveCached());
+		},
+		tokens(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tokens");
+			const modes = resolveModes(options?.modes);
+			return buildFlatTokenMap(resolveCached(), "", modes, format, getEffectiveConfig().pastel);
+		},
+		tasty(options) {
+			const cfg = getEffectiveConfig();
+			const states = {
+				dark: options?.states?.dark ?? cfg.states.dark,
+				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
+			};
+			const modes = resolveModes(options?.modes);
+			const format = options?.format ?? "oklch";
+			const channelCtx = channelCtxFor(options, "oklch", "");
+			return buildTokenMap(resolveCached(), "", states, modes, format, cfg.pastel, channelCtx);
+		},
+		json(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "json");
+			const modes = resolveModes(options?.modes);
+			return buildJsonMap(resolveCached(), modes, format, getEffectiveConfig().pastel);
+		},
+		css(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "css");
+			const channelCtx = channelCtxFor(options, "oklch", "");
+			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
+		},
+		dtcg(options) {
+			const modes = resolveModes(options?.modes);
+			return buildDtcgMap(resolveCached(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
+		},
+		dtcgResolver(options) {
+			return buildDtcgResolver(buildDtcgMap(resolveCached(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel), options);
+		},
+		tailwind(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tailwind");
+			const modes = resolveModes(options?.modes);
+			return buildTailwindMap(resolveCached(), "", options?.namespace ?? "color-", modes, format, options?.darkSelector ?? ".dark", options?.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
+		}
+	};
+}
+
 //#endregion
 //#region src/palette.ts
 function resolvePrefix(options, themeName, defaultPrefix = false) {
@@ -3335,6 +3575,26 @@ function buildPaletteOutput(themes, paletteOptions, options, buildOne, merge, em
 	}
 	return acc;
 }
+/** Rebuild a theme from a `theme.export()` snapshot. */
+function createThemeFromExport(data, factory = "glaze.themeFrom") {
+	if (data === null || typeof data !== "object") throw new Error(`${factory}: expected an object from theme.export(), got ${data === null ? "null" : typeof data}.`);
+	assertExportKind(data, "theme", factory);
+	assertExportVersion(data, factory);
+	if (typeof data.hue !== "number" || typeof data.saturation !== "number") throw new Error(`${factory}: expected numeric "hue" and "saturation" fields.`);
+	return createTheme(data.hue, data.saturation, data.colors, data.config);
+}
+/**
+* Rebuild a palette from a `palette.export()` snapshot.
+*/
+function createPaletteFromExport(data) {
+	if (data === null || typeof data !== "object") throw new Error(`glaze.paletteFrom: expected an object from palette.export(), got ${data === null ? "null" : typeof data}.`);
+	assertExportKind(data, "palette", "glaze.paletteFrom");
+	assertExportVersion(data, "glaze.paletteFrom");
+	if (data.themes === null || typeof data.themes !== "object") throw new Error(`glaze.paletteFrom: expected a "themes" object map of theme exports.`);
+	const rebuilt = {};
+	for (const [name, themeExport] of Object.entries(data.themes)) rebuilt[name] = createThemeFromExport(themeExport, `glaze.paletteFrom (theme "${name}")`);
+	return createPalette(rebuilt, { primary: data.primary });
+}
 function createPalette(themes, paletteOptions) {
 	validatePrimaryTheme(paletteOptions?.primary, themes);
 	const buildDtcgResult = (options) => {
@@ -3348,6 +3608,29 @@ function createPalette(themes, paletteOptions) {
 		}, () => ({ light: {} }));
 	};
 	return {
+		list() {
+			return Object.keys(themes);
+		},
+		get primary() {
+			return paletteOptions?.primary;
+		},
+		theme(name) {
+			return themes[name];
+		},
+		themes() {
+			return { ...themes };
+		},
+		export(override) {
+			const themesExport = {};
+			for (const [name, theme] of Object.entries(themes)) themesExport[name] = theme.export(override);
+			const out = {
+				kind: "palette",
+				version: GLAZE_EXPORT_VERSION,
+				themes: themesExport
+			};
+			if (paletteOptions?.primary !== void 0) out.primary = paletteOptions.primary;
+			return out;
+		},
 		tokens(options) {
 			const format = options?.format ?? "oklch";
 			assertNativeFormat(format, "tokens");
@@ -3436,150 +3719,6 @@ function createPalette(themes, paletteOptions) {
 	};
 }
 
-//#endregion
-//#region src/theme.ts
-function createTheme(hue, saturation, initialColors, configOverride) {
-	let colorDefs = initialColors ? { ...initialColors } : {};
-	let cache = null;
-	function getEffectiveConfig() {
-		const version = getConfigVersion();
-		if (cache && cache.version === version) return cache.effectiveConfig;
-		return mergeConfig(getConfig(), configOverride);
-	}
-	function resolveCached() {
-		const version = getConfigVersion();
-		if (cache && cache.version === version) return cache.map;
-		const effectiveConfig = mergeConfig(getConfig(), configOverride);
-		const map = resolveAllColors(hue, saturation, colorDefs, effectiveConfig);
-		cache = {
-			map,
-			version,
-			effectiveConfig
-		};
-		return map;
-	}
-	function invalidate() {
-		cache = null;
-	}
-	function channelCtxFor(options, formatDefault, prefix) {
-		const format = options?.format ?? formatDefault;
-		if (!options?.splitHue || format !== "oklch") return void 0;
-		assertAllPastel(resolveCached(), resolveModes(options?.modes));
-		return {
-			seedHue: hue,
-			baseName: options.name ?? "theme",
-			prefix,
-			defs: colorDefs,
-			mode: "theme"
-		};
-	}
-	return {
-		get hue() {
-			return hue;
-		},
-		get saturation() {
-			return saturation;
-		},
-		getConfig() {
-			return getEffectiveConfig();
-		},
-		colors(defs) {
-			colorDefs = {
-				...colorDefs,
-				...defs
-			};
-			invalidate();
-		},
-		color(name, def) {
-			if (def === void 0) return colorDefs[name];
-			colorDefs[name] = def;
-			invalidate();
-		},
-		remove(names) {
-			const list = Array.isArray(names) ? names : [names];
-			for (const name of list) delete colorDefs[name];
-			invalidate();
-		},
-		has(name) {
-			return name in colorDefs;
-		},
-		list() {
-			return Object.keys(colorDefs);
-		},
-		reset() {
-			colorDefs = {};
-			invalidate();
-		},
-		export() {
-			const out = {
-				hue,
-				saturation,
-				colors: { ...colorDefs }
-			};
-			if (configOverride !== void 0) out.config = configOverride;
-			return out;
-		},
-		extend(options) {
-			const newHue = options.hue ?? hue;
-			const newSat = options.saturation ?? saturation;
-			const inheritedColors = {};
-			for (const [name, def] of Object.entries(colorDefs)) if (def.inherit !== false) inheritedColors[name] = def;
-			return createTheme(newHue, newSat, options.colors ? {
-				...inheritedColors,
-				...options.colors
-			} : { ...inheritedColors }, configOverride || options.config ? {
-				...configOverride ?? {},
-				...options.config ?? {}
-			} : void 0);
-		},
-		resolve() {
-			return new Map(resolveCached());
-		},
-		tokens(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "tokens");
-			const modes = resolveModes(options?.modes);
-			return buildFlatTokenMap(resolveCached(), "", modes, format, getEffectiveConfig().pastel);
-		},
-		tasty(options) {
-			const cfg = getEffectiveConfig();
-			const states = {
-				dark: options?.states?.dark ?? cfg.states.dark,
-				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
-			};
-			const modes = resolveModes(options?.modes);
-			const format = options?.format ?? "oklch";
-			const channelCtx = channelCtxFor(options, "oklch", "");
-			return buildTokenMap(resolveCached(), "", states, modes, format, cfg.pastel, channelCtx);
-		},
-		json(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "json");
-			const modes = resolveModes(options?.modes);
-			return buildJsonMap(resolveCached(), modes, format, getEffectiveConfig().pastel);
-		},
-		css(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "css");
-			const channelCtx = channelCtxFor(options, "oklch", "");
-			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
-		},
-		dtcg(options) {
-			const modes = resolveModes(options?.modes);
-			return buildDtcgMap(resolveCached(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
-		},
-		dtcgResolver(options) {
-			return buildDtcgResolver(buildDtcgMap(resolveCached(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel), options);
-		},
-		tailwind(options) {
-			const format = options?.format ?? "oklch";
-			assertNativeFormat(format, "tailwind");
-			const modes = resolveModes(options?.modes);
-			return buildTailwindMap(resolveCached(), "", options?.namespace ?? "color-", modes, format, options?.darkSelector ?? ".dark", options?.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
-		}
-	};
-}
-
 //#endregion
 //#region src/glaze.ts
 /**
@@ -3593,6 +3732,7 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 * - `shadow.ts` — standalone shadow factory (`glaze.shadow`)
 * - `formatters.ts` — variant → string (`glaze.format`)
 * - `config.ts` — global config singleton
+* - `serialize.ts` — authoring export type guards / version checks
 */
 /**
 * Create a single-hue glaze theme.
@@ -3624,10 +3764,15 @@ glaze.configure = function configure$1(config) {
 glaze.palette = function palette(themes, options) {
 	return createPalette(themes, options);
 };
-/** Create a theme from a serialized export. */
-glaze.from = function from(data) {
-	return createTheme(data.hue, data.saturation, data.colors, data.config);
+/**
+* Create a theme from a serialized `theme.export()` snapshot.
+* Prefer this over the legacy `glaze.from` alias.
+*/
+glaze.themeFrom = function themeFrom(data) {
+	return createThemeFromExport(data);
 };
+/** Compat alias for `glaze.themeFrom`. */
+glaze.from = glaze.themeFrom;
 /**
 * Create a standalone single-color token.
 *
@@ -3643,8 +3788,8 @@ glaze.from = function from(data) {
 * **arg2 — config override** (optional, all shapes):
 * Overrides the resolve-relevant global config fields for this token.
 * Fields that are omitted fall through to the live global config at
-* create time (and are snapshotted). Pass `false` for a tone window
-* to disable clamping entirely.
+* resolve time. Pass `false` for a tone window to disable clamping
+* entirely. `pastel` is instance-only (not set via `configure()`).
 *
 * ```ts
 * // Bare string — no overrides
@@ -3663,8 +3808,8 @@ glaze.from = function from(data) {
 *
 * Defaults: every form defaults to `mode: 'auto'`. Value-shorthand forms
 * (bare strings and value objects) preserve light tone exactly
-* (`lightTone: false` internally). Structured form snapshots both
-* tone windows from `globalConfig` at create time.
+* (`lightTone: false` locally). Structured form falls through to the live
+* global tone windows for omitted fields.
 *
 * Relative `tone: '+N'` and `contrast` anchor to the literal seed by
 * default; when `base` is set they anchor to the base's resolved variant
@@ -3742,8 +3887,8 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 *
 * The snapshot is a plain JSON-safe object containing the original
 * input value, overrides (with any `base` token recursively serialized),
-* and the effective config snapshot. The reconstructed token is identical
-* in behavior to the original at the time of export.
+* and the effective config freeze from export time. The reconstructed
+* token pins that freeze as its local override.
 *
 * @example
 * ```ts
@@ -3757,6 +3902,18 @@ glaze.fromRgb = function fromRgb(r, g, b) {
 glaze.colorFrom = function colorFrom(data) {
 	return colorFromExport(data);
 };
+/**
+* Rehydrate a palette from a `palette.export()` snapshot.
+*/
+glaze.paletteFrom = function paletteFrom(data) {
+	return createPaletteFromExport(data);
+};
+/** Type guard for theme authoring snapshots. */
+glaze.isThemeExport = isThemeExport;
+/** Type guard for color-token authoring snapshots. */
+glaze.isColorTokenExport = isColorTokenExport;
+/** Type guard for palette authoring snapshots. */
+glaze.isPaletteExport = isPaletteExport;
 /** Get the current global configuration (for testing/debugging). */
 glaze.getConfig = function getConfig() {
 	return snapshotConfig();
@@ -3767,5 +3924,5 @@ glaze.resetConfig = function resetConfig$1() {
 };
 
 //#endregion
-export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, REF_EPS, 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, GLAZE_EXPORT_VERSION, REF_EPS, 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.mjs.map