prowl-tools 0.1.7 → 0.1.9

package/dist/lib.d.cts

@@ -444,6 +444,8 @@ interface SessionDriver {
     goto(url: string, options?: NavigateOptions): Promise<void>;
     currentUrl(): string;
     count(selector: string): Promise<number>;
+    /** Count only elements the driver considers visibly present, when it can distinguish visibility from existence. */
+    visibleCount?(selector: string): Promise<number>;
     textContent(selector: string): Promise<string | null>;
     click(selector: string): Promise<void>;
     clickFirst(selector: string): Promise<void>;
@@ -453,6 +455,12 @@ interface SessionDriver {
     selectOption(selector: string, value: string): Promise<void>;
     selectOptionFirst(selector: string, value: string): Promise<void>;
     hover(selector: string): Promise<void>;
+    /**
+     * Scroll the viewport in `direction` by `amount` (engine-defined units: CSS
+     * pixels on web, a synthesized swipe distance on mobile). Native targets that
+     * have no scroll gesture (macOS) reject this.
+     */
+    scroll(direction: "up" | "down" | "left" | "right", amount?: number): Promise<void>;
     scrollIntoView(selector: string): Promise<void>;
     setInputFiles(selector: string, files: string | string[]): Promise<void>;
     countByRole(role: string, name: string): Promise<number>;
@@ -597,15 +605,38 @@ type ResolveHelperOptions = {
 declare function resolveHelperBinary(env?: NodeJS.ProcessEnv, options?: ResolveHelperOptions): string;
 /** Default per-request deadline for the helper transport. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * A server-initiated event line from the helper (ARCH-008): a JSON object with
+ * an `event` discriminant and **no** `id`, so it is unambiguously distinct from
+ * an id-matched command response. Emitted, for example, when an AXObserver
+ * notification fires during a `waitFor`/`openMenu` wait.
+ */
+type MacHelperEvent = Record<string, unknown> & {
+    event: string;
+};
 type SpawnMacHelperOptions = {
     /** Per-request deadline; a request that gets no response by then rejects. */
     requestTimeoutMs?: number;
+    /**
+     * Optional sink for server-initiated event lines. Events are informational —
+     * waits are resolved helper-side by the id-matched response — so they are
+     * forwarded here (if provided) and otherwise dropped, never touching the
+     * pending-request map.
+     */
+    onEvent?: (event: MacHelperEvent) => void;
+    /**
+     * Optional diagnostic sink for event handler failures. Defaults to stderr so a
+     * bad sink is visible without allowing it to break helper transport.
+     */
+    onEventError?: (message: string) => void;
 };
 /** 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 readonly onEvent?;
+    private readonly onEventError;
     private stdoutBuffer;
     private stderrBuffer;
     private nextId;
@@ -614,6 +645,7 @@ declare class SpawnMacHelperClient implements MacHelperClient {
     constructor(binaryPath: string, options?: SpawnMacHelperOptions);
     private onStdout;
     private dispatch;
+    private handleEvent;
     private failAll;
     private recordTerminalFailure;
     /** Number of in-flight requests awaiting a response (for teardown/tests). */
@@ -751,6 +783,38 @@ declare function collectMacdriverStatus(options?: StatusOptions): Promise<Macdri
 /** Static TCC-permission guidance printed after install / in status. */
 declare function tccGuidance(): string;
 
+/** Screen dimensions in device points, as reported by the agent. */
+interface ScreenSize {
+    width: number;
+    height: number;
+}
+/** One item in a W3C `pointer` action sequence. */
+type PointerActionItem = {
+    type: "pointerMove";
+    duration: number;
+    x: number;
+    y: number;
+    origin?: "viewport";
+} | {
+    type: "pointerDown";
+    button: number;
+} | {
+    type: "pointerUp";
+    button: number;
+} | {
+    type: "pause";
+    duration: number;
+};
+/** A single `touch` pointer input source and its ordered actions. */
+interface PointerActionSequence {
+    type: "pointer";
+    id: string;
+    parameters: {
+        pointerType: "touch";
+    };
+    actions: PointerActionItem[];
+}
+
 /** The selector kinds the native dialect understands. */
 type NativeSelectorKind = "id" | "label" | "text" | "role" | "focused";
 /**
@@ -968,6 +1032,10 @@ interface AndroidAgentClient {
     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>;
+    /** Current screen size in pixels (uiautomator2 `/window/current/size`), for gestures. */
+    windowSize(): Promise<ScreenSize>;
+    /** Perform a W3C pointer action sequence (`POST /session/:id/actions`). */
+    performActions(actions: PointerActionSequence): Promise<void>;
     /** Capture the current screen as PNG bytes. */
     screenshotPng(): Promise<Buffer>;
     /**
@@ -1211,10 +1279,16 @@ interface IosAgentClient {
     /** Replace an element's text (W3C `element/value`). */
     setValue(elementId: string, text: string): Promise<void>;
     getText(elementId: string): Promise<string | null>;
+    /** True only when WDA reports the element is displayed in the current viewport. */
+    isDisplayed(elementId: string): Promise<boolean>;
     /** 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>;
+    /** Current screen size in points (WDA `/window/size`), for gesture geometry. */
+    windowSize(): Promise<ScreenSize>;
+    /** Perform a W3C pointer action sequence (WDA `POST /session/:id/actions`). */
+    performActions(actions: PointerActionSequence): 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
@@ -1516,7 +1590,9 @@ declare function createWdaAgentClient(transport: WdaTransport, sessionId: string
  * 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.
+ * `hover`, `scrollTo`, `waitForSelector`) is portable across targets. The
+ * directional `scroll` step is the one per-target exception — see
+ * {@link MACOS_UNSUPPORTED_STEP_TYPES}.
  */
 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. */
@@ -1524,8 +1600,10 @@ 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.
+ * hunt itself runs. No-op for the web target; every native target rejects the
+ * same web-only step vocabulary, and macOS additionally rejects the directional
+ * `scroll` swipe (no AX equivalent) — but NOT `scrollTo`, which macOS maps to
+ * AXScrollToVisible just as iOS/Android map it to a swipe loop.
  */
 declare function assertStepsSupportedByTarget(steps: Step[], target: Target["type"]): void;
 /** Read the bundle id from an iOS `.app` (root `Info.plist`), or null. */
@@ -1862,24 +1940,24 @@ declare const configSchema: z.ZodObject<{
         }>]>>;
     }, "strip", z.ZodTypeAny, {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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" | {
             width: number;
             height: number;
         } | undefined;
-    }, {
-        timeout?: number | undefined;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+    }, {
+        timeout?: number | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     }>>;
     artifacts: z.ZodOptional<z.ZodObject<{
         screenshots: z.ZodOptional<z.ZodEnum<["on-failure", "all"]>>;
@@ -1993,14 +2071,14 @@ declare const configSchema: z.ZodObject<{
     };
     browser?: {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     } | undefined;
     artifacts?: {
         screenshots?: "on-failure" | "all" | undefined;
@@ -2058,14 +2136,14 @@ declare const configSchema: z.ZodObject<{
     };
     browser?: {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     } | undefined;
     artifacts?: {
         screenshots?: "on-failure" | "all" | undefined;

package/dist/lib.d.ts

@@ -444,6 +444,8 @@ interface SessionDriver {
     goto(url: string, options?: NavigateOptions): Promise<void>;
     currentUrl(): string;
     count(selector: string): Promise<number>;
+    /** Count only elements the driver considers visibly present, when it can distinguish visibility from existence. */
+    visibleCount?(selector: string): Promise<number>;
     textContent(selector: string): Promise<string | null>;
     click(selector: string): Promise<void>;
     clickFirst(selector: string): Promise<void>;
@@ -453,6 +455,12 @@ interface SessionDriver {
     selectOption(selector: string, value: string): Promise<void>;
     selectOptionFirst(selector: string, value: string): Promise<void>;
     hover(selector: string): Promise<void>;
+    /**
+     * Scroll the viewport in `direction` by `amount` (engine-defined units: CSS
+     * pixels on web, a synthesized swipe distance on mobile). Native targets that
+     * have no scroll gesture (macOS) reject this.
+     */
+    scroll(direction: "up" | "down" | "left" | "right", amount?: number): Promise<void>;
     scrollIntoView(selector: string): Promise<void>;
     setInputFiles(selector: string, files: string | string[]): Promise<void>;
     countByRole(role: string, name: string): Promise<number>;
@@ -597,15 +605,38 @@ type ResolveHelperOptions = {
 declare function resolveHelperBinary(env?: NodeJS.ProcessEnv, options?: ResolveHelperOptions): string;
 /** Default per-request deadline for the helper transport. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * A server-initiated event line from the helper (ARCH-008): a JSON object with
+ * an `event` discriminant and **no** `id`, so it is unambiguously distinct from
+ * an id-matched command response. Emitted, for example, when an AXObserver
+ * notification fires during a `waitFor`/`openMenu` wait.
+ */
+type MacHelperEvent = Record<string, unknown> & {
+    event: string;
+};
 type SpawnMacHelperOptions = {
     /** Per-request deadline; a request that gets no response by then rejects. */
     requestTimeoutMs?: number;
+    /**
+     * Optional sink for server-initiated event lines. Events are informational —
+     * waits are resolved helper-side by the id-matched response — so they are
+     * forwarded here (if provided) and otherwise dropped, never touching the
+     * pending-request map.
+     */
+    onEvent?: (event: MacHelperEvent) => void;
+    /**
+     * Optional diagnostic sink for event handler failures. Defaults to stderr so a
+     * bad sink is visible without allowing it to break helper transport.
+     */
+    onEventError?: (message: string) => void;
 };
 /** 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 readonly onEvent?;
+    private readonly onEventError;
     private stdoutBuffer;
     private stderrBuffer;
     private nextId;
@@ -614,6 +645,7 @@ declare class SpawnMacHelperClient implements MacHelperClient {
     constructor(binaryPath: string, options?: SpawnMacHelperOptions);
     private onStdout;
     private dispatch;
+    private handleEvent;
     private failAll;
     private recordTerminalFailure;
     /** Number of in-flight requests awaiting a response (for teardown/tests). */
@@ -751,6 +783,38 @@ declare function collectMacdriverStatus(options?: StatusOptions): Promise<Macdri
 /** Static TCC-permission guidance printed after install / in status. */
 declare function tccGuidance(): string;
 
+/** Screen dimensions in device points, as reported by the agent. */
+interface ScreenSize {
+    width: number;
+    height: number;
+}
+/** One item in a W3C `pointer` action sequence. */
+type PointerActionItem = {
+    type: "pointerMove";
+    duration: number;
+    x: number;
+    y: number;
+    origin?: "viewport";
+} | {
+    type: "pointerDown";
+    button: number;
+} | {
+    type: "pointerUp";
+    button: number;
+} | {
+    type: "pause";
+    duration: number;
+};
+/** A single `touch` pointer input source and its ordered actions. */
+interface PointerActionSequence {
+    type: "pointer";
+    id: string;
+    parameters: {
+        pointerType: "touch";
+    };
+    actions: PointerActionItem[];
+}
+
 /** The selector kinds the native dialect understands. */
 type NativeSelectorKind = "id" | "label" | "text" | "role" | "focused";
 /**
@@ -968,6 +1032,10 @@ interface AndroidAgentClient {
     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>;
+    /** Current screen size in pixels (uiautomator2 `/window/current/size`), for gestures. */
+    windowSize(): Promise<ScreenSize>;
+    /** Perform a W3C pointer action sequence (`POST /session/:id/actions`). */
+    performActions(actions: PointerActionSequence): Promise<void>;
     /** Capture the current screen as PNG bytes. */
     screenshotPng(): Promise<Buffer>;
     /**
@@ -1211,10 +1279,16 @@ interface IosAgentClient {
     /** Replace an element's text (W3C `element/value`). */
     setValue(elementId: string, text: string): Promise<void>;
     getText(elementId: string): Promise<string | null>;
+    /** True only when WDA reports the element is displayed in the current viewport. */
+    isDisplayed(elementId: string): Promise<boolean>;
     /** 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>;
+    /** Current screen size in points (WDA `/window/size`), for gesture geometry. */
+    windowSize(): Promise<ScreenSize>;
+    /** Perform a W3C pointer action sequence (WDA `POST /session/:id/actions`). */
+    performActions(actions: PointerActionSequence): 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
@@ -1516,7 +1590,9 @@ declare function createWdaAgentClient(transport: WdaTransport, sessionId: string
  * 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.
+ * `hover`, `scrollTo`, `waitForSelector`) is portable across targets. The
+ * directional `scroll` step is the one per-target exception — see
+ * {@link MACOS_UNSUPPORTED_STEP_TYPES}.
  */
 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. */
@@ -1524,8 +1600,10 @@ 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.
+ * hunt itself runs. No-op for the web target; every native target rejects the
+ * same web-only step vocabulary, and macOS additionally rejects the directional
+ * `scroll` swipe (no AX equivalent) — but NOT `scrollTo`, which macOS maps to
+ * AXScrollToVisible just as iOS/Android map it to a swipe loop.
  */
 declare function assertStepsSupportedByTarget(steps: Step[], target: Target["type"]): void;
 /** Read the bundle id from an iOS `.app` (root `Info.plist`), or null. */
@@ -1862,24 +1940,24 @@ declare const configSchema: z.ZodObject<{
         }>]>>;
     }, "strip", z.ZodTypeAny, {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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" | {
             width: number;
             height: number;
         } | undefined;
-    }, {
-        timeout?: number | undefined;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+    }, {
+        timeout?: number | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     }>>;
     artifacts: z.ZodOptional<z.ZodObject<{
         screenshots: z.ZodOptional<z.ZodEnum<["on-failure", "all"]>>;
@@ -1993,14 +2071,14 @@ declare const configSchema: z.ZodObject<{
     };
     browser?: {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     } | undefined;
     artifacts?: {
         screenshots?: "on-failure" | "all" | undefined;
@@ -2058,14 +2136,14 @@ declare const configSchema: z.ZodObject<{
     };
     browser?: {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     } | undefined;
     artifacts?: {
         screenshots?: "on-failure" | "all" | undefined;

package/dist/lib.js

@@ -74,7 +74,6 @@ import {
   healSelector,
   injectUsePortIntoXctestrun,
   installMacdriver,
-  interpolateHunt,
   iosAppAllowedIdentities,
   iosNodeToNative,
   iosQueryToLocator,
@@ -150,17 +149,18 @@ import {
   wdaTestRunArgs,
   webOnlyReason,
   zipinfoArchiveLister
-} from "./chunk-R7NUH44M.js";
+} from "./chunk-2RNOK64Y.js";
 import {
   configSchema,
   huntSchema,
+  interpolateHunt,
   listHunts,
   loadConfig,
   loadHunt,
   loadHuntMeta,
   loadHuntTags,
   stepSchema
-} from "./chunk-O3OUTZ2P.js";
+} from "./chunk-JFJQNJSJ.js";
 export {
   ANDROID_INTERACTIVE_CLASSES,
   ANDROID_KEYCODES,

package/dist/{loader-X37URHUV.js → loader-JTHA4BYG.js}

@@ -10,7 +10,7 @@ import {
   loadHuntTags,
   resolveViewport,
   warnLegacyConfigDir
-} from "./chunk-O3OUTZ2P.js";
+} from "./chunk-JFJQNJSJ.js";
 export {
   CONFIG_DIR,
   LEGACY_CONFIG_DIR,
@@ -24,4 +24,4 @@ export {
   resolveViewport,
   warnLegacyConfigDir
 };
-//# sourceMappingURL=loader-X37URHUV.js.map
+//# sourceMappingURL=loader-JTHA4BYG.js.map

package/examples/hunts/form.yml

@@ -0,0 +1,53 @@
+# Form Submission
+# ---
+# Pattern: Forms — fill text fields, pick a dropdown option, submit, verify result.
+# What it tests: Complete a form and confirm the success state renders.
+# Customize:
+#   - Point `navigate` at your form's path
+#   - Update the field labels, the dropdown label/option, and the button text
+#     to match your form
+#
+# Tip: Prefer stable selectors — an accessible label or a data-testid — over
+# brittle CSS. Run `prowl analyze` to dump ranked selector candidates for a page.
+
+name: form
+description: Fill and submit a form, verify the success message
+
+tags:
+  - forms
+  - input
+
+steps:
+  - navigate: "/signup"
+
+  # Shorthand fill — Prowl finds the input by its label or placeholder text.
+  # Equivalent explicit form:
+  #   fill:
+  #     selector: "input[name='name']"
+  #     value: "Ada Lovelace"
+  - fill:
+      "Full name": "Ada Lovelace"
+
+  - fill:
+      "Email": "ada@example.com"
+
+  # Shorthand select — finds the <select> by its label and picks the option by
+  # its visible text. Equivalent explicit form:
+  #   selectOption:
+  #     selector: "select[name='plan']"
+  #     value: "Pro"
+  - select:
+      "Plan": "Pro"
+
+  # Shorthand click — Prowl finds a checkbox or button by its text content.
+  - click: "I agree to the terms"
+
+  - click: "Create account"
+
+  # Mid-flow assertion — verify the success state rendered.
+  - assert:
+      visible: "Welcome, Ada"
+
+assertions:
+  - urlIncludes: "/welcome"
+  - noConsoleErrors: true

package/examples/hunts/macos-hello.yml

@@ -0,0 +1,49 @@
+# macOS Hello — Your First Desktop Hunt (Experimental)
+# ---
+# Prowl drives native macOS apps through Apple's Accessibility API, from the same
+# YAML as web hunts. This starter targets TextEdit — present on every Mac — so you
+# can try the desktop target without wiring up your own app first.
+#
+# ── Before this hunt will run ───────────────────────────────────────────────
+# 1. Install the helper:  prowl macdriver install
+#    Until the first signed release ships, `install` returns a 404 — build from
+#    source instead (needs the Swift toolchain / Xcode CLT):
+#       cd macdriver && swift build -c release
+# 2. Grant Accessibility permission to the app hosting your terminal (Terminal,
+#    iTerm, VS Code, …): System Settings → Privacy & Security → Accessibility.
+#    `prowl macdriver status` prints the resolved binary and this guidance.
+# 3. Point .prowl/config.yml at a macOS target — init's default config targets
+#    the web. Replace its `target:` block, and scope the app under guardrails:
+#
+#       target:
+#         type: macos
+#         app: "com.apple.TextEdit"   # bundle id, or an absolute /path/to/App.app
+#       guardrails:
+#         allowedApps:
+#           - "com.apple.TextEdit"
+#
+# The macOS target is EXPERIMENTAL — the selector dialect and step coverage may
+# still change. `navigate`, `waitForUrl`, and other web-only steps are rejected
+# on it; the portable steps below (`type`, `assert: visible`) run on both targets.
+#
+# ── Finding selectors ───────────────────────────────────────────────────────
+# Don't guess selectors — dump them:  prowl analyze --app com.apple.TextEdit
+# It walks the Accessibility tree and prints every element with ranked selector
+# candidates (prefer `id=` — the native analog of data-testid). TextEdit's
+# controls aren't ours, so treat the steps below as a starting point and adjust
+# to what `analyze` reports on your macOS version.
+
+name: macos-hello
+description: Type into TextEdit and verify the text appears (experimental macOS target)
+
+tags:
+  - macos
+  - smoke
+
+steps:
+  # `type` sends keystrokes to the focused element — a fresh TextEdit document.
+  - type: "Hello from Prowl!"
+
+  # Portable assertion — the document's text should now contain what we typed.
+  - assert:
+      visible: "Hello from Prowl!"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prowl-tools",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
   "type": "module",
   "license": "Apache-2.0",