@tenphi/tasty 1.2.0 → 1.4.0

package/dist/utils/process-tokens.d.ts

@@ -12,10 +12,6 @@ import { Tokens } from "../types.js";
  * @returns CSSProperties object or undefined if no tokens to process
  */
 declare function processTokens(tokens: Tokens | undefined): CSSProperties | undefined;
-/**
- * Stringify tokens for memoization key.
- */
-declare function stringifyTokens(tokens: Tokens | undefined): string;
 //#endregion
-export { processTokens, stringifyTokens };
+export { processTokens };
 //# sourceMappingURL=process-tokens.d.ts.map

package/dist/utils/process-tokens.js

@@ -77,14 +77,7 @@ function processTokens(tokens) {
 	}
 	return result;
 }
-/**
-* Stringify tokens for memoization key.
-*/
-function stringifyTokens(tokens) {
-	if (!tokens) return "";
-	return JSON.stringify(tokens);
-}
 //#endregion
-export { processTokens, stringifyTokens };
+export { processTokens };
 
 //# sourceMappingURL=process-tokens.js.map

package/dist/utils/process-tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"process-tokens.js","names":[],"sources":["../../src/utils/process-tokens.ts"],"sourcesContent":["import type { Tokens, TokenValue } from '../types';\n\nimport type { CSSProperties } from './css-types';\n\nimport { getColorSpaceComponents, getColorSpaceSuffix } from './color-space';\nimport { normalizeColorTokenValue, parseStyle } from './styles';\n\nexport { hslToRgbValues } from './color-math';\n\nconst devMode = process.env.NODE_ENV !== 'production';\n\n/**\n * Extract color components in the configured color space.\n * Returns a CSS variable reference for token colors, or decomposed\n * components as a space-separated string.\n */\nfunction extractColorSpaceValue(\n  colorValue: string,\n  parsedOutput: string,\n): string {\n  const suffix = getColorSpaceSuffix();\n\n  // If the parsed output references a color variable, use the companion variant\n  const varMatch = parsedOutput.match(/var\\(--([a-z0-9-]+)-color\\)/);\n  if (varMatch) {\n    return `var(--${varMatch[1]}-color-${suffix})`;\n  }\n\n  // Try the original color value first, then parsed output\n  const components = getColorSpaceComponents(colorValue);\n  if (components !== colorValue) return components;\n\n  const componentsFromParsed = getColorSpaceComponents(parsedOutput);\n  if (componentsFromParsed !== parsedOutput) return componentsFromParsed;\n\n  // Fallback: return the parsed output\n  return parsedOutput;\n}\n\n/**\n * Check if a value is a valid token value (string, number, or boolean - not object).\n * Returns false for `false` values (they mean \"skip this token\").\n */\nfunction isValidTokenValue(\n  value: unknown,\n): value is Exclude<TokenValue, undefined | null | false> {\n  if (value === undefined || value === null || value === false) {\n    return false;\n  }\n\n  if (typeof value === 'object') {\n    if (devMode) {\n      console.warn(\n        'Tasty: Object values are not allowed in tokens prop. ' +\n          'Tokens do not support state-based styling. Use a primitive value instead.',\n      );\n    }\n    return false;\n  }\n\n  return (\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  );\n}\n\n/**\n * Process a single token value through the tasty parser.\n * Numbers are converted to strings; 0 stays as \"0\".\n */\nfunction processTokenValue(value: string | number): string {\n  if (typeof value === 'number') {\n    // 0 should remain as \"0\", not converted to any unit\n    if (value === 0) {\n      return '0';\n    }\n    return parseStyle(String(value)).output;\n  }\n  return parseStyle(value).output;\n}\n\n/**\n * Process tokens object into inline style properties.\n * - $name -> --name with parsed value\n * - #name -> --name-color AND --name-color-{colorSpace} with parsed values\n *\n * @param tokens - The tokens object to process\n * @returns CSSProperties object or undefined if no tokens to process\n */\nexport function processTokens(\n  tokens: Tokens | undefined,\n): CSSProperties | undefined {\n  if (!tokens) {\n    return undefined;\n  }\n\n  const keys = Object.keys(tokens);\n  if (keys.length === 0) {\n    return undefined;\n  }\n\n  let result: Record<string, string> | undefined;\n\n  for (const key of keys) {\n    const value = tokens[key as keyof Tokens];\n\n    // Skip undefined/null values\n    if (!isValidTokenValue(value)) {\n      continue;\n    }\n\n    if (key.startsWith('$')) {\n      // Custom property token: $name -> --name\n      const propName = `--${key.slice(1)}`;\n      // Boolean true for custom properties converts to empty string (valid CSS value)\n      const effectiveValue = value === true ? '' : value;\n      const processedValue = processTokenValue(effectiveValue);\n\n      if (!result) result = {};\n      result[propName] = processedValue;\n    } else if (key.startsWith('#')) {\n      const colorName = key.slice(1);\n      const suffix = getColorSpaceSuffix();\n\n      // Normalize color token value (true → 'transparent', false is already filtered by isValidTokenValue)\n      const effectiveValue = normalizeColorTokenValue(value);\n      // Skip if normalized to null (shouldn't happen since false is filtered by isValidTokenValue)\n      if (effectiveValue === null) continue;\n\n      const originalValue =\n        typeof effectiveValue === 'number'\n          ? String(effectiveValue)\n          : effectiveValue;\n      const lowerValue = originalValue.toLowerCase();\n      const processedValue = processTokenValue(effectiveValue);\n\n      if (!result) result = {};\n      result[`--${colorName}-color`] = processedValue;\n\n      // Skip component generation for #current values (currentcolor is dynamic, cannot decompose)\n      if (/^#current(?:\\.|$)/i.test(lowerValue)) {\n        continue;\n      }\n\n      result[`--${colorName}-color-${suffix}`] = extractColorSpaceValue(\n        originalValue,\n        processedValue,\n      );\n    }\n  }\n\n  return result as CSSProperties | undefined;\n}\n\n/**\n * Stringify tokens for memoization key.\n */\nexport function stringifyTokens(tokens: Tokens | undefined): string {\n  if (!tokens) return '';\n  return JSON.stringify(tokens);\n}\n"],"mappings":";;;;;;;;;AAgBA,SAAS,uBACP,YACA,cACQ;CACR,MAAM,SAAS,qBAAqB;CAGpC,MAAM,WAAW,aAAa,MAAM,8BAA8B;AAClE,KAAI,SACF,QAAO,SAAS,SAAS,GAAG,SAAS,OAAO;CAI9C,MAAM,aAAa,wBAAwB,WAAW;AACtD,KAAI,eAAe,WAAY,QAAO;CAEtC,MAAM,uBAAuB,wBAAwB,aAAa;AAClE,KAAI,yBAAyB,aAAc,QAAO;AAGlD,QAAO;;;;;;AAOT,SAAS,kBACP,OACwD;AACxD,KAAI,UAAU,KAAA,KAAa,UAAU,QAAQ,UAAU,MACrD,QAAO;AAGT,KAAI,OAAO,UAAU,UAAU;AAE3B,UAAQ,KACN,iIAED;AAEH,SAAO;;AAGT,QACE,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU;;;;;;AAQrB,SAAS,kBAAkB,OAAgC;AACzD,KAAI,OAAO,UAAU,UAAU;AAE7B,MAAI,UAAU,EACZ,QAAO;AAET,SAAO,WAAW,OAAO,MAAM,CAAC,CAAC;;AAEnC,QAAO,WAAW,MAAM,CAAC;;;;;;;;;;AAW3B,SAAgB,cACd,QAC2B;AAC3B,KAAI,CAAC,OACH;CAGF,MAAM,OAAO,OAAO,KAAK,OAAO;AAChC,KAAI,KAAK,WAAW,EAClB;CAGF,IAAI;AAEJ,MAAK,MAAM,OAAO,MAAM;EACtB,MAAM,QAAQ,OAAO;AAGrB,MAAI,CAAC,kBAAkB,MAAM,CAC3B;AAGF,MAAI,IAAI,WAAW,IAAI,EAAE;GAEvB,MAAM,WAAW,KAAK,IAAI,MAAM,EAAE;GAGlC,MAAM,iBAAiB,kBADA,UAAU,OAAO,KAAK,MACW;AAExD,OAAI,CAAC,OAAQ,UAAS,EAAE;AACxB,UAAO,YAAY;aACV,IAAI,WAAW,IAAI,EAAE;GAC9B,MAAM,YAAY,IAAI,MAAM,EAAE;GAC9B,MAAM,SAAS,qBAAqB;GAGpC,MAAM,iBAAiB,yBAAyB,MAAM;AAEtD,OAAI,mBAAmB,KAAM;GAE7B,MAAM,gBACJ,OAAO,mBAAmB,WACtB,OAAO,eAAe,GACtB;GACN,MAAM,aAAa,cAAc,aAAa;GAC9C,MAAM,iBAAiB,kBAAkB,eAAe;AAExD,OAAI,CAAC,OAAQ,UAAS,EAAE;AACxB,UAAO,KAAK,UAAU,WAAW;AAGjC,OAAI,qBAAqB,KAAK,WAAW,CACvC;AAGF,UAAO,KAAK,UAAU,SAAS,YAAY,uBACzC,eACA,eACD;;;AAIL,QAAO;;;;;AAMT,SAAgB,gBAAgB,QAAoC;AAClE,KAAI,CAAC,OAAQ,QAAO;AACpB,QAAO,KAAK,UAAU,OAAO"}
+{"version":3,"file":"process-tokens.js","names":[],"sources":["../../src/utils/process-tokens.ts"],"sourcesContent":["import type { Tokens, TokenValue } from '../types';\n\nimport type { CSSProperties } from './css-types';\n\nimport { getColorSpaceComponents, getColorSpaceSuffix } from './color-space';\nimport { normalizeColorTokenValue, parseStyle } from './styles';\n\nexport { hslToRgbValues } from './color-math';\n\nconst devMode = process.env.NODE_ENV !== 'production';\n\n/**\n * Extract color components in the configured color space.\n * Returns a CSS variable reference for token colors, or decomposed\n * components as a space-separated string.\n */\nfunction extractColorSpaceValue(\n  colorValue: string,\n  parsedOutput: string,\n): string {\n  const suffix = getColorSpaceSuffix();\n\n  // If the parsed output references a color variable, use the companion variant\n  const varMatch = parsedOutput.match(/var\\(--([a-z0-9-]+)-color\\)/);\n  if (varMatch) {\n    return `var(--${varMatch[1]}-color-${suffix})`;\n  }\n\n  // Try the original color value first, then parsed output\n  const components = getColorSpaceComponents(colorValue);\n  if (components !== colorValue) return components;\n\n  const componentsFromParsed = getColorSpaceComponents(parsedOutput);\n  if (componentsFromParsed !== parsedOutput) return componentsFromParsed;\n\n  // Fallback: return the parsed output\n  return parsedOutput;\n}\n\n/**\n * Check if a value is a valid token value (string, number, or boolean - not object).\n * Returns false for `false` values (they mean \"skip this token\").\n */\nfunction isValidTokenValue(\n  value: unknown,\n): value is Exclude<TokenValue, undefined | null | false> {\n  if (value === undefined || value === null || value === false) {\n    return false;\n  }\n\n  if (typeof value === 'object') {\n    if (devMode) {\n      console.warn(\n        'Tasty: Object values are not allowed in tokens prop. ' +\n          'Tokens do not support state-based styling. Use a primitive value instead.',\n      );\n    }\n    return false;\n  }\n\n  return (\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  );\n}\n\n/**\n * Process a single token value through the tasty parser.\n * Numbers are converted to strings; 0 stays as \"0\".\n */\nfunction processTokenValue(value: string | number): string {\n  if (typeof value === 'number') {\n    // 0 should remain as \"0\", not converted to any unit\n    if (value === 0) {\n      return '0';\n    }\n    return parseStyle(String(value)).output;\n  }\n  return parseStyle(value).output;\n}\n\n/**\n * Process tokens object into inline style properties.\n * - $name -> --name with parsed value\n * - #name -> --name-color AND --name-color-{colorSpace} with parsed values\n *\n * @param tokens - The tokens object to process\n * @returns CSSProperties object or undefined if no tokens to process\n */\nexport function processTokens(\n  tokens: Tokens | undefined,\n): CSSProperties | undefined {\n  if (!tokens) {\n    return undefined;\n  }\n\n  const keys = Object.keys(tokens);\n  if (keys.length === 0) {\n    return undefined;\n  }\n\n  let result: Record<string, string> | undefined;\n\n  for (const key of keys) {\n    const value = tokens[key as keyof Tokens];\n\n    // Skip undefined/null values\n    if (!isValidTokenValue(value)) {\n      continue;\n    }\n\n    if (key.startsWith('$')) {\n      // Custom property token: $name -> --name\n      const propName = `--${key.slice(1)}`;\n      // Boolean true for custom properties converts to empty string (valid CSS value)\n      const effectiveValue = value === true ? '' : value;\n      const processedValue = processTokenValue(effectiveValue);\n\n      if (!result) result = {};\n      result[propName] = processedValue;\n    } else if (key.startsWith('#')) {\n      const colorName = key.slice(1);\n      const suffix = getColorSpaceSuffix();\n\n      // Normalize color token value (true → 'transparent', false is already filtered by isValidTokenValue)\n      const effectiveValue = normalizeColorTokenValue(value);\n      // Skip if normalized to null (shouldn't happen since false is filtered by isValidTokenValue)\n      if (effectiveValue === null) continue;\n\n      const originalValue =\n        typeof effectiveValue === 'number'\n          ? String(effectiveValue)\n          : effectiveValue;\n      const lowerValue = originalValue.toLowerCase();\n      const processedValue = processTokenValue(effectiveValue);\n\n      if (!result) result = {};\n      result[`--${colorName}-color`] = processedValue;\n\n      // Skip component generation for #current values (currentcolor is dynamic, cannot decompose)\n      if (/^#current(?:\\.|$)/i.test(lowerValue)) {\n        continue;\n      }\n\n      result[`--${colorName}-color-${suffix}`] = extractColorSpaceValue(\n        originalValue,\n        processedValue,\n      );\n    }\n  }\n\n  return result as CSSProperties | undefined;\n}\n"],"mappings":";;;;;;;;;AAgBA,SAAS,uBACP,YACA,cACQ;CACR,MAAM,SAAS,qBAAqB;CAGpC,MAAM,WAAW,aAAa,MAAM,8BAA8B;AAClE,KAAI,SACF,QAAO,SAAS,SAAS,GAAG,SAAS,OAAO;CAI9C,MAAM,aAAa,wBAAwB,WAAW;AACtD,KAAI,eAAe,WAAY,QAAO;CAEtC,MAAM,uBAAuB,wBAAwB,aAAa;AAClE,KAAI,yBAAyB,aAAc,QAAO;AAGlD,QAAO;;;;;;AAOT,SAAS,kBACP,OACwD;AACxD,KAAI,UAAU,KAAA,KAAa,UAAU,QAAQ,UAAU,MACrD,QAAO;AAGT,KAAI,OAAO,UAAU,UAAU;AAE3B,UAAQ,KACN,iIAED;AAEH,SAAO;;AAGT,QACE,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU;;;;;;AAQrB,SAAS,kBAAkB,OAAgC;AACzD,KAAI,OAAO,UAAU,UAAU;AAE7B,MAAI,UAAU,EACZ,QAAO;AAET,SAAO,WAAW,OAAO,MAAM,CAAC,CAAC;;AAEnC,QAAO,WAAW,MAAM,CAAC;;;;;;;;;;AAW3B,SAAgB,cACd,QAC2B;AAC3B,KAAI,CAAC,OACH;CAGF,MAAM,OAAO,OAAO,KAAK,OAAO;AAChC,KAAI,KAAK,WAAW,EAClB;CAGF,IAAI;AAEJ,MAAK,MAAM,OAAO,MAAM;EACtB,MAAM,QAAQ,OAAO;AAGrB,MAAI,CAAC,kBAAkB,MAAM,CAC3B;AAGF,MAAI,IAAI,WAAW,IAAI,EAAE;GAEvB,MAAM,WAAW,KAAK,IAAI,MAAM,EAAE;GAGlC,MAAM,iBAAiB,kBADA,UAAU,OAAO,KAAK,MACW;AAExD,OAAI,CAAC,OAAQ,UAAS,EAAE;AACxB,UAAO,YAAY;aACV,IAAI,WAAW,IAAI,EAAE;GAC9B,MAAM,YAAY,IAAI,MAAM,EAAE;GAC9B,MAAM,SAAS,qBAAqB;GAGpC,MAAM,iBAAiB,yBAAyB,MAAM;AAEtD,OAAI,mBAAmB,KAAM;GAE7B,MAAM,gBACJ,OAAO,mBAAmB,WACtB,OAAO,eAAe,GACtB;GACN,MAAM,aAAa,cAAc,aAAa;GAC9C,MAAM,iBAAiB,kBAAkB,eAAe;AAExD,OAAI,CAAC,OAAQ,UAAS,EAAE;AACxB,UAAO,KAAK,UAAU,WAAW;AAGjC,OAAI,qBAAqB,KAAK,WAAW,CACvC;AAGF,UAAO,KAAK,UAAU,SAAS,YAAY,uBACzC,eACA,eACD;;;AAIL,QAAO"}

package/docs/injector.md

@@ -207,13 +207,15 @@ import { configure } from '@tenphi/tasty';
 configure({
   devMode: true,                     // Enable development features (auto-detected)
   maxRulesPerSheet: 8192,            // Cap rules per stylesheet (default: 8192)
-  unusedStylesThreshold: 500,        // Trigger cleanup threshold (CSS rules only)
-  bulkCleanupDelay: 5000,            // Cleanup delay (ms) - ignored if idleCleanup is true
-  idleCleanup: true,                 // Use requestIdleCallback for cleanup
-  bulkCleanupBatchRatio: 0.5,        // Clean up oldest 50% per batch
-  unusedStylesMinAgeMs: 10000,       // Minimum age before cleanup (ms)
   forceTextInjection: false,         // Force textContent insertion (auto-detected for tests)
   nonce: 'csp-nonce',                // CSP nonce for security
+  gc: {                              // Garbage collection for unused styles
+    auto: true,                      // Enable automatic background sweep
+    baseMaxAge: 60000,               // Base TTL (ms) for single-use styles
+    cooldown: 30000,                 // Minimum time between GC runs
+    autoInterval: 300000,            // Background sweep interval (ms)
+    cacheCapacity: 5000,             // Hard cap on cached styles (optional)
+  },
   states: {                          // Global predefined states for advanced state mapping
     '@mobile': '@media(w < 768px)',
     '@dark': '@root(schema=dark)',
@@ -229,7 +231,9 @@ configure({
 - Most options have sensible defaults and auto-detection
 - `configure()` is optional - the injector works with defaults
 - **Configuration is locked after styles are generated** - calling `configure()` after first render will emit a warning and be ignored
-- `unusedStylesMinAgeMs`: Minimum time (ms) a style must remain unused before being eligible for cleanup. Helps prevent removal of styles that might be quickly reactivated.
+- `gc.baseMaxAge`: Base TTL for a style rendered only once. Popular styles get longer TTLs via logarithmic scaling (`baseMaxAge * log2(hitCount + 1)`).
+- `gc.auto`: When true, runs a periodic background sweep at `gc.autoInterval` intervals using `requestIdleCallback`.
+- `gc.cooldown`: Minimum time between GC runs to avoid thrashing.
 
 ---
 
@@ -291,21 +295,31 @@ comp3.dispose(); // refCount: 1 → 0, eligible for bulk cleanup
 // Next inject() with same styles will increment refCount and reuse immediately
 ```
 
-### Smart Cleanup System
+### Garbage Collection
 
 ```typescript
-import { configure } from '@tenphi/tasty';
+import { configure, gc, maybeGC } from '@tenphi/tasty';
 
-// CSS rules: Not immediately deleted, marked for bulk cleanup (refCount = 0)
 // Keyframes: Disposed immediately when refCount = 0 (safer for global scope)
+// CSS rules: Tracked by popularity and cleaned up via gc()
 
 configure({
-  unusedStylesThreshold: 100,    // Cleanup when 100+ unused CSS rules
-  bulkCleanupBatchRatio: 0.3,    // Remove oldest 30% each time
+  gc: {
+    auto: true,          // Enable background sweep
+    baseMaxAge: 60000,   // 1-minute base TTL
+    cooldown: 30000,     // 30s between runs
+  },
 });
 
+// Manual GC (synchronous, returns number of swept styles):
+gc();
+
+// Event-driven GC with cooldown (e.g. on route change):
+maybeGC();
+
 // Benefits:
-// - CSS rules: Batch cleanup prevents DOM manipulation overhead  
+// - Popularity-aware: frequently used styles survive longer
+// - DOM-safe: styles currently in the DOM are never evicted
 // - Keyframes: Immediate cleanup prevents global namespace pollution
 // - Unused styles can be instantly reactivated (just increment refCount)
 ```
@@ -462,13 +476,14 @@ injectGlobal([
   { selector: '.container', declarations: 'max-width: 1200px;' }
 ]);
 
-// ✅ Configure appropriate thresholds for your app (BEFORE first render!)
+// ✅ Configure GC for your app (BEFORE first render!)
 import { configure } from '@tenphi/tasty';
 
 configure({
-  unusedStylesThreshold: 500,      // Default threshold (adjust based on app size)
-  bulkCleanupBatchRatio: 0.5,      // Default: clean oldest 50% per batch
-  unusedStylesMinAgeMs: 10000,     // Wait 10s before cleanup eligibility
+  gc: {
+    auto: true,            // Enable background sweep for long-lived pages
+    baseMaxAge: 60000,     // Default base TTL (adjust based on app size)
+  },
 });
 ```
 
@@ -480,8 +495,8 @@ configure({
 // 1. Hash-based deduplication - same CSS = same className
 // 2. Reference counting - styles stay alive while in use (refCount > 0)
 // 3. Immediate keyframes cleanup - disposed instantly when refCount = 0
-// 4. Batch CSS cleanup - unused CSS rules (refCount = 0) cleaned in batches
-// 5. Non-stacking cleanups - prevents timeout accumulation
+// 4. Popularity-aware GC - unused CSS rules are scored by hitCount and age
+// 5. DOM safety guard - styles visible in the DOM are never evicted
 
 // Manual cleanup is rarely needed but available:
 cleanup(); // Force immediate cleanup of all unused CSS rules (refCount = 0)

package/docs/methodology.md

@@ -256,6 +256,54 @@ The `tokens` prop sets `style="--progress: 75%"` on the DOM element. The `$progr
 
 Design tokens (via `configure({ tokens })`) are injected as CSS custom properties on `:root`. Replace tokens (via `configure({ replaceTokens })`) are resolved at parse time and baked into the generated CSS. The `tokens` prop on components is resolved at render time via inline CSS custom properties. Use design tokens for design-system constants, replace tokens for value aliases, and the `tokens` prop for truly dynamic per-instance values.
 
+### tokenProps
+
+`tokenProps` expose token keys as top-level component props — the token equivalent of `styleProps` and `modProps`. Use them when a component has a fixed set of known dynamic token values.
+
+#### Array form
+
+Prop names are plain camelCase identifiers. Names ending in `Color` map to `#` color tokens; everything else maps to `$` custom property tokens:
+
+```tsx
+const ProgressBar = tasty({
+  tokenProps: ['progress', 'accentColor'] as const,
+  styles: { width: '$progress', fill: '#accent' },
+});
+
+// Clean prop API — no tokens object needed
+<ProgressBar progress="75%" accentColor="#purple" />
+
+// Conversion:
+//   'progress'    → $progress    → --progress
+//   'accentColor' → #accent      → --accent-color + --accent-color-oklch
+```
+
+#### Object form
+
+Keys are prop names; values are `$`/`#`-prefixed token keys. No suffix convention needed — the prefix in the value is explicit:
+
+```tsx
+const Card = tasty({
+  tokenProps: {
+    size: '$card-size',
+    color: '#card-accent',
+  },
+  styles: { padding: '$card-size', fill: '#card-accent' },
+});
+
+<Card size="4x" color="#purple" />
+```
+
+#### Merge order
+
+When all three token sources are present, values merge with increasing priority:
+
+1. `tokens` option in `tasty({...})` — default tokens (lowest)
+2. `tokens` prop on the component instance — runtime overrides
+3. `tokenProps`-derived values — highest priority (explicit named props win)
+
+The `tokens` prop remains available for ad-hoc or dynamic tokens alongside `tokenProps`.
+
 ---
 
 ## styles prop vs style prop
@@ -458,7 +506,8 @@ See [Configuration](configuration.md) for the full `configure()` API.
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
 - **Use `modProps`** to expose known modifier states as clean component props
-- **Use `tokens` prop** for per-instance dynamic values (progress, user color)
+- **Use `tokenProps`** to expose known token keys as clean component props
+- **Use `tokens` prop** for ad-hoc or dynamic per-instance token values (progress, user color)
 - **Use modifiers** (`mods` or `modProps`) for state-driven style changes instead of runtime `styles` prop changes
 
 ### Avoid

package/docs/runtime.md

@@ -1,6 +1,6 @@
 # Runtime API
 
-The React-specific `tasty()` component factory, component props, and hooks. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+The React-specific `tasty()` component factory, component props, and hooks. `tasty()` components are hook-free and compatible with React Server Components — no `'use client'` directive needed. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
 
 ---
 
@@ -154,6 +154,75 @@ For architecture guidance on when to use modifiers vs `styleProps`, see [Methodo
 
 ---
 
+## Token Props
+
+Use `tokenProps` to expose token keys as direct component props instead of requiring the `tokens` object:
+
+```jsx
+// Before: tokens object
+<ProgressBar tokens={{ $progress: '75%', '#accent': '#purple' }} />
+
+// After: token props
+<ProgressBar progress="75%" accentColor="#purple" />
+```
+
+### Array form
+
+List prop names. Names ending in `Color` map to `#` color tokens; everything else maps to `$` custom property tokens:
+
+```jsx
+const ProgressBar = tasty({
+  tokenProps: ['progress', 'accentColor'] as const,
+  styles: { width: '$progress', fill: '#accent' },
+});
+
+<ProgressBar progress="75%" accentColor="#purple" />
+// 'progress'    → $progress    → --progress
+// 'accentColor' → #accent      → --accent-color + --accent-color-oklch
+```
+
+### Object form
+
+Map prop names to explicit `$`/`#`-prefixed token keys:
+
+```tsx
+const Card = tasty({
+  tokenProps: {
+    size: '$card-size',
+    color: '#card-accent',
+  },
+  styles: { padding: '$card-size', fill: '#card-accent' },
+});
+
+<Card size="4x" color="#purple" />
+```
+
+### Merge with `tokens`
+
+Token props and the `tokens` prop can be used together. Token props take precedence over `tokens`, which takes precedence over default `tokens` in `tasty({...})`:
+
+```jsx
+const Bar = tasty({
+  tokenProps: ['progress'] as const,
+  tokens: { $progress: '0%' },  // default
+});
+
+<Bar tokens={{ $progress: '50%' }} progress="90%" />
+// progress="90%" wins (from token prop)
+```
+
+### When to use `tokenProps` vs `tokens`
+
+| Use case | Recommendation |
+|---|---|
+| Component has a fixed set of known token keys | `tokenProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic token values | `tokens` — open-ended `Record<string, TokenValue>` |
+| Both fixed and dynamic | Combine: `tokenProps` for known keys, `tokens` for ad-hoc |
+
+For architecture guidance, see [Methodology — tokenProps](methodology.md#tokenprops).
+
+---
+
 ## Variants
 
 Define named style variations. Only CSS for variants actually used at runtime is injected:
@@ -264,11 +333,29 @@ For the mental model behind sub-elements — how they share root state context a
 
 ---
 
+## computeStyles
+
+Hook-free, synchronous style computation. Can be used anywhere — including React Server Components, plain functions, and non-React code:
+
+```tsx
+import { computeStyles } from '@tenphi/tasty';
+
+const { className } = computeStyles({
+  padding: '2x',
+  fill: '#surface',
+  radius: '1r',
+});
+```
+
+On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server, CSS is collected via the SSR collector if one is available. This is the same function that `tasty()` components use internally.
+
+---
+
 ## Hooks
 
 ### useStyles
 
-Generate a className from a style object:
+Generate a className from a style object. Thin wrapper around `computeStyles()` that adds React context-based SSR collector discovery for backward compatibility:
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -469,7 +556,7 @@ function useCounterStyle(
 ### Troubleshooting
 
 - Styles are not updating: make sure `configure()` runs before first render, and verify the generated class name or global rule with [Debug Utilities](debug.md).
-- SSR output looks wrong: check the [SSR guide](ssr.md) because the hooks integrate with SSR collectors differently than the client-only runtime path.
+- SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. `computeStyles()` discovers the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
 - Animation/custom property issues: prefer `useKeyframes()` and `useProperty()` over raw CSS when you want Tasty to manage injection and SSR collection for you.
 
 ---

package/docs/ssr.md

@@ -18,16 +18,16 @@ The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies
 
 ## How It Works
 
-When the environment can execute runtime React code during server rendering, the same `tasty()` and `useStyles()` calls can run there too. In Next.js, generic React SSR, and Astro islands, Tasty simply changes where that runtime-generated CSS goes: `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `useStyles()` skips the rendering pipeline entirely during hydration.
+`tasty()` components are hook-free and use `computeStyles()` internally — a synchronous, framework-agnostic function. On the server, `computeStyles()` detects a `ServerStyleCollector` (via `AsyncLocalStorage` or an explicit option) and collects CSS into it instead of trying to access the DOM. On the client, CSS is injected synchronously into the DOM during render; the injector's content-based cache makes this idempotent. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `computeStyles()` skips the rendering pipeline entirely during hydration.
 
 ```
 Server                         Client
 ──────                         ──────
 tasty() renders                hydrateTastyCache() pre-populates cache
-  └─ useStyles()                 └─ cacheKey → className map ready
+  └─ computeStyles()              └─ cacheKey → className map ready
        └─ collector.collect()
                                  tasty() renders
-After render:                    └─ useStyles()
+After render:                    └─ computeStyles()
   <style data-tasty-ssr>              └─ cache hit → skip pipeline
   <script data-tasty-cache>           └─ no CSS re-injection
 ```
@@ -82,15 +82,15 @@ That's it. All `tasty()` components inside the tree automatically get SSR suppor
 
 ### How it works
 
-- `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load.
-- During SSR, `useStyles()` finds the collector via React context and pushes CSS rules to it.
-- `TastyRegistry` uses `useServerInsertedHTML` to flush collected CSS into the HTML stream as `<style data-tasty-ssr>` tags. This is fully streaming-compatible -- styles are injected alongside each Suspense boundary as it resolves.
+- `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load. The `'use client'` boundary is required solely to access `useServerInsertedHTML` — **not** because `tasty()` components need the client.
+- During SSR, `TastyRegistry` creates a `ServerStyleCollector` and registers it via a module-level global getter. All style computation — whether from `tasty()` components, `computeStyles()`, `useStyles()`, or other hooks like `useGlobalStyles()` — discovers the collector through this single global getter. No React context is involved.
+- `TastyRegistry` uses `useServerInsertedHTML` to flush collected CSS into the HTML stream as `<style data-tasty-ssr>` tags. This is fully streaming-compatible — styles are injected alongside each Suspense boundary as it resolves.
 - A companion `<script>` tag transfers the `cacheKey → className` mapping to the client.
-- When the module loads on the client, `hydrateTastyCache()` runs automatically and pre-populates the injector cache. During hydration, `useStyles()` hits the cache and skips the entire pipeline.
+- When the module loads on the client, `hydrateTastyCache()` runs automatically and pre-populates the injector cache. During hydration, `computeStyles()` hits the cache and skips the entire pipeline.
 
 ### Using tasty() in Server Components
 
-`tasty()` components use React hooks internally, so they require `'use client'`. However, this does **not** prevent them from being used in Server Component pages. In Next.js, `'use client'` components are still server-rendered on initial load. Dynamic `styleProps` like `<Grid flow="column">` work normally when a `tasty()` component is imported into a Server Component page.
+`tasty()` components are hook-free and do not require `'use client'`. They can be used directly in React Server Components. Dynamic `styleProps` like `<Grid flow="column">` work normally in server components. During SSR, `computeStyles()` discovers the collector via the same global getter registered by `TastyRegistry` — no React context or client boundary needed for this path.
 
 ### Options
 
@@ -161,10 +161,10 @@ import Card from '../components/Card.tsx';
 
 ### How it works
 
-Astro's `@astrojs/react` renderer calls `renderToString()` for each React component without wrapping the tree in a provider. The middleware uses `AsyncLocalStorage` to make the collector available to all `useStyles()` calls within the request.
+Astro's `@astrojs/react` renderer calls `renderToString()` for each React component without wrapping the tree in a provider. The middleware uses `AsyncLocalStorage` to make the collector available to all `computeStyles()` calls within the request.
 
 - **Static components** (no `client:*`): Styles are collected during `renderToString` and injected into `</head>`. No JavaScript is shipped for these components.
-- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, importing `@tenphi/tasty/ssr/astro` auto-hydrates the cache from `<script data-tasty-cache>`. The island's `useStyles()` calls hit the cache during hydration.
+- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, importing `@tenphi/tasty/ssr/astro` auto-hydrates the cache from `<script data-tasty-cache>`. The island's `computeStyles()` calls hit the cache during hydration.
 
 ### Client-side hydration for islands
 
@@ -197,12 +197,12 @@ Same as Next.js -- call `configure({ nonce: '...' })` before any rendering happe
 
 ## Generic Framework Integration
 
-Any React-based framework can integrate using the core SSR API:
+Any React-based framework can integrate using `runWithCollector`, which binds a `ServerStyleCollector` to the current async context via `AsyncLocalStorage`. All `computeStyles()` and hook calls within the render automatically discover the collector.
 
 ```tsx
 import {
   ServerStyleCollector,
-  TastySSRContext,
+  runWithCollector,
   hydrateTastyCache,
 } from '@tenphi/tasty/ssr';
 import { renderToString } from 'react-dom/server';
@@ -212,10 +212,8 @@ import { hydrateRoot } from 'react-dom/client';
 
 const collector = new ServerStyleCollector();
 
-const html = renderToString(
-  <TastySSRContext.Provider value={collector}>
-    <App />
-  </TastySSRContext.Provider>
+const html = await runWithCollector(collector, () =>
+  renderToString(<App />)
 );
 
 const css = collector.getCSS();
@@ -251,11 +249,8 @@ For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS
 ```tsx
 const collector = new ServerStyleCollector();
 
-const stream = renderToPipeableStream(
-  <TastySSRContext.Provider value={collector}>
-    <App />
-  </TastySSRContext.Provider>,
-  {
+const stream = await runWithCollector(collector, () =>
+  renderToPipeableStream(<App />, {
     onShellReady() {
       // Flush styles collected so far
       const css = collector.flushCSS();
@@ -270,31 +265,10 @@ const stream = renderToPipeableStream(
       const state = collector.getCacheState();
       res.write(`<script data-tasty-cache type="application/json">${JSON.stringify(state)}</script>`);
     },
-  }
+  })
 );
 ```
 
-### AsyncLocalStorage (no React context)
-
-If your framework doesn't support wrapping the React tree with a provider, use `runWithCollector`:
-
-```tsx
-import {
-  ServerStyleCollector,
-  runWithCollector,
-  hydrateTastyCache,
-} from '@tenphi/tasty/ssr';
-
-const collector = new ServerStyleCollector();
-
-const html = await runWithCollector(collector, () =>
-  renderToString(<App />)
-);
-
-const css = collector.getCSS();
-// ... inject into HTML as above
-```
-
 ---
 
 ## API Reference
@@ -303,7 +277,7 @@ const css = collector.getCSS();
 
 | Import path | Description |
 |---|---|
-| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `TastySSRContext`, `runWithCollector`, `hydrateTastyCache` |
+| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `runWithCollector`, `hydrateTastyCache` |
 | `@tenphi/tasty/ssr/next` | Next.js App Router: `TastyRegistry` component |
 | `@tenphi/tasty/ssr/astro` | Astro: `tastyMiddleware`, auto-hydration on import |
 
@@ -323,10 +297,6 @@ Server-safe style collector. One instance per request.
 | `flushCSS()` | Get only CSS collected since the last flush. For streaming SSR. |
 | `getCacheState()` | Serialize `{ entries: Record<cacheKey, className>, classCounter }` for client hydration. |
 
-### `TastySSRContext`
-
-React context (`createContext<ServerStyleCollector | null>(null)`). Used by `useStyles()` to find the collector during SSR.
-
 ### `TastyRegistry`
 
 Next.js App Router component. Props:
@@ -350,7 +320,7 @@ Pre-populate the client injector cache. When called without arguments, reads fro
 
 ### `runWithCollector(collector, fn)`
 
-Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All `useStyles()` calls within `fn` (and async continuations) will find this collector.
+Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All `computeStyles()` and `useStyles()` calls within `fn` (and async continuations) will find this collector.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -150,13 +150,13 @@
       "name": "main (import *)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "47 kB"
+      "limit": "48 kB"
     },
     {
       "name": "core (import *)",
       "path": "dist/core/index.js",
       "import": "*",
-      "limit": "45 kB"
+      "limit": "46 kB"
     },
     {
       "name": "static",
@@ -184,7 +184,7 @@
         "path",
         "crypto"
       ],
-      "limit": "41 kB"
+      "limit": "42 kB"
     }
   ],
   "scripts": {

package/dist/hooks/resolve-ssr-collector.js

@@ -1,14 +0,0 @@
-import { getRegisteredSSRCollector } from "../ssr/ssr-collector-ref.js";
-//#region src/hooks/resolve-ssr-collector.ts
-/**
-* Resolve the SSR collector from React context or AsyncLocalStorage.
-* Returns null on the client (no collector available).
-*/
-function resolveSSRCollector(reactContext) {
-	if (reactContext) return reactContext;
-	return getRegisteredSSRCollector();
-}
-//#endregion
-export { resolveSSRCollector };
-
-//# sourceMappingURL=resolve-ssr-collector.js.map

package/dist/hooks/resolve-ssr-collector.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-ssr-collector.js","names":[],"sources":["../../src/hooks/resolve-ssr-collector.ts"],"sourcesContent":["import type { ServerStyleCollector } from '../ssr/collector';\nimport { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';\n\n/**\n * Resolve the SSR collector from React context or AsyncLocalStorage.\n * Returns null on the client (no collector available).\n */\nexport function resolveSSRCollector(\n  reactContext: ServerStyleCollector | null,\n): ServerStyleCollector | null {\n  if (reactContext) return reactContext;\n  return getRegisteredSSRCollector();\n}\n"],"mappings":";;;;;;AAOA,SAAgB,oBACd,cAC6B;AAC7B,KAAI,aAAc,QAAO;AACzB,QAAO,2BAA2B"}

package/dist/ssr/context.d.ts

@@ -1,8 +0,0 @@
-import { ServerStyleCollector } from "./collector.js";
-import * as _$react from "react";
-
-//#region src/ssr/context.d.ts
-declare const TastySSRContext: _$react.Context<ServerStyleCollector | null>;
-//#endregion
-export { TastySSRContext };
-//# sourceMappingURL=context.d.ts.map

package/dist/ssr/context.js

@@ -1,13 +0,0 @@
-import { createContext } from "react";
-//#region src/ssr/context.ts
-/**
-* React context for SSR collector discovery.
-*
-* Used by Next.js TastyRegistry to provide the ServerStyleCollector
-* to useStyles() via React context (the streaming-compatible path).
-*/
-const TastySSRContext = createContext(null);
-//#endregion
-export { TastySSRContext };
-
-//# sourceMappingURL=context.js.map

package/dist/ssr/context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.js","names":[],"sources":["../../src/ssr/context.ts"],"sourcesContent":["/**\n * React context for SSR collector discovery.\n *\n * Used by Next.js TastyRegistry to provide the ServerStyleCollector\n * to useStyles() via React context (the streaming-compatible path).\n */\n\nimport { createContext } from 'react';\n\nimport type { ServerStyleCollector } from './collector';\n\nexport const TastySSRContext = createContext<ServerStyleCollector | null>(null);\n"],"mappings":";;;;;;;;AAWA,MAAa,kBAAkB,cAA2C,KAAK"}