nativeproof 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to NativeProof are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## 0.2.0
+
+Locator interaction, generic assertions, and Compose/SwiftUI robustness — plus the docs for each.
+
+**Added**
+
+- **`Locator.fill(text, opts?)`** — native text entry, the analogue of Playwright's `locator.fill()`:
+  it focuses the field (a `tap()`) and types through the device keyboard. New optional `Driver.typeText?`
+  hook (`wdioDriver()` implements it via `browser.keys`); `fill()` throws a clear error on drivers
+  without text input. It does **not** clear existing content first. (#5)
+- **Generic `expect(value)` matchers** — `toBe` / `toEqual` / `toContain` / `toBeTruthy` / `toBeFalsy` /
+  `toBeDefined` / `toBeNull` (+ `.not`). These are **synchronous** (unlike the auto-waiting locator/mock
+  matchers), so non-UI checks (counts, ids, parsed payloads) need no second assertion library. (#4)
+- **`tap({ clickableAncestor: true })`** — taps the smallest `clickable="true"` ancestor that contains
+  the matched node, for Compose/SwiftUI labels that sit on a non-clickable child of the real touch target. (#3)
+
+**Changed**
+
+- **`getByText` / `by.text` is now forgiving** — it matches `text` *or* `content-desc` on Android and
+  `label` *or* `value` on iOS, so a visible label is found wherever the toolkit exposes it. This broadens
+  matching for existing `by.text` selectors; use `getByLabel` / `by.desc` when you want the accessibility
+  description specifically. (#3)
+
+**Fixed**
+
+- **XML entity handling in locators** — selectors built from human-readable strings
+  (`by.text("Terms & Conditions")`) now match the entity-escaped page source, and `textContent()` decodes
+  entities back to plain text. (#2)
+- **`./package.json` is now exported** — resolvable through the package `exports` map for tooling and
+  bundlers that read it. (#1)
+
+**Docs**
+
+- "Bring your own backend" — documents the `MockBackend` adapter pattern for apps with an existing mock
+  server, and clarifies which symbols import from `nativeproof` vs your `nativeproof.config`. (#6)
+- Every feature above is documented in the README (Locators, Assertions, Features, API reference).
+
 ## 0.1.1
 
 Documentation pass: refreshed the README examples, expanded the iOS setup guide, and

package/README.md

@@ -31,16 +31,23 @@ nativeproof --platform android
 - [Features](#features)
 - [Requirements](#requirements)
 - [Install](#install)
+- [Quick start](#quick-start)
 - [Project setup](#project-setup)
 - [Android setup](#android-setup)
 - [iOS setup](#ios-setup)
 - [Writing tests](#writing-tests)
   - [Test blocks](#test-blocks-describe--test)
-  - [Locators & assertions](#locators--assertions)
+  - [Fixtures, roles & the app seam](#fixtures-roles--the-app-seam)
+  - [Locators](#locators)
+  - [Assertions](#assertions)
   - [Network interception & assertions](#network-interception--assertions)
+  - [Bring your own backend](#bring-your-own-backend)
+  - [Gestures & scrolling](#gestures--scrolling)
+  - [Evidence & secrets](#evidence--secrets)
 - [Running](#running)
 - [CI](#ci)
 - [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
 - [API reference](#api-reference)
 - [How it works](#how-it-works)
 
@@ -51,18 +58,21 @@ nativeproof --platform android
 - **Reads like Playwright** — `test.describe` / `test(...)` blocks with a typed fixture
   context injected; no per-test setup/teardown in the spec.
 - **Locators** — `by.text/testId/label/desc/id` and `page(driver).getByText/getByTestId/
-  getByLabel/getByRole`, mapped to the right native attribute per platform (so you never
-  guess `content-desc` vs `accessibilityIdentifier`).
+  getByLabel/getById/getByRole`, each mapped to the right native attribute per platform (so you
+  never guess `content-desc` vs `accessibilityIdentifier`), with built-in auto-waiting and
+  `tap()` / `fill()` for interaction.
 - **Auto-waiting `expect`** — `expect(locator).toBeVisible()/toShow()/toHaveText()` and
-  `.not`, each polling until the condition holds.
-- **Network interception** — a first-party mock server with `route().fulfill/reject/abort`
-  (like `page.route()`) and `expect(mock).toHaveSent()/toHaveReceived()` traffic assertions.
-  No per-app adapter.
+  `.not`, each polling until the condition holds (default 10s); plus synchronous `expect(value)`
+  matchers (`toBe`/`toEqual`/`toContain`/…) so non-UI checks need no second assertion library.
+- **Network interception** — a first-party HTTP + WebSocket mock server with
+  `route().fulfill/reject/abort` (like `page.route()`) and `expect(mock).toHaveSent()/
+  toHaveReceived()` traffic assertions. No per-app adapter.
 - **One seam, by injection** — a single `defineApp(...)` declares the device, mock,
-  login flow, screens and secret patterns; the core imports nothing app-specific.
+  login/join flows, screens and secret patterns; the core imports nothing app-specific.
 - **Cross-platform** — the same spec runs on Android (UiAutomator2) and iOS (XCUITest).
 - **One command** — `nativeproof` resolves your config, ensures Appium is up, and runs the suite.
-- **TypeScript-first**, strict, with evidence (redacted screenshots + source) on every step.
+- **TypeScript-first**, strict, with evidence (redacted screenshots + page source) for an
+  auditable green run.
 
 ## Requirements
 
@@ -82,26 +92,96 @@ npm i -D nativeproof \
 # install the Appium driver(s) you need
 npx appium driver install uiautomator2   # Android
 npx appium driver install xcuitest        # iOS (macOS only)
+
+# optional: verify the toolchain is wired up
+npx appium driver doctor uiautomator2
 ```
 
+## Quick start
+
+Four steps from zero to a green run on Android.
+
+**1. Configure** — one `nativeproof.config.ts` at the project root:
+
+```ts
+import { createHarness, defineApp, defineConfig, page, startMockServer, wdioDriver } from "nativeproof";
+
+const app = defineApp({
+  driver: () => wdioDriver(),
+  mock: () => startMockServer({ port: 18113, host: "0.0.0.0" }), // 0.0.0.0 so a device can reach it
+  screens: {
+    home: ({ driver }) => ({
+      title: page(driver).getByText("Welcome"),
+      start: page(driver).getByRole("button", { name: "Get started" }),
+    }),
+  },
+});
+
+export const { test, expect } = createHarness(app); // specs import these
+
+export default defineConfig({
+  app,
+  testDir: "tests",
+  projects: [
+    {
+      name: "android",
+      platform: "android",
+      capabilities: {
+        platformName: "Android",
+        "appium:automationName": "UiAutomator2",
+        "appium:app": process.env.ANDROID_APP ?? "app/android/app-debug.apk",
+        "appium:autoGrantPermissions": true,
+      },
+    },
+  ],
+});
+```
+
+**2. Write a spec** — `tests/home.spec.ts`:
+
+```ts
+import { test, expect } from "../nativeproof.config";
+
+test.describe("home screen", () => {
+  test("greets the user and starts", async ({ home }) => {
+    await expect(home.title).toBeVisible();
+    await home.start.tap();
+  });
+});
+```
+
+**3. Boot a device** — an emulator (Android) or simulator (iOS) must be running (see
+[Android setup](#android-setup) / [iOS setup](#ios-setup)).
+
+**4. Run:**
+
+```bash
+npx nativeproof --platform android
+```
+
+`nativeproof` discovers the config, starts Appium if it isn't already up, and runs the suite.
+
+## Project setup
+
+Everything lives in one **`nativeproof.config.ts`** — the `playwright.config.ts` analogue. It
+declares the app (the injected seam), exports the typed `test` / `expect` your specs import,
+and lists the device **projects**. The CLI auto-discovers it and synthesises the WebdriverIO
+run, so there's no hand-written `wdio.conf.ts`.
+
 A typical project:
 
 ```
 my-app-e2e/
 ├─ nativeproof.config.ts  # the single config — app, device projects, test/expect exports
 ├─ tests/
+│  ├─ home.spec.ts
 │  └─ chat.spec.ts
 └─ app/
    ├─ android/app-debug.apk
    └─ ios/MyApp.app
 ```
 
-## Project setup
-
-Everything lives in one **`nativeproof.config.ts`** — the `playwright.config.ts` analogue. It
-declares the app (the injected seam), exports the typed `test` / `expect` your specs import,
-and lists the device **projects**. The `nativeproof` CLI auto-discovers it and synthesises the
-WebdriverIO run, so there's no hand-written `wdio.conf.ts`.
+The full, cross-platform config:
 
 ```ts
 // nativeproof.config.ts
@@ -109,9 +189,9 @@ import { createHarness, defineApp, defineConfig, page, startMockServer, wdioDriv
 
 const app = defineApp({
   driver: () => wdioDriver(),                       // the live WebdriverIO/Appium session
-  mock: () => startMockServer({ port: 18113 }),     // first-party mock; route()/frames built in
-  secrets: [/\b2468\b/],                            // kept out of captured evidence
-  login: async ({ role, mock }) => {
+  mock: () => startMockServer({ port: 18113, host: "0.0.0.0" }), // first-party mock; route()/frames built in
+  secrets: [/\b\d{6}\b/],                           // app-specific patterns kept out of captured evidence
+  login: async ({ role, driver, mock }) => {
     // drive your app's sign-in; `mock` is the running backend, `role` comes from the describe
   },
   screens: {
@@ -119,8 +199,12 @@ const app = defineApp({
       const p = page(driver);
       return {
         messages: p.getByTestId("message-list"),
-        signOut: p.getByLabel("Sign out"),
+        roomTitle: p.getByTestId("room-title"),
+        composer: p.getByTestId("composer"),
         sendButton: p.getByRole("button", { name: "Send" }),
+        errorBanner: p.getByTestId("error-banner"),
+        spinner: p.getByTestId("loading"),
+        signOut: p.getByLabel("Sign out"),
       };
     },
   },
@@ -179,9 +263,10 @@ export default defineConfig({
    ```
 4. **App build.** Point `ANDROID_APP` at your debug/E2E `.apk` (or use `appium:appPackage` +
    `appium:appActivity` for an already-installed build).
-5. **Mock host.** From the emulator, the host machine is reachable at **`10.0.2.2`**. Build
-   your E2E app so its backend base URL is `http://10.0.2.2:18113` (the mock server's port),
-   so `mock.route(...)` and `expect(mock)` see the app's traffic.
+5. **Mock host.** From an emulator, the host machine is reachable at **`10.0.2.2`** — build your
+   E2E app so its backend base URL is `http://10.0.2.2:18113` (the mock server's port). Bind the
+   mock with `host: "0.0.0.0"` so the device can reach it (a real device uses your Mac's LAN IP,
+   e.g. `http://192.168.1.20:18113`). Then `mock.route(...)` and `expect(mock)` see the traffic.
 
 ## iOS setup
 
@@ -215,8 +300,7 @@ export default defineConfig({
    - **Already installed:** skip `appium:app` and set `appium:bundleId` instead.
 5. **Mock host.** The simulator shares the host's network, so the backend base URL is
    `http://127.0.0.1:18113` (the mock server's port). A **real device** must reach your Mac by
-   its LAN IP instead, e.g. `http://192.168.1.20:18113` — set the mock's `host` so both bind
-   the same interface.
+   its LAN IP instead — bind the mock with `host: "0.0.0.0"` so both ends use the same interface.
 
 ## Writing tests
 
@@ -246,63 +330,285 @@ test.describe("home screen", () => {
 });
 ```
 
-The destructured fixtures (`member`, `home`, `mock`, …) are exactly the `screens` you
+The destructured fixtures (`member`, `home`, `mock`, `driver`, …) are exactly the `screens` you
 declared in `defineApp`, plus `mock` and `driver` — typed to your app.
 
-### Locators & assertions
+> **Where imports come from:** specs import **`test` / `expect`** from your
+> `nativeproof.config.ts` (the typed pair `createHarness` returns). Everything else —
+> `page`, `by`, the gesture helpers (`swipe` / `tapAt`), `captureState`, and the types —
+> imports from the **`nativeproof`** package directly.
+
+### Fixtures, roles & the app seam
+
+A scenario's context is provisioned **once** before its behaviours and torn down **once** after
+(the analogue of a Playwright scoped fixture / `describe.serial`) — so a single sign-in underpins
+many ordered checks instead of re-logging-in per test. The order is: `driver` → `mock` →
+`login(role)` → `join(role)` → build `screens`.
+
+The **role** string from `test.describe(title, role, …)` flows into `login`/`join`, so one app
+definition drives many roles:
+
+```ts
+const app = defineApp({
+  driver: () => wdioDriver(),
+  mock: () => startMockServer({ port: 18113, host: "0.0.0.0" }),
+  secrets: [/\b\d{6}\b/], // e.g. a 6-digit OTP — redacted from evidence
+
+  // runs once per describe, before screens are built:
+  login: async ({ driver, role }) => {
+    const p = page(driver);
+    await p.getByTestId("email").fill(`${role}@example.com`); // taps to focus, then types
+    await p.getByRole("button", { name: "Sign in" }).tap();
+  },
+
+  // enters the role's main surface after login:
+  join: async ({ driver, role }) => {
+    if (role === "member") await page(driver).getByText("My rooms").tap();
+  },
+
+  screens: {
+    member: ({ driver }) => ({ messages: page(driver).getByTestId("message-list") }),
+    guest: ({ driver }) => ({ banner: page(driver).getByTestId("signup-banner") }),
+  },
+});
+```
+
+```ts
+test.describe("a signed-in member", "member", () => { /* uses { member, mock } */ });
+test.describe("a guest", "guest", () => { /* uses { guest, mock } */ });
+```
+
+> NativeProof locators **read, tap and fill** (text entry). For input `fill()` doesn't cover
+> (clearing a field first, custom keyboards, key chords), drive WebdriverIO's `$(...).setValue(...)`
+> directly inside `login` (the `@wdio/globals` `browser`/`$` are available in the live session).
+
+### Locators
+
+Build locators by intent; NativeProof maps each to the right native attribute per platform — so
+you address elements the way a person describes them, not by `content-desc` vs `name`:
+
+```ts
+const p = page(driver);
+p.getByText("Sign in");                  // visible text
+p.getByTestId("login-button");           // your test id
+p.getByLabel("Sign out");                // accessibility label
+p.getById("message-list");               // resource id
+p.getByRole("button", { name: "Send" }); // accessible name (role is advisory on native)
+p.locator(by.desc("Open menu"));         // escape hatch: a raw selector
+```
+
+How each maps to the page source:
+
+| Locator | Android attribute | iOS attribute |
+|---|---|---|
+| `getByText` / `by.text` | `text` or `content-desc` | `label` or `value` |
+| `getByLabel` / `by.label` / `getByRole({name})` | `content-desc` | `label` |
+| `getByTestId` / `by.testId` | `resource-id` | `name` |
+| `getById` / `by.id` | `resource-id` | `name` |
+| `by.desc` | `content-desc` | `name` |
+
+> **`getByText` is forgiving.** A visible label surfaces as `text` *or* `content-desc` on Android
+> (Jetpack Compose) and as `label` *or* `value` on iOS (SwiftUI), so `getByText` / `by.text` finds
+> the label wherever the toolkit put it — not just the node's own `text`. Reach for `getByLabel` /
+> `by.desc` when you specifically want the accessibility description.
 
-Build locators by intent; NativeProof maps each to the right native attribute per platform:
+A `Locator` is a lazy, awaitable handle with built-in waiting:
 
 ```ts
-page(driver).getByText("Sign in");                 // Android text / iOS label
-page(driver).getByTestId("login-button");          // Android resource-id / iOS accessibilityIdentifier
-page(driver).getByLabel("Sign out");               // Android content-desc / iOS label
-page(driver).getByRole("button", { name: "Send" });// accessible-name match (role is advisory on native)
+await member.messages.isVisible();      // boolean, no waiting
+await member.roomTitle.textContent();   // the node's own text, or null
+await member.spinner.waitFor();         // wait until visible (throws on timeout)
+await member.sendButton.tap();          // wait for it, then tap its centre
+await member.sendButton.tap({ timeout: 2_000, interval: 100 }); // tune the wait
+await member.row.tap({ clickableAncestor: true }); // tap the clickable parent of a non-clickable label
+await member.composer.fill("Hello team"); // focus the field (tap), then type
 ```
 
-Assertions auto-wait (poll until the condition holds or the timeout elapses), and `.not` inverts:
+`tap()` resolves the element's bounds from the page source and taps the centre — a coordinate
+tap that works even on Compose / SwiftUI nodes Appium reports as non-clickable.
+
+On Compose / SwiftUI the visible label often sits on a **non-clickable** child of the real touch
+target (a list row, a card). `tap({ clickableAncestor: true })` taps the smallest
+`clickable="true"` ancestor that fully contains the matched node instead of the node's own centre,
+falling back to the node itself when nothing clickable wraps it.
+
+`fill(text, opts?)` focuses the field with a `tap()` and types `text` through the device keyboard
+— the native analogue of Playwright's `locator.fill()`. It types into the focused field and does
+**not** clear existing content first; it needs a driver with text input (the bundled `wdioDriver()`
+has it) and throws a clear error otherwise. `opts` is the same `{ timeout?, interval? }` as `tap()`.
+
+### Assertions
+
+Assertions **auto-wait** (poll until the condition holds or the timeout elapses, default
+**10s** / 250ms interval), accept a string or `RegExp`, and `.not` inverts:
 
 ```ts
 await expect(member.messages).toBeVisible();
-await expect(member.messages).toShow("Welcome to the room");        // visible + text present
-await expect(member.roomTitle).toHaveText(/Room: \w+/);
+await expect(member.messages).toShow("Welcome to the room");   // present + text anywhere on screen
+await expect(member.roomTitle).toHaveText(/Room: \w+/);        // the node's OWN text (substring or regex)
 await expect(member.spinner).not.toBeVisible({ timeout: 5_000 });
-await member.signOut.tap();                                         // waits, then taps
 ```
 
+- `toBeVisible(opts?)` — the selector matches a node in the source.
+- `toShow(text, opts?)` — the selector is present **and** `text` appears in the source.
+- `toHaveText(text, opts?)` — the matched node's **own** text contains / matches `text`.
+- `opts` is `{ timeout?, interval? }` (ms).
+
+**Value matchers** — `expect(value)` also takes a plain value, for the non-UI assertions a spec
+still needs (counts, ids, parsed payloads). The locator and mock matchers auto-wait and return
+promises; value matchers assert a value you already have, so they are **synchronous** (no `await`)
+and `.not` inverts:
+
+```ts
+const frames = await mock.frames();
+
+expect(2 + 2).toBe(4);                          // strict identity (Object.is)
+expect(frames).toContain(someFrame);            // membership (arrays) or substring (strings)
+expect({ id: 7, name: "Ada" }).toEqual(user);   // deep structural equality
+expect(member.unreadBadge).toBeTruthy();
+expect(reply.error).toBeNull();
+expect(reply.id).toBeDefined();
+expect(reply.id).not.toBe(previousId);
+```
+
+- `toBe(expected)` — strict identity (`Object.is`).
+- `toEqual(expected)` — deep structural equality.
+- `toContain(expected)` — substring (for strings) or membership (for arrays).
+- `toBeTruthy()` / `toBeFalsy()` / `toBeDefined()` / `toBeNull()` — value guards.
+
+This keeps every assertion in a spec under one `expect`, so there's no second assertion library to
+import for the checks the UI/traffic matchers don't cover.
+
 ### Network interception & assertions
 
 The mock backend works like Playwright's `page.route()`. **Intercept** a path to control its
-reply, and **assert** the traffic the app exchanged:
+reply, and **assert** the traffic the app exchanged — over both REST and WebSocket:
 
 ```ts
 test.describe("send failures", "member", () => {
   test("surfaces a rejected send", async ({ member, mock }) => {
-    // Interception — control how a path replies (routes apply to the next request/connect):
-    await mock.route("/messages").reject({ code: 4 });         // or .fulfill({ ... }) / .abort()
+    // Interception — routes apply to the next request/connect on that path:
+    await mock.route("/messages").reject({ code: 503 }); // HTTP status, or WS close code (3000–4999)
     await member.sendButton.tap();
     await expect(member.errorBanner).toShow("Couldn't send message");
   });
 });
 
+test.describe("loading a room", "member", () => {
+  test("renders history fetched on open", async ({ member, mock }) => {
+    // fulfill answers the request/connect with a canned frame/body:
+    await mock.route("/messages").fulfill({ type: "history", messages: ["Hello", "Hi there"] });
+    await expect(member.messages).toShow("Hi there");
+  });
+});
+
 test.describe("chat room", "member", () => {
   test("sends a message and receives the next one", async ({ mock }) => {
-    // Assertion — what the app sent / received, matched by path + type + payload fields:
-    await expect(mock).toHaveSent({ path: "/messages", type: "create" });
+    // Assertions — matched by path + type + any payload field:
+    await expect(mock).toHaveSent({ path: "/messages", type: "create" });     // a WS message
+    await expect(mock).toHaveSent({ path: "/profile", type: "request", method: "GET" }); // a REST call
     await expect(mock).toHaveReceived({ path: "/messages", type: "new" });
     await expect(mock).not.toHaveSent({ type: "error" });
   });
 });
 ```
 
-- `mock.route(path).fulfill(frame)` — answer the request/connect with a canned frame/body.
-- `mock.route(path).reject({ code })` — fail it (WS close / HTTP status).
-- `mock.route(path).abort()` — drop it.
-- `expect(mock).toHaveSent(match)` / `toHaveReceived(match)` — `match` is a partial frame
-  (`path`/`type` plus any payload fields).
+- `mock.route(path).fulfill(frame)` — answer with a canned frame/body (WS connect reply or HTTP JSON).
+- `mock.route(path).reject({ code })` — fail it (HTTP status, or WebSocket close code 3000–4999).
+- `mock.route(path).abort()` — drop the connect/request entirely.
+- `expect(mock).toHaveSent(match)` / `toHaveReceived(match)` — `match` is a partial frame:
+  `path` / `type` plus any payload fields.
+
+**Frame types** — real protocol messages keep their own `type` (a WS JSON message's `type`); the
+server also synthesises types for primitives so you can assert on them:
+
+| What the app did | Recorded as |
+|---|---|
+| Opened a WebSocket | `{ type: "open", direction: "sent" }` |
+| Sent a WS JSON message | `{ type: <message.type>, direction: "sent", payload }` |
+| Made an HTTP request | `{ type: "request", direction: "sent", payload: { method } }` |
+| Got a fulfilled reply | `{ type: <frame.type ?? "response" | "message">, direction: "received" }` |
+
+`startMockServer()` is a real HTTP + WebSocket server (`url` / `wsUrl`), so there's no per-app
+adapter — your app just points at it. It can also push a server-initiated frame to open sockets
+with `server.send(path, frame)` (useful for simulating an incoming message in a config-level helper).
+
+### Bring your own backend
 
-`startMockServer()` is a real HTTP + WebSocket server, so no per-app adapter is needed — your
-app just points at its `url` / `wsUrl`.
+`startMockServer` is the batteries-included option, but `defineApp({ mock })` accepts **any**
+`MockBackend`. An app with its own protocol (or an existing mock server) injects a small adapter
+that exposes the three-method contract — then `route()` and the traffic assertions work unchanged:
+
+```ts
+import { defineApp, type MockBackend, type MockFrame, type MockRoute, wdioDriver } from "nativeproof";
+
+function adapt(server: MyExistingMock): MockBackend {
+  return {
+    frames: async (): Promise<MockFrame[]> =>
+      server.log.map((f) => ({
+        path: f.path,
+        type: f.kind,
+        direction: f.outbound ? "sent" : "received",
+        payload: f.body,
+      })),
+    route: (path: string): MockRoute => ({
+      fulfill: (frame) => server.stub(path, frame),
+      reject: ({ code }) => server.fail(path, code),
+      abort: () => server.drop(path),
+    }),
+    stop: () => server.close(),
+  };
+}
+
+const app = defineApp({
+  driver: () => wdioDriver(),
+  mock: () => adapt(startMyMock()),
+  screens: {
+    /* … */
+  },
+});
+```
+
+The framework depends only on the `MockBackend` interface, never a concrete server — so
+`expect(mock).toHaveSent(...)` reads your backend's traffic with no other changes.
+
+### Gestures & scrolling
+
+For motion the locator layer doesn't cover (scrolling a list, swiping a carousel), use the
+low-level pointer helpers — coordinates are in screen pixels:
+
+```ts
+import { swipe, tapAt, pause } from "nativeproof";
+
+await swipe(540, 1500, 540, 500);  // drag up to scroll a feed down (fromX, fromY, toX, toY, duration=600)
+await tapAt(540, 120);             // a raw coordinate tap
+await pause(250);                  // idle (e.g. let an animation settle)
+```
+
+A common pattern: swipe until the target appears, then assert.
+
+```ts
+while (!(await member.messages.shows("Older message"))) {
+  await swipe(540, 1500, 540, 600);
+}
+await expect(member.messages).toShow("Older message");
+```
+
+### Evidence & secrets
+
+A passing mobile test should prove app state, not just "the runner didn't throw". Capture a
+screenshot + a **redacted** page-source snapshot at any meaningful step:
+
+```ts
+import { captureState } from "nativeproof";
+
+await member.sendButton.tap();
+await captureState("after-send"); // writes .e2e-artifacts/after-send.png + after-send.xml (redacted)
+```
+
+- Artifacts land in `.e2e-artifacts/` (override with the `E2E_ARTIFACT_DIR` env var).
+- Source is redacted before it touches disk: built-in patterns strip 4–8 digit values, `passcode`
+  fields, and `Bearer` tokens; add your app's own patterns via `secrets` / `redact` in `defineApp`.
 
 ## Running
 
@@ -315,13 +621,14 @@ nativeproof --project tablet         # a named project from nativeproof.config.t
 nativeproof --spec tests/chat.spec.ts
 nativeproof --config wdio.conf.ts    # escape hatch: a raw WebdriverIO config
 nativeproof --no-appium              # use an Appium server you started yourself
+nativeproof --appium-host 10.0.0.5 --appium-port 4723   # point at a remote/farm Appium
 nativeproof --help
 ```
 
 `nativeproof` discovers `nativeproof.config.ts` (or falls back to a `wdio.conf.ts`), ensures an
-Appium server is reachable (starting one unless `--no-appium`), and runs the suite with
-`PLATFORM` / `SPEC` / `NATIVEPROOF_PROJECT` / `APPIUM_*` set. A device or emulator must already
-be running — the mobile analogue of needing a display.
+Appium server is reachable (starting one with `--relaxed-security` unless `--no-appium`), and runs
+the suite with `PLATFORM` / `SPEC` / `NATIVEPROOF_PROJECT` / `APPIUM_*` set for you. A device or
+emulator must already be running — the mobile analogue of needing a display.
 
 ## CI
 
@@ -345,33 +652,90 @@ jobs:
           script: npx nativeproof --platform android
 ```
 
-**iOS** runs the same way on a `macos-latest` runner (Xcode + a booted simulator), with
-`npx nativeproof --platform ios`. To offload either platform, point a project's Appium
-`host`/`port` (in `nativeproof.config.ts`, or `nativeproof --appium-host/--appium-port`) at a
-**device farm** (BrowserStack, Sauce Labs, Firebase Test Lab) — NativeProof is just Appium, so
-no test changes are needed.
+**iOS (GitHub Actions, macOS runner + simulator):**
+
+```yaml
+jobs:
+  ios-e2e:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npx appium driver install xcuitest
+      - run: xcrun simctl boot "iPhone 15" || true
+      - run: npx nativeproof --platform ios
+```
+
+To offload either platform, point a project's Appium `host`/`port` (in `nativeproof.config.ts`,
+or `nativeproof --appium-host/--appium-port`) at a **device farm** (BrowserStack, Sauce Labs,
+Firebase Test Lab) — NativeProof is just Appium, so no test changes are needed.
 
 The framework's own unit suite (`npm test`) needs **no device** and runs anywhere.
 
 ## Configuration
 
-| Where | What |
+**`defineConfig({ ... })`**
+
+| Field | Type | Default | What |
+|---|---|---|---|
+| `app` | `App` | — | the app under test (from `defineApp`) |
+| `projects` | `DeviceProject[]` | — | device targets; each `{ name, platform, capabilities }` |
+| `testDir` | `string` | `"tests"` | directory holding the specs |
+| `testMatch` | `string` | `"**/*.spec.ts"` | glob within `testDir` |
+| `appium` | `{ host?, port?, path? }` | `127.0.0.1` : `4723` `/wd/hub` | Appium connection |
+| `mochaTimeout` | `number` | `240000` | per-test timeout (ms) |
+
+**`defineApp({ ... })`** — the seam
+
+| Field | Type | What |
+|---|---|---|
+| `driver` | `() => Driver` | acquire the device (e.g. `wdioDriver()`) |
+| `mock` | `() => MockBackend` | start the mock backend (e.g. `startMockServer(...)`) |
+| `screens` | `Record<string, factory>` | screen-object factories, bound to the device context |
+| `login?` | `({ driver, mock, role }) => Promise` | reach a logged-in state for the role |
+| `join?` | `({ driver, mock, role }) => Promise` | enter the role's main surface |
+| `secrets?` | `RegExp[]` | patterns kept out of captured evidence |
+| `redact?` | `RegExp[]` | extra evidence-redaction patterns |
+
+**CLI flags & env**
+
+| Flag | Env it sets | Default |
+|---|---|---|
+| `--platform <android\|ios>` | `PLATFORM` | — |
+| `--project <name>` | `NATIVEPROOF_PROJECT` | first project |
+| `--spec <glob>` | `SPEC` | all specs in `testDir` |
+| `--config <path>` | — | auto-discovered |
+| `--appium-host/-port/-path` | `APPIUM_HOST/PORT/PATH` | `127.0.0.1` / `4723` / `/wd/hub` |
+| `--no-appium` | — | auto-start Appium |
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
 |---|---|
-| `nativeproof.config.ts` | `defineConfig({...})`: the `app`, device `projects`, `testDir`, `appium`, and the `test`/`expect` exports. |
-| `defineApp({...})` | The seam: `driver`, `mock`, `login`, `join`, `screens`, `secrets`, `redact`. |
-| `nativeproof` flags | `--platform`, `--project`, `--spec`, `--config`, `--appium-host/port/path`, `--no-appium`. |
-| Env | `PLATFORM`, `NATIVEPROOF_PROJECT`, `SPEC`, `APPIUM_HOST/PORT/PATH` (set by the CLI; read by the synthesised config). |
+| `Appium is not reachable …` | No device, or `--no-appium` set without a server. Boot the emulator/simulator; drop `--no-appium` to let NativeProof start Appium. |
+| `no nativeproof.config.ts or wdio.conf.ts found` | Run from the project root, or pass `--config <path>`. |
+| "No specs found" | Specs must match `testDir`/`testMatch` (default `tests/**/*.spec.ts`), or pass `--spec`. |
+| App can't reach the mock | Emulator → use `10.0.2.2`; real device → your machine's LAN IP. Bind the mock with `host: "0.0.0.0"`. |
+| `expect(...)` times out | The selector never matched — confirm the attribute mapping (see the [Locators](#locators) table) and the value; raise `{ timeout }` for slow screens. |
+| iOS first run hangs | WebDriverAgent is building/signing. Set `appium:wdaLaunchTimeout` and, on a real device, the signing capabilities. |
 
 ## API reference
 
-- `defineApp(definition)` → `app` — the seam; `app.session(role?)` is a fixture.
+- `defineApp(definition)` → `app` — the seam; `app.session(role?)` is a scenario fixture.
 - `createHarness(app)` → `{ test, expect }` — typed, app-bound test surface.
-- `defineConfig({ app, projects, testDir?, appium? })` — the `nativeproof.config.ts` the CLI runs.
-- `by.text/testId/label/desc/id`, `page(driver).getByText/getByTestId/getByLabel/getById/getByRole`,
-  `new Locator(driver, selector)` — locators (`isVisible`, `textContent`, `tap`, `waitFor`, …).
-- `expect(locator)` → `toBeVisible` / `toShow` / `toHaveText` (+ `.not`).
-- `expect(mock)` → `toHaveSent` / `toHaveReceived` (+ `.not`).
-- `startMockServer({ port?, host? })` → a `MockBackend` with `route()`, `frames()`, `send()`.
+- `defineConfig({ app, projects, testDir?, testMatch?, appium?, mochaTimeout? })` — the config the CLI runs.
+- `by.text/desc/id/testId/label`, `page(driver).getByText/getByTestId/getByLabel/getById/getByRole`,
+  `page(driver).locator(selector)`, `new Locator(driver, selector)` — locators
+  (`isVisible`, `textContent`, `bounds`, `shows`, `waitFor`, `tap`, `fill` — `tap({ clickableAncestor })`
+  for non-clickable labels).
+- `expect(locator)` → `toBeVisible` / `toShow` / `toHaveText` (+ `.not`), each `(value?, { timeout?, interval? })`.
+- `expect(mock)` → `toHaveSent` / `toHaveReceived` (+ `.not`), matched by partial frame.
+- `expect(value)` → `toBe` / `toEqual` / `toContain` / `toBeTruthy` / `toBeFalsy` / `toBeDefined` / `toBeNull` (+ `.not`) — synchronous matchers for plain values.
+- `startMockServer({ port?, host? })` → a `MockServer` (`url`, `wsUrl`, `route()`, `frames()`, `send()`, `stop()`).
+- `swipe`, `tapAt`, `pause` — low-level pointer gestures.
+- `captureState(prefix)` / `captureScreenshot` / `captureText` / `redactEvidenceText` — evidence.
 - Device commands — **Android** (`adb`): `adbForceStop`, `resetAppAndBrowserState`, `adbTap`, `adbDump`, `adbLogcat*`; **iOS** (`simctl`): `iosTerminate`, `iosLaunch`, `iosInstall`, `iosUninstall`, `iosBoot`, `iosShutdown`, `resetAppState`, `iosLogShow`.
 - `wdioDriver()` → the live `Driver`; `useRunner(hooks)` to host on a non-Mocha runner.
 
@@ -379,13 +743,13 @@ The framework's own unit suite (`npm test`) needs **no device** and runs anywher
 
 The engine is Appium/WebdriverIO; NativeProof is the DX layer. It's app-agnostic by contract:
 a consuming app injects all of its specifics through `defineApp`, and nothing in the package
-imports app code (dependency is one-way, app → framework). The whole DX self-verifies against
+imports app code (the dependency is one-way, app → framework). The whole DX self-verifies against
 an in-memory fake device — see `test/demo.test.ts` and run `npm test` (no emulator needed).
 
 Package layout: `app.ts` (`defineApp`), `harness.ts` (`createHarness`), `config.ts`
 (`defineConfig`) + `runner-config.ts` (the wdio bridge), `fixtures.ts`, `locator.ts` +
 `page.ts`, `expect.ts`, `mock.ts` + `mock-server.ts`, `driver.ts`, `runner.ts`, `cli.ts`
-(the `nativeproof` bin), plus source/wait/gesture/adb/log/evidence primitives.
+(the `nativeproof` bin), plus source/wait/gesture/adb/ios/log/evidence primitives.
 
 ## License
 

package/dist/driver.d.ts

@@ -15,6 +15,11 @@ export interface Driver {
     pause(ms: number): Promise<void>;
     /** Tap an absolute screen coordinate. */
     tapAt(x: number, y: number): Promise<void>;
+    /**
+     * Type into the currently focused element (keyboard input). Optional: drivers that
+     * cannot type leave it undefined, and {@link Locator.fill} throws a clear error.
+     */
+    typeText?(text: string): Promise<void>;
 }
 /** A {@link Driver} backed by the live WebdriverIO/Appium session. */
 export declare function wdioDriver(): Driver;

package/dist/driver.js

@@ -9,5 +9,6 @@ export function wdioDriver() {
         source: () => browser.getPageSource().catch(() => ""),
         pause: (ms) => browser.pause(ms),
         tapAt: (x, y) => tapAt(x, y),
+        typeText: (text) => browser.keys(text),
     };
 }

package/dist/expect.d.ts

@@ -22,5 +22,24 @@ export interface MockAssertions {
     /** The app received a frame matching `match`. */
     toHaveReceived(match: FrameMatch, options?: WaitOptions): Promise<void>;
 }
+/**
+ * Synchronous matchers for a plain value — for the non-UI assertions a spec still needs
+ * (counts, ids, parsed payloads). UI/traffic matchers auto-wait and return promises;
+ * these assert a value that is already known, so they run synchronously and `.not` inverts.
+ */
+export interface ValueAssertions<T> {
+    readonly not: ValueAssertions<T>;
+    /** Strict identity (`Object.is`). */
+    toBe(expected: T): void;
+    /** Deep structural equality. */
+    toEqual(expected: T): void;
+    /** Substring (for strings) or membership (for arrays). */
+    toContain(expected: unknown): void;
+    toBeTruthy(): void;
+    toBeFalsy(): void;
+    toBeDefined(): void;
+    toBeNull(): void;
+}
 export declare function expect(target: Locator): LocatorAssertions;
 export declare function expect(target: MockBackend): MockAssertions;
+export declare function expect<T>(target: T): ValueAssertions<T>;

package/dist/expect.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import { describeSelector, Locator, waitUntil } from "./locator.js";
 import { describeMatch, frameExists } from "./mock.js";
 class LocatorExpectation {
@@ -60,6 +61,70 @@ class MockExpectation {
         }
     }
 }
+function describeValue(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+class ValueExpectation {
+    actual;
+    negated;
+    constructor(actual, negated = false) {
+        this.actual = actual;
+        this.negated = negated;
+    }
+    get not() {
+        return new ValueExpectation(this.actual, !this.negated);
+    }
+    toBe(expected) {
+        this.assert(Object.is(this.actual, expected), "toBe", describeValue(expected));
+    }
+    toEqual(expected) {
+        this.assert(isDeepStrictEqual(this.actual, expected), "toEqual", describeValue(expected));
+    }
+    toContain(expected) {
+        const ok = typeof this.actual === "string"
+            ? this.actual.includes(String(expected))
+            : Array.isArray(this.actual)
+                ? this.actual.includes(expected)
+                : false;
+        this.assert(ok, "toContain", describeValue(expected));
+    }
+    toBeTruthy() {
+        this.assert(Boolean(this.actual), "toBeTruthy");
+    }
+    toBeFalsy() {
+        this.assert(!this.actual, "toBeFalsy");
+    }
+    toBeDefined() {
+        this.assert(this.actual !== undefined, "toBeDefined");
+    }
+    toBeNull() {
+        this.assert(this.actual === null, "toBeNull");
+    }
+    assert(pass, matcher, expectedDesc = "") {
+        const want = !this.negated;
+        if (pass === want)
+            return;
+        const not = this.negated ? ".not" : "";
+        throw new Error(`expect(${describeValue(this.actual)})${not}.${matcher}(${expectedDesc}) — assertion not met`);
+    }
+}
+/** Structural guard: a {@link MockBackend} is anything with `frames`/`route`/`stop`. */
+function isMockBackend(target) {
+    return (typeof target === "object" &&
+        target !== null &&
+        typeof target.frames === "function" &&
+        typeof target.route === "function" &&
+        typeof target.stop === "function");
+}
 export function expect(target) {
-    return target instanceof Locator ? new LocatorExpectation(target) : new MockExpectation(target);
+    if (target instanceof Locator)
+        return new LocatorExpectation(target);
+    if (isMockBackend(target))
+        return new MockExpectation(target);
+    return new ValueExpectation(target);
 }

package/dist/locator.d.ts

@@ -47,6 +47,14 @@ export interface WaitOptions {
     /** Sleep awaited between polls; defaults to a real timer. The locator injects the driver's pause. */
     sleep?: (ms: number) => Promise<void>;
 }
+export interface TapOptions extends WaitOptions {
+    /**
+     * Tap the smallest `clickable="true"` ancestor that contains the matched node, rather
+     * than the node itself. Compose/SwiftUI often expose a label on a non-clickable child;
+     * this taps the real touch target around it.
+     */
+    clickableAncestor?: boolean;
+}
 /**
  * Poll `produce` until `done(value)` holds or the timeout elapses, returning the
  * last value either way (callers decide what an unmet condition means). The interval
@@ -72,7 +80,13 @@ export declare class Locator {
     /** Wait until the selector is visible; throws on timeout. */
     waitFor(options?: WaitOptions): Promise<void>;
     /** Wait for the element, then tap its centre (a source-bounds coordinate tap). */
-    tap(options?: WaitOptions): Promise<void>;
+    tap(options?: TapOptions): Promise<void>;
+    /**
+     * Focus the field (tap it) and type `text`. Requires a driver with text input
+     * ({@link Driver.typeText}); throws a clear error otherwise. Types into the focused
+     * field — it does not clear existing content first.
+     */
+    fill(text: string, options?: WaitOptions): Promise<void>;
 }
 /** Convenience factory: `locator(driver, by.text("Submit"))`. */
 export declare function locator(driver: Driver, selector: Selector, options?: WaitOptions): Locator;

package/dist/locator.js

@@ -1,4 +1,4 @@
-import { boundsForAttribute } from "./source.js";
+import { boundsForAttribute, decodeXmlEntities, encodeXmlEntities, smallestClickableAncestorBounds, } from "./source.js";
 /**
  * Build selectors Playwright-style. The cross-platform attribute each maps to is resolved
  * per platform (see {@link attributeFor}), so you never have to know whether it's a
@@ -20,16 +20,21 @@ export function describeSelector(selector) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/** The page-source attribute a selector resolves to on each platform. */
+/**
+ * The page-source attribute a selector resolves to on each platform. `text` is an
+ * alternation, because a visible label surfaces as `text` OR `content-desc` on Android
+ * (Compose) and as `label` OR `value` on iOS — so `getByText` finds a label wherever
+ * the toolkit put it, not just the node's own `text` attribute.
+ */
 function attributeFor(selector, platform) {
     const android = {
-        text: "text",
+        text: "(?:text|content-desc)",
         desc: "content-desc",
         id: "resource-id",
         testId: "resource-id",
         label: "content-desc",
     };
-    const ios = { text: "label", desc: "name", id: "name", testId: "name", label: "label" };
+    const ios = { text: "(?:label|value)", desc: "name", id: "name", testId: "name", label: "label" };
     return (platform === "ios" ? ios : android)[selector.by];
 }
 const DEFAULTS = { timeout: 10_000, interval: 250 };
@@ -65,7 +70,7 @@ export class Locator {
         return attributeFor(this.selector, this.driver.platform);
     }
     presencePattern() {
-        return new RegExp(`${this.attribute()}="${escapeRegExp(this.selector.value)}"`);
+        return new RegExp(`${this.attribute()}="${escapeRegExp(encodeXmlEntities(this.selector.value))}"`);
     }
     /** True if the selector matches a node in the current source. */
     async isVisible() {
@@ -78,18 +83,20 @@ export class Locator {
     /** The matched node's own visible text, or null if the node is absent. */
     async textContent() {
         const source = await this.driver.source();
-        const node = new RegExp(`<[^>]*${this.attribute()}="${escapeRegExp(this.selector.value)}"[^>]*>`).exec(source)?.[0];
+        const selectorPattern = escapeRegExp(encodeXmlEntities(this.selector.value));
+        const node = new RegExp(`<[^>]*${this.attribute()}="${selectorPattern}"[^>]*>`).exec(source)?.[0];
         if (!node)
             return null;
         const textAttr = this.driver.platform === "ios" ? "value|label" : "text";
-        return new RegExp(`(?:${textAttr})="([^"]*)"`).exec(node)?.[1] ?? null;
+        const raw = new RegExp(`(?:${textAttr})="([^"]*)"`).exec(node)?.[1];
+        return raw == null ? null : decodeXmlEntities(raw);
     }
     /** True if the selector is present AND `text` appears in the source. */
     async shows(text) {
         const source = await this.driver.source();
         if (!this.presencePattern().test(source))
             return false;
-        const pattern = typeof text === "string" ? new RegExp(escapeRegExp(text)) : text;
+        const pattern = typeof text === "string" ? new RegExp(escapeRegExp(encodeXmlEntities(text))) : text;
         return pattern.test(source);
     }
     /** Wait until the selector is visible; throws on timeout. */
@@ -107,7 +114,22 @@ export class Locator {
         if (!bounds) {
             throw new Error(`${describeSelector(this.selector)} was not found to tap within ${opts.timeout ?? DEFAULTS.timeout}ms`);
         }
-        await this.driver.tapAt(bounds.centerX, bounds.centerY);
+        const target = options.clickableAncestor
+            ? smallestClickableAncestorBounds(await this.driver.source(), bounds)
+            : bounds;
+        await this.driver.tapAt(target.centerX, target.centerY);
+    }
+    /**
+     * Focus the field (tap it) and type `text`. Requires a driver with text input
+     * ({@link Driver.typeText}); throws a clear error otherwise. Types into the focused
+     * field — it does not clear existing content first.
+     */
+    async fill(text, options = {}) {
+        if (!this.driver.typeText) {
+            throw new Error(`${describeSelector(this.selector)}.fill(...) needs a driver that supports text input (Driver.typeText)`);
+        }
+        await this.tap(options);
+        await this.driver.typeText(text);
     }
 }
 /** Convenience factory: `locator(driver, by.text("Submit"))`. */

package/dist/source.d.ts

@@ -18,6 +18,18 @@ export type Bounds = {
     centerY: number;
 };
 export declare function parseBounds(bounds: string | undefined | null): Bounds | null;
+/**
+ * Decode the XML entities UiAutomator/XCUITest escape attribute values with
+ * (`&amp;` → `&`, `&lt;` → `<`, …). `&amp;` is decoded LAST so `&amp;lt;` round-trips
+ * to the literal `&lt;` rather than `<`.
+ */
+export declare function decodeXmlEntities(value: string): string;
+/**
+ * Encode a human-readable value to the entity-escaped form the page source uses, so a
+ * selector built from a plain string (`"Terms & Conditions"`) matches the escaped source
+ * (`text="Terms &amp; Conditions"`). `&` is encoded first to avoid double-encoding.
+ */
+export declare function encodeXmlEntities(value: string): string;
 /** Bounds of the first element whose `bounds` follows the given attribute match. */
 export declare function boundsForAttribute(source: string, attribute: string, value: string): Bounds | null;
 /** Bounds of an element addressed by Android `content-desc`. */
@@ -25,8 +37,10 @@ export declare function boundsForContentDesc(source: string, contentDesc: string
 /** Bounds of an element addressed by visible `text`. */
 export declare function boundsForText(source: string, text: string): Bounds | null;
 /**
- * The smallest clickable ancestor that fully contains the given text node — used
- * to turn a non-clickable Compose `TextView` into a reliable tap target (e.g. the
- * "Members (3)" list rows).
+ * The smallest element flagged `clickable="true"` that fully contains the given
+ * bounds, or the bounds themselves if none does — turns a non-clickable Compose node
+ * into a reliable tap target (e.g. the "Members (3)" list rows).
  */
+export declare function smallestClickableAncestorBounds(source: string, nodeBounds: Bounds): Bounds;
+/** The smallest clickable ancestor that fully contains the node with the given visible text. */
 export declare function clickableAncestorBoundsForText(source: string, text: string): Bounds | null;

package/dist/source.js

@@ -29,9 +29,31 @@ export function parseBounds(bounds) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+ * Decode the XML entities UiAutomator/XCUITest escape attribute values with
+ * (`&amp;` → `&`, `&lt;` → `<`, …). `&amp;` is decoded LAST so `&amp;lt;` round-trips
+ * to the literal `&lt;` rather than `<`.
+ */
+export function decodeXmlEntities(value) {
+    return value
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#0?39;|&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/**
+ * Encode a human-readable value to the entity-escaped form the page source uses, so a
+ * selector built from a plain string (`"Terms & Conditions"`) matches the escaped source
+ * (`text="Terms &amp; Conditions"`). `&` is encoded first to avoid double-encoding.
+ */
+export function encodeXmlEntities(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 /** Bounds of the first element whose `bounds` follows the given attribute match. */
 export function boundsForAttribute(source, attribute, value) {
-    const match = new RegExp(`${attribute}="${escapeRegExp(value)}"[^>]*bounds="([^"]+)"`).exec(source);
+    const escaped = escapeRegExp(encodeXmlEntities(value));
+    const match = new RegExp(`${attribute}="${escaped}"[^>]*bounds="([^"]+)"`).exec(source);
     return match ? parseBounds(match[1]) : null;
 }
 /** Bounds of an element addressed by Android `content-desc`. */
@@ -43,18 +65,20 @@ export function boundsForText(source, text) {
     return boundsForAttribute(source, "text", text);
 }
 /**
- * The smallest clickable ancestor that fully contains the given text node — used
- * to turn a non-clickable Compose `TextView` into a reliable tap target (e.g. the
- * "Members (3)" list rows).
+ * The smallest element flagged `clickable="true"` that fully contains the given
+ * bounds, or the bounds themselves if none does — turns a non-clickable Compose node
+ * into a reliable tap target (e.g. the "Members (3)" list rows).
  */
-export function clickableAncestorBoundsForText(source, text) {
-    const textBounds = boundsForText(source, text);
-    if (!textBounds)
-        return null;
+export function smallestClickableAncestorBounds(source, nodeBounds) {
     const clickable = [...source.matchAll(/clickable="true"[^>]*bounds="([^"]+)"/g)]
         .map((m) => parseBounds(m[1]))
         .filter((b) => b !== null)
-        .filter((b) => b.x1 <= textBounds.x1 && b.x2 >= textBounds.x2 && b.y1 <= textBounds.y1 && b.y2 >= textBounds.y2)
+        .filter((b) => b.x1 <= nodeBounds.x1 && b.x2 >= nodeBounds.x2 && b.y1 <= nodeBounds.y1 && b.y2 >= nodeBounds.y2)
         .sort((a, b) => a.width * a.height - b.width * b.height);
-    return clickable[0] ?? textBounds;
+    return clickable[0] ?? nodeBounds;
+}
+/** The smallest clickable ancestor that fully contains the node with the given visible text. */
+export function clickableAncestorBoundsForText(source, text) {
+    const textBounds = boundsForText(source, text);
+    return textBounds ? smallestClickableAncestorBounds(source, textBounds) : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nativeproof",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",
@@ -36,7 +36,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",