@animus-ui/system 0.1.0-next.21 → 0.1.0-next.30

package/dist/index.js

@@ -1,237 +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 { createContext, createElement, forwardRef, useContext, useRef } from "react";
-//#region src/runtime/resolveClasses.ts
+import { n as createComponent, t as createClassResolver } from "./createClassResolver-Dny76K15.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-BjymBo7z.js";
+import { createContext, createElement, forwardRef, useContext } from "react";
+//#region src/utils/deepMerge.ts
 /**
-* CSS properties that accept unitless numeric values.
-* Bare numerics on properties NOT in this set receive `px`.
-*/
-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.
-*/
-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.
-*/
-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.
-*/
-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);
-}
-/**
-* Resolve className parts from props, using extracted configuration.
-* This is the shared logic between createComponent and createClassResolver.
-*/
-function resolveClasses(baseClassName, props, config, systemPropMap, dynamicPropConfig) {
-	const classes = [baseClassName];
-	let dynStyle;
-	if (config.variants) for (const [prop, vc] of Object.entries(config.variants)) {
-		const value = props[prop] ?? vc.default;
-		if (value != null) classes.push(`${baseClassName}--${prop}-${value}`);
-	}
-	if (config.compounds) for (const compound of config.compounds) {
-		let match = true;
-		for (const [prop, expected] of Object.entries(compound.conditions)) {
-			const current = props[prop] ?? config.variants?.[prop]?.default;
-			if (Array.isArray(expected) ? !expected.includes(current) : current !== expected) {
-				match = false;
-				break;
-			}
-		}
-		if (match) classes.push(compound.className);
-	}
-	if (config.states) {
-		for (const state of config.states) if (props[state]) classes.push(`${baseClassName}--${state}`);
-	}
-	const systemPropNames = config.systemPropNames || [];
-	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 (!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;
-						} else {
-							classes.push(`${dc.slotClass}-${bp}`);
-							const varName = `${dc.varName}-${bp}`;
-							const finalVal = resolveValue(bpVal, dc);
-							dynStyle[varName] = finalVal;
-						}
-					}
-					else {
-						classes.push(dc.slotClass);
-						const finalVal = resolveValue(propValue, dc);
-						dynStyle[dc.varName] = finalVal;
-					}
-				}
-			}
-		}
-	}
-	return {
-		classes,
-		dynamicStyle: dynStyle
-	};
-}
-//#endregion
-//#region src/runtime/index.ts
-/**
-* 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.
-*/
-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([
-		"as",
-		...variantProps,
-		...stateProps,
-		...systemPropNames
-	]);
-	const Component = forwardRef((props, ref) => {
-		const renderElement = props.as || element;
-		const isComponentElement = typeof renderElement !== "string";
-		const prevDynKey = useRef("");
-		const prevDynStyle = useRef(null);
-		const { classes, dynamicStyle } = resolveClasses(className, props, config, systemPropMap, dynamicPropConfig);
-		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 (dynamicStyle) {
-			const dynKey = Object.entries(dynamicStyle).map(([k, v]) => `${k}:${v}`).join("|");
-			if (dynKey !== prevDynKey.current) {
-				prevDynKey.current = dynKey;
-				prevDynStyle.current = dynamicStyle;
-			}
-			domProps.style = props.style ? {
-				...props.style,
-				...prevDynStyle.current
-			} : prevDynStyle.current;
-		}
-		return createElement(renderElement, domProps);
-	});
-	Component.displayName = className;
-	Component.__variantKeys = new Set(variantProps);
-	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/runtime/createClassResolver.ts
-/**
-* createClassResolver — framework-agnostic className resolution.
-*
-* Produced by .asClass() terminal. Same resolution logic as createComponent
-* (variants, states, compounds, system props) but returns a className string
-* instead of a React element.
+* Deep merge utility — replaces lodash.merge for variant accumulation.
 */
-function createClassResolver(className, config, systemPropMap, dynamicPropConfig) {
-	return (props) => {
-		const { classes } = resolveClasses(className, props || {}, config, systemPropMap, dynamicPropConfig);
-		return classes.join(" ");
-	};
-}
-//#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 = {};
@@ -267,9 +48,6 @@ var AnimusExtendedWithAll = class {
 	asClass() {
 		return createClassResolver("", this._buildComponentConfig());
 	}
-	build() {
-		return Object.assign((() => ({})), { extend: this.extend.bind(this) });
-	}
 	_buildComponentConfig() {
 		const variantConfig = {};
 		for (const [key, vc] of Object.entries(this.variants)) {
@@ -290,12 +68,12 @@ 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), this.compounds);
+		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, this.compounds);
+	system(config) {
+		return new AnimusExtendedWithSystem(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, deepMerge(this.activeGroups, config), this.custom, this.compounds);
 	}
 };
 var AnimusExtendedWithCompounds = class AnimusExtendedWithCompounds extends AnimusExtendedWithStates {
@@ -306,7 +84,7 @@ var AnimusExtendedWithCompounds = class AnimusExtendedWithCompounds extends Anim
 		}]);
 	}
 	states(config) {
-		return new AnimusExtendedWithStates(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, deepMerge$1(this.statesConfig, config), this.activeGroups, this.custom, this.compounds);
+		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 {
@@ -318,31 +96,22 @@ var AnimusExtendedWithVariants = class AnimusExtendedWithVariants extends Animus
 	}
 	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, this.compounds);
+		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, this.compounds);
+		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, this.compounds);
+		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 = {};
@@ -378,9 +147,6 @@ var AnimusWithAll = class {
 	asClass() {
 		return createClassResolver("", this._buildComponentConfig());
 	}
-	build() {
-		return Object.assign((() => ({})), { extend: this.extend.bind(this) });
-	}
 	_buildComponentConfig() {
 		const variantConfig = {};
 		for (const [key, vc] of Object.entries(this.variants)) {
@@ -411,7 +177,7 @@ var AnimusWithStates = class extends AnimusWithSystem {
 	constructor(props, groups, base, variants, states, compounds = []) {
 		super(props, groups, base, variants, states, {}, compounds);
 	}
-	groups(config) {
+	system(config) {
 		return new AnimusWithSystem(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, config, this.compounds);
 	}
 };
@@ -523,64 +289,78 @@ function compose(slots, options) {
 	return result;
 }
 //#endregion
-//#region src/PropertyBuilder.ts
-var PropertyBuilder = class PropertyBuilder {
-	#props;
-	#groups;
-	constructor(props, groups) {
-		this.#props = props || {};
-		this.#groups = groups || {};
-	}
-	addGroup(name, config) {
-		const newGroup = { [name]: Object.keys(config) };
-		return new PropertyBuilder({
-			...this.#props,
-			...config
-		}, {
-			...this.#groups,
-			...newGroup
-		});
-	}
-	build() {
-		return {
-			propRegistry: this.#props,
-			groupRegistry: this.#groups
-		};
-	}
-};
-//#endregion
 //#region src/SystemBuilder.ts
 var SystemBuilder = class SystemBuilder {
 	#propRegistry;
 	#groupRegistry;
-	#globalStyles;
-	constructor(propRegistry, groupRegistry, globalStyles) {
+	constructor(propRegistry, groupRegistry) {
 		this.#propRegistry = propRegistry || {};
 		this.#groupRegistry = groupRegistry || {};
-		this.#globalStyles = globalStyles;
 	}
-	withProperties(cb) {
-		const result = cb(new PropertyBuilder());
-		return new SystemBuilder(result.propRegistry, result.groupRegistry, this.#globalStyles);
+	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
+		});
+	}
+	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);
 	}
-	withGlobalStyles(styles) {
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, styles);
+	includes(_systems) {
+		return this;
 	}
 	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 system = Object.assign(animus, { toConfig: () => {
+			return serializeInstance(propRegistry, groupRegistry);
 		} });
+		const createGlobalStyles = (styles) => {
+			return {
+				__brand: "GlobalStyleBlock",
+				styles,
+				serialize(propConfig, transforms) {
+					return styles;
+				}
+			};
+		};
+		return {
+			system,
+			createGlobalStyles
+		};
 	}
 };
-function serializeInstance(propRegistry, groupRegistry, globalStyles) {
+function serializeInstance(propRegistry, groupRegistry) {
 	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;
@@ -589,15 +369,14 @@ function serializeInstance(propRegistry, groupRegistry, globalStyles) {
 				transforms[name] = fn;
 			}
 		}
+		if (entry.currentVar) s.currentVar = entry.currentVar;
 		serialized[propName] = s;
 	}
-	const result = {
+	return {
 		propConfig: JSON.stringify(serialized),
 		groupRegistry: JSON.stringify(groupRegistry),
 		transforms
 	};
-	if (globalStyles) result.globalStyles = globalStyles;
-	return result;
 }
 function createSystem() {
 	return new SystemBuilder();
@@ -620,57 +399,46 @@ 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, "-");
 }
 //#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;
-	}
-	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));
-	});
-	return {
-		tokens: tokenReferences,
-		variables: tokenVariables
-	};
-};
-//#endregion
 //#region src/theme/createTheme.ts
 const CSS_NAMED_COLORS = new Set([
 	"aliceblue",
@@ -845,13 +613,20 @@ function isValidCSSColor(value) {
 	if (CSS_NAMED_COLORS.has(v.toLowerCase())) return true;
 	return false;
 }
-/** Validate that mode aliases reference existing color keys. */
-function validateModeAliases(modeName, aliases, colorSet, availableColors, prefix) {
+/**
+* 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 (typeof value === "string") {
-			if (!colorSet.has(value)) throw new Error(`addColorModes: mode '${modeName}' references unknown color '${value}' for alias '${aliasPath}'. Available colors: ${availableColors.slice(0, 10).join(", ")}${availableColors.length > 10 ? ", ..." : ""}`);
-		} else if (isObject(value)) validateModeAliases(modeName, value, colorSet, availableColors, aliasPath);
+		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);
 	}
 }
 /** Validate all color entries, throwing on invalid values. */
@@ -859,237 +634,274 @@ 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 {
+		theme: theme || { breakpoints: {} },
+		emittedScales: /* @__PURE__ */ new Set(),
+		contextualVars: /* @__PURE__ */ new Map()
+	};
+}
+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 {
-	#theme = {};
-	#emittedScales = /* @__PURE__ */ new Set();
-	constructor(baseTheme) {
-		this.#theme = baseTheme;
-	}
-	/** Create a new builder checkpoint, carrying forward emittedScales state. */
-	#checkpoint(nextTheme) {
-		const next = new ThemeBuilder(nextTheme);
-		for (const s of this.#emittedScales) next.#emittedScales.add(s);
+	/** @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. Immediately converted to CSS variables `--color-${key}`.
-	* @example .addColors({ navy: 'navy', hyper: 'purple' })
-	*/
 	addColors(colors) {
 		validateColors(colors);
-		const flatColors = flattenScale(colors);
-		const { variables, tokens } = serializeTokens(flatColors, "color", this.#theme);
-		const nextTheme = merge({}, this.#theme, {
-			colors: tokens,
-			_variables: { root: variables },
-			_tokens: { colors: flatColors }
-		});
-		const next = this.#checkpoint(nextTheme);
-		next.#emittedScales.add("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 Default color mode key.
-	* @param modeConfig Map of color modes with semantic aliases pointing to palette keys.
-	* @example .addColorModes('dark', { dark: { primary: 'ember' }, light: { primary: 'void' } })
-	*/
 	addColorModes(initialMode, modeConfig) {
-		const availableColors = this.#theme._tokens?.colors ? Object.keys(this.#theme._tokens.colors) : Object.keys(this.#theme.colors || {});
-		const colorSet = new Set(availableColors);
-		for (const [modeName, modeAliases] of Object.entries(modeConfig)) validateModeAliases(modeName, modeAliases, colorSet, availableColors, "");
-		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];
-		const nextTheme = 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.#checkpoint(nextTheme);
+		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
-	/**
-	* Add a named scale to the theme.
-	*
-	* @param config.name - Scale name (e.g. 'space', 'sizes')
-	* @param config.values - Scale value map
-	* @param config.emit - When true, generates CSS variables (default: false)
-	*
-	* @example
-	* .addScale({ name: 'space', values: { 0: '0', 8: '0.5rem', 16: '1rem' } })
-	* .addScale({ name: 'sizes', emit: true, values: { navHeight: '48px' } })
-	*/
 	addScale(config) {
 		const { name, values, emit } = config;
-		const flattened = flattenScale(values);
-		let nextTheme;
-		if (emit) {
-			const { variables, tokens } = serializeTokens(flattened, name, this.#theme);
-			nextTheme = merge({}, this.#theme, {
-				[name]: tokens,
-				_variables: { [name]: variables },
-				_tokens: { [name]: flattened }
-			});
-		} else nextTheme = merge({}, this.#theme, { [name]: flattened });
-		const next = this.#checkpoint(nextTheme);
-		if (emit) next.#emittedScales.add(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) {
+		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;
+	}
+	extendScale(key, updateFn) {
+		const nextTheme = merge({}, this._state.theme, { [key]: updateFn(this._state.theme[key]) });
+		return new ThemeBuilder(copyState(this._state, nextTheme));
+	}
 	/**
-	* @param key A current key of theme to update with computed values.
-	* @example .updateScale('fonts', ({ basic }) => ({ basicFallback: `${basic}, Montserrat` }))
+	* Finalize the theme build.
+	* Flattens nested data at the boundary — produces manifest and serialize().
 	*/
-	updateScale(key, updateFn) {
-		const nextTheme = merge({}, this.#theme, { [key]: updateFn(this.#theme[key]) });
-		return this.#checkpoint(nextTheme);
-	}
-	/** Finalize the theme build. Returns the theme with a non-enumerable `.manifest` property. */
 	build() {
-		resolveThemeTokenRefs(this.#theme, this.#emittedScales);
-		const { variables } = serializeTokens(mapValues(this.#theme.breakpoints, (val) => `${val}px`), "breakpoint", this.#theme);
-		const theme = merge({}, this.#theme, {
-			_variables: { breakpoints: variables },
-			_tokens: {}
-		});
-		const manifest = assembleManifest(theme);
+		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} */
+/** Token ref pattern: {scale.key} or {scale.key.sub} */
 const TOKEN_REF_RE = /\{([^}]+)\}/g;
 /**
-* Resolve token refs ({scale.key}) in all scale values.
-* Only refs to emitted scales (those with CSS variables) are valid.
-* Runs once at build() time after all scales have been collected.
+* Flatten the nested theme into dot-path keyed token map and CSS variable declarations.
+* This is the ONLY place where flattening happens.
 */
-function resolveThemeTokenRefs(theme, emittedScales) {
-	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;
-		for (const [key, value] of Object.entries(scaleValue)) {
-			if (typeof value !== "string") continue;
-			if (!value.includes("{")) continue;
-			const resolved = value.replace(TOKEN_REF_RE, (match, ref) => {
-				const dotIdx = ref.indexOf(".");
-				if (dotIdx === -1) return match;
-				const refScale = ref.slice(0, dotIdx);
-				const refKey = ref.slice(dotIdx + 1);
-				if (refScale === scaleName) {
-					console.warn(`[animus] Self-referential token ref {${ref}} in scale '${scaleName}' — skipped`);
-					return match;
-				}
-				const targetScale = theme[refScale];
-				if (!targetScale || !isObject(targetScale)) {
-					console.warn(`[animus] Token ref {${ref}} references unknown scale '${refScale}'`);
-					return match;
-				}
-				const resolvedValue = targetScale[refKey];
-				if (resolvedValue === void 0) {
-					console.warn(`[animus] Token ref {${ref}} — key '${refKey}' not found in scale '${refScale}'`);
-					return match;
-				}
-				return String(resolvedValue);
-			});
-			if (resolved !== value) {
-				scaleValue[key] = resolved;
-				if (theme._tokens?.[scaleName]) theme._tokens[scaleName][key] = resolved;
-				if (theme._variables?.[scaleName]) {
-					const varName = `--${scaleName}-${key.replace("$", "")}`;
-					if (theme._variables[scaleName][varName] !== void 0) theme._variables[scaleName][varName] = resolved;
-				}
-			}
-		}
-	}
-}
-/**
-* Assemble a ThemeManifest from the built theme object.
-*
-* This is the single source of truth for the plugin — no string-matching
-* or re-flattening needed downstream.
-*/
-function assembleManifest(theme) {
+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)) flattenTokens(tokenMap, variableMap, scaleName, scaleValue);
+		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);
+		}
 	}
-	const modes = {};
-	if (theme._tokens?.modes && isObject(theme._tokens.modes)) for (const [modeName, modeTokens] of Object.entries(theme._tokens.modes)) {
-		if (!isObject(modeTokens)) continue;
-		const modeMap = {};
-		flattenModeEntries(modeMap, modeTokens, "");
-		modes[modeName] = modeMap;
+	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,
-		modes,
-		variableCss: buildManifestVariableCss(theme)
+		variables,
+		modeVariables,
+		modeTokens
 	};
 }
-/** Flatten a scale into tokenMap and extract variable references into variableMap. */
-function flattenTokens(tokenMap, variableMap, prefix, obj, parentKey = "") {
-	for (const [key, value] of Object.entries(obj)) {
-		const fullKey = parentKey ? `${parentKey}-${key}` : key;
-		if (isObject(value)) flattenTokens(tokenMap, variableMap, prefix, value, fullKey);
-		else {
-			const tokenPath = `${prefix}.${fullKey}`;
-			const strValue = String(value);
-			tokenMap[tokenPath] = strValue;
-			if (strValue.startsWith("var(") && strValue.endsWith(")")) variableMap[tokenPath] = strValue.slice(4, -1);
-		}
-	}
-}
-/** Flatten mode token entries (resolved values) into a flat key→value map. */
-function flattenModeEntries(modeMap, obj, prefix) {
-	for (const [key, value] of Object.entries(obj)) {
-		const namePart = key === "_" ? prefix : prefix ? `${prefix}-${key}` : key;
-		if (typeof value === "string" || typeof value === "number") modeMap[`colors.${namePart}`] = String(value);
-		else if (isObject(value)) flattenModeEntries(modeMap, value, namePart);
+/**
+* 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 (refValue.startsWith("var(") && opacity) return refValue;
+			return opacity ? refValue : refValue;
+		});
+		if (resolved !== value) tokenMap[tokenPath] = resolved;
 	}
 }
-/** Build CSS variable blocks from theme._variables and _tokens.modes. */
-function buildManifestVariableCss(theme) {
+/** Build CSS variable blocks from flattened data. */
+function buildVariableCss(rootVariables, breakpointVariables, modeVariables) {
 	const parts = [];
-	if (theme._variables && isObject(theme._variables)) {
-		const rootLines = [];
-		for (const categoryValue of Object.values(theme._variables)) {
-			if (!isObject(categoryValue)) continue;
-			for (const [cssVar, cssValue] of Object.entries(categoryValue)) if (typeof cssValue === "string") rootLines.push(`  ${cssVar}: ${cssValue};`);
-		}
-		if (rootLines.length > 0) parts.push(`:root {\n${rootLines.join("\n")}\n}`);
-	}
-	if (theme._tokens?.modes && isObject(theme._tokens.modes)) for (const [modeName, modeTokens] of Object.entries(theme._tokens.modes)) {
-		if (!isObject(modeTokens)) continue;
+	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 = [];
-		flattenModeTokensCss(modeLines, modeTokens, "");
+		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");
 }
-/** Recursively flatten mode tokens into CSS variable declaration lines. */
-function flattenModeTokensCss(lines, obj, prefix) {
-	for (const [key, value] of Object.entries(obj)) {
-		const namePart = key === "_" ? prefix : prefix ? `${prefix}-${key}` : key;
-		if (typeof value === "string" || typeof value === "number") lines.push(`  --color-${namePart}: ${value};`);
-		else if (isObject(value)) flattenModeTokensCss(lines, value, namePart);
-	}
-}
 //#endregion
-export { Animus, AnimusExtended, AnimusExtendedWithAll, AnimusWithAll, PropertyBuilder, SystemBuilder, ThemeBuilder, borderShorthand, compose, createClassResolver, createComponent, createScale, createSystem, createTheme, createTransform, flattenScale, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, serializeTokens, size, stringScale };
+export { Animus, AnimusExtended, AnimusExtendedWithAll, AnimusWithAll, SystemBuilder, ThemeBuilder, borderShorthand, compose, createClassResolver, createComponent, createScale, createSystem, createTheme, createTransform, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, size, stringScale };