@styleframe/scanner 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# @styleframe/scanner
+
+## 3.1.0
+
+### Minor Changes
+
+- [#129](https://github.com/styleframe-dev/styleframe/pull/129) [`2610041`](https://github.com/styleframe-dev/styleframe/commit/2610041beb03a8afc8de17af8857b9931f3359b0) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add custom utility syntax support and separate class name generation from CSS escaping
+  - Extract `defaultUtilitySelectorFn` to `@styleframe/core` returning raw class names; add `classNameToCssSelector` for consistent CSS escaping
+  - Add `ScannerUtilitiesConfig` with pluggable `pattern`, `parse`, and `selector` functions for custom utility naming conventions
+  - Thread custom utilities config through extractor, matcher, scanner, and plugin layers
+
+### Patch Changes
+
+- [#133](https://github.com/styleframe-dev/styleframe/pull/133) [`ce62d31`](https://github.com/styleframe-dev/styleframe/commit/ce62d318275deed277d828fdd8d2500c1a9d767f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add unique id and parent-child traversal to token types, validate @ references, and resolve utility sibling keys
+  - Add unique `id` field to Root, Selector, AtRule, Theme, Utility, Modifier, and Variable token types for stable identity tracking
+  - Add `parentId` to track parent-child relationships across the token tree
+  - Add `root._registry` for efficient id-based lookups and tree traversal
+  - Validate `@`-prefixed string references against root-level variables in `parseDeclarationsBlock`, throwing descriptive errors for undefined variables
+  - Add null/undefined guard to `ref()` with clear error messages
+  - Support `@`-prefixed values in utility entries that resolve to sibling keys (e.g., `{ default: "@solid", solid: "solid" }`)
+
+- Updated dependencies [[`295f04e`](https://github.com/styleframe-dev/styleframe/commit/295f04e6fdd011df6437986cc179e17efd8cd1be), [`71009c2`](https://github.com/styleframe-dev/styleframe/commit/71009c2c0a07a0bfd240e70e61020c8b7e923edb), [`2610041`](https://github.com/styleframe-dev/styleframe/commit/2610041beb03a8afc8de17af8857b9931f3359b0), [`7a61df0`](https://github.com/styleframe-dev/styleframe/commit/7a61df083bc534caa9271a1ef4535f7be979d7c2), [`ce62d31`](https://github.com/styleframe-dev/styleframe/commit/ce62d318275deed277d828fdd8d2500c1a9d767f)]:
+  - @styleframe/core@3.1.0
+
+## 3.0.0
+
+### Major Changes
+
+- [#117](https://github.com/styleframe-dev/styleframe/pull/117) [`ffe6764`](https://github.com/styleframe-dev/styleframe/commit/ffe6764a2e6c84d5b3cfdf431bf11f17a3f3f118) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Introduce global Styleframe single-instance architecture. Extension files (`*.styleframe.ts`) now share the same instance created in `styleframe.config.ts` instead of creating independent instances. This is a breaking change that affects how styles are imported and composed across files.
+
+### Patch Changes
+
+- Updated dependencies [[`266f961`](https://github.com/styleframe-dev/styleframe/commit/266f96143e9ffb47e0e6326d0e5e7cc9d974ab83), [`ffe6764`](https://github.com/styleframe-dev/styleframe/commit/ffe6764a2e6c84d5b3cfdf431bf11f17a3f3f118)]:
+  - @styleframe/core@3.0.0

package/dist/index.cjs

@@ -138,8 +138,8 @@
     }
     return segments;
   }
-  function extractUtilityClasses(content) {
-    const matches = content.match(UTILITY_CLASS_PATTERN);
+  function extractUtilityClasses(content, pattern) {
+    const matches = content.match(pattern ?? UTILITY_CLASS_PATTERN);
     return matches ? [...new Set(matches)] : [];
   }
   function generateUtilityClassName(name, value, modifiers = []) {
@@ -153,7 +153,7 @@
   const CLASS_EXPR_PATTERN = /\bclass\s*=\s*\{/g;
   const CLASS_ATTR_PATTERN = /\bclass\s*=\s*["']([^"']+)["']/gi;
   const CLASSNAME_STRING_PATTERN = /\bclassName\s*=\s*["']([^"']+)["']/gi;
-  const SVELTE_CLASS_DIRECTIVE_PATTERN = /\bclass:(_[a-zA-Z][a-zA-Z0-9-:[\]._]*)/g;
+  const SVELTE_CLASS_DIRECTIVE_PATTERN = /\bclass:([^\s={>]+)/g;
   const SINGLE_QUOTE_PATTERN = /'([^'\\]*(?:\\.[^'\\]*)*)'/g;
   const DOUBLE_QUOTE_PATTERN = /"([^"\\]*(?:\\.[^"\\]*)*)"/g;
   const TEMPLATE_LITERAL_PATTERN = /`([^`\\]*(?:\\.[^`\\]*)*)`/g;
@@ -202,51 +202,51 @@
     }
     return results;
   }
-  function extractFromHTML(content) {
+  function extractFromHTML(content, pattern) {
     const classes = [];
     CLASS_ATTR_PATTERN.lastIndex = 0;
     let match;
     while ((match = CLASS_ATTR_PATTERN.exec(content)) !== null) {
       if (match[1]) {
-        classes.push(...extractUtilityClasses(match[1]));
+        classes.push(...extractUtilityClasses(match[1], pattern));
       }
     }
     return classes;
   }
-  function extractFromJSX(content) {
+  function extractFromJSX(content, pattern) {
     const classes = [];
     CLASSNAME_STRING_PATTERN.lastIndex = 0;
     let match;
     while ((match = CLASSNAME_STRING_PATTERN.exec(content)) !== null) {
       if (match[1]) {
-        classes.push(...extractUtilityClasses(match[1]));
+        classes.push(...extractUtilityClasses(match[1], pattern));
       }
     }
     const expressions = extractClassNameExpressions(content);
     for (const expr of expressions) {
-      classes.push(...extractFromStringLiterals(expr));
+      classes.push(...extractFromStringLiterals(expr, pattern));
     }
     return [...new Set(classes)];
   }
-  function extractFromVue(content) {
+  function extractFromVue(content, pattern) {
     const classes = [];
     const templateMatch = content.match(/<template[^>]*>([\s\S]*?)<\/template>/i);
     if (templateMatch?.[1]) {
-      classes.push(...extractFromHTML(templateMatch[1]));
-      classes.push(...extractFromStringLiterals(templateMatch[1]));
+      classes.push(...extractFromHTML(templateMatch[1], pattern));
+      classes.push(...extractFromStringLiterals(templateMatch[1], pattern));
     }
     const scriptMatch = content.match(/<script[^>]*>([\s\S]*?)<\/script>/i);
     if (scriptMatch?.[1]) {
-      classes.push(...extractFromStringLiterals(scriptMatch[1]));
+      classes.push(...extractFromStringLiterals(scriptMatch[1], pattern));
     }
     return [...new Set(classes)];
   }
-  function extractFromSvelte(content) {
+  function extractFromSvelte(content, pattern) {
     const classes = [];
-    classes.push(...extractFromHTML(content));
+    classes.push(...extractFromHTML(content, pattern));
     const expressions = extractClassExpressions(content);
     for (const expr of expressions) {
-      classes.push(...extractFromStringLiterals(expr));
+      classes.push(...extractFromStringLiterals(expr, pattern));
     }
     SVELTE_CLASS_DIRECTIVE_PATTERN.lastIndex = 0;
     let match;
@@ -257,47 +257,47 @@
     }
     const scriptMatch = content.match(/<script[^>]*>([\s\S]*?)<\/script>/i);
     if (scriptMatch?.[1]) {
-      classes.push(...extractFromStringLiterals(scriptMatch[1]));
+      classes.push(...extractFromStringLiterals(scriptMatch[1], pattern));
     }
     return [...new Set(classes)];
   }
-  function extractFromAstro(content) {
+  function extractFromAstro(content, pattern) {
     const classes = [];
-    classes.push(...extractFromHTML(content));
-    classes.push(...extractFromJSX(content));
+    classes.push(...extractFromHTML(content, pattern));
+    classes.push(...extractFromJSX(content, pattern));
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (frontmatterMatch?.[1]) {
-      classes.push(...extractFromStringLiterals(frontmatterMatch[1]));
+      classes.push(...extractFromStringLiterals(frontmatterMatch[1], pattern));
     }
     return [...new Set(classes)];
   }
-  function extractFromStringLiterals(content) {
+  function extractFromStringLiterals(content, pattern) {
     const classes = [];
     let match;
     SINGLE_QUOTE_PATTERN.lastIndex = 0;
     while ((match = SINGLE_QUOTE_PATTERN.exec(content)) !== null) {
       if (match[1]) {
-        classes.push(...extractUtilityClasses(match[1]));
+        classes.push(...extractUtilityClasses(match[1], pattern));
       }
     }
     DOUBLE_QUOTE_PATTERN.lastIndex = 0;
     while ((match = DOUBLE_QUOTE_PATTERN.exec(content)) !== null) {
       if (match[1]) {
-        classes.push(...extractUtilityClasses(match[1]));
+        classes.push(...extractUtilityClasses(match[1], pattern));
       }
     }
     TEMPLATE_LITERAL_PATTERN.lastIndex = 0;
     while ((match = TEMPLATE_LITERAL_PATTERN.exec(content)) !== null) {
       if (match[1]) {
-        classes.push(...extractUtilityClasses(match[1]));
+        classes.push(...extractUtilityClasses(match[1], pattern));
       }
     }
     return classes;
   }
-  function extractFromMDX(content) {
+  function extractFromMDX(content, pattern) {
     const classes = [];
-    classes.push(...extractFromHTML(content));
-    classes.push(...extractFromJSX(content));
+    classes.push(...extractFromHTML(content, pattern));
+    classes.push(...extractFromJSX(content, pattern));
     return [...new Set(classes)];
   }
   const defaultExtractors = {
@@ -323,7 +323,7 @@
     const parts = filePath.split(".");
     return parts[parts.length - 1]?.toLowerCase() ?? "";
   }
-  function extractClasses(content, filePath, customExtractors) {
+  function extractClasses(content, filePath, customExtractors, utilityPattern) {
     const classes = [];
     const extension = getExtension(filePath);
     if (customExtractors) {
@@ -333,12 +333,160 @@
     }
     const defaultExtractor = defaultExtractors[extension];
     if (defaultExtractor) {
-      classes.push(...defaultExtractor(content));
+      classes.push(...defaultExtractor(content, utilityPattern));
     } else {
-      classes.push(...extractFromStringLiterals(content));
+      classes.push(...extractFromStringLiterals(content, utilityPattern));
     }
     return [...new Set(classes)];
   }
+  const Be = ({
+    name: e,
+    value: t,
+    modifiers: r
+  }) => `_${[
+    ...r,
+    e,
+    ...t === "default" ? [] : [t]
+  ].filter(Boolean).join(":")}`;
+  function Ke(e) {
+    return `.${e.replace(/[[\].#()%,:/]/g, "\\$&")}`;
+  }
+  function v(e) {
+    if (e instanceof Buffer)
+      return Buffer.from(e);
+    const t = e.constructor;
+    return new t(
+      e.buffer.slice(0),
+      e.byteOffset,
+      e.byteLength / e.BYTES_PER_ELEMENT || 1
+    );
+  }
+  function ue(e) {
+    if (e = e || {}, e.circular)
+      return le(e);
+    const t = /* @__PURE__ */ new Map();
+    if (t.set(Date, (i) => new Date(i)), t.set(
+      Map,
+      (i, f) => new Map(n(Array.from(i), f))
+    ), t.set(
+      Set,
+      (i, f) => new Set(n(Array.from(i), f))
+    ), e.constructorHandlers)
+      for (const i of e.constructorHandlers)
+        t.set(i[0], i[1]);
+    let r;
+    return e.proto ? o : s;
+    function n(i, f) {
+      const c = Object.keys(i), a = Array.from({ length: c.length });
+      for (let l = 0; l < c.length; l++) {
+        const u = c[l], d = i[u];
+        typeof d != "object" || d === null ? a[u] = d : d.constructor !== Object && (r = t.get(d.constructor)) ? a[u] = r(d, f) : ArrayBuffer.isView(d) ? a[u] = v(d) : a[u] = f(d);
+      }
+      return a;
+    }
+    function s(i) {
+      if (typeof i != "object" || i === null) return i;
+      if (Array.isArray(i)) return n(i, s);
+      if (i.constructor !== Object && (r = t.get(i.constructor)))
+        return r(i, s);
+      const f = {};
+      for (const c in i) {
+        if (Object.hasOwnProperty.call(i, c) === false) continue;
+        const a = i[c];
+        typeof a != "object" || a === null ? f[c] = a : a.constructor !== Object && (r = t.get(a.constructor)) ? f[c] = r(a, s) : ArrayBuffer.isView(a) ? f[c] = v(a) : f[c] = s(a);
+      }
+      return f;
+    }
+    function o(i) {
+      if (typeof i != "object" || i === null) return i;
+      if (Array.isArray(i)) return n(i, o);
+      if (i.constructor !== Object && (r = t.get(i.constructor)))
+        return r(i, o);
+      const f = {};
+      for (const c in i) {
+        const a = i[c];
+        typeof a != "object" || a === null ? f[c] = a : a.constructor !== Object && (r = t.get(a.constructor)) ? f[c] = r(a, o) : ArrayBuffer.isView(a) ? f[c] = v(a) : f[c] = o(a);
+      }
+      return f;
+    }
+  }
+  function le(e) {
+    const t = [], r = [], n = /* @__PURE__ */ new Map();
+    if (n.set(Date, (c) => new Date(c)), n.set(
+      Map,
+      (c, a) => new Map(o(Array.from(c), a))
+    ), n.set(
+      Set,
+      (c, a) => new Set(o(Array.from(c), a))
+    ), e.constructorHandlers)
+      for (const c of e.constructorHandlers)
+        n.set(c[0], c[1]);
+    let s;
+    return e.proto ? f : i;
+    function o(c, a) {
+      const l = Object.keys(c), u = Array.from({ length: l.length });
+      for (let d = 0; d < l.length; d++) {
+        const y = l[d], m = c[y];
+        if (typeof m != "object" || m === null)
+          u[y] = m;
+        else if (m.constructor !== Object && (s = n.get(m.constructor)))
+          u[y] = s(m, a);
+        else if (ArrayBuffer.isView(m))
+          u[y] = v(m);
+        else {
+          const p = t.indexOf(m);
+          p !== -1 ? u[y] = r[p] : u[y] = a(m);
+        }
+      }
+      return u;
+    }
+    function i(c) {
+      if (typeof c != "object" || c === null) return c;
+      if (Array.isArray(c)) return o(c, i);
+      if (c.constructor !== Object && (s = n.get(c.constructor)))
+        return s(c, i);
+      const a = {};
+      t.push(c), r.push(a);
+      for (const l in c) {
+        if (Object.hasOwnProperty.call(c, l) === false) continue;
+        const u = c[l];
+        if (typeof u != "object" || u === null)
+          a[l] = u;
+        else if (u.constructor !== Object && (s = n.get(u.constructor)))
+          a[l] = s(u, i);
+        else if (ArrayBuffer.isView(u))
+          a[l] = v(u);
+        else {
+          const d = t.indexOf(u);
+          d !== -1 ? a[l] = r[d] : a[l] = i(u);
+        }
+      }
+      return t.pop(), r.pop(), a;
+    }
+    function f(c) {
+      if (typeof c != "object" || c === null) return c;
+      if (Array.isArray(c)) return o(c, f);
+      if (c.constructor !== Object && (s = n.get(c.constructor)))
+        return s(c, f);
+      const a = {};
+      t.push(c), r.push(a);
+      for (const l in c) {
+        const u = c[l];
+        if (typeof u != "object" || u === null)
+          a[l] = u;
+        else if (u.constructor !== Object && (s = n.get(u.constructor)))
+          a[l] = s(u, f);
+        else if (ArrayBuffer.isView(u))
+          a[l] = v(u);
+        else {
+          const d = t.indexOf(u);
+          d !== -1 ? a[l] = r[d] : a[l] = f(u);
+        }
+      }
+      return t.pop(), r.pop(), a;
+    }
+  }
+  ue();
   function generateValueKey(value, modifiers) {
     if (modifiers.length === 0) {
       return value;
@@ -353,8 +501,8 @@
     for (const utility of root.utilities) {
       utilityMap.set(utility.name, utility);
       const valueSet = /* @__PURE__ */ new Set();
-      for (const v of utility.values) {
-        valueSet.add(generateValueKey(v.key, v.modifiers));
+      for (const v2 of utility.values) {
+        valueSet.add(generateValueKey(v2.key, v2.modifiers));
       }
       factoryValueSets.set(utility, valueSet);
     }
@@ -391,36 +539,28 @@
     }
     return matches;
   }
-  function generateUtilitySelector(options) {
-    const { name, value, modifiers } = options;
-    const parts = [
-      ...modifiers,
-      name,
-      ...value === "default" ? [] : [value]
-    ].filter(Boolean);
-    return `._${parts.join("\\:").replace(/[[\].#()%,]/g, "\\$&")}`;
-  }
-  function classNameFromUtilityOptions(options) {
-    const { name, value, modifiers } = options;
-    const parts = [
-      ...modifiers,
-      name,
-      ...value === "default" ? [] : [value]
-    ].filter(Boolean);
-    return `_${parts.join(":")}`;
+  function generateUtilitySelector(options, selectorFn) {
+    const className = classNameFromUtilityOptions(options, selectorFn);
+    return Ke(className);
   }
-  function createUtilityFilter(usedClasses) {
+  function classNameFromUtilityOptions(options, selectorFn) {
+    return (selectorFn ?? Be)(options);
+  }
+  function createUtilityFilter(usedClasses, selectorFn) {
     return (utility) => {
-      const className = classNameFromUtilityOptions({
-        name: utility.name,
-        value: utility.value,
-        modifiers: utility.modifiers
-      });
+      const className = classNameFromUtilityOptions(
+        {
+          name: utility.name,
+          value: utility.value,
+          modifiers: utility.modifiers
+        },
+        selectorFn
+      );
       return usedClasses.has(className);
     };
   }
-  function filterUtilities(root, usedClasses) {
-    const filter = createUtilityFilter(usedClasses);
+  function filterUtilities(root, usedClasses, selectorFn) {
+    const filter = createUtilityFilter(usedClasses, selectorFn);
     return root.children.filter((child) => {
       if (child.type !== "utility") {
         return true;
@@ -526,6 +666,8 @@
     const cache = createCache();
     const cwd = config.cwd ?? process.cwd();
     const customExtractors = config.extractors;
+    const utilityPattern = config.utilities?.pattern;
+    const utilityParse = config.utilities?.parse ?? parseUtilityClass;
     async function getFilePaths() {
       return fg(config.content, {
         cwd,
@@ -540,8 +682,13 @@
       if (cached) {
         return cached;
       }
-      const classNames = extractClasses(content, filePath, customExtractors);
-      const parsed = classNames.map(parseUtilityClass).filter((p) => p !== null);
+      const classNames = extractClasses(
+        content,
+        filePath,
+        customExtractors,
+        utilityPattern
+      );
+      const parsed = classNames.map(utilityParse).filter((p) => p !== null);
       const result = {
         path: filePath,
         classes: new Set(classNames),
@@ -552,8 +699,13 @@
       return result;
     }
     function scanContent(content, filePath = "inline") {
-      const classNames = extractClasses(content, filePath, customExtractors);
-      return classNames.map(parseUtilityClass).filter((p) => p !== null);
+      const classNames = extractClasses(
+        content,
+        filePath,
+        customExtractors,
+        utilityPattern
+      );
+      return classNames.map(utilityParse).filter((p) => p !== null);
     }
     async function scan() {
       const filePaths = await getFilePaths();
@@ -619,14 +771,26 @@
       invalidate
     };
   }
-  function quickScan(content, filePath = "inline.html") {
-    const classNames = extractClasses(content, filePath);
-    return classNames.map(parseUtilityClass).filter((p) => p !== null);
-  }
-  function createContentScanner(customExtractors) {
+  function quickScan(content, filePath = "inline.html", utilities) {
+    const parseFn = utilities?.parse ?? parseUtilityClass;
+    const classNames = extractClasses(
+      content,
+      filePath,
+      void 0,
+      utilities?.pattern
+    );
+    return classNames.map(parseFn).filter((p) => p !== null);
+  }
+  function createContentScanner(customExtractors, utilities) {
+    const parseFn = utilities?.parse ?? parseUtilityClass;
     return (content, filePath = "inline") => {
-      const classNames = extractClasses(content, filePath, customExtractors);
-      return classNames.map(parseUtilityClass).filter((p) => p !== null);
+      const classNames = extractClasses(
+        content,
+        filePath,
+        customExtractors,
+        utilities?.pattern
+      );
+      return classNames.map(parseFn).filter((p) => p !== null);
     };
   }
   exports2.ARBITRARY_VALUE_PATTERN = ARBITRARY_VALUE_PATTERN;

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { ModifierFactory } from '@styleframe/core';
 import { Root } from '@styleframe/core';
 import { Utility } from '@styleframe/core';
 import { UtilityFactory } from '@styleframe/core';
+import { UtilitySelectorFn } from '@styleframe/core';
+import { UtilitySelectorOptions } from '@styleframe/core';
 
 /**
  * Pattern to extract the value from an arbitrary value bracket notation.
@@ -24,7 +26,7 @@ export declare interface CacheEntry {
 /**
  * Generate the raw utility class name from options (without CSS escaping).
  */
-export declare function classNameFromUtilityOptions(options: UtilitySelectorOptions): string;
+export declare function classNameFromUtilityOptions(options: UtilitySelectorOptions, selectorFn?: UtilitySelectorFn): string;
 
 /**
  * Create a scanner cache instance.
@@ -55,7 +57,7 @@ export declare function createChangeHandler(callback: (changedFiles: string[]) =
  *
  * Useful for testing or one-off scans.
  */
-export declare function createContentScanner(customExtractors?: Extractor[]): (content: string, filePath?: string) => ParsedUtility[];
+export declare function createContentScanner(customExtractors?: Extractor[], utilities?: ScannerUtilitiesConfig): (content: string, filePath?: string) => ParsedUtility[];
 
 /**
  * Create a scanner instance for detecting utility classes in content files.
@@ -79,9 +81,10 @@ export declare function createScanner(config: ScannerConfig): Scanner;
  * Create a filter function that checks if a utility is in the used set.
  *
  * @param usedClasses Set of used utility class names
+ * @param selectorFn Optional custom selector function
  * @returns Filter function for utilities
  */
-export declare function createUtilityFilter(usedClasses: Set<string>): (utility: Utility) => boolean;
+export declare function createUtilityFilter(usedClasses: Set<string>, selectorFn?: UtilitySelectorFn): (utility: Utility) => boolean;
 
 /**
  * Simple debounce utility
@@ -104,33 +107,34 @@ export declare const DEFAULT_IGNORE_PATTERNS: string[];
  * @param content The file content
  * @param filePath The file path (used to determine extractor)
  * @param customExtractors Optional custom extractors to use in addition to defaults
+ * @param utilityPattern Optional custom regex pattern for utility class extraction
  * @returns Array of unique utility class names found
  */
-export declare function extractClasses(content: string, filePath: string, customExtractors?: Extractor[]): string[];
+export declare function extractClasses(content: string, filePath: string, customExtractors?: Extractor[], utilityPattern?: RegExp): string[];
 
 /**
  * Extract utility classes from Astro content.
  * Handles both HTML-like and JSX-like patterns.
  */
-export declare function extractFromAstro(content: string): string[];
+export declare function extractFromAstro(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from HTML-like content.
  * Handles class="..." attributes.
  */
-export declare function extractFromHTML(content: string): string[];
+export declare function extractFromHTML(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from JSX/TSX content.
  * Handles className="..." and className={...} patterns.
  */
-export declare function extractFromJSX(content: string): string[];
+export declare function extractFromJSX(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from MDX content.
  * Handles both Markdown and JSX patterns.
  */
-export declare function extractFromMDX(content: string): string[];
+export declare function extractFromMDX(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from string literals in JavaScript/TypeScript code.
@@ -140,19 +144,19 @@ export declare function extractFromMDX(content: string): string[];
  * extract the static portions. Dynamic class names cannot be statically analyzed.
  * For full coverage, use explicit string arrays or safelist patterns.
  */
-export declare function extractFromStringLiterals(content: string): string[];
+export declare function extractFromStringLiterals(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from Svelte content.
  * Handles class="...", class:directive={condition}, and class={...} patterns.
  */
-export declare function extractFromSvelte(content: string): string[];
+export declare function extractFromSvelte(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from Vue SFC content.
  * Handles class="...", :class="...", and :class="{...}" patterns.
  */
-export declare function extractFromVue(content: string): string[];
+export declare function extractFromVue(content: string, pattern?: RegExp): string[];
 
 /**
  * Custom extractor function type
@@ -163,9 +167,10 @@ export declare type Extractor = (content: string, filePath: string) => string[];
  * Extract all utility class names from a content string.
  *
  * @param content The content to search
+ * @param pattern Optional custom regex pattern (must use global flag). Defaults to UTILITY_CLASS_PATTERN.
  * @returns Array of unique utility class names found
  */
-export declare function extractUtilityClasses(content: string): string[];
+export declare function extractUtilityClasses(content: string, pattern?: RegExp): string[];
 
 /**
  * Scan result for a single file
@@ -186,9 +191,10 @@ export declare interface FileScanResult {
  *
  * @param root The Styleframe root instance
  * @param usedClasses Set of used utility class names
+ * @param selectorFn Optional custom selector function
  * @returns Array of used children (utilities are filtered, other types pass through)
  */
-export declare function filterUtilities(root: Root, usedClasses: Set<string>): Root["children"];
+export declare function filterUtilities(root: Root, usedClasses: Set<string>, selectorFn?: UtilitySelectorFn): Root["children"];
 
 /**
  * Generate a utility selector string from components.
@@ -204,9 +210,9 @@ export declare function generateUtilityClassName(name: string, value: string, mo
 /**
  * Generate the CSS selector for a utility instance.
  *
- * This mirrors the logic from @styleframe/transpiler/defaults.ts
+ * Derives the selector from the class name by adding a `.` prefix and escaping special characters.
  */
-export declare function generateUtilitySelector(options: UtilitySelectorOptions): string;
+export declare function generateUtilitySelector(options: UtilitySelectorOptions, selectorFn?: UtilitySelectorFn): string;
 
 /**
  * Get matches for arbitrary values.
@@ -292,9 +298,10 @@ export declare function parseUtilityClass(className: string): ParsedUtility | nu
  *
  * @param content Content string to scan
  * @param filePath Optional file path hint for extractor selection
+ * @param utilities Optional custom utility syntax configuration
  * @returns Array of parsed utilities
  */
-export declare function quickScan(content: string, filePath?: string): ParsedUtility[];
+export declare function quickScan(content: string, filePath?: string, utilities?: ScannerUtilitiesConfig): ParsedUtility[];
 
 /**
  * Scanner instance interface
@@ -342,6 +349,21 @@ export declare interface ScannerConfig {
     extractors?: Extractor[];
     /** Base directory for glob resolution (defaults to process.cwd()) */
     cwd?: string;
+    /** Custom utility class syntax configuration */
+    utilities?: ScannerUtilitiesConfig;
+}
+
+/**
+ * Configuration for custom utility class syntax.
+ * All fields are optional — defaults match the `_modifier:property:value` format.
+ */
+export declare interface ScannerUtilitiesConfig {
+    /** Regex pattern to extract utility class candidates from content strings. Must use the global (`g`) flag. */
+    pattern?: RegExp;
+    /** Parse a matched class name into its components (name, value, modifiers) */
+    parse?: UtilityClassParseFn;
+    /** Generate a raw class name from components (inverse of parse) */
+    selector?: UtilitySelectorFn;
 }
 
 /**
@@ -375,6 +397,12 @@ export declare interface ScanResult {
  */
 export declare const UTILITY_CLASS_PATTERN: RegExp;
 
+/**
+ * Function that parses a class name string into its structured components.
+ * Returns null if the string is not a valid utility class.
+ */
+export declare type UtilityClassParseFn = (className: string) => ParsedUtility | null;
+
 /**
  * Filter function for utilities
  */
@@ -394,14 +422,9 @@ export declare interface UtilityMatch {
     exists: boolean;
 }
 
-/**
- * Utility selector generation options
- */
-export declare interface UtilitySelectorOptions {
-    name: string;
-    value: string;
-    modifiers: string[];
-}
+export { UtilitySelectorFn }
+
+export { UtilitySelectorOptions }
 
 /**
  * Callback type for file change events

package/dist/index.js

@@ -136,8 +136,8 @@ function splitByColons(str) {
   }
   return segments;
 }
-function extractUtilityClasses(content) {
-  const matches = content.match(UTILITY_CLASS_PATTERN);
+function extractUtilityClasses(content, pattern) {
+  const matches = content.match(pattern ?? UTILITY_CLASS_PATTERN);
   return matches ? [...new Set(matches)] : [];
 }
 function generateUtilityClassName(name, value, modifiers = []) {
@@ -151,7 +151,7 @@ const CLASSNAME_EXPR_PATTERN = /\bclassName\s*=\s*\{/g;
 const CLASS_EXPR_PATTERN = /\bclass\s*=\s*\{/g;
 const CLASS_ATTR_PATTERN = /\bclass\s*=\s*["']([^"']+)["']/gi;
 const CLASSNAME_STRING_PATTERN = /\bclassName\s*=\s*["']([^"']+)["']/gi;
-const SVELTE_CLASS_DIRECTIVE_PATTERN = /\bclass:(_[a-zA-Z][a-zA-Z0-9-:[\]._]*)/g;
+const SVELTE_CLASS_DIRECTIVE_PATTERN = /\bclass:([^\s={>]+)/g;
 const SINGLE_QUOTE_PATTERN = /'([^'\\]*(?:\\.[^'\\]*)*)'/g;
 const DOUBLE_QUOTE_PATTERN = /"([^"\\]*(?:\\.[^"\\]*)*)"/g;
 const TEMPLATE_LITERAL_PATTERN = /`([^`\\]*(?:\\.[^`\\]*)*)`/g;
@@ -200,51 +200,51 @@ function extractClassExpressions(content) {
   }
   return results;
 }
-function extractFromHTML(content) {
+function extractFromHTML(content, pattern) {
   const classes = [];
   CLASS_ATTR_PATTERN.lastIndex = 0;
   let match;
   while ((match = CLASS_ATTR_PATTERN.exec(content)) !== null) {
     if (match[1]) {
-      classes.push(...extractUtilityClasses(match[1]));
+      classes.push(...extractUtilityClasses(match[1], pattern));
     }
   }
   return classes;
 }
-function extractFromJSX(content) {
+function extractFromJSX(content, pattern) {
   const classes = [];
   CLASSNAME_STRING_PATTERN.lastIndex = 0;
   let match;
   while ((match = CLASSNAME_STRING_PATTERN.exec(content)) !== null) {
     if (match[1]) {
-      classes.push(...extractUtilityClasses(match[1]));
+      classes.push(...extractUtilityClasses(match[1], pattern));
     }
   }
   const expressions = extractClassNameExpressions(content);
   for (const expr of expressions) {
-    classes.push(...extractFromStringLiterals(expr));
+    classes.push(...extractFromStringLiterals(expr, pattern));
   }
   return [...new Set(classes)];
 }
-function extractFromVue(content) {
+function extractFromVue(content, pattern) {
   const classes = [];
   const templateMatch = content.match(/<template[^>]*>([\s\S]*?)<\/template>/i);
   if (templateMatch?.[1]) {
-    classes.push(...extractFromHTML(templateMatch[1]));
-    classes.push(...extractFromStringLiterals(templateMatch[1]));
+    classes.push(...extractFromHTML(templateMatch[1], pattern));
+    classes.push(...extractFromStringLiterals(templateMatch[1], pattern));
   }
   const scriptMatch = content.match(/<script[^>]*>([\s\S]*?)<\/script>/i);
   if (scriptMatch?.[1]) {
-    classes.push(...extractFromStringLiterals(scriptMatch[1]));
+    classes.push(...extractFromStringLiterals(scriptMatch[1], pattern));
   }
   return [...new Set(classes)];
 }
-function extractFromSvelte(content) {
+function extractFromSvelte(content, pattern) {
   const classes = [];
-  classes.push(...extractFromHTML(content));
+  classes.push(...extractFromHTML(content, pattern));
   const expressions = extractClassExpressions(content);
   for (const expr of expressions) {
-    classes.push(...extractFromStringLiterals(expr));
+    classes.push(...extractFromStringLiterals(expr, pattern));
   }
   SVELTE_CLASS_DIRECTIVE_PATTERN.lastIndex = 0;
   let match;
@@ -255,47 +255,47 @@ function extractFromSvelte(content) {
   }
   const scriptMatch = content.match(/<script[^>]*>([\s\S]*?)<\/script>/i);
   if (scriptMatch?.[1]) {
-    classes.push(...extractFromStringLiterals(scriptMatch[1]));
+    classes.push(...extractFromStringLiterals(scriptMatch[1], pattern));
   }
   return [...new Set(classes)];
 }
-function extractFromAstro(content) {
+function extractFromAstro(content, pattern) {
   const classes = [];
-  classes.push(...extractFromHTML(content));
-  classes.push(...extractFromJSX(content));
+  classes.push(...extractFromHTML(content, pattern));
+  classes.push(...extractFromJSX(content, pattern));
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (frontmatterMatch?.[1]) {
-    classes.push(...extractFromStringLiterals(frontmatterMatch[1]));
+    classes.push(...extractFromStringLiterals(frontmatterMatch[1], pattern));
   }
   return [...new Set(classes)];
 }
-function extractFromStringLiterals(content) {
+function extractFromStringLiterals(content, pattern) {
   const classes = [];
   let match;
   SINGLE_QUOTE_PATTERN.lastIndex = 0;
   while ((match = SINGLE_QUOTE_PATTERN.exec(content)) !== null) {
     if (match[1]) {
-      classes.push(...extractUtilityClasses(match[1]));
+      classes.push(...extractUtilityClasses(match[1], pattern));
     }
   }
   DOUBLE_QUOTE_PATTERN.lastIndex = 0;
   while ((match = DOUBLE_QUOTE_PATTERN.exec(content)) !== null) {
     if (match[1]) {
-      classes.push(...extractUtilityClasses(match[1]));
+      classes.push(...extractUtilityClasses(match[1], pattern));
     }
   }
   TEMPLATE_LITERAL_PATTERN.lastIndex = 0;
   while ((match = TEMPLATE_LITERAL_PATTERN.exec(content)) !== null) {
     if (match[1]) {
-      classes.push(...extractUtilityClasses(match[1]));
+      classes.push(...extractUtilityClasses(match[1], pattern));
     }
   }
   return classes;
 }
-function extractFromMDX(content) {
+function extractFromMDX(content, pattern) {
   const classes = [];
-  classes.push(...extractFromHTML(content));
-  classes.push(...extractFromJSX(content));
+  classes.push(...extractFromHTML(content, pattern));
+  classes.push(...extractFromJSX(content, pattern));
   return [...new Set(classes)];
 }
 const defaultExtractors = {
@@ -321,7 +321,7 @@ function getExtension(filePath) {
   const parts = filePath.split(".");
   return parts[parts.length - 1]?.toLowerCase() ?? "";
 }
-function extractClasses(content, filePath, customExtractors) {
+function extractClasses(content, filePath, customExtractors, utilityPattern) {
   const classes = [];
   const extension = getExtension(filePath);
   if (customExtractors) {
@@ -331,12 +331,160 @@ function extractClasses(content, filePath, customExtractors) {
   }
   const defaultExtractor = defaultExtractors[extension];
   if (defaultExtractor) {
-    classes.push(...defaultExtractor(content));
+    classes.push(...defaultExtractor(content, utilityPattern));
   } else {
-    classes.push(...extractFromStringLiterals(content));
+    classes.push(...extractFromStringLiterals(content, utilityPattern));
   }
   return [...new Set(classes)];
 }
+const Be = ({
+  name: e,
+  value: t,
+  modifiers: r
+}) => `_${[
+  ...r,
+  e,
+  ...t === "default" ? [] : [t]
+].filter(Boolean).join(":")}`;
+function Ke(e) {
+  return `.${e.replace(/[[\].#()%,:/]/g, "\\$&")}`;
+}
+function v(e) {
+  if (e instanceof Buffer)
+    return Buffer.from(e);
+  const t = e.constructor;
+  return new t(
+    e.buffer.slice(0),
+    e.byteOffset,
+    e.byteLength / e.BYTES_PER_ELEMENT || 1
+  );
+}
+function ue(e) {
+  if (e = e || {}, e.circular)
+    return le(e);
+  const t = /* @__PURE__ */ new Map();
+  if (t.set(Date, (i) => new Date(i)), t.set(
+    Map,
+    (i, f) => new Map(n(Array.from(i), f))
+  ), t.set(
+    Set,
+    (i, f) => new Set(n(Array.from(i), f))
+  ), e.constructorHandlers)
+    for (const i of e.constructorHandlers)
+      t.set(i[0], i[1]);
+  let r;
+  return e.proto ? o : s;
+  function n(i, f) {
+    const c = Object.keys(i), a = Array.from({ length: c.length });
+    for (let l = 0; l < c.length; l++) {
+      const u = c[l], d = i[u];
+      typeof d != "object" || d === null ? a[u] = d : d.constructor !== Object && (r = t.get(d.constructor)) ? a[u] = r(d, f) : ArrayBuffer.isView(d) ? a[u] = v(d) : a[u] = f(d);
+    }
+    return a;
+  }
+  function s(i) {
+    if (typeof i != "object" || i === null) return i;
+    if (Array.isArray(i)) return n(i, s);
+    if (i.constructor !== Object && (r = t.get(i.constructor)))
+      return r(i, s);
+    const f = {};
+    for (const c in i) {
+      if (Object.hasOwnProperty.call(i, c) === false) continue;
+      const a = i[c];
+      typeof a != "object" || a === null ? f[c] = a : a.constructor !== Object && (r = t.get(a.constructor)) ? f[c] = r(a, s) : ArrayBuffer.isView(a) ? f[c] = v(a) : f[c] = s(a);
+    }
+    return f;
+  }
+  function o(i) {
+    if (typeof i != "object" || i === null) return i;
+    if (Array.isArray(i)) return n(i, o);
+    if (i.constructor !== Object && (r = t.get(i.constructor)))
+      return r(i, o);
+    const f = {};
+    for (const c in i) {
+      const a = i[c];
+      typeof a != "object" || a === null ? f[c] = a : a.constructor !== Object && (r = t.get(a.constructor)) ? f[c] = r(a, o) : ArrayBuffer.isView(a) ? f[c] = v(a) : f[c] = o(a);
+    }
+    return f;
+  }
+}
+function le(e) {
+  const t = [], r = [], n = /* @__PURE__ */ new Map();
+  if (n.set(Date, (c) => new Date(c)), n.set(
+    Map,
+    (c, a) => new Map(o(Array.from(c), a))
+  ), n.set(
+    Set,
+    (c, a) => new Set(o(Array.from(c), a))
+  ), e.constructorHandlers)
+    for (const c of e.constructorHandlers)
+      n.set(c[0], c[1]);
+  let s;
+  return e.proto ? f : i;
+  function o(c, a) {
+    const l = Object.keys(c), u = Array.from({ length: l.length });
+    for (let d = 0; d < l.length; d++) {
+      const y = l[d], m = c[y];
+      if (typeof m != "object" || m === null)
+        u[y] = m;
+      else if (m.constructor !== Object && (s = n.get(m.constructor)))
+        u[y] = s(m, a);
+      else if (ArrayBuffer.isView(m))
+        u[y] = v(m);
+      else {
+        const p = t.indexOf(m);
+        p !== -1 ? u[y] = r[p] : u[y] = a(m);
+      }
+    }
+    return u;
+  }
+  function i(c) {
+    if (typeof c != "object" || c === null) return c;
+    if (Array.isArray(c)) return o(c, i);
+    if (c.constructor !== Object && (s = n.get(c.constructor)))
+      return s(c, i);
+    const a = {};
+    t.push(c), r.push(a);
+    for (const l in c) {
+      if (Object.hasOwnProperty.call(c, l) === false) continue;
+      const u = c[l];
+      if (typeof u != "object" || u === null)
+        a[l] = u;
+      else if (u.constructor !== Object && (s = n.get(u.constructor)))
+        a[l] = s(u, i);
+      else if (ArrayBuffer.isView(u))
+        a[l] = v(u);
+      else {
+        const d = t.indexOf(u);
+        d !== -1 ? a[l] = r[d] : a[l] = i(u);
+      }
+    }
+    return t.pop(), r.pop(), a;
+  }
+  function f(c) {
+    if (typeof c != "object" || c === null) return c;
+    if (Array.isArray(c)) return o(c, f);
+    if (c.constructor !== Object && (s = n.get(c.constructor)))
+      return s(c, f);
+    const a = {};
+    t.push(c), r.push(a);
+    for (const l in c) {
+      const u = c[l];
+      if (typeof u != "object" || u === null)
+        a[l] = u;
+      else if (u.constructor !== Object && (s = n.get(u.constructor)))
+        a[l] = s(u, f);
+      else if (ArrayBuffer.isView(u))
+        a[l] = v(u);
+      else {
+        const d = t.indexOf(u);
+        d !== -1 ? a[l] = r[d] : a[l] = f(u);
+      }
+    }
+    return t.pop(), r.pop(), a;
+  }
+}
+ue();
 function generateValueKey(value, modifiers) {
   if (modifiers.length === 0) {
     return value;
@@ -351,8 +499,8 @@ function matchUtilities(parsed, root) {
   for (const utility of root.utilities) {
     utilityMap.set(utility.name, utility);
     const valueSet = /* @__PURE__ */ new Set();
-    for (const v of utility.values) {
-      valueSet.add(generateValueKey(v.key, v.modifiers));
+    for (const v2 of utility.values) {
+      valueSet.add(generateValueKey(v2.key, v2.modifiers));
     }
     factoryValueSets.set(utility, valueSet);
   }
@@ -389,36 +537,28 @@ function matchUtilities(parsed, root) {
   }
   return matches;
 }
-function generateUtilitySelector(options) {
-  const { name, value, modifiers } = options;
-  const parts = [
-    ...modifiers,
-    name,
-    ...value === "default" ? [] : [value]
-  ].filter(Boolean);
-  return `._${parts.join("\\:").replace(/[[\].#()%,]/g, "\\$&")}`;
-}
-function classNameFromUtilityOptions(options) {
-  const { name, value, modifiers } = options;
-  const parts = [
-    ...modifiers,
-    name,
-    ...value === "default" ? [] : [value]
-  ].filter(Boolean);
-  return `_${parts.join(":")}`;
+function generateUtilitySelector(options, selectorFn) {
+  const className = classNameFromUtilityOptions(options, selectorFn);
+  return Ke(className);
 }
-function createUtilityFilter(usedClasses) {
+function classNameFromUtilityOptions(options, selectorFn) {
+  return (selectorFn ?? Be)(options);
+}
+function createUtilityFilter(usedClasses, selectorFn) {
   return (utility) => {
-    const className = classNameFromUtilityOptions({
-      name: utility.name,
-      value: utility.value,
-      modifiers: utility.modifiers
-    });
+    const className = classNameFromUtilityOptions(
+      {
+        name: utility.name,
+        value: utility.value,
+        modifiers: utility.modifiers
+      },
+      selectorFn
+    );
     return usedClasses.has(className);
   };
 }
-function filterUtilities(root, usedClasses) {
-  const filter = createUtilityFilter(usedClasses);
+function filterUtilities(root, usedClasses, selectorFn) {
+  const filter = createUtilityFilter(usedClasses, selectorFn);
   return root.children.filter((child) => {
     if (child.type !== "utility") {
       return true;
@@ -524,6 +664,8 @@ function createScanner(config) {
   const cache = createCache();
   const cwd = config.cwd ?? process.cwd();
   const customExtractors = config.extractors;
+  const utilityPattern = config.utilities?.pattern;
+  const utilityParse = config.utilities?.parse ?? parseUtilityClass;
   async function getFilePaths() {
     return fg(config.content, {
       cwd,
@@ -538,8 +680,13 @@ function createScanner(config) {
     if (cached) {
       return cached;
     }
-    const classNames = extractClasses(content, filePath, customExtractors);
-    const parsed = classNames.map(parseUtilityClass).filter((p) => p !== null);
+    const classNames = extractClasses(
+      content,
+      filePath,
+      customExtractors,
+      utilityPattern
+    );
+    const parsed = classNames.map(utilityParse).filter((p) => p !== null);
     const result = {
       path: filePath,
       classes: new Set(classNames),
@@ -550,8 +697,13 @@ function createScanner(config) {
     return result;
   }
   function scanContent(content, filePath = "inline") {
-    const classNames = extractClasses(content, filePath, customExtractors);
-    return classNames.map(parseUtilityClass).filter((p) => p !== null);
+    const classNames = extractClasses(
+      content,
+      filePath,
+      customExtractors,
+      utilityPattern
+    );
+    return classNames.map(utilityParse).filter((p) => p !== null);
   }
   async function scan() {
     const filePaths = await getFilePaths();
@@ -617,14 +769,26 @@ function createScanner(config) {
     invalidate
   };
 }
-function quickScan(content, filePath = "inline.html") {
-  const classNames = extractClasses(content, filePath);
-  return classNames.map(parseUtilityClass).filter((p) => p !== null);
-}
-function createContentScanner(customExtractors) {
+function quickScan(content, filePath = "inline.html", utilities) {
+  const parseFn = utilities?.parse ?? parseUtilityClass;
+  const classNames = extractClasses(
+    content,
+    filePath,
+    void 0,
+    utilities?.pattern
+  );
+  return classNames.map(parseFn).filter((p) => p !== null);
+}
+function createContentScanner(customExtractors, utilities) {
+  const parseFn = utilities?.parse ?? parseUtilityClass;
   return (content, filePath = "inline") => {
-    const classNames = extractClasses(content, filePath, customExtractors);
-    return classNames.map(parseUtilityClass).filter((p) => p !== null);
+    const classNames = extractClasses(
+      content,
+      filePath,
+      customExtractors,
+      utilities?.pattern
+    );
+    return classNames.map(parseFn).filter((p) => p !== null);
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@styleframe/scanner",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",
@@ -22,13 +22,13 @@
     "fast-glob": "^3.3.2"
   },
   "peerDependencies": {
-    "@styleframe/core": "^2.5.0",
+    "@styleframe/core": "^3.1.0",
     "@styleframe/license": "^2.0.2"
   },
   "devDependencies": {
-    "@styleframe/config-typescript": "^2",
-    "@styleframe/config-vite": "^2",
-    "@styleframe/core": "^2.5.0",
+    "@styleframe/config-typescript": "^3.0.0",
+    "@styleframe/config-vite": "^3.0.0",
+    "@styleframe/core": "^3.1.0",
     "@styleframe/license": "^2.0.2",
     "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.8.3",