@tenphi/tasty 0.6.0 → 0.7.1

package/dist/zero/extractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.js","names":[],"sources":["../../src/zero/extractor.ts"],"sourcesContent":["import { createHash } from 'crypto';\n\nimport {\n  categorizeStyleKeys,\n  generateChunkCacheKey,\n  renderStylesForChunk,\n} from '../chunks';\nimport type { KeyframesSteps } from '../injector/types';\nimport {\n  extractAnimationNamesFromStyles,\n  extractLocalKeyframes,\n  filterUsedKeyframes,\n  hasLocalKeyframes,\n  mergeKeyframes,\n} from '../keyframes';\nimport type { StyleResult } from '../pipeline';\nimport { renderStyles } from '../pipeline';\nimport type { Styles } from '../styles/types';\n\nexport interface ExtractedChunk {\n  className: string;\n  css: string;\n}\n\nexport interface ExtractedSelector {\n  selector: string;\n  css: string;\n}\n\nexport interface ExtractedKeyframes {\n  name: string;\n  css: string;\n}\n\nexport interface KeyframesExtractionResult {\n  /** Keyframes to inject (deduplicated by content) */\n  keyframes: ExtractedKeyframes[];\n  /** Map from original animation name to canonical name (for replacement) */\n  nameMap: Map<string, string>;\n}\n\n/**\n * Generate a deterministic className from a cache key using content hash.\n * This ensures the same styles always produce the same className,\n * regardless of build order or incremental compilation.\n */\nfunction generateClassName(cacheKey: string): string {\n  const hash = createHash('md5').update(cacheKey).digest('hex').slice(0, 6);\n  return `ts${hash}`; // 'ts' prefix for \"tasty-static\" to distinguish from runtime 't' classes\n}\n\n/**\n * Extract styles using chunking (for className mode).\n * Returns multiple classes, one per chunk.\n */\nexport function extractStylesWithChunks(styles: Styles): ExtractedChunk[] {\n  const chunks: ExtractedChunk[] = [];\n\n  // Categorize style keys into chunks\n  const chunkMap = categorizeStyleKeys(styles as Record<string, unknown>);\n\n  for (const [chunkName, chunkStyleKeys] of chunkMap) {\n    if (chunkStyleKeys.length === 0) continue;\n\n    // Generate cache key for this chunk (used for className hash)\n    const cacheKey = generateChunkCacheKey(styles, chunkName, chunkStyleKeys);\n\n    // Render styles for this chunk\n    const renderResult = renderStylesForChunk(\n      styles,\n      chunkName,\n      chunkStyleKeys,\n    );\n\n    if (renderResult.rules.length === 0) continue;\n\n    // Generate deterministic className from content hash\n    const className = generateClassName(cacheKey);\n    const selector = `.${className}.${className}`;\n\n    // Format CSS\n    const css = formatRulesToCSS(renderResult.rules, selector);\n\n    chunks.push({ className, css });\n  }\n\n  return chunks;\n}\n\n/**\n * Extract styles for a specific selector (for global/selector mode).\n * Returns a single CSS block.\n */\nexport function extractStylesForSelector(\n  selector: string,\n  styles: Styles,\n): ExtractedSelector {\n  // renderStyles with selector returns StyleResult[] with selectors already applied\n  const rules = renderStyles(styles, selector);\n  // Format without re-prefixing - rules already have the full selector\n  const css = formatRulesDirectly(rules);\n\n  return { selector, css };\n}\n\n/**\n * Format StyleResult[] to CSS string.\n * Prefixes each rule's selector with the base selector.\n * Used for chunked styles where rules have relative selectors.\n */\nfunction formatRulesToCSS(rules: StyleResult[], baseSelector: string): string {\n  return rules\n    .map((rule) => {\n      // Handle selector as array (OR conditions) or string\n      // Note: renderStyles without className joins array selectors with '|||' placeholder\n      const selectorParts = Array.isArray(rule.selector)\n        ? rule.selector\n        : rule.selector\n          ? rule.selector.split('|||')\n          : [''];\n\n      // Prefix each selector part with the base selector\n      const fullSelector = selectorParts\n        .map((part) => {\n          // Build selector: [rootPrefix] baseSelector[part]\n          let selector: string;\n\n          // If part is empty, just use base selector\n          if (!part) {\n            selector = baseSelector;\n          } else if (part.startsWith(':') || part.startsWith('[')) {\n            // If part starts with a pseudo-class or pseudo-element, append to base\n            selector = `${baseSelector}${part}`;\n          } else if (\n            part.startsWith('>') ||\n            part.startsWith('+') ||\n            part.startsWith('~')\n          ) {\n            // If part starts with >, +, ~ combinator, append with space\n            selector = `${baseSelector}${part}`;\n          } else {\n            // Otherwise, combine base with part\n            selector = `${baseSelector}${part}`;\n          }\n\n          // Prepend rootPrefix if present (for @root() states)\n          if (rule.rootPrefix) {\n            selector = `${rule.rootPrefix} ${selector}`;\n          }\n\n          return selector;\n        })\n        .join(', ');\n\n      let css = `${fullSelector} { ${rule.declarations} }`;\n\n      // Wrap in at-rules (in reverse order for proper nesting)\n      if (rule.atRules && rule.atRules.length > 0) {\n        for (const atRule of [...rule.atRules].reverse()) {\n          css = `${atRule} {\\n  ${css}\\n}`;\n        }\n      }\n\n      return css;\n    })\n    .join('\\n\\n');\n}\n\n/**\n * Format StyleResult[] to CSS string directly without prefixing.\n * Used for global styles where rules already have the full selector.\n */\nfunction formatRulesDirectly(rules: StyleResult[]): string {\n  return rules\n    .map((rule) => {\n      // Prepend rootPrefix if present (for @root() states)\n      const selector = rule.rootPrefix\n        ? `${rule.rootPrefix} ${rule.selector}`\n        : rule.selector;\n\n      let css = `${selector} { ${rule.declarations} }`;\n\n      // Wrap in at-rules (in reverse order for proper nesting)\n      if (rule.atRules && rule.atRules.length > 0) {\n        for (const atRule of [...rule.atRules].reverse()) {\n          css = `${atRule} {\\n  ${css}\\n}`;\n        }\n      }\n\n      return css;\n    })\n    .join('\\n\\n');\n}\n\n// Note: With hash-based className generation, counter management functions\n// are no longer needed. ClassNames are deterministic based on content.\n\n/**\n * Generate a deterministic keyframes name from content hash.\n * This ensures the same keyframes content always produces the same name,\n * enabling automatic deduplication across elements and files.\n */\nfunction generateKeyframesName(steps: KeyframesSteps): string {\n  const content = JSON.stringify(steps);\n  const hash = createHash('md5').update(content).digest('hex').slice(0, 6);\n  return `kf${hash}`; // 'kf' prefix for \"keyframes\"\n}\n\n/**\n * Extract keyframes that are used in styles.\n * Merges local @keyframes with global keyframes, filters to only used ones.\n * Generates hash-based names from content for automatic deduplication.\n *\n * @param styles - The styles object (may contain @keyframes and animation properties)\n * @param globalKeyframes - Optional global keyframes from config\n * @returns Keyframes to inject and name mapping for replacement\n */\nexport function extractKeyframesFromStyles(\n  styles: Styles,\n  globalKeyframes?: Record<string, KeyframesSteps> | null,\n): KeyframesExtractionResult {\n  const emptyResult: KeyframesExtractionResult = {\n    keyframes: [],\n    nameMap: new Map(),\n  };\n\n  // Extract animation names from styles\n  const usedNames = extractAnimationNamesFromStyles(styles);\n  if (usedNames.size === 0) return emptyResult;\n\n  // Merge local and global keyframes\n  const local = hasLocalKeyframes(styles)\n    ? extractLocalKeyframes(styles)\n    : null;\n  const allKeyframes = mergeKeyframes(local, globalKeyframes ?? null);\n\n  // Filter to only used keyframes\n  const usedKeyframes = filterUsedKeyframes(allKeyframes, usedNames);\n  if (!usedKeyframes) return emptyResult;\n\n  // Generate hash-based names and collect unique keyframes\n  const seenHashes = new Set<string>();\n  const nameMap = new Map<string, string>();\n  const keyframesToEmit: ExtractedKeyframes[] = [];\n\n  for (const [originalName, steps] of Object.entries(usedKeyframes)) {\n    const hashedName = generateKeyframesName(steps);\n\n    // Always map original name to hashed name (for CSS replacement)\n    nameMap.set(originalName, hashedName);\n\n    // Only emit each unique keyframe once\n    if (!seenHashes.has(hashedName)) {\n      seenHashes.add(hashedName);\n      const css = keyframesToCSS(hashedName, steps);\n      keyframesToEmit.push({ name: hashedName, css });\n    }\n  }\n\n  return { keyframes: keyframesToEmit, nameMap };\n}\n\n/**\n * Convert keyframes steps to CSS string.\n */\nfunction keyframesToCSS(name: string, steps: KeyframesSteps): string {\n  const stepRules: string[] = [];\n\n  for (const [key, value] of Object.entries(steps)) {\n    if (typeof value === 'string') {\n      // Raw CSS string\n      stepRules.push(`${key} { ${value.trim()} }`);\n    } else if (value && typeof value === 'object') {\n      // Style map - convert to CSS declarations\n      const declarations = Object.entries(value)\n        .map(([prop, val]) => {\n          const cssProperty = camelToKebab(prop);\n          return `${cssProperty}: ${val}`;\n        })\n        .join('; ');\n      stepRules.push(`${key} { ${declarations} }`);\n    }\n  }\n\n  return `@keyframes ${name} { ${stepRules.join(' ')} }`;\n}\n\n/**\n * Convert camelCase to kebab-case.\n */\nfunction camelToKebab(str: string): string {\n  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);\n}\n"],"mappings":"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"}
+{"version":3,"file":"extractor.js","names":[],"sources":["../../src/zero/extractor.ts"],"sourcesContent":["import { createHash } from 'crypto';\n\nimport {\n  categorizeStyleKeys,\n  generateChunkCacheKey,\n  renderStylesForChunk,\n} from '../chunks';\nimport type { KeyframesSteps } from '../injector/types';\nimport {\n  extractAnimationNamesFromStyles,\n  extractLocalKeyframes,\n  filterUsedKeyframes,\n  hasLocalKeyframes,\n  mergeKeyframes,\n} from '../keyframes';\nimport type { StyleResult } from '../pipeline';\nimport { renderStyles } from '../pipeline';\nimport { extractLocalProperties, hasLocalProperties } from '../properties';\nimport { PropertyTypeResolver } from '../properties/property-type-resolver';\nimport type { Styles } from '../styles/types';\n\nexport interface ExtractedChunk {\n  className: string;\n  css: string;\n}\n\nexport interface ExtractedSelector {\n  selector: string;\n  css: string;\n}\n\nexport interface ExtractedKeyframes {\n  name: string;\n  css: string;\n}\n\nexport interface KeyframesExtractionResult {\n  /** Keyframes to inject (deduplicated by content) */\n  keyframes: ExtractedKeyframes[];\n  /** Map from original animation name to canonical name (for replacement) */\n  nameMap: Map<string, string>;\n}\n\n/**\n * Generate a deterministic className from a cache key using content hash.\n * This ensures the same styles always produce the same className,\n * regardless of build order or incremental compilation.\n */\nfunction generateClassName(cacheKey: string): string {\n  const hash = createHash('md5').update(cacheKey).digest('hex').slice(0, 6);\n  return `ts${hash}`; // 'ts' prefix for \"tasty-static\" to distinguish from runtime 't' classes\n}\n\n/**\n * Extract styles using chunking (for className mode).\n * Returns multiple classes, one per chunk.\n */\nexport function extractStylesWithChunks(styles: Styles): ExtractedChunk[] {\n  const chunks: ExtractedChunk[] = [];\n\n  // Categorize style keys into chunks\n  const chunkMap = categorizeStyleKeys(styles as Record<string, unknown>);\n\n  for (const [chunkName, chunkStyleKeys] of chunkMap) {\n    if (chunkStyleKeys.length === 0) continue;\n\n    // Generate cache key for this chunk (used for className hash)\n    const cacheKey = generateChunkCacheKey(styles, chunkName, chunkStyleKeys);\n\n    // Render styles for this chunk\n    const renderResult = renderStylesForChunk(\n      styles,\n      chunkName,\n      chunkStyleKeys,\n    );\n\n    if (renderResult.rules.length === 0) continue;\n\n    // Generate deterministic className from content hash\n    const className = generateClassName(cacheKey);\n    const selector = `.${className}.${className}`;\n\n    // Format CSS\n    const css = formatRulesToCSS(renderResult.rules, selector);\n\n    chunks.push({ className, css });\n  }\n\n  return chunks;\n}\n\n/**\n * Extract styles for a specific selector (for global/selector mode).\n * Returns a single CSS block.\n */\nexport function extractStylesForSelector(\n  selector: string,\n  styles: Styles,\n): ExtractedSelector {\n  // renderStyles with selector returns StyleResult[] with selectors already applied\n  const rules = renderStyles(styles, selector);\n  // Format without re-prefixing - rules already have the full selector\n  const css = formatRulesDirectly(rules);\n\n  return { selector, css };\n}\n\n/**\n * Format StyleResult[] to CSS string.\n * Prefixes each rule's selector with the base selector.\n * Used for chunked styles where rules have relative selectors.\n */\nfunction formatRulesToCSS(rules: StyleResult[], baseSelector: string): string {\n  return rules\n    .map((rule) => {\n      // Handle selector as array (OR conditions) or string\n      // Note: renderStyles without className joins array selectors with '|||' placeholder\n      const selectorParts = Array.isArray(rule.selector)\n        ? rule.selector\n        : rule.selector\n          ? rule.selector.split('|||')\n          : [''];\n\n      // Prefix each selector part with the base selector\n      const fullSelector = selectorParts\n        .map((part) => {\n          // Build selector: [rootPrefix] baseSelector[part]\n          let selector: string;\n\n          // If part is empty, just use base selector\n          if (!part) {\n            selector = baseSelector;\n          } else if (part.startsWith(':') || part.startsWith('[')) {\n            // If part starts with a pseudo-class or pseudo-element, append to base\n            selector = `${baseSelector}${part}`;\n          } else if (\n            part.startsWith('>') ||\n            part.startsWith('+') ||\n            part.startsWith('~')\n          ) {\n            // If part starts with >, +, ~ combinator, append with space\n            selector = `${baseSelector}${part}`;\n          } else {\n            // Otherwise, combine base with part\n            selector = `${baseSelector}${part}`;\n          }\n\n          // Prepend rootPrefix if present (for @root() states)\n          if (rule.rootPrefix) {\n            selector = `${rule.rootPrefix} ${selector}`;\n          }\n\n          return selector;\n        })\n        .join(', ');\n\n      let css = `${fullSelector} { ${rule.declarations} }`;\n\n      // Wrap in at-rules (in reverse order for proper nesting)\n      if (rule.atRules && rule.atRules.length > 0) {\n        for (const atRule of [...rule.atRules].reverse()) {\n          css = `${atRule} {\\n  ${css}\\n}`;\n        }\n      }\n\n      return css;\n    })\n    .join('\\n\\n');\n}\n\n/**\n * Format StyleResult[] to CSS string directly without prefixing.\n * Used for global styles where rules already have the full selector.\n */\nfunction formatRulesDirectly(rules: StyleResult[]): string {\n  return rules\n    .map((rule) => {\n      // Prepend rootPrefix if present (for @root() states)\n      const selector = rule.rootPrefix\n        ? `${rule.rootPrefix} ${rule.selector}`\n        : rule.selector;\n\n      let css = `${selector} { ${rule.declarations} }`;\n\n      // Wrap in at-rules (in reverse order for proper nesting)\n      if (rule.atRules && rule.atRules.length > 0) {\n        for (const atRule of [...rule.atRules].reverse()) {\n          css = `${atRule} {\\n  ${css}\\n}`;\n        }\n      }\n\n      return css;\n    })\n    .join('\\n\\n');\n}\n\n// Note: With hash-based className generation, counter management functions\n// are no longer needed. ClassNames are deterministic based on content.\n\n/**\n * Generate a deterministic keyframes name from content hash.\n * This ensures the same keyframes content always produces the same name,\n * enabling automatic deduplication across elements and files.\n */\nfunction generateKeyframesName(steps: KeyframesSteps): string {\n  const content = JSON.stringify(steps);\n  const hash = createHash('md5').update(content).digest('hex').slice(0, 6);\n  return `kf${hash}`; // 'kf' prefix for \"keyframes\"\n}\n\n/**\n * Extract keyframes that are used in styles.\n * Merges local @keyframes with global keyframes, filters to only used ones.\n * Generates hash-based names from content for automatic deduplication.\n *\n * @param styles - The styles object (may contain @keyframes and animation properties)\n * @param globalKeyframes - Optional global keyframes from config\n * @returns Keyframes to inject and name mapping for replacement\n */\nexport function extractKeyframesFromStyles(\n  styles: Styles,\n  globalKeyframes?: Record<string, KeyframesSteps> | null,\n): KeyframesExtractionResult {\n  const emptyResult: KeyframesExtractionResult = {\n    keyframes: [],\n    nameMap: new Map(),\n  };\n\n  // Extract animation names from styles\n  const usedNames = extractAnimationNamesFromStyles(styles);\n  if (usedNames.size === 0) return emptyResult;\n\n  // Merge local and global keyframes\n  const local = hasLocalKeyframes(styles)\n    ? extractLocalKeyframes(styles)\n    : null;\n  const allKeyframes = mergeKeyframes(local, globalKeyframes ?? null);\n\n  // Filter to only used keyframes\n  const usedKeyframes = filterUsedKeyframes(allKeyframes, usedNames);\n  if (!usedKeyframes) return emptyResult;\n\n  // Generate hash-based names and collect unique keyframes\n  const seenHashes = new Set<string>();\n  const nameMap = new Map<string, string>();\n  const keyframesToEmit: ExtractedKeyframes[] = [];\n\n  for (const [originalName, steps] of Object.entries(usedKeyframes)) {\n    const hashedName = generateKeyframesName(steps);\n\n    // Always map original name to hashed name (for CSS replacement)\n    nameMap.set(originalName, hashedName);\n\n    // Only emit each unique keyframe once\n    if (!seenHashes.has(hashedName)) {\n      seenHashes.add(hashedName);\n      const css = keyframesToCSS(hashedName, steps);\n      keyframesToEmit.push({ name: hashedName, css });\n    }\n  }\n\n  return { keyframes: keyframesToEmit, nameMap };\n}\n\n/**\n * Convert keyframes steps to CSS string.\n */\nfunction keyframesToCSS(name: string, steps: KeyframesSteps): string {\n  const stepRules: string[] = [];\n\n  for (const [key, value] of Object.entries(steps)) {\n    if (typeof value === 'string') {\n      // Raw CSS string\n      stepRules.push(`${key} { ${value.trim()} }`);\n    } else if (value && typeof value === 'object') {\n      // Style map - convert to CSS declarations\n      const declarations = Object.entries(value)\n        .map(([prop, val]) => {\n          const cssProperty = camelToKebab(prop);\n          return `${cssProperty}: ${val}`;\n        })\n        .join('; ');\n      stepRules.push(`${key} { ${declarations} }`);\n    }\n  }\n\n  return `@keyframes ${name} { ${stepRules.join(' ')} }`;\n}\n\n/**\n * Convert camelCase to kebab-case.\n */\nfunction camelToKebab(str: string): string {\n  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);\n}\n\n// ============================================================================\n// Property Extraction (auto-infer @property types for zero-runtime)\n// ============================================================================\n\nexport interface ExtractedProperty {\n  name: string;\n  css: string;\n}\n\n/**\n * Extract auto-inferred @property declarations from styles.\n * Scans rendered style declarations and keyframe declarations for custom properties\n * whose types can be inferred from their values.\n *\n * @param styles - The styles object\n * @param options - Options including autoPropertyTypes flag\n * @returns Array of @property CSS rules to inject\n */\nexport function extractPropertiesFromStyles(\n  styles: Styles,\n  options?: { autoPropertyTypes?: boolean },\n): ExtractedProperty[] {\n  if (options?.autoPropertyTypes === false) return [];\n\n  const registered = new Set<string>();\n  const results: ExtractedProperty[] = [];\n\n  // Collect explicitly declared properties (they take precedence)\n  if (hasLocalProperties(styles)) {\n    const localProps = extractLocalProperties(styles);\n    if (localProps) {\n      for (const token of Object.keys(localProps)) {\n        // Normalize token to CSS name\n        let cssName: string;\n        if (token.startsWith('#')) {\n          cssName = `--${token.slice(1)}-color`;\n        } else if (token.startsWith('$')) {\n          cssName = `--${token.slice(1)}`;\n        } else if (token.startsWith('--')) {\n          cssName = token;\n        } else {\n          cssName = `--${token}`;\n        }\n        registered.add(cssName);\n      }\n    }\n  }\n\n  const resolver = new PropertyTypeResolver();\n\n  const registerProperty = (\n    name: string,\n    syntax: string,\n    initialValue: string,\n  ) => {\n    if (registered.has(name)) return;\n    registered.add(name);\n\n    const parts: string[] = [];\n    parts.push(`syntax: \"${syntax}\";`);\n    parts.push(`inherits: true;`);\n    parts.push(`initial-value: ${initialValue};`);\n\n    const css = `@property ${name} { ${parts.join(' ')} }`;\n    results.push({ name, css });\n  };\n\n  const isPropertyDefined = (name: string) => registered.has(name);\n\n  // Scan rendered style declarations\n  const chunkMap = categorizeStyleKeys(styles as Record<string, unknown>);\n  for (const [chunkName, chunkStyleKeys] of chunkMap) {\n    if (chunkStyleKeys.length === 0) continue;\n    const renderResult = renderStylesForChunk(\n      styles,\n      chunkName,\n      chunkStyleKeys,\n    );\n    for (const rule of renderResult.rules) {\n      if (!rule.declarations) continue;\n      resolver.scanDeclarations(\n        rule.declarations,\n        isPropertyDefined,\n        registerProperty,\n      );\n    }\n  }\n\n  // Scan keyframe declarations\n  if (hasLocalKeyframes(styles)) {\n    const localKf = extractLocalKeyframes(styles);\n    if (localKf) {\n      for (const steps of Object.values(localKf)) {\n        scanKeyframeSteps(steps, resolver, isPropertyDefined, registerProperty);\n      }\n    }\n  }\n\n  return results;\n}\n\nfunction scanKeyframeSteps(\n  steps: KeyframesSteps,\n  resolver: PropertyTypeResolver,\n  isPropertyDefined: (name: string) => boolean,\n  registerProperty: (\n    name: string,\n    syntax: string,\n    initialValue: string,\n  ) => void,\n): void {\n  for (const value of Object.values(steps)) {\n    if (typeof value === 'string') {\n      resolver.scanDeclarations(value, isPropertyDefined, registerProperty);\n    } else if (value && typeof value === 'object') {\n      const declarations = Object.entries(value)\n        .map(([prop, val]) => {\n          const cssProperty = camelToKebab(prop);\n          return `${cssProperty}: ${val}`;\n        })\n        .join('; ');\n      resolver.scanDeclarations(\n        declarations,\n        isPropertyDefined,\n        registerProperty,\n      );\n    }\n  }\n}\n"],"mappings":"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"}

package/docs/configuration.md

@@ -0,0 +1,211 @@
+# Configuration
+
+Configure the Tasty style system before your app renders using the `configure()` function. Configuration must be done **before any styles are generated** (before first render).
+
+```jsx
+import { configure } from '@tenphi/tasty';
+
+configure({
+  // CSP nonce for style elements
+  nonce: 'abc123',
+
+  // Global state aliases
+  states: {
+    '@mobile': '@media(w < 768px)',
+    '@tablet': '@media(768px <= w < 1024px)',
+    '@dark': '@root(theme=dark)',
+  },
+
+  // Parser configuration
+  parserCacheSize: 2000, // LRU cache size (default: 1000)
+
+  // Custom units (merged with built-in units)
+  units: {
+    vh: 'vh',
+    vw: 'vw',
+    custom: (n) => `${n * 10}px`, // Function-based unit
+  },
+
+  // Custom functions for the parser
+  funcs: {
+    double: (groups) => {
+      const value = parseFloat(groups[0]?.output || '0');
+      return `${value * 2}px`;
+    },
+  },
+});
+```
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `nonce` | `string` | - | CSP nonce for style elements |
+| `states` | `Record<string, string>` | - | Global state aliases for advanced state mapping |
+| `parserCacheSize` | `number` | `1000` | Parser LRU cache size |
+| `units` | `Record<string, string \| Function>` | Built-in | Custom units (merged with built-in). See [built-in units](usage.md#built-in-units) |
+| `funcs` | `Record<string, Function>` | - | Custom parser functions (merged with existing) |
+| `handlers` | `Record<string, StyleHandlerDefinition>` | Built-in | Custom style handlers (replace built-in) |
+| `tokens` | `Record<string, string \| number>` | - | Predefined tokens replaced during parsing |
+| `keyframes` | `Record<string, KeyframesSteps>` | - | Global keyframes for animations |
+| `properties` | `Record<string, PropertyDefinition>` | - | Global CSS @property definitions |
+| `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
+| `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
+
+---
+
+## Predefined Tokens
+
+Define reusable tokens that are replaced during style parsing. Unlike component-level `tokens` prop (which renders as inline CSS custom properties), predefined tokens are baked into the generated CSS.
+
+Use `$name` for custom property tokens and `#name` for color tokens:
+
+```jsx
+configure({
+  tokens: {
+    $spacing: '2x',
+    '$card-padding': '4x',
+    '$button-height': '40px',
+    '#accent': '#purple',
+    '#surface': '#white',
+    '#surface-hover': '#gray.05',
+  },
+});
+```
+
+Once defined, tokens can be used in any component's styles — see [Using Predefined Tokens](usage.md#predefined-tokens) in the usage guide.
+
+---
+
+## Recipes
+
+Recipes are predefined, named style bundles. Define them globally via `configure()`:
+
+```jsx
+configure({
+  recipes: {
+    card: {
+      padding: '4x',
+      fill: '#surface',
+      radius: '1r',
+      border: true,
+    },
+    elevated: {
+      shadow: '2x 2x 4x #shadow',
+    },
+  },
+});
+```
+
+Recipe values are flat tasty styles (no sub-element keys). They may contain base styles, tokens, local states, `@keyframes`, and `@properties`. Recipes cannot reference other recipes.
+
+For how to apply, compose, and override recipes in components, see [Using Recipes](usage.md#recipes) in the usage guide.
+
+---
+
+## Auto Property Types
+
+CSS cannot transition or animate custom properties unless their type is declared via [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property). Tasty handles this automatically — when a custom property is assigned a concrete value (e.g. `'$scale': 1`, `'$gap': '10px'`, `'#accent': 'purple'`), the type is inferred and a `@property` rule is registered.
+
+This works across all declaration contexts: component styles, `@keyframes`, global config, and the zero-runtime Babel plugin. It also resolves `var()` chains — if `$a` references `var(--b)`, the type propagates once `--b` is resolved.
+
+Supported types:
+
+| Detection | Inferred syntax |
+|-----------|-----------------|
+| `1`, `0.5`, `-3` (bare numbers) | `<number>` |
+| `10px`, `2rem`, `100vw` (length units) | `<length>` |
+| `50%` | `<percentage>` |
+| `45deg`, `0.5turn` (angle units) | `<angle>` |
+| `300ms`, `1s` (time units) | `<time>` |
+| `#name` tokens (by naming convention) | `<color>` |
+
+Auto-inferred properties use `inherits: true` (the CSS default). Use explicit `@properties` when you need different settings:
+
+```jsx
+// In component styles
+styles: {
+  '@properties': {
+    '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
+  },
+}
+
+// Or globally
+configure({
+  properties: {
+    '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
+  },
+});
+```
+
+To disable auto-inference entirely (only explicit `@properties` will be used):
+
+```jsx
+configure({ autoPropertyTypes: false });
+```
+
+---
+
+## Custom Style Handlers
+
+Override or extend the built-in style property handlers. A handler definition can take three forms:
+
+| Form | Syntax | Description |
+|------|--------|-------------|
+| Function only | `handler` | Triggered by its key name; receives only that property |
+| Single dep | `['styleName', handler]` | Triggered by the specified style property |
+| Multi dep | `[['dep1', 'dep2', ...], handler]` | Triggered by any of the listed properties; receives all of them |
+
+The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy).
+
+```jsx
+import { configure, styleHandlers } from '@tenphi/tasty';
+
+configure({
+  handlers: {
+    // Function only — overrides built-in fill handler
+    fill: ({ fill }) => {
+      if (fill?.startsWith('gradient:')) {
+        return { background: fill.slice(9) };
+      }
+      return styleHandlers.fill({ fill });
+    },
+
+    // Function only — new single-prop handler
+    elevation: ({ elevation }) => {
+      const level = parseInt(elevation) || 1;
+      return {
+        'box-shadow': `0 ${level * 2}px ${level * 4}px rgba(0,0,0,0.1)`,
+        'z-index': String(level * 100),
+      };
+    },
+
+    // Multi dep — handler reads multiple style properties
+    gap: [['display', 'flow', 'gap'], ({ display, flow, gap }) => {
+      if (!gap) return;
+      const isGrid = display?.includes('grid');
+      return { gap: isGrid ? gap : `/* custom logic for ${flow} */` };
+    }],
+  },
+});
+```
+
+---
+
+## Extending Style Types (TypeScript)
+
+Use module augmentation to extend the `StylesInterface`:
+
+```tsx
+// tasty.d.ts
+declare module '@tenphi/tasty' {
+  interface StylesInterface {
+    elevation?: string;
+    gradient?: string;
+  }
+}
+```
+
+See [Usage Guide](usage.md) for component creation, state mappings, sub-elements, variants, and hooks.