@immense/vue-pom-generator 1.0.47 → 1.0.49

package/class-generation/index.ts

@@ -1,12 +1,47 @@
 import { parse } from "@babel/parser";
 import type { ClassMethod } from "@babel/types";
+import type { ElementNode, ForNode, IfBranchNode, IfNode, RootNode, TemplateChildNode } from "@vue/compiler-core";
+import { ElementTypes } from "@vue/compiler-core";
+import { NodeTypes, parse as parseTemplate } from "@vue/compiler-dom";
+import { parse as parseSfc } from "@vue/compiler-sfc";
 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 { generateViewObjectModelMembers, generateViewObjectModelMethodContent } from "../method-generation";
 import { introspectNuxtPages, parseRouterFileFromCwd } from "../router-introspection";
-import { IComponentDependencies, IDataTestId, PomExtraClickMethodSpec, PomPrimarySpec, upperFirst } from "../utils";
+import {
+  addExportAll,
+  addNamedImport,
+  buildCommentBlock,
+  buildFilePrefix,
+  createClassConstructor,
+  createClassMethod,
+  createClassProperty,
+  renderClassMembers as renderTsMorphClassMembers,
+  renderSourceFile,
+  renderTypeScript,
+  StructureKind,
+  VariableDeclarationKind,
+  type ConstructorDeclarationStructure,
+  type GetAccessorDeclarationStructure,
+  type MethodDeclarationStructure,
+  type OptionalKind,
+  type ParameterDeclarationStructure,
+  type PropertyDeclarationStructure,
+  type TypeScriptClassMember,
+  type TypeScriptSourceFile,
+  type TypeScriptWriter,
+  writeCommentBlock,
+} from "../typescript-codegen";
+import {
+  IComponentDependencies,
+  IDataTestId,
+  PomExtraClickMethodSpec,
+  PomPrimarySpec,
+  toPascalCase,
+  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).
@@ -16,15 +51,179 @@ 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 GENERATED_GITATTRIBUTES_BLOCK_START = "# BEGIN vue-pom-generator generated files";
 const GENERATED_GITATTRIBUTES_BLOCK_END = "# END vue-pom-generator generated files";
 const eslintSuppressionHeader = "/* eslint-disable perfectionist/sort-imports */\n";
+const VUE_POM_GENERATOR_ERROR_PREFIX = "[vue-pom-generator]" as const;
+
+class VuePomGeneratorError extends Error {
+  public constructor(message: string) {
+    const normalized = message.startsWith(VUE_POM_GENERATOR_ERROR_PREFIX)
+      ? message
+      : `${VUE_POM_GENERATOR_ERROR_PREFIX} ${message}`;
+    super(normalized);
+    this.name = "VuePomGeneratorError";
+  }
+}
+
+function renderClassMembers(write: (writer: TypeScriptWriter) => void): string {
+  const content = renderTypeScript((writer) => {
+    writer.indent(() => {
+      write(writer);
+    });
+  });
+  return content.endsWith("\n") ? content : `${content}\n`;
+}
+
+function writeMemberBlock(writer: TypeScriptWriter, signature: string, body: (writer: TypeScriptWriter) => void): void {
+  writer.write(`${signature} `).block(() => {
+    body(writer);
+  });
+}
+
+function writeClassMembersText(writer: TypeScriptWriter, content: string): void {
+  if (!content) {
+    return;
+  }
+
+  const normalized = content
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map(line => line.startsWith("    ") ? line.slice(4) : line)
+    .join("\n");
+
+  writer.write(normalized.endsWith("\n") ? normalized : `${normalized}\n`);
+}
+
+function writeGeneratedMembers(writer: TypeScriptWriter, members: TypeScriptClassMember[]): void {
+  if (!members.length) {
+    return;
+  }
+
+  writeClassMembersText(writer, renderTsMorphClassMembers(members));
+}
+
+function splitParameterList(parameters: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let braceDepth = 0;
+  let bracketDepth = 0;
+  let parenDepth = 0;
+  let angleDepth = 0;
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inTemplateString = false;
+
+  for (let index = 0; index < parameters.length; index += 1) {
+    const char = parameters[index];
+    const previous = index > 0 ? parameters[index - 1] : "";
+
+    if (char === "'" && !inDoubleQuote && !inTemplateString && previous !== "\\") {
+      inSingleQuote = !inSingleQuote;
+      current += char;
+      continue;
+    }
+    if (char === "\"" && !inSingleQuote && !inTemplateString && previous !== "\\") {
+      inDoubleQuote = !inDoubleQuote;
+      current += char;
+      continue;
+    }
+    if (char === "`" && !inSingleQuote && !inDoubleQuote && previous !== "\\") {
+      inTemplateString = !inTemplateString;
+      current += char;
+      continue;
+    }
+
+    if (inSingleQuote || inDoubleQuote || inTemplateString) {
+      current += char;
+      continue;
+    }
+
+    switch (char) {
+      case "{":
+        braceDepth += 1;
+        break;
+      case "}":
+        braceDepth -= 1;
+        break;
+      case "[":
+        bracketDepth += 1;
+        break;
+      case "]":
+        bracketDepth -= 1;
+        break;
+      case "(":
+        parenDepth += 1;
+        break;
+      case ")":
+        parenDepth -= 1;
+        break;
+      case "<":
+        angleDepth += 1;
+        break;
+      case ">":
+        angleDepth -= 1;
+        break;
+      case ",":
+        if (braceDepth === 0 && bracketDepth === 0 && parenDepth === 0 && angleDepth === 0) {
+          const trimmed = current.trim();
+          if (trimmed) {
+            parts.push(trimmed);
+          }
+          current = "";
+          continue;
+        }
+        break;
+      default:
+        break;
+    }
+
+    current += char;
+  }
+
+  const trimmed = current.trim();
+  if (trimmed) {
+    parts.push(trimmed);
+  }
+
+  return parts;
+}
+
+function parseParameterSignature(parameter: string): OptionalKind<ParameterDeclarationStructure> {
+  const colonIndex = parameter.indexOf(":");
+  if (colonIndex < 0) {
+    return { name: parameter.trim() };
+  }
+
+  const rawName = parameter.slice(0, colonIndex).trim();
+  const hasQuestionToken = rawName.endsWith("?");
+  const name = hasQuestionToken ? rawName.slice(0, -1).trim() : rawName;
+  const remainder = parameter.slice(colonIndex + 1).trim();
+  const initializerIndex = remainder.lastIndexOf("=");
+
+  if (initializerIndex < 0) {
+    return {
+      name,
+      hasQuestionToken,
+      type: remainder || undefined,
+    };
+  }
+
+  return {
+    name,
+    hasQuestionToken,
+    type: remainder.slice(0, initializerIndex).trim() || undefined,
+    initializer: remainder.slice(initializerIndex + 1).trim() || undefined,
+  };
+}
+
+function parseParameterSignatures(parameters: string): OptionalKind<ParameterDeclarationStructure>[] {
+  const trimmed = parameters.trim();
+  if (!trimmed) {
+    return [];
+  }
+  return splitParameterList(trimmed).map(parseParameterSignature);
+}
 
 function toPosixRelativePath(fromDir: string, toFile: string): string {
   let rel = path.relative(fromDir, toFile).replace(/\\/g, "/");
@@ -34,13 +233,6 @@ function toPosixRelativePath(fromDir: string, toFile: string): string {
   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*.
@@ -86,6 +278,101 @@ interface ResolvedCustomPomAttachment {
   methodSignatures: CustomPomMethodSignatureMap;
 }
 
+export type TypeScriptOutputStructure = "aggregated" | "split";
+
+interface ResolvedCustomPomImportSpecifier {
+  exportName: string;
+  localIdentifier: string;
+  absolutePath: string;
+}
+
+interface CustomPomImportResolution {
+  classIdentifierMap: Record<string, string>;
+  methodSignaturesByClass: Map<string, CustomPomMethodSignatureMap>;
+  availableClassIdentifiers: Set<string>;
+  importSpecifiersByClass: Record<string, ResolvedCustomPomImportSpecifier>;
+}
+
+function createCustomPomImportCollisionError(exportName: string, requested: string): VuePomGeneratorError {
+  return new VuePomGeneratorError(
+    `Custom POM import name collision detected for "${exportName}".\n`
+    + `The identifier "${requested}" conflicts with a generated POM class.\n`
+    + `Fix by setting generation.playwright.customPoms.importAliases["${exportName}"] to a unique name, `
+    + `or set generation.playwright.customPoms.importNameCollisionBehavior = "alias" to auto-alias collisions.`,
+  );
+}
+
+function normalizeComponentTagToClassName(tag: string): string | undefined {
+  // Vue templates may reference the same component as <MyWidget /> or <my-widget />.
+  const className = toPascalCase(tag);
+  return className || undefined;
+}
+
+function collectReferencedComponentClassNames(nodes: readonly TemplateChildNode[], names: Set<string>): void {
+  for (const node of nodes) {
+    switch (node.type) {
+      case NodeTypes.ELEMENT: {
+        const element = node as ElementNode;
+        if (element.tagType === ElementTypes.COMPONENT) {
+          const className = normalizeComponentTagToClassName(element.tag);
+          if (className) {
+            names.add(className);
+          }
+        }
+        collectReferencedComponentClassNames(element.children, names);
+        break;
+      }
+      case NodeTypes.IF: {
+        const ifNode = node as IfNode;
+        for (const branch of ifNode.branches) {
+          collectReferencedComponentClassNames((branch as IfBranchNode).children, names);
+        }
+        break;
+      }
+      case NodeTypes.FOR: {
+        const forNode = node as ForNode;
+        collectReferencedComponentClassNames(forNode.children, names);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}
+
+function getComponentClassNamesFromVueSource(source: string): string[] {
+  try {
+    const { descriptor } = parseSfc(source);
+    const template = descriptor.template?.content?.trim();
+    if (!template) {
+      return [];
+    }
+
+    const root = parseTemplate(template) as RootNode;
+    const names = new Set<string>();
+    collectReferencedComponentClassNames(root.children, names);
+    return [...names];
+  }
+  catch {
+    return [];
+  }
+}
+
+function resolveVueSourcePath(
+  targetClassName: string,
+  vueFilesPathMap: Map<string, string>,
+  projectRoot: string,
+): string | undefined {
+  const mapped = vueFilesPathMap.get(targetClassName);
+  const candidates = [
+    mapped,
+    path.join(projectRoot, "src", "views", `${targetClassName}.vue`),
+    path.join(projectRoot, "src", "components", `${targetClassName}.vue`),
+  ].filter((candidate): candidate is string => typeof candidate === "string" && candidate.length > 0);
+
+  return candidates.find(candidate => fs.existsSync(candidate));
+}
+
 async function getRouteMetaByComponent(
   projectRoot?: string,
   routerEntry?: string,
@@ -138,38 +425,44 @@ async function getRouteMetaByComponent(
   );
 }
 
-function generateRouteProperty(routeMeta: RouteMeta | null): string {
-  if (!routeMeta) {
-    return "    static readonly route: { template: string } | null = null;\n";
-  }
-
+function generateRouteProperty(routeMeta: RouteMeta | null): TypeScriptClassMember[] {
   return [
-    "    static readonly route: { template: string } | null = {",
-    `        template: ${JSON.stringify(routeMeta.template)},`,
-    "    } as const;",
-    "",
-  ].join("\n");
+    createClassProperty({
+      name: "route",
+      isStatic: true,
+      isReadonly: true,
+      type: "{ template: string } | null",
+      initializer: routeMeta
+        ? `{ template: ${JSON.stringify(routeMeta.template)} } as const`
+        : "null",
+    }),
+  ];
 }
 
-function generateGoToSelfMethod(componentName: string): string {
+function generateGoToSelfMethod(componentName: string): TypeScriptClassMember[] {
   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}'.");`,
-    "        }",
-    "        const runtimeEnv = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;",
-    "        const runtimeBaseUrl = runtimeEnv?.PLAYWRIGHT_RUNTIME_BASE_URL ?? runtimeEnv?.PLAYWRIGHT_TEST_BASE_URL ?? runtimeEnv?.VITE_PLAYWRIGHT_BASE_URL;",
-    "        const targetUrl = runtimeBaseUrl ? new URL(route.template, runtimeBaseUrl).toString() : route.template;",
-    "        await this.page.goto(targetUrl);",
-    "    }",
-    "",
-  ].join("\n");
+    createClassMethod({
+      name: "goTo",
+      isAsync: true,
+      statements: [
+        "await this.goToSelf();",
+      ],
+    }),
+    createClassMethod({
+      name: "goToSelf",
+      isAsync: true,
+      statements: [
+        `const route = ${componentName}.route;`,
+        "if (!route) {",
+        `    throw new Error("[pom] No router path found for component/page-object '${componentName}'.");`,
+        "}",
+        "const runtimeEnv = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;",
+        "const runtimeBaseUrl = runtimeEnv?.PLAYWRIGHT_RUNTIME_BASE_URL ?? runtimeEnv?.PLAYWRIGHT_TEST_BASE_URL ?? runtimeEnv?.VITE_PLAYWRIGHT_BASE_URL;",
+        "const targetUrl = runtimeBaseUrl ? new URL(route.template, runtimeBaseUrl).toString() : route.template;",
+        "await this.page.goto(targetUrl);",
+      ],
+    }),
+  ];
 }
 
 function formatMethodParams(params: Record<string, string> | undefined): string {
@@ -195,24 +488,14 @@ function formatMethodParams(params: Record<string, string> | undefined): string
     .join(", ");
 }
 
-function generateExtraClickMethodContent(spec: PomExtraClickMethodSpec): string {
+function generateExtraClickMethodMembers(spec: PomExtraClickMethodSpec): TypeScriptClassMember[] {
   if (spec.kind !== "click") {
-    return "";
+    return [];
   }
 
   const params = spec.params ?? {};
   const signatureParams = formatMethodParams(params);
-  const signature = signatureParams ? `(${signatureParams})` : "()";
-
-  const lines: string[] = [];
-  lines.push(
-    "",
-    `    async ${spec.name}${signature} {`,
-  );
-
-  if (spec.keyLiteral !== undefined) {
-    lines.push(`        const key = ${JSON.stringify(spec.keyLiteral)};`);
-  }
+  const parameters = parseParameterSignatures(signatureParams);
 
   const hasAnnotationText = Object.prototype.hasOwnProperty.call(params, "annotationText");
   const hasWait = Object.prototype.hasOwnProperty.call(params, "wait");
@@ -226,7 +509,7 @@ function generateExtraClickMethodContent(spec: PomExtraClickMethodSpec): string
       : JSON.stringify(spec.selector.formattedDataTestId);
 
     if (needsTemplate) {
-      lines.push(`        const testId = ${testIdExpr};`);
+      // handled below
     }
 
     const clickArgs: string[] = [];
@@ -239,10 +522,22 @@ function generateExtraClickMethodContent(spec: PomExtraClickMethodSpec): string
       clickArgs.push(waitArg);
     }
 
-    lines.push(`        await this.clickByTestId(${clickArgs.join(", ")});`);
-    lines.push("    }");
-
-    return `${lines.join("\n")}\n`;
+    return [
+      createClassMethod({
+        name: spec.name,
+        isAsync: true,
+        parameters,
+        statements: (writer) => {
+          if (spec.keyLiteral !== undefined) {
+            writer.writeLine(`const key = ${JSON.stringify(spec.keyLiteral)};`);
+          }
+          if (needsTemplate) {
+            writer.writeLine(`const testId = ${testIdExpr};`);
+          }
+          writer.writeLine(`await this.clickByTestId(${clickArgs.join(", ")});`);
+        },
+      }),
+    ];
   }
 
   const rootNeedsTemplate = spec.selector.rootFormattedDataTestId.includes("${");
@@ -254,26 +549,35 @@ function generateExtraClickMethodContent(spec: PomExtraClickMethodSpec): string
     ? `\`${spec.selector.formattedLabel}\``
     : JSON.stringify(spec.selector.formattedLabel);
 
-  if (rootNeedsTemplate) {
-    lines.push(`        const rootTestId = ${rootExpr};`);
-  }
-  if (labelNeedsTemplate) {
-    lines.push(`        const label = ${labelExpr};`);
-  }
   const rootArg = rootNeedsTemplate ? "rootTestId" : rootExpr;
   const labelArg = labelNeedsTemplate ? "label" : labelExpr;
-  lines.push(`        await this.clickWithinTestIdByLabel(${rootArg}, ${labelArg}, ${annotationArg}, ${waitArg});`);
-  lines.push("    }");
-
-  return `${lines.join("\n")}\n`;
+  return [
+    createClassMethod({
+      name: spec.name,
+      isAsync: true,
+      parameters,
+      statements: (writer) => {
+        if (spec.keyLiteral !== undefined) {
+          writer.writeLine(`const key = ${JSON.stringify(spec.keyLiteral)};`);
+        }
+        if (rootNeedsTemplate) {
+          writer.writeLine(`const rootTestId = ${rootExpr};`);
+        }
+        if (labelNeedsTemplate) {
+          writer.writeLine(`const label = ${labelExpr};`);
+        }
+        writer.writeLine(`await this.clickWithinTestIdByLabel(${rootArg}, ${labelArg}, ${annotationArg}, ${waitArg});`);
+      },
+    }),
+  ];
 }
 
-function generateMethodContentFromPom(primary: PomPrimarySpec, targetPageObjectModelClass?: string): string {
+function generateMethodMembersFromPom(primary: PomPrimarySpec, targetPageObjectModelClass?: string): TypeScriptClassMember[] {
   if (primary.emitPrimary === false) {
-    return "";
+    return [];
   }
 
-  return generateViewObjectModelMethodContent(
+  return generateViewObjectModelMembers(
     targetPageObjectModelClass,
     primary.methodName,
     primary.nativeRole,
@@ -284,7 +588,7 @@ function generateMethodContentFromPom(primary: PomPrimarySpec, targetPageObjectM
   );
 }
 
-function generateMethodsContentForDependencies(dependencies: IComponentDependencies): string {
+function generateMethodsContentForDependencies(dependencies: IComponentDependencies): TypeScriptClassMember[] {
   const entries = Array.from(dependencies.dataTestIdSet ?? []);
   const primarySpecsAll = entries
     .map(e => ({ pom: e.pom, target: e.targetPageObjectModelClass }))
@@ -322,16 +626,16 @@ function generateMethodsContentForDependencies(dependencies: IComponentDependenc
     .slice()
     .sort((a, b) => a.name.localeCompare(b.name));
 
-  let content = "";
+  const members: TypeScriptClassMember[] = [];
   for (const { pom, target } of primarySpecs) {
-    content += generateMethodContentFromPom(pom, target);
+    members.push(...generateMethodMembersFromPom(pom, target));
   }
 
   for (const extra of extras) {
-    content += generateExtraClickMethodContent(extra);
+    members.push(...generateExtraClickMethodMembers(extra));
   }
 
-  return content;
+  return members;
 }
 
 export interface GenerateFilesOptions {
@@ -403,6 +707,14 @@ export interface GenerateFilesOptions {
   /** Which POM languages to emit. Defaults to ["ts"]. */
   emitLanguages?: Array<"ts" | "csharp">;
 
+  /**
+   * Controls how TypeScript Playwright page objects are emitted.
+   *
+   * - "aggregated" (default): emit a single `page-object-models.g.ts`
+   * - "split": emit one generated `.g.ts` file per class plus a stable `index.ts` barrel
+   */
+  typescriptOutputStructure?: TypeScriptOutputStructure;
+
   /** C# generation options. */
   csharp?: {
     namespace?: string;
@@ -423,11 +735,9 @@ export interface GenerateFilesOptions {
   routeMetaByComponent?: Record<string, RouteMeta>;
 }
 
-interface GenerateContentOptions {
+interface BaseGenerateContentOptions {
   /** 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?: CustomPomAttachment[];
 
@@ -436,7 +746,9 @@ interface GenerateContentOptions {
   customPomImportAliases?: Record<string, string>;
   customPomClassIdentifierMap?: Record<string, string>;
   customPomAvailableClassIdentifiers?: Set<string>;
+  customPomImportSpecifiersByClass?: Record<string, ResolvedCustomPomImportSpecifier>;
   customPomMethodSignaturesByClass?: Map<string, CustomPomMethodSignatureMap>;
+  generatedTsFilePathByComponent?: Map<string, string>;
 
   /** Attribute name to treat as the test id. Defaults to `data-testid`. */
   testIdAttribute?: string;
@@ -447,6 +759,12 @@ interface GenerateContentOptions {
   routeMetaByComponent?: Record<string, RouteMeta>;
 }
 
+type GenerateContentOptions
+  = BaseGenerateContentOptions & (
+    { outputStructure: "aggregated" }
+    | { outputStructure?: "split" }
+  );
+
 interface GeneratedFileOutput {
   filePath: string;
   content: string;
@@ -468,6 +786,7 @@ export async function generateFiles(
     customPomImportNameCollisionBehavior = "error",
     testIdAttribute,
     emitLanguages: emitLanguagesOverride,
+    typescriptOutputStructure = "aggregated",
     csharp,
     vueRouterFluentChaining,
     routerEntry,
@@ -498,17 +817,28 @@ export async function generateFiles(
   };
 
   if (emitLanguages.includes("ts")) {
-    const files = await generateAggregatedFiles(componentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
-      customPomAttachments,
-      projectRoot,
-      customPomDir,
-      customPomImportAliases,
-      customPomImportNameCollisionBehavior,
-      testIdAttribute,
-      generateFixtures,
-      routeMetaByComponent,
-      vueRouterFluentChaining,
-    });
+    const files = typescriptOutputStructure === "split"
+      ? await generateSplitTypeScriptFiles(componentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
+        customPomAttachments,
+        projectRoot,
+        customPomDir,
+        customPomImportAliases,
+        customPomImportNameCollisionBehavior,
+        testIdAttribute,
+        routeMetaByComponent,
+        vueRouterFluentChaining,
+      })
+      : await generateAggregatedFiles(componentHierarchyMap, vueFilesPathMap, basePageClassPath, outDir, {
+        customPomAttachments,
+        projectRoot,
+        customPomDir,
+        customPomImportAliases,
+        customPomImportNameCollisionBehavior,
+        testIdAttribute,
+        generateFixtures,
+        routeMetaByComponent,
+        vueRouterFluentChaining,
+      });
     for (const file of files) {
       writeGeneratedFile(file);
     }
@@ -541,6 +871,133 @@ export async function generateFiles(
   }
 }
 
+async function generateSplitTypeScriptFiles(
+  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"];
+    customPomImportNameCollisionBehavior?: GenerateFilesOptions["customPomImportNameCollisionBehavior"];
+    testIdAttribute?: GenerateFilesOptions["testIdAttribute"];
+    routeMetaByComponent?: Record<string, RouteMeta>;
+    vueRouterFluentChaining?: boolean;
+  } = {},
+): Promise<GeneratedFileOutput[]> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const entries = Array.from(componentHierarchyMap.entries())
+    .sort((a, b) => a[0].localeCompare(b[0]));
+
+  const base = ensureDir(outDir);
+  const generatedClassNames = new Set(entries.map(([name]) => name));
+  const referencedTargets = new Set<string>();
+  for (const [, deps] of entries) {
+    for (const dataTestId of deps.dataTestIdSet ?? []) {
+      if (dataTestId.targetPageObjectModelClass) {
+        referencedTargets.add(dataTestId.targetPageObjectModelClass);
+      }
+    }
+  }
+
+  const stubTargets = Array.from(referencedTargets)
+    .filter(target => !generatedClassNames.has(target))
+    .sort((a, b) => a.localeCompare(b));
+
+  const availableClassNames = new Set<string>([...generatedClassNames, ...stubTargets]);
+  const depsByClassName = new Map<string, IComponentDependencies>(entries);
+  const generatedTsFilePathByComponent = new Map<string, string>();
+  for (const className of availableClassNames) {
+    generatedTsFilePathByComponent.set(className, path.join(base, `${className}.g.ts`));
+  }
+
+  const customPomImportResolution = resolveCustomPomImportResolution(generatedClassNames, projectRoot, {
+    customPomDir: options.customPomDir,
+    customPomImportAliases: options.customPomImportAliases,
+    customPomImportNameCollisionBehavior: options.customPomImportNameCollisionBehavior,
+  });
+
+  const runtimeBasePagePath = path.join(base, "_pom-runtime", "class-generation", "BasePage.ts");
+  const files: GeneratedFileOutput[] = [];
+
+  for (const [name, deps] of entries) {
+    const filePath = generatedTsFilePathByComponent.get(name);
+    if (!filePath) {
+      continue;
+    }
+
+    const content = generateViewObjectModelContent(name, deps, componentHierarchyMap, vueFilesPathMap, runtimeBasePagePath, {
+      outputDir: path.dirname(filePath),
+      outputStructure: "split",
+      customPomAttachments: options.customPomAttachments ?? [],
+      projectRoot,
+      customPomDir: options.customPomDir,
+      customPomImportAliases: options.customPomImportAliases,
+      customPomClassIdentifierMap: customPomImportResolution.classIdentifierMap,
+      customPomAvailableClassIdentifiers: customPomImportResolution.availableClassIdentifiers,
+      customPomImportSpecifiersByClass: customPomImportResolution.importSpecifiersByClass,
+      customPomMethodSignaturesByClass: customPomImportResolution.methodSignaturesByClass,
+      generatedTsFilePathByComponent,
+      testIdAttribute: options.testIdAttribute,
+      vueRouterFluentChaining: options.vueRouterFluentChaining,
+      routeMetaByComponent: options.routeMetaByComponent,
+    });
+    files.push({ filePath, content });
+  }
+
+  for (const targetClassName of stubTargets) {
+    const filePath = generatedTsFilePathByComponent.get(targetClassName);
+    if (!filePath) {
+      continue;
+    }
+
+    const outputDir = path.dirname(filePath);
+    const basePageImportSpecifier = stripExtension(toPosixRelativePath(outputDir, runtimeBasePagePath));
+    const composed = getComposedStubBody(targetClassName, availableClassNames, depsByClassName, vueFilesPathMap, projectRoot);
+    const childImports = getChildImportSpecifiers(outputDir, composed?.childClassNames ?? [], generatedTsFilePathByComponent);
+    const members = composed?.members ?? getDefaultStubMembers();
+
+    const content = renderSplitStubPomContent({
+      className: targetClassName,
+      basePageImportSpecifier,
+      childImports,
+      members,
+    });
+
+    files.push({ filePath, content });
+  }
+
+  const runtimeAssetSpecs = getRuntimeGeneratedAssetSpecs(base, basePageClassPath);
+  const runtimeFiles = buildRuntimeGeneratedFilesFromSpecs(runtimeAssetSpecs);
+  const indexContent = renderSourceFile("index.ts", (sourceFile) => {
+    for (const spec of runtimeAssetSpecs) {
+      addExportAll(sourceFile, stripExtension(toPosixRelativePath(base, spec.outputPath)));
+    }
+    for (const [, filePath] of Array.from(generatedTsFilePathByComponent.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+      addExportAll(sourceFile, `./${stripExtension(path.basename(filePath))}`);
+    }
+  }, {
+    prefixText: buildFilePrefix({
+      eslintDisableSortImports: true,
+      commentLines: [
+        "POM exports",
+        "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.",
+      ],
+    }),
+  });
+
+  return [
+    ...files,
+    { filePath: path.join(base, "index.ts"), content: indexContent },
+    ...runtimeFiles,
+  ];
+}
+
 function escapeGitAttributesPattern(value: string): string {
   let output = "";
   for (let i = 0; i < value.length; i++) {
@@ -1123,88 +1580,191 @@ function maybeGenerateFixtureRegistry(
     })
     .filter((entry): entry is { className: string; localIdentifier: string; importSpecifier: string } => !!entry);
   const overrideCtorByClassName = new Map(overrideCtorEntries.map(entry => [entry.className, entry.localIdentifier]));
-  const overrideImports = overrideCtorEntries.length
-    ? `${overrideCtorEntries
-        .map(entry => `import { ${entry.className} as ${entry.localIdentifier} } from "${entry.importSpecifier}";`)
-        .join("\n")}\n\n`
-    : "";
 
   const fixtureCtorExpression = (name: string) => overrideCtorByClassName.get(name) ?? `Pom.${name}`;
+  const pageCtorEntries = viewClassNames.map(name => ({
+    fixtureName: lowerFirst(name),
+    ctorExpression: fixtureCtorExpression(name),
+  }));
+  const componentCtorEntries = componentClassNames.map(name => ({
+    fixtureName: lowerFirst(name),
+    ctorExpression: fixtureCtorExpression(name),
+  }));
+
+  const fixturesContent = renderSourceFile(fixtureFileName, (sourceFile) => {
+    sourceFile.addStatements("/** Generated Playwright fixtures (typed page objects). */");
+
+    addNamedImport(sourceFile, {
+      moduleSpecifier: "@playwright/test",
+      namedImports: [
+        "expect",
+        { name: "test", alias: "base" },
+      ],
+    });
+    addNamedImport(sourceFile, {
+      moduleSpecifier: "@playwright/test",
+      isTypeOnly: true,
+      namedImports: [{ name: "Page", alias: "PwPage" }],
+    });
+    sourceFile.addImportDeclaration({
+      namespaceImport: "Pom",
+      moduleSpecifier: pomImport,
+    });
+    for (const entry of overrideCtorEntries) {
+      addNamedImport(sourceFile, {
+        moduleSpecifier: entry.importSpecifier,
+        namedImports: [{ name: entry.className, alias: entry.localIdentifier }],
+      });
+    }
 
-  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)}: ${fixtureCtorExpression(name)},`)
-    .join("\n");
+    sourceFile.addInterface({
+      isExported: true,
+      name: "PlaywrightOptions",
+      properties: [{
+        name: "animation",
+        type: "Pom.PlaywrightAnimationOptions",
+      }],
+    });
+    sourceFile.addTypeAlias({
+      isExported: true,
+      name: "PomConstructor",
+      typeParameters: [{ name: "T" }],
+      type: "new (page: PwPage) => T",
+    });
+    sourceFile.addInterface({
+      isExported: true,
+      name: "PomFactory",
+      methods: [{
+        name: "create",
+        typeParameters: [{ name: "T" }],
+        parameters: [{ name: "ctor", type: "PomConstructor<T>" }],
+        returnType: "T",
+      }],
+    });
+    sourceFile.addTypeAlias({
+      name: "PomSetupFixture",
+      type: "{ pomSetup: void }",
+    });
+    sourceFile.addTypeAlias({
+      name: "PomFactoryFixture",
+      type: "{ pomFactory: PomFactory }",
+    });
 
-  const componentFixturesTypeEntries = componentClassNames
-    .map(name => `  ${lowerFirst(name)}: ${fixtureCtorExpression(name)},`)
-    .join("\n");
+    sourceFile.addVariableStatement({
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [{
+        name: "pageCtors",
+        initializer: (writer) => {
+          writer.write("{").newLine();
+          writer.indent(() => {
+            for (const entry of pageCtorEntries) {
+              writer.writeLine(`${entry.fixtureName}: ${entry.ctorExpression},`);
+            }
+          });
+          writer.write("} as const");
+        },
+      }],
+    });
+    sourceFile.addVariableStatement({
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [{
+        name: "componentCtors",
+        initializer: (writer) => {
+          writer.write("{").newLine();
+          writer.indent(() => {
+            for (const entry of componentCtorEntries) {
+              writer.writeLine(`${entry.fixtureName}: ${entry.ctorExpression},`);
+            }
+          });
+          writer.write("} as const");
+        },
+      }],
+    });
+
+    sourceFile.addTypeAlias({
+      isExported: true,
+      name: "GeneratedPageFixtures",
+      type: "{ [K in keyof typeof pageCtors]: InstanceType<(typeof pageCtors)[K]> }",
+    });
+    sourceFile.addTypeAlias({
+      isExported: true,
+      name: "GeneratedComponentFixtures",
+      type: "{ [K in keyof typeof componentCtors]: InstanceType<(typeof componentCtors)[K]> }",
+    });
+
+    sourceFile.addFunction({
+      name: "makePomFixture",
+      typeParameters: [{ name: "T" }],
+      parameters: [{ name: "Ctor", type: "PomConstructor<T>" }],
+      statements: [
+        "return async ({ page }: { page: PwPage }, use: (t: T) => Promise<void>) => {",
+        "    await use(new Ctor(page));",
+        "};",
+      ],
+    });
+    sourceFile.addFunction({
+      name: "createPomFixtures",
+      typeParameters: [{ name: "TMap", constraint: "Record<string, PomConstructor<any>>" }],
+      parameters: [{ name: "ctors", type: "TMap" }],
+      statements: [
+        "const out: Record<string, any> = {};",
+        "for (const [key, Ctor] of Object.entries(ctors)) {",
+        "    out[key] = makePomFixture(Ctor as PomConstructor<any>);",
+        "}",
+        "return out as any;",
+      ],
+    });
 
-  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`
-  + `${overrideImports}`
-  + `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`;
+    sourceFile.addVariableStatement({
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [{
+        name: "test",
+        initializer: (writer) => {
+          writer.write("base.extend<PlaywrightOptions & PomSetupFixture & PomFactoryFixture & GeneratedPageFixtures & GeneratedComponentFixtures>(");
+          writer.block(() => {
+            writer.writeLine("animation: [{");
+            writer.indent(() => {
+              writer.writeLine('pointer: { durationMilliseconds: 250, transitionStyle: "ease-in-out", clickDelayMilliseconds: 0 },');
+              writer.writeLine("keyboard: { typeDelayMilliseconds: 100 },");
+            });
+            writer.writeLine("}, { option: true }],");
+            writer.writeLine("pomSetup: [async ({ animation }, use) => {");
+            writer.indent(() => {
+              writer.writeLine("Pom.setPlaywrightAnimationOptions(animation);");
+              writer.writeLine("await use();");
+            });
+            writer.writeLine("}, { auto: true }],");
+            writer.writeLine("pomFactory: async ({ page }, use) => {");
+            writer.indent(() => {
+              writer.writeLine("await use({");
+              writer.indent(() => {
+                writer.writeLine("create: <T>(ctor: PomConstructor<T>) => new ctor(page),");
+              });
+              writer.writeLine("});");
+            });
+            writer.writeLine("},");
+            writer.writeLine("...createPomFixtures(pageCtors),");
+            writer.writeLine("...createPomFixtures(componentCtors),");
+          });
+          writer.write(")");
+        },
+      }],
+    });
+
+    sourceFile.addExportDeclaration({
+      namedExports: ["test", "expect"],
+    });
+  }, {
+    prefixText: buildFilePrefix({
+      eslintDisableSortImports: true,
+      commentLines: [
+        "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.",
+      ],
+    }),
+  });
 
   return {
     filePath: path.resolve(fixtureOutDirAbs, fixtureFileName),
@@ -1214,19 +1774,14 @@ function maybeGenerateFixtureRegistry(
   // No pomFixture is generated; goToSelf is emitted directly on each view POM.
 }
 
-function generateViewObjectModelContent(
+function prepareViewObjectModelClass(
   componentName: string,
   dependencies: IComponentDependencies,
   componentHierarchyMap: Map<string, IComponentDependencies>,
-  vueFilesPathMap: Map<string, string>,
-  basePageClassPath: string,
   options: GenerateContentOptions = {},
 ) {
-  const { isView, childrenComponentSet, usedComponentSet, filePath } = dependencies;
-
+  const { isView, childrenComponentSet, usedComponentSet } = dependencies;
   const {
-    outputDir = path.dirname(filePath),
-    aggregated = false,
     customPomAttachments = [],
     testIdAttribute,
   } = options;
@@ -1271,66 +1826,15 @@ function generateViewObjectModelContent(
         : new Map<string, CustomPomMethodSignature>(),
     }));
 
-  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;
-  }
-
-  // Convert raw component name (may contain hyphens/dots, e.g. "error-test", "FirmsGrid.client")
-  // to a valid PascalCase TypeScript identifier for the class declaration.
-  const className = toPascalCaseLocal(componentName);
-  content += `\nexport class ${className} extends BasePage {\n`;
-
   const widgetInstances = isView
     ? getWidgetInstancesForView(componentName, dependencies.dataTestIdSet, customPomAvailableClassIdentifiers)
     : [];
 
-  // 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;
+
+  const className = toPascalCaseLocal(componentName);
   const childInstancePropertyNames = Array.from(componentRefsForInstances)
     .filter(child => componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size)
     .map(child => child.split(".vue")[0]);
@@ -1345,63 +1849,194 @@ function generateViewObjectModelContent(
     ...childInstancePropertyNames,
   ]);
 
-  // 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`).
+  const members: TypeScriptClassMember[] = [];
   if (isView && (componentRefsForInstances.size > 0 || attachmentsForThisClass.length > 0 || widgetInstances.length > 0)) {
-    content += getComponentInstances(componentRefsForInstances, componentHierarchyMap, attachmentsForThisClass, widgetInstances);
-    content += getConstructor(componentRefsForInstances, componentHierarchyMap, attachmentsForThisClass, widgetInstances, { testIdAttribute });
+    members.push(...getComponentInstances(componentRefsForInstances, componentHierarchyMap, attachmentsForThisClass, widgetInstances));
+    members.push(getConstructor(componentRefsForInstances, componentHierarchyMap, attachmentsForThisClass, widgetInstances, { testIdAttribute }));
   }
   if (!isView && attachmentsForThisClass.length > 0) {
-    content += getComponentInstances(new Set(), componentHierarchyMap, attachmentsForThisClass);
-    content += getConstructor(new Set(), componentHierarchyMap, attachmentsForThisClass, [], { testIdAttribute });
-  }
-  content += getAttachmentPassthroughMethods(componentName, dependencies, attachmentsForThisClass, reservedAttachmentPassthroughNames);
-
-  // 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.
+    members.push(...getComponentInstances(new Set(), componentHierarchyMap, attachmentsForThisClass));
+    members.push(getConstructor(new Set(), componentHierarchyMap, attachmentsForThisClass, [], { testIdAttribute }));
+  }
+
+  members.push(
+    ...getAttachmentPassthroughMethods(componentName, dependencies, attachmentsForThisClass, reservedAttachmentPassthroughNames),
+  );
+
   if (isView && componentRefsForInstances.size === 1) {
-    content += getViewPassthroughMethods(componentName, dependencies, componentRefsForInstances, componentHierarchyMap, blockedViewPassthroughMethodNames);
+    members.push(
+      ...getViewPassthroughMethods(
+        componentName,
+        dependencies,
+        componentRefsForInstances,
+        componentHierarchyMap,
+        blockedViewPassthroughMethodNames,
+      ),
+    );
   }
 
   if (isView && options.vueRouterFluentChaining) {
     const routeMeta = options.routeMetaByComponent?.[componentName] ?? null;
-    content += generateRouteProperty(routeMeta);
-    // Pass className (PascalCase) so the generated route self-reference is a valid identifier.
-    content += generateGoToSelfMethod(className);
+    members.push(...generateRouteProperty(routeMeta));
+    members.push(...generateGoToSelfMethod(className));
   }
 
-  content += generateMethodsContentForDependencies(dependencies);
+  members.push(...generateMethodsContentForDependencies(dependencies));
 
-  content += "}\n";
-  return content;
+  return {
+    className,
+    componentRefsForInstances,
+    attachmentsForThisClass,
+    widgetInstances,
+    isView,
+    members,
+  };
 }
 
-function getViewPassthroughMethods(
-  viewName: string,
-  viewDependencies: IComponentDependencies,
-  childrenComponentSet: Set<string>,
+function generateViewObjectModelContent(
+  componentName: string,
+  dependencies: IComponentDependencies,
   componentHierarchyMap: Map<string, IComponentDependencies>,
-  blockedMethodNames: Set<string> = new Set(),
+  _vueFilesPathMap: Map<string, string>,
+  basePageClassPath: string,
+  options: GenerateContentOptions = {},
 ) {
-  const existingOnView = viewDependencies.generatedMethods ?? new Map<string, { params: string; argNames: string[] } | null>();
+  const { filePath } = dependencies;
+  const outputDir = options.outputDir ?? path.dirname(filePath);
+  const prepared = prepareViewObjectModelClass(componentName, dependencies, componentHierarchyMap, options);
+  const sourceRel = toPosixRelativePath(outputDir, filePath);
+  const kind = prepared.isView ? "Page" : "Component";
+  const doc = `/** ${kind} POM: ${componentName} (source: ${sourceRel}) */`;
+  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, "/");
+  const basePageImportNoExt = stripExtension(basePageImport).replace(/\\/g, "/");
+  const basePageImportSpecifier = basePageImportNoExt.startsWith(".") ? basePageImportNoExt : `./${basePageImportNoExt}`;
+  const needsPlaywrightPageImport = prepared.isView || prepared.attachmentsForThisClass.length > 0;
+  const customPomImportSpecifiersByClass = options.customPomImportSpecifiersByClass ?? {};
+
+  const customImports = Array.from(
+    new Set([
+      ...prepared.attachmentsForThisClass.map(attachment => attachment.className),
+      ...prepared.widgetInstances.map(widget => widget.className),
+    ]),
+  )
+    .reduce<Array<{ moduleSpecifier: string; name: string; alias?: string }>>((imports, localIdentifier) => {
+      const specifier = Object.values(customPomImportSpecifiersByClass)
+        .find(spec => spec.localIdentifier === localIdentifier);
+      if (!specifier) {
+        return imports;
+      }
 
-  // methodName -> candidates
-  const methodToChildren = new Map<string, Array<{ childProp: string; params: string; argNames: string[] }>>();
+      imports.push({
+        moduleSpecifier: stripExtension(toPosixRelativePath(fromAbs, specifier.absolutePath)),
+        name: specifier.exportName,
+        alias: specifier.localIdentifier !== specifier.exportName ? specifier.localIdentifier : undefined,
+      });
+      return imports;
+    }, [])
+    .sort((a, b) => (a.alias ?? a.name).localeCompare(b.alias ?? b.name));
 
-  for (const child of childrenComponentSet) {
-    const childDeps = componentHierarchyMap.get(child);
+  const generatedImports: Array<{ className: string; moduleSpecifier: string }> = [];
+  const importedGeneratedClasses = new Set<string>();
+  const generatedTsFilePathByComponent = options.generatedTsFilePathByComponent;
+
+  const addGeneratedImport = (className: string) => {
+    if (!generatedTsFilePathByComponent || importedGeneratedClasses.has(className) || className === componentName) {
+      return;
+    }
+    const generatedFilePath = generatedTsFilePathByComponent.get(className);
+    if (!generatedFilePath) {
+      return;
+    }
+
+    generatedImports.push({
+      className,
+      moduleSpecifier: stripExtension(toPosixRelativePath(fromAbs, generatedFilePath)),
+    });
+    importedGeneratedClasses.add(className);
+  };
+
+  for (const child of prepared.componentRefsForInstances) {
+    const childName = child.endsWith(".vue") ? child.slice(0, -4) : child;
+    const childDeps = componentHierarchyMap.get(child) ?? componentHierarchyMap.get(childName);
+    if (childDeps?.dataTestIdSet.size) {
+      addGeneratedImport(childName);
+    }
+  }
+
+  const targetClassNames = Array.from(
+    new Set(
+      Array.from(dependencies.dataTestIdSet ?? [])
+        .map(entry => entry.targetPageObjectModelClass)
+        .filter((target): target is string => typeof target === "string" && target.length > 0),
+    ),
+  ).sort((a, b) => a.localeCompare(b));
+
+  for (const targetClassName of targetClassNames) {
+    addGeneratedImport(targetClassName);
+  }
+
+  generatedImports.sort((a, b) => a.className.localeCompare(b.className));
+
+  const prefixText = `${buildFilePrefix({ eslintDisableSortImports: true })}${doc}\n`;
+  return renderSourceFile(`${prepared.className}.ts`, (sourceFile) => {
+    if (needsPlaywrightPageImport) {
+      addNamedImport(sourceFile, {
+        moduleSpecifier: "@playwright/test",
+        isTypeOnly: true,
+        namedImports: [{ name: "Page", alias: "PwPage" }],
+      });
+    }
+
+    addNamedImport(sourceFile, {
+      moduleSpecifier: basePageImportSpecifier,
+      namedImports: ["BasePage", "Fluent"],
+    });
+
+    for (const customImport of customImports) {
+      addNamedImport(sourceFile, {
+        moduleSpecifier: customImport.moduleSpecifier,
+        namedImports: [{ name: customImport.name, alias: customImport.alias }],
+      });
+    }
+
+    for (const generatedImport of generatedImports) {
+      addNamedImport(sourceFile, {
+        moduleSpecifier: generatedImport.moduleSpecifier,
+        namedImports: [generatedImport.className],
+      });
+    }
+
+    const classDeclaration = sourceFile.addClass({
+      name: prepared.className,
+      isExported: true,
+      extends: "BasePage",
+    });
+
+    for (const member of prepared.members) {
+      addClassMember(classDeclaration, member);
+    }
+  }, { prefixText });
+}
+
+function getViewPassthroughMethods(
+  viewName: string,
+  viewDependencies: IComponentDependencies,
+  childrenComponentSet: Set<string>,
+  componentHierarchyMap: Map<string, IComponentDependencies>,
+  blockedMethodNames: Set<string> = new Set(),
+) {
+  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;
 
@@ -1427,34 +2062,23 @@ function getViewPassthroughMethods(
   }
 
   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 passthroughs = sorted.filter(([, candidates]) => candidates.length === 1);
+  if (!passthroughs.length) {
+    return [];
+  }
 
+  return passthroughs.map(([methodName, candidates]) => {
     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");
+    return createClassMethod({
+      name: methodName,
+      isAsync: true,
+      parameters: parseParameterSignatures(params),
+      statements: [
+        `return await this.${childProp}.${methodName}(${callArgs});`,
+      ],
+    });
+  });
 }
 
 function getAttachmentPassthroughMethods(
@@ -1464,7 +2088,7 @@ function getAttachmentPassthroughMethods(
   reservedMemberNames: Set<string>,
 ) {
   if (!attachmentsForThisClass.some(a => a.flatten && a.methodSignatures.size > 0)) {
-    return "";
+    return [];
   }
 
   const existingOnClass = ownerDependencies.generatedMethods ?? new Map<string, { params: string; argNames: string[] } | null>();
@@ -1491,37 +2115,25 @@ function getAttachmentPassthroughMethods(
   }
 
   const sorted = Array.from(methodToAttachments.entries()).sort((a, b) => a[0].localeCompare(b[0]));
-  const lines: string[] = [];
-
-  for (const [methodName, candidates] of sorted) {
-    if (candidates.length !== 1) {
-      continue;
-    }
+  const passthroughs = sorted.filter(([, candidates]) => candidates.length === 1);
+  if (!passthroughs.length) {
+    return [];
+  }
 
+  return passthroughs.map(([methodName, candidates]) => {
     const { propertyName, params, argNames } = candidates[0];
     const callArgs = argNames.join(", ");
     const invocation = callArgs
       ? `this.${propertyName}.${methodName}(${callArgs})`
       : `this.${propertyName}.${methodName}()`;
-
-    lines.push(
-      "",
-      `    ${methodName}(${params}) {`,
-      `        return ${invocation};`,
-      "    }",
-    );
-  }
-
-  if (!lines.length) {
-    return "";
-  }
-
-  return [
-    "",
-    `    // Passthrough methods composed from custom helper attachments of ${ownerName}.`,
-    ...lines,
-    "",
-  ].join("\n");
+    return createClassMethod({
+      name: methodName,
+      parameters: parseParameterSignatures(params),
+      statements: [
+        `return ${invocation};`,
+      ],
+    });
+  });
 }
 
 function sliceNodeSource(source: string, node: { start?: number | null; end?: number | null }): string | null {
@@ -1628,6 +2240,373 @@ function ensureDir(dir: string) {
   return normalized;
 }
 
+function resolvePluginAsset(relative: string): string {
+  try {
+    return fileURLToPath(new URL(relative, import.meta.url));
+  }
+  catch {
+    return path.resolve(__dirname, relative);
+  }
+}
+
+function readTextAsset(absPath: string, description: string): string {
+  try {
+    return fs.readFileSync(absPath, "utf8");
+  }
+  catch {
+    throw new VuePomGeneratorError(`Failed to read ${description} at ${absPath}`);
+  }
+}
+
+function getDefaultStubMembers(): TypeScriptClassMember[] {
+  return [
+    createClassConstructor({
+      parameters: [{ name: "page", type: "PwPage" }],
+      statements: [
+        "super(page);",
+      ],
+    }),
+  ];
+}
+
+function renderSplitStubPomContent(options: {
+  className: string;
+  basePageImportSpecifier: string;
+  childImports: Array<{ className: string; importPath: string }>;
+  members: TypeScriptClassMember[];
+}): string {
+  const prefixText = buildFilePrefix({
+    eslintDisableSortImports: true,
+    commentLines: [
+      `Stub POM: ${options.className}`,
+      "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.",
+    ],
+  });
+
+  return renderSourceFile(`${options.className}.ts`, (sourceFile) => {
+    addNamedImport(sourceFile, {
+      moduleSpecifier: "@playwright/test",
+      isTypeOnly: true,
+      namedImports: [{ name: "Page", alias: "PwPage" }],
+    });
+    addNamedImport(sourceFile, {
+      moduleSpecifier: options.basePageImportSpecifier,
+      namedImports: ["BasePage"],
+    });
+    for (const childImport of options.childImports) {
+      addNamedImport(sourceFile, {
+        moduleSpecifier: childImport.importPath,
+        namedImports: [childImport.className],
+      });
+    }
+    sourceFile.addStatements(buildCommentBlock([
+      "Stub POM generated because it is referenced as a navigation target but",
+      "did not have any generated test ids in this build.",
+    ]).trimEnd());
+    const classDeclaration = sourceFile.addClass({
+      name: options.className,
+      isExported: true,
+      extends: "BasePage",
+    });
+    for (const member of options.members) {
+      addClassMember(classDeclaration, member);
+    }
+  }, { prefixText });
+}
+
+function getChildImportSpecifiers(
+  outputDir: string,
+  childClassNames: string[],
+  generatedTsFilePathByComponent: Map<string, string>,
+): Array<{ className: string; importPath: string }> {
+  return childClassNames
+    .map((childClassName) => {
+      const childFilePath = generatedTsFilePathByComponent.get(childClassName);
+      if (!childFilePath) {
+        return null;
+      }
+      return {
+        className: childClassName,
+        importPath: stripExtension(toPosixRelativePath(outputDir, childFilePath)),
+      };
+    })
+    .filter((entry): entry is { className: string; importPath: string } => !!entry)
+    .sort((a, b) => a.className.localeCompare(b.className));
+}
+
+function isConstructorMember(member: TypeScriptClassMember): member is OptionalKind<ConstructorDeclarationStructure> {
+  return member.kind === StructureKind.Constructor;
+}
+
+function isGetterMember(member: TypeScriptClassMember): member is OptionalKind<GetAccessorDeclarationStructure> {
+  return member.kind === StructureKind.GetAccessor;
+}
+
+function isMethodMember(member: TypeScriptClassMember): member is OptionalKind<MethodDeclarationStructure> {
+  return member.kind === StructureKind.Method;
+}
+
+function isPropertyMember(member: TypeScriptClassMember): member is OptionalKind<PropertyDeclarationStructure> {
+  return member.kind === StructureKind.Property;
+}
+
+function addClassMember(classDeclaration: ReturnType<TypeScriptSourceFile["addClass"]>, member: TypeScriptClassMember): void {
+  if (isConstructorMember(member)) {
+    classDeclaration.addConstructor(member);
+    return;
+  }
+  if (isGetterMember(member)) {
+    classDeclaration.addGetAccessor(member);
+    return;
+  }
+  if (isMethodMember(member)) {
+    classDeclaration.addMethod(member);
+    return;
+  }
+  if (isPropertyMember(member)) {
+    classDeclaration.addProperty(member);
+    return;
+  }
+  throw new Error(`Unsupported class member structure: ${String(member)}`);
+}
+
+interface RuntimeGeneratedAssetSpec {
+  absolutePath: string;
+  description: string;
+  outputPath: string;
+}
+
+function getRuntimeGeneratedAssetSpecs(baseDir: string, basePageClassPath: string): RuntimeGeneratedAssetSpec[] {
+  const runtimeDirAbs = path.join(baseDir, "_pom-runtime");
+  const runtimeClassGenAbs = path.join(runtimeDirAbs, "class-generation");
+  const runtimeClassGenSourceDir = resolvePluginAsset("../class-generation");
+  const runtimeClassGenFiles = fs.readdirSync(runtimeClassGenSourceDir)
+    .filter(file => file.endsWith(".ts"))
+    .filter(file => file !== "BasePage.ts" && file !== "index.ts")
+    .sort((left, right) => left.localeCompare(right));
+
+  return [
+    {
+      absolutePath: resolvePluginAsset("../click-instrumentation.ts"),
+      description: "click-instrumentation.ts",
+      outputPath: path.join(runtimeDirAbs, "click-instrumentation.ts"),
+    },
+    ...runtimeClassGenFiles.map(file => ({
+      absolutePath: path.join(runtimeClassGenSourceDir, file),
+      description: file,
+      outputPath: path.join(runtimeClassGenAbs, file),
+    })),
+    {
+      absolutePath: basePageClassPath,
+      description: "BasePage.ts",
+      outputPath: path.join(runtimeClassGenAbs, "BasePage.ts"),
+    },
+  ];
+}
+
+function buildRuntimeGeneratedFiles(baseDir: string, basePageClassPath: string): GeneratedFileOutput[] {
+  return buildRuntimeGeneratedFilesFromSpecs(getRuntimeGeneratedAssetSpecs(baseDir, basePageClassPath));
+}
+
+function buildRuntimeGeneratedFilesFromSpecs(assetSpecs: RuntimeGeneratedAssetSpec[]): GeneratedFileOutput[] {
+  return assetSpecs.map(spec => ({
+    filePath: spec.outputPath,
+    content: readTextAsset(spec.absolutePath, spec.description),
+  }));
+}
+
+function buildRuntimeGeneratedBarrelExports(outputDir: string, assetSpecs: RuntimeGeneratedAssetSpec[]): string[] {
+  return assetSpecs.map(spec => `export * from "${stripExtension(toPosixRelativePath(outputDir, spec.outputPath))}";`);
+}
+
+function resolveCustomPomImportResolution(
+  generatedClassNames: Set<string>,
+  projectRoot: string,
+  options: {
+    customPomDir?: GenerateFilesOptions["customPomDir"];
+    customPomImportAliases?: GenerateFilesOptions["customPomImportAliases"];
+    customPomImportNameCollisionBehavior?: GenerateFilesOptions["customPomImportNameCollisionBehavior"];
+  } = {},
+): CustomPomImportResolution {
+  const importAliases: Record<string, string> = {
+    Toggle: "ToggleWidget",
+    Checkbox: "CheckboxWidget",
+    ...(options.customPomImportAliases),
+  };
+  const importCollisionBehavior = options.customPomImportNameCollisionBehavior ?? "error";
+
+  const reservedIdentifiers = new Set<string>([
+    "PwLocator",
+    "PwPage",
+    "BasePage",
+    "Fluent",
+    ...generatedClassNames,
+  ]);
+  const usedImportIdentifiers = new Set<string>();
+  const classIdentifierMap: Record<string, string> = {};
+  const methodSignaturesByClass = new Map<string, CustomPomMethodSignatureMap>();
+  const importSpecifiersByClass: Record<string, ResolvedCustomPomImportSpecifier> = {};
+
+  const ensureUniqueIdentifier = (base: string) => {
+    let candidate = base;
+    let i = 2;
+    while (reservedIdentifiers.has(candidate) || usedImportIdentifiers.has(candidate)) {
+      candidate = `${base}${i}`;
+      i++;
+    }
+    usedImportIdentifiers.add(candidate);
+    return candidate;
+  };
+
+  const customDirRelOrAbs = options.customPomDir ?? "tests/playwright/pom/custom";
+  const customDirAbs = path.isAbsolute(customDirRelOrAbs)
+    ? customDirRelOrAbs
+    : path.resolve(projectRoot, customDirRelOrAbs);
+
+  if (!fs.existsSync(customDirAbs)) {
+    return {
+      classIdentifierMap,
+      methodSignaturesByClass,
+      availableClassIdentifiers: new Set<string>(),
+      importSpecifiersByClass,
+    };
+  }
+
+  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, "");
+    const requested = importAliases[exportName] ?? exportName;
+    const collidesWithGeneratedClass = generatedClassNames.has(requested);
+    const explicitAliasProvided = Object.prototype.hasOwnProperty.call(importAliases, exportName);
+
+    if (collidesWithGeneratedClass && importCollisionBehavior === "error") {
+      throw createCustomPomImportCollisionError(exportName, requested);
+    }
+
+    let localIdentifier = requested;
+    if (collidesWithGeneratedClass && importCollisionBehavior === "alias") {
+      const aliasBase = explicitAliasProvided ? requested : `${exportName}Custom`;
+      localIdentifier = ensureUniqueIdentifier(aliasBase);
+    }
+    else {
+      localIdentifier = ensureUniqueIdentifier(requested);
+    }
+
+    const customFileAbs = path.join(customDirAbs, file);
+    classIdentifierMap[exportName] = localIdentifier;
+    importSpecifiersByClass[exportName] = {
+      exportName,
+      localIdentifier,
+      absolutePath: customFileAbs,
+    };
+
+    const customPomMethodSignatures = extractCustomPomMethodSignatures(fs.readFileSync(customFileAbs, "utf8"), exportName);
+    if (customPomMethodSignatures.size > 0) {
+      methodSignaturesByClass.set(exportName, customPomMethodSignatures);
+    }
+  }
+
+  return {
+    classIdentifierMap,
+    methodSignaturesByClass,
+    availableClassIdentifiers: new Set(Object.values(classIdentifierMap)),
+    importSpecifiersByClass,
+  };
+}
+
+function getComposedStubBody(
+  targetClassName: string,
+  availableClassNames: Set<string>,
+  depsByClassName: Map<string, IComponentDependencies>,
+  vueFilesPathMap: Map<string, string>,
+  projectRoot: string,
+) {
+  const filePath = resolveVueSourcePath(targetClassName, vueFilesPathMap, projectRoot);
+  if (!filePath)
+    return undefined;
+
+  let source = "";
+  try {
+    source = fs.readFileSync(filePath, "utf8");
+  }
+  catch {
+    return undefined;
+  }
+
+  const tags = getComponentClassNamesFromVueSource(source);
+  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;
+
+  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;
+      const list = methodToChildren.get(name) ?? [];
+      list.push({ child, params: sig.params, argNames: sig.argNames });
+      methodToChildren.set(name, list);
+    }
+  }
+
+  const passthroughMembers: TypeScriptClassMember[] = [];
+  for (const [methodName, candidatesForMethod] of methodToChildren.entries()) {
+    if (candidatesForMethod.length !== 1 || methodName === "constructor")
+      continue;
+
+    const { child, params, argNames } = candidatesForMethod[0];
+    const callArgs = argNames.join(", ");
+
+    passthroughMembers.push(createClassMethod({
+      name: methodName,
+      isAsync: true,
+      parameters: parseParameterSignatures(params),
+      statements: [
+        `return await this.${child}.${methodName}(${callArgs});`,
+      ],
+    }));
+  }
+
+  return {
+    childClassNames,
+    members: [
+      ...childClassNames.map(childClassName =>
+        createClassProperty({
+          name: childClassName,
+          type: childClassName,
+        })),
+      createClassConstructor({
+        parameters: [{ name: "page", type: "PwPage" }],
+        statements: (writer) => {
+          writer.writeLine("super(page);");
+          for (const childClassName of childClassNames) {
+            writer.writeLine(`this.${childClassName} = new ${childClassName}(page);`);
+          }
+        },
+      }),
+      ...passthroughMembers,
+    ],
+  };
+}
+
 async function generateAggregatedFiles(
   componentHierarchyMap: Map<string, IComponentDependencies>,
   vueFilesPathMap: Map<string, string>,
@@ -1653,7 +2632,6 @@ async function generateAggregatedFiles(
   const components = entries.filter(([, d]) => !d.isView);
 
   const makeAggregatedContent = (
-    header: string,
     outputDir: string,
     items: Array<[string, IComponentDependencies]>,
   ) => {
@@ -1680,111 +2658,23 @@ async function generateAggregatedFiles(
     imports.push(`export * from "${runtimeClassGenRel}/Pointer";`);
     imports.push(`export * from "${runtimeClassGenRel}/BasePage";`);
 
-    // 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 importCollisionBehavior = options.customPomImportNameCollisionBehavior ?? "error";
-
-      const reservedIdentifiers = new Set<string>([
-        "PwLocator",
-        "PwPage",
-        "BasePage",
-        "Fluent",
-        ...generatedClassNames,
-      ]);
-      const usedImportIdentifiers = new Set<string>();
-      const customPomClassIdentifierMap: Record<string, string> = {};
-      const customPomMethodSignaturesByClass = new Map<string, CustomPomMethodSignatureMap>();
-
-      const ensureUniqueIdentifier = (base: string) => {
-        let candidate = base;
-        let i = 2;
-        while (reservedIdentifiers.has(candidate) || usedImportIdentifiers.has(candidate)) {
-          candidate = `${base}${i}`;
-          i++;
-        }
-        usedImportIdentifiers.add(candidate);
-        return candidate;
-      };
-
-      const customDirRelOrAbs = options.customPomDir ?? "tests/playwright/pom/custom";
-      const customDirAbs = path.isAbsolute(customDirRelOrAbs)
-        ? customDirRelOrAbs
-        : path.resolve(projectRoot, customDirRelOrAbs);
-
-      if (!fs.existsSync(customDirAbs)) {
-        return {
-          classIdentifierMap: customPomClassIdentifierMap,
-          methodSignaturesByClass: customPomMethodSignaturesByClass,
-        };
-      }
-
-      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 requested = importAliases[exportName] ?? exportName;
-        const collidesWithGeneratedClass = generatedClassNames.has(requested);
-        const explicitAliasProvided = Object.prototype.hasOwnProperty.call(importAliases, exportName);
-
-        if (collidesWithGeneratedClass && importCollisionBehavior === "error") {
-          throw new Error(
-            `[vue-pom-generator] Custom POM import name collision detected for "${exportName}".\n`
-            + `The identifier "${requested}" conflicts with a generated POM class.\n`
-            + `Fix by setting generation.playwright.customPoms.importAliases["${exportName}"] to a unique name, `
-            + `or set generation.playwright.customPoms.importNameCollisionBehavior = "alias" to auto-alias collisions.`,
-          );
-        }
-
-        let localIdentifier = requested;
-        if (collidesWithGeneratedClass && importCollisionBehavior === "alias") {
-          const aliasBase = explicitAliasProvided ? requested : `${exportName}Custom`;
-          localIdentifier = ensureUniqueIdentifier(aliasBase);
-        }
-        else {
-          localIdentifier = ensureUniqueIdentifier(requested);
-        }
-
-        const customFileAbs = path.join(customDirAbs, file);
-        customPomClassIdentifierMap[exportName] = localIdentifier;
-        const customPomMethodSignatures = extractCustomPomMethodSignatures(fs.readFileSync(customFileAbs, "utf8"), exportName);
-        if (customPomMethodSignatures.size > 0) {
-          customPomMethodSignaturesByClass.set(exportName, customPomMethodSignatures);
-        }
-
-        const fromOutputDir = outputDir;
-        const importPath = stripExtension(toPosixRelativePath(fromOutputDir, customFileAbs));
-        if (localIdentifier !== exportName) {
-          imports.push(`import { ${exportName} as ${localIdentifier} } from "${importPath}";`);
-        }
-        else {
-          imports.push(`import { ${exportName} } from "${importPath}";`);
-        }
+    const customPomImportResolution = resolveCustomPomImportResolution(generatedClassNames, projectRoot, {
+      customPomDir: options.customPomDir,
+      customPomImportAliases: options.customPomImportAliases,
+      customPomImportNameCollisionBehavior: options.customPomImportNameCollisionBehavior,
+    });
+    const customPomClassIdentifierMap = customPomImportResolution.classIdentifierMap;
+    const customPomMethodSignaturesByClass = customPomImportResolution.methodSignaturesByClass;
+    const customPomAvailableClassIdentifiers = customPomImportResolution.availableClassIdentifiers;
+
+    for (const importSpecifier of Object.values(customPomImportResolution.importSpecifiersByClass).sort((left, right) => left.exportName.localeCompare(right.exportName))) {
+      const importPath = stripExtension(toPosixRelativePath(outputDir, importSpecifier.absolutePath));
+      if (importSpecifier.localIdentifier !== importSpecifier.exportName) {
+        imports.push(`import { ${importSpecifier.exportName} as ${importSpecifier.localIdentifier} } from "${importPath}";`);
+        continue;
       }
-
-      return {
-        classIdentifierMap: customPomClassIdentifierMap,
-        methodSignaturesByClass: customPomMethodSignaturesByClass,
-      };
-    };
-
-    const customPomImportResolution = addCustomPomImports();
-    const customPomClassIdentifierMap = customPomImportResolution?.classIdentifierMap ?? {};
-    const customPomMethodSignaturesByClass = customPomImportResolution?.methodSignaturesByClass ?? new Map<string, CustomPomMethodSignatureMap>();
-    const customPomAvailableClassIdentifiers = new Set(Object.values(customPomClassIdentifierMap));
+      imports.push(`import { ${importSpecifier.exportName} } from "${importPath}";`);
+    }
 
     // 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
@@ -1806,184 +2696,21 @@ async function generateAggregatedFiles(
 
     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 composed = getComposedStubBody(t, availableClassNames, depsByClassName, vueFilesPathMap, projectRoot);
+        return {
+          className: t,
+          members: composed?.members ?? getDefaultStubMembers(),
+          isStub: true as const,
+        };
       })(),
     );
 
-    const classes = items.map(([name, deps]) =>
-      generateViewObjectModelContent(name, deps, componentHierarchyMap, vueFilesPathMap, basePageClassPath, {
+    const classes = items.map(([name, deps]) => {
+      const prepared = prepareViewObjectModelClass(name, deps, componentHierarchyMap, {
         outputDir,
-        aggregated: true,
-
+        outputStructure: "aggregated",
         customPomAttachments: options.customPomAttachments ?? [],
         customPomClassIdentifierMap,
         customPomAvailableClassIdentifiers,
@@ -1991,78 +2718,78 @@ async function generateAggregatedFiles(
         testIdAttribute: options.testIdAttribute,
         vueRouterFluentChaining: options.vueRouterFluentChaining,
         routeMetaByComponent: options.routeMetaByComponent,
-      }),
-    );
-
-    const baseContent = [
-      header,
-      ...imports,
-      ...classes,
-      ...(stubs.length ? ["", ...stubs] : []),
-    ].filter(Boolean).join("\n\n");
+      });
+      const sourceRel = toPosixRelativePath(outputDir, deps.filePath);
+      const kind = deps.isView ? "Page" : "Component";
+      return {
+        className: prepared.className,
+        doc: `/** ${kind} POM: ${name} (source: ${sourceRel}) */`,
+        members: prepared.members,
+        isStub: false as const,
+      };
+    });
 
-    return baseContent;
-  };
+    const prefixText = buildFilePrefix({
+      referenceLib: "es2015",
+      eslintDisableSortImports: true,
+      commentLines: [
+        "Aggregated generated POMs",
+        "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.",
+      ],
+    });
 
-  const base = ensureDir(outDir);
-  const outputFile = path.join(base, "page-object-models.g.ts");
-  const header = `/// <reference lib="es2015" />\n${eslintSuppressionHeader}/**\n * Aggregated generated POMs\n${AUTO_GENERATED_COMMENT}`;
-  const content = makeAggregatedContent(header, path.dirname(outputFile), [...views, ...components]);
+    return renderSourceFile("page-object-models.g.ts", (sourceFile) => {
+      for (const line of imports) {
+        sourceFile.addStatements(line);
+      }
 
-  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`;
+      for (const entry of [...classes, ...stubs]) {
+        if (entry.isStub) {
+          sourceFile.addStatements(buildCommentBlock([
+            "Stub POM generated because it is referenced as a navigation target but",
+            "did not have any generated test ids in this build.",
+          ]).trimEnd());
+        }
+        else {
+          sourceFile.addStatements(entry.doc);
+        }
 
-  const runtimeDirAbs = path.join(base, "_pom-runtime");
-  const runtimeClassGenAbs = path.join(runtimeDirAbs, "class-generation");
+        const classDeclaration = sourceFile.addClass({
+          name: entry.className,
+          isExported: true,
+          extends: "BasePage",
+        });
 
-  const readText = (absPath: string, description: string) => {
-    try {
-      return fs.readFileSync(absPath, "utf8");
-    }
-    catch {
-      throw new Error(`Failed to read ${description} at ${absPath}`);
-    }
+        for (const member of entry.members) {
+          addClassMember(classDeclaration, member);
+        }
+      }
+    }, { prefixText });
   };
 
-  // Copy runtime dependencies into the output folder so the aggregated POM file can
-  // import them without relying on workspace package resolution.
-  // Resolve paths to bundled runtime files.  Mirror the pattern in support-plugins.ts:
-  // try fileURLToPath(new URL(..., import.meta.url)) (works in ESM where import.meta.url
-  // is a proper file:// URL), then fall back to __dirname (available in the CJS bundle
-  // via Node's module wrapper).  The fallback is needed because ensureDomShim() in
-  // router-introspection sets globalThis.document via JSDOM (url "https://example.test/"),
-  // after which Rollup's CJS shim for import.meta.url resolves to document.baseURI
-  // ("https://example.test/index.cjs") — not a file:// URL — causing fileURLToPath to throw.
-  const resolvePluginAsset = (relative: string): string => {
-    try {
-      return fileURLToPath(new URL(relative, import.meta.url));
-    }
-    catch {
-      return path.resolve(__dirname, relative);
-    }
-  };
-  const clickInstrumentationAbs = resolvePluginAsset("../click-instrumentation.ts");
-  const pointerAbs = resolvePluginAsset("../class-generation/Pointer.ts");
-  const playwrightTypesAbs = resolvePluginAsset("../class-generation/playwright-types.ts");
+  const base = ensureDir(outDir);
+  const outputFile = path.join(base, "page-object-models.g.ts");
+  const content = makeAggregatedContent(path.dirname(outputFile), [...views, ...components]);
 
-  const runtimeFiles: Array<{ filePath: string; content: string }> = [
-    {
-      filePath: path.join(runtimeDirAbs, "click-instrumentation.ts"),
-      content: readText(clickInstrumentationAbs, "click-instrumentation.ts"),
-    },
-    {
-      filePath: path.join(runtimeClassGenAbs, "Pointer.ts"),
-      content: readText(pointerAbs, "Pointer.ts"),
-    },
-    {
-      filePath: path.join(runtimeClassGenAbs, "playwright-types.ts"),
-      content: readText(playwrightTypesAbs, "playwright-types.ts"),
-    },
-    {
-      filePath: path.join(runtimeClassGenAbs, "BasePage.ts"),
-      content: readText(basePageClassPath, "BasePage.ts"),
-    },
-  ];
+  const indexFile = path.join(base, "index.ts");
+  const indexContent = renderSourceFile("index.ts", (sourceFile) => {
+    addExportAll(sourceFile, "./page-object-models.g");
+  }, {
+    prefixText: buildFilePrefix({
+      eslintDisableSortImports: true,
+      commentLines: [
+        "POM exports",
+        "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.",
+      ],
+    }),
+  });
+  const runtimeFiles = buildRuntimeGeneratedFiles(base, basePageClassPath);
 
   return [
     { filePath: outputFile, content },
@@ -2207,23 +2934,33 @@ function getComponentInstances(
   attachmentsForThisView: Array<{ className: string; propertyName: string }> = [],
   widgetInstances: WidgetInstance[] = [],
 ) {
-  let content = "\n";
+  const declarations: TypeScriptClassMember[] = [];
 
   for (const a of attachmentsForThisView) {
-    content += `    ${a.propertyName}: ${a.className};\n`;
+    declarations.push(createClassProperty({
+      name: a.propertyName,
+      type: a.className,
+    }));
   }
 
   for (const w of widgetInstances) {
-    content += `    ${w.propertyName}: ${w.className};\n`;
+    declarations.push(createClassProperty({
+      name: w.propertyName,
+      type: w.className,
+    }));
   }
 
   childrenComponent.forEach((child) => {
     if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
       const childName = child.split(".vue")[0];
-      content += `    ${childName}: ${childName};\n`;
+      declarations.push(createClassProperty({
+        name: childName,
+        type: childName,
+      }));
     }
   });
-  return `${content}\n`;
+
+  return declarations;
 }
 
 function getConstructor(
@@ -2233,24 +2970,26 @@ function getConstructor(
   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`;
+  return createClassConstructor({
+    parameters: [{ name: "page", type: "PwPage" }],
+    statements: (writer) => {
+      writer.writeLine(`super(page, { testIdAttribute: ${JSON.stringify(attr)} });`);
 
-  for (const a of attachmentsForThisView) {
-    content += `        this.${a.propertyName} = new ${a.className}(page, this);\n`;
-  }
+      for (const a of attachmentsForThisView) {
+        writer.writeLine(`this.${a.propertyName} = new ${a.className}(page, this);`);
+      }
 
-  for (const w of widgetInstances) {
-    content += `        this.${w.propertyName} = new ${w.className}(page, ${JSON.stringify(w.testId)});\n`;
-  }
+      for (const w of widgetInstances) {
+        writer.writeLine(`this.${w.propertyName} = new ${w.className}(page, ${JSON.stringify(w.testId)});`);
+      }
 
-  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`;
-    }
+      childrenComponent.forEach((child) => {
+        if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
+          const childName = child.split(".vue")[0];
+          writer.writeLine(`this.${childName} = new ${childName}(page);`);
+        }
+      });
+    },
   });
-  content += "    }";
-  return `${content}\n`;
 }