fashionable 0.3.0 → 0.4.0

package/dist/shared/{calc-Cih4o2r7.mjs → calc-Uwbxd7CS.mjs}

@@ -2,24 +2,8 @@ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { Pipeable, dual, invariant } from "../utils.mjs";
 import { i as equals$2, n as HashTypeId, o as hashNumber, r as combine, s as hashString, t as EqualTypeId } from "./equal-U9G5LhtL.mjs";
 import { a as specFidelity, i as specEquals, r as formatWith, t as DEFAULT_FORMAT } from "./format-B9jsmCER.mjs";
+import { _ as RefsTypeId, g as EMPTY_REFS, h as refsOfVar, o as fallbackOf, r as declaredTypeOf, s as isVar, u as nameOf } from "./var.internal-DSxAzEFN.mjs";
 import { i as toSpec, n as isPrecision$1, r as significant$1, t as decimals$1 } from "./precision.internal-0lv1nEpF.mjs";
-//#region src/internal/refs.ts
-/**
-* Runtime helpers for the unbound-reference sets carried by expression
-* values. The matching type-level machinery (the phantom `Refs` parameter
-* and `ApplyBindings`) lives with the public types in calc/calc.ts;
-* container modules extract refs from heterogeneous members with
-* conditionals over their member unions (`RuleSet.MemberRefs`).
-*/
-/** @internal */
-const unionRefs = (...sets) => {
-	const merged = /* @__PURE__ */ new Set();
-	for (const set of sets) for (const ref of set) merged.add(ref);
-	return merged;
-};
-/** @internal */
-const EMPTY_REFS = /* @__PURE__ */ new Set();
-//#endregion
 //#region src/calc/calc.internal.ts
 const CalcTypeId = Symbol.for("fashionable/calc");
 const isConstant = (node) => node._tag === "Constant";
@@ -219,7 +203,17 @@ const atan2Node = (y, x) => {
 const substituteNode = (node, bindings) => {
 	switch (node._tag) {
 		case "Constant": return node;
-		case "Ref": return bindings[node.name] ?? node;
+		case "Ref": {
+			const bound = bindings[node.name];
+			if (bound !== void 0) return bound;
+			if (node.fallback === void 0) return node;
+			const fallback = substituteNode(node.fallback, bindings);
+			return fallback === node.fallback ? node : {
+				_tag: "Ref",
+				name: node.name,
+				fallback
+			};
+		}
 		case "Ident": return node;
 		case "Add": return addNode(node.terms.map((term) => substituteNode(term, bindings)));
 		case "Subtract": return subtractNode(substituteNode(node.left, bindings), substituteNode(node.right, bindings));
@@ -244,7 +238,7 @@ const substituteNode = (node, bindings) => {
 * The units that lower with no caller-supplied ratio: `px` is the pixel base
 * (`1`), a radian is already the numeric measure of its angle (`1`), and a
 * degree is a fixed `pi / 180` of one. Every other unit is context-dependent
-* and must appear in the solve context.
+* and must appear in the `units` section of the solve options.
 *
 * @internal
 */
@@ -254,44 +248,44 @@ const DEFAULT_RATIOS = {
 	deg: Math.PI / 180
 };
 /** @internal */
-const evaluateNode = (node, context) => {
+const evaluateNode = (node, unitRatios, identValues) => {
 	switch (node._tag) {
 		case "Constant": {
 			if (node.unit === void 0) return node.value;
-			const ratio = context[node.unit] ?? DEFAULT_RATIOS[node.unit];
-			invariant(ratio !== void 0, `Cannot evaluate ${node.value}${node.unit}: no ratio for '${node.unit}' in the unit context`);
+			const ratio = unitRatios[node.unit] ?? DEFAULT_RATIOS[node.unit];
+			invariant(ratio !== void 0, `Cannot evaluate ${node.value}${node.unit}: no ratio for '${node.unit}' in the units section`);
 			return node.value * ratio;
 		}
-		case "Ref": throw new Error(`Cannot evaluate non-constant reference: ${node.name}`);
+		case "Ref": throw new Error(`Cannot evaluate unbound variable: ${node.name}`);
 		case "Ident": {
-			const value = context[node.name];
-			invariant(value !== void 0, `Cannot evaluate '${node.name}': no value for it in the solve context`);
+			const value = identValues[node.name];
+			invariant(value !== void 0, `Cannot evaluate '${node.name}': no value for it in the idents section`);
 			return value;
 		}
-		case "Add": return node.terms.reduce((total, term) => total + evaluateNode(term, context), 0);
-		case "Subtract": return evaluateNode(node.left, context) - evaluateNode(node.right, context);
-		case "Multiply": return evaluateNode(node.left, context) * evaluateNode(node.right, context);
-		case "Divide": return evaluateNode(node.left, context) / evaluateNode(node.right, context);
+		case "Add": return node.terms.reduce((total, term) => total + evaluateNode(term, unitRatios, identValues), 0);
+		case "Subtract": return evaluateNode(node.left, unitRatios, identValues) - evaluateNode(node.right, unitRatios, identValues);
+		case "Multiply": return evaluateNode(node.left, unitRatios, identValues) * evaluateNode(node.right, unitRatios, identValues);
+		case "Divide": return evaluateNode(node.left, unitRatios, identValues) / evaluateNode(node.right, unitRatios, identValues);
 		case "Mod": {
-			const dividend = evaluateNode(node.left, context);
-			const divisor = evaluateNode(node.right, context);
+			const dividend = evaluateNode(node.left, unitRatios, identValues);
+			const divisor = evaluateNode(node.right, unitRatios, identValues);
 			return dividend - divisor * Math.floor(dividend / divisor);
 		}
-		case "Pow": return evaluateNode(node.base, context) ** evaluateNode(node.exponent, context);
+		case "Pow": return evaluateNode(node.base, unitRatios, identValues) ** evaluateNode(node.exponent, unitRatios, identValues);
 		case "SignedPow": {
-			const base = evaluateNode(node.base, context);
-			return Math.abs(base) ** evaluateNode(node.exponent, context) * Math.sign(base);
+			const base = evaluateNode(node.base, unitRatios, identValues);
+			return Math.abs(base) ** evaluateNode(node.exponent, unitRatios, identValues) * Math.sign(base);
 		}
-		case "Min": return Math.min(...node.args.map((arg) => evaluateNode(arg, context)));
-		case "Max": return Math.max(...node.args.map((arg) => evaluateNode(arg, context)));
-		case "Clamp": return Math.max(evaluateNode(node.minimum, context), Math.min(evaluateNode(node.value, context), evaluateNode(node.maximum, context)));
+		case "Min": return Math.min(...node.args.map((arg) => evaluateNode(arg, unitRatios, identValues)));
+		case "Max": return Math.max(...node.args.map((arg) => evaluateNode(arg, unitRatios, identValues)));
+		case "Clamp": return Math.max(evaluateNode(node.minimum, unitRatios, identValues), Math.min(evaluateNode(node.value, unitRatios, identValues), evaluateNode(node.maximum, unitRatios, identValues)));
 		case "Abs":
 		case "Sign":
 		case "Sin":
 		case "Cos":
 		case "Tan":
-		case "Acos": return UNARY[node._tag].fn(evaluateNode(node.argument, context));
-		case "Atan2": return Math.atan2(evaluateNode(node.y, context), evaluateNode(node.x, context));
+		case "Acos": return UNARY[node._tag].fn(evaluateNode(node.argument, unitRatios, identValues));
+		case "Atan2": return Math.atan2(evaluateNode(node.y, unitRatios, identValues), evaluateNode(node.x, unitRatios, identValues));
 	}
 };
 /**
@@ -308,6 +302,16 @@ const formatConstant = (node, insideMath, context) => {
 	return node.unit !== void 0 ? `${text}${node.unit}` : text;
 };
 const wrapOperand = (node, serialized) => node._tag === "Add" || node._tag === "Subtract" ? `(${serialized})` : serialized;
+/**
+* A fallback renders under the normal top-level rules — `var()`
+* substitution is token-level, so an arithmetic fallback carries its own
+* nested `calc()` wrapper rather than leaning on the surrounding context.
+*/
+const serializeFallback = (node, context) => {
+	const wrap = needsCalcWrap(node);
+	const body = serializeNode(node, wrap, context);
+	return wrap ? `calc(${body})` : body;
+};
 const hasNegativeCoefficient = (node) => {
 	if (isConstant(node)) return node.value < 0;
 	if (node._tag === "Multiply" || node._tag === "Divide") return isConstant(node.left) && node.left.value < 0;
@@ -332,7 +336,7 @@ const serializeNegated = (node, insideMath, context) => {
 const serializeNode = (node, insideMath, context) => {
 	switch (node._tag) {
 		case "Constant": return formatConstant(node, insideMath, context);
-		case "Ref": return `var(--${node.name})`;
+		case "Ref": return node.fallback === void 0 ? `var(--${node.name})` : `var(--${node.name}, ${serializeFallback(node.fallback, context)})`;
 		case "Ident": return node.name;
 		case "Add": {
 			let out = "";
@@ -382,7 +386,11 @@ const nodeEquals = (a, b) => {
 			const other = b;
 			return a.value === other.value && a.unit === other.unit && specEquals(a.precision, other.precision);
 		}
-		case "Ref": return a.name === b.name;
+		case "Ref": {
+			const other = b;
+			if (a.name !== other.name) return false;
+			return a.fallback === void 0 || other.fallback === void 0 ? a.fallback === other.fallback : nodeEquals(a.fallback, other.fallback);
+		}
 		case "Ident": return a.name === b.name;
 		case "Add": return nodeArrayEquals(a.terms, b.terms);
 		case "Subtract":
@@ -428,7 +436,7 @@ const nodeHash = (node) => {
 			const unit = node.unit === void 0 ? 0 : hashString(node.unit);
 			return combine(hashString("Constant"), combine(combine(hashNumber(node.value), precision), unit));
 		}
-		case "Ref": return combine(hashString("Ref"), hashString(node.name));
+		case "Ref": return combine(combine(hashString("Ref"), hashString(node.name)), node.fallback === void 0 ? 0 : nodeHash(node.fallback));
 		case "Ident": return combine(hashString("Ident"), hashString(node.name));
 		case "Add": return hashNodeArray("Add", node.terms);
 		case "Subtract":
@@ -463,6 +471,9 @@ var CalcImpl = class extends Pipeable {
 		this.node = node;
 		this.refSet = refSet;
 	}
+	get [RefsTypeId]() {
+		return this.refSet;
+	}
 	[EqualTypeId](that) {
 		return isCalc$1(that) && nodeEquals(this.node, nodeOf(that));
 	}
@@ -483,36 +494,38 @@ const isCalc$1 = (u) => typeof u === "object" && u !== null && CalcTypeId in u;
 const nodeOf = (expr) => expr.node;
 /** @internal */
 const refsOf = (expr) => expr.refSet;
-const collectIdents = (node, into) => {
+const collectTokens = (node, intoUnits, intoIdents) => {
 	switch (node._tag) {
 		case "Ident":
-			into.add(node.name);
+			intoIdents?.add(node.name);
 			return;
 		case "Constant":
+			if (node.unit !== void 0) intoUnits?.add(node.unit);
+			return;
 		case "Ref": return;
 		case "Add":
-			for (const term of node.terms) collectIdents(term, into);
+			for (const term of node.terms) collectTokens(term, intoUnits, intoIdents);
 			return;
 		case "Min":
 		case "Max":
-			for (const arg of node.args) collectIdents(arg, into);
+			for (const arg of node.args) collectTokens(arg, intoUnits, intoIdents);
 			return;
 		case "Subtract":
 		case "Multiply":
 		case "Divide":
 		case "Mod":
-			collectIdents(node.left, into);
-			collectIdents(node.right, into);
+			collectTokens(node.left, intoUnits, intoIdents);
+			collectTokens(node.right, intoUnits, intoIdents);
 			return;
 		case "Pow":
 		case "SignedPow":
-			collectIdents(node.base, into);
-			collectIdents(node.exponent, into);
+			collectTokens(node.base, intoUnits, intoIdents);
+			collectTokens(node.exponent, intoUnits, intoIdents);
 			return;
 		case "Clamp":
-			collectIdents(node.minimum, into);
-			collectIdents(node.value, into);
-			collectIdents(node.maximum, into);
+			collectTokens(node.minimum, intoUnits, intoIdents);
+			collectTokens(node.value, intoUnits, intoIdents);
+			collectTokens(node.maximum, intoUnits, intoIdents);
 			return;
 		case "Abs":
 		case "Sign":
@@ -520,18 +533,24 @@ const collectIdents = (node, into) => {
 		case "Cos":
 		case "Tan":
 		case "Acos":
-			collectIdents(node.argument, into);
+			collectTokens(node.argument, intoUnits, intoIdents);
 			return;
 		case "Atan2":
-			collectIdents(node.y, into);
-			collectIdents(node.x, into);
+			collectTokens(node.y, intoUnits, intoIdents);
+			collectTokens(node.x, intoUnits, intoIdents);
 			return;
 	}
 };
 /** @internal */
 const identsOf = (node) => {
 	const set = /* @__PURE__ */ new Set();
-	collectIdents(node, set);
+	collectTokens(node, void 0, set);
+	return set;
+};
+/** @internal */
+const unitsOf = (node) => {
+	const set = /* @__PURE__ */ new Set();
+	collectTokens(node, set, void 0);
 	return set;
 };
 const makeCalc = (node, refSet) => new CalcImpl(node, refSet);
@@ -557,16 +576,39 @@ function dimension(value, unit, kind, precision) {
 	return makeCalc(constantNode(value, precision === void 0 ? void 0 : toSpec(precision), unit, kind), EMPTY_REFS);
 }
 const refCache = /* @__PURE__ */ new Map();
+const lowerFallback = (fb) => {
+	if (typeof fb === "number") return constantNode(fb, void 0);
+	if (isVar(fb)) return lowerRead(fb);
+	invariant(isCalc$1(fb), "Calc var fallback must be a number, a Calc expression, or a Var read");
+	return nodeOf(fb);
+};
+const lowerRead = (read) => {
+	invariant(declaredTypeOf(read) !== "color", "A color-declared read cannot lift into calc; use Color.var");
+	const fb = fallbackOf(read);
+	return fb === void 0 ? {
+		_tag: "Ref",
+		name: nameOf(read)
+	} : {
+		_tag: "Ref",
+		name: nameOf(read),
+		fallback: lowerFallback(fb)
+	};
+};
 /** @internal */
-function ref$1(name) {
-	const cached = refCache.get(name);
+function ref(read) {
+	if (typeof read !== "string") {
+		invariant(declaredTypeOf(read) !== "color", "A color-declared read cannot lift into calc; use Color.var");
+		if (fallbackOf(read) === void 0) return ref(nameOf(read));
+		return makeCalc(lowerRead(read), refsOfVar(read));
+	}
+	const cached = refCache.get(read);
 	if (cached) return cached;
-	invariant(name.length > 0, "Reference name must be a non-empty string");
+	invariant(read.length > 0, "Reference name must be a non-empty string");
 	const expr = makeCalc({
 		_tag: "Ref",
-		name
-	}, /* @__PURE__ */ new Set([name]));
-	refCache.set(name, expr);
+		name: read
+	}, /* @__PURE__ */ new Set([read]));
+	refCache.set(read, expr);
 	return expr;
 }
 /**
@@ -709,16 +751,16 @@ const bind$1 = dual(2, (expr, bindings) => {
 	return makeCalc(substituteNode(nodeOf(expr), collected.nodeBindings), collected.refSet);
 });
 /** @internal */
-function solve$1(expr, bindings, context) {
+function solve$1(expr, options) {
 	let node = nodeOf(expr);
 	let remaining = refsOf(expr);
-	if (bindings !== void 0) {
-		const collected = collectBindings(remaining, bindings);
+	if (options?.bindings !== void 0) {
+		const collected = collectBindings(remaining, options.bindings);
 		node = substituteNode(node, collected.nodeBindings);
 		remaining = collected.refSet;
 	}
-	invariant(remaining.size === 0, "Cannot convert expression to number: unbound references remain");
-	return evaluateNode(node, context ?? {});
+	invariant(remaining.size === 0, "Cannot convert expression to number: unbound variables remain");
+	return evaluateNode(node, options?.units ?? {}, options?.idents ?? {});
 }
 /** @internal */
 function serialize$1(expr, options) {
@@ -731,14 +773,18 @@ function serialize$1(expr, options) {
 	return serializeTop(node, precision);
 }
 /** @internal */
-function refs$1(expr) {
+function refs(expr) {
 	return refsOf(expr);
 }
 /** @internal */
-function channels$1(expr) {
+function idents$1(expr) {
 	return identsOf(nodeOf(expr));
 }
 /** @internal */
+function units$1(expr) {
+	return unitsOf(nodeOf(expr));
+}
+/** @internal */
 const equals$1 = dual(2, (self, that) => equals$2(self, that));
 //#endregion
 //#region src/calc/calc.ts
@@ -748,11 +794,11 @@ var calc_exports = /* @__PURE__ */ __exportAll({
 	add: () => add,
 	atan2: () => atan2,
 	bind: () => bind,
-	channels: () => channels,
 	clamp: () => clamp,
 	cos: () => cos,
 	divide: () => divide,
 	equals: () => equals,
+	idents: () => idents,
 	isCalc: () => isCalc,
 	lerp: () => lerp,
 	max: () => max,
@@ -761,15 +807,16 @@ var calc_exports = /* @__PURE__ */ __exportAll({
 	multiply: () => multiply,
 	of: () => of,
 	pow: () => pow,
-	ref: () => ref,
-	refs: () => refs,
 	serialize: () => serialize,
 	sign: () => sign,
 	signedPow: () => signedPow,
 	sin: () => sin,
 	solve: () => solve,
 	subtract: () => subtract,
-	tan: () => tan
+	tan: () => tan,
+	units: () => units,
+	var: () => _var,
+	vars: () => vars
 });
 /**
 * Checks if a value is a `Calc`.
@@ -798,29 +845,12 @@ const isCalc = isCalc$1;
 * @example
 * ```ts
 * const k = Calc.of(0.8377580409572781, Precision.significant(10))
-* Calc.serialize(Calc.multiply(k, Calc.ref('t'))) // 'calc(0.837758041 * var(--t))'
+* Calc.serialize(Calc.multiply(k, Calc.var('t'))) // 'calc(0.837758041 * var(--t))'
 * ```
 * @since 0.1.0
 */
 const of = of$1;
-/**
-* Creates a reference to an unbound name. References serialize as
-* `var(--name)` and are the channel through which expressions read CSS
-* custom properties; `bind` replaces them with values or other
-* expressions.
-*
-* Repeated calls with the same name return the same instance.
-*
-* @param name - The reference name, without the `--` prefix. Must be non-empty.
-* @returns A `Calc` with `name` as its one unbound reference.
-* @throws `Error` when `name` is empty.
-* @example
-* ```ts
-* Calc.serialize(Calc.ref('width')) // 'var(--width)'
-* ```
-* @since 0.1.0
-*/
-const ref = ref$1;
+const _var = ref;
 /**
 * Adds expressions. Constant operands fold at construction.
 *
@@ -829,11 +859,11 @@ const ref = ref$1;
 * `a + (-2)` serializes as `a - 2`.
 *
 * @param a - The first operand.
-* @param b - The second operand.
-* @returns The sum, with the operands' references unioned.
+* @param b - The second operand, sharing `a`'s dimension.
+* @returns The sum, with the operands' variables, results, and requirements unioned.
 * @example
 * ```ts
-* Calc.serialize(Calc.add(Calc.ref('x'), 10)) // 'calc(var(--x) + 10)'
+* Calc.serialize(Calc.add(Calc.var('x'), 10)) // 'calc(var(--x) + 10)'
 * ```
 * @since 0.1.0
 */
@@ -842,54 +872,64 @@ const add = add$1;
 * Subtracts `right` from `left`. Constant operands fold at construction.
 *
 * @param left - The minuend.
-* @param right - The subtrahend.
-* @returns The difference, with the operands' references unioned.
+* @param right - The subtrahend, sharing `left`'s dimension.
+* @returns The difference, with the operands' variables, results, and requirements unioned.
 * @since 0.1.0
 */
 const subtract = subtract$1;
 /**
 * The CSS `mod()` of `dividend` and `divisor` — the remainder that takes the
 * sign of the divisor (the floored modulo), so `mod(x, 360)` lands in
-* `[0, 360)` for a positive divisor. Same-kind operands, as `subtract`;
+* `[0, 360)` for a positive divisor. Same-dimension operands, as `subtract`;
 * constant operands fold at construction.
 *
 * @param dividend - The value to reduce.
-* @param divisor - The modulus, sharing `dividend`'s kind.
-* @returns The modulo, with the operands' references unioned.
+* @param divisor - The modulus, sharing `dividend`'s dimension.
+* @returns The modulo, with the operands' variables, results, and requirements unioned.
 * @example
 * ```ts
-* Calc.serialize(Calc.mod(Calc.ref('h'), 360)) // 'mod(var(--h), 360)'
+* Calc.serialize(Calc.mod(Calc.var('h'), 360)) // 'mod(var(--h), 360)'
 * ```
 * @since 0.2.0
 */
 const mod = mod$1;
 /**
-* Multiplies expressions. Constant operands fold at construction.
+* Multiplies expressions. One factor must be a `<number>`; the dimensioned
+* factor's result rides through. Constant operands fold at construction.
 *
 * Addition and subtraction operands are parenthesized when serialized
 * under a product: `(a + b) * c`.
 *
 * @param left - The first factor.
 * @param right - The second factor.
-* @returns The product, with the operands' references unioned.
+* @returns The product, carrying the dimensioned factor's result and both operands' variables and requirements.
 * @since 0.1.0
 */
 const multiply = multiply$1;
 /**
 * Divides `left` by `right`. Constant operands fold at construction.
 *
+* Dividing by a `<number>` keeps the dividend's result; dividing two
+* same-dimension expressions produces a `<number>` (`Unit.None`) — the
+* units cancel. The requirements discharge only where folding guarantees
+* they can: a same-single-unit division always folds once bound, so its
+* requirement drops; anything mixed keeps both operands'.
+*
 * @param left - The dividend.
-* @param right - The divisor.
-* @returns The quotient, with the operands' references unioned.
+* @param right - The divisor: a number, or an expression sharing `left`'s dimension.
+* @returns The quotient, with the operands' variables unioned.
 * @since 0.1.0
 */
 const divide = divide$1;
 /**
-* Raises `base` to `exponent`. Serializes as the CSS `pow()` function.
+* Raises `base` to `exponent`. Serializes as the CSS `pow()` function,
+* whose operands are `<number>`s — so both take number-result expressions,
+* which may carry identifier requirements (`pow(l, 2.2)` gamma-adjusts a
+* relative-color channel).
 *
 * @param base - The base.
 * @param exponent - The exponent.
-* @returns The power, with the operands' references unioned.
+* @returns The power, a `<number>`, with the operands' variables and requirements unioned.
 * @since 0.1.0
 */
 const pow = pow$1;
@@ -900,7 +940,7 @@ const pow = pow$1;
 *
 * @param base - The base.
 * @param exponent - The exponent.
-* @returns The signed power, with the operands' references unioned.
+* @returns The signed power, a `<number>`, with the operands' variables and requirements unioned.
 * @since 0.1.0
 */
 const signedPow = signedPow$1;
@@ -908,8 +948,8 @@ const signedPow = signedPow$1;
 * The minimum of the operands. Serializes as the CSS `min()` function.
 *
 * @param a - The first operand.
-* @param b - The second operand.
-* @returns The minimum, with the operands' references unioned.
+* @param b - The second operand, sharing `a`'s dimension.
+* @returns The minimum, with the operands' variables, results, and requirements unioned.
 * @since 0.1.0
 */
 const min = min$1;
@@ -917,8 +957,8 @@ const min = min$1;
 * The maximum of the operands. Serializes as the CSS `max()` function.
 *
 * @param a - The first operand.
-* @param b - The second operand.
-* @returns The maximum, with the operands' references unioned.
+* @param b - The second operand, sharing `a`'s dimension.
+* @returns The maximum, with the operands' variables, results, and requirements unioned.
 * @since 0.1.0
 */
 const max = max$1;
@@ -927,12 +967,12 @@ const max = max$1;
 * `clamp()` function, with the CSS argument order `(min, value, max)`.
 *
 * @param minimum - The lower bound.
-* @param value - The value to clamp.
-* @param maximum - The upper bound.
-* @returns The clamped expression, with the operands' references unioned.
+* @param value - The value to clamp, sharing `minimum`'s dimension.
+* @param maximum - The upper bound, likewise.
+* @returns The clamped expression, with the operands' variables, results, and requirements unioned.
 * @example
 * ```ts
-* Calc.serialize(Calc.clamp(-1, Calc.ref('u'), 1)) // 'clamp(-1, var(--u), 1)'
+* Calc.serialize(Calc.clamp(-1, Calc.var('u'), 1)) // 'clamp(-1, var(--u), 1)'
 * ```
 * @since 0.1.0
 */
@@ -940,12 +980,13 @@ const clamp = clamp$1;
 /**
 * Linear interpolation from `a` to `b` by `t`. This is sugar, not a node:
 * it desugars to `(1 - t) * a + t * b`, and serializes as that expanded
-* form.
+* form. `t` contributes its variables and requirements but never the
+* result — the endpoints alone fix the dimension.
 *
 * @param a - The value at `t = 0`.
-* @param b - The value at `t = 1`.
-* @param t - The interpolation parameter.
-* @returns The interpolated expression, with the operands' references unioned.
+* @param b - The value at `t = 1`, sharing `a`'s dimension.
+* @param t - The interpolation parameter, a `<number>`.
+* @returns The interpolated expression, with the operands' variables unioned.
 * @since 0.1.0
 */
 const lerp = lerp$1;
@@ -953,64 +994,68 @@ const lerp = lerp$1;
 * The absolute value. Serializes as the CSS `abs()` function.
 *
 * @param argument - The operand.
-* @returns The absolute value expression.
+* @returns The absolute value expression, preserving the operand's result.
 * @since 0.1.0
 */
 const abs = abs$1;
 /**
-* The sign (`-1`, `0`, or `1`). Serializes as the CSS `sign()` function.
+* The sign (`-1`, `0`, or `1`). Serializes as the CSS `sign()` function,
+* which accepts a calculation of any dimension and returns a `<number>` —
+* so any operand is accepted here.
 *
-* @param argument - The operand.
-* @returns The sign expression.
+* @param argument - The operand, of any dimension.
+* @returns The sign, a `<number>`, carrying the operand's requirements.
 * @since 0.1.0
 */
 const sign = sign$1;
 /**
 * The sine of its argument. Serializes as the CSS `sin()` function, which
 * accepts an `<angle>` or a plain number treated as radians — so this takes
-* either an angle-kind expression or a number, and returns a number.
+* either an angle expression or a number, and returns a number.
 *
 * @param argument - An angle, or a plain number in radians.
-* @returns The sine, a `<number>`, carrying the argument's units.
+* @returns The sine, a `<number>`, carrying the argument's requirements.
 * @since 0.1.0
 */
 const sin = sin$1;
 /**
 * The cosine of its argument. Serializes as the CSS `cos()` function, which
 * accepts an `<angle>` or a plain number treated as radians — so this takes
-* either an angle-kind expression or a number, and returns a number.
+* either an angle expression or a number, and returns a number.
 *
 * @param argument - An angle, or a plain number in radians.
-* @returns The cosine, a `<number>`, carrying the argument's units.
+* @returns The cosine, a `<number>`, carrying the argument's requirements.
 * @since 0.1.0
 */
 const cos = cos$1;
 /**
 * The tangent of its argument. Serializes as the CSS `tan()` function, which
 * accepts an `<angle>` or a plain number treated as radians. Paired with
-* `atan2`, `tan(atan2(a, b))` divides two same-kind dimensions to a `<number>` —
-* the length ratio that works where `a / b` does not, since Firefox does not
-* yet support `<length> / <length>` in `calc()`.
+* `atan2`, `tan(atan2(a, b))` divides two same-dimension expressions to a
+* `<number>` — the length ratio that works where `a / b` does not, since
+* Firefox does not yet support `<length> / <length>` in `calc()`.
 *
 * @param argument - An angle, or a plain number in radians.
-* @returns The tangent, a `<number>`, carrying the argument's units.
+* @returns The tangent, a `<number>`, carrying the argument's requirements.
 * @since 0.2.0
 */
 const tan = tan$1;
 /**
-* The arccosine of a value in `[-1, 1]`, an `<angle>` in radians (CSS's
-* `acos()` returns an `<angle>`). Solving evaluates `Math.acos`, in radians.
+* The arccosine of a value in `[-1, 1]`, an `<angle>` in radians — the
+* result is `Unit.Rad`, matching what solving evaluates (`Math.acos`) and
+* what constant folding emits (`rad` constants); CSS's `acos()` returns an
+* `<angle>` and serialization is unchanged.
 *
-* Because the result is angle-kind, it composes only with other angles: divide
+* Because the result is an angle, it composes only with other angles: divide
 * or scale it by a number, and add or subtract an `Angle.rad(...)` phase. A
 * plain number added to it is a type error — supply the phase as an angle.
 *
 * @param argument - The cosine value, in `[-1, 1]`.
-* @returns The arccosine, an `<angle>`, carrying the argument's units.
+* @returns The arccosine in radians, carrying the argument's requirements.
 * @example
 * ```ts
 * const phase = Angle.rad(2.0943951)
-* Calc.serialize(Calc.cos(Calc.subtract(Calc.divide(Calc.acos(Calc.ref('u')), 3), phase)))
+* Calc.serialize(Calc.cos(Calc.subtract(Calc.divide(Calc.acos(Calc.var('u')), 3), phase)))
 * // 'cos(acos(var(--u)) / 3 - 2.0944rad)'
 * ```
 * @since 0.1.0
@@ -1018,14 +1063,15 @@ const tan = tan$1;
 const acos = acos$1;
 /**
 * The angle, in radians, of the vector from the origin to `(x, y)` — CSS's
-* `atan2()`, which returns an `<angle>`. The operands must share a kind (two
-* numbers, two lengths, two angles); their units cancel in the ratio, so
-* `tan(atan2(a, b))` recovers `a / b` as a `<number>` and is the portable way to
-* divide two `<length>`s.
+* `atan2()`, which returns an `<angle>`; the result is `Unit.Rad`, as
+* `acos`. The operands must share a dimension (two numbers, two lengths,
+* two angles); their units cancel in the ratio, so `tan(atan2(a, b))`
+* recovers `a / b` as a `<number>` and is the portable way to divide two
+* `<length>`s.
 *
 * @param y - The vertical component.
-* @param x - The horizontal component, sharing `y`'s kind.
-* @returns The angle, an `<angle>`, with the operands' units unioned.
+* @param x - The horizontal component, sharing `y`'s dimension.
+* @returns The angle in radians, with the operands' variables and requirements unioned.
 * @example
 * ```ts
 * const ratio = Calc.tan(Calc.atan2(Calc.subtract(Length.vw(100), Length.px(320)), Length.px(160)))
@@ -1039,11 +1085,11 @@ const solve = solve$1;
 /**
 * Renders an expression as CSS text. Arithmetic gets a `calc()` wrapper;
 * function forms (`min`, `clamp`, `sin`, ...) and leaves stand alone.
-* References render as `var(--name)`.
+* Variables render as `var(--name)`.
 *
 * Bindings in `options` are applied first and may be partial — this is
 * the serialize half of the solve/serialize duality, and unbound
-* references are the values left for the browser. Constants render with
+* variables are the values left for the browser. Constants render with
 * their annotated precision, or the context `precision` option (default
 * `Precision.decimals(5)`). Constants equal to pi render as the CSS
 * constant `pi` where a math function surrounds them.
@@ -1053,7 +1099,7 @@ const solve = solve$1;
 * @returns Deterministic CSS text.
 * @example
 * ```ts
-* const fluid = Calc.add(10, Calc.ref('runtime'))
+* const fluid = Calc.add(10, Calc.var('runtime'))
 * Calc.serialize(fluid) // 'calc(10 + var(--runtime))'
 * Calc.serialize(fluid, { bindings: { runtime: 4 } }) // '14'
 * ```
@@ -1061,35 +1107,57 @@ const solve = solve$1;
 */
 const serialize = serialize$1;
 /**
-* The expression's unbound reference names.
+* The expression's unbound variable names — bare names, the value-level
+* mirror of the read identities in `Vars`. A fallback chain's names are
+* included: `var(--x, var(--y))` reads both.
 *
 * @param expr - The expression to inspect.
-* @returns The set of unbound reference names.
+* @returns The set of unbound variable names.
 * @since 0.1.0
 */
-const refs = refs$1;
+const vars = refs;
 /**
-* The channel-keyword tokens the expression reads — the `Channel` keywords a
-* relative color introduces (`l`, `c`, `h`, ...). Empty for an expression with
-* no channel keywords.
+* The bare-identifier tokens the expression reads — leaves that serialize
+* as themselves (`l`, not `var(--l)`) and are resolved by the CSS construct
+* around them, the `Channel` keywords being the only source today. Empty
+* for an expression with none.
 *
-* This is the runtime companion to the `Leaves`-level scoping that `solve`'s
-* context requires: `channels` reports which values a context must supply,
-* exactly as `refs` reports the custom properties a binding must, and — unlike
-* a `Calc`'s `Kind`/`Leaves` type — survives on a `Calc<Refs, Kind, unknown>`
-* whose leaves have been erased. Channel keywords are not references, so `refs`
-* never lists them and they never reach a `Stylesheet`'s dependency report.
+* The runtime mirror of the `Ident` brands in `Requires`: it reports which
+* values the `idents` section of `solve`'s options must supply, exactly as
+* `vars` reports what `bindings` must — and, unlike the type parameter, it
+* survives on a `Calc<Vars, Unit.Any, unknown>` whose requirements have
+* been erased. Identifiers are not variables, so `vars` never lists them
+* and they never reach a `Stylesheet`'s dependency report.
 *
 * @param expr - The expression to inspect.
-* @returns The set of channel-keyword tokens the expression reads.
+* @returns The set of bare-identifier tokens the expression reads.
 * @example
 * ```ts
-* Calc.channels(Calc.multiply(Channel.L, 0.8)) // Set { 'l' }
-* Calc.channels(Calc.ref('x')) // Set {}
+* Calc.idents(Calc.multiply(Channel.L, 0.8)) // Set { 'l' }
+* Calc.idents(Calc.var('x')) // Set {}
 * ```
 * @since 0.2.0
 */
-const channels = channels$1;
+const idents = idents$1;
+/**
+* The unit tokens the expression's dimensioned constants carry (`'vw'`,
+* `'px'`, `'%'`). Empty for a unit-free expression.
+*
+* The runtime mirror of the `Unit` brands in `Requires`: it reports which
+* ratios the `units` section of `solve`'s options may need to supply, and —
+* unlike the type parameter — it survives on a `Calc<Vars, Unit.Any, unknown>`
+* whose requirements have been erased. Pre-satisfied units (`px`, `rad`,
+* `deg`) are reported too; they lower with no entry.
+*
+* @param expr - The expression to inspect.
+* @returns The set of unit tokens the expression's constants carry.
+* @example
+* ```ts
+* Calc.units(Calc.subtract(Length.vw(100), Length.px(320))) // Set { 'vw', 'px' }
+* ```
+* @since 0.4.0
+*/
+const units = units$1;
 const equals = equals$1;
 //#endregion
 //#region src/calc/precision.ts
@@ -1140,6 +1208,6 @@ const decimals = decimals$1;
 */
 const significant = significant$1;
 //#endregion
-export { EMPTY_REFS as C, toCalc as S, nodeOf as _, multiply as a, serializeNode as b, bind$1 as c, ident as d, identsOf as f, nodeHash as g, nodeEquals as h, mod as i, collectBindings as l, needsCalcWrap as m, add as n, sign as o, isCalc$1 as p, calc_exports as r, subtract as s, precision_exports as t, dimension as u, refsOf as v, unionRefs as w, substituteNode as x, serialize$1 as y };
+export { toCalc as S, nodeOf as _, multiply as a, serializeNode as b, bind$1 as c, ident as d, identsOf as f, nodeHash as g, nodeEquals as h, mod as i, collectBindings as l, needsCalcWrap as m, add as n, sign as o, isCalc$1 as p, calc_exports as r, subtract as s, precision_exports as t, dimension as u, refsOf as v, substituteNode as x, serialize$1 as y };
 
-//# sourceMappingURL=calc-Cih4o2r7.mjs.map
+//# sourceMappingURL=calc-Uwbxd7CS.mjs.map