@immense/vue-pom-generator 1.0.3

package/class-generation/index.ts

@@ -0,0 +1,1691 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { generateViewObjectModelMethodContent } from "../method-generation";
+import { parseRouterFileFromCwd } from "../router-introspection";
+// NOTE: This module intentionally does not depend on Babel parsing.
+
+import { IComponentDependencies, IDataTestId, PomExtraClickMethodSpec, PomPrimarySpec, upperFirst } from "../utils";
+
+// Intentionally imported so tooling understands this exported helper is part of the
+// generated POM public surface (it is consumed by generated Playwright fixtures).
+import { setPlaywrightAnimationOptions } from "./Pointer";
+
+void setPlaywrightAnimationOptions;
+
+export { generateViewObjectModelMethodContent };
+
+const AUTO_GENERATED_COMMENT
+  = " * DO NOT MODIFY BY HAND\n"
+    + " *\n"
+    + " * This file is auto-generated by vue-pom-generator.\n"
+    + " * Changes should be made in the generator/template, not in the generated output.\n"
+    + " */";
+const eslintSuppressionHeader = "/* eslint-disable perfectionist/sort-imports */\n";
+
+function toPosixRelativePath(fromDir: string, toFile: string): string {
+  let rel = path.relative(fromDir, toFile).replace(/\\/g, "/");
+  if (!rel.startsWith(".")) {
+    rel = `./${rel}`;
+  }
+  return rel;
+}
+
+function changeExtension(filePath: string, expectedExt: string, nextExtWithDot: string): string {
+  const parsed = path.parse(filePath);
+  if (parsed.ext !== expectedExt)
+    return filePath;
+  return path.format({ ...parsed, base: `${parsed.name}${nextExtWithDot}`, ext: nextExtWithDot });
+}
+
+function stripExtension(filePath: string): string {
+  // IMPORTANT:
+  // This helper is used for generating *import specifiers*.
+  // On Windows, `path.parse/path.format` can re-introduce backslashes even when
+  // the input contains `/` separators, producing invalid TS string escapes like `"..\\pom\\custom\\nGrid"`.
+  // Keep these paths POSIX-normalized.
+  const posix = (filePath ?? "").replace(/\\/g, "/");
+  const parsed = path.posix.parse(posix);
+  return path.posix.format({ ...parsed, base: parsed.name, ext: "" });
+}
+
+function resolveRouterEntry(projectRoot?: string, routerEntry?: string) {
+  if (!routerEntry) {
+    throw new Error("[vue-pom-generator] Router entry path is required when routerAwarePoms is enabled.");
+  }
+  const root = projectRoot ?? process.cwd();
+  return path.isAbsolute(routerEntry) ? routerEntry : path.resolve(root, routerEntry);
+}
+
+interface RouteMeta {
+  template: string;
+}
+
+async function getRouteMetaByComponent(projectRoot?: string, routerEntry?: string): Promise<Record<string, RouteMeta>> {
+  const resolvedRouterEntry = resolveRouterEntry(projectRoot, routerEntry);
+  const { routeMetaEntries } = await parseRouterFileFromCwd(resolvedRouterEntry);
+
+  const map = new Map<string, RouteMeta[]>();
+  for (const entry of routeMetaEntries) {
+    const list = map.get(entry.componentName) ?? [];
+    list.push({ template: entry.pathTemplate });
+    map.set(entry.componentName, list);
+  }
+
+  const chooseRouteMeta = (entries: RouteMeta[]): RouteMeta | null => {
+    if (!entries.length)
+      return null;
+    return entries
+      .slice()
+      .sort((a, b) => a.template.length - b.template.length || a.template.localeCompare(b.template))[0];
+  };
+
+  const sorted = Array.from(map.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+  return Object.fromEntries(
+    sorted
+      .map(([componentName, entries]) => {
+        const chosen = chooseRouteMeta(entries);
+        return chosen ? [componentName, chosen] : null;
+      })
+      .filter((entry): entry is [string, RouteMeta] => !!entry),
+  );
+}
+
+function generateRouteProperty(routeMeta: RouteMeta | null): string {
+  if (!routeMeta) {
+    return "    static readonly route: { template: string } | null = null;\n";
+  }
+
+  return [
+    "    static readonly route: { template: string } | null = {",
+    `        template: ${JSON.stringify(routeMeta.template)},`,
+    "    } as const;",
+    "",
+  ].join("\n");
+}
+
+function generateGoToSelfMethod(componentName: string): string {
+  return [
+    "",
+    "    async goTo() {",
+    "        await this.goToSelf();",
+    "    }",
+    "",
+    "    async goToSelf() {",
+    `        const route = ${componentName}.route;`,
+    "        if (!route) {",
+    `            throw new Error("[pom] No router path found for component/page-object '${componentName}'.");`,
+    "        }",
+    "        await this.page.goto(route.template);",
+    "    }",
+    "",
+  ].join("\n");
+}
+
+function formatMethodParams(params: Record<string, string> | undefined): string {
+  if (!params)
+    return "";
+
+  // Keep output stable and somewhat intuitive.
+  const preferredOrder = ["key", "value", "text", "timeOut", "annotationText", "wait"];
+
+  const entries = Object.entries(params);
+  if (!entries.length)
+    return "";
+
+  const score = (name: string) => {
+    const idx = preferredOrder.indexOf(name);
+    return idx < 0 ? 999 : idx;
+  };
+
+  return entries
+    .slice()
+    .sort((a, b) => score(a[0]) - score(b[0]) || a[0].localeCompare(b[0]))
+    .map(([name, typeExpr]) => `${name}: ${typeExpr}`)
+    .join(", ");
+}
+
+function generateExtraClickMethodContent(spec: PomExtraClickMethodSpec): string {
+  if (spec.kind !== "click") {
+    return "";
+  }
+
+  const params = spec.params ?? {};
+  const signatureParams = formatMethodParams(params);
+  const signature = signatureParams ? `(${signatureParams})` : "()";
+
+  const needsTemplate = spec.formattedDataTestId.includes("${");
+  const testIdExpr = needsTemplate
+    ? `\`${spec.formattedDataTestId}\``
+    : JSON.stringify(spec.formattedDataTestId);
+
+  const lines: string[] = [];
+  lines.push(
+    "",
+    `    async ${spec.name}${signature} {`,
+  );
+
+  if (spec.keyLiteral !== undefined) {
+    lines.push(`        const key = ${JSON.stringify(spec.keyLiteral)};`);
+  }
+
+  if (needsTemplate) {
+    lines.push(`        const testId = ${testIdExpr};`);
+  }
+
+  // clickByTestId(testId, annotationText = "", wait = true)
+  const hasAnnotationText = Object.prototype.hasOwnProperty.call(params, "annotationText");
+  const hasWait = Object.prototype.hasOwnProperty.call(params, "wait");
+
+  const clickArgs: string[] = [];
+  clickArgs.push(needsTemplate ? "testId" : testIdExpr);
+
+  if (hasAnnotationText || hasWait) {
+    clickArgs.push(hasAnnotationText ? "annotationText" : "\"\"");
+  }
+  if (hasWait) {
+    clickArgs.push("wait");
+  }
+
+  lines.push(`        await this.clickByTestId(${clickArgs.join(", ")});`);
+  lines.push("    }");
+
+  return `${lines.join("\n")}\n`;
+}
+
+function generateMethodContentFromPom(primary: PomPrimarySpec, targetPageObjectModelClass?: string): string {
+  if (primary.emitPrimary === false) {
+    return "";
+  }
+
+  return generateViewObjectModelMethodContent(
+    targetPageObjectModelClass,
+    primary.methodName,
+    primary.nativeRole,
+    primary.formattedDataTestId,
+    primary.alternateFormattedDataTestIds,
+    primary.getterNameOverride,
+    primary.params ?? {},
+  );
+}
+
+function generateMethodsContentForDependencies(dependencies: IComponentDependencies): string {
+  const entries = Array.from(dependencies.dataTestIdSet ?? []);
+  const primarySpecsAll = entries
+    .map(e => ({ pom: e.pom, target: e.targetPageObjectModelClass }))
+    .filter((x): x is { pom: PomPrimarySpec; target: string | undefined } => !!x.pom)
+    .sort((a, b) => a.pom.methodName.localeCompare(b.pom.methodName));
+
+  // IMPORTANT:
+  // `dependencies.dataTestIdSet` is a Set of objects; it does not de-dupe by semantic identity.
+  // It's possible to end up with multiple IDataTestId entries that carry identical `pom` specs.
+  // When we emit from IR, we must de-dupe here to avoid duplicate getters/methods.
+  const seenPrimaryKeys = new Set<string>();
+  const primarySpecs = primarySpecsAll.filter(({ pom, target }) => {
+    const stableParams = pom.params
+      ? Object.fromEntries(Object.entries(pom.params).sort((a, b) => a[0].localeCompare(b[0])))
+      : undefined;
+    const alternates = (pom.alternateFormattedDataTestIds ?? []).slice().sort();
+    const key = JSON.stringify({
+      role: pom.nativeRole,
+      methodName: pom.methodName,
+      getterNameOverride: pom.getterNameOverride ?? null,
+      testId: pom.formattedDataTestId,
+      alternateTestIds: alternates.length ? alternates : undefined,
+      params: stableParams,
+      target: target ?? null,
+      emitPrimary: pom.emitPrimary ?? true,
+    });
+    if (seenPrimaryKeys.has(key)) {
+      return false;
+    }
+    seenPrimaryKeys.add(key);
+    return true;
+  });
+
+  const extras = (dependencies.pomExtraMethods ?? [])
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  let content = "";
+  for (const { pom, target } of primarySpecs) {
+    content += generateMethodContentFromPom(pom, target);
+  }
+
+  for (const extra of extras) {
+    content += generateExtraClickMethodContent(extra);
+  }
+
+  return content;
+}
+
+export interface GenerateFilesOptions {
+  /**
+   * Output directory for generated files.
+   *
+   * Defaults to `./pom` when omitted (backwards compatible default for internal usage).
+   */
+  outDir?: string;
+
+  /**
+   * Generate Playwright fixture helpers alongside generated POMs.
+   *
+   * Default output (when `true`):
+   * - `<projectRoot>/<outDir>/fixtures.g.ts`
+   *
+   * Accepted values:
+   * - `true`: enable with defaults
+   * - `"path"`: enable and write the fixture file under this directory (resolved relative to projectRoot),
+   *   or to this file path if it ends with `.ts`/`.tsx`/`.mts`/`.cts`
+   * - `{ outDir }`: enable and override where fixture files are written (resolved relative to projectRoot)
+   */
+  generateFixtures?: boolean | string | { outDir?: string };
+
+  /**
+   * Project root used for resolving conventional paths (e.g. src/views, tests/playwright/pom/custom).
+   * Defaults to process.cwd() for backwards compatibility.
+   */
+  projectRoot?: string;
+
+  /**
+   * Directory containing handwritten POM helpers to import into aggregated output.
+   * Defaults to <projectRoot>/tests/playwright/pom/custom.
+   */
+  customPomDir?: string;
+
+  /**
+   * Optional import aliases for handwritten POM helpers.
+   *
+   * Keyed by the helper file/export name (basename of the .ts file).
+   * Value is the identifier to import it as.
+   *
+   * Example: { Toggle: "ToggleWidget" }
+   */
+  customPomImportAliases?: Record<string, string>;
+
+  /**
+   * Handwritten POM helper attachments. These helpers are assumed to be present in the
+   * aggregated output (e.g. via `tests/playwright/pom/custom/*.ts` inlining), but we only attach them to
+   * view classes that actually use certain components.
+   */
+  customPomAttachments?: Array<{
+    className: string;
+    propertyName: string;
+    attachWhenUsesComponents: string[];
+
+    /**
+     * Controls whether this attachment is applied to views, components, or both.
+     * Defaults to "views" for backwards compatibility.
+     */
+    attachTo?: "views" | "components" | "both";
+  }>;
+
+  /** Attribute name to treat as the test id. Defaults to `data-testid`. */
+  testIdAttribute?: string;
+
+  /** Which POM languages to emit. Defaults to ["ts"]. */
+  emitLanguages?: Array<"ts" | "csharp">;
+
+  /** When true, generate router-aware helpers like goToSelf() on view POMs. */
+  vueRouterFluentChaining?: boolean;
+
+  /** Router entry path used for vue-router introspection when fluent chaining is enabled. */
+  routerEntry?: string;
+
+  routeMetaByComponent?: Record<string, RouteMeta>;
+}
+
+interface GenerateContentOptions {
+  /** Directory the generated .g.ts file will live in (used for relative imports). Defaults to the Vue file's directory. */
+  outputDir?: string;
+  /** When true, omit file headers/import blocks that should be shared in an aggregated file. */
+  aggregated?: boolean;
+
+  customPomAttachments?: Array<{
+    className: string;
+    propertyName: string;
+    attachWhenUsesComponents: string[];
+
+    /**
+     * Controls whether this attachment is applied to views, components, or both.
+     * Defaults to "views" for backwards compatibility.
+     */
+    attachTo?: "views" | "components" | "both";
+  }>;
+
+  projectRoot?: string;
+  customPomDir?: string;
+  customPomImportAliases?: Record<string, string>;
+
+  /** Attribute name to treat as the test id. Defaults to `data-testid`. */
+  testIdAttribute?: string;
+
+  /** When true, generate router-aware helpers like goToSelf() on view POMs. */
+  vueRouterFluentChaining?: boolean;
+
+  routeMetaByComponent?: Record<string, RouteMeta>;
+}
+
+export async function generateFiles(
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  vueFilesPathMap: Map<string, string>,
+  basePageClassPath: string,
+  options: GenerateFilesOptions = {},
+) {
+  const {
+    outDir: outDirOverride,
+    generateFixtures,
+    customPomAttachments = [],
+    projectRoot,
+    customPomDir,
+    customPomImportAliases,
+    testIdAttribute,
+    emitLanguages: emitLanguagesOverride,
+    vueRouterFluentChaining,
+    routerEntry,
+  } = options;
+
+  const emitLanguages: Array<"ts" | "csharp"> = emitLanguagesOverride?.length
+    ? emitLanguagesOverride
+    : ["ts"];
+
+  const outDir = outDirOverride ?? "./pom";
+
+  const routeMetaByComponent = vueRouterFluentChaining
+    ? await getRouteMetaByComponent(projectRoot, routerEntry)
+    : undefined;
+
+  if (emitLanguages.includes("ts")) {
+    const files = await generateAggregatedFiles(componentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
+      customPomAttachments,
+      projectRoot,
+      customPomDir,
+      customPomImportAliases,
+      testIdAttribute,
+      generateFixtures,
+      routeMetaByComponent,
+      vueRouterFluentChaining,
+    });
+    for (const file of files) {
+      createFile(file.filePath, file.content);
+    }
+
+    maybeGenerateFixtureRegistry(componentHierarchyMap, {
+      generateFixtures,
+      pomOutDir: outDir,
+      projectRoot,
+    });
+  }
+
+  if (emitLanguages.includes("csharp")) {
+    const csFiles = generateAggregatedCSharpFiles(componentHierarchyMap, outDir, {
+      projectRoot,
+    });
+    for (const file of csFiles) {
+      createFile(file.filePath, file.content);
+    }
+  }
+}
+
+function toCSharpTestIdExpression(formattedDataTestId: string): string {
+  // Convert our `${var}` placeholder format into C# interpolated-string `{var}`.
+  const needsInterpolation = formattedDataTestId.includes("${");
+  if (!needsInterpolation) {
+    return JSON.stringify(formattedDataTestId);
+  }
+
+  const inner = formattedDataTestId.replace(/\$\{/g, "{");
+  // Use verbatim JSON escaping for quotes/backslashes, then adapt to C# string literal.
+  // JSON.stringify gives us a JS string literal with escapes, which is close enough for a C# normal string.
+  const quoted = JSON.stringify(inner);
+  return `$${quoted}`;
+}
+
+function toCSharpParam(paramTypeExpr: string): { type: string; defaultExpr?: string } {
+  const trimmed = (paramTypeExpr ?? "").trim();
+
+  // Handle default values: "boolean = true", "string = \"\"", "timeOut = 500".
+  const eqIdx = trimmed.indexOf("=");
+  const left = eqIdx >= 0 ? trimmed.slice(0, eqIdx).trim() : trimmed;
+  const right = eqIdx >= 0 ? trimmed.slice(eqIdx + 1).trim() : undefined;
+
+  // Collapse union types to their widest practical type.
+  const typePart = left.includes("|") ? "string" : left;
+
+  let type = "string";
+  if (/(^|\s)boolean(\s|$)/.test(typePart))
+    type = "bool";
+  else if (/(^|\s)string(\s|$)/.test(typePart))
+    type = "string";
+  else if (/(^|\s)number(\s|$)/.test(typePart))
+    type = "int";
+  else if (/\d+/.test(typePart) && typePart === "")
+    type = "int";
+  else if (/\btimeOut\b/i.test(typePart))
+    type = "int";
+
+  let defaultExpr: string | undefined;
+  if (right !== undefined) {
+    if (type === "bool") {
+      defaultExpr = right.includes("true") ? "true" : right.includes("false") ? "false" : undefined;
+    }
+    else if (type === "int") {
+      const m = right.match(/\d+/);
+      defaultExpr = m ? m[0] : undefined;
+    }
+    else {
+      // string defaults, keep empty string if detected.
+      if (right === "\"\"" || right === "\"\"" || right === "''") {
+        defaultExpr = "\"\"";
+      }
+    }
+  }
+
+  return { type, defaultExpr };
+}
+
+function formatCSharpParams(params: Record<string, string> | undefined): { signature: string; argNames: string[] } {
+  if (!params)
+    return { signature: "", argNames: [] };
+
+  const entries = Object.entries(params);
+  if (!entries.length)
+    return { signature: "", argNames: [] };
+
+  const signatureParts: string[] = [];
+  const argNames: string[] = [];
+
+  for (const [name, typeExpr] of entries) {
+    const { type, defaultExpr } = toCSharpParam(typeExpr);
+    argNames.push(name);
+    signatureParts.push(defaultExpr !== undefined ? `${type} ${name} = ${defaultExpr}` : `${type} ${name}`);
+  }
+
+  return { signature: signatureParts.join(", "), argNames };
+}
+
+function generateAggregatedCSharpFiles(
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  outDir: string,
+  options: { projectRoot?: string } = {},
+): Array<{ filePath: string; content: string }> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const outAbs = path.isAbsolute(outDir) ? outDir : path.resolve(projectRoot, outDir);
+
+  const entries = Array.from(componentHierarchyMap.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+
+  const header = [
+    "// <auto-generated>",
+    "// DO NOT MODIFY BY HAND",
+    "//",
+    "// This file is auto-generated by vue-pom-generator.",
+    "// Changes should be made in the generator/template, not in the generated output.",
+    "// </auto-generated>",
+    "",
+    "using System;",
+    "using System.Threading.Tasks;",
+    "using Microsoft.Playwright;",
+    "",
+    "namespace ImmyBot.Playwright.Generated;",
+    "",
+    "public abstract class BasePage",
+    "{",
+    "    protected BasePage(IPage page) => Page = page;",
+    "    protected IPage Page { get; }",
+    "    protected ILocator LocatorByTestId(string testId) => Page.GetByTestId(testId);",
+    "",
+    "    // Minimal vue-select helper mirroring the TS BasePage.selectVSelectByTestId behavior.",
+    "    // Note: annotationText is currently a no-op in C# output (we don't render a cursor overlay).",
+    "    protected async Task SelectVSelectByTestIdAsync(string testId, string value, int timeOut = 500)",
+    "    {",
+    "        var root = LocatorByTestId(testId);",
+    "        var input = root.Locator(\"input\");",
+    "",
+    "        await input.ClickAsync(new LocatorClickOptions { Force = true });",
+    "        await input.FillAsync(value);",
+    "        await Page.WaitForTimeoutAsync(timeOut);",
+    "",
+    "        var option = root.Locator(\"ul.vs__dropdown-menu li[role='option']\").First;",
+    "        if (await option.CountAsync() > 0)",
+    "        {",
+    "            await option.ClickAsync();",
+    "        }",
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+
+  const chunks: string[] = [header];
+
+  for (const [componentName, deps] of entries) {
+    chunks.push(
+      `public sealed class ${componentName} : BasePage\n{\n    public ${componentName}(IPage page) : base(page) { }\n`,
+    );
+
+    // Primary specs
+    const primaries = Array.from(deps.dataTestIdSet ?? [])
+      .map(e => ({ pom: e.pom, target: e.targetPageObjectModelClass }))
+      .filter((x): x is { pom: PomPrimarySpec; target: string | undefined } => !!x.pom)
+      .sort((a, b) => a.pom.methodName.localeCompare(b.pom.methodName));
+
+    for (const { pom, target } of primaries) {
+      if (pom.emitPrimary === false)
+        continue;
+
+      const roleSuffix = (pom.nativeRole || "Element") === "vselect" ? "VSelect" : upperFirst(pom.nativeRole || "Element");
+      const baseMethodName = upperFirst(pom.methodName);
+      const baseGetterName = upperFirst(pom.getterNameOverride ?? pom.methodName);
+      const locatorName = baseGetterName.endsWith(roleSuffix) ? baseGetterName : `${baseGetterName}${roleSuffix}`;
+      const testIdExpr = toCSharpTestIdExpression(pom.formattedDataTestId);
+      const { signature, argNames } = formatCSharpParams(pom.params);
+      const args = argNames.join(", ");
+
+      const allTestIds = [pom.formattedDataTestId, ...(pom.alternateFormattedDataTestIds ?? [])]
+        .filter((v, idx, arr) => v && arr.indexOf(v) === idx);
+
+      if (pom.formattedDataTestId.includes("${")) {
+        chunks.push(`    public ILocator ${locatorName}(${signature}) => LocatorByTestId(${testIdExpr});`);
+      }
+      else {
+        chunks.push(`    public ILocator ${locatorName} => LocatorByTestId(${testIdExpr});`);
+      }
+
+      // Action method
+      const actionPrefix = pom.nativeRole === "input"
+        ? "Type"
+        : (pom.nativeRole === "select" || pom.nativeRole === "vselect" || pom.nativeRole === "radio")
+          ? "Select"
+          : target
+            ? "GoTo"
+            : "Click";
+
+      const actionName = `${actionPrefix}${baseMethodName}Async`;
+      const sig = signature;
+
+      if (target) {
+        chunks.push(`    public async Task<${target}> ${actionName}(${sig})`);
+        chunks.push("    {");
+        if (pom.formattedDataTestId.includes("${") || allTestIds.length <= 1) {
+          chunks.push(`        await ${locatorName}${pom.formattedDataTestId.includes("${") ? `(${args})` : ""}.ClickAsync();`);
+        }
+        else {
+          chunks.push("        Exception? lastError = null;");
+          chunks.push(`        foreach (var testId in new[] { ${allTestIds.map(toCSharpTestIdExpression).join(", ")} })`);
+          chunks.push("        {");
+          chunks.push("            try");
+          chunks.push("            {");
+          chunks.push("                var locator = LocatorByTestId(testId);");
+          chunks.push("                if (await locator.CountAsync() > 0)");
+          chunks.push("                {");
+          chunks.push("                    await locator.ClickAsync();");
+          chunks.push(`                    return new ${target}(Page);`);
+          chunks.push("                }");
+          chunks.push("            }");
+          chunks.push("            catch (Exception e)");
+          chunks.push("            {");
+          chunks.push("                lastError = e;");
+          chunks.push("            }");
+          chunks.push("        }");
+          chunks.push("        throw lastError ?? new System.Exception(\"[pom] Failed to navigate using any candidate test id.\");");
+        }
+        chunks.push(`        return new ${target}(Page);`);
+        chunks.push("    }");
+        chunks.push("");
+        continue;
+      }
+
+      chunks.push(`    public async Task ${actionName}(${sig})`);
+      chunks.push("    {");
+
+      const callSuffix = pom.formattedDataTestId.includes("${") ? `(${args})` : "";
+
+      const emitActionCall = (locatorAccess: string) => {
+        if (pom.nativeRole === "input") {
+          chunks.push(`        await ${locatorAccess}.FillAsync(text);`);
+        }
+        else if (pom.nativeRole === "select") {
+          chunks.push(`        await ${locatorAccess}.SelectOptionAsync(value);`);
+        }
+        else if (pom.nativeRole === "vselect") {
+          // vselect requires custom selection mechanics.
+          chunks.push(`        await SelectVSelectByTestIdAsync(${testIdExpr}, value, timeOut);`);
+        }
+        else {
+          chunks.push(`        await ${locatorAccess}.ClickAsync();`);
+        }
+      };
+
+      if (!pom.formattedDataTestId.includes("${") && allTestIds.length > 1) {
+        chunks.push("        Exception? lastError = null;");
+        chunks.push(`        foreach (var testId in new[] { ${allTestIds.map(toCSharpTestIdExpression).join(", ")} })`);
+        chunks.push("        {");
+        chunks.push("            try");
+        chunks.push("            {");
+        if (pom.nativeRole === "vselect") {
+          chunks.push("                // vselect fallback: use the same selection routine for each candidate test id.");
+          chunks.push("                var root = LocatorByTestId(testId);");
+          chunks.push("                if (await root.CountAsync() > 0)");
+          chunks.push("                {");
+          chunks.push("                    await SelectVSelectByTestIdAsync(testId, value, timeOut);");
+          chunks.push("                    return;");
+          chunks.push("                }");
+        }
+        else {
+          chunks.push("                var locator = LocatorByTestId(testId);");
+          chunks.push("                if (await locator.CountAsync() > 0)");
+          chunks.push("                {");
+          if (pom.nativeRole === "input") {
+            chunks.push("                    await locator.FillAsync(text);");
+          }
+          else if (pom.nativeRole === "select") {
+            chunks.push("                    await locator.SelectOptionAsync(value);");
+          }
+          else {
+            chunks.push("                    await locator.ClickAsync();");
+          }
+          chunks.push("                    return;");
+          chunks.push("                }");
+        }
+        chunks.push("            }");
+        chunks.push("            catch (Exception e)");
+        chunks.push("            {");
+        chunks.push("                lastError = e;");
+        chunks.push("            }");
+        chunks.push("        }");
+        chunks.push("        throw lastError ?? new Exception(\"[pom] Failed to click any candidate test id.\");");
+        chunks.push("    }");
+        chunks.push("");
+        continue;
+      }
+
+      emitActionCall(`${locatorName}${callSuffix}`);
+
+      chunks.push("    }");
+      chunks.push("");
+    }
+
+    // Extra click specs
+    const extras = (deps.pomExtraMethods ?? []).slice().sort((a, b) => a.name.localeCompare(b.name));
+    for (const extra of extras) {
+      if (extra.kind !== "click")
+        continue;
+      const { signature } = formatCSharpParams(extra.params);
+      const needsTemplate = extra.formattedDataTestId.includes("${");
+      const testIdExpr = toCSharpTestIdExpression(extra.formattedDataTestId);
+
+      const extraName = upperFirst(extra.name);
+
+      chunks.push(`    public async Task ${extraName}Async(${signature})`);
+      chunks.push("    {");
+      if (extra.keyLiteral !== undefined) {
+        chunks.push(`        var key = ${JSON.stringify(extra.keyLiteral)};`);
+      }
+      if (needsTemplate) {
+        chunks.push(`        var testId = ${testIdExpr};`);
+        chunks.push("        await LocatorByTestId(testId).ClickAsync();");
+      }
+      else {
+        chunks.push(`        await LocatorByTestId(${testIdExpr}).ClickAsync();`);
+      }
+      chunks.push("    }");
+      chunks.push("");
+    }
+
+    chunks.push("}");
+    chunks.push("");
+  }
+
+  const outputFile = path.join(outAbs, "page-object-models.g.cs");
+  return [{ filePath: outputFile, content: chunks.join("\n") }];
+}
+
+function maybeGenerateFixtureRegistry(
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  options: {
+    generateFixtures: GenerateFilesOptions["generateFixtures"];
+    pomOutDir: string;
+    projectRoot?: string;
+  },
+) {
+  const { generateFixtures, pomOutDir, projectRoot } = options;
+  if (!generateFixtures)
+    return;
+
+  // generateFixtures accepts:
+  // - true: enable fixtures with defaults
+  // - "path": enable fixtures and write them under this directory OR to this file if it ends with .ts
+  // - { outDir }: enable fixtures and override output directory
+  const defaultFixtureOutDirRel = pomOutDir;
+  const fixtureOutRel = typeof generateFixtures === "string"
+    ? generateFixtures
+    : (typeof generateFixtures === "object" && generateFixtures?.outDir
+      ? generateFixtures.outDir
+      : defaultFixtureOutDirRel);
+
+  const looksLikeFilePath = fixtureOutRel.endsWith(".ts") || fixtureOutRel.endsWith(".tsx") || fixtureOutRel.endsWith(".mts") || fixtureOutRel.endsWith(".cts");
+  const fixtureOutDirRel = looksLikeFilePath ? path.dirname(fixtureOutRel) : fixtureOutRel;
+  const fixtureFileName = looksLikeFilePath ? path.basename(fixtureOutRel) : "fixtures.g.ts";
+
+  const root = projectRoot ?? process.cwd();
+  const fixtureOutDirAbs = path.isAbsolute(fixtureOutDirRel)
+    ? fixtureOutDirRel
+    : path.resolve(root, fixtureOutDirRel);
+
+  // Resolve the directory that contains the POM barrel export (e.g. <root>/pom).
+  const pomDirAbs = path.isAbsolute(pomOutDir) ? pomOutDir : path.resolve(root, pomOutDir);
+
+  const pomImport = toPosixRelativePath(fixtureOutDirAbs, pomDirAbs);
+
+  const viewClassNames = Array.from(componentHierarchyMap.entries())
+    .filter(([, deps]) => !!deps.isView)
+    .map(([name]) => name)
+    .sort((a, b) => a.localeCompare(b));
+
+  const reservedPlaywrightFixtureNames = new Set([
+    // Built-in Playwright fixtures
+    "page",
+    "context",
+    "browser",
+    "browserName",
+    "request",
+    // Our own fixtureOptions
+    "animation",
+  ]);
+
+  const viewFixtureNames = new Set(viewClassNames.map(name => lowerFirst(name)));
+
+  const componentClassNames = Array.from(componentHierarchyMap.entries())
+    .filter(([, deps]) => !deps.isView)
+    .map(([name]) => name)
+    .filter((name) => {
+      const fixtureName = lowerFirst(name);
+      if (reservedPlaywrightFixtureNames.has(fixtureName))
+        return false;
+      if (viewFixtureNames.has(fixtureName))
+        return false;
+      return true;
+    })
+    .sort((a, b) => a.localeCompare(b));
+
+  const header = `${eslintSuppressionHeader}/**\n`
+    + ` * DO NOT MODIFY BY HAND\n`
+    + ` *\n`
+    + ` * This file is auto-generated by vue-pom-generator.\n`
+    + ` * Changes should be made in the generator/template, not in the generated output.\n`
+    + ` */\n\n`;
+
+  // Concrete, strongly-typed fixtures for Playwright tests.
+  //   test("...", async ({ preferencesPage }) => { ... })
+  //
+  // View POMs implement goTo() directly, so fixtures can be strongly typed without
+  // casting/augmenting at runtime.
+  const fixturesTypeEntries = viewClassNames
+    .map(name => `  ${lowerFirst(name)}: Pom.${name},`)
+    .join("\n");
+
+  const componentFixturesTypeEntries = componentClassNames
+    .map(name => `  ${lowerFirst(name)}: Pom.${name},`)
+    .join("\n");
+
+  const pomFactoryType = `export type PomConstructor<T> = new (page: PwPage) => T;\n\n`
+    + `export interface PomFactory {\n`
+    + `  create<T>(ctor: PomConstructor<T>): T;\n`
+    + `}\n\n`;
+
+  // NOTE: We intentionally do not generate "openXPage" helpers.
+  // Each view POM provides goTo(), and tests call it explicitly.
+
+  // Openers removed.
+
+  const fixturesContent = `${header
+  }/** Generated Playwright fixtures (typed page objects). */\n\n`
+  + `import { expect, test as base } from "@playwright/test";\n`
+  + `import type { Page as PwPage } from "@playwright/test";\n`
+  + `import * as Pom from "${pomImport}";\n\n`
+  + `export interface PlaywrightOptions {\n`
+  + `  animation: Pom.PlaywrightAnimationOptions;\n`
+  + `}\n\n`
+  + `${pomFactoryType}`
+  + `type PomSetupFixture = { pomSetup: void };\n`
+  + `type PomFactoryFixture = { pomFactory: PomFactory };\n\n`
+            + `const pageCtors = {\n${fixturesTypeEntries}\n} as const;\n`
+                + `const componentCtors = {\n${componentFixturesTypeEntries}\n} as const;\n\n`
+                + `export type GeneratedPageFixtures = { [K in keyof typeof pageCtors]: InstanceType<(typeof pageCtors)[K]> };\n`
+                + `export type GeneratedComponentFixtures = { [K in keyof typeof componentCtors]: InstanceType<(typeof componentCtors)[K]> };\n\n`
+                + `const makePomFixture = <T>(Ctor: PomConstructor<T>) => async ({ page }: { page: PwPage }, use: (t: T) => Promise<void>) => {\n`
+                + `  await use(new Ctor(page));\n`
+                + `};\n\n`
+                + `const createPomFixtures = <TMap extends Record<string, PomConstructor<any>>>(ctors: TMap) => {\n`
+                + `  const out: Record<string, any> = {};\n`
+                + `  for (const [key, Ctor] of Object.entries(ctors)) {\n`
+                + `    out[key] = makePomFixture(Ctor as PomConstructor<any>);\n`
+                + `  }\n`
+                + `  return out as any;\n`
+                + `};\n\n`
+                + `const test = base.extend<PlaywrightOptions & PomSetupFixture & PomFactoryFixture & GeneratedPageFixtures & GeneratedComponentFixtures>({\n`
+                + `  animation: [{\n`
+                + `    pointer: { durationMilliseconds: 250, transitionStyle: "ease-in-out", clickDelayMilliseconds: 0 },\n`
+                + `    keyboard: { typeDelayMilliseconds: 100 },\n`
+                + `  }, { option: true }],\n`
+                + `  pomSetup: [async ({ animation }, use) => {\n`
+                + `    Pom.setPlaywrightAnimationOptions(animation);\n`
+                + `    await use();\n`
+                + `  }, { auto: true }],\n`
+                + `  pomFactory: async ({ page }, use) => {\n`
+                + `    await use({\n`
+                + `      create: <T>(ctor: PomConstructor<T>) => new ctor(page),\n`
+                + `    });\n`
+                + `  },\n`
+                + `  ...createPomFixtures(pageCtors),\n`
+                + `  ...createPomFixtures(componentCtors),\n`
+                + `});\n\n`
+                + `export { test, expect };\n`;
+
+  createFile(path.resolve(fixtureOutDirAbs, fixtureFileName), fixturesContent);
+
+  // No pomFixture is generated; goToSelf is emitted directly on each view POM.
+}
+
+function generateViewObjectModelContent(
+  componentName: string,
+  dependencies: IComponentDependencies,
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  vueFilesPathMap: Map<string, string>,
+  basePageClassPath: string,
+  options: GenerateContentOptions = {},
+) {
+  const { isView, childrenComponentSet, usedComponentSet, filePath } = dependencies;
+
+  const {
+    outputDir = path.dirname(filePath),
+    aggregated = false,
+    customPomAttachments = [],
+    testIdAttribute,
+  } = options;
+
+  const hasChildComponent = (needle: string) => {
+    const haystack = usedComponentSet?.size ? usedComponentSet : childrenComponentSet;
+    for (const child of haystack) {
+      if (child === needle)
+        return true;
+      if (child === `${needle}.vue`)
+        return true;
+      if (child.endsWith(".vue") && child.slice(0, -4) === needle)
+        return true;
+    }
+    return false;
+  };
+
+  const attachmentsForThisClass = customPomAttachments
+    .filter((a) => {
+      const scope = a.attachTo ?? "views";
+      const scopeOk = isView
+        ? (scope === "views" || scope === "both")
+        : (scope === "components" || scope === "both");
+      if (!scopeOk)
+        return false;
+      return a.attachWhenUsesComponents.some(c => hasChildComponent(c));
+    })
+    .map(a => ({ className: a.className, propertyName: a.propertyName }));
+
+  let content: string = "";
+
+  const sourceRel = toPosixRelativePath(outputDir, filePath);
+  const kind = isView ? "Page" : "Component";
+  const doc = `/** ${kind} POM: ${componentName} (source: ${sourceRel}) */\n`;
+
+  // In aggregated mode, imports are hoisted once at the top of the file.
+  if (!aggregated) {
+    content = `${eslintSuppressionHeader}${doc}`;
+
+    // We only need PwPage when we emit a constructor (views always do; components only do
+    // when they have custom attachments like Grid).
+    if (isView || attachmentsForThisClass.length > 0) {
+      content += "import type { Page as PwPage } from \"@playwright/test\";\n";
+    }
+
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const fromAbs = path.isAbsolute(outputDir) ? outputDir : path.resolve(projectRoot, outputDir);
+    const toAbs = basePageClassPath
+      ? (path.isAbsolute(basePageClassPath) ? basePageClassPath : path.resolve(projectRoot, basePageClassPath))
+      : "";
+    const basePageImport = path.relative(fromAbs, toAbs).replace(/\\/g, "/");
+    // stripExtension uses node:path formatting (platform-specific). Re-normalize to POSIX
+    // so the import specifier is valid on Windows.
+    const basePageImportNoExt = stripExtension(basePageImport).replace(/\\/g, "/");
+    const basePageImportSpecifier = basePageImportNoExt.startsWith(".") ? basePageImportNoExt : `./${basePageImportNoExt}`;
+    content += `import { BasePage, Fluent } from '${basePageImportSpecifier}';\n\n`;
+
+    if (isView && childrenComponentSet.size > 0) {
+      childrenComponentSet.forEach((child) => {
+        if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
+          const childPath = vueFilesPathMap.get(child);
+          let relativePath = path.relative(outputDir, childPath || "");
+          relativePath = changeExtension(relativePath, ".vue", ".g").replace(/\\/g, "/");
+          content += `import { ${child} } from '${relativePath}';\n`;
+        }
+      });
+    }
+  }
+  else {
+    // Keep per-class doc comment, but avoid repeating eslint suppression / imports.
+    content = doc;
+  }
+
+  content += `\nexport class ${componentName} extends BasePage {\n`;
+
+  const widgetInstances = isView
+    ? getWidgetInstancesForView(componentName, dependencies.dataTestIdSet)
+    : [];
+
+  // For views, `childrenComponentSet` only includes component tags on which we applied a data-testid.
+  // Thin wrapper views (e.g. NewTenantPage) may have *no* generated test ids but still contain
+  // important child component POMs (forms, grids, etc). In those cases, we use `usedComponentSet`
+  // to discover and instantiate child component POMs.
+  const componentRefsForInstances = isView
+    ? (usedComponentSet?.size ? usedComponentSet : childrenComponentSet)
+    : childrenComponentSet;
+
+  // Only views get child component instance fields by default.
+  // Components will only get a constructor/fields when they have explicit custom attachments
+  // (e.g. wrapper components around a third-party data grid should get a `grid: Grid`).
+  if (isView && (componentRefsForInstances.size > 0 || attachmentsForThisClass.length > 0 || widgetInstances.length > 0)) {
+    content += getComponentInstances(componentRefsForInstances, componentHierarchyMap, attachmentsForThisClass, widgetInstances);
+    content += getConstructor(componentRefsForInstances, componentHierarchyMap, attachmentsForThisClass, widgetInstances, { testIdAttribute });
+  }
+  if (!isView && attachmentsForThisClass.length > 0) {
+    content += getComponentInstances(new Set(), componentHierarchyMap, attachmentsForThisClass);
+    content += getConstructor(new Set(), componentHierarchyMap, attachmentsForThisClass, [], { testIdAttribute });
+  }
+
+  // Ergonomics: when a view is primarily composed of a single component POM (e.g. a form),
+  // allow calling that component's methods directly on the page class.
+  //
+  // Example:
+  //   await tenantListPage.goToNewTenant().typeTenantName(...).clickCreateTenant();
+  //
+  // Rules:
+  // - Only for views (not components) to avoid polluting component surfaces.
+  // - Only generate pass-throughs when the method is unambiguous across child components.
+  // - Never generate a pass-through that would collide with an existing method on the view.
+  // Only generate view passthrough methods when the view is essentially a thin wrapper
+  // around a single child component POM. This prevents "layout" components (Page, PageHeader,
+  // etc.) from injecting lots of noisy passthrough APIs into every view.
+  if (isView && componentRefsForInstances.size === 1) {
+    content += getViewPassthroughMethods(componentName, dependencies, componentRefsForInstances, componentHierarchyMap);
+  }
+
+  if (isView && options.vueRouterFluentChaining) {
+    const routeMeta = options.routeMetaByComponent?.[componentName] ?? null;
+    content += generateRouteProperty(routeMeta);
+    content += generateGoToSelfMethod(componentName);
+  }
+
+  content += generateMethodsContentForDependencies(dependencies);
+
+  content += "}\n";
+  return content;
+}
+
+function getViewPassthroughMethods(
+  viewName: string,
+  viewDependencies: IComponentDependencies,
+  childrenComponentSet: Set<string>,
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+) {
+  const existingOnView = viewDependencies.generatedMethods ?? new Map<string, { params: string; argNames: string[] } | null>();
+
+  // methodName -> candidates
+  const methodToChildren = new Map<string, Array<{ childProp: string; params: string; argNames: string[] }>>();
+
+  for (const child of childrenComponentSet) {
+    const childDeps = componentHierarchyMap.get(child);
+    if (!childDeps || !childDeps.dataTestIdSet?.size)
+      continue;
+
+    const methods = childDeps.generatedMethods;
+    if (!methods)
+      continue;
+
+    // Property name matches how we emit instance fields (strip .vue if present).
+    const childProp = child.endsWith(".vue") ? child.slice(0, -4) : child;
+
+    for (const [name, sig] of methods.entries()) {
+      if (!sig)
+        continue; // ambiguous on the child itself
+
+      // If the view already has this method name, never generate a pass-through.
+      if (existingOnView.has(name))
+        continue;
+
+      const list = methodToChildren.get(name) ?? [];
+      list.push({ childProp, params: sig.params, argNames: sig.argNames });
+      methodToChildren.set(name, list);
+    }
+  }
+
+  const sorted = Array.from(methodToChildren.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+  const lines: string[] = [];
+
+  for (const [methodName, candidates] of sorted) {
+    // Only generate when exactly one child can satisfy the call.
+    if (candidates.length !== 1)
+      continue;
+
+    const { childProp, params, argNames } = candidates[0];
+    const callArgs = argNames.join(", ");
+
+    lines.push(
+      "",
+      `    async ${methodName}(${params}) {`,
+      `        return await this.${childProp}.${methodName}(${callArgs});`,
+      "    }",
+    );
+  }
+
+  if (!lines.length) {
+    return "";
+  }
+
+  return [
+    "",
+    `    // Passthrough methods composed from child component POMs of ${viewName}.`,
+    ...lines,
+    "",
+  ].join("\n");
+}
+
+function ensureDir(dir: string) {
+  const normalized = dir.replace(/\\/g, "/");
+  if (!fs.existsSync(normalized)) {
+    fs.mkdirSync(normalized, { recursive: true });
+  }
+  return normalized;
+}
+
+async function generateAggregatedFiles(
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  vueFilesPathMap: Map<string, string>,
+  basePageClassPath: string,
+  outDir: string,
+  options: {
+    customPomAttachments?: GenerateFilesOptions["customPomAttachments"];
+    projectRoot?: GenerateFilesOptions["projectRoot"];
+    customPomDir?: GenerateFilesOptions["customPomDir"];
+    customPomImportAliases?: GenerateFilesOptions["customPomImportAliases"];
+    testIdAttribute?: GenerateFilesOptions["testIdAttribute"];
+    generateFixtures?: GenerateFilesOptions["generateFixtures"];
+    routeMetaByComponent?: Record<string, RouteMeta>;
+    vueRouterFluentChaining?: boolean;
+  } = {},
+) {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const entries = Array.from(componentHierarchyMap.entries())
+    .sort((a, b) => a[0].localeCompare(b[0]));
+
+  const views = entries.filter(([, d]) => d.isView);
+  const components = entries.filter(([, d]) => !d.isView);
+
+  const makeAggregatedContent = (
+    header: string,
+    outputDir: string,
+    items: Array<[string, IComponentDependencies]>,
+  ) => {
+    // Alias Playwright types to avoid collisions with generated classes (e.g. a Vue component named `Page`).
+    const imports: string[] = ["import type { Locator as PwLocator, Page as PwPage } from \"@playwright/test\";"];
+
+    if (!basePageClassPath) {
+      throw new Error("basePageClassPath is required for aggregated generation");
+    }
+
+    // Inline BasePage into the aggregated output.
+    //
+    // Why:
+    // - Playwright's runtime loader can treat workspace packages (like `vue-pom-generator`)
+    //   as external and not apply TS transforms/module resolution consistently.
+    // - Importing a .ts file from inside a "type": "module" package can fail with
+    //   "Cannot find module" at runtime.
+    //
+    // Inlining keeps the generated POMs self-contained and stable across platforms.
+    const clickInstrumentationInline = [
+      "export const TESTID_CLICK_EVENT_NAME = \"__testid_event__\";",
+      "export const TESTID_CLICK_EVENT_STRICT_FLAG = \"__testid_click_event_strict__\";",
+      "export interface TestIdClickEventDetail {",
+      "  testId?: string;",
+      "  phase?: \"before\" | \"after\" | \"error\" | string;",
+      "  err?: string;",
+      "}",
+    ].join("\n");
+
+    const inlinePointerModule = () => {
+      // Inline Pointer.ts from this package so generated POMs are self-contained and do not
+      // rely on runtime TS module resolution within workspace packages.
+      const pointerPath = fileURLToPath(new URL("./Pointer.ts", import.meta.url));
+
+      let pointerSource = "";
+      try {
+        pointerSource = fs.readFileSync(pointerPath, "utf8");
+      }
+      catch {
+        throw new Error(`Failed to read Pointer.ts at ${pointerPath}`);
+      }
+
+      // Replace the click-instrumentation import with an inline copy.
+      pointerSource = pointerSource.replace(
+        /import\s*\{[\s\S]*?\}\s*from\s*["']\.\.\/click-instrumentation["'];?\s*/,
+        `${clickInstrumentationInline}\n\n`,
+      );
+
+      // If Pointer uses a split value import + type-only import, remove the type-only import too.
+      // The inline block already declares TestIdClickEventDetail.
+      pointerSource = pointerSource.replace(
+        /import\s+type\s*\{\s*TestIdClickEventDetail\s*\}\s*from\s*["']\.\.\/click-instrumentation["'];?\s*/g,
+        "",
+      );
+
+      // The aggregated file already imports these Playwright types once at the top.
+      pointerSource = pointerSource.replace(
+        /import\s+type\s*\{\s*Locator\s+as\s+PwLocator\s*,\s*Page\s+as\s+PwPage\s*\}\s*from\s*["']@playwright\/test["'];?\s*/,
+        "",
+      );
+
+      return pointerSource.trim();
+    };
+
+    const inlineBasePageModule = () => {
+      let basePageSource = "";
+      try {
+        basePageSource = fs.readFileSync(basePageClassPath, "utf8");
+      }
+      catch {
+        throw new Error(`Failed to read BasePage.ts at ${basePageClassPath}`);
+      }
+
+      // Replace the click-instrumentation import with an inline copy.
+      basePageSource = basePageSource.replace(
+        /import\s*\{[\s\S]*?\}\s*from\s*["']\.\.\/click-instrumentation["'];?\s*/,
+        `${clickInstrumentationInline}\n\n`,
+      );
+
+      // If BasePage uses a split value import + type-only import, remove the type-only import too.
+      // The inline block already declares TestIdClickEventDetail.
+      basePageSource = basePageSource.replace(
+        /import\s+type\s*\{\s*TestIdClickEventDetail\s*\}\s*from\s*["']\.\.\/click-instrumentation["'];?\s*/g,
+        "",
+      );
+
+      // The aggregated file already imports these Playwright types once at the top.
+      // Remove BasePage's own import to avoid duplicate identifiers.
+      basePageSource = basePageSource.replace(
+        /import\s+type\s*\{\s*Locator\s+as\s+PwLocator\s*,\s*Page\s+as\s+PwPage\s*\}\s*from\s*["']@playwright\/test["'];?\s*/,
+        "",
+      );
+
+      // BasePage references Pointer, but in aggregated output we inline Pointer above.
+      basePageSource = basePageSource.replace(
+        /import\s*\{\s*Pointer\s*\}\s*from\s*["']\.\/Pointer["'];?\s*/g,
+        "",
+      );
+
+      return basePageSource.trim();
+    };
+
+    const pointerInline = inlinePointerModule();
+    const basePageInline = inlineBasePageModule();
+
+    // Handwritten POM helpers for complicated/third-party widgets.
+    // Convention: place them in `tests/playwright/pom/custom/*.ts`.
+    // Import them rather than inlining so TypeScript can typecheck them.
+    const addCustomPomImports = () => {
+      // Some custom POM helpers intentionally share names with generated component POMs
+      // (e.g. Toggle.vue -> generated class `Toggle`). Import with aliases to avoid
+      // merged-declaration conflicts in the aggregated output.
+      const importAliases: Record<string, string> = {
+        Toggle: "ToggleWidget",
+        Checkbox: "CheckboxWidget",
+        ...(options.customPomImportAliases ?? {}),
+      };
+
+      const customDirRelOrAbs = options.customPomDir ?? "tests/playwright/pom/custom";
+      const customDirAbs = path.isAbsolute(customDirRelOrAbs)
+        ? customDirRelOrAbs
+        : path.resolve(projectRoot, customDirRelOrAbs);
+
+      if (!fs.existsSync(customDirAbs)) {
+        return;
+      }
+
+      const files = fs.readdirSync(customDirAbs)
+        .filter(f => f.endsWith(".ts"))
+        .sort((a, b) => a.localeCompare(b));
+
+      for (const file of files) {
+        const exportName = file.replace(/\.ts$/i, "");
+        // In this repo, custom POMs are authored as `export class <Name> { ... }`.
+        // Import by the basename, which matches the class name convention.
+        const alias = importAliases[exportName];
+        const customFileAbs = path.join(customDirAbs, file);
+        const fromOutputDir = outputDir;
+        const importPath = stripExtension(toPosixRelativePath(fromOutputDir, customFileAbs));
+        if (alias) {
+          imports.push(`import { ${exportName} as ${alias} } from "${importPath}";`);
+        }
+        else {
+          imports.push(`import { ${exportName} } from "${importPath}";`);
+        }
+      }
+    };
+
+    addCustomPomImports();
+
+    // Collect any navigation return types referenced by generated methods so we can emit
+    // stub classes when the destination view has no generated test ids (and therefore no
+    // corresponding POM class in this file).
+    const referencedTargets = new Set<string>();
+    for (const [, deps] of items) {
+      for (const dt of deps.dataTestIdSet) {
+        if (dt.targetPageObjectModelClass) {
+          referencedTargets.add(dt.targetPageObjectModelClass);
+        }
+      }
+    }
+
+    const generatedClassNames = new Set(items.map(([name]) => name));
+    const stubTargets = Array.from(referencedTargets)
+      .filter(t => !generatedClassNames.has(t))
+      .sort((a, b) => a.localeCompare(b));
+
+    const availableClassNames = new Set<string>([...generatedClassNames, ...stubTargets]);
+
+    const depsByClassName = new Map<string, IComponentDependencies>(entries);
+
+    const scanPascalCaseTags = (template: string) => {
+      // Extracts tag names like <TenantDetailsEditForm ...> without regex.
+      // We only care about PascalCase component tags.
+      const names: string[] = [];
+      const len = template.length;
+      let i = 0;
+      while (i < len) {
+        const ch = template[i];
+        if (ch !== "<") {
+          i++;
+          continue;
+        }
+
+        i++; // consume '<'
+        if (i >= len)
+          break;
+
+        // Skip closing tags and directives/comments
+        if (template[i] === "/" || template[i] === "!" || template[i] === "?") {
+          i++;
+          continue;
+        }
+
+        // Skip whitespace
+        while (i < len && (template[i] === " " || template[i] === "\n" || template[i] === "\t" || template[i] === "\r")) i++;
+        if (i >= len)
+          break;
+
+        const first = template[i];
+        // Only PascalCase (starts with A-Z)
+        if (first < "A" || first > "Z") {
+          continue;
+        }
+
+        const start = i;
+        i++;
+        while (i < len) {
+          const c = template[i];
+          const isLetter = (c >= "A" && c <= "Z") || (c >= "a" && c <= "z");
+          const isDigit = c >= "0" && c <= "9";
+          const isUnderscore = c === "_";
+          if (isLetter || isDigit || isUnderscore) {
+            i++;
+            continue;
+          }
+          break;
+        }
+        const name = template.slice(start, i);
+        if (name)
+          names.push(name);
+      }
+      return Array.from(new Set(names));
+    };
+
+    const getComposedStubBody = (targetClassName: string) => {
+      const mapped = vueFilesPathMap.get(targetClassName);
+      const candidates = [
+        mapped,
+        path.join(projectRoot, "src", "views", `${targetClassName}.vue`),
+        path.join(projectRoot, "src", "components", `${targetClassName}.vue`),
+      ].filter((p): p is string => typeof p === "string" && p.length > 0);
+
+      const filePath = candidates.find(p => fs.existsSync(p));
+      if (!filePath)
+        return undefined;
+
+      // Heuristic: scan the SFC template for PascalCase tags. If we have generated
+      // POM classes for those components, include them as composed children.
+      let source = "";
+      try {
+        source = fs.readFileSync(filePath, "utf8");
+      }
+      catch {
+        return undefined;
+      }
+
+      const templateOpen = source.indexOf("<template");
+      const templateClose = source.lastIndexOf("</template>");
+      if (templateOpen === -1 || templateClose === -1 || templateClose <= templateOpen)
+        return undefined;
+
+      const afterOpenTag = source.indexOf(">", templateOpen);
+      if (afterOpenTag === -1 || afterOpenTag >= templateClose)
+        return undefined;
+
+      const template = source.slice(afterOpenTag + 1, templateClose);
+      if (!template)
+        return undefined;
+
+      const tags = scanPascalCaseTags(template);
+      const childClassNames = Array.from(
+        new Set(
+          tags
+            .filter(name => availableClassNames.has(name))
+            .filter(name => name !== targetClassName),
+        ),
+      ).sort((a, b) => a.localeCompare(b));
+
+      if (!childClassNames.length)
+        return undefined;
+
+      // Build passthrough methods from stub -> child component when the method is unambiguous.
+      // This enables ergonomics like:
+      //   await tenantListPage.goToNewTenant().typeTenantName(...)
+      // without forcing the test to reference `.TenantDetailsEditForm`.
+      const methodToChildren = new Map<string, Array<{ child: string; params: string; argNames: string[] }>>();
+      for (const child of childClassNames) {
+        const childDeps = depsByClassName.get(child);
+        const methods = childDeps?.generatedMethods;
+        if (!methods)
+          continue;
+
+        for (const [name, sig] of methods.entries()) {
+          if (!sig)
+            continue; // ambiguous
+          const list = methodToChildren.get(name) ?? [];
+          list.push({ child, params: sig.params, argNames: sig.argNames });
+          methodToChildren.set(name, list);
+        }
+      }
+
+      const passthroughLines: string[] = [];
+      for (const [methodName, candidatesForMethod] of methodToChildren.entries()) {
+        if (candidatesForMethod.length !== 1)
+          continue;
+
+        // Avoid creating pass-throughs for internal-ish helpers.
+        if (methodName === "constructor")
+          continue;
+
+        const { child, params, argNames } = candidatesForMethod[0];
+        const callArgs = argNames.join(", ");
+
+        passthroughLines.push(
+          "",
+          `    async ${methodName}(${params}) {`,
+          `        return await this.${child}.${methodName}(${callArgs});`,
+          "    }",
+        );
+      }
+
+      return {
+        childClassNames,
+        lines: [
+          ...childClassNames.map(c => `    ${c}: ${c};`),
+          "",
+          "    constructor(page: PwPage) {",
+          "        super(page);",
+          ...childClassNames.map(c => `        this.${c} = new ${c}(page);`),
+          "    }",
+          ...passthroughLines,
+        ],
+      };
+    };
+
+    const stubs = stubTargets.map(t =>
+      (() => {
+        const composed = getComposedStubBody(t);
+        const body = composed?.lines ?? [
+          "    constructor(page: PwPage) {",
+          "        super(page);",
+          "    }",
+        ];
+
+        return [
+          "/**\n * Stub POM generated because it is referenced as a navigation target but\n * did not have any generated test ids in this build.\n */",
+          `export class ${t} extends BasePage {`,
+          ...body,
+          "}",
+        ].join("\n");
+      })(),
+    );
+
+    const classes = items.map(([name, deps]) =>
+      generateViewObjectModelContent(name, deps, componentHierarchyMap, vueFilesPathMap, basePageClassPath, {
+        outputDir,
+        aggregated: true,
+
+        customPomAttachments: options.customPomAttachments ?? [],
+        testIdAttribute: options.testIdAttribute,
+        vueRouterFluentChaining: options.vueRouterFluentChaining,
+        routeMetaByComponent: options.routeMetaByComponent,
+      }),
+    );
+
+    const baseContent = [
+      header,
+      ...imports,
+      "",
+      pointerInline,
+      "",
+      basePageInline,
+      "",
+      ...classes,
+      ...(stubs.length ? ["", ...stubs] : []),
+    ].filter(Boolean).join("\n\n");
+
+    return baseContent;
+  };
+
+  const base = ensureDir(outDir);
+  const outputFile = path.join(base, "page-object-models.g.ts");
+  const header = `${eslintSuppressionHeader}/**\n * Aggregated generated POMs\n${AUTO_GENERATED_COMMENT}`;
+  const content = makeAggregatedContent(header, path.dirname(outputFile), [...views, ...components]);
+
+  const indexFile = path.join(base, "index.ts");
+  const indexContent = `${eslintSuppressionHeader}/**\n * POM exports\n${AUTO_GENERATED_COMMENT}\n\nexport * from "./page-object-models.g";\n`;
+
+  return [
+    { filePath: outputFile, content },
+    { filePath: indexFile, content: indexContent },
+  ];
+}
+
+function createFile(filePath: string, content: string) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+  fs.writeFileSync(filePath, content);
+}
+
+function lowerFirst(value: string): string {
+  if (!value)
+    return value;
+  return value.charAt(0).toLowerCase() + value.slice(1);
+}
+
+function toPascalCaseLocal(str: string): string {
+  const cleaned = (str ?? "")
+    .replace(/\$\{[^}]*\}/g, " ")
+    .replace(/[^a-z0-9]+/gi, " ")
+    .trim();
+
+  if (!cleaned)
+    return "";
+
+  return cleaned
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((word) => {
+      const preserveInternalCaps = /[a-z][A-Z]/.test(word);
+      return preserveInternalCaps
+        ? upperFirst(word)
+        : upperFirst(word.toLowerCase());
+    })
+    .join("");
+}
+
+interface WidgetInstance {
+  className: "ToggleWidget" | "CheckboxWidget";
+  propertyName: string;
+  testId: string;
+}
+
+function getWidgetInstancesForView(componentName: string, dataTestIdSet: Set<IDataTestId>): WidgetInstance[] {
+  const out: WidgetInstance[] = [];
+  const usedPropNames = new Set<string>();
+
+  const ensureUnique = (base: string) => {
+    let candidate = base;
+    let i = 2;
+    while (usedPropNames.has(candidate)) {
+      candidate = `${base}${i}`;
+      i++;
+    }
+    usedPropNames.add(candidate);
+    return candidate;
+  };
+
+  for (const dt of dataTestIdSet) {
+    const raw = dt.value;
+
+    // Skip keyed/dynamic test ids; instance fields can't represent those ergonomically.
+    if (raw.includes("${")) {
+      continue;
+    }
+
+    const toggleSuffix = "-toggle";
+    const checkboxSuffix = "-checkbox";
+
+    let className: WidgetInstance["className"] | null = null;
+    let stem = "";
+
+    if (raw.endsWith(toggleSuffix)) {
+      className = "ToggleWidget";
+      stem = raw.slice(0, -toggleSuffix.length);
+    }
+    else if (raw.endsWith(checkboxSuffix)) {
+      className = "CheckboxWidget";
+      stem = raw.slice(0, -checkboxSuffix.length);
+    }
+    else {
+      continue;
+    }
+
+    // Prefer stripping the view prefix (e.g. PreferencesPage-) for cleaner member names.
+    const viewPrefix = `${componentName}-`;
+    const descriptorRaw = stem.startsWith(viewPrefix) ? stem.slice(viewPrefix.length) : stem;
+    const descriptorPascal = toPascalCaseLocal(descriptorRaw);
+
+    if (!descriptorPascal) {
+      continue;
+    }
+
+    if (className === "ToggleWidget") {
+      let base = descriptorPascal.replace(/Toggle$/i, "");
+
+      // Ergonomic naming: if a toggle name contains an "Enable..." tail, prefer that tail.
+      // Example: AppPreferencesEnableSessionEmails -> enableSessionEmailsToggle
+      const enableIndex = base.indexOf("Enable");
+      if (enableIndex > 0) {
+        base = base.slice(enableIndex);
+      }
+
+      const propBase = lowerFirst(base);
+      const propName = ensureUnique(propBase ? `${propBase}Toggle` : "toggle");
+      out.push({ className, propertyName: propName, testId: raw });
+      continue;
+    }
+
+    // Checkbox
+    const base = descriptorPascal
+      .replace(/CheckBox$/i, "")
+      .replace(/Checkbox$/i, "");
+    const propBase = lowerFirst(base);
+    const propName = ensureUnique(propBase ? `${propBase}Checkbox` : "checkbox");
+    out.push({ className, propertyName: propName, testId: raw });
+  }
+
+  return out;
+}
+
+function getComponentInstances(
+  childrenComponent: Set<string>,
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  attachmentsForThisView: Array<{ className: string; propertyName: string }> = [],
+  widgetInstances: WidgetInstance[] = [],
+) {
+  let content = "\n";
+
+  for (const a of attachmentsForThisView) {
+    content += `    ${a.propertyName}: ${a.className};\n`;
+  }
+
+  for (const w of widgetInstances) {
+    content += `    ${w.propertyName}: ${w.className};\n`;
+  }
+
+  childrenComponent.forEach((child) => {
+    if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
+      const childName = child.split(".vue")[0];
+      content += `    ${childName}: ${childName};\n`;
+    }
+  });
+  return `${content}\n`;
+}
+
+function getConstructor(
+  childrenComponent: Set<string>,
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  attachmentsForThisView: Array<{ className: string; propertyName: string }> = [],
+  widgetInstances: WidgetInstance[] = [],
+  options?: { testIdAttribute?: string },
+) {
+  let content = "    constructor(page: PwPage) {\n";
+  const attr = (options?.testIdAttribute ?? "data-testid").trim() || "data-testid";
+  content += `        super(page, { testIdAttribute: ${JSON.stringify(attr)} });\n`;
+
+  for (const a of attachmentsForThisView) {
+    content += `        this.${a.propertyName} = new ${a.className}(page, this);\n`;
+  }
+
+  for (const w of widgetInstances) {
+    content += `        this.${w.propertyName} = new ${w.className}(page, ${JSON.stringify(w.testId)});\n`;
+  }
+
+  childrenComponent.forEach((child) => {
+    if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
+      const childName = child.split(".vue")[0];
+      content += `        this.${childName} = new ${childName}(page);\n`;
+    }
+  });
+  content += "    }";
+  return `${content}\n`;
+}