@pikacss/core 0.0.61 → 0.0.63

package/dist/index.mjs

@@ -1362,25 +1362,6 @@ 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";
-}
-/**
 * Type-narrowing guard that returns `true` when the value is a plain object record (non-null, non-array object).
 * @internal
 *
@@ -1513,7 +1494,7 @@ function serialize(value) {
 * @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.
+* @remarks The boolean return lets callers detect whether adding values changed the set.
 *
 * @example
 * ```ts
@@ -1528,95 +1509,6 @@ function addToSet(set, ...values) {
 	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. 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 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;
-}
-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.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.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.
@@ -1688,21 +1580,22 @@ function createEngineStore() {
 * 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 - Object containing the style `content`, the engine `prefix`, the `stored` ID map, and the resolved allocation strategy.
 * @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.
+* @param options.atomicStyleIdStrategy - Engine-owned strategy used only when a new ID is required.
 * @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 })
+* const id = getAtomicStyleId({ content, prefix: 'pk-', stored: store.atomicStyleIds, atomicStyleIdStrategy })
 * // 'pk-a'
 * ```
 */
-function getAtomicStyleId({ content, prefix, stored }) {
+function getAtomicStyleId({ content, prefix, stored, atomicStyleIdStrategy }) {
 	const baseKey = getAtomicStyleBaseKey(content);
 	if (isOrderSensitiveContent(content) === false) {
 		const cached = stored.get(baseKey);
@@ -1711,12 +1604,15 @@ function getAtomicStyleId({ content, prefix, stored }) {
 			return cached;
 		}
 	}
-	const num = stored.size;
-	const id = `${prefix}${numberToChars(num)}`;
+	const index = stored.size;
+	const id = atomicStyleIdStrategy({
+		index,
+		prefix
+	});
 	const key = getAtomicStyleStoredKey({
 		content,
 		baseKey,
-		num
+		num: index
 	});
 	stored.set(key, id);
 	log.debug(`Generated new atomic style ID: ${id}`);
@@ -1726,11 +1622,12 @@ function getAtomicStyleId({ content, prefix, stored }) {
 * 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 - Object containing the style `content`, `prefix`, `store`, the per-use-call `resolvedIdsByBaseKey` map, and the engine-owned allocation strategy.
 * @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.
+* @param options.atomicStyleIdStrategy - Engine-owned strategy used only at the new-allocation boundary.
 * @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.
@@ -1738,11 +1635,11 @@ function getAtomicStyleId({ content, prefix, stored }) {
 * @example
 * ```ts
 * const { id, atomicStyle } = resolveAtomicStyle({
-*   content, prefix: 'pk-', store, resolvedIdsByBaseKey,
+*   content, prefix: 'pk-', store, resolvedIdsByBaseKey, atomicStyleIdStrategy,
 * })
 * ```
 */
-function resolveAtomicStyle({ content, prefix, store, resolvedIdsByBaseKey }) {
+function resolveAtomicStyle({ content, prefix, store, resolvedIdsByBaseKey, atomicStyleIdStrategy }) {
 	const reusableId = findReusableAtomicStyleId({
 		content,
 		store,
@@ -1755,7 +1652,8 @@ function resolveAtomicStyle({ content, prefix, store, resolvedIdsByBaseKey }) {
 	const id = getAtomicStyleId({
 		content,
 		prefix,
-		stored: store.atomicStyleIds
+		stored: store.atomicStyleIds,
+		atomicStyleIdStrategy
 	});
 	if (store.atomicStyles.has(id)) return { id };
 	const atomicStyle = {
@@ -1873,6 +1771,93 @@ function getOrderSensitiveDependencyKeys(scoped, property) {
 	return dependencyKeys;
 }
 //#endregion
+//#region src/config-clone.ts
+/**
+* Deep-copies ordinary config data while preserving behavioral identities.
+*
+* Recursively isolated (fresh copies): plain objects (null or Object
+* prototype, third-party augmented fields included), arrays, `Map` keys and
+* values, `Set` values, `Date`, `RegExp` (with `lastIndex`).
+*
+* Identity-preserved (returned as-is): primitives, functions/callbacks, and
+* any other non-plain instance (class instances, typed arrays, promises, …) —
+* Core cannot know a safe clone semantic for those, so they are treated as
+* opaque immutable values.
+*
+* Cycles and diamond references between plain objects/arrays/Maps/Sets are
+* preserved through `seen`; `Date`/`RegExp` diamonds become independent
+* value copies (they are immutable-by-convention config data).
+*/
+function cloneConfigValue(value, seen) {
+	if (typeof value !== "object" || value == null) return value;
+	const cached = seen.get(value);
+	if (cached != null) return cached;
+	if (Array.isArray(value)) {
+		const copy = [];
+		seen.set(value, copy);
+		for (const item of value) copy.push(cloneConfigValue(item, seen));
+		return copy;
+	}
+	if (value instanceof Date) return new Date(value.getTime());
+	if (value instanceof RegExp) {
+		const copy = new RegExp(value.source, value.flags);
+		copy.lastIndex = value.lastIndex;
+		return copy;
+	}
+	if (value instanceof Map) {
+		const copy = /* @__PURE__ */ new Map();
+		seen.set(value, copy);
+		for (const [key, entry] of value) copy.set(cloneConfigValue(key, seen), cloneConfigValue(entry, seen));
+		return copy;
+	}
+	if (value instanceof Set) {
+		const copy = /* @__PURE__ */ new Set();
+		seen.set(value, copy);
+		for (const item of value) copy.add(cloneConfigValue(item, seen));
+		return copy;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return value;
+	const copy = prototype === null ? Object.create(null) : {};
+	seen.set(value, copy);
+	for (const [key, entry] of Object.entries(value)) if (key === "__proto__") Object.defineProperty(copy, key, {
+		value: cloneConfigValue(entry, seen),
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	else copy[key] = cloneConfigValue(entry, seen);
+	return copy;
+}
+/**
+* Creates the engine-local mutable working copy of a caller-owned config.
+* @internal
+*
+* @param config - The caller-owned engine configuration.
+* @returns An independent working config for one `createEngine()` invocation.
+*
+* @remarks
+* `createEngine(config)` treats the caller's `EngineConfig` graph as
+* immutable input (#117): plugin configuration hooks mutate this working
+* copy, never the caller's objects, so one caller config can be reused
+* across sequential or concurrent engine creations without accumulating
+* setup mutations. Ordinary config data is recursively isolated —
+* including module-augmented third-party fields; functions and opaque
+* class instances keep their identity; and the `plugins` array is copied
+* while the `EnginePlugin` definition objects inside it keep their
+* identity, per the #116 reusable-definition contract (per-engine plugin
+* state is keyed by definition identity).
+*/
+function cloneEngineConfig(config) {
+	const seen = /* @__PURE__ */ new WeakMap();
+	const plugins = config.plugins;
+	if (plugins != null) {
+		seen.set(plugins, [...plugins]);
+		for (const plugin of plugins) if (typeof plugin === "object" && plugin != null) seen.set(plugin, plugin);
+	}
+	return cloneConfigValue(config, seen);
+}
+//#endregion
 //#region src/constants.ts
 /**
 * CSS `@layer` at-rule prefix used when constructing layer-scoped selectors
@@ -2106,9 +2091,230 @@ function createExtractFn(options) {
 	});
 }
 //#endregion
+//#region src/finalization.ts
+const finalizers = /* @__PURE__ */ new WeakMap();
+/** @internal */
+function registerCoreEngineFinalizer(engine, finalizer) {
+	const tasks = finalizers.get(engine) ?? [];
+	tasks.push(finalizer);
+	finalizers.set(engine, tasks);
+}
+/** @internal */
+async function runCoreEngineFinalizers(engine) {
+	const tasks = finalizers.get(engine) ?? [];
+	finalizers.delete(engine);
+	for (const task of tasks) await task();
+}
+//#endregion
+//#region src/pika.ts
+const states$1 = /* @__PURE__ */ new WeakMap();
+/** @internal */
+function createPikaManager() {
+	const manager = {
+		hasStatic(name) {
+			return states$1.get(manager).entries.has(name);
+		},
+		getStatic(name) {
+			return states$1.get(manager).entries.get(name)?.implementation;
+		}
+	};
+	states$1.set(manager, {
+		entries: /* @__PURE__ */ new Map(),
+		finalized: false
+	});
+	return manager;
+}
+/** @internal */
+function createPikaRegistrationController(manager, owner) {
+	const gate = { open: false };
+	return {
+		capability: Object.freeze({ extendStatic(name, implementation) {
+			const state = states$1.get(manager);
+			if (state.finalized) throw new Error("Pika static extensions are finalized and cannot be modified");
+			if (!gate.open) throw new Error("Pika static extensions may only be registered during this plugin configureEngine hook");
+			if (typeof name !== "string" || name.trim().length === 0) throw new Error("Pika static extension name must be a non-empty string");
+			if (state.entries.has(name)) throw new Error(`Pika static extension root "${name}" is already registered`);
+			state.entries.set(name, {
+				owner,
+				implementation
+			});
+		} }),
+		open: () => {
+			gate.open = true;
+		},
+		close: () => {
+			gate.open = false;
+		}
+	};
+}
+/** @internal */
+function getPikaStaticOwner(manager, name) {
+	return states$1.get(manager).entries.get(name)?.owner;
+}
+/** @internal */
+function finalizePikaManager(manager) {
+	const state = states$1.get(manager);
+	state.finalized = true;
+	Object.freeze(manager);
+}
+//#endregion
+//#region src/typegen/registry.ts
+const states = /* @__PURE__ */ new WeakMap();
+const snapshotRenderOverrides = /* @__PURE__ */ new WeakMap();
+const MANAGED_REF_KEYS = [
+	"selectors",
+	"properties",
+	"cssProperties",
+	"cssPropertyValues",
+	"propertyConstraints"
+];
+function compareStrings$3(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function validateContribution(contribution) {
+	if (contribution == null || typeof contribution !== "object" || Array.isArray(contribution)) throw new Error("Typegen contribution must be an object");
+	if (typeof contribution.id !== "string" || contribution.id.trim().length === 0) throw new Error("Typegen contribution id must be a non-empty string");
+	if (contribution.declarations !== void 0 && typeof contribution.declarations !== "string") throw new Error("Typegen declarations must be a string when provided");
+	for (const key of MANAGED_REF_KEYS) {
+		const ref = contribution[key];
+		if (ref !== void 0 && (typeof ref !== "string" || ref.trim().length === 0)) throw new Error(`Typegen managed attachment "${key}" must be a non-empty string when provided`);
+	}
+	if (contribution.pika !== void 0) {
+		if (contribution.pika == null || typeof contribution.pika !== "object" || Array.isArray(contribution.pika)) throw new Error("Typegen Pika attachment must be an object when provided");
+		for (const [root, ref] of Object.entries(contribution.pika)) {
+			if (root.trim().length === 0) throw new Error("Typegen Pika root must be a non-empty string");
+			if (typeof ref !== "string" || ref.trim().length === 0) throw new Error(`Typegen Pika root "${root}" must reference a non-empty TypeScript expression`);
+		}
+	}
+}
+function freezePikaAttachment(pika) {
+	return Object.freeze(Object.fromEntries(Object.entries(pika).sort(([a], [b]) => compareStrings$3(a, b))));
+}
+function freezeContribution(contribution) {
+	const result = {
+		id: contribution.id,
+		...contribution.declarations === void 0 ? {} : { declarations: contribution.declarations },
+		...contribution.pika === void 0 ? {} : { pika: freezePikaAttachment(contribution.pika) },
+		...contribution.selectors === void 0 ? {} : { selectors: contribution.selectors },
+		...contribution.properties === void 0 ? {} : { properties: contribution.properties },
+		...contribution.cssProperties === void 0 ? {} : { cssProperties: contribution.cssProperties },
+		...contribution.cssPropertyValues === void 0 ? {} : { cssPropertyValues: contribution.cssPropertyValues },
+		...contribution.propertyConstraints === void 0 ? {} : { propertyConstraints: contribution.propertyConstraints }
+	};
+	return Object.freeze(result);
+}
+/** @internal */
+function createTypegenManager() {
+	const manager = { get snapshot() {
+		const snapshot = states.get(manager).snapshot;
+		if (snapshot == null) throw new Error("Typegen snapshot is not available until Engine finalization");
+		return snapshot;
+	} };
+	states.set(manager, {
+		contributions: [],
+		ids: /* @__PURE__ */ new Set(),
+		pikaOwners: /* @__PURE__ */ new Map(),
+		previewAssets: /* @__PURE__ */ new Map(),
+		renderOverrides: /* @__PURE__ */ new Map(),
+		finalized: false
+	});
+	return manager;
+}
+/** @internal */
+function createTypegenRegistrationController(manager, owner) {
+	const gate = { open: false };
+	return {
+		capability: Object.freeze({ add(contribution) {
+			const state = states.get(manager);
+			if (state.finalized) throw new Error("Typegen contributions are finalized and cannot be modified");
+			if (!gate.open) throw new Error("Typegen contributions may only be registered during this plugin configureEngine hook");
+			validateContribution(contribution);
+			if (state.ids.has(contribution.id)) throw new Error(`Typegen contribution id "${contribution.id}" is already registered`);
+			for (const root of Object.keys(contribution.pika ?? {}).sort(compareStrings$3)) if (state.pikaOwners.has(root)) throw new Error(`Typegen Pika root "${root}" is already registered`);
+			const value = freezeContribution(contribution);
+			state.ids.add(value.id);
+			for (const root of Object.keys(value.pika ?? {}).sort(compareStrings$3)) state.pikaOwners.set(root, owner);
+			state.contributions.push({
+				owner,
+				value
+			});
+		} }),
+		open: () => {
+			gate.open = true;
+		},
+		close: () => {
+			gate.open = false;
+		}
+	};
+}
+/**
+* Replaces one Core-owned generated declaration and attaches path-free render
+* metadata after plugin configuration settles but before Typegen finalization.
+* Third-party raw `declarations` never pass through this seam.
+* @internal
+*/
+function setCoreGeneratedTypegenContribution(manager, id, options) {
+	const state = states.get(manager);
+	if (state.finalized) throw new Error("Typegen contributions are finalized and cannot be modified");
+	const index = state.contributions.findIndex(({ value }) => value.id === id);
+	if (index < 0) throw new Error(`Typegen contribution id "${id}" is not registered`);
+	const validatedAssets = /* @__PURE__ */ new Map();
+	for (const asset of options.previewAssets ?? []) {
+		if (asset == null || typeof asset !== "object" || typeof asset.id !== "string" || asset.id.length === 0) throw new Error("Typegen preview asset id must be a non-empty string");
+		if (typeof asset.content !== "string" || typeof asset.mediaType !== "string" || asset.mediaType.length === 0) throw new Error(`Typegen preview asset "${asset.id}" must provide string content and a non-empty mediaType`);
+		const previous = validatedAssets.get(asset.id) ?? state.previewAssets.get(asset.id);
+		if (previous != null && (previous.content !== asset.content || previous.mediaType !== asset.mediaType)) throw new Error(`Typegen preview asset id "${asset.id}" is already registered with different content`);
+		validatedAssets.set(asset.id, Object.freeze({ ...asset }));
+	}
+	const existing = state.contributions[index];
+	state.contributions[index] = {
+		owner: existing.owner,
+		value: Object.freeze({
+			...existing.value,
+			declarations: options.declarations
+		})
+	};
+	state.renderOverrides.set(id, options.renderDeclarations);
+	for (const [assetId, asset] of validatedAssets) state.previewAssets.set(assetId, asset);
+}
+/** @internal */
+function renderTypegenContributionDeclarations(snapshot, contribution, bindings) {
+	return snapshotRenderOverrides.get(snapshot)?.get(contribution.id)?.(bindings) ?? contribution.declarations;
+}
+/** @internal */
+function validateTypegenPikaOwners(manager, getRuntimeOwner) {
+	const state = states.get(manager);
+	for (const root of [...state.pikaOwners.keys()].sort(compareStrings$3)) {
+		const typegenOwner = state.pikaOwners.get(root);
+		const runtimeOwner = getRuntimeOwner(root);
+		if (runtimeOwner != null && runtimeOwner !== typegenOwner) throw new Error(`Pika root "${root}" has different runtime and Typegen owners`);
+	}
+}
+/** @internal */
+function finalizeTypegenManager(manager) {
+	const state = states.get(manager);
+	const contributions = Object.freeze(state.contributions.map(({ value }) => value).sort((a, b) => compareStrings$3(a.id, b.id)));
+	const previewAssets = Object.freeze([...state.previewAssets.values()].sort((a, b) => compareStrings$3(a.id, b.id)));
+	const snapshot = Object.freeze({
+		contributions,
+		previewAssets
+	});
+	state.snapshot = snapshot;
+	snapshotRenderOverrides.set(snapshot, new Map(state.renderOverrides));
+	state.finalized = true;
+	Object.freeze(manager);
+}
+//#endregion
 //#region src/plugin.ts
-const VOID_HOOKS = new Set(["preflightUpdated", "autocompleteConfigUpdated"]);
-const DEFAULT_PLUGIN_CONTEXT = { onDiagnostic: noopDiagnosticHandler };
+const VOID_HOOKS = new Set(["preflightUpdated"]);
+const DEFAULT_PLUGIN_CONTEXT = {
+	onDiagnostic: noopDiagnosticHandler,
+	state: void 0,
+	host: {}
+};
+function resolvePluginContext(source, plugin) {
+	return typeof source === "function" ? source(plugin) : source;
+}
 function getPluginHook(plugin, hook) {
 	const hookFn = plugin[hook];
 	return typeof hookFn === "function" ? hookFn : null;
@@ -2159,12 +2365,13 @@ async function execAsyncHook(plugins, hook, payload, context = DEFAULT_PLUGIN_CO
 	for (const plugin of plugins) {
 		const hookFn = getPluginHook(plugin, hook);
 		if (hookFn == null) continue;
+		const pluginContext = resolvePluginContext(context, plugin);
 		try {
 			logPluginHookStart(plugin, hook);
-			current = applyHookPayload(current, await invokePluginHook(hookFn, hook, current, context));
+			current = applyHookPayload(current, await invokePluginHook(hookFn, hook, current, pluginContext));
 			logPluginHookEnd(plugin, hook);
 		} catch (error) {
-			reportPluginHookError(context, plugin, hook, error);
+			reportPluginHookError(pluginContext, plugin, hook, error);
 			throw error;
 		}
 	}
@@ -2184,12 +2391,13 @@ function execSyncHook(plugins, hook, payload, context = DEFAULT_PLUGIN_CONTEXT)
 	for (const plugin of plugins) {
 		const hookFn = getPluginHook(plugin, hook);
 		if (hookFn == null) continue;
+		const pluginContext = resolvePluginContext(context, plugin);
 		try {
 			logPluginHookStart(plugin, hook);
-			current = applyHookPayload(current, invokePluginHook(hookFn, hook, current, context));
+			current = applyHookPayload(current, invokePluginHook(hookFn, hook, current, pluginContext));
 			logPluginHookEnd(plugin, hook);
 		} catch (error) {
-			reportPluginHookError(context, plugin, hook, error);
+			reportPluginHookError(pluginContext, plugin, hook, error);
 			throw error;
 		}
 	}
@@ -2200,19 +2408,89 @@ function execSyncHook(plugins, hook, payload, context = DEFAULT_PLUGIN_CONTEXT)
 * Creates an engine-local hook dispatcher bound to one diagnostic context.
 *
 * @internal
+* @remarks
+* Each dispatcher instance owns one plugin-context store: every plugin
+* definition gets exactly one `EnginePluginContext` (with `state` initialized
+* lazily via `createState()`) per dispatcher — i.e. per engine, since
+* `createEngine` creates one dispatcher per engine (#116). The same plugin
+* definition used with another dispatcher/engine gets a distinct context and
+* distinct state.
 */
 function createEngineHooks(context) {
+	const pluginContexts = /* @__PURE__ */ new WeakMap();
+	const host = context.host ?? {};
+	const contextFor = (plugin) => {
+		let entry = pluginContexts.get(plugin);
+		if (entry == null) {
+			try {
+				entry = {
+					status: "ok",
+					context: {
+						onDiagnostic: context.onDiagnostic,
+						state: plugin.createState?.(),
+						host
+					}
+				};
+			} catch (error) {
+				entry = {
+					status: "failed",
+					error
+				};
+				emitDiagnostic(context.onDiagnostic, {
+					level: "error",
+					code: "plugin-state-init-error",
+					message: `Plugin "${plugin.name}" failed to initialize its engine-local state: ${error instanceof Error ? error.message : String(error)}`,
+					cause: error,
+					plugin: plugin.name
+				});
+			}
+			pluginContexts.set(plugin, entry);
+		}
+		if (entry.status === "failed") throw entry.error;
+		return entry.context;
+	};
+	const configureEngine = async (plugins, engine) => {
+		logHookStart("Async", "configureEngine");
+		for (const plugin of plugins) {
+			const hookFn = getPluginHook(plugin, "configureEngine");
+			if (hookFn == null) continue;
+			const pluginContext = contextFor(plugin);
+			const pikaRegistration = createPikaRegistrationController(engine.pika, plugin);
+			const typegenRegistration = createTypegenRegistrationController(engine.typegen, plugin);
+			const configurator = Object.freeze({
+				...pluginContext,
+				runtime: engine,
+				pika: pikaRegistration.capability,
+				typegen: typegenRegistration.capability
+			});
+			pikaRegistration.open();
+			typegenRegistration.open();
+			try {
+				logPluginHookStart(plugin, "configureEngine");
+				await hookFn(configurator);
+				logPluginHookEnd(plugin, "configureEngine");
+			} catch (error) {
+				reportPluginHookError(pluginContext, plugin, "configureEngine", error);
+				throw error;
+			} finally {
+				pikaRegistration.close();
+				typegenRegistration.close();
+			}
+		}
+		logHookEnd("Async", "configureEngine");
+		return engine;
+	};
 	return {
-		configureRawConfig: (plugins, config) => execAsyncHook(plugins, "configureRawConfig", config, context),
-		rawConfigConfigured: (plugins, config) => execSyncHook(plugins, "rawConfigConfigured", config, context),
-		configureResolvedConfig: (plugins, resolvedConfig) => execAsyncHook(plugins, "configureResolvedConfig", resolvedConfig, context),
-		configureEngine: (plugins, engine) => execAsyncHook(plugins, "configureEngine", engine, context),
-		transformSelectors: (plugins, selectors) => execAsyncHook(plugins, "transformSelectors", selectors, context),
-		transformStyleItems: (plugins, styleItems) => execAsyncHook(plugins, "transformStyleItems", styleItems, context),
-		transformStyleDefinitions: (plugins, styleDefinitions) => execAsyncHook(plugins, "transformStyleDefinitions", styleDefinitions, context),
-		preflightUpdated: (plugins) => execSyncHook(plugins, "preflightUpdated", void 0, context),
-		atomicStyleAdded: (plugins, atomicStyle) => execSyncHook(plugins, "atomicStyleAdded", atomicStyle, context),
-		autocompleteConfigUpdated: (plugins) => execSyncHook(plugins, "autocompleteConfigUpdated", void 0, context)
+		configureRawConfig: (plugins, config) => execAsyncHook(plugins, "configureRawConfig", config, contextFor),
+		rawConfigConfigured: (plugins, config) => execSyncHook(plugins, "rawConfigConfigured", config, contextFor),
+		configureResolvedConfig: (plugins, resolvedConfig) => execAsyncHook(plugins, "configureResolvedConfig", resolvedConfig, contextFor),
+		configureEngine,
+		transformSelectors: (plugins, selectors) => execAsyncHook(plugins, "transformSelectors", selectors, contextFor),
+		transformStyleItems: (plugins, styleItems) => execAsyncHook(plugins, "transformStyleItems", styleItems, contextFor),
+		transformStyleDefinitions: (plugins, styleDefinitions) => execAsyncHook(plugins, "transformStyleDefinitions", styleDefinitions, contextFor),
+		transformStyleContents: (plugins, styleContents) => execAsyncHook(plugins, "transformStyleContents", styleContents, contextFor),
+		preflightUpdated: (plugins) => execSyncHook(plugins, "preflightUpdated", void 0, contextFor),
+		atomicStyleAdded: (plugins, atomicStyle) => execSyncHook(plugins, "atomicStyleAdded", atomicStyle, contextFor)
 	};
 }
 createEngineHooks(DEFAULT_PLUGIN_CONTEXT);
@@ -2235,6 +2513,10 @@ function resolvePlugins(plugins) {
 *
 * @param plugin - The plugin definition to return unchanged.
 * @returns The same plugin instance.
+*
+* @remarks
+* When the plugin declares `createState`, the state type is inferred from its
+* return value and every hook's `context.state` is typed accordingly.
 */
 function defineEnginePlugin(plugin) {
 	return plugin;
@@ -2257,7 +2539,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. 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.
+* @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).
 *
 * @example
 * ```ts
@@ -2265,7 +2547,6 @@ 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,
@@ -2278,23 +2559,28 @@ function important() {
 	}
 	return defineEnginePlugin({
 		name: "core:important",
-		rawConfigConfigured(config) {
-			defaultValue = config.important?.default ?? false;
+		createState: () => ({ defaultValue: false }),
+		rawConfigConfigured(config, context) {
+			context.state.defaultValue = config.important?.default ?? false;
 		},
-		configureEngine(engine) {
-			engine.appendAutocomplete({
-				extraProperties: "__important",
-				properties: { __important: "boolean" }
+		configureEngine(configurator) {
+			configurator.typegen.add({
+				id: "core:important",
+				declarations: [
+					"interface __PikaImportantProperties {",
+					"  __important?: boolean",
+					"}"
+				].join("\n"),
+				properties: "__PikaImportantProperties"
 			});
 		},
-		transformStyleDefinitions(styleDefinitions) {
+		transformStyleDefinitions(styleDefinitions, context) {
 			return styleDefinitions.map((styleDefinition) => {
 				const { __important, ...rest } = styleDefinition;
 				const explicit = __important;
-				const important = explicit ?? defaultValue;
+				const important = explicit ?? context.state.defaultValue;
 				if (important === false && explicit == null) return rest;
 				return Object.fromEntries(Object.entries(rest).map(([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)];
 				}));
@@ -2303,45 +2589,147 @@ function important() {
 	});
 }
 //#endregion
-//#region src/plugins/keyframes.ts
+//#region src/typegen/jsdoc.ts
+const LEFT_TO_RIGHT_MARK = "‎";
+const RE_LEADING_INDENT = /^(\s*)/;
+const RE_USER_JSDOC_TAG = /^(\s*)@/;
+function sanitizeJSDocText(text, neutralizeTags) {
+	return text.replaceAll("*/", `*${LEFT_TO_RIGHT_MARK}/`).split("\n").map((line) => {
+		return `${LEFT_TO_RIGHT_MARK}${(neutralizeTags ? line.replace(RE_USER_JSDOC_TAG, `$1${LEFT_TO_RIGHT_MARK}@`) : line).replace(RE_LEADING_INDENT, `$1${LEFT_TO_RIGHT_MARK}`)}`;
+	});
+}
+function markdownImage(alt, href) {
+	return `![${alt}](${href})`;
+}
 /**
-* Built-in engine plugin that provides CSS `@keyframes` registration, autocomplete integration, and smart pruning.
+* Renders one lexical-safe JSDoc block from path-free semantic documentation.
 *
-* @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
+* The renderer preserves the historical `### PikaCSS Preview` fenced-CSS
+* convention and U+200E safety workaround. Arbitrary descriptions are prevented
+* from becoming semantic JSDoc `@tags`. Preview-image hrefs are supplied only at
+* final render time, so semantic snapshots never contain host paths or URIs.
 *
-* @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.
+* @param documentation - Path-free description, preview, and semantic tags to render.
+* @param bindings - Host callbacks used to resolve semantic preview asset IDs to hrefs.
+* @param indent - Prefix applied to every line of the generated JSDoc block.
 *
-* @example
-* ```ts
-* createEngine({ plugins: [keyframes()] })
-* ```
+* @internal
 */
+function renderTypegenJSDoc(documentation, bindings = {}, indent = "") {
+	const body = [];
+	if (documentation.description != null && documentation.description.length > 0) body.push(...sanitizeJSDocText(documentation.description, true));
+	const imageLines = (documentation.previewImages ?? []).flatMap((image) => {
+		const href = bindings.resolvePreviewImageHref?.(image.assetId);
+		if (href == null) return [];
+		return sanitizeJSDocText(markdownImage(image.alt ?? "PikaCSS Preview", href), true);
+	});
+	const hasPreview = (documentation.previewCss?.length ?? 0) > 0 || imageLines.length > 0;
+	if (hasPreview && body.length > 0) body.push("");
+	if (hasPreview) body.push(`${LEFT_TO_RIGHT_MARK}### PikaCSS Preview`);
+	body.push(...imageLines);
+	if ((documentation.previewCss?.length ?? 0) > 0) {
+		body.push(`${LEFT_TO_RIGHT_MARK}\`\`\`css`);
+		body.push(...sanitizeJSDocText(documentation.previewCss, false));
+		body.push(`${LEFT_TO_RIGHT_MARK}\`\`\``);
+	}
+	const tags = (documentation.tags ?? []).flatMap((tag) => {
+		if (!/^[A-Z][\w-]*$/i.test(tag.name)) throw new Error(`Invalid Typegen JSDoc tag name: ${tag.name}`);
+		const text = tag.text == null || tag.text.length === 0 ? [] : sanitizeJSDocText(tag.text, true);
+		if (text.length === 0) return [`@${tag.name}`];
+		return [`@${tag.name} ${text[0]}`, ...text.slice(1)];
+	});
+	if (tags.length > 0 && body.length > 0) body.push("");
+	body.push(...tags);
+	if (body.length === 0) return [];
+	return [
+		`${indent}/**`,
+		...body.map((line) => `${indent} * ${line}`),
+		`${indent} */`
+	];
+}
+//#endregion
+//#region src/plugins/keyframes.ts
+function resolveKeyframesConfig(config, defaultPruneUnused) {
+	if ("external" in config) {
+		if (typeof config.external !== "string" || config.external.trim().length === 0) return void 0;
+		return {
+			name: config.external,
+			animationValues: [config.animationValues ?? []].flat(),
+			description: config.description,
+			external: true,
+			pruneUnused: false
+		};
+	}
+	if (typeof config.name !== "string" || config.name.trim().length === 0 || config.frames == null) return void 0;
+	return {
+		name: config.name,
+		frames: config.frames,
+		animationValues: [config.animationValues ?? []].flat(),
+		description: config.description,
+		external: false,
+		pruneUnused: config.pruneUnused ?? defaultPruneUnused
+	};
+}
+function renderKeyframesPreview(name, frames) {
+	const lines = [`@keyframes ${name} {`];
+	for (const [stop, properties] of Object.entries(frames)) {
+		lines.push(`  ${stop} {`);
+		for (const [property, rawValue] of Object.entries(properties)) {
+			const values = normalizeValue(rawValue) ?? [];
+			for (const value of values) lines.push(`    ${toKebab(property)}: ${value};`);
+		}
+		lines.push("  }");
+	}
+	lines.push("}");
+	return lines.join("\n");
+}
+function renderKeyframesDeclarations(definitions) {
+	const ordered = [...definitions].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+	const lines = ["interface __PikaKeyframes {"];
+	for (const definition of ordered) {
+		lines.push(...renderTypegenJSDoc({
+			description: definition.description,
+			previewCss: definition.frames == null ? void 0 : renderKeyframesPreview(definition.name, definition.frames)
+		}, {}, "  "));
+		lines.push(`  ${JSON.stringify(definition.name)}: ${JSON.stringify(definition.name)}`);
+	}
+	lines.push("}");
+	const names = ordered.map(({ name }) => JSON.stringify(name));
+	const animationValues = ordered.flatMap(({ name, animationValues }) => [name, ...animationValues]).filter((value, index, list) => list.indexOf(value) === index).map((value) => JSON.stringify(value));
+	lines.push("interface __PikaKeyframePropertyValues {");
+	lines.push(`  animationName: ${names.length === 0 ? "never" : names.join(" | ")}`);
+	lines.push(`  animation: ${animationValues.length === 0 ? "never" : animationValues.join(" | ")}`);
+	lines.push("}");
+	return lines.join("\n");
+}
+/** Built-in keyframes subsystem with config-only semantic ingress. */
 function keyframes() {
-	let resolveKeyframesConfig;
-	let configList;
 	return defineEnginePlugin({
 		name: "core:keyframes",
-		rawConfigConfigured(config) {
-			resolveKeyframesConfig = createResolveConfigFn({ pruneUnused: config.keyframes?.pruneUnused });
-			configList = config.keyframes?.definitions ?? [];
+		createState: () => ({
+			definitions: [],
+			defaultPruneUnused: true,
+			store: /* @__PURE__ */ new Map()
+		}),
+		rawConfigConfigured(config, context) {
+			context.state.definitions = config.keyframes?.definitions ?? [];
+			context.state.defaultPruneUnused = config.keyframes?.pruneUnused ?? true;
 		},
-		configureEngine(engine) {
-			engine.keyframes = {
-				store: /* @__PURE__ */ new Map(),
-				add: (...list) => {
-					list.forEach((config) => {
-						const resolved = resolveKeyframesConfig(config);
-						const { name, frames, autocomplete: autocompleteAnimation } = resolved;
-						if (frames != null) engine.keyframes.store.set(name, resolved);
-						engine.appendAutocomplete({ cssProperties: {
-							animationName: name,
-							animation: autocompleteAnimation.length > 0 ? [`${name} `, ...autocompleteAnimation] : `${name} `
-						} });
-					});
-					engine.notifyPreflightUpdated();
-				}
-			};
-			engine.keyframes.add(...configList);
+		configureEngine(configurator) {
+			const engine = configurator.runtime;
+			const resolved = configurator.state.definitions.map((definition) => resolveKeyframesConfig(definition, configurator.state.defaultPruneUnused)).filter((definition) => definition != null);
+			configurator.state.store.clear();
+			for (const definition of resolved) if (!definition.external) configurator.state.store.set(definition.name, definition);
+			const namespace = Object.freeze(Object.fromEntries(resolved.map(({ name }) => [name, name])));
+			configurator.pika.extendStatic("kf", namespace);
+			configurator.typegen.add({
+				id: "core:keyframes",
+				declarations: renderKeyframesDeclarations(resolved),
+				pika: { kf: "__PikaKeyframes" },
+				cssPropertyValues: "__PikaKeyframePropertyValues"
+			});
+			const state = configurator.state;
 			engine.addPreflight((engine, _isFormatted, ctx) => {
 				const maybeUsedName = /* @__PURE__ */ new Set();
 				engine.store.atomicStyles.forEach(({ content: { property, value } }, id) => {
@@ -2356,41 +2744,41 @@ 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 }) => {
+				for (const { name, frames, pruneUnused } of state.store.values()) {
+					if (frames == null || pruneUnused !== false && !maybeUsedName.has(name)) continue;
 					preflightDefinition[`@keyframes ${name}`] = frames;
-				});
+				}
 				return preflightDefinition;
 			});
 		}
 	});
 }
-function createResolveConfigFn({ pruneUnused: defaultPruneUnused = true } = {}) {
-	return function resolveKeyframesConfig(config) {
-		if (typeof config === "string") return {
-			name: config,
-			frames: null,
-			autocomplete: [],
-			pruneUnused: defaultPruneUnused
-		};
-		if (Array.isArray(config)) {
-			const [name, frames, autocomplete = [], pruneUnused = defaultPruneUnused] = config;
-			return {
-				name,
-				frames,
-				autocomplete,
-				pruneUnused
-			};
+//#endregion
+//#region src/plugins/layers.ts
+function compareStrings$2(a, b) {
+	return a < b ? -1 : 1;
+}
+function renderLayerDeclarations(names) {
+	return [
+		`type __PikaLayerName = ${[...[...new Set(names)].sort(compareStrings$2).map((name) => JSON.stringify(name)), "(string & {})"].join(" | ")}`,
+		"interface __PikaLayerProperties {",
+		"  __layer?: __PikaLayerName",
+		"}"
+	].join("\n");
+}
+/** Internal Core owner for the `__layer` authoring directive Typegen surface. */
+function layers() {
+	return defineEnginePlugin({
+		name: "core:layers",
+		configureEngine(configurator) {
+			configurator.typegen.add({
+				id: "core:layers",
+				declarations: renderLayerDeclarations(Object.keys(configurator.runtime.config.layers)),
+				properties: "__PikaLayerProperties"
+			});
 		}
-		const { name, frames, autocomplete = [], pruneUnused = defaultPruneUnused } = config;
-		return {
-			name,
-			frames,
-			autocomplete,
-			pruneUnused
-		};
-	};
+	});
 }
 //#endregion
 //#region src/resolver.ts
@@ -2398,6 +2786,12 @@ function stripGlobalFlag(re) {
 	if (!re.global) return re;
 	return new RegExp(re.source, re.flags.replace("g", ""));
 }
+/** Tests one input without observing or mutating the caller's RegExp lastIndex. */
+function matchesRulePattern(pattern, input) {
+	const isolated = new RegExp(pattern.source, pattern.flags);
+	isolated.lastIndex = 0;
+	return isolated.test(input);
+}
 /**
 * Base resolver class that manages static and dynamic rules and caches resolution results.
 * @internal
@@ -2712,308 +3106,311 @@ function createDynamicResolvedFactory(fn) {
 	};
 }
 /**
-* 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[] }`.
-*
-* 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')
-* // { type: 'static', rule: { key: 'hover', ... }, autocomplete: ['hover'] }
-* ```
+* Normalizes the frozen object-only selector/shortcut rule grammar.
+* Static definitions use `{ name, value }`; dynamic definitions use
+* `{ pattern, inputType, resolve, autocomplete? }`. `inputType` and rich
+* documentation metadata are semantic Typegen inputs and intentionally do not
+* affect runtime matching here.
 */
-function resolveRuleConfig(config, keyName) {
-	if (typeof config === "string") return config;
-	if (typeof config !== "object" || config === null) 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 {
+function resolveRuleConfig(config) {
+	if (typeof config !== "object" || config === null || Array.isArray(config)) return void 0;
+	const definition = config;
+	if (typeof definition.name === "string" && definition.name.trim().length > 0 && "value" in definition) return {
 		type: "static",
 		rule: {
-			key,
-			string: key,
-			resolved: [value].flat(1)
+			key: definition.name,
+			string: definition.name,
+			resolved: [definition.value].flat(1)
 		},
-		autocomplete: [key]
+		autocomplete: [definition.name]
 	};
-	if (key instanceof RegExp && typeof value === "function") return {
+	if (definition.pattern instanceof RegExp && typeof definition.inputType === "string" && definition.inputType.trim().length > 0 && typeof definition.resolve === "function") return {
 		type: "dynamic",
 		rule: {
-			key: key.source,
-			stringPattern: stripGlobalFlag(key),
-			createResolved: createDynamicResolvedFactory(value)
+			key: definition.pattern.source,
+			stringPattern: stripGlobalFlag(definition.pattern),
+			createResolved: createDynamicResolvedFactory(definition.resolve)
 		},
-		autocomplete: autocomplete != null ? [autocomplete].flat(1) : []
+		autocomplete: definition.autocomplete == null ? [] : [definition.autocomplete].flat(1)
 	};
 }
 //#endregion
 //#region src/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 renderSelectorDeclarations(definitions, onInvalidAutocomplete) {
+	const explicit = /* @__PURE__ */ new Map();
+	const dynamicTypes = [];
+	for (const definition of definitions) {
+		if ("name" in definition) {
+			explicit.set(definition.name, definition.description);
+			continue;
+		}
+		dynamicTypes.push(definition.inputType);
+		for (const value of [definition.autocomplete ?? []].flat()) {
+			if (!matchesRulePattern(definition.pattern, value)) {
+				onInvalidAutocomplete(value, definition.pattern);
+				continue;
+			}
+			explicit.set(value, definition.description);
+		}
+	}
+	const lines = ["interface __PikaExplicitSelectors {"];
+	for (const [name, description] of [...explicit].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+		lines.push(...renderTypegenJSDoc({ description }, {}, "  "));
+		lines.push(`  ${JSON.stringify(name)}?: __StyleDefinition | __StyleItem[]`);
+	}
+	lines.push("}");
+	if (dynamicTypes.length === 0) lines.push("type __PikaSelectors = __PikaExplicitSelectors");
+	else {
+		lines.push(`type __PikaDynamicSelectorInput = ${dynamicTypes.join(" | ")}`);
+		lines.push("type __PikaDynamicSelectors = { [K in __PikaDynamicSelectorInput]?: __StyleDefinition | __StyleItem[] }");
+		lines.push("type __PikaSelectors = __PikaExplicitSelectors & __PikaDynamicSelectors");
+	}
+	return lines.join("\n");
+}
+/** Built-in selector subsystem. Effective raw config is its only semantic ingress. */
 function selectors() {
-	let engine;
-	let configList;
 	return defineEnginePlugin({
 		name: "core:selectors",
-		rawConfigConfigured(config) {
-			configList = config.selectors?.definitions ?? [];
+		createState: () => ({ definitions: [] }),
+		rawConfigConfigured(config, context) {
+			context.state.definitions = config.selectors?.definitions ?? [];
 		},
-		configureEngine(_engine) {
-			engine = _engine;
-			engine.selectors = {
-				resolver: new SelectorResolver(engine.onDiagnostic),
-				add: (...list) => {
-					list.forEach((config) => {
-						const resolved = resolveSelectorConfig(config);
-						if (resolved == null) return;
-						if (typeof resolved === "string") {
-							engine.appendAutocomplete({ selectors: resolved });
-							return;
-						}
-						if (resolved.type === "static") engine.selectors.resolver.addStaticRule(resolved.rule);
-						else engine.selectors.resolver.addDynamicRule(resolved.rule);
-						engine.appendAutocomplete({ selectors: resolved.autocomplete });
-					});
-				}
-			};
-			engine.selectors.add(...configList);
-			engine.selectors.resolver.onResolved = (string, type) => {
-				if (type === "dynamic") engine.appendAutocomplete({ selectors: string });
-			};
+		configureEngine(configurator) {
+			const resolver = new SelectorResolver(configurator.onDiagnostic);
+			const acceptedDefinitions = [];
+			for (const definition of configurator.state.definitions) {
+				const resolved = resolveSelectorConfig(definition);
+				if (resolved == null) continue;
+				acceptedDefinitions.push(definition);
+				if (resolved.type === "static") resolver.addStaticRule(resolved.rule);
+				else resolver.addDynamicRule(resolved.rule);
+			}
+			configurator.state.definitions = acceptedDefinitions;
+			configurator.state.resolver = resolver;
+			const declarations = renderSelectorDeclarations(acceptedDefinitions, (value, pattern) => {
+				configurator.onDiagnostic({
+					level: "warning",
+					code: "selector-autocomplete-pattern-mismatch",
+					message: `Selector autocomplete value "${value}" does not match ${pattern}`
+				});
+			});
+			configurator.typegen.add({
+				id: "core:selectors",
+				declarations,
+				selectors: "__PikaSelectors"
+			});
 		},
-		async transformSelectors(selectors) {
+		async transformSelectors(selectors, context) {
+			const resolver = context.state.resolver;
+			if (resolver == null) return selectors;
 			const result = [];
-			for (const selector of selectors) result.push(...await engine.selectors.resolver.resolve(selector));
+			for (const selector of selectors) result.push(...await resolver.resolve(selector));
 			return result;
 		}
 	});
 }
 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'])
-* ```
-*/
+/** @internal */
 function resolveSelectorConfig(config) {
-	return resolveRuleConfig(config, "selector");
+	return resolveRuleConfig(config);
 }
 //#endregion
 //#region src/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 createStrictShortcutNamespace(definitions) {
+	const staticNames = new Set(definitions.flatMap((definition) => "name" in definition ? [definition.name] : []));
+	const dynamicPatterns = definitions.flatMap((definition) => "pattern" in definition ? [definition.pattern] : []);
+	return new Proxy(Object.create(null), { get(_target, property) {
+		if (typeof property !== "string") return void 0;
+		return staticNames.has(property) || dynamicPatterns.some((pattern) => matchesRulePattern(pattern, property)) ? property : void 0;
+	} });
+}
+function renderShortcutDeclarations(definitions, onInvalidAutocomplete, documentation = /* @__PURE__ */ new Map(), bindings = {}) {
+	const explicit = /* @__PURE__ */ new Map();
+	const dynamicTypes = [];
+	for (const definition of definitions) {
+		if ("name" in definition) {
+			explicit.set(definition.name, { description: definition.description });
+			continue;
+		}
+		dynamicTypes.push(definition.inputType);
+		for (const value of [definition.autocomplete ?? []].flat()) {
+			if (!matchesRulePattern(definition.pattern, value)) {
+				onInvalidAutocomplete(value, definition.pattern);
+				continue;
+			}
+			explicit.set(value, documentation.get(value) ?? { description: definition.description });
+		}
+	}
+	const lines = ["interface __PikaExplicitShortcuts {"];
+	for (const [name, docs] of [...explicit].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+		lines.push(...renderTypegenJSDoc(docs, bindings, "  "));
+		lines.push(`  ${JSON.stringify(name)}: string`);
+	}
+	lines.push("}");
+	if (dynamicTypes.length === 0) lines.push("type __PikaShortcuts = __PikaExplicitShortcuts");
+	else {
+		lines.push(`type __PikaDynamicShortcutInput = ${dynamicTypes.join(" | ")}`);
+		lines.push("type __PikaDynamicShortcuts = { [K in __PikaDynamicShortcutInput]: string }");
+		lines.push("type __PikaShortcuts = __PikaExplicitShortcuts & __PikaDynamicShortcuts");
+	}
+	return lines.join("\n");
+}
+function resolveShortcutConfigForContext(config, context) {
+	if (context != null && typeof config === "object" && config != null && !Array.isArray(config) && "pattern" in config) return resolveRuleConfig({
+		...config,
+		resolve: (matched) => config.resolve(matched, context)
+	});
+	return resolveRuleConfig(config);
+}
+function createShortcutResolver(definitions, onDiagnostic, context) {
+	const resolver = new ShortcutResolver(onDiagnostic);
+	for (const definition of definitions) {
+		const resolved = resolveShortcutConfigForContext(definition, context);
+		if (resolved?.type === "static") resolver.addStaticRule(resolved.rule);
+		else if (resolved?.type === "dynamic") resolver.addDynamicRule(resolved.rule);
+	}
+	return resolver;
+}
+function renderPreviewCss(contents) {
+	if (contents.length === 0) return "";
+	const blocks = /* @__PURE__ */ new Map();
+	for (const { selector: rawSelector, property, value } of contents) {
+		const selector = [...rawSelector];
+		if (selector[0]?.startsWith("@layer ")) {
+			const layer = selector.shift().slice(7).trim();
+			if (layer.length > 0) selector.unshift(`@layer ${layer}`);
+		}
+		const renderedSelectors = selector.map((part) => replaceAtomicStyleIdPlaceholder(part, "pika-preview"));
+		if (renderedSelectors.length === 0) continue;
+		let current = blocks;
+		for (let index = 0; index < renderedSelectors.length; index++) {
+			const currentSelector = renderedSelectors[index];
+			const body = current.get(currentSelector) ?? { properties: [] };
+			if (index === renderedSelectors.length - 1) body.properties.push(...value.map((v) => ({
+				property,
+				value: v
+			})));
+			else body.children ??= /* @__PURE__ */ new Map();
+			current.set(currentSelector, body);
+			if (index < renderedSelectors.length - 1) current = body.children;
+		}
+	}
+	return renderCSSStyleBlocks(blocks, true).trim();
+}
+async function finalizeShortcutTypegen(engine, definitions, onDiagnostic) {
+	const documentation = /* @__PURE__ */ new Map();
+	const previewAssets = [];
+	const concreteSet = /* @__PURE__ */ new Set();
+	for (const definition of definitions) {
+		if ("pattern" in definition === false) continue;
+		for (const value of [definition.autocomplete ?? []].flat()) {
+			if (!matchesRulePattern(definition.pattern, value)) {
+				onDiagnostic({
+					level: "warning",
+					code: "shortcut-autocomplete-pattern-mismatch",
+					message: `Shortcut autocomplete value "${value}" does not match ${definition.pattern}`
+				});
+				continue;
+			}
+			concreteSet.add(value);
+		}
+	}
+	const concrete = [...concreteSet].sort();
+	for (let memberIndex = 0; memberIndex < concrete.length; memberIndex++) {
+		const member = concrete[memberIndex];
+		const owner = definitions.find((definition) => "pattern" in definition && matchesRulePattern(definition.pattern, member));
+		if (owner == null) continue;
+		const images = [];
+		let imageIndex = 0;
+		const context = Object.freeze({ preview: Object.freeze({ image(image) {
+			const assetId = `core:shortcuts:${memberIndex}:image:${imageIndex++}`;
+			previewAssets.push(Object.freeze({
+				id: assetId,
+				content: image.content,
+				mediaType: image.mediaType
+			}));
+			images.push(Object.freeze({
+				assetId,
+				...image.alt == null ? {} : { alt: image.alt }
+			}));
+		} }) });
+		let previewCss;
+		try {
+			let resolutionFailure;
+			const resolved = await createShortcutResolver(definitions, (diagnostic) => {
+				if (diagnostic.code === "resolver-resolution-error") {
+					resolutionFailure ??= diagnostic.cause ?? new Error(diagnostic.message);
+					return;
+				}
+				engine.reportDiagnostic(diagnostic);
+			}, context).resolve(member);
+			if (resolutionFailure != null) throw resolutionFailure;
+			const styleItems = resolved.filter((item) => typeof item !== "string");
+			if (styleItems.length > 0) previewCss = renderPreviewCss((await engine.prepareUse(...styleItems)).contents) || void 0;
+		} catch (cause) {
+			onDiagnostic({
+				level: "warning",
+				code: "shortcut-preview-resolution-error",
+				message: `Failed to render Typegen preview for shortcut "${member}": ${cause instanceof Error ? cause.message : String(cause)}`,
+				cause
+			});
+		}
+		documentation.set(member, Object.freeze({
+			description: owner.description,
+			...previewCss == null ? {} : { previewCss },
+			...images.length === 0 ? {} : { previewImages: Object.freeze(images) }
+		}));
+	}
+	const render = (bindings) => renderShortcutDeclarations(definitions, () => {}, documentation, bindings);
+	setCoreGeneratedTypegenContribution(engine.typegen, "core:shortcuts", {
+		declarations: render({}),
+		renderDeclarations: render,
+		previewAssets
+	});
+}
+/** Built-in shortcut subsystem. Effective raw config is its only semantic ingress. */
 function shortcuts() {
-	let engine;
-	let configList;
 	return defineEnginePlugin({
 		name: "core:shortcuts",
-		rawConfigConfigured(config) {
-			configList = config.shortcuts?.definitions ?? [];
+		createState: () => ({ definitions: [] }),
+		rawConfigConfigured(config, context) {
+			context.state.definitions = config.shortcuts?.definitions ?? [];
 		},
-		configureEngine(_engine) {
-			engine = _engine;
-			engine.shortcuts = {
-				resolver: new ShortcutResolver(engine.onDiagnostic),
-				add: (...list) => {
-					list.forEach((config) => {
-						const resolved = resolveShortcutConfig(config);
-						if (resolved == null) return;
-						if (typeof resolved === "string") {
-							engine.appendAutocomplete({ shortcuts: resolved });
-							return;
-						}
-						if (resolved.type === "static") engine.shortcuts.resolver.addStaticRule(resolved.rule);
-						else engine.shortcuts.resolver.addDynamicRule(resolved.rule);
-						engine.appendAutocomplete({ shortcuts: resolved.autocomplete });
-					});
-				}
-			};
-			engine.shortcuts.add(...configList);
-			engine.shortcuts.resolver.onResolved = (string, type) => {
-				if (type === "dynamic") engine.appendAutocomplete({ shortcuts: string });
-			};
-			const unionType = ["(string & {})", "Autocomplete['Shortcut']"].join(" | ");
-			engine.appendAutocomplete({
-				extraProperties: "__shortcut",
-				properties: { __shortcut: [unionType, `(${unionType})[]`] }
+		configureEngine(configurator) {
+			const acceptedDefinitions = configurator.state.definitions.filter((definition) => resolveShortcutConfig(definition) != null);
+			const resolver = createShortcutResolver(acceptedDefinitions, configurator.onDiagnostic);
+			configurator.state.definitions = acceptedDefinitions;
+			configurator.state.resolver = resolver;
+			configurator.pika.extendStatic("sc", createStrictShortcutNamespace(acceptedDefinitions));
+			configurator.typegen.add({
+				id: "core:shortcuts",
+				declarations: renderShortcutDeclarations(acceptedDefinitions, () => {}),
+				pika: { sc: "__PikaShortcuts" }
 			});
+			registerCoreEngineFinalizer(configurator.runtime, () => finalizeShortcutTypegen(configurator.runtime, acceptedDefinitions, configurator.onDiagnostic));
 		},
-		async transformStyleItems(styleItems) {
+		async transformStyleItems(styleItems, context) {
+			const resolver = context.state.resolver;
+			if (resolver == null) return styleItems;
 			const result = [];
 			for (const styleItem of styleItems) {
 				if (typeof styleItem === "string") {
-					result.push(...await engine.shortcuts.resolver.resolve(styleItem));
+					result.push(...await resolver.resolve(styleItem));
 					continue;
 				}
 				result.push(styleItem);
 			}
 			return result;
-		},
-		async transformStyleDefinitions(styleDefinitions) {
-			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(...explicitImportant == null ? resolved : resolved.map((definition) => ({
-						__important: explicitImportant,
-						...definition
-					})));
-				}
-				result.push(...applied, rest);
-			} else result.push(styleDefinition);
-			return result;
 		}
 	});
 }
 var ShortcutResolver = class extends RecursiveResolver {};
+/** @internal */
 function resolveShortcutConfig(config) {
-	return resolveRuleConfig(config, "shortcut");
+	return resolveShortcutConfigForContext(config);
 }
 //#endregion
 //#region src/plugins/variables.ts
-/**
-* 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;
-	let safeSet;
-	return defineEnginePlugin({
-		name: "core:variables",
-		rawConfigConfigured(config, context) {
-			resolveVariables = createResolveVariablesFn({
-				pruneUnused: config.variables?.pruneUnused,
-				onDiagnostic: context?.onDiagnostic
-			});
-			rawVariables = normalizeVariablesConfig(config.variables);
-			safeSet = new Set(config.variables?.safeList ?? []);
-		},
-		configureEngine(engine) {
-			engine.variables = {
-				store: /* @__PURE__ */ new Map(),
-				add: (variables) => {
-					resolveVariables(variables).forEach((resolved) => {
-						const { name, value, autocomplete: { asValueOf, asProperty } } = resolved;
-						const cssProperties = Object.fromEntries(asValueOf.filter((p) => p !== "-").map((p) => [p, `var(${name})`]));
-						engine.appendAutocomplete({
-							cssProperties,
-							extraCssProperties: asProperty ? name : void 0
-						});
-						if (value != null) {
-							const list = engine.variables.store.get(name) ?? [];
-							list.push(resolved);
-							engine.variables.store.set(name, list);
-						}
-					});
-					engine.notifyPreflightUpdated();
-				}
-			};
-			rawVariables.forEach((variables) => engine.variables.add(variables));
-			engine.addPreflight({
-				id: "core:variables",
-				preflight: async (engine, isFormatted, ctx) => {
-					const used = /* @__PURE__ */ new Set();
-					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 }) => engine.invokePreflight(fn, isFormatted, ctx).catch(() => null)))).forEach((result) => {
-						if (result == null) return;
-						extractUsedVarNamesFromPreflightResult(result).forEach((name) => used.add(name));
-					});
-					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();
-						const entries = varMap.get(name);
-						if (!entries) continue;
-						for (const { value } of entries) {
-							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);
-							}
-						}
-					}
-					const usedVariables = Array.from(engine.variables.store.values()).flat().filter(({ name, pruneUnused, value }) => (safeSet.has(name) || pruneUnused === false || used.has(name)) && value != null);
-					const preflightDefinition = {};
-					for (const { name, value, selector: _selector } of usedVariables) {
-						const selector = await engine.pluginHooks.transformSelectors(engine.config.plugins, _selector);
-						let current = preflightDefinition;
-						selector.forEach((s) => {
-							current[s] ||= {};
-							current = current[s];
-						});
-						Object.assign(current, { [name]: value });
-					}
-					return preflightDefinition;
-				}
-			});
-		}
-	});
-}
 function normalizeVariablesConfig(config) {
 	if (config == null) return [];
 	const merged = {};
@@ -3030,49 +3427,236 @@ function mergeVariablesDefinition(target, source) {
 	}
 	return target;
 }
+function resolveSuggestTargets(asValueOf) {
+	if (asValueOf === false || asValueOf == null) return [];
+	return [...new Set([asValueOf].flat().map(String))];
+}
 function createResolveVariablesFn({ pruneUnused: defaultPruneUnused = true, onDiagnostic = noopDiagnosticHandler } = {}) {
-	function _resolveVariables(variables, levels, result) {
-		for (const [key, value] of Object.entries(variables)) if (key.startsWith("--")) {
-			const { value: varValue, autocomplete = {}, pruneUnused = defaultPruneUnused } = isPlainObjectRecord(value) ? value : { value };
-			result.push({
-				name: key,
-				value: varValue,
-				selector: levels.length > 0 ? levels : [":root"],
-				autocomplete: {
-					asValueOf: resolveAutocompleteValueTargets({ asValueOf: autocomplete.asValueOf }),
-					asProperty: autocomplete.asProperty ?? true
-				},
-				pruneUnused
-			});
-		} else {
-			if (!isPlainObjectRecord(value)) {
-				const message = `Invalid variables scope for selector "${key}". Expected a nested object, received ${typeof value}. Skipping.`;
-				if (onDiagnostic === noopDiagnosticHandler) log.warn(message);
-				else emitDiagnostic(onDiagnostic, {
-					level: "warning",
-					code: "variables-invalid-scope",
-					message
+	const warn = (code, message) => {
+		if (onDiagnostic === noopDiagnosticHandler) log.warn(message);
+		else emitDiagnostic(onDiagnostic, {
+			level: "warning",
+			code,
+			message
+		});
+	};
+	function walk(variables, levels, result) {
+		for (const [key, value] of Object.entries(variables)) {
+			if (key.startsWith("--")) {
+				if (!isPlainObjectRecord(value) || !("external" in value) && !("value" in value)) {
+					warn("variables-invalid-leaf", `Invalid variable leaf for "${key}". Variable leaves must use the canonical object form. Skipping.`);
+					continue;
+				}
+				if (value.external === true) {
+					if (levels.length > 0) {
+						warn("variables-scoped-external", `External variable "${key}" cannot be declared under selector scope "${levels.join(" -> ")}". Skipping.`);
+						continue;
+					}
+					result.push({
+						name: key,
+						selector: [":root"],
+						pruneUnused: false,
+						suggest: {
+							asValueOf: resolveSuggestTargets(value.suggest?.asValueOf),
+							asProperty: value.suggest?.asProperty ?? true
+						},
+						description: typeof value.description === "string" ? value.description : void 0,
+						external: true
+					});
+					continue;
+				}
+				const leaf = value;
+				result.push({
+					name: key,
+					value: leaf.value,
+					selector: levels.length > 0 ? levels : [":root"],
+					pruneUnused: leaf.pruneUnused ?? defaultPruneUnused,
+					suggest: {
+						asValueOf: resolveSuggestTargets(leaf.suggest?.asValueOf),
+						asProperty: leaf.suggest?.asProperty ?? true
+					},
+					description: leaf.description,
+					external: false
 				});
 				continue;
 			}
-			_resolveVariables(value, [...levels, key], result);
+			if (!isPlainObjectRecord(value)) {
+				warn("variables-invalid-scope", `Invalid variables scope for selector "${key}". Expected a nested object, received ${typeof value}. Skipping.`);
+				continue;
+			}
+			walk(value, [...levels, key], result);
 		}
 		return result;
 	}
-	return function resolveVariables(variables) {
-		return _resolveVariables(variables, [], []);
-	};
+	return (variables) => walk(variables, [], []);
+}
+function compareStrings$1(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function groupVariablesByName(resolved) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const variable of resolved) {
+		const list = groups.get(variable.name) ?? [];
+		list.push(variable);
+		groups.set(variable.name, list);
+	}
+	return groups;
+}
+function renderVariablePreview(name, entries) {
+	const emitted = entries.filter((entry) => !entry.external && entry.value != null);
+	if (emitted.length === 0) return void 0;
+	const lines = [];
+	for (const entry of emitted) {
+		entry.selector.forEach((selector, depth) => {
+			lines.push(`${"  ".repeat(depth)}${selector} {`);
+		});
+		const values = Array.isArray(entry.value) ? [...entry.value[1].map(String), String(entry.value[0])] : [String(entry.value)];
+		const propertyIndent = "  ".repeat(entry.selector.length);
+		for (const value of values) lines.push(`${propertyIndent}${name}: ${value};`);
+		for (let depth = entry.selector.length - 1; depth >= 0; depth--) lines.push(`${"  ".repeat(depth)}}`);
+	}
+	return lines.join("\n");
+}
+function renderVariableDeclarations(resolved) {
+	const groups = groupVariablesByName(resolved);
+	const orderedNames = [...groups.keys()].sort(compareStrings$1);
+	const lines = ["interface __PikaVariables {"];
+	for (const name of orderedNames) {
+		const entries = groups.get(name);
+		const descriptions = [...new Set(entries.flatMap((entry) => entry.description == null ? [] : [entry.description]))].sort(compareStrings$1);
+		const reference = `var(${name})`;
+		lines.push(...renderTypegenJSDoc({
+			description: [...descriptions, `CSS variable reference: ${reference}`].join("\n\n"),
+			previewCss: renderVariablePreview(name, entries)
+		}, {}, "  "));
+		lines.push(`  ${JSON.stringify(name)}: ${JSON.stringify(reference)}`);
+	}
+	lines.push("}");
+	lines.push("interface __PikaVariableProperties {");
+	for (const name of orderedNames) {
+		const entries = groups.get(name);
+		if (!entries.some((entry) => entry.suggest.asProperty)) continue;
+		const descriptions = [...new Set(entries.flatMap((entry) => entry.description == null ? [] : [entry.description]))].sort(compareStrings$1);
+		lines.push(...renderTypegenJSDoc({ description: descriptions.join("\n\n") || void 0 }, {}, "  "));
+		lines.push(`  ${JSON.stringify(name)}?: string | [value: string, fallback: string[]] | null | undefined`);
+	}
+	lines.push("}");
+	const valuesByTarget = /* @__PURE__ */ new Map();
+	for (const [name, entries] of groups) {
+		const reference = `var(${name})`;
+		for (const target of entries.flatMap((entry) => entry.suggest.asValueOf)) {
+			const values = valuesByTarget.get(target) ?? /* @__PURE__ */ new Set();
+			values.add(reference);
+			valuesByTarget.set(target, values);
+		}
+	}
+	lines.push("interface __PikaVariablePropertyValues {");
+	for (const target of [...valuesByTarget.keys()].sort(compareStrings$1)) {
+		const values = [...valuesByTarget.get(target)].sort(compareStrings$1).map((value) => JSON.stringify(value));
+		lines.push(`  ${JSON.stringify(target)}: ${values.join(" | ")}`);
+	}
+	lines.push("}");
+	return lines.join("\n");
 }
-function resolveAutocompleteValueTargets({ asValueOf }) {
-	const explicitTargets = asValueOf == null ? [] : [asValueOf].flat().map((value) => String(value));
-	if (explicitTargets.includes("-")) return [];
-	const targets = /* @__PURE__ */ new Set();
-	if (asValueOf == null) targets.add("*");
-	explicitTargets.forEach((target) => {
-		targets.add(target);
+function collectAtomicVariableUsage(engine, usedAtomicStyleIds) {
+	const used = /* @__PURE__ */ new Set();
+	engine.store.atomicStyles.forEach(({ content: { value } }, id) => {
+		if (usedAtomicStyleIds != null && usedAtomicStyleIds.has(id) === false) return;
+		value.flatMap(extractUsedVarNames).map(normalizeVariableName).forEach((name) => used.add(name));
+	});
+	return used;
+}
+function expandVariableUsage(used, store) {
+	const queue = Array.from(used);
+	while (queue.length > 0) {
+		const name = queue.pop();
+		const entries = store.get(name);
+		if (entries == null) continue;
+		for (const { value } of entries) {
+			const referencedValue = Array.isArray(value) ? value.join(" ") : String(value);
+			for (const refName of extractUsedVarNames(referencedValue).map(normalizeVariableName)) {
+				if (used.has(refName)) continue;
+				used.add(refName);
+				queue.push(refName);
+			}
+		}
+	}
+	return used;
+}
+/** Built-in CSS variable subsystem with config-only semantic ingress. */
+function variables() {
+	return defineEnginePlugin({
+		name: "core:variables",
+		createState: () => ({
+			definitions: [],
+			defaultPruneUnused: true,
+			safeSet: /* @__PURE__ */ new Set(),
+			resolved: [],
+			store: /* @__PURE__ */ new Map()
+		}),
+		rawConfigConfigured(config, context) {
+			context.state.definitions = normalizeVariablesConfig(config.variables);
+			context.state.defaultPruneUnused = config.variables?.pruneUnused ?? true;
+			context.state.safeSet = new Set(config.variables?.safeList ?? []);
+		},
+		configureEngine(configurator) {
+			const engine = configurator.runtime;
+			const resolveVariables = createResolveVariablesFn({
+				pruneUnused: configurator.state.defaultPruneUnused,
+				onDiagnostic: configurator.onDiagnostic
+			});
+			const resolved = configurator.state.definitions.flatMap(resolveVariables);
+			configurator.state.resolved = resolved;
+			configurator.state.store.clear();
+			for (const variable of resolved) {
+				if (variable.external || variable.value == null) continue;
+				const list = configurator.state.store.get(variable.name) ?? [];
+				list.push(variable);
+				configurator.state.store.set(variable.name, list);
+			}
+			const groups = groupVariablesByName(resolved);
+			const namespace = Object.freeze(Object.fromEntries([...groups.keys()].sort(compareStrings$1).map((name) => [name, `var(${name})`])));
+			configurator.pika.extendStatic("var", namespace);
+			configurator.typegen.add({
+				id: "core:variables",
+				declarations: renderVariableDeclarations(resolved),
+				pika: { var: "__PikaVariables" },
+				cssProperties: "__PikaVariableProperties",
+				cssPropertyValues: "__PikaVariablePropertyValues"
+			});
+			const state = configurator.state;
+			engine.getUsedVariableNames = () => new Set(expandVariableUsage(collectAtomicVariableUsage(engine), state.store));
+			engine.addPreflight({
+				id: "core:variables",
+				preflight: async (engine, isFormatted, ctx) => {
+					const used = collectAtomicVariableUsage(engine, ctx?.usedAtomicStyleIds);
+					const otherPreflights = engine.config.preflights.filter((p) => p.id !== "core:variables");
+					(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 = state.store;
+					for (const [name, entries] of varMap.entries()) {
+						if (used.has(name)) continue;
+						if (state.safeSet.has(name) || entries.some((entry) => entry.pruneUnused === false)) used.add(name);
+					}
+					expandVariableUsage(used, varMap);
+					const usedVariables = Array.from(varMap.values()).flat().filter(({ name, pruneUnused, value }) => (state.safeSet.has(name) || pruneUnused === false || used.has(name)) && value != null);
+					const preflightDefinition = {};
+					for (const { name, value, selector: rawSelector } of usedVariables) {
+						const selector = await engine.pluginHooks.transformSelectors(engine.config.plugins, rawSelector);
+						let current = preflightDefinition;
+						for (const item of selector) {
+							current[item] ||= {};
+							current = current[item];
+						}
+						Object.assign(current, { [name]: value });
+					}
+					return preflightDefinition;
+				}
+			});
+		}
 	});
-	if (targets.has("*")) return ["*"];
-	return [...targets];
 }
 const VAR_NAME_RE = /var\(\s*(--[\w-]+)/g;
 /**
@@ -3178,6 +3762,26 @@ const DEFAULT_LAYERS = {
 	[DEFAULT_PREFLIGHTS_LAYER]: 1,
 	[DEFAULT_UTILITIES_LAYER]: 10
 };
+const engineInitializationStates = /* @__PURE__ */ new WeakMap();
+const defaultAtomicStyleIdStrategy = ({ index, prefix }) => `${prefix}${numberToChars(index)}`;
+function snapshotEngineHostContext(host) {
+	const snapshot = {};
+	if (host?.projectRoot != null) Object.assign(snapshot, { projectRoot: host.projectRoot });
+	if (host?.privateCssDiscriminator != null) Object.assign(snapshot, { privateCssDiscriminator: host.privateCssDiscriminator });
+	return Object.freeze(snapshot);
+}
+function snapshotConfigDependencies(state) {
+	return Object.freeze([...state.dependencies.keys()].sort().map((key) => Object.freeze({ ...state.dependencies.get(key) })));
+}
+async function finalizeEngineInitialization(engine) {
+	const state = engineInitializationStates.get(engine);
+	await runCoreEngineFinalizers(engine);
+	validateTypegenPikaOwners(engine.typegen, (root) => getPikaStaticOwner(engine.pika, root));
+	finalizePikaManager(engine.pika);
+	finalizeTypegenManager(engine.typegen);
+	state.finalizedDependencies = snapshotConfigDependencies(state);
+	state.finalized = true;
+}
 /**
 * Creates and initializes a PikaCSS engine with the given configuration.
 *
@@ -3187,19 +3791,28 @@ const DEFAULT_LAYERS = {
 *
 * @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.
 *
+* The caller-owned `config` graph is treated as immutable input (#117): the engine clones it into an engine-local working copy before any plugin configuration hook runs, so plugin hooks that mutate their config (`config.layers ??= {}` and friends) never write back into caller-owned objects, and the same config object can be reused across sequential or concurrent `createEngine()` calls without accumulating setup mutations. Ordinary config data (plain objects/arrays, `Map`/`Set` contents, `Date`, `RegExp`) is recursively isolated — module-augmented plugin fields included; functions and other opaque class instances keep their identity and are treated as immutable values; the `plugins` array is copied while plugin definition objects keep their identity (#116).
+*
 * @example
 * ```ts
 * const engine = await createEngine({ prefix: 'pk-', plugins: [myPlugin()] })
 * ```
 */
 async function createEngine(config = {}, options = {}) {
+	config = cloneEngineConfig(config);
 	const hostOnDiagnostic = options.onDiagnostic ?? noopDiagnosticHandler;
 	const onDiagnostic = (diagnostic) => emitDiagnostic(hostOnDiagnostic, diagnostic);
-	const pluginHooks = createEngineHooks({ onDiagnostic });
+	const host = snapshotEngineHostContext(options.host);
+	const atomicStyleIdStrategy = options.atomicStyleIdStrategy ?? defaultAtomicStyleIdStrategy;
+	const pluginHooks = createEngineHooks({
+		onDiagnostic,
+		host
+	});
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
 		variables(),
 		keyframes(),
+		layers(),
 		selectors(),
 		shortcuts(),
 		important()
@@ -3216,20 +3829,18 @@ async function createEngine(config = {}, options = {}) {
 	let resolvedConfig = await resolveEngineConfig(config);
 	log.debug("Engine config resolved with prefix:", resolvedConfig.prefix);
 	resolvedConfig = await pluginHooks.configureResolvedConfig(resolvedConfig.plugins, resolvedConfig);
-	let engine = new Engine(resolvedConfig, hostOnDiagnostic, pluginHooks);
-	engine.appendAutocomplete({
-		extraProperties: "__layer",
-		properties: { __layer: "Autocomplete['Layer']" }
-	});
+	let engine = new Engine(resolvedConfig, hostOnDiagnostic, pluginHooks, atomicStyleIdStrategy);
+	engineInitializationStates.get(engine).onConfigDependency = options.onConfigDependency;
 	log.debug("Engine instance created");
 	engine = await pluginHooks.configureEngine(engine.config.plugins, engine);
+	await finalizeEngineInitialization(engine);
 	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`).
+* @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`, `appendCssImport`).
 *
 * @example
 * ```ts
@@ -3245,16 +3856,21 @@ var Engine = class {
 	onDiagnostic;
 	/** Reference to the instance-scoped plugin hook dispatcher. */
 	pluginHooks;
+	/** Finalized/read-side first-level Pika static authoring extension registry. */
+	pika;
+	/** Finalized/read-side Typegen semantic registry. */
+	typegen;
 	/** 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();
-	/**
-	* 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();
+	/** Finalized external file and directory-membership dependencies for this engine. */
+	get configDependencies() {
+		const state = engineInitializationStates.get(this);
+		return state.finalizedDependencies ?? snapshotConfigDependencies(state);
+	}
+	/** Engine-owned atomic-style ID allocation strategy. */
+	#atomicStyleIdStrategy;
 	/**
 	* Creates an engine instance from a resolved configuration.
 	*
@@ -3267,11 +3883,18 @@ var Engine = class {
 	* const engine = new Engine(resolvedConfig)
 	* ```
 	*/
-	constructor(config, onDiagnostic = noopDiagnosticHandler, pluginHooks) {
+	constructor(config, onDiagnostic = noopDiagnosticHandler, pluginHooks, atomicStyleIdStrategy = defaultAtomicStyleIdStrategy) {
+		engineInitializationStates.set(this, {
+			finalized: false,
+			dependencies: /* @__PURE__ */ new Map()
+		});
+		this.#atomicStyleIdStrategy = atomicStyleIdStrategy;
 		const safeOnDiagnostic = (diagnostic) => emitDiagnostic(onDiagnostic, diagnostic);
 		this.config = config;
 		this.onDiagnostic = safeOnDiagnostic;
 		this.pluginHooks = pluginHooks ?? createEngineHooks({ onDiagnostic: safeOnDiagnostic });
+		this.pika = createPikaManager();
+		this.typegen = createTypegenManager();
 		this.extract = createExtractFn({
 			defaultSelector: this.config.defaultSelector,
 			transformSelectors: (selectors) => this.pluginHooks.transformSelectors(this.config.plugins, selectors),
@@ -3312,19 +3935,34 @@ var Engine = class {
 		return invocation;
 	}
 	/**
-	* Registers an external file path as a config dependency of this engine.
+	* Registers a file dependency during Engine initialization.
 	*
-	* @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')
-	* ```
+	* @param path - File path whose content/existence participates in Engine configuration semantics. Missing files are allowed.
+	* @throws If registration is attempted after Engine finalization.
 	*/
 	addConfigDependency(path) {
-		this.configDependencies.add(path);
+		this.#registerConfigDependency("file", path);
+	}
+	/**
+	* Registers a direct directory-membership dependency during Engine initialization.
+	*
+	* @param path - Directory path whose direct member create/delete/rename events invalidate Engine configuration semantics.
+	* @throws If registration is attempted after Engine finalization.
+	*/
+	addConfigDirectoryMembershipDependency(path) {
+		this.#registerConfigDependency("directory-membership", path);
+	}
+	#registerConfigDependency(type, path) {
+		const state = engineInitializationStates.get(this);
+		if (state == null || state.finalized) throw new Error("Engine config dependencies are finalized and cannot be modified");
+		const key = `${type === "file" ? "0" : "1"}\0${path}`;
+		if (state.dependencies.has(key)) return;
+		const dependency = Object.freeze({
+			type,
+			path
+		});
+		state.dependencies.set(key, dependency);
+		state.onConfigDependency?.(dependency);
 	}
 	/**
 	* Fires the `preflightUpdated` hook to notify plugins that preflight content has changed.
@@ -3345,7 +3983,7 @@ var Engine = class {
 	*
 	* @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.
+	* @remarks Called automatically by `commitUse()` when a previously unseen atomic style is registered. This is a committed notification: the style's ID, cache keys, and store indices are already established, so mutating the payload is unsupported — plugins that need to transform styles must use the provisional hooks (`transformStyleItems`, `transformStyleDefinitions`, `transformSelectors`, `transformStyleContents`) instead (#114).
 	*
 	* @example
 	* ```ts
@@ -3356,35 +3994,6 @@ var Engine = class {
 		this.pluginHooks.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() {
-		this.pluginHooks.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).
@@ -3421,43 +4030,95 @@ var Engine = class {
 		this.notifyPreflightUpdated();
 	}
 	/**
-	* Processes style items through the plugin pipeline and registers the resulting atomic styles in the store.
+	* Provisionally resolves style items into a commit-ready plan without touching committed engine state.
 	*
 	* @param itemList - Style items to process: string references (shortcuts) and/or style definition objects.
-	* @returns An array containing any unresolved string references first, followed by atomic style IDs in resolution order.
+	* @returns A promise of the {@link StyleUsePlan} to pass to `commitUse()`.
 	*
-	* @remarks Runs `transformStyleItems` and `extractStyleDefinition` hooks, resolves each extracted content into an atomic style, deduplicates by base key, and fires `atomicStyleAdded` for new entries.
+	* @remarks
+	* Runs the full provisional pipeline: `transformStyleItems`, extraction
+	* (`transformStyleDefinitions`/`transformSelectors`), normalization, and the
+	* normalized-content seam `transformStyleContents`. It allocates no atomic
+	* style IDs, mutates no `EngineStore` state, and fires no committed
+	* notifications — a rejection anywhere leaves the engine exactly as it was.
+	* Plans deliberately carry no IDs: reuse-vs-fresh decisions read live store
+	* state and are only valid inside `commitUse()` (#114).
 	*
 	* @example
 	* ```ts
-	* const ids = await engine.use({ color: 'red' }, { padding: '1rem' })
+	* const plan = await engine.prepareUse({ color: 'red' })
+	* const ids = engine.commitUse(plan)
 	* ```
 	*/
-	async use(...itemList) {
-		log.debug(`Processing ${itemList.length} style items`);
+	async prepareUse(...itemList) {
+		log.debug(`Preparing ${itemList.length} style items`);
 		const { unknown, contents } = await resolveStyleItemList({
 			itemList,
 			transformStyleItems: (styleItems) => this.pluginHooks.transformStyleItems(this.config.plugins, styleItems),
 			extractStyleDefinition: (styleDefinition) => this.extract(styleDefinition)
 		});
+		return {
+			unknown,
+			contents: optimizeAtomicStyleContents(await this.pluginHooks.transformStyleContents(this.config.plugins, contents))
+		};
+	}
+	/**
+	* Commits a prepared plan: allocates/reuses atomic style IDs and registers new styles in the store.
+	*
+	* @param plan - A plan produced by `prepareUse()`.
+	* @returns An array containing any unresolved string references first, followed by atomic style IDs in resolution order.
+	*
+	* @remarks
+	* This is the short, mutation-critical section and MUST stay synchronous:
+	* integration layers commit whole modules inside a revision/epoch-checked
+	* synchronous block, so an `await` here would reopen the stale-commit race
+	* (#114). `atomicStyleAdded` fires per newly registered style as a committed
+	* notification; a throwing observer is reported through the diagnostic
+	* context but never rolls back the already-committed registration.
+	*
+	* @example
+	* ```ts
+	* const ids = engine.commitUse(await engine.prepareUse({ color: 'red' }))
+	* ```
+	*/
+	commitUse(plan) {
 		const resolvedIds = [];
 		const resolvedIdsByBaseKey = /* @__PURE__ */ new Map();
-		for (const content of contents) {
+		for (const content of plan.contents) {
 			const { id, atomicStyle } = resolveAtomicStyle({
 				content,
 				prefix: this.config.prefix,
 				store: this.store,
-				resolvedIdsByBaseKey
+				resolvedIdsByBaseKey,
+				atomicStyleIdStrategy: this.#atomicStyleIdStrategy
 			});
 			resolvedIds.push(id);
 			resolvedIdsByBaseKey.set(getAtomicStyleBaseKey(content), id);
 			if (atomicStyle != null) {
 				log.debug(`Atomic style added: ${id}`);
-				this.notifyAtomicStyleAdded(atomicStyle);
+				try {
+					this.notifyAtomicStyleAdded(atomicStyle);
+				} catch {}
 			}
 		}
-		log.debug(`Resolved ${resolvedIds.length} atomic styles, ${unknown.size} unknown items`);
-		return [...unknown, ...resolvedIds];
+		log.debug(`Resolved ${resolvedIds.length} atomic styles, ${plan.unknown.size} unknown items`);
+		return [...plan.unknown, ...resolvedIds];
+	}
+	/**
+	* 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 containing any unresolved string references first, followed by atomic style IDs in resolution order.
+	*
+	* @remarks Equivalent to `commitUse(await prepareUse(...itemList))` — the convenience path for direct consumers. Integration layers that need whole-module transactionality call the two phases separately (#114).
+	*
+	* @example
+	* ```ts
+	* const ids = await engine.use({ color: 'red' }, { padding: '1rem' })
+	* ```
+	*/
+	async use(...itemList) {
+		return this.commitUse(await this.prepareUse(...itemList));
 	}
 	/**
 	* Renders all registered preflight definitions into a CSS string.
@@ -3519,12 +4180,11 @@ var Engine = class {
 	* 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 - Optional filtering: `atomicStyleIds` to render a subset.
 	* @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.
+	* @remarks Styles are sorted by rendering weight (selector specificity depth), grouped into configured `@layer` blocks, and rendered.
 	*
 	* @example
 	* ```ts
@@ -3533,13 +4193,12 @@ var Engine = class {
 	*/
 	async renderAtomicStyles(isFormatted, options = {}) {
 		log.debug("Rendering atomic styles...");
-		const { atomicStyleIds = null, isPreview = false } = options;
+		const { atomicStyleIds = null } = options;
 		const atomicStyles = atomicStyleIds == null ? [...this.store.atomicStyles.values()] : atomicStyleIds.map((id) => this.store.atomicStyles.get(id)).filter(isNotNullish);
-		log.debug(`Rendering ${atomicStyles.length} atomic styles (preview: ${isPreview})`);
+		log.debug(`Rendering ${atomicStyles.length} atomic styles`);
 		reportUnknownAtomicStyleLayers(this, atomicStyles);
 		return renderAtomicStyles({
 			atomicStyles,
-			isPreview,
 			isFormatted,
 			defaultSelector: this.config.defaultSelector,
 			layers: this.config.layers,
@@ -3735,9 +4394,9 @@ function resolvePreflight(preflight) {
 * @internal
 *
 * @param config - The raw engine configuration.
-* @returns A `ResolvedEngineConfig` with defaults applied, plugins sorted, preflights resolved, and autocomplete initialized.
+* @returns A `ResolvedEngineConfig` with defaults applied, plugins sorted, preflights resolved, .
 *
-* @remarks Merges `DEFAULT_LAYERS`, normalizes CSS imports, resolves preflight definitions, and initializes the empty autocomplete sets/maps.
+* @remarks Merges `DEFAULT_LAYERS`, normalizes CSS imports, and resolves preflight definitions.
 *
 * @example
 * ```ts
@@ -3759,23 +4418,8 @@ async function resolveEngineConfig(config) {
 		cssImports: [...new Set(cssImports.map(normalizeCssImport).filter(isNotNullish))],
 		layers,
 		defaultPreflightsLayer,
-		defaultUtilitiesLayer,
-		autocomplete: {
-			selectors: /* @__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(),
-				shortcuts: /* @__PURE__ */ new Set(),
-				properties: /* @__PURE__ */ new Map(),
-				cssProperties: /* @__PURE__ */ new Map()
-			}
-		}
+		defaultUtilitiesLayer
 	};
-	appendAutocomplete(resolvedConfig, config.autocomplete ?? {});
 	const resolvedPreflights = preflights.map(resolvePreflight);
 	resolvedConfig.preflights.push(...resolvedPreflights);
 	log.debug(`Engine config resolved: ${resolvedPreflights.length} preflights processed`);
@@ -3834,13 +4478,13 @@ async function resolveStyleItemList({ itemList, transformStyleItems, extractStyl
 function sortAtomicStyles(styles, defaultSelector) {
 	return [...styles].sort((a, b) => calcAtomicStyleRenderingWeight(a, defaultSelector) - calcAtomicStyleRenderingWeight(b, defaultSelector));
 }
-function renderAtomicStylesCss({ atomicStyles, isPreview, isFormatted }) {
+function renderAtomicStylesCss({ atomicStyles, isFormatted }) {
 	const blocks = /* @__PURE__ */ new Map();
 	atomicStyles.forEach(({ id, content: { selector: rawSelector, property, value } }) => {
 		const { selector } = splitLayerSelector(rawSelector);
 		if (selector.some((s) => hasAtomicStyleIdPlaceholder(s)) === false || value == null) return;
 		const renderObject = {
-			selector: isPreview ? selector : selector.map((s) => replaceAtomicStyleIdPlaceholder(s, id)),
+			selector: selector.map((s) => replaceAtomicStyleIdPlaceholder(s, id)),
 			properties: value.map((v) => ({
 				property,
 				value: v
@@ -3863,9 +4507,8 @@ function renderAtomicStylesCss({ atomicStyles, isPreview, 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 - An object containing `atomicStyles`, `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.
@@ -3876,15 +4519,14 @@ function renderAtomicStylesCss({ atomicStyles, isPreview, isFormatted }) {
 *
 * @example
 * ```ts
-* const css = renderAtomicStyles({ atomicStyles, isPreview: false, isFormatted: true, defaultSelector: '.pk-__ID__', layers: { utilities: 10 } })
+* const css = renderAtomicStyles({ atomicStyles, isFormatted: true, defaultSelector: '.pk-__ID__', layers: { utilities: 10 } })
 * ```
 */
 function renderAtomicStyles(payload) {
-	const { atomicStyles, isPreview, isFormatted, defaultSelector, layers, defaultUtilitiesLayer } = payload;
+	const { atomicStyles, isFormatted, defaultSelector, layers, defaultUtilitiesLayer } = payload;
 	const sortedStyles = sortAtomicStyles(atomicStyles, defaultSelector);
 	if (layers == null) return renderAtomicStylesCss({
 		atomicStyles: sortedStyles,
-		isPreview,
 		isFormatted
 	});
 	const layerOrder = sortLayerNames(layers);
@@ -3897,7 +4539,6 @@ function renderAtomicStyles(payload) {
 	const parts = [];
 	if (unlayeredStyles.length > 0) parts.push(renderAtomicStylesCss({
 		atomicStyles: unlayeredStyles,
-		isPreview,
 		isFormatted
 	}));
 	parts.push(...renderLayerBlocks({
@@ -3906,7 +4547,6 @@ function renderAtomicStyles(payload) {
 		isFormatted,
 		render: (styles) => renderAtomicStylesCss({
 			atomicStyles: styles,
-			isPreview,
 			isFormatted
 		})
 	}));
@@ -3995,6 +4635,115 @@ async function renderPreflightDefinition(payload) {
 	}), isFormatted);
 }
 //#endregion
+//#region src/typegen/render.ts
+function joinRefs(contributions, key) {
+	const refs = contributions.flatMap((contribution) => contribution[key] == null ? [] : [contribution[key]]);
+	return refs.length === 0 ? "never" : refs.join(" | ");
+}
+function joinIntersectionRefs(contributions, key) {
+	const refs = contributions.flatMap((contribution) => contribution[key] == null ? [] : [contribution[key]]);
+	return refs.length === 0 ? "{}" : refs.join(" & ");
+}
+function compareStrings(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function renderPikaMembers(contributions) {
+	return contributions.flatMap((contribution) => Object.entries(contribution.pika ?? {})).sort(([a], [b]) => compareStrings(a, b)).map(([root, ref]) => `    ${JSON.stringify(root)}: ${ref}`);
+}
+function renderUnit(unit, index) {
+	const namespace = `__PikaTypegenUnit${index}`;
+	const contributions = [...unit.snapshot.contributions].sort((a, b) => compareStrings(a.id, b.id));
+	const declarations = contributions.flatMap((contribution) => {
+		const declarations = renderTypegenContributionDeclarations(unit.snapshot, contribution, unit.hostBindings ?? {});
+		return declarations == null ? [] : [declarations];
+	});
+	const resultType = unit.transformedFormat === "array" ? "string[]" : "string";
+	const selectors = joinIntersectionRefs(contributions, "selectors");
+	const properties = joinRefs(contributions, "properties");
+	const cssProperties = joinRefs(contributions, "cssProperties");
+	const cssPropertyValues = joinRefs(contributions, "cssPropertyValues");
+	const propertyConstraints = joinIntersectionRefs(contributions, "propertyConstraints");
+	const pikaMembers = renderPikaMembers(contributions);
+	const moduleName = JSON.stringify(unit.publicModule);
+	return {
+		namespace,
+		lines: [
+			`declare namespace ${namespace} {`,
+			...declarations,
+			...declarations.length === 0 ? [] : [""],
+			"  type __UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends ((value: infer I) => void) ? I : never",
+			"  type __Additive<T> = [T] extends [never] ? {} : __UnionToIntersection<T>",
+			`  type __SelectorContributions = ${selectors}`,
+			`  type __PropertyContributions = ${properties}`,
+			`  type __CssPropertyContributions = ${cssProperties}`,
+			`  type __CssPropertyValueContributions = ${cssPropertyValues}`,
+			`  type __PropertyConstraints = ${propertyConstraints}`,
+			`  type __CustomProperties = { [K in \`--\${string}\`]?: import(${moduleName}).TypegenCSSPropertyInputValue<__CssPropertyValueContributions, import(${moduleName}).UnionString, K> }`,
+			`  type __Properties = import(${moduleName}).TypegenCSSPropertiesInput<__CssPropertyValueContributions>`,
+			`    & import(${moduleName}).TypegenCSSPropertiesHyphenInput<__CssPropertyValueContributions>`,
+			"    & __CustomProperties",
+			"    & __Additive<__PropertyContributions>",
+			"    & __Additive<__CssPropertyContributions>",
+			"  interface __StyleDefinitionMapBase {",
+			"    [selector: string]:",
+			`      | import(${moduleName}).PropertyValue<import(${moduleName}).UnionString>`,
+			"      | __StyleDefinition",
+			"      | __StyleItem[]",
+			"      | undefined",
+			"  }",
+			"  type __ConstrainedProperties = Omit<__Properties, keyof __PropertyConstraints> & __PropertyConstraints",
+			"  type __StyleDefinitionMap = __StyleDefinitionMapBase & __SelectorContributions & __PropertyConstraints",
+			"  type __StyleDefinition = __ConstrainedProperties | __StyleDefinitionMap",
+			`  type __StyleItem = import(${moduleName}).UnionString | __StyleDefinition`,
+			`  type __StyleFn = (...params: __StyleItem[]) => ${resultType}`,
+			...pikaMembers.length === 0 ? ["  export type Pika = __StyleFn"] : [
+				"  type __StaticExtensions = {",
+				...pikaMembers,
+				"  }",
+				"  export type Pika = __StyleFn & __StaticExtensions"
+			],
+			"}"
+		]
+	};
+}
+/**
+* Renders one collision-safe TypeScript declaration document from isolated
+* finalized Engine Typegen snapshots and explicit project/host bindings.
+*
+* @param units - Isolated finalized snapshots and host bindings to render as one declaration document.
+*/
+function renderTypegenDocument(units) {
+	const fnNames = /* @__PURE__ */ new Set();
+	const rendered = units.map((unit, index) => {
+		if (fnNames.has(unit.fnName)) throw new Error(`Typegen render unit fnName "${unit.fnName}" is duplicated`);
+		fnNames.add(unit.fnName);
+		return {
+			unit,
+			...renderUnit(unit, index)
+		};
+	});
+	const vueUnits = rendered.filter(({ unit }) => unit.vueTemplateGlobals === true);
+	return [
+		"// Auto-generated by PikaCSS",
+		...rendered.flatMap(({ lines }) => ["", ...lines]),
+		"",
+		"declare global {",
+		...rendered.map(({ namespace, unit }) => `  const ${unit.fnName}: ${namespace}.Pika`),
+		"}",
+		...vueUnits.length === 0 ? [] : [
+			"",
+			"declare module 'vue' {",
+			"  interface ComponentCustomProperties {",
+			...vueUnits.map(({ namespace, unit }) => `    ${unit.fnName}: ${namespace}.Pika`),
+			"  }",
+			"}"
+		],
+		"",
+		"export {}",
+		""
+	].join("\n");
+}
+//#endregion
 //#region src/index.ts
 /**
 * Identity helper that returns the engine configuration as-is, providing TypeScript type inference and autocompletion.
@@ -4003,11 +4752,16 @@ async function renderPreflightDefinition(payload) {
 * @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.
+* @remarks A compile-time-only helper with no runtime effect. Use it for low-level `EngineConfig` authoring or as a typed value nested under the canonical project `defineConfig({ engine: ... })` surface. It is not itself the default-export root for `pika.config.*`.
 *
 * @example
 * ```ts
-* export default defineEngineConfig({ prefix: 'pk-', plugins: [myPlugin()] })
+* import { defineEngineConfig } from '@pikacss/core'
+*
+* const engineConfig = defineEngineConfig({
+*   prefix: 'pk-',
+*   plugins: [],
+* })
 * ```
 */
 function defineEngineConfig(config) {
@@ -4015,4 +4769,4 @@ function defineEngineConfig(config) {
 }
 /* c8 ignore end */
 //#endregion
-export { appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, isPlainObjectRecord, log, renderCSSStyleBlocks, sortLayerNames };
+export { createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, isPlainObjectRecord, log, renderCSSStyleBlocks, renderTypegenDocument, renderTypegenJSDoc, sortLayerNames };