prowl-tools 0.1.4 → 0.1.6

package/dist/lib.d.ts

@@ -22,7 +22,40 @@ type MacosTarget = {
     type: "macos";
     app: string;
 };
-type Target = WebTarget | MacosTarget;
+/**
+ * Android native execution target (experimental, PROWL-058). `app` is an Android
+ * package name (e.g. `com.example.app`) or an absolute/relative path to an `.apk`
+ * file, which Prowl installs before launch. Optional `deviceSerial` selects one of
+ * several attached devices/emulators; `coldStart` opts into a deterministic
+ * `pm clear` before launch (default off). Android guardrails match package IDs
+ * or canonical full APK paths; APK package IDs are resolved before install.
+ */
+type AndroidTarget = {
+    type: "android";
+    app: string;
+    /** adb device serial to target when more than one device is attached. */
+    deviceSerial?: string;
+    /** Run `pm clear <package>` before launch for a deterministic cold start (default off). */
+    coldStart?: boolean;
+};
+/**
+ * iOS simulator native execution target (experimental, PROWL-059). `app` is an
+ * iOS bundle identifier (e.g. `com.example.App`) or an absolute/relative path to
+ * a built `.app` bundle, which Prowl installs onto the simulator before launch.
+ * Optional `udid` selects a specific booted simulator; `coldStart` opts into an
+ * uninstall+reinstall before launch (default off, and only possible with a `.app`
+ * path). Real devices are out of scope (PROWL-062) — simulators only. iOS
+ * guardrails match bundle ids, the bundle name, or the canonical `.app` path.
+ */
+type IosTarget = {
+    type: "ios";
+    app: string;
+    /** UDID of the booted simulator to target when more than one is booted. */
+    udid?: string;
+    /** Uninstall+reinstall the app before launch for a deterministic cold start (default off). */
+    coldStart?: boolean;
+};
+type Target = WebTarget | MacosTarget | AndroidTarget | IosTarget;
 type Config = {
     target: Target;
     browser: {
@@ -48,7 +81,7 @@ type Config = {
     guardrails: {
         maxSteps: number;
         allowedDomains: string[];
-        /** Native scope analog of `allowedDomains`: allowed bundle IDs, app bundle names, or `.app` paths. */
+        /** Native scope analog of `allowedDomains`: allowed bundle/package IDs or canonical app artifact paths. */
         allowedApps: string[];
         forbiddenSelectors: string[];
         selfHealing: boolean;
@@ -263,7 +296,10 @@ type AssertScreenshotStep = {
         threshold?: number;
     };
 };
-type Step = NavigateStep | ClickStep | FillStep | TypeStep | PressStep | WaitStep | SelectOptionStep | SelectStep | OnDialogStep | SetInputFilesStep | InlineAssertStep | RunHuntStep | WaitForSelectorStep | WaitForUrlStep | WaitForNetworkIdleStep | HoverStep | ScrollStep | ScrollToStep | ScreenshotStep | IfStep | RepeatStep | MockRouteStep | UnmockRouteStep | EvalScriptStep | RunScriptStep | AssertScreenshotStep | CopyTextStep | WaitForDownloadStep;
+type AssertWithAiStep = {
+    assertWithAI: string;
+};
+type Step = NavigateStep | ClickStep | FillStep | TypeStep | PressStep | WaitStep | SelectOptionStep | SelectStep | OnDialogStep | SetInputFilesStep | InlineAssertStep | RunHuntStep | WaitForSelectorStep | WaitForUrlStep | WaitForNetworkIdleStep | HoverStep | ScrollStep | ScrollToStep | ScreenshotStep | IfStep | RepeatStep | MockRouteStep | UnmockRouteStep | EvalScriptStep | RunScriptStep | AssertScreenshotStep | AssertWithAiStep | CopyTextStep | WaitForDownloadStep;
 type Assertion = {
     selectorExists: string;
 } | {
@@ -279,7 +315,7 @@ type Assertion = {
 };
 type StepResult = {
     type: string;
-    status: "pass" | "fail";
+    status: "pass" | "fail" | "warn";
     durationMs: number;
     selector?: string;
     value?: string;
@@ -558,6 +594,758 @@ declare function launchMacSession(options: LaunchMacOptions): Promise<MacSession
 /** Quit the target app (best effort) and shut the helper down. */
 declare function closeMacSession(session: MacSession): Promise<void>;
 
+/** The selector kinds the native dialect understands. */
+type NativeSelectorKind = "id" | "label" | "text" | "role" | "focused";
+/**
+ * A Prowl native selector parsed into a neutral, platform-independent shape.
+ * `role` optionally carries a `name` (the `role=Type[name="…"]` form); `name` is
+ * present only when the bracket was supplied and non-empty.
+ */
+type NativeSelector = {
+    kind: "id";
+    value: string;
+} | {
+    kind: "label";
+    value: string;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "role";
+    role: string;
+    name?: string;
+} | {
+    kind: "focused";
+};
+/**
+ * Strip one layer of matching single/double quotes from a selector value. Mirrors
+ * the historical per-driver `unquote`, kept here so every native target unquotes
+ * identically.
+ */
+declare function unquoteSelectorValue(value: string): string;
+/** Wrap a selector value in double quotes (the ranker's canonical emitted form). */
+declare function quoteSelectorValue(value: string): string;
+/**
+ * Parse a Prowl selector string into a neutral {@link NativeSelector}. This is
+ * the single grammar shared by both mobile drivers (which then map the neutral
+ * kind onto their own wire query). Precedence — `:focus`, then `id=`, `role=`,
+ * `label=`, `text=`, and finally a bare string treated as `text=` — matches the
+ * behavior the per-driver parsers had before consolidation.
+ */
+declare function parseNativeSelector(selector: string): NativeSelector;
+/**
+ * The literal a `text=` selector matches, or null when `selector` is not an
+ * explicit `text=` form (a bare string is intentionally excluded — it mirrors the
+ * web driver's `parseTextSelector`, which `forbiddenSelectors` relies on). Shared
+ * so Android and iOS unwrap text selectors identically.
+ */
+declare function unwrapNativeTextSelector(selector: string): string | null;
+/**
+ * Qualify a bare Android `resource-id` with the app's package. The raw
+ * uiautomator2 server matches resource-ids exactly (bare names return no
+ * elements), so `id=save` becomes `<appPackage>:id/save`. Values that already
+ * contain a `:` (e.g. `android:id/title`) — or calls without a package — pass
+ * through untouched. Both the Android driver's locator translation and the
+ * host-side matcher qualify through this one function.
+ */
+declare function qualifyResourceId(value: string, appPackage?: string): string;
+/** Prefix `XCUIElementType` onto an iOS role shorthand (e.g. `Button`) when missing. */
+declare function normalizeXcuiClassName(role: string): string;
+/** Strip the `XCUIElementType` prefix for a friendlier `role=` shorthand. */
+declare function shortIosType(type: string): string;
+/**
+ * The per-node ingredients the ranker needs, already projected out of a
+ * platform's own node shape:
+ *   - `id`    the native identifier (Android resource-id, iOS accessibility id,
+ *             macOS AXIdentifier) → emitted as `id=`.
+ *   - `label` the exact accessibility label (Android content-desc, iOS label,
+ *             macOS title/description) → emitted as `label="…"`.
+ *   - `role`  the class/type/role string to emit verbatim (already shortened for
+ *             iOS) → emitted as `role=` and in `role=…[name="…"]`.
+ *   - `name`  the representative visible-text name used for `role=…[name]` and
+ *             the `text=` fallback.
+ */
+type NativeRankFields = {
+    id?: string;
+    label?: string;
+    role?: string;
+    name?: string;
+};
+/**
+ * Ranked selector candidates for a node, best → last resort:
+ *   `id=` > `label="…"` > `role=…[name="…"]` > `text="…"`, with a bare `role=`
+ * fallback so any node carrying a role stays addressable. This is the one ranking
+ * algorithm every native analyzer emits through, so a change to selector priority
+ * happens in exactly one place. Returns an empty array when a node exposes nothing
+ * addressable.
+ */
+declare function rankNativeSelectors(fields: NativeRankFields): string[];
+/** The native targets whose selector dialect this module defines. */
+type NativePlatform = "android" | "ios" | "macos";
+/** How a selector kind resolves on one platform (mirrors the matrix above). */
+type SelectorKindMapping = {
+    /** The native attribute(s) the kind targets. */
+    attribute: string;
+    /** The comparison mode against that attribute. */
+    match: "exact" | "exact (package-qualified)" | "substring";
+};
+/**
+ * The per-platform attribute mapping tables — the machine-readable form of the
+ * compatibility matrix, so the mapping is documented once and can be asserted in
+ * tests. Keyed by platform, then by the four addressable selector kinds. (`role`
+ * describes the bare `role=` form; the `role=…[name]` composite pairs an exact
+ * role with a substring name, per the matrix.)
+ */
+declare const NATIVE_ATTRIBUTE_MAP: Readonly<Record<NativePlatform, Readonly<Record<"id" | "label" | "text" | "role", SelectorKindMapping>>>>;
+/**
+ * A hierarchy node projected into the neutral attributes the matcher compares
+ * against. Platform code (analyzers, and later the runners/macdriver) projects
+ * its own node shape into this:
+ *   - `id`         native identifier for exact `id=` matching.
+ *   - `label`      exact accessibility label for exact `label=` matching.
+ *   - `role`       class/type/role in the platform's canonical (full) form; the
+ *                  dialect's {@link NativeMatchDialect.normalizeRole} reconciles a
+ *                  shorthand selector (`Button`) with a full node type.
+ *   - `textValues` every string a `text=` / `[name]` substring should test
+ *                  (Android: `[text]`; iOS: `[label, value]`; macOS:
+ *                  `[title, description, value]`).
+ *   - `focused`    whether the node currently holds keyboard focus (`:focus`).
+ */
+type NativeNode = {
+    id?: string;
+    label?: string;
+    role?: string;
+    textValues: string[];
+    focused?: boolean;
+};
+/** Options threaded into matching (currently only Android id package-qualification). */
+type NativeMatchOptions = {
+    /** App package used to qualify a bare Android `id=` before an exact compare. */
+    appPackage?: string;
+};
+/**
+ * The platform-specific part of matching: how to normalize a role/type string for
+ * comparison, and how to normalize an `id=` value before an exact id compare.
+ * Everything else (exact id/label, substring text, focus) is platform-independent.
+ */
+type NativeMatchDialect = {
+    platform: NativePlatform;
+    /** Canonicalize a role/type string so a shorthand selector matches a full node type. */
+    normalizeRole: (role: string) => string;
+    /** Canonicalize an `id=` value (Android package-qualifies bare ids; others identity). */
+    normalizeId: (value: string, options: NativeMatchOptions) => string;
+};
+/** Android matching dialect: identity role compare, package-qualified ids. */
+declare const ANDROID_MATCH_DIALECT: NativeMatchDialect;
+/** iOS matching dialect: `XCUIElementType…`-normalized role compare, identity ids. */
+declare const IOS_MATCH_DIALECT: NativeMatchDialect;
+/** macOS matching dialect (exposed for the future macdriver migration). */
+declare const MACOS_MATCH_DIALECT: NativeMatchDialect;
+/**
+ * Decide whether a single projected {@link NativeNode} satisfies a parsed
+ * {@link NativeSelector}, using the platform's attribute + match-mode semantics:
+ *   - `id`      exact match on `node.id` (Android value package-qualified first).
+ *   - `label`   exact match on `node.label`.
+ *   - `text`    substring match against any of `node.textValues`.
+ *   - `role`    exact (normalized) role match; with `name`, additionally a
+ *               substring match against any of `node.textValues`.
+ *   - `focused` node currently holds keyboard focus.
+ */
+declare function nodeMatchesSelector(dialect: NativeMatchDialect, selector: NativeSelector, node: NativeNode, options?: NativeMatchOptions): boolean;
+/**
+ * Walk a hierarchy of platform nodes depth-first and collect every node matching
+ * `selector`, in document order. Generic over the caller's own node type so the
+ * analyzers get their original, fully-typed nodes back: pass a `project` that maps
+ * a node to its {@link NativeNode} attributes and a `children` accessor.
+ */
+declare function matchNativeTree<T>(dialect: NativeMatchDialect, selector: NativeSelector, root: T, project: (node: T) => NativeNode, children: (node: T) => readonly T[], options?: NativeMatchOptions): T[];
+/**
+ * Parse a raw agent `/source` XML dump into an element tree (best-effort, via the
+ * dependency-free {@link parseXml}) so a caller can match against a snapshot
+ * without a device. Returns null when the payload holds no element.
+ */
+declare function parseSnapshot(xml: string): XmlElement | null;
+
+/** A structured query the {@link AndroidAgentClient} resolves against the device. */
+type AndroidQuery = {
+    by: "id";
+    value: string;
+} | {
+    by: "accessibilityId";
+    value: string;
+} | {
+    by: "role";
+    role: string;
+    name?: string;
+} | {
+    by: "text";
+    value: string;
+} | {
+    by: "focused";
+};
+/**
+ * A locator in the uiautomator2 server's native wire shape. The raw on-device
+ * server does NOT accept W3C `{using, value}` — that translation normally lives
+ * in Appium's driver layer, which we bypass — it requires `{strategy, selector}`
+ * (plus a `context` field, empty for a root-scoped search). Device-verified
+ * against appium-uiautomator2-server 10.6.2 (2026-08-19).
+ */
+type AndroidLocator = {
+    strategy: string;
+    selector: string;
+    context: string;
+};
+/**
+ * The semantic transport `AndroidDriver` talks to: element lookups return opaque
+ * element ids, and interactions take those ids. The HTTP/UiAutomator2
+ * implementation lives in {@link ./android-agent.js}; tests fake this interface.
+ */
+interface AndroidAgentClient {
+    /** Resolve the first element matching `query`, or null when none match. */
+    findElement(query: AndroidQuery): Promise<string | null>;
+    /** Resolve every element id matching `query` (empty when none match). */
+    findElements(query: AndroidQuery): Promise<string[]>;
+    click(elementId: string): Promise<void>;
+    /** Replace an element's text (unicode-safe; W3C `element/value`). */
+    setValue(elementId: string, text: string): Promise<void>;
+    getText(elementId: string): Promise<string | null>;
+    /** Dispatch a global key event by Android key code (goes to the focused view). */
+    pressKeyCode(keyCode: number): Promise<void>;
+    /** Capture the current screen as PNG bytes. */
+    screenshotPng(): Promise<Buffer>;
+    /**
+     * Return the current UI hierarchy as uiautomator2 `/source` XML. Present on
+     * live clients and consumed by the analyzer (PROWL-061); optional so lighter
+     * fakes that only drive/query need not implement it.
+     */
+    source?(): Promise<string>;
+    close(): Promise<void>;
+}
+type AndroidDriverOptions = {
+    /** Package name, used only for the informational `currentUrl()` value. */
+    appLabel?: string;
+};
+/**
+ * Android key names accepted by the `press` step, mapped to KeyEvent key codes.
+ * Names are matched case-insensitively.
+ */
+declare const ANDROID_KEYCODES: Readonly<Record<string, number>>;
+/** Escape a string for embedding inside a `new UiSelector()...("...")` argument. */
+declare function escapeUiSelectorArg(value: string): string;
+/**
+ * Parse a Prowl selector string into an {@link AndroidQuery}. Bare text matches by
+ * text. The grammar (and its `label=`-in-assertions trap) is defined once in the
+ * shared native selector engine ({@link parseNativeSelector}, PROWL-060); this
+ * only maps the neutral result onto Android's on-device query.
+ */
+declare function parseAndroidSelector(selector: string): AndroidQuery;
+/**
+ * Translate an {@link AndroidQuery} into the uiautomator2 server's native
+ * locator shape. `id`/`accessibility id` are native strategies;
+ * text/role(+name)/focused compose a `-android uiautomator` `UiSelector`.
+ * `appPackage` qualifies bare `id=` names ({@link qualifyResourceId}).
+ */
+declare function androidQueryToLocator(query: AndroidQuery, options?: {
+    appPackage?: string;
+}): AndroidLocator;
+/** The literal text a `text=` selector matches, else null (mirrors the web driver). */
+declare function unwrapAndroidTextSelector(selector: string): string | null;
+/** Wrap a live {@link AndroidAgentClient} as a {@link SessionDriver}. */
+declare function createAndroidDriver(client: AndroidAgentClient, options?: AndroidDriverOptions): SessionDriver;
+
+/** Result of one adb invocation. */
+type AdbResult = {
+    stdout: string;
+    stderr: string;
+    code: number;
+};
+/** Runs one adb command to completion and resolves with its captured output. */
+type AdbRunner = (args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<AdbResult>;
+/** A handle to a spawned long-running adb process (the instrumentation server). */
+type AdbProcessHandle = {
+    kill(): void;
+};
+/** Spawns a long-running adb command (e.g. `am instrument -w`) in the background. */
+type AdbSpawner = (args: string[]) => AdbProcessHandle;
+/** One row of `adb devices -l`. */
+type AdbDevice = {
+    serial: string;
+    state: string;
+    description: Record<string, string>;
+};
+/**
+ * Parse `adb devices -l` output into structured rows. The header line
+ * (`List of devices attached`) and blank lines are skipped.
+ */
+declare function parseAdbDevices(stdout: string): AdbDevice[];
+/** Devices that are fully booted and usable (`device` state). */
+declare function bootedDevices(devices: AdbDevice[]): AdbDevice[];
+/**
+ * Choose which device to drive. With `requested` set it must be attached and
+ * booted. Otherwise exactly one booted device is required; zero or many raise an
+ * actionable error listing what was found.
+ */
+declare function selectDeviceSerial(devices: AdbDevice[], requested?: string): string;
+/** List attached devices via `adb devices -l`. */
+declare function listDevices(runner: AdbRunner): Promise<AdbDevice[]>;
+/**
+ * Parse the local port `adb forward tcp:0 tcp:<remote>` prints (dynamic port
+ * allocation). adb echoes the chosen local port on stdout.
+ */
+declare function parseForwardPort(stdout: string): number;
+/** Parse the package name out of `aapt dump badging <apk>` output. */
+declare function parseAaptPackage(stdout: string): string | null;
+
+/** The remote port the uiautomator2 server listens on inside the device. */
+declare const UIA2_REMOTE_PORT = 6790;
+/** Locations of the two prebuilt agent APKs. */
+type AgentApks = {
+    serverApk: string;
+    testApk: string;
+};
+/** Establishes a live {@link AndroidAgentClient} against a forwarded local port. */
+type AgentConnector = (options: {
+    host: string;
+    port: number;
+    requestTimeoutMs: number;
+    readyDeadlineMs: number;
+    /** Target app's package name; qualifies bare `id=` selectors on the device. */
+    appPackage?: string;
+}) => Promise<AndroidAgentClient>;
+/** Resolve a package name from an `.apk` file, or null when it can't be determined. */
+type AaptResolver = (apkPath: string) => Promise<string | null>;
+/**
+ * Resolve the two agent APKs shipped inside `appium-uiautomator2-server`. They
+ * live under the package's `apks/` folder; the server APK is version-stamped.
+ */
+declare function resolveAgentApks(requireFn?: NodeRequire): AgentApks;
+/** Default connector: builds the HTTP transport, waits for readiness, opens a session. */
+declare const defaultAgentConnector: AgentConnector;
+type AndroidSession = {
+    client: AndroidAgentClient;
+    driver: SessionDriver;
+    /** The resolved package name being driven. */
+    package: string;
+    /** The adb serial of the device being driven. */
+    serial: string;
+    /** Tear down the session, agent, port forward, and app (best effort). */
+    teardown(): Promise<void>;
+};
+type LaunchAndroidOptions = {
+    /** Package name or `.apk` path. */
+    app: string;
+    /** adb serial when more than one device is attached. */
+    deviceSerial?: string;
+    /** `pm clear` the package before launch for a deterministic cold start. */
+    coldStart?: boolean;
+    timeoutMs?: number;
+    runner?: AdbRunner;
+    spawner?: AdbSpawner;
+    agentConnector?: AgentConnector;
+    apks?: AgentApks;
+    aaptResolver?: AaptResolver;
+    /** Optional app scope guardrail from config.guardrails.allowedApps. */
+    allowedApps?: string[];
+};
+/**
+ * Preflight, install, launch, and attach the uiautomator2 agent, returning a
+ * live {@link AndroidSession}. Actionable errors cover each failure mode: adb
+ * missing / no booted device (device selection), agent unreachable (readiness).
+ */
+declare function launchAndroidSession(options: LaunchAndroidOptions): Promise<AndroidSession>;
+/** Tear down an Android session (agent session, instrumentation, forward, app). */
+declare function closeAndroidSession(session: AndroidSession): Promise<void>;
+
+/**
+ * PROWL-058 / ARCH-009 — HTTP/JSON transport for the on-device uiautomator2 agent.
+ *
+ * `appium-uiautomator2-server` exposes W3C-WebDriver-shaped endpoints over plain
+ * HTTP. This module speaks them with the global `fetch` (no heavy WebDriver SDK,
+ * per the `ai.ts` ethos), mirroring the mac-helper client's ergonomics: a
+ * per-request deadline via `AbortController`, and cleanup on
+ * every path. It exposes the semantic {@link AndroidAgentClient} the driver
+ * consumes; tests fake either the `fetch` implementation or the client itself.
+ */
+
+/** The subset of `fetch` this module uses; overridable in tests. */
+type FetchLike$1 = (url: string, init: RequestInit) => Promise<Response>;
+/** Default per-request deadline for the agent transport. */
+declare const DEFAULT_AGENT_REQUEST_TIMEOUT_MS = 30000;
+type Uia2TransportOptions = {
+    /** Base URL including the `/wd/hub` prefix, e.g. `http://127.0.0.1:6790/wd/hub`. */
+    baseUrl: string;
+    requestTimeoutMs?: number;
+    fetchImpl?: FetchLike$1;
+};
+/** An HTTP-level failure from the agent, carrying the status and parsed body. */
+declare class Uia2HttpError extends Error {
+    readonly status: number;
+    readonly webdriverError?: string | undefined;
+    constructor(message: string, status: number, webdriverError?: string | undefined);
+}
+/** Low-level request/response transport with a per-request deadline. */
+declare class Uia2Transport {
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    constructor(options: Uia2TransportOptions);
+    /**
+     * Send one request and return the parsed `value` field. Rejects with a
+     * {@link Uia2HttpError} on a non-2xx response, or a timeout error when the
+     * per-request deadline elapses.
+     */
+    request(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+}
+/** Extract an element id from a W3C element-reference object, or null. */
+declare function extractElementId(value: unknown): string | null;
+/**
+ * Create a uiautomator2 session and return its id. Uses the W3C `capabilities`
+ * envelope; the server ignores the empty match set and starts a default session.
+ */
+declare function createUia2Session(transport: Uia2Transport): Promise<string>;
+/** Poll `GET /status` until the agent reports ready or the deadline elapses. */
+declare function waitForAgentReady(transport: Uia2Transport, options?: {
+    deadlineMs: number;
+    intervalMs?: number;
+}): Promise<void>;
+/**
+ * Build the semantic {@link AndroidAgentClient} over a live session. `close`
+ * deletes the session (best effort); the transport itself is stateless.
+ */
+declare function createUia2AgentClient(transport: Uia2Transport, sessionId: string, options?: {
+    appPackage?: string;
+}): AndroidAgentClient;
+
+/** A structured query the {@link IosAgentClient} resolves against the simulator. */
+type IosQuery = {
+    by: "accessibilityId";
+    value: string;
+} | {
+    by: "label";
+    value: string;
+} | {
+    by: "role";
+    role: string;
+    name?: string;
+} | {
+    by: "text";
+    value: string;
+} | {
+    by: "focused";
+};
+/** A WDA locator strategy ({@code using}) + its value, as the agent expects. */
+type IosLocator = {
+    using: string;
+    value: string;
+};
+/**
+ * The semantic transport `IosDriver` talks to: element lookups return opaque
+ * element ids, and interactions take those ids. The HTTP/WDA implementation lives
+ * in {@link ./ios-agent.js}; tests fake this interface.
+ */
+interface IosAgentClient {
+    /** Resolve the first element matching `query`, or null when none match. */
+    findElement(query: IosQuery): Promise<string | null>;
+    /** Resolve every element id matching `query` (empty when none match). */
+    findElements(query: IosQuery): Promise<string[]>;
+    click(elementId: string): Promise<void>;
+    /** Replace an element's text (W3C `element/value`). */
+    setValue(elementId: string, text: string): Promise<void>;
+    getText(elementId: string): Promise<string | null>;
+    /** Send raw key sequences to the focused element (WDA `/wda/keys`). */
+    sendKeys(keys: string[]): Promise<void>;
+    /** Return to the springboard home screen (WDA `/wda/homescreen`). */
+    homescreen(): Promise<void>;
+    /**
+     * Return the current UI hierarchy as WebDriverAgent `/source` XML. Present on
+     * live clients and consumed by the analyzer (PROWL-061); optional so lighter
+     * fakes that only drive/query need not implement it.
+     */
+    source?(): Promise<string>;
+    close(): Promise<void>;
+}
+type IosDriverOptions = {
+    /** Bundle id, used only for the informational `currentUrl()` value. */
+    appLabel?: string;
+    /** Capture a PNG screenshot to `path` (injected simctl capture). */
+    captureScreenshot: (path: string) => Promise<void>;
+};
+/**
+ * Key names the `press` step supports on iOS, sorted for error messages. `enter`/
+ * `return` send a newline, `delete`/`backspace` send a backspace (both via WDA's
+ * key endpoint), and `home` returns to the springboard.
+ */
+declare const IOS_PRESS_KEYS: readonly string[];
+/** Escape a string for embedding inside a double-quoted NSPredicate string literal. */
+declare function escapePredicateArg(value: string): string;
+/**
+ * Parse a Prowl selector string into an {@link IosQuery}. Bare text matches by
+ * text. The grammar (and its `label=`-in-assertions trap) is defined once in the
+ * shared native selector engine ({@link parseNativeSelector}, PROWL-060); this
+ * only maps the neutral result onto iOS's WDA query.
+ */
+declare function parseIosSelector(selector: string): IosQuery;
+/**
+ * Translate an {@link IosQuery} into a WDA locator strategy. `id` uses the native
+ * `accessibility id` strategy and bare roles use `class name`; everything else
+ * composes an NSPredicate string (WDA's `predicate string` strategy).
+ */
+declare function iosQueryToLocator(query: IosQuery): IosLocator;
+/** The literal text a `text=` selector matches, else null (mirrors the web driver). */
+declare function unwrapIosTextSelector(selector: string): string | null;
+/** Wrap a live {@link IosAgentClient} as a {@link SessionDriver}. */
+declare function createIosDriver(client: IosAgentClient, options: IosDriverOptions): SessionDriver;
+
+/** Result of one `xcrun` invocation. */
+type SimctlResult = {
+    stdout: string;
+    stderr: string;
+    code: number;
+};
+/** Runs one `xcrun <args>` command to completion and resolves with its output. */
+type SimctlRunner = (args: string[], options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<SimctlResult>;
+/** A handle to a spawned long-running `xcrun` process (the WDA xcodebuild test host). */
+type XcrunProcessHandle = {
+    kill(): void;
+};
+/**
+ * Spawns a long-running `xcrun` command in the background — used for the
+ * `xcodebuild test-without-building` run that hosts WebDriverAgent (which never
+ * exits on its own; it serves HTTP until killed). Mirrors the Android
+ * `AdbSpawner` so the launch flow stays unit-testable with a fake.
+ */
+type XcrunSpawner = (args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+}) => XcrunProcessHandle;
+/** One simulator device from `simctl list devices --json`. */
+type SimDevice = {
+    udid: string;
+    name: string;
+    state: string;
+    runtime: string;
+    isAvailable: boolean;
+};
+type SimulatorReservation = {
+    udid: string;
+    release(): Promise<void>;
+};
+type ReserveSimulatorOptions = {
+    /** Override the lock directory root; intended for tests. */
+    lockRoot?: string;
+};
+declare const DEFAULT_SIMULATOR_LOCK_ROOT: string;
+/**
+ * Reserve a simulator UDID across processes. The lock is held until `release` is
+ * called, preventing one session's teardown from terminating another session's
+ * WDA runner or target app on the same simulator.
+ */
+declare function reserveSimulatorUdid(udid: string, options?: ReserveSimulatorOptions): Promise<SimulatorReservation>;
+/**
+ * Allocate a free local TCP port by binding to :0 and releasing it. The returned
+ * port is advisory after release; callers that hand it to another process must
+ * handle a later bind/readiness failure.
+ */
+declare function findFreePort(): Promise<number>;
+/**
+ * Parse `simctl list devices --json` into a flat device list. The JSON maps
+ * runtime identifiers to arrays of devices; the runtime is folded into each row.
+ */
+declare function parseSimctlDevices(json: string): SimDevice[];
+/** Simulators that are currently booted. */
+declare function bootedSimulators(devices: SimDevice[]): SimDevice[];
+/**
+ * Choose which simulator to drive. With `requested` set it must exist and be
+ * booted. Otherwise exactly one booted simulator is required; zero or many raise
+ * an actionable error listing what was found.
+ */
+declare function selectSimulatorUdid(devices: SimDevice[], requested?: string): string;
+/** List all simulators via `simctl list devices --json`. */
+declare function listSimulators(runner: SimctlRunner): Promise<SimDevice[]>;
+/** Parse the `x.y[.z]` version out of `xcodebuild -version` output. */
+declare function parseXcodeVersion(stdout: string): string | null;
+
+/** Bundle id of the prebuilt WebDriverAgent runner (its xctest host app). */
+declare const WDA_RUNNER_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
+/** Env var WDA reads to pick its HTTP port (injected into the runner's xctestrun env). */
+declare const WDA_USE_PORT_ENV = "USE_PORT";
+/** Establishes a live {@link IosAgentClient} against a running WDA HTTP server. */
+type IosAgentConnector = (options: {
+    host: string;
+    port: number;
+    bundleId: string;
+    requestTimeoutMs: number;
+    readyDeadlineMs: number;
+}) => Promise<IosAgentClient>;
+/** Default connector: builds the HTTP transport, waits for readiness, opens a session. */
+declare const defaultIosAgentConnector: IosAgentConnector;
+/** Resolve the WDA Xcode project bundled inside `appium-webdriveragent`. */
+declare function resolveWdaProject(requireFn?: NodeRequire): {
+    projectPath: string;
+    version: string;
+};
+/** Cache directory for a built WDA runner, keyed on the WDA + Xcode versions. */
+declare function wdaCacheDir(wdaVersion: string, xcode: string, homeDir?: string): string;
+type ResolveWdaTestRunOptions = {
+    runner?: SimctlRunner;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    requireFn?: NodeRequire;
+    /** One-line progress notice sink (defaults to stderr). */
+    logger?: (message: string) => void;
+};
+/**
+ * Resolve a WebDriverAgent `.xctestrun` file (the input to the XCTest host
+ * launch). Order: (a) the `PROWL_WDA_RUNNER` env override; (b) a previously built
+ * xctestrun in the version-keyed cache; (c) a one-time
+ * `xcodebuild build-for-testing` that populates the cache. Simulators need no
+ * code signing. Throws actionable errors when Xcode is missing or the build fails.
+ */
+declare function resolveWdaTestRun(options?: ResolveWdaTestRunOptions): Promise<string>;
+/**
+ * Return a deep copy of a parsed `.xctestrun` plist with the WDA HTTP port
+ * (`USE_PORT`) injected into every test target's `EnvironmentVariables`. WDA
+ * reads `USE_PORT` from its process environment; under `xcodebuild test` that
+ * environment comes from the xctestrun, so the dynamic port must be written here.
+ *
+ * Handles both xctestrun layouts: format 1 (top-level dict keyed by test-target
+ * name) and format 2 (a `TestConfigurations[].TestTargets[]` tree). A test target
+ * is recognized by a `TestBundlePath`/`TestHostPath` string; any object that
+ * already carries an `EnvironmentVariables` dict is updated too. Throws when no
+ * target is found, so a future format change fails loudly rather than launching
+ * WDA on the wrong port.
+ */
+declare function injectUsePortIntoXctestrun(plist: unknown, port: number): unknown;
+/**
+ * Produce a launch-specific `.xctestrun` with `USE_PORT` set to `port`, returning
+ * its path. The base xctestrun (built/cached) is never mutated in place.
+ */
+type WdaTestRunPreparer = (options: {
+    xctestrunPath: string;
+    port: number;
+}) => Promise<string>;
+/**
+ * Default preparer: reads the base xctestrun with `plutil` (JSON), injects
+ * `USE_PORT`, and writes a fresh, uniquely-named xctestrun **next to the base
+ * one**. This placement is required, not incidental: an xctestrun's product
+ * paths are relative to `__TESTROOT__`, which xcodebuild resolves to the
+ * directory containing the xctestrun file — so a copy written to a temp dir
+ * makes `xcodebuild test-without-building` fail with "Missing test product".
+ * Writing the sibling into the build's Products dir keeps `__TESTROOT__` pointing
+ * at the real products. The intermediate JSON goes to a temp dir; only the
+ * `.xctestrun` lands beside the products and is removed on teardown. `plutil`
+ * ships with macOS, so no extra dependency is added.
+ */
+declare const defaultWdaTestRunPreparer: WdaTestRunPreparer;
+/** The `xcodebuild test-without-building` args that host WDA against `udid`. */
+declare function wdaTestRunArgs(xctestrunPath: string, udid: string): string[];
+type IosSession = {
+    client: IosAgentClient;
+    driver: SessionDriver;
+    /** The resolved bundle id being driven. */
+    bundleId: string;
+    /** The UDID of the simulator being driven. */
+    udid: string;
+    /** Tear down the session, WDA runner, and target app (best effort). */
+    teardown(): Promise<void>;
+};
+type LaunchIosOptions = {
+    /** Bundle id or `.app` path. */
+    app: string;
+    /** Simulator UDID when more than one is booted. */
+    udid?: string;
+    /** Uninstall+reinstall the app before launch (requires a `.app` path). */
+    coldStart?: boolean;
+    timeoutMs?: number;
+    runner?: SimctlRunner;
+    /** Spawner for the long-running `xcodebuild test-without-building` WDA host. */
+    spawner?: XcrunSpawner;
+    /** Builds the per-launch port-injected xctestrun. */
+    testRunPreparer?: WdaTestRunPreparer;
+    portAllocator?: () => Promise<number>;
+    agentConnector?: IosAgentConnector;
+    /** Skip WDA build/resolution by supplying the base `.xctestrun` path directly. */
+    wdaTestRun?: string;
+    /** Optional app scope guardrail from config.guardrails.allowedApps. */
+    allowedApps?: string[];
+    /** Override the simulator lock root; intended for tests. */
+    simulatorLockRoot?: string;
+    logger?: (message: string) => void;
+};
+/**
+ * Preflight, host WDA via `xcodebuild test-without-building`, launch the target
+ * app, and attach, returning a live {@link IosSession}. Actionable errors cover
+ * each failure mode: Xcode/simctl missing, no booted simulator (device
+ * selection), WDA build failures, agent unreachable (readiness).
+ */
+declare function launchIosSession(options: LaunchIosOptions): Promise<IosSession>;
+/** Tear down an iOS session (agent session, WDA runner, target app). */
+declare function closeIosSession(session: IosSession): Promise<void>;
+
+/**
+ * PROWL-059 / ARCH-010 — HTTP/JSON transport for the on-simulator WebDriverAgent.
+ *
+ * WebDriverAgent (WDA) exposes W3C-WebDriver-shaped endpoints over plain HTTP. On
+ * a simulator it is reachable directly at `http://127.0.0.1:<port>` (no tunnel),
+ * so this module speaks it with the global `fetch` (no heavy WebDriver SDK, per
+ * the `ai.ts` ethos), mirroring the Android agent's ergonomics: a per-request
+ * deadline via `AbortController`, unref'd timers, and W3C element-key extraction.
+ * It exposes the semantic {@link IosAgentClient} the driver consumes; tests fake
+ * either the `fetch` implementation or the client itself.
+ */
+
+/** The subset of `fetch` this module uses; overridable in tests. */
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+/** Default per-request deadline for the agent transport. */
+declare const DEFAULT_WDA_REQUEST_TIMEOUT_MS = 30000;
+type WdaTransportOptions = {
+    /** Base URL, e.g. `http://127.0.0.1:8100`. */
+    baseUrl: string;
+    requestTimeoutMs?: number;
+    fetchImpl?: FetchLike;
+};
+/** An HTTP-level failure from WDA, carrying the status and parsed body. */
+declare class WdaHttpError extends Error {
+    readonly status: number;
+    readonly webdriverError?: string | undefined;
+    constructor(message: string, status: number, webdriverError?: string | undefined);
+}
+/** Low-level request/response transport with a per-request deadline. */
+declare class WdaTransport {
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    constructor(options: WdaTransportOptions);
+    /**
+     * Send one request and return the full parsed JSON body. Rejects with a
+     * {@link WdaHttpError} on a non-2xx response, or a timeout error when the
+     * per-request deadline elapses.
+     */
+    requestFull(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+    /** Like {@link requestFull} but returns just the `value` field. */
+    request(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<unknown>;
+}
+/**
+ * Create a WDA session bound to `bundleId` and return its id. WDA activates the
+ * app under test named in `alwaysMatch.bundleId`. The session id may arrive at
+ * the envelope root or inside `value`, so both are checked.
+ */
+declare function createWdaSession(transport: WdaTransport, bundleId: string): Promise<string>;
+/** Poll `GET /status` until WDA reports ready or the deadline elapses. */
+declare function waitForWdaReady(transport: WdaTransport, options?: {
+    deadlineMs: number;
+    intervalMs?: number;
+}): Promise<void>;
+/**
+ * Build the semantic {@link IosAgentClient} over a live session. `close` deletes
+ * the session (best effort); the transport itself is stateless.
+ */
+declare function createWdaAgentClient(transport: WdaTransport, sessionId: string): IosAgentClient;
+
 /**
  * PROWL-048 / ARCH-002 — target ⇄ step compatibility.
  *
@@ -579,9 +1367,18 @@ declare function webOnlyReason(step: Step): string | null;
 /**
  * Throw if any step in `steps` (recursing into `if`/`repeat` bodies) is not
  * supported by `target`. `runHunt` references are validated when the referenced
- * hunt itself runs. No-op for the web target.
+ * hunt itself runs. No-op for the web target; every native target (macOS,
+ * Android, iOS) rejects the same web-only step vocabulary.
  */
 declare function assertStepsSupportedByTarget(steps: Step[], target: Target["type"]): void;
+/** Read the bundle id from an iOS `.app` (root `Info.plist`), or null. */
+declare function readIosBundleIdentifier(appPath: string): string | null;
+/**
+ * Accepted identities for an iOS target app. A bare bundle id matches itself; a
+ * `.app` path is authorized by its path, bundle name, or the `CFBundleIdentifier`
+ * read from the bundle's root `Info.plist`.
+ */
+declare function iosAppAllowedIdentities(app: string): string[];
 /**
  * Native scope guardrail: if `allowedApps` is non-empty it must include an
  * accepted identity for the target app: bundle id, app bundle name, or `.app`
@@ -589,6 +1386,39 @@ declare function assertStepsSupportedByTarget(steps: Step[], target: Target["typ
  * allowed — mirroring how allowedDomains auto-includes the web target's host.
  */
 declare function assertTargetAppAllowed(allowedApps: string[], app: string): void;
+/**
+ * iOS scope guardrail (PROWL-059): mirrors {@link assertTargetAppAllowed} but
+ * resolves identities via {@link iosAppAllowedIdentities} (bundle id or `.app`
+ * path with the id read from the bundle's root `Info.plist`).
+ */
+declare function assertIosAppAllowed(allowedApps: string[], app: string): void;
+/**
+ * Accepted identities for an Android target app. A bare package name matches
+ * itself. An `.apk` path is authorized only by its canonical full path; pass the
+ * resolved package name when validating an APK after `aapt` resolution so
+ * package-ID allowlists can authorize it before install.
+ */
+declare function androidAppAllowedIdentities(app: string, resolvedPackage?: string): string[];
+/**
+ * Android scope guardrail (PROWL-058): mirrors {@link assertTargetAppAllowed} but
+ * resolves identities via {@link androidAppAllowedIdentities} (package name or
+ * canonical APK path) rather than macOS bundle identities.
+ */
+declare function assertAndroidAppAllowed(allowedApps: string[], app: string, resolvedPackage?: string): void;
+
+type AiProvider = "anthropic" | "openai";
+type AiConfig = {
+    provider: AiProvider;
+    model: string;
+    apiKey: string;
+    /**
+     * API root the request is sent to (no trailing slash, no path). When omitted,
+     * falls back to the provider's public API. Set via `PROWL_AI_BASE_URL` so a
+     * self-hosted gateway or (later) a managed Prowl proxy can slot in without
+     * code changes.
+     */
+    baseUrl?: string;
+};
 
 type StepCallback = (result: StepResult, step: Step, index: number) => void;
 
@@ -606,6 +1436,10 @@ type RunOptions = {
     junit?: boolean;
     /** Inject a macOS helper client (tests / a prebuilt binary); defaults to spawning the helper. */
     macClientFactory?: () => MacHelperClient;
+    /** Inject an Android session factory (tests); defaults to {@link launchAndroidSession}. */
+    androidSessionFactory?: (options: LaunchAndroidOptions) => Promise<AndroidSession>;
+    /** Inject an iOS session factory (tests); defaults to {@link launchIosSession}. */
+    iosSessionFactory?: (options: LaunchIosOptions) => Promise<IosSession>;
 };
 declare function runHunt(options: RunOptions): Promise<{
     result: RunResult;
@@ -813,6 +1647,36 @@ declare const configSchema: z.ZodObject<{
     }, {
         app: string;
         type: "macos";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"android">;
+        app: z.ZodString;
+        deviceSerial: z.ZodOptional<z.ZodString>;
+        coldStart: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    }, {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ios">;
+        app: z.ZodString;
+        udid: z.ZodOptional<z.ZodString>;
+        coldStart: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
+    }, {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
     }>, z.ZodObject<{
         type: z.ZodOptional<z.ZodLiteral<"web">>;
         url: z.ZodString;
@@ -959,6 +1823,16 @@ declare const configSchema: z.ZodObject<{
     } | {
         app: string;
         type: "macos";
+    } | {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    } | {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
     };
     browser?: {
         timeout?: number | undefined;
@@ -1014,6 +1888,16 @@ declare const configSchema: z.ZodObject<{
     } | {
         app: string;
         type: "macos";
+    } | {
+        app: string;
+        type: "android";
+        deviceSerial?: string | undefined;
+        coldStart?: boolean | undefined;
+    } | {
+        app: string;
+        type: "ios";
+        udid?: string | undefined;
+        coldStart?: boolean | undefined;
     };
     browser?: {
         timeout?: number | undefined;
@@ -1212,12 +2096,353 @@ type AnalysisResult = {
 };
 declare function analyzePage(page: DomEvaluator): Promise<AnalysisResult>;
 
-type AiProvider = "anthropic" | "openai";
-type AiConfig = {
-    provider: AiProvider;
-    model: string;
-    apiKey: string;
+/**
+ * PROWL-055 / ARCH-007 — macOS analyzer.
+ *
+ * The native analog of {@link analyzePage}: dumps a macOS app's interactive
+ * elements with ranked selector candidates so hunt authors don't have to guess
+ * accessibility identifiers. It talks to the same `prowl-macdriver` helper the
+ * runner uses ({@link MacHelperClient}) — reading the AX tree, the window list,
+ * and (read-only) the status-item menu — and shapes the result to mirror the web
+ * analyzer's feel.
+ *
+ * Selector ranking (best → last resort), matching the driver's selector dialect
+ * so the emitted selectors are directly usable in hunts:
+ *   id=<AXIdentifier>              (best — the native `data-testid`)
+ *   label="<exact title/desc>"     (exact accessibility label)
+ *   role=<role>[name="<name>"]     (role + accessible name)
+ *   text="<substring>"             (last resort — substring match)
+ *
+ * Read-only: the ONLY state-changing interaction is opening the status-item menu
+ * to read its items (their identifiers are gold) and immediately closing it.
+ */
+
+/**
+ * The interactive AX roles the analyzer surfaces from the window tree. Menu
+ * items are collected separately via the status-item menu; windows are listed
+ * as navigable surfaces. Tuned from the roles the helper's `tree`/`openMenu`
+ * payloads actually expose for controls.
+ */
+declare const INTERACTIVE_ROLES: ReadonlySet<string>;
+/** Default AX-tree depth requested from the helper (deeper than the run default). */
+declare const DEFAULT_ANALYZE_TREE_DEPTH = 20;
+/** A single element the `axInfo` snapshot describes (tree / menu / window node). */
+type MacAxNode = {
+    role?: string;
+    title?: string;
+    description?: string;
+    value?: string;
+    identifier?: string;
+    enabled?: boolean;
+    children?: MacAxNode[];
 };
+/** An interactive element with ranked selector candidates (best first). */
+type MacAnalysisElement = {
+    role: string;
+    title?: string;
+    description?: string;
+    value?: string;
+    identifier?: string;
+    enabled?: boolean;
+    /** Where the element was discovered: the app's window tree or the status menu. */
+    source: "window" | "menu";
+    /** Ranked selector candidates, best first. Always at least one entry. */
+    selectors: string[];
+};
+/** A top-level window, exposed as a navigable surface with its best selector. */
+type MacAnalysisWindow = {
+    title?: string;
+    identifier?: string;
+    /** Best selector candidate for the window. */
+    selector: string;
+};
+type MacAnalysisResult = {
+    /** Bundle id (or the app reference) of the analyzed app. */
+    app: string;
+    elements: MacAnalysisElement[];
+    windows: MacAnalysisWindow[];
+    menuItems: MacAnalysisElement[];
+};
+/**
+ * Ranked selector candidates for an element, best first. Mirrors the driver's
+ * selector dialect (`id=` > `label=` > `role=…[name="…"]` > `text=`). Falls back
+ * to a bare `role=<role>` so every element with a role is at least addressable.
+ */
+declare function rankMacSelectors(node: MacAxNode): string[];
+type AnalyzeMacOptions = {
+    /** Bundle id / app label to report in the result. */
+    app: string;
+    /** AX-tree depth to request from the helper. */
+    treeDepth?: number;
+    /** Timeout (seconds) for opening the status-item menu. */
+    menuTimeoutSeconds?: number;
+};
+/**
+ * Analyze an already-launched macOS app through `client`, returning its
+ * interactive elements, windows, and status-menu items with ranked selectors.
+ *
+ * The caller owns the session lifecycle (launch + guardrails + teardown); this
+ * function is read-only apart from opening and immediately closing the
+ * status-item menu to read its contents.
+ */
+declare function analyzeMacApp(client: MacHelperClient, options: AnalyzeMacOptions): Promise<MacAnalysisResult>;
+
+/**
+ * PROWL-061 — a tiny, dependency-free XML parser for on-device UI hierarchies.
+ *
+ * Both native mobile analyzers read an XML page source: Android via the
+ * uiautomator2 agent's `GET /source` (a `<hierarchy>` of `<node>` elements) and
+ * iOS via WebDriverAgent's `GET /source` (a tree of `<XCUIElementType…>`
+ * elements). Both dialects share the same shape — a tree of elements whose data
+ * lives entirely in double-quoted attributes, with no meaningful text between
+ * tags — so one small scanner serves both, keeping with the repo's "no heavy
+ * SDK" ethos (there is no XML parser in our own dependency set, only transitive
+ * ones we must not rely on).
+ *
+ * The scanner is deliberately narrow: it understands element start/end/self-close
+ * tags, quoted attributes (single or double), XML declarations, comments, and the
+ * five predefined entities plus numeric character references. It ignores text
+ * nodes and CDATA (the UI dumps carry none). It never throws on malformed input —
+ * it returns the best-effort root element, or null when there is no element at
+ * all — so a surprising payload degrades to an empty analysis rather than a crash.
+ */
+/** A parsed XML element: its tag name, attributes, and child elements. */
+type XmlElement = {
+    tag: string;
+    attrs: Record<string, string>;
+    children: XmlElement[];
+};
+/** Decode the five predefined XML entities and numeric character references. */
+declare function decodeXmlEntities(value: string): string;
+/**
+ * Parse an XML document into its root {@link XmlElement} (best-effort). Returns
+ * null when the input contains no element. Malformed markup is tolerated: unknown
+ * constructs are skipped and mismatched end tags simply pop the stack.
+ */
+declare function parseXml(input: string): XmlElement | null;
+
+/**
+ * PROWL-061 — Android analyzer.
+ *
+ * The Android analog of {@link analyzeMacApp}: dumps a running Android app's
+ * interactive elements with ranked selector candidates so hunt authors don't have
+ * to guess resource-ids. It reads the on-device UI hierarchy through the same
+ * uiautomator2 agent the runner uses (`GET /source`, the standard `uiautomator
+ * dump` XML) and shapes the result to mirror the macOS analyzer's feel.
+ *
+ * Selector ranking (best → last resort), matching the Android driver's selector
+ * dialect so the emitted selectors are directly usable in hunts:
+ *   id=<resource-id>             (best — the native `data-testid`; already
+ *                                 package-qualified in the dump, e.g.
+ *                                 `com.android.settings:id/title`)
+ *   label="<content-desc>"       (exact content-description)
+ *   role=<class>[name="<text>"]  (widget class + visible text, substring)
+ *   text="<text>"                (last resort — visible-text substring)
+ *
+ * Read-only: this never taps, types, or otherwise mutates the app — it only reads
+ * the page source.
+ */
+
+/**
+ * Widget classes treated as interactive on their own (in addition to any node
+ * flagged clickable / long-clickable / checkable / scrollable). Tuned to the
+ * common `android.widget` / AndroidX input and control classes; text/containers
+ * without an interactive flag are surfaced only when clickable.
+ */
+declare const ANDROID_INTERACTIVE_CLASSES: ReadonlySet<string>;
+/** A single node in the uiautomator hierarchy (`<node>` element attributes). */
+type AndroidUiNode = {
+    className?: string;
+    resourceId?: string;
+    contentDesc?: string;
+    text?: string;
+    package?: string;
+    clickable?: boolean;
+    longClickable?: boolean;
+    checkable?: boolean;
+    checked?: boolean;
+    scrollable?: boolean;
+    focusable?: boolean;
+    /** Whether the node currently holds input focus (`:focus`; from the dump's `focused` attr). */
+    focused?: boolean;
+    enabled?: boolean;
+    children: AndroidUiNode[];
+};
+/** An interactive element with ranked selector candidates (best first). */
+type AndroidAnalysisElement = {
+    className: string;
+    resourceId?: string;
+    contentDesc?: string;
+    text?: string;
+    clickable?: boolean;
+    checkable?: boolean;
+    scrollable?: boolean;
+    enabled?: boolean;
+    /** Ranked selector candidates, best first. Always at least one entry. */
+    selectors: string[];
+};
+type AndroidAnalysisResult = {
+    /** Package name of the analyzed app. */
+    app: string;
+    elements: AndroidAnalysisElement[];
+};
+/** Parse a uiautomator2 `/source` XML dump into a tree of {@link AndroidUiNode}. */
+declare function parseAndroidHierarchy(xml: string): AndroidUiNode | null;
+/** Whether a node is worth surfacing as an interactive element. */
+declare function isAndroidInteractive(node: AndroidUiNode): boolean;
+/**
+ * Ranked selector candidates for a node, best first, via the shared native
+ * selector engine (PROWL-060). The Android attribute mapping is applied here —
+ * `id=`←resource-id (already package-qualified in the dump, emitted verbatim),
+ * `label=`←content-desc, `role=`←class, name←visible text — then
+ * {@link rankNativeSelectors} imposes the shared `id=` > `label=` >
+ * `role=…[name]` > `text=` order (with a bare `role=` fallback).
+ */
+declare function rankAndroidSelectors(node: AndroidUiNode): string[];
+/**
+ * Project an {@link AndroidUiNode} into the neutral {@link NativeNode} the shared
+ * matcher compares against: `id`←resource-id, `label`←content-desc, `role`←class,
+ * `text=` substring source ← visible text.
+ */
+declare function androidNodeToNative(node: AndroidUiNode): NativeNode;
+/**
+ * Host-side "snapshot-then-match": parse a uiautomator2 `/source` dump and return
+ * every node the Prowl `selector` resolves to, in document order, using Android's
+ * shared dialect semantics. Read-only and device-free. Exposed for tooling and a
+ * future runner/macdriver migration; the runner still matches on-device today.
+ */
+declare function matchAndroidSelector(xml: string, selector: string, options?: NativeMatchOptions): AndroidUiNode[];
+/** The minimal transport the Android analyzer needs: read the UI hierarchy XML. */
+interface AndroidUiSource {
+    /** Return the current UI hierarchy as uiautomator2 `/source` XML. */
+    source(): Promise<string>;
+}
+type AnalyzeAndroidOptions = {
+    /** Package name to report in the result. */
+    app: string;
+};
+/**
+ * Analyze an already-launched Android app through `client`, returning its
+ * interactive elements with ranked selectors.
+ *
+ * The caller owns the session lifecycle (launch + guardrails + teardown); this
+ * function is strictly read-only — it only reads the page source.
+ */
+declare function analyzeAndroidApp(client: AndroidUiSource, options: AnalyzeAndroidOptions): Promise<AndroidAnalysisResult>;
+
+/**
+ * PROWL-061 — iOS analyzer.
+ *
+ * The iOS analog of {@link analyzeMacApp}: dumps a running iOS app's interactive
+ * elements (and its windows) with ranked selector candidates so hunt authors
+ * don't have to guess accessibility identifiers. It reads the on-simulator UI
+ * hierarchy through the same WebDriverAgent the runner uses (`GET /source`, WDA's
+ * XML page source of `<XCUIElementType…>` elements) and shapes the result to
+ * mirror the macOS analyzer's feel.
+ *
+ * Selector ranking (best → last resort), matching the iOS driver's selector
+ * dialect so the emitted selectors are directly usable in hunts:
+ *   id=<accessibility id>        (best — the native `data-testid`)
+ *   label="<label>"              (exact accessibility label)
+ *   role=<Type>[name="<text>"]   (element type + visible text, substring)
+ *   text="<text>"                (last resort — label/value substring)
+ *
+ * Identifier caveat: WDA's page source exposes a single `name` attribute that is
+ * the element's `accessibilityIdentifier` when one is set, otherwise its label.
+ * We therefore rank `id=` only when `name` differs from `label`, so the analyzer
+ * does not recommend label-shaped ids. Host-side matching still follows WDA's
+ * `accessibility id` strategy and resolves `id=` against `name`.
+ *
+ * Read-only: this never taps, types, or otherwise mutates the app — it only reads
+ * the page source.
+ */
+
+/**
+ * Element types treated as interactive. Tuned to the common `XCUIElementType…`
+ * controls; static text and layout containers are intentionally excluded.
+ */
+declare const IOS_INTERACTIVE_TYPES: ReadonlySet<string>;
+/** The element type that represents a navigable window/screen surface. */
+declare const IOS_WINDOW_TYPE = "XCUIElementTypeWindow";
+/** A single node in the WDA hierarchy (`<XCUIElementType…>` element attributes). */
+type IosUiNode = {
+    type?: string;
+    name?: string;
+    label?: string;
+    value?: string;
+    enabled?: boolean;
+    visible?: boolean;
+    children: IosUiNode[];
+};
+/** An interactive element with ranked selector candidates (best first). */
+type IosAnalysisElement = {
+    type: string;
+    name?: string;
+    label?: string;
+    value?: string;
+    enabled?: boolean;
+    visible?: boolean;
+    /** Ranked selector candidates, best first. Always at least one entry. */
+    selectors: string[];
+};
+/** A top-level window, exposed as a navigable surface with its best selector. */
+type IosAnalysisWindow = {
+    name?: string;
+    label?: string;
+    /** Best selector candidate for the window. */
+    selector: string;
+};
+type IosAnalysisResult = {
+    /** Bundle id of the analyzed app. */
+    app: string;
+    elements: IosAnalysisElement[];
+    windows: IosAnalysisWindow[];
+};
+/** Parse a WDA `/source` XML dump into a tree of {@link IosUiNode}. */
+declare function parseIosHierarchy(xml: string): IosUiNode | null;
+/**
+ * Ranked selector candidates for a node, best first, via the shared native
+ * selector engine (PROWL-060). The iOS attribute mapping is applied here — `id=`←
+ * accessibility id (the `name` attribute, but only when it differs from the label;
+ * see the caveat above), `label=`←label, `role=`←the short element type, name←
+ * `label ?? value` — then {@link rankNativeSelectors} imposes the shared `id=` >
+ * `label=` > `role=…[name]` > `text=` order (with a bare `role=` fallback).
+ */
+declare function rankIosSelectors(node: IosUiNode): string[];
+/**
+ * Project an {@link IosUiNode} into the neutral {@link NativeNode} the shared
+ * matcher compares against: `id`←name (matching WDA's `accessibility id`
+ * strategy even when it equals the label), `label`←label, `role`←the full
+ * element type (the dialect normalizes a `Button` shorthand against it), and both
+ * label and value as `text=` substring sources.
+ */
+declare function iosNodeToNative(node: IosUiNode): NativeNode;
+/**
+ * Host-side "snapshot-then-match": parse a WebDriverAgent `/source` dump and
+ * return every node the Prowl `selector` resolves to, in document order, using
+ * iOS's shared dialect semantics. Read-only and device-free. Exposed for tooling
+ * and a future runner/macdriver migration; the runner still matches on-device.
+ */
+declare function matchIosSelector(xml: string, selector: string): IosUiNode[];
+/** Whether a node is worth surfacing as an interactive element. */
+declare function isIosInteractive(node: IosUiNode): boolean;
+/** The minimal transport the iOS analyzer needs: read the UI hierarchy XML. */
+interface IosUiSource {
+    /** Return the current UI hierarchy as WebDriverAgent `/source` XML. */
+    source(): Promise<string>;
+}
+type AnalyzeIosOptions = {
+    /** Bundle id to report in the result. */
+    app: string;
+};
+/**
+ * Analyze an already-launched iOS app through `client`, returning its interactive
+ * elements and windows with ranked selectors.
+ *
+ * The caller owns the session lifecycle (launch + guardrails + teardown); this
+ * function is strictly read-only — it only reads the page source.
+ */
+declare function analyzeIosApp(client: IosUiSource, options: AnalyzeIosOptions): Promise<IosAnalysisResult>;
 
 type GenerateOptions = {
     url?: string;
@@ -1229,4 +2454,4 @@ type GenerateOptions = {
 };
 declare function generateHunt(options: GenerateOptions): Promise<string>;
 
-export { type AnalysisResult, type AssertScreenshotStep, type Assertion, type AssertionResult, type BrowserChannel, type BrowserEngine, type BugFailure, type BugLogSummary, type CiFailureCluster, type CiFlakyHunt, type CiHuntResult, type CiResult, type CiStatus, type Config, DEFAULT_FLAKY_THRESHOLD, DEFAULT_REQUEST_TIMEOUT_MS, type EvalScriptStep, type FailureCluster, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, type IfStep, type LaunchMacOptions, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacosTarget, type MockRouteStep, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, SpawnMacHelperClient, type SpawnMacHelperOptions, type Step, type StepResult, type Target, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, WEB_ONLY_STEP_TYPES, type WebTarget, analyzePage, assertStepsSupportedByTarget, assertTargetAppAllowed, buildHealCandidates, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createMacDriver, extractFailures, extractSelectorIntent, generateHunt, healSelector, huntSchema, interpolateHunt, launchMacSession, listHunts, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, parseMacSelector, rankFlaky, readHistory, readHuntHistory, resolveHelperBinary, runHunt, runSuite, stepSchema, updateBacklogFromSuite, webOnlyReason };
+export { ANDROID_INTERACTIVE_CLASSES, ANDROID_KEYCODES, ANDROID_MATCH_DIALECT, type AdbDevice, type AdbResult, type AdbRunner, type AdbSpawner, type AgentApks, type AgentConnector, type AnalysisResult, type AnalyzeAndroidOptions, type AnalyzeIosOptions, type AnalyzeMacOptions, type AndroidAgentClient, type AndroidAnalysisElement, type AndroidAnalysisResult, type AndroidDriverOptions, type AndroidLocator, type AndroidQuery, type AndroidSession, type AndroidTarget, type AndroidUiNode, type AndroidUiSource, type AssertScreenshotStep, type Assertion, type AssertionResult, type BrowserChannel, type BrowserEngine, type BugFailure, type BugLogSummary, type CiFailureCluster, type CiFlakyHunt, type CiHuntResult, type CiResult, type CiStatus, type Config, DEFAULT_AGENT_REQUEST_TIMEOUT_MS, DEFAULT_ANALYZE_TREE_DEPTH, DEFAULT_FLAKY_THRESHOLD, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SIMULATOR_LOCK_ROOT, DEFAULT_WDA_REQUEST_TIMEOUT_MS, type EvalScriptStep, type FailureCluster, type FetchLike$1 as FetchLike, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, INTERACTIVE_ROLES, IOS_INTERACTIVE_TYPES, IOS_MATCH_DIALECT, IOS_PRESS_KEYS, IOS_WINDOW_TYPE, type IfStep, type IosAgentClient, type IosAgentConnector, type IosAnalysisElement, type IosAnalysisResult, type IosAnalysisWindow, type IosDriverOptions, type IosLocator, type IosQuery, type IosSession, type IosTarget, type IosUiNode, type IosUiSource, type LaunchAndroidOptions, type LaunchIosOptions, type LaunchMacOptions, MACOS_MATCH_DIALECT, type MacAnalysisElement, type MacAnalysisResult, type MacAnalysisWindow, type MacAxNode, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacosTarget, type MockRouteStep, NATIVE_ATTRIBUTE_MAP, type NativeMatchDialect, type NativeMatchOptions, type NativeNode, type NativePlatform, type NativeRankFields, type NativeSelector, type NativeSelectorKind, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type ReserveSimulatorOptions, type ResolveWdaTestRunOptions, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, type SelectorKindMapping, type SimDevice, type SimctlResult, type SimctlRunner, type SimulatorReservation, SpawnMacHelperClient, type SpawnMacHelperOptions, type Step, type StepResult, type Target, UIA2_REMOTE_PORT, Uia2HttpError, Uia2Transport, type Uia2TransportOptions, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, WDA_RUNNER_BUNDLE_ID, WDA_USE_PORT_ENV, WEB_ONLY_STEP_TYPES, WdaHttpError, type WdaTestRunPreparer, WdaTransport, type WdaTransportOptions, type WebTarget, type XmlElement, analyzeAndroidApp, analyzeIosApp, analyzeMacApp, analyzePage, androidAppAllowedIdentities, androidNodeToNative, androidQueryToLocator, assertAndroidAppAllowed, assertIosAppAllowed, assertStepsSupportedByTarget, assertTargetAppAllowed, bootedDevices, bootedSimulators, buildHealCandidates, closeAndroidSession, closeIosSession, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createAndroidDriver, createIosDriver, createMacDriver, createUia2AgentClient, createUia2Session, createWdaAgentClient, createWdaSession, decodeXmlEntities, defaultAgentConnector, defaultIosAgentConnector, defaultWdaTestRunPreparer, escapePredicateArg, escapeUiSelectorArg, extractElementId, extractFailures, extractSelectorIntent, findFreePort, generateHunt, healSelector, huntSchema, injectUsePortIntoXctestrun, interpolateHunt, iosAppAllowedIdentities, iosNodeToNative, iosQueryToLocator, isAndroidInteractive, isIosInteractive, launchAndroidSession, launchIosSession, launchMacSession, listDevices, listHunts, listSimulators, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, matchAndroidSelector, matchIosSelector, matchNativeTree, nodeMatchesSelector, normalizeXcuiClassName, parseAaptPackage, parseAdbDevices, parseAndroidHierarchy, parseAndroidSelector, parseForwardPort, parseIosHierarchy, parseIosSelector, parseMacSelector, parseNativeSelector, parseSimctlDevices, parseSnapshot, parseXcodeVersion, parseXml, qualifyResourceId, quoteSelectorValue, rankAndroidSelectors, rankFlaky, rankIosSelectors, rankMacSelectors, rankNativeSelectors, readHistory, readHuntHistory, readIosBundleIdentifier, reserveSimulatorUdid, resolveAgentApks, resolveHelperBinary, resolveWdaProject, resolveWdaTestRun, runHunt, runSuite, selectDeviceSerial, selectSimulatorUdid, shortIosType, stepSchema, unquoteSelectorValue, unwrapAndroidTextSelector, unwrapIosTextSelector, unwrapNativeTextSelector, updateBacklogFromSuite, waitForAgentReady, waitForWdaReady, wdaCacheDir, wdaTestRunArgs, webOnlyReason };