@schemyx/mcp 0.1.1 → 0.1.2

package/dist/codebase-scanner/extractors.js

@@ -25,6 +25,7 @@ exports.extractModelFields = extractModelFields;
 exports.extractCssVariables = extractCssVariables;
 exports.extractCssVariableValues = extractCssVariableValues;
 exports.extractCssRules = extractCssRules;
+exports.extractCssAtRuleBlocks = extractCssAtRuleBlocks;
 exports.extractCssClasses = extractCssClasses;
 exports.extractCssIds = extractCssIds;
 exports.extractCssVariableReferences = extractCssVariableReferences;
@@ -43,6 +44,9 @@ exports.readBalancedRange = readBalancedRange;
 exports.skipQuoted = skipQuoted;
 exports.isInsideQuotedString = isInsideQuotedString;
 exports.extractClassListsFromStrings = extractClassListsFromStrings;
+exports.readPrimaryClassHelperUsage = readPrimaryClassHelperUsage;
+exports.readClassHelperUsages = readClassHelperUsages;
+exports.parseHelperVariantProps = parseHelperVariantProps;
 exports.analyzeClassSource = analyzeClassSource;
 exports.toClassSourceAnalysis = toClassSourceAnalysis;
 exports.isConditionalClassLiteral = isConditionalClassLiteral;
@@ -86,9 +90,20 @@ exports.isCompositionElement = isCompositionElement;
 exports.filterClasses = filterClasses;
 exports.isResponsiveClass = isResponsiveClass;
 exports.isSpacingClass = isSpacingClass;
+exports.isLayoutClass = isLayoutClass;
 exports.isSurfaceClass = isSurfaceClass;
 exports.isDecorativeAccentClass = isDecorativeAccentClass;
 exports.isTypographyClass = isTypographyClass;
+exports.isTypographyScaleBase = isTypographyScaleBase;
+exports.isLayoutSafetyBase = isLayoutSafetyBase;
+exports.isSizingClass = isSizingClass;
+exports.isVisibilityClass = isVisibilityClass;
+exports.isLineHeightClass = isLineHeightClass;
+exports.isMaxWidthClass = isMaxWidthClass;
+exports.createUiLayoutSafety = createUiLayoutSafety;
+exports.createUiResponsiveProfile = createUiResponsiveProfile;
+exports.createUiScaleProfile = createUiScaleProfile;
+exports.responsivePrefix = responsivePrefix;
 exports.groupClassExpressionsByTarget = groupClassExpressionsByTarget;
 exports.buildComponentSlots = buildComponentSlots;
 exports.createUiCompositionGuidance = createUiCompositionGuidance;
@@ -97,6 +112,28 @@ exports.extractTailwindUtilities = extractTailwindUtilities;
 exports.extractPackageDependencies = extractPackageDependencies;
 exports.extractUiElements = extractUiElements;
 exports.summarizeDirectUiChildren = summarizeDirectUiChildren;
+exports.createUiSemanticProfile = createUiSemanticProfile;
+exports.createUiRoleSignature = createUiRoleSignature;
+exports.exactRoleClassFacts = exactRoleClassFacts;
+exports.createRoleScaleKey = createRoleScaleKey;
+exports.createRoleDensityKey = createRoleDensityKey;
+exports.createRoleSurfaceKey = createRoleSurfaceKey;
+exports.createRoleLayoutKey = createRoleLayoutKey;
+exports.isCompactHeroEyebrow = isCompactHeroEyebrow;
+exports.isOverlayPill = isOverlayPill;
+exports.isHeroHeadingScale = isHeroHeadingScale;
+exports.isOversizedHeadingScale = isOversizedHeadingScale;
+exports.isMetricValueScale = isMetricValueScale;
+exports.isCompactStatValue = isCompactStatValue;
+exports.isLargeMetricValue = isLargeMetricValue;
+exports.isCompactStatCard = isCompactStatCard;
+exports.isInteractiveServiceCard = isInteractiveServiceCard;
+exports.isStaticArticleCard = isStaticArticleCard;
+exports.isMediaPanelCard = isMediaPanelCard;
+exports.isQuietAction = isQuietAction;
+exports.isCompactAction = isCompactAction;
+exports.roleClassSort = roleClassSort;
+exports.deriveUiChildSemanticRole = deriveUiChildSemanticRole;
 exports.deriveLayoutRole = deriveLayoutRole;
 exports.isStateClass = isStateClass;
 exports.extractApiCalls = extractApiCalls;
@@ -150,6 +187,8 @@ exports.styleConfidenceForFile = styleConfidenceForFile;
 exports.entryMatchesConcept = entryMatchesConcept;
 exports.splitClassList = splitClassList;
 exports.classifyUiElement = classifyUiElement;
+exports.looksLikeSurfaceContainer = looksLikeSurfaceContainer;
+exports.looksLikePillBadge = looksLikePillBadge;
 exports.stripTags = stripTags;
 const path = require("node:path");
 const constants_1 = require("./constants");
@@ -562,7 +601,13 @@ function extractCssRules(content, relPath) {
         return [];
     }
     const rules = [];
+    const mediaBlocks = extractCssAtRuleBlocks(content, 'media');
+    const mediaRanges = mediaBlocks.map((block) => ({ start: block.start, end: block.end }));
     for (const match of content.matchAll(/([^{}@][^{}]{0,240})\{([^{}]{1,2400})\}/g)) {
+        const matchIndex = match.index ?? 0;
+        if (mediaRanges.some((range) => matchIndex >= range.start && matchIndex <= range.end)) {
+            continue;
+        }
         const selector = match[1].trim().replace(/\s+/g, ' ');
         if (!selector || selector.includes(';') || selector.startsWith('import')) {
             continue;
@@ -577,7 +622,59 @@ function extractCssRules(content, relPath) {
             line: (0, utils_1.lineNumberAt)(content, match.index ?? 0),
         });
     }
-    return (0, utils_1.uniqueBy)(rules, (rule) => `${rule.selector}:${rule.line}`).slice(0, 200);
+    for (const block of mediaBlocks) {
+        for (const match of block.body.matchAll(/([^{}@][^{}]{0,240})\{([^{}]{1,2400})\}/g)) {
+            const selector = match[1].trim().replace(/\s+/g, ' ');
+            if (!selector || selector.includes(';') || selector.startsWith('import')) {
+                continue;
+            }
+            const declarations = parseCssDeclarations(match[2]).slice(0, 40);
+            if (!declarations.length) {
+                continue;
+            }
+            rules.push({
+                selector,
+                declarations,
+                line: (0, utils_1.lineNumberAt)(content, block.bodyStart + (match.index ?? 0)),
+                media: block.prelude,
+            });
+        }
+    }
+    return (0, utils_1.uniqueBy)(rules, (rule) => `${rule.selector}:${rule.line}:${rule.media ?? ''}`).slice(0, 320);
+}
+function extractCssAtRuleBlocks(content, atRule) {
+    const blocks = [];
+    const pattern = new RegExp(`@${atRule}\\s+([^{}]+)\\{`, 'g');
+    for (const match of content.matchAll(pattern)) {
+        const start = match.index ?? 0;
+        const openIndex = start + match[0].length - 1;
+        let depth = 0;
+        let end = -1;
+        for (let cursor = openIndex; cursor < content.length; cursor += 1) {
+            const char = content[cursor];
+            if (char === '{') {
+                depth += 1;
+            }
+            else if (char === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    end = cursor;
+                    break;
+                }
+            }
+        }
+        if (end <= openIndex) {
+            continue;
+        }
+        blocks.push({
+            prelude: match[1].trim().replace(/\s+/g, ' '),
+            body: content.slice(openIndex + 1, end),
+            start,
+            end,
+            bodyStart: openIndex + 1,
+        });
+    }
+    return blocks;
 }
 function extractCssClasses(content) {
     return (0, utils_1.unique)(Array.from(content.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]+)\b/g)).map((match) => match[1])).slice(0, 80);
@@ -617,6 +714,7 @@ function extractClassExpressions(content) {
             const classValue = match[2] ?? match[1] ?? '';
             const classes = splitClassList(classValue);
             if (classes.length) {
+                const helperUsage = readPrimaryClassHelperUsage(classValue);
                 const analysis = analyzeClassSource(classValue);
                 expressions.push({
                     kind: 'attribute',
@@ -626,6 +724,10 @@ function extractClassExpressions(content) {
                     conditionalClasses: analysis.conditionalClasses,
                     line: (0, utils_1.lineNumberAt)(content, match.index ?? 0),
                     target: readTagBefore(content, match.index ?? 0),
+                    ...(helperUsage ? { styleHelper: helperUsage.name } : {}),
+                    ...(helperUsage && Object.keys(helperUsage.variantProps).length
+                        ? { styleHelperVariants: helperUsage.variantProps }
+                        : {}),
                 });
             }
         }
@@ -642,7 +744,8 @@ function extractClassExpressions(content) {
             }
             const analysis = analyzeClassSource(call);
             const classes = analysis.classes;
-            if (classes.length) {
+            const helperUsage = readPrimaryClassHelperUsage(call);
+            if (classes.length || helperUsage) {
                 expressions.push({
                     kind: helperName === 'cva' ? 'variant-definition' : 'helper',
                     raw: (0, utils_1.truncate)(call, 900),
@@ -651,10 +754,44 @@ function extractClassExpressions(content) {
                     conditionalClasses: analysis.conditionalClasses,
                     line: (0, utils_1.lineNumberAt)(content, match.index ?? 0),
                     target: helperName,
+                    ...(helperUsage ? { styleHelper: helperUsage.name } : {}),
+                    ...(helperUsage && Object.keys(helperUsage.variantProps).length
+                        ? { styleHelperVariants: helperUsage.variantProps }
+                        : {}),
                 });
             }
         }
     }
+    for (const match of content.matchAll(/\b([A-Za-z_$][\w$]*(?:Variants?|ClassNames?|Styles?))\s*\(/g)) {
+        const helperName = match[1];
+        if (/^(?:cn|clsx|classNames|twMerge|cva)$/i.test(helperName)) {
+            continue;
+        }
+        if (isInsideQuotedString(content, match.index ?? 0)) {
+            continue;
+        }
+        const call = readBalancedCall(content, match.index ?? 0);
+        if (!call) {
+            continue;
+        }
+        const helperUsage = readPrimaryClassHelperUsage(call);
+        if (!helperUsage) {
+            continue;
+        }
+        expressions.push({
+            kind: 'helper',
+            raw: (0, utils_1.truncate)(call, 900),
+            classes: [],
+            defaultClasses: [],
+            conditionalClasses: [],
+            line: (0, utils_1.lineNumberAt)(content, match.index ?? 0),
+            target: helperName,
+            styleHelper: helperUsage.name,
+            ...(Object.keys(helperUsage.variantProps).length
+                ? { styleHelperVariants: helperUsage.variantProps }
+                : {}),
+        });
+    }
     for (const match of content.matchAll(/(["'`])([^"'`]{5,900})\1/g)) {
         const classes = splitClassList(match[2]);
         if (classes.length >= 2 && looksLikeClassList(classes)) {
@@ -920,6 +1057,56 @@ function isInsideQuotedString(content, targetIndex) {
 function extractClassListsFromStrings(source) {
     return analyzeClassSource(source).classes;
 }
+function readPrimaryClassHelperUsage(source) {
+    const usages = readClassHelperUsages(source);
+    return (usages.find((usage) => /button|cta|action/i.test(usage.name)) ??
+        usages.find((usage) => Object.keys(usage.variantProps).length > 0) ??
+        usages[0]);
+}
+function readClassHelperUsages(source) {
+    const usages = [];
+    const helperPattern = /\b([A-Za-z_$][\w$]*(?:Variants?|ClassNames?|Styles?))\s*\(/g;
+    for (const match of source.matchAll(helperPattern)) {
+        const name = match[1];
+        if (/^(?:cn|clsx|classNames|twMerge|cva)$/i.test(name)) {
+            continue;
+        }
+        const call = readBalancedCall(source, match.index ?? 0);
+        if (!call) {
+            continue;
+        }
+        usages.push({
+            name,
+            variantProps: parseHelperVariantProps(call),
+            call: (0, utils_1.truncate)(call, 700),
+        });
+    }
+    return (0, utils_1.uniqueBy)(usages, (usage) => `${usage.name}:${JSON.stringify(usage.variantProps)}`).slice(0, 12);
+}
+function parseHelperVariantProps(call) {
+    const props = {};
+    const openIndex = call.indexOf('{');
+    if (openIndex < 0) {
+        return props;
+    }
+    const block = readBalancedBlock(call, openIndex);
+    if (!block) {
+        return props;
+    }
+    for (const entry of parseTopLevelObjectEntries(block)) {
+        const literalValues = readStringLiterals(entry.rawValue)
+            .map((value) => value.trim())
+            .filter(Boolean)
+            .slice(0, 4);
+        const value = literalValues.length > 1
+            ? literalValues.join('|')
+            : (literalValues[0] ?? cleanupBareValue(entry.rawValue));
+        if (value) {
+            props[entry.key] = value;
+        }
+    }
+    return props;
+}
 function analyzeClassSource(source) {
     const classes = new Set();
     const defaultClasses = new Set();
@@ -992,7 +1179,8 @@ function directClassCandidate(source) {
         return undefined;
     }
     const withoutTemplateExpressions = trimmed.replace(/\$\{[\s\S]*?\}/g, ' ');
-    if (/[{}"'`,;]/.test(withoutTemplateExpressions)) {
+    const withoutArbitraryValues = withoutTemplateExpressions.replace(/\[[^\]]+\]/g, '[arbitrary]');
+    if (/[{}"'`,;]/.test(withoutArbitraryValues)) {
         return undefined;
     }
     return withoutTemplateExpressions;
@@ -1010,6 +1198,7 @@ function looksLikeClassList(classes) {
 function isLikelyStyleClass(className) {
     const base = className.split(':').pop() ?? className;
     return (/^(?:-?m[trblxy]?|-?p[trblxy]?|flex|grid|block|inline|hidden|items-|justify-|content-|self-|gap-|space-|w-|h-|min-|max-|size-|rounded|border|bg-|from-|via-|to-|text-|font-|leading-|tracking-|shadow|ring|outline|opacity|transition|duration|ease|animate-|hover|focus|active|disabled|dark|sm|md|lg|xl|2xl|container|sr-only|absolute|relative|fixed|sticky|inset-|top-|right-|bottom-|left-|z-|overflow-|object-|aspect-|backdrop-|blur|scale-|translate-|rotate-)/.test(className) ||
+        /^(?:btn(?:-.+)?|card(?:-.+)?|badge(?:-.+)?|form(?:-.+)?|input-group(?:-.+)?|navbar(?:-.+)?|nav(?:-.+)?|row|col(?:-.+)?|container(?:-.+)?|d-(?:sm-|md-|lg-|xl-|xxl-)?|justify-content-|align-items-|align-self-|fw-|fs-|lh-|display-|lead|small|list-group(?:-.+)?|modal(?:-.+)?|alert(?:-.+)?|rounded-(?:pill|circle|\d)|shadow(?:-.+)?|w-\d+|h-\d+|mw-\d+|mh-\d+|min-vh-|min-vw-|vw-|vh-)/.test(className) ||
         /^(?:button|btn|card|panel|surface|badge|pill|chip|nav|field|input|dialog|modal|drawer|sheet|container|wrapper|section|hero|header|footer|sidebar|menu)$/.test(base) ||
         className.includes('[') ||
         className.includes(']'));
@@ -1468,22 +1657,28 @@ function groupTailwindClasses(classes) {
                 addClassGroup(groups, 'state', className);
             }
         }
-        if (/^(flex|grid|block|inline|hidden|items-|justify-|content-|self-|place-|order-|col-|row-)/.test(base)) {
+        if (/^(flex|grid|block|inline|hidden|items-|justify-|content-|self-|place-|order-|col-|row-|container|d-|justify-content-|align-items-|align-self-)/.test(base)) {
             addClassGroup(groups, 'layout', className);
         }
         else if (/^(?:-?m[trblxy]?|-?p[trblxy]?|gap-|space-|inset-|top-|right-|bottom-|left-)/.test(base)) {
             addClassGroup(groups, 'spacing', className);
         }
-        else if (/^(w-|h-|min-|max-|size-|aspect-|basis-|grow|shrink)/.test(base)) {
+        else if (/^(w-|h-|mw-|mh-|vw-|vh-|min-|max-|size-|aspect-|basis-|grow|shrink)/.test(base)) {
             addClassGroup(groups, 'sizing', className);
         }
+        else if (isTypographyScaleBase(base)) {
+            addClassGroup(groups, 'typography', className);
+        }
+        else if (isLayoutSafetyBase(base)) {
+            addClassGroup(groups, 'layout-safety', className);
+        }
         else if (/^(bg-|from-|via-|to-|text-|decoration-|accent-|caret-|fill-|stroke-)/.test(base)) {
             addClassGroup(groups, 'color', className);
         }
         else if (/^(rounded|border|divide-|outline|ring)/.test(base)) {
             addClassGroup(groups, 'border', className);
         }
-        else if (/^(font-|text-|leading-|tracking-|line-clamp|list-|whitespace-|break-|truncate)/.test(base)) {
+        else if (/^(list-)/.test(base)) {
             addClassGroup(groups, 'typography', className);
         }
         else if (/^(shadow|opacity|blur|backdrop|mix-|bg-blend|drop-shadow|filter)/.test(base)) {
@@ -1542,12 +1737,17 @@ function filterClasses(classes, predicate) {
     return (0, utils_1.unique)(classes.filter(predicate));
 }
 function isResponsiveClass(className) {
-    return /^(?:sm|md|lg|xl|2xl|max-|min-):/.test(className);
+    return (/^(?:sm|md|lg|xl|2xl|min-[^:]+|max-[^:]+):/.test(className) ||
+        /^(?:d|col|offset|order|m[stebxy]?|p[stebxy]?|gap|text|float|flex|justify-content|align-items|align-self)-(?:sm|md|lg|xl|xxl)-/.test(className));
 }
 function isSpacingClass(className) {
     const base = (0, utils_1.classBase)(className);
     return /^(?:-?m[trblxy]?|-?p[trblxy]?|gap-|space-|inset-|top-|right-|bottom-|left-)/.test(base);
 }
+function isLayoutClass(className) {
+    const base = (0, utils_1.classBase)(className);
+    return /^(?:flex|grid|block|inline|hidden|items-|justify-|content-|self-|place-|order-|col-|row-|container|d-|justify-content-|align-items-|align-self-)/.test(base);
+}
 function isSurfaceClass(className) {
     const base = (0, utils_1.classBase)(className);
     return (/^(?:bg-|border|rounded|shadow|ring|outline|divide-|opacity|backdrop|blur|drop-shadow)/.test(base) ||
@@ -1562,7 +1762,109 @@ function isDecorativeAccentClass(className) {
 }
 function isTypographyClass(className) {
     const base = (0, utils_1.classBase)(className);
-    return /^(?:text-|font-|leading-|tracking-|line-clamp|whitespace-|break-|truncate|max-w-|text-balance)/.test(base);
+    return isTypographyScaleBase(base);
+}
+function isTypographyScaleBase(base) {
+    return (/^(?:font-|leading-|tracking-|line-clamp|whitespace-|break-|truncate|text-balance|text-pretty|text-nowrap|text-wrap)/.test(base) ||
+        /^(?:fs-|fw-|lh-|display-|lead|small|text-uppercase|text-lowercase|text-capitalize)/.test(base) ||
+        /^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[[^\]]+\])/.test(base) ||
+        /^max-w-\[(?:\d+(?:\.\d+)?)?ch\]/.test(base));
+}
+function isLayoutSafetyBase(base) {
+    return /^(?:overflow-|min-w-|min-h-|max-w-|max-h-|w-fit|h-fit|w-max|h-max|w-min|h-min|basis-|grow|shrink|flex-1|flex-none|self-|whitespace-|break-|truncate|line-clamp|text-ellipsis|text-nowrap|text-balance|text-pretty)/.test(base);
+}
+function isSizingClass(className) {
+    const base = (0, utils_1.classBase)(className);
+    return /^(?:w-|h-|mw-|mh-|vw-|vh-|min-|max-|size-|aspect-|basis-|grow|shrink|flex-1|flex-none)/.test(base);
+}
+function isVisibilityClass(className) {
+    const base = (0, utils_1.classBase)(className);
+    return /^(?:hidden|block|inline|inline-block|flex|inline-flex|grid|inline-grid|table|contents)$/.test(base);
+}
+function isLineHeightClass(className) {
+    return (0, utils_1.classBase)(className).startsWith('leading-');
+}
+function isMaxWidthClass(className) {
+    return (0, utils_1.classBase)(className).startsWith('max-w-');
+}
+function createUiLayoutSafety(classes) {
+    const wrapClasses = filterClasses(classes, (className) => /^(?:whitespace-|break-|truncate|line-clamp|text-ellipsis|text-nowrap|text-balance|text-pretty|text-wrap)/.test((0, utils_1.classBase)(className))).slice(0, 40);
+    const overflowClasses = filterClasses(classes, (className) => /^(?:overflow-|line-clamp|truncate|text-ellipsis)/.test((0, utils_1.classBase)(className))).slice(0, 40);
+    const minSizeClasses = filterClasses(classes, (className) => /^(?:min-w-|min-h-)/.test((0, utils_1.classBase)(className))).slice(0, 40);
+    const maxSizeClasses = filterClasses(classes, (className) => /^(?:max-w-|max-h-)/.test((0, utils_1.classBase)(className))).slice(0, 40);
+    const fitClasses = filterClasses(classes, (className) => /^(?:w-fit|h-fit|w-max|h-max|w-min|h-min|basis-|self-)/.test((0, utils_1.classBase)(className))).slice(0, 40);
+    const flexBehaviorClasses = filterClasses(classes, (className) => /^(?:grow|shrink|flex-1|flex-none|basis-)/.test((0, utils_1.classBase)(className))).slice(0, 40);
+    const layoutSafetyClasses = (0, utils_1.unique)([
+        ...wrapClasses,
+        ...overflowClasses,
+        ...minSizeClasses,
+        ...maxSizeClasses,
+        ...fitClasses,
+        ...flexBehaviorClasses,
+    ]).slice(0, 80);
+    if (!layoutSafetyClasses.length) {
+        return undefined;
+    }
+    return {
+        wrapClasses,
+        overflowClasses,
+        minSizeClasses,
+        maxSizeClasses,
+        fitClasses,
+        flexBehaviorClasses,
+        layoutSafetyClasses,
+    };
+}
+function createUiResponsiveProfile(classes) {
+    const responsiveClasses = filterClasses(classes, isResponsiveClass).slice(0, 120);
+    if (!responsiveClasses.length) {
+        return undefined;
+    }
+    const breakpoints = {};
+    for (const className of responsiveClasses) {
+        const prefix = responsivePrefix(className);
+        if (!prefix) {
+            continue;
+        }
+        breakpoints[prefix] = (0, utils_1.unique)([...(breakpoints[prefix] ?? []), className]).slice(0, 60);
+    }
+    return {
+        breakpoints,
+        layoutClasses: filterClasses(responsiveClasses, isLayoutClass).slice(0, 60),
+        typographyClasses: filterClasses(responsiveClasses, isTypographyClass).slice(0, 60),
+        spacingClasses: filterClasses(responsiveClasses, isSpacingClass).slice(0, 60),
+        sizingClasses: filterClasses(responsiveClasses, isSizingClass).slice(0, 60),
+        visibilityClasses: filterClasses(responsiveClasses, isVisibilityClass).slice(0, 60),
+        stateClasses: filterClasses(responsiveClasses, isStateClass).slice(0, 60),
+    };
+}
+function createUiScaleProfile(classes) {
+    const typographyClasses = filterClasses(classes, isTypographyClass).slice(0, 80);
+    const spacingClasses = filterClasses(classes, isSpacingClass).slice(0, 80);
+    const sizingClasses = filterClasses(classes, isSizingClass).slice(0, 80);
+    const gapClasses = filterClasses(classes, (className) => /^(?:gap-|space-)/.test((0, utils_1.classBase)(className))).slice(0, 60);
+    const maxWidthClasses = filterClasses(classes, isMaxWidthClass).slice(0, 60);
+    const lineHeightClasses = filterClasses(classes, isLineHeightClass).slice(0, 60);
+    if (!typographyClasses.length &&
+        !spacingClasses.length &&
+        !sizingClasses.length &&
+        !gapClasses.length &&
+        !maxWidthClasses.length &&
+        !lineHeightClasses.length) {
+        return undefined;
+    }
+    return {
+        typographyClasses,
+        spacingClasses,
+        sizingClasses,
+        gapClasses,
+        maxWidthClasses,
+        lineHeightClasses,
+    };
+}
+function responsivePrefix(className) {
+    return (className.split(':').find((part) => /^(?:sm|md|lg|xl|2xl|min-|max-)/.test(part)) ??
+        className.match(/^(?:d|col|offset|order|m[stebxy]?|p[stebxy]?|gap|text|float|flex|justify-content|align-items|align-self)-(sm|md|lg|xl|xxl)-/)?.[1]);
 }
 function groupClassExpressionsByTarget(expressions) {
     const grouped = {};
@@ -1630,6 +1932,15 @@ function createUiCompositionGuidance(file) {
     if (classes.has('section-frame') || classes.has('context-surface')) {
         guidance.push('Use section-frame/context-surface only for framed technical panels, not every repeated card.');
     }
+    if (classes.has('section-frame')) {
+        guidance.push('section-frame owns the clipped section-frame::before grid overlay for that surface; do not treat it as a simple border/background token.');
+    }
+    if (classes.has('section-frame') && classes.has('context-surface')) {
+        guidance.push('Keep section-frame and context-surface paired for technical surfaces when child content must sit above the parent grid overlay.');
+    }
+    if (classes.has('sm:section-frame') || classes.has('bg-transparent')) {
+        guidance.push('Preserve transparent mobile surfaces and only add framed behavior at the same responsive breakpoint as the source.');
+    }
     if (file.classReferences.some(isDecorativeAccentClass)) {
         guidance.push('Treat brand-spectrum-card and purple glow shadow classes as accent/highlight-only; do not use them for default repeated cards unless the source element is explicitly current, highlighted, or featured.');
     }
@@ -1647,7 +1958,7 @@ function createUiPatternGuidance(kind, decorativeAccentClasses) {
 }
 function extractTailwindUtilities(classReferences) {
     return classReferences
-        .filter((className) => /^(?:-?m[trblxy]?|-?p[trblxy]?|flex|grid|block|inline|hidden|items-|justify-|gap-|space-|w-|h-|min-|max-|rounded|border|bg-|text-|font-|leading-|tracking-|shadow|ring|opacity|transition|duration|ease|hover:|focus:|active:|disabled:|dark:|sm:|md:|lg:|xl:|2xl:|container|sr-only)/.test(className))
+        .filter((className) => /^(?:-?m[trblxy]?|-?p[trblxy]?|flex|grid|block|inline|hidden|items-|justify-|gap-|space-|w-|h-|min-|max-|size-|basis-|grow|shrink|aspect-|overflow-|object-|whitespace-|break-|truncate|line-clamp|text-balance|text-pretty|text-nowrap|rounded|border|bg-|text-|font-|leading-|tracking-|shadow|ring|opacity|transition|duration|ease|hover:|focus:|active:|disabled:|dark:|sm:|md:|lg:|xl:|2xl:|min-[^:]+:|max-[^:]+:|container|sr-only)/.test(className))
         .slice(0, 160);
 }
 function extractPackageDependencies(relPath, content) {
@@ -1701,10 +2012,17 @@ function extractUiElements(content, relPath) {
         const label = extractElementLabel(content, tagInfo);
         const classSource = readClassSource(attrs);
         const classAnalysis = classSource ? analyzeClassSource(classSource) : undefined;
+        const styleHelper = classSource ? readPrimaryClassHelperUsage(classSource) : undefined;
         const classes = classAnalysis?.classes ?? [];
         const role = (0, utils_1.readAttr)(attrs, 'role');
-        const props = readUiProps(attrs);
-        const variants = readVariantProps(props);
+        const props = {
+            ...readUiProps(attrs),
+            ...(styleHelper ? { styleHelper: styleHelper.name } : {}),
+        };
+        const variants = {
+            ...readVariantProps(props),
+            ...(styleHelper?.variantProps ?? {}),
+        };
         const kind = classifyUiElement(tagInfo.originalTag, attrs, classes, role);
         const parentTagInfo = tagInfo.parentIndex === undefined ? undefined : tags[tagInfo.parentIndex];
         const parentClassSource = parentTagInfo ? readClassSource(parentTagInfo.attrs) : undefined;
@@ -1716,7 +2034,21 @@ function extractUiElements(content, relPath) {
         const layoutRole = deriveLayoutRole(tagInfo.originalTag, kind, classes, label);
         const responsiveClasses = classes.filter(isResponsiveClass);
         const stateClasses = classes.filter(isStateClass);
+        const layoutSafety = createUiLayoutSafety(classes);
+        const responsiveProfile = createUiResponsiveProfile(classes);
+        const scaleProfile = createUiScaleProfile(classes);
         const childSummary = summarizeDirectUiChildren(content, tags, index);
+        const semanticProfile = createUiSemanticProfile(kind, tagInfo.originalTag, classes, childSummary);
+        const roleSignature = createUiRoleSignature({
+            kind,
+            tag: tagInfo.originalTag,
+            classes,
+            children: childSummary,
+            label,
+            layoutRole,
+            parentKind,
+            parentClasses,
+        });
         if (kind === 'unknown') {
             continue;
         }
@@ -1748,6 +2080,11 @@ function extractUiElements(content, relPath) {
             classGroups: groupTailwindClasses(classes),
             ...(responsiveClasses.length ? { responsiveClasses } : {}),
             ...(stateClasses.length ? { stateClasses } : {}),
+            ...(layoutSafety ? { layoutSafety } : {}),
+            ...(responsiveProfile ? { responsiveProfile } : {}),
+            ...(scaleProfile ? { scaleProfile } : {}),
+            ...(semanticProfile ? { semanticProfile } : {}),
+            ...(roleSignature ? { roleSignature } : {}),
             ...(childSummary.length ? { childSummary } : {}),
             ...((0, utils_1.readAttr)(attrs, 'id') ? { id: (0, utils_1.readAttr)(attrs, 'id') } : {}),
             ...(role ? { role } : {}),
@@ -1757,6 +2094,10 @@ function extractUiElements(content, relPath) {
             ...((0, utils_1.readAttr)(attrs, 'method') ? { method: (0, utils_1.readAttr)(attrs, 'method')?.toUpperCase() } : {}),
             ...(Object.keys(props).length ? { props } : {}),
             ...(Object.keys(variants).length ? { variants } : {}),
+            ...(styleHelper ? { styleHelper: styleHelper.name } : {}),
+            ...(styleHelper && Object.keys(styleHelper.variantProps).length
+                ? { styleHelperVariants: styleHelper.variantProps }
+                : {}),
             evidence: `<${tagInfo.originalTag}${classes.length ? ` class="${classes.slice(0, 6).join(' ')}"` : ''}>`,
         });
     }
@@ -1769,11 +2110,31 @@ function summarizeDirectUiChildren(content, tags, parentIndex) {
         .map(({ tagInfo, index }) => {
         const classSource = readClassSource(tagInfo.attrs);
         const classAnalysis = classSource ? analyzeClassSource(classSource) : undefined;
+        const styleHelper = classSource ? readPrimaryClassHelperUsage(classSource) : undefined;
         const classes = classAnalysis?.classes ?? [];
         const role = (0, utils_1.readAttr)(tagInfo.attrs, 'role');
         const kind = classifyUiElement(tagInfo.originalTag, tagInfo.attrs, classes, role);
         const label = extractElementLabel(content, tagInfo);
         const layoutRole = deriveLayoutRole(tagInfo.originalTag, kind, classes, label);
+        const layoutSafety = createUiLayoutSafety(classes);
+        const responsiveProfile = createUiResponsiveProfile(classes);
+        const scaleProfile = createUiScaleProfile(classes);
+        const semanticRole = deriveUiChildSemanticRole(tagInfo.originalTag, kind, classes, label);
+        const roleSignature = createUiRoleSignature({
+            kind,
+            tag: tagInfo.originalTag,
+            classes,
+            label,
+            layoutRole,
+        });
+        const props = {
+            ...readUiProps(tagInfo.attrs),
+            ...(styleHelper ? { styleHelper: styleHelper.name } : {}),
+        };
+        const variants = {
+            ...readVariantProps(props),
+            ...(styleHelper?.variantProps ?? {}),
+        };
         return {
             index,
             kind,
@@ -1787,12 +2148,496 @@ function summarizeDirectUiChildren(content, tags, parentIndex) {
             ...(classAnalysis?.conditionalClasses.length
                 ? { conditionalClasses: classAnalysis.conditionalClasses.slice(0, 32) }
                 : {}),
+            ...(layoutSafety ? { layoutSafety } : {}),
+            ...(responsiveProfile ? { responsiveProfile } : {}),
+            ...(scaleProfile ? { scaleProfile } : {}),
+            ...(semanticRole ? { semanticRole } : {}),
+            ...(roleSignature ? { roleSignature } : {}),
+            ...(Object.keys(props).length ? { props } : {}),
+            ...(Object.keys(variants).length ? { variants } : {}),
+            ...(styleHelper ? { styleHelper: styleHelper.name } : {}),
+            ...(styleHelper && Object.keys(styleHelper.variantProps).length
+                ? { styleHelperVariants: styleHelper.variantProps }
+                : {}),
             ...(label ? { label } : {}),
         };
     })
-        .filter((child) => child.kind !== 'unknown' || child.classes.length || child.label)
+        .filter((child) => child.kind !== 'unknown' ||
+        child.classes.length ||
+        child.label ||
+        Boolean(child.semanticRole))
         .slice(0, 16);
 }
+function createUiSemanticProfile(kind, tag, classes, children) {
+    const roles = (0, utils_1.unique)(children.flatMap((child) => child.semanticRole ?? [])).slice(0, 24);
+    const textStyleSignatures = (0, utils_1.unique)(children
+        .filter((child) => ['text', 'heading', 'badge'].includes(child.kind) || child.semanticRole)
+        .map((child) => JSON.stringify(groupTailwindClasses(child.defaultClasses?.length ? child.defaultClasses : child.classes)))).filter(Boolean);
+    const hasIcon = roles.includes('icon') || roles.includes('component-icon') || roles.includes('image');
+    const hasDivider = roles.includes('divider');
+    const hasImage = roles.includes('image');
+    const hasMultipleTextStyles = textStyleSignatures.length > 1;
+    const isCompound = children.length > 1 &&
+        (hasIcon ||
+            hasDivider ||
+            hasMultipleTextStyles ||
+            roles.includes('primary-text') ||
+            roles.includes('secondary-text'));
+    if (!isCompound && !roles.length) {
+        return undefined;
+    }
+    return {
+        roles,
+        isCompound,
+        hasIcon,
+        hasDivider,
+        hasImage,
+        hasMultipleTextStyles,
+        textStyleCount: textStyleSignatures.length,
+        childCount: children.length,
+    };
+}
+function createUiRoleSignature(input) {
+    const { kind, tag, classes } = input;
+    const children = input.children ?? [];
+    const tagName = tag.toLowerCase();
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    const childRoles = (0, utils_1.unique)(children.flatMap((child) => [child.semanticRole, child.roleSignature?.role].filter((value) => typeof value === 'string' && Boolean(value)))).slice(0, 24);
+    const childKinds = (0, utils_1.unique)(children.map((child) => child.kind).filter(Boolean)).slice(0, 24);
+    const hasIcon = childRoles.some((role) => /(?:icon|image|logo|mark)/.test(role));
+    const hasDivider = childRoles.includes('divider');
+    const hasMultipleTextSegments = childRoles.filter((role) => /(?:primary|secondary|text|segment)/.test(role)).length > 1;
+    const exactClassFacts = exactRoleClassFacts(classes);
+    const flags = new Set();
+    const layout = createRoleLayoutKey(kind, tagName, classes, children, input.parentClasses ?? []);
+    const scale = createRoleScaleKey(classes, children);
+    const density = createRoleDensityKey(classes, children);
+    const surface = createRoleSurfaceKey(classes);
+    let roleGroup = kind;
+    let role = `${kind}-${input.layoutRole ?? 'element'}`;
+    if (input.layoutRole) {
+        flags.add(`layout-role:${input.layoutRole}`);
+    }
+    if (hasIcon)
+        flags.add('has-icon');
+    if (hasDivider)
+        flags.add('has-divider');
+    if (hasMultipleTextSegments)
+        flags.add('multiple-text-segments');
+    if (baseSet.has('uppercase'))
+        flags.add('uppercase');
+    if (classes.some((className) => className.includes('hover:')))
+        flags.add('has-hover-state');
+    if (baseSet.has('group'))
+        flags.add('group-context');
+    if (classes.some((className) => (0, utils_1.classBase)(className).startsWith('backdrop-blur'))) {
+        flags.add('backdrop-blur');
+    }
+    if (kind === 'section') {
+        roleGroup = 'section';
+        if (baseSet.has('min-h-screen')) {
+            role = 'hero-section-fullscreen';
+            flags.add('full-screen-hero');
+        }
+        else if (layout === 'split-media-layout') {
+            role = 'split-media-section';
+            flags.add('split-media');
+        }
+        else if (layout === 'card-grid-layout') {
+            role = 'card-grid-section';
+            flags.add('card-grid');
+        }
+        else {
+            role = 'section-shell';
+        }
+    }
+    if (kind === 'layout') {
+        roleGroup = 'layout';
+        if (layout === 'split-media-layout') {
+            role = 'split-media-layout';
+            flags.add('split-media');
+        }
+        else if (layout === 'card-grid-layout') {
+            role = 'card-grid-layout';
+            flags.add('card-grid');
+        }
+        else if (layout === 'hero-content-layout') {
+            role = 'hero-content-layout';
+            flags.add('hero-content');
+        }
+        else {
+            role = `layout-${layout}`;
+        }
+    }
+    if (kind === 'heading') {
+        roleGroup = tagName === 'h1' ? 'hero-heading' : 'heading';
+        if (tagName === 'h1') {
+            if (isOversizedHeadingScale(classes)) {
+                role = 'hero-heading-oversized';
+                flags.add('oversized-heading');
+            }
+            else if (isHeroHeadingScale(classes)) {
+                role = 'hero-heading-standard';
+                flags.add('hero-heading');
+            }
+            else {
+                role = 'page-heading';
+            }
+        }
+        else if (isMetricValueScale(classes)) {
+            role = 'metric-heading';
+            flags.add('metric-value');
+        }
+        else {
+            role = 'section-heading';
+        }
+    }
+    if (kind === 'badge') {
+        roleGroup = 'badge';
+        if (isOverlayPill(classes)) {
+            role = 'overlay-disclaimer-pill';
+            flags.add('overlay-pill');
+        }
+        else if (hasIcon || hasDivider || hasMultipleTextSegments) {
+            role = 'brand-lockup-badge';
+            flags.add('compound-badge');
+        }
+        else if (isCompactHeroEyebrow(classes)) {
+            role = 'hero-eyebrow-compact';
+            flags.add('compact-eyebrow');
+        }
+        else {
+            role = 'badge-pill';
+        }
+    }
+    if (kind === 'card') {
+        roleGroup = 'surface';
+        if (isCompactStatCard(classes, childRoles)) {
+            role = 'hero-stat-card-compact';
+            flags.add('compact-stat-card');
+        }
+        else if (isInteractiveServiceCard(classes)) {
+            role = 'interactive-service-card';
+            flags.add('interactive-card');
+        }
+        else if (isStaticArticleCard(classes)) {
+            role = 'static-article-card';
+            flags.add('static-article-surface');
+        }
+        else if (isMediaPanelCard(classes, childKinds, childRoles)) {
+            role = 'media-panel-card';
+            flags.add('media-panel');
+        }
+        else {
+            role = 'surface-card';
+        }
+    }
+    if (kind === 'text') {
+        roleGroup = 'text';
+        if (isCompactStatValue(classes)) {
+            role = 'compact-stat-value';
+            flags.add('compact-stat-value');
+        }
+        else if (isLargeMetricValue(classes)) {
+            role = 'large-metric-value';
+            flags.add('large-metric-value');
+        }
+        else if (isOverlayPill(classes)) {
+            role = 'overlay-disclaimer-text';
+            flags.add('overlay-pill');
+        }
+        else {
+            role = 'body-copy';
+        }
+    }
+    if (kind === 'button') {
+        roleGroup = 'action';
+        if (isQuietAction(classes)) {
+            role = 'quiet-action';
+            flags.add('low-emphasis-action');
+        }
+        else if (isCompactAction(classes)) {
+            role = 'compact-action-button';
+            flags.add('compact-action');
+        }
+        else {
+            role = 'action-button';
+        }
+    }
+    if (!classes.length && !childRoles.length && role === `${kind}-${input.layoutRole ?? 'element'}`) {
+        return undefined;
+    }
+    return {
+        role,
+        roleGroup,
+        scale,
+        density,
+        surface,
+        layout,
+        flags: Array.from(flags).sort(),
+        exactClassFacts,
+        ...(childRoles.length ? { childRoles } : {}),
+        ...(childKinds.length ? { childKinds } : {}),
+    };
+}
+function exactRoleClassFacts(classes) {
+    return (0, utils_1.unique)(classes.filter((className) => {
+        const base = (0, utils_1.classBase)(className);
+        return (isTypographyClass(className) ||
+            isSpacingClass(className) ||
+            isSizingClass(className) ||
+            isLayoutClass(className) ||
+            isStateClass(className) ||
+            /^(?:bg-|text-|border|rounded|shadow|backdrop|opacity|ring|outline|z-|absolute|relative|fixed|sticky|top-|right-|bottom-|left-|overflow-|object-|aspect-|group|transition|duration|ease)/.test(base));
+    })).slice(0, 120);
+}
+function createRoleScaleKey(classes, children = []) {
+    const scaleClasses = (0, utils_1.unique)([
+        ...classes,
+        ...children.flatMap((child) => child.classes.slice(0, 24)),
+    ].filter((className) => {
+        const base = (0, utils_1.classBase)(className);
+        return (isTypographyClass(className) ||
+            isSizingClass(className) ||
+            /^(?:max-w-|min-w-|leading-|tracking-|text-|font-|h-|w-|min-h-|max-h-)/.test(base));
+    }))
+        .sort(roleClassSort)
+        .slice(0, 40);
+    return scaleClasses.length ? scaleClasses.join(' ') : 'scale-unspecified';
+}
+function createRoleDensityKey(classes, children = []) {
+    const densityClasses = (0, utils_1.unique)([
+        ...classes,
+        ...children.flatMap((child) => child.classes.slice(0, 16)),
+    ].filter((className) => {
+        const base = (0, utils_1.classBase)(className);
+        return /^(?:p[trblxy]?|m[trblxy]?|gap-|space-|h-|min-h-|max-h-|w-|min-w-|max-w-)/.test(base);
+    }))
+        .sort(roleClassSort)
+        .slice(0, 40);
+    if (!densityClasses.length) {
+        return 'density-unspecified';
+    }
+    if (densityClasses.some((className) => /(?:^|:)py-(?:1|1\.5|2)$/.test(className)) ||
+        densityClasses.some((className) => /(?:^|:)h-(?:8|9|10|11|12)$/.test(className))) {
+        return `compact:${densityClasses.join(' ')}`;
+    }
+    if (densityClasses.some((className) => /(?:^|:)p-(?:8|10|12|16|20|24)$/.test(className)) ||
+        densityClasses.some((className) => /(?:^|:)py-(?:8|10|12|16|20|24)$/.test(className))) {
+        return `spacious:${densityClasses.join(' ')}`;
+    }
+    return densityClasses.join(' ');
+}
+function createRoleSurfaceKey(classes) {
+    const surfaceClasses = (0, utils_1.unique)(classes.filter((className) => {
+        const base = (0, utils_1.classBase)(className);
+        return /^(?:bg-|border|rounded|shadow|ring|outline|backdrop|opacity|group|transition|hover:border|hover:bg)/.test(base);
+    }))
+        .sort(roleClassSort)
+        .slice(0, 40);
+    return surfaceClasses.length ? surfaceClasses.join(' ') : 'surface-unspecified';
+}
+function createRoleLayoutKey(kind, tagName, classes, children = [], parentClasses = []) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    const childKinds = new Set(children.map((child) => child.kind));
+    const childRoles = new Set(children.flatMap((child) => [child.semanticRole, child.roleSignature?.role].filter(Boolean)));
+    const childClassBases = children.flatMap((child) => child.classes.map(utils_1.classBase));
+    const hasMediaChild = childKinds.has('image') ||
+        childRoles.has('image') ||
+        childRoles.has('media-panel-card') ||
+        childClassBases.some((base) => /^(?:aspect-|object-|h-\[|min-h-\[)/.test(base));
+    const hasCardChildren = children.filter((child) => child.kind === 'card').length >= 2;
+    const hasTextChildren = children.some((child) => ['heading', 'text', 'badge'].includes(child.kind) ||
+        (child.kind === 'layout' &&
+            child.classes.some((className) => /^(?:max-w-|space-y-|prose|flex|grid)/.test((0, utils_1.classBase)(className)))));
+    const parentBaseSet = new Set(parentClasses.map(utils_1.classBase));
+    if (baseSet.has('min-h-screen')) {
+        return 'full-screen-hero-layout';
+    }
+    if (baseSet.has('absolute') &&
+        (baseSet.has('bottom-3') || baseSet.has('bottom-4')) &&
+        (baseSet.has('right-3') || baseSet.has('right-4'))) {
+        return 'absolute-bottom-right-overlay';
+    }
+    if ((baseSet.has('grid') || parentBaseSet.has('grid')) &&
+        hasMediaChild &&
+        hasTextChildren &&
+        classes.some((className) => /(?:^|:)grid-cols-|(?:^|:)lg:grid-cols-/.test(className))) {
+        return 'split-media-layout';
+    }
+    if ((baseSet.has('grid') || parentBaseSet.has('grid')) && hasCardChildren) {
+        return 'card-grid-layout';
+    }
+    if (tagName === 'main' || (kind === 'layout' && baseSet.has('mx-auto'))) {
+        return 'page-content-layout';
+    }
+    if (baseSet.has('flex') || baseSet.has('inline-flex')) {
+        return 'flex-layout';
+    }
+    if (baseSet.has('grid')) {
+        return 'grid-layout';
+    }
+    return 'layout-unspecified';
+}
+function isCompactHeroEyebrow(classes) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    return (baseSet.has('inline-flex') &&
+        baseSet.has('rounded-full') &&
+        baseSet.has('uppercase') &&
+        classes.some((className) => /(?:^|:)text-xs$/.test(className)) &&
+        classes.some((className) => /(?:^|:)sm:text-sm$/.test(className)) &&
+        bases.some((base) => /^py-(?:1\.5|2)$/.test(base)) &&
+        bases.some((base) => /^px-(?:3|4|5)$/.test(base)));
+}
+function isOverlayPill(classes) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    return (baseSet.has('absolute') &&
+        baseSet.has('rounded-full') &&
+        bases.some((base) => /^bottom-/.test(base)) &&
+        bases.some((base) => /^right-/.test(base)) &&
+        (bases.some((base) => /^text-\[(?:10|11)px\]$/.test(base)) ||
+            classes.some((className) => /(?:^|:)sm:text-\[(?:10|11)px\]$/.test(className))));
+}
+function isHeroHeadingScale(classes) {
+    const classSet = new Set(classes);
+    const bases = classes.map(utils_1.classBase);
+    return (classSet.has('text-4xl') &&
+        classSet.has('sm:text-6xl') &&
+        classSet.has('lg:text-7xl') &&
+        bases.some((base) => /^leading-/.test(base)));
+}
+function isOversizedHeadingScale(classes) {
+    const classSet = new Set(classes);
+    return (classSet.has('text-6xl') ||
+        classSet.has('sm:text-7xl') ||
+        classSet.has('lg:text-8xl') ||
+        classSet.has('xl:text-9xl') ||
+        classes.some((className) => /(?:^|:)text-\[(?:8|9|10)\dpx\]/.test(className)));
+}
+function isMetricValueScale(classes) {
+    return classes.some((className) => /(?:^|:)text-(?:lg|xl|2xl|3xl|4xl)$/.test(className));
+}
+function isCompactStatValue(classes) {
+    const classSet = new Set(classes);
+    const bases = classes.map(utils_1.classBase);
+    return (classSet.has('text-lg') &&
+        bases.some((base) => /^font-(?:bold|extrabold|black)$/.test(base)) &&
+        bases.some((base) => /^text-\[|^text-(?:brand|accent|yellow|amber|gold)/.test(base)));
+}
+function isLargeMetricValue(classes) {
+    const classSet = new Set(classes);
+    return (classSet.has('text-2xl') ||
+        classSet.has('sm:text-3xl') ||
+        classSet.has('text-3xl') ||
+        classSet.has('text-4xl'));
+}
+function isCompactStatCard(classes, childRoles) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    return (childRoles.includes('compact-stat-value') ||
+        (baseSet.has('rounded-lg') &&
+            baseSet.has('border') &&
+            bases.some((base) => /^p-(?:4|5)$/.test(base)) &&
+            !baseSet.has('group')));
+}
+function isInteractiveServiceCard(classes) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    return (baseSet.has('group') ||
+        classes.some((className) => className.includes('hover:')) ||
+        (baseSet.has('transition') && bases.includes('shadow-2xl')));
+}
+function isStaticArticleCard(classes) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    return (baseSet.has('flex') &&
+        baseSet.has('h-full') &&
+        baseSet.has('flex-col') &&
+        baseSet.has('rounded-lg') &&
+        baseSet.has('border') &&
+        bases.includes('p-6') &&
+        !baseSet.has('group') &&
+        !classes.some((className) => className.includes('hover:')));
+}
+function isMediaPanelCard(classes, childKinds, childRoles) {
+    const bases = classes.map(utils_1.classBase);
+    return (childKinds.includes('image') ||
+        childRoles.includes('image') ||
+        bases.some((base) => /^(?:aspect-|object-|overflow-hidden)$/.test(base)));
+}
+function isQuietAction(classes) {
+    const bases = classes.map(utils_1.classBase);
+    return (bases.includes('bg-transparent') &&
+        (bases.includes('border-transparent') ||
+            bases.some((base) => /^text-(?:muted|secondary|slate|gray)/.test(base))));
+}
+function isCompactAction(classes) {
+    const bases = classes.map(utils_1.classBase);
+    return (bases.some((base) => /^h-(?:9|10|11|12)$/.test(base)) &&
+        bases.some((base) => /^px-(?:4|5)$/.test(base)) &&
+        classes.some((className) => /(?:^|:)text-sm$/.test(className)));
+}
+function roleClassSort(a, b) {
+    const priority = (value) => {
+        const base = (0, utils_1.classBase)(value);
+        if (/^(?:max-w-|min-w-|w-|h-|min-h-|max-h-)/.test(base))
+            return 0;
+        if (/^(?:text-|font-|leading-|tracking-)/.test(base))
+            return 1;
+        if (/^(?:p|m|gap|space)-/.test(base))
+            return 2;
+        if (/^(?:bg-|border|rounded|shadow|backdrop)/.test(base))
+            return 3;
+        return 4;
+    };
+    return priority(a) - priority(b) || a.localeCompare(b);
+}
+function deriveUiChildSemanticRole(tag, kind, classes, label) {
+    const tagName = tag.toLowerCase();
+    const tagBase = tag.split('.')[0].split(':').pop() ?? tag;
+    const lowerBase = tagBase.toLowerCase();
+    const classBases = classes.map(utils_1.classBase);
+    const classHaystack = [tagName, lowerBase, ...classBases].join(' ').toLowerCase();
+    const labelHaystack = (label ?? '').toLowerCase();
+    if (kind === 'icon') {
+        return 'icon';
+    }
+    if (kind === 'image') {
+        return 'image';
+    }
+    if (kind === 'divider') {
+        return 'divider';
+    }
+    if (tagName === 'img' ||
+        tagName === 'picture' ||
+        tagName === 'svg' ||
+        /(?:icon|logo|mark|glyph|avatar|image|img)$/.test(lowerBase) ||
+        /\b(?:icon|logo|mark|glyph|avatar)\b/.test(classHaystack)) {
+        return tagName === 'img' || tagName === 'picture' ? 'image' : 'icon';
+    }
+    if (classes.some((className) => /^(?:w-px|h-px|border-l|border-r|border-t|border-b|divide-x|divide-y)$/.test((0, utils_1.classBase)(className))) ||
+        /\b(?:divider|separator|sep|rule)\b/.test(classHaystack)) {
+        return 'divider';
+    }
+    if (kind === 'text' || kind === 'heading' || kind === 'badge') {
+        if (classes.some((className) => /^(?:text-muted|text-muted-foreground|text-secondary|opacity-|font-normal)/.test((0, utils_1.classBase)(className)))) {
+            return 'secondary-text';
+        }
+        if (classes.some((className) => /^(?:font-bold|font-semibold|font-black|text-primary|text-brand|text-accent|text-yellow|text-amber|text-gold|text-\[)/.test((0, utils_1.classBase)(className))) ||
+            (labelHaystack.length > 0 && labelHaystack.length <= 32)) {
+            return 'primary-text';
+        }
+        return 'text-segment';
+    }
+    if (/^[A-Z]/.test(tagBase) && !classes.length && !label) {
+        return 'component-icon';
+    }
+    return undefined;
+}
 function deriveLayoutRole(tag, kind, classes, label) {
     const tagName = tag.toLowerCase();
     const tagBase = tag.split('.')[0].split(':').pop() ?? tag;
@@ -1857,7 +2702,8 @@ function deriveLayoutRole(tag, kind, classes, label) {
     return undefined;
 }
 function isStateClass(className) {
-    return /^(?:hover|focus|active|disabled|visited|dark|group|peer|aria|data):/.test(className);
+    const prefixes = className.split(':').slice(0, -1);
+    return prefixes.some((prefix) => /^(?:hover|focus|active|disabled|visited|dark|group|peer|aria|data)/.test(prefix));
 }
 function extractApiCalls(content) {
     const calls = new Set();
@@ -2314,7 +3160,8 @@ function isTemplateFile(relPath) {
         relPath.endsWith('.blade.php'));
 }
 function isTestFile(relPath) {
-    return (/(?:^|\/)(?:__tests__|tests?|spec)\//i.test(relPath) ||
+    return (/(?:^|\/)(?:app|pages|src\/app|src\/pages)\/test\//i.test(relPath) ||
+        /(?:^|\/)(?:__tests__|tests?|spec)\//i.test(relPath) ||
         /\.(test|spec)\.[A-Za-z0-9]+$/.test(relPath));
 }
 function isConfigFile(relPath) {
@@ -2527,6 +3374,8 @@ function classifyUiElement(tag, attrs, classes, role) {
     const tagBase = originalTag.split('.')[0].split(':').pop() ?? originalTag;
     const lowerBase = tagBase.toLowerCase();
     const classHaystack = [tagName, role ?? '', ...classes].join(' ').toLowerCase();
+    const classHelper = readPrimaryClassHelperUsage(readClassSource(attrs) ?? '');
+    const classHelperName = classHelper?.name.toLowerCase() ?? '';
     const propHaystack = [
         tagName,
         role ?? '',
@@ -2541,12 +3390,30 @@ function classifyUiElement(tag, attrs, classes, role) {
     if (/^h[1-6]$/.test(tagName) || /^(heading|title|headline)$/i.test(tagBase)) {
         return 'heading';
     }
+    if (tagName === 'img' ||
+        tagName === 'picture' ||
+        /^(image|img|avatar)$/i.test(tagBase) ||
+        /(?:image|img|avatar)$/.test(lowerBase)) {
+        return 'image';
+    }
+    if (tagName === 'svg' ||
+        /^(icon|logo|mark|glyph)$/i.test(tagBase) ||
+        /(?:icon|logo|mark|glyph)$/.test(lowerBase) ||
+        /\b(icon|logo|mark|glyph)\b/.test(classHaystack)) {
+        return 'icon';
+    }
+    if (/^(divider|separator|rule)$/i.test(tagBase) ||
+        /\b(divider|separator|rule)\b/.test(classHaystack) ||
+        classes.some((className) => /^(?:w-px|h-px|border-l|border-r|border-t|border-b|divide-x|divide-y)$/.test((0, utils_1.classBase)(className)))) {
+        return 'divider';
+    }
     if (['input', 'textarea', 'select', 'option', 'label', 'fieldset'].includes(tagName) ||
         /^(input|textarea|select|field|fieldlabel|label|checkbox|switch|slider|radio|combobox)$/i.test(tagBase) ||
         /\b(field|input|textarea|select|checkbox|switch|slider|radio)\b/.test(classHaystack)) {
         return 'input';
     }
-    if (tagName === 'button' ||
+    if (/(?:button|cta|action)/.test(classHelperName) ||
+        tagName === 'button' ||
         role === 'button' ||
         /^(button|iconbutton|submitbutton|cta)$/i.test(tagBase) ||
         /\b(btn|button|cta|submit)\b/.test(classHaystack) ||
@@ -2574,12 +3441,15 @@ function classifyUiElement(tag, attrs, classes, role) {
         /\b(dialog|modal|popover|drawer|sheet)\b/.test(classHaystack)) {
         return 'dialog';
     }
-    if (/^(badge|chip|pill|tag|status|eyebrow)$/i.test(tagBase) ||
-        /\b(badge|chip|pill|tag|status|eyebrow)\b/.test(classHaystack)) {
+    if (/(?:badge|chip|pill|status)/.test(classHelperName) ||
+        /^(badge|chip|pill|tag|status|eyebrow)$/i.test(tagBase) ||
+        /\b(badge|chip|pill|tag|status|eyebrow)\b/.test(classHaystack) ||
+        looksLikePillBadge(tagName, classes)) {
         return 'badge';
     }
     if (/^(card|panel|tile|surface|sectionframe|frame|callout)$/i.test(tagBase) ||
-        /\b(card|panel|tile|surface|section-frame|frame|callout)\b/.test(classHaystack)) {
+        /\b(card|panel|tile|section-frame|context-surface|frame|callout)\b/.test(classHaystack) ||
+        looksLikeSurfaceContainer(tagName, tagBase, classes)) {
         return 'card';
     }
     if (tagName === 'section' || lowerBase === 'section') {
@@ -2594,6 +3464,49 @@ function classifyUiElement(tag, attrs, classes, role) {
     }
     return 'unknown';
 }
+function looksLikeSurfaceContainer(tagName, tagBase, classes) {
+    const bases = classes.map(utils_1.classBase);
+    const isContainerTag = ['div', 'article', 'section', 'aside', 'figure', 'li', 'main', 'header', 'footer'].includes(tagName) ||
+        /^[A-Z]/.test(tagBase);
+    const isTinyIndicator = tagName === 'span' &&
+        bases.includes('rounded-full') &&
+        bases.some((base) => /^(?:h|size)-(?:px|0\.5|1|1\.5|2|2\.5|3)$/.test(base)) &&
+        bases.some((base) => /^(?:w|size)-(?:px|0\.5|1|1\.5|2|2\.5|3)$/.test(base));
+    if (!isContainerTag || isTinyIndicator) {
+        return false;
+    }
+    const hasSurfaceBackground = bases.some((base) => base === 'bg-card' ||
+        base === 'section-frame' ||
+        base === 'context-surface' ||
+        /^bg-/.test(base) ||
+        /^bg-\[var\(--(?:surface|card)-/.test(base));
+    const hasContainerShape = bases.some((base) => /^(?:border|rounded|shadow|ring|outline|overflow-hidden)/.test(base));
+    const hasContainerStructure = bases.some((base) => /^(?:p[trblxy]?|gap-|space-|min-h-|max-w-|w-full|flex|grid|relative)/.test(base));
+    return hasSurfaceBackground && hasContainerShape && hasContainerStructure;
+}
+function looksLikePillBadge(tagName, classes) {
+    const bases = classes.map(utils_1.classBase);
+    const baseSet = new Set(bases);
+    const allowedTag = ['div', 'span', 'small', 'p', 'li'].includes(tagName);
+    const hasPillShape = baseSet.has('rounded-full') || bases.some((base) => /^rounded-\[/.test(base));
+    const hasCompactSpacing = bases.some((base) => /^px-(?:2|2\.5|3|4|5|6)$/.test(base)) &&
+        bases.some((base) => /^py-(?:1|1\.5|2|2\.5|3)$/.test(base));
+    const hasBadgeText = baseSet.has('uppercase') ||
+        classes.some((className) => /(?:^|:)text-(?:xs|sm|\[(?:10|11|12|13|14)px\])$/.test(className));
+    const hasCompoundPillLayout = bases.some((base) => /^gap-/.test(base));
+    const hasBadgeSurface = bases.some((base) => /^bg-/.test(base)) ||
+        bases.some((base) => /^border/.test(base)) ||
+        bases.some((base) => /^shadow/.test(base));
+    const hasInlineLayout = baseSet.has('inline-flex') ||
+        baseSet.has('inline-grid') ||
+        (baseSet.has('absolute') && bases.some((base) => /^bottom-|^top-/.test(base)));
+    return (allowedTag &&
+        hasPillShape &&
+        hasCompactSpacing &&
+        (hasBadgeText || hasCompoundPillLayout) &&
+        hasBadgeSurface &&
+        hasInlineLayout);
+}
 function stripTags(value) {
     return value.replace(/<[^>]+>/g, ' ').replace(/\{[{%][\s\S]*?[}%]\}/g, ' ');
 }