@allwright.dev/core 0.1.19 → 0.1.21

package/README.md

@@ -51,7 +51,7 @@ 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) and [examples/android-basic.ts](./examples/android-basic.ts).
+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).
 
 Shared config files are stack-agnostic and can live in `allwright.config.yaml` or `allwright.config.json`.
 The shared schema lives at the repo root in `allwright.schema.json`.
@@ -104,7 +104,7 @@ const value = await page.locator('input, textarea').inputValue();
 const options = await page.locator('select').selectedOptions(); // [{ value, label, index }]
 const selectedText = await page.locator('textarea').selectedText();
 const checked = await page.locator('input[type=checkbox]').isChecked();
-const text = await page.locator('h1').innerText(); // { selector, text, note }
+const text = await page.locator('h1').innerText(); // string
 const attribute = await page.locator('a').getAttribute('href');
 const box = await page.locator('button').boundingBox(); // { x, y, width, height }
 ```

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.19";
+const DEFAULT_RELEASE_VERSION = "0.1.21";
 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.d.ts

@@ -0,0 +1,2 @@
+import type { DesktopSurfaceNamespace } from "./types.js";
+export declare const desktop: DesktopSurfaceNamespace;

package/dist/desktop.js

@@ -0,0 +1,73 @@
+import { createBrowserSessionHandle, getRuntime } from "./runtime.js";
+import { MobileAndroidAppImpl } from "./mobile.js";
+function retryOptions(timeoutMs) {
+    return timeoutMs === undefined ? undefined : { timeoutMs };
+}
+class DesktopMacImpl {
+    sessionId;
+    surfaceSessionId;
+    runtime;
+    stream;
+    queue;
+    #closed = false;
+    #currentApp;
+    constructor(sessionId, surfaceSessionId, runtime, stream, queue, initialAppSessionId) {
+        this.sessionId = sessionId;
+        this.surfaceSessionId = surfaceSessionId;
+        this.runtime = runtime;
+        this.stream = stream;
+        this.queue = queue;
+        this.#currentApp = new MobileAndroidAppImpl(runtime, surfaceSessionId, initialAppSessionId);
+    }
+    app() {
+        return this.#currentApp;
+    }
+    async launch(options) {
+        if (this.#closed)
+            throw new Error(`macOS desktop session ${this.sessionId} is closed`);
+        this.stream.write({
+            launchDesktopApp: {
+                appId: options.appId,
+                terminateRunning: options.terminateRunning ?? false,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
+        });
+        while (true) {
+            const event = await this.queue.next();
+            if (event.desktopAppLaunched?.appSessionId) {
+                this.#currentApp = new MobileAndroidAppImpl(this.runtime, this.surfaceSessionId, event.desktopAppLaunched.appSessionId);
+                return this.#currentApp;
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+            if (event.closed) {
+                this.#closed = true;
+                throw new Error(`macOS desktop session ${this.sessionId} closed while launching app`);
+            }
+        }
+    }
+}
+class DesktopMacSurfaceImpl {
+    async connect(options = {}) {
+        const runtime = await getRuntime();
+        const { stream, queue } = await createBrowserSessionHandle(runtime);
+        stream.write({
+            connectDesktop: {
+                platform: 1,
+                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);
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+}
+export const desktop = {
+    mac: new DesktopMacSurfaceImpl(),
+};

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
 import { mobile } from "./mobile.js";
+import { desktop } from "./desktop.js";
 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, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, MobileIosConnectOptions, MobileIosDevice, MobileIosLaunchOptions, MobileIosLocator, MobileIosApp, Locator, LocatorInfo, MobileSurfaceNamespace, 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, 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 declare const chromium: BrowserType;
 export declare const firefox: BrowserType;
 export declare const hooks: {
@@ -15,6 +16,7 @@ export declare const hooks: {
     download: HookType<Download>;
 };
 export { mobile };
+export { desktop };
 export type Tab = Page;
 export declare function ping(): Promise<string>;
 export declare function launchChrome(options?: LaunchOptions): Promise<Browser>;

package/dist/index.js

@@ -2,6 +2,7 @@ import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
 import { formatActionError } from "./errors.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
 import { mobile } from "./mobile.js";
+import { desktop } from "./desktop.js";
 import { PageImpl } from "./page.js";
 import { createBrowserSessionHandle, getRuntime, launchConfiguredBrowser as launchConfiguredBrowserWithResolver, ping as runtimePing, resolveLaunchBrowserArgs, setServerAddr, shutdown, } from "./runtime.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
@@ -14,6 +15,7 @@ export const hooks = {
     download: Object.freeze({ name: "download" }),
 };
 export { mobile };
+export { desktop };
 export async function ping() {
     return runtimePing();
 }

package/dist/locator.d.ts

@@ -1,27 +1,27 @@
 import { WebLocatorBuilders, type LocatorFilterOptions } from "./web-locators.js";
-import type { BoundingBox, CapturedOption, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, Locator, LocatorInfo, Page, PressOptions, PressResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult } from "./types.js";
+import type { BoundingBox, CapturedOption, 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<ClickResult>;
-    count(options?: CommandOptions): Promise<CountResult>;
-    highlight(options?: HighlightOptions): Promise<HighlightResult>;
-    focus(options?: CommandOptions): Promise<ElementResult>;
-    fill(value: string, options?: CommandOptions): Promise<FillResult>;
-    hover(options?: CommandOptions): Promise<ElementResult>;
-    press(key: string, options?: PressOptions): Promise<PressResult>;
+    click(options?: CommandOptions): Promise<void>;
+    count(options?: CommandOptions): Promise<number>;
+    highlight(options?: HighlightOptions): Promise<void>;
+    focus(options?: CommandOptions): Promise<void>;
+    fill(value: string, options?: CommandOptions): Promise<void>;
+    hover(options?: CommandOptions): Promise<void>;
+    press(key: string, options?: PressOptions): Promise<void>;
     inputValue(options?: CommandOptions): Promise<string>;
     selectedOptions(options?: CommandOptions): Promise<CapturedOption[]>;
     selectedText(options?: CommandOptions): Promise<string | null>;
     isChecked(options?: CommandOptions): Promise<boolean>;
     getAttribute(name: string, options?: CommandOptions): Promise<string | null>;
     boundingBox(options?: CommandOptions): Promise<BoundingBox | null>;
-    textContent(options?: CommandOptions): Promise<TextResult>;
-    innerText(options?: CommandOptions): Promise<TextResult>;
-    waitFor(options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
+    textContent(options?: CommandOptions): Promise<string | null>;
+    innerText(options?: CommandOptions): Promise<string>;
+    waitFor(options?: WaitForSelectorOptions): Promise<void>;
     not(other: Locator): Locator;
     filter(options?: LocatorFilterOptions): Locator;
     nth(index: number): Locator;

package/dist/mobile.d.ts

@@ -1,2 +1,28 @@
-import type { MobileSurfaceNamespace } from "./types.js";
+import { type RoleOptions, type TextMatcher, type TextOptions } from "./web-locators.js";
+import type { AccessibilitySnapshotOptions, CommandOptions, Hook, HookType, MobileAndroidLocator, MobileAndroidApp, MobileSurfaceNamespace, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
+export declare class MobileAndroidAppImpl implements MobileAndroidApp {
+    #private;
+    readonly sessionId: string;
+    constructor(runtime: RuntimeClient, surfaceSessionId: string, sessionId: string);
+    locator(selector: string): MobileAndroidLocator;
+    getByRole(role: string, options?: RoleOptions): MobileAndroidLocator;
+    getByText(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
+    getByLabel(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
+    getByTestId(text: TextMatcher): MobileAndroidLocator;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
+    setChooserFiles(fileChooserId: string, files: string[], options: CommandOptions): Promise<void>;
+    saveMobileDownload(downloadId: string, path: string, options: CommandOptions): Promise<void>;
+    click(selector: string, options?: CommandOptions): Promise<void>;
+    goto(url: string, options?: CommandOptions): Promise<void>;
+    navigate(url: string, options?: CommandOptions): Promise<void>;
+    count(selector: string, options?: CommandOptions): Promise<number>;
+    focus(selector: string, options?: CommandOptions): Promise<void>;
+    fill(selector: string, value: string, options?: CommandOptions): Promise<void>;
+    press(selector: string, key: string, options?: PressOptions): Promise<void>;
+    textContent(selector: string, options?: CommandOptions): Promise<string | null>;
+    innerText(selector: string, options?: CommandOptions): Promise<string>;
+    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
+    accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
+    screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+}
 export declare const mobile: MobileSurfaceNamespace;

package/dist/mobile.js

@@ -7,7 +7,7 @@ import { semanticSelector } from "./web-locators.js";
 function retryOptions(timeoutMs) {
     return timeoutMs ? { timeoutMs } : undefined;
 }
-class MobileAndroidAppImpl {
+export class MobileAndroidAppImpl {
     sessionId;
     #runtime;
     #surfaceSessionId;
@@ -204,11 +204,7 @@ class MobileAndroidAppImpl {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementClicked) {
-                return {
-                    selector: event.elementClicked.cssSelector ?? "",
-                    note: event.elementClicked.note ?? "",
-                    bidiSessionId: event.elementClicked.bidiSessionId ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);
@@ -219,6 +215,30 @@ class MobileAndroidAppImpl {
             }
         }
     }
+    async goto(url, options = {}) {
+        return this.navigate(url, options);
+    }
+    async navigate(url, options = {}) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            navigate: { url, retryOptions: retryOptions(options.timeoutMs) },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.navigated) {
+                return;
+            }
+            if (event.error?.message)
+                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`);
+            }
+        }
+    }
     async count(selector, options = {}) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
@@ -233,11 +253,7 @@ class MobileAndroidAppImpl {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementCounted) {
-                return {
-                    selector: event.elementCounted.cssSelector ?? "",
-                    count: event.elementCounted.count ?? 0,
-                    note: event.elementCounted.note ?? "",
-                };
+                return event.elementCounted.count ?? 0;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);
@@ -262,10 +278,7 @@ class MobileAndroidAppImpl {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementFocused) {
-                return {
-                    selector: event.elementFocused.cssSelector ?? "",
-                    note: event.elementFocused.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);
@@ -291,11 +304,7 @@ class MobileAndroidAppImpl {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementFilled) {
-                return {
-                    selector: event.elementFilled.cssSelector ?? "",
-                    value: event.elementFilled.value ?? "",
-                    note: event.elementFilled.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);
@@ -322,11 +331,7 @@ class MobileAndroidAppImpl {
         while (true) {
             const event = await handle.queue.next();
             if (event.keyPressed) {
-                return {
-                    selector: event.keyPressed.cssSelector ?? "",
-                    key: event.keyPressed.key ?? "",
-                    note: event.keyPressed.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);
@@ -338,10 +343,10 @@ class MobileAndroidAppImpl {
         }
     }
     async textContent(selector, options = {}) {
-        return this.#readText(selector, options, true);
+        return (await this.#readText(selector, options, true)).text;
     }
     async innerText(selector, options = {}) {
-        return this.#readText(selector, options, false);
+        return (await this.#readText(selector, options, false)).text;
     }
     async waitForSelector(selector, options = {}) {
         const handle = await this.#getHandle();
@@ -358,11 +363,7 @@ class MobileAndroidAppImpl {
         while (true) {
             const event = await handle.queue.next();
             if (event.selectorWaitSatisfied) {
-                return {
-                    selector: event.selectorWaitSatisfied.cssSelector ?? "",
-                    visible: event.selectorWaitSatisfied.visible ?? false,
-                    note: event.selectorWaitSatisfied.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);
@@ -426,7 +427,7 @@ class MobileAndroidAppImpl {
                 if (options.path) {
                     await writeFile(options.path, screenshot.pngData);
                 }
-                return screenshot;
+                return screenshot.pngData;
             }
             if (event.error?.message) {
                 throw new Error(event.error.message);

package/dist/mobileSelectors.js

@@ -152,6 +152,9 @@ export function normalizeMobileSelectorForTransport(selector) {
     if (!trimmed) {
         return "";
     }
+    if (/^ref[=:]/i.test(trimmed)) {
+        return `ref=${decodeSelectorBody(trimmed.slice(4))}`;
+    }
     if (isNormalizedTransportSelector(trimmed)) {
         return trimmed;
     }

package/dist/page.d.ts

@@ -1,5 +1,5 @@
 import { WebLocatorBuilders, type LocatorFilterOptions } from "./web-locators.js";
-import type { BoundingBox, CapturedOption, AccessibilitySnapshotOptions, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, FileChooser, Download, HighlightOptions, HighlightResult, Hook, HookType, Locator, NavigateResult, Page, PageInfo, PressOptions, PressResult, RuntimeClient, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult } from "./types.js";
+import type { BoundingBox, CapturedOption, AccessibilitySnapshotOptions, 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 & {
@@ -13,14 +13,14 @@ export declare class PageImpl extends WebLocatorBuilders implements Page {
     setFileChooserFiles(fileChooserId: string, files: string[], options?: CommandOptions): Promise<void>;
     saveDownload(downloadId: string, path: string, options?: CommandOptions): Promise<void>;
     locator(selector: string, options?: LocatorFilterOptions): Locator;
-    goto(url: string, options?: CommandOptions): Promise<NavigateResult>;
-    click(selector: string, options?: CommandOptions): Promise<ClickResult>;
-    count(selector: string, options?: CommandOptions): Promise<CountResult>;
-    highlight(selector: string, options?: HighlightOptions): Promise<HighlightResult>;
-    focus(selector: string, options?: CommandOptions): Promise<ElementResult>;
-    fill(selector: string, value: string, options?: CommandOptions): Promise<FillResult>;
-    hover(selector: string, options?: CommandOptions): Promise<ElementResult>;
-    press(selector: string, key: string, options?: PressOptions): Promise<PressResult>;
+    goto(url: string, options?: CommandOptions): Promise<void>;
+    click(selector: string, options?: CommandOptions): Promise<void>;
+    count(selector: string, options?: CommandOptions): Promise<number>;
+    highlight(selector: string, options?: HighlightOptions): Promise<void>;
+    focus(selector: string, options?: CommandOptions): Promise<void>;
+    fill(selector: string, value: string, options?: CommandOptions): Promise<void>;
+    hover(selector: string, options?: CommandOptions): Promise<void>;
+    press(selector: string, key: string, options?: PressOptions): Promise<void>;
     url(options?: CommandOptions): Promise<string>;
     inputValue(selector: string, options?: CommandOptions): Promise<string>;
     selectedOptions(selector: string, options?: CommandOptions): Promise<CapturedOption[]>;
@@ -28,15 +28,15 @@ export declare class PageImpl extends WebLocatorBuilders implements Page {
     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>;
-    textContent(selector: string, options?: CommandOptions): Promise<TextResult>;
-    innerText(selector: string, options?: CommandOptions): Promise<TextResult>;
-    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
+    textContent(selector: string, options?: CommandOptions): Promise<string | null>;
+    innerText(selector: string, options?: CommandOptions): Promise<string>;
+    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
-    screenshot(options?: ScreenshotOptions): Promise<ScreenshotResult>;
+    screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     pageInfo(): PageInfo;
-    navigate(url: string, options?: CommandOptions): Promise<NavigateResult>;
+    navigate(url: string, options?: CommandOptions): Promise<void>;
     dispose(): void;
 }
 export declare class FileChooserImpl implements FileChooser {

package/dist/page.js

@@ -278,14 +278,7 @@ export class PageImpl extends WebLocatorBuilders {
                 throw new Error(`page session ${this.sessionId} closed while navigating`);
             }
             if (navigated && injection) {
-                return {
-                    url: navigated.url ?? "",
-                    note: navigated.note ?? "",
-                    bidiSessionId: injection.bidiSessionId ?? "",
-                    mapperTargetId: injection.mapperTargetId ?? "",
-                    mapperSessionId: injection.mapperSessionId ?? "",
-                    packageVersion: injection.packageVersion ?? "",
-                };
+                return;
             }
         }
     }
@@ -304,11 +297,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementClicked) {
-                return {
-                    selector: event.elementClicked.cssSelector ?? "",
-                    note: event.elementClicked.note ?? "",
-                    bidiSessionId: event.elementClicked.bidiSessionId ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("click", event.error.message, selector);
@@ -334,11 +323,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementCounted) {
-                return {
-                    selector: event.elementCounted.cssSelector ?? "",
-                    count: event.elementCounted.count ?? 0,
-                    note: event.elementCounted.note ?? "",
-                };
+                return event.elementCounted.count ?? 0;
             }
             if (event.error?.message) {
                 throw formatActionError("count elements", event.error.message, selector);
@@ -365,11 +350,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementsHighlighted) {
-                return {
-                    selector: event.elementsHighlighted.cssSelector ?? "",
-                    count: event.elementsHighlighted.count ?? 0,
-                    note: event.elementsHighlighted.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("highlight elements", event.error.message, selector);
@@ -395,10 +376,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementFocused) {
-                return {
-                    selector: event.elementFocused.cssSelector ?? "",
-                    note: event.elementFocused.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("focus", event.error.message, selector);
@@ -425,11 +403,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementFilled) {
-                return {
-                    selector: event.elementFilled.cssSelector ?? "",
-                    value: event.elementFilled.value ?? "",
-                    note: event.elementFilled.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("fill", event.error.message, selector);
@@ -455,10 +429,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.elementHovered) {
-                return {
-                    selector: event.elementHovered.cssSelector ?? "",
-                    note: event.elementHovered.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("hover", event.error.message, selector);
@@ -486,11 +457,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.keyPressed) {
-                return {
-                    selector: event.keyPressed.cssSelector ?? "",
-                    key: event.keyPressed.key ?? "",
-                    note: event.keyPressed.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("press key", event.error.message, selector);
@@ -548,10 +515,10 @@ export class PageImpl extends WebLocatorBuilders {
         return r.boundingBox ?? null;
     }
     async textContent(selector, options = {}) {
-        return this.#readText(selector, options, true);
+        return (await this.#readText(selector, options, true)).text;
     }
     async innerText(selector, options = {}) {
-        return this.#readText(selector, options, false);
+        return (await this.#readText(selector, options, false)).text;
     }
     async waitForSelector(selector, options = {}) {
         const handle = await this.#getHandle();
@@ -569,11 +536,7 @@ export class PageImpl extends WebLocatorBuilders {
         while (true) {
             const event = await handle.queue.next();
             if (event.selectorWaitSatisfied) {
-                return {
-                    selector: event.selectorWaitSatisfied.cssSelector ?? "",
-                    visible: event.selectorWaitSatisfied.visible ?? false,
-                    note: event.selectorWaitSatisfied.note ?? "",
-                };
+                return;
             }
             if (event.error?.message) {
                 throw formatActionError("wait for selector", event.error.message, selector);
@@ -637,7 +600,7 @@ export class PageImpl extends WebLocatorBuilders {
                 if (options.path) {
                     await writeFile(options.path, screenshot.pngData);
                 }
-                return screenshot;
+                return screenshot.pngData;
             }
             if (event.error?.message) {
                 throw formatActionError("screenshot", event.error.message);

package/dist/types.d.ts

@@ -153,19 +153,19 @@ export interface Page extends PageInfo, WebLocators {
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
     locator(selector: string, options?: LocatorFilterOptions): Locator;
-    goto(url: string, options?: CommandOptions): Promise<NavigateResult>;
-    navigate(url: string, options?: CommandOptions): Promise<NavigateResult>;
-    click(selector: string, options?: CommandOptions): Promise<ClickResult>;
-    count(selector: string, options?: CommandOptions): Promise<CountResult>;
-    highlight(selector: string, options?: HighlightOptions): Promise<HighlightResult>;
-    focus(selector: string, options?: CommandOptions): Promise<ElementResult>;
-    fill(selector: string, value: string, options?: CommandOptions): Promise<FillResult>;
-    hover(selector: string, options?: CommandOptions): Promise<ElementResult>;
-    press(selector: string, key: string, options?: PressOptions): Promise<PressResult>;
-    textContent(selector: string, options?: CommandOptions): Promise<TextResult>;
-    innerText(selector: string, options?: CommandOptions): Promise<TextResult>;
-    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
-    screenshot(options?: ScreenshotOptions): Promise<ScreenshotResult>;
+    goto(url: string, options?: CommandOptions): Promise<void>;
+    navigate(url: string, options?: CommandOptions): Promise<void>;
+    click(selector: string, options?: CommandOptions): Promise<void>;
+    count(selector: string, options?: CommandOptions): Promise<number>;
+    highlight(selector: string, options?: HighlightOptions): Promise<void>;
+    focus(selector: string, options?: CommandOptions): Promise<void>;
+    fill(selector: string, value: string, options?: CommandOptions): Promise<void>;
+    hover(selector: string, options?: CommandOptions): Promise<void>;
+    press(selector: string, key: string, options?: PressOptions): Promise<void>;
+    textContent(selector: string, options?: CommandOptions): Promise<string | null>;
+    innerText(selector: string, options?: CommandOptions): Promise<string>;
+    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
+    screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     pageInfo(): PageInfo;
@@ -186,14 +186,14 @@ export interface MobileAndroidLaunchOptions {
 export interface MobileAndroidLocator {
     readonly page: MobileAndroidApp;
     readonly selector: string;
-    click(options?: CommandOptions): Promise<ClickResult>;
-    count(options?: CommandOptions): Promise<CountResult>;
-    focus(options?: CommandOptions): Promise<ElementResult>;
-    fill(value: string, options?: CommandOptions): Promise<FillResult>;
-    press(key: string, options?: PressOptions): Promise<PressResult>;
-    textContent(options?: CommandOptions): Promise<TextResult>;
-    innerText(options?: CommandOptions): Promise<TextResult>;
-    waitFor(options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
+    click(options?: CommandOptions): Promise<void>;
+    count(options?: CommandOptions): Promise<number>;
+    focus(options?: CommandOptions): Promise<void>;
+    fill(value: string, options?: CommandOptions): Promise<void>;
+    press(key: string, options?: PressOptions): Promise<void>;
+    textContent(options?: CommandOptions): Promise<string | null>;
+    innerText(options?: CommandOptions): Promise<string>;
+    waitFor(options?: WaitForSelectorOptions): Promise<void>;
     locator(selector: string): MobileAndroidLocator;
     getByRole(role: string, options?: RoleOptions): MobileAndroidLocator;
     getByText(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
@@ -203,20 +203,22 @@ export interface MobileAndroidLocator {
 export interface MobileAndroidApp {
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
     readonly sessionId: string;
+    goto(url: string, options?: CommandOptions): Promise<void>;
+    navigate(url: string, options?: CommandOptions): Promise<void>;
     locator(selector: string): MobileAndroidLocator;
     getByRole(role: string, options?: RoleOptions): MobileAndroidLocator;
     getByText(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
     getByLabel(text: TextMatcher, options?: TextOptions): MobileAndroidLocator;
     getByTestId(text: TextMatcher): MobileAndroidLocator;
-    click(selector: string, options?: CommandOptions): Promise<ClickResult>;
-    count(selector: string, options?: CommandOptions): Promise<CountResult>;
-    focus(selector: string, options?: CommandOptions): Promise<ElementResult>;
-    fill(selector: string, value: string, options?: CommandOptions): Promise<FillResult>;
-    press(selector: string, key: string, options?: PressOptions): Promise<PressResult>;
-    textContent(selector: string, options?: CommandOptions): Promise<TextResult>;
-    innerText(selector: string, options?: CommandOptions): Promise<TextResult>;
-    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
-    screenshot(options?: ScreenshotOptions): Promise<ScreenshotResult>;
+    click(selector: string, options?: CommandOptions): Promise<void>;
+    count(selector: string, options?: CommandOptions): Promise<number>;
+    focus(selector: string, options?: CommandOptions): Promise<void>;
+    fill(selector: string, value: string, options?: CommandOptions): Promise<void>;
+    press(selector: string, key: string, options?: PressOptions): Promise<void>;
+    textContent(selector: string, options?: CommandOptions): Promise<string | null>;
+    innerText(selector: string, options?: CommandOptions): Promise<string>;
+    waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<void>;
+    screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
 }
 export interface MobileAndroidDevice {
@@ -253,6 +255,27 @@ export interface MobileSurfaceNamespace {
         connect(options?: MobileIosConnectOptions): Promise<MobileIosDevice>;
     };
 }
+export interface DesktopMacConnectOptions {
+    agentEndpoint?: string;
+    timeoutMs?: number;
+}
+export interface DesktopMacLaunchOptions {
+    appId: string;
+    terminateRunning?: boolean;
+    timeoutMs?: number;
+}
+export type DesktopMacApp = MobileAndroidApp;
+export type DesktopMacLocator = MobileAndroidLocator;
+export interface DesktopMacDesktop {
+    readonly sessionId: string;
+    app(): DesktopMacApp;
+    launch(options: DesktopMacLaunchOptions): Promise<DesktopMacApp>;
+}
+export interface DesktopSurfaceNamespace {
+    mac: {
+        connect(options?: DesktopMacConnectOptions): Promise<DesktopMacDesktop>;
+    };
+}
 export interface Locator extends WebLocators {
     inputValue(options?: CommandOptions): Promise<string>;
     selectedOptions(options?: CommandOptions): Promise<CapturedOption[]>;
@@ -269,16 +292,16 @@ export interface Locator extends WebLocators {
     last(): Locator;
     readonly page: Page;
     readonly selector: string;
-    click(options?: CommandOptions): Promise<ClickResult>;
-    count(options?: CommandOptions): Promise<CountResult>;
-    highlight(options?: HighlightOptions): Promise<HighlightResult>;
-    focus(options?: CommandOptions): Promise<ElementResult>;
-    fill(value: string, options?: CommandOptions): Promise<FillResult>;
-    hover(options?: CommandOptions): Promise<ElementResult>;
-    press(key: string, options?: PressOptions): Promise<PressResult>;
-    textContent(options?: CommandOptions): Promise<TextResult>;
-    innerText(options?: CommandOptions): Promise<TextResult>;
-    waitFor(options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
+    click(options?: CommandOptions): Promise<void>;
+    count(options?: CommandOptions): Promise<number>;
+    highlight(options?: HighlightOptions): Promise<void>;
+    focus(options?: CommandOptions): Promise<void>;
+    fill(value: string, options?: CommandOptions): Promise<void>;
+    hover(options?: CommandOptions): Promise<void>;
+    press(key: string, options?: PressOptions): Promise<void>;
+    textContent(options?: CommandOptions): Promise<string | null>;
+    innerText(options?: CommandOptions): Promise<string>;
+    waitFor(options?: WaitForSelectorOptions): Promise<void>;
     locator(selector: string, options?: LocatorFilterOptions): Locator;
 }
 export interface AllwrightConfig {
@@ -415,6 +438,19 @@ export interface SurfaceSessionEvent {
         activityName?: string;
         webviewContext?: string;
     };
+    desktopConnected?: {
+        platform?: number | string;
+        hostName?: string;
+        note?: string;
+        backend?: string;
+        desktopSessionId?: string;
+        initialAppSessionId?: string;
+    };
+    desktopAppLaunched?: {
+        appSessionId?: string;
+        appId?: string;
+        note?: string;
+    };
     contextOpened?: {
         contextSessionId?: string;
         note?: string;
@@ -734,6 +770,24 @@ export interface LaunchAppRequest {
         };
     };
 }
+export interface ConnectDesktopRequest {
+    connectDesktop: {
+        platform: number;
+        agentEndpoint?: string;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+export interface LaunchDesktopAppRequest {
+    launchDesktopApp: {
+        appId: string;
+        terminateRunning?: boolean;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
 export interface SurfacePingRequest {
     ping: {
         message: string;
@@ -890,7 +944,7 @@ export interface CloseContextRequest {
     contextSessionId: string;
     close: Record<string, never>;
 }
-export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
+export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | ConnectDesktopRequest | LaunchDesktopAppRequest | SurfacePingRequest | CloseSurfaceRequest;
 export type ContextSessionRequest = {
     surfaceSessionId: string;
     contextSessionId: string;

package/package.json

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

package/proto/core/v1/surface.proto

@@ -6,6 +6,7 @@ option java_package = "dev.allwright.engine.v1";
 option java_multiple_files = true;
 
 import "core/v1/common.proto";
+import "surfaces/desktop/v1/desktop.proto";
 import "surfaces/mobile/v1/mobile.proto";
 import "surfaces/web/v1/web.proto";
 
@@ -18,6 +19,8 @@ message SurfaceSessionCommand {
     LaunchBrowserCommand launch_browser = 5;
     ConnectMobileCommand connect_mobile = 6;
     LaunchAppCommand launch_app = 7;
+    ConnectDesktopCommand connect_desktop = 8;
+    LaunchDesktopAppCommand launch_desktop_app = 9;
   }
 }
 
@@ -43,6 +46,8 @@ message SurfaceSessionEvent {
     BrowserLaunchedEvent browser_launched = 7;
     MobileConnectedEvent mobile_connected = 8;
     AppLaunchedEvent app_launched = 9;
+    DesktopConnectedEvent desktop_connected = 10;
+    DesktopAppLaunchedEvent desktop_app_launched = 11;
   }
 }
 

package/proto/surfaces/desktop/v1/desktop.proto

@@ -0,0 +1,40 @@
+syntax = "proto3";
+
+package allwright.engine.v1;
+option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+option java_package = "dev.allwright.engine.v1";
+option java_multiple_files = true;
+
+import "core/v1/common.proto";
+
+enum DesktopPlatform {
+  DESKTOP_PLATFORM_UNSPECIFIED = 0;
+  DESKTOP_PLATFORM_MAC = 1;
+}
+
+message ConnectDesktopCommand {
+  DesktopPlatform platform = 1;
+  optional string agent_endpoint = 2;
+  optional CommandRetryOptions retry_options = 3;
+}
+
+message DesktopConnectedEvent {
+  DesktopPlatform platform = 1;
+  string host_name = 2;
+  string note = 3;
+  string backend = 4;
+  string desktop_session_id = 5;
+  string initial_app_session_id = 6;
+}
+
+message LaunchDesktopAppCommand {
+  string app_id = 1;
+  bool terminate_running = 2;
+  optional CommandRetryOptions retry_options = 3;
+}
+
+message DesktopAppLaunchedEvent {
+  string app_session_id = 1;
+  string app_id = 2;
+  string note = 3;
+}