prowl-tools 0.1.3 → 0.1.5

package/dist/lib.d.ts

@@ -1,16 +1,63 @@
-import { Page } from 'playwright';
 import { z } from 'zod';
 
-type BrowserEngine = "chromium" | "firefox" | "webkit";
+declare const SUPPORTED_BROWSER_ENGINES: readonly ["chromium", "firefox", "webkit"];
+type BrowserEngine = (typeof SUPPORTED_BROWSER_ENGINES)[number];
 type BrowserChannel = "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev";
 type Viewport = {
     width: number;
     height: number;
 };
+/** Web execution target (default): drives a browser at `url`. */
+type WebTarget = {
+    type: "web";
+    url: string;
+};
+/**
+ * macOS native execution target (experimental, PROWL-048). `app` is a bundle
+ * identifier (e.g. `com.example.App`) or an absolute path to a `.app` bundle.
+ * App-path guardrails are matched against the path, bundle name, and
+ * `CFBundleIdentifier` from `Contents/Info.plist` when it is readable.
+ */
+type MacosTarget = {
+    type: "macos";
+    app: string;
+};
+/**
+ * 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: {
-        url: string;
-    };
+    target: Target;
     browser: {
         headless: boolean;
         slowMo: number;
@@ -34,6 +81,8 @@ type Config = {
     guardrails: {
         maxSteps: number;
         allowedDomains: string[];
+        /** Native scope analog of `allowedDomains`: allowed bundle/package IDs or canonical app artifact paths. */
+        allowedApps: string[];
         forbiddenSelectors: string[];
         selfHealing: boolean;
     };
@@ -339,6 +388,801 @@ type CiResult = {
     clusters?: CiFailureCluster[];
 };
 
+/**
+ * PROWL-047 / ARCH-001 — Session driver abstraction.
+ *
+ * `SessionDriver` is the narrow, engine-agnostic surface the step runner drives.
+ * Today the only implementation is the Playwright driver (`playwright-driver.ts`),
+ * but factoring the runner against this interface is the prerequisite for
+ * non-browser execution targets (macOS native, Electron, mobile — see PROWL-048).
+ *
+ * The interface intentionally covers only the verbs `src/runner/steps.ts`
+ * actually uses. Selector strings are the driver's own dialect: the driver
+ * supplies `parseTextSelector` so the guardrail policy can reason about them
+ * without knowing the engine.
+ */
+/** Coarse capability groups a step handler can require of a driver. */
+type DriverCapability = "navigate" | "query" | "interact" | "wait" | "screenshot" | "evaluate" | "response" | "route" | "dialog" | "files" | "download";
+/** How a dialog opened by the page should be answered. */
+type DialogAction = "accept" | "dismiss";
+/** Options accepted when navigating; mirrors the subset of Playwright's `goto`. */
+type NavigateOptions = {
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+};
+/** A network response as the driver exposes it (engine-neutral). */
+type DriverResponse = {
+    url(): string;
+    status(): number;
+    /** Header names MUST be lowercased by the driver; consumers look up lowercase keys. */
+    headers(): Record<string, string>;
+};
+/** A route intercepted via `route()`; the handler fulfills it with a canned response. */
+type DriverRoute = {
+    fulfill(response: {
+        status: number;
+        contentType?: string;
+        body?: string;
+    }): Promise<void>;
+};
+/** A file download surfaced by `waitForDownloadEvent()`. */
+type DriverDownload = {
+    suggestedFilename(): string;
+    saveAs(path: string): Promise<void>;
+};
+/**
+ * The operations the step runner performs against a live session. Each method
+ * corresponds to one Playwright Page/Locator call in the legacy runner, so the
+ * Playwright implementation is a faithful pass-through and behaviour is
+ * unchanged.
+ */
+interface SessionDriver {
+    /** Capabilities this driver supports; handlers declare what they need. */
+    readonly capabilities: ReadonlySet<DriverCapability>;
+    goto(url: string, options?: NavigateOptions): Promise<void>;
+    currentUrl(): string;
+    count(selector: string): Promise<number>;
+    textContent(selector: string): Promise<string | null>;
+    click(selector: string): Promise<void>;
+    clickFirst(selector: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    fillFirst(selector: string, value: string): Promise<void>;
+    press(selector: string, key: string): Promise<void>;
+    selectOption(selector: string, value: string): Promise<void>;
+    selectOptionFirst(selector: string, value: string): Promise<void>;
+    hover(selector: string): Promise<void>;
+    scrollIntoView(selector: string): Promise<void>;
+    setInputFiles(selector: string, files: string | string[]): Promise<void>;
+    countByRole(role: string, name: string): Promise<number>;
+    clickFirstByRole(role: string, name: string): Promise<void>;
+    countByLabel(label: string): Promise<number>;
+    fillFirstByLabel(label: string, value: string): Promise<void>;
+    selectOptionFirstByLabel(label: string, value: string): Promise<void>;
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForUrl(predicate: (url: string) => boolean, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForNetworkIdle(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    evaluate<R = unknown, A = unknown>(pageFunction: string | ((arg: A) => R | Promise<R>), arg?: A): Promise<R>;
+    screenshot(options: {
+        path: string;
+        fullPage?: boolean;
+    }): Promise<void>;
+    onResponse(handler: (response: DriverResponse) => void): void;
+    route(url: string, handler: (route: DriverRoute) => void | Promise<void>): Promise<void>;
+    unroute(url: string): Promise<void>;
+    onDialog(action: DialogAction): void;
+    waitForDownloadEvent(options?: {
+        timeout?: number;
+    }): Promise<DriverDownload>;
+    /**
+     * Driver-supplied selector parser: returns the literal text a text-engine
+     * selector matches (e.g. `text="Delete"` → `Delete`), or null for any other
+     * selector. The guardrail policy uses this to interpret forbidden patterns
+     * without hard-coding the engine's selector dialect.
+     */
+    parseTextSelector(selector: string): string | null;
+}
+
+/**
+ * PROWL-048 / ARCH-002 — macOS native implementation of {@link SessionDriver}.
+ *
+ * `MacDriver` drives a native macOS app through the `prowl-macdriver` Swift
+ * helper (Accessibility / AXUIElement) over a long-lived JSON-over-stdio
+ * transport ({@link MacHelperClient}). 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 the macOS target.
+ *
+ * Selector dialect (parsed here, so the Swift helper only matches attributes):
+ *   id=openSettings              → accessibility identifier
+ *   role=button[name="Save"]     → AX role + accessible name
+ *   label="Email"                → exact accessibility label
+ *   text="Save" | Save           → title/description/value substring
+ *   statusItem                   → open the app's menu bar status-item menu
+ *   menu=Preferences…            → open the status-item menu and click an item
+ */
+
+/** A structured accessibility query understood by the Swift helper. */
+type MacQuery = {
+    by: "id";
+    value: string;
+} | {
+    by: "role";
+    role: string;
+    name?: string;
+} | {
+    by: "text";
+    value: string;
+} | {
+    by: "label";
+    value: string;
+} | {
+    by: "focused";
+};
+/** The transport MacDriver talks to: one request → one response, matched by id. */
+interface MacHelperClient {
+    /** Send a command; resolve with its `result` payload or reject with its error. */
+    request(cmd: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Shut the helper down. */
+    close(): Promise<void>;
+}
+type MacDriverOptions = {
+    /** Bundle id / app label, used only for the informational `currentUrl()` value. */
+    appLabel?: string;
+};
+/** Parse a Prowl selector string into a {@link MacQuery}. Bare text matches by text. */
+declare function parseMacSelector(selector: string): MacQuery;
+/** Wrap a live {@link MacHelperClient} as a {@link SessionDriver}. */
+declare function createMacDriver(client: MacHelperClient, options?: MacDriverOptions): SessionDriver;
+
+declare function macdriverBuildInstructions(): string;
+/**
+ * Resolve the helper binary path. Order: `PROWL_MACDRIVER_BIN`, then the
+ * release then debug build under `macdriver/.build/`. Throws with build
+ * instructions when none is found.
+ */
+declare function resolveHelperBinary(env?: NodeJS.ProcessEnv): string;
+/** Default per-request deadline for the helper transport. */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+type SpawnMacHelperOptions = {
+    /** Per-request deadline; a request that gets no response by then rejects. */
+    requestTimeoutMs?: number;
+};
+/** A {@link MacHelperClient} backed by a spawned `prowl-macdriver serve` process. */
+declare class SpawnMacHelperClient implements MacHelperClient {
+    private readonly child;
+    private readonly pending;
+    private readonly requestTimeoutMs;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private nextId;
+    private closed;
+    private terminalError;
+    constructor(binaryPath: string, options?: SpawnMacHelperOptions);
+    private onStdout;
+    private dispatch;
+    private failAll;
+    private recordTerminalFailure;
+    /** Number of in-flight requests awaiting a response (for teardown/tests). */
+    get pendingCount(): number;
+    request(cmd: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+type MacSession = {
+    client: MacHelperClient;
+    driver: SessionDriver;
+    bundleId: string;
+};
+type LaunchMacOptions = {
+    /** Bundle id or absolute `.app` path. */
+    app: string;
+    timeoutMs?: number;
+    /** Inject a helper client (tests / a prebuilt binary); defaults to spawning the helper. */
+    clientFactory?: () => MacHelperClient;
+};
+/** Launch/attach the target app through the helper and build a {@link MacDriver}. */
+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>;
+
+/** 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>;
+    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. */
+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;
+
+/**
+ * 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";
+    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>;
+    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;
+/** 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. */
+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>;
+/** 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";
+/** The runner `.app` produced by `xcodebuild build-for-testing`. */
+declare const WDA_RUNNER_APP_NAME = "WebDriverAgentRunner-Runner.app";
+/** 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 ResolveWdaRunnerOptions = {
+    runner?: SimctlRunner;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    requireFn?: NodeRequire;
+    /** One-line progress notice sink (defaults to stderr). */
+    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.
+ */
+declare function resolveWdaRunner(options?: ResolveWdaRunnerOptions): Promise<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;
+    portAllocator?: () => Promise<number>;
+    agentConnector?: IosAgentConnector;
+    /** Skip WDA build/resolution by supplying the runner app path directly. */
+    wdaRunnerApp?: 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, 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).
+ */
+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.
+ *
+ * The runtime capability gate in the step runner already rejects steps a driver
+ * cannot honor. This adds a friendlier, earlier validation-time rejection: when
+ * the selected target is macOS, hunts using web-only steps fail fast with a
+ * clear message before anything launches.
+ */
+
+/**
+ * Step types that only make sense on the web target. Everything else
+ * (`click`, `fill`, `type`, `press`, `wait`, `assert visible/notVisible`,
+ * `screenshot`, `assertScreenshot`, `repeat`, `runHunt`, `if`, `copyText`,
+ * `hover`, `scrollTo`, `waitForSelector`) is portable across targets.
+ */
+declare const WEB_ONLY_STEP_TYPES: ReadonlySet<string>;
+/** The web-only reason a step is unsupported on a non-web target, or null if portable. */
+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; 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`
+ * path. An empty list means the scope is unset and the target app is implicitly
+ * 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 StepCallback = (result: StepResult, step: Step, index: number) => void;
 
 type RunOptions = {
@@ -353,6 +1197,12 @@ type RunOptions = {
     channel?: BrowserChannel;
     viewport?: string;
     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;
@@ -468,6 +1318,16 @@ type RankFlakyOptions = {
  */
 declare function rankFlaky(configDir: string, options?: RankFlakyOptions): FlakyScore[];
 
+/**
+ * The minimal probe surface healing needs: count matches for a candidate
+ * selector. A live Playwright page and a {@link SessionDriver}-backed adapter
+ * both satisfy it, so healing carries no Playwright dependency.
+ */
+type SelectorProbe = {
+    locator(selector: string): {
+        count(): Promise<number>;
+    };
+};
 /**
  * Self-healing selectors (PROWL-023). When an explicit selector matches nothing,
  * derive the human "intent" from the selector and try alternative strategies —
@@ -508,7 +1368,7 @@ declare function buildHealCandidates(selector: string): Array<{
  * resolves to exactly one element; otherwise null. Counting is delegated so this
  * is unit-testable with a fake page.
  */
-declare function healSelector(page: Pick<Page, "locator">, selector: string, options: {
+declare function healSelector(probe: SelectorProbe, selector: string, options: {
     enabled: boolean;
 }): Promise<HealResult | null>;
 
@@ -541,13 +1401,55 @@ declare function loadHuntMeta(huntName: string, configDir: string): {
 declare function listHunts(configDir: string): string[];
 
 declare const configSchema: z.ZodObject<{
-    target: z.ZodObject<{
+    target: z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"macos">;
+        app: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        app: string;
+        type: "macos";
+    }, {
+        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;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         url: string;
+        type?: "web" | undefined;
     }, {
         url: string;
-    }>;
+        type?: "web" | undefined;
+    }>]>;
     browser: z.ZodOptional<z.ZodObject<{
         headless: z.ZodOptional<z.ZodBoolean>;
         slowMo: z.ZodOptional<z.ZodNumber>;
@@ -565,9 +1467,9 @@ declare const configSchema: z.ZodObject<{
             height: number;
         }>]>>;
     }, "strip", z.ZodTypeAny, {
+        timeout?: number | undefined;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
-        timeout?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
@@ -575,9 +1477,9 @@ declare const configSchema: z.ZodObject<{
             height: number;
         } | undefined;
     }, {
+        timeout?: number | undefined;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
-        timeout?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
@@ -620,16 +1522,19 @@ declare const configSchema: z.ZodObject<{
     guardrails: z.ZodOptional<z.ZodObject<{
         maxSteps: z.ZodOptional<z.ZodNumber>;
         allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedApps: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         forbiddenSelectors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         selfHealing: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     }, {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     }>>;
@@ -677,11 +1582,25 @@ declare const configSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     target: {
         url: string;
+        type?: "web" | undefined;
+    } | {
+        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;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
-        timeout?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
@@ -704,6 +1623,7 @@ declare const configSchema: z.ZodObject<{
     guardrails?: {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     } | undefined;
@@ -727,11 +1647,25 @@ declare const configSchema: z.ZodObject<{
 }, {
     target: {
         url: string;
+        type?: "web" | undefined;
+    } | {
+        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;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
-        timeout?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
@@ -754,6 +1688,7 @@ declare const configSchema: z.ZodObject<{
     guardrails?: {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     } | undefined;
@@ -831,6 +1766,7 @@ declare const huntSchema: z.ZodObject<{
     }>>;
 }, "strict", z.ZodTypeAny, {
     steps: Step[];
+    name?: string | undefined;
     assertions?: ({
         selectorExists: string;
     } | {
@@ -844,7 +1780,6 @@ declare const huntSchema: z.ZodObject<{
     } | {
         noNetworkErrors: boolean;
     })[] | undefined;
-    name?: string | undefined;
     vars?: Record<string, string> | undefined;
     description?: string | undefined;
     tags?: string[] | undefined;
@@ -854,6 +1789,7 @@ declare const huntSchema: z.ZodObject<{
     } | undefined;
 }, {
     steps: Step[];
+    name?: string | undefined;
     assertions?: ({
         selectorExists: string;
     } | {
@@ -867,7 +1803,6 @@ declare const huntSchema: z.ZodObject<{
     } | {
         noNetworkErrors: boolean;
     })[] | undefined;
-    name?: string | undefined;
     vars?: Record<string, string> | undefined;
     description?: string | undefined;
     tags?: string[] | undefined;
@@ -885,6 +1820,15 @@ type InterpolatedHunt = {
 };
 declare function interpolateHunt(hunt: Hunt, env: NodeJS.ProcessEnv, randomVars?: Record<string, string>): InterpolatedHunt;
 
+/**
+ * The minimal surface `analyzePage` needs: a way to evaluate a DOM-scraping
+ * function in the page. Both a live Playwright page and a {@link SessionDriver}
+ * satisfy it (the driver's `evaluate` verb), so the analyzer has no direct
+ * Playwright dependency — its DOM scraping runs through the driver.
+ */
+type DomEvaluator = {
+    evaluate(pageFunction: () => unknown): Promise<unknown>;
+};
 type PageElement = {
     tag: string;
     type?: string;
@@ -913,7 +1857,98 @@ type AnalysisResult = {
     forms: PageForm[];
     links: PageLink[];
 };
-declare function analyzePage(page: Page): Promise<AnalysisResult>;
+declare function analyzePage(page: DomEvaluator): Promise<AnalysisResult>;
+
+/**
+ * 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>;
 
 type AiProvider = "anthropic" | "openai";
 type AiConfig = {
@@ -932,4 +1967,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, type EvalScriptStep, type FailureCluster, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, type IfStep, 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, type Step, type StepResult, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, analyzePage, buildHealCandidates, clusterFailures, computeFlakeScore, configSchema, extractFailures, extractSelectorIntent, generateHunt, healSelector, huntSchema, interpolateHunt, listHunts, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, rankFlaky, readHistory, readHuntHistory, runHunt, runSuite, stepSchema, updateBacklogFromSuite };
+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 };