@pikacss/core 0.0.57 → 0.0.58

package/README.md

@@ -25,6 +25,26 @@ const css = await engine.renderAtomicStyles(true, { atomicStyleIds: ids })
 
 See the [full documentation](https://pikacss.github.io/api/core).
 
+## Diagnostics
+
+`@pikacss/core` is platform-neutral and performs no console I/O by default. Explicitly install an instance-scoped handler when diagnostics should be surfaced:
+
+```ts
+const engine = await createEngine(config, {
+  onDiagnostic(diagnostic) {
+    // Route to your host logger, editor UI, telemetry, or test assertions.
+  },
+})
+```
+
+Plugin lifecycle failures are reported and rethrown; warnings are delivered only through the configured handler.
+
+Diagnostics and optional tracing are separate host-controlled channels, so configuring both does not duplicate the same runtime event.
+
+## Optional tracing
+
+The exported `log` and `createLogger()` APIs independently default to no-op output handlers. A host explicitly controls which debug, info, warning, and error sinks tracing uses.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -151,6 +151,46 @@ interface ResolvedKeyframesConfig {
   autocomplete: string[];
 }
 //#endregion
+//#region src/diagnostics.d.ts
+/** Severity of a PikaCSS diagnostic. */
+type DiagnosticLevel = 'warning' | 'error';
+/**
+ * Structured diagnostic emitted by the PikaCSS engine or an engine plugin.
+ *
+ * @remarks Diagnostics are data only. The core package never assumes a console,
+ * logger, browser, or Node.js runtime. Hosts decide how diagnostics are displayed.
+ */
+interface Diagnostic {
+  /** Diagnostic severity. */
+  level: DiagnosticLevel;
+  /** Stable machine-readable identifier. */
+  code: string;
+  /** Human-readable explanation. */
+  message: string;
+  /** Original error or value related to the diagnostic. */
+  cause?: unknown;
+  /** Plugin that produced the diagnostic, when applicable. */
+  plugin?: string;
+  /** Plugin hook that produced the diagnostic, when applicable. */
+  hook?: string;
+}
+/** Callback used by a host to receive structured diagnostics. */
+type DiagnosticHandler = (diagnostic: Diagnostic) => void;
+/** Runtime-only options accepted by {@link createEngine}. */
+interface CreateEngineOptions {
+  /**
+   * Receives warnings and errors produced by this engine instance.
+   *
+   * @default A no-op handler.
+   */
+  onDiagnostic?: DiagnosticHandler;
+}
+/** Context passed to plugin hooks by the engine. */
+interface EnginePluginContext {
+  /** Instance-scoped diagnostic handler. */
+  onDiagnostic: DiagnosticHandler;
+}
+//#endregion
 //#region src/resolver.d.ts
 /**
  * Wrapper holding a resolved value, used as the cache entry in resolver maps.
@@ -231,6 +271,7 @@ interface DynamicRule<T> {
  * ```
  */
 declare abstract class AbstractResolver<T> {
+  readonly onDiagnostic: DiagnosticHandler;
   /** Cache of previously resolved input-string → result pairs. */
   _resolvedResultsMap: Map<string, ResolvedResult<T>>;
   /** Negative cache of input strings that matched no rule at all. Retryable-unresolved dynamic results (a matched dynamic rule whose value fn returned nullish) are never stored here. */
@@ -243,6 +284,9 @@ declare abstract class AbstractResolver<T> {
   dynamicRulesMap: Map<string, DynamicRule<T>>;
   /** Callback invoked after a successful resolution, receiving the input string, rule type, and result. */
   onResolved: (string: string, type: 'static' | 'dynamic', result: ResolvedResult<T>) => void;
+  constructor(onDiagnostic?: DiagnosticHandler);
+  /** Reports through the host handler, falling back to the optional logger only for standalone resolvers. */
+  reportDiagnostic(diagnostic: Diagnostic): void;
   get staticRules(): StaticRule<T>[];
   get dynamicRules(): DynamicRule<T>[];
   /**
@@ -1284,6 +1328,7 @@ type ExtractFn = (styleDefinition: InternalStyleDefinition) => Promise<Extracted
  * Creates and initializes a PikaCSS engine with the given configuration.
  *
  * @param config - The engine configuration, including plugins, selectors, shortcuts, variables, keyframes, preflights, and layer settings.
+ * @param options - Runtime-only host capabilities, including the instance-scoped diagnostic handler.
  * @returns A fully initialized `Engine` instance.
  *
  * @remarks Core plugins (`important`, `variables`, `keyframes`, `selectors`, `shortcuts`) are prepended automatically. The function resolves plugins, runs all configuration hooks in sequence, and returns the ready-to-use engine.
@@ -1293,7 +1338,7 @@ type ExtractFn = (styleDefinition: InternalStyleDefinition) => Promise<Extracted
  * const engine = await createEngine({ prefix: 'pk-', plugins: [myPlugin()] })
  * ```
  */
-declare function createEngine(config?: EngineConfig): Promise<Engine>;
+declare function createEngine(config?: EngineConfig, options?: CreateEngineOptions): Promise<Engine>;
 /**
  * The PikaCSS engine: manages atomic style resolution, rendering, preflights, and plugin hooks.
  *
@@ -1309,19 +1354,10 @@ declare function createEngine(config?: EngineConfig): Promise<Engine>;
 declare class Engine {
   /** The fully resolved engine configuration. */
   config: ResolvedEngineConfig;
-  /** Reference to the plugin hook dispatcher for invoking lifecycle hooks. */
-  pluginHooks: {
-    configureRawConfig: (plugins: EnginePlugin[], payload: EngineConfig) => Promise<EngineConfig>;
-    rawConfigConfigured: (plugins: EnginePlugin[], payload: EngineConfig) => void;
-    configureResolvedConfig: (plugins: EnginePlugin[], payload: ResolvedEngineConfig) => Promise<ResolvedEngineConfig>;
-    configureEngine: (plugins: EnginePlugin[], payload: Engine) => Promise<Engine>;
-    transformSelectors: (plugins: EnginePlugin[], payload: string[]) => Promise<string[]>;
-    transformStyleItems: (plugins: EnginePlugin[], payload: StyleItem[]) => Promise<StyleItem[]>;
-    transformStyleDefinitions: (plugins: EnginePlugin[], payload: StyleDefinition[]) => Promise<StyleDefinition[]>;
-    preflightUpdated: (plugins: EnginePlugin[]) => void;
-    atomicStyleAdded: (plugins: EnginePlugin[], payload: AtomicStyle) => AtomicStyle;
-    autocompleteConfigUpdated: (plugins: EnginePlugin[]) => void;
-  };
+  /** Instance-scoped diagnostic handler supplied by the host. */
+  readonly onDiagnostic: DiagnosticHandler;
+  /** Reference to the instance-scoped plugin hook dispatcher. */
+  pluginHooks: ReturnType<typeof createEngineHooks>;
   /** The extraction function that decomposes style definitions into atomic style contents. */
   extract: ExtractFn;
   /** The engine's runtime store holding registered atomic styles and their ID mappings. */
@@ -1344,7 +1380,13 @@ declare class Engine {
    * const engine = new Engine(resolvedConfig)
    * ```
    */
-  constructor(config: ResolvedEngineConfig);
+  constructor(config: ResolvedEngineConfig, onDiagnostic?: DiagnosticHandler, pluginHooks?: ReturnType<typeof createEngineHooks>);
+  /**
+   * Reports a structured diagnostic to this engine instance's host handler.
+   *
+   * @param diagnostic - The structured warning or error to deliver.
+   */
+  reportDiagnostic(diagnostic: Diagnostic): void;
   /**
    * Invokes a preflight function, memoizing the result in the given render-pass context.
    *
@@ -1549,45 +1591,28 @@ type EngineHooksDefinition = DefineHooks<{
   autocompleteConfigUpdated: ['sync', void];
 }>;
 type HookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H[1] extends void ? [] : [payload: H[1]];
-type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: HookParams<EngineHooksDefinition[K]>) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: HookParams<EngineHooksDefinition[K]>) => EngineHooksDefinition[K][1] | void };
+type PluginHookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H[1] extends void ? [context?: EnginePluginContext] : [payload: H[1], context?: EnginePluginContext];
+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]> };
 /**
- * Describes an engine plugin that can hook into the PikaCSS engine lifecycle.
- *
- * @remarks Plugins implement optional hook methods corresponding to engine lifecycle events. Hooks run in plugin registration order, optionally reordered by the `order` property.
+ * Creates an engine-local hook dispatcher bound to one diagnostic context.
  *
- * @example
- * ```ts
- * const myPlugin: EnginePlugin = {
- *   name: 'my-plugin',
- *   configureRawConfig: (config) => ({ ...config, important: { default: true } }),
- * }
- * ```
+ * @internal
  */
+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 {
-  /** The unique human-readable name identifying this plugin in logs and diagnostics. */
+  /** The unique human-readable name identifying this plugin in diagnostics. */
   name: string;
-  /**
-   * Controls plugin execution order relative to other plugins.
-   *
-   * @default undefined (normal order)
-   */
+  /** Controls execution order relative to other plugins. */
   order?: 'pre' | 'post';
 }
 /**
- * Identity helper that returns the plugin object as-is, providing TypeScript type inference for plugin definitions.
- *
- * @param plugin - The engine plugin definition.
- * @returns The same plugin object, unchanged.
+ * Identity helper that provides type inference for an engine plugin definition.
  *
- * @remarks This is a compile-time-only helper; it has no runtime effect. Using it ensures type checking and IDE autocompletion for hook names and payloads.
- *
- * @example
- * ```ts
- * export default defineEnginePlugin({
- *   name: 'my-plugin',
- *   configureRawConfig: (config) => ({ ...config, important: { default: true } }),
- * })
- * ```
+ * @param plugin - The plugin definition to return unchanged.
+ * @returns The same plugin instance.
  */
 declare function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin;
 //#endregion
@@ -37336,7 +37361,7 @@ interface ResolvedEngineConfig {
  * @param prefix - Label prepended to every log message (e.g. `'[PikaCSS]'`).
  * @returns A logger object with `debug`, `info`, `warn`, `error` methods and configuration setters.
  *
- * @remarks Debug messages are suppressed by default. Call `log.toggleDebug()` to enable them. Each log level can be replaced with a custom implementation via the `set*Fn` methods, which is useful for redirecting output in non-browser environments.
+ * @remarks All output handlers are no-ops by default, and debug messages are additionally disabled. Hosts may install output functions through the `set*Fn` methods; engine warnings and errors are reported through `createEngine(..., { onDiagnostic })` instead.
  *
  * @example
  * ```ts
@@ -37469,4 +37494,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 DefineAutocomplete, type Engine, type EngineConfig, type EnginePlugin, 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 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 };

package/dist/index.mjs

@@ -1231,7 +1231,7 @@ function hasPropertyEffectOverlap(left, right) {
 * @param prefix - Label prepended to every log message (e.g. `'[PikaCSS]'`).
 * @returns A logger object with `debug`, `info`, `warn`, `error` methods and configuration setters.
 *
-* @remarks Debug messages are suppressed by default. Call `log.toggleDebug()` to enable them. Each log level can be replaced with a custom implementation via the `set*Fn` methods, which is useful for redirecting output in non-browser environments.
+* @remarks All output handlers are no-ops by default, and debug messages are additionally disabled. Hosts may install output functions through the `set*Fn` methods; engine warnings and errors are reported through `createEngine(..., { onDiagnostic })` instead.
 *
 * @example
 * ```ts
@@ -1244,10 +1244,11 @@ function hasPropertyEffectOverlap(left, right) {
 function createLogger(prefix) {
 	let currentPrefix = prefix;
 	let enabledDebug = false;
-	let _debug = console.log;
-	let _info = console.log;
-	let _warn = console.warn;
-	let _error = console.error;
+	const noop = (_prefix, ..._args) => {};
+	let _debug = noop;
+	let _info = noop;
+	let _warn = noop;
+	let _error = noop;
 	return {
 		debug: (...args) => {
 			if (!enabledDebug) return;
@@ -1927,6 +1928,20 @@ function replaceAtomicStyleIdPlaceholder(selector, atomicStyleId) {
 	return transformOutsideQuotes(selector, (segment) => segment.replace(ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, () => atomicStyleId));
 }
 //#endregion
+//#region src/diagnostics.ts
+/** Default diagnostic handler used by the platform-neutral core. */
+const noopDiagnosticHandler = (_diagnostic) => {};
+/**
+* Delivers a diagnostic without allowing a faulty host handler to alter engine execution.
+*
+* @internal
+*/
+function emitDiagnostic(handler, diagnostic) {
+	try {
+		handler(diagnostic);
+	} catch {}
+}
+//#endregion
 //#region src/extractor.ts
 function replaceBySplitAndJoin(str, split, mapFn, join) {
 	let splitted = str.split(split);
@@ -2092,10 +2107,15 @@ function createExtractFn(options) {
 }
 //#endregion
 //#region src/plugin.ts
+const VOID_HOOKS = new Set(["preflightUpdated", "autocompleteConfigUpdated"]);
+const DEFAULT_PLUGIN_CONTEXT = { onDiagnostic: noopDiagnosticHandler };
 function getPluginHook(plugin, hook) {
 	const hookFn = plugin[hook];
 	return typeof hookFn === "function" ? hookFn : null;
 }
+function invokePluginHook(hookFn, hook, payload, context) {
+	return VOID_HOOKS.has(hook) ? hookFn(context) : hookFn(payload, context);
+}
 function applyHookPayload(current, next) {
 	return next ?? current;
 }
@@ -2111,27 +2131,29 @@ function logPluginHookStart(plugin, hook) {
 function logPluginHookEnd(plugin, hook) {
 	log.debug(`  - Plugin "${plugin.name}" completed ${hook}`);
 }
-function logPluginHookError(plugin, hook, error) {
-	log.error(`Plugin "${plugin.name}" failed to execute hook "${hook}": ${error instanceof Error ? error.message : error}`, error);
+function reportPluginHookError(context, plugin, hook, error) {
+	const message = `Plugin "${plugin.name}" failed to execute hook "${hook}": ${error instanceof Error ? error.message : String(error)}`;
+	if (context.onDiagnostic === noopDiagnosticHandler) {
+		log.error(message, error);
+		return;
+	}
+	emitDiagnostic(context.onDiagnostic, {
+		level: "error",
+		code: "plugin-hook-error",
+		message,
+		cause: error,
+		plugin: plugin.name,
+		hook
+	});
 }
 /**
-* Executes an async hook across all plugins in order, piping the payload through each plugin's handler.
-* @internal
-*
-* @typeParam P - The payload/return type flowing through the hook pipeline.
-* @param plugins - The ordered list of engine plugins to execute.
-* @param hook - The name of the async hook to invoke.
-* @param payload - The initial payload to pass into the first plugin.
-* @returns The final payload after all plugins have processed it.
+* Executes an async hook across all plugins in order, piping the payload through each handler.
 *
-* @remarks Each plugin's hook receives the current payload and may return a replacement. If a plugin's hook throws, the error is logged and the current payload is preserved for subsequent plugins.
-*
-* @example
-* ```ts
-* const config = await execAsyncHook(plugins, 'configureRawConfig', rawConfig)
-* ```
+* @internal
+* @remarks A thrown plugin error is reported through the supplied diagnostic context and then
+* rethrown. The engine never converts a failed lifecycle into a silently partial result.
 */
-async function execAsyncHook(plugins, hook, payload) {
+async function execAsyncHook(plugins, hook, payload, context = DEFAULT_PLUGIN_CONTEXT) {
 	logHookStart("Async", hook);
 	let current = payload;
 	for (const plugin of plugins) {
@@ -2139,33 +2161,24 @@ async function execAsyncHook(plugins, hook, payload) {
 		if (hookFn == null) continue;
 		try {
 			logPluginHookStart(plugin, hook);
-			current = applyHookPayload(current, await hookFn(current));
+			current = applyHookPayload(current, await invokePluginHook(hookFn, hook, current, context));
 			logPluginHookEnd(plugin, hook);
 		} catch (error) {
-			logPluginHookError(plugin, hook, error);
+			reportPluginHookError(context, plugin, hook, error);
+			throw error;
 		}
 	}
 	logHookEnd("Async", hook);
 	return current;
 }
 /**
-* Executes a synchronous hook across all plugins in order, piping the payload through each plugin's handler.
-* @internal
+* Executes a synchronous hook across all plugins in order, piping the payload through each handler.
 *
-* @typeParam P - The payload/return type flowing through the hook pipeline.
-* @param plugins - The ordered list of engine plugins to execute.
-* @param hook - The name of the sync hook to invoke.
-* @param payload - The initial payload to pass into the first plugin.
-* @returns The final payload after all plugins have processed it.
-*
-* @remarks Functions identically to `execAsyncHook` but without awaiting. Used for notification-style hooks like `preflightUpdated` or `atomicStyleAdded`.
-*
-* @example
-* ```ts
-* execSyncHook(plugins, 'atomicStyleAdded', atomicStyle)
-* ```
+* @internal
+* @remarks A thrown plugin error is reported through the supplied diagnostic context and then
+* rethrown. Notification hooks therefore cannot fail silently.
 */
-function execSyncHook(plugins, hook, payload) {
+function execSyncHook(plugins, hook, payload, context = DEFAULT_PLUGIN_CONTEXT) {
 	logHookStart("Sync", hook);
 	let current = payload;
 	for (const plugin of plugins) {
@@ -2173,78 +2186,55 @@ function execSyncHook(plugins, hook, payload) {
 		if (hookFn == null) continue;
 		try {
 			logPluginHookStart(plugin, hook);
-			current = applyHookPayload(current, hookFn(current));
+			current = applyHookPayload(current, invokePluginHook(hookFn, hook, current, context));
 			logPluginHookEnd(plugin, hook);
 		} catch (error) {
-			logPluginHookError(plugin, hook, error);
+			reportPluginHookError(context, plugin, hook, error);
+			throw error;
 		}
 	}
 	logHookEnd("Sync", hook);
 	return current;
 }
 /**
-* Pre-built hook dispatcher object mapping each hook name to a function that delegates to `execAsyncHook` or `execSyncHook`.
-* @internal
-*
-* @remarks Provides a convenient, type-safe interface for calling any engine hook by name without manually selecting between `execAsyncHook` and `execSyncHook`. Used throughout the `Engine` class.
+* Creates an engine-local hook dispatcher bound to one diagnostic context.
 *
-* @example
-* ```ts
-* const config = await hooks.configureRawConfig(plugins, rawConfig)
-* hooks.preflightUpdated(plugins)
-* ```
+* @internal
 */
-const hooks = {
-	configureRawConfig: (plugins, config) => execAsyncHook(plugins, "configureRawConfig", config),
-	rawConfigConfigured: (plugins, config) => execSyncHook(plugins, "rawConfigConfigured", config),
-	configureResolvedConfig: (plugins, resolvedConfig) => execAsyncHook(plugins, "configureResolvedConfig", resolvedConfig),
-	configureEngine: (plugins, engine) => execAsyncHook(plugins, "configureEngine", engine),
-	transformSelectors: (plugins, selectors) => execAsyncHook(plugins, "transformSelectors", selectors),
-	transformStyleItems: (plugins, styleItems) => execAsyncHook(plugins, "transformStyleItems", styleItems),
-	transformStyleDefinitions: (plugins, styleDefinitions) => execAsyncHook(plugins, "transformStyleDefinitions", styleDefinitions),
-	preflightUpdated: (plugins) => execSyncHook(plugins, "preflightUpdated", void 0),
-	atomicStyleAdded: (plugins, atomicStyle) => execSyncHook(plugins, "atomicStyleAdded", atomicStyle),
-	autocompleteConfigUpdated: (plugins) => execSyncHook(plugins, "autocompleteConfigUpdated", void 0)
-};
+function createEngineHooks(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)
+	};
+}
+createEngineHooks(DEFAULT_PLUGIN_CONTEXT);
 const orderMap = new Map([
 	[void 0, 1],
 	["pre", 0],
 	["post", 2]
 ]);
 /**
-* Sorts an array of plugins by their `order` property: `'pre'` first, default in the middle, `'post'` last.
-* @internal
-*
-* @param plugins - The unordered array of engine plugins.
-* @returns A new array sorted by execution order.
-*
-* @remarks The original array is not mutated. Plugins with the same order retain their relative insertion order (stable sort).
+* Sorts plugins by `pre`, default, then `post` order without mutating the input.
 *
-* @example
-* ```ts
-* const ordered = resolvePlugins([postPlugin, prePlugin, normalPlugin])
-* // [prePlugin, normalPlugin, postPlugin]
-* ```
+* @internal
 */
 function resolvePlugins(plugins) {
 	return [...plugins].sort((a, b) => orderMap.get(a.order) - orderMap.get(b.order));
 }
 /* c8 ignore start */
 /**
-* Identity helper that returns the plugin object as-is, providing TypeScript type inference for plugin definitions.
-*
-* @param plugin - The engine plugin definition.
-* @returns The same plugin object, unchanged.
-*
-* @remarks This is a compile-time-only helper; it has no runtime effect. Using it ensures type checking and IDE autocompletion for hook names and payloads.
+* Identity helper that provides type inference for an engine plugin definition.
 *
-* @example
-* ```ts
-* export default defineEnginePlugin({
-*   name: 'my-plugin',
-*   configureRawConfig: (config) => ({ ...config, important: { default: true } }),
-* })
-* ```
+* @param plugin - The plugin definition to return unchanged.
+* @returns The same plugin instance.
 */
 function defineEnginePlugin(plugin) {
 	return plugin;
@@ -2436,6 +2426,19 @@ var AbstractResolver = class {
 	dynamicRulesMap = /* @__PURE__ */ new Map();
 	/** Callback invoked after a successful resolution, receiving the input string, rule type, and result. */
 	onResolved = () => {};
+	constructor(onDiagnostic = noopDiagnosticHandler) {
+		this.onDiagnostic = onDiagnostic;
+	}
+	/** Reports through the host handler, falling back to the optional logger only for standalone resolvers. */
+	reportDiagnostic(diagnostic) {
+		if (this.onDiagnostic === noopDiagnosticHandler) {
+			const args = diagnostic.cause == null ? [] : [diagnostic.cause];
+			if (diagnostic.level === "error") log.error(diagnostic.message, ...args);
+			else log.warn(diagnostic.message, ...args);
+			return;
+		}
+		emitDiagnostic(this.onDiagnostic, diagnostic);
+	}
 	get staticRules() {
 		return [...this.staticRulesMap.values()];
 	}
@@ -2483,7 +2486,12 @@ var AbstractResolver = class {
 	removeStaticRule(key) {
 		const rule = this.staticRulesMap.get(key);
 		if (rule == null) {
-			log.warn(`Static rule not found for removal: ${key}`);
+			const message = `Static rule not found for removal: ${key}`;
+			this.reportDiagnostic({
+				level: "warning",
+				code: "resolver-static-rule-not-found",
+				message
+			});
 			return this;
 		}
 		log.debug(`Removing static rule: ${key}`);
@@ -2542,7 +2550,12 @@ var AbstractResolver = class {
 	*/
 	removeDynamicRule(key) {
 		if (this.dynamicRulesMap.get(key) == null) {
-			log.warn(`Dynamic rule not found for removal: ${key}`);
+			const message = `Dynamic rule not found for removal: ${key}`;
+			this.reportDiagnostic({
+				level: "warning",
+				code: "resolver-dynamic-rule-not-found",
+				message
+			});
 			return this;
 		}
 		log.debug(`Removing dynamic rule: ${key}`);
@@ -2663,12 +2676,25 @@ var RecursiveResolver = class extends AbstractResolver {
 	async resolve(string, _visited) {
 		const visited = _visited ?? /* @__PURE__ */ new Set();
 		if (visited.has(string)) {
-			log.warn(`Circular reference detected for "${string}", returning as-is`);
+			const message = `Circular reference detected for "${string}", returning as-is`;
+			this.reportDiagnostic({
+				level: "warning",
+				code: "resolver-circular-reference",
+				message
+			});
+			log.warn(message);
 			return [string];
 		}
 		visited.add(string);
 		const resolved = await this._resolve(string).catch((error) => {
-			log.warn(`Failed to resolve "${string}": ${error.message}`, error);
+			const message = `Failed to resolve "${string}": ${error instanceof Error ? error.message : String(error)}`;
+			this.reportDiagnostic({
+				level: "warning",
+				code: "resolver-resolution-error",
+				message,
+				cause: error
+			});
+			log.warn(message, error);
 		});
 		if (resolved == null) return [string];
 		const result = [];
@@ -2763,7 +2789,7 @@ function selectors() {
 		configureEngine(_engine) {
 			engine = _engine;
 			engine.selectors = {
-				resolver: new SelectorResolver(),
+				resolver: new SelectorResolver(engine.onDiagnostic),
 				add: (...list) => {
 					list.forEach((config) => {
 						const resolved = resolveSelectorConfig(config);
@@ -2832,7 +2858,7 @@ function shortcuts() {
 		configureEngine(_engine) {
 			engine = _engine;
 			engine.shortcuts = {
-				resolver: new ShortcutResolver(),
+				resolver: new ShortcutResolver(engine.onDiagnostic),
 				add: (...list) => {
 					list.forEach((config) => {
 						const resolved = resolveShortcutConfig(config);
@@ -2911,8 +2937,11 @@ function variables() {
 	let safeSet;
 	return defineEnginePlugin({
 		name: "core:variables",
-		rawConfigConfigured(config) {
-			resolveVariables = createResolveVariablesFn({ pruneUnused: config.variables?.pruneUnused });
+		rawConfigConfigured(config, context) {
+			resolveVariables = createResolveVariablesFn({
+				pruneUnused: config.variables?.pruneUnused,
+				onDiagnostic: context?.onDiagnostic
+			});
 			rawVariables = normalizeVariablesConfig(config.variables);
 			safeSet = new Set(config.variables?.safeList ?? []);
 		},
@@ -3001,7 +3030,7 @@ function mergeVariablesDefinition(target, source) {
 	}
 	return target;
 }
-function createResolveVariablesFn({ pruneUnused: defaultPruneUnused = true } = {}) {
+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 };
@@ -3017,7 +3046,13 @@ function createResolveVariablesFn({ pruneUnused: defaultPruneUnused = true } = {
 			});
 		} else {
 			if (!isPlainObjectRecord(value)) {
-				log.warn(`Invalid variables scope for selector "${key}". Expected a nested object, received ${typeof value}. Skipping.`);
+				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
+				});
 				continue;
 			}
 			_resolveVariables(value, [...levels, key], result);
@@ -3147,6 +3182,7 @@ const DEFAULT_LAYERS = {
 * Creates and initializes a PikaCSS engine with the given configuration.
 *
 * @param config - The engine configuration, including plugins, selectors, shortcuts, variables, keyframes, preflights, and layer settings.
+* @param options - Runtime-only host capabilities, including the instance-scoped diagnostic handler.
 * @returns A fully initialized `Engine` instance.
 *
 * @remarks Core plugins (`important`, `variables`, `keyframes`, `selectors`, `shortcuts`) are prepended automatically. The function resolves plugins, runs all configuration hooks in sequence, and returns the ready-to-use engine.
@@ -3156,7 +3192,10 @@ const DEFAULT_LAYERS = {
 * const engine = await createEngine({ prefix: 'pk-', plugins: [myPlugin()] })
 * ```
 */
-async function createEngine(config = {}) {
+async function createEngine(config = {}, options = {}) {
+	const hostOnDiagnostic = options.onDiagnostic ?? noopDiagnosticHandler;
+	const onDiagnostic = (diagnostic) => emitDiagnostic(hostOnDiagnostic, diagnostic);
+	const pluginHooks = createEngineHooks({ onDiagnostic });
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
 		variables(),
@@ -3172,18 +3211,18 @@ async function createEngine(config = {}) {
 		plugins
 	};
 	log.debug(`Total plugins resolved: ${plugins.length}`);
-	config = await hooks.configureRawConfig(config.plugins, config);
-	hooks.rawConfigConfigured(resolvePlugins(config.plugins), config);
+	config = await pluginHooks.configureRawConfig(config.plugins, config);
+	pluginHooks.rawConfigConfigured(resolvePlugins(config.plugins), config);
 	let resolvedConfig = await resolveEngineConfig(config);
 	log.debug("Engine config resolved with prefix:", resolvedConfig.prefix);
-	resolvedConfig = await hooks.configureResolvedConfig(resolvedConfig.plugins, resolvedConfig);
-	let engine = new Engine(resolvedConfig);
+	resolvedConfig = await pluginHooks.configureResolvedConfig(resolvedConfig.plugins, resolvedConfig);
+	let engine = new Engine(resolvedConfig, hostOnDiagnostic, pluginHooks);
 	engine.appendAutocomplete({
 		extraProperties: "__layer",
 		properties: { __layer: "Autocomplete['Layer']" }
 	});
 	log.debug("Engine instance created");
-	engine = await hooks.configureEngine(engine.config.plugins, engine);
+	engine = await pluginHooks.configureEngine(engine.config.plugins, engine);
 	log.debug("Engine initialized successfully");
 	return engine;
 }
@@ -3202,8 +3241,10 @@ async function createEngine(config = {}) {
 var Engine = class {
 	/** The fully resolved engine configuration. */
 	config;
-	/** Reference to the plugin hook dispatcher for invoking lifecycle hooks. */
-	pluginHooks = hooks;
+	/** Instance-scoped diagnostic handler supplied by the host. */
+	onDiagnostic;
+	/** Reference to the instance-scoped plugin hook dispatcher. */
+	pluginHooks;
 	/** 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. */
@@ -3226,16 +3267,27 @@ var Engine = class {
 	* const engine = new Engine(resolvedConfig)
 	* ```
 	*/
-	constructor(config) {
+	constructor(config, onDiagnostic = noopDiagnosticHandler, pluginHooks) {
+		const safeOnDiagnostic = (diagnostic) => emitDiagnostic(onDiagnostic, diagnostic);
 		this.config = config;
+		this.onDiagnostic = safeOnDiagnostic;
+		this.pluginHooks = pluginHooks ?? createEngineHooks({ onDiagnostic: safeOnDiagnostic });
 		this.extract = createExtractFn({
 			defaultSelector: this.config.defaultSelector,
-			transformSelectors: (selectors) => hooks.transformSelectors(this.config.plugins, selectors),
-			transformStyleItems: (styleItems) => hooks.transformStyleItems(this.config.plugins, styleItems),
-			transformStyleDefinitions: (styleDefinitions) => hooks.transformStyleDefinitions(this.config.plugins, styleDefinitions)
+			transformSelectors: (selectors) => this.pluginHooks.transformSelectors(this.config.plugins, selectors),
+			transformStyleItems: (styleItems) => this.pluginHooks.transformStyleItems(this.config.plugins, styleItems),
+			transformStyleDefinitions: (styleDefinitions) => this.pluginHooks.transformStyleDefinitions(this.config.plugins, styleDefinitions)
 		});
 	}
 	/**
+	* Reports a structured diagnostic to this engine instance's host handler.
+	*
+	* @param diagnostic - The structured warning or error to deliver.
+	*/
+	reportDiagnostic(diagnostic) {
+		emitDiagnostic(this.onDiagnostic, diagnostic);
+	}
+	/**
 	* Invokes a preflight function, memoizing the result in the given render-pass context.
 	*
 	* @param fn - The preflight function to invoke.
@@ -3286,7 +3338,7 @@ var Engine = class {
 	* ```
 	*/
 	notifyPreflightUpdated() {
-		hooks.preflightUpdated(this.config.plugins);
+		this.pluginHooks.preflightUpdated(this.config.plugins);
 	}
 	/**
 	* Fires the `atomicStyleAdded` hook to notify plugins that a new atomic style was registered.
@@ -3301,7 +3353,7 @@ var Engine = class {
 	* ```
 	*/
 	notifyAtomicStyleAdded(atomicStyle) {
-		hooks.atomicStyleAdded(this.config.plugins, atomicStyle);
+		this.pluginHooks.atomicStyleAdded(this.config.plugins, atomicStyle);
 	}
 	/**
 	* Fires the `autocompleteConfigUpdated` hook to notify plugins that autocomplete entries changed.
@@ -3315,7 +3367,7 @@ var Engine = class {
 	* ```
 	*/
 	notifyAutocompleteConfigUpdated() {
-		hooks.autocompleteConfigUpdated(this.config.plugins);
+		this.pluginHooks.autocompleteConfigUpdated(this.config.plugins);
 	}
 	/**
 	* Merges an autocomplete contribution into the resolved autocomplete config.
@@ -3385,7 +3437,7 @@ var Engine = class {
 		log.debug(`Processing ${itemList.length} style items`);
 		const { unknown, contents } = await resolveStyleItemList({
 			itemList,
-			transformStyleItems: (styleItems) => hooks.transformStyleItems(this.config.plugins, styleItems),
+			transformStyleItems: (styleItems) => this.pluginHooks.transformStyleItems(this.config.plugins, styleItems),
 			extractStyleDefinition: (styleDefinition) => this.extract(styleDefinition)
 		});
 		const resolvedIds = [];
@@ -3484,6 +3536,7 @@ var Engine = class {
 		const { atomicStyleIds = null, isPreview = false } = 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})`);
+		reportUnknownAtomicStyleLayers(this, atomicStyles);
 		return renderAtomicStyles({
 			atomicStyles,
 			isPreview,
@@ -3601,6 +3654,20 @@ function splitLayerSelector(selector) {
 function prependLayerSelector(selector, layer) {
 	return [`${LAYER_SELECTOR_PREFIX}${layer}`, ...selector];
 }
+function reportUnknownAtomicStyleLayers(engine, styles) {
+	const knownLayers = new Set(Object.keys(engine.config.layers));
+	const reportedLayers = /* @__PURE__ */ new Set();
+	for (const style of styles) {
+		const { layer } = splitLayerSelector(style.content.selector);
+		if (layer == null || knownLayers.has(layer) || reportedLayers.has(layer)) continue;
+		reportedLayers.add(layer);
+		engine.reportDiagnostic({
+			level: "warning",
+			code: "atomic-style-unknown-layer",
+			message: `Unknown layer "${layer}" encountered in atomic style; falling back to unlayered output.`
+		});
+	}
+}
 function groupAtomicStylesByLayer({ styles, layerOrder, defaultUtilitiesLayer }) {
 	const unlayeredStyles = [];
 	const layerGroups = new Map(layerOrder.map((name) => [name, []]));
@@ -3613,7 +3680,6 @@ function groupAtomicStylesByLayer({ styles, layerOrder, defaultUtilitiesLayer })
 			continue;
 		}
 		if (layer != null) {
-			log.warn(`Unknown layer "${layer}" encountered in atomic style; falling back to unlayered output.`);
 			unlayeredStyles.push(style);
 			continue;
 		}
@@ -3859,7 +3925,7 @@ function renderAtomicStyles(payload) {
 * @param options.blocks - Optional accumulator map reused during recursive descent.
 * @returns The accumulated `CSSStyleBlocks` map.
 *
-* @remarks Each key in the definition is either a CSS property (when its value is a property value) or a nested selector scope (when its value is an object). Selector keys are expanded through `hooks.transformSelectors`. The resulting blocks map is consumable by `renderCSSStyleBlocks`.
+* @remarks Each key in the definition is either a CSS property (when its value is a property value) or a nested selector scope (when its value is an object). Selector keys are expanded through the engine-local `pluginHooks.transformSelectors` dispatcher. The resulting blocks map is consumable by `renderCSSStyleBlocks`.
 *
 * @example
 * ```ts
@@ -3870,7 +3936,7 @@ async function _renderPreflightDefinition({ engine, preflightDefinition, blocks
 	for (const [selector, propertiesOrDefinition] of Object.entries(preflightDefinition)) {
 		if (propertiesOrDefinition == null) continue;
 		const selectors = normalizeSelectors({
-			selectors: await hooks.transformSelectors(engine.config.plugins, [selector]),
+			selectors: await engine.pluginHooks.transformSelectors(engine.config.plugins, [selector]),
 			defaultSelector: ""
 		}).filter(Boolean);
 		if (selectors.length === 0) continue;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pikacss/core",
   "type": "module",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "homepage": "https://pikacss.github.io",
@@ -36,9 +36,6 @@
   "files": [
     "dist"
   ],
-  "engines": {
-    "node": ">=22"
-  },
   "scripts": {
     "build": "tsdown",
     "build:watch": "tsdown --watch",