@pikacss/core 0.0.52 → 0.0.54

package/dist/index.mjs

@@ -489,6 +489,7 @@ const PROPERTY_EFFECTS = {
 	"flex-direction": ["flex-direction"],
 	"flex-flow": ["flex-direction", "flex-wrap"],
 	"flex-grow": ["flex-grow"],
+	"flex-line-count": ["flex-line-count"],
 	"flex-shrink": ["flex-shrink"],
 	"flex-wrap": ["flex-wrap"],
 	"float": ["float"],
@@ -1148,6 +1149,7 @@ const PROPERTY_EFFECTS = {
 	"widows": ["widows"],
 	"width": ["width"],
 	"will-change": ["will-change"],
+	"window-drag": ["window-drag"],
 	"word-break": ["word-break"],
 	"word-space-transform": ["word-space-transform"],
 	"word-spacing": ["word-spacing"],
@@ -1301,13 +1303,13 @@ const numOfChars = chars.length;
 * @param num - The non-negative integer to encode.
 * @returns A short alphabetic string unique to the given integer.
 *
-* @remarks Used to generate compact, human-readable atomic style class IDs. The encoding is deterministic: the same number always produces the same string.
+* @remarks Used to generate compact, human-readable atomic style class IDs. The encoding is deterministic (the same number always produces the same string) and least-significant-digit first: `52` maps to `'aa'`, `53` to `'ba'`, and so on.
 *
 * @example
 * ```ts
 * numberToChars(0)  // 'a'
 * numberToChars(51) // 'Z'
-* numberToChars(52) // 'ba'
+* numberToChars(52) // 'aa'
 * ```
 */
 function numberToChars(num) {
@@ -1378,27 +1380,111 @@ function isNotString(value) {
 	return typeof value !== "string";
 }
 /**
-* Tests whether a value conforms to the `InternalPropertyValue` shape: a string, a `[value, fallback[]]` tuple, or nullish.
+* Type-narrowing guard that returns `true` when the value is a plain object record (non-null, non-array object).
+* @internal
+*
+* @param value - The value to test.
+* @returns `true` if the value is an object that is neither `null` nor an array, narrowing the type to `Record<string, unknown>`.
+*
+* @remarks Used to distinguish nested definition objects (variables, design tokens) from scalar values and arrays while walking configuration trees.
+*
+* @example
+* ```ts
+* isPlainObjectRecord({ a: 1 }) // true
+* isPlainObjectRecord([1, 2])   // false
+* isPlainObjectRecord(null)     // false
+* ```
+*/
+function isPlainObjectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const REGEXP_SPECIAL_CHARS_RE = /[.*+?^${}()|[\]\\/-]/g;
+/**
+* Escapes regular expression special characters in a string so it can be embedded in a `RegExp` source as a literal match.
+* @internal
+*
+* @param value - The literal text to escape.
+* @returns The input with every regex special character prefixed by a backslash.
+*
+* @remarks Runtime substitute for `RegExp.escape()` (available in Node.js >= 24 but not yet typed by TypeScript 5.9). Escapes all regex syntax characters plus `/` and `-`; the extra escapes are identity escapes in non-`u`-flag patterns, so the result is safe to embed in the non-unicode-mode regexes built by the engine and integrations.
+*
+* @example
+* ```ts
+* escapeRegExp('i-icon?') // 'i\\-icon\\?'
+* new RegExp(`^${escapeRegExp('a.b')}$`).test('a.b') // true
+* ```
+*/
+function escapeRegExp(value) {
+	return value.replace(REGEXP_SPECIAL_CHARS_RE, "\\$&");
+}
+function isPropertyValueScalar(v) {
+	return typeof v === "string" || typeof v === "number";
+}
+/**
+* Tests whether a value conforms to the `InternalPropertyValue` shape: a string, a number, a `[value, fallback[]]` tuple, or nullish.
 * @internal
 *
 * @param v - The value to inspect.
 * @returns `true` if the value is a valid property value.
 *
-* @remarks During extraction, the engine uses this guard to distinguish CSS property values from nested selector objects or style item arrays.
+* @remarks During extraction, the engine uses this guard to distinguish CSS property values from nested selector objects or style item arrays. Numbers are accepted because the csstype-based input types allow numeric values such as `0`; they are converted to strings during value normalization.
 *
 * @example
 * ```ts
 * isPropertyValue('red')                  // true
+* isPropertyValue(0)                       // true
 * isPropertyValue(['red', ['blue']])       // true
+* isPropertyValue(['auto', [0]])           // true
 * isPropertyValue(null)                    // true
 * isPropertyValue({ color: 'red' })        // false
 * ```
 */
 function isPropertyValue(v) {
-	if (Array.isArray(v)) return v.length === 2 && typeof v[0] === "string" && Array.isArray(v[1]) && v[1].every((i) => typeof i === "string");
+	if (Array.isArray(v)) return v.length === 2 && isPropertyValueScalar(v[0]) && Array.isArray(v[1]) && v[1].every(isPropertyValueScalar);
 	if (v == null) return true;
-	if (typeof v === "string") return true;
-	return false;
+	return isPropertyValueScalar(v);
+}
+/**
+* Applies a transform to the parts of a string outside quoted segments,
+* leaving single- and double-quoted content (e.g. attribute values) untouched.
+* @internal
+*
+* @param str - The string to scan.
+* @param transform - Transform applied to each unquoted segment.
+* @returns The reassembled string with transformed unquoted segments and untouched quoted segments.
+*
+* @remarks A backslash-escaped character is treated as a literal both inside and outside quoted segments, so a CSS-escaped quote in an identifier (e.g. `.it\'s`) never starts quoted-segment scanning.
+*
+* @example
+* ```ts
+* transformOutsideQuotes('[data-x="%"] %', s => s.replace(/%/g, 'pk-a'))
+* // '[data-x="%"] pk-a'
+* ```
+*/
+function transformOutsideQuotes(str, transform) {
+	let result = "";
+	let segmentStart = 0;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str[i];
+		if (ch === "\\") {
+			i++;
+			continue;
+		}
+		if (ch === "\"" || ch === "'") {
+			result += transform(str.slice(segmentStart, i));
+			let j = i + 1;
+			while (j < str.length && str[j] !== ch) {
+				if (str[j] === "\\") j++;
+				j++;
+			}
+			const end = Math.min(j, str.length - 1);
+			result += str.slice(i, end + 1);
+			i = end;
+			segmentStart = i + 1;
+		}
+	}
+	result += transform(str.slice(segmentStart));
+	return result;
 }
 /**
 * Serializes a value to a JSON string for use as a deterministic cache key.
@@ -1470,23 +1556,25 @@ function appendAutocompleteEntries(set, values) {
 * @param entries - A record mapping keys to single or arrayed string values, or `undefined` to skip.
 * @returns `true` if at least one entry was added or extended; `false` if the input was nullish or empty.
 *
-* @remarks Existing map entries are extended (not replaced) with the new values, maintaining all previously registered suggestions for a given key. This accumulative behavior allows multiple plugins to contribute value suggestions for the same property.
+* @remarks Existing map entries are extended (not replaced) with the new values, maintaining all previously registered suggestions for a given key. This accumulative behavior allows multiple plugins to contribute value suggestions for the same property. Values already present for a key are skipped, and the function returns `false` when nothing new was added.
 *
 * @example
 * ```ts
 * const map = new Map<string, string[]>()
 * appendAutocompleteRecordEntries(map, { color: ['red', 'blue'] }) // true
 * appendAutocompleteRecordEntries(map, { color: 'green' })         // true (now ['red','blue','green'])
+* appendAutocompleteRecordEntries(map, { color: 'green' })         // false (no change)
 * ```
 */
 function appendAutocompleteRecordEntries(map, entries) {
 	if (entries == null) return false;
 	let changed = false;
 	for (const [key, value] of Object.entries(entries)) {
-		const nextValues = [value].flat();
-		if (nextValues.length === 0) continue;
-		const current = map.get(key) || [];
-		map.set(key, [...current, ...nextValues]);
+		const current = map.get(key);
+		const existing = new Set(current);
+		const added = [value].flat().filter((v) => !existing.has(v));
+		if (added.length === 0) continue;
+		map.set(key, [...current ?? [], ...added]);
 		changed = true;
 	}
 	return changed;
@@ -1552,17 +1640,25 @@ function renderCSSStyleBlocks(blocks, isFormatted, depth = 0) {
 	const propertySpace = isFormatted ? " " : "";
 	const lineEnd = isFormatted ? "\n" : "";
 	const lines = [];
-	blocks.forEach(({ properties, children }, selector) => {
-		if (properties.length === 0 && (children == null || children.size === 0)) return;
+	blocks.forEach((blockBody, selector) => {
+		if (hasRenderableBlockContent(blockBody) === false) return;
+		const { properties, children } = blockBody;
+		const childrenCss = children != null && children.size > 0 ? renderCSSStyleBlocks(children, isFormatted, depth + 1) : "";
 		lines.push(...[
 			`${blockIndent}${selector}${selectorEnd}{`,
 			...properties.map(({ property, value }) => `${blockBodyIndent}${property}:${propertySpace}${value};`),
-			...children != null && children.size > 0 ? [renderCSSStyleBlocks(children, isFormatted, depth + 1)] : [],
+			...childrenCss !== "" ? [childrenCss] : [],
 			`${blockIndent}}`
 		]);
 	});
 	return lines.join(lineEnd);
 }
+function hasRenderableBlockContent(blockBody) {
+	if (blockBody.properties.length > 0) return true;
+	if (blockBody.children == null) return false;
+	for (const child of blockBody.children.values()) if (hasRenderableBlockContent(child)) return true;
+	return false;
+}
 //#endregion
 //#region src/atomic-style.ts
 /**
@@ -1788,9 +1884,48 @@ const LAYER_SELECTOR_PREFIX = "@layer ";
 * Global regex matching all occurrences of {@link ATOMIC_STYLE_ID_PLACEHOLDER}
 * for batch replacement in selector templates.
 *
+* A `%` directly preceded by a digit is treated as a literal percentage
+* (e.g. `@supports (width: 50%)`), not a placeholder.
+*
+* @internal
+*/
+const ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL = /(?<!\d)%/g;
+/**
+* Tests whether a selector string contains the atomic style ID placeholder.
+*
+* Uses the same digit-protection rule as {@link ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL}:
+* `%` preceded by a digit is a literal percentage, not a placeholder.
+* A `%` inside single- or double-quoted content (e.g. an attribute value)
+* is never treated as a placeholder.
+*
 * @internal
 */
-const ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL = /%/g;
+function hasAtomicStyleIdPlaceholder(selector) {
+	if (!selector.includes("\"") && !selector.includes("'")) {
+		ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL.lastIndex = 0;
+		return ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL.test(selector);
+	}
+	let found = false;
+	transformOutsideQuotes(selector, (segment) => {
+		if (found === false) {
+			ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL.lastIndex = 0;
+			found = ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL.test(segment);
+		}
+		return segment;
+	});
+	return found;
+}
+/**
+* Replaces every atomic style ID placeholder in a selector string with the given atomic style ID.
+*
+* Applies the same rules as {@link hasAtomicStyleIdPlaceholder}: a `%` directly
+* preceded by a digit is a literal percentage, and quoted content is never rewritten.
+*
+* @internal
+*/
+function replaceAtomicStyleIdPlaceholder(selector, atomicStyleId) {
+	return transformOutsideQuotes(selector, (segment) => segment.replace(ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, () => atomicStyleId));
+}
 //#endregion
 //#region src/extractor.ts
 function replaceBySplitAndJoin(str, split, mapFn, join) {
@@ -1811,7 +1946,7 @@ const ATTRIBUTE_SUFFIX_MATCH_RE_GLOBAL = /\$=/g;
 * @param options.defaultSelector - The selector template that replaces `$` placeholders.
 * @returns An array of normalized selector strings with all placeholders resolved.
 *
-* @remarks The `$` character in a selector is replaced with the engine's `defaultSelector`. The `%` character is the atomic style ID placeholder, preserved for later substitution. Attribute suffix matches (`$=`) are protected from the `$` replacement.
+* @remarks The `$` character in a selector is replaced with the engine's `defaultSelector`. The `%` character is the atomic style ID placeholder, preserved for later substitution. Attribute suffix matches (`$=`) are protected from the `$` replacement. Content inside single or double quotes is never rewritten, and a `%` directly preceded by a digit (e.g. `@supports (width: 50%)`) is treated as a literal percentage.
 *
 * @example
 * ```ts
@@ -1820,7 +1955,7 @@ const ATTRIBUTE_SUFFIX_MATCH_RE_GLOBAL = /\$=/g;
 * ```
 */
 function normalizeSelectors({ selectors, defaultSelector }) {
-	return selectors.map((s) => replaceBySplitAndJoin(s.replace(RE_SPLIT, ","), ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, (a) => replaceBySplitAndJoin(a, ATTRIBUTE_SUFFIX_MATCH_RE_GLOBAL, (b) => replaceBySplitAndJoin(b, DEFAULT_SELECTOR_PLACEHOLDER_RE_GLOBAL, null, defaultSelector), ATTRIBUTE_SUFFIX_MATCH), "%"));
+	return selectors.map((s) => transformOutsideQuotes(s, (segment) => replaceBySplitAndJoin(segment.replace(RE_SPLIT, ","), ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, (a) => replaceBySplitAndJoin(a, ATTRIBUTE_SUFFIX_MATCH_RE_GLOBAL, (b) => replaceBySplitAndJoin(b, DEFAULT_SELECTOR_PLACEHOLDER_RE_GLOBAL, null, defaultSelector), ATTRIBUTE_SUFFIX_MATCH), "%")));
 }
 /**
 * Normalizes a raw `InternalPropertyValue` into the extraction output format: an array of trimmed, deduplicated CSS value strings with fallbacks ordered before the primary value, or `null`/`undefined` to signal removal.
@@ -1829,11 +1964,12 @@ function normalizeSelectors({ selectors, defaultSelector }) {
 * @param value - The raw property value to normalize.
 * @returns An array of CSS value strings (fallbacks first, primary last), or `null`/`undefined` for removal.
 *
-* @remarks For tuple values `[primary, fallbacks]`, duplicates among fallbacks are removed and the primary value is appended last so CSS cascade uses it as the effective value while older browsers fall back to earlier entries.
+* @remarks For tuple values `[primary, fallbacks]`, duplicates among fallbacks are removed and the primary value is appended last so CSS cascade uses it as the effective value while older browsers fall back to earlier entries. Numeric values (e.g. `0`) are converted to strings.
 *
 * @example
 * ```ts
 * normalizeValue('red')                 // ['red']
+* normalizeValue(0)                     // ['0']
 * normalizeValue(['red', ['blue']])     // ['blue', 'red']
 * normalizeValue(null)                  // null
 * ```
@@ -1842,11 +1978,11 @@ function normalizeValue(value) {
 	if (value == null) return value;
 	if (Array.isArray(value)) {
 		const [primary, fallbacks] = value;
-		const p = primary.trim();
+		const p = String(primary).trim();
 		const seen = new Set([p]);
 		const result = [];
 		for (const v of fallbacks) {
-			const s = v.trim();
+			const s = String(v).trim();
 			if (!seen.has(s)) {
 				seen.add(s);
 				result.push(s);
@@ -1855,7 +1991,7 @@ function normalizeValue(value) {
 		result.push(p);
 		return result;
 	}
-	return [value.trim()];
+	return [String(value).trim()];
 }
 /**
 * Recursively walks a style definition tree, extracting each CSS property-value pair into a flat list of `ExtractedStyleContent` entries with their full selector chain.
@@ -1885,18 +2021,24 @@ function normalizeValue(value) {
 * ```
 */
 async function extract({ styleDefinition, levels = [], result = [], defaultSelector, transformSelectors, transformStyleItems, transformStyleDefinitions }) {
-	for (const definition of await transformStyleDefinitions([styleDefinition])) for (const [k, v] of Object.entries(definition)) if (isPropertyValue(v)) {
-		const selector = normalizeSelectors({
-			selectors: await transformSelectors(levels),
-			defaultSelector
-		});
-		if (selector.length === 0 || selector.every((s) => s.includes("%") === false)) selector.push(defaultSelector);
-		result.push({
-			selector,
-			property: toKebab(k),
-			value: normalizeValue(v)
-		});
-	} else if (Array.isArray(v)) for (const styleItem of await transformStyleItems(v)) {
+	let scopeSelector;
+	const resolveScopeSelector = async () => {
+		if (scopeSelector == null) {
+			const selector = normalizeSelectors({
+				selectors: await transformSelectors(levels),
+				defaultSelector
+			});
+			if (selector.length === 0 || selector.every((s) => hasAtomicStyleIdPlaceholder(s) === false)) selector.push(defaultSelector);
+			scopeSelector = selector;
+		}
+		return scopeSelector;
+	};
+	for (const definition of await transformStyleDefinitions([styleDefinition])) for (const [k, v] of Object.entries(definition)) if (isPropertyValue(v)) result.push({
+		selector: await resolveScopeSelector(),
+		property: toKebab(k),
+		value: normalizeValue(v)
+	});
+	else if (Array.isArray(v)) for (const styleItem of await transformStyleItems(v)) {
 		if (typeof styleItem === "string") continue;
 		await extract({
 			styleDefinition: styleItem,
@@ -2100,7 +2242,7 @@ function resolvePlugins(plugins) {
 * ```ts
 * export default defineEnginePlugin({
 *   name: 'my-plugin',
-*   configureRawConfig: (config) => ({ ...config, important: true }),
+*   configureRawConfig: (config) => ({ ...config, important: { default: true } }),
 * })
 * ```
 */
@@ -2110,8 +2252,10 @@ function defineEnginePlugin(plugin) {
 /* c8 ignore end */
 //#endregion
 //#region src/plugins/important.ts
+const TRAILING_IMPORTANT_RE = /!\s*important\s*$/i;
 function appendImportant(v) {
-	return v.endsWith("!important") ? v : `${v} !important`;
+	const value = String(v);
+	return TRAILING_IMPORTANT_RE.test(value) ? value : `${value} !important`;
 }
 function modifyPropertyValue(value) {
 	if (value == null) return null;
@@ -2123,7 +2267,7 @@ function modifyPropertyValue(value) {
 *
 * @returns An `EnginePlugin` that intercepts `transformStyleDefinitions` to conditionally append `!important` to every property value.
 *
-* @remarks When `EngineConfig.important.default` is `true`, all property values receive `!important` unless the style definition explicitly sets `__important: false`. Individual style definitions can also opt-in with `__important: true` regardless of the default.
+* @remarks When `EngineConfig.important.default` is `true`, all property values receive `!important` unless the style definition explicitly sets `__important: false`. Individual style definitions can also opt-in with `__important: true` regardless of the default. An explicit `__important` flag is propagated into nested selector blocks (which may override it with their own explicit flag). The `__shortcut` reference is never modified.
 *
 * @example
 * ```ts
@@ -2132,6 +2276,16 @@ function modifyPropertyValue(value) {
 */
 function important() {
 	let defaultValue;
+	function propagateExplicitFlag(v, flag) {
+		if (Array.isArray(v)) return v.map((item) => typeof item === "object" && item !== null && !Array.isArray(item) ? {
+			__important: flag,
+			...item
+		} : item);
+		return {
+			__important: flag,
+			...v
+		};
+	}
 	return defineEnginePlugin({
 		name: "core:important",
 		rawConfigConfigured(config) {
@@ -2146,10 +2300,13 @@ function important() {
 		transformStyleDefinitions(styleDefinitions) {
 			return styleDefinitions.map((styleDefinition) => {
 				const { __important, ...rest } = styleDefinition;
-				if ((__important ?? defaultValue) === false) return rest;
+				const explicit = __important;
+				const important = explicit ?? defaultValue;
+				if (important === false && explicit == null) return rest;
 				return Object.fromEntries(Object.entries(rest).map(([k, v]) => {
-					if (isPropertyValue(v)) return [k, modifyPropertyValue(v)];
-					return [k, v];
+					if (k === "__shortcut") return [k, v];
+					if (isPropertyValue(v)) return [k, important ? modifyPropertyValue(v) : v];
+					return [k, explicit == null ? v : propagateExplicitFlag(v, explicit)];
 				}));
 			});
 		}
@@ -2195,11 +2352,12 @@ function keyframes() {
 				}
 			};
 			engine.keyframes.add(...configList);
-			engine.addPreflight((engine) => {
+			engine.addPreflight((engine, _isFormatted, ctx) => {
 				const maybeUsedName = /* @__PURE__ */ new Set();
-				engine.store.atomicStyles.forEach(({ content: { property, value } }) => {
+				engine.store.atomicStyles.forEach(({ content: { property, value } }, id) => {
+					if (ctx?.usedAtomicStyleIds != null && ctx.usedAtomicStyleIds.has(id) === false) return;
 					if (property === "animation-name") {
-						value.forEach((name) => maybeUsedName.add(name));
+						value.forEach((name) => addToSet(maybeUsedName, ...name.split(",").map((v) => v.trim())));
 						return;
 					}
 					if (property === "animation") value.forEach((value) => {
@@ -2211,7 +2369,7 @@ function keyframes() {
 				const maybeUsedKeyframes = Array.from(engine.keyframes.store.values()).filter(({ name, frames, pruneUnused }) => (pruneUnused === false || maybeUsedName.has(name)) && frames != null);
 				const preflightDefinition = {};
 				maybeUsedKeyframes.forEach(({ name, frames }) => {
-					preflightDefinition[`@keyframes ${name}`] = Object.fromEntries(Object.entries(frames).map(([frame, properties]) => [frame, properties]));
+					preflightDefinition[`@keyframes ${name}`] = frames;
 				});
 				return preflightDefinition;
 			});
@@ -2268,6 +2426,10 @@ function stripGlobalFlag(re) {
 var AbstractResolver = class {
 	/** Cache of previously resolved input-string → result pairs. */
 	_resolvedResultsMap = /* @__PURE__ */ new Map();
+	/** Negative cache of input strings that matched no rule at all. Retryable-unresolved dynamic results (a matched dynamic rule whose value fn returned nullish) are never stored here. */
+	_unmatchedStrings = /* @__PURE__ */ new Set();
+	/** Index of static rules keyed by their exact match string (first registered rule wins on string collisions), giving O(1) static lookups. */
+	_staticRulesByString = /* @__PURE__ */ new Map();
 	/** Registry of static rules keyed by their unique key. */
 	staticRulesMap = /* @__PURE__ */ new Map();
 	/** Registry of dynamic rules keyed by their unique key. */
@@ -2286,7 +2448,7 @@ var AbstractResolver = class {
 	* @param rule - The static rule to register.
 	* @returns `this` for chaining.
 	*
-	* @remarks Overwrites any existing static rule with the same key.
+	* @remarks Overwrites any existing static rule with the same key. The entire resolution cache is cleared because cached results (including recursively expanded ones) may depend on the previous rule.
 	*
 	* @example
 	* ```ts
@@ -2295,7 +2457,14 @@ var AbstractResolver = class {
 	*/
 	addStaticRule(rule) {
 		log.debug(`Adding static rule: ${rule.key}`);
+		const previous = this.staticRulesMap.get(rule.key);
 		this.staticRulesMap.set(rule.key, rule);
+		if (previous != null) {
+			if (previous.string !== rule.string) this._reindexStaticRuleString(previous.string);
+			this._reindexStaticRuleString(rule.string);
+		} else if (this._staticRulesByString.has(rule.string) === false) this._staticRulesByString.set(rule.string, rule);
+		this._resolvedResultsMap.clear();
+		this._unmatchedStrings.clear();
 		return this;
 	}
 	/**
@@ -2304,7 +2473,7 @@ var AbstractResolver = class {
 	* @param key - The key of the static rule to remove.
 	* @returns `this` for chaining.
 	*
-	* @remarks Logs a warning if the key does not exist. Also evicts the cached result for the rule's input string.
+	* @remarks Logs a warning if the key does not exist. The entire resolution cache is cleared because cached results (including recursively expanded ones) may depend on the removed rule.
 	*
 	* @example
 	* ```ts
@@ -2319,16 +2488,32 @@ var AbstractResolver = class {
 		}
 		log.debug(`Removing static rule: ${key}`);
 		this.staticRulesMap.delete(key);
-		this._resolvedResultsMap.delete(rule.string);
+		if (this._staticRulesByString.get(rule.string) === rule) this._reindexStaticRuleString(rule.string);
+		this._resolvedResultsMap.clear();
+		this._unmatchedStrings.clear();
 		return this;
 	}
 	/**
+	* Recomputes the string-index entry for a given match string after a rule mutation.
+	*
+	* @param string - The match string whose index entry should be recomputed.
+	*
+	* @remarks Scans `staticRulesMap` in insertion order so the first registered rule matching the string wins, mirroring the pre-index linear-scan behavior. Removes the entry when no rule matches the string anymore.
+	*/
+	_reindexStaticRuleString(string) {
+		for (const rule of this.staticRulesMap.values()) if (rule.string === string) {
+			this._staticRulesByString.set(string, rule);
+			return;
+		}
+		this._staticRulesByString.delete(string);
+	}
+	/**
 	* Registers a dynamic rule in the resolver.
 	*
 	* @param rule - The dynamic rule to register.
 	* @returns `this` for chaining.
 	*
-	* @remarks Overwrites any existing dynamic rule with the same key.
+	* @remarks Overwrites any existing dynamic rule with the same key. The entire resolution cache is cleared because cached results (including recursively expanded ones) may depend on the previous rule.
 	*
 	* @example
 	* ```ts
@@ -2338,6 +2523,8 @@ var AbstractResolver = class {
 	addDynamicRule(rule) {
 		log.debug(`Adding dynamic rule: ${rule.key}`);
 		this.dynamicRulesMap.set(rule.key, rule);
+		this._resolvedResultsMap.clear();
+		this._unmatchedStrings.clear();
 		return this;
 	}
 	/**
@@ -2346,7 +2533,7 @@ var AbstractResolver = class {
 	* @param key - The key of the dynamic rule to remove.
 	* @returns `this` for chaining.
 	*
-	* @remarks Iterates through all cached results and deletes any whose input string matches the removed rule's pattern. Logs a warning if the key does not exist.
+	* @remarks Logs a warning if the key does not exist. The entire resolution cache is cleared because cached results (including recursively expanded ones) may depend on the removed rule.
 	*
 	* @example
 	* ```ts
@@ -2354,19 +2541,14 @@ var AbstractResolver = class {
 	* ```
 	*/
 	removeDynamicRule(key) {
-		const rule = this.dynamicRulesMap.get(key);
-		if (rule == null) {
+		if (this.dynamicRulesMap.get(key) == null) {
 			log.warn(`Dynamic rule not found for removal: ${key}`);
 			return this;
 		}
 		log.debug(`Removing dynamic rule: ${key}`);
-		const matchedResolvedStringList = Array.from(this._resolvedResultsMap.keys()).filter((string) => {
-			rule.stringPattern.lastIndex = 0;
-			return rule.stringPattern.test(string);
-		});
 		this.dynamicRulesMap.delete(key);
-		matchedResolvedStringList.forEach((string) => this._resolvedResultsMap.delete(string));
-		log.debug(`  - Cleared ${matchedResolvedStringList.length} cached results`);
+		this._resolvedResultsMap.clear();
+		this._unmatchedStrings.clear();
 		return this;
 	}
 	/**
@@ -2375,7 +2557,7 @@ var AbstractResolver = class {
 	* @param string - The input string to resolve.
 	* @returns The resolved result wrapper, or `null`/`undefined` if no rule matches.
 	*
-	* @remarks Results are cached for subsequent calls. Invokes `onResolved` after a successful match. Dynamic rule matching is async because `createResolved` may return a `Promise`.
+	* @remarks Results are cached for subsequent calls. Invokes `onResolved` after a successful match. Dynamic rule matching is async because `createResolved` may return a `Promise`. When a dynamic rule's `createResolved` returns `undefined`/`null`, the input is treated as unresolved and no cache entry is stored, so a later resolve call re-invokes the rule.
 	*
 	* @example
 	* ```ts
@@ -2388,7 +2570,11 @@ var AbstractResolver = class {
 			log.debug(`Resolved from cache: ${string}`);
 			return existedResult;
 		}
-		const staticRule = Array.from(this.staticRulesMap.values()).find((rule) => rule.string === string);
+		if (this._unmatchedStrings.has(string)) {
+			log.debug(`Resolution failed (cached): ${string}`);
+			return;
+		}
+		const staticRule = this._staticRulesByString.get(string);
 		if (staticRule != null) {
 			log.debug(`Resolved by static rule: ${staticRule.key}`);
 			const resolvedResult = { value: staticRule.resolved };
@@ -2407,13 +2593,19 @@ var AbstractResolver = class {
 			}
 		}
 		if (dynamicRule != null && matched != null) {
+			const value = await dynamicRule.createResolved(matched);
+			if (value == null) {
+				log.debug(`Dynamic rule "${dynamicRule.key}" returned no value for "${string}", treating as unresolved (not cached)`);
+				return;
+			}
 			log.debug(`Resolved by dynamic rule: ${dynamicRule.key}`);
-			const resolvedResult = { value: await dynamicRule.createResolved(matched) };
+			const resolvedResult = { value };
 			this._resolvedResultsMap.set(string, resolvedResult);
 			this.onResolved(string, "dynamic", resolvedResult);
 			return resolvedResult;
 		}
 		log.debug(`Resolution failed for: ${string}`);
+		this._unmatchedStrings.add(string);
 	}
 	/**
 	* Updates or creates the cached resolved result for a given input string.
@@ -2425,10 +2617,11 @@ var AbstractResolver = class {
 	*
 	* @example
 	* ```ts
-	* resolver._setResolvedResult('hover', ['&:hover'])
+	* resolver._setResolvedResult('hover', ['$:hover'])
 	* ```
 	*/
 	_setResolvedResult(string, resolved) {
+		this._unmatchedStrings.delete(string);
 		const resolvedResult = this._resolvedResultsMap.get(string);
 		if (resolvedResult) {
 			resolvedResult.value = resolved;
@@ -2449,7 +2642,7 @@ var AbstractResolver = class {
 * ```ts
 * class SelectorResolver extends RecursiveResolver<string> { }
 * const result = await resolver.resolve('hover-focus')
-* // ['&:hover', '&:focus'] after recursive expansion
+* // ['$:hover', '$:focus'] after recursive expansion
 * ```
 */
 var RecursiveResolver = class extends AbstractResolver {
@@ -2485,6 +2678,13 @@ var RecursiveResolver = class extends AbstractResolver {
 		return result;
 	}
 };
+function createDynamicResolvedFactory(fn) {
+	return async (match) => {
+		const value = await fn(match);
+		if (value == null) return value;
+		return [value].flat(1);
+	};
+}
 /**
 * Normalizes a user-supplied rule shorthand into a `ResolvedRuleConfig`, a plain redirect string, or `undefined`.
 * @internal
@@ -2499,61 +2699,44 @@ var RecursiveResolver = class extends AbstractResolver {
 * - **Tuple**: `[string, T | T[]]` for static rules, `[RegExp, fn, autocomplete?]` for dynamic rules.
 * - **Object**: `{ [keyName]: string | RegExp, value: T | fn, autocomplete?: string[] }`.
 *
+* A dynamic rule's value function may return `undefined`/`null` to signal a retryable-unresolved result: the resolver treats the input as unresolved and stores no cache entry, so the rule is re-invoked on a later resolve call.
+*
 * @example
 * ```ts
-* resolveRuleConfig(['hover', '&:hover'], 'selector')
+* resolveRuleConfig(['hover', '$:hover'], 'selector')
 * // { type: 'static', rule: { key: 'hover', ... }, autocomplete: ['hover'] }
 * ```
 */
 function resolveRuleConfig(config, keyName) {
 	if (typeof config === "string") return config;
-	if (Array.isArray(config)) {
-		if (typeof config[0] === "string" && typeof config[1] !== "function") return {
-			type: "static",
-			rule: {
-				key: config[0],
-				string: config[0],
-				resolved: [config[1]].flat(1)
-			},
-			autocomplete: [config[0]]
-		};
-		if (config[0] instanceof RegExp && typeof config[1] === "function") {
-			const fn = config[1];
-			return {
-				type: "dynamic",
-				rule: {
-					key: config[0].source,
-					stringPattern: stripGlobalFlag(config[0]),
-					createResolved: async (match) => [await fn(match)].flat(1)
-				},
-				autocomplete: config[2] != null ? [config[2]].flat(1) : []
-			};
-		}
-		return;
-	}
 	if (typeof config !== "object" || config === null) return;
-	const configKey = config[keyName];
-	if (typeof configKey === "string" && typeof config.value !== "function") return {
+	const { key, value, autocomplete } = Array.isArray(config) ? {
+		key: config[0],
+		value: config[1],
+		autocomplete: config[2]
+	} : {
+		key: config[keyName],
+		value: config.value,
+		autocomplete: config.autocomplete
+	};
+	if (typeof key === "string" && typeof value !== "function") return {
 		type: "static",
 		rule: {
-			key: configKey,
-			string: configKey,
-			resolved: [config.value].flat(1)
+			key,
+			string: key,
+			resolved: [value].flat(1)
 		},
-		autocomplete: [configKey]
+		autocomplete: [key]
+	};
+	if (key instanceof RegExp && typeof value === "function") return {
+		type: "dynamic",
+		rule: {
+			key: key.source,
+			stringPattern: stripGlobalFlag(key),
+			createResolved: createDynamicResolvedFactory(value)
+		},
+		autocomplete: autocomplete != null ? [autocomplete].flat(1) : []
 	};
-	if (configKey instanceof RegExp && typeof config.value === "function") {
-		const fn = config.value;
-		return {
-			type: "dynamic",
-			rule: {
-				key: configKey.source,
-				stringPattern: stripGlobalFlag(configKey),
-				createResolved: async (match) => [await fn(match)].flat(1)
-			},
-			autocomplete: "autocomplete" in config && config.autocomplete != null ? [config.autocomplete].flat(1) : []
-		};
-	}
 }
 //#endregion
 //#region src/plugins/selectors.ts
@@ -2589,11 +2772,8 @@ function selectors() {
 							engine.appendAutocomplete({ selectors: resolved });
 							return;
 						}
-						const addRule = {
-							static: () => engine.selectors.resolver.addStaticRule(resolved.rule),
-							dynamic: () => engine.selectors.resolver.addDynamicRule(resolved.rule)
-						}[resolved.type];
-						addRule?.();
+						if (resolved.type === "static") engine.selectors.resolver.addStaticRule(resolved.rule);
+						else engine.selectors.resolver.addDynamicRule(resolved.rule);
 						engine.appendAutocomplete({ selectors: resolved.autocomplete });
 					});
 				}
@@ -2621,7 +2801,7 @@ var SelectorResolver = class extends RecursiveResolver {};
 *
 * @example
 * ```ts
-* const resolved = resolveSelectorConfig(['hover', '&:hover'])
+* const resolved = resolveSelectorConfig(['hover', '$:hover'])
 * ```
 */
 function resolveSelectorConfig(config) {
@@ -2661,11 +2841,8 @@ function shortcuts() {
 							engine.appendAutocomplete({ shortcuts: resolved });
 							return;
 						}
-						const addRule = {
-							static: () => engine.shortcuts.resolver.addStaticRule(resolved.rule),
-							dynamic: () => engine.shortcuts.resolver.addDynamicRule(resolved.rule)
-						}[resolved.type];
-						addRule?.();
+						if (resolved.type === "static") engine.shortcuts.resolver.addStaticRule(resolved.rule);
+						else engine.shortcuts.resolver.addDynamicRule(resolved.rule);
 						engine.appendAutocomplete({ shortcuts: resolved.autocomplete });
 					});
 				}
@@ -2695,10 +2872,14 @@ function shortcuts() {
 			const result = [];
 			for (const styleDefinition of styleDefinitions) if ("__shortcut" in styleDefinition) {
 				const { __shortcut, ...rest } = styleDefinition;
+				const explicitImportant = rest.__important ?? null;
 				const applied = [];
 				for (const shortcut of __shortcut == null ? [] : [__shortcut].flat(1)) {
 					const resolved = (await engine.shortcuts.resolver.resolve(shortcut)).filter(isNotString);
-					applied.push(...resolved);
+					applied.push(...explicitImportant == null ? resolved : resolved.map((definition) => ({
+						__important: explicitImportant,
+						...definition
+					})));
 				}
 				result.push(...applied, rest);
 			} else result.push(styleDefinition);
@@ -2758,18 +2939,22 @@ function variables() {
 			rawVariables.forEach((variables) => engine.variables.add(variables));
 			engine.addPreflight({
 				id: "core:variables",
-				preflight: async (engine) => {
+				preflight: async (engine, isFormatted, ctx) => {
 					const used = /* @__PURE__ */ new Set();
-					engine.store.atomicStyles.forEach(({ content: { value } }) => {
+					engine.store.atomicStyles.forEach(({ content: { value } }, id) => {
+						if (ctx?.usedAtomicStyleIds != null && ctx.usedAtomicStyleIds.has(id) === false) return;
 						value.flatMap(extractUsedVarNames).forEach((name) => used.add(normalizeVariableName(name)));
 					});
 					const otherPreflights = engine.config.preflights.filter((p) => p.id !== "core:variables");
-					(await Promise.all(otherPreflights.map(({ fn }) => Promise.resolve().then(() => fn(engine, false)).catch(() => null)))).forEach((result) => {
+					(await Promise.all(otherPreflights.map(({ fn }) => engine.invokePreflight(fn, isFormatted, ctx).catch(() => null)))).forEach((result) => {
 						if (result == null) return;
 						extractUsedVarNamesFromPreflightResult(result).forEach((name) => used.add(name));
 					});
-					const varMap = /* @__PURE__ */ new Map();
-					for (const [name, list] of engine.variables.store.entries()) varMap.set(name, list);
+					const varMap = engine.variables.store;
+					for (const [name, entries] of varMap.entries()) {
+						if (used.has(name)) continue;
+						if (safeSet.has(name) || entries.some((entry) => entry.pruneUnused === false)) used.add(name);
+					}
 					const queue = Array.from(used);
 					while (queue.length > 0) {
 						const name = queue.pop();
@@ -2816,9 +3001,6 @@ function mergeVariablesDefinition(target, source) {
 	}
 	return target;
 }
-function isPlainObjectRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function createResolveVariablesFn({ pruneUnused: defaultPruneUnused = true } = {}) {
 	function _resolveVariables(variables, levels, result) {
 		for (const [key, value] of Object.entries(variables)) if (key.startsWith("--")) {
@@ -2857,7 +3039,7 @@ function resolveAutocompleteValueTargets({ asValueOf }) {
 	if (targets.has("*")) return ["*"];
 	return [...targets];
 }
-const VAR_NAME_RE = /var\((--[\w-]+)/g;
+const VAR_NAME_RE = /var\(\s*(--[\w-]+)/g;
 /**
 * Extracts all CSS variable names referenced via `var(--*)` calls in a string.
 *
@@ -2977,11 +3159,11 @@ const DEFAULT_LAYERS = {
 async function createEngine(config = {}) {
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
-		important(),
 		variables(),
 		keyframes(),
 		selectors(),
-		shortcuts()
+		shortcuts(),
+		important()
 	];
 	log.debug("Core plugins loaded:", corePlugins.length);
 	const plugins = resolvePlugins([...corePlugins, ...config.plugins || []]);
@@ -3027,6 +3209,12 @@ var Engine = class {
 	/** The engine's runtime store holding registered atomic styles and their ID mappings. */
 	store = createEngineStore();
 	/**
+	* Absolute paths of external files this engine's config depends on (e.g. token files loaded by plugins).
+	*
+	* @remarks Plugins register paths via `addConfigDependency` during `configureEngine`. Integration layers (e.g. the unplugin) watch these files and re-create the engine when they change.
+	*/
+	configDependencies = /* @__PURE__ */ new Set();
+	/**
 	* Creates an engine instance from a resolved configuration.
 	*
 	* @param config - The fully resolved engine configuration.
@@ -3048,6 +3236,45 @@ var Engine = class {
 		});
 	}
 	/**
+	* Invokes a preflight function, memoizing the result in the given render-pass context.
+	*
+	* @param fn - The preflight function to invoke.
+	* @param isFormatted - Whether the preflight should produce formatted output.
+	* @param ctx - The render-pass context created by `renderPreflights`. When provided, each function executes at most once per pass and the context is forwarded to the preflight function.
+	* @returns A promise of the preflight result.
+	*
+	* @remarks Within one render pass each function executes at most once; concurrent callers (e.g. the variables pruning preflight scanning other preflights for `var()` usage) share the same promise. The memoization is scoped to `ctx`, so overlapping `renderPreflights` calls never interfere with each other. Without a context the function is invoked directly without caching — this is a deliberate change from the previous instance-scoped memoization, which could not tell overlapping passes apart. A preflight that inspects other preflights must therefore forward the `ctx` it receives (its third argument); calling with only `(fn, isFormatted)` from inside a pass runs `fn` again instead of reusing the pass result.
+	*
+	* @example
+	* ```ts
+	* const result = await engine.invokePreflight(preflight.fn, false, ctx)
+	* ```
+	*/
+	invokePreflight(fn, isFormatted, ctx) {
+		if (ctx == null) return Promise.resolve().then(() => fn(this, isFormatted));
+		let invocation = ctx.invocations.get(fn);
+		if (invocation == null) {
+			invocation = Promise.resolve().then(() => fn(this, isFormatted, ctx));
+			ctx.invocations.set(fn, invocation);
+		}
+		return invocation;
+	}
+	/**
+	* Registers an external file path as a config dependency of this engine.
+	*
+	* @param path - The file path (ideally absolute) the current config was derived from.
+	*
+	* @remarks Call from a plugin (typically in `configureEngine`) after loading data from disk. Integration layers watch registered paths and rebuild the engine when any of them changes.
+	*
+	* @example
+	* ```ts
+	* engine.addConfigDependency('/project/design.md')
+	* ```
+	*/
+	addConfigDependency(path) {
+		this.configDependencies.add(path);
+	}
+	/**
 	* Fires the `preflightUpdated` hook to notify plugins that preflight content has changed.
 	*
 	*
@@ -3145,7 +3372,7 @@ var Engine = class {
 	* Processes style items through the plugin pipeline and registers the resulting atomic styles in the store.
 	*
 	* @param itemList - Style items to process: string references (shortcuts) and/or style definition objects.
-	* @returns An array of atomic style IDs (and unresolved string references) in insertion order.
+	* @returns An array containing any unresolved string references first, followed by atomic style IDs in resolution order.
 	*
 	* @remarks Runs `transformStyleItems` and `extractStyleDefinition` hooks, resolves each extracted content into an atomic style, deduplicates by base key, and fires `atomicStyleAdded` for new entries.
 	*
@@ -3184,20 +3411,27 @@ var Engine = class {
 	* Renders all registered preflight definitions into a CSS string.
 	*
 	* @param isFormatted - Whether to produce human-readable CSS with newlines and indentation.
+	* @param options - Optional render-pass options.
+	* @param options.usedAtomicStyleIds - Atomic style IDs considered "in use" for this pass. When provided, pruning preflights (variables, keyframes) only consider these atomic styles instead of the whole append-only store; when omitted, all stored atomic styles are considered.
 	* @returns The rendered preflight CSS, including `@import` statements, optional `@layer` wrappers, and all preflight content.
 	*
-	* @remarks Evaluates each preflight function, groups output by layer, wraps unlayered preflights in the default preflights layer (when present), and respects configured layer ordering.
+	* @remarks Evaluates each preflight function, groups output by layer, wraps unlayered preflights in the default preflights layer (when present), and respects configured layer ordering. Each call creates its own `PreflightContext`, so within one pass each preflight function executes exactly once even when passes overlap.
 	*
 	* @example
 	* ```ts
 	* const css = await engine.renderPreflights(true)
+	* const scoped = await engine.renderPreflights(true, { usedAtomicStyleIds: ['pk-a'] })
 	* ```
 	*/
-	async renderPreflights(isFormatted) {
+	async renderPreflights(isFormatted, options = {}) {
 		log.debug("Rendering preflights...");
 		const lineEnd = isFormatted ? "\n" : "";
+		const ctx = {
+			invocations: /* @__PURE__ */ new Map(),
+			usedAtomicStyleIds: options.usedAtomicStyleIds == null ? void 0 : new Set(options.usedAtomicStyleIds)
+		};
 		const rendered = (await Promise.all(this.config.preflights.map(async ({ layer, fn }) => {
-			const result = await fn(this, isFormatted);
+			const result = await this.invokePreflight(fn, isFormatted, ctx);
 			return {
 				layer,
 				css: (typeof result === "string" ? result : await renderPreflightDefinition({
@@ -3394,15 +3628,10 @@ function groupAtomicStylesByLayer({ styles, layerOrder, defaultUtilitiesLayer })
 		layerGroups
 	};
 }
-function isWithLayer(p) {
-	if (typeof p !== "object" || p === null) return false;
-	const record = p;
-	return typeof record.layer === "string" && record.preflight !== void 0;
-}
-function isWithId(p) {
+function hasPreflightWrapper(p, key) {
 	if (typeof p !== "object" || p === null) return false;
 	const record = p;
-	return typeof record.id === "string" && record.preflight !== void 0;
+	return typeof record[key] === "string" && record.preflight !== void 0;
 }
 /**
 * Normalizes a `Preflight` input into a `ResolvedPreflight` by extracting optional `layer` and `id` wrappers.
@@ -3421,11 +3650,11 @@ function isWithId(p) {
 function resolvePreflight(preflight) {
 	let layer;
 	let id;
-	if (isWithLayer(preflight)) {
+	if (hasPreflightWrapper(preflight, "layer")) {
 		layer = preflight.layer;
 		preflight = preflight.preflight;
 	}
-	if (isWithId(preflight)) {
+	if (hasPreflightWrapper(preflight, "id")) {
 		id = preflight.id;
 		preflight = preflight.preflight;
 	}
@@ -3543,9 +3772,9 @@ function renderAtomicStylesCss({ atomicStyles, isPreview, isFormatted }) {
 	const blocks = /* @__PURE__ */ new Map();
 	atomicStyles.forEach(({ id, content: { selector: rawSelector, property, value } }) => {
 		const { selector } = splitLayerSelector(rawSelector);
-		if (selector.some((s) => s.includes("%")) === false || value == null) return;
+		if (selector.some((s) => hasAtomicStyleIdPlaceholder(s)) === false || value == null) return;
 		const renderObject = {
-			selector: isPreview ? selector : selector.map((s) => s.replace(ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, id)),
+			selector: isPreview ? selector : selector.map((s) => replaceAtomicStyleIdPlaceholder(s, id)),
 			properties: value.map((v) => ({
 				property,
 				value: v
@@ -3720,4 +3949,4 @@ function defineEngineConfig(config) {
 }
 /* c8 ignore end */
 //#endregion
-export { appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, log, renderCSSStyleBlocks, sortLayerNames };
+export { appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, isPlainObjectRecord, log, renderCSSStyleBlocks, sortLayerNames };