@animus-ui/system 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,13 +1,14 @@
-import { n as createClassResolver, r as createComponent, t as createComposedFamily } from "./createComposedFamily-DSE2ZuRE.js";
+import { n as createClassResolver, r as createComponent, t as createComposedFamily } from "./createComposedFamily-DJ2aqfqN.js";
 import { compose } from "./compose.js";
 import { a as borderShorthand, c as numericOrStringScale, i as gridItemRatio, l as numericScale, n as size, o as createTransform, r as gridItem, s as createScale, t as percentageOrAbsolute, u as stringScale } from "./size-CusLCguT.js";
 //#region src/utils/deepMerge.ts
 /**
 * Deep merge utility — replaces lodash.merge for variant accumulation.
 */
+const isMergeable = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 function deepMerge(target, source) {
 	const result = { ...target };
-	for (const key of Object.keys(source)) if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key]) && target[key] && typeof target[key] === "object" && !Array.isArray(target[key])) result[key] = deepMerge(target[key], source[key]);
+	for (const key of Object.keys(source)) if (isMergeable(source[key]) && isMergeable(target[key])) result[key] = deepMerge(target[key], source[key]);
 	else result[key] = source[key];
 	return result;
 }
@@ -228,6 +229,149 @@ var Animus = class extends AnimusWithBase {
 	}
 };
 //#endregion
+//#region src/conditions.ts
+/**
+* Built-in condition aliases (design D8, increment 06).
+*
+* The Panda-compatible media-feature set: motion, print, orientation, contrast,
+* and OS color-scheme preferences. Every alias is a pure `@media` feature query
+* (`kind: 'media'`). Color-mode aliases (`_dark` / `_light`) are DELIBERATELY
+* excluded — they are selector-kind (`[data-color-mode]`) surface owned by the
+* `system-color-scheme` change, not media features.
+*
+* ORDER BAND (inc-03 full-pass): built-ins occupy a reserved band BELOW the user
+* band — one slot of 10 per alias in table row order, 300–380. The user band
+* starts at 500 (`mergeConditions` floors allocation at 490 → first user alias
+* is 500), so built-ins and user registrations never interleave on collision.
+* This mirrors the selector registry's real layout (built-ins 10–440, users
+* 500+).
+*
+* The static type-level mirror is `BuiltInConditionAlias` in `types/config.ts`
+* (added to `KnownUnderscoreKey`'s VALIDATING branch, exactly like
+* `BuiltInSelectorAlias`). Built-ins are NOT members of the augmentable
+* `Conditions` interface: interface members would make publication permanently
+* non-empty, killing inc-04's graceful-degradation contract. The
+* `types.test-d.tsx` drift positives keep the two in sync.
+*/
+const BUILT_IN_CONDITIONS = {
+	_motionReduce: {
+		value: "@media (prefers-reduced-motion: reduce)",
+		order: 300,
+		kind: "media"
+	},
+	_motionSafe: {
+		value: "@media (prefers-reduced-motion: no-preference)",
+		order: 310,
+		kind: "media"
+	},
+	_print: {
+		value: "@media print",
+		order: 320,
+		kind: "media"
+	},
+	_portrait: {
+		value: "@media (orientation: portrait)",
+		order: 330,
+		kind: "media"
+	},
+	_landscape: {
+		value: "@media (orientation: landscape)",
+		order: 340,
+		kind: "media"
+	},
+	_moreContrast: {
+		value: "@media (prefers-contrast: more)",
+		order: 350,
+		kind: "media"
+	},
+	_lessContrast: {
+		value: "@media (prefers-contrast: less)",
+		order: 360,
+		kind: "media"
+	},
+	_osDark: {
+		value: "@media (prefers-color-scheme: dark)",
+		order: 370,
+		kind: "media"
+	},
+	_osLight: {
+		value: "@media (prefers-color-scheme: light)",
+		order: 380,
+		kind: "media"
+	}
+};
+/** The supported at-rule prefixes, longest-first so `@media`/`@container`/
+*  `@supports` match unambiguously. */
+const CONDITION_PREFIXES = [
+	["@media", "media"],
+	["@container", "container"],
+	["@supports", "supports"]
+];
+/**
+* Infer the condition kind from an at-rule value's prefix (design D3).
+* Throws (fail-loud, build time) when the value does not begin with a
+* supported at-rule name. The compile-time complement is `addConditions()`'s
+* value constraint (`@media`/`@container`/`@supports`-prefixed template
+* literals); this runtime throw remains the backstop for untyped callers.
+*/
+function inferConditionKind(value) {
+	for (const [prefix, kind] of CONDITION_PREFIXES) if (value.startsWith(prefix)) return kind;
+	throw new Error(`addConditions: value "${value}" must begin with @media, @container, or @supports`);
+}
+/**
+* Merge user-provided condition aliases with a base map.
+*
+* - User aliases override built-ins of the same name, preserving the existing
+*   order (mirrors `mergeSelectors`).
+* - New aliases allocate orders CONTINUING from the highest existing order
+*   (floored at 490, so the first user alias lands at 500) rather than
+*   restarting at 500 each call — chained `.addConditions()` calls must not
+*   collide on order 500.
+* - Fails loud when a condition alias name is already reserved by the SELECTOR
+*   alias registry (`reservedSelectorNames`): the two registries share the `_`
+*   namespace at the call site and their names MUST be disjoint, else a block
+*   key would be ambiguous. The error names the offending alias and both
+*   registries.
+*/
+function mergeConditions(base, custom, reservedSelectorNames = /* @__PURE__ */ new Set()) {
+	const merged = { ...base };
+	let nextOrder = Math.max(490, ...Object.values(merged).map((c) => c.order)) + 10;
+	for (const [key, value] of Object.entries(custom)) {
+		if (reservedSelectorNames.has(key)) throw new Error(`addConditions: alias "${key}" is already registered in the selector alias registry — condition and selector alias names must be disjoint (rename the condition alias or the selector alias).`);
+		const kind = inferConditionKind(value);
+		if (key in merged) merged[key] = {
+			value,
+			order: merged[key].order,
+			kind
+		};
+		else {
+			merged[key] = {
+				value,
+				order: nextOrder,
+				kind
+			};
+			nextOrder += 10;
+		}
+	}
+	return merged;
+}
+/** Get the sorted alias keys for deterministic cascade ordering. */
+function getSortedConditionKeys(map) {
+	return Object.keys(map).sort((a, b) => map[a].order - map[b].order);
+}
+/**
+* Serialize the condition map for the extraction pipeline.
+* Emits `alias → { value, order, kind }` in registry (cascade) order so the
+* JSON is deterministic. Distinct in SHAPE from the selector map (which
+* flattens to `alias → selector`) — the object entry is forward-compatible
+* with a future multi-valued `values: string[]` property (design D3).
+*/
+function serializeConditionMap(map) {
+	const conditions = {};
+	for (const key of getSortedConditionKeys(map)) conditions[key] = map[key];
+	return conditions;
+}
+//#endregion
 //#region src/keyframes.ts
 const fnv1a = (input) => {
 	let hash = 2166136261;
@@ -423,27 +567,52 @@ function serializeSelectorMap(map) {
 }
 //#endregion
 //#region src/SystemBuilder.ts
+function orderedPropertiesEqual(existing, incoming) {
+	if (existing === incoming) return true;
+	if (!existing || !incoming || existing.length !== incoming.length) return false;
+	return existing.every((property, index) => property === incoming[index]);
+}
+function arePropDefinitionsEqual(existing, incoming) {
+	return existing.property === incoming.property && orderedPropertiesEqual(existing.properties, incoming.properties) && existing.scale === incoming.scale && existing.variable === incoming.variable && existing.negative === incoming.negative && existing.strict === incoming.strict && existing.currentVar === incoming.currentVar && existing.transform === incoming.transform;
+}
 var SystemBuilder = class SystemBuilder {
 	#propRegistry;
 	#groupRegistry;
 	#selectorRegistry;
 	#includesRegistry;
-	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry) {
+	#conditionRegistry;
+	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry, conditionRegistry) {
 		this.#propRegistry = propRegistry || {};
 		this.#groupRegistry = groupRegistry || {};
 		this.#selectorRegistry = selectorRegistry || { ...BUILT_IN_SELECTORS };
 		this.#includesRegistry = includesRegistry || [];
+		this.#conditionRegistry = conditionRegistry || { ...BUILT_IN_CONDITIONS };
 	}
 	addSelectors(selectors) {
+		for (const name of Object.keys(selectors)) if (name in this.#conditionRegistry) throw new Error(`addSelectors: "${name}" is already registered as a condition alias; a name resolves through exactly one registry. Pick a distinct name.`);
 		const merged = mergeSelectors(this.#selectorRegistry, selectors);
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry, this.#conditionRegistry);
+	}
+	/**
+	* Register condition aliases (`_motionReduce`, `_cardSm`, …) → at-rule
+	* condition strings (`@media …` / `@container …` / `@supports …`).
+	* Recognized as block keys in style objects; user aliases override built-ins
+	* of the same name (design D3). Keys are constrained to `_`-prefixed aliases
+	* and values to `@`-prefixed at-rule strings — a value that does not begin
+	* with an at-rule name is a compile-time type error (design D9; the runtime
+	* `inferConditionKind` throw is defense-in-depth). The registered keys are
+	* accumulated into the phantom `Conds` union and surfaced on `build()`.
+	*/
+	addConditions(conditions) {
+		const merged = mergeConditions(this.#conditionRegistry, conditions, new Set(Object.keys(this.#selectorRegistry)));
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, merged);
 	}
 	addGroup(name, config) {
 		if (name in this.#propRegistry) throw new Error(`Group name "${name}" collides with an existing prop name. Group names and prop names must be disjoint.`);
 		for (const key of Object.keys(config)) if (key in this.#propRegistry) {
 			const existing = this.#propRegistry[key];
 			const incoming = config[key];
-			if (existing.property !== incoming.property || existing.scale !== incoming.scale || existing.transform !== incoming.transform || existing.negative !== incoming.negative) throw new Error(`Prop "${key}" already registered with a different definition. Existing: property="${existing.property}", scale="${String(existing.scale)}". Incoming: property="${incoming.property}", scale="${String(incoming.scale)}".`);
+			if (!arePropDefinitionsEqual(existing, incoming)) throw new Error(`Prop "${key}" already registered with a different definition. Existing: property="${existing.property}", scale="${String(existing.scale)}". Incoming: property="${incoming.property}", scale="${String(incoming.scale)}".`);
 		}
 		const nextProps = {
 			...this.#propRegistry,
@@ -453,31 +622,33 @@ var SystemBuilder = class SystemBuilder {
 		return new SystemBuilder(nextProps, {
 			...this.#groupRegistry,
 			...newGroup
-		}, this.#selectorRegistry, this.#includesRegistry);
+		}, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry);
 	}
 	addProps(config) {
 		for (const key of Object.keys(config)) if (key in this.#groupRegistry) throw new Error(`Prop name "${key}" collides with an existing group name. Group names and prop names must be disjoint.`);
 		for (const key of Object.keys(config)) if (key in this.#propRegistry) {
 			const existing = this.#propRegistry[key];
 			const incoming = config[key];
-			if (existing.property !== incoming.property || existing.scale !== incoming.scale || existing.transform !== incoming.transform || existing.negative !== incoming.negative) throw new Error(`Prop "${key}" already registered with a different definition.`);
+			if (!arePropDefinitionsEqual(existing, incoming)) throw new Error(`Prop "${key}" already registered with a different definition.`);
 		}
 		return new SystemBuilder({
 			...this.#propRegistry,
 			...config
-		}, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry);
+		}, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry);
 	}
 	build() {
 		const animus = new Animus(this.#propRegistry, this.#groupRegistry);
 		const propRegistry = this.#propRegistry;
 		const groupRegistry = this.#groupRegistry;
 		const selectorRegistry = this.#selectorRegistry;
+		const conditionRegistry = this.#conditionRegistry;
 		const system = Object.assign(animus, { toConfig: () => {
-			return serializeInstance(propRegistry, groupRegistry, selectorRegistry);
+			return serializeInstance(propRegistry, groupRegistry, selectorRegistry, conditionRegistry);
 		} });
-		const createGlobalStyles = ((styles) => ({
+		const createGlobalStyles = ((styles, options) => ({
 			__brand: "GlobalStyleBlock",
-			styles
+			styles,
+			...options?.fontFaces?.length ? { fontFaces: [...options.fontFaces] } : {}
 		}));
 		const createKeyframes = ((frames) => keyframes(frames));
 		return {
@@ -487,7 +658,7 @@ var SystemBuilder = class SystemBuilder {
 		};
 	}
 };
-function serializeInstance(propRegistry, groupRegistry, selectorRegistry) {
+function serializeInstance(propRegistry, groupRegistry, selectorRegistry, conditionRegistry) {
 	const serialized = {};
 	const transforms = {};
 	for (const [propName, entry] of Object.entries(propRegistry)) {
@@ -509,11 +680,13 @@ function serializeInstance(propRegistry, groupRegistry, selectorRegistry) {
 		serialized[propName] = s;
 	}
 	const { selectors } = serializeSelectorMap(selectorRegistry);
+	const conditions = serializeConditionMap(conditionRegistry);
 	return {
 		propConfig: JSON.stringify(serialized),
 		groupRegistry: JSON.stringify(groupRegistry),
 		transforms,
-		selectorAliases: JSON.stringify(selectors)
+		selectorAliases: JSON.stringify(selectors),
+		conditionAliases: JSON.stringify(conditions)
 	};
 }
 function createSystem(config) {
@@ -618,6 +791,109 @@ function validateModeAliases(modeName, aliases, nestedColors, flatColorKeys, pre
 		} else if (isObject(value)) validateModeAliases(modeName, value, nestedColors, flatColorKeys, aliasPath);
 	}
 }
+/**
+* Reserved mode name (D4). "System" is modeled as the ABSENCE of
+* `data-color-mode`, never as a mode: an attribute value `system` would defeat
+* the `:root:not([data-color-mode])` guard while matching no mode block.
+*/
+const RESERVED_MODE_NAME = "system";
+/**
+* Theme keys owned by the color-mode options. A scale may not claim them —
+* they are skipped by `flattenTheme` and read back as option objects in
+* `build()`, so a same-named scale would emit zero tokens AND fabricate a
+* manifest field from its values.
+*
+* NOTE: the pre-existing `mode` / `modes` / `breakpoints` structural keys have
+* the same hole and are deliberately NOT covered here (out of scope).
+*/
+const RESERVED_THEME_KEYS = new Set(["systemPreference", "browserColorScheme"]);
+const COLOR_SCHEME_VALUES = new Set([
+	"light",
+	"dark",
+	"normal"
+]);
+/**
+* The axis → scheme pairs the mapping forces: the mode named for the OS light
+* preference must classify `light`, the dark one `dark`. Single source for
+* BOTH the default fill and the conflict check in
+* {@link resolveColorModeOptions} — one rule, one table.
+*/
+const MAPPING_FORCED_SCHEMES = [["light", "light"], ["dark", "dark"]];
+/**
+* Merge an incoming option object over the one already on the theme, mirroring
+* `merge`'s per-key override. Returns `undefined` when neither side supplied
+* one, so an unconfigured theme never gains the key (byte parity, G4).
+*/
+function mergeOptionObject(existing, incoming) {
+	const hasExisting = isObject(existing);
+	const hasIncoming = isObject(incoming);
+	if (!hasExisting && !hasIncoming) return void 0;
+	return {
+		...hasExisting ? existing : {},
+		...hasIncoming ? incoming : {}
+	};
+}
+/** Reject the reserved mode name (D4) wherever a mode set is declared or merged. */
+function validateReservedModeNames(modeNames) {
+	for (const modeName of modeNames) if (modeName === RESERVED_MODE_NAME) throw new Error(`addColorModes: '${RESERVED_MODE_NAME}' is a reserved mode name — the system preference is represented by the absence of the data-color-mode attribute, never by a declared mode. Rename it. Declared modes: ${modeNames.join(", ")}`);
+}
+/**
+* Normalize AND validate the optional system-participation options against the
+* declared modes, returning the normalized classification. One entry point on
+* purpose: the D3-amendment fill (mapping-named modes default to their forced
+* schemes) must always run before totality is checked, so exposing fill and
+* validation separately would make "validate an unfilled map" representable.
+* An explicit entry survives the fill's spread and is still conflict-checked,
+* so a wrong value errors rather than being silently corrected. `undefined`
+* passes through untouched — the classification stays opt-in, and a theme with
+* only `systemPreference` emits no `color-scheme` (byte parity, G4).
+*
+* ALWAYS called with MERGED state — `theme.modes` unions across `addColorModes`
+* calls and `from()` composition, so a per-call view both misses invalidation
+* (a later mode declaration un-totals a carried classification) and invents
+* false rejections (a mapping naming a mode declared by an earlier call).
+* Run at both gates: `addColorModes` (fail fast) and `build()` (authoritative —
+* `from()` composition never passes through `addColorModes`; only build()'s
+* resolved map feeds emission and the manifest).
+*
+* Error tone mirrors `validateModeAliases`: `addColorModes:` prefix plus the
+* available names.
+*/
+function resolveColorModeOptions(modeNames, systemPreference, suppliedBrowserColorScheme) {
+	let browserColorScheme = suppliedBrowserColorScheme;
+	if (browserColorScheme && systemPreference) {
+		const forced = {};
+		for (const [axis, scheme] of MAPPING_FORCED_SCHEMES) {
+			const modeName = systemPreference[axis];
+			if (typeof modeName === "string") forced[modeName] = scheme;
+		}
+		browserColorScheme = {
+			...forced,
+			...suppliedBrowserColorScheme
+		};
+	}
+	const available = `Available modes: ${modeNames.join(", ")}`;
+	const declared = new Set(modeNames);
+	if (systemPreference) for (const axis of ["light", "dark"]) {
+		const modeName = systemPreference[axis];
+		if (typeof modeName !== "string" || modeName === "") throw new Error(`addColorModes: systemPreference requires both 'light' and 'dark' to name a declared mode — '${axis}' is missing. ${available}`);
+		if (modeName === RESERVED_MODE_NAME) throw new Error(`addColorModes: '${RESERVED_MODE_NAME}' is reserved and cannot be used as systemPreference.${axis} — the system preference is represented by the absence of the data-color-mode attribute. ${available}`);
+		if (!declared.has(modeName)) throw new Error(`addColorModes: systemPreference.${axis} references unknown mode '${modeName}'. ${available}`);
+	}
+	if (!browserColorScheme) return browserColorScheme;
+	for (const [modeName, value] of Object.entries(browserColorScheme)) {
+		if (!declared.has(modeName)) throw new Error(`addColorModes: browserColorScheme references unknown mode '${modeName}'. ${available}`);
+		if (!COLOR_SCHEME_VALUES.has(value)) throw new Error(`addColorModes: browserColorScheme['${modeName}'] must be 'light', 'dark', or 'normal', got ${JSON.stringify(value)}.`);
+	}
+	for (const modeName of modeNames) if (!(modeName in browserColorScheme)) throw new Error(`addColorModes: browserColorScheme must classify every declared mode — mode '${modeName}' is unclassified. ${available}`);
+	if (!systemPreference) return browserColorScheme;
+	for (const [axis, expected] of MAPPING_FORCED_SCHEMES) {
+		const modeName = systemPreference[axis];
+		const classification = browserColorScheme[modeName];
+		if (classification !== expected) throw new Error(`addColorModes: browserColorScheme conflicts with systemPreference — mode '${modeName}' is mapped to the OS ${axis} preference but classified '${classification}'; expected '${expected}'.`);
+	}
+	return browserColorScheme;
+}
 /** Validate all color entries, throwing on invalid values. */
 function validateColors(colors) {
 	for (const [key, value] of Object.entries(colors)) if (isObject(value)) validateColors(value);
@@ -627,14 +903,19 @@ function createState(theme) {
 	return {
 		theme: theme || { breakpoints: {} },
 		emittedScales: /* @__PURE__ */ new Set(),
-		contextualVars: /* @__PURE__ */ new Map()
+		contextualVars: /* @__PURE__ */ new Map(),
+		contextualVarRegistrations: /* @__PURE__ */ new Map(),
+		hasLegacyManifestSource: false
 	};
 }
 function copyState(state, nextTheme) {
 	const next = {
 		theme: nextTheme,
 		emittedScales: new Set(state.emittedScales),
-		contextualVars: /* @__PURE__ */ new Map()
+		contextualVars: /* @__PURE__ */ new Map(),
+		contextualVarRegistrations: new Map(state.contextualVarRegistrations),
+		...state.carriedManifestV2 ? { carriedManifestV2: { ...state.carriedManifestV2 } } : {},
+		hasLegacyManifestSource: state.hasLegacyManifestSource
 	};
 	for (const [scale, vars] of state.contextualVars) next.contextualVars.set(scale, [...vars]);
 	return next;
@@ -667,6 +948,17 @@ var ThemeBuilder = class ThemeBuilder {
 			next._state.emittedScales.add(scale === "colors" ? "colors" : scale);
 		}
 		if (manifest?.contextualVars) for (const [scale, vars] of Object.entries(manifest.contextualVars)) next._state.contextualVars.set(scale, [...vars]);
+		if (manifest) if (manifest.manifestVersion === 2) {
+			next._state.carriedManifestV2 = {
+				tokenDefinitions: manifest.tokenDefinitions,
+				modeAliasDefinitions: manifest.modeAliasDefinitions,
+				registrations: manifest.registrations,
+				emitterVersion: manifest.emitterVersion,
+				contractHash: manifest.contractHash,
+				cssFragments: manifest.cssFragments
+			};
+			if (manifest.registrations) for (const [name, registration] of Object.entries(manifest.registrations)) next._state.contextualVarRegistrations.set(name, registration);
+		} else next._state.hasLegacyManifestSource = true;
 		return next;
 	}
 	addColors(colors) {
@@ -676,31 +968,46 @@ var ThemeBuilder = class ThemeBuilder {
 		next._state.emittedScales.add("colors");
 		return next;
 	}
-	addColorModes(initialMode, modeConfig) {
+	addColorModes(initialMode, modeConfig, options) {
 		const nestedColors = this._state.theme.colors || {};
 		const flatColors = flattenToDotPaths(nestedColors);
 		const flatColorKeys = Object.keys(flatColors);
+		const existingModes = isObject(this._state.theme.modes) ? this._state.theme.modes : {};
+		const modeNames = Object.keys({
+			...existingModes,
+			...modeConfig
+		});
+		validateReservedModeNames(modeNames);
 		for (const [modeName, modeAliases] of Object.entries(modeConfig)) validateModeAliases(modeName, modeAliases, nestedColors, flatColorKeys, "");
+		const systemPreference = mergeOptionObject(this._state.theme.systemPreference, options?.systemPreference);
+		const browserColorScheme = mergeOptionObject(this._state.theme.browserColorScheme, options?.browserColorScheme);
+		resolveColorModeOptions(modeNames, systemPreference, browserColorScheme);
 		const nextTheme = merge({}, this._state.theme, {
 			modes: modeConfig,
-			mode: initialMode
+			mode: initialMode,
+			...systemPreference ? { systemPreference } : {},
+			...browserColorScheme ? { browserColorScheme } : {}
 		});
 		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
 	addScale(config) {
 		const { name, values, emit } = config;
+		if (RESERVED_THEME_KEYS.has(name)) throw new Error(`addScale: '${name}' is a reserved theme key owned by addColorModes options — it is skipped by the token flatten pass and read back as an option object, so a scale by this name would emit no tokens. Choose another scale name.`);
 		const nextTheme = merge({}, this._state.theme, { [name]: values });
 		const next = new ThemeBuilder(copyState(this._state, nextTheme));
 		if (emit) next._state.emittedScales.add(name);
 		return next;
 	}
-	declareContextualVars(vars) {
+	declareContextualVars(vars, registrations) {
 		for (const scale of Object.keys(vars)) if (!(scale in this._state.theme)) throw new Error(`declareContextualVars: scale '${scale}' not found — call addColors or addScale first`);
 		const next = new ThemeBuilder(copyState(this._state, this._state.theme));
 		for (const [scale, names] of Object.entries(vars)) {
 			const existing = next._state.contextualVars.get(scale) || [];
 			next._state.contextualVars.set(scale, [...existing, ...names]);
 		}
+		if (registrations) {
+			for (const [name, registration] of Object.entries(registrations)) if (registration) next._state.contextualVarRegistrations.set(name, registration);
+		}
 		return next;
 	}
 	extendScale(key, updateFn) {
@@ -715,7 +1022,11 @@ var ThemeBuilder = class ThemeBuilder {
 		const theme = merge({}, this._state.theme);
 		const emittedScales = this._state.emittedScales;
 		const contextualVars = this._state.contextualVars;
-		const { tokenMap, variableMap, variables, modeVariables, modeTokens } = flattenTheme(theme, emittedScales);
+		const systemPreference = isObject(theme.systemPreference) ? theme.systemPreference : void 0;
+		const mergedModeNames = isObject(theme.modes) ? Object.keys(theme.modes) : [];
+		validateReservedModeNames(mergedModeNames);
+		const browserColorScheme = resolveColorModeOptions(mergedModeNames, systemPreference, isObject(theme.browserColorScheme) ? theme.browserColorScheme : void 0);
+		const { tokenMap, variableMap, variables, modeVariables, modeTokens, tokenDefinitions, modeAliasDefinitions } = flattenTheme(theme, emittedScales);
 		resolveTokenRefs(tokenMap, variableMap, emittedScales);
 		const bpVariables = {};
 		if (theme.breakpoints && isObject(theme.breakpoints)) for (const [key, value] of Object.entries(theme.breakpoints)) bpVariables[`--breakpoint-${key}`] = `${value}px`;
@@ -724,7 +1035,44 @@ var ThemeBuilder = class ThemeBuilder {
 			contextualVarsSerialized = {};
 			for (const [scale, vars] of contextualVars) contextualVarsSerialized[scale] = vars;
 		}
-		const variableCss = buildVariableCss(variables, bpVariables, modeVariables);
+		const propertyCss = buildPropertyRegistrationCss(contextualVars, this._state.contextualVarRegistrations);
+		const baseVariableCss = buildVariableCss(variables, bpVariables, modeVariables, {
+			initialMode: typeof theme.mode === "string" ? theme.mode : void 0,
+			systemPreference,
+			browserColorScheme
+		});
+		const variableCss = propertyCss ? baseVariableCss ? `${propertyCss}\n\n${baseVariableCss}` : propertyCss : baseVariableCss;
+		let manifestV2Fields = {};
+		if (!this._state.hasLegacyManifestSource) {
+			const registrations = Object.fromEntries(this._state.contextualVarRegistrations);
+			const cssFragments = [];
+			if (propertyCss) cssFragments.push({
+				id: "registrations",
+				kind: "registrations",
+				cssText: propertyCss
+			});
+			if (baseVariableCss) cssFragments.push({
+				id: "base",
+				kind: "base",
+				cssText: baseVariableCss
+			});
+			manifestV2Fields = {
+				manifestVersion: 2,
+				tokenDefinitions,
+				modeAliasDefinitions,
+				registrations,
+				emitterVersion: EMITTER_VERSION,
+				contractHash: computeContractHash({
+					tokenDefinitions,
+					modeAliasDefinitions,
+					initialMode: typeof theme.mode === "string" ? theme.mode : void 0,
+					registrations,
+					systemPreference,
+					browserColorScheme
+				}),
+				cssFragments
+			};
+		}
 		const manifest = {
 			tokenMap: {
 				...tokenMap,
@@ -733,7 +1081,10 @@ var ThemeBuilder = class ThemeBuilder {
 			variableMap,
 			modes: modeTokens,
 			variableCss,
-			...contextualVarsSerialized ? { contextualVars: contextualVarsSerialized } : {}
+			...contextualVarsSerialized ? { contextualVars: contextualVarsSerialized } : {},
+			...systemPreference ? { systemPreference } : {},
+			...browserColorScheme ? { browserColorScheme } : {},
+			...manifestV2Fields
 		};
 		Object.defineProperty(theme, "manifest", {
 			value: manifest,
@@ -787,9 +1138,11 @@ function flattenTheme(theme, emittedScales) {
 	const variables = {};
 	const modeVariables = {};
 	const modeTokens = {};
+	const tokenDefinitions = {};
+	const modeAliasDefinitions = {};
 	for (const [scaleName, scaleValue] of Object.entries(theme)) {
 		if (scaleName.startsWith("_")) continue;
-		if (scaleName === "breakpoints" || scaleName === "mode" || scaleName === "modes") continue;
+		if (scaleName === "breakpoints" || scaleName === "mode" || scaleName === "modes" || scaleName === "systemPreference" || scaleName === "browserColorScheme") continue;
 		if (typeof scaleValue === "function") continue;
 		if (!isObject(scaleValue)) continue;
 		const flat = flattenToDotPaths(scaleValue);
@@ -798,6 +1151,7 @@ function flattenTheme(theme, emittedScales) {
 			const tokenPath = `${scaleName}.${dotKey}`;
 			const dashKey = dotToDash(dotKey);
 			const varName = `--${scaleName === "colors" ? "color" : scaleName}-${dashKey}`;
+			tokenDefinitions[tokenPath] = parseTokenDefinition(String(rawValue));
 			if (isEmitted) {
 				tokenMap[tokenPath] = `var(${varName})`;
 				variableMap[tokenPath] = varName;
@@ -812,15 +1166,18 @@ function flattenTheme(theme, emittedScales) {
 			const flatAliases = flattenToDotPaths(modeAliases);
 			const modeVars = {};
 			const modeVals = {};
+			const modeAliasDefs = {};
 			for (const [aliasDotKey, colorRef] of Object.entries(flatAliases)) {
 				if (typeof colorRef !== "string") continue;
 				const varName = `--color-${dotToDash(aliasDotKey)}`;
+				modeAliasDefs[aliasDotKey] = colorRef;
 				const rawValue = flatColors[colorRef];
 				modeVals[`colors.${aliasDotKey}`] = rawValue !== void 0 ? String(rawValue) : String(colorRef);
 				modeVars[varName] = rawValue !== void 0 ? String(rawValue) : String(colorRef);
 			}
 			modeVariables[modeName] = modeVars;
 			modeTokens[modeName] = modeVals;
+			modeAliasDefinitions[modeName] = modeAliasDefs;
 		}
 		const initialMode = theme.mode;
 		if (initialMode && modeVariables[initialMode]) {
@@ -842,10 +1199,239 @@ function flattenTheme(theme, emittedScales) {
 		variableMap,
 		variables,
 		modeVariables,
-		modeTokens
+		modeTokens,
+		tokenDefinitions,
+		modeAliasDefinitions
 	};
 }
 /**
+* Classify a RAW token value into its authored form (manifest v2, D6). MUST
+* run before `resolveTokenRefs` — resolution rewrites the string, and the
+* authored graph cannot be reconstructed from resolved CSS (D8). Uses
+* `matchAll` so the shared global {@link TOKEN_REF_RE} never carries a stale
+* `lastIndex` between callers.
+*/
+function parseTokenDefinition(rawValue) {
+	const references = [];
+	for (const match of rawValue.matchAll(TOKEN_REF_RE)) {
+		const ref = match[1];
+		const slashIdx = ref.indexOf("/");
+		references.push(slashIdx === -1 ? { path: ref } : {
+			path: ref.slice(0, slashIdx),
+			opacity: ref.slice(slashIdx + 1)
+		});
+	}
+	if (references.length === 0) return {
+		kind: "literal",
+		value: rawValue
+	};
+	return {
+		kind: "reference",
+		value: rawValue,
+		references
+	};
+}
+/**
+* Version of the CSS emitter that composed a manifest's fragments. Bump when
+* ANY emitted byte changes for the same authored input — composition (D8)
+* regenerates dirty sections "under the pinned emitter version", and this is
+* that pin.
+*/
+const EMITTER_VERSION = 1;
+/**
+* Sorted-key canonical form for hashing: object keys are emitted in sorted
+* order at every depth so the digest is independent of insertion order;
+* arrays keep authored order (reference order is contractual).
+*/
+function canonicalize(value) {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (isObject(value)) {
+		const record = value;
+		const sorted = {};
+		for (const key of Object.keys(record).sort()) sorted[key] = canonicalize(record[key]);
+		return sorted;
+	}
+	return value;
+}
+/**
+* sha256 hex digest. Primary path is `node:crypto` `createHash('sha256')`,
+* reached via `process.getBuiltinModule` so this module gains NO static
+* `node:crypto` import edge: built themes execute inside client bundles today
+* (e2e fixtures inline `createTheme(…).build()` at module init), and a static
+* builtin import is exactly what `./bootstrap` documents as forbidden in app
+* bundles. Non-Node runtimes use the pure fallback below, which produces
+* identical hex for identical input — determinism holds across environments.
+*/
+function sha256Hex(input) {
+	const nodeCrypto = globalThis.process?.getBuiltinModule?.("node:crypto");
+	if (nodeCrypto?.createHash) return nodeCrypto.createHash("sha256").update(input).digest("hex");
+	return sha256HexFallback(input);
+}
+/** SHA-256 round constants (FIPS 180-4 §4.2.2). */
+const SHA256_K = new Uint32Array([
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+]);
+function rotr(x, n) {
+	return (x >>> n | x << 32 - n) >>> 0;
+}
+/**
+* UTF-8 bytes of `input` without WHATWG `TextEncoder`: the Rust system-loader
+* evaluates the system bundle in QuickJS, which provides ES built-ins only —
+* no Node globals and no WHATWG APIs. Iterating by code point handles
+* surrogate pairs; lone surrogates cannot reach this path because the input
+* is well-formed `JSON.stringify` output (ES2019 escapes them as `\uXXXX`).
+*/
+function utf8Bytes(input) {
+	const bytes = [];
+	for (const char of input) {
+		const code = char.codePointAt(0);
+		if (code < 128) bytes.push(code);
+		else if (code < 2048) bytes.push(192 | code >> 6, 128 | code & 63);
+		else if (code < 65536) bytes.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
+		else bytes.push(240 | code >> 18, 128 | code >> 12 & 63, 128 | code >> 6 & 63, 128 | code & 63);
+	}
+	return new Uint8Array(bytes);
+}
+/**
+* Pure SHA-256 (FIPS 180-4) over the UTF-8 bytes of `input` — the non-Node
+* fallback for {@link sha256Hex}. Not a security surface: the contract hash
+* is a content digest for composition-identity comparison only.
+*/
+function sha256HexFallback(input) {
+	const bytes = utf8Bytes(input);
+	const bitLength = bytes.length * 8;
+	const paddedLength = (bytes.length + 8 >> 6) + 1 << 6 >>> 0;
+	const padded = new Uint8Array(paddedLength);
+	padded.set(bytes);
+	padded[bytes.length] = 128;
+	const view = new DataView(padded.buffer);
+	view.setUint32(paddedLength - 8, Math.floor(bitLength / 4294967296));
+	view.setUint32(paddedLength - 4, bitLength >>> 0);
+	const state = new Uint32Array([
+		1779033703,
+		3144134277,
+		1013904242,
+		2773480762,
+		1359893119,
+		2600822924,
+		528734635,
+		1541459225
+	]);
+	const w = new Uint32Array(64);
+	for (let offset = 0; offset < paddedLength; offset += 64) {
+		for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + i * 4);
+		for (let i = 16; i < 64; i++) {
+			const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ w[i - 15] >>> 3;
+			const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ w[i - 2] >>> 10;
+			w[i] = w[i - 16] + s0 + w[i - 7] + s1;
+		}
+		let a = state[0];
+		let b = state[1];
+		let c = state[2];
+		let d = state[3];
+		let e = state[4];
+		let f = state[5];
+		let g = state[6];
+		let h = state[7];
+		for (let i = 0; i < 64; i++) {
+			const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+			const ch = e & f ^ ~e & g;
+			const temp1 = h + S1 + ch + SHA256_K[i] + w[i] >>> 0;
+			const temp2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) >>> 0;
+			h = g;
+			g = f;
+			f = e;
+			e = d + temp1 >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = temp1 + temp2 >>> 0;
+		}
+		state[0] += a;
+		state[1] += b;
+		state[2] += c;
+		state[3] += d;
+		state[4] += e;
+		state[5] += f;
+		state[6] += g;
+		state[7] += h;
+	}
+	let hex = "";
+	for (const word of state) hex += word.toString(16).padStart(8, "0");
+	return hex;
+}
+/**
+* Stable digest over the canonical authored inputs. Identical authored input
+* ⇒ identical hash, across processes: keys sort at every depth and
+* `JSON.stringify` drops `undefined`-valued members deterministically.
+*/
+function computeContractHash(input) {
+	return sha256Hex(JSON.stringify(canonicalize(input)));
+}
+/**
 * Resolve token refs ({scale.key}) in all flattened token values.
 * Operates on the flattened tokenMap — does NOT mutate the nested theme.
 */
@@ -882,19 +1468,56 @@ function resolveTokenRefs(tokenMap, _variableMap, _emittedScales) {
 		if (resolved !== value) tokenMap[tokenPath] = resolved;
 	}
 }
+/**
+* Build `@property` registration rules for registered contextual vars.
+* The emitted custom property is `--${name}` — the same name the Rust resolver
+* maps a bare contextual var value to. Rules emit in declaration order and only
+* for names that are genuinely declared contextual vars. Returns `''` when no
+* registration metadata was supplied (opt-in / byte-identical guarantee).
+*/
+function buildPropertyRegistrationCss(contextualVars, registrations) {
+	if (registrations.size === 0) return "";
+	const declaredNames = /* @__PURE__ */ new Set();
+	for (const names of contextualVars.values()) for (const name of names) declaredNames.add(name);
+	const blocks = [];
+	for (const [name, registration] of registrations) {
+		if (!declaredNames.has(name)) continue;
+		const descriptors = [`syntax: "${registration.syntax}";`, `inherits: ${registration.inherits};`];
+		if (registration.initialValue !== void 0) descriptors.push(`initial-value: ${registration.initialValue};`);
+		blocks.push(`@property --${name} { ${descriptors.join(" ")} }`);
+	}
+	return blocks.join("\n");
+}
 /** Build CSS variable blocks from flattened data. */
-function buildVariableCss(rootVariables, breakpointVariables, modeVariables) {
+function buildVariableCss(rootVariables, breakpointVariables, modeVariables, systemEmission = {}) {
+	const { initialMode, systemPreference, browserColorScheme } = systemEmission;
 	const parts = [];
 	const rootLines = [];
 	for (const [varName, value] of Object.entries(rootVariables)) rootLines.push(`  ${varName}: ${value};`);
 	for (const [varName, value] of Object.entries(breakpointVariables)) rootLines.push(`  ${varName}: ${value};`);
+	if (browserColorScheme && initialMode) {
+		const initialScheme = browserColorScheme[initialMode];
+		if (initialScheme) rootLines.push(`  color-scheme: ${initialScheme};`);
+	}
 	if (rootLines.length > 0) parts.push(`:root {\n${rootLines.join("\n")}\n}`);
+	if (systemPreference) for (const scheme of ["light", "dark"]) {
+		const modeName = systemPreference[scheme];
+		const mediaLines = [];
+		const modeVars = modeVariables[modeName];
+		if (modeVars) for (const [varName, value] of Object.entries(modeVars)) mediaLines.push(`    ${varName}: ${value};`);
+		const mediaScheme = browserColorScheme?.[modeName];
+		if (mediaScheme) mediaLines.push(`    color-scheme: ${mediaScheme};`);
+		if (mediaLines.length === 0) continue;
+		parts.push(`@media (prefers-color-scheme: ${scheme}) {\n  :root:not([data-color-mode]) {\n${mediaLines.join("\n")}\n  }\n}`);
+	}
 	for (const [modeName, modeVars] of Object.entries(modeVariables)) {
 		const modeLines = [];
 		for (const [varName, value] of Object.entries(modeVars)) modeLines.push(`  ${varName}: ${value};`);
+		const modeScheme = browserColorScheme?.[modeName];
+		if (modeScheme) modeLines.push(`  color-scheme: ${modeScheme};`);
 		if (modeLines.length > 0) parts.push(`[data-color-mode="${modeName}"] {\n${modeLines.join("\n")}\n}`);
 	}
 	return parts.join("\n\n");
 }
 //#endregion
-export { Animus, AnimusExtended, AnimusExtendedWithAll, AnimusWithAll, BUILT_IN_SELECTORS, SystemBuilder, ThemeBuilder, borderShorthand, compose, createClassResolver, createComponent, createComposedFamily, createScale, createSystem, createTheme, createTransform, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, size, stringScale };
+export { Animus, AnimusExtended, AnimusExtendedWithAll, AnimusWithAll, BUILT_IN_CONDITIONS, BUILT_IN_SELECTORS, SystemBuilder, ThemeBuilder, borderShorthand, compose, createClassResolver, createComponent, createComposedFamily, createScale, createSystem, createTheme, createTransform, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, size, stringScale };