@specific.dev/spectest 0.38.0 → 0.41.0

package/src/locator.ts

@@ -0,0 +1,716 @@
+// Playwright-native locators for the browser/mobile test surface.
+//
+// A `Locator` mirrors playwright-core's `Locator` shape — the same method
+// names, arguments, and semantics (STRICT mode included) — but it is our own
+// type, not playwright's, so we control exactly what's exposed. Everything
+// here is recordable in the dashboard timeline; playwright methods that bypass
+// the recorder (`elementHandle()`, `page()`, `contentFrame()`) are
+// deliberately absent.
+//
+// The implementation is a **lazy call-chain**. A locator carries a list of
+// `Step`s (getByRole → filter → nth …) and never touches a page until an
+// action runs. At action time `lower(page, chain)` folds the steps onto the
+// live playwright `Page`, producing a real playwright `Locator` that is used
+// once and discarded. This is load-bearing: the persistent browser session
+// swaps its underlying `page` on DNS-recovery (`rebuildView` in browser.ts),
+// so a locator must re-resolve against the *current* page every time — it can
+// never pin a playwright `Locator`/`Page` at creation.
+//
+// Composition (`locator`, `getBy*`, `filter`, `and`, `or`, `first`/`last`/
+// `nth`) returns a new lazy `Locator` with an extended chain. Terminal methods
+// (actions, reads, `waitFor`) run inside `backend.pageOp`, so each
+// author-facing call is exactly one recorded browser event (with its rrweb
+// drain), whatever playwright work it composes underneath.
+
+import type { Page, Locator as PWLocator } from "playwright-core";
+import type { RecordableFields } from "./browser.js";
+import type { Wrapped } from "./inspect.js";
+import { truncateUtf8 } from "./recorder.js";
+
+/** Default deadline for a locator action/read's target to become actionable.
+ *  Playwright's own default is 30s — far too slow-failing for tests; 5s
+ *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
+ *  `undefined` falls through to the context default (also set to this in
+ *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
+export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+
+// Brand + chain carrier. Both are `Symbol.for` keys so `JSON.stringify` drops
+// them (locators are never serialized) while runtime code can still detect a
+// locator and read a nested one's chain during lowering.
+const LOCATOR_BRAND: unique symbol = Symbol.for("spectest.locator");
+const CHAIN: unique symbol = Symbol.for("spectest.locatorChain");
+
+// ────────────────────────────────────────────────────────────────────────
+// Option shapes (re-declared here, not re-exported from playwright-core, so
+// playwright's types stay an implementation detail of the SDK)
+// ────────────────────────────────────────────────────────────────────────
+
+export interface GetByTextOptions {
+  /** Whole-string, case-sensitive match instead of the default
+   *  case-insensitive substring. Ignored when the query is a RegExp. */
+  exact?: boolean;
+}
+
+export interface GetByRoleOptions {
+  /** Match by accessible name. */
+  name?: string | RegExp;
+  /** Whole-string, case-sensitive name match. */
+  exact?: boolean;
+}
+
+export interface FilterOptions {
+  /** Keep only elements whose subtree contains this text. */
+  hasText?: string | RegExp;
+  /** Drop elements whose subtree contains this text. */
+  hasNotText?: string | RegExp;
+  /** Keep only elements that contain a match for this locator. */
+  has?: Locator;
+  /** Drop elements that contain a match for this locator. */
+  hasNot?: Locator;
+}
+
+export interface ClickOptions {
+  timeout?: number;
+  force?: boolean;
+  button?: "left" | "right" | "middle";
+  clickCount?: number;
+  delay?: number;
+  position?: { x: number; y: number };
+  modifiers?: Array<"Alt" | "Control" | "Meta" | "Shift">;
+}
+
+export interface TimeoutOption {
+  timeout?: number;
+}
+
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type WaitForState = "attached" | "detached" | "visible" | "hidden";
+
+// ────────────────────────────────────────────────────────────────────────
+// Chain model
+// ────────────────────────────────────────────────────────────────────────
+
+type Step =
+  | { m: "locator"; args: [string] }
+  | { m: "getByRole"; args: [string, GetByRoleOptions?] }
+  | { m: "getByText"; args: [string | RegExp, GetByTextOptions?] }
+  | { m: "getByLabel"; args: [string | RegExp, GetByTextOptions?] }
+  | { m: "getByPlaceholder"; args: [string | RegExp, GetByTextOptions?] }
+  | { m: "getByAltText"; args: [string | RegExp, GetByTextOptions?] }
+  | { m: "getByTitle"; args: [string | RegExp, GetByTextOptions?] }
+  | { m: "getByTestId"; args: [string] }
+  | { m: "filter"; args: [FilterOptions] }
+  | { m: "and"; args: [Locator] }
+  | { m: "or"; args: [Locator] }
+  | { m: "first"; args: [] }
+  | { m: "last"; args: [] }
+  | { m: "nth"; args: [number] };
+
+interface Chain {
+  steps: Step[];
+}
+
+interface InternalLocator extends Locator {
+  readonly [LOCATOR_BRAND]: true;
+  readonly [CHAIN]: Chain;
+}
+
+/** True if `x` is a spectest {@link Locator}. */
+export function isLocator(x: unknown): x is Locator {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    (x as Record<symbol, unknown>)[LOCATOR_BRAND] === true
+  );
+}
+
+function chainOf(loc: Locator): Chain {
+  return (loc as InternalLocator)[CHAIN];
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Lowering: chain → live playwright Locator
+// ────────────────────────────────────────────────────────────────────────
+
+/** Fold a chain onto a live page, producing a throwaway playwright Locator.
+ *  Nested spectest locators (`filter({has})`, `and`, `or`) are lowered
+ *  recursively against the same page. */
+export function lower(page: Page, chain: Chain): PWLocator {
+  let cur: Page | PWLocator = page;
+  for (const step of chain.steps) {
+    cur = applyStep(page, cur, step);
+  }
+  return cur as PWLocator;
+}
+
+function applyStep(page: Page, cur: Page | PWLocator, step: Step): PWLocator {
+  switch (step.m) {
+    case "locator":
+      return cur.locator(step.args[0]);
+    case "getByRole":
+      return cur.getByRole(
+        step.args[0] as Parameters<Page["getByRole"]>[0],
+        step.args[1],
+      );
+    case "getByText":
+      return cur.getByText(step.args[0], step.args[1]);
+    case "getByLabel":
+      return cur.getByLabel(step.args[0], step.args[1]);
+    case "getByPlaceholder":
+      return cur.getByPlaceholder(step.args[0], step.args[1]);
+    case "getByAltText":
+      return cur.getByAltText(step.args[0], step.args[1]);
+    case "getByTitle":
+      return cur.getByTitle(step.args[0], step.args[1]);
+    case "getByTestId":
+      return cur.getByTestId(step.args[0]);
+    case "filter": {
+      const o = step.args[0];
+      return (cur as PWLocator).filter({
+        hasText: o.hasText,
+        hasNotText: o.hasNotText,
+        has: o.has ? lower(page, chainOf(o.has)) : undefined,
+        hasNot: o.hasNot ? lower(page, chainOf(o.hasNot)) : undefined,
+      });
+    }
+    case "and":
+      return (cur as PWLocator).and(lower(page, chainOf(step.args[0])));
+    case "or":
+      return (cur as PWLocator).or(lower(page, chainOf(step.args[0])));
+    case "first":
+      return (cur as PWLocator).first();
+    case "last":
+      return (cur as PWLocator).last();
+    case "nth":
+      return (cur as PWLocator).nth(step.args[0]);
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Human labels (event `selector` field / dashboard timeline)
+// ────────────────────────────────────────────────────────────────────────
+
+function textArg(v: string | RegExp): string {
+  return v instanceof RegExp ? `/${v.source}/${v.flags}` : JSON.stringify(v);
+}
+
+function stepLabel(step: Step): string {
+  switch (step.m) {
+    case "locator":
+      return `css ${JSON.stringify(step.args[0])}`;
+    case "getByRole": {
+      const name = step.args[1]?.name;
+      return name !== undefined
+        ? `role ${step.args[0]} ${textArg(name)}`
+        : `role ${step.args[0]}`;
+    }
+    case "getByText":
+      return `text ${textArg(step.args[0])}`;
+    case "getByLabel":
+      return `label ${textArg(step.args[0])}`;
+    case "getByPlaceholder":
+      return `placeholder ${textArg(step.args[0])}`;
+    case "getByAltText":
+      return `alt ${textArg(step.args[0])}`;
+    case "getByTitle":
+      return `title ${textArg(step.args[0])}`;
+    case "getByTestId":
+      return `testid ${JSON.stringify(step.args[0])}`;
+    case "filter": {
+      const o = step.args[0];
+      if (o.has) return `filter(has: ${chainLabel(chainOf(o.has))})`;
+      if (o.hasNot) return `filter(hasNot: ${chainLabel(chainOf(o.hasNot))})`;
+      if (o.hasText !== undefined) return `filter(hasText: ${textArg(o.hasText)})`;
+      if (o.hasNotText !== undefined) return `filter(hasNotText: ${textArg(o.hasNotText)})`;
+      return "filter()";
+    }
+    case "and":
+      return `and(${chainLabel(chainOf(step.args[0]))})`;
+    case "or":
+      return `or(${chainLabel(chainOf(step.args[0]))})`;
+    case "first":
+      return ".first()";
+    case "last":
+      return ".last()";
+    case "nth":
+      return `.nth(${step.args[0]})`;
+  }
+}
+
+/** Short human label for a chain, e.g.
+ *  `role button "15" ‹ filter(has: text "July 2026") ‹ css .calendar`.
+ *  Root first; narrowing steps appended in reading order. */
+export function chainLabel(chain: Chain): string {
+  const [root, ...rest] = chain.steps;
+  if (!root) return "<empty>";
+  let out = stepLabel(root);
+  for (const s of rest) {
+    // first/last/nth read naturally appended ("… .first()"); the rest are
+    // narrowing relations, joined with a left-arrow.
+    out += s.m === "first" || s.m === "last" || s.m === "nth"
+      ? ` ${stepLabel(s)}`
+      : ` ‹ ${stepLabel(s)}`;
+  }
+  return out;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Backend + strategy seams
+// ────────────────────────────────────────────────────────────────────────
+
+/** The slice of the browser backend a locator needs. `pageOp` records one
+ *  browser event and (when `wrap`) provenance-wraps the result so a later
+ *  `expect(...)` nests under the step. `silentRead` runs a lowered read with
+ *  NO recording/drain — the poll path for `expect(locator)` matchers, which
+ *  must not emit one browser event per retry. */
+export interface LocatorBackend {
+  pageOp<T>(
+    action: string,
+    fields: Partial<RecordableFields>,
+    fn: (page: Page) => Promise<T>,
+    opts?: { wrap?: boolean },
+  ): Promise<T>;
+  silentRead<T>(fn: (page: Page) => Promise<T>): Promise<T>;
+  /** CDP touch tap with press dwell (mobile only). */
+  rawTap(x: number, y: number, durationMs?: number): Promise<void>;
+  /** Record ONE settled browser event for an `expect(locator)` matcher (label
+   *  + session seek point) and return its seq, so the assertion nests under it.
+   *  See {@link "./browser".MobileBackend.recordSettled}. */
+  recordSettled(
+    action: string,
+    fields: Partial<RecordableFields>,
+    waitedMs: number,
+    error?: string,
+  ): Promise<number | undefined>;
+}
+
+/** Silent (non-recorded) reads a locator exposes for `expect(...)` matchers to
+ *  poll. See {@link getLocatorProbe}. */
+export interface LocatorProbe {
+  /** Human label of the locator (for failure messages). */
+  readonly label: string;
+  isVisible(): Promise<boolean>;
+  textContent(timeout?: number): Promise<string | null>;
+  inputValue(timeout?: number): Promise<string>;
+  count(): Promise<number>;
+  isEnabled(timeout?: number): Promise<boolean>;
+  isChecked(timeout?: number): Promise<boolean>;
+  /** After the silent poll settles, emit the single settled browser step this
+   *  locator's `expect(...)` matcher assertion nests under, and return its seq
+   *  (provenance + replay seek). `action` is the matcher name, `waitedMs` the
+   *  poll time, `error` marks the step failed on a timed-out matcher. Returns
+   *  `undefined` when nothing is recording. */
+  settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+}
+
+/** Silent (non-recorded) reads an `expect(browser)` matcher polls — the
+ *  session twin of {@link LocatorProbe}. Lives here, next to it, so `index.ts`
+ *  can reach both seams without importing `browser.ts` (and with it
+ *  playwright) at runtime. */
+export interface BrowserProbe {
+  /** Current main-frame URL. Synchronous, unrecorded, no rrweb drain. */
+  url(): string;
+  /** After the silent poll settles, emit the single settled browser step the
+   *  matcher's assertion nests under, and return its seq. Same contract as
+   *  {@link LocatorProbe.settle}. */
+  settle(action: string, waitedMs: number, error?: string): Promise<number | undefined>;
+}
+
+const PROBE: unique symbol = Symbol.for("spectest.locatorProbe");
+const BROWSER_PROBE: unique symbol = Symbol.for("spectest.browserProbe");
+
+/** Brand a browser/mobile session with its {@link BrowserProbe}. */
+export function attachBrowserProbe<T extends object>(session: T, probe: BrowserProbe): T {
+  (session as unknown as Record<symbol, BrowserProbe>)[BROWSER_PROBE] = probe;
+  return session;
+}
+
+/** True if `x` is a spectest browser/mobile session (i.e. probe-branded). */
+export function isBrowserSession(x: unknown): boolean {
+  return typeof x === "object" && x !== null && BROWSER_PROBE in x;
+}
+
+/** The probe branded onto a browser/mobile session by `buildBackend`. */
+export function getBrowserProbe(session: unknown): BrowserProbe {
+  return (session as Record<symbol, BrowserProbe>)[BROWSER_PROBE];
+}
+
+/** The silent-read probe for a locator — the seam `expect(locator)` matchers
+ *  poll (in index.ts) without pulling playwright types or the backend into
+ *  that module. */
+export function getLocatorProbe(loc: Locator): LocatorProbe {
+  return (loc as unknown as Record<symbol, LocatorProbe>)[PROBE];
+}
+
+/** Per-session flavor of the `tap()` gesture. Desktop and mobile differ only
+ *  here; every other locator method is platform-agnostic. */
+export interface ActionStrategy {
+  /** Whether this session supports touch. Desktop → `tap()` throws. */
+  readonly touch: boolean;
+  /** Perform a touch tap on the resolved element (mobile only). `rec` is the
+   *  gesture's own step, still open — see {@link stampActionPoint}. */
+  tap(
+    backend: LocatorBackend,
+    loc: PWLocator,
+    opts?: { timeout?: number; duration?: number },
+    rec?: Partial<RecordableFields>,
+  ): Promise<void>;
+}
+
+/** Desktop: no touchscreen. `tap()` is a mobile gesture — steer authors to
+ *  `click()`. */
+export const desktopStrategy: ActionStrategy = {
+  touch: false,
+  async tap() {
+    throw new Error(
+      "tap() is a mobile-session gesture (ctx.mobile). On a desktop ctx.browser() session use click().",
+    );
+  },
+};
+
+/** Mobile: resolve the element's center and dispatch a real CDP touch with
+ *  the press dwell RN Pressables need (playwright's `tap()` has no dwell). */
+export const mobileStrategy: ActionStrategy = {
+  touch: true,
+  async tap(backend, loc, opts, rec) {
+    await loc.waitFor({ state: "visible", timeout: opts?.timeout });
+    await loc.scrollIntoViewIfNeeded({ timeout: opts?.timeout });
+    const box = await loc.boundingBox();
+    if (!box) throw new Error("tap: element vanished before it could be tapped");
+    const x = box.x + box.width / 2;
+    const y = box.y + box.height / 2;
+    // Exact, no probe needed: this IS the point the touch is dispatched at,
+    // measured after the scroll. Same field the replay reads — see
+    // stampActionPoint.
+    if (rec) {
+      rec.x = Math.round(x);
+      rec.y = Math.round(y);
+    }
+    await backend.rawTap(x, y, opts?.duration);
+  },
+};
+
+/** How long the click-point probe waits for the element. Short on purpose:
+ *  either it is already on screen and the answer is one round trip away, or
+ *  the action's own actionability wait — with the author's timeout and a real
+ *  error message — is the one that should report it. */
+const POINT_PROBE_MS = 250;
+
+/** Stamp the viewport point an action is about to act on onto its (still
+ *  open) step, as the `x`/`y` a raw `browser.clickAt` records.
+ *
+ *  The replay cursor is normally positioned from rrweb's own recorded mouse
+ *  events — but a click that navigates loses them. The page-side event buffer
+ *  lives on `window`, so everything the click emitted dies with the document
+ *  before the post-op drain can collect it, and the step arrives carrying only
+ *  the destination page's load. The step's own coordinates are then the sole
+ *  record of where the click landed; without them the viewer has nothing to
+ *  put the cursor on.
+ *
+ *  Best-effort in every direction. A probe failure (not attached yet, strict
+ *  violation, frame detached) leaves the step unstamped and lets the action
+ *  itself report the problem. We only stamp a centre that is inside the
+ *  viewport of the top-level document, because that is exactly the case where
+ *  playwright clicks the element where it currently sits — one that is
+ *  off-screen (or in an iframe, whose rect is frame-relative) gets scrolled
+ *  into view first, which moves the point we measured. */
+async function stampActionPoint(
+  loc: PWLocator,
+  rec: Partial<RecordableFields>,
+  position?: { x: number; y: number },
+): Promise<void> {
+  try {
+    const pt = await loc.evaluate(
+      (el, pos) => {
+        if (window.top !== window) return null;
+        const r = el.getBoundingClientRect();
+        if (!r.width || !r.height) return null;
+        // Playwright clicks the element's centre unless the caller named a
+        // point — which it takes relative to the PADDING box, so an element
+        // with a border (a plain `<button>` has 2px of it) sits that far off
+        // the rect we measured.
+        const cs = pos ? getComputedStyle(el) : null;
+        const x = cs ? r.left + parseFloat(cs.borderLeftWidth) + pos!.x : r.left + r.width / 2;
+        const y = cs ? r.top + parseFloat(cs.borderTopWidth) + pos!.y : r.top + r.height / 2;
+        const onScreen =
+          x >= 0 && y >= 0 && x <= window.innerWidth && y <= window.innerHeight;
+        return onScreen ? { x, y } : null;
+      },
+      position,
+      { timeout: POINT_PROBE_MS },
+    );
+    if (pt) {
+      rec.x = Math.round(pt.x);
+      rec.y = Math.round(pt.y);
+    }
+  } catch {
+    /* Element not ready / gone / strict violation — the action reports it. */
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// The Locator interface
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * A lazy reference to element(s), resolved with auto-waiting at the moment an
+ * action runs. Mirrors playwright-core's `Locator`: STRICT by default — a
+ * locator resolving to multiple elements throws a strict-mode violation at
+ * action time rather than silently acting on one. Narrow with `exact: true`,
+ * a testid, `filter(...)`, or the explicit `first()`/`last()`/`nth(i)`
+ * opt-outs.
+ */
+export interface Locator {
+  // ── Composition (lazy; return a new Locator) ──────────────────────────
+  /** Descendant CSS query, scoped to this locator's subtree. */
+  locator(css: string): Locator;
+  getByRole(role: string, opts?: GetByRoleOptions): Locator;
+  getByText(text: string | RegExp, opts?: GetByTextOptions): Locator;
+  getByLabel(text: string | RegExp, opts?: GetByTextOptions): Locator;
+  getByPlaceholder(text: string | RegExp, opts?: GetByTextOptions): Locator;
+  getByAltText(text: string | RegExp, opts?: GetByTextOptions): Locator;
+  getByTitle(text: string | RegExp, opts?: GetByTextOptions): Locator;
+  getByTestId(testId: string): Locator;
+  /** Narrow the current match set by content or by a descendant locator. */
+  filter(opts: FilterOptions): Locator;
+  /** Intersect with another locator (both must match the same element). */
+  and(other: Locator): Locator;
+  /** Union with another locator (either may match). */
+  or(other: Locator): Locator;
+  /** Explicit strict-mode opt-out: the first resolved element. */
+  first(): Locator;
+  /** Explicit strict-mode opt-out: the last resolved element. */
+  last(): Locator;
+  /** Explicit strict-mode opt-out: the i-th resolved element (0-based). */
+  nth(index: number): Locator;
+
+  // ── Actions (auto-wait; default 5s, `{ timeout }` overrides) ──────────
+  click(opts?: ClickOptions): Promise<void>;
+  dblclick(opts?: ClickOptions): Promise<void>;
+  /** Touch-tap (mobile sessions only; throws on desktop). `duration`
+   *  overrides the press dwell. */
+  tap(opts?: { timeout?: number; duration?: number }): Promise<void>;
+  /** Set an input/textarea's value (React-safe: native setter + input event). */
+  fill(value: string, opts?: TimeoutOption): Promise<void>;
+  /** Clear an input's value (`fill("")`). */
+  clear(opts?: TimeoutOption): Promise<void>;
+  /** Focus and press a single key or chord (`"Enter"`, `"Control+A"`). */
+  press(key: string, opts?: TimeoutOption): Promise<void>;
+  /** Focus and type character-by-character (fires keydown/keyup per char). */
+  pressSequentially(text: string, opts?: { timeout?: number; delay?: number }): Promise<void>;
+  check(opts?: TimeoutOption): Promise<void>;
+  uncheck(opts?: TimeoutOption): Promise<void>;
+  setChecked(checked: boolean, opts?: TimeoutOption): Promise<void>;
+  /** Select `<option>`(s) by value/label/index; returns the selected values,
+   *  provenance-wrapped so `expect(...)` on them nests under this step. */
+  selectOption(
+    values: string | string[] | { label?: string; value?: string; index?: number },
+    opts?: TimeoutOption,
+  ): Promise<Wrapped<string[]>>;
+  hover(opts?: TimeoutOption): Promise<void>;
+  focus(opts?: TimeoutOption): Promise<void>;
+  blur(opts?: TimeoutOption): Promise<void>;
+  scrollIntoViewIfNeeded(opts?: TimeoutOption): Promise<void>;
+  dragTo(target: Locator, opts?: TimeoutOption): Promise<void>;
+
+  // ── Reads (wrapped so `expect(...)` nests under the step) ─────────────
+  textContent(opts?: TimeoutOption): Promise<Wrapped<string | null>>;
+  innerText(opts?: TimeoutOption): Promise<Wrapped<string>>;
+  innerHTML(opts?: TimeoutOption): Promise<Wrapped<string>>;
+  inputValue(opts?: TimeoutOption): Promise<Wrapped<string>>;
+  getAttribute(name: string, opts?: TimeoutOption): Promise<Wrapped<string | null>>;
+  isVisible(): Promise<Wrapped<boolean>>;
+  isHidden(): Promise<Wrapped<boolean>>;
+  isEnabled(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+  isDisabled(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+  isChecked(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+  isEditable(opts?: TimeoutOption): Promise<Wrapped<boolean>>;
+  count(): Promise<Wrapped<number>>;
+  /** Resolve to one locator per current match (handle-free — each is pinned
+   *  with `nth(i)`). One recorded event. */
+  all(): Promise<Locator[]>;
+  allTextContents(): Promise<Wrapped<string[]>>;
+  allInnerTexts(): Promise<Wrapped<string[]>>;
+  boundingBox(opts?: TimeoutOption): Promise<Wrapped<BoundingBox | null>>;
+  /** Evaluate a function against the resolved element. `description` labels
+   *  the step in the timeline (spectest keeps it for readability). */
+  evaluate<T = unknown>(
+    description: string,
+    fn: string | ((el: Element, arg?: unknown) => T),
+    arg?: unknown,
+  ): Promise<Wrapped<T>>;
+
+  /** Wait until the element reaches `state` (default `"visible"`). */
+  waitFor(opts?: { state?: WaitForState; timeout?: number }): Promise<void>;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Factory
+// ────────────────────────────────────────────────────────────────────────
+
+/** Build a lazy {@link Locator} over `chain`. `backend`/`strategy` are the
+ *  session seams; composition methods extend the chain, terminal methods run
+ *  through `backend.pageOp`. */
+export function makeLocator(
+  backend: LocatorBackend,
+  strategy: ActionStrategy,
+  chain: Chain,
+): Locator {
+  const label = chainLabel(chain);
+  const extend = (step: Step): Locator =>
+    makeLocator(backend, strategy, { steps: [...chain.steps, step] });
+
+  // One recorded event, result NOT wrapped (void/action).
+  const act = <T>(
+    action: string,
+    fields: Partial<RecordableFields>,
+    fn: (loc: PWLocator, page: Page) => Promise<T>,
+  ): Promise<T> =>
+    backend.pageOp(action, { selector: label, ...fields }, (page) =>
+      fn(lower(page, chain), page),
+    );
+
+  // One recorded event whose fields the action itself finishes filling in:
+  // `rec` is the very object the recorder spreads once `fn` resolves (the
+  // same mutate-in-flight seam `screenshot`'s artifact id rides), so the
+  // click family can stamp the point it acted on. See stampActionPoint.
+  const actAt = <T>(
+    action: string,
+    fn: (loc: PWLocator, rec: Partial<RecordableFields>) => Promise<T>,
+  ): Promise<T> => {
+    const rec: Partial<RecordableFields> = { selector: label };
+    return backend.pageOp(action, rec, (page) => fn(lower(page, chain), rec));
+  };
+
+  // One recorded event, result provenance-wrapped for expect().
+  const read = <T>(
+    action: string,
+    fn: (loc: PWLocator) => Promise<T>,
+    fields: Partial<RecordableFields> = {},
+  ): Promise<Wrapped<T>> =>
+    backend.pageOp(action, { selector: label, ...fields }, (page) => fn(lower(page, chain)), {
+      wrap: true,
+    }) as Promise<Wrapped<T>>;
+
+  // Silent, non-recorded reads for expect(locator) matchers to poll.
+  const probe: LocatorProbe = {
+    label,
+    isVisible: () => backend.silentRead((page) => lower(page, chain).isVisible()),
+    textContent: (timeout) => backend.silentRead((page) => lower(page, chain).textContent({ timeout })),
+    inputValue: (timeout) => backend.silentRead((page) => lower(page, chain).inputValue({ timeout })),
+    count: () => backend.silentRead((page) => lower(page, chain).count()),
+    isEnabled: (timeout) => backend.silentRead((page) => lower(page, chain).isEnabled({ timeout })),
+    isChecked: (timeout) => backend.silentRead((page) => lower(page, chain).isChecked({ timeout })),
+    settle: (action, waitedMs, error) =>
+      backend.recordSettled(action, { selector: label }, waitedMs, error),
+  };
+
+  const loc: InternalLocator = {
+    [LOCATOR_BRAND]: true,
+    [CHAIN]: chain,
+
+    // composition
+    locator: (css) => extend({ m: "locator", args: [css] }),
+    getByRole: (role, opts) => extend({ m: "getByRole", args: [role, opts] }),
+    getByText: (text, opts) => extend({ m: "getByText", args: [text, opts] }),
+    getByLabel: (text, opts) => extend({ m: "getByLabel", args: [text, opts] }),
+    getByPlaceholder: (text, opts) => extend({ m: "getByPlaceholder", args: [text, opts] }),
+    getByAltText: (text, opts) => extend({ m: "getByAltText", args: [text, opts] }),
+    getByTitle: (text, opts) => extend({ m: "getByTitle", args: [text, opts] }),
+    getByTestId: (id) => extend({ m: "getByTestId", args: [id] }),
+    filter: (opts) => extend({ m: "filter", args: [opts] }),
+    and: (other) => extend({ m: "and", args: [other] }),
+    or: (other) => extend({ m: "or", args: [other] }),
+    first: () => extend({ m: "first", args: [] }),
+    last: () => extend({ m: "last", args: [] }),
+    nth: (i) => extend({ m: "nth", args: [i] }),
+
+    // actions
+    click: (opts) =>
+      actAt("click", async (l, rec) => {
+        await stampActionPoint(l, rec, opts?.position);
+        return l.click(opts);
+      }),
+    dblclick: (opts) =>
+      actAt("dblclick", async (l, rec) => {
+        await stampActionPoint(l, rec, opts?.position);
+        return l.dblclick(opts);
+      }),
+    tap: (opts) => actAt("tap", (l, rec) => strategy.tap(backend, l, opts, rec)),
+    fill: (value, opts) => {
+      const t = truncateUtf8(value);
+      return act("fill", { text: t.value, textTruncated: t.truncated }, (l) =>
+        l.fill(value, { timeout: opts?.timeout }),
+      );
+    },
+    clear: (opts) => act("clear", {}, (l) => l.clear({ timeout: opts?.timeout })),
+    press: (key, opts) => act("press", { key }, (l) => l.press(key, { timeout: opts?.timeout })),
+    pressSequentially: (text, opts) => {
+      const t = truncateUtf8(text);
+      return act("pressSequentially", { text: t.value, textTruncated: t.truncated }, (l) =>
+        l.pressSequentially(text, { timeout: opts?.timeout, delay: opts?.delay }),
+      );
+    },
+    check: (opts) => act("check", {}, (l) => l.check({ timeout: opts?.timeout })),
+    uncheck: (opts) => act("uncheck", {}, (l) => l.uncheck({ timeout: opts?.timeout })),
+    setChecked: (checked, opts) =>
+      act("setChecked", {}, (l) => l.setChecked(checked, { timeout: opts?.timeout })),
+    selectOption: (values, opts) =>
+      read("selectOption", (l) => l.selectOption(values as never, { timeout: opts?.timeout })),
+    hover: (opts) => act("hover", {}, (l) => l.hover({ timeout: opts?.timeout })),
+    focus: (opts) => act("focus", {}, (l) => l.focus({ timeout: opts?.timeout })),
+    blur: (opts) => act("blur", {}, (l) => l.blur({ timeout: opts?.timeout })),
+    scrollIntoViewIfNeeded: (opts) =>
+      act("scrollIntoViewIfNeeded", {}, (l) => l.scrollIntoViewIfNeeded({ timeout: opts?.timeout })),
+    dragTo: (target, opts) =>
+      act("dragTo", {}, (l, page) => l.dragTo(lower(page, chainOf(target)), { timeout: opts?.timeout })),
+
+    // reads
+    textContent: (opts) => read("textContent", (l) => l.textContent({ timeout: opts?.timeout })),
+    innerText: (opts) => read("innerText", (l) => l.innerText({ timeout: opts?.timeout })),
+    innerHTML: (opts) => read("innerHTML", (l) => l.innerHTML({ timeout: opts?.timeout })),
+    inputValue: (opts) => read("inputValue", (l) => l.inputValue({ timeout: opts?.timeout })),
+    getAttribute: (name, opts) =>
+      read("getAttribute", (l) => l.getAttribute(name, { timeout: opts?.timeout }), {
+        attribute: name,
+      }),
+    isVisible: () => read("isVisible", (l) => l.isVisible()),
+    isHidden: () => read("isHidden", (l) => l.isHidden()),
+    isEnabled: (opts) => read("isEnabled", (l) => l.isEnabled({ timeout: opts?.timeout })),
+    isDisabled: (opts) => read("isDisabled", (l) => l.isDisabled({ timeout: opts?.timeout })),
+    isChecked: (opts) => read("isChecked", (l) => l.isChecked({ timeout: opts?.timeout })),
+    isEditable: (opts) => read("isEditable", (l) => l.isEditable({ timeout: opts?.timeout })),
+    count: () => read("count", (l) => l.count()),
+    allTextContents: () => read("allTextContents", (l) => l.allTextContents()),
+    allInnerTexts: () => read("allInnerTexts", (l) => l.allInnerTexts()),
+    boundingBox: (opts) => read("boundingBox", (l) => l.boundingBox({ timeout: opts?.timeout })),
+    async all() {
+      // count() lowered once (one event), then one child locator per match,
+      // each pinned with nth(i). Stays lazy + handle-free.
+      const n = await act("all", {}, (l) => l.count());
+      const out: Locator[] = [];
+      for (let i = 0; i < n; i++) out.push(extend({ m: "nth", args: [i] }));
+      return out;
+    },
+    evaluate: (description, fn, arg) =>
+      backend.pageOp(
+        "evaluate",
+        { selector: label, description },
+        (page) => lower(page, chain).evaluate(fn as never, arg),
+        { wrap: true },
+      ) as Promise<Wrapped<never>>,
+
+    waitFor: (opts) =>
+      act("waitFor", {}, (l) => l.waitFor({ state: opts?.state, timeout: opts?.timeout })),
+  };
+  // Attach the silent-read probe under its symbol (kept off the typed literal
+  // so declaration order stays simple).
+  (loc as unknown as Record<symbol, LocatorProbe>)[PROBE] = probe;
+  return loc;
+}