@pikacss/core 0.0.61 → 0.0.62

package/dist/index.d.mts

@@ -37,7 +37,7 @@ declare module '@pikacss/core' {
  * createEngine({ plugins: [important()] })
  * ```
  */
-declare function important(): EnginePlugin;
+declare function important(): EnginePlugin<void>;
 //#endregion
 //#region src/plugins/keyframes.d.ts
 /**
@@ -143,7 +143,7 @@ declare module '@pikacss/core' {
  * createEngine({ plugins: [keyframes()] })
  * ```
  */
-declare function keyframes(): EnginePlugin;
+declare function keyframes(): EnginePlugin<void>;
 interface ResolvedKeyframesConfig {
   name: string;
   frames: KeyframesProgress | Nullish;
@@ -176,6 +176,26 @@ interface Diagnostic {
 }
 /** Callback used by a host to receive structured diagnostics. */
 type DiagnosticHandler = (diagnostic: Diagnostic) => void;
+/**
+ * Host semantic metadata for one engine, supplied by the integration/bundler
+ * host and transported — never interpreted — by the platform-neutral core.
+ *
+ * @remarks
+ * The host (Vite adapter, Nuxt module, a programmatic caller) is the
+ * authority for these values. Plugins consume them through
+ * `context.host` so project-relative resources resolve against the same
+ * effective PikaCSS project root as config discovery, scans, and generated
+ * artifacts — never against `process.cwd()` once a host supplied a more
+ * specific root (#118). Core adds no filesystem, path, or bundler APIs here.
+ */
+interface EngineHostContext {
+  /**
+   * The effective PikaCSS project root for this engine (e.g. Vite's
+   * `config.root`, Nuxt's `rootDir`). Absent for standalone `createEngine()`
+   * callers that supply no host context.
+   */
+  projectRoot?: string;
+}
 /** Runtime-only options accepted by {@link createEngine}. */
 interface CreateEngineOptions {
   /**
@@ -184,11 +204,40 @@ interface CreateEngineOptions {
    * @default A no-op handler.
    */
   onDiagnostic?: DiagnosticHandler;
+  /**
+   * Host semantic metadata for this engine (e.g. the effective project
+   * root). Exposed to plugins as `context.host`.
+   *
+   * @default An empty context.
+   */
+  host?: EngineHostContext;
 }
-/** Context passed to plugin hooks by the engine. */
-interface EnginePluginContext {
+/**
+ * Context passed to plugin hooks by the engine.
+ *
+ * @remarks
+ * One context object exists per plugin definition **per engine** (#116): the
+ * same object is passed to every hook invocation of that plugin/engine pair,
+ * from `configureRawConfig` through committed notifications. Long-lived
+ * callbacks a plugin registers (shortcut resolvers, preflight functions,
+ * engine service methods) should close over this context — never over mutable
+ * plugin-factory closure variables, which are shared across every engine
+ * reusing the definition.
+ */
+interface EnginePluginContext<State = void> {
   /** Instance-scoped diagnostic handler. */
   onDiagnostic: DiagnosticHandler;
+  /**
+   * Engine-local plugin state, created once per plugin/engine pair by the
+   * plugin's `createState()` initializer. `undefined` (typed `void`) for
+   * stateless plugins that omit the initializer.
+   */
+  state: State;
+  /**
+   * Host semantic metadata for this engine (#118). Read-only from a
+   * plugin's perspective; empty when no host context was supplied.
+   */
+  host: EngineHostContext;
 }
 //#endregion
 //#region src/resolver.d.ts
@@ -514,7 +563,7 @@ declare module '@pikacss/core' {
  * createEngine({ plugins: [selectors()] })
  * ```
  */
-declare function selectors$1(): EnginePlugin;
+declare function selectors$1(): EnginePlugin<void>;
 declare class SelectorResolver extends RecursiveResolver<string> {}
 /**
  * Normalizes a `Selector` configuration into a `ResolvedRuleConfig`, a redirect string, or `undefined`.
@@ -598,7 +647,7 @@ declare module '@pikacss/core' {
  * createEngine({ plugins: [shortcuts()] })
  * ```
  */
-declare function shortcuts(): EnginePlugin;
+declare function shortcuts(): EnginePlugin<void>;
 declare class ShortcutResolver extends RecursiveResolver<InternalStyleItem> {}
 //#endregion
 //#region src/plugins/variables.d.ts
@@ -749,7 +798,7 @@ declare module '@pikacss/core' {
  * createEngine({ plugins: [variables()] })
  * ```
  */
-declare function variables(): EnginePlugin;
+declare function variables(): EnginePlugin<void>;
 interface ResolvedVariable {
   name: string;
   value: InternalPropertyValue;
@@ -1333,6 +1382,8 @@ type ExtractFn = (styleDefinition: InternalStyleDefinition) => Promise<Extracted
  *
  * @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()] })
@@ -1408,7 +1459,7 @@ declare class Engine {
    *
    * @param path - The file path (ideally absolute) the current config was derived from.
    *
-   * @remarks Call from a plugin (typically in `configureEngine`) after loading data from disk. Integration layers watch registered paths and rebuild the engine when any of them changes.
+   * @remarks Call from a plugin after loading data from disk — typically in `configureEngine`, but registering during later hooks (e.g. while resolving inside `engine.use()`) is fully supported: each genuinely new path fires the `configDependencyAdded` committed notification so integration layers can extend an already-running watcher (#122). Integration layers watch registered paths and rebuild the engine when any of them changes.
    *
    * @example
    * ```ts
@@ -1433,7 +1484,7 @@ declare class Engine {
    *
    * @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
@@ -1492,13 +1543,55 @@ declare class Engine {
    * ```
    */
   addPreflight(preflight: Preflight): void;
+  /**
+   * 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 A promise of the {@link StyleUsePlan} to pass to `commitUse()`.
+   *
+   * @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 plan = await engine.prepareUse({ color: 'red' })
+   * const ids = engine.commitUse(plan)
+   * ```
+   */
+  prepareUse(...itemList: InternalStyleItem[]): Promise<StyleUsePlan>;
+  /**
+   * 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: StyleUsePlan): string[];
   /**
    * 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 Runs `transformStyleItems` and `extractStyleDefinition` hooks, resolves each extracted content into an atomic style, deduplicates by base key, and fires `atomicStyleAdded` for new entries.
+   * @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
@@ -1529,12 +1622,11 @@ declare class Engine {
    * 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
@@ -1543,7 +1635,6 @@ declare class Engine {
    */
   renderAtomicStyles(isFormatted: boolean, options?: {
     atomicStyleIds?: string[];
-    isPreview?: boolean;
   }): Promise<string>;
   /**
    * Renders the CSS `@layer` order declaration for all configured layers.
@@ -1575,6 +1666,23 @@ declare class Engine {
  * ```
  */
 declare function sortLayerNames(layers: Record<string, number>): string[];
+/**
+ * The provisional result of `engine.prepareUse()`: fully transformed, extracted,
+ * and normalized style contents plus unresolved string references, ready to be
+ * committed via `engine.commitUse()`.
+ *
+ * @remarks
+ * A plan deliberately carries no atomic style IDs and no base-key resolutions:
+ * reuse-vs-fresh-ID decisions read live `EngineStore` state and are only valid
+ * at the moment `commitUse()` runs. Discarding an uncommitted plan has no
+ * effect on the engine (#114).
+ */
+interface StyleUsePlan {
+  /** String references no plugin resolved; echoed back verbatim by `commitUse()`. */
+  unknown: Set<string>;
+  /** Deduplicated, normalized style contents in resolution order. */
+  contents: StyleContent[];
+}
 //#endregion
 //#region src/plugin.d.ts
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: unknown, returnValue?: unknown]>> = Hooks;
@@ -1586,35 +1694,72 @@ type EngineHooksDefinition = DefineHooks<{
   transformSelectors: ['async', selectors: string[]];
   transformStyleItems: ['async', styleItems: ResolvedStyleItem[]];
   transformStyleDefinitions: ['async', styleDefinitions: ResolvedStyleDefinition[]];
+  transformStyleContents: ['async', styleContents: StyleContent[]];
   preflightUpdated: ['sync', void];
   atomicStyleAdded: ['sync', AtomicStyle];
   autocompleteConfigUpdated: ['sync', void];
+  configDependencyAdded: ['sync', path: string];
 }>;
 type HookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H[1] extends void ? [] : [payload: H[1]];
-type PluginHookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H[1] extends void ? [context?: EnginePluginContext] : [payload: H[1], context?: EnginePluginContext];
+type PluginHookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any], State = any> = H[1] extends void ? [context: EnginePluginContext<State>] : [payload: H[1], context: EnginePluginContext<State>];
 type HookReturnType<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H extends [any, any, infer R] ? H[0] extends 'async' ? Promise<R> : R : H[0] extends 'async' ? Promise<H[1]> : H[1];
 type EngineHooks = { [K in keyof EngineHooksDefinition]: (plugins: EnginePlugin[], ...params: HookParams<EngineHooksDefinition[K]>) => HookReturnType<EngineHooksDefinition[K]> };
 /**
  * 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.
+ */
+declare function createEngineHooks(context: Pick<EnginePluginContext, 'onDiagnostic'> & Partial<Pick<EnginePluginContext, 'host'>>): EngineHooks;
+type EnginePluginHooksOptions<State = any> = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: PluginHookParams<EngineHooksDefinition[K], State>) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: PluginHookParams<EngineHooksDefinition[K], State>) => EngineHooksDefinition[K][1] | void };
+/**
+ * Describes an engine plugin that can hook into the PikaCSS engine lifecycle.
+ *
+ * @remarks
+ * A plugin object is a reusable **definition**, not a single-engine resource
+ * (#116): the same object may be passed to any number of `createEngine()`
+ * calls, sequentially or concurrently. Mutable per-engine data therefore must
+ * never live in the plugin factory's closure — declare it via `createState`
+ * and read/write it through `context.state`, which the engine keeps isolated
+ * per plugin/engine pair. Factory arguments that are never mutated may stay in
+ * the closure as immutable definition configuration.
  */
-declare function createEngineHooks(context: EnginePluginContext): EngineHooks;
-type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: PluginHookParams<EngineHooksDefinition[K]>) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: PluginHookParams<EngineHooksDefinition[K]>) => EngineHooksDefinition[K][1] | void };
-/** Describes an engine plugin that can hook into the PikaCSS engine lifecycle. */
-interface EnginePlugin extends EnginePluginHooksOptions {
+interface EnginePlugin<State = any> extends EnginePluginHooksOptions<State> {
   /** The unique human-readable name identifying this plugin in diagnostics. */
   name: string;
   /** Controls execution order relative to other plugins. */
   order?: 'pre' | 'post';
+  /**
+   * Initializes this plugin's engine-local state.
+   *
+   * @returns The fresh state for one engine.
+   *
+   * @remarks
+   * Invoked by the engine at most once per plugin definition **per engine**,
+   * before the first hook of this plugin runs for that engine; every hook
+   * invocation of that plugin/engine pair then receives the same object via
+   * `context.state`. Another engine reusing the same definition gets a
+   * distinct state object. Stateless plugins simply omit this.
+   */
+  createState?: () => State;
 }
 /**
  * Identity helper that provides type inference for an engine plugin definition.
  *
  * @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.
  */
-declare function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin;
+declare function defineEnginePlugin<State = void>(plugin: EnginePlugin<State>): EnginePlugin<State>;
 //#endregion
 //#region src/generated/csstype.d.ts
 type UnionString$1 = string & {};
@@ -37494,4 +37639,4 @@ declare function renderCSSStyleBlocks(blocks: CSSStyleBlocks, isFormatted: boole
  */
 declare function defineEngineConfig<const T extends EngineConfig>(config: T): T;
 //#endregion
-export { Arrayable, type AutocompleteConfig, type AutocompleteContribution, type AutocompletePatternsConfig, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type CreateEngineOptions, type DefineAutocomplete, type Diagnostic, type DiagnosticHandler, type DiagnosticLevel, type Engine, type EngineConfig, type EnginePlugin, type EnginePluginContext, FromKebab, GetValue, ImportantConfig, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Preflight, type PreflightDefinition, type PreflightFn, type Properties, type PropertyValue, ResolveFrom, type ResolvedLayerName, type ResolvedPreflight, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleDefinitionMap, type StyleItem, ToKebab, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, extractUsedVarNames, extractUsedVarNamesFromPreflightResult, important, isPlainObjectRecord, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, sortLayerNames, variables };
+export { Arrayable, type AutocompleteConfig, type AutocompleteContribution, type AutocompletePatternsConfig, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type CreateEngineOptions, type DefineAutocomplete, type Diagnostic, type DiagnosticHandler, type DiagnosticLevel, type Engine, type EngineConfig, type EngineHostContext, type EnginePlugin, type EnginePluginContext, FromKebab, GetValue, ImportantConfig, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Preflight, type PreflightDefinition, type PreflightFn, type Properties, type PropertyValue, ResolveFrom, type ResolvedLayerName, type ResolvedPreflight, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleDefinitionMap, type StyleItem, type StyleUsePlan, ToKebab, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, extractUsedVarNames, extractUsedVarNamesFromPreflightResult, important, isPlainObjectRecord, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, sortLayerNames, variables };

package/dist/index.mjs

@@ -1873,6 +1873,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
@@ -2108,7 +2195,14 @@ function createExtractFn(options) {
 //#endregion
 //#region src/plugin.ts
 const VOID_HOOKS = new Set(["preflightUpdated", "autocompleteConfigUpdated"]);
-const DEFAULT_PLUGIN_CONTEXT = { onDiagnostic: noopDiagnosticHandler };
+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 +2253,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 +2279,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 +2296,60 @@ 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;
+	};
 	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: (plugins, engine) => execAsyncHook(plugins, "configureEngine", engine, contextFor),
+		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),
+		autocompleteConfigUpdated: (plugins) => execSyncHook(plugins, "autocompleteConfigUpdated", void 0, contextFor),
+		configDependencyAdded: (plugins, path) => execSyncHook(plugins, "configDependencyAdded", path, contextFor)
 	};
 }
 createEngineHooks(DEFAULT_PLUGIN_CONTEXT);
@@ -2235,6 +2372,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;
@@ -3187,15 +3328,21 @@ 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 pluginHooks = createEngineHooks({
+		onDiagnostic,
+		host: options.host ?? {}
+	});
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
 		variables(),
@@ -3316,7 +3463,7 @@ var Engine = class {
 	*
 	* @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.
+	* @remarks Call from a plugin after loading data from disk — typically in `configureEngine`, but registering during later hooks (e.g. while resolving inside `engine.use()`) is fully supported: each genuinely new path fires the `configDependencyAdded` committed notification so integration layers can extend an already-running watcher (#122). Integration layers watch registered paths and rebuild the engine when any of them changes.
 	*
 	* @example
 	* ```ts
@@ -3324,7 +3471,11 @@ var Engine = class {
 	* ```
 	*/
 	addConfigDependency(path) {
+		if (this.configDependencies.has(path)) return;
 		this.configDependencies.add(path);
+		try {
+			this.pluginHooks.configDependencyAdded(this.config.plugins, path);
+		} catch {}
 	}
 	/**
 	* Fires the `preflightUpdated` hook to notify plugins that preflight content has changed.
@@ -3345,7 +3496,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
@@ -3421,28 +3572,61 @@ 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,
@@ -3453,11 +3637,29 @@ var Engine = class {
 			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 +3721,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 +3734,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,
@@ -3834,13 +4034,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 +4063,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 +4075,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 +4095,6 @@ function renderAtomicStyles(payload) {
 	const parts = [];
 	if (unlayeredStyles.length > 0) parts.push(renderAtomicStylesCss({
 		atomicStyles: unlayeredStyles,
-		isPreview,
 		isFormatted
 	}));
 	parts.push(...renderLayerBlocks({
@@ -3906,7 +4103,6 @@ function renderAtomicStyles(payload) {
 		isFormatted,
 		render: (styles) => renderAtomicStylesCss({
 			atomicStyles: styles,
-			isPreview,
 			isFormatted
 		})
 	}));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pikacss/core",
   "type": "module",
-  "version": "0.0.61",
+  "version": "0.0.62",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "homepage": "https://pikacss.github.io",