@dcoder-x/plugin-shared 0.1.4 → 0.1.5

package/dist/extractors/ComponentExtractor.js

@@ -10,6 +10,8 @@ const parser_1 = require("@babel/parser");
 const traverse_1 = __importDefault(require("@babel/traverse"));
 const InteractionGraphExtractor_1 = require("./InteractionGraphExtractor");
 const ComponentContextResolver_1 = require("./ComponentContextResolver");
+const HtmlTagGuards_1 = require("../injection/HtmlTagGuards");
+const IdStrategy_1 = require("../injection/IdStrategy");
 class ComponentExtractor {
     constructor(source, routes) {
         this.source = source;
@@ -257,21 +259,32 @@ class ComponentExtractor {
                 const tagName = nodePath.node.name?.name;
                 if (!tagName)
                     return;
-                const isInteractive = ['button', 'input', 'select', 'textarea', 'a', 'form'].includes(tagName) ||
-                    nodePath.node.attributes.some((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'onClick');
-                if (!isInteractive)
+                // Navigation components (Link, NavLink) are included for flow graph building
+                // but flagged so the selector manifest skips them
+                const isNavigationComponent = (tagName === 'Link' || tagName === 'NavLink' || tagName === 'RouterLink') &&
+                    nodePath.node.attributes.some((a) => a.name?.name === 'href' || a.name?.name === 'to');
+                // Only intrinsic HTML tags get data-clippy-id injected; skip React components
+                if (!(0, HtmlTagGuards_1.isIntrinsicTag)(tagName) && !isNavigationComponent)
+                    return;
+                const INTERACTIVE_TAGS = new Set(['button', 'input', 'select', 'textarea', 'a', 'form', 'label']);
+                if (!isNavigationComponent && !INTERACTIVE_TAGS.has(tagName))
                     return;
                 const staticProps = extractStaticProps(nodePath.node.attributes);
                 const nearbyText = extractNearbyText(nodePath);
+                const label = deriveLabel(staticProps, nearbyText) ?? undefined;
+                const componentName = (0, IdStrategy_1.findEnclosingComponentName)(nodePath) ?? undefined;
                 elements.push({
                     tag: tagName,
                     filePath,
                     route,
                     staticProps,
                     nearbyText,
+                    label,
+                    component: componentName,
                     semanticRole: inferSemanticRole(tagName, staticProps, nearbyText),
                     interactions: inferInteractions(tagName, staticProps),
                     loc: { line: nodePath.node.loc?.start?.line ?? 0 },
+                    isNavigationLink: isNavigationComponent,
                 });
             },
         });
@@ -331,18 +344,55 @@ function extractStaticProps(attributes) {
     return props;
 }
 function extractNearbyText(nodePath) {
-    const texts = [];
     const parent = nodePath.parentPath?.node;
-    if (parent?.children) {
-        for (const child of parent.children) {
-            if (child.type === 'JSXText') {
-                const text = child.value.trim();
-                if (text)
-                    texts.push(text);
+    if (!parent?.children)
+        return [];
+    return extractTextFromChildren(parent.children, 0);
+}
+function extractTextFromChildren(children, depth) {
+    if (depth > 3)
+        return [];
+    const texts = [];
+    for (const child of children) {
+        if (child.type === 'JSXText') {
+            const t = child.value.trim();
+            if (t)
+                texts.push(t);
+        }
+        else if (child.type === 'JSXExpressionContainer') {
+            if (child.expression?.type === 'StringLiteral') {
+                texts.push(child.expression.value);
+            }
+            else if (child.expression?.type === 'TemplateLiteral' &&
+                child.expression.quasis?.length === 1) {
+                const raw = child.expression.quasis[0].value.raw.trim();
+                if (raw)
+                    texts.push(raw);
+            }
+        }
+        else if (child.type === 'JSXElement') {
+            const childTag = child.openingElement?.name?.name || '';
+            // Skip icon-like leaf components — they contribute no readable text
+            if (!/^(Icon|Svg|Loader|Spinner|Arrow|Check|Plus|Minus|Close|X)[A-Z]?/i.test(childTag)) {
+                texts.push(...extractTextFromChildren(child.children || [], depth + 1));
             }
         }
     }
-    return texts;
+    return texts.filter(Boolean);
+}
+function deriveLabel(props, nearbyText) {
+    if (props['aria-label'])
+        return props['aria-label'];
+    if (props['title'])
+        return props['title'];
+    const joined = nearbyText.join(' ').trim();
+    if (joined && joined.length <= 60)
+        return joined;
+    if (props['placeholder'])
+        return props['placeholder'];
+    if (props['name'])
+        return props['name'];
+    return null;
 }
 function inferSemanticRole(tag, props, nearbyText) {
     const label = props['aria-label'] || props['placeholder'] || nearbyText[0] || '';

package/dist/extractors/FlowInferrer.d.ts

@@ -9,4 +9,5 @@ export declare class FlowInferrer {
     private detectLinearFlows;
     private detectInteractionFlows;
     private buildChain;
+    private generateIntentPatterns;
 }

package/dist/extractors/FlowInferrer.js

@@ -1,6 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowInferrer = void 0;
+const SEMANTIC_INTENT_PATTERNS = {
+    'login': ['log in', 'sign in', 'login'],
+    'signup': ['sign up', 'create account', 'register', 'get started'],
+    'register': ['register', 'sign up', 'create account'],
+    'forgot-password': ['forgot password', 'reset password', 'recover account'],
+    'reset-password': ['reset my password', 'set new password', 'change password'],
+    'verify': ['verify email', 'verify account', 'confirm email'],
+    'otp': ['enter code', 'verify code', 'enter otp'],
+    'billing': ['upgrade plan', 'manage billing', 'change subscription', 'view billing'],
+    'payment-method': ['add payment method', 'update card', 'change payment'],
+    'settings': ['settings', 'account settings', 'preferences'],
+    'team': ['invite team member', 'manage team', 'add team member'],
+    'forms': ['view forms', 'manage forms', 'create form', 'my forms'],
+    'builder': ['build form', 'form builder', 'edit form'],
+    'submissions': ['view submissions', 'form submissions', 'see responses'],
+    'analytics': ['view analytics', 'form analytics', 'see stats'],
+    'templates': ['view templates', 'browse templates', 'use template'],
+    'studio': ['template studio', 'create template'],
+    'transactions': ['view transactions', 'transaction history', 'payment history'],
+    'documents': ['view documents', 'open document', 'my documents'],
+    'integrations': ['integrations', 'connect integration', 'manage integrations'],
+    'developer': ['developer settings', 'api keys', 'developer dashboard'],
+    'automations': ['automations', 'manage automations', 'view automations'],
+    'campaigns': ['campaigns', 'view campaigns', 'manage campaigns'],
+    'website': ['website', 'manage website'],
+    'workflows': ['workflows', 'manage workflows'],
+    'invite': ['accept invite', 'join team'],
+};
 class FlowInferrer {
     constructor(routes, elements, components) {
         this.routes = routes;
@@ -17,15 +45,25 @@ class FlowInferrer {
         const edges = [];
         const routePaths = new Set(this.routes.map((r) => r.path));
         for (const el of this.elements) {
+            // Include both native <a> tags and navigation components (Link, NavLink)
+            const isNav = el.tag === 'a' ||
+                el.isNavigationLink === true;
             const href = el.staticProps['href'] || el.staticProps['to'];
-            if (el.tag === 'a' && href && routePaths.has(href)) {
-                edges.push({
-                    from: el.route,
-                    to: href,
-                    trigger: el.staticProps['aria-label'] || el.nearbyText[0] || 'link',
-                    confidence: 0.85,
-                });
-            }
+            if (!isNav || !href)
+                continue;
+            // Only build edges to known internal routes
+            if (!routePaths.has(href))
+                continue;
+            const triggerText = el.staticProps['aria-label'] ||
+                el.label ||
+                el.nearbyText[0] ||
+                'link';
+            edges.push({
+                from: el.route,
+                to: href,
+                trigger: triggerText,
+                confidence: 0.85,
+            });
         }
         return edges;
     }
@@ -43,6 +81,11 @@ class FlowInferrer {
                 continue;
             const chain = this.buildChain(route.path, adjacency, new Set());
             if (chain.length >= 2) {
+                const chainEdges = edges.filter((e) => {
+                    const s = new Set(chain);
+                    return s.has(e.from) && s.has(e.to);
+                });
+                const intentPatterns = this.generateIntentPatterns(chain, chainEdges);
                 flows.push({
                     id: `flow_${flows.length + 1}`,
                     name: chain
@@ -50,10 +93,8 @@ class FlowInferrer {
                         .join(' -> '),
                     page: chain[0],
                     steps: chain,
-                    edges: edges.filter((e) => {
-                        const s = new Set(chain);
-                        return s.has(e.from) && s.has(e.to);
-                    }),
+                    edges: chainEdges,
+                    intentPatterns,
                 });
                 chain.forEach((p) => visited.add(p));
             }
@@ -61,18 +102,26 @@ class FlowInferrer {
         return flows;
     }
     detectInteractionFlows() {
-        if (!this.components || this.components.length === 0) {
+        if (!this.components || this.components.length === 0)
             return [];
-        }
         const flows = [];
         for (const component of this.components) {
             for (const interaction of component.interactions || []) {
-                const routePath = component.route || '/';
+                // Only emit flows for interactions with a meaningful wait strategy
                 if (!interaction.trigger?.event)
                     continue;
+                if (!interaction.effect || interaction.effect.waitStrategy === 'none')
+                    continue;
+                const routePath = component.route || '/';
+                const effectTarget = interaction.effect.selector ||
+                    (interaction.effect.rendersWhenTrue
+                        ? `[data-clippy-component='${interaction.effect.rendersWhenTrue}']`
+                        : null);
+                if (!effectTarget)
+                    continue;
                 flows.push({
                     id: `flow_${flows.length + 1}`,
-                    name: `${routePath} ${interaction.trigger.event}`,
+                    name: interaction.effect.rendersWhenTrue || interaction.trigger.event,
                     page: routePath,
                     steps: [routePath],
                     edges: [
@@ -83,6 +132,7 @@ class FlowInferrer {
                             confidence: 0.65,
                         },
                     ],
+                    intentPatterns: [],
                 });
             }
         }
@@ -98,5 +148,26 @@ class FlowInferrer {
         const best = [...next].sort((a, b) => b.confidence - a.confidence)[0];
         return [start, ...this.buildChain(best.to, adjacency, seen)];
     }
+    generateIntentPatterns(chain, edges) {
+        const patterns = new Set();
+        // 1. Route-segment semantic lookup
+        for (const routePath of chain) {
+            const segments = routePath.split('/').filter(Boolean);
+            for (const segment of segments) {
+                const clean = segment.replace(/[\[\]$:]/g, '').toLowerCase();
+                const known = SEMANTIC_INTENT_PATTERNS[clean];
+                if (known)
+                    known.forEach((p) => patterns.add(p));
+            }
+        }
+        // 2. Link/button trigger text from the edges themselves
+        for (const edge of edges) {
+            const trigger = edge.trigger?.trim();
+            if (trigger && trigger !== 'link' && trigger.length > 2) {
+                patterns.add(trigger.toLowerCase());
+            }
+        }
+        return Array.from(patterns).filter(Boolean);
+    }
 }
 exports.FlowInferrer = FlowInferrer;

package/dist/extractors/InteractionGraphExtractor.d.ts

@@ -2,7 +2,7 @@ import type { NodePath } from '@babel/traverse';
 import type { ComponentInteraction } from '../types';
 /**
  * Extracts interaction graphs from React component ASTs.
- * Maps event handlers -> state mutations -> conditional renders and effects.
+ * Maps event handlers -> state mutations -> conditional renders, navigation, and async effects.
  */
 export declare class InteractionGraphExtractor {
     private contextResolver;
@@ -10,25 +10,19 @@ export declare class InteractionGraphExtractor {
      * Extract all interactions (trigger -> effect mappings) from a component.
      */
     extractInteractions(componentPath: NodePath<any>, componentName: string): ComponentInteraction[];
+    private buildInteractionFromSetters;
     /**
-     * Extract trigger/effect pair from a JSX element with an event handler.
+     * Detect router.push() / router.replace() / navigate() calls inside a handler.
+     * Returns the destination route string if found, otherwise null.
      */
-    private extractTriggerAndEffect;
+    private resolveRouterNavigation;
+    private findHandlerBody;
+    private extractRouterCallFromNode;
     private resolveStateSettersForAttribute;
     private collectSettersFromNode;
-    /**
-     * Find conditional renders/effects that depend on a state variable.
-     * Looks for logical expressions and ternaries using the state var.
-     */
     private findConditionalEffect;
     private findConditionalEffectInAncestors;
     private findConditionalEffectInComponent;
-    /**
-     * Check if a node references a specific state variable by name.
-     */
     private nodeReferencesState;
-    /**
-     * Extract component name from a JSX element or identifier.
-     */
     private extractComponentNameFromNode;
 }

package/dist/extractors/InteractionGraphExtractor.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InteractionGraphExtractor = void 0;
 const ComponentContextResolver_1 = require("./ComponentContextResolver");
+const MODAL_STATE_PATTERN = /^(is|show|open|visible)/i;
 /**
  * Extracts interaction graphs from React component ASTs.
- * Maps event handlers -> state mutations -> conditional renders and effects.
+ * Maps event handlers -> state mutations -> conditional renders, navigation, and async effects.
  */
 class InteractionGraphExtractor {
     constructor() {
@@ -16,21 +17,54 @@ class InteractionGraphExtractor {
     extractInteractions(componentPath, componentName) {
         const context = this.contextResolver.extractContext(componentPath, componentName);
         const interactions = [];
-        // Walk all JSX elements looking for event handlers
         componentPath.traverse({
             JSXOpeningElement: (jsxPath) => {
                 const attributes = jsxPath.node.attributes || [];
                 for (const attr of attributes) {
-                    if (attr.type === 'JSXAttribute' &&
-                        attr.name?.name &&
-                        attr.name.name.startsWith('on')) {
-                        const eventName = attr.name.name;
-                        const settersCalledByEvent = this.resolveStateSettersForAttribute(attr, context);
-                        if (settersCalledByEvent.length === 0)
-                            continue;
-                        const interaction = this.extractTriggerAndEffect(jsxPath, componentPath, eventName, context, settersCalledByEvent);
+                    if (attr.type !== 'JSXAttribute' ||
+                        !attr.name?.name?.startsWith('on'))
+                        continue;
+                    const eventName = attr.name.name;
+                    // Path A: handler calls a known state setter → find conditional effect
+                    const settersCalledByEvent = this.resolveStateSettersForAttribute(attr, context);
+                    if (settersCalledByEvent.length > 0) {
+                        const interaction = this.buildInteractionFromSetters(jsxPath, componentPath, eventName, context, settersCalledByEvent);
                         if (interaction) {
                             interactions.push(interaction);
+                            continue;
+                        }
+                    }
+                    // Path B: handler contains router.push / router.replace → navigation effect
+                    const navTarget = this.resolveRouterNavigation(attr, context);
+                    if (navTarget) {
+                        const tagName = jsxPath.node.name?.name || 'unknown';
+                        interactions.push({
+                            trigger: { event: eventName, element: tagName },
+                            effect: {
+                                type: 'asyncEffect',
+                                waitStrategy: 'domSettle',
+                                settleMs: 0,
+                            },
+                        });
+                        continue;
+                    }
+                    // Path C: handler calls a setter with a modal/open-like name → domSettle fallback
+                    if (settersCalledByEvent.length > 0) {
+                        const hasModalSetter = settersCalledByEvent.some((s) => MODAL_STATE_PATTERN.test(s));
+                        if (hasModalSetter) {
+                            const tagName = jsxPath.node.name?.name || 'unknown';
+                            interactions.push({
+                                trigger: {
+                                    event: eventName,
+                                    element: tagName,
+                                    setsState: settersCalledByEvent[0],
+                                },
+                                effect: {
+                                    type: 'conditionalRender',
+                                    waitStrategy: 'domSettle',
+                                    settleMs: 150,
+                                },
+                            });
                         }
                     }
                 }
@@ -38,23 +72,96 @@ class InteractionGraphExtractor {
         });
         return interactions;
     }
-    /**
-     * Extract trigger/effect pair from a JSX element with an event handler.
-     */
-    extractTriggerAndEffect(jsxPath, componentPath, eventName, context, settersCalledByEvent) {
+    buildInteractionFromSetters(jsxPath, componentPath, eventName, context, settersCalledByEvent) {
         const tagName = jsxPath.node.name?.name || 'unknown';
-        const stateVar = settersCalledByEvent[0]; // Take first setter as primary
+        const stateVar = settersCalledByEvent[0];
         const trigger = {
             event: eventName,
             element: tagName,
             setsState: stateVar,
         };
-        // Look for conditional effects that depend on the modified state
+        // Try to find a conditional render driven by this state variable
         const effect = this.findConditionalEffect(jsxPath, componentPath, stateVar);
-        if (!effect) {
+        if (effect) {
+            return { trigger, effect };
+        }
+        // Fallback: if setter name looks modal-like, emit a domSettle effect
+        if (MODAL_STATE_PATTERN.test(stateVar)) {
+            return {
+                trigger,
+                effect: {
+                    type: 'conditionalRender',
+                    waitStrategy: 'domSettle',
+                    settleMs: 150,
+                },
+            };
+        }
+        // Generic async/loading pattern: setter name contains loading, pending, fetching
+        if (/loading|pending|fetching|submitting/i.test(stateVar)) {
+            return {
+                trigger,
+                effect: {
+                    type: 'asyncEffect',
+                    waitStrategy: 'domSettle',
+                    settleMs: 300,
+                },
+            };
+        }
+        return null;
+    }
+    /**
+     * Detect router.push() / router.replace() / navigate() calls inside a handler.
+     * Returns the destination route string if found, otherwise null.
+     */
+    resolveRouterNavigation(attr, context) {
+        if (attr.type !== 'JSXAttribute' || !attr.value || attr.value.type !== 'JSXExpressionContainer') {
             return null;
         }
-        return { trigger, effect };
+        const expression = attr.value.expression;
+        if (!expression)
+            return null;
+        const body = expression.type === 'ArrowFunctionExpression' || expression.type === 'FunctionExpression'
+            ? expression.body
+            : expression.type === 'Identifier'
+                ? this.findHandlerBody(expression.name, context)
+                : null;
+        if (!body)
+            return null;
+        return this.extractRouterCallFromNode(body);
+    }
+    findHandlerBody(handlerName, context) {
+        const handler = context.eventHandlers.find((h) => h.name === handlerName);
+        return handler?._body ?? null;
+    }
+    extractRouterCallFromNode(node) {
+        if (!node || typeof node !== 'object')
+            return null;
+        if (node.type === 'CallExpression') {
+            const callee = node.callee;
+            const isRouterCall = (callee?.type === 'MemberExpression' &&
+                (callee.object?.name === 'router' || callee.object?.name === 'navigate') &&
+                (callee.property?.name === 'push' || callee.property?.name === 'replace')) ||
+                (callee?.type === 'Identifier' && callee.name === 'navigate');
+            if (isRouterCall && node.arguments?.[0]?.type === 'StringLiteral') {
+                return node.arguments[0].value;
+            }
+        }
+        for (const key of Object.keys(node)) {
+            const value = node[key];
+            if (Array.isArray(value)) {
+                for (const child of value) {
+                    const found = this.extractRouterCallFromNode(child);
+                    if (found)
+                        return found;
+                }
+            }
+            else if (value && typeof value === 'object') {
+                const found = this.extractRouterCallFromNode(value);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
     }
     resolveStateSettersForAttribute(attr, context) {
         if (attr.type !== 'JSXAttribute' || !attr.value || attr.value.type !== 'JSXExpressionContainer') {
@@ -99,32 +206,23 @@ class InteractionGraphExtractor {
         for (const key of Object.keys(node)) {
             const value = node[key];
             if (Array.isArray(value)) {
-                for (const child of value) {
+                for (const child of value)
                     this.collectSettersFromNode(child, setterMap, result);
-                }
             }
             else if (value && typeof value === 'object') {
                 this.collectSettersFromNode(value, setterMap, result);
             }
         }
     }
-    /**
-     * Find conditional renders/effects that depend on a state variable.
-     * Looks for logical expressions and ternaries using the state var.
-     */
     findConditionalEffect(jsxPath, componentPath, stateVar) {
-        const directEffect = this.findConditionalEffectInAncestors(jsxPath, stateVar);
-        if (directEffect) {
-            return directEffect;
-        }
-        return this.findConditionalEffectInComponent(componentPath, stateVar);
+        return (this.findConditionalEffectInAncestors(jsxPath, stateVar) ||
+            this.findConditionalEffectInComponent(componentPath, stateVar));
     }
     findConditionalEffectInAncestors(jsxPath, stateVar) {
         let effectFound = null;
         let current = jsxPath.parentPath;
         while (current && !effectFound) {
             const node = current.node;
-            // Check for logical AND/OR: condition && <Component />
             if (node.type === 'LogicalExpression') {
                 if (this.nodeReferencesState(node.left, stateVar)) {
                     const rendersWhenTrue = this.extractComponentNameFromNode(node.right);
@@ -138,7 +236,6 @@ class InteractionGraphExtractor {
                     }
                 }
             }
-            // Check for ternary: condition ? <Component /> : null
             if (node.type === 'ConditionalExpression') {
                 if (this.nodeReferencesState(node.test, stateVar)) {
                     const rendersWhenTrue = this.extractComponentNameFromNode(node.consequent);
@@ -149,7 +246,9 @@ class InteractionGraphExtractor {
                             rendersWhenTrue: rendersWhenTrue ?? undefined,
                             rendersWhenFalse: rendersWhenFalse ?? undefined,
                             waitStrategy: 'elementAppears',
-                            selector: rendersWhenTrue ? `[data-clippy-component='${rendersWhenTrue}']` : undefined,
+                            selector: rendersWhenTrue
+                                ? `[data-clippy-component='${rendersWhenTrue}']`
+                                : undefined,
                         };
                     }
                 }
@@ -190,7 +289,9 @@ class InteractionGraphExtractor {
                             rendersWhenTrue: rendersWhenTrue ?? undefined,
                             rendersWhenFalse: rendersWhenFalse ?? undefined,
                             waitStrategy: 'elementAppears',
-                            selector: rendersWhenTrue ? `[data-clippy-component='${rendersWhenTrue}']` : undefined,
+                            selector: rendersWhenTrue
+                                ? `[data-clippy-component='${rendersWhenTrue}']`
+                                : undefined,
                         };
                     }
                 }
@@ -198,47 +299,34 @@ class InteractionGraphExtractor {
         });
         return effectFound;
     }
-    /**
-     * Check if a node references a specific state variable by name.
-     */
     nodeReferencesState(node, stateVar) {
-        if (node.type === 'Identifier' && node.name === stateVar) {
+        if (node.type === 'Identifier' && node.name === stateVar)
             return true;
-        }
-        if (node.type === 'MemberExpression') {
+        if (node.type === 'MemberExpression')
             return this.nodeReferencesState(node.object, stateVar);
-        }
-        if (node.type === 'CallExpression') {
+        if (node.type === 'CallExpression')
             return this.nodeReferencesState(node.callee, stateVar);
-        }
         if (node.type === 'BinaryExpression' || node.type === 'LogicalExpression') {
-            return this.nodeReferencesState(node.left, stateVar) || this.nodeReferencesState(node.right, stateVar);
+            return (this.nodeReferencesState(node.left, stateVar) ||
+                this.nodeReferencesState(node.right, stateVar));
         }
-        if (node.type === 'UnaryExpression') {
+        if (node.type === 'UnaryExpression')
             return this.nodeReferencesState(node.argument, stateVar);
-        }
         return false;
     }
-    /**
-     * Extract component name from a JSX element or identifier.
-     */
     extractComponentNameFromNode(node) {
         if (!node)
             return null;
         if (node.type === 'JSXElement' && node.openingElement?.name?.name) {
             const name = node.openingElement.name.name;
-            // Only return if it looks like a component (PascalCase)
             return /^[A-Z]/.test(name) ? name : null;
         }
-        if (node.type === 'JSXFragment') {
+        if (node.type === 'JSXFragment')
             return null;
-        }
-        if (node.type === 'Identifier' && /^[A-Z]/.test(node.name)) {
+        if (node.type === 'Identifier' && /^[A-Z]/.test(node.name))
             return node.name;
-        }
-        if (node.type === 'MemberExpression' && node.property?.name) {
+        if (node.type === 'MemberExpression' && node.property?.name)
             return node.property.name;
-        }
         return null;
     }
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './injection/ClippyIdInjector';
+export * from './injection/IdStrategy';
 export * from './buildId';
 export * from './upload/Adapter';
 export * from './upload/BackendAdapter';

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./injection/ClippyIdInjector"), exports);
+__exportStar(require("./injection/IdStrategy"), exports);
 __exportStar(require("./buildId"), exports);
 __exportStar(require("./upload/Adapter"), exports);
 __exportStar(require("./upload/BackendAdapter"), exports);

package/dist/injection/ClippyIdInjector.d.ts

@@ -3,10 +3,15 @@ export interface InjectedEntry {
     component: string;
     tag: string;
     line: number;
+    label?: string;
 }
 export interface InjectResult {
     source: string;
     injectedCount: number;
     injected: InjectedEntry[];
 }
-export declare function injectClippyIds(source: string, filePath: string): InjectResult;
+/**
+ * Inject data-clippy-id and data-clippy-component attributes into intrinsic HTML elements.
+ * IDs incorporate the route-derived component name and visible label text for readability.
+ */
+export declare function injectClippyIds(source: string, filePath: string, routePath?: string): InjectResult;

package/dist/injection/ClippyIdInjector.js

@@ -8,7 +8,11 @@ const parser_1 = require("@babel/parser");
 const traverse_1 = __importDefault(require("@babel/traverse"));
 const HtmlTagGuards_1 = require("./HtmlTagGuards");
 const IdStrategy_1 = require("./IdStrategy");
-function injectClippyIds(source, filePath) {
+/**
+ * Inject data-clippy-id and data-clippy-component attributes into intrinsic HTML elements.
+ * IDs incorporate the route-derived component name and visible label text for readability.
+ */
+function injectClippyIds(source, filePath, routePath) {
     let ast;
     try {
         ast = (0, parser_1.parse)(source, {
@@ -31,9 +35,22 @@ function injectClippyIds(source, filePath) {
             const attrs = opening.attributes;
             if ((0, HtmlTagGuards_1.hasAttribute)(attrs, 'data-clippy-id'))
                 return;
-            const componentName = findEnclosingComponentName(path) || (0, IdStrategy_1.deriveComponentName)(filePath);
+            // Resolve component name: prefer enclosing name, fall back to route-derived or filename
+            const enclosing = (0, IdStrategy_1.findEnclosingComponentName)(path);
+            let componentName;
+            if (enclosing && !IdStrategy_1.GENERIC_COMPONENT_NAMES.has(enclosing)) {
+                componentName = enclosing;
+            }
+            else if (routePath) {
+                componentName = (0, IdStrategy_1.deriveRouteComponentName)(routePath);
+            }
+            else {
+                componentName = (0, IdStrategy_1.deriveComponentName)(filePath);
+            }
             const line = opening.loc?.start.line ?? 0;
-            const clippyId = (0, IdStrategy_1.deriveClippyId)(componentName, tagName, line);
+            // Extract visible label text from element children for ID enrichment
+            const labelText = extractLabelFromOpeningElement(path, attrs);
+            const clippyId = (0, IdStrategy_1.deriveClippyId)(componentName, tagName, line, routePath, labelText ?? undefined);
             const componentAttr = (0, HtmlTagGuards_1.hasAttribute)(attrs, 'data-clippy-component')
                 ? ''
                 : ` data-clippy-component="${componentName}"`;
@@ -42,7 +59,13 @@ function injectClippyIds(source, filePath) {
             if (insertIndex === null)
                 return;
             edits.push({ index: insertIndex, text: insertText });
-            injected.push({ clippyId, component: componentName, tag: tagName, line });
+            injected.push({
+                clippyId,
+                component: componentName,
+                tag: tagName,
+                line,
+                label: labelText ?? undefined,
+            });
         },
     });
     if (edits.length === 0) {
@@ -51,26 +74,76 @@ function injectClippyIds(source, filePath) {
     const transformed = applyEdits(source, edits);
     return { source: transformed, injectedCount: edits.length, injected };
 }
-function findEnclosingComponentName(path) {
-    let current = path;
-    while (current) {
-        if (current.isFunctionDeclaration() && current.node.id?.name) {
-            return current.node.id.name;
+/**
+ * Extract a usable label from the element's attributes and children.
+ * Priority: aria-label > title > visible text content > placeholder > name.
+ */
+function extractLabelFromOpeningElement(path, attrs) {
+    // Check attributes first — fastest path
+    for (const attr of attrs) {
+        if (attr.type !== 'JSXAttribute')
+            continue;
+        const name = attr.name?.name;
+        if (name !== 'aria-label' && name !== 'title')
+            continue;
+        if (attr.value?.type === 'StringLiteral')
+            return attr.value.value;
+        if (attr.value?.type === 'JSXExpressionContainer' &&
+            attr.value.expression?.type === 'StringLiteral')
+            return attr.value.expression.value;
+    }
+    // Extract visible text from children
+    const parent = path.parentPath?.node;
+    if (parent?.children) {
+        const text = extractTextFromChildren(parent.children, 0);
+        const joined = text.join(' ').trim();
+        if (joined && joined.length <= 60) {
+            const sanitized = (0, IdStrategy_1.sanitizeLabelForId)(joined);
+            if (sanitized)
+                return joined; // return raw joined text; sanitization happens in deriveClippyId
         }
-        if (current.isClassDeclaration() && current.node.id?.name) {
-            return current.node.id.name;
+    }
+    // Fallback to placeholder / name for inputs
+    for (const attr of attrs) {
+        if (attr.type !== 'JSXAttribute')
+            continue;
+        const name = attr.name?.name;
+        if (name !== 'placeholder' && name !== 'name')
+            continue;
+        if (attr.value?.type === 'StringLiteral')
+            return attr.value.value;
+    }
+    return null;
+}
+function extractTextFromChildren(children, depth) {
+    if (depth > 3)
+        return [];
+    const texts = [];
+    for (const child of children) {
+        if (child.type === 'JSXText') {
+            const t = child.value.trim();
+            if (t)
+                texts.push(t);
         }
-        if (current.isVariableDeclarator() && current.node.id?.type === 'Identifier') {
-            return current.node.id.name;
+        else if (child.type === 'JSXExpressionContainer') {
+            if (child.expression?.type === 'StringLiteral') {
+                texts.push(child.expression.value);
+            }
+            else if (child.expression?.type === 'TemplateLiteral' &&
+                child.expression.quasis?.length === 1) {
+                const raw = child.expression.quasis[0].value.raw.trim();
+                if (raw)
+                    texts.push(raw);
+            }
         }
-        if ((current.isArrowFunctionExpression() || current.isFunctionExpression()) &&
-            current.parentPath?.isVariableDeclarator() &&
-            current.parentPath.node.id?.type === 'Identifier') {
-            return current.parentPath.node.id.name;
+        else if (child.type === 'JSXElement') {
+            const childTag = child.openingElement?.name?.name || '';
+            if (!/^(Icon|Svg|Loader|Spinner|Arrow|Check|Plus|Minus|Close|X)[A-Z]?/i.test(childTag)) {
+                texts.push(...extractTextFromChildren(child.children || [], depth + 1));
+            }
         }
-        current = current.parentPath;
     }
-    return null;
+    return texts.filter(Boolean);
 }
 function findAttributeInsertIndex(source, range) {
     if (!range)

package/dist/injection/IdStrategy.d.ts

@@ -1,2 +1,36 @@
+import type { NodePath } from '@babel/traverse';
 export declare function deriveComponentName(filePath: string, fallback?: string): string;
-export declare function deriveClippyId(componentName: string, tagName: string, lineNumber: number): string;
+/**
+ * Generic Next.js component names that should be replaced by a route-derived name.
+ */
+export declare const GENERIC_COMPONENT_NAMES: Set<string>;
+/**
+ * Infer the route path from an absolute file path.
+ * Handles both App Router (app/…/page.tsx) and Pages Router (pages/….tsx).
+ * Returns null if the file is not a route file.
+ */
+export declare function inferRouteFromFilePath(filePath: string): string | null;
+/**
+ * Convert a route path to a PascalCase component name.
+ * /admin/transactions      → AdminTransactions
+ * /dashboard/forms/[id]   → DashboardForms
+ * /auth/forgot-password   → AuthForgotPassword
+ */
+export declare function deriveRouteComponentName(routePath: string): string;
+/**
+ * Compute a short route hash for use in stable IDs.
+ * Takes a route path (e.g., "/admin/transactions") and produces a 4-char hash.
+ */
+export declare function hashRoutePath(routePath: string): string;
+/**
+ * Sanitize a label string for embedding in a CSS/HTML attribute ID.
+ * TitleCase, max 2 words, alphanumeric only, minimum 2 chars.
+ * Returns null if no usable text can be extracted.
+ */
+export declare function sanitizeLabelForId(label: string): string | null;
+export declare function deriveClippyId(componentName: string, tagName: string, lineNumber: number, routePath?: string, labelText?: string): string;
+/**
+ * Walk the AST upward to find the enclosing React component name.
+ * Exported here so both the injector and the extractor use the same logic.
+ */
+export declare function findEnclosingComponentName(path: NodePath<any>): string | null;

package/dist/injection/IdStrategy.js

@@ -3,8 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GENERIC_COMPONENT_NAMES = void 0;
 exports.deriveComponentName = deriveComponentName;
+exports.inferRouteFromFilePath = inferRouteFromFilePath;
+exports.deriveRouteComponentName = deriveRouteComponentName;
+exports.hashRoutePath = hashRoutePath;
+exports.sanitizeLabelForId = sanitizeLabelForId;
 exports.deriveClippyId = deriveClippyId;
+exports.findEnclosingComponentName = findEnclosingComponentName;
 const path_1 = __importDefault(require("path"));
 function deriveComponentName(filePath, fallback) {
     if (fallback)
@@ -15,11 +21,115 @@ function deriveComponentName(filePath, fallback) {
     }
     return normalizeComponentName(base);
 }
-function deriveClippyId(componentName, tagName, lineNumber) {
+/**
+ * Generic Next.js component names that should be replaced by a route-derived name.
+ */
+exports.GENERIC_COMPONENT_NAMES = new Set([
+    'Page', 'Layout', 'App', 'Index', 'Component', 'Default',
+    'Loading', 'Error', 'NotFound', 'Template', 'Root',
+]);
+/**
+ * Infer the route path from an absolute file path.
+ * Handles both App Router (app/…/page.tsx) and Pages Router (pages/….tsx).
+ * Returns null if the file is not a route file.
+ */
+function inferRouteFromFilePath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const appMatch = normalized.match(/\/app(\/.*?)\/page\.[jt]sx?$/);
+    if (appMatch) {
+        const segment = appMatch[1]
+            .replace(/\/\([^)]+\)/g, ''); // strip route groups like (auth)
+        return segment || '/';
+    }
+    const pagesMatch = normalized.match(/\/pages(\/.*?)\.[jt]sx?$/);
+    if (pagesMatch) {
+        const segment = pagesMatch[1].replace(/\/index$/, '') || '/';
+        return segment;
+    }
+    return null;
+}
+/**
+ * Convert a route path to a PascalCase component name.
+ * /admin/transactions      → AdminTransactions
+ * /dashboard/forms/[id]   → DashboardForms
+ * /auth/forgot-password   → AuthForgotPassword
+ */
+function deriveRouteComponentName(routePath) {
+    const name = routePath
+        .split('/')
+        .filter(Boolean)
+        .filter(s => !s.startsWith('[') && !s.startsWith(':') && !s.startsWith('$'))
+        .map(s => s
+        .split('-')
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(''))
+        .join('');
+    return name || 'Page';
+}
+/**
+ * Compute a short route hash for use in stable IDs.
+ * Takes a route path (e.g., "/admin/transactions") and produces a 4-char hash.
+ */
+function hashRoutePath(routePath) {
+    let hash = 0;
+    for (let i = 0; i < routePath.length; i++) {
+        hash = (hash << 5) - hash + routePath.charCodeAt(i);
+        hash = hash & hash;
+    }
+    return Math.abs(hash).toString(36).slice(0, 4);
+}
+/**
+ * Sanitize a label string for embedding in a CSS/HTML attribute ID.
+ * TitleCase, max 2 words, alphanumeric only, minimum 2 chars.
+ * Returns null if no usable text can be extracted.
+ */
+function sanitizeLabelForId(label) {
+    const words = label
+        .replace(/[^A-Za-z0-9\s]/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 2)
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+    const result = words.join('');
+    return result.length >= 2 ? result : null;
+}
+function deriveClippyId(componentName, tagName, lineNumber, routePath, labelText) {
     const sanitizedComponent = normalizeComponentName(componentName);
     const normalizedTag = tagName.replace(/[^a-z0-9]/gi, '') || 'element';
+    const sanitizedLabel = labelText ? sanitizeLabelForId(labelText) : null;
     const stableLine = lineNumber > 0 ? lineNumber : 0;
-    return `${sanitizedComponent}-${normalizedTag}-${stableLine}`;
+    const parts = [sanitizedComponent];
+    if (sanitizedLabel)
+        parts.push(sanitizedLabel);
+    parts.push(normalizedTag);
+    parts.push(String(stableLine));
+    return parts.join('-');
+}
+/**
+ * Walk the AST upward to find the enclosing React component name.
+ * Exported here so both the injector and the extractor use the same logic.
+ */
+function findEnclosingComponentName(path) {
+    let current = path;
+    while (current) {
+        if (current.isFunctionDeclaration() && current.node.id?.name) {
+            return current.node.id.name;
+        }
+        if (current.isClassDeclaration() && current.node.id?.name) {
+            return current.node.id.name;
+        }
+        if (current.isVariableDeclarator() && current.node.id?.type === 'Identifier') {
+            return current.node.id.name;
+        }
+        if ((current.isArrowFunctionExpression() || current.isFunctionExpression()) &&
+            current.parentPath?.isVariableDeclarator() &&
+            current.parentPath.node.id?.type === 'Identifier') {
+            return current.parentPath.node.id.name;
+        }
+        current = current.parentPath;
+    }
+    return null;
 }
 function normalizeComponentName(value) {
     const sanitized = value

package/dist/types.d.ts

@@ -38,6 +38,9 @@ export interface DiscoveredElement {
     nearbyText: string[];
     semanticRole: string;
     interactions: string[];
+    label?: string;
+    component?: string;
+    isNavigationLink?: boolean;
     loc?: {
         line: number;
     };
@@ -62,6 +65,7 @@ export interface InferredFlow {
     page: string;
     steps: string[];
     edges: FlowEdge[];
+    intentPatterns?: string[];
 }
 export interface ArtifactMetadata {
     version: string;
@@ -91,6 +95,7 @@ export interface PolicySelectorEntry {
     selector: string;
     tag: string;
     component: string;
+    label?: string;
     route: string;
     filePath: string;
     attributes: Array<{
@@ -136,7 +141,8 @@ export interface SelectorManifestEntry {
     selector: string;
     component: string;
     tag: string;
-    route: string;
+    label?: string;
+    routes: string[];
 }
 export interface SelectorManifest {
     version: string;

package/dist/upload/PackageBuilder.d.ts

@@ -26,6 +26,8 @@ export declare class PackageBuilder {
     }): SelectorManifest;
     build(data: Omit<KnowledgePackage, 'generatedAt'>): Buffer;
     buildArtifactsBuffer(artifacts: PolicyArtifacts): Buffer;
+    private inferProjectRoot;
+    private normalizePath;
     private toPolicySelectors;
     private toPolicyComponents;
     private toPolicyFlows;

package/dist/upload/PackageBuilder.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageBuilder = void 0;
 const zlib_1 = __importDefault(require("zlib"));
+const path_1 = __importDefault(require("path"));
 const IdStrategy_1 = require("../injection/IdStrategy");
 class PackageBuilder {
     constructor() {
@@ -39,31 +40,51 @@ class PackageBuilder {
         };
     }
     buildPolicyDocument(data) {
-        const policySelectors = this.toPolicySelectors(data.selectors);
+        const projectRoot = this.inferProjectRoot(data.routes);
+        const normalizedRoutes = data.routes.map((r) => ({
+            ...r,
+            filePath: this.normalizePath(r.filePath, projectRoot),
+            layout: r.layout ? this.normalizePath(r.layout, projectRoot) : null,
+        }));
+        const policySelectors = this.toPolicySelectors(data.selectors, projectRoot);
         return {
             version: this.version,
             buildId: data.buildId,
             generatedAt: data.generatedAt,
             bundler: data.bundler,
-            routes: data.routes,
+            routes: normalizedRoutes,
             selectors: policySelectors,
             components: data.components ?? this.toPolicyComponents(data.selectors),
-            flows: this.toPolicyFlows(data.flows, data.routes, policySelectors),
+            flows: this.toPolicyFlows(data.flows, normalizedRoutes, policySelectors),
         };
     }
     buildSelectorManifest(data) {
-        const selectors = data.selectors.map((entry) => ({
-            id: entry.clippyId,
-            selector: entry.selector,
-            component: entry.component,
-            tag: entry.tag,
-            route: entry.route,
-        }));
+        // Deduplicate by clippyId — shared components used on multiple routes appear once
+        // with a routes[] array listing every route where they appear.
+        const byId = new Map();
+        for (const entry of data.selectors) {
+            if (byId.has(entry.clippyId)) {
+                const existing = byId.get(entry.clippyId);
+                if (!existing.routes.includes(entry.route)) {
+                    existing.routes.push(entry.route);
+                }
+            }
+            else {
+                byId.set(entry.clippyId, {
+                    id: entry.clippyId,
+                    selector: entry.selector,
+                    component: entry.component,
+                    tag: entry.tag,
+                    label: entry.label,
+                    routes: [entry.route],
+                });
+            }
+        }
         return {
             version: this.version,
             buildId: data.buildId,
             generatedAt: data.generatedAt,
-            selectors,
+            selectors: Array.from(byId.values()),
         };
     }
     build(data) {
@@ -73,9 +94,37 @@ class PackageBuilder {
     buildArtifactsBuffer(artifacts) {
         return zlib_1.default.gzipSync(JSON.stringify(artifacts));
     }
-    toPolicySelectors(selectors) {
-        return selectors.map((element, index) => {
-            const component = (0, IdStrategy_1.deriveComponentName)(element.filePath);
+    inferProjectRoot(routes) {
+        const filePaths = routes.map((r) => r.filePath).filter(Boolean);
+        if (filePaths.length === 0)
+            return process.cwd();
+        // Find the longest common directory prefix across all route file paths
+        const parts = filePaths[0].replace(/\\/g, '/').split('/');
+        let commonParts = parts;
+        for (const fp of filePaths.slice(1)) {
+            const fpParts = fp.replace(/\\/g, '/').split('/');
+            const len = Math.min(commonParts.length, fpParts.length);
+            let i = 0;
+            while (i < len && commonParts[i] === fpParts[i])
+                i++;
+            commonParts = commonParts.slice(0, i);
+        }
+        return commonParts.join('/') || process.cwd();
+    }
+    normalizePath(filePath, projectRoot) {
+        try {
+            const rel = path_1.default.relative(projectRoot, filePath).replace(/\\/g, '/');
+            return rel.startsWith('..') ? filePath.replace(/\\/g, '/') : rel;
+        }
+        catch {
+            return filePath.replace(/\\/g, '/');
+        }
+    }
+    toPolicySelectors(selectors, projectRoot) {
+        return selectors
+            .filter((element) => !element.isNavigationLink)
+            .map((element, index) => {
+            const component = element.component || (0, IdStrategy_1.deriveComponentName)(element.filePath);
             const preferred = element.selectors.find((candidate) => candidate.type === 'clippy_id') ||
                 element.selectors[0];
             const stableLine = element.loc?.line ?? index;
@@ -90,8 +139,9 @@ class PackageBuilder {
                 selector,
                 tag: element.tag,
                 component,
+                label: element.label,
                 route: element.route,
-                filePath: element.filePath,
+                filePath: projectRoot ? this.normalizePath(element.filePath, projectRoot) : element.filePath.replace(/\\/g, '/'),
                 attributes: Object.entries(element.staticProps).map(([name, value]) => ({ name, value })),
                 candidates: element.selectors,
             };
@@ -100,12 +150,16 @@ class PackageBuilder {
     toPolicyComponents(selectors) {
         const byFile = new Map();
         for (const element of selectors) {
+            if (element.isNavigationLink)
+                continue;
             if (!byFile.has(element.filePath))
                 byFile.set(element.filePath, []);
             byFile.get(element.filePath).push(element);
         }
         return Array.from(byFile.entries()).map(([filePath, items]) => {
-            const componentName = this.deriveComponentName(filePath);
+            // Prefer the component name captured during extraction over the filename
+            const componentName = items.find((i) => i.component)?.component ||
+                this.deriveComponentName(filePath);
             const route = items[0]?.route || '/';
             return {
                 name: componentName,
@@ -119,25 +173,48 @@ class PackageBuilder {
     toPolicyFlows(flows, routes, selectors) {
         return flows.map((flow, flowIndex) => {
             const firstRoute = flow.steps[0] || '/';
-            const page = flow.page || routes.find((route) => route.path === firstRoute)?.path || firstRoute;
-            const hasInteraction = flow.edges.some((edge) => edge.from === edge.to && edge.trigger?.startsWith('on'));
+            const page = flow.page || routes.find((r) => r.path === firstRoute)?.path || firstRoute;
             const steps = flow.steps.map((routePath, stepIndex) => {
-                const target = selectors.find((entry) => entry.route === routePath)?.selector ||
-                    `[data-clippy-route='${routePath}']`;
+                // For transition steps (not the first), find the edge that leads to this route
+                // and try to match its trigger text to a specific selector
+                const incomingEdge = stepIndex > 0
+                    ? flow.edges.find((e) => e.to === routePath)
+                    : null;
+                let target;
+                if (incomingEdge?.trigger && incomingEdge.trigger !== 'link') {
+                    // Try to find the specific triggering element by label match
+                    const fromRoute = incomingEdge.from;
+                    const byLabel = selectors.find((s) => s.route === fromRoute &&
+                        s.label?.toLowerCase() === incomingEdge.trigger.toLowerCase());
+                    const byAttr = !byLabel
+                        ? selectors.find((s) => s.route === fromRoute &&
+                            s.attributes.some((a) => a.value.toLowerCase() === incomingEdge.trigger.toLowerCase()))
+                        : null;
+                    target = (byLabel || byAttr)?.selector;
+                }
+                // Fallback: first selector on the destination route
+                if (!target) {
+                    target =
+                        selectors.find((s) => s.route === routePath)?.selector ||
+                            `[data-clippy-route='${routePath}']`;
+                }
+                const isFirst = stepIndex === 0;
+                const isInteractionStep = flow.edges.some((e) => e.from === e.to && e.trigger?.startsWith('on'));
                 return {
                     step: stepIndex + 1,
-                    action: stepIndex === 0
-                        ? hasInteraction
-                            ? 'interact'
-                            : 'navigate'
+                    action: isFirst
+                        ? isInteractionStep ? 'interact' : 'navigate'
                         : 'transition',
                     target,
                 };
             });
+            const intentPatterns = flow.intentPatterns && flow.intentPatterns.length > 0
+                ? flow.intentPatterns
+                : [flow.name.toLowerCase()];
             return {
                 flowId: flow.id || `flow_${flowIndex + 1}`,
                 page,
-                intentPatterns: [flow.name.toLowerCase()],
+                intentPatterns,
                 steps,
             };
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcoder-x/plugin-shared",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",