[Feature]: Official APIs to resolve/map ephemeral aria-refs to stable locators for LLM automation

The issue requests new APIs to map ephemeral aria-refs to stable locators for LLM automation. Start by examining the existing aria_snapshot(mode="ai") implementation and the private codegen utilities. Look for internal methods like generateLocator or exposeConsoleApi. The goal is to design a public API that returns a Locator object or a structured selector bundle from a given aria-ref.

🚀 Feature Request

With the rapid evolution of LLM-driven browser automation (especially leveraging Playwright's excellent aria_snapshot(mode="ai")), there is a growing need to bridge the gap between ephemeral AI session references (aria-ref=e5) and persistent, deterministic locators.

Currently, LLM agents perceive the page through temporary aria-ref identifiers. However, to "compile" these exploratory runs into reusable production scripts, developers must map these temporary refs to stable, best-practice locators (e.g., get_by_role, get_by_text).

While Playwright's internal codegen engine is powerful for this, it is currently locked behind private APIs. More importantly, simply generating a code string is often not enough; developers need a native, structured way to resolve an aria-ref into a stable Locator object or a "locator bundle" (role, name, css, xpath) to maintain this mapping throughout the automation pipeline.

Example

I would love to see official APIs that allow developers to programmatically resolve and map aria-refs to stable locators. This could take several forms, depending on what fits Playwright's design philosophy best:

1. Structured Locator Resolution: Provide a method to resolve an aria-ref directly into a stable Locator object or a structured dictionary of candidate selectors.
2. Expose Codegen/Console APIs: Alternatively, officially expose exposeConsoleApi or a dedicated codegen utility so developers can safely access window.playwright.generateLocator without relying on private internals.

Motivation

Right now, the only way to achieve this workflow is by reaching into Playwright's private internals:

# Python example of the current hacky workaround
await context._impl_obj._channel.send("exposeConsoleApi", None, {})

This is undocumented, fragile, and could break in any future release. Furthermore, it forces developers to manually parse and manage the relationship between the temporary ref and the resulting stable locator, without any native support for maintaining this mapping across complex agent workflows.

If this API were officially exposed, it would create a seamless, closed-loop workflow for AI agents:

1. AI Perception: Get the page state using snapshot = await page.aria_snapshot(mode="ai")
2. LLM Decision: The LLM decides to interact with an element, returning a reference like ref=e5
3. Resolution & Mapping...
4. Action & Persistence....

Playwright has already taken a huge step forward by introducing aria_snapshot(mode="ai"). Providing a native way to resolve these ephemeral AI refs into stable locators would be the perfect companion feature. It would bridge the gap between ephemeral AI sessions and persistent, deterministic automation, making Playwright the undisputed best framework for building reliable AI web agents.

Thank you for considering this request!