prowl-tools 0.1.5 → 0.1.6

package/dist/lib.d.ts

@@ -296,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;
 } | {
@@ -312,7 +315,7 @@ type Assertion = {
 };
 type StepResult = {
     type: string;
-    status: "pass" | "fail";
+    status: "pass" | "fail" | "warn";
     durationMs: number;
     selector?: string;
     value?: string;
@@ -591,6 +594,178 @@ 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";
@@ -638,6 +813,12 @@ interface AndroidAgentClient {
     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 = {
@@ -651,7 +832,12 @@ type AndroidDriverOptions = {
 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. */
+/**
+ * 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
@@ -832,33 +1018,6 @@ declare function createUia2AgentClient(transport: Uia2Transport, sessionId: stri
     appPackage?: string;
 }): AndroidAgentClient;
 
-/**
- * PROWL-059 / ARCH-010 — iOS simulator implementation of {@link SessionDriver}.
- *
- * `IosDriver` drives a native iOS app through a prebuilt WebDriverAgent (WDA)
- * runner over its W3C-shaped HTTP/JSON API ({@link IosAgentClient}). Like the
- * macOS and Android drivers it implements only the portable subset of the driver
- * surface — its `capabilities` set is honest: `query`, `interact`, `wait`,
- * `screenshot`. Web-only verbs (navigation, network, dialogs, files, downloads,
- * script evaluation) are unsupported stubs; the runner never reaches them because
- * both the target step-compatibility check and the runtime capability gate reject
- * web-only steps for native targets.
- *
- * Screenshots are captured via `simctl` (injected as `captureScreenshot`), not
- * WDA, so artifacts still work even if the agent wedges.
- *
- * Selector dialect (parsed here into an {@link IosQuery}; the agent then matches
- * on the simulator). Semantics mirror the macOS/Android drivers so `id=`/`label=`/
- * `text=`/`role=` mean the same thing across native targets (PROWL-060 will unify
- * the engines later):
- *   id=save                    → accessibility id (accessibilityIdentifier / name)
- *   label="Submit"             → predicate `label == "Submit"` (exact)
- *   role=XCUIElementTypeButton → element class (shorthand `Button` is accepted too)
- *   role=Button[name="Save"]   → class + visible text (label/value substring)
- *   text="Save" | Save         → label/value substring
- *   :focus                     → predicate `hasKeyboardFocus == 1`
- */
-
 /** A structured query the {@link IosAgentClient} resolves against the simulator. */
 type IosQuery = {
     by: "accessibilityId";
@@ -899,6 +1058,12 @@ interface IosAgentClient {
     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 = {
@@ -915,9 +1080,12 @@ type IosDriverOptions = {
 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;
-/** Prefix `XCUIElementType` onto a role shorthand (e.g. `Button`) when missing. */
-declare function normalizeXcuiClassName(role: string): string;
-/** Parse a Prowl selector string into an {@link IosQuery}. Bare text matches by text. */
+/**
+ * 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
@@ -941,6 +1109,19 @@ 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;
@@ -990,8 +1171,8 @@ 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";
-/** The runner `.app` produced by `xcodebuild build-for-testing`. */
-declare const WDA_RUNNER_APP_NAME = "WebDriverAgentRunner-Runner.app";
+/** 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;
@@ -1009,7 +1190,7 @@ declare function resolveWdaProject(requireFn?: NodeRequire): {
 };
 /** Cache directory for a built WDA runner, keyed on the WDA + Xcode versions. */
 declare function wdaCacheDir(wdaVersion: string, xcode: string, homeDir?: string): string;
-type ResolveWdaRunnerOptions = {
+type ResolveWdaTestRunOptions = {
     runner?: SimctlRunner;
     env?: NodeJS.ProcessEnv;
     homeDir?: string;
@@ -1018,13 +1199,50 @@ type ResolveWdaRunnerOptions = {
     logger?: (message: string) => void;
 };
 /**
- * Resolve a WebDriverAgent runner `.app`. Order: (a) the `PROWL_WDA_RUNNER` env
- * override; (b) a previously built runner 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.
+ * 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 function resolveWdaRunner(options?: ResolveWdaRunnerOptions): Promise<string>;
+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;
@@ -1044,10 +1262,14 @@ type LaunchIosOptions = {
     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 runner app path directly. */
-    wdaRunnerApp?: string;
+    /** 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. */
@@ -1055,9 +1277,10 @@ type LaunchIosOptions = {
     logger?: (message: string) => void;
 };
 /**
- * Preflight, install, launch, and attach WDA, 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).
+ * 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). */
@@ -1183,6 +1406,20 @@ declare function androidAppAllowedIdentities(app: string, resolvedPackage?: stri
  */
 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;
 
 type RunOptions = {
@@ -1950,12 +2187,262 @@ type AnalyzeMacOptions = {
  */
 declare function analyzeMacApp(client: MacHelperClient, options: AnalyzeMacOptions): Promise<MacAnalysisResult>;
 
-type AiProvider = "anthropic" | "openai";
-type AiConfig = {
-    provider: AiProvider;
-    model: string;
-    apiKey: string;
+/**
+ * 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;
@@ -1967,4 +2454,4 @@ type GenerateOptions = {
 };
 declare function generateHunt(options: GenerateOptions): Promise<string>;
 
-export { ANDROID_KEYCODES, type AdbDevice, type AdbResult, type AdbRunner, type AdbSpawner, type AgentApks, type AgentConnector, type AnalysisResult, type AnalyzeMacOptions, type AndroidAgentClient, type AndroidDriverOptions, type AndroidLocator, type AndroidQuery, type AndroidSession, type AndroidTarget, 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_PRESS_KEYS, type IfStep, type IosAgentClient, type IosAgentConnector, type IosDriverOptions, type IosLocator, type IosQuery, type IosSession, type IosTarget, type LaunchAndroidOptions, type LaunchIosOptions, type LaunchMacOptions, type MacAnalysisElement, type MacAnalysisResult, type MacAnalysisWindow, type MacAxNode, 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 ReserveSimulatorOptions, type ResolveWdaRunnerOptions, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, 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_APP_NAME, WDA_RUNNER_BUNDLE_ID, WEB_ONLY_STEP_TYPES, WdaHttpError, WdaTransport, type WdaTransportOptions, type WebTarget, analyzeMacApp, analyzePage, androidAppAllowedIdentities, androidQueryToLocator, assertAndroidAppAllowed, assertIosAppAllowed, assertStepsSupportedByTarget, assertTargetAppAllowed, bootedDevices, bootedSimulators, buildHealCandidates, closeAndroidSession, closeIosSession, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createAndroidDriver, createIosDriver, createMacDriver, createUia2AgentClient, createUia2Session, createWdaAgentClient, createWdaSession, defaultAgentConnector, defaultIosAgentConnector, escapePredicateArg, escapeUiSelectorArg, extractElementId, extractFailures, extractSelectorIntent, findFreePort, generateHunt, healSelector, huntSchema, interpolateHunt, iosAppAllowedIdentities, iosQueryToLocator, launchAndroidSession, launchIosSession, launchMacSession, listDevices, listHunts, listSimulators, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, normalizeXcuiClassName, parseAaptPackage, parseAdbDevices, parseAndroidSelector, parseForwardPort, parseIosSelector, parseMacSelector, parseSimctlDevices, parseXcodeVersion, rankFlaky, rankMacSelectors, readHistory, readHuntHistory, readIosBundleIdentifier, reserveSimulatorUdid, resolveAgentApks, resolveHelperBinary, resolveWdaProject, resolveWdaRunner, runHunt, runSuite, selectDeviceSerial, selectSimulatorUdid, stepSchema, unwrapAndroidTextSelector, unwrapIosTextSelector, updateBacklogFromSuite, waitForAgentReady, waitForWdaReady, wdaCacheDir, 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 };