pomwright 1.5.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pomwright",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "POMWright is a complementary test framework for Playwright written in TypeScript.",
   "repository": {
     "type": "git",
@@ -17,6 +17,12 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "keywords": [
     "Playwright",
     "POM",
@@ -43,8 +49,7 @@
     "@changesets/cli": "^2.29.7",
     "@types/node": "^24.5.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.2"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.57.0 <2.0.0"
@@ -53,15 +58,8 @@
     "build": "tsup index.ts --format cjs,esm --dts",
     "release": "pnpm run build && changeset publish",
     "lint": "biome check ./src",
-    "lint:v2": "biome check ./srcV2",
-    "lint:all": "pnpm lint && pnpm lint:v2",
     "format": "biome format ./src --write",
-    "format:v2": "biome format ./srcV2 --write",
-    "format:all": "pnpm format && pnpm format:v2",
     "pack-test": "bash pack-test.sh",
-    "pack-test:v2": "bash pack-test-v2.sh",
-    "test": "vitest run && bash pack-test.sh",
-    "test:v2": "bash pack-test-v2.sh",
-    "test:all": "pnpm test && pnpm test:v2"
+    "test": "pnpm pack-test"
   }
 }

package/AGENTS.md

@@ -1,37 +0,0 @@
-# Agent Guidelines for POMWright
-
-This repository carries both the **v1** codepath (`src`, `intTest`) and the ongoing **v2** refactor (`srcV2`, `intTestV2`). Use the guidance below whenever you modify files in this repo.
-
-## Development priorities
-
-- Focus exclusively on the v2 codepath for implementation work. Do **not** change v1 (`src`, `intTest`); it is retained only for side-by-side comparison and regression awareness.
-- Preserve the fluent locator registry API introduced in v2 (via `LocatorRegistry`, `bindLocatorAccessors`, and the thenable builders) and keep examples/tests aligned with it.
-- Design v2 around the Page Object Model pattern expressed through functional programming: features should be as independent and composable as possible so users can adopt only what they need.
-- Write documentation under `docsV2/` for v2 work while consulting v1 docs in `docs/` for context and completeness.
-- Always consult the drift tracker at `docsV2/v1-v2-drift.md` before making changes, and update it immediately when you spot new breaking changes, regressions, or bug fixes.
-- Prefer migration helpers/shims over strict runtime compatibility with v1 APIs; clear improvements in functionality and syntax take priority over backwards compatibility.
-
-## Coding style
-
-- Follow the `.editorconfig` (tabs, size 2) and existing TypeScript conventions in the project.
-- Use pnpm for scripts and dependency management.
-- Prefer descriptive naming for locator paths and avoid anonymous segments; the registry validates dot-delimited paths with no leading/trailing dots.
-- Avoid `//biome-ignore` where possible by addressing the underlying lint/type issue; when necessary, include a short justification with the directive.
-- Do not wrap imports in `try/catch` blocks.
-
-## Testing and quality
-
-- Always run and fix `pnpm pack-test:v2` and `pnpm lint:v2` before committing. Use `lint:v2` to avoid unrelated v1 noise.
-- If you add or change locators or behavioural contracts, expand integration coverage in `intTestV2`; err on the side of more tests while keeping existing cases intact.
-- Existing tests in `intTestV2` should be maintained and keep their scope/cases. If a change would require large edits to a case, prefer adding new tests instead.
-
-## Commit and PR expectations
-
-- Keep commits scoped and descriptive; call out the v2 focus explicitly.
-- Keep docs and examples showing both v1 and v2 patterns where relevant to ease migration, but prioritize clear improvements in functionality and syntax over backwards compatibility.
-
-## Notes on locator work
-
-- Use v2’s builder DSL (`locators.add('path').getByRole(...)`, filters/index steps, frame handling) for new schemas and tests.
-- Prefer migration helpers/shims over trying to keep strict runtime compatibility with v1 APIs.
-- Document any intentionally breaking changes and provide migration tips where possible—capture them in `docsV2/v1-v2-drift.md` as they arise.

package/docs/v1/BaseApi-explanation.md

@@ -1,63 +0,0 @@
-# BaseApi
-
-The `BaseApi` class offers a minimal foundation for writing API helpers in POMWright.  It wraps Playwright's `APIRequestContext` and integrates with the shared [`PlaywrightReportLogger`](./PlaywrightReportLogger-explanation.md).
-
-## Constructor
-
-```ts
-constructor(baseUrl: string, apiName: string, context: APIRequestContext, pwrl: PlaywrightReportLogger)
-```
-
-* `baseUrl` – root address used to build request URLs.
-* `apiName` – human‑readable identifier; also used as a logging prefix.
-* `context` – Playwright [`APIRequestContext`](https://playwright.dev/docs/api/class-apirequestcontext).
-* `pwrl` – logger instance supplied by the test fixtures.  A child logger is created for the API class.
-
-The class stores these values on the instance and exposes the `request` and `log` properties for use in subclasses.
-
-## Example
-
-```ts
-import type { APIRequestContext } from "@playwright/test";
-import { BaseApi, type PlaywrightReportLogger } from "pomwright";
-
-class MyApi extends BaseApi {
-  constructor(baseUrl: string, context: APIRequestContext, pwrl: PlaywrightReportLogger) {
-    super(baseUrl, MyApi.name, context, pwrl);
-  }
-
-  v1 = {
-    users: {
-      id: {
-        get: async (id: string, status: number = 200) => {
-          const response = await this.request.get(`/api/users/${id}`);
-          expect(response.status(), "should have status code: 200").toBe(status);
-          const body = await response.json();
-          return body;
-        },
-        //...etc.
-      }
-    },
-    products: {
-      //...etc.
-    }
-  }
-}
-```
-
-Then in a test you'd do:
-
-```ts
-test("some test", { tag: ["@api", "@user"] }, async ({ myApi }) => {
-  // Create user
-
-  const existingUser = await myApi.v1.users.id.get(userId); // 200 (default) user found
-  
-  // Delete user
-
-  const deletedUser = await myApi.v1.users.id.get(userId, 204); // 204 user not found successfully
-
-})
-```
-
-`BaseApi` does not dictate how requests are made; you are free to add domain‑specific methods using the provided `request` context and logger.

package/docs/v1/BasePage-explanation.md

@@ -1,96 +0,0 @@
-# BasePage
-
-`BasePage` is the foundation for all Page Object Classes (POCs) in POMWright.  It provides common plumbing for Playwright pages, logging, locator management and session storage.
-
-## Generics
-
-```ts
-BasePage<LocatorSchemaPathType, Options = { urlOptions: { baseUrlType: string; urlPathType: string } }, LocatorSubstring>
-```
-
-* **LocatorSchemaPathType** – union of valid locator paths for the POC.
-* **Options** – optional configuration that allows the `baseUrl` or `urlPath` to be typed as a `RegExp` when dynamic values are required for mapping certain resource paths. See [intTest/page-object-models/testApp/with-options/base/baseWithOptions.page.ts](../intTest/page-object-models/testApp/with-options/base/baseWithOptions.page.ts)
-* **LocatorSubstring** – internal type used when working with sub paths; normally left undefined.
-
-## Constructor
-
-```ts
-constructor(
-  page: Page,
-  testInfo: TestInfo,
-  baseUrl: ExtractBaseUrlType<Options>,
-  urlPath: ExtractUrlPathType<Options>,
-  pocName: string,
-  pwrl: PlaywrightReportLogger
-)
-```
-
-The base class stores these values and derives `fullUrl`.  A child [`PlaywrightReportLogger`](./PlaywrightReportLogger-explanation.md) is created for the POC and a [`SessionStorage`](./sessionStorage-methods-explanation.md) helper is exposed as `sessionStorage`.
-
-## Required implementation
-
-Every POC extending `BasePage` must:
-
-1. Define a `LocatorSchemaPath` union describing available locators.
-2. Implement the `initLocatorSchemas()` method which adds schemas to the internal `GetLocatorBase` instance.
-
-```ts
-// login.page.ts
-import type { Page, TestInfo } from "@playwright/test";
-import { BasePage, type PlaywrightReportLogger } from "pomwright";
-import { test } from "@fixtures/all.fixtures";
-import { type LocatorSchemaPath, initLocatorSchemas } from "./login.locatorSchema";
-
-export default class Login extends BasePage<LocatorSchemaPath> {
-  constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", Login.name, pwrl);
-  }
-
-  protected initLocatorSchemas() {
-    initLocatorSchemas(this.locators);
-  }
-
-  public async login(user: string, pass: string) {
-    await test.step(`${this.pocName}: Fill login form and login`, async () => {
-
-      await test.step(`${this.pocName}: Fill username field`, async () => {
-        const locator = await this.getNestedLocator("main.section@login.form.textbox@username");
-        await locator.fill(user);
-        await locator.blur();
-      });
-
-      await test.step(`${this.pocName}: Fill password field`, async () => {
-        const locator = await this.getNestedLocator("main.section@login.form.textbox@password");
-        await locator.fill(pass);
-        await locator.blur();
-      });
-
-      await test.step(`${this.pocName}: Click login button`, async () => {
-        const locator = await this.getNestedLocator("main.section@login.button@login");
-        await locator.click();
-      });
-
-      /** 
-       * We probably don't want to await navigation here, instead we do it in the test, 
-       * using the POC representing the page we are navigated to (e.g. /profile) 
-       */
-    });
-  }
-}
-```
-
-## Helper methods
-
-`BasePage` exposes a small API built around `LocatorSchema` definitions:
-
-* `getLocatorSchema(path)` – returns a chainable object; see [locator methods](./get-locator-methods-explanation.md).
-* `getLocator(path)` – wrapper method for `getLocatorSchema(path).getLocator();` - resolves the locator for the final segment of a path, e.g. the Locator created from the LocatorSchema the full LocatorSchemaPath references.
-* `getNestedLocator(path, indices?)` – wrapper method for `getLocatorSchema(path).getNestedLocator();` - automatically chains locators along the path and optionally selects nth occurrences.
-
-All locators are strongly typed, giving compile‑time suggestions and preventing typos in `LocatorSchemaPath` strings.
-
-## Recommendation
-
-Instead of extending each of your POC's with BasePage from POMWright, opt instead to create an abstract BasePage class for your domain and have it extend BasePage from POMWright. Then have each of your POC's extend your abstract POC instead. This allows us to easily sentralize common helper methods, LocatorSchema, etc. and reuse it across all our POC's for the given domain.
-
-For examples see [intTest/page-object-models/testApp](../intTest/page-object-models/testApp)

package/docs/v1/LocatorSchema-explanation.md

@@ -1,271 +0,0 @@
-# LocatorSchema
-
-A `LocatorSchema` describes how to find an element in the DOM. Instead of storing Playwright `Locator` objects directly, POMWright keeps these schema definitions and resolves them only when a test requests the locator. The same schema can be reused across multiple page objects and test files without risking stale references.
-
-Every schema must set `locatorMethod` to one of the [`GetByMethod`](../src/helpers/locatorSchema.interface.ts) enum values. The matching selector fields listed below determine which Playwright API call is executed under the hood. You can provide more than one selector field, but the method chosen by `locatorMethod` is the one that will be used when the locator is created.
-
-When you register a schema with `GetLocatorBase.addSchema(path, schemaDetails)` the `locatorSchemaPath` is stored automatically and becomes part of the structured logs produced by POMWright.
-
-## Selector strategies
-
-> Note: You can define both "role" and "locator" on the same LocatorSchema, but which one is used is dictated by "locatorMethod". Too keep things clean I recommend only defining the actual type of Playwright Locator you'll be using.
-
-Each selector strategy maps directly to a Playwright locator helper. The snippets below show the POMWright configuration alongside the equivalent raw Playwright call.
-
-### `role` and `roleOptions`
-
-Use [ARIA roles](https://playwright.dev/docs/api/class-page#page-get-by-role) as your primary selector. The optional `roleOptions` map to the options object accepted by `page.getByRole()`.
-
-```ts
-locators.addSchema("content.button@edit", {
-  role: "button",
-  roleOptions: { name: "Edit" },
-  locatorMethod: GetByMethod.role
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByRole("button", { name: "Edit" });
-```
-
-### `text` and `textOptions`
-
-Match visible text using the same semantics as [`page.getByText()`](https://playwright.dev/docs/api/class-page#page-get-by-text).
-
-```ts
-locators.addSchema("content.link.help", {
-  text: "Need help?",
-  textOptions: { exact: true },
-  locatorMethod: GetByMethod.text
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByText("Need help?", { exact: true });
-```
-
-### `label` and `labelOptions`
-
-Reference form controls by their accessible label. `labelOptions` accepts the same arguments as [`page.getByLabel()`](https://playwright.dev/docs/api/class-page#page-get-by-label).
-
-```ts
-locators.addSchema("content.form.password", {
-  label: "Password",
-  locatorMethod: GetByMethod.label
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByLabel("Password");
-```
-
-### `placeholder` and `placeholderOptions`
-
-Target elements by placeholder text via [`page.getByPlaceholder()`](https://playwright.dev/docs/api/class-page#page-get-by-placeholder).
-
-```ts
-locators.addSchema("content.form.search", {
-  placeholder: "Search",
-  placeholderOptions: { exact: true },
-  locatorMethod: GetByMethod.placeholder
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByPlaceholder("Search", { exact: true });
-```
-
-### `altText` and `altTextOptions`
-
-Resolve images and other elements with alternative text via [`page.getByAltText()`](https://playwright.dev/docs/api/class-page#page-get-by-alt-text).
-
-```ts
-locators.addSchema("content.hero.image", {
-  altText: "Company logo",
-  locatorMethod: GetByMethod.altText
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByAltText("Company logo");
-```
-
-### `title` and `titleOptions`
-
-Tap into the [`title` attribute](https://playwright.dev/docs/api/class-page#page-get-by-title) of an element.
-
-```ts
-locators.addSchema("content.tooltip.info", {
-  title: "More information",
-  locatorMethod: GetByMethod.title
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByTitle("More information");
-```
-
-### `locator` and `locatorOptions`
-
-Fallback to raw selectors or locator chaining with [`page.locator()`](https://playwright.dev/docs/api/class-page#page-locator). `locatorOptions` is passed straight through to the Playwright call.
-
-```ts
-locators.addSchema("content.main", {
-  locator: "main",
-  locatorOptions: { hasText: "Profile" },
-  locatorMethod: GetByMethod.locator
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.locator("main", { hasText: "Profile" });
-```
-
-### `frameLocator`
-
-Create [`FrameLocator`](https://playwright.dev/docs/api/class-page#page-frame-locator) instances when your DOM interaction starts inside an iframe.
-
-```ts
-locators.addSchema("iframe.login", {
-  frameLocator: "#auth-frame",
-  locatorMethod: GetByMethod.frameLocator
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.frameLocator("#auth-frame");
-```
-
-### `testId`
-
-Call [`page.getByTestId()`](https://playwright.dev/docs/api/class-page#page-get-by-test-id) by setting the `testId` field.
-
-```ts
-locators.addSchema("content.button.reset", {
-  testId: "reset-btn",
-  locatorMethod: GetByMethod.testId
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByTestId("reset-btn");
-```
-
-### `dataCy`
-
-`dataCy` is a POMWright convenience for the legacy `data-cy` attribute used in Cypress-based projects. Under the hood it still calls `page.locator()` with the [`data-cy=` selector engine](https://playwright.dev/docs/extensibility#custom-selector-engines) registered by `BasePage`.
-
-```ts
-locators.addSchema("content.card.actions", {
-  dataCy: "card-actions",
-  locatorMethod: GetByMethod.dataCy
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.locator("data-cy=card-actions");
-```
-
-If you prefer to control the selector string yourself you can pass the full expression (`"data-cy=card-actions"`) and it will be used verbatim.
-
-### `id`
-
-`id` is the second POMWright-specific helper. Provide either the raw id string or a `RegExp`. Strings are normalised to CSS id selectors, so `"details"`, `"#details"`, and `"id=details"` all resolve to the same element. A regular expression matches the start of the `id` attribute, allowing you to capture generated identifiers.
-
-```ts
-locators.addSchema("content.region.details", {
-  id: "profile-details",
-  locatorMethod: GetByMethod.id
-});
-
-locators.addSchema("content.region.dynamic", {
-  id: /^region-/,
-  locatorMethod: GetByMethod.id
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.locator("#profile-details");
-page.locator('*[id^="region-"]');
-```
-
-### `filter`
-
-Any schema can define a `filter` object with the same shape as [`locator.filter()`](https://playwright.dev/docs/api/class-locator#locator-filter). Filters are applied immediately after the initial Playwright locator is created.
-
-```ts
-locators.addSchema("content.list.item", {
-  role: "listitem",
-  locatorMethod: GetByMethod.role,
-  filter: { hasText: /Primary Colors/i }
-});
-```
-
-Playwright equivalent:
-
-```ts
-page.getByRole("listitem").filter({ hasText: /Primary Colors/i });
-```
-
-## Putting it together
-
-Schemas are typically registered inside `initLocatorSchemas()` of a `BasePage` subclass. The example below demonstrates reusable fragments and multiple selector strategies working together.
-
-```ts
-import { GetByMethod, type GetLocatorBase, type LocatorSchemaWithoutPath } from "pomwright";
-type LocatorSchemaPath =
-  | "main"
-  | "main.button"
-  | "main.button@continue"
-  | "main.button@back";
-
-export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
-  locators.addSchema("main", {
-    locator: "main",
-    locatorMethod: GetByMethod.locator
-  });
-
-  const button: LocatorSchemaWithoutPath = {
-    role: "button",
-    locatorMethod: GetByMethod.role
-  };
-
-  locators.addSchema("main.button", {
-    ...button
-    });
-
-  locators.addSchema("main.button@continue", {
-    ...button,
-    roleOptions: { name: "Continue" }
-  });
-
-  locators.addSchema("main.button@back", {
-    ...button,
-    roleOptions: { name: "Back" }
-  });
-}
-```
-
-Once registered, the schemas can be consumed through the BasePage helpers documented in [`docs/get-locator-methods-explanation.md`](./get-locator-methods-explanation.md).

package/docs/v1/LocatorSchemaPath-explanation.md

@@ -1,165 +0,0 @@
-# LocatorSchemaPath
-
-A `LocatorSchemaPath` is the unique key that identifies a `LocatorSchema`.  Paths let POMWright build nested Playwright locators while keeping the definitions type‑safe and searchable.
-
-## Path syntax
-
-A `LocatorSchemaPath` is declared as a union of string literals.
-
-```ts
-type LocatorSchemaPath = "main";
-```
-
-Each word or segment of a string are separated by `.` (dot), where each dot represents a new element in the chain. Thus we end up with paths describing the hierarchy of elements on a page through dot notation.
-
-```ts
-type LocatorSchemaPath = 
-  | "main"
-  | "main.heading";
-```
-
-In other words, each `.` (dot) separates a new segment in the chain. A LocatorSchemaPath string:
-
-- Cannot be empty.
-- The string cannot start or end with `.`.
-- The string cannot contain consecutive dots.
-
-A path must start and end with a "word", a word is any combination of characters except `.` (dot). The following paths will throw during runtime:
-
-```ts
-// These throw at runtime
-type LocatorSchemaPath =
-  | ""              // empty string
-  | ".main"         // starting with a dot
-  | "main."         // ending with a dot
-  | "main..heading" // consecutive dots
-```
-
-Every path represents a chain of locators that describe the hierarchy of elements on the page. POMWright enforces uniqueness, so registering the same path twice causes fixture initialisation to fail before any test using them can runs.
-
-```ts
-import { GetByMethod, type GetLocatorBase } from "pomwright";
-
-export type LocatorSchemaPath =
-  | "main"
-  | "main.heading";
-
-export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
-  locators.addSchema("main.heading", { /* ... */ });
-  locators.addSchema("main.heading", { /* ... */ }); // duplicate – throws
-}
-```
-
-## Referencing schemas
-
-Each path declared in the type must be implemented with `addSchema` inside `initLocatorSchemas`.  Missing implementations raise a `not implemented` error when the fixtures are created, helping you catch mistakes early.
-
-Locator paths can be shared across Page Object Classes by re‑exporting the union of strings:
-
-```ts
-import { GetByMethod, type GetLocatorBase } from "pomwright";
-import {
-  type LocatorSchemaPath as common,
-  initLocatorSchemas as initCommon
-} from "../page-components/common.locatorSchema";
-
-export type LocatorSchemaPath =
-  | common
-  | "main.heading";
-
-export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
-  initCommon(locators);
-
-  locators.addSchema("main.heading", {
-    role: "heading",
-    roleOptions: { name: "Welcome!" },
-    locatorMethod: GetByMethod.role
-  });
-}
-```
-
-## Descriptive segments
-
-A path may include segments that exist purely for readability.  POMWright skips any missing intermediate keys when chaining the locator.
-
-```ts
-import { GetByMethod, type GetLocatorBase } from "pomwright";
-
-type LocatorSchemaPath = 
-  | "main"
-  | "main.button.continue";  // "button" communicates intent
-
-export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
-
-  locators.addSchema("main", {
-    locator: "main",
-    locatorMethod: GetByMethod.locator
-  });
-
-  locators.addSchema("main.button.continue", {
-    role: "button",
-    roleOptions: { name: "Continue" },
-    locatorMethod: GetByMethod.role
-  });
-}
-```
-
-You can also suffix segments with a friendly name using `@`.  POMWright treats `@` like any other character—it simply improves readability for humans. You're free to use any special character to improve readability.
-
-```ts
-import { GetByMethod, type GetLocatorBase, type LocatorSchemaWithoutPath } from "pomwright";
-
-type LocatorSchemaPath = 
-  | "main"
-  | "main.button"
-  | "main.button@continue"
-  | "main.button@back";  // "button" is here used for human context
-
-export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
-
-  locators.addSchema("main", {
-    locator: "main",
-    locatorMethod: GetByMethod.locator
-  });
-
-  const button: LocatorSchemaWithoutPath = { 
-      role: "button", 
-      locatorMethod: GetByMethod.role
-    }
-
-  locators.addSchema("main.button", {
-    ...button,
-  });
-
-  locators.addSchema("main.button@continue", {
-    ...button,
-    roleOptions: { name: "Continue" }
-  });
-
-  locators.addSchema("main.button@back", {
-    ...button,
-    roleOptions: { name: "Back" }
-  });
-}
-```
-
-> Use something like `main.button` when you need a broad locator (for example, to count buttons) and `main.button@continue` or `main.button@back` when you need a specific instance.
-
-The portion before `@` usually describes the element type (`section`, `button`), while the part after `@` is a friendly identifier (`playground`, `reset`).  This makes long chains readable while still conveying intent.
-
-> **Note:** There is nothing special about the character `@`, in the eyes of POMWright it's just another character in a word. The only "special" character is `.` dot.
-
-Remember: the goal is not to mirror the DOM structure 1:1. Just enough to ensure a descriptive and unique path to the elements you interact with and validate through the use of simple Locators.
-
-## LocatorSchemaPath, Sub-paths and IntelliSense
-
-Every dot‑delimited segment forms a sub path.  Sub paths power IntelliSense and let you scope updates or filters to a specific part of the chain.
-
-```ts
-const resetBtn = await profile
-  .getLocatorSchema("body.section@playground.button@reset")
-  .addFilter("body.section@playground", { hasText: /Primary Colors/i })
-  .getNestedLocator();
-```
-
-The TypeScript union of all paths enables autocomplete, prevents typos, and makes refactors simple.  Update a single `LocatorSchema` definition and every test using that path immediately benefits from the change.