@pikacss/core 0.0.47 → 0.0.49

package/dist/index.mjs

@@ -810,7 +810,6 @@ const PROPERTY_EFFECTS = {
 	"z-index": ["z-index"],
 	"zoom": ["zoom"]
 };
-
 //#endregion
 //#region src/internal/property-effects.ts
 const UNIVERSAL_EFFECT = "*";
@@ -821,11 +820,45 @@ function isCustomProperty(property) {
 function isVendorPrefixedProperty(property) {
 	return property.startsWith("-") && property.startsWith("--") === false;
 }
+/**
+* Returns the list of CSS properties that a given property can affect, accounting for shorthand expansion.
+* @internal
+*
+* @param property - A CSS property name in kebab-case.
+* @returns An array of affected property names. For the `all` shorthand, returns `['*']`. For custom or vendor-prefixed properties, returns the property itself. For standard shorthands, returns the set of longhand properties they expand to.
+*
+* @remarks Used by the order-sensitivity detection logic to determine whether two properties in the same scope share overlapping effects (e.g. `margin` and `margin-top`). The lookup map is generated at build time from the CSS shorthand specification.
+*
+* @example
+* ```ts
+* getPropertyEffects('margin')    // ['margin-top', 'margin-right', 'margin-bottom', 'margin-left']
+* getPropertyEffects('color')     // ['color']
+* getPropertyEffects('--my-var')  // ['--my-var']
+* getPropertyEffects('all')       // ['*']
+* ```
+*/
 function getPropertyEffects(property) {
 	if (property === "all") return [UNIVERSAL_EFFECT];
 	if (isCustomProperty(property) || isVendorPrefixedProperty(property)) return [property];
 	return propertyEffectsLookup[property] || [property];
 }
+/**
+* Determines whether two CSS properties have overlapping effects, meaning they can interfere with each other when both are present in the same selector scope.
+* @internal
+*
+* @param left - First CSS property name in kebab-case.
+* @param right - Second CSS property name in kebab-case.
+* @returns `true` if the two properties share at least one common affected property or if either is the universal `all` shorthand.
+*
+* @remarks Custom properties never overlap with other properties. Identical properties always overlap. This check drives the order-sensitivity detection in `optimizeAtomicStyleContents`, ensuring that shorthand/longhand conflicts like `margin` + `margin-top` are correctly handled.
+*
+* @example
+* ```ts
+* hasPropertyEffectOverlap('margin', 'margin-top')  // true
+* hasPropertyEffectOverlap('color', 'font-size')     // false
+* hasPropertyEffectOverlap('all', 'color')            // true
+* ```
+*/
 function hasPropertyEffectOverlap(left, right) {
 	if (left === right) return true;
 	if (isCustomProperty(left) || isCustomProperty(right)) return false;
@@ -835,9 +868,24 @@ function hasPropertyEffectOverlap(left, right) {
 	const rightEffectSet = new Set(rightEffects);
 	return leftEffects.some((effect) => rightEffectSet.has(effect));
 }
-
 //#endregion
 //#region src/internal/utils.ts
+/**
+* Creates a scoped logger with configurable log-level functions and a toggleable debug mode.
+*
+* @param prefix - Label prepended to every log message (e.g. `'[PikaCSS]'`).
+* @returns A logger object with `debug`, `info`, `warn`, `error` methods and configuration setters.
+*
+* @remarks Debug messages are suppressed by default. Call `log.toggleDebug()` to enable them. Each log level can be replaced with a custom implementation via the `set*Fn` methods, which is useful for redirecting output in non-browser environments.
+*
+* @example
+* ```ts
+* const log = createLogger('[MyPlugin]')
+* log.info('initialized')  // '[MyPlugin][INFO] initialized'
+* log.toggleDebug()
+* log.debug('verbose info') // '[MyPlugin][DEBUG] verbose info'
+* ```
+*/
 function createLogger(prefix) {
 	let currentPrefix = prefix;
 	let enabledDebug = false;
@@ -879,9 +927,36 @@ function createLogger(prefix) {
 		}
 	};
 }
+/**
+* Default logger instance used throughout the PikaCSS core engine, prefixed with `[PikaCSS]`.
+*
+* @remarks Shared across all internal modules. Plugins and integration code can call `log.toggleDebug()` to enable verbose output during development.
+*
+* @example
+* ```ts
+* log.info('Engine created')
+* log.warn('Unknown layer detected')
+* ```
+*/
 const log = createLogger("[PikaCSS]");
 const chars = [..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"];
 const numOfChars = chars.length;
+/**
+* Converts a non-negative integer to a compact alphabetic string using a bijective base-52 encoding (a-z, A-Z).
+* @internal
+*
+* @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.
+*
+* @example
+* ```ts
+* numberToChars(0)  // 'a'
+* numberToChars(51) // 'Z'
+* numberToChars(52) // 'ba'
+* ```
+*/
 function numberToChars(num) {
 	if (num < numOfChars) return chars[num];
 	let result = "";
@@ -893,34 +968,164 @@ function numberToChars(num) {
 	return result;
 }
 const UPPER_CASE = /[A-Z]/g;
+/**
+* Converts a camelCase string to kebab-case at runtime. CSS custom properties (`--*`) are returned unchanged.
+* @internal
+*
+* @param str - The camelCase string to convert.
+* @returns The kebab-case equivalent of the input string.
+*
+* @remarks Runtime counterpart of the `ToKebab` type utility. Used during style extraction to normalize JavaScript-style property names to CSS property names.
+*
+* @example
+* ```ts
+* toKebab('backgroundColor') // 'background-color'
+* toKebab('--my-var')        // '--my-var'
+* ```
+*/
 function toKebab(str) {
 	if (str.startsWith("--")) return str;
 	return str.replace(UPPER_CASE, (c) => `-${c.toLowerCase()}`);
 }
+/**
+* Type-narrowing guard that returns `true` when the value is neither `null` nor `undefined`.
+* @internal
+*
+* @typeParam T - The type of the input value.
+* @param value - The value to test.
+* @returns `true` if the value is non-nullish, narrowing the type to `NonNullable<T>`.
+*
+* @remarks Commonly used as a `.filter()` predicate to strip nullish entries from arrays while preserving the narrowed type.
+*
+* @example
+* ```ts
+* [1, null, 2, undefined].filter(isNotNullish) // [1, 2] typed as number[]
+* ```
+*/
 function isNotNullish(value) {
 	return value != null;
 }
+/**
+* Type-narrowing guard that returns `true` when the value is not a string, narrowing the type to `Exclude<V, string>`.
+* @internal
+*
+* @typeParam V - The union type of the input value.
+* @param value - The value to test.
+* @returns `true` if the value is not a `string`.
+*
+* @remarks Useful for filtering processed style items to separate resolved definition objects from unresolved string references.
+*
+* @example
+* ```ts
+* const items: (string | object)[] = ['btn', { color: 'red' }]
+* const objects = items.filter(isNotString) // [{ color: 'red' }]
+* ```
+*/
 function isNotString(value) {
 	return typeof value !== "string";
 }
+/**
+* Tests whether a value conforms to the `InternalPropertyValue` shape: a string, 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.
+*
+* @example
+* ```ts
+* isPropertyValue('red')                  // true
+* isPropertyValue(['red', ['blue']])       // 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 (v == null) return true;
 	if (typeof v === "string") return true;
 	return false;
 }
+/**
+* Serializes a value to a JSON string for use as a deterministic cache key.
+* @internal
+*
+* @param value - The value to serialize.
+* @returns The JSON string representation.
+*
+* @remarks Used to produce stable keys for selector chains and property content when building deduplication maps in the optimization pipeline.
+*
+* @example
+* ```ts
+* serialize(['.pk-%', 'color']) // '[[".pk-%"],"color"]'
+* ```
+*/
 function serialize(value) {
 	return JSON.stringify(value);
 }
+/**
+* Adds one or more values to a `Set` and returns whether the set's size increased.
+* @internal
+*
+* @typeParam T - The element type of the set.
+* @param set - The target set to append to.
+* @param values - Values to add.
+* @returns `true` if at least one new element was added (the set grew).
+*
+* @remarks The boolean return is used by `appendAutocomplete` to determine whether the autocomplete config actually changed, avoiding unnecessary notification callbacks.
+*
+* @example
+* ```ts
+* const s = new Set(['a'])
+* addToSet(s, 'a', 'b') // true (added 'b')
+* addToSet(s, 'a')      // false (no change)
+* ```
+*/
 function addToSet(set, ...values) {
 	const before = set.size;
 	values.forEach((value) => set.add(value));
 	return set.size !== before;
 }
+/**
+* Flattens an `Arrayable<string>` value and adds all entries to a `Set`, returning whether the set grew.
+* @internal
+*
+* @param set - The target set to append to.
+* @param values - A single string or array of strings to add, or `undefined`/`null` to skip.
+* @returns `true` if at least one new entry was added; `false` if the input was nullish or all entries already existed.
+*
+* @remarks Short-circuits on nullish input for convenience, since many autocomplete contribution fields are optional.
+*
+* @example
+* ```ts
+* const s = new Set<string>()
+* appendAutocompleteEntries(s, 'hover')       // true
+* appendAutocompleteEntries(s, ['hover'])      // false (already present)
+* appendAutocompleteEntries(s, undefined)      // false
+* ```
+*/
 function appendAutocompleteEntries(set, values) {
 	if (values == null) return false;
 	return addToSet(set, ...[values].flat());
 }
+/**
+* Merges a record of `Arrayable<string>` values into a `Map<string, string[]>`, returning whether any entry was added.
+* @internal
+*
+* @param map - The target map to append entries to.
+* @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.
+*
+* @example
+* ```ts
+* const map = new Map<string, string[]>()
+* appendAutocompleteRecordEntries(map, { color: ['red', 'blue'] }) // true
+* appendAutocompleteRecordEntries(map, { color: 'green' })         // true (now ['red','blue','green'])
+* ```
+*/
 function appendAutocompleteRecordEntries(map, entries) {
 	if (entries == null) return false;
 	let changed = false;
@@ -937,21 +1142,56 @@ function normalizeAutocompleteRecordEntries(entries) {
 	if (entries == null) return void 0;
 	return Array.isArray(entries) ? Object.fromEntries(entries) : entries;
 }
+/**
+* Merges an `AutocompleteContribution` or `AutocompleteConfig` into the resolved autocomplete state, returning whether any entry changed.
+*
+* @param config - The resolved engine config (or a subset with the `autocomplete` field) to mutate.
+* @param contribution - The autocomplete entries to merge in.
+* @returns `true` if any selector, shortcut, property, CSS property, or pattern entry was added or extended.
+*
+* @remarks Called by `engine.appendAutocomplete()` and during initial config resolution. Each sub-field (selectors, shortcuts, etc.) is independently merged and the function returns `true` if any of them changed, which triggers an `autocompleteConfigUpdated` notification.
+*
+* @example
+* ```ts
+* const changed = appendAutocomplete(resolvedConfig, {
+*   selectors: 'dark',
+*   cssProperties: { color: 'primary' },
+* })
+* ```
+*/
 function appendAutocomplete(config, contribution) {
 	const { patterns, properties, cssProperties, ...literals } = contribution;
 	return [
 		appendAutocompleteEntries(config.autocomplete.selectors, literals.selectors),
-		appendAutocompleteEntries(config.autocomplete.styleItemStrings, literals.styleItemStrings),
+		appendAutocompleteEntries(config.autocomplete.shortcuts, literals.shortcuts),
 		appendAutocompleteEntries(config.autocomplete.extraProperties, literals.extraProperties),
 		appendAutocompleteEntries(config.autocomplete.extraCssProperties, literals.extraCssProperties),
 		appendAutocompleteRecordEntries(config.autocomplete.properties, normalizeAutocompleteRecordEntries(properties)),
 		appendAutocompleteRecordEntries(config.autocomplete.cssProperties, normalizeAutocompleteRecordEntries(cssProperties)),
 		appendAutocompleteEntries(config.autocomplete.patterns.selectors, patterns?.selectors),
-		appendAutocompleteEntries(config.autocomplete.patterns.styleItemStrings, patterns?.styleItemStrings),
+		appendAutocompleteEntries(config.autocomplete.patterns.shortcuts, patterns?.shortcuts),
 		appendAutocompleteRecordEntries(config.autocomplete.patterns.properties, patterns?.properties),
 		appendAutocompleteRecordEntries(config.autocomplete.patterns.cssProperties, patterns?.cssProperties)
 	].some(Boolean);
 }
+/**
+* Serializes a `CSSStyleBlocks` tree into a CSS string, optionally formatted with indentation and newlines.
+*
+* @param blocks - The CSS block tree to render.
+* @param isFormatted - When `true`, output includes indentation and newlines for readability; when `false`, output is minified.
+* @param depth - Current nesting depth for indentation (defaults to `0`).
+* @returns The rendered CSS string.
+*
+* @remarks Recursively renders nested blocks (e.g. media queries wrapping selectors). Empty blocks (no properties and no children) are omitted from the output.
+*
+* @example
+* ```ts
+* const blocks: CSSStyleBlocks = new Map()
+* blocks.set('.pk-a', { properties: [{ property: 'color', value: 'red' }] })
+* renderCSSStyleBlocks(blocks, true)
+* // '.pk-a {\n  color: red;\n}'
+* ```
+*/
 function renderCSSStyleBlocks(blocks, isFormatted, depth = 0) {
 	const blockIndent = isFormatted ? "  ".repeat(depth) : "";
 	const blockBodyIndent = isFormatted ? "  ".repeat(depth + 1) : "";
@@ -970,9 +1210,22 @@ function renderCSSStyleBlocks(blocks, isFormatted, depth = 0) {
 	});
 	return lines.join(lineEnd);
 }
-
 //#endregion
 //#region src/internal/atomic-style.ts
+/**
+* Creates a fresh, empty `EngineStore` with all maps initialized.
+* @internal
+*
+* @returns A new `EngineStore` instance with empty maps.
+*
+* @remarks Called once during engine construction. Each engine instance owns a single store.
+*
+* @example
+* ```ts
+* const store = createEngineStore()
+* store.atomicStyles.size // 0
+* ```
+*/
 function createEngineStore() {
 	return {
 		atomicStyleIds: /* @__PURE__ */ new Map(),
@@ -981,6 +1234,24 @@ function createEngineStore() {
 		atomicStyleOrder: /* @__PURE__ */ new Map()
 	};
 }
+/**
+* Assigns or retrieves a compact atomic style ID for the given resolved style content.
+* @internal
+*
+* @param options - Object containing the style `content`, the engine `prefix`, and the `stored` ID map.
+* @param options.content - The resolved style content to hash and identify.
+* @param options.prefix - The class-name prefix used when constructing a new atomic style ID.
+* @param options.stored - The map that caches assigned IDs by serialized key.
+* @returns The short alphabetic ID string (e.g. `'pk-a'`, `'pk-bA'`).
+*
+* @remarks For non-order-sensitive content, returns a cached ID if one already exists for the same base key. For order-sensitive content (where `orderSensitiveTo` is set), always generates a new ID to prevent incorrect reuse across different call-site orderings.
+*
+* @example
+* ```ts
+* const id = getAtomicStyleId({ content, prefix: 'pk-', stored: store.atomicStyleIds })
+* // 'pk-a'
+* ```
+*/
 function getAtomicStyleId({ content, prefix, stored }) {
 	const baseKey = getAtomicStyleBaseKey(content);
 	if (isOrderSensitiveContent(content) === false) {
@@ -1001,6 +1272,26 @@ function getAtomicStyleId({ content, prefix, stored }) {
 	log.debug(`Generated new atomic style ID: ${id}`);
 	return id;
 }
+/**
+* Resolves a `StyleContent` into an atomic style: either reusing an existing ID or creating a new `AtomicStyle` entry in the store.
+* @internal
+*
+* @param options - Object containing the style `content`, `prefix`, `store`, and the per-use-call `resolvedIdsByBaseKey` map for order-sensitive reuse tracking.
+* @param options.content - The style content to resolve into a cached or newly registered atomic style.
+* @param options.prefix - The atomic style ID prefix for any newly created IDs.
+* @param options.store - The engine store holding existing atomic styles and lookup maps.
+* @param options.resolvedIdsByBaseKey - Per-call memoization map for reusing order-sensitive IDs within one `engine.use()` execution.
+* @returns An `AtomicStyleResolution` with the assigned `id` and optionally the newly created `atomicStyle` (absent when the ID was already registered).
+*
+* @remarks First checks for reusable order-sensitive IDs within the current `engine.use()` call, then falls back to `getAtomicStyleId` for general ID assignment. When a new atomic style is created, it is registered in all store indices.
+*
+* @example
+* ```ts
+* const { id, atomicStyle } = resolveAtomicStyle({
+*   content, prefix: 'pk-', store, resolvedIdsByBaseKey,
+* })
+* ```
+*/
 function resolveAtomicStyle({ content, prefix, store, resolvedIdsByBaseKey }) {
 	const reusableId = findReusableOrderSensitiveAtomicStyleId({
 		content,
@@ -1027,6 +1318,19 @@ function resolveAtomicStyle({ content, prefix, store, resolvedIdsByBaseKey }) {
 		atomicStyle
 	};
 }
+/**
+* Deduplicates and optimizes a list of extracted style contents by merging duplicate selector-property pairs and detecting order-sensitive shorthand overlaps.
+* @internal
+* @param list - The raw extracted style contents to optimize.
+* @returns An optimized array of `StyleContent` entries with nullish-value removals applied and `orderSensitiveTo` metadata attached where needed.
+*
+* @remarks Later definitions of the same selector-property pair cancel earlier ones. When two properties in the same scope share overlapping CSS effects (e.g. `margin` and `margin-top`), the later one is marked as order-sensitive to prevent incorrect ID reuse.
+*
+* @example
+* ```ts
+* const optimized = optimizeAtomicStyleContents(extractedList)
+* ```
+*/
 function optimizeAtomicStyleContents(list) {
 	const map = /* @__PURE__ */ new Map();
 	const scopedEntries = /* @__PURE__ */ new Map();
@@ -1051,6 +1355,20 @@ function optimizeAtomicStyleContents(list) {
 	});
 	return [...map.values()];
 }
+/**
+* Computes the base cache key for an atomic style from its selector, property, and value.
+* @internal
+*
+* @param content - An object with `selector`, `property`, and `value` fields.
+* @returns A deterministic serialized string key.
+*
+* @remarks Used for deduplication: two atomic styles with the same base key are considered equivalent (unless order-sensitive). The key is derived by serializing the triple `[selector, property, value]`.
+*
+* @example
+* ```ts
+* const key = getAtomicStyleBaseKey({ selector: ['.pk-__ID__'], property: 'color', value: ['red'] })
+* ```
+*/
 function getAtomicStyleBaseKey(content) {
 	return serialize([
 		content.selector,
@@ -1091,7 +1409,7 @@ function findReusableOrderSensitiveAtomicStyleId({ content, store, resolvedIdsBy
 	if (isOrderSensitiveContent(content) === false) return void 0;
 	const baseKey = getAtomicStyleBaseKey(content);
 	const requiredOrder = getRequiredAtomicStyleOrder({
-		dependencyKeys: content.orderSensitiveTo ?? [],
+		dependencyKeys: content.orderSensitiveTo,
 		store,
 		resolvedIdsByBaseKey
 	});
@@ -1105,14 +1423,22 @@ function getOrderSensitiveDependencyKeys(scoped, property) {
 	for (const existing of scoped.values()) if (hasPropertyEffectOverlap(existing.property, property)) dependencyKeys.push(getAtomicStyleBaseKey(existing));
 	return dependencyKeys;
 }
-
 //#endregion
 //#region src/internal/constants.ts
+/**
+* CSS `@layer` at-rule prefix used when constructing layer-scoped selectors
+* in generated stylesheet output.
+*
+* @internal
+*/
 const LAYER_SELECTOR_PREFIX = "@layer ";
-const DEFAULT_ATOMIC_STYLE_ID_PREFIX = "pk-";
-const ATOMIC_STYLE_ID_PLACEHOLDER = "%";
+/**
+* Global regex matching all occurrences of {@link ATOMIC_STYLE_ID_PLACEHOLDER}
+* for batch replacement in selector templates.
+*
+* @internal
+*/
 const ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL = /%/g;
-
 //#endregion
 //#region src/internal/extractor.ts
 function replaceBySplitAndJoin(str, split, mapFn, join) {
@@ -1124,9 +1450,42 @@ const RE_SPLIT = /\s*,\s*/g;
 const DEFAULT_SELECTOR_PLACEHOLDER_RE_GLOBAL = /\$/g;
 const ATTRIBUTE_SUFFIX_MATCH = "$=";
 const ATTRIBUTE_SUFFIX_MATCH_RE_GLOBAL = /\$=/g;
+/**
+* Normalizes selector strings by replacing placeholders (`$` → `defaultSelector`, `%` → atomic style ID placeholder) and splitting comma-separated selectors.
+* @internal
+*
+* @param options - Object containing the raw `selectors` array and the `defaultSelector` template.
+* @param options.selectors - The raw selector strings to normalize.
+* @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.
+*
+* @example
+* ```ts
+* normalizeSelectors({ selectors: ['$hover $'], defaultSelector: '.%' })
+* // ['.%:hover .%'] (conceptually)
+* ```
+*/
 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), ATOMIC_STYLE_ID_PLACEHOLDER));
+	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), "%"));
 }
+/**
+* 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.
+* @internal
+*
+* @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.
+*
+* @example
+* ```ts
+* normalizeValue('red')                 // ['red']
+* normalizeValue(['red', ['blue']])     // ['blue', 'red']
+* normalizeValue(null)                  // null
+* ```
+*/
 function normalizeValue(value) {
 	if (value == null) return value;
 	if (Array.isArray(value)) {
@@ -1146,13 +1505,40 @@ function normalizeValue(value) {
 	}
 	return [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.
+* @internal
+*
+* @param options - Extraction context: the `styleDefinition` to walk, current nesting `levels`, accumulated `result`, `defaultSelector`, and plugin transform hooks for selectors, style items, and style definitions.
+* @param options.styleDefinition - The style definition subtree currently being traversed.
+* @param options.levels - The accumulated nested selector levels leading to this subtree.
+* @param options.result - The mutable extraction result array being appended to.
+* @param options.defaultSelector - The selector substituted when extracted selectors omit the atomic-style placeholder.
+* @param options.transformSelectors - Hook that rewrites selector levels before normalization.
+* @param options.transformStyleItems - Hook that expands array style items before recursive extraction.
+* @param options.transformStyleDefinitions - Hook that rewrites style definition objects before traversal.
+* @returns The accumulated array of `ExtractedStyleContent` entries.
+*
+* @remarks Property values are identified using `isPropertyValue`. Array values are treated as style item lists (resolved via `transformStyleItems`). Object values are treated as nested style definitions and recursed into. The transform hooks allow plugins (shortcuts, selectors) to intercept and expand values during extraction.
+*
+* @example
+* ```ts
+* const contents = await extract({
+*   styleDefinition: { color: 'red', '$hover': { color: 'blue' } },
+*   defaultSelector: '.%',
+*   transformSelectors: async s => s,
+*   transformStyleItems: async i => i,
+*   transformStyleDefinitions: async d => d,
+* })
+* ```
+*/
 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(ATOMIC_STYLE_ID_PLACEHOLDER) === false)) selector.push(defaultSelector);
+		if (selector.length === 0 || selector.every((s) => s.includes("%") === false)) selector.push(defaultSelector);
 		result.push({
 			selector,
 			property: toKebab(k),
@@ -1181,13 +1567,35 @@ async function extract({ styleDefinition, levels = [], result = [], defaultSelec
 	});
 	return result;
 }
+/**
+* Creates a bound extraction function that closes over the default selector and plugin transform hooks.
+* @internal
+*
+* @param options - The extraction options: `defaultSelector`, `transformSelectors`, `transformStyleItems`, and `transformStyleDefinitions`.
+* @param options.defaultSelector - The selector used when no explicit atomic placeholder selector remains.
+* @param options.transformSelectors - Hook that rewrites selector arrays before normalization.
+* @param options.transformStyleItems - Hook that rewrites or expands style item arrays.
+* @param options.transformStyleDefinitions - Hook that rewrites style definition objects before extraction.
+* @returns An `ExtractFn` that accepts a style definition and returns extracted contents.
+*
+* @remarks Called once during engine construction. The returned function is stored as `engine.extract` and used for all subsequent `engine.use()` calls.
+*
+* @example
+* ```ts
+* const extractFn = createExtractFn({
+*   defaultSelector: '.%',
+*   transformSelectors: async s => s,
+*   transformStyleItems: async i => i,
+*   transformStyleDefinitions: async d => d,
+* })
+* ```
+*/
 function createExtractFn(options) {
 	return (styleDefinition) => extract({
 		styleDefinition,
 		...options
 	});
 }
-
 //#endregion
 //#region src/internal/plugin.ts
 function getPluginHook(plugin, hook) {
@@ -1195,7 +1603,7 @@ function getPluginHook(plugin, hook) {
 	return typeof hookFn === "function" ? hookFn : null;
 }
 function applyHookPayload(current, next) {
-	return next != null ? next : current;
+	return next ?? current;
 }
 function logHookStart(kind, hook) {
 	log.debug(`Executing ${kind.toLowerCase()} hook: ${hook}`);
@@ -1212,6 +1620,23 @@ function logPluginHookEnd(plugin, hook) {
 function logPluginHookError(plugin, hook, error) {
 	log.error(`Plugin "${plugin.name}" failed to execute hook "${hook}": ${error instanceof Error ? error.message : error}`, error);
 }
+/**
+* Executes an async hook across all plugins in order, piping the payload through each plugin's handler.
+* @internal
+*
+* @typeParam P - The payload/return type flowing through the hook pipeline.
+* @param plugins - The ordered list of engine plugins to execute.
+* @param hook - The name of the async hook to invoke.
+* @param payload - The initial payload to pass into the first plugin.
+* @returns The final payload after all plugins have processed it.
+*
+* @remarks Each plugin's hook receives the current payload and may return a replacement. If a plugin's hook throws, the error is logged and the current payload is preserved for subsequent plugins.
+*
+* @example
+* ```ts
+* const config = await execAsyncHook(plugins, 'configureRawConfig', rawConfig)
+* ```
+*/
 async function execAsyncHook(plugins, hook, payload) {
 	logHookStart("Async", hook);
 	let current = payload;
@@ -1229,6 +1654,23 @@ async function execAsyncHook(plugins, hook, payload) {
 	logHookEnd("Async", hook);
 	return current;
 }
+/**
+* Executes a synchronous hook across all plugins in order, piping the payload through each plugin's handler.
+* @internal
+*
+* @typeParam P - The payload/return type flowing through the hook pipeline.
+* @param plugins - The ordered list of engine plugins to execute.
+* @param hook - The name of the sync hook to invoke.
+* @param payload - The initial payload to pass into the first plugin.
+* @returns The final payload after all plugins have processed it.
+*
+* @remarks Functions identically to `execAsyncHook` but without awaiting. Used for notification-style hooks like `preflightUpdated` or `atomicStyleAdded`.
+*
+* @example
+* ```ts
+* execSyncHook(plugins, 'atomicStyleAdded', atomicStyle)
+* ```
+*/
 function execSyncHook(plugins, hook, payload) {
 	logHookStart("Sync", hook);
 	let current = payload;
@@ -1246,6 +1688,18 @@ function execSyncHook(plugins, hook, payload) {
 	logHookEnd("Sync", hook);
 	return current;
 }
+/**
+* Pre-built hook dispatcher object mapping each hook name to a function that delegates to `execAsyncHook` or `execSyncHook`.
+* @internal
+*
+* @remarks Provides a convenient, type-safe interface for calling any engine hook by name without manually selecting between `execAsyncHook` and `execSyncHook`. Used throughout the `Engine` class.
+*
+* @example
+* ```ts
+* const config = await hooks.configureRawConfig(plugins, rawConfig)
+* hooks.preflightUpdated(plugins)
+* ```
+*/
 const hooks = {
 	configureRawConfig: (plugins, config) => execAsyncHook(plugins, "configureRawConfig", config),
 	rawConfigConfigured: (plugins, config) => execSyncHook(plugins, "rawConfigConfigured", config),
@@ -1263,15 +1717,45 @@ const orderMap = new Map([
 	["pre", 0],
 	["post", 2]
 ]);
+/**
+* Sorts an array of plugins by their `order` property: `'pre'` first, default in the middle, `'post'` last.
+* @internal
+*
+* @param plugins - The unordered array of engine plugins.
+* @returns A new array sorted by execution order.
+*
+* @remarks The original array is not mutated. Plugins with the same order retain their relative insertion order (stable sort).
+*
+* @example
+* ```ts
+* const ordered = resolvePlugins([postPlugin, prePlugin, normalPlugin])
+* // [prePlugin, normalPlugin, postPlugin]
+* ```
+*/
 function resolvePlugins(plugins) {
 	return [...plugins].sort((a, b) => orderMap.get(a.order) - orderMap.get(b.order));
 }
 /* c8 ignore start */
+/**
+* Identity helper that returns the plugin object as-is, providing TypeScript type inference for plugin definitions.
+*
+* @param plugin - The engine plugin definition.
+* @returns The same plugin object, unchanged.
+*
+* @remarks This is a compile-time-only helper; it has no runtime effect. Using it ensures type checking and IDE autocompletion for hook names and payloads.
+*
+* @example
+* ```ts
+* export default defineEnginePlugin({
+*   name: 'my-plugin',
+*   configureRawConfig: (config) => ({ ...config, important: true }),
+* })
+* ```
+*/
 function defineEnginePlugin(plugin) {
 	return plugin;
 }
 /* c8 ignore end */
-
 //#endregion
 //#region src/internal/plugins/important.ts
 function appendImportant(v) {
@@ -1282,6 +1766,18 @@ function modifyPropertyValue(value) {
 	if (Array.isArray(value)) return [appendImportant(value[0]), value[1].map((i) => appendImportant(i))];
 	return appendImportant(value);
 }
+/**
+* Built-in engine plugin that appends `!important` to generated CSS declarations.
+*
+* @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.
+*
+* @example
+* ```ts
+* createEngine({ plugins: [important()] })
+* ```
+*/
 function important() {
 	let defaultValue;
 	return defineEnginePlugin({
@@ -1298,8 +1794,7 @@ function important() {
 		transformStyleDefinitions(styleDefinitions) {
 			return styleDefinitions.map((styleDefinition) => {
 				const { __important, ...rest } = styleDefinition;
-				const value = __important;
-				if ((value == null ? defaultValue : value) === false) return rest;
+				if ((__important ?? defaultValue) === false) return rest;
 				return Object.fromEntries(Object.entries(rest).map(([k, v]) => {
 					if (isPropertyValue(v)) return [k, modifyPropertyValue(v)];
 					return [k, v];
@@ -1308,9 +1803,20 @@ function important() {
 		}
 	});
 }
-
 //#endregion
 //#region src/internal/plugins/keyframes.ts
+/**
+* Built-in engine plugin that provides CSS `@keyframes` registration, autocomplete integration, and smart pruning.
+*
+* @returns An `EnginePlugin` that registers keyframes definitions, wires up `animationName`/`animation` autocomplete entries, and emits a preflight containing only the `@keyframes` rules actually referenced by atomic styles.
+*
+* @remarks Reads `EngineConfig.keyframes` during `rawConfigConfigured` and attaches the `engine.keyframes` management interface during `configureEngine`. Unused keyframes are pruned from the output unless `pruneUnused: false` is set on the individual definition or globally.
+*
+* @example
+* ```ts
+* createEngine({ plugins: [keyframes()] })
+* ```
+*/
 function keyframes() {
 	let resolveKeyframesConfig;
 	let configList;
@@ -1330,7 +1836,7 @@ function keyframes() {
 						if (frames != null) engine.keyframes.store.set(name, resolved);
 						engine.appendAutocomplete({ cssProperties: {
 							animationName: name,
-							animation: autocompleteAnimation != null ? [`${name} `, ...autocompleteAnimation] : `${name} `
+							animation: autocompleteAnimation.length > 0 ? [`${name} `, ...autocompleteAnimation] : `${name} `
 						} });
 					});
 					engine.notifyPreflightUpdated();
@@ -1386,17 +1892,35 @@ function createResolveConfigFn({ pruneUnused: defaultPruneUnused = true } = {})
 		};
 	};
 }
-
 //#endregion
 //#region src/internal/resolver.ts
 function stripGlobalFlag(re) {
 	if (!re.global) return re;
 	return new RegExp(re.source, re.flags.replace("g", ""));
 }
+/**
+* Base resolver class that manages static and dynamic rules and caches resolution results.
+* @internal
+*
+* @typeParam T - The type of resolved values.
+*
+* @remarks Subclasses override resolution behavior (e.g. `RecursiveResolver` adds recursive expansion). The base class handles rule storage, cache lookup, and the static-then-dynamic matching order. Results are cached in `_resolvedResultsMap` for subsequent lookups.
+*
+* @example
+* ```ts
+* class MyResolver extends AbstractResolver<string> { }
+* const r = new MyResolver()
+* r.addStaticRule({ key: 'x', string: 'x', resolved: 'X' })
+* ```
+*/
 var AbstractResolver = class {
+	/** Cache of previously resolved input-string → result pairs. */
 	_resolvedResultsMap = /* @__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. */
 	dynamicRulesMap = /* @__PURE__ */ new Map();
+	/** Callback invoked after a successful resolution, receiving the input string, rule type, and result. */
 	onResolved = () => {};
 	get staticRules() {
 		return [...this.staticRulesMap.values()];
@@ -1404,11 +1928,37 @@ var AbstractResolver = class {
 	get dynamicRules() {
 		return [...this.dynamicRulesMap.values()];
 	}
+	/**
+	* Registers a static rule in the resolver.
+	*
+	* @param rule - The static rule to register.
+	* @returns `this` for chaining.
+	*
+	* @remarks Overwrites any existing static rule with the same key.
+	*
+	* @example
+	* ```ts
+	* resolver.addStaticRule({ key: 'dark', string: 'dark', resolved: ['.dark &'] })
+	* ```
+	*/
 	addStaticRule(rule) {
 		log.debug(`Adding static rule: ${rule.key}`);
 		this.staticRulesMap.set(rule.key, rule);
 		return this;
 	}
+	/**
+	* Removes a static rule and its cached resolution result.
+	*
+	* @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.
+	*
+	* @example
+	* ```ts
+	* resolver.removeStaticRule('dark')
+	* ```
+	*/
 	removeStaticRule(key) {
 		const rule = this.staticRulesMap.get(key);
 		if (rule == null) {
@@ -1420,11 +1970,37 @@ var AbstractResolver = class {
 		this._resolvedResultsMap.delete(rule.string);
 		return this;
 	}
+	/**
+	* 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.
+	*
+	* @example
+	* ```ts
+	* resolver.addDynamicRule({ key: 'bp', stringPattern: /^bp-(\d+)$/, createResolved: m => [`@media (min-width: ${m[1]}px)`] })
+	* ```
+	*/
 	addDynamicRule(rule) {
 		log.debug(`Adding dynamic rule: ${rule.key}`);
 		this.dynamicRulesMap.set(rule.key, rule);
 		return this;
 	}
+	/**
+	* Removes a dynamic rule and evicts all cached results that its pattern matched.
+	*
+	* @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.
+	*
+	* @example
+	* ```ts
+	* resolver.removeDynamicRule('bp')
+	* ```
+	*/
 	removeDynamicRule(key) {
 		const rule = this.dynamicRulesMap.get(key);
 		if (rule == null) {
@@ -1441,6 +2017,19 @@ var AbstractResolver = class {
 		log.debug(`  - Cleared ${matchedResolvedStringList.length} cached results`);
 		return this;
 	}
+	/**
+	* Attempts to resolve an input string by checking cached results, then static rules, then dynamic rules in order.
+	*
+	* @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`.
+	*
+	* @example
+	* ```ts
+	* const result = await resolver._resolve('hover')
+	* ```
+	*/
 	async _resolve(string) {
 		const existedResult = this._resolvedResultsMap.get(string);
 		if (existedResult != null) {
@@ -1474,6 +2063,19 @@ var AbstractResolver = class {
 		}
 		log.debug(`Resolution failed for: ${string}`);
 	}
+	/**
+	* Updates or creates the cached resolved result for a given input string.
+	*
+	* @param string - The input string whose cached result should be updated.
+	* @param resolved - The new resolved value to store.
+	*
+	* @remarks If a cached `ResolvedResult` already exists for `string`, its `value` property is mutated in place. Otherwise a new entry is created. This allows `RecursiveResolver` to retroactively update partially resolved values without allocating a new wrapper.
+	*
+	* @example
+	* ```ts
+	* resolver._setResolvedResult('hover', ['&:hover'])
+	* ```
+	*/
 	_setResolvedResult(string, resolved) {
 		const resolvedResult = this._resolvedResultsMap.get(string);
 		if (resolvedResult) {
@@ -1483,7 +2085,36 @@ var AbstractResolver = class {
 		this._resolvedResultsMap.set(string, { value: resolved });
 	}
 };
+/**
+* Resolver subclass that recursively expands resolved values until all string references are fully resolved.
+* @internal
+*
+* @typeParam T - The element type of the final resolved array.
+*
+* @remarks Each resolution step may return a mix of final values and string references. The `resolve` method recurses into string values, flattening nested references while detecting circular dependencies via a visited set.
+*
+* @example
+* ```ts
+* class SelectorResolver extends RecursiveResolver<string> { }
+* const result = await resolver.resolve('hover-focus')
+* // ['&:hover', '&:focus'] after recursive expansion
+* ```
+*/
 var RecursiveResolver = class extends AbstractResolver {
+	/**
+	* Recursively resolves an input string into a flat array of final values.
+	*
+	* @param string - The input string to resolve.
+	* @param _visited - Accumulator set for cycle detection; callers should omit this.
+	* @returns A flat array of resolved values. If no rule matches, returns `[string]` cast to `T`.
+	*
+	* @remarks Detects circular references and short-circuits by returning the unresolved string. After full expansion, the cache is updated with the final flat result via `_setResolvedResult`.
+	*
+	* @example
+	* ```ts
+	* const selectors = await resolver.resolve('hover')
+	* ```
+	*/
 	async resolve(string, _visited) {
 		const visited = _visited ?? /* @__PURE__ */ new Set();
 		if (visited.has(string)) {
@@ -1502,6 +2133,26 @@ var RecursiveResolver = class extends AbstractResolver {
 		return result;
 	}
 };
+/**
+* Normalizes a user-supplied rule shorthand into a `ResolvedRuleConfig`, a plain redirect string, or `undefined`.
+* @internal
+*
+* @typeParam T - The element type of the rule's resolved value array.
+* @param config - The raw rule configuration: a string redirect, a tuple (`[string, value]` or `[RegExp, fn, autocomplete?]`), or an object with `keyName` and `value` properties.
+* @param keyName - The property name on an object-form config that holds the match key or pattern.
+* @returns A `ResolvedRuleConfig<T>` for valid static/dynamic configs, the original string for redirect configs, or `undefined` if the config shape is unrecognized.
+*
+* @remarks Handles three config shapes:
+* - **String**: returned as-is for the caller to treat as a redirect to another rule.
+* - **Tuple**: `[string, T | T[]]` for static rules, `[RegExp, fn, autocomplete?]` for dynamic rules.
+* - **Object**: `{ [keyName]: string | RegExp, value: T | fn, autocomplete?: string[] }`.
+*
+* @example
+* ```ts
+* 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)) {
@@ -1552,9 +2203,20 @@ function resolveRuleConfig(config, keyName) {
 		};
 	}
 }
-
 //#endregion
 //#region src/internal/plugins/selectors.ts
+/**
+* Built-in engine plugin that provides the selector resolution system.
+*
+* @returns An `EnginePlugin` that registers the `selectors` resolver on the engine and hooks into `transformSelectors` to expand selector names into resolved CSS selectors.
+*
+* @remarks Reads `EngineConfig.selectors` during `rawConfigConfigured`, attaches a `RecursiveResolver` to `engine.selectors` during `configureEngine`, and resolves all selector strings in the `transformSelectors` hook.
+*
+* @example
+* ```ts
+* createEngine({ plugins: [selectors()] })
+* ```
+*/
 function selectors() {
 	let engine;
 	let configList;
@@ -1575,8 +2237,11 @@ function selectors() {
 							engine.appendAutocomplete({ selectors: resolved });
 							return;
 						}
-						if (resolved.type === "static") engine.selectors.resolver.addStaticRule(resolved.rule);
-						else if (resolved.type === "dynamic") engine.selectors.resolver.addDynamicRule(resolved.rule);
+						const addRule = {
+							static: () => engine.selectors.resolver.addStaticRule(resolved.rule),
+							dynamic: () => engine.selectors.resolver.addDynamicRule(resolved.rule)
+						}[resolved.type];
+						addRule?.();
 						engine.appendAutocomplete({ selectors: resolved.autocomplete });
 					});
 				}
@@ -1594,12 +2259,36 @@ function selectors() {
 	});
 }
 var SelectorResolver = class extends RecursiveResolver {};
+/**
+* Normalizes a `Selector` configuration into a `ResolvedRuleConfig`, a redirect string, or `undefined`.
+*
+* @param config - The selector rule configuration to resolve.
+* @returns A resolved static/dynamic rule config, a redirect string, or `undefined` if the shape is unrecognized.
+*
+* @remarks Delegates to the generic `resolveRuleConfig` with `'selector'` as the key name.
+*
+* @example
+* ```ts
+* const resolved = resolveSelectorConfig(['hover', '&:hover'])
+* ```
+*/
 function resolveSelectorConfig(config) {
 	return resolveRuleConfig(config, "selector");
 }
-
 //#endregion
 //#region src/internal/plugins/shortcuts.ts
+/**
+* Built-in engine plugin that provides the shortcut resolution system.
+*
+* @returns An `EnginePlugin` that registers the `shortcuts` resolver on the engine and hooks into `transformStyleItems` and `transformStyleDefinitions` to expand shortcut names into style items.
+*
+* @remarks Reads `EngineConfig.shortcuts` during `rawConfigConfigured`, attaches a `RecursiveResolver` to `engine.shortcuts` during `configureEngine`, and expands shortcut references in both `transformStyleItems` (string style items) and `transformStyleDefinitions` (the `__shortcut` pseudo-property).
+*
+* @example
+* ```ts
+* createEngine({ plugins: [shortcuts()] })
+* ```
+*/
 function shortcuts() {
 	let engine;
 	let configList;
@@ -1617,20 +2306,23 @@ function shortcuts() {
 						const resolved = resolveShortcutConfig(config);
 						if (resolved == null) return;
 						if (typeof resolved === "string") {
-							engine.appendAutocomplete({ styleItemStrings: resolved });
+							engine.appendAutocomplete({ shortcuts: resolved });
 							return;
 						}
-						if (resolved.type === "static") engine.shortcuts.resolver.addStaticRule(resolved.rule);
-						else if (resolved.type === "dynamic") engine.shortcuts.resolver.addDynamicRule(resolved.rule);
-						engine.appendAutocomplete({ styleItemStrings: resolved.autocomplete });
+						const addRule = {
+							static: () => engine.shortcuts.resolver.addStaticRule(resolved.rule),
+							dynamic: () => engine.shortcuts.resolver.addDynamicRule(resolved.rule)
+						}[resolved.type];
+						addRule?.();
+						engine.appendAutocomplete({ shortcuts: resolved.autocomplete });
 					});
 				}
 			};
 			engine.shortcuts.add(...configList);
 			engine.shortcuts.resolver.onResolved = (string, type) => {
-				if (type === "dynamic") engine.appendAutocomplete({ styleItemStrings: string });
+				if (type === "dynamic") engine.appendAutocomplete({ shortcuts: string });
 			};
-			const unionType = ["(string & {})", "Autocomplete['StyleItemString']"].join(" | ");
+			const unionType = ["(string & {})", "Autocomplete['Shortcut']"].join(" | ");
 			engine.appendAutocomplete({
 				extraProperties: "__shortcut",
 				properties: { __shortcut: [unionType, `(${unionType})[]`] }
@@ -1666,22 +2358,8 @@ var ShortcutResolver = class extends RecursiveResolver {};
 function resolveShortcutConfig(config) {
 	return resolveRuleConfig(config, "shortcut");
 }
-
 //#endregion
 //#region src/internal/generated-property-semantics.ts
-const VARIABLE_SEMANTIC_FAMILIES = [
-	"color",
-	"length",
-	"time",
-	"number",
-	"percentage",
-	"angle",
-	"image",
-	"url",
-	"position",
-	"easing",
-	"font-family"
-];
 const VARIABLE_SEMANTIC_FAMILY_PROPERTIES = {
 	"angle": [],
 	"color": [
@@ -1759,10 +2437,20 @@ const VARIABLE_SEMANTIC_FAMILY_PROPERTIES = {
 	],
 	"url": []
 };
-
 //#endregion
 //#region src/internal/plugins/variables.ts
-const KNOWN_VARIABLE_SEMANTIC_FAMILIES = new Set(VARIABLE_SEMANTIC_FAMILIES);
+/**
+* Built-in engine plugin that provides CSS custom properties (variables) with smart pruning and autocomplete integration.
+*
+* @returns An `EnginePlugin` that registers variable definitions, manages a preflight for emitting `:root` / scoped variables, and prunes unused variables from the output.
+*
+* @remarks Reads `EngineConfig.variables` during `rawConfigConfigured` and attaches the `engine.variables` management interface during `configureEngine`. A preflight is registered that collects variable references from atomic styles and other preflights, transitively expands dependencies, and emits only used (or safe-listed) variables.
+*
+* @example
+* ```ts
+* createEngine({ plugins: [variables()] })
+* ```
+*/
 function variables() {
 	let resolveVariables;
 	let rawVariables;
@@ -1803,7 +2491,7 @@ function variables() {
 						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(fn(engine, false)).catch(() => null)))).forEach((result) => {
+					(await Promise.all(otherPreflights.map(({ fn }) => Promise.resolve().then(() => fn(engine, false)).catch(() => null)))).forEach((result) => {
 						if (result == null) return;
 						extractUsedVarNamesFromPreflightResult(result).forEach((name) => used.add(name));
 					});
@@ -1815,8 +2503,8 @@ function variables() {
 						const entries = varMap.get(name);
 						if (!entries) continue;
 						for (const { value } of entries) {
-							if (value == null) continue;
-							for (const refName of extractUsedVarNames(String(value)).map(normalizeVariableName)) if (!used.has(refName)) {
+							const referencedValue = Array.isArray(value) ? value.join(" ") : String(value);
+							for (const refName of extractUsedVarNames(referencedValue).map(normalizeVariableName)) if (!used.has(refName)) {
 								used.add(refName);
 								queue.push(refName);
 							}
@@ -1880,7 +2568,7 @@ function resolveAutocompleteValueTargets({ name, asValueOf, semanticType }) {
 	const targets = /* @__PURE__ */ new Set();
 	if (asValueOf == null && semanticTypes.length === 0) targets.add("*");
 	explicitTargets.forEach((target) => {
-		if (target !== "-") targets.add(target);
+		targets.add(target);
 	});
 	semanticTypes.forEach((family) => {
 		const properties = VARIABLE_SEMANTIC_FAMILY_PROPERTIES[family];
@@ -1888,42 +2576,128 @@ function resolveAutocompleteValueTargets({ name, asValueOf, semanticType }) {
 			properties.forEach((property) => targets.add(property));
 			return;
 		}
-		if (KNOWN_VARIABLE_SEMANTIC_FAMILIES.has(family) === false) log.warn(`Unknown semanticType "${family}" for variable "${name}". Skipping semantic autocomplete expansion.`);
+		log.warn(`Unknown semanticType "${family}" for variable "${name}". Skipping semantic autocomplete expansion.`);
 	});
 	if (targets.has("*")) return ["*"];
 	return [...targets];
 }
 const VAR_NAME_RE = /var\((--[\w-]+)/g;
+/**
+* Extracts all CSS variable names referenced via `var(--*)` calls in a string.
+*
+* @param input - The CSS value string to scan.
+* @returns An array of variable names (including the `--` prefix) found in `var()` expressions.
+*
+* @remarks Uses a global regex to find all `var(--name)` occurrences. Nested `var()` calls are matched independently.
+*
+* @example
+* ```ts
+* extractUsedVarNames('color: var(--primary)')  // ['--primary']
+* extractUsedVarNames('var(--a) var(--b)')       // ['--a', '--b']
+* ```
+*/
 function extractUsedVarNames(input) {
 	return Array.from(input.matchAll(VAR_NAME_RE), (m) => m[1]);
 }
+/**
+* Ensures a variable name has the `--` prefix.
+*
+* @param name - The variable name, with or without the `--` prefix.
+* @returns The name with a guaranteed `--` prefix.
+*
+* @remarks A no-op when the name already starts with `--`.
+*
+* @example
+* ```ts
+* normalizeVariableName('color')     // '--color'
+* normalizeVariableName('--color')   // '--color'
+* ```
+*/
 function normalizeVariableName(name) {
 	if (name.startsWith("--")) return name;
 	return `--${name}`;
 }
 /**
-* Recursively extract all CSS variable names referenced inside a preflight
-* result (either a plain CSS string or a `PreflightDefinition` object).
+* Recursively extracts all CSS variable names referenced in a preflight result.
+*
+* @param result - A preflight output: either a raw CSS string or a nested `PreflightDefinition` object.
+* @returns A flat array of normalized variable names found in the result.
+*
+* @remarks For string results, scans for `var(--*)` references. For object results, recursively traverses selector scopes and string/number values. All returned names are normalized with the `--` prefix.
+*
+* @example
+* ```ts
+* extractUsedVarNamesFromPreflightResult({ ':root': { color: 'var(--primary)' } })
+* // ['--primary']
+* ```
 */
 function extractUsedVarNamesFromPreflightResult(result) {
 	if (typeof result === "string") return extractUsedVarNames(result).map(normalizeVariableName);
 	const names = [];
 	for (const value of Object.values(result)) {
 		if (value == null) continue;
-		if (typeof value === "string" || typeof value === "number") extractUsedVarNames(String(value)).forEach((n) => names.push(normalizeVariableName(n)));
-		else if (typeof value === "object") extractUsedVarNamesFromPreflightResult(value).forEach((n) => names.push(n));
+		if (typeof value === "string" || typeof value === "number") {
+			extractUsedVarNames(String(value)).forEach((n) => names.push(normalizeVariableName(n)));
+			continue;
+		}
+		extractUsedVarNamesFromPreflightResult(value).forEach((n) => names.push(n));
 	}
 	return names;
 }
-
 //#endregion
 //#region src/internal/engine.ts
+/**
+* Default CSS layer name for preflight styles.
+* @internal
+*
+* @remarks Used as the layer name wrapping all unlayered preflight output when the layer exists in `config.layers`.
+*
+* @example
+* ```ts
+* // 'preflights'
+* ```
+*/
 const DEFAULT_PREFLIGHTS_LAYER = "preflights";
+/**
+* Default CSS layer name for utility (atomic) styles.
+* @internal
+*
+* @remarks Atomic styles without an explicit layer are placed into this layer when it exists in `config.layers`.
+*
+* @example
+* ```ts
+* // 'utilities'
+* ```
+*/
 const DEFAULT_UTILITIES_LAYER = "utilities";
+/**
+* Default layer ordering map: `preflights` at weight 1, `utilities` at weight 10.
+* @internal
+*
+* @remarks Merged with any user-supplied `config.layers` during engine config resolution. Numeric weights determine the `@layer` declaration order.
+*
+* @example
+* ```ts
+* // { preflights: 1, utilities: 10 }
+* ```
+*/
 const DEFAULT_LAYERS = {
 	[DEFAULT_PREFLIGHTS_LAYER]: 1,
 	[DEFAULT_UTILITIES_LAYER]: 10
 };
+/**
+* Creates and initializes a PikaCSS engine with the given configuration.
+*
+* @param config - The engine configuration, including plugins, selectors, shortcuts, variables, keyframes, preflights, and layer settings.
+* @returns A fully initialized `Engine` instance.
+*
+* @remarks Core plugins (`important`, `variables`, `keyframes`, `selectors`, `shortcuts`) are prepended automatically. The function resolves plugins, runs all configuration hooks in sequence, and returns the ready-to-use engine.
+*
+* @example
+* ```ts
+* const engine = await createEngine({ prefix: 'pk-', plugins: [myPlugin()] })
+* ```
+*/
 async function createEngine(config = {}) {
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
@@ -1941,7 +2715,7 @@ async function createEngine(config = {}) {
 	};
 	log.debug(`Total plugins resolved: ${plugins.length}`);
 	config = await hooks.configureRawConfig(config.plugins, config);
-	hooks.rawConfigConfigured(resolvePlugins(config.plugins ?? []), config);
+	hooks.rawConfigConfigured(resolvePlugins(config.plugins), config);
 	let resolvedConfig = await resolveEngineConfig(config);
 	log.debug("Engine config resolved with prefix:", resolvedConfig.prefix);
 	resolvedConfig = await hooks.configureResolvedConfig(resolvedConfig.plugins, resolvedConfig);
@@ -1955,11 +2729,39 @@ async function createEngine(config = {}) {
 	log.debug("Engine initialized successfully");
 	return engine;
 }
+/**
+* The PikaCSS engine: manages atomic style resolution, rendering, preflights, and plugin hooks.
+*
+* @remarks Constructed via `createEngine()`. Holds the resolved configuration, the atomic style store, and exposes methods for processing style items (`use`), rendering CSS output (`renderPreflights`, `renderAtomicStyles`, `renderLayerOrderDeclaration`), and managing runtime extensions (`addPreflight`, `appendAutocomplete`, `appendCssImport`).
+*
+* @example
+* ```ts
+* const engine = await createEngine({ prefix: 'pk-' })
+* const ids = await engine.use({ color: 'red' })
+* const css = await engine.renderAtomicStyles(true)
+* ```
+*/
 var Engine = class {
+	/** The fully resolved engine configuration. */
 	config;
+	/** Reference to the plugin hook dispatcher for invoking lifecycle hooks. */
 	pluginHooks = hooks;
+	/** The extraction function that decomposes style definitions into atomic style contents. */
 	extract;
+	/** The engine's runtime store holding registered atomic styles and their ID mappings. */
 	store = createEngineStore();
+	/**
+	* Creates an engine instance from a resolved configuration.
+	*
+	* @param config - The fully resolved engine configuration.
+	*
+	* @remarks Initializes the `extract` function by wiring it to the plugin hook pipeline for selectors, style items, and style definitions.
+	*
+	* @example
+	* ```ts
+	* const engine = new Engine(resolvedConfig)
+	* ```
+	*/
 	constructor(config) {
 		this.config = config;
 		this.extract = createExtractFn({
@@ -1969,30 +2771,113 @@ var Engine = class {
 			transformStyleDefinitions: (styleDefinitions) => hooks.transformStyleDefinitions(this.config.plugins, styleDefinitions)
 		});
 	}
+	/**
+	* Fires the `preflightUpdated` hook to notify plugins that preflight content has changed.
+	*
+	*
+	* @remarks Called automatically after `addPreflight` or when plugins modify preflight-contributing state (e.g. variables, keyframes).
+	*
+	* @example
+	* ```ts
+	* engine.notifyPreflightUpdated()
+	* ```
+	*/
 	notifyPreflightUpdated() {
 		hooks.preflightUpdated(this.config.plugins);
 	}
+	/**
+	* Fires the `atomicStyleAdded` hook to notify plugins that a new atomic style was registered.
+	*
+	* @param atomicStyle - The atomic style that was just added to the store.
+	*
+	* @remarks Called automatically by `use()` when a previously unseen atomic style is resolved.
+	*
+	* @example
+	* ```ts
+	* engine.notifyAtomicStyleAdded(atomicStyle)
+	* ```
+	*/
 	notifyAtomicStyleAdded(atomicStyle) {
 		hooks.atomicStyleAdded(this.config.plugins, atomicStyle);
 	}
+	/**
+	* Fires the `autocompleteConfigUpdated` hook to notify plugins that autocomplete entries changed.
+	*
+	*
+	* @remarks Called automatically after `appendAutocomplete` when the contribution modifies the resolved autocomplete config.
+	*
+	* @example
+	* ```ts
+	* engine.notifyAutocompleteConfigUpdated()
+	* ```
+	*/
 	notifyAutocompleteConfigUpdated() {
 		hooks.autocompleteConfigUpdated(this.config.plugins);
 	}
+	/**
+	* Merges an autocomplete contribution into the resolved autocomplete config.
+	*
+	* @param contribution - The autocomplete entries to append (selectors, properties, CSS properties, etc.).
+	*
+	* @remarks Delegates to the `appendAutocomplete` utility and fires `autocompleteConfigUpdated` if the config was actually modified.
+	*
+	* @example
+	* ```ts
+	* engine.appendAutocomplete({ selectors: 'hover', cssProperties: { color: 'red' } })
+	* ```
+	*/
 	appendAutocomplete(contribution) {
 		if (appendAutocomplete(this.config, contribution)) this.notifyAutocompleteConfigUpdated();
 	}
+	/**
+	* Appends a CSS `@import` statement to the preflight output.
+	*
+	* @param cssImport - The raw `@import` string (a trailing semicolon is appended if missing).
+	*
+	* @remarks Deduplicates imports. Fires `preflightUpdated` when a new import is added.
+	*
+	* @example
+	* ```ts
+	* engine.appendCssImport('@import url("https://fonts.googleapis.com/css2?family=Inter")')
+	* ```
+	*/
 	appendCssImport(cssImport) {
 		const normalized = normalizeCssImport(cssImport);
 		if (normalized == null || this.config.cssImports.includes(normalized)) return;
 		this.config.cssImports.push(normalized);
 		this.notifyPreflightUpdated();
 	}
+	/**
+	* Registers a new preflight that will be rendered before atomic styles.
+	*
+	* @param preflight - A preflight definition: a function, a static string/object, or a wrapper with `layer`/`id` metadata.
+	*
+	* @remarks The preflight is resolved into a `ResolvedPreflight` (extracting optional `layer` and `id`) and appended to `config.preflights`. Fires `preflightUpdated` so plugins and the integration layer know to re-render.
+	*
+	* @example
+	* ```ts
+	* engine.addPreflight({ layer: 'base', preflight: '*, *::before { box-sizing: border-box; }' })
+	* ```
+	*/
 	addPreflight(preflight) {
 		log.debug("Adding preflight");
 		this.config.preflights.push(resolvePreflight(preflight));
 		log.debug(`Total preflights: ${this.config.preflights.length}`);
 		this.notifyPreflightUpdated();
 	}
+	/**
+	* 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.
+	*
+	* @remarks Runs `transformStyleItems` and `extractStyleDefinition` hooks, resolves each extracted content into an atomic style, deduplicates by base key, and fires `atomicStyleAdded` for new entries.
+	*
+	* @example
+	* ```ts
+	* const ids = await engine.use({ color: 'red' }, { padding: '1rem' })
+	* ```
+	*/
 	async use(...itemList) {
 		log.debug(`Processing ${itemList.length} style items`);
 		const { unknown, contents } = await resolveStyleItemList({
@@ -2019,6 +2904,19 @@ var Engine = class {
 		log.debug(`Resolved ${resolvedIds.length} atomic styles, ${unknown.size} unknown items`);
 		return [...unknown, ...resolvedIds];
 	}
+	/**
+	* Renders all registered preflight definitions into a CSS string.
+	*
+	* @param isFormatted - Whether to produce human-readable CSS with newlines and indentation.
+	* @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.
+	*
+	* @example
+	* ```ts
+	* const css = await engine.renderPreflights(true)
+	* ```
+	*/
 	async renderPreflights(isFormatted) {
 		log.debug("Rendering preflights...");
 		const lineEnd = isFormatted ? "\n" : "";
@@ -2055,6 +2953,22 @@ var Engine = class {
 		}));
 		return outputParts.join(lineEnd);
 	}
+	/**
+	* Renders atomic styles into a CSS string, optionally filtered by ID and grouped by layer.
+	*
+	* @param isFormatted - Whether to produce human-readable CSS with newlines and indentation.
+	* @param options - Optional filtering: `atomicStyleIds` to render a subset, `isPreview` to use placeholder IDs.
+	* @param options.atomicStyleIds - Specific atomic style IDs to render instead of the full store.
+	* @param options.isPreview - Whether to keep placeholder IDs instead of substituting real class names.
+	* @returns The rendered atomic-style CSS.
+	*
+	* @remarks Styles are sorted by rendering weight (selector specificity depth), grouped into configured `@layer` blocks, and rendered. When `isPreview` is true, atomic style IDs remain as placeholders for tooling previews.
+	*
+	* @example
+	* ```ts
+	* const css = await engine.renderAtomicStyles(true)
+	* ```
+	*/
 	async renderAtomicStyles(isFormatted, options = {}) {
 		log.debug("Rendering atomic styles...");
 		const { atomicStyleIds = null, isPreview = false } = options;
@@ -2069,16 +2983,58 @@ var Engine = class {
 			defaultUtilitiesLayer: this.config.defaultUtilitiesLayer
 		});
 	}
+	/**
+	* Renders the CSS `@layer` order declaration for all configured layers.
+	*
+	* @returns A `@layer` statement listing layer names in weight order, or an empty string if no layers are configured.
+	*
+	* @remarks Ensures the browser applies the intended cascade priority for `preflights`, `utilities`, and any user-defined layers.
+	*
+	* @example
+	* ```ts
+	* engine.renderLayerOrderDeclaration()
+	* // '@layer preflights, utilities;'
+	* ```
+	*/
 	renderLayerOrderDeclaration() {
 		const { layers } = this.config;
 		if (Object.keys(layers).length === 0) return "";
 		return `@layer ${sortLayerNames(layers).join(", ")};`;
 	}
 };
+/**
+* Computes a numeric rendering weight for an atomic style based on its selector depth.
+* @internal
+*
+* @param style - The atomic style to weigh.
+* @param defaultSelector - The engine's default selector pattern.
+* @returns `0` for styles using only the default selector; otherwise the number of selector segments.
+*
+* @remarks Used to sort atomic styles so that simpler selectors appear before more specific ones in the CSS output, preserving deterministic cascade ordering.
+*
+* @example
+* ```ts
+* calcAtomicStyleRenderingWeight(style, '.pk-__PLACEHOLDER__')
+* ```
+*/
 function calcAtomicStyleRenderingWeight(style, defaultSelector) {
 	const { selector } = splitLayerSelector(style.content.selector);
 	return selector.length === 1 && selector[0] === defaultSelector ? 0 : selector.length;
 }
+/**
+* Sorts layer names by their numeric weight, then alphabetically for ties.
+*
+* @param layers - A record mapping layer names to numeric weights.
+* @returns An array of layer names in ascending weight order.
+*
+* @remarks Used to produce the `@layer` declaration order and to order layer group rendering.
+*
+* @example
+* ```ts
+* sortLayerNames({ utilities: 10, preflights: 1 })
+* // ['preflights', 'utilities']
+* ```
+*/
 function sortLayerNames(layers) {
 	return Object.entries(layers).sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0])).map(([name]) => name);
 }
@@ -2087,7 +3043,7 @@ function appendLayerGroupItem(layerGroups, layer, item) {
 	layerGroups.get(layer).push(item);
 }
 function getOrderedLayerNamesForGroups(layerGroups, layerOrder) {
-	return [...layerOrder.filter((name) => (layerGroups.get(name)?.length ?? 0) > 0), ...[...layerGroups.keys()].filter((name) => !layerOrder.includes(name) && (layerGroups.get(name)?.length ?? 0) > 0)];
+	return [...layerOrder.filter((name) => (layerGroups.get(name)?.length ?? 0) > 0), ...[...layerGroups.keys()].filter((name) => !layerOrder.includes(name) && layerGroups.get(name).length > 0)];
 }
 function renderLayerBlocks({ layerGroups, layerOrder, isFormatted, render }) {
 	const lineEnd = isFormatted ? "\n" : "";
@@ -2118,11 +3074,11 @@ function groupRenderedPreflightsByLayer(rendered) {
 }
 function splitLayerSelector(selector) {
 	const [first, ...rest] = selector;
-	if (first == null || first.startsWith(LAYER_SELECTOR_PREFIX) === false) return {
+	if (first == null || first.startsWith("@layer ") === false) return {
 		layer: void 0,
 		selector
 	};
-	const layer = first.slice(LAYER_SELECTOR_PREFIX.length).trim();
+	const layer = first.slice(7).trim();
 	if (layer.length === 0) return {
 		layer: void 0,
 		selector
@@ -2138,8 +3094,8 @@ function prependLayerSelector(selector, layer) {
 function groupAtomicStylesByLayer({ styles, layerOrder, defaultUtilitiesLayer }) {
 	const unlayeredStyles = [];
 	const layerGroups = new Map(layerOrder.map((name) => [name, []]));
-	const candidateDefaultLayer = defaultUtilitiesLayer ?? layerOrder[layerOrder.length - 1];
-	const defaultLayer = candidateDefaultLayer != null && layerGroups.has(candidateDefaultLayer) ? candidateDefaultLayer : layerOrder[layerOrder.length - 1];
+	const candidateDefaultLayer = defaultUtilitiesLayer ?? layerOrder.at(-1);
+	const defaultLayer = candidateDefaultLayer != null && layerGroups.has(candidateDefaultLayer) ? candidateDefaultLayer : layerOrder.at(-1);
 	for (const style of styles) {
 		const { layer } = splitLayerSelector(style.content.selector);
 		if (layer != null && layerGroups.has(layer)) {
@@ -2172,6 +3128,20 @@ function isWithId(p) {
 	const record = p;
 	return typeof record.id === "string" && record.preflight !== void 0;
 }
+/**
+* Normalizes a `Preflight` input into a `ResolvedPreflight` by extracting optional `layer` and `id` wrappers.
+* @internal
+*
+* @param preflight - A preflight value: a function, a static string/`PreflightDefinition`, or a wrapper with `layer`/`id` metadata.
+* @returns A `ResolvedPreflight` with separated `layer`, `id`, and `fn`.
+*
+* @remarks Handles nested wrappers: a `{ layer, preflight: { id, preflight: fn } }` shape is unwrapped in order.
+*
+* @example
+* ```ts
+* resolvePreflight({ layer: 'base', id: 'reset', preflight: '* { margin: 0 }' })
+* ```
+*/
 function resolvePreflight(preflight) {
 	let layer;
 	let id;
@@ -2189,11 +3159,25 @@ function resolvePreflight(preflight) {
 		fn: typeof preflight === "function" ? preflight : () => preflight
 	};
 }
+/**
+* Resolves a raw `EngineConfig` into a fully normalized `ResolvedEngineConfig`.
+* @internal
+*
+* @param config - The raw engine configuration.
+* @returns A `ResolvedEngineConfig` with defaults applied, plugins sorted, preflights resolved, and autocomplete initialized.
+*
+* @remarks Merges `DEFAULT_LAYERS`, normalizes CSS imports, resolves preflight definitions, and initializes the empty autocomplete sets/maps.
+*
+* @example
+* ```ts
+* const resolved = await resolveEngineConfig({ prefix: 'pk-' })
+* ```
+*/
 async function resolveEngineConfig(config) {
-	const { prefix = DEFAULT_ATOMIC_STYLE_ID_PREFIX, defaultSelector = `.${ATOMIC_STYLE_ID_PLACEHOLDER}`, plugins = [], cssImports = [], preflights = [] } = config;
+	const { prefix = "pk-", defaultSelector = `.%`, plugins = [], cssImports = [], preflights = [] } = config;
 	const layers = Object.assign({}, DEFAULT_LAYERS, config.layers);
-	const defaultPreflightsLayer = config.defaultPreflightsLayer ?? DEFAULT_PREFLIGHTS_LAYER;
-	const defaultUtilitiesLayer = config.defaultUtilitiesLayer ?? DEFAULT_UTILITIES_LAYER;
+	const defaultPreflightsLayer = config.defaultPreflightsLayer ?? "preflights";
+	const defaultUtilitiesLayer = config.defaultUtilitiesLayer ?? "utilities";
 	log.debug(`Resolving engine config with prefix: "${prefix}", plugins: ${plugins.length}, preflights: ${preflights.length}`);
 	const resolvedConfig = {
 		rawConfig: config,
@@ -2207,14 +3191,14 @@ async function resolveEngineConfig(config) {
 		defaultUtilitiesLayer,
 		autocomplete: {
 			selectors: /* @__PURE__ */ new Set(),
-			styleItemStrings: /* @__PURE__ */ new Set(),
+			shortcuts: /* @__PURE__ */ new Set(),
 			extraProperties: /* @__PURE__ */ new Set(),
 			extraCssProperties: /* @__PURE__ */ new Set(),
 			properties: /* @__PURE__ */ new Map(),
 			cssProperties: /* @__PURE__ */ new Map(),
 			patterns: {
 				selectors: /* @__PURE__ */ new Set(),
-				styleItemStrings: /* @__PURE__ */ new Set(),
+				shortcuts: /* @__PURE__ */ new Set(),
 				properties: /* @__PURE__ */ new Map(),
 				cssProperties: /* @__PURE__ */ new Map()
 			}
@@ -2239,6 +3223,26 @@ function extractLayerFromStyleItem(item) {
 		definition: rest
 	};
 }
+/**
+* Transforms and extracts a list of style items into deduplicated atomic style contents.
+* @internal
+*
+* @param options - An object containing:
+*   - `itemList` — the raw style items to process.
+*   - `transformStyleItems` — the plugin hook for transforming style items.
+*   - `extractStyleDefinition` — the function that decomposes a style definition into extracted contents.
+* @param options.itemList - The raw style items to process.
+* @param options.transformStyleItems - Hook that expands or rewrites style items before extraction.
+* @param options.extractStyleDefinition - Function that decomposes a style definition into extracted style contents.
+* @returns An object with `unknown` (unresolved string references) and `contents` (optimized extracted style contents).
+*
+* @remarks String items that survive the `transformStyleItems` hook are collected into the `unknown` set. Object items are extracted, optionally layer-prepended, and optimized for duplicate property merging.
+*
+* @example
+* ```ts
+* const { unknown, contents } = await resolveStyleItemList({ itemList, transformStyleItems, extractStyleDefinition })
+* ```
+*/
 async function resolveStyleItemList({ itemList, transformStyleItems, extractStyleDefinition }) {
 	const unknown = /* @__PURE__ */ new Set();
 	const list = [];
@@ -2263,7 +3267,7 @@ 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(ATOMIC_STYLE_ID_PLACEHOLDER)) === false || value == null) return;
+		if (selector.some((s) => s.includes("%")) === false || value == null) return;
 		const renderObject = {
 			selector: isPreview ? selector : selector.map((s) => s.replace(ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, id)),
 			properties: value.map((v) => ({
@@ -2284,6 +3288,26 @@ function renderAtomicStylesCss({ atomicStyles, isPreview, isFormatted }) {
 	});
 	return renderCSSStyleBlocks(blocks, isFormatted);
 }
+/**
+* Standalone function that renders atomic styles into CSS with layer grouping.
+* @internal
+*
+* @param payload - An object containing `atomicStyles`, `isPreview`, `isFormatted`, `defaultSelector`, and optional `layers`/`defaultUtilitiesLayer`.
+* @param payload.atomicStyles - The atomic styles to render.
+* @param payload.isPreview - Whether placeholder IDs should be preserved for preview output.
+* @param payload.isFormatted - Whether to render with indentation and line breaks.
+* @param payload.defaultSelector - The engine default selector used when computing render order.
+* @param payload.layers - Optional configured CSS layers to group atomic styles into.
+* @param payload.defaultUtilitiesLayer - Optional fallback layer for unlayered utility styles.
+* @returns The rendered CSS string.
+*
+* @remarks Sorts styles by rendering weight, groups them into `@layer` blocks when layers are configured, and renders each group. Used by both the `Engine.renderAtomicStyles` method and external consumers.
+*
+* @example
+* ```ts
+* const css = renderAtomicStyles({ atomicStyles, isPreview: false, isFormatted: true, defaultSelector: '.pk-__ID__', layers: { utilities: 10 } })
+* ```
+*/
 function renderAtomicStyles(payload) {
 	const { atomicStyles, isPreview, isFormatted, defaultSelector, layers, defaultUtilitiesLayer } = payload;
 	const sortedStyles = sortAtomicStyles(atomicStyles, defaultSelector);
@@ -2317,6 +3341,26 @@ function renderAtomicStyles(payload) {
 	}));
 	return parts.join(lineEnd);
 }
+/**
+* Recursively converts a `PreflightDefinition` object tree into CSS style blocks.
+* @internal
+*
+* @param options - An object containing:
+*   - `engine` — the engine instance (used for selector transformation).
+*   - `preflightDefinition` — the nested object tree of selectors and CSS properties.
+*   - `blocks` — accumulator map for the resulting CSS blocks.
+* @param options.engine - The engine instance used to run selector transforms.
+* @param options.preflightDefinition - The nested preflight definition object to convert into CSS blocks.
+* @param options.blocks - Optional accumulator map reused during recursive descent.
+* @returns The accumulated `CSSStyleBlocks` map.
+*
+* @remarks Each key in the definition is either a CSS property (when its value is a property value) or a nested selector scope (when its value is an object). Selector keys are expanded through `hooks.transformSelectors`. The resulting blocks map is consumable by `renderCSSStyleBlocks`.
+*
+* @example
+* ```ts
+* const blocks = await _renderPreflightDefinition({ engine, preflightDefinition: { ':root': { '--color': 'red' } } })
+* ```
+*/
 async function _renderPreflightDefinition({ engine, preflightDefinition, blocks = /* @__PURE__ */ new Map() }) {
 	for (const [selector, propertiesOrDefinition] of Object.entries(preflightDefinition)) {
 		if (propertiesOrDefinition == null) continue;
@@ -2355,6 +3399,23 @@ async function _renderPreflightDefinition({ engine, preflightDefinition, blocks
 	}
 	return blocks;
 }
+/**
+* Renders a `PreflightDefinition` into a CSS string via the engine's selector pipeline.
+* @internal
+*
+* @param payload - An object with the `engine`, the `preflightDefinition` to render, and `isFormatted` flag.
+* @param payload.engine - The engine instance whose selector pipeline should be applied.
+* @param payload.preflightDefinition - The preflight definition tree to render.
+* @param payload.isFormatted - Whether the rendered CSS should include indentation and line breaks.
+* @returns The rendered CSS string.
+*
+* @remarks A convenience wrapper that calls `_renderPreflightDefinition` and pipes the result through `renderCSSStyleBlocks`.
+*
+* @example
+* ```ts
+* const css = await renderPreflightDefinition({ engine, preflightDefinition: { ':root': { color: 'red' } }, isFormatted: true })
+* ```
+*/
 async function renderPreflightDefinition(payload) {
 	const { engine, preflightDefinition, isFormatted } = payload;
 	return renderCSSStyleBlocks(await _renderPreflightDefinition({
@@ -2362,31 +3423,127 @@ async function renderPreflightDefinition(payload) {
 		preflightDefinition
 	}), isFormatted);
 }
-
 //#endregion
 //#region src/index.ts
+/**
+* Identity helper that returns the engine configuration as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the configuration object.
+* @param config - The engine configuration object.
+* @returns The same configuration object, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect. Useful in `pika.config.ts` files for IDE support.
+*
+* @example
+* ```ts
+* export default defineEngineConfig({ prefix: 'pk-', plugins: [myPlugin()] })
+* ```
+*/
 function defineEngineConfig(config) {
 	return config;
 }
+/**
+* Identity helper that returns the style definition as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the style definition.
+* @param styleDefinition - A style definition object.
+* @returns The same style definition, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect. Useful for extracting a reusable style definition with full type safety.
+*
+* @example
+* ```ts
+* const card = defineStyleDefinition({ padding: '1rem', borderRadius: '0.5rem' })
+* ```
+*/
 function defineStyleDefinition(styleDefinition) {
 	return styleDefinition;
 }
+/**
+* Identity helper that returns the preflight as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the preflight.
+* @param preflight - A preflight definition: a function, a static string/object, or a wrapper with `layer`/`id` metadata.
+* @returns The same preflight, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect. Useful for defining reusable preflight values with type safety.
+*
+* @example
+* ```ts
+* const reset = definePreflight('*, *::before { box-sizing: border-box; }')
+* ```
+*/
 function definePreflight(preflight) {
 	return preflight;
 }
+/**
+* Identity helper that returns the keyframes definition as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the keyframes configuration.
+* @param keyframes - A keyframes definition: a name string, a tuple, or an object form.
+* @returns The same keyframes definition, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect.
+*
+* @example
+* ```ts
+* const spin = defineKeyframes(['spin', { from: { transform: 'rotate(0deg)' }, to: { transform: 'rotate(360deg)' } }])
+* ```
+*/
 function defineKeyframes(keyframes) {
 	return keyframes;
 }
+/**
+* Identity helper that returns the selector definition as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the selector configuration.
+* @param selector - A selector definition: a string redirect, tuple, or object form.
+* @returns The same selector definition, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect.
+*
+* @example
+* ```ts
+* const hover = defineSelector(['hover', '&:hover'])
+* ```
+*/
 function defineSelector(selector) {
 	return selector;
 }
+/**
+* Identity helper that returns the shortcut definition as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the shortcut configuration.
+* @param shortcut - A shortcut definition: a string redirect, tuple, or object form.
+* @returns The same shortcut definition, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect.
+*
+* @example
+* ```ts
+* const btn = defineShortcut(['btn', { padding: '0.5rem 1rem', borderRadius: '0.25rem' }])
+* ```
+*/
 function defineShortcut(shortcut) {
 	return shortcut;
 }
+/**
+* Identity helper that returns the variables definition as-is, providing TypeScript type inference and autocompletion.
+*
+* @typeParam T - The exact literal type of the variables definition.
+* @param variables - A nested record of CSS custom property definitions.
+* @returns The same variables definition, unchanged.
+*
+* @remarks A compile-time-only helper with no runtime effect.
+*
+* @example
+* ```ts
+* const vars = defineVariables({ '--color-primary': '#3b82f6', '.dark': { '--color-primary': '#60a5fa' } })
+* ```
+*/
 function defineVariables(variables) {
 	return variables;
 }
 /* c8 ignore end */
-
 //#endregion
-export { appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, log, renderCSSStyleBlocks, sortLayerNames };
+export { appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, log, renderCSSStyleBlocks, sortLayerNames };