@animus-ui/system 0.1.2 → 0.1.4

package/dist/index.js

@@ -1,6 +1,6 @@
 import { n as createClassResolver, r as createComponent, t as createComposedFamily } from "./createComposedFamily-DJ2aqfqN.js";
 import { compose } from "./compose.js";
-import { a as borderShorthand, c as numericOrStringScale, i as gridItemRatio, l as numericScale, n as size, o as createTransform, r as gridItem, s as createScale, t as percentageOrAbsolute, u as stringScale } from "./size-CusLCguT.js";
+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-CDBRRzkb.js";
 //#region src/utils/deepMerge.ts
 /**
 * Deep merge utility — replaces lodash.merge for variant accumulation.
@@ -229,6 +229,20 @@ var Animus = class extends AnimusWithBase {
 	}
 };
 //#endregion
+//#region src/asset.ts
+/** The reserved scheme marking an unsubstituted asset reference. */
+const ASSET_PLACEHOLDER_PREFIX = "animus-asset:";
+/**
+* Reference a package-owned asset (e.g. a font file) by module specifier:
+* `asset('@acme/tokens/fonts/inter.woff2')`. Resolution — aliases, exports
+* maps, `base`, content hashing — belongs to the host bundler; this function
+* only brands the specifier into its placeholder form. A literal URL string
+* (`'/fonts/inter.woff2'`) remains the pass-through alternative.
+*/
+function asset(specifier) {
+	return ASSET_PLACEHOLDER_PREFIX + specifier;
+}
+//#endregion
 //#region src/conditions.ts
 /**
 * Built-in condition aliases (design D8, increment 06).
@@ -529,11 +543,15 @@ const BUILT_IN_SELECTORS = {
 /**
 * Merge user-provided selectors with built-in defaults.
 * User selectors override built-in aliases of the same name.
-* New aliases get an order value based on their position (500+).
+* New aliases allocate orders CONTINUING from the highest existing order
+* (floored at 490, so the first user alias lands at 500) rather than
+* restarting at 500 each call (mirrors `mergeConditions`) — aliases from
+* successive `.addSelectors()`/`extend()` merges must not collide on
+* order 500.
 */
 function mergeSelectors(base, custom) {
 	const merged = { ...base };
-	let nextOrder = 500;
+	let nextOrder = Math.max(490, ...Object.values(merged).map((s) => s.order)) + 10;
 	for (const [key, selector] of Object.entries(custom)) if (key in merged) merged[key] = {
 		selector,
 		order: merged[key].order
@@ -567,13 +585,69 @@ function serializeSelectorMap(map) {
 }
 //#endregion
 //#region src/SystemBuilder.ts
+const snapshotTransformBySource = /* @__PURE__ */ new WeakMap();
+function snapshotTransform(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 });
+	const sourceText = source.toString();
+	Object.defineProperty(wrapper, "toString", { value: () => sourceText });
+	const named = source;
+	if (named.transformName !== void 0) Object.defineProperty(wrapper, "transformName", {
+		value: named.transformName,
+		enumerable: true
+	});
+	if (named.transformSource !== void 0) Object.defineProperty(wrapper, "transformSource", {
+		value: named.transformSource,
+		enumerable: true
+	});
+	Object.freeze(wrapper);
+	snapshotTransformBySource.set(source, wrapper);
+	return wrapper;
+}
+/**
+* The one runtime discriminator for a library bundle: `system.toConfig`
+* being callable. A built system instance also has a `.system()` CHAIN
+* METHOD, so presence of a `system` key alone cannot discriminate the two
+* shapes. Both builders' `from()` use this guard; the QuickJS capture
+* script in the Rust system-loader mirrors it by necessity (it cannot
+* import TS) and points back here.
+*/
+function isLibraryBundle(value) {
+	const system = value?.system;
+	return Boolean(system) && typeof system?.toConfig === "function";
+}
 function orderedPropertiesEqual(existing, incoming) {
 	if (existing === incoming) return true;
 	if (!existing || !incoming || existing.length !== incoming.length) return false;
 	return existing.every((property, index) => property === incoming[index]);
 }
-function arePropDefinitionsEqual(existing, incoming) {
-	return existing.property === incoming.property && orderedPropertiesEqual(existing.properties, incoming.properties) && existing.scale === incoming.scale && existing.variable === incoming.variable && existing.negative === incoming.negative && existing.strict === incoming.strict && existing.currentVar === incoming.currentVar && existing.transform === incoming.transform;
+function scalesEqual(existing, incoming) {
+	if (existing === incoming) return true;
+	if (!existing || !incoming || typeof existing !== typeof incoming) return false;
+	if (typeof existing === "string" || typeof incoming === "string") return false;
+	if (Array.isArray(existing) || Array.isArray(incoming)) return Array.isArray(existing) && Array.isArray(incoming) && existing.length === incoming.length && existing.every((value, index) => value === incoming[index]);
+	const existingMap = existing;
+	const incomingMap = incoming;
+	const existingKeys = Object.keys(existingMap).sort();
+	return orderedMembersEqual(existingKeys, Object.keys(incomingMap).sort()) && existingKeys.every((key) => existingMap[key] === incomingMap[key]);
+}
+function arePropDefinitionsEqual(existing, incoming, structuralScale = false) {
+	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]);
+}
+/**
+* Divergent-prop error naming both definitions AND both origins — used by the
+* `extend()` merge (sibling/dual-version conflicts, design D3/G4) and by
+* `addGroup`/`addProps` when the colliding entry arrived through `extend()`
+* (origin labels "extended source #n" / "builder state"). When no extension
+* provenance exists, the pre-existing origin-less messages are kept verbatim.
+*/
+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)}".`);
 }
 var SystemBuilder = class SystemBuilder {
 	#propRegistry;
@@ -581,17 +655,107 @@ var SystemBuilder = class SystemBuilder {
 	#selectorRegistry;
 	#includesRegistry;
 	#conditionRegistry;
-	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry, conditionRegistry) {
+	#extendProvenance;
+	#extendCount;
+	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry, conditionRegistry, extendProvenance, extendCount) {
 		this.#propRegistry = propRegistry || {};
 		this.#groupRegistry = groupRegistry || {};
 		this.#selectorRegistry = selectorRegistry || { ...BUILT_IN_SELECTORS };
 		this.#includesRegistry = includesRegistry || [];
 		this.#conditionRegistry = conditionRegistry || { ...BUILT_IN_CONDITIONS };
+		this.#extendProvenance = extendProvenance || /* @__PURE__ */ new Map();
+		this.#extendCount = extendCount || 0;
+	}
+	#originOf(provenanceKey) {
+		const index = this.#extendProvenance.get(provenanceKey);
+		return index === void 0 ? "builder state" : `extended source #${index}`;
+	}
+	from(source) {
+		const instance = isLibraryBundle(source) ? source.system : source;
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, [...this.#includesRegistry, instance], this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
+	}
+	extend(source) {
+		const instance = isLibraryBundle(source) ? source.system : source;
+		const snapshot = instance.getRegistrySnapshot?.();
+		if (!snapshot) throw new Error("extend: source system carries no registry snapshot — it was built by an older @animus-ui/system. Rebuild the source against this version (a lossy toConfig() reconstruction is never substituted).");
+		const sourceIndex = this.#extendCount + 1;
+		const incomingOrigin = `extended source #${sourceIndex}`;
+		const provenance = new Map(this.#extendProvenance);
+		const nextProps = { ...this.#propRegistry };
+		for (const [name, incoming] of Object.entries(snapshot.props)) {
+			if (name in this.#groupRegistry) throw new Error(`extend: prop "${name}" (${incomingOrigin}) collides with an existing group name (${this.#originOf(`group:${name}`)}). Group names and prop names must be disjoint.`);
+			const existing = nextProps[name];
+			if (!existing) {
+				nextProps[name] = incoming;
+				provenance.set(`prop:${name}`, sourceIndex);
+			} else if (!arePropDefinitionsEqual(existing, incoming, true)) throw divergentPropError(name, existing, incoming, this.#originOf(`prop:${name}`), incomingOrigin);
+		}
+		const nextGroups = { ...this.#groupRegistry };
+		for (const [name, incoming] of Object.entries(snapshot.groups)) {
+			const existing = nextGroups[name];
+			if (!existing) {
+				if (name in nextProps) throw new Error(`extend: group name "${name}" (${incomingOrigin}) collides with an existing prop name (${this.#originOf(`prop:${name}`)}). Group names and prop names must be disjoint.`);
+				nextGroups[name] = [...incoming];
+				provenance.set(`group:${name}`, sourceIndex);
+			} else if (!orderedMembersEqual(existing, incoming)) throw new Error(`extend: group "${name}" already registered with different membership. Existing (${this.#originOf(`group:${name}`)}): [${existing.join(", ")}]. Incoming (${incomingOrigin}): [${incoming.join(", ")}].`);
+		}
+		const selectorOverrides = {};
+		const newSelectors = {};
+		for (const [name, incoming] of Object.entries(snapshot.selectors)) {
+			const builtIn = BUILT_IN_SELECTORS[name];
+			if (builtIn && builtIn.selector === incoming.selector) continue;
+			if (name in this.#conditionRegistry) throw new Error(`extend: selector alias "${name}" (${incomingOrigin}) is already registered as a condition alias (${this.#originOf(`condition:${name}`)}); a name resolves through exactly one registry. Pick a distinct name.`);
+			const existing = this.#selectorRegistry[name];
+			if (!existing) {
+				newSelectors[name] = incoming.selector;
+				provenance.set(`selector:${name}`, sourceIndex);
+			} else if (existing.selector !== incoming.selector) {
+				const existingIndex = provenance.get(`selector:${name}`);
+				if (existingIndex === void 0) {
+					selectorOverrides[name] = {
+						selector: incoming.selector,
+						order: existing.order
+					};
+					provenance.set(`selector:${name}`, sourceIndex);
+				} else throw new Error(`extend: selector alias "${name}" already registered with a different selector. Existing (extended source #${existingIndex}): "${existing.selector}". Incoming (${incomingOrigin}): "${incoming.selector}".`);
+			}
+		}
+		const nextSelectors = mergeSelectors({
+			...this.#selectorRegistry,
+			...selectorOverrides
+		}, newSelectors);
+		const conditionOverrides = {};
+		const newConditions = {};
+		for (const [name, incoming] of Object.entries(snapshot.conditions)) {
+			const builtIn = BUILT_IN_CONDITIONS[name];
+			if (builtIn && builtIn.value === incoming.value) continue;
+			if (name in nextSelectors) throw new Error(`extend: condition alias "${name}" (${incomingOrigin}) is already registered as a selector alias (${this.#originOf(`selector:${name}`)}); a name resolves through exactly one registry. Pick a distinct name.`);
+			const existing = this.#conditionRegistry[name];
+			if (!existing) {
+				newConditions[name] = incoming.value;
+				provenance.set(`condition:${name}`, sourceIndex);
+			} else if (existing.value !== incoming.value) {
+				const existingIndex = provenance.get(`condition:${name}`);
+				if (existingIndex === void 0) {
+					conditionOverrides[name] = {
+						value: incoming.value,
+						order: existing.order,
+						kind: incoming.kind
+					};
+					provenance.set(`condition:${name}`, sourceIndex);
+				} else throw new Error(`extend: condition alias "${name}" already registered with a different condition. Existing (extended source #${existingIndex}): "${existing.value}". Incoming (${incomingOrigin}): "${incoming.value}".`);
+			}
+		}
+		const nextConditions = mergeConditions({
+			...this.#conditionRegistry,
+			...conditionOverrides
+		}, newConditions, new Set(Object.keys(nextSelectors)));
+		return new SystemBuilder(nextProps, nextGroups, nextSelectors, [...this.#includesRegistry, instance], nextConditions, provenance, sourceIndex);
 	}
 	addSelectors(selectors) {
 		for (const name of Object.keys(selectors)) if (name in this.#conditionRegistry) throw new Error(`addSelectors: "${name}" is already registered as a condition alias; a name resolves through exactly one registry. Pick a distinct name.`);
 		const merged = mergeSelectors(this.#selectorRegistry, selectors);
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry, this.#conditionRegistry);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
 	}
 	/**
 	* Register condition aliases (`_motionReduce`, `_cardSm`, …) → at-rule
@@ -605,14 +769,17 @@ var SystemBuilder = class SystemBuilder {
 	*/
 	addConditions(conditions) {
 		const merged = mergeConditions(this.#conditionRegistry, conditions, new Set(Object.keys(this.#selectorRegistry)));
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, merged);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, merged, this.#extendProvenance, this.#extendCount);
 	}
 	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 (!arePropDefinitionsEqual(existing, incoming)) throw new Error(`Prop "${key}" already registered with a different definition. Existing: property="${existing.property}", scale="${String(existing.scale)}". Incoming: property="${incoming.property}", scale="${String(incoming.scale)}".`);
+			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)}".`);
+			}
 		}
 		const nextProps = {
 			...this.#propRegistry,
@@ -622,32 +789,37 @@ var SystemBuilder = class SystemBuilder {
 		return new SystemBuilder(nextProps, {
 			...this.#groupRegistry,
 			...newGroup
-		}, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry);
+		}, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
 	}
 	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 (!arePropDefinitionsEqual(existing, incoming)) throw new Error(`Prop "${key}" already registered with a different definition.`);
+			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.`);
+			}
 		}
 		return new SystemBuilder({
 			...this.#propRegistry,
 			...config
-		}, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry);
+		}, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
 	}
 	build() {
-		const animus = new Animus(this.#propRegistry, this.#groupRegistry);
-		const propRegistry = this.#propRegistry;
-		const groupRegistry = this.#groupRegistry;
-		const selectorRegistry = this.#selectorRegistry;
-		const conditionRegistry = this.#conditionRegistry;
+		const animus = new Animus(Object.fromEntries(Object.entries(this.#propRegistry).map(([key, entry]) => [key, { ...entry }])), Object.fromEntries(Object.entries(this.#groupRegistry).map(([key, members]) => [key, [...members]])));
+		const snapshot = createRegistrySnapshot(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#conditionRegistry);
 		const system = Object.assign(animus, { toConfig: () => {
-			return serializeInstance(propRegistry, groupRegistry, selectorRegistry, conditionRegistry);
+			return serializeInstance(snapshot.props, snapshot.groups, snapshot.selectors, snapshot.conditions);
 		} });
-		const createGlobalStyles = ((styles) => ({
+		Object.defineProperty(system, "getRegistrySnapshot", {
+			value: () => snapshot,
+			enumerable: false
+		});
+		const createGlobalStyles = ((styles, options) => ({
 			__brand: "GlobalStyleBlock",
-			styles
+			styles,
+			...options?.fontFaces?.length ? { fontFaces: [...options.fontFaces] } : {}
 		}));
 		const createKeyframes = ((frames) => keyframes(frames));
 		return {
@@ -657,9 +829,41 @@ var SystemBuilder = class SystemBuilder {
 		};
 	}
 };
+/**
+* Freeze the builder's registries into the build-time snapshot (design D7):
+* containers, per-entry objects, and the mutable values nested inside a prop
+* (`properties` arrays, object/array scales) are copies, so neither the
+* builder's onward chaining nor post-build mutation of the instance's public
+* registry fields reaches serialized or merged output. Transform functions
+* are cached immutable forwarding wrappers: behavior survives without keeping
+* mutable serialization metadata live.
+*/
+function createRegistrySnapshot(propRegistry, groupRegistry, selectorRegistry, conditionRegistry) {
+	const props = {};
+	for (const [name, entry] of Object.entries(propRegistry)) {
+		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 });
+		if (copy.transform) copy.transform = snapshotTransform(copy.transform);
+		props[name] = Object.freeze(copy);
+	}
+	const groups = {};
+	for (const [name, members] of Object.entries(groupRegistry)) groups[name] = Object.freeze([...members]);
+	const selectors = {};
+	for (const [name, entry] of Object.entries(selectorRegistry)) selectors[name] = Object.freeze({ ...entry });
+	const conditions = {};
+	for (const [name, entry] of Object.entries(conditionRegistry)) conditions[name] = Object.freeze({ ...entry });
+	return Object.freeze({
+		props: Object.freeze(props),
+		groups: Object.freeze(groups),
+		selectors: Object.freeze(selectors),
+		conditions: Object.freeze(conditions)
+	});
+}
 function serializeInstance(propRegistry, groupRegistry, selectorRegistry, conditionRegistry) {
 	const serialized = {};
 	const transforms = {};
+	const transformOwners = {};
 	for (const [propName, entry] of Object.entries(propRegistry)) {
 		const s = { property: entry.property };
 		if (entry.properties && entry.properties.length > 0) s.properties = [...entry.properties];
@@ -671,8 +875,11 @@ function serializeInstance(propRegistry, groupRegistry, selectorRegistry, condit
 			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;
 			}
 		}
 		if (entry.currentVar) s.currentVar = entry.currentVar;
@@ -692,6 +899,144 @@ function createSystem(config) {
 	return new SystemBuilder(void 0, void 0, void 0, config?.includes ?? []);
 }
 //#endregion
+//#region src/theme/resolveReferences.ts
+/**
+* Late-binding token-reference resolution over the flattened theme (D4,
+* openspec change first-class-extension).
+*
+* Replaces the old single-pass, insertion-order-dependent rewrite: references
+* resolve against the COMPLETE flattened map via depth-first traversal of the
+* reference DAG, so declaration order is never observable (G3), references
+* inside emitted scales resolve into the emitted variable declarations
+* instead of leaking literally into CSS (G2), and a token resolves to the
+* same value whether its scale is emitted or inlined (G1 — an emitted target
+* substitutes as `var()`, which the cascade late-binds to exactly the value
+* the inlined form substitutes directly).
+*
+* Pure module: consumes the flatten pass's maps, returns fresh maps, mutates
+* nothing. Runs in QuickJS — ES built-ins only, no Node/WHATWG APIs.
+*/
+/** Token ref pattern: {scale.key}, {scale.key.sub}, or {path/NN} (opacity). */
+const TOKEN_REF_RE$1 = /\{([^}]+)\}/g;
+/** DFS node states for cycle detection. */
+const UNVISITED = 0;
+const RESOLVING = 1;
+const RESOLVED = 2;
+/** Parse every `{...}` occurrence via matchAll — no shared lastIndex. */
+function parseReferences(value) {
+	const references = [];
+	for (const match of value.matchAll(TOKEN_REF_RE$1)) {
+		const text = match[1];
+		const slashIdx = text.indexOf("/");
+		references.push(slashIdx === -1 ? {
+			text,
+			path: text
+		} : {
+			text,
+			path: text.slice(0, slashIdx),
+			opacity: text.slice(slashIdx + 1)
+		});
+	}
+	return references;
+}
+/**
+* Resolve token references over the complete flattened maps.
+*
+* - `tokenMap`/`variableMap`/`variables` are `flattenTheme`'s outputs: an
+*   emitted path's tokenMap entry is its `var()` indirection and its RAW
+*   authored value is parked in `variables`; a non-emitted path's tokenMap
+*   entry IS its raw value.
+* - Substitution per reference: emitted target → `var(--target)`; non-emitted
+*   target → its resolved literal; `{path/NN}` keeps the existing
+*   `color-mix` output shape (`/0` → `transparent`, `/100` → the base).
+* - Unresolvable target: warn once per missing path, keep the literal — a
+*   SUPPORTED pattern (a kit theme may reference tokens its consumer
+*   provides later). Dangling-reference errors arrive with the explicit
+*   replacement form (D5, increment 04).
+* - Reference cycle: hard error naming the cycle's token paths in traversal
+*   order, regardless of emission flags (emission-invariant failure, G1).
+*/
+function resolveReferences(tokenMap, variableMap, variables) {
+	const paths = Object.keys(tokenMap).sort();
+	const known = new Set(paths);
+	/** The authored (raw) value behind a path — see the contract note above. */
+	const rawValueOf = (path) => {
+		const varName = variableMap[path];
+		if (varName !== void 0 && variables[varName] !== void 0) return variables[varName];
+		return tokenMap[path];
+	};
+	const referencesByPath = /* @__PURE__ */ new Map();
+	for (const path of paths) {
+		const raw = rawValueOf(path);
+		if (typeof raw === "string" && raw.includes("{")) {
+			const references = parseReferences(raw);
+			if (references.length > 0) referencesByPath.set(path, references);
+		}
+	}
+	const state = /* @__PURE__ */ new Map();
+	const resolved = /* @__PURE__ */ new Map();
+	/** Active DFS trail — the cycle report slices it from the revisited node. */
+	const trail = [];
+	const warnedMissing = /* @__PURE__ */ new Set();
+	const substitute = (reference, match) => {
+		if (!known.has(reference.path)) {
+			if (!warnedMissing.has(reference.path)) {
+				warnedMissing.add(reference.path);
+				console.warn(`[animus] Token ref {${reference.text}} — path '${reference.path}' not found in token map`);
+			}
+			return match;
+		}
+		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;
+	};
+	const resolvePath = (path) => {
+		const status = state.get(path) ?? UNVISITED;
+		if (status === RESOLVED) return;
+		if (status === RESOLVING) {
+			const cycle = [...trail.slice(trail.indexOf(path)), path];
+			throw new Error(`build: token reference cycle — ${cycle.map((cyclePath) => `'${cyclePath}'`).join(" → ")}. Reference cycles cannot be resolved; give one of these tokens a literal value.`);
+		}
+		state.set(path, RESOLVING);
+		trail.push(path);
+		const references = referencesByPath.get(path);
+		if (references) {
+			for (const reference of references) if (known.has(reference.path)) resolvePath(reference.path);
+		}
+		let value = rawValueOf(path);
+		if (references) {
+			let index = 0;
+			value = value.replace(TOKEN_REF_RE$1, (match) => substitute(references[index++], match));
+		}
+		trail.pop();
+		state.set(path, RESOLVED);
+		resolved.set(path, value);
+	};
+	for (const path of paths) resolvePath(path);
+	const outTokenMap = {};
+	const outVariables = {};
+	for (const path of paths) {
+		const varName = variableMap[path];
+		if (varName === void 0) outTokenMap[path] = resolved.get(path);
+		else {
+			outTokenMap[path] = tokenMap[path];
+			if (variables[varName] !== void 0) outVariables[varName] = resolved.get(path);
+		}
+	}
+	for (const varName of Object.keys(variables).sort()) if (outVariables[varName] === void 0) outVariables[varName] = variables[varName];
+	return {
+		tokenMap: outTokenMap,
+		variables: outVariables
+	};
+}
+//#endregion
 //#region src/theme/utils.ts
 /** Type guard: true for non-null, non-array objects */
 function isObject(value) {
@@ -796,16 +1141,18 @@ function validateModeAliases(modeName, aliases, nestedColors, flatColorKeys, pre
 * the `:root:not([data-color-mode])` guard while matching no mode block.
 */
 const RESERVED_MODE_NAME = "system";
-/**
-* Theme keys owned by the color-mode options. A scale may not claim them —
-* they are skipped by `flattenTheme` and read back as option objects in
-* `build()`, so a same-named scale would emit zero tokens AND fabricate a
-* manifest field from its values.
-*
-* NOTE: the pre-existing `mode` / `modes` / `breakpoints` structural keys have
-* the same hole and are deliberately NOT covered here (out of scope).
-*/
-const RESERVED_THEME_KEYS = new Set(["systemPreference", "browserColorScheme"]);
+const RESERVED_THEME_KEYS = new Set([
+	"breakpoints",
+	"modes",
+	"mode",
+	"systemPreference",
+	"browserColorScheme",
+	"modeBases",
+	"__emitted",
+	"manifest",
+	"serialize",
+	"varRef"
+]);
 const COLOR_SCHEME_VALUES = new Set([
 	"light",
 	"dark",
@@ -893,6 +1240,33 @@ function resolveColorModeOptions(modeNames, systemPreference, suppliedBrowserCol
 	}
 	return browserColorScheme;
 }
+/**
+* Validate the D6 `basedOn` mode-base map against the MERGED mode set: every
+* key and every base must name a declared mode, self-bases are rejected, and
+* base chains must terminate (a cycle can never fill coverage). Runs at both
+* gates like the other mode options — `addColorModes` (fail fast) and
+* `build()` (authoritative: extend/from composition merges modes without
+* passing through `addColorModes`).
+*/
+function validateModeBases(modeNames, modeBases) {
+	if (!modeBases) return;
+	const declared = new Set(modeNames);
+	const available = `Available modes: ${modeNames.join(", ")}`;
+	for (const [modeName, base] of Object.entries(modeBases)) {
+		if (!declared.has(modeName)) throw new Error(`addColorModes: basedOn names unknown mode '${modeName}'. ${available}`);
+		if (typeof base !== "string" || !declared.has(base)) throw new Error(`addColorModes: basedOn['${modeName}'] references unknown base mode '${String(base)}'. ${available}`);
+		if (base === modeName) throw new Error(`addColorModes: basedOn['${modeName}'] cannot base a mode on itself.`);
+	}
+	for (const start of Object.keys(modeBases)) {
+		const seen = /* @__PURE__ */ new Set();
+		let cursor = start;
+		while (cursor !== void 0) {
+			if (seen.has(cursor)) throw new Error(`addColorModes: basedOn chain cycles — ${[...seen, cursor].map((mode) => `'${mode}'`).join(" → ")}. Give one mode in the chain a covered literal base.`);
+			seen.add(cursor);
+			cursor = modeBases[cursor];
+		}
+	}
+}
 /** Validate all color entries, throwing on invalid values. */
 function validateColors(colors) {
 	for (const [key, value] of Object.entries(colors)) if (isObject(value)) validateColors(value);
@@ -904,7 +1278,12 @@ function createState(theme) {
 		emittedScales: /* @__PURE__ */ new Set(),
 		contextualVars: /* @__PURE__ */ new Map(),
 		contextualVarRegistrations: /* @__PURE__ */ new Map(),
-		hasLegacyManifestSource: false
+		hasLegacyManifestSource: false,
+		extendProvenance: /* @__PURE__ */ new Map(),
+		extendCount: 0,
+		inheritedModes: /* @__PURE__ */ new Set(),
+		inheritedModeAliases: /* @__PURE__ */ new Set(),
+		droppedTokenPaths: /* @__PURE__ */ new Map()
 	};
 }
 function copyState(state, nextTheme) {
@@ -914,12 +1293,101 @@ function copyState(state, nextTheme) {
 		contextualVars: /* @__PURE__ */ new Map(),
 		contextualVarRegistrations: new Map(state.contextualVarRegistrations),
 		...state.carriedManifestV2 ? { carriedManifestV2: { ...state.carriedManifestV2 } } : {},
-		hasLegacyManifestSource: state.hasLegacyManifestSource
+		hasLegacyManifestSource: state.hasLegacyManifestSource,
+		extendProvenance: new Map(state.extendProvenance),
+		extendCount: state.extendCount,
+		inheritedModes: new Set(state.inheritedModes),
+		inheritedModeAliases: new Set(state.inheritedModeAliases),
+		droppedTokenPaths: new Map(state.droppedTokenPaths)
 	};
 	for (const [scale, vars] of state.contextualVars) next.contextualVars.set(scale, [...vars]);
 	return next;
 }
 /**
+* Exact leaf-path flatten for extend() provenance: like `flattenToDotPaths`
+* but WITHOUT the `_` identity-key collapse, so a leaf and a branch can
+* never share a path spelling. A prefix relation between two tracked paths
+* is then a GENUINE structural divergence (one sibling authored a leaf
+* value where the other authored a nested branch) — the review-F1 case that
+* per-leaf value comparison alone cannot see.
+*/
+function flattenLeafPathsExact(object, path) {
+	const result = {};
+	for (const key of Object.keys(object)) {
+		const nextKey = path ? `${path}.${key}` : key;
+		const current = object[key];
+		if (isObject(current)) Object.assign(result, flattenLeafPathsExact(current, nextKey));
+		else result[nextKey] = current;
+	}
+	return result;
+}
+/**
+* Deep copy of plain theme data (records, arrays, primitives). `merge`
+* adopts and MUTATES nested source objects in place, so EVERY builder step
+* copies before folding: a consumed kit's built theme must never be
+* corrupted by composition, and prior builder state must never be shared by
+* reference — a one-level copy lets branching a builder cross-contaminate
+* both branches and lets build() outputs mutate after the fact.
+*/
+function deepCopyPlain(value) {
+	if (Array.isArray(value)) return value.map(deepCopyPlain);
+	if (isObject(value)) {
+		const record = value;
+		const copy = {};
+		for (const key of Object.keys(record)) copy[key] = deepCopyPlain(record[key]);
+		return copy;
+	}
+	return value;
+}
+/** Structural equality over plain theme data (records, arrays, primitives). */
+function plainDataEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, index) => plainDataEqual(item, b[index]));
+	if (isObject(a) && isObject(b)) {
+		const aRecord = a;
+		const bRecord = b;
+		const aKeys = Object.keys(aRecord);
+		return aKeys.length === Object.keys(bRecord).length && aKeys.every((key) => Object.prototype.hasOwnProperty.call(bRecord, key) && plainDataEqual(aRecord[key], bRecord[key]));
+	}
+	return false;
+}
+/**
+* Re-seed builder state from a source theme's manifest. This is `from()`'s
+* manifest read, factored out verbatim so `extend()` inherits the SAME
+* emitted-scale/contextual-var/manifest-v2 carry semantics: the manifest is
+* non-enumerable, so the ordinary key-copy loop never sees it (D6/D8).
+*/
+function reseedStateFromManifest(state, manifest, mergeExtensionState = false) {
+	if (manifest?.emittedScales) for (const scale of manifest.emittedScales) state.emittedScales.add(scale);
+	else if (manifest?.variableMap) {
+		const emittedPaths = manifest.manifestVersion === 2 && manifest.tokenDefinitions ? Object.keys(manifest.variableMap).filter((tokenPath) => manifest.tokenDefinitions?.[tokenPath] !== void 0) : Object.keys(manifest.variableMap);
+		for (const tokenPath of emittedPaths) {
+			const scale = tokenPath.split(".")[0];
+			state.emittedScales.add(scale === "colors" ? "colors" : scale);
+		}
+	}
+	if (manifest?.contextualVars) for (const [scale, vars] of Object.entries(manifest.contextualVars)) {
+		const existing = mergeExtensionState ? state.contextualVars.get(scale) : void 0;
+		state.contextualVars.set(scale, existing ? [...new Set([...existing, ...vars])] : [...vars]);
+	}
+	if (manifest) if (manifest.manifestVersion === 2) {
+		state.carriedManifestV2 = {
+			tokenDefinitions: manifest.tokenDefinitions,
+			emittedScales: manifest.emittedScales,
+			modeAliasDefinitions: manifest.modeAliasDefinitions,
+			registrations: manifest.registrations,
+			emitterVersion: manifest.emitterVersion,
+			contractHash: manifest.contractHash,
+			cssFragments: manifest.cssFragments
+		};
+		if (manifest.registrations) for (const [name, registration] of Object.entries(manifest.registrations)) {
+			const existing = state.contextualVarRegistrations.get(name);
+			if (mergeExtensionState && existing && (existing.syntax !== registration.syntax || existing.inherits !== registration.inherits || existing.initialValue !== registration.initialValue)) throw new Error(`extend: contextual variable '${name}' has divergent @property registrations across extended themes`);
+			state.contextualVarRegistrations.set(name, registration);
+		}
+	} else state.hasLegacyManifestSource = true;
+}
+/**
 * ThemeScales — the final phase. Has addScale, extendScale, declareContextualVars, build.
 * Also allows addColors and addColorModes for augmentation.
 */
@@ -930,39 +1398,94 @@ var ThemeBuilder = class ThemeBuilder {
 	}
 	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 });
+		const nextTheme = merge(deepCopyPlain(this._state.theme), { breakpoints });
 		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
+	/**
+	* FROZEN for the deprecation window (D1/G6): source-WINS precedence over
+	* prior builder state, callable at ANY stage — the phantom Stage passes
+	* through unchanged. Do not add a stage gate; do not flip the merge
+	* direction. Those semantics ship under the new verb only.
+	*
+	* @deprecated Use `extend(source)` — the single extension verb on both
+	* builders: the extended source seeds the base and later local calls win.
+	* `from()` keeps these frozen source-wins semantics for at least one minor
+	* release after `extend()` ships.
+	*/
 	from(builtTheme) {
+		const source = isLibraryBundle(builtTheme) ? builtTheme.theme ?? builtTheme.tokens ?? {} : builtTheme;
 		const raw = {};
-		for (const key of Object.keys(builtTheme)) {
-			const val = builtTheme[key];
+		for (const key of Object.keys(source)) {
+			const val = source[key];
 			if (typeof val !== "function") raw[key] = val;
 		}
-		const nextTheme = merge({}, this._state.theme, raw);
+		const nextTheme = merge(deepCopyPlain(this._state.theme), deepCopyPlain(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);
+		reseedStateFromManifest(next._state, source.manifest);
+		return next;
+	}
+	/**
+	* Extend this theme from a consumed library (D1/D2): the source's complete
+	* configuration — tokens, modes, preferences, registrations, emitted-scale
+	* set — seeds the builder as the BASE, and local calls made after
+	* `extend()` win on conflict (the mirror of `from()`'s source-wins).
+	* Chainable and repeatable, but only before augmentation methods ("inherit
+	* first, then extend" — enforced by the phantom builder stage). Accepts a
+	* built theme or a library bundle, consuming the bundle's theme half
+	* (`theme ?? tokens`, D9) and ignoring the rest.
+	*
+	* Sibling conflicts fail loud (D3/G4): a leaf path defined divergently by
+	* two extended sources throws naming the path and both sources
+	* positionally; equal values coalesce silently, and the consumer's own
+	* post-extend `add*` calls override silently (NS-4).
+	*/
+	extend(source) {
+		const themeHalf = isLibraryBundle(source) ? source.theme ?? source.tokens ?? {} : source;
+		const raw = {};
+		for (const key of Object.keys(themeHalf)) {
+			const val = themeHalf[key];
+			if (typeof val !== "function") raw[key] = val;
 		}
-		if (manifest?.contextualVars) for (const [scale, vars] of Object.entries(manifest.contextualVars)) next._state.contextualVars.set(scale, [...vars]);
-		if (manifest) if (manifest.manifestVersion === 2) {
-			next._state.carriedManifestV2 = {
-				tokenDefinitions: manifest.tokenDefinitions,
-				modeAliasDefinitions: manifest.modeAliasDefinitions,
-				registrations: manifest.registrations,
-				emitterVersion: manifest.emitterVersion,
-				contractHash: manifest.contractHash,
-				cssFragments: manifest.cssFragments
-			};
-			if (manifest.registrations) for (const [name, registration] of Object.entries(manifest.registrations)) next._state.contextualVarRegistrations.set(name, registration);
-		} else next._state.hasLegacyManifestSource = true;
+		const sourceIndex = this._state.extendCount + 1;
+		const provenance = new Map(this._state.extendProvenance);
+		const existingLeaves = flattenLeafPathsExact(this._state.theme);
+		const incomingLeaves = flattenLeafPathsExact(raw);
+		const trackedPrefixes = /* @__PURE__ */ new Map();
+		for (const [trackedPath, index] of provenance) for (let dot = trackedPath.lastIndexOf("."); dot !== -1; dot = trackedPath.lastIndexOf(".", dot - 1)) {
+			const prefix = trackedPath.slice(0, dot);
+			if (!trackedPrefixes.has(prefix)) trackedPrefixes.set(prefix, index);
+		}
+		for (const [path, value] of Object.entries(incomingLeaves)) {
+			const priorIndex = provenance.get(path);
+			if (priorIndex !== void 0) {
+				const existing = existingLeaves[path];
+				if (!plainDataEqual(existing, value)) throw new Error(`extend: path '${path}' is defined divergently by extended theme #${priorIndex} (${JSON.stringify(existing)}) and extended theme #${sourceIndex} (${JSON.stringify(value)}). Sibling themes must agree — override intentionally with an add* call after extend().`);
+				continue;
+			}
+			const branchIndex = trackedPrefixes.get(path);
+			if (branchIndex !== void 0) throw new Error(`extend: path '${path}' is defined divergently by extended theme #${branchIndex} (a nested branch) and extended theme #${sourceIndex} (a leaf value). Sibling themes must agree — override intentionally with an add* call after extend().`);
+			for (let dot = path.lastIndexOf("."); dot !== -1; dot = path.lastIndexOf(".", dot - 1)) {
+				const ancestor = path.slice(0, dot);
+				const ancestorIndex = provenance.get(ancestor);
+				if (ancestorIndex !== void 0 && ancestorIndex !== sourceIndex) throw new Error(`extend: path '${ancestor}' is defined divergently by extended theme #${ancestorIndex} (a leaf value) and extended theme #${sourceIndex} (a nested branch). Sibling themes must agree — override intentionally with an add* call after extend().`);
+			}
+			provenance.set(path, sourceIndex);
+		}
+		const nextTheme = merge(deepCopyPlain(raw), deepCopyPlain(this._state.theme));
+		const next = new ThemeBuilder(copyState(this._state, nextTheme));
+		next._state.extendProvenance = provenance;
+		next._state.extendCount = sourceIndex;
+		if (isObject(raw.modes)) for (const [modeName, modeAliases] of Object.entries(raw.modes)) {
+			next._state.inheritedModes.add(modeName);
+			if (!isObject(modeAliases)) continue;
+			for (const aliasPath of Object.keys(flattenToDotPaths(modeAliases))) next._state.inheritedModeAliases.add(aliasPath);
+		}
+		reseedStateFromManifest(next._state, themeHalf.manifest, true);
 		return next;
 	}
 	addColors(colors) {
 		validateColors(colors);
-		const nextTheme = merge({}, this._state.theme, { colors });
+		const nextTheme = merge(deepCopyPlain(this._state.theme), { colors });
 		const next = new ThemeBuilder(copyState(this._state, nextTheme));
 		next._state.emittedScales.add("colors");
 		return next;
@@ -981,20 +1504,32 @@ var ThemeBuilder = class ThemeBuilder {
 		const systemPreference = mergeOptionObject(this._state.theme.systemPreference, options?.systemPreference);
 		const browserColorScheme = mergeOptionObject(this._state.theme.browserColorScheme, options?.browserColorScheme);
 		resolveColorModeOptions(modeNames, systemPreference, browserColorScheme);
-		const nextTheme = merge({}, this._state.theme, {
+		const modeBases = mergeOptionObject(this._state.theme.modeBases, options?.basedOn);
+		validateModeBases(modeNames, modeBases);
+		const nextTheme = merge(deepCopyPlain(this._state.theme), {
 			modes: modeConfig,
 			mode: initialMode,
 			...systemPreference ? { systemPreference } : {},
-			...browserColorScheme ? { browserColorScheme } : {}
+			...browserColorScheme ? { browserColorScheme } : {},
+			...modeBases ? { modeBases } : {}
 		});
 		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
 	addScale(config) {
-		const { name, values, emit } = config;
-		if (RESERVED_THEME_KEYS.has(name)) throw new Error(`addScale: '${name}' is a reserved theme key owned by addColorModes options — it is skipped by the token flatten pass and read back as an option object, so a scale by this name would emit no tokens. Choose another scale name.`);
-		const nextTheme = merge({}, this._state.theme, { [name]: values });
+		const { 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.`);
+		const prior = this._state.theme[name];
+		let nextTheme;
+		if (replace) {
+			nextTheme = deepCopyPlain(this._state.theme);
+			nextTheme[name] = values;
+		} else nextTheme = merge(deepCopyPlain(this._state.theme), { [name]: values });
 		const next = new ThemeBuilder(copyState(this._state, nextTheme));
 		if (emit) next._state.emittedScales.add(name);
+		if (replace && isObject(prior)) {
+			const kept = new Set(Object.keys(flattenToDotPaths(values)));
+			for (const dotKey of Object.keys(flattenToDotPaths(prior))) if (!kept.has(dotKey)) next._state.droppedTokenPaths.set(`${name}.${dotKey}`, name);
+		}
 		return next;
 	}
 	declareContextualVars(vars, registrations) {
@@ -1010,7 +1545,7 @@ var ThemeBuilder = class ThemeBuilder {
 		return next;
 	}
 	extendScale(key, updateFn) {
-		const nextTheme = merge({}, this._state.theme, { [key]: updateFn(this._state.theme[key]) });
+		const nextTheme = merge(deepCopyPlain(this._state.theme), { [key]: updateFn(this._state.theme[key]) });
 		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
 	/**
@@ -1018,24 +1553,44 @@ var ThemeBuilder = class ThemeBuilder {
 	* Flattens nested data at the boundary — produces manifest and serialize().
 	*/
 	build() {
-		const theme = merge({}, this._state.theme);
+		const theme = deepCopyPlain(this._state.theme);
 		const emittedScales = this._state.emittedScales;
 		const contextualVars = this._state.contextualVars;
 		const systemPreference = isObject(theme.systemPreference) ? theme.systemPreference : void 0;
 		const mergedModeNames = isObject(theme.modes) ? Object.keys(theme.modes) : [];
 		validateReservedModeNames(mergedModeNames);
 		const browserColorScheme = resolveColorModeOptions(mergedModeNames, systemPreference, isObject(theme.browserColorScheme) ? theme.browserColorScheme : void 0);
-		const { tokenMap, variableMap, variables, modeVariables, modeTokens, tokenDefinitions, modeAliasDefinitions } = flattenTheme(theme, emittedScales);
-		resolveTokenRefs(tokenMap, variableMap, emittedScales);
+		const modeBases = isObject(theme.modeBases) ? theme.modeBases : void 0;
+		validateModeBases(mergedModeNames, modeBases);
+		if (isObject(theme.modes) && isObject(theme.colors)) {
+			const nestedColors = theme.colors;
+			const flatColorKeys = Object.keys(flattenToDotPaths(nestedColors));
+			for (const [modeName, modeAliases] of Object.entries(theme.modes)) {
+				if (!isObject(modeAliases)) continue;
+				validateModeAliases(modeName, modeAliases, nestedColors, flatColorKeys, "");
+			}
+		}
+		const modeAliasDefinitions = collectAuthoredModeAliases(theme);
+		const { effectiveModes, coverageFills } = resolveModeCoverage(modeAliasDefinitions, modeBases, this._state.inheritedModes, this._state.inheritedModeAliases);
+		for (const fill of coverageFills) console.info(`[animus] Mode '${fill.mode}': ${fill.count} alias(es) inherit from '${fill.base}'`);
+		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 { modeVariables, modeTokens } = resolveModeValueMaps(effectiveModes, variableMap, variables, tokenMap);
 		const bpVariables = {};
-		if (theme.breakpoints && isObject(theme.breakpoints)) for (const [key, value] of Object.entries(theme.breakpoints)) bpVariables[`--breakpoint-${key}`] = `${value}px`;
+		if (theme.breakpoints && isObject(theme.breakpoints)) {
+			const breakpointEntries = Object.entries(theme.breakpoints).map(([key, value]) => [`--breakpoint-${key}`, `${value}px`]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+			for (const [varName, value] of breakpointEntries) bpVariables[varName] = value;
+		}
 		let contextualVarsSerialized;
 		if (contextualVars.size > 0) {
 			contextualVarsSerialized = {};
 			for (const [scale, vars] of contextualVars) contextualVarsSerialized[scale] = vars;
 		}
 		const propertyCss = buildPropertyRegistrationCss(contextualVars, this._state.contextualVarRegistrations);
-		const baseVariableCss = buildVariableCss(variables, bpVariables, modeVariables, {
+		const { emittableVariables, emittableModeVariables, omitted } = omitUnresolvedDeclarations(variables, modeVariables);
+		if (omitted.length > 0) console.warn(`[animus] Omitted ${omitted.length} CSS declaration(s) whose token references never resolved: ${omitted.join(", ")}`);
+		const baseVariableCss = buildVariableCss(emittableVariables, bpVariables, emittableModeVariables, {
 			initialMode: typeof theme.mode === "string" ? theme.mode : void 0,
 			systemPreference,
 			browserColorScheme
@@ -1058,26 +1613,30 @@ var ThemeBuilder = class ThemeBuilder {
 			manifestV2Fields = {
 				manifestVersion: 2,
 				tokenDefinitions,
+				emittedScales: [...emittedScales].sort(),
 				modeAliasDefinitions,
 				registrations,
 				emitterVersion: EMITTER_VERSION,
 				contractHash: computeContractHash({
 					tokenDefinitions,
+					emittedScales: [...emittedScales].sort(),
 					modeAliasDefinitions,
 					initialMode: typeof theme.mode === "string" ? theme.mode : void 0,
 					registrations,
 					systemPreference,
-					browserColorScheme
+					browserColorScheme,
+					modeBases
 				}),
 				cssFragments
 			};
 		}
+		const sortedVariableMap = sortRecordByKey(variableMap);
 		const manifest = {
 			tokenMap: {
 				...tokenMap,
-				...Object.fromEntries(Object.entries(theme.breakpoints || {}).map(([k, v]) => [`breakpoints.${k}`, String(v)]))
+				...sortRecordByKey(Object.fromEntries(Object.entries(theme.breakpoints || {}).map(([k, v]) => [`breakpoints.${k}`, String(v)])))
 			},
-			variableMap,
+			variableMap: sortedVariableMap,
 			modes: modeTokens,
 			variableCss,
 			...contextualVarsSerialized ? { contextualVars: contextualVarsSerialized } : {},
@@ -1129,19 +1688,19 @@ function createTheme() {
 const TOKEN_REF_RE = /\{([^}]+)\}/g;
 /**
 * Flatten the nested theme into dot-path keyed token map and CSS variable declarations.
-* This is the ONLY place where flattening happens.
+* This is the ONLY place where flattening happens. Mode VALUE maps are no
+* longer computed here — they resolve AFTER `resolveReferences` (see
+* {@link resolveModeValueMaps}), closing the G2 gap where mode-override
+* declarations bypassed the resolver.
 */
-function flattenTheme(theme, emittedScales) {
+function flattenTheme(theme, emittedScales, effectiveModes) {
 	const tokenMap = {};
 	const variableMap = {};
 	const variables = {};
-	const modeVariables = {};
-	const modeTokens = {};
 	const tokenDefinitions = {};
-	const modeAliasDefinitions = {};
 	for (const [scaleName, scaleValue] of Object.entries(theme)) {
 		if (scaleName.startsWith("_")) continue;
-		if (scaleName === "breakpoints" || scaleName === "mode" || scaleName === "modes" || scaleName === "systemPreference" || scaleName === "browserColorScheme") continue;
+		if (scaleName === "breakpoints" || scaleName === "mode" || scaleName === "modes" || scaleName === "systemPreference" || scaleName === "browserColorScheme" || scaleName === "modeBases") continue;
 		if (typeof scaleValue === "function") continue;
 		if (!isObject(scaleValue)) continue;
 		const flat = flattenToDotPaths(scaleValue);
@@ -1158,54 +1717,242 @@ function flattenTheme(theme, emittedScales) {
 			} else tokenMap[tokenPath] = String(rawValue);
 		}
 	}
-	if (theme.modes && isObject(theme.modes) && theme.colors && isObject(theme.colors)) {
-		const flatColors = flattenToDotPaths(theme.colors);
-		for (const [modeName, modeAliases] of Object.entries(theme.modes)) {
-			if (!isObject(modeAliases)) continue;
-			const flatAliases = flattenToDotPaths(modeAliases);
-			const modeVars = {};
-			const modeVals = {};
-			const modeAliasDefs = {};
-			for (const [aliasDotKey, colorRef] of Object.entries(flatAliases)) {
-				if (typeof colorRef !== "string") continue;
-				const varName = `--color-${dotToDash(aliasDotKey)}`;
-				modeAliasDefs[aliasDotKey] = colorRef;
-				const rawValue = flatColors[colorRef];
-				modeVals[`colors.${aliasDotKey}`] = rawValue !== void 0 ? String(rawValue) : String(colorRef);
-				modeVars[varName] = rawValue !== void 0 ? String(rawValue) : String(colorRef);
-			}
-			modeVariables[modeName] = modeVars;
-			modeTokens[modeName] = modeVals;
-			modeAliasDefinitions[modeName] = modeAliasDefs;
-		}
-		const initialMode = theme.mode;
-		if (initialMode && modeVariables[initialMode]) {
-			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);
+	const initialMode = theme.mode;
+	const initialAliases = typeof initialMode === "string" ? effectiveModes[initialMode] : void 0;
+	if (initialAliases) for (const [aliasDotKey, colorRef] of Object.entries(initialAliases)) {
+		const varName = `--color-${dotToDash(aliasDotKey)}`;
+		const paletteVarName = variableMap[`colors.${colorRef}`];
+		if (paletteVarName) {
+			if (paletteVarName !== varName) variables[varName] = `var(${paletteVarName})`;
+		} else {
+			const literal = tokenMap[`colors.${colorRef}`];
+			if (literal !== void 0) variables[varName] = literal;
 		}
+		tokenMap[`colors.${aliasDotKey}`] = `var(${varName})`;
+		variableMap[`colors.${aliasDotKey}`] = varName;
 	}
 	return {
 		tokenMap,
 		variableMap,
 		variables,
+		tokenDefinitions
+	};
+}
+/** Rebuild a record with lexicographically sorted keys (wire determinism, G3). */
+function sortRecordByKey(record) {
+	const sorted = {};
+	for (const key of Object.keys(record).sort()) sorted[key] = record[key];
+	return sorted;
+}
+/**
+* Collect the AUTHORED mode alias graph: mode name → alias dot-path → the
+* authored color dot-path (manifest v2, D6 — never a resolved value).
+* Empty when the theme has no modes or no colors, mirroring the original
+* flatten-pass guard.
+*/
+function collectAuthoredModeAliases(theme) {
+	const authored = {};
+	if (!isObject(theme.modes) || !isObject(theme.colors)) return authored;
+	for (const [modeName, modeAliases] of Object.entries(theme.modes)) {
+		if (!isObject(modeAliases)) continue;
+		const defs = {};
+		for (const [aliasDotKey, colorRef] of Object.entries(flattenToDotPaths(modeAliases))) {
+			if (typeof colorRef !== "string") continue;
+			defs[aliasDotKey] = colorRef;
+		}
+		authored[modeName] = defs;
+	}
+	return authored;
+}
+/**
+* D6 coverage over the merged mode set: a CONSUMER-declared mode leaving
+* inherited aliases uncovered must name a base (`basedOn`) whose chain
+* covers them — otherwise the build fails listing the uncovered set.
+* Inherited modes are exempt (a kit's own asymmetry is pre-existing
+* behavior and must round-trip byte-identically). Returns the effective
+* alias map per mode (base-chain fills + authored, authored winning) and
+* one aggregated fill report per mode for the build diagnostic.
+*/
+function resolveModeCoverage(authoredModeAliases, modeBases, inheritedModes, inheritedModeAliases) {
+	const effectiveModes = {};
+	const coverageFills = [];
+	for (const modeName of Object.keys(authoredModeAliases)) {
+		const authored = authoredModeAliases[modeName];
+		const fills = {};
+		if (!inheritedModes.has(modeName)) {
+			const uncovered = [...inheritedModeAliases].filter((alias) => !(alias in authored)).sort();
+			if (uncovered.length > 0) {
+				const base = modeBases?.[modeName];
+				if (base === void 0) throw new Error(`build: mode '${modeName}' leaves ${uncovered.length} inherited alias(es) uncovered and declares no base — uncovered: ${uncovered.join(", ")}. Add basedOn: { '${modeName}': '<mode>' } to addColorModes options or override every inherited alias.`);
+				const stillUncovered = [];
+				for (const alias of uncovered) {
+					let cursor = base;
+					const seen = new Set([modeName]);
+					let resolved;
+					while (cursor !== void 0 && !seen.has(cursor)) {
+						seen.add(cursor);
+						resolved = authoredModeAliases[cursor]?.[alias];
+						if (resolved !== void 0) break;
+						cursor = modeBases?.[cursor];
+					}
+					if (resolved === void 0) stillUncovered.push(alias);
+					else fills[alias] = resolved;
+				}
+				if (stillUncovered.length > 0) throw new Error(`build: mode '${modeName}' resolves through base '${base}' but the chain never covers: ${stillUncovered.join(", ")}. Cover them in a chained mode or override them directly.`);
+				coverageFills.push({
+					mode: modeName,
+					base,
+					count: Object.keys(fills).length
+				});
+			}
+		}
+		effectiveModes[modeName] = {
+			...fills,
+			...authored
+		};
+	}
+	return {
+		effectiveModes,
+		coverageFills
+	};
+}
+/**
+* Resolve the per-mode value maps AFTER reference resolution: every mode
+* declaration carries the RESOLVED value of its target color (emitted →
+* the resolved declaration value; inlined → the resolved literal), never
+* the raw flattened string — the G2 closure for `[data-color-mode]` blocks.
+* Modes iterate in sorted name order and lines in sorted property-name
+* order, so mode declaration/insertion order is never observable (G3).
+*/
+function resolveModeValueMaps(effectiveModes, variableMap, variables, tokenMap) {
+	const modeVariables = {};
+	const modeTokens = {};
+	const resolvedColorValue = (colorRef) => {
+		const path = `colors.${colorRef}`;
+		const varName = variableMap[path];
+		if (varName !== void 0) {
+			const declared = variables[varName];
+			if (declared !== void 0) return declared;
+		} else if (tokenMap[path] !== void 0) return tokenMap[path];
+		return String(colorRef);
+	};
+	for (const modeName of Object.keys(effectiveModes).sort()) {
+		const aliases = effectiveModes[modeName];
+		const entries = Object.keys(aliases).map((aliasDotKey) => [`--color-${dotToDash(aliasDotKey)}`, aliasDotKey]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+		const modeVars = {};
+		const modeVals = {};
+		for (const [varName, aliasDotKey] of entries) {
+			const value = resolvedColorValue(aliases[aliasDotKey]);
+			modeVars[varName] = value;
+			modeVals[`colors.${aliasDotKey}`] = value;
+		}
+		modeVariables[modeName] = modeVars;
+		modeTokens[modeName] = modeVals;
+	}
+	return {
 		modeVariables,
-		modeTokens,
-		tokenDefinitions,
-		modeAliasDefinitions
+		modeTokens
+	};
+}
+/**
+* D5 enforcement: a reference whose target is absent from the merged map
+* AND was dropped by an explicit `addScale({ replace: true })` fails the
+* build — unconditional on usage — naming the referencing token (with its
+* positional origin), the replacement call's scale, and the dropped keys.
+* Targets never defined ANYWHERE stay warn-and-literal (supported kit
+* pattern); a re-added key is simply known again and passes.
+*/
+function assertNoDroppedReferences(tokenDefinitions, flatTokenMap, droppedTokenPaths, extendProvenance) {
+	if (droppedTokenPaths.size === 0) return;
+	const known = new Set(Object.keys(flatTokenMap));
+	const violations = [];
+	const droppedNamed = /* @__PURE__ */ new Set();
+	for (const [tokenPath, definition] of Object.entries(tokenDefinitions)) {
+		if (definition.kind !== "reference") continue;
+		for (const reference of definition.references) {
+			if (known.has(reference.path)) continue;
+			const scale = droppedTokenPaths.get(reference.path);
+			if (scale === void 0) continue;
+			const provenanceIndex = extendProvenance.get(tokenPath);
+			const origin = provenanceIndex === void 0 ? "builder state" : `extended theme #${provenanceIndex}`;
+			violations.push(`'${tokenPath}' (${origin}) references '{${reference.path}}', dropped by addScale({ name: '${scale}', replace: true })`);
+			droppedNamed.add(reference.path);
+		}
+	}
+	if (violations.length > 0) throw new Error(`build: dangling token reference(s) after explicit scale replacement — ${violations.join("; ")}. Dropped keys: ${[...droppedNamed].sort().join(", ")}.`);
+}
+/** A resolved value still carrying a `{…}` reference — never shippable (G2). */
+const UNRESOLVED_REF_RE = /\{[^}]+\}/;
+/** Custom-property names referenced through `var(--name)` in a value. */
+const VAR_REF_NAME_RE = /var\(\s*(--[\w-]+)/g;
+function varRefNames(value) {
+	const names = [];
+	for (const match of value.matchAll(VAR_REF_NAME_RE)) names.push(match[1]);
+	return names;
+}
+/**
+* Split root and mode variable maps into shippable declarations and omitted
+* var names (G2): any value still containing `{…}` after resolution — a
+* direct or TRANSITIVE never-defined target — is withheld from emitted CSS.
+*
+* Withholding must follow `var()` indirection too: flattenTheme synthesizes
+* the initial mode's aliases as `var(--target)` BEFORE resolution, so a
+* withheld target would otherwise leave an emitted alias pointing at a
+* declaration that exists nowhere. A declaration is dangling when a var()
+* target of its value was DECLARED in this build but withheld everywhere
+* the declaration can see (:root for root declarations; the same mode
+* block or :root for mode declarations); chains drop to a fixpoint. Var
+* names never declared here (breakpoints, contextual vars) are exempt.
+*/
+function omitUnresolvedDeclarations(variables, modeVariables) {
+	const omitted = [];
+	const emittableVariables = {};
+	const droppedRoot = /* @__PURE__ */ new Set();
+	for (const [varName, value] of Object.entries(variables)) if (UNRESOLVED_REF_RE.test(value)) {
+		omitted.push(varName);
+		droppedRoot.add(varName);
+	} else emittableVariables[varName] = value;
+	let rootChanged = true;
+	while (rootChanged) {
+		rootChanged = false;
+		for (const [varName, value] of Object.entries(emittableVariables)) if (varRefNames(value).some((name) => droppedRoot.has(name))) {
+			delete emittableVariables[varName];
+			droppedRoot.add(varName);
+			omitted.push(varName);
+			rootChanged = true;
+		}
+	}
+	const emittableModeVariables = {};
+	for (const [modeName, modeVars] of Object.entries(modeVariables)) {
+		const kept = {};
+		const droppedInMode = /* @__PURE__ */ new Set();
+		const dropFromMode = (varName) => {
+			omitted.push(`${varName} ([data-color-mode="${modeName}"])`);
+			droppedInMode.add(varName);
+		};
+		for (const [varName, value] of Object.entries(modeVars)) if (UNRESOLVED_REF_RE.test(value)) dropFromMode(varName);
+		else kept[varName] = value;
+		const dangling = (name) => (droppedInMode.has(name) || droppedRoot.has(name)) && !(name in kept) && !(name in emittableVariables);
+		let modeChanged = true;
+		while (modeChanged) {
+			modeChanged = false;
+			for (const [varName, value] of Object.entries(kept)) if (varRefNames(value).some(dangling)) {
+				delete kept[varName];
+				dropFromMode(varName);
+				modeChanged = true;
+			}
+		}
+		emittableModeVariables[modeName] = kept;
+	}
+	return {
+		emittableVariables,
+		emittableModeVariables,
+		omitted
 	};
 }
 /**
 * Classify a RAW token value into its authored form (manifest v2, D6). MUST
-* run before `resolveTokenRefs` — resolution rewrites the string, and the
+* run before `resolveReferences` — resolution rewrites the string, and the
 * authored graph cannot be reconstructed from resolved CSS (D8). Uses
 * `matchAll` so the shared global {@link TOKEN_REF_RE} never carries a stale
 * `lastIndex` between callers.
@@ -1431,43 +2178,6 @@ function computeContractHash(input) {
 	return sha256Hex(JSON.stringify(canonicalize(input)));
 }
 /**
-* Resolve token refs ({scale.key}) in all flattened token values.
-* Operates on the flattened tokenMap — does NOT mutate the nested theme.
-*/
-function resolveTokenRefs(tokenMap, _variableMap, _emittedScales) {
-	for (const [tokenPath, value] of Object.entries(tokenMap)) {
-		if (typeof value !== "string") continue;
-		if (!value.includes("{")) continue;
-		if (value.startsWith("var(")) continue;
-		const scaleName = tokenPath.split(".")[0];
-		const resolved = value.replace(TOKEN_REF_RE, (match, ref) => {
-			if (ref.split(".")[0] === scaleName) {
-				console.warn(`[animus] Self-referential token ref {${ref}} in scale '${scaleName}' — skipped`);
-				return match;
-			}
-			let lookupPath = ref;
-			let opacity;
-			const slashIdx = ref.indexOf("/");
-			if (slashIdx !== -1) {
-				lookupPath = ref.slice(0, slashIdx);
-				opacity = ref.slice(slashIdx + 1);
-			}
-			const refValue = tokenMap[lookupPath];
-			if (refValue === void 0) {
-				console.warn(`[animus] Token ref {${ref}} — path '${lookupPath}' not found in token map`);
-				return match;
-			}
-			if (opacity) {
-				const alpha = Number.parseInt(opacity, 10);
-				if (alpha === 0) return "transparent";
-				if (alpha !== 100) return `color-mix(in srgb, ${refValue} ${alpha}%, transparent)`;
-			}
-			return refValue;
-		});
-		if (resolved !== value) tokenMap[tokenPath] = resolved;
-	}
-}
-/**
 * Build `@property` registration rules for registered contextual vars.
 * The emitted custom property is `--${name}` — the same name the Rust resolver
 * maps a bare contextual var value to. Rules emit in declaration order and only
@@ -1519,4 +2229,4 @@ function buildVariableCss(rootVariables, breakpointVariables, modeVariables, sys
 	return parts.join("\n\n");
 }
 //#endregion
-export { Animus, AnimusExtended, AnimusExtendedWithAll, AnimusWithAll, BUILT_IN_CONDITIONS, BUILT_IN_SELECTORS, SystemBuilder, ThemeBuilder, borderShorthand, compose, createClassResolver, createComponent, createComposedFamily, createScale, createSystem, createTheme, createTransform, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, size, stringScale };
+export { ASSET_PLACEHOLDER_PREFIX, Animus, AnimusExtended, AnimusExtendedWithAll, AnimusWithAll, BUILT_IN_CONDITIONS, BUILT_IN_SELECTORS, SystemBuilder, ThemeBuilder, areTransformsEqual, asset, borderShorthand, compose, createClassResolver, createComponent, createComposedFamily, createScale, createSystem, createTheme, createTransform, gridItem, gridItemRatio, numericOrStringScale, numericScale, percentageOrAbsolute, size, stringScale };