@animus-ui/system 0.1.16 → 0.1.18

package/dist/index.js

@@ -1,7 +1,7 @@
-import { t as createClassResolver } from "./createClassResolver-EpwTL9Sa.js";
-import { n as createComponent, t as createComposedFamily } from "./createComposedFamily-C4NovMcd.js";
+import { t as createClassResolver } from "./createClassResolver-CcCgar2Z.js";
+import { n as createComponent, t as createComposedFamily } from "./createComposedFamily-C9ShrVy6.js";
 import { compose } from "./compose.js";
-import { a as borderShorthand, c as numericScale, d as createTransform, i as gridItemRatio, l as stringScale, n as size, o as createScale, r as gridItem, s as numericOrStringScale, t as percentageOrAbsolute, u as areTransformsEqual } from "./size-C4gOY6lI.js";
+import { a as borderShorthand, c as numericScale, d as createTransform, f as linkAuthoredCallable, i as gridItemRatio, l as stringScale, n as size, o as createScale, r as gridItem, s as numericOrStringScale, t as percentageOrAbsolute, u as areTransformsEqual } from "./size-ZhCTPtA-.js";
 //#region src/utils/deepMerge.ts
 const isMergeable = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 function deepMerge(target, source) {
@@ -70,7 +70,10 @@ 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({}, config), this.compounds);
+		return new AnimusExtendedWithAll(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, {
+			...this.custom,
+			...config
+		}, this.compounds);
 	}
 };
 var AnimusExtendedWithStates = class extends AnimusExtendedWithSystem {
@@ -347,6 +350,126 @@ function serializeConditionMap(map) {
 	return conditions;
 }
 //#endregion
+//#region src/declarations.ts
+/**
+* Fields of a value prop. A declaration prop carrying one would imply a
+* primary property, a transform or a negative form it does not have.
+*/
+const VALUE_PROP_FIELDS = [
+	"property",
+	"properties",
+	"transform",
+	"negative",
+	"strict",
+	"variable",
+	"currentVar"
+];
+const MEMBER_NAME = /^-?[A-Za-z][A-Za-z0-9-]*$/;
+/** Representation tags, which tell data apart without trusting its type. */
+function tagOf(value) {
+	return Object.prototype.toString.call(value);
+}
+function isRecord(value) {
+	return tagOf(value) === "[object Object]";
+}
+function isText(value) {
+	return tagOf(value) === "[object String]";
+}
+function isFiniteNumber(value) {
+	return tagOf(value) === "[object Number]" && Number.isFinite(value);
+}
+function isDeclarationProp(entry) {
+	return entry?.kind === "declarations";
+}
+/**
+* The camelCase spelling of a CSS property, so `font-size` and `fontSize`
+* name one member; vendor prefixes follow React's spelling (`WebkitX`,
+* `msX`). Custom properties are not members.
+*/
+function canonicalMemberName(name) {
+	if (!MEMBER_NAME.test(name) || name.endsWith("-") || name.includes("--")) return;
+	if (!name.includes("-")) return name;
+	const vendor = name.startsWith("-") ? name.slice(1) : void 0;
+	const words = (vendor ?? name).split("-");
+	return (vendor === void 0 || words[0] === "ms" ? words[0] : words[0].charAt(0).toUpperCase() + words[0].slice(1)) + words.slice(1).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+/** Canonical members in authored order; a duplicate spelling throws. */
+function canonicalMembers(label, members) {
+	const seen = /* @__PURE__ */ new Set();
+	return members.map((member) => {
+		const canonical = isText(member) ? canonicalMemberName(member) : void 0;
+		if (canonical === void 0) throw new Error(`${label}: member ${JSON.stringify(member)} is not a CSS property name.`);
+		if (seen.has(canonical)) throw new Error(`${label}: member '${canonical}' is listed more than once.`);
+		seen.add(canonical);
+		return canonical;
+	});
+}
+/**
+* A declaration prop with its members canonicalized. Matching its members
+* against the effective scale happens where the system and theme meet.
+*/
+function validateDeclarationProp(propName, entry) {
+	const label = `Declaration prop "${propName}"`;
+	for (const field of VALUE_PROP_FIELDS) if (entry[field] !== void 0) throw new Error(`${label}: '${field}' does not apply to a declaration prop — its scale's records name every property it sets.`);
+	if (!isText(entry.scale) || entry.scale === "") throw new Error(`${label}: 'scale' must name a scale registered with addDeclarationScale.`);
+	if (!Array.isArray(entry.members) || entry.members.length === 0) throw new Error(`${label}: 'members' must list at least one property.`);
+	return {
+		kind: "declarations",
+		scale: entry.scale,
+		members: canonicalMembers(label, entry.members)
+	};
+}
+function memberSetKey(record) {
+	return Object.keys(record).sort().join(",");
+}
+function describeLeaf(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return "an array";
+	if (isRecord(value)) return "a nested record";
+	if (tagOf(value) === "[object Number]") return String(value);
+	return tagOf(value).slice(8, -1).toLowerCase();
+}
+function validateRecord(where, record) {
+	if (!isRecord(record) || Object.keys(record).length === 0) throw new Error(`${where} must be a non-empty record of declarations.`);
+	const canonical = {};
+	for (const [member, value] of Object.entries(record)) {
+		const name = canonicalMemberName(member);
+		if (name === void 0) throw new Error(`${where}: member '${member}' is not a CSS property name.`);
+		if (name in canonical) throw new Error(`${where}: member '${name}' is set more than once.`);
+		if (!isText(value) && !isFiniteNumber(value)) throw new Error(`${where}: member '${name}' must be a string or finite number, got ${describeLeaf(value)}.`);
+		canonical[name] = value;
+	}
+	return canonical;
+}
+/**
+* Each record must be flat, with string or finite-number values, and every
+* record of one scale must set the same members. Returns the records with
+* canonical member names.
+*/
+function validateDeclarationRecords(label, scale, values) {
+	if (!isRecord(values) || Object.keys(values).length === 0) throw new Error(`${label}: declaration scale '${scale}' must map at least one key to a record.`);
+	const result = {};
+	for (const [key, record] of Object.entries(values)) result[key] = validateRecord(`${label}: declaration scale '${scale}' key '${key}'`, record);
+	assertUniformMembers(label, scale, result);
+	return result;
+}
+/** Every record names the members of the first; the diagnostic names the gap. */
+function assertUniformMembers(label, scale, values) {
+	const keys = Object.keys(values).sort();
+	if (keys.length === 0) return;
+	const expected = values[keys[0]];
+	const expectedKey = memberSetKey(expected);
+	for (const key of keys.slice(1)) {
+		const record = values[key];
+		if (memberSetKey(record) === expectedKey) continue;
+		const missing = Object.keys(expected).filter((member) => !(member in record));
+		const extra = Object.keys(record).filter((member) => !(member in expected));
+		const gaps = [missing.length > 0 ? `is missing ${missing.map((member) => `'${member}'`).join(", ")}` : "", extra.length > 0 ? `sets extra ${extra.map((member) => `'${member}'`).join(", ")}` : ""].filter(Boolean);
+		throw new Error(`${label}: declaration scale '${scale}' key '${key}' ${gaps.join(" and ")} relative to key '${keys[0]}' — every record must set the same members.`);
+	}
+}
+//#endregion
 //#region src/keyframes.ts
 const fnv1a = (input) => {
 	let hash = 2166136261;
@@ -592,11 +715,18 @@ function mergeVocabularyEntries(existingEntries, existingCollisions, incoming, i
 	};
 }
 const snapshotTransformBySource = /* @__PURE__ */ new WeakMap();
+const snapshotTransforms = /* @__PURE__ */ new WeakSet();
+/**
+* A snapshot is already frozen, so re-snapshotting it across `extend()`
+* returns it: the callable keeps one identity however often it is inherited.
+*/
 function snapshotTransform(source) {
+	if (snapshotTransforms.has(source)) return source;
 	const cached = snapshotTransformBySource.get(source);
 	if (cached) return cached;
 	const wrapper = (value, property, props) => source(value, property, props);
 	Object.defineProperty(wrapper, "name", { value: source.name });
+	linkAuthoredCallable(wrapper, source);
 	const sourceText = source.toString();
 	Object.defineProperty(wrapper, "toString", { value: () => sourceText });
 	const named = source;
@@ -610,6 +740,7 @@ function snapshotTransform(source) {
 	});
 	Object.freeze(wrapper);
 	snapshotTransformBySource.set(source, wrapper);
+	snapshotTransforms.add(wrapper);
 	return wrapper;
 }
 /**
@@ -638,13 +769,23 @@ function scalesEqual(existing, incoming) {
 	return orderedMembersEqual(existingKeys, Object.keys(incomingMap).sort()) && existingKeys.every((key) => existingMap[key] === incomingMap[key]);
 }
 function arePropDefinitionsEqual(existing, incoming, structuralScale = false) {
+	if (isDeclarationProp(existing) || isDeclarationProp(incoming)) return isDeclarationProp(existing) && isDeclarationProp(incoming) && existing.scale === incoming.scale && orderedMembersEqual(existing.members, incoming.members);
 	return existing.property === incoming.property && orderedPropertiesEqual(existing.properties, incoming.properties) && (structuralScale ? scalesEqual(existing.scale, incoming.scale) : existing.scale === incoming.scale) && existing.variable === incoming.variable && existing.negative === incoming.negative && existing.strict === incoming.strict && existing.currentVar === incoming.currentVar && areTransformsEqual(existing.transform, incoming.transform);
 }
 function orderedMembersEqual(existing, incoming) {
 	return existing.length === incoming.length && existing.every((member, index) => member === incoming[index]);
 }
+function describePropDefinition(entry) {
+	return isDeclarationProp(entry) ? `kind="declarations", scale="${entry.scale}", members="${entry.members.join(",")}"` : `property="${entry.property}", scale="${String(entry.scale)}"`;
+}
 function divergentPropError(key, existing, incoming, existingOrigin, incomingOrigin) {
-	return /* @__PURE__ */ new Error(`Prop "${key}" already registered with a different definition. Existing (${existingOrigin}): property="${existing.property}", scale="${String(existing.scale)}". Incoming (${incomingOrigin}): property="${incoming.property}", scale="${String(incoming.scale)}".`);
+	return /* @__PURE__ */ new Error(`Prop "${key}" already registered with a different definition. Existing (${existingOrigin}): ${describePropDefinition(existing)}. Incoming (${incomingOrigin}): ${describePropDefinition(incoming)}.`);
+}
+/** Declaration props with canonical members; value props unchanged. */
+function normalizePropConfig(config) {
+	const normalized = {};
+	for (const [key, entry] of Object.entries(config)) normalized[key] = isDeclarationProp(entry) ? validateDeclarationProp(key, entry) : entry;
+	return normalized;
 }
 var SystemBuilder = class SystemBuilder {
 	#propRegistry;
@@ -793,14 +934,15 @@ var SystemBuilder = class SystemBuilder {
 		const merged = mergeConditions(this.#conditionRegistry, conditions, new Set(Object.keys(this.#selectorRegistry)));
 		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, merged, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, this.#legacyVerbWitnesses);
 	}
-	addGroup(name, config) {
+	addGroup(name, authored) {
 		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.`);
+		const config = normalizePropConfig(authored);
 		for (const key of Object.keys(config)) if (key in this.#propRegistry) {
 			const existing = this.#propRegistry[key];
 			const incoming = config[key];
 			if (!arePropDefinitionsEqual(existing, incoming, this.#extendProvenance.has(`prop:${key}`))) {
 				if (this.#extendProvenance.has(`prop:${key}`)) throw divergentPropError(key, existing, incoming, this.#originOf(`prop:${key}`), "builder state");
-				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)}".`);
+				throw new Error(`Prop "${key}" already registered with a different definition. Existing: ${describePropDefinition(existing)}. Incoming: ${describePropDefinition(incoming)}.`);
 			}
 		}
 		const nextProps = {
@@ -814,8 +956,9 @@ var SystemBuilder = class SystemBuilder {
 		};
 		return new SystemBuilder(nextProps, nextGroups, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, this.#legacyVerbWitnesses);
 	}
-	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.`);
+	addProps(authored) {
+		for (const key of Object.keys(authored)) 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.`);
+		const config = normalizePropConfig(authored);
 		for (const key of Object.keys(config)) if (key in this.#propRegistry) {
 			const existing = this.#propRegistry[key];
 			const incoming = config[key];
@@ -945,6 +1088,13 @@ var SystemBuilder = class SystemBuilder {
 function createRegistrySnapshot(propRegistry, groupRegistry, selectorRegistry, conditionRegistry) {
 	const props = {};
 	for (const [name, entry] of Object.entries(propRegistry)) {
+		if (isDeclarationProp(entry)) {
+			props[name] = Object.freeze({
+				...entry,
+				members: Object.freeze([...entry.members])
+			});
+			continue;
+		}
 		const copy = { ...entry };
 		if (copy.properties) copy.properties = Object.freeze([...copy.properties]);
 		if (copy.scale && typeof copy.scale === "object") copy.scale = Object.freeze(Array.isArray(copy.scale) ? [...copy.scale] : { ...copy.scale });
@@ -964,26 +1114,46 @@ function createRegistrySnapshot(propRegistry, groupRegistry, selectorRegistry, c
 		conditions: Object.freeze(conditions)
 	});
 }
+/**
+* A configured definition's identity: its system provenance is the first of
+* its bound props in sorted order, so registration order, unrelated props and
+* callback edits leave it unchanged. The readable name is carried for
+* legibility; the prop alone keeps two same-named definitions apart.
+*/
+function transformDefinitionId(name, props) {
+	const [owner] = [...props].sort();
+	return `${name}@system.${owner}`;
+}
 function serializeInstance(propRegistry, groupRegistry, selectorRegistry, conditionRegistry) {
 	const serialized = {};
-	const transforms = {};
-	const transformOwners = {};
+	const definitions = /* @__PURE__ */ new Map();
 	for (const [propName, entry] of Object.entries(propRegistry)) {
+		if (isDeclarationProp(entry)) {
+			serialized[propName] = {
+				kind: "declarations",
+				scale: entry.scale,
+				members: [...entry.members]
+			};
+			continue;
+		}
 		const s = { property: entry.property };
 		if (entry.properties && entry.properties.length > 0) s.properties = [...entry.properties];
 		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 (s.scale !== void 0 && entry.strict !== false) s.strict = true;
 		if (entry.transform) {
 			const fn = entry.transform;
 			const name = fn.transformName ?? fn.name;
 			if (name) {
-				const existing = transforms[name];
-				if (existing && !areTransformsEqual(existing, fn)) throw new Error(`Transform name "${name}" is registered by both props "${transformOwners[name]}" and "${propName}" with different function instances. Share one cached transform instance or give the transforms distinct names.`);
 				s.transform = name;
-				transforms[name] = fn;
-				transformOwners[name] = propName;
+				const definition = definitions.get(fn);
+				if (definition) definition.props.push(propName);
+				else definitions.set(fn, {
+					name,
+					props: [propName]
+				});
 			}
 		}
 		if (entry.currentVar) s.currentVar = entry.currentVar;
@@ -991,10 +1161,14 @@ function serializeInstance(propRegistry, groupRegistry, selectorRegistry, condit
 	}
 	const { selectors } = serializeSelectorMap(selectorRegistry);
 	const conditions = serializeConditionMap(conditionRegistry);
+	const transforms = {};
 	const transformSources = {};
-	for (const [name, fn] of Object.entries(transforms)) {
+	for (const [fn, { name, props }] of definitions) {
+		const id = transformDefinitionId(name, props);
+		for (const propName of props) serialized[propName].transformId = id;
+		transforms[id] = fn;
 		const source = fn.transformSource;
-		if (source !== void 0) transformSources[name] = source;
+		if (source !== void 0) transformSources[id] = source;
 	}
 	return {
 		propConfig: JSON.stringify(serialized),
@@ -1040,6 +1214,31 @@ function parseReferences(value) {
 	}
 	return references;
 }
+function applyOpacity(base, opacity) {
+	if (opacity === void 0) return base;
+	const alpha = Number.parseInt(opacity, 10);
+	if (Number.isNaN(alpha)) return base;
+	if (alpha === 0) return "transparent";
+	if (alpha !== 100) return `color-mix(in srgb, ${base} ${alpha}%, transparent)`;
+	return base;
+}
+/**
+* Substitutes `{path}` references in one value from a resolved token map,
+* whose emitted paths already read `var(--…)`. An unknown path warns and
+* keeps its literal, as a token's own reference does.
+*/
+function resolveValueReferences(value, tokenMap) {
+	if (!value.includes("{")) return value;
+	return value.replace(TOKEN_REF_RE$1, (match) => {
+		const [reference] = parseReferences(match);
+		const target = tokenMap[reference.path];
+		if (target === void 0) {
+			console.warn(`[animus] Token ref {${reference.text}} — path '${reference.path}' not found in token map`);
+			return match;
+		}
+		return applyOpacity(target, reference.opacity);
+	});
+}
 /**
 * An unresolvable reference warns and keeps its literal: a kit theme may
 * reference tokens its consumer supplies later.
@@ -1074,14 +1273,7 @@ function resolveReferences(tokenMap, variableMap, variables) {
 		}
 		const targetVar = variableMap[reference.path];
 		const targetValue = resolved.get(reference.path);
-		const base = targetVar !== void 0 && !targetValue.includes("{") ? `var(${targetVar})` : targetValue;
-		if (reference.opacity !== void 0) {
-			const alpha = Number.parseInt(reference.opacity, 10);
-			if (Number.isNaN(alpha)) return base;
-			if (alpha === 0) return "transparent";
-			if (alpha !== 100) return `color-mix(in srgb, ${base} ${alpha}%, transparent)`;
-		}
-		return base;
+		return applyOpacity(targetVar !== void 0 && !targetValue.includes("{") ? `var(${targetVar})` : targetValue, reference.opacity);
 	};
 	const resolvePath = (path) => {
 		const status = state.get(path) ?? UNVISITED;
@@ -1213,6 +1405,7 @@ const RESERVED_THEME_KEYS = /* @__PURE__ */ new Set([
 	"browserColorScheme",
 	"modeBases",
 	"__emitted",
+	"__declarationScales",
 	"manifest",
 	"serialize",
 	"varRef"
@@ -1317,7 +1510,9 @@ function createState(theme) {
 		extendCount: 0,
 		inheritedModes: /* @__PURE__ */ new Set(),
 		inheritedModeAliases: /* @__PURE__ */ new Set(),
-		droppedTokenPaths: /* @__PURE__ */ new Map()
+		droppedTokenPaths: /* @__PURE__ */ new Map(),
+		declarationScales: {},
+		declarationProvenance: /* @__PURE__ */ new Map()
 	};
 }
 function copyState(state, nextTheme) {
@@ -1332,7 +1527,9 @@ function copyState(state, nextTheme) {
 		extendCount: state.extendCount,
 		inheritedModes: new Set(state.inheritedModes),
 		inheritedModeAliases: new Set(state.inheritedModeAliases),
-		droppedTokenPaths: new Map(state.droppedTokenPaths)
+		droppedTokenPaths: new Map(state.droppedTokenPaths),
+		declarationScales: { ...state.declarationScales },
+		declarationProvenance: new Map(state.declarationProvenance)
 	};
 	for (const [scale, vars] of state.contextualVars) next.contextualVars.set(scale, [...vars]);
 	return next;
@@ -1376,6 +1573,20 @@ function plainDataEqual(a, b) {
 	}
 	return false;
 }
+/** The declaration scales a built theme carries for composition. */
+function declarationScalesOf(source) {
+	const carried = source?.__declarationScales;
+	return isObject(carried) ? carried : {};
+}
+/** Key-level fold: an overlay record replaces the base record whole. */
+function overlayDeclarationScales(base, overlay) {
+	const result = deepCopyPlain(base);
+	for (const [scale, values] of Object.entries(overlay)) result[scale] = {
+		...result[scale],
+		...deepCopyPlain(values)
+	};
+	return result;
+}
 /**
 * Re-seeds emitted scales, contextual vars and the manifest-v2 carry from a
 * source manifest — non-enumerable, so key-copy loops never see it.
@@ -1435,6 +1646,7 @@ var ThemeBuilder = class ThemeBuilder {
 		}
 		const nextTheme = merge(deepCopyPlain(this._state.theme), deepCopyPlain(raw));
 		const next = new ThemeBuilder(copyState(this._state, nextTheme));
+		next._state.declarationScales = overlayDeclarationScales(this._state.declarationScales, declarationScalesOf(source));
 		reseedStateFromManifest(next._state, source.manifest);
 		return next;
 	}
@@ -1478,6 +1690,16 @@ var ThemeBuilder = class ThemeBuilder {
 		const next = new ThemeBuilder(copyState(this._state, nextTheme));
 		next._state.extendProvenance = provenance;
 		next._state.extendCount = sourceIndex;
+		const incomingDeclarations = declarationScalesOf(themeHalf);
+		const declarationProvenance = new Map(this._state.declarationProvenance);
+		for (const [scale, values] of Object.entries(incomingDeclarations)) for (const [key, record] of Object.entries(values)) {
+			const path = `${scale}.${key}`;
+			const priorIndex = declarationProvenance.get(path);
+			if (priorIndex === void 0) declarationProvenance.set(path, sourceIndex);
+			else if (!plainDataEqual(this._state.declarationScales[scale]?.[key], record)) throw new Error(`extend: declaration scale '${scale}' key '${key}' is defined divergently by extended theme #${priorIndex} and extended theme #${sourceIndex}. Sibling themes must agree — override intentionally with addDeclarationScale after extend().`);
+		}
+		next._state.declarationScales = overlayDeclarationScales(incomingDeclarations, this._state.declarationScales);
+		next._state.declarationProvenance = declarationProvenance;
 		if (isObject(raw.modes)) for (const [modeName, modeAliases] of Object.entries(raw.modes)) {
 			next._state.inheritedModes.add(modeName);
 			if (!isObject(modeAliases)) continue;
@@ -1521,6 +1743,7 @@ var ThemeBuilder = class ThemeBuilder {
 	addScale(config) {
 		const { name, values, emit, replace } = config;
 		if (RESERVED_THEME_KEYS.has(name)) throw new Error(`addScale: '${name}' is a reserved theme key owned by the builder or built-theme boundary, so a scale by this name cannot survive build(). Choose another scale name.`);
+		if (name in this._state.declarationScales) throw new Error(`addScale: '${name}' is already a declaration scale — a scale is either scalar or declaration-valued.`);
 		const prior = this._state.theme[name];
 		let nextTheme;
 		if (replace) {
@@ -1535,6 +1758,27 @@ var ThemeBuilder = class ThemeBuilder {
 		}
 		return next;
 	}
+	/**
+	* Registers a finite declaration scale: each key maps to a flat record of
+	* CSS declarations, and every record sets the same members. Bind it with a
+	* `{ kind: 'declarations', scale, members }` system or component prop. Keys merge by
+	* record; `replace` makes the scale exactly these keys.
+	*/
+	addDeclarationScale(config) {
+		const { name, values, replace } = config;
+		const label = "addDeclarationScale";
+		if (RESERVED_THEME_KEYS.has(name)) throw new Error(`${label}: '${name}' is a reserved theme key owned by the builder or built-theme boundary. Choose another scale name.`);
+		if (name in this._state.theme) throw new Error(`${label}: '${name}' is already a scalar scale — a scale is either scalar or declaration-valued.`);
+		const records = validateDeclarationRecords(label, name, values);
+		const next = new ThemeBuilder(copyState(this._state, this._state.theme));
+		const merged = replace ? records : {
+			...next._state.declarationScales[name],
+			...records
+		};
+		assertUniformMembers(label, name, merged);
+		next._state.declarationScales[name] = merged;
+		return next;
+	}
 	declareContextualVars(vars, registrations) {
 		for (const scale of Object.keys(vars)) if (!(scale in this._state.theme)) throw new Error(`declareContextualVars: scale '${scale}' not found — call addColors or addScale first`);
 		const next = new ThemeBuilder(copyState(this._state, this._state.theme));
@@ -1575,6 +1819,8 @@ var ThemeBuilder = class ThemeBuilder {
 		const { tokenMap: flatTokenMap, variableMap, variables: flatVariables, tokenDefinitions } = flattenTheme(theme, emittedScales, effectiveModes);
 		assertNoDroppedReferences(tokenDefinitions, flatTokenMap, this._state.droppedTokenPaths, this._state.extendProvenance);
 		const { tokenMap, variables } = resolveReferences(flatTokenMap, variableMap, flatVariables);
+		const declarationScales = this._state.declarationScales;
+		const resolvedDeclarationScales = resolveDeclarationScales(declarationScales, theme, tokenMap);
 		const { modeVariables, modeTokens } = resolveModeValueMaps(effectiveModes, variableMap, variables, tokenMap);
 		const bpVariables = {};
 		if (theme.breakpoints && isObject(theme.breakpoints)) {
@@ -1649,12 +1895,20 @@ var ThemeBuilder = class ThemeBuilder {
 			configurable: false,
 			writable: false
 		});
+		Object.defineProperty(theme, "__declarationScales", {
+			value: deepCopyPlain(declarationScales),
+			enumerable: false,
+			configurable: false,
+			writable: false
+		});
+		const declarationScalesJson = resolvedDeclarationScales ? JSON.stringify(resolvedDeclarationScales) : void 0;
 		Object.defineProperty(theme, "serialize", {
 			value: () => ({
 				scalesJson: JSON.stringify(manifest.tokenMap),
 				variableMapJson: JSON.stringify(manifest.variableMap),
 				variableCss: manifest.variableCss,
-				contextualVarsJson: JSON.stringify(manifest.contextualVars ?? {})
+				contextualVarsJson: JSON.stringify(manifest.contextualVars ?? {}),
+				...declarationScalesJson ? { declarationScalesJson } : {}
 			}),
 			enumerable: false,
 			configurable: false,
@@ -1683,6 +1937,32 @@ var ThemeBuilder = class ThemeBuilder {
 function createTheme() {
 	return new ThemeBuilder(createState());
 }
+/**
+* The effective declaration scales in serialized order, token references
+* resolved against the final token map; `undefined` when there are none.
+*/
+function resolveDeclarationScales(declarationScales, theme, tokenMap) {
+	const names = Object.keys(declarationScales).sort();
+	if (names.length === 0) return void 0;
+	const serialized = {};
+	for (const name of names) {
+		if (name in theme) throw new Error(`build: '${name}' is both a scalar scale and a declaration scale — a scale is either scalar or declaration-valued.`);
+		const values = declarationScales[name];
+		assertUniformMembers("build", name, values);
+		const resolved = {};
+		for (const key of Object.keys(values).sort()) {
+			const record = values[key];
+			resolved[key] = sortRecordByKey(Object.fromEntries(Object.entries(record).map(([member, value]) => [member, typeof value === "string" ? resolveValueReferences(value, tokenMap) : value])));
+		}
+		const [firstKey] = Object.keys(resolved);
+		serialized[name] = {
+			kind: "declarations",
+			members: Object.keys(resolved[firstKey]),
+			values: resolved
+		};
+	}
+	return serialized;
+}
 /** Authored token reference: `{scale.key}` or `{scale.key/opacity}`. */
 const TOKEN_REF_RE = /\{([^}]+)\}/g;
 /**

package/dist/runtime/index.d.ts

@@ -3,9 +3,11 @@ import { type ClassResolverConfig, type DynamicPropConfig, type SystemPropMap }
 interface ComponentConfig extends ClassResolverConfig {
 }
 type ElementType = string | React.ComponentType<any>;
+type Transform = NonNullable<DynamicPropConfig[string]['transform']>;
 type AnimusComponent = ReturnType<typeof forwardRef> & {
     extend: () => never;
     variantDefaults: Readonly<Record<string, string>>;
+    customTransforms: Readonly<Record<string, Transform>>;
 };
 export declare function createComponent(element: ElementType, className: string, config: ComponentConfig, systemPropMap?: SystemPropMap, dynamicPropConfig?: DynamicPropConfig): AnimusComponent;
 export {};

package/dist/runtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,UAAU,EAEX,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EAEtB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,UAAU,eAAgB,SAAQ,mBAAmB;CAAG;AAExD,KAAK,WAAW,GAAG,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;AAErD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG;IACrD,MAAM,EAAE,MAAM,KAAK,CAAC;IACpB,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD,CAAC;AA6GF,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,aAAa,CAAC,EAAE,aAAa,EAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,eAAe,CAoEjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,UAAU,EAEX,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EAEtB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,UAAU,eAAgB,SAAQ,mBAAmB;CAAG;AAExD,KAAK,WAAW,GAAG,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;AAErD,KAAK,SAAS,GAAG,WAAW,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAErE,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG;IACrD,MAAM,EAAE,MAAM,KAAK,CAAC;IACpB,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACvD,CAAC;AAwHF,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,aAAa,CAAC,EAAE,aAAa,EAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,eAAe,CA4EjB"}

package/dist/runtime/resolveClasses.d.ts

@@ -13,17 +13,43 @@ export interface ClassResolverConfig {
     systemPropNames?: string[];
     customPropMap?: Record<string, Record<string, string>>;
     customDynamicConfig?: DynamicPropConfig;
+    /** Callback props whose `customPropMap` keys are `typedValueKey`s. */
+    typedCustomProps?: readonly string[];
+    /** System props bound to a configured transform, whose `systemPropMap`
+     *  keys are `typedValueKey`s. */
+    typedSystemProps?: readonly string[];
 }
 export type SystemPropMap = Record<string, Record<string, string>>;
-export type DynamicPropConfig = Record<string, {
+interface ValueDynamicPropConfig {
     varName: string;
     slotClass: string;
     property?: string;
     properties?: readonly string[];
+    /** The bound transform's readable name, for diagnostics. */
     transformName?: string;
+    /** The bound definition's key in the generated `transforms` registry. */
+    transformId?: string;
     transform?: (value: string | number) => string | number;
-    scaleValues?: Record<string, string>;
-}>;
+    scaleValues?: Record<string, string | number>;
+    negative?: boolean;
+    /** Values outside `scaleValues` are dropped, not applied raw. */
+    strict?: boolean;
+    /** The keywords a strict prop admits beside its tokens. */
+    keywords?: readonly string[];
+    kind?: never;
+}
+interface DeclarationDynamicPropConfig {
+    kind: 'declarations';
+    slotClass: string;
+    /** Member property → its variable; a breakpoint appends `-{bp}`. */
+    memberVars: Record<string, string>;
+    /** Scale key → member property → resolved CSS value. */
+    declarationScaleValues: Record<string, Record<string, string>>;
+}
+type DeclarationConfig = DeclarationDynamicPropConfig & {
+    [K in Exclude<keyof ValueDynamicPropConfig, 'kind' | 'slotClass'>]?: never;
+};
+export type DynamicPropConfig = Record<string, ValueDynamicPropConfig | DeclarationConfig>;
 /**
  * A mixed property set resolves to unitless: a bare number on a length
  * property is dropped by the parser, `px` on a unitless one shifts layout.
@@ -39,11 +65,12 @@ export declare function serializeValueKey(value: unknown): string;
  * or finite number passed here is mislabeled.
  */
 export declare function describeResultShape(result: unknown): string;
+type DynamicEntryConfig = Pick<ValueDynamicPropConfig, 'varName' | 'property' | 'properties' | 'transform' | 'scaleValues' | 'negative' | 'strict' | 'keywords'>;
 /**
- * `null` means a configured transform returned neither a string nor a finite
- * number; paths without a transform never return `null`.
+ * `null` means the value missed a strict scale, or a configured transform
+ * threw or returned neither a string nor a finite number.
  */
-export declare function resolveValue(value: unknown, dc: Pick<DynamicPropConfig[string], 'varName' | 'property' | 'properties' | 'transform' | 'scaleValues'>): string | null;
+export declare function resolveValue(value: unknown, dc: DynamicEntryConfig): string | null;
 export interface ClassResolution {
     classes: string[];
     dynamicStyle?: Record<string, string>;

package/dist/runtime/resolveClasses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveClasses.d.ts","sourceRoot":"","sources":["../../src/runtime/resolveClasses.ts"],"names":[],"mappings":"AAAA,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACzC,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,mBAAmB,CAAC,EAAE,iBAAiB,CAAC;CACzC;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE,MAAM,MAAM,iBAAiB,GAAG,MAAM,CACpC,MAAM,EACN;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,KAAK,MAAM,GAAG,MAAM,CAAC;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CACF,CAAC;AAOF;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,CAQR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWxD;AASD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAK3D;AAwCD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,EAAE,EAAE,IAAI,CACN,iBAAiB,CAAC,MAAM,CAAC,EACzB,SAAS,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CACpE,GACA,MAAM,GAAG,IAAI,CAGf;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AA8ID,wBAAgB,cAAc,CAC5B,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,aAAa,CAAC,EAAE,aAAa,EAC7B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,eAAe,CAoDjB"}
+{"version":3,"file":"resolveClasses.d.ts","sourceRoot":"","sources":["../../src/runtime/resolveClasses.ts"],"names":[],"mappings":"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"}

package/dist/runtime-entry.js

@@ -1,3 +1,3 @@
-import { t as createClassResolver } from "./createClassResolver-EpwTL9Sa.js";
-import { n as createComponent, t as createComposedFamily } from "./createComposedFamily-C4NovMcd.js";
+import { t as createClassResolver } from "./createClassResolver-CcCgar2Z.js";
+import { n as createComponent, t as createComposedFamily } from "./createComposedFamily-C9ShrVy6.js";
 export { createClassResolver, createComponent, createComposedFamily };