@barocss/kit 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -0,0 +1,1259 @@
+/** Arbitrary property class `[prop:value]` (parser sets token.property). */
+export declare const arbitraryPropertyRegistration: UtilityRegistration;
+
+/**
+ * AST cache management
+ */
+export declare class AstCache {
+    private cache;
+    private maxSize;
+    set(key: string, ast: AstNode[]): void;
+    get(key: string): AstNode[] | undefined;
+    has(key: string): boolean;
+    clear(): void;
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+    };
+}
+
+export declare const astCache: AstCache;
+
+export declare type AstNode = {
+    type: "wrap";
+    items: AstNode[];
+    source?: string;
+} | {
+    type: "decl";
+    prop: string;
+    value: string | [string, string][];
+    source?: string;
+} | {
+    type: "at-rule";
+    name: string;
+    params: string;
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "style-rule";
+    selector: string;
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "rule";
+    selector: string;
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "at-root";
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "comment";
+    text: string;
+    source?: string;
+} | {
+    type: "raw";
+    value: string;
+    source?: string;
+};
+
+/**
+ * Converts AST nodes to CSS string
+ * @param ast { AstNode[] } - Array of AST nodes to convert
+ * @param baseSelector { string } - Base selector for nested rules (e.g., ".parent" for ".parent .child")
+ * @param opts { minify?: boolean } - Options for CSS generation
+     * @param _indent { string } - Current indentation level for pretty formatting
+     */
+ export declare function astToCss(ast: AstNode[], baseSelector?: string, opts?: {
+     minify?: boolean;
+     important?: boolean;
+ }, _indent?: string): string;
+
+ export declare function atRoot(nodes: AstNode[], source?: string): AstNode;
+
+ export declare function atRule(name: string, params: string, nodes: AstNode[], source?: string): AstNode;
+
+ /**
+  * The structured input format for BaroCSS engine.
+  * Designed to be easily generated by AI models.
+  */
+ export declare type BaroJsonInput = {
+     /**
+      * The core utility to apply.
+      * Corresponds to the utility class name in Tailwind (e.g., 'bg-red-500', 'p-4').
+      */
+     utility: {
+         /**
+          * The utility prefix.
+          * @example 'bg', 'text', 'p', 'm', 'flex', 'hidden'
+          */
+         name: string;
+         /**
+          * The value of the utility.
+          * Optional for boolean utilities like 'flex', 'hidden'.
+          * @example 'red-500', '4', 'lg', '#123456'
+          */
+         value?: string;
+         /**
+          * Whether the value is an arbitrary value (JIT).
+          * @default false
+          * @example true for 'bg-[#123456]'
+          */
+         arbitrary?: boolean;
+         /**
+          * Whether the value is negative.
+          * @default false
+          * @example true for '-m-4'
+          */
+         negative?: boolean;
+         /**
+          * Opacity modifier for colors.
+          * @example '50' for 'bg-red-500/50'
+          */
+         opacity?: string;
+         /**
+          * Whether the value is a custom property.
+          * @default false
+          * @example true for 'bg-(--my-bg)'
+          */
+         customProperty?: boolean;
+         /**
+          * Whether the utility is marked as important (!).
+          * @default false
+          * @example true for '!bg-red-500'
+          */
+         important?: boolean;
+     };
+     /**
+      * List of variants/modifiers to apply.
+      * Applied from outside to inside (left to right in string format).
+      * @example ['hover', 'focus'] for 'hover:focus:bg-red-500'
+      */
+     variants?: Array<string | BaroVariant>;
+ };
+
+ /**
+  * Detailed configuration for a variant.
+  */
+ export declare type BaroVariant = {
+     /**
+      * The name of the variant.
+      * @example 'hover', 'focus', 'sm', 'data', 'group-hover'
+      */
+     name: string;
+     /**
+      * The value for parameterized variants.
+      * @example 'open' for 'data-[state=open]'
+      */
+     value?: string;
+     /**
+      * Whether the variant is arbitrary.
+      * @default false
+      * @example true for 'min-[320px]'
+      */
+     arbitrary?: boolean;
+ };
+
+ /**
+  * Clear all caches (for context changes or testing)
+  */
+ export declare function clearAllCaches(): void;
+
+ /**
+  * Clear all AST caches (mainly for testing)
+  */
+ export declare function clearAstCache(ctx?: Context): void;
+
+ /**
+  * collectDeclPaths
+  * Collects all paths from AST tree to decl(leaf) (including variant chains).
+  * - Input: AST node array
+  * - Output: decl-to-root path(variant chain) array
+  * - Usage: Used for path extraction for AST optimization/merging in optimizeAst, declPathToAst, etc.
+  *
+  * @param nodes AstNode[] - AST tree
+  * @param path PathNode[] - Recursive use (initial value omitted)
+  * @returns DeclPath[] - Array of paths to decl (variant chains)
+  */
+ export declare function collectDeclPaths(nodes?: AstNode[], path?: PathNode[]): DeclPath[];
+
+ export declare function comment(text: string, source?: string): AstNode;
+
+ export declare function compareKeys(a: RuleKey, b: RuleKey): number;
+
+ export declare interface Config {
+     prefix?: string;
+     cssVarPrefix?: string;
+     /**
+      * Modern dark mode strategy
+      * - 'media': uses @media (prefers-color-scheme: dark)
+      * - 'class': uses .dark selector
+      * - string[]: custom selectors (e.g. ['class', '[data-theme="dark"]'])
+      */
+     darkMode?: 'media' | 'class' | string[];
+     theme?: Theme;
+     presets?: {
+         theme: Theme;
+     }[];
+     /**
+      * Whether to include preflight CSS
+      * - 'minimal': Minimal preflight CSS
+      * - 'standard': Standard preflight CSS
+      * - 'full': Full preflight CSS
+      * - true: Full preflight CSS (default)
+      * - false: No preflight CSS
+      *
+      * default: true (full preflight)
+      */
+     preflight?: PreflightLevel;
+     /**
+      * Enable kit console diagnostics (off by default).
+      * This sets a process-wide flag (see setDebug): it affects every context, and a
+      * config without this key leaves the current flag unchanged.
+      */
+     debug?: boolean;
+     /**
+      * @deprecated Contexts now own their caches. Creating a context does not
+      * clear caches that belong to another context.
+      */
+     clearCacheOnContextChange?: boolean;
+     /**
+      * #287: static custom utilities, the runtime mirror of a stylesheet's static `@utility name { ... }`.
+      * Name → declarations (property → value; CSS custom properties allowed). Each one is registered on
+      * this context only; variants and `!` apply as usual. A name equal to a built-in extends it like
+      * `@utility` in Tailwind 4: the built-in declarations are emitted first, then the custom ones (a later
+      * duplicate property wins). An entry with an invalid name, property or value is skipped whole.
+      * @example utilities: { 'max-w-app': { 'max-width': '72rem', 'margin-inline': 'auto' } }
+      */
+     utilities?: CustomUtilities;
+     [key: string]: unknown;
+ }
+
+ export declare function configGetter(config: ContextRecord, ...path: (string | number)[]): unknown;
+
+ export declare interface Context {
+     hasPreset: (category: string, preset: string) => boolean;
+     theme: (...path: (string | number)[]) => unknown;
+     config: (...path: (string | number)[]) => unknown;
+     themeToCssVars: (prefix?: string) => string;
+     extendTheme: (category: string, values: Record<string, unknown> | Function_2) => void;
+     getPreflightCSS: (level?: PreflightLevel) => string;
+ }
+
+ declare type ContextRecord = Record<string, unknown>;
+
+ export declare function createContext(configObj: Config): Context;
+
+ /** #287: static custom utilities by class name. */
+ export declare type CustomUtilities = Record<string, CustomUtilityDeclarations>;
+
+ /** #287: declarations of one static custom utility (property → value). */
+ export declare type CustomUtilityDeclarations = Record<string, string | number>;
+
+ export declare function decl(prop: string, value: string | [string, string][], source?: string): AstNode;
+
+ export declare type DeclPath = PathNode[];
+
+ /**
+  * declPathToAst
+  * Converts decl-to-root path(variant chain) to actual nested AST.
+  * - Input: DeclPath(variant chain)
+  * - Output: Nested AstNode[]
+  * - Consecutive same variants (same key) are merged, nested in outside→inside order
+  *
+  * @param declPath DeclPath
+  * @returns AstNode[]
+  */
+ export declare function declPathToAst(declPath: DeclPath): AstNode[];
+
+ export declare function deepMerge<T extends Record<string, unknown>>(base: T, override: Partial<T>): T;
+
+ export declare const defaultConfig: Config;
+
+ export declare function escapeClassName(className: string): string;
+
+ /**
+  * Add Tailwind-style spacing inside calc()/min()/max()/clamp():
+  * `calc(100%-2rem)` -> `calc(100% - 2rem)`. Leaves nested non-math functions
+  * (var(--x-y)), unary signs and exponents (1e-3) alone.
+  */
+ export declare function expandThemeFunctions(value: string): string;
+
+ declare type Function_2 = (...args: unknown[]) => unknown;
+
+ export declare function functionalModifier(match: ModifierRegistration['match'], modifySelector: ModifierRegistration['modifySelector'], wrap?: ModifierRegistration['wrap'], options?: Partial<ModifierRegistration>, ctx?: Context): void;
+
+ export declare function functionalUtility(opts: FunctionalUtilityOptions, ctx?: Context): void;
+
+ export declare type FunctionalUtilityExtra = {
+     opacity?: string;
+     /** The theme key that matched, set when it is a colour key (or the utility lists no `colors` namespace). */
+     realThemeValue?: string;
+     /**
+      * #338: the theme namespace that resolved the key and the key itself. On a root shared by colours and another
+      * namespace (`border-*`: colors + borderWidth), a key from the other namespace leaves `realThemeValue` unset so the
+      * colour branch does not claim it; the handler dispatches on `themeNamespace` instead.
+      */
+     themeNamespace?: string;
+     themeKey?: string;
+ };
+
+ export declare type FunctionalUtilityOptions = {
+     /**
+      * The name of the utility
+      *
+      * prefix is automatically added to the name
+      */
+     name: string;
+     /**
+      * The CSS property to set
+      *
+      * css property is automatically added to the prop
+      */
+     prop?: string;
+     /**
+      * The theme key to look up values
+      *
+      * theme key is automatically added to the themeKey
+      *
+      * @example
+      * ```
+      * themeKey: 'colors'
+      * ```
+      */
+     themeKey?: string;
+     /**
+      * The theme keys to look up values
+      *
+      * theme keys are automatically added to the themeKeys
+      *
+      * @example
+      * ```
+      * themeKeys: ['colors', 'spacing']
+      * ```
+      */
+     themeKeys?: string[];
+     /**
+      * Whether to support arbitrary values
+      *
+      * `bg-[#ff0000]`
+      *
+      * @example
+      * ```
+      * supportsArbitrary: true
+      * ```
+      */
+     supportsArbitrary?: boolean;
+     /**
+      * Whether to support fraction values
+      *
+      * `m-4`
+      *
+      * @example
+      * ```
+      * supportsFraction: true
+      * ```
+      */
+     supportsFraction?: boolean;
+     /**
+      * Whether to support custom properties
+      *
+      * `bg-(--my-bg)`
+      *
+      * @example
+      * ```
+      * supportsCustomProperty: true
+      * ```
+      */
+     supportsCustomProperty?: boolean;
+     /**
+      * Whether to support negative values
+      *
+      * `-m-4`
+      *
+      * @example
+      * ```
+      * supportsNegative: true
+      * ```
+      */
+     supportsNegative?: boolean;
+     /**
+      * Whether to support opacity values
+      */
+     supportsOpacity?: boolean;
+     /**
+      * The handler function that processes values
+      *
+      * @example
+      * ```
+      * handle: (value, ctx, token, extra) => {
+      *  return [decl('background-color', value)];
+      * }
+      * ```
+      *
+      * @param value The value to process
+      * @param ctx The context
+      * @param token The parsed utility
+      * @param extra The extra metadata
+      *
+      * @returns {AstNode[] | null | undefined} The AST nodes or null | undefined
+      */
+     handle?: (value: string, ctx: Context, token: ParsedUtility, extra?: FunctionalUtilityExtra) => AstNode[] | null | undefined;
+     /**
+      * The handler function that processes bare values
+      *
+      * @example
+      * ```
+      * handleBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
+      * ```
+      *
+      * @param args The arguments
+      * @param args.value The value to process
+      * @param args.ctx The context
+      * @param args.token The parsed utility
+      * @param args.extra The extra metadata
+      *
+      * @returns {string | null | undefined} The processed value or null | undefined
+      */
+     handleBareValue?: (args: {
+         value: string;
+         ctx: Context;
+         token: ParsedUtility;
+         extra?: FunctionalUtilityExtra;
+     }) => string | null | undefined;
+     /**
+      * The handler function that processes negative bare values
+      *
+      * @example
+      * ```
+      * handleNegativeBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
+      * ```
+      */
+     /**
+      * #261: the utility uses the spacing scale, so a named `theme.spacing` key (`p-gutter`) resolves to
+      * `var(--spacing-<key>)` (negative: `calc(var(--spacing-<key>) * -1)`), as in Tailwind 4. Only tried
+      * after the bare-value handler rejects the value, so built-in keywords keep precedence.
+      */
+     spacingKeys?: boolean;
+     handleNegativeBareValue?: (args: {
+         value: string;
+         ctx: Context;
+         token: ParsedUtility;
+         extra?: FunctionalUtilityExtra;
+     }) => string | null | undefined;
+     /**
+      * The handler function that processes custom property values
+      *
+      *
+      * @example
+      * ```
+      * handleCustomProperty: (value, ctx, token, extra) => [decl('background-color', value)],
+      * ```
+      *
+      * @param args The arguments
+      * @param args.value The value to process
+      * @param args.ctx The context
+      * @param args.token The parsed utility
+      * @param args.extra The extra metadata
+      *
+      * @returns {AstNode[] | null | undefined} The AST nodes or null | undefined
+      */
+     handleCustomProperty?: (value: string, ctx: Context, token: ParsedUtility, extra?: FunctionalUtilityExtra) => AstNode[] | null | undefined;
+     /**
+      * The description of the utility
+      *
+      * @example
+      * ```
+      * description: 'Custom utility description',
+      * ```
+      */
+     description?: string;
+     /**
+      * The category of the utility
+      *
+      * It is used to group utilities in the documentation and styles
+      *
+      *
+      * @example
+      * ```
+      * category: 'background',
+      * ```
+      */
+     category?: string;
+     /**
+      * The priority of the utility
+      *
+      * It is used to sort utilities in the styles
+      *
+      * @example
+      * ```
+      * priority: 10,
+      * ```
+      *
+      * The higher the number, the higher the priority
+      *
+      * @default 0
+      */
+     priority?: number;
+ };
+
+ /**
+  * generateCss
+  * Takes multiple classNames and generates CSS for each, joining them.
+  * - Input: classList(string), Context, options
+  * - Output: string (result of joining multiple CSS blocks)
+  * - Processes internally parseClassToAst → optimizeAst → astToCss in sequence
+  * - Supports options like dedup, minify
+  *
+  * @param classList string (e.g., 'bg-red-500 text-lg hover:bg-blue-500')
+  * @param ctx Context
+  * @param opts { minify?: boolean, dedup?: boolean }
+      * @returns string
+      *
+      * @example
+      *   const css = generateCss('sm:dark:hover:bg-red-500 sm:focus:bg-blue-500', ctx);
+      */
+  export declare function generateCss(classList: string, ctx: Context, opts?: {
+      minify?: boolean;
+      dedup?: boolean;
+  }): string;
+
+  /**
+   * Generates CSS from a list of BaroJsonInput objects.
+   *
+   * @param inputs Array of BaroJsonInput
+   * @param ctx Context
+   * @param opts Options (minify, etc.)
+   * @returns CSS string
+   */
+  export declare function generateCssFromJson(inputs: BaroJsonInput[], ctx: Context, opts?: {
+      minify?: boolean;
+  }): string;
+
+  /**
+   * Returns an array of optimized results for multiple class names with dedup/filter.
+   * - Each object: { cls, ast, css }
+   * - Supports minify, dedup options
+   * - Applies astToCss(cleanAst, cls, opts) per class
+   * @param classList string (space-separated)
+   * @param ctx Context
+   * @param opts { minify?: boolean; dedup?: boolean }
+       * @returns Array<{ cls: string; ast: AstNode[]; css: string }>
+       */
+   export declare function generateCssRules(classList: string, ctx: Context, opts?: {
+       minify?: boolean;
+       dedup?: boolean;
+   }): Array<GenerateCssRulesResult>;
+
+   export declare type GenerateCssRulesResult = {
+       cls: string;
+       ast: AstNode[];
+       css: string;
+       cssList: string[];
+       rootCss: string;
+       rootCssList: string[];
+   };
+
+   /** Read AST cache statistics for one context, or the legacy global cache. */
+   export declare function getAstCacheStats(ctx?: Context): {
+       size: number;
+       maxSize: number;
+       hitRate: number;
+   };
+
+   export declare function getModifier(ctx?: Context): ModifierRegistration[];
+
+   export declare function getPreflightCSS(level?: PreflightLevel): string;
+
+   export declare function getUtility(ctx?: Context): UtilityRegistration[];
+
+   /**
+    * #273: true when an emitted selector or at-rule prelude contains a comment opener or closer outside a CSS escape.
+    * Backslash-escape pairs are skipped, so an escaped `\/` or `\*` from a class name never counts. Used by the
+    * serializer on the final, composed string, where adjacent pieces that were each safe alone can join into one.
+    */
+   export declare function hasCommentDelimiter(text: string): boolean;
+
+   /** #248: a comment opener or closer anywhere in a variant (quoted or not) could leave a comment unclosed in the output. */
+   export declare function hasCommentToken(value: string): boolean;
+
+   /**
+    * #323: true when emitted text contains a markup end-tag opener (less-than then slash). Generated CSS can be
+    * placed inside an HTML style element, where that sequence could end the element early. CSS escapes in the
+    * output never form it, and a lone less-than (range media queries) stays allowed.
+    */
+   export declare function hasHtmlEndTagOpener(text: string): boolean;
+
+   export declare type HasItems = {
+       items?: AstNode[];
+   };
+
+   export declare type HasName = {
+       name?: string;
+   };
+
+   export declare type HasNodes = {
+       nodes?: AstNode[];
+   };
+
+   export declare type HasParams = {
+       params?: string;
+   };
+
+   export declare function hasPreset(themeObj: Theme, category: string, preset: string): boolean;
+
+   export declare type HasProp = {
+       prop?: string;
+   };
+
+   export declare type HasSelector = {
+       selector?: string;
+   };
+
+   export declare type HasSource = {
+       source?: string;
+   };
+
+   export declare type HasText = {
+       text?: string;
+   };
+
+   export declare type HasValue = {
+       value?: string | [string, string][];
+   };
+
+   /**
+    * Incremental parsing system for efficient class processing
+    *
+    * This class provides an optimized approach to CSS class processing by:
+    * - Tracking processed classes to avoid redundant work
+    * - Batching multiple class operations for better performance
+    * - Supporting both synchronous and asynchronous processing modes
+    *
+    * ## Usage Patterns
+    *
+    * ### Universal Usage (Node.js & Browser)
+    * ```typescript
+    * const parser = new IncrementalParser(ctx);
+    *
+    * // Process classes synchronously
+    * const results = parser.processClasses(['bg-blue-500', 'text-lg']);
+    *
+    * // Process single class
+    * const result = parser.processClass('bg-red-500');
+    *
+    * // Get statistics
+    * const stats = parser.getStats();
+    * ```
+    *
+    * ### Browser Integration
+    * ```typescript
+    * const parser = new IncrementalParser(ctx);
+    * const BrowserRuntime = new BrowserRuntime();
+    *
+    * // Process classes and manually inject CSS
+    * const results = parser.processClasses(['bg-blue-500', 'text-lg']);
+    * results.forEach(result => {
+    *   if (result.css) {
+    *     BrowserRuntime.insertRule(result.css);
+    *   }
+    * });
+    *
+    * // Use with ChangeDetector for automatic DOM monitoring
+    * const detector = new ChangeDetector(parser);
+    * detector.observe(document.body, { scan: true });
+    * ```
+    *
+    * ## Architecture
+    *
+    * - **IncrementalParser**: Pure CSS processing (works in Node.js and browser)
+    * - **ChangeDetector**: Browser-only DOM monitoring (uses MutationObserver)
+    * - **BrowserRuntime**: Browser-only CSS injection (uses DOM APIs)
+    */
+   export declare class IncrementalParser {
+       /** Set of class names that have already been processed to avoid duplicates */
+       private processedClasses;
+       /** BAROCSS context for theme and utility resolution */
+       private ctx;
+       /** Maximum number of classes to process in a single batch */
+       private batchSize;
+       /** Debounce delay for batch processing in milliseconds */
+       private debounceMs;
+       /** Set of classes waiting to be processed */
+       private pendingClasses;
+       /** Timer for debounced batch processing */
+       private batchTimer;
+       /**
+        * Create a new IncrementalParser instance
+        *
+        * @param ctx - BAROCSS context for theme and utility resolution
+        */
+       constructor(ctx: Context);
+       /**
+        * Processes a single CSS class and generates its AST and CSS representation
+        *
+        * This method performs the complete pipeline for a single class:
+        * 1. Checks if the class has already been processed
+        * 2. Parses the class name to extract utility information
+        * 3. Generates the Abstract Syntax Tree (AST)
+        * 4. Converts the AST to CSS rules
+        * 5. Marks the class as processed to avoid future duplicates
+        *
+        * @param className - The CSS class name to process (e.g., 'bg-blue-500')
+        * @returns Object containing AST and CSS, or null if processing failed or class was already processed
+        */
+       processClass(className: string): GenerateCssRulesResult | null;
+       /**
+        * Processes multiple CSS classes in batches for optimal performance
+        *
+        * This method handles multiple classes efficiently by:
+        * - Filtering out already processed classes to avoid redundant work
+        * - Processing classes in configurable batch sizes
+        * - Returning comprehensive results for each processed class
+        *
+        * @param classes - Array of CSS class names to process
+        * @returns Array of processing results, each containing className, AST, and CSS
+        */
+       processClasses(classes: string[]): Array<GenerateCssRulesResult>;
+       /**
+        * Adds classes to the pending queue for asynchronous batch processing
+        *
+        * This method is used by the ChangeDetector when new classes are discovered
+        * in the DOM. Classes are queued and processed together to minimize
+        * performance impact from frequent DOM mutations.
+        *
+        * @param classes - Array of CSS class names to queue for processing
+        */
+       addToPending(classes: string[]): void;
+       /**
+        * Schedule batch processing with debouncing
+        *
+        * This method uses setTimeout to debounce rapid class additions
+        * and process them in batches for better performance.
+        */
+       private scheduleBatchProcessing;
+       /**
+        * Process pending classes from the queue
+        *
+        * This method is called by the debounced timer to process
+        * all classes that have been added to the pending queue.
+        */
+       private processPendingClasses;
+       /**
+        * Core method that processes classes and marks them as processed
+        *
+        * This is the common processing logic used by both pending and synchronous
+        * processing methods. It:
+        * 1. Processes the provided classes using the batch processor
+        * 2. Marks classes as processed to prevent duplicates
+        *
+        * @param classes - Array of CSS class names to process
+        */
+       private applyClasses;
+       /**
+        * Returns comprehensive statistics about the incremental parser's state
+        *
+        * This method provides detailed metrics including:
+        * - Number of processed classes
+        * - Number of pending classes
+        * - Cache statistics from AST and CSS caches
+        *
+        * @returns Object containing processing statistics and cache information
+        */
+       getStats(): {
+           processedClasses: number;
+           pendingClasses: number;
+           cacheStats: {
+               ast: {
+                   size: number;
+                   maxSize: number;
+                   hitRate: number;
+               };
+               css: {};
+           };
+       };
+       /**
+        * Clears all processed classes and pending queue
+        *
+        * This method is useful when the theme or configuration changes,
+        * requiring all classes to be reprocessed. It:
+        * - Clears the processed classes set
+        * - Clears the pending classes queue
+        * - Cancels any pending batch processing timer
+        */
+       clearProcessed(): void;
+       /**
+        * Checks if a specific class has been processed
+        *
+        * @param cls - The CSS class name to check
+        * @returns True if the class has been processed, false otherwise
+        */
+       isProcessed(cls: string): boolean;
+       /**
+        * Marks a class as processed to prevent future duplicate processing
+        *
+        * @param cls - The CSS class name to mark as processed
+        */
+       markProcessed(cls: string): void;
+       /**
+        * Forgets that a class was processed, so a later request generates it again
+        * (used when the browser runtime reclaims an unused class's rules, #269).
+        *
+        * @param cls - The CSS class name to forget
+        */
+       unmarkProcessed(cls: string): void;
+       /**
+        * Process classes synchronously and update BrowserRuntime cache
+        * This method is used by ChangeDetector for scan operations
+        */
+       processClassesSync(classes: string[]): void;
+       /**
+        * Returns all currently processed class names
+        *
+        * This method is useful for debugging and monitoring purposes,
+        * providing visibility into which classes have been processed.
+        *
+        * @returns Array of all processed class names
+        */
+       getProcessedClasses(): string[];
+   }
+
+   /**
+    * #332: true when an emitted selector or at-rule prelude has balanced, correctly nested `()`, `[]` and `{}` and
+    * no open quote. CSS escapes (backslash pairs) and quoted strings are skipped, so escaped brackets from a class
+    * name never count. Top-level commas are allowed (selector lists, `:is(a, b)`). Checked on the final composed
+    * string: an unbalanced prelude in concatenated CSS text would swallow the rules that follow it.
+    */
+   export declare function isBalancedPrelude(text: string): boolean;
+
+   export declare function isDebug(): boolean;
+
+   /**
+    * #221: isSafeVariantValue for a whole variant token, except that has-[…]/not-[…] (optionally group-/peer-) may
+    * carry a comma at the top level of their bracket value: those variants wrap the value in `:has()`/`:not()`.
+    * The value itself must still be balanced and free of `{`, `}` and `;`, so it cannot close the pseudo-class.
+    */
+   export declare function isSafeVariantToken(value: string): boolean;
+
+   export declare function isSafeVariantValue(value: string, allowTopLevelComma?: boolean): boolean;
+
+   export declare function isStructureSafeValue(value: string): boolean;
+
+   /**
+    * #224: true when a utility value (or a whole utility token) cannot change the structure of the declaration block it
+    * is pasted into. Rejects, outside quotes: `{`, `}`, `;`, unbalanced or mismatched ()/[], and a quote left open.
+    * Commas are allowed (values are not selector lists), so this is isSafeVariantValue with top-level commas allowed.
+    */
+   /**
+    * #332: a variant token's bracket groups must be well formed. An empty group (`[]`, as in an empty
+    * `has-[]`/`group-has-[]`/`[]` variant) has nothing to select and emits nothing. A token that opens with `[`
+    * is one arbitrary variant: its first group must close at the token's last character, so two adjacent groups
+    * are never read as a single variant whose inner text is unbalanced. CSS escapes and quoted strings are skipped.
+    */
+   export declare function isWellFormedVariantBrackets(value: string): boolean;
+
+   /**
+    * Converts a single BaroJsonInput object into an AST tree.
+    * Bypasses string parsing and directly invokes utility/modifier handlers.
+    *
+    * @param input BaroJsonInput object
+    * @param ctx Context
+    * @returns AstNode[]
+    */
+   export declare function jsonToAst(input: BaroJsonInput, ctx: Context): AstNode[];
+
+   /**
+    * mergeAstTreeList
+    * Takes a list of declPathToAst results (AstNode[][]), merges same at-rule(name, params) etc., and returns the final AST tree.
+    * - Input: AstNode[][] (nested ASTs of multiple decl-to-root paths)
+    * @returns AstNode[]
+    * - Usage: Used in optimizeAst for final AST merging/optimization
+    *
+    * @param astList AstNode[][]
+    * @returns AstNode[]
+    */
+   export declare function mergeAstTreeList(astList: AstNode[][]): AstNode[];
+
+   export declare type ModifierRegistration = {
+       match: (mod: string, context: Context) => boolean;
+       modifySelector?: (params: {
+           selector: string;
+           fullClassName: string;
+           mod: ParsedModifier;
+           context: Context;
+           variantChain?: ParsedModifier[];
+           index?: number;
+       }) => string | ModifierSelector | ModifierSelector[];
+       wrap?: (mod: ParsedModifier, context: Context) => AstNode[];
+       astHandler?: (ast: AstNode[], mod: ParsedModifier, context: Context, variantChain?: ParsedModifier[], index?: number) => AstNode[];
+       sort?: number;
+       description?: string;
+       source?: string;
+       /** Static variant name; lets the parser tell `placeholder-shown:` (variant) from a `placeholder-*` utility (#307). */
+       name?: string;
+   };
+
+   export declare const modifierRegistry: ModifierRegistration[];
+
+   export declare type ModifierSelector = {
+       selector: string;
+       flatten?: boolean;
+       wrappingType?: 'rule' | 'style-rule' | 'at-rule';
+       override?: boolean;
+       source?: string;
+   };
+
+   export declare function normalizeMathSpacing(value: string): string;
+
+   /**
+    * optimizeAst
+    * Merges/organizes AST generated by parseClassToAst into an optimized AST tree based on decl-to-root path.
+    * - Input: AstNode[] (result of parseClassToAst)
+    * - Output: Optimized AST tree (AstNode[])
+    * - Uses collectDeclPaths, declPathToAst, mergeAstTreeList internally
+    * - Reflects all variant wrapping structures (nesting, siblings, merging, etc.)
+    *
+    * @param ast AstNode[]
+    * @returns AstNode[]
+    */
+   export declare function optimizeAst(ast: AstNode[]): AstNode[];
+
+   /**
+    * Parses a class name string into modifiers and utility using tokenization
+    * Supports both directions:
+    * - modifier:utility (traditional CSS)
+    * - utility:modifier (Master CSS style)
+    *
+    * Examples:
+    * - 'group-hover:sm:bg-[red]' → modifier:utility
+    * - 'bg-red-500:hover' → utility:modifier
+    * - 'text-[color:var(--foo)]' → utility only
+    *
+    * @param className e.g. 'group-hover:sm:bg-[red]', 'text-[color:var(--foo)]'
+    * @returns { modifiers, utility }
+        */
+    export declare function parseClassName(className: string, ctx?: Context): {
+        modifiers: ParsedModifier[];
+        utility: ParsedUtility | null;
+    };
+
+    /**
+     * parseClassToAst
+     * Parses className(including variant chain) to generate AST tree.
+     * - Input: className(string), Context
+     * - Output: AstNode[] (multiple roots possible for variant wrapping path)
+     * - Perfectly supports variant wrapping structure (Cartesian product, nesting, siblings, etc.)
+     * - Accumulates wrappers in wrappers and applies them from right to left.
+     * - Can return multiple root asts.
+     *
+     * @param fullClassName string (e.g., 'sm:dark:hover:bg-red-500')
+     * @param ctx Context
+     * @returns AstNode[]
+     *
+     * @example
+     *   const ast = parseClassToAst('sm:dark:hover:bg-red-500', ctx);
+     *   // ast is an AST tree with sm, dark, hover variants nested
+     */
+    export declare function parseClassToAst(fullClassName: string, ctx: Context): AstNode[];
+
+    export declare interface ParsedModifier {
+        type: string;
+        value?: string;
+        negative?: boolean;
+        arbitrary?: boolean;
+        [key: string]: unknown;
+    }
+
+    export declare interface ParsedUtility {
+        category?: string;
+        prefix: string;
+        value?: string;
+        arbitrary?: boolean;
+        customProperty?: boolean;
+        negative?: boolean;
+        opacity?: string;
+        priority?: number;
+        important?: boolean;
+        /** Set for an arbitrary property class (`[prop:value]`); `value` holds the raw value. */
+        property?: string;
+        [key: string]: unknown;
+    }
+
+    /**
+     * Parse result cache management
+     */
+    export declare class ParseResultCache {
+        private cache;
+        private maxSize;
+        set(key: string, result: {
+            modifiers: ParsedModifier[];
+            utility: ParsedUtility | null;
+        }): void;
+        get(key: string): {
+            modifiers: ParsedModifier[];
+            utility: ParsedUtility | null;
+        } | undefined;
+        has(key: string): boolean;
+        clear(): void;
+        getStats(): {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+    }
+
+    export declare const parseResultCache: ParseResultCache;
+
+    /**
+     * decl-to-root path collection function (reused in normalizeAstOrder, etc.)
+     */
+    export declare type PathNode = Partial<AstNode>;
+
+    declare type PreflightLevel = 'minimal' | 'standard' | 'full' | true | false;
+
+    export declare function property(name: string, initialValue?: string, syntax?: string, source?: string): AstNode;
+
+    export declare function raw(value: string, source?: string): AstNode;
+
+    export declare function registerModifier(modifier: ModifierRegistration, ctx?: Context): void;
+
+    export declare function registerUtility(util: UtilityRegistration, ctx?: Context): void;
+
+    export declare function resolveTheme(config: Config): Theme;
+
+    export declare function rootToCss(nodes: AstNode[], opts?: {
+        minify?: boolean;
+    }): string;
+
+    export declare function rule(selector: string, nodes: AstNode[], source?: string): AstNode;
+
+    /**
+     * Tailwind-compatible cascade order for runtime-inserted rules (#254); shared by @barocss/server (#267).
+     *
+     * The runtime discovers classes in DOM order, so without sorting `lg:px-8`
+     * seen before `sm:px-6` would land earlier and lose at >= 1024px. Each rule
+     * gets a sort key derived from its leading `@media` / `@container` preludes:
+     *
+     *   0  base, state media (hover), motion/contrast, unknown
+     *   1  max-* breakpoints        (larger width first)
+     *   2  min-* breakpoints        (smaller width first)
+     *   3  @max-* container queries (larger width first)
+     *   4  @min-* container queries (smaller width first)
+     *   5  orientation, dark (prefers-color-scheme), print, forced-colors
+     *
+     * Nested at-rules (e.g. `sm:dark:`) contribute one key pair per level, so
+     * `sm:` < `sm:dark:` < `md:`. Equal keys keep discovery order.
+     */
+    export declare type RuleKey = number[];
+
+    export declare function ruleSortKey(rule: string): RuleKey;
+
+    /** Internal hook for caches owned by contexts. */
+    export declare function setContextCacheReset(reset: () => void): void;
+
+    export declare function setDebug(enabled: boolean): void;
+
+    /**
+     * staticModifier: A helper that registers a modifier name and an array of CSS selectors directly to the registry
+     *
+     * @example
+     * ```
+     * staticModifier('disabled', ['&:disabled'], { source: 'pseudo' });
+     * ```
+     *
+     * @param name The name of the modifier
+     * @param selectors The selectors of the modifier
+     * @param options The options of the modifier
+     *
+     * @returns {void}
+     */
+    export declare function staticModifier(name: string, selectors: string[], options?: any, ctx?: Context): void;
+
+    /**
+     * staticUtility: A helper that registers a utility name and an array of CSS declaration pairs directly to the registry
+     *
+     * @example
+     * ```
+     *   staticUtility('block', [['display', 'block']]);
+     *   staticUtility('hidden', [['display', 'none']]);
+     *   staticUtility('space-x-px', [
+     *     [
+     *       '& > :not([hidden]) ~ :not([hidden])', // selector
+     *       [
+     *         ['margin-inline-start', '1px'], // [prop, value]
+     *         ['margin-inline-end', '1px'], // [prop, value]
+     *       ],
+     *     ],
+     *   ]);
+     * ```
+     *
+     * @param name The name of the utility
+     * @param decls The declarations of the utility
+     * @param opts The options of the utility
+     *
+     * @returns {void}
+     */
+    export declare function staticUtility(name: string, decls: StaticUtilityValue[], opts?: {
+        description?: string;
+        category?: string;
+        priority?: number;
+    }, ctx?: Context): void;
+
+    declare type StaticUtilityValue = AstNode | [string, string] | [string, [string, string][]] | ((value: string) => AstNode);
+
+    export declare function styleRule(selector: string, nodes: AstNode[], source?: string): AstNode;
+
+    export declare interface Theme {
+        extend?: Theme;
+        [namespace: string]: unknown;
+    }
+
+    export declare type ThemeGetter = (...path: (string | number)[]) => unknown;
+
+    /**
+     * Modern theme getter for BAROCSS
+     *
+     * - Supports category-level (first path segment) function values only.
+     *   - If the category (e.g., 'spacing', 'colors') is a function, it will be executed with the theme getter as argument.
+     *   - This allows dynamic theme extension and plugin-style patterns, e.g.:
+     *     spacing: (theme) => ({ ...theme('spacing'), '72': '18rem' })
+     * - Leaf (property) functions are NOT supported and will be ignored (returns undefined).
+     * - Infinite recursion is prevented: If the exact same path is being resolved recursively (directly or indirectly), undefined is returned for that call.
+     *   - Category-level functions can safely call theme('category.otherKey') for dynamic references.
+     *   - Only true recursion on the same path is blocked.
+     * - All theme lookups (theme('category.key')) will always re-execute the category function if present, ensuring dynamic resolution.
+     *
+     * @param themeObj - The theme object (possibly with category functions)
+     * @param path - Path segments (string or number), or dot-path string (e.g. 'colors.red.500')
+     * @returns The resolved theme value, or undefined if not found or if a leaf function is encountered
+     *
+     * @example
+     *   const theme = {
+     *     spacing: (theme) => ({ 1: '0.25rem', 2: theme('spacing.1') }),
+     *   };
+     *   themeGetter(theme, 'spacing.2'); // '0.25rem'
+     *
+     * @example
+     *   // Infinite recursion is prevented:
+     *   const theme = {
+     *     spacing: (theme) => theme('spacing.1'),
+     *   };
+     *   themeGetter(theme, 'spacing.1'); // undefined
+     */
+    export declare function themeGetter(themeObj: Theme, ...path: (string | number)[]): unknown;
+
+    /** #300: the literal value of `theme.<namespace>.<key>` when it is a string, else null. */
+    export declare function themeKeyValue(ctx: Context, namespace: string, key: string): string | null;
+
+    /** #300: `var(--<varPrefix>-<key>)` when `theme.<namespace>.<key>` exists (the :root var BaroCSS emits for it), else null. */
+    export declare function themeKeyVar(ctx: Context, namespace: string, key: string, varPrefix: string): string | null;
+
+    export declare function themeToCssVars(theme: Theme): string;
+
+    export declare interface Token {
+        value: string;
+        start: number;
+        end: number;
+    }
+
+    /**
+     * Tokenizes a class name string into an array of tokens
+     * Only handles separation by ':' while respecting brackets and parentheses
+     *
+     * Examples:
+     * - 'hover:bg-red-500' → [{ value: 'hover' }, { value: 'bg-red-500' }]
+     * - 'bg-[#ff0000]:hover' → [{ value: 'bg-[#ff0000]' }, { value: 'hover' }]
+     * - 'text-[color:var(--foo)]' → [{ value: 'text-[color:var(--foo)]' }]
+     * - '!bg-[red]' → [{ value: '!bg-[red]' }]
+     */
+    export declare function tokenize(className: string): Token[];
+
+    /** Index after the last key <= `key` (stable upper bound) in sorted `keys`. */
+    export declare function upperBound(keys: RuleKey[], key: RuleKey): number;
+
+    /**
+     * Utility cache management
+     */
+    export declare class UtilityCache {
+        private cache;
+        private maxSize;
+        set(key: string, value: boolean): void;
+        get(key: string): boolean | undefined;
+        has(key: string): boolean;
+        clear(): void;
+        getStats(): {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+    }
+
+    export declare const utilityCache: UtilityCache;
+
+    export declare interface UtilityRegistration {
+        /**
+         * The name of the utility
+         */
+        name: string;
+        /**
+         * The match function for the utility
+         * @param className The class name of the utility
+         * @returns {boolean} Whether the utility matches the class name
+         */
+        match: (className: string) => boolean;
+        /**
+         * Handler for utility value
+         * @param value Utility value (e.g. 'red-500')
+         * @param ctx Context
+         * @param token Parsed token
+         * @param options Registration options
+         */
+        handler: (value: string, ctx: Context, token: ParsedUtility, options: UtilityRegistration) => AstNode[] | null | undefined;
+        /**
+         * The description of the utility
+         * @example
+         * ```
+         * description: 'Custom utility description',
+         * ```
+         */
+        description?: string;
+        /**
+         * The category of the utility
+         * @example
+         * ```
+         * category: 'background',
+         * ```
+         */
+        category?: string;
+        /**
+         * The priority of the utility
+         * @example
+         * ```
+         * priority: 10,
+         * ```
+         */
+        priority?: number;
+        [key: string]: unknown;
+    }
+
+    /**
+     * WeakMap-based cache for memory optimization
+     */
+    export declare class WeakCache<T> {
+        private cache;
+        private keyMap;
+        private maxSize;
+        set(key: string, value: T): void;
+        get(key: string): T | undefined;
+        has(key: string): boolean;
+        clear(): void;
+        getStats(): {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+    }
+
+    export { }