@animus-ui/system 0.1.0-next.9 → 0.1.0

package/dist/index.js

@@ -1,204 +1,18 @@
-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-Dge_rsuz.js";
-import { createElement, forwardRef, useRef } from "react";
-//#region src/runtime/index.ts
+import { n as createClassResolver, r as createComponent, t as createComposedFamily } from "./createComposedFamily-BsyI6rBc.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
 /**
-* CSS properties that accept unitless numeric values.
-* Bare numerics on properties NOT in this set receive `px`.
-* Matches @emotion/unitless and React DOM's style handling.
-*/
-const UNITLESS_PROPERTIES = new Set([
-	"animation-iteration-count",
-	"border-image-outset",
-	"border-image-slice",
-	"border-image-width",
-	"box-flex",
-	"box-flex-group",
-	"box-ordinal-group",
-	"column-count",
-	"columns",
-	"flex",
-	"flex-grow",
-	"flex-positive",
-	"flex-shrink",
-	"flex-negative",
-	"flex-order",
-	"font-weight",
-	"grid-area",
-	"grid-column",
-	"grid-column-end",
-	"grid-column-span",
-	"grid-column-start",
-	"grid-row",
-	"grid-row-end",
-	"grid-row-span",
-	"grid-row-start",
-	"line-clamp",
-	"line-height",
-	"opacity",
-	"order",
-	"orphans",
-	"tab-size",
-	"widows",
-	"z-index",
-	"zoom",
-	"fill-opacity",
-	"flood-opacity",
-	"stop-opacity",
-	"stroke-dasharray",
-	"stroke-dashoffset",
-	"stroke-miterlimit",
-	"stroke-opacity",
-	"stroke-width"
-]);
-/**
-* Apply unit fallback to a value for a given CSS property.
-* Unitless numeric values on properties that expect length units receive `px`.
-*/
-function applyUnitFallback(value, cssProperty) {
-	if (typeof value === "number") {
-		if (UNITLESS_PROPERTIES.has(cssProperty)) return String(value);
-		return `${value}px`;
-	}
-	return String(value);
-}
-/**
-* Serialize a system prop value to a lookup key matching the Rust
-* css_generator's serialize_value_key output format:
-* - Numbers and strings → their string representation
-* - Responsive objects → sorted "key:value" pairs joined by "|"
-*/
-function serializeValueKey(value) {
-	if (typeof value === "number" || typeof value === "string") return String(value);
-	if (typeof value === "object" && value !== null && !Array.isArray(value)) return Object.keys(value).sort().map((k) => `${k}:${value[k]}`).join("|");
-	return String(value);
-}
-/**
-* Resolve a dynamic prop value through scale lookup → transform → unit fallback.
-* Scale lookup uses pre-resolved values shipped from the extraction pipeline.
-*/
-function resolveValue(value, dc) {
-	const key = String(value);
-	const scaleResolved = dc.scaleValues?.[key];
-	if (scaleResolved != null) {
-		const transformed = dc.transform ? dc.transform(scaleResolved) : scaleResolved;
-		return String(transformed);
-	}
-	return applyUnitFallback(dc.transform ? dc.transform(value) : value, dc.varName);
-}
-/**
-* Create a lightweight component that applies extracted CSS class names.
-* Replaces Emotion's styled() for extracted components.
-*
-* The element parameter accepts either an HTML tag string (e.g. 'button') or
-* a React component reference (e.g. NextLink). When a component reference is
-* used, prop forwarding skips the HTML-attribute validity check — all
-* non-filtered props are forwarded to the component.
-*
-* The optional systemPropMap parameter provides the shared prop→value→className
-* lookup table, served as a virtual module by the Vite plugin.
-*
-* The optional dynamicPropConfig parameter provides CSS variable fallback
-* metadata for props with detected dynamic usage.
+* Deep merge utility — replaces lodash.merge for variant accumulation.
 */
-function createComponent(element, className, config, systemPropMap, dynamicPropConfig) {
-	const variantProps = config.variants ? Object.keys(config.variants) : [];
-	const stateProps = config.states || [];
-	const systemPropNames = config.systemPropNames || [];
-	const filterProps = new Set([
-		...variantProps,
-		...stateProps,
-		...systemPropNames
-	]);
-	const isComponentElement = typeof element !== "string";
-	const Component = forwardRef((props, ref) => {
-		const classes = [className];
-		const prevDynKey = useRef("");
-		const prevDynStyle = useRef(null);
-		if (config.variants) for (const [prop, vc] of Object.entries(config.variants)) {
-			const value = props[prop] ?? vc.default;
-			if (value != null) classes.push(`${className}--${prop}-${value}`);
-		}
-		if (config.states) {
-			for (const state of config.states) if (props[state]) classes.push(`${className}--${state}`);
-		}
-		let dynKeyParts;
-		let dynStyle;
-		if (systemPropNames.length > 0) {
-			const { customPropMap, customDynamicConfig } = config;
-			for (const propName of systemPropNames) {
-				if (!(propName in props)) continue;
-				const propValue = props[propName];
-				if (propValue == null) continue;
-				const key = serializeValueKey(propValue);
-				const cls = customPropMap?.[propName]?.[key] ?? systemPropMap?.[propName]?.[key];
-				if (cls) classes.push(cls);
-				else {
-					const dc = customDynamicConfig?.[propName] ?? dynamicPropConfig?.[propName];
-					if (dc) {
-						if (!dynKeyParts) dynKeyParts = [];
-						if (!dynStyle) dynStyle = {};
-						if (typeof propValue === "object" && propValue !== null && !Array.isArray(propValue)) for (const [bp, bpVal] of Object.entries(propValue)) {
-							if (bpVal == null) continue;
-							if (bp === "_") {
-								classes.push(dc.slotClass);
-								const finalVal = resolveValue(bpVal, dc);
-								dynStyle[dc.varName] = finalVal;
-								dynKeyParts.push(`${dc.varName}:${finalVal}`);
-							} else {
-								classes.push(`${dc.slotClass}-${bp}`);
-								const varName = `${dc.varName}-${bp}`;
-								const finalVal = resolveValue(bpVal, dc);
-								dynStyle[varName] = finalVal;
-								dynKeyParts.push(`${varName}:${finalVal}`);
-							}
-						}
-						else {
-							classes.push(dc.slotClass);
-							const finalVal = resolveValue(propValue, dc);
-							dynStyle[dc.varName] = finalVal;
-							dynKeyParts.push(`${dc.varName}:${finalVal}`);
-						}
-					}
-				}
-			}
-		}
-		if (props.className) classes.push(props.className);
-		const domProps = {
-			ref,
-			className: classes.join(" ")
-		};
-		for (const [key, value] of Object.entries(props)) {
-			if (key === "className") continue;
-			if (filterProps.has(key)) continue;
-			if (!isComponentElement) {}
-			domProps[key] = value;
-		}
-		if (dynKeyParts && dynStyle) {
-			const dynKey = dynKeyParts.join("|");
-			if (dynKey !== prevDynKey.current) {
-				prevDynKey.current = dynKey;
-				prevDynStyle.current = dynStyle;
-			}
-			domProps.style = props.style ? {
-				...props.style,
-				...prevDynStyle.current
-			} : prevDynStyle.current;
-		}
-		return createElement(element, domProps);
-	});
-	Component.displayName = className;
-	return Object.assign(Component, { extend: () => {
-		throw new Error(`Cannot extend extracted component "${className}" at runtime. Extensions must be authored in source code using the builder API (e.g. import the original component and call .extend() there) so the extraction pipeline can resolve them at build time.`);
-	} });
-}
-//#endregion
-//#region src/AnimusExtended.ts
-function deepMerge$1(target, source) {
+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$1(target[key], source[key]);
+	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]);
 	else result[key] = source[key];
 	return result;
 }
+//#endregion
+//#region src/AnimusExtended.ts
 var AnimusExtendedWithAll = class {
 	propRegistry = {};
 	groupRegistry = {};
@@ -207,7 +21,8 @@ var AnimusExtendedWithAll = class {
 	variants = {};
 	activeGroups = {};
 	custom = {};
-	constructor(props, groups, base, variants, states, activeGroups, custom) {
+	compounds = [];
+	constructor(props, groups, base, variants, states, activeGroups, custom, compounds = []) {
 		this.propRegistry = props;
 		this.groupRegistry = groups;
 		this.baseStyles = base;
@@ -215,9 +30,10 @@ var AnimusExtendedWithAll = class {
 		this.statesConfig = states;
 		this.activeGroups = activeGroups;
 		this.custom = custom;
+		this.compounds = compounds;
 	}
 	extend() {
-		return new AnimusExtended(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom);
+		return new AnimusExtended(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 	asElement(component) {
 		const Component = createComponent(component, "", this._buildComponentConfig());
@@ -229,8 +45,8 @@ var AnimusExtendedWithAll = class {
 		const extendFn = this.extend.bind(this);
 		return Object.assign(Component, { extend: extendFn });
 	}
-	build() {
-		return Object.assign((() => ({})), { extend: this.extend.bind(this) });
+	asClass() {
+		return createClassResolver("", this._buildComponentConfig());
 	}
 	_buildComponentConfig() {
 		const variantConfig = {};
@@ -252,45 +68,50 @@ var AnimusExtendedWithAll = class {
 };
 var AnimusExtendedWithSystem = class extends AnimusExtendedWithAll {
 	props(config) {
-		return new AnimusExtendedWithAll(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, deepMerge$1({}, config));
+		return new AnimusExtendedWithAll(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, deepMerge({}, config), this.compounds);
 	}
 };
 var AnimusExtendedWithStates = class extends AnimusExtendedWithSystem {
-	groups(config) {
-		return new AnimusExtendedWithSystem(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, deepMerge$1(this.activeGroups, config), this.custom);
+	system(config) {
+		return new AnimusExtendedWithSystem(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, deepMerge(this.activeGroups, config), this.custom, this.compounds);
 	}
 };
-var AnimusExtendedWithVariants = class AnimusExtendedWithVariants extends AnimusExtendedWithStates {
-	variant(options) {
-		const prop = options.prop || "variant";
-		return new AnimusExtendedWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge$1(this.variants, { [prop]: options }), this.statesConfig, this.activeGroups, this.custom);
+var AnimusExtendedWithCompounds = class AnimusExtendedWithCompounds extends AnimusExtendedWithStates {
+	compound(condition, styles) {
+		return new AnimusExtendedWithCompounds(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom, [...this.compounds, {
+			condition,
+			styles
+		}]);
 	}
 	states(config) {
-		return new AnimusExtendedWithStates(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, deepMerge$1(this.statesConfig, config), this.activeGroups, this.custom);
+		return new AnimusExtendedWithStates(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, deepMerge(this.statesConfig, config), this.activeGroups, this.custom, this.compounds);
+	}
+};
+var AnimusExtendedWithVariants = class AnimusExtendedWithVariants extends AnimusExtendedWithCompounds {
+	compound(condition, styles) {
+		return new AnimusExtendedWithCompounds(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom, [...this.compounds, {
+			condition,
+			styles
+		}]);
+	}
+	variant(options) {
+		const prop = options.prop || "variant";
+		return new AnimusExtendedWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge(this.variants, { [prop]: options }), this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 };
 var AnimusExtendedWithBase = class extends AnimusExtendedWithVariants {
 	variant(options) {
 		const prop = options.prop || "variant";
-		return new AnimusExtendedWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge$1(this.variants, { [prop]: options }), this.statesConfig, this.activeGroups, this.custom);
+		return new AnimusExtendedWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge(this.variants, { [prop]: options }), this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 };
 var AnimusExtended = class extends AnimusExtendedWithBase {
 	styles(config) {
-		return new AnimusExtendedWithBase(this.propRegistry, this.groupRegistry, deepMerge$1(this.baseStyles, config), this.variants, this.statesConfig, this.activeGroups, this.custom);
+		return new AnimusExtendedWithBase(this.propRegistry, this.groupRegistry, deepMerge(this.baseStyles, config), this.variants, this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 };
 //#endregion
 //#region src/Animus.ts
-/**
-* Deep merge utility — replaces lodash.merge for variant accumulation.
-*/
-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]);
-	else result[key] = source[key];
-	return result;
-}
 var AnimusWithAll = class {
 	propRegistry = {};
 	groupRegistry = {};
@@ -299,7 +120,8 @@ var AnimusWithAll = class {
 	variants = {};
 	activeGroups = {};
 	custom = {};
-	constructor(props, groups, base, variants, states, activeGroups, custom) {
+	compounds = [];
+	constructor(props, groups, base, variants, states, activeGroups, custom, compounds = []) {
 		this.propRegistry = props;
 		this.groupRegistry = groups;
 		this.baseStyles = base;
@@ -307,9 +129,10 @@ var AnimusWithAll = class {
 		this.statesConfig = states;
 		this.activeGroups = activeGroups;
 		this.custom = custom;
+		this.compounds = compounds;
 	}
 	extend() {
-		return new AnimusExtended(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom);
+		return new AnimusExtended(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 	asElement(component) {
 		const Component = createComponent(component, "", this._buildComponentConfig());
@@ -321,8 +144,8 @@ var AnimusWithAll = class {
 		const extendFn = this.extend.bind(this);
 		return Object.assign(Component, { extend: extendFn });
 	}
-	build() {
-		return Object.assign((() => ({})), { extend: this.extend.bind(this) });
+	asClass() {
+		return createClassResolver("", this._buildComponentConfig());
 	}
 	_buildComponentConfig() {
 		const variantConfig = {};
@@ -343,31 +166,48 @@ var AnimusWithAll = class {
 	}
 };
 var AnimusWithSystem = class extends AnimusWithAll {
-	constructor(props, groups, base, variants, states, activeGroups) {
-		super(props, groups, base, variants, states, activeGroups, {});
+	constructor(props, groups, base, variants, states, activeGroups, compounds = []) {
+		super(props, groups, base, variants, states, activeGroups, {}, compounds);
 	}
 	props(config) {
-		return new AnimusWithAll(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, config);
+		return new AnimusWithAll(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, config, this.compounds);
 	}
 };
 var AnimusWithStates = class extends AnimusWithSystem {
-	constructor(props, groups, base, variants, states) {
-		super(props, groups, base, variants, states, {});
+	constructor(props, groups, base, variants, states, compounds = []) {
+		super(props, groups, base, variants, states, {}, compounds);
 	}
-	groups(config) {
-		return new AnimusWithSystem(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, config);
+	system(config) {
+		return new AnimusWithSystem(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, config, this.compounds);
 	}
 };
-var AnimusWithVariants = class AnimusWithVariants extends AnimusWithStates {
-	constructor(props, groups, base, variants) {
-		super(props, groups, base, variants, {});
+var AnimusWithCompounds = class AnimusWithCompounds extends AnimusWithStates {
+	constructor(props, groups, base, variants, compounds = []) {
+		super(props, groups, base, variants, {}, compounds);
+	}
+	compound(condition, styles) {
+		return new AnimusWithCompounds(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, [...this.compounds, {
+			condition,
+			styles
+		}]);
 	}
 	states(config) {
-		return new AnimusWithStates(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, config);
+		return new AnimusWithStates(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, config, this.compounds);
+	}
+};
+var AnimusWithVariants = class AnimusWithVariants extends AnimusWithCompounds {
+	constructor(props, groups, base, variants, compounds = []) {
+		super(props, groups, base, variants, compounds);
+	}
+	compound(condition, styles) {
+		return new AnimusWithCompounds(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, [...this.compounds, {
+			condition,
+			styles
+		}]);
 	}
 	variant(options) {
 		const prop = options.prop || "variant";
-		return new AnimusWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge(this.variants, { [prop]: options }));
+		return new AnimusWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge(this.variants, { [prop]: options }), this.compounds);
 	}
 };
 var AnimusWithBase = class extends AnimusWithVariants {
@@ -376,7 +216,7 @@ var AnimusWithBase = class extends AnimusWithVariants {
 	}
 	variant(options) {
 		const prop = options.prop || "variant";
-		return new AnimusWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge(this.variants, { [prop]: options }));
+		return new AnimusWithVariants(this.propRegistry, this.groupRegistry, this.baseStyles, deepMerge(this.variants, { [prop]: options }), this.compounds);
 	}
 };
 var Animus = class extends AnimusWithBase {
@@ -388,64 +228,275 @@ var Animus = class extends AnimusWithBase {
 	}
 };
 //#endregion
-//#region src/PropertyBuilder.ts
-var PropertyBuilder = class PropertyBuilder {
-	#props;
-	#groups;
-	constructor(props, groups) {
-		this.#props = props || {};
-		this.#groups = groups || {};
+//#region src/keyframes.ts
+const fnv1a = (input) => {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)) >>> 0;
+	}
+	return hash.toString(36);
+};
+const serializeFrames = (frames) => {
+	return Object.keys(frames).sort().map((stop) => {
+		const frame = frames[stop] ?? {};
+		return `${stop}{${Object.keys(frame).sort().map((p) => `${p}:${String(frame[p])}`).join(";")}}`;
+	}).join("|");
+};
+const generateName = (frames) => `animus-kf-${fnv1a(serializeFrames(frames))}`;
+const createRef = (name, resolvedName) => ({
+	__brand: "KeyframeRef",
+	__name: name,
+	toString() {
+		return resolvedName;
+	},
+	valueOf() {
+		return resolvedName;
+	}
+});
+function keyframes(map) {
+	const frameData = {};
+	const refs = {};
+	for (const key of Object.keys(map)) {
+		const frames = map[key];
+		const resolvedName = generateName(frames);
+		frameData[key] = {
+			name: resolvedName,
+			frames
+		};
+		refs[key] = createRef(key, resolvedName);
 	}
-	addGroup(name, config) {
-		const newGroup = { [name]: Object.keys(config) };
-		return new PropertyBuilder({
-			...this.#props,
-			...config
-		}, {
-			...this.#groups,
-			...newGroup
-		});
+	return {
+		__brand: "Keyframes",
+		__frames: frameData,
+		...refs
+	};
+}
+//#endregion
+//#region src/selectors.ts
+/**
+* Built-in selector aliases.
+*
+* Compound selectors (e.g. `_disabled`) target multiple CSS selectors
+* via comma-separation to cover native, ARIA, and data attribute conventions.
+*/
+const BUILT_IN_SELECTORS = {
+	_link: {
+		selector: "&:link",
+		order: 10
+	},
+	_visited: {
+		selector: "&:visited",
+		order: 20
+	},
+	_hover: {
+		selector: "&:hover",
+		order: 30
+	},
+	_focusWithin: {
+		selector: "&:focus-within",
+		order: 40
+	},
+	_focus: {
+		selector: "&:focus",
+		order: 50
+	},
+	_focusVisible: {
+		selector: "&:focus-visible",
+		order: 60
+	},
+	_active: {
+		selector: "&:active",
+		order: 70
+	},
+	_target: {
+		selector: "&:target",
+		order: 80
+	},
+	_checked: {
+		selector: "&:checked, &[aria-checked=\"true\"], &[data-checked]",
+		order: 100
+	},
+	_invalid: {
+		selector: "&:invalid, &[aria-invalid=\"true\"], &[data-invalid]",
+		order: 110
+	},
+	_required: {
+		selector: "&:required, &[aria-required=\"true\"]",
+		order: 120
+	},
+	_readOnly: {
+		selector: "&:read-only, &[aria-readonly=\"true\"], &[data-readonly]",
+		order: 130
+	},
+	_expanded: {
+		selector: "&[aria-expanded=\"true\"], &[data-expanded]",
+		order: 140
+	},
+	_selected: {
+		selector: "&[aria-selected=\"true\"], &[data-selected]",
+		order: 150
+	},
+	_pressed: {
+		selector: "&[aria-pressed=\"true\"], &[data-pressed]",
+		order: 160
+	},
+	_disabled: {
+		selector: "&:disabled, &[disabled], &[aria-disabled=\"true\"], &[data-disabled]",
+		order: 200
+	},
+	_before: {
+		selector: "&::before",
+		order: 300
+	},
+	_after: {
+		selector: "&::after",
+		order: 310
+	},
+	_placeholder: {
+		selector: "&::placeholder",
+		order: 320
+	},
+	_selection: {
+		selector: "&::selection",
+		order: 330
+	},
+	_first: {
+		selector: "&:first-child",
+		order: 400
+	},
+	_last: {
+		selector: "&:last-child",
+		order: 410
+	},
+	_even: {
+		selector: "&:nth-child(even)",
+		order: 420
+	},
+	_odd: {
+		selector: "&:nth-child(odd)",
+		order: 430
+	},
+	_empty: {
+		selector: "&:empty",
+		order: 440
 	}
-	build() {
-		return {
-			propRegistry: this.#props,
-			groupRegistry: this.#groups
+};
+/**
+* Merge user-provided selectors with built-in defaults.
+* User selectors override built-in aliases of the same name.
+* New aliases get an order value based on their position (500+).
+*/
+function mergeSelectors(base, custom) {
+	const merged = { ...base };
+	let nextOrder = 500;
+	for (const [key, selector] of Object.entries(custom)) if (key in merged) merged[key] = {
+		selector,
+		order: merged[key].order
+	};
+	else {
+		merged[key] = {
+			selector,
+			order: nextOrder
 		};
+		nextOrder += 10;
 	}
-};
+	return merged;
+}
+/** Get the sorted alias keys for deterministic cascade ordering. */
+function getSortedAliasKeys(map) {
+	return Object.keys(map).sort((a, b) => map[a].order - map[b].order);
+}
+/**
+* Serialize the selector map for the extraction pipeline.
+* Emits a flat `Record<string, string>` (alias → selector) plus
+* the ordered key list for cascade determinism.
+*/
+function serializeSelectorMap(map) {
+	const selectors = {};
+	const order = getSortedAliasKeys(map);
+	for (const key of order) selectors[key] = map[key].selector;
+	return {
+		selectors,
+		order
+	};
+}
 //#endregion
 //#region src/SystemBuilder.ts
 var SystemBuilder = class SystemBuilder {
 	#propRegistry;
 	#groupRegistry;
-	#globalStyles;
-	constructor(propRegistry, groupRegistry, globalStyles) {
+	#selectorRegistry;
+	#includesRegistry;
+	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry) {
 		this.#propRegistry = propRegistry || {};
 		this.#groupRegistry = groupRegistry || {};
-		this.#globalStyles = globalStyles;
+		this.#selectorRegistry = selectorRegistry || { ...BUILT_IN_SELECTORS };
+		this.#includesRegistry = includesRegistry || [];
 	}
-	withProperties(cb) {
-		const result = cb(new PropertyBuilder());
-		return new SystemBuilder(result.propRegistry, result.groupRegistry, this.#globalStyles);
+	addSelectors(selectors) {
+		const merged = mergeSelectors(this.#selectorRegistry, selectors);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry);
 	}
-	withGlobalStyles(styles) {
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, styles);
+	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)}".`);
+		}
+		const nextProps = {
+			...this.#propRegistry,
+			...config
+		};
+		const newGroup = { [name]: Object.keys(config) };
+		return new SystemBuilder(nextProps, {
+			...this.#groupRegistry,
+			...newGroup
+		}, this.#selectorRegistry, this.#includesRegistry);
+	}
+	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.`);
+		}
+		return new SystemBuilder({
+			...this.#propRegistry,
+			...config
+		}, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry);
 	}
 	build() {
 		const animus = new Animus(this.#propRegistry, this.#groupRegistry);
-		const globalStyles = this.#globalStyles;
-		return Object.assign(animus, { serialize: () => {
-			return serializeInstance(this.#propRegistry, this.#groupRegistry, globalStyles);
+		const propRegistry = this.#propRegistry;
+		const groupRegistry = this.#groupRegistry;
+		const selectorRegistry = this.#selectorRegistry;
+		const system = Object.assign(animus, { toConfig: () => {
+			return serializeInstance(propRegistry, groupRegistry, selectorRegistry);
 		} });
+		const createGlobalStyles = ((styles) => ({
+			__brand: "GlobalStyleBlock",
+			styles
+		}));
+		const createKeyframes = ((frames) => keyframes(frames));
+		return {
+			system,
+			createGlobalStyles,
+			createKeyframes
+		};
 	}
 };
-function serializeInstance(propRegistry, groupRegistry, globalStyles) {
+function serializeInstance(propRegistry, groupRegistry, selectorRegistry) {
 	const serialized = {};
 	const transforms = {};
 	for (const [propName, entry] of Object.entries(propRegistry)) {
 		const s = { property: entry.property };
 		if (entry.properties && entry.properties.length > 0) s.properties = [...entry.properties];
-		if (typeof entry.scale === "string") s.scale = entry.scale;
+		const scale = entry.scale;
+		if (typeof scale === "string") s.scale = scale;
+		else if (scale && typeof scale === "object") s.scale = scale;
+		if (entry.negative) s.negative = true;
 		if (entry.transform) {
 			const fn = entry.transform;
 			const name = fn.transformName ?? fn.name;
@@ -454,18 +505,20 @@ function serializeInstance(propRegistry, groupRegistry, globalStyles) {
 				transforms[name] = fn;
 			}
 		}
+		if (entry.currentVar) s.currentVar = entry.currentVar;
 		serialized[propName] = s;
 	}
-	const result = {
+	const { selectors, order } = serializeSelectorMap(selectorRegistry);
+	return {
 		propConfig: JSON.stringify(serialized),
 		groupRegistry: JSON.stringify(groupRegistry),
-		transforms
+		transforms,
+		selectorAliases: JSON.stringify(selectors),
+		selectorOrder: JSON.stringify(order)
 	};
-	if (globalStyles) result.globalStyles = globalStyles;
-	return result;
 }
-function createSystem() {
-	return new SystemBuilder();
+function createSystem(config) {
+	return new SystemBuilder(void 0, void 0, void 0, config?.includes ?? []);
 }
 //#endregion
 //#region src/theme/utils.ts
@@ -485,146 +538,364 @@ function merge(target, ...sources) {
 	}
 	return target;
 }
-function mapValues(obj, fn) {
+/**
+* Resolve a dot-path string against a nested object.
+* walkDotPath({ gray: { 50: '#fafafa' } }, 'gray.50') → '#fafafa'
+* The `_` identity key is handled: 'primary' resolves to obj.primary._ if obj.primary is an object with _.
+*/
+function walkDotPath(obj, path) {
+	const parts = path.split(".");
+	let current = obj;
+	for (const part of parts) {
+		if (!isObject(current)) return void 0;
+		current = current[part];
+	}
+	return current;
+}
+/**
+* Flatten a nested object into a flat Record with dot-path keys.
+* The `_` key is an identity marker — it produces the parent key without suffix.
+* { gray: { 50: '#fafafa' } } → { 'gray.50': '#fafafa' }
+* { primary: { _: 'ember', hover: 'x' } } → { 'primary': 'ember', 'primary.hover': 'x' }
+* CSS variable names use dash-join, computed at the serialization boundary (not here).
+*/
+function flattenToDotPaths(object, path) {
 	const result = {};
-	for (const key of Object.keys(obj)) result[key] = fn(obj[key], key, obj);
+	for (const key of Object.keys(object)) {
+		const nextKey = path ? key === "_" ? path : `${path}.${key}` : key;
+		const current = object[key];
+		if (isObject(current)) Object.assign(result, flattenToDotPaths(current, nextKey));
+		else result[nextKey] = current;
+	}
 	return result;
 }
-//#endregion
-//#region src/theme/flattenScale.ts
-function flattenScale(object, path) {
-	return Object.keys(object).reduce((carry, key) => {
-		const nextKey = path ? `${path}${key === "_" ? "" : `-${key}`}` : key;
-		const current = object[key];
-		if (isObject(current)) return {
-			...carry,
-			...flattenScale(current, nextKey)
-		};
-		return {
-			...carry,
-			[nextKey]: object[key]
-		};
-	}, {});
+/**
+* Convert a dot-path key to a dash-join key for CSS variable naming.
+* 'gray.50' → 'gray-50'
+* 'primary.hover' → 'primary-hover'
+*/
+function dotToDash(dotPath) {
+	return dotPath.replace(/\./g, "-");
 }
+/** Map over object values — matches lodash.mapValues overload signatures */
 //#endregion
-//#region src/theme/serializeTokens.ts
-const templateBreakpoints = (value, alias, theme) => {
-	if (isObject(value)) {
-		const { _, ...rest } = value;
-		const css = { [alias]: _ };
-		if (theme) {
-			const breakpoints = theme.breakpoints;
-			Object.keys(breakpoints).forEach((key) => {
-				if (rest[key]) css[breakpoints[key]] = { [alias]: rest[key] };
-			});
-		}
-		return css;
+//#region src/theme/createTheme.ts
+const COLOR_FUNCTION_PREFIXES = [
+	"rgb(",
+	"rgba(",
+	"hsl(",
+	"hsla(",
+	"oklch(",
+	"oklab(",
+	"lch(",
+	"lab(",
+	"color(",
+	"color-mix("
+];
+/** Validate that a value is a valid CSS <color>. */
+function isValidCSSColor(value) {
+	if (typeof value !== "string") return false;
+	const v = value.trim();
+	if (v === "") return false;
+	if (v === "transparent" || v === "currentColor" || v === "currentcolor") return true;
+	if (v.startsWith("#") && /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v)) return true;
+	for (const prefix of COLOR_FUNCTION_PREFIXES) if (v.startsWith(prefix) && v.endsWith(")")) return true;
+	if (/^[a-zA-Z]+$/.test(v)) return true;
+	return false;
+}
+/**
+* Validate that mode aliases reference existing color keys via dot-path traversal.
+* Aliases are dot-path strings like 'gray.50' that must resolve in the nested color structure.
+*/
+function validateModeAliases(modeName, aliases, nestedColors, flatColorKeys, prefix) {
+	for (const [key, value] of Object.entries(aliases)) {
+		const aliasPath = prefix ? `${prefix}.${key}` : key;
+		if (key === "_") {
+			if (typeof value === "string") {
+				if (walkDotPath(nestedColors, value) === void 0) throw new Error(`addColorModes: mode '${modeName}' references unknown color '${value}' for alias '${prefix || key}'. Available colors: ${flatColorKeys.slice(0, 10).join(", ")}${flatColorKeys.length > 10 ? ", ..." : ""}`);
+			} else if (isObject(value)) validateModeAliases(modeName, value, nestedColors, flatColorKeys, prefix);
+		} else if (typeof value === "string") {
+			if (walkDotPath(nestedColors, value) === void 0) throw new Error(`addColorModes: mode '${modeName}' references unknown color '${value}' for alias '${aliasPath}'. Available colors: ${flatColorKeys.slice(0, 10).join(", ")}${flatColorKeys.length > 10 ? ", ..." : ""}`);
+		} else if (isObject(value)) validateModeAliases(modeName, value, nestedColors, flatColorKeys, aliasPath);
 	}
-	return { [alias]: value };
-};
-const serializeTokens = (tokens, prefix, theme) => {
-	const tokenReferences = {};
-	const tokenVariables = {};
-	Object.keys(tokens).forEach((key) => {
-		const varName = `--${prefix}-${key.replace("$", "")}`;
-		tokenReferences[key] = `var(${varName})`;
-		merge(tokenVariables, templateBreakpoints(tokens[key], varName, theme));
-	});
+}
+/** Validate all color entries, throwing on invalid values. */
+function validateColors(colors) {
+	for (const [key, value] of Object.entries(colors)) if (isObject(value)) validateColors(value);
+	else if (!isValidCSSColor(value)) throw new Error(`addColors: '${String(value)}' is not a valid CSS <color> value for key '${key}'. Expected hex (#fff), rgb(), hsl(), oklch(), named color, transparent, or currentColor.`);
+}
+function createState(theme) {
 	return {
-		tokens: tokenReferences,
-		variables: tokenVariables
+		theme: theme || { breakpoints: {} },
+		emittedScales: /* @__PURE__ */ new Set(),
+		contextualVars: /* @__PURE__ */ new Map()
 	};
-};
-//#endregion
-//#region src/theme/createTheme.ts
-var ThemeBuilder = class {
-	#theme = {};
-	constructor(baseTheme) {
-		this.#theme = baseTheme;
-	}
-	/**
-	*
-	* @param key A key of the current theme to transform into CSS Variables and Variable References
-	* @example .createScaleVariables('fontSize')
-	*/
-	createScaleVariables(key) {
-		const { variables, tokens } = serializeTokens(this.#theme[key], key, this.#theme);
-		this.#theme = merge({}, this.#theme, {
-			[key]: tokens,
-			_variables: { [key]: variables },
-			_tokens: { [key]: this.#theme[key] }
-		});
-		return this;
+}
+function copyState(state, nextTheme) {
+	const next = {
+		theme: nextTheme,
+		emittedScales: new Set(state.emittedScales),
+		contextualVars: /* @__PURE__ */ new Map()
+	};
+	for (const [scale, vars] of state.contextualVars) next.contextualVars.set(scale, [...vars]);
+	return next;
+}
+/**
+* ThemeScales — the final phase. Has addScale, extendScale, declareContextualVars, build.
+* Also allows addColors and addColorModes for augmentation.
+*/
+var ThemeBuilder = class ThemeBuilder {
+	/** @internal */ _state;
+	constructor(state) {
+		this._state = state;
+	}
+	addBreakpoints(breakpoints) {
+		for (const [key, value] of Object.entries(breakpoints)) if (typeof value !== "number" || value < 0) throw new Error(`addBreakpoints: breakpoint '${key}' must be a non-negative number, got ${JSON.stringify(value)}`);
+		const nextTheme = merge({}, this._state.theme, { breakpoints });
+		return new ThemeBuilder(copyState(this._state, nextTheme));
+	}
+	from(builtTheme) {
+		const raw = {};
+		for (const key of Object.keys(builtTheme)) {
+			const val = builtTheme[key];
+			if (typeof val !== "function") raw[key] = val;
+		}
+		const nextTheme = merge({}, this._state.theme, raw);
+		const next = new ThemeBuilder(copyState(this._state, nextTheme));
+		const manifest = builtTheme.manifest;
+		if (manifest?.variableMap) for (const tokenPath of Object.keys(manifest.variableMap)) {
+			const scale = tokenPath.split(".")[0];
+			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]);
+		return next;
 	}
-	/**
-	*
-	* @param colors A map of color tokens to add to the theme. These tokens are immediately converted to CSS Variables `--color-${key}`.
-	* @example .addColors({ navy: 'navy', hyper: 'purple' })
-	*/
 	addColors(colors) {
-		const flatColors = flattenScale(colors);
-		const { variables, tokens } = serializeTokens(flatColors, "color", this.#theme);
-		this.#theme = merge({}, this.#theme, {
-			colors: tokens,
-			_variables: { root: variables },
-			_tokens: { colors: flatColors }
-		});
-		return this;
+		validateColors(colors);
+		const nextTheme = merge({}, this._state.theme, { colors });
+		const next = new ThemeBuilder(copyState(this._state, nextTheme));
+		next._state.emittedScales.add("colors");
+		return next;
 	}
-	/**
-	*
-	* @param initialMode A key of the object passed for modes.  This sets the default state for the theme and transforms the correct variables.
-	* @param modes A map of color modes with keys of each possible mode with a value of alias to color keys.  This must be called after `addColors`
-	* @example .addColorModes('light', { light: { primary: 'hyper' }, { dark: { primary: 'navy' } } })
-	*/
 	addColorModes(initialMode, modeConfig) {
-		const modes = mapValues(modeConfig, (mode) => flattenScale(mode));
-		const { tokens: colors, variables } = serializeTokens(mapValues(merge({}, this.#theme.modes?.[initialMode], modes[initialMode]), (color) => this.#theme.colors[color]), "color", this.#theme);
-		const getColorValue = (color) => this.#theme._tokens?.colors?.[color];
-		this.#theme = merge({}, this.#theme, {
-			colors,
-			modes,
-			mode: initialMode,
-			_getColorValue: getColorValue,
-			_variables: { mode: variables },
-			_tokens: { modes: mapValues(modes, (mode) => mapValues(mode, getColorValue)) }
+		const nestedColors = this._state.theme.colors || {};
+		const flatColors = flattenToDotPaths(nestedColors);
+		const flatColorKeys = Object.keys(flatColors);
+		for (const [modeName, modeAliases] of Object.entries(modeConfig)) validateModeAliases(modeName, modeAliases, nestedColors, flatColorKeys, "");
+		const nextTheme = merge({}, this._state.theme, {
+			modes: modeConfig,
+			mode: initialMode
 		});
-		return this;
-	}
-	/**
-	*
-	* @param key A new key of theme
-	* @param createScale A function that accepts the current theme and returns a new object of scale values.
-	* @example .addScale('fonts', () => ({ basic: 'Gotham', cool: 'Wingdings' }))
-	*/
-	addScale(key, createScale) {
-		this.#theme = merge({}, this.#theme, { [key]: flattenScale(createScale(this.#theme)) });
-		return this;
+		return new ThemeBuilder(copyState(this._state, nextTheme));
+	}
+	addScale(config) {
+		const { name, values, emit } = config;
+		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) {
+		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]);
+		}
+		return next;
 	}
-	/**
-	*
-	* @param key A current key of theme to be updated with new or computed values
-	* @param updateFn A function that accepts an argument of the current values at the specified keys an returns a map of new values to merge.
-	* @example .updateScale('fonts', ({ basic }) => ({ basicFallback: `{basic}, Montserrat` }))
-	*/
-	updateScale(key, updateFn) {
-		this.#theme = merge({}, this.#theme, { [key]: updateFn(this.#theme[key]) });
-		return this;
+	extendScale(key, updateFn) {
+		const nextTheme = merge({}, this._state.theme, { [key]: updateFn(this._state.theme[key]) });
+		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
 	/**
-	* This finalizes the theme build and returns the final theme and variables to be provided.
-	* Simplify flattens the deeply nested MergeTheme chain into a shallow object type.
+	* Finalize the theme build.
+	* Flattens nested data at the boundary — produces manifest and serialize().
 	*/
 	build() {
-		const { variables } = serializeTokens(mapValues(this.#theme.breakpoints, (val) => `${val}px`), "breakpoint", this.#theme);
-		return merge({}, this.#theme, {
-			_variables: { breakpoints: variables },
-			_tokens: {}
+		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);
+		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`;
+		let contextualVarsSerialized;
+		if (contextualVars.size > 0) {
+			contextualVarsSerialized = {};
+			for (const [scale, vars] of contextualVars) contextualVarsSerialized[scale] = vars;
+		}
+		const variableCss = buildVariableCss(variables, bpVariables, modeVariables);
+		const manifest = {
+			tokenMap: {
+				...tokenMap,
+				...Object.fromEntries(Object.entries(theme.breakpoints || {}).map(([k, v]) => [`breakpoints.${k}`, String(v)]))
+			},
+			variableMap,
+			modes: modeTokens,
+			variableCss,
+			...contextualVarsSerialized ? { contextualVars: contextualVarsSerialized } : {}
+		};
+		Object.defineProperty(theme, "manifest", {
+			value: manifest,
+			enumerable: false,
+			configurable: false,
+			writable: false
+		});
+		Object.defineProperty(theme, "serialize", {
+			value: () => ({
+				scalesJson: JSON.stringify(manifest.tokenMap),
+				variableMapJson: JSON.stringify(manifest.variableMap),
+				variableCss: manifest.variableCss,
+				contextualVarsJson: JSON.stringify(manifest.contextualVars ?? {})
+			}),
+			enumerable: false,
+			configurable: false,
+			writable: false
 		});
+		Object.defineProperty(theme, "varRef", {
+			value: (tokenPath) => {
+				const varName = variableMap[tokenPath];
+				if (varName) return `var(${varName})`;
+				const dotIdx = tokenPath.indexOf(".");
+				if (dotIdx === -1) return void 0;
+				const scale = tokenPath.slice(0, dotIdx);
+				const key = tokenPath.slice(dotIdx + 1);
+				const scaleObj = theme[scale];
+				if (!isObject(scaleObj)) return void 0;
+				const val = walkDotPath(scaleObj, key);
+				return val !== void 0 ? String(val) : void 0;
+			},
+			enumerable: false,
+			configurable: false,
+			writable: false
+		});
+		return theme;
 	}
 };
-function createTheme(base) {
-	return new ThemeBuilder(base);
+function createTheme() {
+	return new ThemeBuilder(createState());
+}
+/** Token ref pattern: {scale.key} or {scale.key.sub} */
+const TOKEN_REF_RE = /\{([^}]+)\}/g;
+/**
+* Flatten the nested theme into dot-path keyed token map and CSS variable declarations.
+* This is the ONLY place where flattening happens.
+*/
+function flattenTheme(theme, emittedScales) {
+	const tokenMap = {};
+	const variableMap = {};
+	const variables = {};
+	const modeVariables = {};
+	const modeTokens = {};
+	for (const [scaleName, scaleValue] of Object.entries(theme)) {
+		if (scaleName.startsWith("_")) continue;
+		if (scaleName === "breakpoints" || scaleName === "mode" || scaleName === "modes") continue;
+		if (typeof scaleValue === "function") continue;
+		if (!isObject(scaleValue)) continue;
+		const flat = flattenToDotPaths(scaleValue);
+		const isEmitted = emittedScales.has(scaleName);
+		for (const [dotKey, rawValue] of Object.entries(flat)) {
+			const tokenPath = `${scaleName}.${dotKey}`;
+			const dashKey = dotToDash(dotKey);
+			const varName = `--${scaleName === "colors" ? "color" : scaleName}-${dashKey}`;
+			if (isEmitted) {
+				tokenMap[tokenPath] = `var(${varName})`;
+				variableMap[tokenPath] = varName;
+				variables[varName] = String(rawValue);
+			} else tokenMap[tokenPath] = String(rawValue);
+		}
+	}
+	if (theme.modes && isObject(theme.modes) && theme.colors && isObject(theme.colors)) {
+		const flatColors = flattenToDotPaths(theme.colors);
+		for (const [modeName, modeAliases] of Object.entries(theme.modes)) {
+			if (!isObject(modeAliases)) continue;
+			const flatAliases = flattenToDotPaths(modeAliases);
+			const modeVars = {};
+			const modeVals = {};
+			for (const [aliasDotKey, colorRef] of Object.entries(flatAliases)) {
+				if (typeof colorRef !== "string") continue;
+				const varName = `--color-${dotToDash(aliasDotKey)}`;
+				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;
+		}
+		const initialMode = theme.mode;
+		if (initialMode && modeVariables[initialMode]) {
+			const initialModeVars = {};
+			const flatInitialAliases = flattenToDotPaths(theme.modes[initialMode]);
+			for (const [aliasDotKey, colorRef] of Object.entries(flatInitialAliases)) {
+				if (typeof colorRef !== "string") continue;
+				const varName = `--color-${dotToDash(aliasDotKey)}`;
+				const paletteVarName = variableMap[`colors.${colorRef}`];
+				if (paletteVarName) initialModeVars[varName] = `var(${paletteVarName})`;
+				tokenMap[`colors.${aliasDotKey}`] = `var(${varName})`;
+				variableMap[`colors.${aliasDotKey}`] = varName;
+			}
+			Object.assign(variables, initialModeVars);
+		}
+	}
+	return {
+		tokenMap,
+		variableMap,
+		variables,
+		modeVariables,
+		modeTokens
+	};
+}
+/**
+* Resolve token refs ({scale.key}) in all flattened token values.
+* Operates on the flattened tokenMap — does NOT mutate the nested theme.
+*/
+function resolveTokenRefs(tokenMap, _variableMap, _emittedScales) {
+	for (const [tokenPath, value] of Object.entries(tokenMap)) {
+		if (typeof value !== "string") continue;
+		if (!value.includes("{")) continue;
+		if (value.startsWith("var(")) continue;
+		const scaleName = tokenPath.split(".")[0];
+		const resolved = value.replace(TOKEN_REF_RE, (match, ref) => {
+			if (ref.split(".")[0] === scaleName) {
+				console.warn(`[animus] Self-referential token ref {${ref}} in scale '${scaleName}' — skipped`);
+				return match;
+			}
+			let lookupPath = ref;
+			let opacity;
+			const slashIdx = ref.indexOf("/");
+			if (slashIdx !== -1) {
+				lookupPath = ref.slice(0, slashIdx);
+				opacity = ref.slice(slashIdx + 1);
+			}
+			const refValue = tokenMap[lookupPath];
+			if (refValue === void 0) {
+				console.warn(`[animus] Token ref {${ref}} — path '${lookupPath}' not found in token map`);
+				return match;
+			}
+			if (opacity) {
+				const alpha = Number.parseInt(opacity, 10);
+				if (alpha === 0) return "transparent";
+				if (alpha !== 100) return `color-mix(in srgb, ${refValue} ${alpha}%, transparent)`;
+			}
+			return refValue;
+		});
+		if (resolved !== value) tokenMap[tokenPath] = resolved;
+	}
+}
+/** Build CSS variable blocks from flattened data. */
+function buildVariableCss(rootVariables, breakpointVariables, modeVariables) {
+	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 (rootLines.length > 0) parts.push(`:root {\n${rootLines.join("\n")}\n}`);
+	for (const [modeName, modeVars] of Object.entries(modeVariables)) {
+		const modeLines = [];
+		for (const [varName, value] of Object.entries(modeVars)) modeLines.push(`  ${varName}: ${value};`);
+		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, PropertyBuilder, SystemBuilder, ThemeBuilder, borderShorthand, createComponent, createScale, createSystem, createTheme, createTransform, flattenScale, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, serializeTokens, size, stringScale };
+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 };