@allwright.dev/core 0.1.23 → 0.1.25

package/README.md

@@ -20,6 +20,9 @@ await page.click(
 await browser.close();
 ```
 
+Web clicks accept `{ button: "left" | "middle" | "right", clickCount: 1 | 2 | 3 }`.
+Use `page.dblclick(selector)` or `locator.dblclick()` for the common double-click case.
+
 Register a typed hook before an action that opens a tab, then wait for its
 typed result afterward:
 
@@ -51,11 +54,17 @@ Paths passed to `setFiles` and `saveAs` belong to the test process, even when
 the Allwright server is remote. Android apps support the same `fileChooser` and
 `download` hook shape; Android `newPage` hooks are not applicable.
 
-Runnable examples live in [examples/web-basic.ts](./examples/web-basic.ts), [examples/android-basic.ts](./examples/android-basic.ts), and [examples/ios-basic.ts](./examples/ios-basic.ts).
+Runnable examples cover every implemented surface:
+[Web](./examples/web-basic.ts), [Android](./examples/android-basic.ts),
+[iOS](./examples/ios-basic.ts), [macOS](./examples/macos-basic.ts), and
+[Windows](./examples/windows-basic.ts). The desktop examples default to
+Calculator on macOS and Notepad on Windows and accept `ALLWRIGHT_MAC_APP_ID`
+or `ALLWRIGHT_WINDOWS_APP_ID`.
 
-Android, iOS, and macOS applications implement the shared `NativeApp` and
+Android, iOS, macOS, and Windows applications implement the shared `NativeApp` and
 `NativeAppLocator` interfaces. Platform-specific type names such as
-`MobileAndroidApp`, `MobileIosLocator`, and `DesktopMacLocator` remain exported
+`MobileAndroidApp`, `MobileIosLocator`, `DesktopMacLocator`, and
+`DesktopWindowsLocator` remain exported
 as aliases for compatibility and platform-oriented annotations.
 
 Shared config files are stack-agnostic and can live in `allwright.config.yaml` or `allwright.config.json`.
@@ -117,3 +126,5 @@ const box = await page.locator('button').boundingBox(); // { x, y, width, height
 Element reads also have page methods such as `page.inputValue(selector, options)` and accept `timeoutMs`. Reads use the first locator match and work in frame pages. `inputValue` reads the live property of an input, textarea, or select. `selectedOptions` supports native selects (including multiple selections) and ARIA combobox/listbox options marked `aria-selected="true"`. `selectedText` returns the textbox's selected substring, an empty string for a caret, or `null` for input types without selection support. `isChecked` supports native checkbox/radio and ARIA checked controls; ARIA mixed state returns false.
 
 Missing attributes return `null` (an empty attribute remains `""`). Bounding boxes use CSS pixels relative to the page/frame viewport and return `null` for hidden or zero-area elements. Missing elements and incompatible control types raise errors. Use `textContent()` for raw text or `innerText()` for rendered text.
+
+`NativeApp` and `NativeAppLocator` expose `inputValue`, `isChecked`, `getAttribute`, and `boundingBox` on Android, iOS, macOS, and Windows. Native attributes are platform accessibility/UI Automation properties, and native boxes use platform screen coordinates. Selected-option and selected-text reads remain web-only.

package/dist/bootstrap.js

@@ -12,7 +12,7 @@ const ALLWRIGHT_HOME_ENV_VAR = "ALLWRIGHT_HOME";
 const ALLWRIGHT_REPOSITORY_ENV_VAR = "ALLWRIGHT_REPOSITORY";
 const ALLWRIGHT_VERSION_ENV_VAR = "ALLWRIGHT_VERSION";
 const DEFAULT_RELEASE_REPOSITORY = "allwright-dev/allwright";
-const DEFAULT_RELEASE_VERSION = "0.1.23";
+const DEFAULT_RELEASE_VERSION = "0.1.25";
 const STARTUP_TIMEOUT_MS = 20_000;
 const PING_TIMEOUT_MS = 1_000;
 const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));

package/dist/desktop.js

@@ -9,14 +9,16 @@ class DesktopMacImpl {
     runtime;
     stream;
     queue;
+    platformLabel;
     #closed = false;
     #currentApp;
-    constructor(sessionId, surfaceSessionId, runtime, stream, queue, initialAppSessionId) {
+    constructor(sessionId, surfaceSessionId, runtime, stream, queue, initialAppSessionId, platformLabel = "macOS") {
         this.sessionId = sessionId;
         this.surfaceSessionId = surfaceSessionId;
         this.runtime = runtime;
         this.stream = stream;
         this.queue = queue;
+        this.platformLabel = platformLabel;
         this.#currentApp = new NativeAppImpl(runtime, surfaceSessionId, initialAppSessionId);
     }
     app() {
@@ -24,7 +26,7 @@ class DesktopMacImpl {
     }
     async launch(options) {
         if (this.#closed)
-            throw new Error(`macOS desktop session ${this.sessionId} is closed`);
+            throw new Error(`${this.platformLabel} desktop session ${this.sessionId} is closed`);
         this.stream.write({
             launchDesktopApp: {
                 appId: options.appId,
@@ -42,7 +44,7 @@ class DesktopMacImpl {
                 throw new Error(event.error.message);
             if (event.closed) {
                 this.#closed = true;
-                throw new Error(`macOS desktop session ${this.sessionId} closed while launching app`);
+                throw new Error(`${this.platformLabel} desktop session ${this.sessionId} closed while launching app`);
             }
         }
     }
@@ -61,7 +63,28 @@ class DesktopMacSurfaceImpl {
         while (true) {
             const event = await queue.next();
             if (event.desktopConnected?.initialAppSessionId) {
-                return new DesktopMacImpl(event.desktopConnected.desktopSessionId ?? event.sessionId ?? "", event.sessionId ?? "", runtime, stream, queue, event.desktopConnected.initialAppSessionId);
+                return new DesktopMacImpl(event.desktopConnected.desktopSessionId ?? event.sessionId ?? "", event.sessionId ?? "", runtime, stream, queue, event.desktopConnected.initialAppSessionId, "macOS");
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+}
+class DesktopWindowsSurfaceImpl {
+    async connect(options = {}) {
+        const runtime = await getRuntime();
+        const { stream, queue } = await createBrowserSessionHandle(runtime);
+        stream.write({
+            connectDesktop: {
+                platform: 2,
+                agentEndpoint: options.agentEndpoint,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
+        });
+        while (true) {
+            const event = await queue.next();
+            if (event.desktopConnected?.initialAppSessionId) {
+                return new DesktopMacImpl(event.desktopConnected.desktopSessionId ?? event.sessionId ?? "", event.sessionId ?? "", runtime, stream, queue, event.desktopConnected.initialAppSessionId, "Windows");
             }
             if (event.error?.message)
                 throw new Error(event.error.message);
@@ -70,4 +93,5 @@ class DesktopMacSurfaceImpl {
 }
 export const desktop = {
     mac: new DesktopMacSurfaceImpl(),
+    windows: new DesktopWindowsSurfaceImpl(),
 };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { PageImpl } from "./page.js";
 import { setServerAddr, shutdown } from "./runtime.js";
 import type { Browser, BrowserKind, BrowserType, LaunchOptions, Page, Dialog, FileChooser, Download, HookType, ResolveConfigOptions, ResolvedAllwrightConfig } from "./types.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
-export type { CapturedOption, BoundingBox, AccessibilitySnapshotOptions, AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, Hook, HookType, Dialog, FileChooser, Download, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, NativeApp, NativeAppLocator, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, MobileIosConnectOptions, MobileIosDevice, MobileIosLaunchOptions, MobileIosLocator, MobileIosApp, Locator, LocatorInfo, MobileSurfaceNamespace, DesktopMacApp, DesktopMacConnectOptions, DesktopMacDesktop, DesktopMacLaunchOptions, DesktopMacLocator, DesktopSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
+export type { CapturedOption, BoundingBox, AccessibilitySnapshotOptions, AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, Hook, HookType, Dialog, FileChooser, Download, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, NativeApp, NativeAppLocator, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, MobileIosConnectOptions, MobileIosDevice, MobileIosLaunchOptions, MobileIosLocator, MobileIosApp, Locator, LocatorInfo, MobileSurfaceNamespace, DesktopMacApp, DesktopMacConnectOptions, DesktopMacDesktop, DesktopMacLaunchOptions, DesktopMacLocator, DesktopWindowsApp, DesktopWindowsConnectOptions, DesktopWindowsDesktop, DesktopWindowsLaunchOptions, DesktopWindowsLocator, DesktopSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
 export declare const chromium: BrowserType;
 export declare const firefox: BrowserType;
 export declare const hooks: {

package/dist/locator.d.ts

@@ -1,12 +1,13 @@
 import { WebLocatorBuilders, type LocatorFilterOptions } from "./web-locators.js";
-import type { BoundingBox, CapturedOption, CommandOptions, HighlightOptions, Locator, LocatorInfo, Page, PressOptions, WaitForSelectorOptions } from "./types.js";
+import type { BoundingBox, CapturedOption, ClickOptions, CommandOptions, HighlightOptions, Locator, LocatorInfo, Page, PressOptions, WaitForSelectorOptions } from "./types.js";
 export declare class LocatorImpl extends WebLocatorBuilders implements Locator {
     readonly page: Page;
     readonly selector: string;
     constructor(input: LocatorInfo);
     frame(options?: CommandOptions): Promise<Page>;
     Frame(options?: CommandOptions): Promise<Page>;
-    click(options?: CommandOptions): Promise<void>;
+    click(options?: ClickOptions): Promise<void>;
+    dblclick(options?: Omit<ClickOptions, "clickCount">): Promise<void>;
     count(options?: CommandOptions): Promise<number>;
     highlight(options?: HighlightOptions): Promise<void>;
     focus(options?: CommandOptions): Promise<void>;

package/dist/locator.js

@@ -13,6 +13,9 @@ export class LocatorImpl extends WebLocatorBuilders {
     async click(options = {}) {
         return this.page.click(this.selector, options);
     }
+    async dblclick(options = {}) {
+        return this.page.dblclick(this.selector, options);
+    }
     async count(options = {}) {
         return this.page.count(this.selector, options);
     }

package/dist/mobile.d.ts

@@ -1,5 +1,5 @@
 import { type RoleOptions, type TextMatcher, type TextOptions } from "./web-locators.js";
-import type { AccessibilitySnapshotOptions, CommandOptions, Hook, HookType, MobileSurfaceNamespace, NativeApp, NativeAppLocator, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
+import type { AccessibilitySnapshotOptions, BoundingBox, CommandOptions, Hook, HookType, MobileSurfaceNamespace, NativeApp, NativeAppLocator, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
 export declare class NativeAppImpl implements NativeApp {
     #private;
     readonly sessionId: string;
@@ -21,6 +21,10 @@ export declare class NativeAppImpl implements NativeApp {
     press(selector: string, key: string, options?: PressOptions): Promise<void>;
     textContent(selector: string, options?: CommandOptions): Promise<string | null>;
     innerText(selector: string, options?: CommandOptions): Promise<string>;
+    inputValue(selector: string, options?: CommandOptions): Promise<string>;
+    isChecked(selector: string, options?: CommandOptions): Promise<boolean>;
+    getAttribute(selector: string, name: string, options?: CommandOptions): Promise<string | null>;
+    boundingBox(selector: string, options?: CommandOptions): Promise<BoundingBox | null>;
     waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
     screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;

package/dist/mobile.js

@@ -94,7 +94,7 @@ export class NativeAppImpl {
             setMobileFileChooserFiles: {
                 fileChooserId,
                 fileIds,
-                retryOptions: retryOptions(options.timeoutMs),
+                retryOptions: options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : undefined,
             },
         });
         while (true) {
@@ -235,7 +235,7 @@ export class NativeAppImpl {
                 throw new Error(event.error.message);
             if (event.closed) {
                 handle.closed = true;
-                throw new Error(`mobile app session ${this.sessionId} closed while opening deep link`);
+                throw new Error(`native app session ${this.sessionId} closed while opening deep link`);
             }
         }
     }
@@ -348,6 +348,18 @@ export class NativeAppImpl {
     async innerText(selector, options = {}) {
         return (await this.#readText(selector, options, false)).text;
     }
+    async inputValue(selector, options = {}) {
+        return (await this.#capture("CAPTURE_KIND_INPUT_VALUE", selector, "", options)).value ?? "";
+    }
+    async isChecked(selector, options = {}) {
+        return (await this.#capture("CAPTURE_KIND_CHECKED", selector, "", options)).checked ?? false;
+    }
+    async getAttribute(selector, name, options = {}) {
+        return (await this.#capture("CAPTURE_KIND_ATTRIBUTE", selector, name, options)).value ?? null;
+    }
+    async boundingBox(selector, options = {}) {
+        return (await this.#capture("CAPTURE_KIND_BOUNDING_BOX", selector, "", options)).boundingBox ?? null;
+    }
     async waitForSelector(selector, options = {}) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
@@ -449,6 +461,31 @@ export class NativeAppImpl {
             throw new Error(`android app session ${this.sessionId} is closed`);
         }
     }
+    async #capture(kind, selector, attributeName, options) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            capture: {
+                kind,
+                cssSelector: normalizeMobileSelectorForTransport(selector),
+                attributeName,
+                retryOptions: options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : undefined,
+            },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.captureResolved)
+                return event.captureResolved;
+            if (event.error?.message)
+                throw new Error(event.error.message);
+            if (event.closed) {
+                handle.closed = true;
+                throw new Error(`native app session ${this.sessionId} closed while capturing element state`);
+            }
+        }
+    }
     async #readText(selector, options, textContent) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
@@ -558,6 +595,18 @@ class NativeAppLocatorImpl {
     async innerText(options = {}) {
         return this.page.innerText(this.selector, options);
     }
+    async inputValue(options = {}) {
+        return this.page.inputValue(this.selector, options);
+    }
+    async isChecked(options = {}) {
+        return this.page.isChecked(this.selector, options);
+    }
+    async getAttribute(name, options = {}) {
+        return this.page.getAttribute(this.selector, name, options);
+    }
+    async boundingBox(options = {}) {
+        return this.page.boundingBox(this.selector, options);
+    }
     async waitFor(options = {}) {
         return this.page.waitForSelector(this.selector, options);
     }

package/dist/page.d.ts

@@ -1,5 +1,5 @@
 import { WebLocatorBuilders, type LocatorFilterOptions } from "./web-locators.js";
-import type { BoundingBox, CapturedOption, AccessibilitySnapshotOptions, CommandOptions, FileChooser, Download, HighlightOptions, Hook, HookType, Locator, Page, PageInfo, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
+import type { BoundingBox, CapturedOption, AccessibilitySnapshotOptions, ClickOptions, CommandOptions, FileChooser, Download, HighlightOptions, Hook, HookType, Locator, Page, PageInfo, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
 export declare class PageImpl extends WebLocatorBuilders implements Page {
     #private;
     constructor(input: PageInfo & {
@@ -14,7 +14,8 @@ export declare class PageImpl extends WebLocatorBuilders implements Page {
     saveDownload(downloadId: string, path: string, options?: CommandOptions): Promise<void>;
     locator(selector: string, options?: LocatorFilterOptions): Locator;
     goto(url: string, options?: CommandOptions): Promise<void>;
-    click(selector: string, options?: CommandOptions): Promise<void>;
+    click(selector: string, options?: ClickOptions): Promise<void>;
+    dblclick(selector: string, options?: Omit<ClickOptions, "clickCount">): Promise<void>;
     count(selector: string, options?: CommandOptions): Promise<number>;
     highlight(selector: string, options?: HighlightOptions): Promise<void>;
     focus(selector: string, options?: CommandOptions): Promise<void>;

package/dist/page.js

@@ -291,6 +291,8 @@ export class PageImpl extends WebLocatorBuilders {
             contextSessionId: this.sessionId,
             clickElement: {
                 cssSelector: transportSelector,
+                button: options.button,
+                clickCount: options.clickCount,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
             },
         });
@@ -308,6 +310,9 @@ export class PageImpl extends WebLocatorBuilders {
             }
         }
     }
+    async dblclick(selector, options = {}) {
+        return this.click(selector, { ...options, clickCount: 2 });
+    }
     async count(selector, options = {}) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);

package/dist/types.d.ts

@@ -9,6 +9,11 @@ export type BrowserKind = "chromium" | "firefox";
 export interface CommandOptions {
     timeoutMs?: number;
 }
+export type MouseButton = "left" | "middle" | "right";
+export interface ClickOptions extends CommandOptions {
+    button?: MouseButton;
+    clickCount?: 1 | 2 | 3;
+}
 export interface AccessibilitySnapshotOptions extends CommandOptions {
     format?: "json" | "yaml";
     mode?: "default" | "ai" | "autoexpect" | "codegen";
@@ -155,7 +160,8 @@ export interface Page extends PageInfo, WebLocators {
     locator(selector: string, options?: LocatorFilterOptions): Locator;
     goto(url: string, options?: CommandOptions): Promise<void>;
     navigate(url: string, options?: CommandOptions): Promise<void>;
-    click(selector: string, options?: CommandOptions): Promise<void>;
+    click(selector: string, options?: ClickOptions): Promise<void>;
+    dblclick(selector: string, options?: Omit<ClickOptions, "clickCount">): Promise<void>;
     count(selector: string, options?: CommandOptions): Promise<number>;
     highlight(selector: string, options?: HighlightOptions): Promise<void>;
     focus(selector: string, options?: CommandOptions): Promise<void>;
@@ -193,6 +199,10 @@ export interface NativeAppLocator {
     press(key: string, options?: PressOptions): Promise<void>;
     textContent(options?: CommandOptions): Promise<string | null>;
     innerText(options?: CommandOptions): Promise<string>;
+    inputValue(options?: CommandOptions): Promise<string>;
+    isChecked(options?: CommandOptions): Promise<boolean>;
+    getAttribute(name: string, options?: CommandOptions): Promise<string | null>;
+    boundingBox(options?: CommandOptions): Promise<BoundingBox | null>;
     waitFor(options?: WaitForSelectorOptions): Promise<void>;
     locator(selector: string): NativeAppLocator;
     getByRole(role: string, options?: RoleOptions): NativeAppLocator;
@@ -217,6 +227,10 @@ export interface NativeApp {
     press(selector: string, key: string, options?: PressOptions): Promise<void>;
     textContent(selector: string, options?: CommandOptions): Promise<string | null>;
     innerText(selector: string, options?: CommandOptions): Promise<string>;
+    inputValue(selector: string, options?: CommandOptions): Promise<string>;
+    isChecked(selector: string, options?: CommandOptions): Promise<boolean>;
+    getAttribute(selector: string, name: string, options?: CommandOptions): Promise<string | null>;
+    boundingBox(selector: string, options?: CommandOptions): Promise<BoundingBox | null>;
     waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
     screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
@@ -273,10 +287,22 @@ export interface DesktopMacDesktop {
     app(): DesktopMacApp;
     launch(options: DesktopMacLaunchOptions): Promise<DesktopMacApp>;
 }
+export type DesktopWindowsConnectOptions = DesktopMacConnectOptions;
+export type DesktopWindowsLaunchOptions = DesktopMacLaunchOptions;
+export type DesktopWindowsApp = NativeApp;
+export type DesktopWindowsLocator = NativeAppLocator;
+export interface DesktopWindowsDesktop {
+    readonly sessionId: string;
+    app(): DesktopWindowsApp;
+    launch(options: DesktopWindowsLaunchOptions): Promise<DesktopWindowsApp>;
+}
 export interface DesktopSurfaceNamespace {
     mac: {
         connect(options?: DesktopMacConnectOptions): Promise<DesktopMacDesktop>;
     };
+    windows: {
+        connect(options?: DesktopWindowsConnectOptions): Promise<DesktopWindowsDesktop>;
+    };
 }
 export interface Locator extends WebLocators {
     inputValue(options?: CommandOptions): Promise<string>;
@@ -294,7 +320,8 @@ export interface Locator extends WebLocators {
     last(): Locator;
     readonly page: Page;
     readonly selector: string;
-    click(options?: CommandOptions): Promise<void>;
+    click(options?: ClickOptions): Promise<void>;
+    dblclick(options?: Omit<ClickOptions, "clickCount">): Promise<void>;
     count(options?: CommandOptions): Promise<number>;
     highlight(options?: HighlightOptions): Promise<void>;
     focus(options?: CommandOptions): Promise<void>;
@@ -820,6 +847,8 @@ export interface ClickRequest {
     contextSessionId: string;
     clickElement: {
         cssSelector: string;
+        button?: MouseButton;
+        clickCount?: number;
         retryOptions?: {
             timeoutMs?: number;
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/core",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",

package/proto/core/v1/context.proto

@@ -170,6 +170,8 @@ message NavigatePageCommand {
 message ClickElementCommand {
   string css_selector = 1;
   optional CommandRetryOptions retry_options = 2;
+  optional string button = 3;
+  optional uint32 click_count = 4;
 }
 
 message CountElementsCommand {