@cube-dev/ui-kit 0.74.3 → 0.76.0

package/es/tasty/debug.js

@@ -0,0 +1,703 @@
+/**
+ * @license MIT
+ * author: Cube Dev Team
+ * @cube-dev/ui-kit v0.76.0
+ * Released under the MIT license.
+ */
+
+/**
+ * Debug utilities for inspecting tasty-generated CSS at runtime
+ */
+import { getCssTextForNode, injector } from './injector';
+import { isDevEnv } from './utils/isDevEnv';
+/**
+ * Pretty-print CSS with proper indentation and formatting
+ */
+function prettifyCSS(css) {
+    if (!css || css.trim() === '') {
+        return '';
+    }
+    // First, normalize whitespace but preserve structure
+    let formatted = css.replace(/\s+/g, ' ').trim();
+    // Add newlines after opening braces
+    formatted = formatted.replace(/\s*\{\s*/g, ' {\n');
+    // Add newlines after semicolons (but not inside strings or functions)
+    formatted = formatted.replace(/;(?![^"']*["'][^"']*$)(?![^()]*\))/g, ';\n');
+    // Add newlines before closing braces
+    formatted = formatted.replace(/\s*\}\s*/g, '\n}\n');
+    // Handle comma-separated selectors (only outside of property values)
+    // This regex looks for commas that are:
+    // 1. Not inside quotes
+    // 2. Not inside parentheses (CSS functions)
+    // 3. Not followed by a colon (not in a property value)
+    formatted = formatted.replace(/,(?![^"']*["'][^"']*$)(?![^()]*\))(?=.*:.*\{|.*\{)/g, ',\n');
+    // Process line by line for proper indentation
+    const lines = formatted.split('\n');
+    let indentLevel = 0;
+    const indentSize = 2;
+    const formattedLines = lines.map((line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return '';
+        // Handle closing braces - decrease indent first
+        if (trimmed === '}') {
+            indentLevel = Math.max(0, indentLevel - 1);
+            return ' '.repeat(indentLevel * indentSize) + trimmed;
+        }
+        // Current line with proper indentation
+        const indent = ' '.repeat(indentLevel * indentSize);
+        let result = indent + trimmed;
+        // Handle opening braces - increase indent for next line
+        if (trimmed.endsWith('{')) {
+            indentLevel++;
+        }
+        return result;
+    });
+    // Clean up the result and ensure proper spacing
+    let result = formattedLines
+        .filter((line) => line.trim()) // Remove empty lines
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n') // Max 2 consecutive newlines
+        .trim();
+    // Final cleanup: ensure single spaces in function calls
+    result = result.replace(/,\s+/g, ', ');
+    return result;
+}
+// Helper functions
+function findAllTastyClasses(root = document) {
+    const classes = new Set();
+    const elements = root.querySelectorAll?.('[class]') || [];
+    elements.forEach((element) => {
+        const classList = element.getAttribute('class');
+        if (classList) {
+            const tastyClasses = classList
+                .split(/\s+/)
+                .filter((cls) => /^t\d+$/.test(cls));
+            tastyClasses.forEach((cls) => classes.add(cls));
+        }
+    });
+    return Array.from(classes).sort((a, b) => {
+        const aNum = parseInt(a.slice(1));
+        const bNum = parseInt(b.slice(1));
+        return aNum - bNum;
+    });
+}
+function findAllStyledClasses(root = document) {
+    // Extract tasty classes from all CSS text by parsing selectors
+    const allCSS = injector.instance.getCssText({ root });
+    const classes = new Set();
+    // Simple regex to find .t{number} class selectors
+    const classRegex = /\.t(\d+)/g;
+    let match;
+    while ((match = classRegex.exec(allCSS)) !== null) {
+        classes.add(`t${match[1]}`);
+    }
+    return Array.from(classes).sort((a, b) => {
+        const aNum = parseInt(a.slice(1));
+        const bNum = parseInt(b.slice(1));
+        return aNum - bNum;
+    });
+}
+function extractCSSRules(css) {
+    const rules = [];
+    // Remove comments
+    let cleanCSS = css.replace(/\/\*[\s\S]*?\*\//g, '');
+    let i = 0;
+    while (i < cleanCSS.length) {
+        // Skip whitespace
+        while (i < cleanCSS.length && /\s/.test(cleanCSS[i])) {
+            i++;
+        }
+        if (i >= cleanCSS.length)
+            break;
+        // Find selector start
+        const selectorStart = i;
+        let braceDepth = 0;
+        let inString = false;
+        let stringChar = '';
+        // Find opening brace
+        while (i < cleanCSS.length) {
+            const char = cleanCSS[i];
+            if (inString) {
+                if (char === stringChar && cleanCSS[i - 1] !== '\\') {
+                    inString = false;
+                }
+            }
+            else {
+                if (char === '"' || char === "'") {
+                    inString = true;
+                    stringChar = char;
+                }
+                else if (char === '{') {
+                    braceDepth++;
+                    if (braceDepth === 1)
+                        break;
+                }
+            }
+            i++;
+        }
+        if (i >= cleanCSS.length)
+            break;
+        const selector = cleanCSS.substring(selectorStart, i).trim();
+        i++; // Skip opening brace
+        // Find matching closing brace
+        const contentStart = i;
+        braceDepth = 1;
+        inString = false;
+        while (i < cleanCSS.length && braceDepth > 0) {
+            const char = cleanCSS[i];
+            if (inString) {
+                if (char === stringChar && cleanCSS[i - 1] !== '\\') {
+                    inString = false;
+                }
+            }
+            else {
+                if (char === '"' || char === "'") {
+                    inString = true;
+                    stringChar = char;
+                }
+                else if (char === '{') {
+                    braceDepth++;
+                }
+                else if (char === '}') {
+                    braceDepth--;
+                }
+            }
+            i++;
+        }
+        const content = cleanCSS.substring(contentStart, i - 1).trim();
+        if (content && selector) {
+            rules.push({ selector, declarations: content });
+        }
+    }
+    return rules;
+}
+function getGlobalCSS(root = document) {
+    const allCSS = injector.instance.getCssText({ root });
+    const rules = extractCSSRules(allCSS);
+    const globalRules = rules.filter((rule) => {
+        const selectors = rule.selector.split(',').map((s) => s.trim());
+        return !selectors.every((selector) => {
+            const cleanSelector = selector.replace(/[.#:\s>+~[\]()]/g, ' ');
+            const parts = cleanSelector.split(/\s+/).filter(Boolean);
+            return parts.length > 0 && parts.every((part) => /^t\d+$/.test(part));
+        });
+    });
+    const globalCSS = globalRules
+        .map((rule) => `${rule.selector} { ${rule.declarations} }`)
+        .join('\n');
+    return prettifyCSS(globalCSS);
+}
+function getPageCSS(options) {
+    const root = options?.root || document;
+    const includeCrossOrigin = options?.includeCrossOrigin ?? false;
+    const cssChunks = [];
+    try {
+        if ('styleSheets' in root) {
+            const styleSheets = Array.from(root.styleSheets);
+            for (const sheet of styleSheets) {
+                try {
+                    if (sheet.cssRules) {
+                        const rules = Array.from(sheet.cssRules);
+                        cssChunks.push(rules.map((rule) => rule.cssText).join('\n'));
+                    }
+                }
+                catch (e) {
+                    // Cross-origin sheet or other access error
+                    if (includeCrossOrigin) {
+                        cssChunks.push(`/* Cross-origin stylesheet: ${sheet.href || 'inline'} */`);
+                    }
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Fallback error handling
+    }
+    return cssChunks.join('\n');
+}
+function getPageStats(options) {
+    const root = options?.root || document;
+    const includeCrossOrigin = options?.includeCrossOrigin ?? false;
+    let cssSize = 0;
+    let ruleCount = 0;
+    let stylesheetCount = 0;
+    let skippedStylesheets = 0;
+    try {
+        if ('styleSheets' in root) {
+            const styleSheets = Array.from(root.styleSheets);
+            stylesheetCount = styleSheets.length;
+            for (const sheet of styleSheets) {
+                try {
+                    if (sheet.cssRules) {
+                        const rules = Array.from(sheet.cssRules);
+                        ruleCount += rules.length;
+                        cssSize += rules.reduce((sum, rule) => sum + rule.cssText.length, 0);
+                    }
+                }
+                catch (e) {
+                    skippedStylesheets++;
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Fallback error handling
+    }
+    return { cssSize, ruleCount, stylesheetCount, skippedStylesheets };
+}
+/**
+ * Concise tastyDebug API for inspecting styles at runtime
+ */
+export const tastyDebug = {
+    // 1) One function to get CSS from anywhere
+    css(target, opts) {
+        const { root = document, prettify = true, log = false } = opts || {};
+        let css = '';
+        if (typeof target === 'string') {
+            if (target === 'all') {
+                css = injector.instance.getCssText({ root });
+            }
+            else if (target === 'global') {
+                css = getGlobalCSS(root);
+            }
+            else if (target === 'active') {
+                const activeClasses = findAllTastyClasses(root);
+                css = injector.instance.getCssTextForClasses(activeClasses, { root });
+            }
+            else if (target === 'unused') {
+                // Get unused classes (refCount = 0) from the registry
+                const registry = injector.instance['sheetManager']?.getRegistry(root);
+                const unusedClasses = registry
+                    ? Array.from(registry.refCounts.entries())
+                        .filter(([, refCount]) => refCount === 0)
+                        .map(([className]) => className)
+                    : [];
+                css = injector.instance.getCssTextForClasses(unusedClasses, { root });
+            }
+            else if (target === 'page') {
+                css = getPageCSS({ root, includeCrossOrigin: true });
+            }
+            else if (/^t\d+$/.test(target)) {
+                // Single tasty class
+                css = injector.instance.getCssTextForClasses([target], { root });
+            }
+            else {
+                // CSS selector - find element and get its CSS
+                const element = root.querySelector?.(target);
+                if (element) {
+                    css = getCssTextForNode(element, { root });
+                }
+            }
+        }
+        else if (Array.isArray(target)) {
+            // Array of tasty classes
+            css = injector.instance.getCssTextForClasses(target, { root });
+        }
+        else if (target instanceof Element) {
+            // DOM element
+            css = getCssTextForNode(target, { root });
+        }
+        const result = prettify ? prettifyCSS(css) : css;
+        if (log) {
+            console.group(`🎨 CSS for ${Array.isArray(target) ? `[${target.join(', ')}]` : target}`);
+            console.log(result || '(empty)');
+            console.groupEnd();
+        }
+        return result;
+    },
+    // 2) Element-level inspection
+    inspect(target, opts) {
+        const { root = document } = opts || {};
+        const element = typeof target === 'string'
+            ? root.querySelector?.(target)
+            : target;
+        if (!element) {
+            return {
+                element: null,
+                classes: [],
+                css: '',
+                size: 0,
+                rules: 0,
+            };
+        }
+        const classList = element.getAttribute('class') || '';
+        const tastyClasses = classList
+            .split(/\s+/)
+            .filter((cls) => /^t\d+$/.test(cls));
+        const css = getCssTextForNode(element, { root });
+        const prettifiedCSS = prettifyCSS(css);
+        const ruleCount = (css.match(/\{[^}]*\}/g) || []).length;
+        return {
+            element,
+            classes: tastyClasses,
+            css: prettifiedCSS,
+            size: css.length,
+            rules: ruleCount,
+        };
+    },
+    // 3) Cache + metrics at a glance
+    cache(opts) {
+        const { root = document } = opts || {};
+        const activeClasses = findAllTastyClasses(root);
+        const allClasses = findAllStyledClasses(root);
+        // Get unused classes (refCount = 0) from the registry
+        const registry = injector.instance['sheetManager']?.getRegistry(root);
+        const unusedClasses = registry
+            ? Array.from(registry.refCounts.entries())
+                .filter(([, refCount]) => refCount === 0)
+                .map(([className]) => className)
+            : [];
+        return {
+            classes: {
+                active: activeClasses,
+                unused: unusedClasses,
+                all: [...activeClasses, ...unusedClasses],
+            },
+            metrics: injector.instance.getMetrics({ root }),
+        };
+    },
+    // 4) Cleanup + metrics utilities
+    cleanup(opts) {
+        const { root } = opts || {};
+        injector.instance.cleanup(root);
+    },
+    metrics(opts) {
+        const { root } = opts || {};
+        return injector.instance.getMetrics({ root });
+    },
+    resetMetrics(opts) {
+        const { root } = opts || {};
+        injector.instance.resetMetrics({ root });
+    },
+    // 5) Tasty global CSS and selector analysis
+    global(opts) {
+        const { root = document, log = false } = opts || {};
+        const css = getGlobalCSS(root);
+        const rules = extractCSSRules(css);
+        // Analyze selectors
+        const selectors = {
+            elements: [],
+            classes: [],
+            ids: [],
+            pseudoClasses: [],
+            mediaQueries: [],
+            keyframes: [],
+            other: [],
+        };
+        rules.forEach((rule) => {
+            const selector = rule.selector;
+            if (selector.startsWith('@media')) {
+                selectors.mediaQueries.push(selector);
+            }
+            else if (selector.startsWith('@keyframes')) {
+                selectors.keyframes.push(selector);
+            }
+            else if (selector.includes('.') &&
+                !selector.includes('#') &&
+                !selector.includes(':')) {
+                selectors.classes.push(selector);
+            }
+            else if (selector.includes('#') &&
+                !selector.includes('.') &&
+                !selector.includes(':')) {
+                selectors.ids.push(selector);
+            }
+            else if (selector.includes(':')) {
+                selectors.pseudoClasses.push(selector);
+            }
+            else if (/^[a-zA-Z][a-zA-Z0-9]*$/.test(selector.trim())) {
+                selectors.elements.push(selector);
+            }
+            else {
+                selectors.other.push(selector);
+            }
+        });
+        const result = {
+            css,
+            totalRules: rules.length,
+            totalCSSSize: css.length,
+            selectors,
+        };
+        if (log) {
+            console.group(`🌍 Global CSS (${result.totalRules} rules)`);
+            console.log(`📊 Size: ${result.totalCSSSize} characters`);
+            console.log('🎯 Selector breakdown:', result.selectors);
+            console.log('🎨 CSS:\n' + result.css);
+            console.groupEnd();
+        }
+        return result;
+    },
+    // 6) Defined @property and keyframes
+    defs(opts) {
+        const { root = document } = opts || {};
+        // Get properties from injector if available, otherwise scan CSS
+        let properties = [];
+        try {
+            const registry = injector.instance['sheetManager']?.getRegistry(root);
+            if (registry?.injectedProperties) {
+                properties = Array.from(registry.injectedProperties).sort();
+            }
+        }
+        catch {
+            // Fallback: scan CSS for @property rules
+            const allCSS = injector.instance.getCssText({ root });
+            const propRegex = /@property\s+(--[a-z0-9-]+)/gi;
+            const propSet = new Set();
+            let match;
+            while ((match = propRegex.exec(allCSS)) !== null) {
+                propSet.add(match[1]);
+            }
+            properties = Array.from(propSet).sort();
+        }
+        // Get keyframes
+        let keyframes = [];
+        try {
+            const registry = injector.instance['sheetManager']?.getRegistry(root);
+            if (registry) {
+                for (const entry of registry.keyframesCache.values()) {
+                    keyframes.push({
+                        name: entry.name,
+                        refCount: entry.refCount,
+                    });
+                }
+                keyframes.sort((a, b) => a.name.localeCompare(b.name));
+            }
+        }
+        catch {
+            // Fallback: scan CSS for @keyframes rules
+            const allCSS = injector.instance.getCssText({ root });
+            const keyframesRegex = /@keyframes\s+([a-zA-Z0-9_-]+)/gi;
+            const keyframesSet = new Set();
+            let match;
+            while ((match = keyframesRegex.exec(allCSS)) !== null) {
+                keyframesSet.add(match[1]);
+            }
+            keyframes = Array.from(keyframesSet)
+                .sort()
+                .map((name) => ({ name, refCount: 1 }));
+        }
+        return { properties, keyframes };
+    },
+    // 7) One-shot overview
+    summary(opts) {
+        const { root = document, log = false, includePageCSS = false } = opts || {};
+        const cacheStatus = this.cache({ root });
+        const globalBreakdown = this.global({ root });
+        const definitions = this.defs({ root });
+        const metrics = this.metrics({ root });
+        const activeCSS = this.css('active', { root, prettify: false });
+        const unusedCSS = this.css('unused', { root, prettify: false });
+        const allCSS = this.css('all', { root, prettify: false });
+        // Build cleanup summary from metrics
+        const cleanupSummary = {
+            enabled: !!metrics,
+            totalCleanups: metrics?.cleanupHistory?.length || 0,
+            totalClassesDeleted: metrics?.cleanupHistory?.reduce((sum, c) => sum + c.classesDeleted, 0) || 0,
+            totalCssDeleted: metrics?.cleanupHistory?.reduce((sum, c) => sum + c.cssSize, 0) || 0,
+            totalRulesDeleted: metrics?.cleanupHistory?.reduce((sum, c) => sum + c.rulesDeleted, 0) ||
+                0,
+            averageClassesPerCleanup: 0,
+            averageCssPerCleanup: 0,
+            averageRulesPerCleanup: 0,
+            lastCleanup: undefined,
+        };
+        if (cleanupSummary.totalCleanups > 0) {
+            cleanupSummary.averageClassesPerCleanup =
+                cleanupSummary.totalClassesDeleted / cleanupSummary.totalCleanups;
+            cleanupSummary.averageCssPerCleanup =
+                cleanupSummary.totalCssDeleted / cleanupSummary.totalCleanups;
+            cleanupSummary.averageRulesPerCleanup =
+                cleanupSummary.totalRulesDeleted / cleanupSummary.totalCleanups;
+            const lastCleanup = metrics?.cleanupHistory?.[metrics.cleanupHistory.length - 1];
+            if (lastCleanup) {
+                cleanupSummary.lastCleanup = {
+                    ...lastCleanup,
+                    date: new Date(lastCleanup.timestamp).toISOString(),
+                };
+            }
+        }
+        let page;
+        if (includePageCSS) {
+            const pageStats = getPageStats({ root, includeCrossOrigin: true });
+            page = {
+                ...pageStats,
+                css: includePageCSS === 'all'
+                    ? getPageCSS({ root, includeCrossOrigin: true })
+                    : undefined,
+            };
+        }
+        const summary = {
+            activeClasses: cacheStatus.classes.active,
+            unusedClasses: cacheStatus.classes.unused,
+            totalStyledClasses: cacheStatus.classes.all,
+            activeCSSSize: activeCSS.length,
+            unusedCSSSize: unusedCSS.length,
+            totalCSSSize: allCSS.length,
+            activeCSS: prettifyCSS(activeCSS),
+            unusedCSS: prettifyCSS(unusedCSS),
+            allCSS: prettifyCSS(allCSS),
+            globalCSS: globalBreakdown.css,
+            globalCSSSize: globalBreakdown.totalCSSSize,
+            globalRuleCount: globalBreakdown.totalRules,
+            page,
+            metrics,
+            definedProperties: definitions.properties,
+            definedKeyframes: definitions.keyframes,
+            propertyCount: definitions.properties.length,
+            keyframeCount: definitions.keyframes.length,
+            cleanupSummary,
+        };
+        if (log) {
+            console.group('🎨 Comprehensive Tasty Debug Summary');
+            console.log(`📊 Style Cache Status:`);
+            console.log(`  • Active classes (in DOM): ${summary.activeClasses.length}`);
+            console.log(`  • 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(`  • Unused CSS: ${summary.unusedCSSSize} characters`);
+            console.log(`  • Global CSS: ${summary.globalCSSSize} characters (${summary.globalRuleCount} rules)`);
+            console.log(`  • Total CSS: ${summary.totalCSSSize} characters`);
+            if (page) {
+                console.log(`📄 Page CSS:`);
+                console.log(`  • Total page CSS: ${page.cssSize} characters`);
+                console.log(`  • Total page rules: ${page.ruleCount}`);
+                console.log(`  • Stylesheets: ${page.stylesheetCount} (${page.skippedStylesheets} skipped)`);
+            }
+            console.log('🏷️ Properties & Keyframes:');
+            console.log(`  • Defined @property: ${summary.propertyCount}`);
+            console.log(`  • Defined @keyframes: ${summary.keyframeCount}`);
+            if (metrics) {
+                console.log(`⚡ Performance Metrics:`);
+                console.log(`  • Cache hits: ${metrics.hits}`);
+                console.log(`  • Cache misses: ${metrics.misses}`);
+                console.log(`  • Cached style reuses: ${metrics.unusedHits}`);
+                const hitRate = metrics.hits + metrics.misses > 0
+                    ? (((metrics.hits + (metrics.unusedHits || 0)) /
+                        (metrics.hits + metrics.misses)) *
+                        100).toFixed(1)
+                    : '0';
+                console.log(`  • Overall cache hit rate: ${hitRate}%`);
+            }
+            console.log('🔍 Details:');
+            console.log('  • Active classes:', summary.activeClasses);
+            console.log('  • Unused classes:', summary.unusedClasses);
+            console.groupEnd();
+        }
+        return summary;
+    },
+    // 8) Page-level CSS helpers
+    pageCSS(opts) {
+        const { root = document, prettify = true, log = false, includeCrossOrigin = true, } = opts || {};
+        const css = getPageCSS({ root, includeCrossOrigin });
+        const result = prettify ? prettifyCSS(css) : css;
+        if (log) {
+            console.group('📄 Page CSS (All Stylesheets)');
+            console.log(result || '(empty)');
+            console.groupEnd();
+        }
+        return result;
+    },
+    pageStats(opts) {
+        const { root = document, includeCrossOrigin = true } = opts || {};
+        return getPageStats({ root, includeCrossOrigin });
+    },
+    // 9) Install globally
+    install() {
+        if (typeof window !== 'undefined' &&
+            window.tastyDebug !== tastyDebug) {
+            window.tastyDebug = tastyDebug;
+            console.log('🎨 tastyDebug installed on window. Run tastyDebug.help() for quick start guide.');
+        }
+    },
+    // 10) Beautiful console logging with collapsible CSS
+    log(target, opts) {
+        const { title, ...cssOpts } = opts || {};
+        const css = tastyDebug.css(target, cssOpts);
+        if (!css.trim()) {
+            console.warn(`🎨 No CSS found for target: ${String(target)}`);
+            return;
+        }
+        const targetStr = Array.isArray(target)
+            ? target.join(', ')
+            : String(target);
+        const displayTitle = title || `CSS for "${targetStr}"`;
+        // Get some stats about the CSS
+        const lines = css.split('\n').length;
+        const size = new Blob([css]).size;
+        const sizeStr = size > 1024 ? `${(size / 1024).toFixed(1)}KB` : `${size}B`;
+        // Count CSS rules (blocks with opening braces)
+        const ruleCount = (css.match(/\{/g) || []).length;
+        console.group(`🎨 ${displayTitle} (${ruleCount} rules, ${lines} lines, ${sizeStr})`);
+        // Detect sub-elements in CSS
+        const subElementMatches = css.match(/\[data-element="([^"]+)"\]/g) || [];
+        const subElements = [
+            ...new Set(subElementMatches
+                .map((match) => match.match(/\[data-element="([^"]+)"\]/)?.[1])
+                .filter(Boolean)),
+        ];
+        if (subElements.length > 0) {
+            console.log(`🧩 Sub-elements found: ${subElements.join(', ')}`);
+            // Show stats and CSS for each sub-element
+            subElements.forEach((element) => {
+                const elementSelector = `[data-element="${element}"]`;
+                const elementRegex = new RegExp(`[^}]*\\[data-element="${element.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"\\][^{]*\\{[^}]*\\}`, 'gm');
+                const elementCSS = (css.match(elementRegex) || []).join('\n');
+                if (elementCSS) {
+                    const elementRules = (elementCSS.match(/\{/g) || []).length;
+                    const elementLines = elementCSS.split('\n').length;
+                    const elementSize = new Blob([elementCSS]).size;
+                    const elementSizeStr = elementSize > 1024
+                        ? `${(elementSize / 1024).toFixed(1)}KB`
+                        : `${elementSize}B`;
+                    console.groupCollapsed(`🧩 ${element} (${elementRules} rules, ${elementLines} lines, ${elementSizeStr})`);
+                    console.log(`%c${elementCSS}`, 'color: #666; font-family: monospace; font-size: 12px; white-space: pre;');
+                    console.groupEnd();
+                }
+            });
+        }
+        // Full CSS in collapsible group (hidden by default)
+        console.groupCollapsed('📄 Full CSS (click to expand)');
+        console.log(`%c${css}`, 'color: #666; font-family: monospace; font-size: 12px; white-space: pre;');
+        console.groupEnd();
+        console.groupEnd();
+    },
+    // 11) Show help and usage examples
+    help() {
+        console.group('🎨 tastyDebug - Quick Start Guide');
+        console.log('💡 Essential commands:');
+        console.log('  • tastyDebug.summary({ log: true }) - comprehensive overview');
+        console.log('  • tastyDebug.log("active") - beautiful CSS display');
+        console.log('  • tastyDebug.css("active") - get active CSS');
+        console.log('  • tastyDebug.inspect(".my-element") - detailed element inspection');
+        console.log('  • tastyDebug.global({ log: true }) - global CSS analysis');
+        console.log('  • tastyDebug.cache() - cache status');
+        console.log('  • tastyDebug.defs() - defined properties & keyframes');
+        console.log('  • tastyDebug.pageCSS({ log: true }) - all page CSS');
+        console.log('');
+        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('  • "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');
+        console.log('  • [".my-selector"] - CSS selector');
+        console.log('');
+        console.log('🔧 Available options:');
+        console.log('  • { log: true } - auto-log results to console');
+        console.log('  • { title: "Custom" } - custom title for log()');
+        console.log('  • { root: shadowRoot } - target Shadow DOM');
+        console.log('  • { prettify: false } - skip CSS formatting');
+        console.groupEnd();
+    },
+};
+/**
+ * Auto-install in development
+ */
+if (typeof window !== 'undefined' && isDevEnv()) {
+    tastyDebug.install();
+}
+
+