@barocss/kit 0.8.2 → 0.10.0

package/dist/index.d.cts

@@ -289,7 +289,15 @@ export declare type AstNode = {
 
  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 = {
@@ -491,755 +499,746 @@ export declare type AstNode = {
      priority?: number;
  };
 
+ export declare function generateCss(classList: string, ctx: Context, opts?: {
+     minify?: boolean;
+     dedup?: boolean;
+ }): string;
+
  /**
-  * 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
+  * Generates CSS from a list of BaroJsonInput objects.
   *
-  * @param classList string (e.g., 'bg-red-500 text-lg hover:bg-blue-500')
+  * @param inputs Array of BaroJsonInput
   * @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);
+  * @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 generateCss(classList: string, ctx: Context, opts?: {
+  export declare function generateCssRules(classList: string, ctx: Context, opts?: {
       minify?: boolean;
       dedup?: boolean;
-  }): string;
+  }): 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[];
 
   /**
-   * Generates CSS from a list of BaroJsonInput objects.
-   *
-   * @param inputs Array of BaroJsonInput
-   * @param ctx Context
-   * @param opts Options (minify, etc.)
-   * @returns CSS string
+   * #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 generateCssFromJson(inputs: BaroJsonInput[], ctx: Context, opts?: {
-      minify?: boolean;
-  }): string;
+  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;
 
   /**
-   * 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[];
-   };
+   * #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;
 
-   /** 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 type HasItems = {
+      items?: AstNode[];
+  };
 
-   export declare function getModifier(ctx?: Context): ModifierRegistration[];
+  export declare type HasName = {
+      name?: string;
+  };
 
-   export declare function getPreflightCSS(level?: PreflightLevel): string;
+  export declare type HasNodes = {
+      nodes?: AstNode[];
+  };
 
-   export declare function getUtility(ctx?: Context): UtilityRegistration[];
+  export declare type HasParams = {
+      params?: string;
+  };
 
-   /**
-    * #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;
+  export declare function hasPreset(themeObj: Theme, category: string, preset: 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;
+  export declare type HasProp = {
+      prop?: string;
+  };
 
-   /**
-    * #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 HasSelector = {
+      selector?: string;
+  };
 
-   export declare type HasItems = {
-       items?: AstNode[];
-   };
+  export declare type HasSource = {
+      source?: string;
+  };
 
-   export declare type HasName = {
-       name?: string;
-   };
+  export declare type HasText = {
+      text?: string;
+  };
 
-   export declare type HasNodes = {
-       nodes?: AstNode[];
-   };
+  export declare type HasValue = {
+      value?: string | [string, string][];
+  };
 
-   export declare type HasParams = {
-       params?: 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[];
+  }
 
-   export declare function hasPreset(themeObj: Theme, category: string, preset: string): boolean;
+  /**
+   * #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 type HasProp = {
-       prop?: string;
-   };
+  export declare function isDebug(): boolean;
 
-   export declare type HasSelector = {
-       selector?: string;
-   };
+  /**
+   * #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 type HasSource = {
-       source?: string;
-   };
+  export declare function isSafeVariantValue(value: string, allowTopLevelComma?: boolean): boolean;
 
-   export declare type HasText = {
-       text?: string;
-   };
+  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[];
 
-   export declare type HasValue = {
-       value?: string | [string, string][];
+  /**
+   * 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[] | null;
+      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;
    };
 
    /**
-    * 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');
+    * 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.
     *
-    * // 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
+    * @param fullClassName string (e.g., 'sm:dark:hover:bg-red-500')
+    * @param ctx Context
+    * @returns AstNode[]
     *
-    * - **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)
+    * @example
+    *   const ast = parseClassToAst('sm:dark:hover:bg-red-500', ctx);
+    *   // ast is an AST tree with sm, dark, hover variants nested
     */
-   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[];
+   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;
    }
 
    /**
-    * #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.
+    * Parse result cache management
     */
-   export declare function isBalancedPrelude(text: string): boolean;
+   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 function isDebug(): boolean;
+   export declare const parseResultCache: ParseResultCache;
 
    /**
-    * #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.
+    * decl-to-root path collection function (reused in normalizeAstOrder, etc.)
     */
-   export declare function isSafeVariantToken(value: string): boolean;
+   export declare type PathNode = Partial<AstNode>;
 
-   export declare function isSafeVariantValue(value: string, allowTopLevelComma?: boolean): boolean;
+   declare type PreflightLevel = 'minimal' | 'standard' | 'full' | true | false;
 
-   export declare function isStructureSafeValue(value: string): boolean;
+   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;
 
    /**
-    * #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.
+    * 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, negated media (`not-md:` → `@media not (…)`, as Tailwind 4.3.3 orders them, #352),
+    *      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 function isWellFormedVariantBrackets(value: string): boolean;
+   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;
 
    /**
-    * Converts a single BaroJsonInput object into an AST tree.
-    * Bypasses string parsing and directly invokes utility/modifier handlers.
+    * staticModifier: A helper that registers a modifier name and an array of CSS selectors directly to the registry
     *
-    * @param input BaroJsonInput object
-    * @param ctx Context
-    * @returns AstNode[]
+    * @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 jsonToAst(input: BaroJsonInput, ctx: Context): AstNode[];
+   export declare function staticModifier(name: string, selectors: string[], options?: any, ctx?: Context): void;
 
    /**
-    * 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
+    * staticUtility: A helper that registers a utility name and an array of CSS declaration pairs directly to the registry
     *
-    * @param astList AstNode[][]
-    * @returns AstNode[]
+    * @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 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;
+   export declare function staticUtility(name: string, decls: StaticUtilityValue[], opts?: {
        description?: string;
-       source?: string;
-       /** Static variant name; lets the parser tell `placeholder-shown:` (variant) from a `placeholder-*` utility (#307). */
-       name?: string;
-   };
+       category?: string;
+       priority?: number;
+   }, ctx?: Context): void;
 
-   export declare const modifierRegistry: ModifierRegistration[];
+   declare type StaticUtilityValue = AstNode | [string, string] | [string, [string, string][]] | ((value: string) => AstNode);
 
-   export declare type ModifierSelector = {
-       selector: string;
-       flatten?: boolean;
-       wrappingType?: 'rule' | 'style-rule' | 'at-rule';
-       override?: boolean;
-       source?: string;
-   };
+   export declare function styleRule(selector: string, nodes: AstNode[], source?: string): AstNode;
 
-   export declare function normalizeMathSpacing(value: string): string;
+   export declare interface Theme {
+       extend?: Theme;
+       [namespace: string]: unknown;
+   }
 
-   /**
-    * 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[];
+   export declare type ThemeGetter = (...path: (string | number)[]) => unknown;
 
    /**
-    * Parses a class name string into modifiers and utility using tokenization
-    * Supports both directions:
-    * - modifier:utility (traditional CSS)
-    * - utility:modifier (Master CSS style)
+    * Modern theme getter for BAROCSS
     *
-    * Examples:
-    * - 'group-hover:sm:bg-[red]' → modifier:utility
-    * - 'bg-red-500:hover' → utility:modifier
-    * - 'text-[color:var(--foo)]' → utility only
+    * - 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 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>;
+    * @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;
 
-    declare type PreflightLevel = 'minimal' | 'standard' | 'full' | true | false;
+   /** #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;
 
-    export declare function property(name: string, initialValue?: string, syntax?: string, source?: string): AstNode;
+   /** #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 raw(value: string, source?: string): AstNode;
+   export declare function themeToCssVars(theme: Theme): string;
 
-    export declare function registerModifier(modifier: ModifierRegistration, ctx?: Context): void;
+   export declare interface Token {
+       value: string;
+       start: number;
+       end: number;
+   }
 
-    export declare function registerUtility(util: UtilityRegistration, ctx?: Context): void;
+   /**
+    * 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[];
 
-    export declare function resolveTheme(config: Config): Theme;
+   /** Index after the last key <= `key` (stable upper bound) in sorted `keys`. */
+   export declare function upperBound(keys: RuleKey[], key: RuleKey): number;
 
-    export declare function rootToCss(nodes: AstNode[], opts?: {
-        minify?: boolean;
-    }): string;
+   /**
+    * 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 function rule(selector: string, nodes: AstNode[], source?: string): AstNode;
+   export declare const utilityCache: UtilityCache;
 
-    /**
-     * 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;
-
-    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[];
+   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;
+   }
 
-    /** Index after the last key <= `key` (stable upper bound) in sorted `keys`. */
-    export declare function upperBound(keys: RuleKey[], key: RuleKey): number;
+   /**
+    * 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;
+       };
+   }
 
-    /**
-     * 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 { }
+   export { }