@pikacss/integration 0.0.47 → 0.0.49

package/README.md

@@ -0,0 +1,27 @@
+# @pikacss/integration
+
+Integration layer between the PikaCSS core engine and bundler plugins. Handles config loading, file scanning, source transformation, and code generation.
+
+## Installation
+
+```bash
+pnpm add @pikacss/integration
+```
+
+## Usage
+
+```ts
+import { createCtx } from '@pikacss/integration'
+
+const ctx = createCtx({
+  cwd: process.cwd(),
+})
+```
+
+## Documentation
+
+See the [full documentation](https://pikacss.com/guide/integrations/).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -3,41 +3,127 @@ import { SourceMap } from "magic-string";
 export * from "@pikacss/core";
 
 //#region src/eventHook.d.ts
+/**
+ * Callback function invoked when an event is triggered on an `EventHook`.
+ * @internal
+ *
+ * @typeParam EventPayload - The type of data passed to the listener when the event fires.
+ */
 type EventHookListener<EventPayload> = (payload: EventPayload) => void;
+/**
+ * Lightweight publish-subscribe event hook for internal reactive state notifications.
+ * @internal
+ *
+ * @typeParam EventPayload - The type of data passed to listeners when the event fires.
+ *
+ * @remarks
+ * Used by the integration context to notify build-tool plugins when styles
+ * or TypeScript codegen content have changed and need to be regenerated.
+ */
 interface EventHook<EventPayload> {
+  /** The set of currently registered listener callbacks. */
   listeners: Set<EventHookListener<EventPayload>>;
+  /** Invokes all registered listeners synchronously with the given payload. No-op when the listener set is empty. */
   trigger: (payload: EventPayload) => void;
+  /** Registers a listener and returns an unsubscribe function that removes it. */
   on: (listener: EventHookListener<EventPayload>) => () => void;
+  /** Removes a previously registered listener. No-op if the listener is not registered. */
   off: (listener: EventHookListener<EventPayload>) => void;
 }
+/**
+ * Creates a new event hook instance for publish-subscribe event dispatching.
+ * @internal
+ *
+ * @typeParam EventPayload - The type of data passed to listeners when the event fires.
+ * @returns A new `EventHook` with an empty listener set.
+ *
+ * @remarks
+ * The returned hook can register listeners via `on`, remove them via `off`,
+ * and broadcast payloads to all listeners via `trigger`. Calling `trigger`
+ * with no registered listeners is a no-op.
+ *
+ * @example
+ * ```ts
+ * const hook = createEventHook<string>()
+ * const off = hook.on((msg) => console.log(msg))
+ * hook.trigger('hello') // logs "hello"
+ * off() // unsubscribes
+ * ```
+ */
 declare function createEventHook<EventPayload>(): EventHook<EventPayload>;
 //#endregion
 //#region src/types.d.ts
+/**
+ * Records a single `pika()` call result, pairing the resolved atomic style IDs with the original call arguments.
+ *
+ * @remarks
+ * Each source file may produce multiple `UsageRecord` entries — one per `pika()` call site.
+ * These records drive both CSS output (via `atomicStyleIds`) and IDE preview overloads (via `params`).
+ */
 interface UsageRecord {
+  /** The list of atomic CSS class names generated by the engine for this call. */
   atomicStyleIds: string[];
+  /** The original arguments passed to `engine.use()`, preserved for TypeScript codegen overload generation. */
   params: Parameters<Engine['use']>;
 }
+/**
+ * Classifier and regex utilities for recognizing all `pika()` function call variants in source code.
+ *
+ * @remarks
+ * The function name is configurable via `IntegrationContextOptions.fnName`, so all
+ * variants (`.str`, `.arr`, preview `p` suffix, bracket notation) are derived
+ * dynamically from that base name.
+ */
 interface FnUtils {
+  /** Returns `true` if the given function name is a normal call (output format determined by `transformedFormat`). */
   isNormal: (fnName: string) => boolean;
+  /** Returns `true` if the given function name forces string output (e.g., `pika.str`). */
   isForceString: (fnName: string) => boolean;
+  /** Returns `true` if the given function name forces array output (e.g., `pika.arr`). */
   isForceArray: (fnName: string) => boolean;
+  /** Returns `true` if the given function name is a preview variant (e.g., `pikap`, `pikap.str`). */
   isPreview: (fnName: string) => boolean;
+  /** A compiled global regex that matches all recognized function call variants, including bracket-notation accessors. */
   RE: RegExp;
 }
+/**
+ * Configuration options for creating an integration context.
+ *
+ * @remarks
+ * These options are set by bundler plugin adapters (Vite, webpack, Nuxt) and are
+ * not typically configured by end users directly.
+ */
 interface IntegrationContextOptions {
+  /** The working directory used to resolve relative paths for config files, codegen outputs, and source scanning. */
   cwd: string;
+  /** The npm package name of the integration consumer (e.g., `'@pikacss/unplugin'`), embedded in generated file headers and import paths. */
   currentPackageName: string;
+  /** Glob patterns controlling which source files are scanned for `pika()` calls. `include` specifies files to process; `exclude` specifies files to skip. */
   scan: {
     include: string[];
     exclude: string[];
   };
+  /** The engine configuration object, a path to a config file, or `null`/`undefined` to trigger auto-discovery of `pika.config.*` files. */
   configOrPath: EngineConfig | string | Nullish;
+  /** The base function name to recognize in source code (e.g., `'pika'`). All variants (`.str`, `.arr`, preview) are derived from this name. */
   fnName: string;
+  /** Controls the default output format of normal `pika()` calls: `'string'` produces a space-joined class string, `'array'` produces a string array. */
   transformedFormat: 'string' | 'array';
+  /** Path to the generated TypeScript declaration file (`pika.gen.ts`), or `false` to disable TypeScript codegen entirely. */
   tsCodegen: false | string;
+  /** Path to the generated CSS output file (e.g., `'pika.gen.css'`). */
   cssCodegen: string;
+  /** When `true`, automatically scaffolds a default `pika.config.js` file if no config file is found. */
   autoCreateConfig: boolean;
 }
+/**
+ * Discriminated union representing the outcome of loading an engine configuration file.
+ *
+ * @remarks
+ * Three shapes are possible: an inline config (no file), a successfully loaded file-based
+ * config, or a failed/missing load (all fields `null`). The `file` and `content` fields are
+ * populated only when the config was loaded from disk, enabling hot-reload detection.
+ */
 type LoadedConfigResult = {
   config: EngineConfig;
   file: null;
@@ -51,42 +137,87 @@ type LoadedConfigResult = {
   file: string;
   content: string;
 };
+/**
+ * The main build-tool integration context that bridges the PikaCSS engine with bundler plugins.
+ *
+ * @remarks
+ * Created via `createCtx()`. The context manages the full build lifecycle: config loading,
+ * engine initialization, source file transformation, usage tracking, and output file generation.
+ * All transform and codegen calls automatically await `setup()` completion before proceeding.
+ */
 interface IntegrationContext {
+  /** The current working directory. Can be updated at runtime (e.g., when the project root changes). */
   cwd: string;
+  /** The npm package name of the integration consumer, used in generated file headers and module declarations. */
   currentPackageName: string;
+  /** The base function name recognized in source transforms (e.g., `'pika'`). */
   fnName: string;
+  /** The default output format for normal `pika()` calls: `'string'` or `'array'`. */
   transformedFormat: 'string' | 'array';
+  /** Absolute path to the generated CSS output file, computed from `cwd` and the configured relative path. */
   cssCodegenFilepath: string;
+  /** Absolute path to the generated TypeScript declaration file, or `null` if TypeScript codegen is disabled. */
   tsCodegenFilepath: string | Nullish;
+  /** Whether the `vue` package is installed in the project, used to include Vue-specific type declarations in codegen. */
   hasVue: boolean;
+  /** The loaded engine configuration object, or `null` if loading failed or no config was found. */
   resolvedConfig: EngineConfig | Nullish;
+  /** Absolute path to the resolved config file on disk, or `null` for inline configs or when no config was loaded. */
   resolvedConfigPath: string | Nullish;
+  /** Raw string content of the config file, or `null` for inline configs or when no config was loaded. */
   resolvedConfigContent: string | Nullish;
+  /** Loads (or reloads) the engine configuration from disk or inline source, updating `resolvedConfig`, `resolvedConfigPath`, and `resolvedConfigContent`. */
   loadConfig: () => Promise<LoadedConfigResult>;
+  /** Map from source file ID to the list of `UsageRecord` entries extracted during transforms. Keyed by the file path relative to `cwd`. */
   usages: Map<string, UsageRecord[]>;
+  /** Map from source file ID to preview-only `UsageRecord` entries (from `pikap()` calls). Only these drive TypeScript preview overload generation. */
+  previewUsages: Map<string, UsageRecord[]>;
+  /** Event hooks for notifying plugins when generated outputs need refreshing. `styleUpdated` fires on CSS changes; `tsCodegenUpdated` fires on TypeScript declaration changes. */
   hooks: {
     styleUpdated: ReturnType<typeof createEventHook<void>>;
     tsCodegenUpdated: ReturnType<typeof createEventHook<void>>;
   };
+  /** The initialized PikaCSS engine instance. Throws if accessed before `setup()` completes. */
   engine: Engine;
+  /** Glob patterns for the bundler's transform pipeline, derived from the scan config with codegen files excluded. */
   transformFilter: {
     include: string[];
     exclude: string[];
   };
+  /** Processes a source file by extracting `pika()` calls, resolving them through the engine, and replacing them with computed output. Returns the transformed code and source map, or `null` if no calls were found. */
   transform: (code: string, id: string) => Promise<{
     code: string;
     map: SourceMap;
   } | Nullish>;
+  /** Generates the full CSS output string, including layer declarations, preflights, and all atomic styles collected from transforms. */
   getCssCodegenContent: () => Promise<string | Nullish>;
+  /** Generates the full TypeScript declaration content for `pika.gen.ts`, or `null` if TypeScript codegen is disabled. */
   getTsCodegenContent: () => Promise<string | Nullish>;
+  /** Generates and writes the CSS codegen file to disk at `cssCodegenFilepath`. */
   writeCssCodegenFile: () => Promise<void>;
+  /** Generates and writes the TypeScript codegen file to disk at `tsCodegenFilepath`. No-op if TypeScript codegen is disabled. */
   writeTsCodegenFile: () => Promise<void>;
+  /** Scans all matching source files, collects usages via transform, then writes the CSS codegen file. Used for full rebuilds. */
   fullyCssCodegen: () => Promise<void>;
+  /** The pending setup promise while initialization is in progress, or `null` when idle. Transform calls await this before proceeding. */
   setupPromise: Promise<void> | null;
+  /** Initializes (or reinitializes) the context by clearing state, loading config, creating the engine, and wiring up dev hooks. Returns a promise that resolves when setup is complete. */
   setup: () => Promise<void>;
 }
 //#endregion
 //#region src/ctx.d.ts
+/**
+ * Creates an `IntegrationContext` that wires together config loading, engine initialization, source file transformation, and codegen output.
+ *
+ * @param options - The integration configuration including paths, function name, scan globs, and codegen settings.
+ * @returns A fully constructed `IntegrationContext`. Call `setup()` on the returned context before using transforms.
+ *
+ * @remarks
+ * The context uses reactive signals internally so that computed paths (CSS and TS codegen
+ * file paths) automatically update when `cwd` changes. The `setup()` method must be called
+ * before any transform or codegen operations - transform calls automatically await the
+ * pending setup promise.
+ */
 declare function createCtx(options: IntegrationContextOptions): IntegrationContext;
 //#endregion
 export { FnUtils, IntegrationContext, IntegrationContextOptions, LoadedConfigResult, UsageRecord, createCtx };

package/dist/index.mjs

@@ -7,10 +7,226 @@ import { klona } from "klona";
 import { isPackageExists } from "local-pkg";
 import MagicString from "magic-string";
 import { dirname, isAbsolute, join, relative, resolve } from "pathe";
-
-export * from "@pikacss/core"
-
+export * from "@pikacss/core";
+//#region src/ctx.transform-utils.ts
+const ESCAPE_REPLACE_RE = /[.*+?^${}()|[\]\\/]/g;
+/**
+* Builds classifier functions and a compiled regex for all `pika()` function call variants derived from the given base name.
+* @internal
+*
+* @param fnName - The base function name (e.g., `'pika'`). All variants (`.str`, `.arr`, `p` suffix, bracket notation) are derived from this.
+* @returns An `FnUtils` object with classifier methods and a global regex for matching all call variants.
+*
+* @remarks
+* The generated regex handles bracket-notation property access (e.g., `pika['str']`)
+* in addition to dot notation, and includes word-boundary anchors to avoid false
+* matches within longer identifiers.
+*
+* @example
+* ```ts
+* const fnUtils = createFnUtils('pika')
+* fnUtils.isNormal('pika')         // true
+* fnUtils.isForceString('pika.str') // true
+* fnUtils.RE.test('pika(')         // true
+* ```
+*/
+function createFnUtils(fnName) {
+	const available = {
+		normal: new Set([fnName]),
+		forceString: new Set([
+			`${fnName}.str`,
+			`${fnName}['str']`,
+			`${fnName}["str"]`,
+			`${fnName}[\`str\`]`
+		]),
+		forceArray: new Set([
+			`${fnName}.arr`,
+			`${fnName}['arr']`,
+			`${fnName}["arr"]`,
+			`${fnName}[\`arr\`]`
+		]),
+		normalPreview: new Set([`${fnName}p`]),
+		forceStringPreview: new Set([
+			`${fnName}p.str`,
+			`${fnName}p['str']`,
+			`${fnName}p["str"]`,
+			`${fnName}p[\`str\`]`
+		]),
+		forceArrayPreview: new Set([
+			`${fnName}p.arr`,
+			`${fnName}p['arr']`,
+			`${fnName}p["arr"]`,
+			`${fnName}p[\`arr\`]`
+		])
+	};
+	return {
+		isNormal: (name) => available.normal.has(name) || available.normalPreview.has(name),
+		isForceString: (name) => available.forceString.has(name) || available.forceStringPreview.has(name),
+		isForceArray: (name) => available.forceArray.has(name) || available.forceArrayPreview.has(name),
+		isPreview: (name) => available.normalPreview.has(name) || available.forceStringPreview.has(name) || available.forceArrayPreview.has(name),
+		RE: new RegExp(`\\b(${Object.values(available).flatMap((set) => Array.from(set, (name) => `(${name.replace(ESCAPE_REPLACE_RE, "\\$&")})`)).join("|")})\\(`, "g")
+	};
+}
+/**
+* Finds the index of the closing `}` that terminates a template literal `${...}` expression.
+* @internal
+*
+* @param code - The full source code string to search within.
+* @param start - The index of the opening `{` of the template expression.
+* @returns The index of the matching closing `}`, or `-1` if the expression is malformed or unterminated.
+*
+* @remarks
+* Tracks nested braces, string literals (single, double, and backtick), escape sequences,
+* line comments, and block comments. Recursively handles nested template expressions
+* within backtick strings.
+*/
+function findTemplateExpressionEnd(code, start) {
+	let end = start;
+	let depth = 1;
+	let inString = false;
+	let isEscaped = false;
+	while (depth > 0 && end < code.length - 1) {
+		end++;
+		const char = code[end];
+		if (isEscaped) {
+			isEscaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			isEscaped = true;
+			continue;
+		}
+		if (inString !== false) {
+			if (char === inString) inString = false;
+			else if (inString === "`" && char === "$" && code[end + 1] === "{") {
+				if ((end = findTemplateExpressionEnd(code, end + 1)) < 0) return -1;
+			}
+			continue;
+		}
+		if (char === "{") depth++;
+		else if (char === "}") depth--;
+		else if (char === "'" || char === "\"" || char === "`") inString = char;
+		else if (char === "/" && code[end + 1] === "/") {
+			const lineEnd = code.indexOf("\n", end);
+			if (lineEnd === -1) return -1;
+			end = lineEnd;
+		} else if (char === "/" && code[end + 1] === "*") {
+			if ((end = code.indexOf("*/", end + 2) + 1) === 0) return -1;
+		}
+	}
+	return depth === 0 ? end : -1;
+}
+/**
+* Scans source code and returns all `pika()` function call matches found by the provided regex.
+* @internal
+*
+* @param code - The full source code string to scan for function calls.
+* @param fnUtils - An object providing the `RE` regex used to locate function call start positions.
+* @returns An array of `FunctionCallMatch` objects, one per matched call. Malformed calls (unbalanced parentheses) are logged and skipped.
+*
+* @remarks
+* Correctly handles nested parentheses, string literals, template expressions,
+* line comments, and block comments within function arguments. Each match
+* includes the full call snippet for later evaluation.
+*
+* @example
+* ```ts
+* const fnUtils = createFnUtils('pika')
+* const matches = findFunctionCalls(`pika('bg:red', 'c:white')`, fnUtils)
+* // [{ fnName: 'pika', start: 0, end: 25, snippet: "pika('bg:red', 'c:white')" }]
+* ```
+*/
+function findFunctionCalls(code, fnUtils) {
+	const RE = fnUtils.RE;
+	const result = [];
+	let matched = RE.exec(code);
+	while (matched != null) {
+		const fnName = matched[1];
+		const start = matched.index;
+		let end = start + fnName.length;
+		let depth = 1;
+		let inString = false;
+		let isEscaped = false;
+		while (depth > 0 && end < code.length) {
+			end++;
+			const char = code[end];
+			if (isEscaped) {
+				isEscaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				isEscaped = true;
+				continue;
+			}
+			if (inString !== false) {
+				if (char === inString) inString = false;
+				else if (inString === "`" && char === "$" && code[end + 1] === "{") {
+					const templateExpressionEnd = findTemplateExpressionEnd(code, end + 1);
+					if (templateExpressionEnd === -1) {
+						log.warn(`Malformed template literal expression in function call at position ${start}`);
+						break;
+					}
+					end = templateExpressionEnd;
+				}
+				continue;
+			}
+			if (char === "(") depth++;
+			else if (char === ")") depth--;
+			else if (char === "'" || char === "\"" || char === "`") inString = char;
+			else if (char === "/" && code[end + 1] === "/") {
+				const lineEnd = code.indexOf("\n", end);
+				if (lineEnd === -1) {
+					log.warn(`Unclosed function call at position ${start}`);
+					break;
+				}
+				end = lineEnd;
+			} else if (char === "/" && code[end + 1] === "*") {
+				const commentEnd = code.indexOf("*/", end + 2);
+				if (commentEnd === -1) {
+					log.warn(`Unclosed comment in function call at position ${start}`);
+					break;
+				}
+				end = commentEnd + 1;
+			}
+		}
+		if (depth !== 0) {
+			log.warn(`Malformed function call at position ${start}, skipping`);
+			matched = RE.exec(code);
+			continue;
+		}
+		const snippet = code.slice(start, end + 1);
+		result.push({
+			fnName,
+			start,
+			end,
+			snippet
+		});
+		matched = RE.exec(code);
+	}
+	return result;
+}
+//#endregion
 //#region src/eventHook.ts
+/**
+* Creates a new event hook instance for publish-subscribe event dispatching.
+* @internal
+*
+* @typeParam EventPayload - The type of data passed to listeners when the event fires.
+* @returns A new `EventHook` with an empty listener set.
+*
+* @remarks
+* The returned hook can register listeners via `on`, remove them via `off`,
+* and broadcast payloads to all listeners via `trigger`. Calling `trigger`
+* with no registered listeners is a no-op.
+*
+* @example
+* ```ts
+* const hook = createEventHook<string>()
+* const off = hook.on((msg) => console.log(msg))
+* hook.trigger('hello') // logs "hello"
+* off() // unsubscribes
+* ```
+*/
 function createEventHook() {
 	const listeners = /* @__PURE__ */ new Set();
 	function trigger(payload) {
@@ -32,9 +248,9 @@ function createEventHook() {
 		off
 	};
 }
-
 //#endregion
 //#region src/tsCodegen.ts
+const RE_LEADING_INDENT = /^(\s*)/;
 function formatUnionType(parts) {
 	return parts.length > 0 ? parts.join(" | ") : "never";
 }
@@ -42,7 +258,7 @@ function formatUnionStringType(list) {
 	return formatUnionType(list.map((i) => JSON.stringify(i)));
 }
 function formatAutocompleteUnion(literals, patterns) {
-	return formatUnionType([...Array.from(literals, (value) => JSON.stringify(value)), ...patterns == null ? [] : [...patterns]]);
+	return formatUnionType([...Array.from(literals, (value) => JSON.stringify(value)), ...patterns]);
 }
 function formatAutocompleteValueMap(keys, entries, patternEntries, formatValue) {
 	const mergedKeys = new Set(keys);
@@ -54,20 +270,20 @@ function generateAutocomplete(ctx) {
 	const autocomplete = ctx.engine.config.autocomplete;
 	const patterns = autocomplete.patterns ?? {
 		selectors: /* @__PURE__ */ new Set(),
-		styleItemStrings: /* @__PURE__ */ new Set(),
+		shortcuts: /* @__PURE__ */ new Set(),
 		properties: /* @__PURE__ */ new Map(),
 		cssProperties: /* @__PURE__ */ new Map()
 	};
 	const { layers } = ctx.engine.config;
 	const layerNames = sortLayerNames(layers);
 	return [
-		"export type Autocomplete = DefineAutocomplete<{",
+		"export type Autocomplete = {",
 		`  Selector: ${formatAutocompleteUnion(autocomplete.selectors, patterns.selectors)}`,
-		`  StyleItemString: ${formatAutocompleteUnion(autocomplete.styleItemStrings, patterns.styleItemStrings)}`,
+		`  Shortcut: ${formatAutocompleteUnion(autocomplete.shortcuts, patterns.shortcuts)}`,
 		`  PropertyValue: ${formatAutocompleteValueMap(autocomplete.extraProperties, autocomplete.properties, patterns.properties, (values, patterns) => formatUnionType([...values, ...patterns]))}`,
 		`  CSSPropertyValue: ${formatAutocompleteValueMap(autocomplete.extraCssProperties, autocomplete.cssProperties, patterns.cssProperties, (values, patterns) => formatAutocompleteUnion(values, patterns))}`,
 		`  Layer: ${formatUnionStringType(layerNames)}`,
-		"}>",
+		"}",
 		""
 	];
 }
@@ -120,8 +336,8 @@ async function generateOverloadContent(ctx) {
 	log.debug("Generating TypeScript overload content");
 	const paramsLines = [];
 	const fnsLines = [];
-	const usages = [...ctx.usages.values()].flat();
-	log.debug(`Processing ${usages.length} style usages for overload generation`);
+	const usages = [...ctx.previewUsages.values()].flat();
+	log.debug(`Processing ${usages.length} preview usages for overload generation`);
 	for (let i = 0; i < usages.length; i++) {
 		const usage = usages[i];
 		try {
@@ -133,7 +349,7 @@ async function generateOverloadContent(ctx) {
 				...(await ctx.engine.renderAtomicStyles(true, {
 					atomicStyleIds: usage.atomicStyleIds,
 					isPreview: true
-				})).trim().split("\n").map((line) => `   * ‎${line.replace(/^(\s*)/, "$1‎")}`),
+				})).trim().split("\n").map((line) => `   * ‎${line.replace(RE_LEADING_INDENT, "$1‎")}`),
 				"   * ```",
 				"   */",
 				`  fn(...params: [${usage.params.map((_, index) => `p${index}: P${i}_${index}`).join(", ")}]): ReturnType<StyleFn>`
@@ -154,11 +370,24 @@ async function generateOverloadContent(ctx) {
 		...paramsLines
 	];
 }
+/**
+* Generates the full content of the `pika.gen.ts` TypeScript declaration file from the current engine and usage state.
+* @internal
+*
+* @param ctx - The integration context providing engine config, usage records, and codegen settings.
+* @returns The complete TypeScript source string for the generated declaration file.
+*
+* @remarks
+* The output includes module augmentation for `PikaAugment`, autocomplete type literals
+* derived from selectors/shortcuts/properties, style function type overloads (respecting
+* `transformedFormat`), global declarations, optional Vue component property declarations,
+* and per-usage preview overloads with inline CSS previews.
+*/
 async function generateTsCodegenContent(ctx) {
 	log.debug("Generating TypeScript code generation content");
 	const lines = [
 		`// Auto-generated by ${ctx.currentPackageName}`,
-		`import type { CSSProperty, CSSSelector, DefineAutocomplete, Properties, StyleDefinition, StyleItem } from \'${ctx.currentPackageName}\'`,
+		`import type { CSSProperty, CSSSelector, Properties, StyleDefinition, StyleItem } from \'${ctx.currentPackageName}\'`,
 		"",
 		`declare module \'${ctx.currentPackageName}\' {`,
 		"  interface PikaAugment {",
@@ -180,9 +409,9 @@ async function generateTsCodegenContent(ctx) {
 	log.debug("TypeScript code generation content completed");
 	return lines.join("\n");
 }
-
 //#endregion
 //#region src/ctx.ts
+const RE_VALID_CONFIG_EXT = /\.(?:js|cjs|mjs|ts|cts|mts)$/;
 function createConfigScaffoldContent({ currentPackageName, resolvedConfigPath, tsCodegenFilepath }) {
 	const relativeTsCodegenFilepath = tsCodegenFilepath == null ? null : `./${relative(dirname(resolvedConfigPath), tsCodegenFilepath)}`;
 	return [
@@ -222,7 +451,6 @@ function usePaths({ cwd: _cwd, cssCodegen, tsCodegen }) {
 	};
 }
 function useConfig({ cwd, tsCodegenFilepath, currentPackageName, autoCreateConfig, configOrPath, scan }) {
-	const RE_VALID_CONFIG_EXT = /\.(?:js|cjs|mjs|ts|cts|mts)$/;
 	const specificConfigPath = computed(() => {
 		if (typeof configOrPath === "string" && RE_VALID_CONFIG_EXT.test(configOrPath)) return isAbsolute(configOrPath) ? configOrPath : join(cwd(), configOrPath);
 		return null;
@@ -231,7 +459,10 @@ function useConfig({ cwd, tsCodegenFilepath, currentPackageName, autoCreateConfi
 		const _cwd = cwd();
 		const _specificConfigPath = specificConfigPath();
 		if (_specificConfigPath != null && statSync(_specificConfigPath, { throwIfNoEntry: false })?.isFile()) return _specificConfigPath;
-		const stream = globbyStream("**/{pika,pikacss}.config.{js,cjs,mjs,ts,cts,mts}", { ignore: scan.exclude });
+		const stream = globbyStream("**/{pika,pikacss}.config.{js,cjs,mjs,ts,cts,mts}", {
+			cwd: _cwd,
+			ignore: scan.exclude
+		});
 		for await (const entry of stream) return join(_cwd, entry);
 		return null;
 	}
@@ -294,165 +525,20 @@ function useConfig({ cwd, tsCodegenFilepath, currentPackageName, autoCreateConfi
 		loadConfig
 	};
 }
-function useTransform({ cwd, cssCodegenFilepath, tsCodegenFilepath, scan, fnName, usages, engine, transformedFormat, triggerStyleUpdated, triggerTsCodegenUpdated }) {
-	const ESCAPE_REPLACE_RE = /[.*+?^${}()|[\]\\/]/g;
-	function createFnUtils(fnName) {
-		const available = {
-			normal: new Set([fnName]),
-			forceString: new Set([
-				`${fnName}.str`,
-				`${fnName}['str']`,
-				`${fnName}["str"]`,
-				`${fnName}[\`str\`]`
-			]),
-			forceArray: new Set([
-				`${fnName}.arr`,
-				`${fnName}['arr']`,
-				`${fnName}["arr"]`,
-				`${fnName}[\`arr\`]`
-			]),
-			normalPreview: new Set([`${fnName}p`]),
-			forceStringPreview: new Set([
-				`${fnName}p.str`,
-				`${fnName}p['str']`,
-				`${fnName}p["str"]`,
-				`${fnName}p[\`str\`]`
-			]),
-			forceArrayPreview: new Set([
-				`${fnName}p.arr`,
-				`${fnName}p['arr']`,
-				`${fnName}p["arr"]`,
-				`${fnName}p[\`arr\`]`
-			])
-		};
-		return {
-			isNormal: (fnName) => available.normal.has(fnName) || available.normalPreview.has(fnName),
-			isForceString: (fnName) => available.forceString.has(fnName) || available.forceStringPreview.has(fnName),
-			isForceArray: (fnName) => available.forceArray.has(fnName) || available.forceArrayPreview.has(fnName),
-			isPreview: (fnName) => available.normalPreview.has(fnName) || available.forceStringPreview.has(fnName) || available.forceArrayPreview.has(fnName),
-			RE: new RegExp(`\\b(${Object.values(available).flatMap((s) => [...s].map((f) => `(${f.replace(ESCAPE_REPLACE_RE, "\\$&")})`)).join("|")})\\(`, "g")
-		};
-	}
+function useTransform({ cwd, cssCodegenFilepath, tsCodegenFilepath, scan, fnName, usages, previewUsages, engine, transformedFormat, triggerStyleUpdated, triggerTsCodegenUpdated }) {
 	const fnUtils = createFnUtils(fnName);
-	function findTemplateExpressionEnd(code, start) {
-		let end = start;
-		let depth = 1;
-		let inString = false;
-		let isEscaped = false;
-		while (depth > 0 && end < code.length - 1) {
-			end++;
-			const char = code[end];
-			if (isEscaped) {
-				isEscaped = false;
-				continue;
-			}
-			if (char === "\\") {
-				isEscaped = true;
-				continue;
-			}
-			if (inString !== false) {
-				if (char === inString) inString = false;
-				else if (inString === "`" && char === "$" && code[end + 1] === "{") {
-					const nestedExpressionEnd = findTemplateExpressionEnd(code, end + 1);
-					if (nestedExpressionEnd === -1) return -1;
-					end = nestedExpressionEnd;
-				}
-				continue;
-			}
-			if (char === "{") depth++;
-			else if (char === "}") depth--;
-			else if (char === "'" || char === "\"" || char === "`") inString = char;
-			else if (char === "/" && code[end + 1] === "/") {
-				const lineEnd = code.indexOf("\n", end);
-				if (lineEnd === -1) return -1;
-				end = lineEnd;
-			} else if (char === "/" && code[end + 1] === "*") {
-				const commentEnd = code.indexOf("*/", end + 2);
-				if (commentEnd === -1) return -1;
-				end = commentEnd + 1;
-			}
-		}
-		return depth === 0 ? end : -1;
-	}
-	function findFunctionCalls(code) {
-		const RE = fnUtils.RE;
-		const result = [];
-		let matched = RE.exec(code);
-		while (matched != null) {
-			const fnName = matched[1];
-			const start = matched.index;
-			let end = start + fnName.length;
-			let depth = 1;
-			let inString = false;
-			let isEscaped = false;
-			while (depth > 0 && end < code.length) {
-				end++;
-				const char = code[end];
-				if (isEscaped) {
-					isEscaped = false;
-					continue;
-				}
-				if (char === "\\") {
-					isEscaped = true;
-					continue;
-				}
-				if (inString !== false) {
-					if (char === inString) inString = false;
-					else if (inString === "`" && char === "$" && code[end + 1] === "{") {
-						const templateExpressionEnd = findTemplateExpressionEnd(code, end + 1);
-						if (templateExpressionEnd === -1) {
-							log.warn(`Malformed template literal expression in function call at position ${start}`);
-							break;
-						}
-						end = templateExpressionEnd;
-					}
-					continue;
-				}
-				if (char === "(") depth++;
-				else if (char === ")") depth--;
-				else if (char === "'" || char === "\"" || char === "`") inString = char;
-				else if (char === "/" && code[end + 1] === "/") {
-					const lineEnd = code.indexOf("\n", end);
-					if (lineEnd === -1) {
-						log.warn(`Unclosed function call at position ${start}`);
-						break;
-					}
-					end = lineEnd;
-				} else if (char === "/" && code[end + 1] === "*") {
-					const commentEnd = code.indexOf("*/", end + 2);
-					if (commentEnd === -1) {
-						log.warn(`Unclosed comment in function call at position ${start}`);
-						break;
-					}
-					end = commentEnd + 1;
-				}
-			}
-			if (depth !== 0) {
-				log.warn(`Malformed function call at position ${start}, skipping`);
-				matched = RE.exec(code);
-				continue;
-			}
-			const snippet = code.slice(start, end + 1);
-			result.push({
-				fnName,
-				start,
-				end,
-				snippet
-			});
-			matched = RE.exec(code);
-		}
-		return result;
-	}
 	async function transform(code, id) {
 		const _engine = engine();
 		if (_engine == null) return null;
 		try {
 			log.debug(`Transforming file: ${id}`);
 			usages.delete(id);
-			const functionCalls = findFunctionCalls(code);
+			previewUsages.delete(id);
+			const functionCalls = findFunctionCalls(code, fnUtils);
 			if (functionCalls.length === 0) return;
 			log.debug(`Found ${functionCalls.length} style function calls in ${id}`);
 			const usageList = [];
+			const previewUsageList = [];
 			const transformed = new MagicString(code);
 			for (const fnCall of functionCalls) {
 				const argsStr = `[${fnCall.snippet.slice(fnCall.fnName.length + 1, -1)}]`;
@@ -463,6 +549,7 @@ function useTransform({ cwd, cssCodegenFilepath, tsCodegenFilepath, scan, fnName
 					params: args
 				};
 				usageList.push(usage);
+				if (fnUtils.isPreview(fnCall.fnName)) previewUsageList.push(usage);
 				let transformedContent;
 				if (fnUtils.isNormal(fnCall.fnName)) transformedContent = transformedFormat === "array" ? `[${names.map((n) => `'${n}'`).join(", ")}]` : `'${names.join(" ")}'`;
 				else if (fnUtils.isForceString(fnCall.fnName)) transformedContent = `'${names.join(" ")}'`;
@@ -471,6 +558,7 @@ function useTransform({ cwd, cssCodegenFilepath, tsCodegenFilepath, scan, fnName
 				transformed.update(fnCall.start, fnCall.end + 1, transformedContent);
 			}
 			usages.set(id, usageList);
+			if (previewUsageList.length > 0) previewUsages.set(id, previewUsageList);
 			triggerStyleUpdated();
 			triggerTsCodegenUpdated();
 			log.debug(`Transformed ${usageList.length} style usages in ${id}`);
@@ -479,7 +567,7 @@ function useTransform({ cwd, cssCodegenFilepath, tsCodegenFilepath, scan, fnName
 				map: transformed.generateMap({ hires: true })
 			};
 		} catch (error) {
-			log.error(`Failed to transform code (${join(cwd(), id)}): ${error.message}`, error);
+			log.error(`Failed to transform code (${isAbsolute(id) ? id : join(cwd(), id)}): ${error.message}`, error);
 			return;
 		}
 	}
@@ -488,13 +576,25 @@ function useTransform({ cwd, cssCodegenFilepath, tsCodegenFilepath, scan, fnName
 			include: scan.include,
 			exclude: [
 				...scan.exclude,
-				cssCodegenFilepath(),
-				...tsCodegenFilepath() ? [tsCodegenFilepath()] : []
+				relative(cwd(), cssCodegenFilepath()),
+				...tsCodegenFilepath() ? [relative(cwd(), tsCodegenFilepath())] : []
 			]
 		},
 		transform
 	};
 }
+/**
+* Creates an `IntegrationContext` that wires together config loading, engine initialization, source file transformation, and codegen output.
+*
+* @param options - The integration configuration including paths, function name, scan globs, and codegen settings.
+* @returns A fully constructed `IntegrationContext`. Call `setup()` on the returned context before using transforms.
+*
+* @remarks
+* The context uses reactive signals internally so that computed paths (CSS and TS codegen
+* file paths) automatically update when `cwd` changes. The `setup()` method must be called
+* before any transform or codegen operations - transform calls automatically await the
+* pending setup promise.
+*/
 function createCtx(options) {
 	const { cwd, cssCodegenFilepath, tsCodegenFilepath } = usePaths(options);
 	const { resolvedConfig, resolvedConfigPath, resolvedConfigContent, loadConfig } = useConfig({
@@ -503,6 +603,7 @@ function createCtx(options) {
 		tsCodegenFilepath
 	});
 	const usages = /* @__PURE__ */ new Map();
+	const previewUsages = /* @__PURE__ */ new Map();
 	const engine = signal(null);
 	const hooks = {
 		styleUpdated: createEventHook(),
@@ -514,6 +615,7 @@ function createCtx(options) {
 		cssCodegenFilepath,
 		tsCodegenFilepath,
 		usages,
+		previewUsages,
 		engine,
 		triggerStyleUpdated: () => hooks.styleUpdated.trigger(),
 		triggerTsCodegenUpdated: () => hooks.tsCodegenUpdated.trigger()
@@ -548,6 +650,7 @@ function createCtx(options) {
 		},
 		loadConfig,
 		usages,
+		previewUsages,
 		hooks,
 		get engine() {
 			const _engine = engine();
@@ -597,12 +700,16 @@ function createCtx(options) {
 		fullyCssCodegen: async () => {
 			await ctx.setupPromise;
 			log.debug("Starting full CSS code generation scan");
-			const stream = globbyStream(options.scan.include, { ignore: options.scan.exclude });
-			let fileCount = 0;
 			const _cwd = cwd();
+			const stream = globbyStream(options.scan.include, {
+				cwd: _cwd,
+				ignore: options.scan.exclude
+			});
+			let fileCount = 0;
 			for await (const entry of stream) {
-				const code = await readFile(join(_cwd, entry), "utf-8");
-				await ctx.transform(code, entry);
+				const filePath = join(_cwd, entry);
+				const code = await readFile(filePath, "utf-8");
+				await ctx.transform(code, filePath);
 				fileCount++;
 			}
 			log.debug(`Scanned ${fileCount} files for style collection`);
@@ -621,6 +728,7 @@ function createCtx(options) {
 	async function setup() {
 		log.debug("Setting up integration context");
 		usages.clear();
+		previewUsages.clear();
 		hooks.styleUpdated.listeners.clear();
 		hooks.tsCodegenUpdated.listeners.clear();
 		engine(null);
@@ -645,6 +753,5 @@ function createCtx(options) {
 	}
 	return ctx;
 }
-
 //#endregion
-export { createCtx };
+export { createCtx };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@pikacss/integration",
   "type": "module",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
+  "homepage": "https://pikacss.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pikacss/pikacss.git",
+    "url": "git+https://github.com/pikacss/pikacss.git",
     "directory": "packages/integration"
   },
   "bugs": {
@@ -18,6 +19,7 @@
     "css-in-js",
     "atomic-css-in-js-engine"
   ],
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": {
@@ -34,28 +36,27 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
     "alien-signals": "^3.1.2",
-    "globby": "^16.1.1",
+    "globby": "^16.2.0",
     "jiti": "^2.6.1",
     "klona": "^2.0.6",
     "local-pkg": "^1.1.2",
     "magic-string": "^0.30.21",
-    "micromatch": "^4.0.8",
     "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0",
-    "@pikacss/core": "0.0.47"
-  },
-  "devDependencies": {
-    "@types/micromatch": "^4.0.10"
+    "@pikacss/core": "0.0.49"
   },
   "scripts": {
-    "build": "tsdown && pnpm exec publint",
+    "build": "tsdown",
     "build:watch": "tsdown --watch",
     "typecheck": "pnpm typecheck:package && pnpm typecheck:test",
     "typecheck:package": "tsc --project ./tsconfig.package.json --noEmit",
     "typecheck:test": "tsc --project ./tsconfig.tests.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:watch": "vitest --config ./vitest.config.ts"
   }
 }