pomwright 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # pomwright
 
+## 1.5.1
+
+### Patch Changes
+
+- [#40](https://github.com/DyHex/POMWright/pull/40) [`c8232d2`](https://github.com/DyHex/POMWright/commit/c8232d21e2d7f0149042f4844037c67289d26068) Thanks [@DyHex](https://github.com/DyHex)! - # Summary
+
+  This PR focuses on preventative quality improvements to v2 locator-registry typing and internal safety.
+
+  ## What changed
+
+  - Refined compile-time diagnostics for invalid locator schema paths so errors are clearer and more actionable at the literal argument level.
+  - Hardened internal registry retrieval behavior (`get` / `getIfExists`) for safer, more predictable handling of missing paths and record cloning semantics.
+  - Added both compile-time and runtime guards to reject path-based reuse when the source path equals the target registration path `registry.add(path, { reuse: path })`.
+
 ## 1.5.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -1232,6 +1232,11 @@ declare class ReusableLocatorFactory<LocatorSchemaPathType extends string> {
     private create;
 }
 
+type PathArgument<Paths extends string, Path extends Paths> = LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>;
+type InvalidReusePath<Path extends string> = [
+    `Invalid reuse path, reuse path cannot be the same as registration path: ${Path}`
+];
+type ReusePathArgument<Paths extends string, Path extends Paths, ReusePath extends Paths> = Exclude<ReusePath, Path> extends never ? InvalidReusePath<Path> : PathArgument<Paths, ReusePath>;
 declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
     private readonly page;
     private readonly schemas;
@@ -1267,13 +1272,11 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      *   .nth("last");
      * ```
      */
-    add(path: RegistryPath<LocatorSchemaPathType>): LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false>;
-    add(path: RegistryPath<LocatorSchemaPathType>, options: {
-        reuse: RegistryPath<LocatorSchemaPathType>;
-    }): void;
-    add<Reuse extends ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>>(path: RegistryPath<LocatorSchemaPathType>, options: {
-        reuse: Reuse;
-    }): LocatorRegistrationSeededBuilderForType<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, Reuse["type"]>;
+    add<Path extends LocatorSchemaPathType, Reuse extends LocatorSchemaPathType | ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]> | undefined = undefined>(path: PathArgument<LocatorSchemaPathType, Path>, ...args: Reuse extends undefined ? [] : [
+        options: {
+            reuse: Reuse extends LocatorSchemaPathType ? ReusePathArgument<LocatorSchemaPathType, Path, Reuse> : Extract<Reuse, ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>>;
+        }
+    ]): Reuse extends undefined ? LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false> : Reuse extends LocatorSchemaPathType ? void : LocatorRegistrationSeededBuilderForType<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, Extract<Reuse, ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>>["type"]>;
     register(path: RegistryPath<LocatorSchemaPathType>, record: LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>): void;
     replace(path: RegistryPath<LocatorSchemaPathType>, record: LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>): void;
     get(path: RegistryPath<LocatorSchemaPathType>): LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>;
@@ -1297,7 +1300,7 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      * const locator = builder.getNestedLocator();
      * ```
      */
-    getLocatorSchema<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): LocatorQueryBuilderPublic<LocatorSchemaPathType, Path>;
+    getLocatorSchema<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): LocatorQueryBuilderPublic<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>>;
     /**
      * Resolves the Playwright {@link Locator} for the provided path, applying only the terminal
      * definition and its recorded steps (no ancestor chaining). Throws if the path is not registered.
@@ -1308,7 +1311,7 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      * await button.click();
      * ```
      */
-    getLocator<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): Locator;
+    getLocator<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): Locator;
     /**
      * Resolves a chained Playwright {@link Locator} for a nested path, traversing each registered
      * segment and applying their steps in order. Throws if any segment in the chain is missing.
@@ -1319,7 +1322,7 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      * await expect(nested).toBeVisible();
      * ```
      */
-    getNestedLocator<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): Locator;
+    getNestedLocator<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): Locator;
     buildLocatorChain(path: RegistryPath<LocatorSchemaPathType>, definitions: Map<string, LocatorStrategyDefinition>, steps: Map<string, LocatorStep<RegistryPath<LocatorSchemaPathType>, RegistryPath<LocatorSchemaPathType>>[]>, tombstones?: Set<string>, terminalDescription?: LocatorDescription, context?: {
         rootPath: RegistryPath<LocatorSchemaPathType>;
         resolvingPaths: Set<string>;
@@ -1334,10 +1337,10 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
         }[];
     };
 }
-type GetLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends RegistryPath<LocatorSchemaPathType>>(path: Path) => Locator;
+type GetLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>) => Locator;
 type AddAccessor<LocatorSchemaPathType extends string> = LocatorRegistryInternal<LocatorSchemaPathType>["add"];
-type GetLocatorSchemaAccessor<LocatorSchemaPathType extends string> = <Path extends RegistryPath<LocatorSchemaPathType>>(path: Path) => LocatorQueryBuilderPublic<LocatorSchemaPathType, Path>;
-type GetNestedLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends RegistryPath<LocatorSchemaPathType>>(path: Path) => Locator;
+type GetLocatorSchemaAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>) => LocatorQueryBuilderPublic<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>>;
+type GetNestedLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>) => Locator;
 type LocatorRegistry<LocatorSchemaPathType extends string> = Pick<LocatorRegistryInternal<LocatorSchemaPathType>, "add" | "createReusable" | "getLocator" | "getLocatorSchema" | "getNestedLocator">;
 /**
  * Creates a v2 locator registry bound to a Playwright {@link Page} and returns the registry plus
@@ -1359,15 +1362,9 @@ type LocatorRegistry<LocatorSchemaPathType extends string> = Pick<LocatorRegistr
  */
 declare const createRegistryWithAccessors: <Paths extends string>(page: Page) => {
     readonly registry: LocatorRegistry<Paths>;
-    readonly add: {
-        (path: RegistryPath<Paths>): LocatorRegistrationPreDefinitionBuilder<Paths, RegistryPath<Paths>, false>;
-        (path: RegistryPath<Paths>, options: {
-            reuse: RegistryPath<Paths>;
-        }): void;
-        <Reuse extends ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id">>(path: RegistryPath<Paths>, options: {
-            reuse: Reuse;
-        }): LocatorRegistrationSeededBuilderForType<Paths, RegistryPath<Paths>, Reuse["type"]>;
-    };
+    readonly add: <Path extends Paths, Reuse extends Paths | ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id"> | undefined = undefined>(path: PathArgument<Paths, Path>, ...args: Reuse extends undefined ? [] : [options: {
+        reuse: Reuse extends Paths ? ReusePathArgument<Paths, Path, Reuse> : Extract<Reuse, ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id">>;
+    }]) => Reuse extends undefined ? LocatorRegistrationPreDefinitionBuilder<Paths, RegistryPath<Paths>, false> : Reuse extends Paths ? void : LocatorRegistrationSeededBuilderForType<Paths, RegistryPath<Paths>, Extract<Reuse, ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id">>["type"]>;
     readonly getLocator: GetLocatorAccessor<Paths>;
     readonly getNestedLocator: GetNestedLocatorAccessor<Paths>;
     readonly getLocatorSchema: GetLocatorSchemaAccessor<Paths>;

package/dist/index.d.ts

@@ -1232,6 +1232,11 @@ declare class ReusableLocatorFactory<LocatorSchemaPathType extends string> {
     private create;
 }
 
+type PathArgument<Paths extends string, Path extends Paths> = LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>;
+type InvalidReusePath<Path extends string> = [
+    `Invalid reuse path, reuse path cannot be the same as registration path: ${Path}`
+];
+type ReusePathArgument<Paths extends string, Path extends Paths, ReusePath extends Paths> = Exclude<ReusePath, Path> extends never ? InvalidReusePath<Path> : PathArgument<Paths, ReusePath>;
 declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
     private readonly page;
     private readonly schemas;
@@ -1267,13 +1272,11 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      *   .nth("last");
      * ```
      */
-    add(path: RegistryPath<LocatorSchemaPathType>): LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false>;
-    add(path: RegistryPath<LocatorSchemaPathType>, options: {
-        reuse: RegistryPath<LocatorSchemaPathType>;
-    }): void;
-    add<Reuse extends ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>>(path: RegistryPath<LocatorSchemaPathType>, options: {
-        reuse: Reuse;
-    }): LocatorRegistrationSeededBuilderForType<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, Reuse["type"]>;
+    add<Path extends LocatorSchemaPathType, Reuse extends LocatorSchemaPathType | ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]> | undefined = undefined>(path: PathArgument<LocatorSchemaPathType, Path>, ...args: Reuse extends undefined ? [] : [
+        options: {
+            reuse: Reuse extends LocatorSchemaPathType ? ReusePathArgument<LocatorSchemaPathType, Path, Reuse> : Extract<Reuse, ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>>;
+        }
+    ]): Reuse extends undefined ? LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false> : Reuse extends LocatorSchemaPathType ? void : LocatorRegistrationSeededBuilderForType<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, Extract<Reuse, ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>>["type"]>;
     register(path: RegistryPath<LocatorSchemaPathType>, record: LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>): void;
     replace(path: RegistryPath<LocatorSchemaPathType>, record: LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>): void;
     get(path: RegistryPath<LocatorSchemaPathType>): LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>;
@@ -1297,7 +1300,7 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      * const locator = builder.getNestedLocator();
      * ```
      */
-    getLocatorSchema<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): LocatorQueryBuilderPublic<LocatorSchemaPathType, Path>;
+    getLocatorSchema<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): LocatorQueryBuilderPublic<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>>;
     /**
      * Resolves the Playwright {@link Locator} for the provided path, applying only the terminal
      * definition and its recorded steps (no ancestor chaining). Throws if the path is not registered.
@@ -1308,7 +1311,7 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      * await button.click();
      * ```
      */
-    getLocator<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): Locator;
+    getLocator<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): Locator;
     /**
      * Resolves a chained Playwright {@link Locator} for a nested path, traversing each registered
      * segment and applying their steps in order. Throws if any segment in the chain is missing.
@@ -1319,7 +1322,7 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
      * await expect(nested).toBeVisible();
      * ```
      */
-    getNestedLocator<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): Locator;
+    getNestedLocator<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): Locator;
     buildLocatorChain(path: RegistryPath<LocatorSchemaPathType>, definitions: Map<string, LocatorStrategyDefinition>, steps: Map<string, LocatorStep<RegistryPath<LocatorSchemaPathType>, RegistryPath<LocatorSchemaPathType>>[]>, tombstones?: Set<string>, terminalDescription?: LocatorDescription, context?: {
         rootPath: RegistryPath<LocatorSchemaPathType>;
         resolvingPaths: Set<string>;
@@ -1334,10 +1337,10 @@ declare class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
         }[];
     };
 }
-type GetLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends RegistryPath<LocatorSchemaPathType>>(path: Path) => Locator;
+type GetLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>) => Locator;
 type AddAccessor<LocatorSchemaPathType extends string> = LocatorRegistryInternal<LocatorSchemaPathType>["add"];
-type GetLocatorSchemaAccessor<LocatorSchemaPathType extends string> = <Path extends RegistryPath<LocatorSchemaPathType>>(path: Path) => LocatorQueryBuilderPublic<LocatorSchemaPathType, Path>;
-type GetNestedLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends RegistryPath<LocatorSchemaPathType>>(path: Path) => Locator;
+type GetLocatorSchemaAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>) => LocatorQueryBuilderPublic<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>>;
+type GetNestedLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>) => Locator;
 type LocatorRegistry<LocatorSchemaPathType extends string> = Pick<LocatorRegistryInternal<LocatorSchemaPathType>, "add" | "createReusable" | "getLocator" | "getLocatorSchema" | "getNestedLocator">;
 /**
  * Creates a v2 locator registry bound to a Playwright {@link Page} and returns the registry plus
@@ -1359,15 +1362,9 @@ type LocatorRegistry<LocatorSchemaPathType extends string> = Pick<LocatorRegistr
  */
 declare const createRegistryWithAccessors: <Paths extends string>(page: Page) => {
     readonly registry: LocatorRegistry<Paths>;
-    readonly add: {
-        (path: RegistryPath<Paths>): LocatorRegistrationPreDefinitionBuilder<Paths, RegistryPath<Paths>, false>;
-        (path: RegistryPath<Paths>, options: {
-            reuse: RegistryPath<Paths>;
-        }): void;
-        <Reuse extends ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id">>(path: RegistryPath<Paths>, options: {
-            reuse: Reuse;
-        }): LocatorRegistrationSeededBuilderForType<Paths, RegistryPath<Paths>, Reuse["type"]>;
-    };
+    readonly add: <Path extends Paths, Reuse extends Paths | ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id"> | undefined = undefined>(path: PathArgument<Paths, Path>, ...args: Reuse extends undefined ? [] : [options: {
+        reuse: Reuse extends Paths ? ReusePathArgument<Paths, Path, Reuse> : Extract<Reuse, ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id">>;
+    }]) => Reuse extends undefined ? LocatorRegistrationPreDefinitionBuilder<Paths, RegistryPath<Paths>, false> : Reuse extends Paths ? void : LocatorRegistrationSeededBuilderForType<Paths, RegistryPath<Paths>, Extract<Reuse, ReusableLocator<Paths, RegistryPath<Paths>, "role" | "text" | "label" | "placeholder" | "altText" | "title" | "locator" | "frameLocator" | "testId" | "id">>["type"]>;
     readonly getLocator: GetLocatorAccessor<Paths>;
     readonly getNestedLocator: GetNestedLocatorAccessor<Paths>;
     readonly getLocatorSchema: GetLocatorSchemaAccessor<Paths>;

package/dist/index.js

@@ -2498,20 +2498,45 @@ var LocatorRegistryInternal = class {
       ...record.description !== void 0 ? { description: record.description } : {}
     };
   }
-  add(path, options) {
+  /**
+   * Registers a locator schema at the provided dot-delimited path.
+   * Accepts exactly one locator strategy (`getByRole`, `locator`, etc.) and any number of
+   * `filter`/`nth` steps chained in call order. When `{ reuse }` is supplied, the seeded
+   * definition is applied first and one matching override is allowed as a PATCH of the seed;
+   * otherwise, calling multiple locator strategies will throw.
+   *
+   * @example
+   * ```ts
+   * registry
+   *   .add("list.item")
+   *   .getByRole("listitem", { name: /Row/ })
+   *   .filter({ hasText: "Row" })
+   *   .nth("last");
+   * ```
+   */
+  add(path, ...args) {
+    const options = args[0];
     const reuse = options?.reuse;
-    if (!reuse) {
+    if (reuse === void 0) {
       return new LocatorRegistrationBuilder(
         this,
         path
       );
     }
     if (typeof reuse === "string") {
+      const targetPath = path;
+      if (reuse === targetPath) {
+        throw new Error(`Locator reuse path cannot be the same as registration path: "${targetPath}".`);
+      }
       const sourceRecord = this.get(reuse);
-      const cloned = this.cloneRecordForReuse(sourceRecord, path);
-      this.register(path, cloned);
+      const cloned = this.cloneRecordForReuse(sourceRecord, targetPath);
+      this.register(targetPath, cloned);
       return void 0;
     }
+    if (Array.isArray(reuse)) {
+      const [reason] = reuse;
+      throw new Error(`Invalid reuse path configuration for "${path}": ${reason}`);
+    }
     const reusedRecord = this.cloneRecordForReuse(
       {
         locatorSchemaPath: path,
@@ -2562,7 +2587,7 @@ Existing Schema: ${errorDetails}`);
     }
     return {
       locatorSchemaPath: record.locatorSchemaPath,
-      definition: record.definition,
+      definition: cloneLocatorStrategyDefinition(record.definition),
       steps: normalizeSteps(record.steps),
       ...record.description !== void 0 ? { description: record.description } : {}
     };
@@ -2577,7 +2602,7 @@ Existing Schema: ${errorDetails}`);
     }
     return {
       locatorSchemaPath: record.locatorSchemaPath,
-      definition: record.definition,
+      definition: cloneLocatorStrategyDefinition(record.definition),
       steps: normalizeSteps(record.steps),
       ...record.description !== void 0 ? { description: record.description } : {}
     };
@@ -2656,7 +2681,10 @@ Existing Schema: ${errorDetails}`);
    * ```
    */
   getLocatorSchema(path) {
-    return new LocatorQueryBuilder(this, path);
+    return new LocatorQueryBuilder(
+      this,
+      path
+    );
   }
   /**
    * Resolves the Playwright {@link Locator} for the provided path, applying only the terminal
@@ -2759,7 +2787,6 @@ Existing Schema: ${errorDetails}`);
   }
 };
 var createRegistryWithAccessors = (page) => {
-  const _assertValidPaths = true;
   const registryInstance = new LocatorRegistryInternal(page);
   const add = registryInstance.add.bind(registryInstance);
   const getLocator = registryInstance.getLocator.bind(registryInstance);

package/dist/index.mjs

@@ -2462,20 +2462,45 @@ var LocatorRegistryInternal = class {
       ...record.description !== void 0 ? { description: record.description } : {}
     };
   }
-  add(path, options) {
+  /**
+   * Registers a locator schema at the provided dot-delimited path.
+   * Accepts exactly one locator strategy (`getByRole`, `locator`, etc.) and any number of
+   * `filter`/`nth` steps chained in call order. When `{ reuse }` is supplied, the seeded
+   * definition is applied first and one matching override is allowed as a PATCH of the seed;
+   * otherwise, calling multiple locator strategies will throw.
+   *
+   * @example
+   * ```ts
+   * registry
+   *   .add("list.item")
+   *   .getByRole("listitem", { name: /Row/ })
+   *   .filter({ hasText: "Row" })
+   *   .nth("last");
+   * ```
+   */
+  add(path, ...args) {
+    const options = args[0];
     const reuse = options?.reuse;
-    if (!reuse) {
+    if (reuse === void 0) {
       return new LocatorRegistrationBuilder(
         this,
         path
       );
     }
     if (typeof reuse === "string") {
+      const targetPath = path;
+      if (reuse === targetPath) {
+        throw new Error(`Locator reuse path cannot be the same as registration path: "${targetPath}".`);
+      }
       const sourceRecord = this.get(reuse);
-      const cloned = this.cloneRecordForReuse(sourceRecord, path);
-      this.register(path, cloned);
+      const cloned = this.cloneRecordForReuse(sourceRecord, targetPath);
+      this.register(targetPath, cloned);
       return void 0;
     }
+    if (Array.isArray(reuse)) {
+      const [reason] = reuse;
+      throw new Error(`Invalid reuse path configuration for "${path}": ${reason}`);
+    }
     const reusedRecord = this.cloneRecordForReuse(
       {
         locatorSchemaPath: path,
@@ -2526,7 +2551,7 @@ Existing Schema: ${errorDetails}`);
     }
     return {
       locatorSchemaPath: record.locatorSchemaPath,
-      definition: record.definition,
+      definition: cloneLocatorStrategyDefinition(record.definition),
       steps: normalizeSteps(record.steps),
       ...record.description !== void 0 ? { description: record.description } : {}
     };
@@ -2541,7 +2566,7 @@ Existing Schema: ${errorDetails}`);
     }
     return {
       locatorSchemaPath: record.locatorSchemaPath,
-      definition: record.definition,
+      definition: cloneLocatorStrategyDefinition(record.definition),
       steps: normalizeSteps(record.steps),
       ...record.description !== void 0 ? { description: record.description } : {}
     };
@@ -2620,7 +2645,10 @@ Existing Schema: ${errorDetails}`);
    * ```
    */
   getLocatorSchema(path) {
-    return new LocatorQueryBuilder(this, path);
+    return new LocatorQueryBuilder(
+      this,
+      path
+    );
   }
   /**
    * Resolves the Playwright {@link Locator} for the provided path, applying only the terminal
@@ -2723,7 +2751,6 @@ Existing Schema: ${errorDetails}`);
   }
 };
 var createRegistryWithAccessors = (page) => {
-  const _assertValidPaths = true;
   const registryInstance = new LocatorRegistryInternal(page);
   const add = registryInstance.add.bind(registryInstance);
   const getLocator = registryInstance.getLocator.bind(registryInstance);

package/docs/v2/locator-registry.md

@@ -119,7 +119,9 @@ type Paths =
     | "main.button@login";
 ```
 
-If invalid literals are included in the union, type errors are surfaced where the registry factory is instantiated.
+If invalid literals are included in the union, TypeScript blocks those values at locator accessor argument usage
+(`add`, `getLocator`, `getNestedLocator`, `getLocatorSchema`) with path-format diagnostics while preserving
+valid path autocomplete suggestions. Runtime validation still applies for non-literal strings.
 
 ### Runtime validation rules
 

package/intTestV2/package.json

@@ -13,7 +13,7 @@
 		"@types/express": "^5.0.3",
 		"@types/node": "^24.5.2",
 		"express": "^5.1.0",
-		"pomwright": "file:../pomwright-1.4.0.tgz"
+		"pomwright": "file:../pomwright-1.5.0.tgz"
 	},
 	"dependencies": {
 		"dotenv": "^17.2.2"

package/intTestV2/tests/locatorRegistry/add/add.get.clone.spec.ts

@@ -0,0 +1,76 @@
+import { expect, test } from "@fixtures-v2/testApp.fixtures";
+import type { Page } from "@playwright/test";
+import { LocatorRegistryInternal } from "../../../../srcV2/locators";
+
+const createTestRegistry = <Paths extends string>(page: Page) => new LocatorRegistryInternal<Paths>(page);
+
+test("registry.get returns a cloned definition copy", async ({ page }) => {
+	type LocatorSchemaPaths = "button";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("button").getByRole("button", { name: "Submit", exact: true });
+
+	const firstRecord = registry.get("button");
+
+	expect(firstRecord).toEqual({
+		locatorSchemaPath: "button",
+		definition: {
+			type: "role",
+			role: "button",
+			options: { name: "Submit", exact: true },
+		},
+		steps: [],
+	});
+
+	if (firstRecord.definition.type !== "role") {
+		throw new Error("Expected role definition for mutation test");
+	}
+
+	firstRecord.definition.options = { name: "Mutated" };
+
+	const secondRecord = registry.get("button");
+
+	expect(secondRecord).toEqual({
+		locatorSchemaPath: "button",
+		definition: {
+			type: "role",
+			role: "button",
+			options: { name: "Submit", exact: true },
+		},
+		steps: [],
+	});
+});
+
+test("registry.getIfExists returns a cloned definition copy", async ({ page }) => {
+	type LocatorSchemaPaths = "banner";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	registry.add("banner").locator("section.banner", { hasText: "Welcome" });
+
+	const firstRecord = registry.getIfExists("banner");
+	expect(firstRecord).toBeDefined();
+
+	if (!firstRecord || firstRecord.definition.type !== "locator") {
+		throw new Error("Expected locator definition for mutation test");
+	}
+
+	firstRecord.definition.options = { hasText: "Mutated" };
+	if (!firstRecord.steps) {
+		throw new Error("Expected steps array on cloned record");
+	}
+	firstRecord.steps.push({ kind: "index", index: 0 });
+
+	const secondRecord = registry.getIfExists("banner");
+
+	expect(secondRecord).toEqual({
+		locatorSchemaPath: "banner",
+		definition: {
+			type: "locator",
+			selector: "section.banner",
+			options: { hasText: "Welcome" },
+		},
+		steps: [],
+	});
+});

package/intTestV2/tests/locatorRegistry/add/add.reuseExisting.spec.ts

@@ -21,6 +21,47 @@ test("add reuses with existing record by path does not have chainable methods",
 	});
 });
 
+test("add reuse by path with empty string does not silently skip reuse", async ({ page }) => {
+	type LocatorSchemaPaths = "button";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	// @ts-expect-error - testing runtime error when reuse is an empty string
+	expect(() => registry.add("button", { reuse: "" })).toThrowError('No locator schema registered for path "".');
+});
+
+test("add reuse by path throws when source path matches target path", async ({ page }) => {
+	type LocatorSchemaPaths = "button";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	// @ts-expect-error - testing runtime error when reuse path is the same as registration path
+	expect(() => registry.add("button", { reuse: "button" })).toThrowError(
+		'Locator reuse path cannot be the same as registration path: "button".',
+	);
+});
+
+test("add reuse by path reports compile-time fallback reason when forced at runtime", async ({ page }) => {
+	type LocatorSchemaPaths = "button" | "button.copy";
+
+	const registry = createTestRegistry<LocatorSchemaPaths>(page);
+
+	const addUnsafe = registry.add as unknown as (
+		path: string,
+		options: {
+			reuse: [string];
+		},
+	) => void;
+
+	expect(() =>
+		addUnsafe("button.copy", {
+			reuse: ["Invalid reuse path, reuse path cannot be the same as registration path: button.copy"],
+		}),
+	).toThrowError(
+		'Invalid reuse path configuration for "button.copy": Invalid reuse path, reuse path cannot be the same as registration path: button.copy',
+	);
+});
+
 test("add reuse by path clones records so mutations do not leak", async ({ page }) => {
 	type LocatorSchemaPaths = "button" | "button.copy";
 

package/intTestV2/tests/locatorRegistry/validation/validation.locatorSchemaPath.typecheck.ts

@@ -0,0 +1,86 @@
+import type { Page } from "@playwright/test";
+import { createRegistryWithAccessors } from "pomwright";
+
+declare const page: Page;
+
+type ValidPaths = "valid" | "validReuse";
+
+const validRegistryFactoryResult = createRegistryWithAccessors<ValidPaths>(page);
+
+validRegistryFactoryResult.add("valid").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+validRegistryFactoryResult.add("does.not.exist").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+validRegistryFactoryResult.add("valid", { reuse: "does.not.exist" });
+// @ts-expect-error reuse path cannot be the same as registration path
+validRegistryFactoryResult.add("validReuse", { reuse: "validReuse" });
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+validRegistryFactoryResult.getLocator("does.not.exist");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+validRegistryFactoryResult.getLocatorSchema("does.not.exist");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+validRegistryFactoryResult.getNestedLocator("does.not.exist");
+
+type InvalidPaths = ValidPaths | "" | ".leading" | "trailing." | "double..dot" | "contains whitespace";
+
+const invalidRegistryFactoryResult = createRegistryWithAccessors<InvalidPaths>(page);
+
+invalidRegistryFactoryResult.add("valid").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add(".leading").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("trailing.").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("double..dot").locator("body");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("contains whitespace").locator("body");
+
+invalidRegistryFactoryResult.add("validReuse", { reuse: "valid" });
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("validReuse", { reuse: "" });
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("validReuse", { reuse: ".leading" });
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("validReuse", { reuse: "trailing." });
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("validReuse", { reuse: "double..dot" });
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.add("validReuse", { reuse: "contains whitespace" });
+
+invalidRegistryFactoryResult.getLocator("valid");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocator("");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocator(".leading");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocator("trailing.");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocator("double..dot");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocator("contains whitespace");
+
+invalidRegistryFactoryResult.getLocatorSchema("valid");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocatorSchema("");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocatorSchema(".leading");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocatorSchema("trailing.");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocatorSchema("double..dot");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getLocatorSchema("contains whitespace");
+
+invalidRegistryFactoryResult.getNestedLocator("valid");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getNestedLocator("");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getNestedLocator(".leading");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getNestedLocator("trailing.");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getNestedLocator("double..dot");
+// @ts-expect-error invalid path literal should fail at the accessor argument with path-format details
+invalidRegistryFactoryResult.getNestedLocator("contains whitespace");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pomwright",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "POMWright is a complementary test framework for Playwright written in TypeScript.",
   "repository": {
     "type": "git",

package/srcV2/locators/locatorRegistry.ts

@@ -12,7 +12,7 @@ import type {
 	IndexSelector,
 	LocatorBuilderTarget,
 	LocatorDescription,
-	LocatorSchemaPathErrors,
+	LocatorSchemaPathFormat,
 	LocatorSchemaRecord,
 	LocatorStep,
 	LocatorStrategyDefinition,
@@ -33,6 +33,21 @@ import {
 	validateLocatorSchemaPath,
 } from "./utils";
 
+type PathArgument<Paths extends string, Path extends Paths> = LocatorSchemaPathFormat<Path> extends Path
+	? Path
+	: LocatorSchemaPathFormat<Path>;
+
+type InvalidReusePath<Path extends string> = [
+	`Invalid reuse path, reuse path cannot be the same as registration path: ${Path}`,
+];
+
+type ReusePathArgument<Paths extends string, Path extends Paths, ReusePath extends Paths> = Exclude<
+	ReusePath,
+	Path
+> extends never
+	? InvalidReusePath<Path>
+	: PathArgument<Paths, ReusePath>;
+
 export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	private readonly schemas = new Map<
 		RegistryPath<LocatorSchemaPathType>,
@@ -94,50 +109,82 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	 *   .nth("last");
 	 * ```
 	 */
-	add(
-		path: RegistryPath<LocatorSchemaPathType>,
-	): LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false>;
-	add(path: RegistryPath<LocatorSchemaPathType>, options: { reuse: RegistryPath<LocatorSchemaPathType> }): void;
 	add<
-		Reuse extends ReusableLocator<
-			LocatorSchemaPathType,
-			RegistryPath<LocatorSchemaPathType>,
-			LocatorStrategyDefinition["type"]
-		>,
+		Path extends LocatorSchemaPathType,
+		Reuse extends
+			| LocatorSchemaPathType
+			| ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>
+			| undefined = undefined,
 	>(
-		path: RegistryPath<LocatorSchemaPathType>,
-		options: { reuse: Reuse },
-	): LocatorRegistrationSeededBuilderForType<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, Reuse["type"]>;
-	add(
-		path: RegistryPath<LocatorSchemaPathType>,
-		options?: {
-			reuse?:
-				| ReusableLocator<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, LocatorStrategyDefinition["type"]>
-				| RegistryPath<LocatorSchemaPathType>;
-		},
-	):
-		| LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false>
-		| LocatorRegistrationSeededBuilderForType<
-				LocatorSchemaPathType,
-				RegistryPath<LocatorSchemaPathType>,
-				LocatorStrategyDefinition["type"]
-		  >
-		| undefined {
+		path: PathArgument<LocatorSchemaPathType, Path>,
+		...args: Reuse extends undefined
+			? []
+			: [
+					options: {
+						reuse: Reuse extends LocatorSchemaPathType
+							? ReusePathArgument<LocatorSchemaPathType, Path, Reuse>
+							: Extract<
+									Reuse,
+									ReusableLocator<
+										LocatorSchemaPathType,
+										RegistryPath<LocatorSchemaPathType>,
+										LocatorStrategyDefinition["type"]
+									>
+								>;
+					},
+				]
+	): Reuse extends undefined
+		? LocatorRegistrationPreDefinitionBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false>
+		: Reuse extends LocatorSchemaPathType
+			? void
+			: LocatorRegistrationSeededBuilderForType<
+					LocatorSchemaPathType,
+					RegistryPath<LocatorSchemaPathType>,
+					Extract<
+						Reuse,
+						ReusableLocator<
+							LocatorSchemaPathType,
+							RegistryPath<LocatorSchemaPathType>,
+							LocatorStrategyDefinition["type"]
+						>
+					>["type"]
+				> {
+		const options = args[0] as
+			| {
+					reuse?:
+						| ReusableLocator<
+								LocatorSchemaPathType,
+								RegistryPath<LocatorSchemaPathType>,
+								LocatorStrategyDefinition["type"]
+						  >
+						| LocatorSchemaPathType
+						| InvalidReusePath<RegistryPath<LocatorSchemaPathType>>;
+			  }
+			| undefined;
 		const reuse = options?.reuse;
 
-		if (!reuse) {
+		if (reuse === undefined) {
 			return new LocatorRegistrationBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, false>(
 				this,
-				path,
-			);
+				path as RegistryPath<LocatorSchemaPathType>,
+			) as never;
 		}
 
 		if (typeof reuse === "string") {
+			const targetPath = path as RegistryPath<LocatorSchemaPathType>;
+			if (reuse === targetPath) {
+				throw new Error(`Locator reuse path cannot be the same as registration path: "${targetPath}".`);
+			}
 			const sourceRecord = this.get(reuse as RegistryPath<LocatorSchemaPathType>);
-			const cloned = this.cloneRecordForReuse(sourceRecord, path);
+			const cloned = this.cloneRecordForReuse(sourceRecord, targetPath);
+
+			this.register(targetPath, cloned);
+			return undefined as never;
+		}
 
-			this.register(path, cloned);
-			return undefined;
+		if (Array.isArray(reuse)) {
+			const [reason] = reuse;
+			throw new Error(`Invalid reuse path configuration for "${path}": ${reason}`);
 		}
 
 		const reusedRecord: LocatorSchemaRecord<
@@ -145,24 +192,24 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 			RegistryPath<LocatorSchemaPathType>
 		> = this.cloneRecordForReuse(
 			{
-				locatorSchemaPath: path,
+				locatorSchemaPath: path as RegistryPath<LocatorSchemaPathType>,
 				definition: reuse.definition,
 				steps: reuse.steps,
 				description: reuse.description,
 			},
-			path,
+			path as RegistryPath<LocatorSchemaPathType>,
 		);
 
 		return new LocatorRegistrationBuilder<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>, true>(
 			this,
-			path,
+			path as RegistryPath<LocatorSchemaPathType>,
 			{
 				initialDefinition: reusedRecord.definition,
 				initialSteps: reusedRecord.steps,
 				reuseType: reusedRecord.definition.type,
 				initialDescription: reusedRecord.description,
 			},
-		).persistSeededDefinition();
+		).persistSeededDefinition() as never;
 	}
 
 	register(
@@ -204,7 +251,7 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 		}
 		return {
 			locatorSchemaPath: record.locatorSchemaPath,
-			definition: record.definition,
+			definition: cloneLocatorStrategyDefinition(record.definition),
 			steps: normalizeSteps(record.steps),
 			...(record.description !== undefined ? { description: record.description } : {}),
 		} satisfies LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>;
@@ -219,12 +266,12 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	): LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>> | undefined {
 		const record = this.schemas.get(path);
 		if (!record) {
-			return undefined;
+			return undefined as never;
 		}
 
 		return {
 			locatorSchemaPath: record.locatorSchemaPath,
-			definition: record.definition,
+			definition: cloneLocatorStrategyDefinition(record.definition),
 			steps: normalizeSteps(record.steps),
 			...(record.description !== undefined ? { description: record.description } : {}),
 		} satisfies LocatorSchemaRecord<LocatorSchemaPathType, RegistryPath<LocatorSchemaPathType>>;
@@ -345,10 +392,13 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	 * const locator = builder.getNestedLocator();
 	 * ```
 	 */
-	getLocatorSchema<Path extends RegistryPath<LocatorSchemaPathType>>(
-		path: Path,
-	): LocatorQueryBuilderPublic<LocatorSchemaPathType, Path> {
-		return new LocatorQueryBuilder<LocatorSchemaPathType, Path>(this, path);
+	getLocatorSchema<Path extends LocatorSchemaPathType>(
+		path: PathArgument<LocatorSchemaPathType, Path>,
+	): LocatorQueryBuilderPublic<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>> {
+		return new LocatorQueryBuilder<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>>(
+			this,
+			path as Extract<Path, RegistryPath<LocatorSchemaPathType>>,
+		);
 	}
 
 	/**
@@ -361,7 +411,7 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	 * await button.click();
 	 * ```
 	 */
-	getLocator<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): Locator {
+	getLocator<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): Locator {
 		return this.getLocatorSchema(path).getLocator();
 	}
 
@@ -375,7 +425,7 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	 * await expect(nested).toBeVisible();
 	 * ```
 	 */
-	getNestedLocator<Path extends RegistryPath<LocatorSchemaPathType>>(path: Path): Locator {
+	getNestedLocator<Path extends LocatorSchemaPathType>(path: PathArgument<LocatorSchemaPathType, Path>): Locator {
 		return this.getLocatorSchema(path).getNestedLocator();
 	}
 
@@ -485,24 +535,18 @@ export class LocatorRegistryInternal<LocatorSchemaPathType extends string> {
 	}
 }
 
-export type GetLocatorAccessor<LocatorSchemaPathType extends string> = <
-	Path extends RegistryPath<LocatorSchemaPathType>,
->(
-	path: Path,
+export type GetLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(
+	path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>,
 ) => Locator;
 
 export type AddAccessor<LocatorSchemaPathType extends string> = LocatorRegistryInternal<LocatorSchemaPathType>["add"];
 
-export type GetLocatorSchemaAccessor<LocatorSchemaPathType extends string> = <
-	Path extends RegistryPath<LocatorSchemaPathType>,
->(
-	path: Path,
-) => LocatorQueryBuilderPublic<LocatorSchemaPathType, Path>;
+export type GetLocatorSchemaAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(
+	path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>,
+) => LocatorQueryBuilderPublic<LocatorSchemaPathType, Extract<Path, RegistryPath<LocatorSchemaPathType>>>;
 
-export type GetNestedLocatorAccessor<LocatorSchemaPathType extends string> = <
-	Path extends RegistryPath<LocatorSchemaPathType>,
->(
-	path: Path,
+export type GetNestedLocatorAccessor<LocatorSchemaPathType extends string> = <Path extends LocatorSchemaPathType>(
+	path: LocatorSchemaPathFormat<Path> extends Path ? Path : LocatorSchemaPathFormat<Path>,
 ) => Locator;
 
 export type LocatorRegistry<LocatorSchemaPathType extends string> = Pick<
@@ -529,8 +573,6 @@ export type LocatorRegistry<LocatorSchemaPathType extends string> = Pick<
  * ```
  */
 export const createRegistryWithAccessors = <Paths extends string>(page: Page) => {
-	type PathErrors = LocatorSchemaPathErrors<Paths>;
-	const _assertValidPaths: PathErrors extends never ? true : never = true as PathErrors extends never ? true : never;
 	const registryInstance = new LocatorRegistryInternal<Paths>(page);
 	const add: LocatorRegistryInternal<Paths>["add"] = registryInstance.add.bind(registryInstance);
 	const getLocator: GetLocatorAccessor<Paths> = registryInstance.getLocator.bind(registryInstance);