@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/docs/superpowers/plans/2026-09-29-auto-wait.md

@@ -1,1827 +0,0 @@
-# Auto-Waiting Actions Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `Locator.click()`, `fill()` and `focus()` wait until the element is ready for that action (with a clear error naming the unmet check), add `waitFor()`, `isEnabled()`, `isEditable()` and a `force` option, and share one retry mechanism with `expect`.
-
-**Architecture:** A generic `waitUntil(probe, isDone, { timeout })` loop (`src/wait/wait-until.ts`) replaces the polling loop inside `expect.ts`. For actions, each poll runs one browser script (`src/locator/element-state.ts`) that returns the element's full state (attached, visible, enabled, editable, box, hit target) as JSON; Node evaluates the per-action checks (stability = same box on two consecutive polls) and, once all pass, performs a real BiDi pointer click at the centre of the latest box. Timeouts throw `ActionTimeoutError` with a per-check ✓/✗/— summary.
-
-**Tech Stack:** TypeScript (`module: nodenext`, `strict`, `verbatimModuleSyntax`, `noUncheckedIndexedAccess`), tsx, Node 26 `node:test` + `node:assert/strict`, WebDriver BiDi (`script.evaluate`, `input.performActions`), Firefox.
-
-**Spec:** `docs/superpowers/specs/2026-09-29-auto-wait-design.md`
-
-## Global Constraints
-
-- Execute on a new branch `feat/auto-wait` created from the current `feat/expect` HEAD (it builds on the `expect` feature and its fix wave).
-- No new dependencies. Relative imports use the `.js` extension; type-only imports use `import type`.
-- Timeout resolution everywhere: per-call `{ timeout }` → config `expect.timeout` → `5000` ms. Poll interval `100` ms.
-- Check names, in this order when present: `attached`, `visible`, `stable`, `enabled`, `editable`, `hit target`. Symbols: `✓` pass, `✗` fail, `—` pending (not evaluated because an earlier check failed).
-- Per action: `click` → attached, visible, stable, enabled, hit target (probe scrolls + hit-tests); `fill` → attached, visible, enabled, editable, hit target (probe scrolls + hit-tests); `focus` → attached (no scroll, no hit test); `force: true` → only `attached` (probe still scrolls for click/fill).
-- `click()` and `fill()` click with real BiDi pointer input at the centre of the **latest** probed box; `click()` / `focus()` resolve to `undefined`.
-- Error messages (exact):
-  - `<action>(): could not read <selector> within <timeout>ms`
-  - `<action>(): <selector> was not attached within <timeout>ms`
-  - `<action>(): <selector> was not actionable within <timeout>ms\n  <name> <symbol>  <name> <symbol> …` with `hit target ✗ (covered by <description>)` when covered
-  - `waitFor(): <selector> did not become <state> within <timeout>ms`
-- Unit tests (`npm test`, glob `src/**/*.test.ts`) never launch a browser and always pass an explicit `timeout` (so `samurai.config.ts` is never read). Browser tests live only in `*.browser-test.ts` files and run via `npm run test:browser`.
-- Never run `bun run dev` / `npm run dev` (it submits a real contact form).
-- `npx tsc --noEmit -p .` must show no errors other than the pre-existing `src/config/default.ts(3,14): error TS2739`. Ignore tsx's `DeprecationWarning: module.register()` (DEP0205); any other warning (e.g. unhandled rejection) is a defect.
-- Never stage `result/report.json` or `src/tests/index.spec.ts` (the user has uncommitted changes there); stage explicit paths only.
-- Every commit message ends with a blank line and `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
-
----
-
-## File Structure
-
-| File | Status | Responsibility |
-|---|---|---|
-| `src/wait/wait-until.ts` | create | `waitUntil`, `resolveTimeout`, `WaitTimeoutError` — the one retry loop |
-| `src/wait/wait-until.test.ts` | create | unit tests for the loop |
-| `src/assert/expect.ts` | modify | `assertEventually` rewritten on `waitUntil`; own loop, `readBefore`, `DEADLINE`, `resolveTimeout` removed |
-| `src/locator/element-state.ts` | create | browser probe script, `parseElementState`, check evaluation, shared types |
-| `src/locator/element-state.test.ts` | create | unit tests |
-| `src/locator/action-timeout-error.ts` | create | `ActionTimeoutError` and its message format |
-| `src/locator/action-timeout-error.test.ts` | create | unit tests |
-| `src/locator/locator.ts` | modify | waiting `click`/`fill`/`focus`, `force`, `waitFor`, `isEnabled`, `isEditable`, `clickRect` param widened |
-| `src/locator/locator-actions.test.ts` | create | action/wait unit tests against the stub connector |
-| `src/locator/locator.test.ts` | modify | three existing tests adapted to the probing `click`/`fill` |
-| `src/testing/stub-connector.ts` | modify | also answers `browsingContext.navigate` |
-| `src/browser/page.ts` | modify | `navigateTo` keeps URLs that already have a scheme |
-| `src/browser/page.test.ts` | create | unit test for `navigateTo` |
-| `src/testing/browser-fixture.ts` | create | `setContent(page, html, setup)` for browser tests |
-| `src/locator/locator.browser-test.ts` | create | opt-in headless-Firefox tests |
-| `package.json` | modify | `test:browser` script |
-
----
-
-### Task 1: `waitUntil` retry loop
-
-**Files:**
-- Create: `src/wait/wait-until.ts`
-- Test: `src/wait/wait-until.test.ts`
-
-**Interfaces:**
-- Consumes: `readConfig("expect")` from `src/config/config.ts` (`Promise<{ timeout?: number } | undefined>`).
-- Produces:
-  - `export interface WaitOptions { timeout: number; interval?: number }`
-  - `export class WaitTimeoutError<T> extends Error { readonly timeout: number; readonly last: T | undefined }` (`name === "WaitTimeoutError"`)
-  - `export function resolveTimeout(perCall?: number): Promise<number>`
-  - `export function waitUntil<T>(probe: () => Promise<T>, isDone: (current: T, previous: T | undefined) => boolean, options: WaitOptions): Promise<T>`
-
-- [ ] **Step 1: Write the failing test**
-
-Create `src/wait/wait-until.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { resolveTimeout, waitUntil, WaitTimeoutError } from "./wait-until.js";
-
-/** Probe returning the given values in order; the last one repeats */
-function sequence<T>(...values: T[]) {
-  let calls = 0;
-  const probe = async () => values[Math.min(calls++, values.length - 1)]!;
-  return { probe, calls: () => calls };
-}
-
-test("probes until isDone and resolves with that value", async () => {
-  const { probe, calls } = sequence(1, 2, 3);
-  assert.equal(await waitUntil(probe, (value) => value === 3, { timeout: 2000 }), 3);
-  assert.equal(calls(), 3);
-});
-
-test("passes the previous value to isDone", async () => {
-  const { probe } = sequence(1, 2, 2);
-  const seen: Array<[number, number | undefined]> = [];
-  await waitUntil(
-    probe,
-    (current, previous) => {
-      seen.push([current, previous]);
-      return current === previous;
-    },
-    { timeout: 2000 },
-  );
-  assert.deepEqual(seen, [
-    [1, undefined],
-    [2, 1],
-    [2, 2],
-  ]);
-});
-
-test("times out with the last value, ending at the deadline", async () => {
-  const { probe, calls } = sequence("a", "b");
-  const start = Date.now();
-  await assert.rejects(waitUntil(probe, () => false, { timeout: 250 }), (err) => {
-    assert.ok(err instanceof WaitTimeoutError);
-    assert.equal(err.name, "WaitTimeoutError");
-    assert.equal(err.timeout, 250);
-    assert.equal(err.last, "b");
-    return true;
-  });
-  const elapsed = Date.now() - start;
-  // probes at ~0, ~100, ~200; the final sleep is clamped to the ~50ms left, and no probe starts after the deadline
-  assert.ok(elapsed >= 250 && elapsed < 295, `elapsed ${elapsed}ms`);
-  assert.equal(calls(), 3);
-});
-
-test("timeout 0 probes exactly once", async () => {
-  const { probe, calls } = sequence(false);
-  await assert.rejects(waitUntil(probe, (value) => value, { timeout: 0 }), WaitTimeoutError);
-  assert.equal(calls(), 1);
-});
-
-test("timeout 0 resolves when the single probe is done", async () => {
-  const { probe } = sequence(true);
-  assert.equal(await waitUntil(probe, (value) => value, { timeout: 0 }), true);
-});
-
-test("probe errors are rethrown without retrying", async () => {
-  let calls = 0;
-  const probe = async () => {
-    calls++;
-    throw new Error("boom");
-  };
-  await assert.rejects(waitUntil(probe, () => true, { timeout: 2000 }), /boom/);
-  assert.equal(calls, 1);
-});
-
-test("a probe that never settles stops at the deadline", async () => {
-  const start = Date.now();
-  await assert.rejects(
-    waitUntil(() => new Promise<never>(() => {}), () => true, { timeout: 200 }),
-    (err) => {
-      assert.ok(err instanceof WaitTimeoutError);
-      assert.equal(err.last, undefined);
-      return true;
-    },
-  );
-  assert.ok(Date.now() - start < 400);
-});
-
-test("a probe that hangs after earlier results reports the last completed value", async () => {
-  let calls = 0;
-  const probe = () => (calls++ === 0 ? Promise.resolve("first") : new Promise<string>(() => {}));
-  await assert.rejects(waitUntil(probe, () => false, { timeout: 200 }), (err) => {
-    assert.ok(err instanceof WaitTimeoutError);
-    assert.equal(err.last, "first");
-    return true;
-  });
-});
-
-test("no timer outlives a resolved wait", async () => {
-  const timers = () => process.getActiveResourcesInfo().filter((name) => name === "Timeout").length;
-  const before = timers();
-  await waitUntil(async () => true, (value) => value, { timeout: 10000 });
-  assert.equal(timers(), before);
-});
-
-test("resolveTimeout prefers the per-call value", async () => {
-  assert.equal(await resolveTimeout(1234), 1234);
-  assert.equal(await resolveTimeout(0), 0);
-});
-```
-
-- [ ] **Step 2: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `Cannot find module '.../src/wait/wait-until.js'`; the other 48 tests still pass.
-
-- [ ] **Step 3: Implement**
-
-Create `src/wait/wait-until.ts`:
-
-```ts
-import { setTimeout as sleep } from "node:timers/promises";
-import { readConfig } from "../config/config.js";
-
-const DEFAULT_TIMEOUT = 5000;
-const DEFAULT_INTERVAL = 100;
-
-export interface WaitOptions {
-  /** Total time (ms) to keep probing; 0 probes exactly once */
-  timeout: number;
-  /** Time (ms) between probes. @default 100 */
-  interval?: number;
-}
-
-export class WaitTimeoutError<T> extends Error {
-  public readonly timeout: number;
-  /** Last completed probe result; undefined when no probe completed */
-  public readonly last: T | undefined;
-
-  constructor(timeout: number, last: T | undefined) {
-    super(`Condition not met within ${timeout}ms`);
-    this.name = "WaitTimeoutError";
-    this.timeout = timeout;
-    this.last = last;
-  }
-}
-
-/** Per-call timeout, else config `expect.timeout`, else 5000 */
-export async function resolveTimeout(perCall?: number): Promise<number> {
-  if (perCall !== undefined) return perCall;
-  return (await readConfig("expect"))?.timeout ?? DEFAULT_TIMEOUT;
-}
-
-const DEADLINE = Symbol("deadline");
-
-/**
- * Races `probe()` against the time left. Resolves `{ value }` when the probe wins,
- * DEADLINE when the time runs out first; probe errors reject as-is.
- */
-function probeBefore<T>(
-  probe: () => Promise<T>,
-  remaining: number,
-): Promise<{ value: T } | typeof DEADLINE> {
-  const probing = probe();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const expired = new Promise<typeof DEADLINE>((resolve) => {
-    timer = setTimeout(() => resolve(DEADLINE), remaining);
-  });
-  // A probe that loses the race may still fail later; nobody is waiting for it any more
-  probing.catch(() => {});
-  return Promise.race([probing.then((value) => ({ value })), expired]).finally(() =>
-    clearTimeout(timer),
-  );
-}
-
-/**
- * Probes until `isDone(current, previous)` is true and resolves with that result.
- * Always probes at least once; with `timeout > 0` every probe races the time left.
- * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
- */
-export async function waitUntil<T>(
-  probe: () => Promise<T>,
-  isDone: (current: T, previous: T | undefined) => boolean,
-  { timeout, interval = DEFAULT_INTERVAL }: WaitOptions,
-): Promise<T> {
-  const deadline = Date.now() + timeout;
-  let previous: T | undefined;
-
-  for (let first = true; ; first = false) {
-    const remaining = deadline - Date.now();
-    // Only start a probe while time remains; a later one could only lose the race
-    if (!first && remaining <= 0) throw new WaitTimeoutError(timeout, previous);
-
-    // timeout 0 keeps the single probe un-raced so it always completes
-    const result = timeout > 0 ? await probeBefore(probe, remaining) : { value: await probe() };
-    if (result === DEADLINE) throw new WaitTimeoutError(timeout, previous);
-    if (isDone(result.value, previous)) return result.value;
-    previous = result.value;
-
-    const left = deadline - Date.now();
-    if (left <= 0) throw new WaitTimeoutError(timeout, previous);
-    await sleep(Math.min(interval, left));
-  }
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `npm test` (three times — the timing test must be stable)
-Expected: `ℹ pass 58`, `ℹ fail 0` each run.
-
-- [ ] **Step 5: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/wait/wait-until.ts src/wait/wait-until.test.ts
-git commit -m "feat(wait): add shared waitUntil retry loop"
-```
-
----
-
-### Task 2: Run `expect` locator assertions on `waitUntil`
-
-**Files:**
-- Modify: `src/assert/expect.ts`
-
-**Interfaces:**
-- Consumes: `waitUntil`, `WaitTimeoutError`, `resolveTimeout` from `../wait/wait-until.js` (Task 1).
-- Produces: no API change. `expect.ts` exports stay exactly: `takePendingAssertions`, `LocatorAssertionOptions`, `ValueAssertions`, `LocatorAssertions`, `expect`.
-
-This is a behaviour-preserving refactor: the existing `src/assert/expect-locator.test.ts` and `src/assert/expect.test.ts` are the tests. Do not change any test file in this task.
-
-- [ ] **Step 1: Confirm the baseline is green**
-
-Run: `npm test`
-Expected: `ℹ pass 58`, `ℹ fail 0`.
-
-- [ ] **Step 2: Replace the imports and remove the old loop pieces**
-
-In `src/assert/expect.ts`:
-
-a) Replace the first five import lines
-
-```ts
-import { isDeepStrictEqual } from "node:util";
-import { setTimeout as sleep } from "node:timers/promises";
-import { AssertionError } from "./assertion-error.js";
-import Locator from "../locator/locator.js";
-import { readConfig } from "../config/config.js";
-```
-
-with
-
-```ts
-import { isDeepStrictEqual } from "node:util";
-import { AssertionError } from "./assertion-error.js";
-import Locator from "../locator/locator.js";
-import { resolveTimeout, waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
-```
-
-b) Delete these declarations entirely (they now live in `wait-until.ts` or are no longer needed):
-- `const DEFAULT_EXPECT_TIMEOUT = 5000;`
-- `const POLL_INTERVAL = 100;`
-- the `async function resolveTimeout(options?: LocatorAssertionOptions) { … }` function
-- `const DEADLINE = Symbol("deadline");`
-- the `readBefore` function and its doc comment
-
-Keep `LocatorAssertionOptions` (its doc comment stays accurate).
-
-- [ ] **Step 3: Rewrite `assertEventually`**
-
-Replace the whole `private assertEventually<V>(…) { … }` method in `LocatorAssertions` with:
-
-```ts
-  /** Re-reads the element until `check` passes or the timeout expires */
-  private assertEventually<V>(
-    matcher: string,
-    expected: unknown,
-    read: () => Promise<V>,
-    check: (actual: V) => boolean,
-    options?: LocatorAssertionOptions,
-  ): Promise<void> {
-    const name = this.negated ? `not.${matcher}` : matcher;
-
-    return track(
-      name,
-      (async () => {
-        const timeout = await resolveTimeout(options?.timeout);
-        try {
-          await waitUntil(read, (actual) => check(actual) !== this.negated, { timeout });
-        } catch (err) {
-          if (!(err instanceof WaitTimeoutError)) throw err;
-          // Reads never resolve to undefined, so an undefined `last` means no read completed
-          if (err.last === undefined) {
-            throw new Error(
-              `expect(locator).${name}: could not read ${this.locator.selector} within ${timeout}ms`,
-            );
-          }
-          throw new AssertionError({
-            matcher: name,
-            expected,
-            actual: err.last,
-            locator: this.locator.selector,
-          });
-        }
-      })(),
-    );
-  }
-```
-
-- [ ] **Step 4: Check nothing references the removed names**
-
-Run: `grep -n "readBefore\|DEADLINE\|POLL_INTERVAL\|DEFAULT_EXPECT_TIMEOUT\|sleep(\|readConfig" src/assert/expect.ts`
-Expected: no output.
-
-- [ ] **Step 5: Run tests and type-check**
-
-Run: `npm test` (three times)
-Expected: `ℹ pass 58`, `ℹ fail 0` each run — the same tests as Step 1, all unchanged.
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/assert/expect.ts
-git commit -m "refactor(expect): poll locator assertions with waitUntil"
-```
-
----
-
-### Task 3: Element state probe and check evaluation
-
-**Files:**
-- Create: `src/locator/element-state.ts`
-- Test: `src/locator/element-state.test.ts`
-
-**Interfaces:**
-- Consumes: `RemoteValue` type from `src/types/bidi-modules/script.js`.
-- Produces:
-  - `export interface ElementBox { x: number; y: number; width: number; height: number }`
-  - `export interface ElementState { attached: boolean; visible: boolean; enabled: boolean; editable: boolean; box: ElementBox | null; hitTarget: string | null }`
-  - `export interface ProbeOptions { scroll: boolean; hitTest: boolean }`
-  - `export type WaitForState = "attached" | "detached" | "visible" | "hidden"`
-  - `export type CheckName = "attached" | "visible" | "stable" | "enabled" | "editable" | "hit target"`
-  - `export type CheckResult = "pass" | "fail" | "pending"`
-  - `export type CheckResults = Partial<Record<CheckName, CheckResult>>`
-  - `export function elementStateScript(elementExpression: string, options: ProbeOptions): string`
-  - `export function parseElementState(value: RemoteValue): ElementState`
-  - `export function evaluateChecks(required: readonly CheckName[], current: ElementState, previous: ElementState | undefined): CheckResults`
-  - `export function allPass(results: CheckResults): boolean`
-
-- [ ] **Step 1: Write the failing test**
-
-Create `src/locator/element-state.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import {
-  allPass,
-  elementStateScript,
-  evaluateChecks,
-  parseElementState,
-  type CheckName,
-  type ElementState,
-} from "./element-state.js";
-
-const EL = `document.evaluate("//button", document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue`;
-const READY: ElementState = {
-  attached: true,
-  visible: true,
-  enabled: true,
-  editable: true,
-  box: { x: 10, y: 20, width: 100, height: 40 },
-  hitTarget: "self",
-};
-const ALL: CheckName[] = ["attached", "visible", "stable", "enabled", "editable", "hit target"];
-
-test("the script compiles for every option combination", () => {
-  for (const scroll of [false, true]) {
-    for (const hitTest of [false, true]) {
-      const script = elementStateScript(EL, { scroll, hitTest });
-      assert.doesNotThrow(() => new Function(script), script);
-    }
-  }
-});
-
-test("the script embeds the element expression", () => {
-  assert.ok(elementStateScript(EL, { scroll: false, hitTest: false }).includes(EL));
-});
-
-test("scrolling and hit testing are only included when requested", () => {
-  const plain = elementStateScript(EL, { scroll: false, hitTest: false });
-  assert.ok(!plain.includes("scrollIntoView"));
-  assert.ok(!plain.includes("elementFromPoint"));
-  const full = elementStateScript(EL, { scroll: true, hitTest: true });
-  assert.ok(full.includes("scrollIntoView"));
-  assert.ok(full.includes("elementFromPoint"));
-});
-
-test("parseElementState reads the JSON state", () => {
-  assert.deepEqual(parseElementState({ type: "string", value: JSON.stringify(READY) }), READY);
-});
-
-test("parseElementState rejects a non-string result", () => {
-  assert.throws(
-    () => parseElementState({ type: "null" }),
-    /Expected an element state string but received "null"/,
-  );
-});
-
-test("parseElementState rejects malformed state", () => {
-  assert.throws(
-    () => parseElementState({ type: "string", value: "not json" }),
-    /Malformed element state/,
-  );
-  assert.throws(
-    () => parseElementState({ type: "string", value: JSON.stringify({ attached: true }) }),
-    /Malformed element state/,
-  );
-});
-
-test("evaluateChecks passes an actionable element whose box did not move", () => {
-  const results = evaluateChecks(ALL, READY, READY);
-  assert.deepEqual(results, {
-    attached: "pass",
-    visible: "pass",
-    stable: "pass",
-    enabled: "pass",
-    editable: "pass",
-    "hit target": "pass",
-  });
-  assert.equal(allPass(results), true);
-});
-
-test("the first failing check marks later checks pending", () => {
-  const results = evaluateChecks(ALL, { ...READY, visible: false }, READY);
-  assert.deepEqual(results, {
-    attached: "pass",
-    visible: "fail",
-    stable: "pending",
-    enabled: "pending",
-    editable: "pending",
-    "hit target": "pending",
-  });
-  assert.equal(allPass(results), false);
-});
-
-test("stable needs a previous probe with the same box", () => {
-  const stable = (previous: ElementState | undefined) =>
-    evaluateChecks(["stable"], READY, previous).stable;
-  assert.equal(stable(undefined), "fail");
-  assert.equal(stable({ ...READY, box: { ...READY.box!, x: 11 } }), "fail");
-  assert.equal(stable({ ...READY, box: null }), "fail");
-  assert.equal(stable(READY), "pass");
-});
-
-test("hit target passes only when the element itself is hit", () => {
-  const hit = (hitTarget: string | null) =>
-    evaluateChecks(["hit target"], { ...READY, hitTarget }, READY)["hit target"];
-  assert.equal(hit("self"), "pass");
-  assert.equal(hit("div#overlay"), "fail");
-  assert.equal(hit(null), "fail");
-});
-
-test("only the required checks are evaluated, in the given order", () => {
-  assert.deepEqual(Object.keys(evaluateChecks(["attached", "enabled"], READY, undefined)), [
-    "attached",
-    "enabled",
-  ]);
-});
-```
-
-- [ ] **Step 2: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `Cannot find module '.../src/locator/element-state.js'`; the other 58 tests pass.
-
-- [ ] **Step 3: Implement**
-
-Create `src/locator/element-state.ts`:
-
-```ts
-import type { RemoteValue } from "../types/bidi-modules/script.js";
-
-export interface ElementBox {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-export interface ElementState {
-  attached: boolean;
-  visible: boolean;
-  enabled: boolean;
-  editable: boolean;
-  /** Viewport coordinates after any scroll; null when not attached */
-  box: ElementBox | null;
-  /**
-   * "self" when a click at the element's centre reaches it, otherwise a description of
-   * the covering element ("nothing" when no element is there); null when not checked
-   */
-  hitTarget: string | null;
-}
-
-export interface ProbeOptions {
-  /** Scroll the element into view first when it is not fully inside the viewport */
-  scroll: boolean;
-  /** Check which element receives a click at the element's centre */
-  hitTest: boolean;
-}
-
-export type WaitForState = "attached" | "detached" | "visible" | "hidden";
-export type CheckName = "attached" | "visible" | "stable" | "enabled" | "editable" | "hit target";
-export type CheckResult = "pass" | "fail" | "pending";
-/** Results keyed by check name, in the order the checks were evaluated */
-export type CheckResults = Partial<Record<CheckName, CheckResult>>;
-
-const TEXT_INPUT_TYPES = ["text", "search", "email", "url", "tel", "password", "number"];
-
-const SCROLL_INTO_VIEW = `
-  const before = el.getBoundingClientRect();
-  const inViewport = before.top >= 0 && before.left >= 0 &&
-    before.bottom <= window.innerHeight && before.right <= window.innerWidth;
-  if (!inViewport) el.scrollIntoView({ block: "center", inline: "center" });`;
-
-const HIT_TEST = `
-  const top = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
-  hitTarget = !top ? "nothing"
-    : top === el || el.contains(top) ? "self"
-    : top.tagName.toLowerCase() + (top.id ? "#" + top.id : "") +
-      Array.from(top.classList, (name) => "." + name).join("");`;
-
-/** Script returning the element's state as a JSON string in one round trip */
-export function elementStateScript(
-  elementExpression: string,
-  { scroll, hitTest }: ProbeOptions,
-): string {
-  return `(() => {
-  const el = ${elementExpression};
-  if (!el) {
-    return JSON.stringify({ attached: false, visible: false, enabled: false, editable: false, box: null, hitTarget: null });
-  }${scroll ? SCROLL_INTO_VIEW : ""}
-  const rect = el.getBoundingClientRect();
-  const style = getComputedStyle(el);
-  const visible = rect.width > 0 && rect.height > 0 &&
-    style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
-  const enabled = !el.matches(":disabled") && el.getAttribute("aria-disabled") !== "true";
-  const tag = el.tagName.toLowerCase();
-  const typeable =
-    (tag === "input" && ${JSON.stringify(TEXT_INPUT_TYPES)}.includes((el.getAttribute("type") || "text").toLowerCase())) ||
-    tag === "textarea" || el.isContentEditable;
-  const editable = enabled && !el.readOnly && typeable;
-  let hitTarget = null;${hitTest ? HIT_TEST : ""}
-  return JSON.stringify({
-    attached: true, visible, enabled, editable,
-    box: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
-    hitTarget,
-  });
-})()`;
-}
-
-/** Parses the probe result; throws on anything that is not a complete state */
-export function parseElementState(value: RemoteValue): ElementState {
-  if (value.type !== "string") {
-    throw new Error(`Expected an element state string but received "${value.type}"`);
-  }
-  let state: Partial<ElementState>;
-  try {
-    state = JSON.parse(value.value) as Partial<ElementState>;
-  } catch {
-    throw new Error(`Malformed element state: ${value.value}`);
-  }
-  const flags = ["attached", "visible", "enabled", "editable"] as const;
-  if (
-    typeof state !== "object" ||
-    state === null ||
-    flags.some((flag) => typeof state[flag] !== "boolean") ||
-    !("box" in state) ||
-    !("hitTarget" in state)
-  ) {
-    throw new Error(`Malformed element state: ${value.value}`);
-  }
-  return state as ElementState;
-}
-
-function sameBox(a: ElementBox | null, b: ElementBox | null) {
-  return (
-    a !== null &&
-    b !== null &&
-    a.x === b.x &&
-    a.y === b.y &&
-    a.width === b.width &&
-    a.height === b.height
-  );
-}
-
-function checkPasses(name: CheckName, current: ElementState, previous: ElementState | undefined) {
-  switch (name) {
-    case "attached":
-      return current.attached;
-    case "visible":
-      return current.visible;
-    case "stable":
-      return sameBox(current.box, previous?.box ?? null);
-    case "enabled":
-      return current.enabled;
-    case "editable":
-      return current.editable;
-    case "hit target":
-      return current.hitTarget === "self";
-  }
-}
-
-/** Evaluates the required checks in order; after the first failure the rest are pending */
-export function evaluateChecks(
-  required: readonly CheckName[],
-  current: ElementState,
-  previous: ElementState | undefined,
-): CheckResults {
-  const results: CheckResults = {};
-  let failed = false;
-  for (const name of required) {
-    if (failed) {
-      results[name] = "pending";
-      continue;
-    }
-    const pass = checkPasses(name, current, previous);
-    results[name] = pass ? "pass" : "fail";
-    failed = !pass;
-  }
-  return results;
-}
-
-export function allPass(results: CheckResults): boolean {
-  return Object.values(results).every((result) => result === "pass");
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 69`, `ℹ fail 0`.
-
-- [ ] **Step 5: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/locator/element-state.ts src/locator/element-state.test.ts
-git commit -m "feat(locator): add element state probe and actionability checks"
-```
-
----
-
-### Task 4: `ActionTimeoutError`
-
-**Files:**
-- Create: `src/locator/action-timeout-error.ts`
-- Test: `src/locator/action-timeout-error.test.ts`
-
-**Interfaces:**
-- Consumes: `CheckName`, `CheckResult`, `CheckResults`, `WaitForState` types from `./element-state.js` (Task 3).
-- Produces:
-  - `export type ActionTimeoutReason = "unreadable" | "not-attached" | "not-actionable" | "wrong-state"`
-  - `export interface ActionTimeoutDetails { action: string; selector: string; timeout: number; reason: ActionTimeoutReason; checks?: CheckResults | undefined; coveredBy?: string | undefined; state?: WaitForState | undefined }`
-  - `export class ActionTimeoutError extends Error` with readonly `action`, `selector`, `timeout`, `reason`, `checks`, `coveredBy`, `state`; `name === "ActionTimeoutError"`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `src/locator/action-timeout-error.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { ActionTimeoutError } from "./action-timeout-error.js";
-
-const base = { action: "click", selector: '//button[@type="submit"]', timeout: 5000 } as const;
-
-test("unreadable: no probe completed", () => {
-  const err = new ActionTimeoutError({ ...base, reason: "unreadable" });
-  assert.equal(err.message, 'click(): could not read //button[@type="submit"] within 5000ms');
-});
-
-test("not attached", () => {
-  const err = new ActionTimeoutError({
-    ...base,
-    reason: "not-attached",
-    checks: { attached: "fail", visible: "pending" },
-  });
-  assert.equal(err.message, 'click(): //button[@type="submit"] was not attached within 5000ms');
-});
-
-test("wrong state for waitFor", () => {
-  const err = new ActionTimeoutError({
-    action: "waitFor",
-    selector: '//div[@class="spinner"]',
-    timeout: 300,
-    reason: "wrong-state",
-    state: "hidden",
-  });
-  assert.equal(err.message, 'waitFor(): //div[@class="spinner"] did not become hidden within 300ms');
-});
-
-test("not actionable lists every check in order", () => {
-  const err = new ActionTimeoutError({
-    ...base,
-    reason: "not-actionable",
-    checks: {
-      attached: "pass",
-      visible: "pass",
-      stable: "pass",
-      enabled: "fail",
-      "hit target": "pending",
-    },
-  });
-  assert.equal(
-    err.message,
-    'click(): //button[@type="submit"] was not actionable within 5000ms\n' +
-      "  attached ✓  visible ✓  stable ✓  enabled ✗  hit target —",
-  );
-});
-
-test("a failed hit target names the covering element", () => {
-  const err = new ActionTimeoutError({
-    ...base,
-    reason: "not-actionable",
-    checks: {
-      attached: "pass",
-      visible: "pass",
-      stable: "pass",
-      enabled: "pass",
-      "hit target": "fail",
-    },
-    coveredBy: "div#cookie-banner.overlay",
-  });
-  assert.equal(
-    err.message,
-    'click(): //button[@type="submit"] was not actionable within 5000ms\n' +
-      "  attached ✓  visible ✓  stable ✓  enabled ✓  hit target ✗ (covered by div#cookie-banner.overlay)",
-  );
-});
-
-test("exposes its details", () => {
-  const checks = { attached: "fail" } as const;
-  const err = new ActionTimeoutError({ ...base, reason: "not-attached", checks });
-  assert.ok(err instanceof Error);
-  assert.equal(err.name, "ActionTimeoutError");
-  assert.equal(err.action, "click");
-  assert.equal(err.selector, '//button[@type="submit"]');
-  assert.equal(err.timeout, 5000);
-  assert.equal(err.reason, "not-attached");
-  assert.deepEqual(err.checks, checks);
-  assert.equal(err.coveredBy, undefined);
-  assert.equal(err.state, undefined);
-});
-```
-
-- [ ] **Step 2: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `Cannot find module '.../src/locator/action-timeout-error.js'`; the other 69 tests pass.
-
-- [ ] **Step 3: Implement**
-
-Create `src/locator/action-timeout-error.ts`:
-
-```ts
-import type { CheckName, CheckResult, CheckResults, WaitForState } from "./element-state.js";
-
-export type ActionTimeoutReason = "unreadable" | "not-attached" | "not-actionable" | "wrong-state";
-
-export interface ActionTimeoutDetails {
-  /** Locator method that timed out, e.g. "click" */
-  action: string;
-  selector: string;
-  timeout: number;
-  reason: ActionTimeoutReason;
-  /** Check results from the last probe, in check order */
-  checks?: CheckResults | undefined;
-  /** Description of the element covering the target, when the hit-target check failed */
-  coveredBy?: string | undefined;
-  /** Target state, for waitFor */
-  state?: WaitForState | undefined;
-}
-
-const SYMBOLS: Record<CheckResult, string> = { pass: "✓", fail: "✗", pending: "—" };
-
-function formatMessage({
-  action,
-  selector,
-  timeout,
-  reason,
-  checks,
-  coveredBy,
-  state,
-}: ActionTimeoutDetails) {
-  switch (reason) {
-    case "unreadable":
-      return `${action}(): could not read ${selector} within ${timeout}ms`;
-    case "not-attached":
-      return `${action}(): ${selector} was not attached within ${timeout}ms`;
-    case "wrong-state":
-      return `${action}(): ${selector} did not become ${state} within ${timeout}ms`;
-    case "not-actionable": {
-      const summary = (Object.entries(checks ?? {}) as Array<[CheckName, CheckResult]>)
-        .map(([name, result]) => {
-          const covered =
-            name === "hit target" && result === "fail" && coveredBy
-              ? ` (covered by ${coveredBy})`
-              : "";
-          return `${name} ${SYMBOLS[result]}${covered}`;
-        })
-        .join("  ");
-      return `${action}(): ${selector} was not actionable within ${timeout}ms\n  ${summary}`;
-    }
-  }
-}
-
-export class ActionTimeoutError extends Error {
-  public readonly action: string;
-  public readonly selector: string;
-  public readonly timeout: number;
-  public readonly reason: ActionTimeoutReason;
-  public readonly checks: CheckResults | undefined;
-  public readonly coveredBy: string | undefined;
-  public readonly state: WaitForState | undefined;
-
-  constructor(details: ActionTimeoutDetails) {
-    super(formatMessage(details));
-    this.name = "ActionTimeoutError";
-    this.action = details.action;
-    this.selector = details.selector;
-    this.timeout = details.timeout;
-    this.reason = details.reason;
-    this.checks = details.checks;
-    this.coveredBy = details.coveredBy;
-    this.state = details.state;
-  }
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `npm test`
-Expected: `ℹ pass 75`, `ℹ fail 0`.
-
-- [ ] **Step 5: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/locator/action-timeout-error.ts src/locator/action-timeout-error.test.ts
-git commit -m "feat(locator): add ActionTimeoutError with per-check summary"
-```
-
----
-
-### Task 5: Waiting `click`, `fill`, `focus`, `force`, `isEnabled`, `isEditable`
-
-**Files:**
-- Modify: `src/locator/locator.ts`
-- Modify: `src/locator/locator.test.ts` (three existing tests adapted)
-- Test: `src/locator/locator-actions.test.ts` (new)
-
-**Interfaces:**
-- Consumes: Task 1 (`waitUntil`, `WaitTimeoutError`, `resolveTimeout`), Task 3 (`elementStateScript`, `parseElementState`, `evaluateChecks`, `allPass`, types), Task 4 (`ActionTimeoutError`); existing `stubConnector(...responses)` → `{ connector, expressions, sent }` where `StubResponse = RemoteValue | { exception: string } | { hang: true }` and `input.performActions` resolves `{}`.
-- Produces (on `Locator`):
-  - `export interface ActionOptions { timeout?: number; force?: boolean }`
-  - `export type { WaitForState } from "./element-state.js"` (re-export)
-  - `click(options?: ActionOptions): Promise<void>`
-  - `fill(value: string, options?: ActionOptions): Promise<void>`
-  - `focus(options?: ActionOptions): Promise<void>`
-  - `isEnabled(): Promise<boolean>`, `isEditable(): Promise<boolean>`
-  - `clickRect(rect: Pick<ElementRectangle, "x" | "y" | "width" | "height">): Promise<void>` (param widened; behaviour unchanged)
-  - private `probeState(options: ProbeOptions): Promise<ElementState>` (Task 6 uses it)
-
-- [ ] **Step 1: Write the failing tests**
-
-Create `src/locator/locator-actions.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import Locator from "./locator.js";
-import { ActionTimeoutError } from "./action-timeout-error.js";
-import type { ElementState } from "./element-state.js";
-import { stubConnector, type StubResponse } from "../testing/stub-connector.js";
-
-const BOX = { x: 10, y: 20, width: 100, height: 40 };
-
-/** Element state response; defaults describe an element ready for any action */
-function state(overrides: Partial<ElementState> = {}): StubResponse {
-  return {
-    type: "string",
-    value: JSON.stringify({
-      attached: true,
-      visible: true,
-      enabled: true,
-      editable: true,
-      box: BOX,
-      hitTarget: "self",
-      ...overrides,
-    }),
-  };
-}
-
-const detached = state({
-  attached: false,
-  visible: false,
-  enabled: false,
-  editable: false,
-  box: null,
-  hitTarget: null,
-});
-
-function locatorWith(xpath: string, ...responses: StubResponse[]) {
-  const stub = stubConnector(...responses);
-  return { locator: new Locator(xpath, stub.connector, "ctx"), ...stub };
-}
-
-type Performed = {
-  actions: Array<{
-    type: string;
-    actions: Array<{ type: string; x?: number; y?: number; value?: string }>;
-  }>;
-};
-type Sent = Array<{ method: string; params: unknown }>;
-
-function performed(sent: Sent, sourceType: string) {
-  return sent
-    .filter(({ method }) => method === "input.performActions")
-    .map(({ params }) => (params as Performed).actions[0]!)
-    .filter((source) => source.type === sourceType);
-}
-
-/** [x, y] of the pointerMove of every pointer click sent */
-function pointerClicks(sent: Sent) {
-  return performed(sent, "pointer").map((source) => [source.actions[0]!.x, source.actions[0]!.y]);
-}
-
-function keysTyped(sent: Sent) {
-  return performed(sent, "key")
-    .flatMap((source) => source.actions.map((action) => action.value))
-    .join("");
-}
-
-test("click() retries through every check, then clicks the latest box centre once", async () => {
-  const { locator, sent, expressions } = locatorWith(
-    "button",
-    detached, // attached ✗
-    state({ visible: false }), // visible ✗
-    state({ box: { ...BOX, x: 0 } }), // stable ✗ (moved)
-    state(), // stable ✗ (moved back)
-    state({ enabled: false }), // enabled ✗
-    state({ hitTarget: "div#overlay" }), // hit target ✗
-    state(), // actionable
-  );
-  assert.equal(await locator.click({ timeout: 3000 }), undefined);
-  assert.equal(expressions.length, 7);
-  assert.ok(expressions[0]!.includes("scrollIntoView"));
-  assert.ok(expressions[0]!.includes("elementFromPoint"));
-  assert.deepEqual(pointerClicks(sent), [[60, 40]]);
-});
-
-test("click() needs the same box on two probes, so a ready element is probed twice", async () => {
-  const { locator, expressions } = locatorWith("button", state());
-  await locator.click({ timeout: 3000 });
-  assert.equal(expressions.length, 2);
-});
-
-test("click() timeout lists the checks of the last probe", async () => {
-  const { locator, sent } = locatorWith("button", state({ enabled: false }));
-  await assert.rejects(locator.click({ timeout: 250 }), (err) => {
-    assert.ok(err instanceof ActionTimeoutError);
-    assert.equal(err.reason, "not-actionable");
-    assert.equal(
-      err.message,
-      "click(): //button was not actionable within 250ms\n" +
-        "  attached ✓  visible ✓  stable ✓  enabled ✗  hit target —",
-    );
-    return true;
-  });
-  assert.deepEqual(pointerClicks(sent), []);
-});
-
-test("click() timeout names a covering element", async () => {
-  const { locator } = locatorWith("button", state({ hitTarget: "div#cookie-banner.overlay" }));
-  await assert.rejects(
-    locator.click({ timeout: 250 }),
-    new ActionTimeoutError({
-      action: "click",
-      selector: "//button",
-      timeout: 250,
-      reason: "not-actionable",
-      checks: {
-        attached: "pass",
-        visible: "pass",
-        stable: "pass",
-        enabled: "pass",
-        "hit target": "fail",
-      },
-      coveredBy: "div#cookie-banner.overlay",
-    }),
-  );
-});
-
-test("click() on an element that never appears reports it was not attached", async () => {
-  const { locator } = locatorWith("button", detached);
-  await assert.rejects(
-    locator.click({ timeout: 250 }),
-    /^ActionTimeoutError: click\(\): \/\/button was not attached within 250ms$/,
-  );
-});
-
-test("click() when no probe completes reports it could not read the element", async () => {
-  const { locator } = locatorWith("button", { hang: true });
-  await assert.rejects(locator.click({ timeout: 250 }), (err) => {
-    assert.ok(err instanceof ActionTimeoutError);
-    assert.equal(err.reason, "unreadable");
-    assert.equal(err.message, "click(): could not read //button within 250ms");
-    return true;
-  });
-});
-
-test("force skips every check except attached", async () => {
-  const { locator, sent, expressions } = locatorWith(
-    "button",
-    state({ visible: false, enabled: false, hitTarget: "div#overlay" }),
-  );
-  await locator.click({ force: true, timeout: 1000 });
-  assert.equal(expressions.length, 1);
-  assert.ok(expressions[0]!.includes("scrollIntoView"));
-  assert.deepEqual(pointerClicks(sent), [[60, 40]]);
-});
-
-test("force still waits for the element to be attached", async () => {
-  const { locator } = locatorWith("button", detached);
-  await assert.rejects(
-    locator.click({ force: true, timeout: 250 }),
-    /was not attached within 250ms/,
-  );
-});
-
-test("fill() waits until the field is editable, then clicks, selects and types", async () => {
-  const { locator, sent, expressions } = locatorWith(
-    "input",
-    state({ editable: false }),
-    state(),
-    { type: "undefined" },
-  );
-  await locator.fill("ab", { timeout: 3000 });
-  assert.equal(expressions.length, 3);
-  assert.match(expressions[2]!, /\.select\(\)/);
-  assert.deepEqual(pointerClicks(sent), [[60, 40]]);
-  assert.equal(keysTyped(sent), "aabb");
-});
-
-test("fill() timeout lists the fill checks", async () => {
-  const { locator } = locatorWith("input", state({ editable: false }));
-  await assert.rejects(
-    locator.fill("x", { timeout: 250 }),
-    (err) =>
-      err instanceof ActionTimeoutError &&
-      err.message ===
-        "fill(): //input was not actionable within 250ms\n" +
-          "  attached ✓  visible ✓  enabled ✓  editable ✗  hit target —",
-  );
-});
-
-test("focus() waits only for the element to be attached", async () => {
-  const { locator, expressions } = locatorWith(
-    "input",
-    detached,
-    state({ visible: false, enabled: false }),
-    { type: "undefined" },
-  );
-  assert.equal(await locator.focus({ timeout: 3000 }), undefined);
-  assert.equal(expressions.length, 3);
-  assert.ok(!expressions[0]!.includes("scrollIntoView"));
-  assert.match(expressions[2]!, /\.focus\(\)$/);
-});
-
-test("isEnabled() and isEditable() read the state without waiting", async () => {
-  assert.equal(await locatorWith("button", state()).locator.isEnabled(), true);
-  assert.equal(await locatorWith("button", state({ enabled: false })).locator.isEnabled(), false);
-  assert.equal(await locatorWith("button", detached).locator.isEnabled(), false);
-  assert.equal(await locatorWith("input", state()).locator.isEditable(), true);
-  assert.equal(await locatorWith("input", state({ editable: false })).locator.isEditable(), false);
-  assert.equal(await locatorWith("input", detached).locator.isEditable(), false);
-});
-```
-
-- [ ] **Step 2: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — `locator-actions.test.ts` fails (e.g. `click()` resolves a BiDi value / `isEnabled is not a function` / pointer clicks empty); ≥ 10 failures in that file; the other 75 tests pass.
-
-- [ ] **Step 3: Implement in `src/locator/locator.ts`**
-
-a) Add imports below the existing ones:
-
-```ts
-import { resolveTimeout, waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
-import { ActionTimeoutError } from "./action-timeout-error.js";
-import {
-  allPass,
-  elementStateScript,
-  evaluateChecks,
-  parseElementState,
-  type CheckName,
-  type CheckResults,
-  type ElementState,
-  type ProbeOptions,
-} from "./element-state.js";
-
-export type { WaitForState } from "./element-state.js";
-
-export interface ActionOptions {
-  /** Time (ms) to wait for the element to become actionable. Defaults to config `expect.timeout`, then 5000 */
-  timeout?: number;
-  /** Skip every actionability check except "attached" */
-  force?: boolean;
-}
-
-const CLICK_CHECKS: readonly CheckName[] = ["attached", "visible", "stable", "enabled", "hit target"];
-const FILL_CHECKS: readonly CheckName[] = ["attached", "visible", "enabled", "editable", "hit target"];
-const ATTACHED_ONLY: readonly CheckName[] = ["attached"];
-```
-
-b) Replace
-
-```ts
-  /** Simulate a 'Click' event on the element */
-  public async click() {
-    return await this.evaluate(this.buildExpression("click()"));
-  }
-```
-
-with
-
-```ts
-  /** Reads the element's actionability state in one round trip */
-  private async probeState(options: ProbeOptions): Promise<ElementState> {
-    return parseElementState(
-      await this.evaluate(elementStateScript(this.elementExpression(), options)),
-    );
-  }
-
-  /**
-   * Probes until every required check passes and returns that state.
-   * Throws ActionTimeoutError describing the last probe on timeout.
-   */
-  private async waitForActionable(
-    action: string,
-    checks: readonly CheckName[],
-    probe: ProbeOptions,
-    options: ActionOptions | undefined,
-  ): Promise<ElementState> {
-    const required = options?.force ? ATTACHED_ONLY : checks;
-    const timeout = await resolveTimeout(options?.timeout);
-    let lastChecks: CheckResults | undefined;
-    try {
-      return await waitUntil(
-        () => this.probeState(probe),
-        (current, previous) => {
-          lastChecks = evaluateChecks(required, current, previous);
-          return allPass(lastChecks);
-        },
-        { timeout },
-      );
-    } catch (err) {
-      if (!(err instanceof WaitTimeoutError)) throw err;
-      const last = err.last as ElementState | undefined;
-      throw new ActionTimeoutError({
-        action,
-        selector: this.selector,
-        timeout,
-        reason: !last ? "unreadable" : last.attached ? "not-actionable" : "not-attached",
-        checks: lastChecks,
-        coveredBy: last?.hitTarget && last.hitTarget !== "self" ? last.hitTarget : undefined,
-      });
-    }
-  }
-
-  /** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
-  public async click(options?: ActionOptions): Promise<void> {
-    const state = await this.waitForActionable(
-      "click",
-      CLICK_CHECKS,
-      { scroll: true, hitTest: true },
-      options,
-    );
-    // "attached" is always required, so the box is present
-    await this.clickRect(state.box!);
-  }
-```
-
-c) Change the `clickRect` signature line
-
-```ts
-  public async clickRect(rect: ElementRectangle) {
-```
-
-to
-
-```ts
-  public async clickRect(rect: Pick<ElementRectangle, "x" | "y" | "width" | "height">) {
-```
-
-d) Replace
-
-```ts
-  /** Simulates focusing an element */
-  public async focus() {
-    return await this.evaluate(this.buildExpression("focus()"));
-  }
-```
-
-with
-
-```ts
-  /** Waits until the element is attached, then focuses it */
-  public async focus(options?: ActionOptions): Promise<void> {
-    await this.waitForActionable("focus", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
-    await this.evaluate(this.buildExpression("focus()"));
-  }
-```
-
-e) Add after `count()`:
-
-```ts
-  /** Whether the element exists and is not disabled; does not wait */
-  public async isEnabled(): Promise<boolean> {
-    const state = await this.probeState({ scroll: false, hitTest: false });
-    return state.attached && state.enabled;
-  }
-
-  /** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
-  public async isEditable(): Promise<boolean> {
-    const state = await this.probeState({ scroll: false, hitTest: false });
-    return state.attached && state.editable;
-  }
-```
-
-f) In `fill`, replace the signature, doc comment and first line
-
-```ts
-  /** Replaces the value of an input or textarea by typing `value`; an empty string clears it */
-  public async fill(value: string) {
-    const rect = await this.getBoundingClientRect();
-```
-
-with
-
-```ts
-  /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
-  public async fill(value: string, options?: ActionOptions): Promise<void> {
-    const state = await this.waitForActionable(
-      "fill",
-      FILL_CHECKS,
-      { scroll: true, hitTest: true },
-      options,
-    );
-```
-
-and further down in `fill` replace `await this.clickRect(rect);` with `await this.clickRect(state.box!);`. Leave the rest of `fill` (wait, select, typing) unchanged.
-
-- [ ] **Step 4: Adapt three existing tests in `src/locator/locator.test.ts`**
-
-`click()` and `fill()` now probe the element state first, so the scripted stub responses must include a state.
-
-a) Directly after the `assertCompiles` function add:
-
-```ts
-/** Element state for an element that is ready for any action */
-const ready: StubResponse = {
-  type: "string",
-  value: JSON.stringify({
-    attached: true,
-    visible: true,
-    enabled: true,
-    editable: true,
-    box: { x: 0, y: 0, width: 100, height: 20 },
-    hitTarget: "self",
-  }),
-};
-```
-
-b) In `test("xpaths with both quote styles produce valid JavaScript", …)`, change the stub responses from
-
-```ts
-    { type: "string", value: "Don't stop" },
-    { type: "number", value: 1 },
-  );
-```
-
-to
-
-```ts
-    { type: "string", value: "Don't stop" },
-    { type: "number", value: 1 },
-    ready,
-  );
-```
-
-and add `{ timeout: 3000 }` to the call: `await locator.click({ timeout: 3000 });`. The assertions stay as they are (`expressions[2]` is now the first state probe, which embeds the xpath).
-
-c) Replace the whole `test("actions on an all() item target that item", …)` with:
-
-```ts
-test("actions on an all() item target that item", async () => {
-  const { connector, expressions, sent } = stubConnector({ type: "number", value: 2 }, ready);
-  const items = await new Locator("li", connector, "ctx").all();
-  await items[1]!.click({ timeout: 3000 });
-  assert.ok(expressions[1]!.includes(JSON.stringify("(//li)[2]")));
-  assert.match(expressions[1]!, /FIRST_ORDERED_NODE_TYPE/);
-  assertCompiles(expressions[1]!);
-  assert.equal(sent.filter(({ method }) => method === "input.performActions").length, 1);
-});
-```
-
-d) Delete the line
-
-```ts
-const rect = { type: "string", value: JSON.stringify({ x: 0, y: 0, width: 100, height: 20 }) } as const;
-```
-
-and in the two `fill()` tests change `locatorWith("input", rect, { type: "undefined" })` to `locatorWith("input", ready, { type: "undefined" })`, and pass an explicit timeout so the config file is never read: `await locator.fill("abc", { timeout: 3000 });` and `await locator.fill("", { timeout: 3000 });`. Their expected traces stay unchanged (the first `evaluate:other` is now the state probe instead of `getBoundingClientRect`).
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `npm test` (three times)
-Expected: `ℹ pass 87`, `ℹ fail 0` each run.
-
-- [ ] **Step 6: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/locator/locator.ts src/locator/locator.test.ts src/locator/locator-actions.test.ts
-git commit -m "feat(locator): wait for actionability in click, fill and focus"
-```
-
----
-
-### Task 6: `waitFor()`
-
-**Files:**
-- Modify: `src/locator/locator.ts`
-- Modify: `src/locator/locator-actions.test.ts`
-
-**Interfaces:**
-- Consumes: Task 5's private `probeState`, `ActionTimeoutError`, `waitUntil`, `WaitTimeoutError`, `resolveTimeout`; `WaitForState` and `ElementState` from `./element-state.js`.
-- Produces: `waitFor(options?: { state?: WaitForState; timeout?: number }): Promise<void>` (state default `"visible"`).
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `src/locator/locator-actions.test.ts`:
-
-```ts
-test("waitFor() waits for visible by default, without scrolling", async () => {
-  const { locator, expressions } = locatorWith("div", state({ visible: false }), state());
-  await locator.waitFor({ timeout: 3000 });
-  assert.equal(expressions.length, 2);
-  assert.ok(!expressions[0]!.includes("scrollIntoView"));
-  assert.ok(!expressions[0]!.includes("elementFromPoint"));
-});
-
-test("waitFor({ state: \"hidden\" }) resolves once the element is gone or invisible", async () => {
-  const gone = locatorWith("div", state(), detached);
-  await gone.locator.waitFor({ state: "hidden", timeout: 3000 });
-  assert.equal(gone.expressions.length, 2);
-
-  const invisible = locatorWith("div", state(), state({ visible: false }));
-  await invisible.locator.waitFor({ state: "hidden", timeout: 3000 });
-  assert.equal(invisible.expressions.length, 2);
-});
-
-test("waitFor() for attached and detached", async () => {
-  const appears = locatorWith("div", detached, state({ visible: false }));
-  await appears.locator.waitFor({ state: "attached", timeout: 3000 });
-  assert.equal(appears.expressions.length, 2);
-
-  const disappears = locatorWith("div", state(), detached);
-  await disappears.locator.waitFor({ state: "detached", timeout: 3000 });
-  assert.equal(disappears.expressions.length, 2);
-});
-
-test("waitFor() timeout names the state it waited for", async () => {
-  const { locator } = locatorWith("div", state({ visible: false }));
-  await assert.rejects(locator.waitFor({ timeout: 250 }), (err) => {
-    assert.ok(err instanceof ActionTimeoutError);
-    assert.equal(err.reason, "wrong-state");
-    assert.equal(err.state, "visible");
-    assert.equal(err.message, "waitFor(): //div did not become visible within 250ms");
-    return true;
-  });
-});
-
-test("waitFor() when no probe completes reports it could not read the element", async () => {
-  const { locator } = locatorWith("div", { hang: true });
-  await assert.rejects(
-    locator.waitFor({ state: "hidden", timeout: 250 }),
-    /^ActionTimeoutError: waitFor\(\): could not read \/\/div within 250ms$/,
-  );
-});
-```
-
-- [ ] **Step 2: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — 5 failures, `locator.waitFor is not a function`; the other 87 tests pass.
-
-- [ ] **Step 3: Implement**
-
-In `src/locator/locator.ts`, extend the `./element-state.js` import list with `type WaitForState` (keep the existing re-export line), then add after `focus()`:
-
-```ts
-  /** Waits until the element reaches `state` (default "visible"); does not scroll */
-  public async waitFor({
-    state = "visible",
-    timeout,
-  }: { state?: WaitForState; timeout?: number } = {}): Promise<void> {
-    const resolved = await resolveTimeout(timeout);
-    const reached: Record<WaitForState, (current: ElementState) => boolean> = {
-      attached: (current) => current.attached,
-      detached: (current) => !current.attached,
-      visible: (current) => current.attached && current.visible,
-      hidden: (current) => !current.attached || !current.visible,
-    };
-    try {
-      await waitUntil(() => this.probeState({ scroll: false, hitTest: false }), reached[state], {
-        timeout: resolved,
-      });
-    } catch (err) {
-      if (!(err instanceof WaitTimeoutError)) throw err;
-      throw new ActionTimeoutError({
-        action: "waitFor",
-        selector: this.selector,
-        timeout: resolved,
-        reason: err.last === undefined ? "unreadable" : "wrong-state",
-        state,
-      });
-    }
-  }
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `npm test` (three times)
-Expected: `ℹ pass 92`, `ℹ fail 0` each run.
-
-- [ ] **Step 5: Type-check**
-
-Run: `npx tsc --noEmit -p .`
-Expected: only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/locator/locator.ts src/locator/locator-actions.test.ts
-git commit -m "feat(locator): add waitFor for attached, detached, visible and hidden"
-```
-
----
-
-### Task 7: `navigateTo` scheme fix and headless-Firefox browser tests
-
-**Files:**
-- Modify: `src/testing/stub-connector.ts`
-- Modify: `src/browser/page.ts` (`navigateTo`)
-- Create: `src/browser/page.test.ts`
-- Create: `src/testing/browser-fixture.ts`
-- Create: `src/locator/locator.browser-test.ts`
-- Modify: `package.json` (`scripts`)
-
-**Interfaces:**
-- Consumes: `Browser.launch(browserName, launchOptions?, signal?)` → `Promise<{ browser: Browser; page: Page }>`; `browser.close(): Promise<void>`; `Page` (private fields `biDiConnector`, `contextId`); Tasks 5-6 actions and `ActionTimeoutError`.
-- Produces: `setContent(page: Page, html: string, setup?: string): Promise<void>`; `npm run test:browser`.
-
-The browser tests need a blank page; `navigateTo("about:blank")` is currently turned into the literal `https://url`, so that bug is fixed first (TDD, unit level).
-
-- [ ] **Step 1: Let the stub answer navigation**
-
-In `src/testing/stub-connector.ts`, change
-
-```ts
-      if (method === "input.performActions") {
-        return {};
-      }
-```
-
-to
-
-```ts
-      if (method === "input.performActions" || method === "browsingContext.navigate") {
-        return {};
-      }
-```
-
-and in the doc comment change `` `input.performActions` resolves empty. `` to `` `input.performActions` and `browsingContext.navigate` resolve empty. ``
-
-- [ ] **Step 2: Write the failing `navigateTo` test**
-
-Create `src/browser/page.test.ts`:
-
-```ts
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import Page from "./page.js";
-import { stubConnector } from "../testing/stub-connector.js";
-
-test("navigateTo keeps URLs that have a scheme and prefixes bare hosts", async () => {
-  const { connector, sent } = stubConnector({ type: "undefined" });
-  const page = new Page(connector, "ctx");
-  await page.navigateTo("about:blank");
-  await page.navigateTo("https://itmetsam.nl/contact");
-  await page.navigateTo("itmetsam.nl");
-  await page.navigateTo("localhost:3000/login");
-  await page.navigateTo("itmetsam.nl", undefined, "http");
-  assert.deepEqual(
-    sent.map(({ params }) => (params as { url: string }).url),
-    [
-      "about:blank",
-      "https://itmetsam.nl/contact",
-      "https://itmetsam.nl",
-      "https://localhost:3000/login",
-      "http://itmetsam.nl",
-    ],
-  );
-});
-```
-
-- [ ] **Step 3: Run it to verify it fails**
-
-Run: `npm test`
-Expected: FAIL — 1 failure; actual URLs contain `https://url`; the other 92 tests pass.
-
-- [ ] **Step 4: Fix `navigateTo`**
-
-In `src/browser/page.ts` replace
-
-```ts
-    const parsedURL = url.startsWith("http") ? url : `${protocol}://url`;
-```
-
-with
-
-```ts
-    // A scheme is letters followed by ":" not directly followed by a digit, so "localhost:3000" is a host
-    const hasScheme = /^[a-z][a-z\d+.-]*:(?!\d)/i.test(url);
-    const parsedURL = hasScheme ? url : `${protocol}://${url}`;
-```
-
-Run: `npm test`
-Expected: `ℹ pass 93`, `ℹ fail 0`.
-
-- [ ] **Step 5: Add the fixture helper and script**
-
-Create `src/testing/browser-fixture.ts`:
-
-```ts
-import type Page from "../browser/page.js";
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-
-/**
- * Test-only: replaces the page body with `html`, then runs `setup` (JavaScript source,
- * wrapped in its own function scope) in the page. Reaches into Page's private fields.
- */
-export async function setContent(page: Page, html: string, setup = "") {
-  const internals = page as unknown as { biDiConnector: BiDiConnector; contextId: string };
-  const result = await internals.biDiConnector.send("script.evaluate", {
-    expression: `document.body.innerHTML = ${JSON.stringify(html)}; (() => { ${setup} })();`,
-    awaitPromise: false,
-    target: { context: internals.contextId },
-  });
-  if (result.type === "exception") {
-    throw new Error(`setContent failed: ${result.exceptionDetails.text}`);
-  }
-}
-```
-
-In `package.json` `scripts`, add after `"test"`:
-
-```json
-    "test:browser": "tsx --test \"src/**/*.browser-test.ts\""
-```
-
-(add the comma after the `"test"` line).
-
-- [ ] **Step 6: Write the browser tests**
-
-Create `src/locator/locator.browser-test.ts`:
-
-```ts
-import { after, before, test } from "node:test";
-import assert from "node:assert/strict";
-import { Browser } from "../browser/browser.js";
-import type Page from "../browser/page.js";
-import { setContent } from "../testing/browser-fixture.js";
-import { ActionTimeoutError } from "./action-timeout-error.js";
-
-let browser: Browser;
-let page: Page;
-
-before(async () => {
-  ({ browser, page } = await Browser.launch("firefox", { port: 9231, headless: true }));
-  await page.navigateTo("about:blank", "complete");
-});
-
-after(async () => {
-  await browser?.close();
-});
-
-/** Records on the button whether a click was a real (trusted) pointer click */
-const RECORD_CLICKS = `
-  const b = document.getElementById("b");
-  b.addEventListener("click", (event) => { b.dataset.clicked = event.isTrusted ? "trusted" : "synthetic"; });`;
-
-const OPTIONS = { timeout: 15000 };
-
-test("click waits for a button that becomes enabled", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<button id="b" disabled>Go</button>`,
-    `${RECORD_CLICKS} setTimeout(() => { b.disabled = false; }, 300);`,
-  );
-  const button = page.locator("button[@id='b']");
-  await button.click({ timeout: 3000 });
-  assert.equal(await button.getAttribute("data-clicked"), "trusted");
-});
-
-test("click waits for a covering overlay to disappear", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<button id="b">Go</button><div id="overlay" style="position:fixed;inset:0;background:rgba(0,0,0,0.5)"></div>`,
-    `${RECORD_CLICKS} setTimeout(() => document.getElementById("overlay").remove(), 300);`,
-  );
-  const button = page.locator("button[@id='b']");
-  await button.click({ timeout: 3000 });
-  assert.equal(await button.getAttribute("data-clicked"), "trusted");
-});
-
-test("click waits for a moving button to stop", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<button id="b" style="position:absolute;left:0;top:0;transition:left 300ms linear">Go</button>`,
-    `${RECORD_CLICKS} requestAnimationFrame(() => requestAnimationFrame(() => { b.style.left = "300px"; }));`,
-  );
-  const button = page.locator("button[@id='b']");
-  await button.click({ timeout: 3000 });
-  assert.equal(await button.getAttribute("data-clicked"), "trusted");
-});
-
-test("click scrolls a button below the fold into view", OPTIONS, async () => {
-  await setContent(page, `<div style="height:3000px"></div><button id="b">Go</button>`, RECORD_CLICKS);
-  const button = page.locator("button[@id='b']");
-  await button.click({ timeout: 3000 });
-  assert.equal(await button.getAttribute("data-clicked"), "trusted");
-});
-
-test("fill waits for a readonly field to become editable and replaces its value", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<input id="i" readonly value="old">`,
-    `setTimeout(() => { document.getElementById("i").readOnly = false; }, 300);`,
-  );
-  const input = page.locator("input[@id='i']");
-  await input.fill("typed", { timeout: 3000 });
-  assert.equal(await input.inputValue(), "typed");
-});
-
-test("force clicks an element that is not considered visible", OPTIONS, async () => {
-  await setContent(page, `<button id="b" style="opacity:0">Go</button>`, RECORD_CLICKS);
-  const button = page.locator("button[@id='b']");
-  await assert.rejects(button.click({ timeout: 300 }), /visible ✗/);
-  await button.click({ force: true, timeout: 3000 });
-  assert.equal(await button.getAttribute("data-clicked"), "trusted");
-});
-
-test("waitFor hidden resolves when the element is removed; visible times out when it stays hidden", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<div id="s">Loading</div>`,
-    `setTimeout(() => document.getElementById("s").remove(), 300);`,
-  );
-  await page.locator("div[@id='s']").waitFor({ state: "hidden", timeout: 3000 });
-
-  await setContent(page, `<div id="s" style="display:none">Loading</div>`);
-  await assert.rejects(
-    page.locator("div[@id='s']").waitFor({ timeout: 300 }),
-    (err) =>
-      err instanceof ActionTimeoutError &&
-      err.message === "waitFor(): //div[@id='s'] did not become visible within 300ms",
-  );
-});
-
-test("a disabled button times out with the check summary", OPTIONS, async () => {
-  await setContent(page, `<button id="b" disabled>Go</button>`);
-  await assert.rejects(
-    page.locator("button[@id='b']").click({ timeout: 500 }),
-    (err) =>
-      err instanceof ActionTimeoutError &&
-      err.message ===
-        "click(): //button[@id='b'] was not actionable within 500ms\n" +
-          "  attached ✓  visible ✓  stable ✓  enabled ✗  hit target —",
-  );
-});
-
-test("a covered button times out naming the covering element", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<button id="b">Go</button><div id="cover" class="overlay" style="position:fixed;inset:0"></div>`,
-  );
-  await assert.rejects(
-    page.locator("button[@id='b']").click({ timeout: 500 }),
-    /hit target ✗ \(covered by div#cover\.overlay\)/,
-  );
-});
-```
-
-- [ ] **Step 7: Run the browser tests**
-
-Run: `npm run test:browser`
-(In a sandboxed agent shell, run this one command with the sandbox disabled: Firefox must read its profile data and the BiDi port must be reachable. It launches headless Firefox on port 9231 and loads only `about:blank` — no external site.)
-Expected: `ℹ pass 9`, `ℹ fail 0`; the process exits on its own. Framework debug logging is printed; that is expected.
-If a test fails, it is a real finding about the browser-side script: fix the implementation (element-state script or locator), not the fixture's expectations, and re-run both `npm test` and `npm run test:browser`.
-
-- [ ] **Step 8: Final checks**
-
-Run: `npm test` → `ℹ pass 93`, `ℹ fail 0` (browser tests are not picked up).
-Run: `npx tsc --noEmit -p .` → only the pre-existing `src/config/default.ts` error.
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add src/testing/stub-connector.ts src/browser/page.ts src/browser/page.test.ts src/testing/browser-fixture.ts src/locator/locator.browser-test.ts package.json
-git commit -m "test(locator): headless Firefox tests for auto-waiting actions"
-```