/**
 * Main CSS parser for resolving Tailwind v4 theme variables
 * Entry point for parsing CSS files and building theme objects
 */
import type { ParseOptions, ParseResult, Theme } from '../../types';
/**
 * Parses CSS file(s) and resolves Tailwind v4 theme variables
 *
 * This is the main entry point for CSS parsing. It handles:
 * - Reading CSS files or parsing raw CSS strings
 * - Recursively resolving @import statements
 * - Resolving variables from @theme and :root blocks
 * - Building a structured theme object
 *
 * Error Handling:
 * - File not found: Throws error if the specified filePath doesn't exist
 * - Missing imports: Failed @import statements are silently skipped (see resolveImports)
 * - Invalid CSS syntax: PostCSS parsing errors will throw and should be caught by caller
 * - Enable `debug` option to log warnings for import resolution failures
 *
 * @template TTheme - The concrete theme type (e.g., GeneratedTheme from generated types)
 * @param options - Parse options specifying the CSS source and behavior
 * @returns Promise resolving to the parse result with theme, variables, and processed files
 * @throws Error if neither input nor css is provided
 * @throws Error if input is provided but file cannot be read
 * @throws Error if CSS syntax is invalid and cannot be parsed by PostCSS
 *
 * @example
 * ```typescript
 * // Parse from file
 * const result = await parseCSS({
 *   input: './src/theme.css',
 *   resolveImports: true
 * });
 *
 * // Parse from string
 * const result = await parseCSS({
 *   css: '@theme { --color-primary: #3b82f6; }'
 * });
 *
 * // Enable debug mode for troubleshooting
 * const result = await parseCSS({
 *   input: './src/theme.css',
 *   debug: true
 * });
 *
 * // With theme overrides
 * const result = await parseCSS({
 *   input: './src/theme.css',
 *   overrides: {
 *     'dark': { 'colors.background': '#000000' },
 *     '*': { 'fonts.sans': 'Inter, sans-serif' }
 *   }
 * });
 *
 * // With type parameter for full type safety
 * import type { GeneratedTheme } from './generated/tailwindcss';
 *
 * const result = await parseCSS<GeneratedTheme>({
 *   input: './src/theme.css'
 * });
 * ```
 */
export declare function parseCSS<TTheme extends Theme = Theme>(options: ParseOptions): Promise<ParseResult<TTheme>>;