fix(tasty): optimizations

Author: tenphi

src/stories/StyleInjector.docs.mdx

@@ -13,13 +13,13 @@ A high-performance CSS-in-JS solution that powers the Tasty design system with e
 The Style Injector is the core engine behind Tasty's styling system, providing:
 
 - **🔄 Hash-based deduplication** - Identical CSS gets the same className
-- **📊 Reference counting** - Automatic cleanup when components unmount
+- **📊 Reference counting** - Automatic cleanup when components unmount (refCount = 0)
 - **🎯 CSS nesting flattening** - Handles `&`, `.Class`, `SubElement` patterns
-- **🎬 Keyframes injection** - First-class `@keyframes` support with deduplication
-- **🧹 Safe bulk cleanup** - Unused styles are aged and cleaned up in partial batches
+- **🎬 Keyframes injection** - First-class `@keyframes` support with immediate disposal
+- **🧹 Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
 - **🖥️ SSR support** - Deterministic class names and CSS extraction
 - **🌙 Multiple roots** - Works with Document and ShadowRoot
-- **🔒 DOM presence validation** - Prevents deletion of styles still active in DOM
+- **⚡ Non-stacking cleanups** - Prevents timeout accumulation for better performance
 
 > **💡 Note:** This is internal infrastructure that powers Tasty components. Most developers will interact with the higher-level `tasty()` API instead.
 
@@ -67,7 +67,7 @@ const result = inject([{
 
 console.log(result.className); // 't-abc123'
 
-// Cleanup when component unmounts
+// Cleanup when component unmounts (refCount decremented)
 result.dispose();
 ```
 
@@ -116,9 +116,9 @@ const animatedComponent = inject([{
   declarations: `animation: ${fadeIn} 300ms ease-in;`
 }]);
 
-// Cleanup
-fadeIn.dispose();
-animatedComponent.dispose();
+// Cleanup (keyframes disposed immediately, CSS rules marked for batch cleanup)
+fadeIn.dispose();           // Immediate keyframes deletion from DOM
+animatedComponent.dispose(); // CSS rules marked unused (refCount = 0)
 ```
 
 ### `configure(config): void`
@@ -129,11 +129,10 @@ Configures the global injector instance.
 configure({
   devMode: true,                     // Enable development features
   maxRulesPerSheet: 8000,            // Cap rules per stylesheet
-  unusedStylesThreshold: 500,        // Trigger cleanup threshold
+  unusedStylesThreshold: 500,        // Trigger cleanup threshold (CSS rules only)
   bulkCleanupDelay: 5000,            // Cleanup delay (ms)
   idleCleanup: true,                 // Use requestIdleCallback
-  bulkCleanupBatchRatio: 0.5,        // Clean up oldest 50%
-  unusedStylesMinAgeMs: 10000,       // Minimum age before cleanup
+  bulkCleanupBatchRatio: 0.5,        // Clean up oldest 50% per batch
   forceTextInjection: false,         // Force textContent insertion
   nonce: 'csp-nonce',                // CSP nonce for security
 });
@@ -193,23 +192,27 @@ const comp3 = inject([commonStyle]);
 // Style is kept alive while any component uses it
 comp1.dispose(); // refCount: 3 → 2
 comp2.dispose(); // refCount: 2 → 1
-comp3.dispose(); // refCount: 1 → 0, marked for cleanup
+comp3.dispose(); // refCount: 1 → 0, eligible for bulk cleanup
+
+// Rule exists but refCount = 0 means unused
+// Next inject() with same styles will increment refCount and reuse immediately
 ```
 
-### Bulk Cleanup System
+### Smart Cleanup System
 
 ```typescript
-// Styles are not immediately deleted when dispose() is called
-// Instead, they're marked as unused and cleaned up in batches
+// CSS rules: Not immediately deleted, marked for bulk cleanup (refCount = 0)
+// Keyframes: Disposed immediately when refCount = 0 (safer for global scope)
 
 configure({
-  unusedStylesThreshold: 100,    // Cleanup when 100+ unused styles
+  unusedStylesThreshold: 100,    // Cleanup when 100+ unused CSS rules
   bulkCleanupBatchRatio: 0.3,    // Remove oldest 30% each time
-  unusedStylesMinAgeMs: 5000,    // Styles must be unused for 5s
 });
 
-// This prevents performance issues from frequent DOM manipulation
-// and allows "recently used" styles to be quickly reactivated
+// Benefits:
+// - CSS rules: Batch cleanup prevents DOM manipulation overhead  
+// - Keyframes: Immediate cleanup prevents global namespace pollution
+// - Unused styles can be instantly reactivated (just increment refCount)
 ```
 
 ### Shadow DOM Support
@@ -292,10 +295,10 @@ configure({ devMode: true });
 const metrics = injector.instance.getMetrics();
 
 console.log({
-  cacheHits: metrics.hits,           // Successful cache hits
+  cacheHits: metrics.hits,           // Successful cache hits  
   cacheMisses: metrics.misses,       // New styles injected
-  unusedHits: metrics.unusedHits,    // Reactivated unused styles
-  bulkCleanups: metrics.bulkCleanups, // Cleanup operations
+  unusedHits: metrics.unusedHits,    // Current unused styles (calculated)
+  bulkCleanups: metrics.bulkCleanups, // CSS cleanup operations (keyframes disposed immediately)
   stylesCleanedUp: metrics.stylesCleanedUp, // Total styles removed
   totalInsertions: metrics.totalInsertions, // Lifetime insertions
 });
@@ -364,13 +367,13 @@ configure({
 // The injector automatically manages memory through:
 
 // 1. Hash-based deduplication - same CSS = same className
-// 2. Reference counting - styles stay alive while in use
-// 3. Aged cleanup - unused styles must remain unused for minimum time
-// 4. Partial cleanup - only oldest unused styles are removed per batch
-// 5. DOM validation - prevents cleanup of styles still in DOM
+// 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
 
 // Manual cleanup is rarely needed but available:
-cleanup(); // Force immediate cleanup of eligible unused styles
+cleanup(); // Force immediate cleanup of all unused CSS rules (refCount = 0)
 destroy(); // Nuclear option: remove all stylesheets and reset
 ```
 

src/tasty/debug.ts

@@ -10,7 +10,7 @@ type CSSTarget =
   | 'all' // tasty CSS + tasty global CSS (createGlobalStyle)
   | 'global' // only tasty global CSS
   | 'active' // tasty CSS for classes currently in DOM
-  | 'cached' // tasty CSS present in sheets but not in DOM
+  | 'unused' // tasty CSS with refCount = 0 (still in cache but not actively used)
   | 'page' // ALL CSS on the page across stylesheets (not only tasty)
   | string // 't123' tasty class or a CSS selector
   | string[] // array of tasty classes like ['t1', 't2']
@@ -33,7 +33,6 @@ interface InspectResult {
 interface CacheMetrics {
   hits: number;
   misses: number;
-  unusedHits: number;
   bulkCleanups: number;
   totalInsertions: number;
   totalUnused: number;
@@ -45,12 +44,15 @@ interface CacheMetrics {
     rulesDeleted: number;
   }>;
   startTime: number;
+
+  // Calculated metrics
+  unusedHits?: number; // calculated as current unused count
 }
 
 interface CacheStatus {
   classes: {
-    active: string[]; // from DOM scan
-    cached: string[]; // present in sheets but not currently in DOM
+    active: string[]; // classes with refCount > 0 and present in DOM
+    unused: string[]; // classes with refCount = 0 but still in cache
     all: string[]; // union of both
   };
   metrics: CacheMetrics | null;
@@ -88,18 +90,18 @@ interface SummaryOptions {
 interface Summary {
   // Classes
   activeClasses: string[];
-  cachedClasses: string[];
+  unusedClasses: string[];
   totalStyledClasses: string[];
 
   // Tasty CSS sizes
   activeCSSSize: number;
-  cachedCSSSize: number;
-  totalCSSSize: number; // tasty-only: active + cached + tasty global
+  unusedCSSSize: number;
+  totalCSSSize: number; // tasty-only: active + unused + tasty global
 
   // Tasty CSS payloads
   activeCSS: string;
-  cachedCSS: string;
-  allCSS: string; // tasty-only CSS (active + cached + tasty global)
+  unusedCSS: string;
+  allCSS: string; // tasty-only CSS (active + unused + tasty global)
 
   // Tasty global (createGlobalStyle)
   globalCSS: string;
@@ -449,13 +451,21 @@ export const tastyDebug = {
       } else if (target === 'active') {
         const activeClasses = findAllTastyClasses(root);
         css = injector.instance.getCssTextForClasses(activeClasses, { root });
-      } else if (target === 'cached') {
-        const activeClasses = findAllTastyClasses(root);
-        const allClasses = findAllStyledClasses(root);
-        const cachedClasses = allClasses.filter(
-          (cls) => !activeClasses.includes(cls),
-        );
-        css = injector.instance.getCssTextForClasses(cachedClasses, { root });
+      } else if (target === 'unused') {
+        // Get unused classes (refCount = 0) from the registry
+        const registry = (injector.instance as any)[
+          'sheetManager'
+        ]?.getRegistry(root);
+        const unusedClasses: string[] = registry
+          ? Array.from(
+              registry.refCounts.entries() as IterableIterator<
+                [string, number]
+              >,
+            )
+              .filter(([, refCount]: [string, number]) => refCount === 0)
+              .map(([className]: [string, number]) => className)
+          : [];
+        css = injector.instance.getCssTextForClasses(unusedClasses, { root });
       } else if (target === 'page') {
         css = getPageCSS({ root, includeCrossOrigin: true });
       } else if (/^t\d+$/.test(target)) {
@@ -536,15 +546,23 @@ export const tastyDebug = {
     const { root = document } = opts || {};
     const activeClasses = findAllTastyClasses(root);
     const allClasses = findAllStyledClasses(root);
-    const cachedClasses = allClasses.filter(
-      (cls) => !activeClasses.includes(cls),
+    // Get unused classes (refCount = 0) from the registry
+    const registry = (injector.instance as any)['sheetManager']?.getRegistry(
+      root,
     );
+    const unusedClasses: string[] = registry
+      ? Array.from(
+          registry.refCounts.entries() as IterableIterator<[string, number]>,
+        )
+          .filter(([, refCount]: [string, number]) => refCount === 0)
+          .map(([className]: [string, number]) => className)
+      : [];
 
     return {
       classes: {
         active: activeClasses,
-        cached: cachedClasses,
-        all: allClasses,
+        unused: unusedClasses,
+        all: [...activeClasses, ...unusedClasses],
       },
       metrics: injector.instance.getMetrics({ root }),
     };
@@ -699,7 +717,7 @@ export const tastyDebug = {
     const metrics = this.metrics({ root });
 
     const activeCSS = this.css('active', { root, prettify: false });
-    const cachedCSS = this.css('cached', { root, prettify: false });
+    const unusedCSS = this.css('unused', { root, prettify: false });
     const allCSS = this.css('all', { root, prettify: false });
 
     // Build cleanup summary from metrics
@@ -754,13 +772,13 @@ export const tastyDebug = {
 
     const summary: Summary = {
       activeClasses: cacheStatus.classes.active,
-      cachedClasses: cacheStatus.classes.cached,
+      unusedClasses: cacheStatus.classes.unused,
       totalStyledClasses: cacheStatus.classes.all,
       activeCSSSize: activeCSS.length,
-      cachedCSSSize: cachedCSS.length,
+      unusedCSSSize: unusedCSS.length,
       totalCSSSize: allCSS.length,
       activeCSS: prettifyCSS(activeCSS),
-      cachedCSS: prettifyCSS(cachedCSS),
+      unusedCSS: prettifyCSS(unusedCSS),
       allCSS: prettifyCSS(allCSS),
       globalCSS: globalBreakdown.css,
       globalCSSSize: globalBreakdown.totalCSSSize,
@@ -781,14 +799,14 @@ export const tastyDebug = {
         `  • Active classes (in DOM): ${summary.activeClasses.length}`,
       );
       console.log(
-        `  • Cached classes (performance cache): ${summary.cachedClasses.length}`,
+        `  • Unused classes (refCount = 0): ${summary.unusedClasses.length}`,
       );
       console.log(
         `  • Total styled classes: ${summary.totalStyledClasses.length}`,
       );
       console.log(`💾 CSS Size:`);
       console.log(`  • Active CSS: ${summary.activeCSSSize} characters`);
-      console.log(`  • Cached CSS: ${summary.cachedCSSSize} characters`);
+      console.log(`  • Unused CSS: ${summary.unusedCSSSize} characters`);
       console.log(
         `  • Global CSS: ${summary.globalCSSSize} characters (${summary.globalRuleCount} rules)`,
       );
@@ -815,7 +833,7 @@ export const tastyDebug = {
         const hitRate =
           metrics.hits + metrics.misses > 0
             ? (
-                ((metrics.hits + metrics.unusedHits) /
+                ((metrics.hits + (metrics.unusedHits || 0)) /
                   (metrics.hits + metrics.misses)) *
                 100
               ).toFixed(1)
@@ -825,7 +843,7 @@ export const tastyDebug = {
 
       console.log('🔍 Details:');
       console.log('  • Active classes:', summary.activeClasses);
-      console.log('  • Cached classes:', summary.cachedClasses);
+      console.log('  • Unused classes:', summary.unusedClasses);
       console.groupEnd();
     }
 
@@ -984,7 +1002,7 @@ export const tastyDebug = {
     console.log('📖 Common targets for css()/log():');
     console.log('  • "all" - all tasty CSS + global CSS');
     console.log('  • "active" - CSS for classes in DOM');
-    console.log('  • "cached" - CSS for unused classes');
+    console.log('  • "unused" - CSS for classes with refCount = 0');
     console.log('  • "global" - only global CSS (createGlobalStyle)');
     console.log('  • "page" - ALL page CSS (including non-tasty)');
     console.log('  • "t123" - specific tasty class');

src/tasty/injector/index.ts

@@ -239,7 +239,6 @@ export type {
   KeyframesResult,
   KeyframesSteps,
   KeyframesCacheEntry,
-  UnusedRuleInfo,
   CacheMetrics,
 } from './types';