pomwright 1.4.0 → 1.5.0

package/AGENTS.md

@@ -0,0 +1,37 @@
+# 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/CHANGELOG.md

@@ -1,5 +1,184 @@
 # pomwright
 
+## 1.5.0
+
+### Minor Changes
+
+- [#35](https://github.com/DyHex/POMWright/pull/35) [`50fb6f4`](https://github.com/DyHex/POMWright/commit/50fb6f47ffd0745d81fffdf63cfbcf4c8b569bcf) Thanks [@DyHex](https://github.com/DyHex)! - # v1.5 Bridge Release
+
+  ## Summary
+
+  POMWright **v1.5** is a bridge release. It ships the legacy v1 API and the redesigned v2 API side-by-side so teams can migrate at their own pace.
+
+  For projects continuing to use only v1 patterns, upgrading from **v1.4 → v1.5** should require no behavioral changes by default. Migration starts when you opt into v2 APIs.
+
+  ## Philosophy and Motivation
+
+  The v2 redesign preserves the original POMWright principles from v1 (typed path-based locator modeling and automatic locator chaining), while modernizing the architecture around:
+
+  - better composability,
+  - clearer public API boundaries,
+  - stronger validation/error handling,
+  - and **Playwright-native ergonomics**.
+
+  The Playwright-native API shape (`getByRole`, `locator`, `filter`, `nth`, etc.) makes adoption easier for teams already fluent in Playwright, reducing cognitive overhead while improving long-term maintainability in larger test suites.
+
+  ## Migration Documentation
+
+  - [v1 to v2 comparison](../docs/v1-to-v2-migration/v1-to-v2-comparison.md)
+  - [Direct migration guide](../docs/v1-to-v2-migration/direct-migration-guide.md)
+  - [Bridge migration guide](../docs/v1-to-v2-migration/bridge-migration-guide.md)
+
+  ## v2 documentation
+
+  - [v2 Overview](../docs/v2/overview.md)
+  - [v2 PageObject](../docs/v2/PageObject.md)
+  - [v2 Locator Registry](../docs/v2/locator-registry.md)
+  - [v2 Composing Locator Modules](../docs/v2/composing-locator-modules.md)
+  - [v2 Session Storage](../docs/v2/session-storage.md)
+  - [v2 Logging](../docs/v2/logging.md)
+
+  ***
+
+  ## What changes when moving from v1 to v2
+
+  > Important: These are migration-time changes. They do **not** affect users who remain on v1 usage patterns in v1.5.
+
+  ### 1) Base class and architecture
+
+  - **v1**: `BasePage` is the core abstraction and requires `Page`, `testInfo`, and `PlaywrightReportLogger`.
+  - **v2**: `PageObject` is slimmer and composes navigation, locator registry accessors, and session storage without hard-coupling `testInfo` or logger.
+
+  ### 2) Modular adoption (“cherry-pick” usage)
+
+  v2 does not force inheritance from `PageObject`.
+
+  Adopters can use only what they need:
+
+  - `LocatorRegistry` (via `createRegistryWithAccessors`)
+  - `SessionStorage`
+  - `step` decorator
+  - logging fixture/logger
+  - or `PageObject` as a convenience composition.
+
+  ### 3) Locator definitions: schema objects → fluent builder DSL
+
+  - **v1**: `addSchema(path, { locatorMethod, ... })` + `GetByMethod` enum + `LocatorSchemaWithoutPath`.
+  - **v2**: `add(path).getByRole(...).filter(...).nth(...).describe(...)`.
+
+  This redesign improves readability and aligns locator registration with native Playwright style.
+
+  ### 4) Retrieval API behavior
+
+  - Conceptually preserved: `getLocator` (terminal) vs `getNestedLocator` (full chain).
+  - **v1** retrieval was async.
+  - **v2** retrieval is synchronous.
+
+  ### 5) Step handling (`filter` + `nth`) is significantly more expressive
+
+  - **v1**: filters could be chained, but indexing behavior was constrained and applied after filter composition.
+  - **v2**:
+    - `filter` and `nth` are both first-class steps,
+    - steps are applied in exact chain order,
+    - no practical chain-limit restrictions,
+    - `nth` can be set at registration time and query time,
+    - `filter has/hasNot` accepts both Playwright locators and registry path references.
+
+  ### 6) FrameLocator semantics are explicit and safer
+
+  - **v1** cast `FrameLocator` to `Locator` for compatibility.
+  - **v2** handles frame segments explicitly:
+    - non-terminal frame segments continue resolution inside frame context,
+    - terminal frame segments resolve to frame owner locator.
+
+  ### 7) Mutation model redesign
+
+  - **v1**: `update(...)` + `addFilter(...)` on schema clones.
+  - **v2** separates concerns:
+    - definition ops: `update`, `replace`, `remove`
+    - step ops: `filter`, `nth`, `clearSteps`
+    - locator annotation: `describe`
+
+  This improves intent clarity and reduces accidental side effects.
+
+  ### 8) Reuse model upgrade
+
+  - **v1** reuse centered around shared `LocatorSchemaWithoutPath` objects.
+  - **v2** introduces:
+    - typed reusable seeds (`createReusable`),
+    - controlled typed overrides,
+    - reuse-by-path cloning.
+
+  This reduces duplication while improving type guidance and safety.
+
+  ### 9) Navigation helper (new in v2)
+
+  `PageObject.navigation` is URL-type aware:
+
+  - string fullUrl support includes `goto`, `gotoThisPage`, `expectThisPage`, `expectAnotherPage`.
+  - RegExp fullUrl support narrows to assertion-oriented methods (`expectThisPage`, `expectAnotherPage`).
+
+  ### 10) SessionStorage evolution
+
+  SessionStorage is not removed; it is redesigned and strengthened:
+
+  - context-aware operations (`waitForContext`),
+  - key-targeted clear,
+  - clearer option signatures.
+
+  ### 11) Logging decoupling
+
+  - v1 tightly coupled logger usage through base class constructor patterns.
+  - v2 keeps logging available but optional; `PageObject` does not force logger coupling.
+
+  ### 12) Step decorator (new in v2)
+
+  v2 introduces a `@step` decorator for wrapping POM methods in `test.step` with typed arguments and returns.
+
+  ### 13) Error handling and validation improvements
+
+  v2 strengthens diagnostics and safety across registry operations:
+
+  - stricter path validation (compile-time + runtime alignment),
+  - improved sub-path validation,
+  - better reuse guardrails,
+  - explicit filter reference constraints,
+  - filter cycle detection,
+  - clearer frame/filter misuse errors.
+
+  ***
+
+  ## Breaking / Behavioral Notes (migration-scoped)
+
+  The following apply when adopting v2 APIs:
+
+  - retrieval methods are synchronous,
+  - v1 nested index-map style is replaced by ordered `nth(...)` steps,
+  - `addFilter(...)` is replaced by `filter(...)`,
+  - frame handling semantics are explicit (terminal frame resolves to owner locator),
+  - built-in `data-cy` selector engine behavior from v1 is removed from framework defaults,
+  - `BaseApi` is not part of v2.
+
+  ***
+
+  ## Additional improvements worth mentioning
+
+  - Cleaner public/internal API boundary for registry internals.
+  - Functional-friendly factory (`createRegistryWithAccessors`) for dependency injection and non-class usage.
+  - Clone-based query mutation semantics that avoid mutating canonical registry state.
+  - Better migration support via bridge mechanisms and v1 schema translation helpers.
+  - Better docs structure for v2 and migration workflows.
+
+  ## skills
+
+  In the repository ./skills folder you can find AI assistant migration skills to help upgrade POMWright page objects from v1 to v2. These skills provide step-by-step guidance for migrating BasePage to the v1.5 bridge (BasePageV1toV2) or directly to v2 PageObject.
+
+  > **Important:** Use at your own discretion. These migration skills are an optional aid intended to reduce manual effort when moving POMWright page objects from v1 to v2. They offer practical guidance for common migration paths, but they cannot account for every project-specific variation, custom abstraction, or edge case in existing v1 implementations. Treat them as a helpful starting point—not a guaranteed or complete migration solution. Always review and validate AI-generated changes before using them.
+
+  ## Bridge Positioning Statement
+
+  POMWright v1.5 is intentionally designed to let teams keep shipping on v1 while preparing migration to v2. The release provides both a staged bridge path and a direct migration path, with no forced v1 behavior changes unless v2 APIs are adopted.
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -7,32 +7,294 @@
 [![NPM dev or peer Dependency Version](https://img.shields.io/npm/dependency-version/pomwright/peer/%40playwright%2Ftest)](https://www.npmjs.com/package/playwright)
 [![Static Badge](https://img.shields.io/badge/created%40-ICE-ffcd00)](https://www.ice.no/)
 
-POMWright is a lightweight TypeScript framework that layers the Page Object Model on top of Playwright.  It keeps locators, page objects, and fixtures organised so that UI tests stay readable and maintainable.
+POMWright is a TypeScript companion framework for Playwright focused on Page Object Model workflows.
 
-POMWright provides a way of abstracting the implementation details of a web page and encapsulating them into a reusable page object. This approach makes the tests easier to read, write, and maintain, and helps reduce duplicated code by breaking down the code into smaller, reusable components, making the code more maintainable and organized.
+It provides automatic locator chaining via a LocatorRegistry, a Session Storage API, a log fixture for report attachments, and a test.step decorator — all of which can be used independently either through a functional approachs or as part of your custom POMs or quickly create new standardized POMS by extending a class with the provided the abstract PageObject class. PageObject also adds navigation helpers and URL typing which supports multiple base URLs and dynamic RegExp paths.
 
-## Key capabilities
+---
 
-- Quickly build maintainable Page Object Classes.
-- Define any Playwright Locator through type-safe LocatorSchemas.
-- Automatic chaining of locators with dot-delimited paths that map directly to Playwright locator methods.
-- Auto-completion of LocatorSchemaPaths and sub-paths.
-- Adjust locators on the fly without mutating the original definitions.
-- Attach structured logs directly to the Playwright HTML report.
-- Manage `sessionStorage` for browser setup and state hand‑off.
-- Multiple Domains/BaseURLs
-- Validate elements position in DOM through chaining
+## Version status: v1.5 is a migration bridge
 
-## Why POMWright?
+POMWright v1.5 currently ships both:
 
-- **Stronger reliability** – centralised locator definitions reduce brittle inline selectors and make refactors visible at compile time.
-- **Faster authoring** – strongly typed schema paths provide instant auto-complete, even for deeply nested segments and reusable fragments.
-- **Easier maintenance** – shared helper patterns keep page objects, fixtures, and API clients aligned so teams can extend coverage without duplicating boilerplate.
-- **Incremental adoption** – each helper sits on top of Playwright primitives, making it straightforward to migrate existing tests component by component.
+- **v1 API** (legacy/deprecated)
+- **v2 API** (current direction)
 
-## Installation
+**v1.5 is the bridge release** for migrating from v1 patterns to v2 patterns. If you are starting fresh, use **v2 (`PageObject` + `LocatorRegistry`)**. If you are on v1, use the migration docs to move incrementally.
+
+---
+
+## Why use POMWright instead of vanilla Playwright POM?
+
+Playwright’s official best practices emphasize locator chaining for clarity and resilience. In practice, manually writing and maintaining those chains becomes tedious and fragile as pages grow. POMWright’s solution is the LocatorRegistry, which automatically builds locator chains from single locator definitions tied to unique paths. You register one locator per path (with Playwright‑like syntax), and POMWright composes the full chain for you.
+
+This gives you the same Playwright primitives you already use — but with dramatically simpler maintenance, better structure, and safer refactors across small and large projects.
+
+### Chain everything
+
+POMWright’s default behavior is to resolve locators by chaining all segments in a path. That brings two major benefits:
+
+- **Robustness through scope‑aware uniqueness:** Chaining narrows selectors through the intended DOM structure, producing more robust locators that are less brittle to UI changes and therefore less prone to flake. A “Change” button tied to a password field under a “Credentials” region resolves differently than a “Change” button tied to an email field under a “Contact info” region. If an identical button is added elsewhere, existing tests keep working because their paths remain scoped. If the button is mistakenly added under the wrong section, tests will fail and reveal the mistake.
+
+- **Implicit DOM structure validation:** Because chains traverse the DOM hierarchy, locator resolution validates that the UI is still arranged as expected — as strictly or loosely as you choose. You don’t need to map the entire DOM; just chain the “structural anchors” that matter. Often, user‑visible elements are good enough.
 
-Install POMWright alongside Playwright:
+### Highlights
+
+- **Centralized locator definitions with automatic chaining** — one path defines an entire selector chain across the app, across all Playwright locator types.
+- **Safer refactors** — update a locator once and all usages update automatically (including full chains).
+- **Typed paths and sub‑paths** with contextual autocomplete and compile‑time validation, making structural updates as simple as find‑and‑replace.
+- **Explicit control of chain depth** — choose terminal resolution (getLocator) or full chained resolution (`getNestedLocator`) at the call site.
+- **Non‑mutating query overrides** — handle edge cases, variations, and iteration without changing base definitions (`getLocatorSchema(...).update/replace/remove/filter/nth/describe`).
+- **Reusable locator seeds + typed path reuse** — share locator patterns or clone existing definitions across contexts without duplication.
+- **Optional helpers** — locator registry, session storage, logging, and step decorator can be adopted independently.
+- **Minimal base class** — `PageObject` provides URL + navigation + registry + session storage, leaving everything else to your own composition.
+
+---
+
+## Example: vanilla Playwright POM vs POMWright `PageObject`
+
+### Vanilla Playwright POM (typical)
+
+```ts
+import { test, type Locator, type Page } from "@playwright/test";
+
+export class LoginPage {
+  readonly page: Page;
+  readonly main: Locator;
+  readonly loginForm: Locator;
+  readonly usernameInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.main = page.locator("main");
+    this.loginForm = this.main.getByRole("form", { name: "Login" });
+    this.usernameInput = this.loginForm.getByLabel("Username");
+    this.passwordInput = this.loginForm.getByLabel("Password");
+    this.submitButton = this.main.getByRole("button", { name: "Login" });
+  }
+
+  async goto() {
+    await test.step("LoginPage.goto", async () => {
+      await this.page.goto("/login");
+    });
+  }
+
+  async login(username: string, password: string) {
+    await test.step("LoginPage.login", async () => {
+      await this.usernameInput.fill(username);
+      await this.passwordInput.fill(password);
+      await this.submitButton.click();      
+    });
+  }
+}
+```
+
+### Vanilla Playwright fixture
+
+```ts
+import { test as base } from "@playwright/test";
+import { LoginPage } from "./login.page";
+
+type Fixtures = { loginPage: LoginPage };
+
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+});
+```
+
+### Vanilla Playwright Test
+
+```ts
+import { test } from "./fixtures";
+
+test("login flow", async ({ loginPage }) => {
+  await loginPage.goto();
+  await loginPage.login("alice", "secret");
+});
+```
+
+### POMWright `PageObject` (v2)
+
+```ts
+import { type Page } from "@playwright/test";
+import { PageObject, step } from "pomwright";
+
+type Paths =
+  | "main"
+  | "main.form@login"
+  | "main.form@login.input@username"
+  | "main.form@login.input@password"
+  | "main.button@login";
+
+export class LoginPage extends PageObject<Paths> {
+  constructor(page: Page) {
+    super(page, "https://example.com", "/login");
+  }
+
+  protected defineLocators(): void {
+    this.add("main").locator("main");
+    this.add("main.form@login").getByRole("form", { name: "Login" });
+    this.add("main.form@login.input@username").getByLabel("Username");
+    this.add("main.form@login.input@password").getByLabel("Password");
+    this.add("main.button@login").getByRole("button", { name: "Login" });
+  }
+
+  protected pageActionsToPerformAfterNavigation() {
+    return [
+      async () => {
+        await this.getNestedLocator("main.form@login").waitFor({ state: "visible" });
+      },
+    ];
+  }
+
+  @step()
+  async login(username: string, password: string) {
+    await this.getNestedLocator("main.form@login.input@username").fill(username);
+    await this.getNestedLocator("main.form@login.input@password").fill(password);
+    await this.getNestedLocator("main.button@login").click();
+  }
+}
+```
+
+**Tip:** If a Page Object grows large with many Paths and this.add(...) calls, move the locator definitions into a companion file (e.g., login.page.ts + login.locators.ts) to keep the class focused on behavior while keeping the registry definitions centralized and reusable. Simmilarily you can move all Paths and add calls for locator definitions common to all POMs for a given domain into a common.locators.ts file to share across your POMs.
+
+```ts
+// login.locators.ts
+import type { LocatorRegistry } from "pomwright";
+import { Paths as Common, defineLocators as addCommon } from "../common.locators"; // errors, dialogs, navbar, main, etc.
+
+export type Paths =
+  | Common
+  | "main.form@login"
+  | "main.form@login.input@username"
+  | "main.form@login.input@password"
+  | "main.button@login";
+
+export function defineLocators(registry: LocatorRegistry<Paths>) {
+  addCommon(registry);
+  registry.add("main.form@login").getByRole("form", { name: "Login" });
+  registry.add("main.form@login.input@username").getByLabel("Username");
+  registry.add("main.form@login.input@password").getByLabel("Password");
+  registry.add("main.button@login").getByRole("button", { name: "Login" });
+}
+```
+
+```ts
+// login.page.ts
+import { type Page } from "@playwright/test";
+import { PageObject, step } from "pomwright";
+import { type Paths, defineLocators } from "./login.locators.ts";
+
+export class LoginPage extends PageObject<Paths> {
+  constructor(page: Page) {
+    super(page, "https://example.com", "/login");
+  }
+
+  protected defineLocators(): void {
+    defineLocators(this.locatorRegistry);
+  }
+
+  protected pageActionsToPerformAfterNavigation() {
+    return [
+      async () => {
+        await this.getNestedLocator("common.nav.logo").waitFor({ state: "visible" });
+        await this.getNestedLocator("main.form@login").waitFor({ state: "visible" });
+      },
+    ];
+  }
+
+  @step()
+  async login(username: string, password: string) {
+    await this.getNestedLocator("main.form@login.input@username").fill(username);
+    await this.getNestedLocator("main.form@login.input@password").fill(password);
+    await this.getNestedLocator("main.button@login").click();
+  }
+}
+```
+
+### POMWright fixtures
+
+```ts
+import { test as base } from "@playwright/test";
+import { PlaywrightReportLogger, type LogEntry, type LogLevel } from "pomwright";
+import { LoginPage } from "./login.page";
+
+type Fixtures = { 
+  loginPage: LoginPage,
+  log: PlaywrightReportLogger
+};
+
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+  log: async ({}, use, testInfo) => { // or just import { test as base } from "pomwright";
+    const sharedLogEntry: LogEntry[] = [];
+    const sharedLogLevel: { current: LogLevel; initial: LogLevel } =
+      testInfo.retry === 0
+        ? { current: "warn", initial: "warn" }
+        : { current: "debug", initial: "debug" };
+
+    const log = new PlaywrightReportLogger(sharedLogLevel, sharedLogEntry, "TestCase");
+    await use(log);
+    log.attachLogsToTest(testInfo);
+  },
+});
+```
+
+### POMWright test
+
+```ts
+import { test } from "./fixtures";
+
+test("login flow", async ({ loginPage, log }) => {
+  await loginPage.navigation.gotoThisPage();
+  await loginPage.login("alice", "secret");
+  log.info("Hellow World!");
+});
+
+```
+
+### What improves in the POMWright version?
+
+- **No manual chain construction in class properties**:
+The vanilla POM has to build and store each chain manually (main → form → input). In POMWright, you register each locator once and chaining is automatic, so you avoid duplicated chain logic and drift.
+- **Single source of truth for structure**:
+The DOM structure is encoded in the registry paths, not scattered across class fields. This makes the page structure explicit and easier to reason about.
+- **Refactors touch fewer places**:
+In vanilla POM, changing a DOM structure often means editing multiple chained fields. In POMWright, you update the registry definitions once and all chains update together.
+- **Less coupling between fields**:
+The vanilla POM creates dependencies between stored locators (loginForm must exist before usernameInput). POMWright doesn’t rely on field chains — each locator is defined independently and assembled by the registry.
+- **Clearer intent at call sites lowers cognitive load when scanning code**:
+In POMWright, call sites read like semantic paths (`"main.form@login.input@username"`), which makes intent clearer than referencing nested locator properties. Semantic paths make it obvious what a locator represents, while the registry tells you how it’s built.
+- **Explicit terminal vs chained resolution**:
+You can choose terminal‑only (getLocator) or fully chained (getNestedLocator) resolution per call without creating extra fields for each variation.
+- **Chaining consistency by default**:
+Every getNestedLocator(...) resolves the same full chain, so you can’t accidentally skip a parent locator when implementing or refactoring methods.
+- **Easier to introduce variations**:
+In vanilla POM, you often need extra fields or conditional logic for small variations. POMWright’s getLocatorSchema lets you tweak chains or filters for edge cases without changing the base definitions.
+- **Consistent fixture usage**:
+The POMWright fixture exposes a uniform API (navigation, registry, session storage), whereas the vanilla fixture just provides a class instance with custom fields. This reduces ad‑hoc helpers over time.
+- **Built‑in navigation flow**:
+The POMWright version can express “loaded state” directly as post‑navigation actions. The vanilla version requires separate helper methods or repeated waits in tests.
+- **Step and logging instrumentation are standardized**:
+@step() and optional logging make action tracing consistent across pages instead of ad‑hoc test.step wrappers in individual methods.
+- **Registry definitions are shareable across POCs**:
+If multiple POMs share UI sections, the same locator paths can be reused directly rather than copied.
+- **Better guardrails for large teams**:
+Typed paths and consistent chaining help prevent “near‑miss” locators that work in one file but differ subtly elsewhere.
+- **More predictable long‑term maintenance**:
+Registry‑driven chains reduce the risk of subtle inconsistencies between methods or tests as the suite grows.
+- **Easier onboarding for new contributors**:
+Paths reveal structure and intent immediately, so newcomers don’t need to trace nested Locator fields to understand what’s happening.
+
+---
+
+## Installation
 
 ```bash
 pnpm add -D pomwright
@@ -40,28 +302,48 @@ pnpm add -D pomwright
 npm install --save-dev pomwright
 ```
 
-## Documentation
+---
+
+## Documentation index
+
+### v2 documentation (recommended)
+
+- [v2 Overview](./docs/v2/overview.md)
+- [v2 PageObject](./docs/v2/PageObject.md)
+- [v2 Locator Registry](./docs/v2/locator-registry.md)
+- [v2 Composing Locator Modules](./docs/v2/composing-locator-modules.md)
+- [v2 Session Storage](./docs/v2/session-storage.md)
+- [v2 Logging](./docs/v2/logging.md)
+
+### v1 -> v2 migration guides
+
+- [v1 to v2 Comparison](./docs/v1-to-v2-migration/v1-to-v2-comparison.md)
+- [Direct Migration Guide](./docs/v1-to-v2-migration/direct-migration-guide.md)
+- [Bridge Migration Guide](./docs/v1-to-v2-migration/bridge-migration-guide.md)
+
+### v1 documentation (legacy/deprecated)
 
-Start with the introduction and continue through the topics:
+- [Intro to using POMWright (v1)](./docs/v1/intro-to-using-pomwright.md)
+- [BasePage](./docs/v1/BasePage-explanation.md)
+- [LocatorSchemaPath](./docs/v1/LocatorSchemaPath-explanation.md)
+- [LocatorSchema](./docs/v1/LocatorSchema-explanation.md)
+- [Locator helper methods](./docs/v1/get-locator-methods-explanation.md)
+- [BaseApi](./docs/v1/BaseApi-explanation.md)
+- [PlaywrightReportLogger](./docs/v1/PlaywrightReportLogger-explanation.md)
+- [Session storage helpers](./docs/v1/sessionStorage-methods-explanation.md)
+- [Tips for folder structure](./docs/v1/tips-folder-structure.md)
 
-1. [Intro to using POMWright](./docs/intro-to-using-pomwright.md)
-2. [BasePage](./docs/BasePage-explanation.md)
-3. [LocatorSchemaPath](./docs/LocatorSchemaPath-explanation.md)
-4. [LocatorSchema](./docs/LocatorSchema-explanation.md)
-5. [Locator schema helper methods](./docs/get-locator-methods-explanation.md)
-6. [BaseApi](./docs/BaseApi-explanation.md)
-7. [PlaywrightReportLogger](./docs/PlaywrightReportLogger-explanation.md)
-8. [Session storage helpers](./docs/sessionStorage-methods-explanation.md)
-9. [Tips for structuring locator files](./docs/tips-folder-structure.md)
+---
 
-## Troubleshooting and Support
+## Support
 
-If you encounter any issues or have questions, please check our [issues page](https://github.com/DyHex/POMWright/issues) or reach out to us directly.
+If you run into issues or have questions, please use the
+[GitHub issues page](https://github.com/DyHex/POMWright/issues).
 
 ## Contributing
 
-Pull Requests are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.
+Pull requests are welcome!
 
 ## License
 
-POMWright is open-source software licensed under the [Apache-2.0 license](https://github.com/DyHex/POMWright/blob/main/LICENSE).
+POMWright is open-source software licensed under [Apache-2.0](./LICENSE).