@immense/vue-pom-generator 1.0.66 → 1.0.68

package/dist/index.mjs

@@ -645,7 +645,7 @@ function createInlineParameter(name, options = {}) {
     initializer: options.initializer
   };
 }
-function removeByKeySegment$1(value) {
+function removeByKeySegment(value) {
   const idx = value.lastIndexOf("ByKey");
   if (idx < 0) {
     return value;
@@ -849,13 +849,13 @@ function generateGetElementByDataTestId(componentName, methodName, nativeRole, s
   const roleSuffix = upperFirst$1(nativeRole || "Element");
   const baseName = upperFirst$1(methodName);
   const numericSuffix = baseName.startsWith(roleSuffix) ? baseName.slice(roleSuffix.length) : "";
-  const hasRoleSuffix2 = baseName.endsWith(roleSuffix) || baseName.startsWith(roleSuffix) && isAllDigits(numericSuffix);
-  const propertyName = hasRoleSuffix2 ? `${baseName}` : `${baseName}${roleSuffix}`;
+  const hasRoleSuffix = baseName.endsWith(roleSuffix) || baseName.startsWith(roleSuffix) && isAllDigits(numericSuffix);
+  const propertyName = hasRoleSuffix ? `${baseName}` : `${baseName}${roleSuffix}`;
   const selectorParams = orderPomPatternParameters(parameters, [selector]);
   const indexedVariable = getIndexedPomPatternVariable(selector);
   if (indexedVariable) {
     const keyType = getPomParameter(selectorParams, indexedVariable)?.typeExpression || "string";
-    const keyedPropertyName = getterNameOverride ?? removeByKeySegment$1(propertyName);
+    const keyedPropertyName = getterNameOverride ?? removeByKeySegment(propertyName);
     return [
       createClassGetter({
         name: keyedPropertyName,
@@ -2894,7 +2894,7 @@ Fix: either (1) include ${bestKeyPreservePlaceholder} in your :${attrLabel} temp
     }
     return value.slice(0, idx) + value.slice(idx + "ByKey".length);
   };
-  const hasRoleSuffix2 = (baseName, roleSuffix) => {
+  const hasRoleSuffix = (baseName, roleSuffix) => {
     if (baseName.endsWith(roleSuffix)) {
       return true;
     }
@@ -2904,13 +2904,13 @@ Fix: either (1) include ${bestKeyPreservePlaceholder} in your :${attrLabel} temp
   const getPrimaryGetterName = (primaryMethodName) => {
     const roleSuffix = upperFirst(normalizedRole || "Element");
     const baseName = upperFirst(primaryMethodName);
-    const propertyName = hasRoleSuffix2(baseName, roleSuffix) ? baseName : `${baseName}${roleSuffix}`;
+    const propertyName = hasRoleSuffix(baseName, roleSuffix) ? baseName : `${baseName}${roleSuffix}`;
     return selectorIsParameterized ? removeByKeySegment2(propertyName) : propertyName;
   };
   const getPrimaryGetterNameCandidates = (primaryMethodName) => {
     const roleSuffix = upperFirst(normalizedRole || "Element");
     const baseName = upperFirst(primaryMethodName);
-    const propertyName = hasRoleSuffix2(baseName, roleSuffix) ? baseName : `${baseName}${roleSuffix}`;
+    const propertyName = hasRoleSuffix(baseName, roleSuffix) ? baseName : `${baseName}${roleSuffix}`;
     if (!selectorIsParameterized) {
       return { primary: propertyName };
     }
@@ -3037,7 +3037,7 @@ Fix: either (1) include ${bestKeyPreservePlaceholder} in your :${attrLabel} temp
       if (conflicts && nameCollisionBehavior === "error") {
         const roleSuffix = upperFirst(normalizedRole || "Element");
         const baseNameUpper = upperFirst(baseWithSuffix);
-        if (!hasRoleSuffix2(baseNameUpper, roleSuffix)) {
+        if (!hasRoleSuffix(baseNameUpper, roleSuffix)) {
           const baseWithRoleSuffix = `${baseWithSuffix}${roleSuffix}`;
           const candidateWithRoleSuffix = selectorIsParameterized ? `${baseWithRoleSuffix}ByKey` : baseWithRoleSuffix;
           const actionNameWithRoleSuffix = getPrimaryActionMethodName(candidateWithRoleSuffix);
@@ -3147,12 +3147,32 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
     alternateSelectors: void 0,
     mergeKey: args.pomMergeKey,
     parameters: normalizedParameters,
-    keyValuesOverride: args.keyValuesOverride ?? null
+    keyValuesOverride: args.keyValuesOverride ?? null,
+    generatedActionName: getPrimaryActionMethodName(methodName),
+    generatedPropertyName: getterNameOverride ?? getPrimaryGetterName(methodName)
     // emitPrimary defaults to true; special cases (including merge) may set it to false below.
   };
   if (mergedIntoExisting && dataTestIdEntry.pom) {
     dataTestIdEntry.pom.emitPrimary = false;
   }
+  if (addHtmlAttribute && args.annotatorMetadata && dataTestIdEntry.pom) {
+    const filename = args.contextFilename?.trim();
+    if (!filename) {
+      throw new Error(`[vue-pom-generator] runtime.annotator.enabled requires contextFilename for ${args.componentName}.`);
+    }
+    const sourceLocation = args.element.loc?.start;
+    if (!sourceLocation) {
+      throw new Error(`[vue-pom-generator] runtime.annotator.enabled requires element source locations for ${args.componentName}.`);
+    }
+    const metadataAttributePrefix = args.annotatorMetadata.metadataAttributePrefix;
+    upsertAttribute(args.element, args.annotatorMetadata.sourceAttribute, staticAttributeValue(`${filename}:${sourceLocation.line}:${sourceLocation.column}`));
+    upsertAttribute(args.element, `${metadataAttributePrefix}-component`, staticAttributeValue(args.componentName));
+    upsertAttribute(args.element, `${metadataAttributePrefix}-tag`, staticAttributeValue(args.element.tag));
+    upsertAttribute(args.element, `${metadataAttributePrefix}-testid`, runtimeDataTestId);
+    upsertAttribute(args.element, `${metadataAttributePrefix}-action`, staticAttributeValue(buildPomGeneratedActionName(dataTestIdEntry.pom)));
+    upsertAttribute(args.element, `${metadataAttributePrefix}-property`, staticAttributeValue(buildPomGeneratedPropertyName(dataTestIdEntry.pom)));
+    upsertAttribute(args.element, `${metadataAttributePrefix}-role`, staticAttributeValue(normalizedRole));
+  }
   args.dependencies.childrenComponentSet.add(childComponentName);
   args.dependencies.usedComponentSet.add(childComponentName);
   args.dependencies.dataTestIdSet.add(dataTestIdEntry);
@@ -3351,7 +3371,7 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
           registerGeneratedMethodSignature(generatedName2, createPomMethodSignature([createPomParameterSpec("annotationText", `string = ""`)]));
         }
       }
-      return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting };
+      return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting, entry: dataTestIdEntry };
     }
     const generatedName = ensureUniqueGeneratedName(`select${upperFirst(methodName || "Radio")}`);
     if (dataTestIdEntry.pom) {
@@ -3378,7 +3398,7 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
         createPomParameterSpec("annotationText", `string = ""`)
       ]));
     }
-    return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting };
+    return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting, entry: dataTestIdEntry };
   }
   const staticKeyValues = args.keyValuesOverride ?? null;
   const needsKey = hasPomParameter(normalizedParameters, "key") && selectorIsParameterized;
@@ -3412,7 +3432,7 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
         ]));
       }
     }
-    return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting };
+    return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting, entry: dataTestIdEntry };
   }
   if (dataTestIdEntry.pom) {
     if (dataTestIdEntry.pom.emitPrimary !== false) {
@@ -3426,7 +3446,66 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
     const generatedName = getGeneratedMethodName();
     registerGeneratedMethodSignature(generatedName, signature);
   }
-  return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting };
+  return { selectorValue: dataTestId, runtimeValue: runtimeDataTestId, fromExisting, entry: dataTestIdEntry };
+}
+function requireStructuredPomName(value, fieldName, pom) {
+  const normalized = value?.trim();
+  if (normalized) {
+    return normalized;
+  }
+  throw new Error(`[vue-pom-generator] Missing ${fieldName} for POM spec ${pom.methodName}.`);
+}
+function buildPomGeneratedPropertyName(pom) {
+  return requireStructuredPomName(pom.generatedPropertyName, "generatedPropertyName", pom);
+}
+function buildPomGeneratedActionName(pom) {
+  return requireStructuredPomName(pom.generatedActionName, "generatedActionName", pom);
+}
+const STANDALONE_WRAPPER_FALLBACK_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "input",
+  "select",
+  "vselect",
+  "checkbox",
+  "toggle",
+  "radio"
+]);
+function stripTrailingAsciiDigits(value) {
+  let end = value.length;
+  while (end > 0 && isAsciiDigitCode(value.charCodeAt(end - 1))) {
+    end -= 1;
+  }
+  return value.slice(0, end);
+}
+function matchesStandaloneWrapperFallbackMethodName(methodName, componentClassName) {
+  let normalizedMethodName = methodName;
+  if (normalizedMethodName.endsWith("ByKey")) {
+    normalizedMethodName = normalizedMethodName.slice(0, -"ByKey".length);
+  }
+  normalizedMethodName = stripTrailingAsciiDigits(normalizedMethodName);
+  return normalizedMethodName === componentClassName;
+}
+function shouldSuppressStandaloneWrapperFallbackSurface(componentName, dependencies) {
+  if (dependencies.isView || (dependencies.pomExtraMethods?.length ?? 0) > 0) {
+    return false;
+  }
+  const entries = Array.from(dependencies.dataTestIdSet ?? []);
+  if (!entries.length) {
+    return false;
+  }
+  const primaryEntries = entries.filter((entry) => {
+    return !!entry.pom && entry.pom.emitPrimary !== false;
+  });
+  if (!primaryEntries.length || primaryEntries.length !== entries.length) {
+    return false;
+  }
+  const componentClassName = toPascalCase(componentName.endsWith(".vue") ? componentName.slice(0, -4) : componentName);
+  if (!componentClassName) {
+    return false;
+  }
+  return primaryEntries.every(({ pom }) => {
+    return STANDALONE_WRAPPER_FALLBACK_ROLES.has(pom.nativeRole) && matchesStandaloneWrapperFallbackMethodName(pom.methodName, componentClassName);
+  });
 }
 function safeRealpath(value) {
   try {
@@ -3443,6 +3522,14 @@ function safeRealpath(value) {
   const resolvedParent = safeRealpath(parent);
   return resolvedParent === parent ? value : path.join(resolvedParent, path.basename(value));
 }
+function normalizeScopePath(value, pathImpl = path) {
+  return pathImpl.normalize(value);
+}
+function isNormalizedPathWithinDir(filePathAbs, dirPathAbs, pathImpl = path) {
+  const normalizedFileAbs = normalizeScopePath(filePathAbs, pathImpl);
+  const normalizedDirAbs = normalizeScopePath(dirPathAbs, pathImpl);
+  return normalizedFileAbs === normalizedDirAbs || normalizedFileAbs.startsWith(`${normalizedDirAbs}${pathImpl.sep}`);
+}
 function isPathWithinDir(filePathAbs, dirPathAbs) {
   const fileAbs = path.resolve(filePathAbs);
   const dirAbs = path.resolve(dirPathAbs);
@@ -3472,6 +3559,43 @@ function resolveComponentNameFromPath(options) {
   }
   return toPascalCase(path.parse(normalizedAbsFilename).name);
 }
+function isFileInConfiguredSourceScope(options) {
+  const { filename, projectRoot, viewsDirAbs, sourceDirs, extraRoots = [], pathImpl = path } = options;
+  if (!filename) {
+    return false;
+  }
+  const cleanFilename = filename.includes("?") ? filename.substring(0, filename.indexOf("?")) : filename;
+  const normalizedProjectRoot = normalizeScopePath(projectRoot, pathImpl);
+  const normalizedAbsFilename = normalizeScopePath(
+    pathImpl.isAbsolute(cleanFilename) ? cleanFilename : pathImpl.resolve(normalizedProjectRoot, cleanFilename),
+    pathImpl
+  );
+  if (normalizedAbsFilename.includes(`${pathImpl.sep}node_modules${pathImpl.sep}`) || normalizedAbsFilename.includes("/node_modules/")) {
+    return false;
+  }
+  const normalizedViewsDirAbs = normalizeScopePath(viewsDirAbs, pathImpl);
+  if (isNormalizedPathWithinDir(normalizedAbsFilename, normalizedViewsDirAbs, pathImpl)) {
+    return true;
+  }
+  const rootsToTry = Array.from(/* @__PURE__ */ new Set([
+    normalizedProjectRoot,
+    ...extraRoots.map((root) => normalizeScopePath(root, pathImpl))
+  ]));
+  return sourceDirs.some((dir) => {
+    return rootsToTry.some((root) => {
+      const normalizedAbsDir = normalizeScopePath(pathImpl.resolve(root, dir), pathImpl);
+      if (isNormalizedPathWithinDir(normalizedAbsFilename, normalizedAbsDir, pathImpl)) {
+        return true;
+      }
+      if (dir.startsWith("app/") && pathImpl.basename(root) === "app") {
+        const relativeDir = dir.substring(4);
+        const normalizedAbsDirAlt = normalizeScopePath(pathImpl.resolve(root, relativeDir), pathImpl);
+        return isNormalizedPathWithinDir(normalizedAbsFilename, normalizedAbsDirAlt, pathImpl);
+      }
+      return false;
+    });
+  });
+}
 let routerIntrospectionQueue = Promise.resolve();
 async function runRouterIntrospectionExclusive(fn) {
   const prev = routerIntrospectionQueue.catch(() => void 0);
@@ -4726,6 +4850,11 @@ async function generateFiles(componentHierarchyMap, vueFilesPathMap, basePageCla
     componentDirs,
     layoutDirs
   }) : void 0);
+  const emittableComponentHierarchyMap = new Map(
+    Array.from(componentHierarchyMap.entries()).filter(([componentName, dependencies]) => {
+      return !shouldSuppressStandaloneWrapperFallbackSurface(componentName, dependencies);
+    })
+  );
   const generatedFilePaths = [];
   const writeGeneratedFile = (file) => {
     const resolvedFilePath = path.resolve(file.filePath);
@@ -4733,7 +4862,7 @@ async function generateFiles(componentHierarchyMap, vueFilesPathMap, basePageCla
     generatedFilePaths.push(resolvedFilePath);
   };
   if (emitLanguages.includes("ts")) {
-    const files = typescriptOutputStructure === "split" ? await generateSplitTypeScriptFiles(componentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
+    const files = typescriptOutputStructure === "split" ? await generateSplitTypeScriptFiles(emittableComponentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
       customPomAttachments,
       projectRoot,
       customPomDir,
@@ -4743,7 +4872,7 @@ async function generateFiles(componentHierarchyMap, vueFilesPathMap, basePageCla
       testIdAttribute,
       routeMetaByComponent,
       vueRouterFluentChaining
-    }) : await generateAggregatedFiles(componentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
+    }) : await generateAggregatedFiles(emittableComponentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
       customPomAttachments,
       projectRoot,
       customPomDir,
@@ -4757,7 +4886,7 @@ async function generateFiles(componentHierarchyMap, vueFilesPathMap, basePageCla
     for (const file of files) {
       writeGeneratedFile(file);
     }
-    const fixtureRegistryFile = maybeGenerateFixtureRegistry(componentHierarchyMap, {
+    const fixtureRegistryFile = maybeGenerateFixtureRegistry(emittableComponentHierarchyMap, {
       generateFixtures,
       pomOutDir: outDir,
       projectRoot,
@@ -4768,7 +4897,7 @@ async function generateFiles(componentHierarchyMap, vueFilesPathMap, basePageCla
     }
   }
   if (emitLanguages.includes("csharp")) {
-    const csFiles = generateAggregatedCSharpFiles(componentHierarchyMap, outDir, {
+    const csFiles = generateAggregatedCSharpFiles(emittableComponentHierarchyMap, outDir, {
       testIdAttribute,
       csharp
     });
@@ -5505,7 +5634,12 @@ function prepareViewObjectModelClass(componentName, dependencies, componentHiera
   const rawComponentRefsForInstances = isView ? usedComponentSet?.size ? usedComponentSet : childrenComponentSet : childrenComponentSet;
   const componentRefsForInstances = /* @__PURE__ */ new Set();
   for (const ref of rawComponentRefsForInstances) {
-    componentRefsForInstances.add(resolveTrackedComponentRef(ref) ?? normalizeTrackedComponentRef(ref));
+    const resolvedRef = resolveTrackedComponentRef(ref) ?? normalizeTrackedComponentRef(ref);
+    const resolvedDependencies = componentHierarchyMap.get(resolvedRef);
+    if (!resolvedDependencies?.dataTestIdSet.size) {
+      continue;
+    }
+    componentRefsForInstances.add(resolvedRef);
   }
   const hasChildComponent = (needle) => {
     const normalizedNeedle = normalizeTrackedComponentRef(needle);
@@ -7064,6 +7198,7 @@ function createTestIdTransform(componentName, componentHierarchyMap, nativeWrapp
   const warn = options.warn;
   const vueFilesPathMap = options.vueFilesPathMap;
   const wrapperSearchRoots = options.wrapperSearchRoots ?? [];
+  const annotatorMetadata = options.annotatorMetadata ?? null;
   const safeRealpath2 = (p) => {
     try {
       return fs.existsSync(p) ? fs.realpathSync(p) : p;
@@ -7327,7 +7462,8 @@ function createTestIdTransform(componentName, componentHierarchyMap, nativeWrapp
         testIdAttribute,
         existingIdBehavior,
         nameCollisionBehavior,
-        warn
+        warn,
+        annotatorMetadata
       });
     };
     const { nativeWrappersValue, optionDataTestIdPrefixValue, semanticNameHint } = getNativeWrapperTransformInfo(element, componentName, nativeWrappers);
@@ -8318,48 +8454,6 @@ function collectAccessibilityReviewWarnings(manifest) {
   }
   return warnings;
 }
-function removeByKeySegment(value) {
-  const idx = value.indexOf("ByKey");
-  if (idx < 0) {
-    return value;
-  }
-  return value.slice(0, idx) + value.slice(idx + "ByKey".length);
-}
-function hasRoleSuffix(baseName, roleSuffix) {
-  if (baseName.endsWith(roleSuffix)) {
-    return true;
-  }
-  const re = new RegExp(`^${roleSuffix}\\d+$`);
-  return re.test(baseName);
-}
-function getGeneratedPropertyName(pom) {
-  if (pom.getterNameOverride) {
-    return pom.getterNameOverride;
-  }
-  const roleSuffix = upperFirst(pom.nativeRole || "Element");
-  const baseName = upperFirst(pom.methodName);
-  const propertyName = hasRoleSuffix(baseName, roleSuffix) ? baseName : `${baseName}${roleSuffix}`;
-  return pom.selector.patternKind === "parameterized" ? removeByKeySegment(propertyName) : propertyName;
-}
-function getGeneratedActionName(entry, pom) {
-  const methodNameUpper = upperFirst(pom.methodName);
-  const radioMethodNameUpper = upperFirst(pom.methodName || "Radio");
-  const isNavigation = !!entry.targetPageObjectModelClass;
-  if (isNavigation) {
-    return `goTo${methodNameUpper}`;
-  }
-  switch (pom.nativeRole) {
-    case "input":
-      return `type${methodNameUpper}`;
-    case "select":
-    case "vselect":
-      return `select${methodNameUpper}`;
-    case "radio":
-      return `select${radioMethodNameUpper}`;
-    default:
-      return `click${methodNameUpper}`;
-  }
-}
 function matchesPrimarySelector(extraMethod, pom) {
   if (extraMethod.selector.kind !== "testId") {
     return false;
@@ -8370,7 +8464,7 @@ function getManifestEntry(componentName, entry, componentMetadata, extraMethods)
   const testId = entry.selectorValue.formatted;
   const metadata = componentMetadata?.get(testId);
   const pom = entry.pom;
-  const generatedActionName = pom ? getGeneratedActionName(entry, pom) : null;
+  const generatedActionName = pom ? buildPomGeneratedActionName(pom) : null;
   const extraActionNames = pom ? extraMethods.filter((extraMethod) => matchesPrimarySelector(extraMethod, pom)).map((extraMethod) => extraMethod.name).sort((a, b) => a.localeCompare(b)) : [];
   const generatedActionNames = Array.from(/* @__PURE__ */ new Set([
     ...generatedActionName ? [generatedActionName] : [],
@@ -8388,13 +8482,15 @@ function getManifestEntry(componentName, entry, componentMetadata, extraMethods)
     }) : componentName,
     inferredRole: pom?.nativeRole ?? null,
     ...accessibility ? { accessibility } : {},
-    generatedPropertyName: pom ? getGeneratedPropertyName(pom) : null,
+    generatedPropertyName: pom ? buildPomGeneratedPropertyName(pom) : null,
     generatedActionName,
     generatedActionNames,
     emitPrimary: pom?.emitPrimary !== false,
     ...entry.targetPageObjectModelClass ? { targetPageObjectModelClass: entry.targetPageObjectModelClass } : {},
     ...metadata?.tag ? { sourceTag: metadata.tag } : {},
     ...metadata ? { sourceTagType: metadata.tagType } : {},
+    ...metadata?.sourceLine !== void 0 ? { sourceLine: metadata.sourceLine } : {},
+    ...metadata?.sourceColumn !== void 0 ? { sourceColumn: metadata.sourceColumn } : {},
     ...metadata?.patchFlag !== void 0 ? { patchFlag: metadata.patchFlag } : {},
     ...metadata?.dynamicProps?.length ? { dynamicProps: metadata.dynamicProps } : {},
     ...metadata?.hasClickHandler !== void 0 ? { hasClickHandler: metadata.hasClickHandler } : {},
@@ -8404,7 +8500,7 @@ function getManifestEntry(componentName, entry, componentMetadata, extraMethods)
   };
 }
 function buildPomManifest(componentHierarchyMap, elementMetadata) {
-  const manifestEntries = Array.from(componentHierarchyMap.entries()).sort((a, b) => a[0].localeCompare(b[0])).map(([componentName, dependencies]) => {
+  const manifestEntries = Array.from(componentHierarchyMap.entries()).filter(([componentName, dependencies]) => !shouldSuppressStandaloneWrapperFallbackSurface(componentName, dependencies)).sort((a, b) => a[0].localeCompare(b[0])).map(([componentName, dependencies]) => {
     const entries = Array.from(dependencies.dataTestIdSet).sort((a, b) => a.selectorValue.formatted.localeCompare(b.selectorValue.formatted)).map((entry) => getManifestEntry(componentName, entry, elementMetadata.get(componentName), dependencies.pomExtraMethods ?? []));
     if (!entries.length) {
       return null;
@@ -8420,9 +8516,15 @@ function buildPomManifest(componentHierarchyMap, elementMetadata) {
   }).filter((entry) => entry !== null);
   return Object.fromEntries(manifestEntries);
 }
-function buildTestIdManifest(pomManifest) {
+function buildTestIdManifest(componentHierarchyMap) {
   return Object.fromEntries(
-    Object.entries(pomManifest).map(([componentName, component]) => [componentName, Array.from(new Set(component.testIds)).sort((a, b) => a.localeCompare(b))])
+    Array.from(componentHierarchyMap.entries()).sort((a, b) => a[0].localeCompare(b[0])).map(([componentName, dependencies]) => {
+      const testIds = Array.from(dependencies.dataTestIdSet).map((entry) => entry.selectorValue.formatted).filter(Boolean);
+      if (!testIds.length) {
+        return null;
+      }
+      return [componentName, Array.from(new Set(testIds)).sort((a, b) => a.localeCompare(b))];
+    }).filter((entry) => entry !== null)
   );
 }
 function writeConstJson(value) {
@@ -8432,7 +8534,7 @@ function writeConstJson(value) {
 }
 function generateTestIdsModule(componentHierarchyMap, elementMetadata) {
   const pomManifest = buildPomManifest(componentHierarchyMap, elementMetadata);
-  const testIdManifest = buildTestIdManifest(pomManifest);
+  const testIdManifest = buildTestIdManifest(componentHierarchyMap);
   return renderSourceFile("virtual-testids.ts", (sourceFile) => {
     sourceFile.addStatements("// Virtual module: test id manifest");
     sourceFile.addVariableStatement({
@@ -8518,7 +8620,89 @@ function createTestIdsVirtualModulesPlugin(componentHierarchyMap, elementMetadat
     }
   };
 }
-function createSupportPlugins(options) {
+const ANNOTATOR_CLIENT_VIRTUAL_ID = "virtual:vue-pom-generator/annotator-client";
+const ANNOTATOR_CLIENT_RESOLVED_ID = `\0${ANNOTATOR_CLIENT_VIRTUAL_ID}`;
+const DEFAULT_ENTRY_SUFFIXES = [
+  "/src/main.ts",
+  "/src/main.js",
+  "/src/main.mts",
+  "/src/main.tsx",
+  "/src/main.jsx"
+];
+function toFsImportPath(filePath) {
+  return `/@fs/${filePath.replace(/\\/g, "/")}`;
+}
+function resolveAnnotatorClientPath() {
+  const candidates = [
+    fileURLToPath(new URL("./client.ts", import.meta.url)),
+    fileURLToPath(new URL("../plugin/runtime/annotator/client.ts", import.meta.url))
+  ];
+  const resolved = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!resolved) {
+    throw new Error("[vue-pom-generator] Unable to locate annotator client source.");
+  }
+  return path.resolve(resolved);
+}
+function createAnnotatorUiPlugin(options) {
+  const clientPath = resolveAnnotatorClientPath();
+  const clientImportPath = toFsImportPath(clientPath);
+  const clientOptions = JSON.stringify({
+    sourceAttribute: options.sourceAttribute,
+    metadataAttributePrefix: options.metadataAttributePrefix,
+    outputDetail: options.outputDetail,
+    copyToClipboard: options.copyToClipboard,
+    showComponentTree: options.showComponentTree
+  });
+  return {
+    name: "vue-pom-generator:annotator-ui",
+    apply: "serve",
+    resolveId(id) {
+      if (id === ANNOTATOR_CLIENT_VIRTUAL_ID) {
+        return ANNOTATOR_CLIENT_RESOLVED_ID;
+      }
+    },
+    load(id) {
+      if (id !== ANNOTATOR_CLIENT_RESOLVED_ID) {
+        return null;
+      }
+      return [
+        `import { mountAnnotatorClient } from ${JSON.stringify(clientImportPath)};`,
+        `mountAnnotatorClient(${clientOptions});`,
+        ""
+      ].join("\n");
+    },
+    transform(code, id) {
+      if (!options.enabled) {
+        return null;
+      }
+      const normalizedId = id.replace(/\\/g, "/");
+      if (!DEFAULT_ENTRY_SUFFIXES.some((suffix) => normalizedId.endsWith(suffix))) {
+        return null;
+      }
+      if (code.includes(ANNOTATOR_CLIENT_VIRTUAL_ID)) {
+        return null;
+      }
+      return {
+        code: `import ${JSON.stringify(ANNOTATOR_CLIENT_VIRTUAL_ID)};
+${code}`,
+        map: null
+      };
+    },
+    transformIndexHtml() {
+      if (!options.enabled) {
+        return void 0;
+      }
+      const tag = {
+        tag: "script",
+        attrs: { type: "module" },
+        children: `import ${JSON.stringify(ANNOTATOR_CLIENT_VIRTUAL_ID)};`,
+        injectTo: "body"
+      };
+      return [tag];
+    }
+  };
+}
+function createInternalPlugins(options) {
   const {
     componentHierarchyMap,
     elementMetadata,
@@ -8534,7 +8718,8 @@ function createSupportPlugins(options) {
     generation,
     projectRootRef,
     basePageClassPath: basePageClassPathOverride,
-    loggerRef
+    loggerRef,
+    annotatorRuntime
   } = options;
   const {
     outDir,
@@ -8608,7 +8793,13 @@ function createSupportPlugins(options) {
     loggerRef
   });
   const virtualModules = createTestIdsVirtualModulesPlugin(componentHierarchyMap, elementMetadata);
-  return [tsProcessor, devProcessor, virtualModules];
+  const annotatorUiPlugin = createAnnotatorUiPlugin({
+    ...annotatorRuntime.ui,
+    enabled: annotatorRuntime.enabled && annotatorRuntime.ui.enabled,
+    sourceAttribute: annotatorRuntime.sourceAttribute,
+    metadataAttributePrefix: annotatorRuntime.metadataAttributePrefix
+  });
+  return [tsProcessor, devProcessor, virtualModules, annotatorUiPlugin];
 }
 function findDataTestIdProp(element, attributeName = "data-testid") {
   return element.props.find(
@@ -8728,7 +8919,9 @@ function tryCreateElementMetadata(args) {
     staticAriaLabel: findStaticAttributeValue(element, "aria-label"),
     staticRole: findStaticAttributeValue(element, "role"),
     staticTitle: findStaticAttributeValue(element, "title"),
-    staticTextContent: collectStaticTextContent(element.children)
+    staticTextContent: collectStaticTextContent(element.children),
+    sourceLine: element.loc?.start.line,
+    sourceColumn: element.loc?.start.column
   };
   return metadata;
 }
@@ -8800,7 +8993,8 @@ function createVuePluginWithTestIds(options) {
     loggerRef,
     getSourceDirs,
     getWrapperSearchRoots,
-    getProjectRoot
+    getProjectRoot,
+    annotatorMetadata
   } = options;
   const lastAccessibilityWarningSignatureByComponent = /* @__PURE__ */ new Map();
   const getComponentNameFromPath = (filename) => {
@@ -8817,27 +9011,15 @@ function createVuePluginWithTestIds(options) {
       return false;
     const cleanPath = filename.includes("?") ? filename.substring(0, filename.indexOf("?")) : filename;
     const projectRoot = getProjectRoot();
-    const absFilename = path.isAbsolute(cleanPath) ? cleanPath : path.resolve(projectRoot, cleanPath);
-    if (absFilename.includes(`${path.sep}node_modules${path.sep}`) || absFilename.includes("/node_modules/"))
-      return false;
-    const viewsDirAbs = getViewsDirAbs();
-    if (absFilename.startsWith(viewsDirAbs + path.sep) || absFilename === viewsDirAbs)
-      return true;
-    const rootsToTry = [projectRoot, process.cwd()];
-    const matched = getSourceDirs().some((dir) => {
-      return rootsToTry.some((root) => {
-        const absDir = path.resolve(root, dir);
-        if (absFilename.startsWith(absDir + path.sep) || absFilename === absDir)
-          return true;
-        if (dir.startsWith("app/") && root.endsWith("/app")) {
-          const relativeDir = dir.substring(4);
-          const absDirAlt = path.resolve(root, relativeDir);
-          return absFilename.startsWith(absDirAlt + path.sep) || absFilename === absDirAlt;
-        }
-        return false;
-      });
+    const matched = isFileInConfiguredSourceScope({
+      filename,
+      projectRoot,
+      viewsDirAbs: getViewsDirAbs(),
+      sourceDirs: getSourceDirs(),
+      extraRoots: [process.cwd()]
     });
     if (cleanPath.endsWith(".vue") && !matched) {
+      const absFilename = path.normalize(path.isAbsolute(cleanPath) ? cleanPath : path.resolve(projectRoot, cleanPath));
       loggerRef.current.debug(`[isFileInScope] REJECTED: ${absFilename} (Clean: ${cleanPath})`);
     }
     return matched;
@@ -8871,7 +9053,8 @@ function createVuePluginWithTestIds(options) {
                 missingSemanticNameBehavior,
                 warn: (message) => loggerRef.current.warn(message),
                 vueFilesPathMap,
-                wrapperSearchRoots: getWrapperSearchRoots()
+                wrapperSearchRoots: getWrapperSearchRoots(),
+                annotatorMetadata
               }
             )
           );
@@ -8926,7 +9109,8 @@ function createVuePluginWithTestIds(options) {
               missingSemanticNameBehavior,
               warn: (message) => loggerRef.current.warn(message),
               vueFilesPathMap,
-              wrapperSearchRoots: getWrapperSearchRoots()
+              wrapperSearchRoots: getWrapperSearchRoots(),
+              annotatorMetadata
             }
           );
           perFileTransform.set(componentName, transform);
@@ -9071,6 +9255,12 @@ function assertOneOf(value, allowed, name) {
   }
   throw new TypeError(`${name} must be one of: ${allowed.join(", ")}.`);
 }
+function assertDataAttributeName(value, name) {
+  assertNonEmptyString(value, name);
+  if (!value.startsWith("data-")) {
+    throw new TypeError(`${name} must start with "data-".`);
+  }
+}
 function readPackageJson(projectRoot) {
   const packageJsonPath = path.join(projectRoot, "package.json");
   if (!fs.existsSync(packageJsonPath)) {
@@ -9234,6 +9424,19 @@ function createVuePomGeneratorPlugins(options = {}) {
   const generationEnabled = generationOptions !== null;
   const vueGenerationOptions = generationOptions;
   const verbosity = options.logging?.verbosity ?? "warn";
+  const annotatorRuntimeOptions = options.runtime?.annotator;
+  const annotatorUiRuntimeOptions = annotatorRuntimeOptions?.ui;
+  const resolvedAnnotatorRuntimeOptions = {
+    enabled: annotatorRuntimeOptions?.enabled === true,
+    sourceAttribute: annotatorRuntimeOptions?.sourceAttribute ?? "data-v-inspector",
+    metadataAttributePrefix: annotatorRuntimeOptions?.metadataAttributePrefix ?? "data-v-pom",
+    ui: {
+      enabled: annotatorUiRuntimeOptions?.enabled === true,
+      outputDetail: annotatorUiRuntimeOptions?.outputDetail ?? "forensic",
+      copyToClipboard: annotatorUiRuntimeOptions?.copyToClipboard ?? false,
+      showComponentTree: annotatorUiRuntimeOptions?.showComponentTree ?? true
+    }
+  };
   const vueOptions = options.vueOptions;
   const resolvedInjectionOptionsRef = {
     current: resolveInjectionSupportOptions({
@@ -9337,6 +9540,10 @@ function createVuePomGeneratorPlugins(options = {}) {
       assertNonEmptyStringArray(getComponentDirs(), "[vue-pom-generator] injection.componentDirs");
       assertNonEmptyStringArray(getLayoutDirs(), "[vue-pom-generator] injection.layoutDirs");
       assertNonEmptyStringArray(getWrapperSearchRoots(), "[vue-pom-generator] injection.wrapperSearchRoots");
+      if (resolvedAnnotatorRuntimeOptions.enabled) {
+        assertDataAttributeName(resolvedAnnotatorRuntimeOptions.sourceAttribute, "[vue-pom-generator] runtime.annotator.sourceAttribute");
+        assertDataAttributeName(resolvedAnnotatorRuntimeOptions.metadataAttributePrefix, "[vue-pom-generator] runtime.annotator.metadataAttributePrefix");
+      }
       if (generationEnabled) {
         assertNonEmptyString(resolvedGenerationOptions.outDir, "[vue-pom-generator] generation.outDir");
         assertOneOf(resolvedGenerationOptions.typescriptOutputStructure, ["aggregated", "split"], "[vue-pom-generator] generation.playwright.outputStructure");
@@ -9379,10 +9586,14 @@ function createVuePomGeneratorPlugins(options = {}) {
     loggerRef,
     getSourceDirs,
     getWrapperSearchRoots: getWrapperSearchRootsAbs,
-    getProjectRoot: () => projectRootRef.current
+    getProjectRoot: () => projectRootRef.current,
+    annotatorMetadata: resolvedAnnotatorRuntimeOptions.enabled ? {
+      sourceAttribute: resolvedAnnotatorRuntimeOptions.sourceAttribute,
+      metadataAttributePrefix: resolvedAnnotatorRuntimeOptions.metadataAttributePrefix
+    } : null
   });
   templateCompilerOptionsForResolvedPlugin = templateCompilerOptions;
-  const supportPlugins = createSupportPlugins({
+  const internalPlugins = createInternalPlugins({
     componentHierarchyMap,
     elementMetadata,
     vueFilesPathMap,
@@ -9397,7 +9608,8 @@ function createVuePomGeneratorPlugins(options = {}) {
     generation: resolvedGenerationOptions,
     projectRootRef,
     basePageClassPath: basePageClassPathOverride,
-    loggerRef
+    loggerRef,
+    annotatorRuntime: resolvedAnnotatorRuntimeOptions
   });
   if (isNuxt) {
     loggerRef.current.info("Nuxt environment detected. Skipping internal @vitejs/plugin-vue to avoid conflicts.");
@@ -9408,7 +9620,7 @@ function createVuePomGeneratorPlugins(options = {}) {
     configPlugin,
     metadataCollectorPlugin,
     ...usesExternalVuePlugin ? [] : [internalVuePlugin],
-    ...supportPlugins
+    ...internalPlugins
   ];
   if (!generationEnabled) {
     const virtualModules = createTestIdsVirtualModulesPlugin(componentHierarchyMap, elementMetadata);