@allwright.dev/core 0.0.51 → 0.0.53

package/README.md

@@ -13,11 +13,14 @@ import { firefox } from "@allwright.dev/core";
 
 const browser = await firefox.launch();
 const page = browser.page();
-await page.goto("https://example.com");
+await page.goto("https://themoderninternet.vercel.app");
+await page.click(
+  "xpath=//div[contains(@class,'card')][.//h2[normalize-space()='Form Inputs']]//button[normalize-space()='Visit page']",
+);
 await browser.close();
 ```
 
-A small runnable example also lives in [examples/basic.ts](./examples/basic.ts), and the fuller end-to-end playground lives in [examples/playground.ts](./examples/playground.ts).
+Runnable examples live in [examples/web-basic.ts](./examples/web-basic.ts) and [examples/android-basic.ts](./examples/android-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`.

package/dist/bootstrap.d.ts

@@ -1,4 +1,2 @@
 export declare function ensureRuntimeReady(serverAddr: string): Promise<string>;
 export declare function shutdownManagedServer(): Promise<void>;
-export declare function ensurePluginsInstalled(pluginIds: string[]): Promise<void>;
-export declare function invokePlugin<TResponse>(pluginId: string, request: unknown): Promise<TResponse>;

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.0.51";
+const DEFAULT_RELEASE_VERSION = "0.0.53";
 const STARTUP_TIMEOUT_MS = 20_000;
 const PING_TIMEOUT_MS = 1_000;
 const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));
@@ -168,65 +168,6 @@ async function installCli() {
     fs.rmSync(assetPath, { force: true });
     return cliPath;
 }
-export async function ensurePluginsInstalled(pluginIds) {
-    const expectedVersion = expectedRuntimeVersion();
-    const cliPath = await ensureCliAvailable(expectedVersion);
-    ensurePluginsInstalledWithCli(cliPath, expectedVersion, pluginIds);
-}
-export async function invokePlugin(pluginId, request) {
-    const expectedVersion = expectedRuntimeVersion();
-    const cliPath = await ensureCliAvailable(expectedVersion);
-    const requestJson = JSON.stringify(request);
-    const result = spawnSync(cliPath, ["plugin", "invoke", pluginId, "--request-json", requestJson], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (result.error) {
-        throw new Error(`failed to invoke allwright ${pluginId} plugin with ${cliPath}: ${result.error.message}`);
-    }
-    if (result.status !== 0) {
-        const details = [result.stdout, result.stderr]
-            .map((value) => value?.trim())
-            .filter((value) => !!value)
-            .join("\n");
-        throw new Error(details
-            ? `allwright ${pluginId} plugin invocation failed:\n${details}`
-            : `allwright ${pluginId} plugin invocation failed`);
-    }
-    try {
-        return JSON.parse(result.stdout);
-    }
-    catch (error) {
-        throw new Error(`failed to decode allwright ${pluginId} plugin response: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-function ensurePluginsInstalledWithCli(cliPath, expectedVersion, pluginIds) {
-    for (const pluginId of new Set(pluginIds.map((value) => value.trim()).filter(Boolean))) {
-        const pluginPath = path.join(allwrightHome(), "plugins", pluginId, "lib", pluginLibraryFilename(pluginId));
-        if (isFile(pluginPath) && installedPluginVersion(pluginId) === expectedVersion) {
-            continue;
-        }
-        const result = spawnSync(cliPath, ["plugin", "install", pluginId, "--version", expectedVersion], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        if (result.error) {
-            throw new Error(`failed to install allwright ${pluginId} plugin with ${cliPath}: ${result.error.message}`);
-        }
-        if (result.status !== 0 || !isFile(pluginPath)) {
-            const details = [result.stdout, result.stderr]
-                .map((value) => value?.trim())
-                .filter((value) => !!value)
-                .join("\n");
-            throw new Error(details
-                ? `allwright attempted to install the \`${pluginId}\` plugin automatically, but the install did not complete successfully:\n${details}`
-                : `allwright attempted to install the \`${pluginId}\` plugin automatically, but the install did not complete successfully`);
-        }
-        if (installedPluginVersion(pluginId) !== expectedVersion) {
-            throw new Error(`allwright attempted to install the \`${pluginId}\` plugin automatically, but version ${expectedVersion} is still not active`);
-        }
-    }
-}
 async function resolveReleaseTag() {
     const version = process.env[ALLWRIGHT_VERSION_ENV_VAR]?.trim() || DEFAULT_RELEASE_VERSION;
     if (version !== "latest") {
@@ -325,23 +266,6 @@ function isLocalServerAddr(serverAddr) {
     const host = parseServerHost(serverAddr);
     return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
-function installedPluginVersion(pluginId) {
-    const manifestPath = path.join(allwrightHome(), "plugins.txt");
-    if (!isFile(manifestPath)) {
-        return null;
-    }
-    for (const line of fs.readFileSync(manifestPath, "utf8").split(/\r?\n/)) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#")) {
-            continue;
-        }
-        const [id, , version] = trimmed.split("\t", 3);
-        if (id === pluginId && version) {
-            return normalizeReleaseVersion(version);
-        }
-    }
-    return null;
-}
 async function allocateManagedServerAddr(serverAddr) {
     const host = localBindingHost(serverAddr);
     const port = await new Promise((resolve, reject) => {
@@ -454,26 +378,6 @@ function findExtractedCli(extractRoot) {
     }
     return null;
 }
-function pluginLibraryFilename(pluginId) {
-    const stem = pluginLibraryStem(pluginId);
-    if (process.platform === "darwin") {
-        return `lib${stem}.dylib`;
-    }
-    if (process.platform === "win32") {
-        return `${stem}.dll`;
-    }
-    return `lib${stem}.so`;
-}
-function pluginLibraryStem(pluginId) {
-    switch (pluginId) {
-        case "web":
-            return "allwright_surface_web";
-        case "mobile-android":
-            return "allwright_surface_mobile_android";
-        default:
-            throw new Error(`automatic install is not supported for allwright plugin \`${pluginId}\``);
-    }
-}
 function autoInstallEnabled() {
     const raw = process.env[ALLWRIGHT_AUTO_INSTALL_ENV_VAR]?.trim().toLowerCase();
     return raw !== "0" && raw !== "false" && raw !== "no";

package/dist/browser.js

@@ -33,7 +33,7 @@ export class BrowserImpl {
         this.launchNote = browserInfo.launchNote;
         this.cdpWebSocketURL = browserInfo.cdpWebSocketURL;
         this.userDataDir = browserInfo.userDataDir;
-        this.#initialPage = this.#createPage(state.launched.initialTabSessionId ?? "");
+        this.#initialPage = this.#createPage(state.launched.initialPageSessionId ?? "");
     }
     sessionId;
     browserName;
@@ -52,17 +52,17 @@ export class BrowserImpl {
     async newPage(options = {}) {
         this.#ensureOpen();
         this.#stream.write({
-            openTab: {
+            openContext: {
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
             },
         });
         while (true) {
             const event = await this.#queue.next();
-            if (event.tabOpened?.tabSessionId) {
-                return this.#createPage(event.tabOpened.tabSessionId);
+            if (event.contextOpened?.contextSessionId) {
+                return this.#createPage(event.contextOpened.contextSessionId);
             }
             if (event.error?.message) {
-                throw formatActionError("open tab", event.error.message);
+                throw formatActionError("open page", event.error.message);
             }
         }
     }

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { PageImpl } from "./page.js";
 import { setServerAddr, shutdown } from "./runtime.js";
 import type { Browser, BrowserKind, BrowserType, LaunchOptions, Page, ResolveConfigOptions, ResolvedAllwrightConfig } from "./types.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
-export type { AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidPage, Locator, LocatorInfo, MobileSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
+export type { AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, Locator, LocatorInfo, MobileSurfaceNamespace, NavigateResult, Page, PageInfo, PressOptions, PressResult, ResolveConfigOptions, ResolvedAllwrightConfig, RetryConfig, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
 export declare const chromium: BrowserType;
 export declare const firefox: BrowserType;
 export { mobile };

package/dist/mobile.js

@@ -1,59 +1,90 @@
-import { invokePlugin } from "./bootstrap.js";
+import { createBrowserSessionHandle, createPageHandle, getRuntime } from "./runtime.js";
 import { chainMobileSelectorForTransport, normalizeMobileSelectorForTransport } from "./mobileSelectors.js";
-function timeoutMsOf(options) {
-    return options?.timeoutMs;
+function retryOptions(timeoutMs) {
+    return timeoutMs ? { timeoutMs } : undefined;
 }
-async function invokeAndroidExpected(commandName, request) {
-    const envelope = await invokePlugin("mobile-android", request);
-    if (!envelope.ok) {
-        throw new Error(envelope.error ?? `mobile-android plugin ${commandName} failed`);
-    }
-    if (envelope.result === undefined) {
-        throw new Error(`mobile-android plugin ${commandName} returned no result`);
-    }
-    return envelope.result;
-}
-class MobileAndroidPageImpl {
-    browserSession;
-    pageSession;
-    constructor(browserSession, pageSession) {
-        this.browserSession = browserSession;
-        this.pageSession = pageSession;
-    }
-    get sessionId() {
-        return this.pageSession.page_id;
+class MobileAndroidAppImpl {
+    sessionId;
+    #runtime;
+    #surfaceSessionId;
+    #handlePromise = null;
+    constructor(runtime, surfaceSessionId, sessionId) {
+        this.sessionId = sessionId;
+        this.#runtime = runtime;
+        this.#surfaceSessionId = surfaceSessionId;
     }
     locator(selector) {
         return new MobileAndroidLocatorImpl(this, normalizeMobileSelectorForTransport(selector));
     }
     async click(selector, options = {}) {
-        const result = await invokeAndroidExpected("click", {
-            command: "click_element",
-            browser_session: this.browserSession,
-            page_session: this.pageSession,
-            selector: normalizeMobileSelectorForTransport(selector),
-            timeout_ms: timeoutMsOf(options),
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            clickElement: {
+                cssSelector: normalizeMobileSelectorForTransport(selector),
+                retryOptions: retryOptions(options.timeoutMs),
+            },
         });
-        return {
-            selector: result.selector,
-            note: result.note,
-            bidiSessionId: result.session_id,
-        };
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.elementClicked) {
+                return {
+                    selector: event.elementClicked.cssSelector ?? "",
+                    note: event.elementClicked.note ?? "",
+                    bidiSessionId: event.elementClicked.bidiSessionId ?? "",
+                };
+            }
+            if (event.error?.message) {
+                throw new Error(event.error.message);
+            }
+            if (event.closed) {
+                handle.closed = true;
+                throw new Error(`android app session ${this.sessionId} closed while clicking`);
+            }
+        }
     }
     async fill(selector, value, options = {}) {
-        const result = await invokeAndroidExpected("fill", {
-            command: "fill_element",
-            browser_session: this.browserSession,
-            page_session: this.pageSession,
-            selector: normalizeMobileSelectorForTransport(selector),
-            value,
-            timeout_ms: timeoutMsOf(options),
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            fillElement: {
+                cssSelector: normalizeMobileSelectorForTransport(selector),
+                value,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
         });
-        return {
-            selector: result.selector,
-            value: result.value,
-            note: result.note,
-        };
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.elementFilled) {
+                return {
+                    selector: event.elementFilled.cssSelector ?? "",
+                    value: event.elementFilled.value ?? "",
+                    note: event.elementFilled.note ?? "",
+                };
+            }
+            if (event.error?.message) {
+                throw new Error(event.error.message);
+            }
+            if (event.closed) {
+                handle.closed = true;
+                throw new Error(`android app session ${this.sessionId} closed while filling`);
+            }
+        }
+    }
+    async #getHandle() {
+        if (!this.#handlePromise) {
+            this.#handlePromise = createPageHandle(this.#runtime);
+        }
+        return this.#handlePromise;
+    }
+    #ensureOpen(handle) {
+        if (handle.closed) {
+            throw new Error(`android app session ${this.sessionId} is closed`);
+        }
     }
 }
 class MobileAndroidLocatorImpl {
@@ -74,48 +105,81 @@ class MobileAndroidLocatorImpl {
     }
 }
 class MobileAndroidDeviceImpl {
-    connectInfoRaw;
-    #initialPage;
-    constructor(connectInfoRaw) {
-        this.connectInfoRaw = connectInfoRaw;
-        this.#initialPage = new MobileAndroidPageImpl(this.connectInfoRaw.browser_session, this.connectInfoRaw.initial_page.page_session);
-    }
-    get sessionId() {
-        return this.connectInfoRaw.browser_session.automation.session_id;
-    }
-    page() {
-        return this.#initialPage;
-    }
-    initialPage() {
-        return this.#initialPage;
+    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;
+    }
+    initialApp() {
+        return this.#currentApp;
     }
     async launch(options = {}) {
-        const page = await invokeAndroidExpected("launch", {
-            command: "launch_app",
-            browser_session: this.connectInfoRaw.browser_session,
-            options: {
-                apk_path: options.apkPath,
-                app_id: options.appId,
-                launch_activity: options.launchActivity,
-                stop_before_launch: options.stopBeforeLaunch ?? false,
-                timeout_ms: timeoutMsOf(options),
+        this.#ensureOpen();
+        this.#stream.write({
+            launchApp: {
+                apkPath: options.apkPath,
+                appId: options.appId,
+                launchActivity: options.launchActivity,
+                stopBeforeLaunch: options.stopBeforeLaunch ?? false,
+                retryOptions: retryOptions(options.timeoutMs),
             },
         });
-        this.#initialPage = new MobileAndroidPageImpl(this.connectInfoRaw.browser_session, page.page_session);
-        return this.#initialPage;
+        while (true) {
+            const event = await this.#queue.next();
+            if (event.appLaunched?.appSessionId) {
+                this.#currentApp = new MobileAndroidAppImpl(this.runtime, this.surfaceSessionId, event.appLaunched.appSessionId);
+                return this.#currentApp;
+            }
+            if (event.error?.message) {
+                throw new Error(event.error.message);
+            }
+            if (event.closed) {
+                this.#closed = true;
+                throw new Error(`android device session ${this.sessionId} closed while launching app`);
+            }
+        }
+    }
+    #ensureOpen() {
+        if (this.#closed) {
+            throw new Error(`android device session ${this.sessionId} is closed`);
+        }
     }
 }
 class MobileAndroidSurfaceImpl {
     async connect(options = {}) {
-        const connectInfo = await invokeAndroidExpected("connect", {
-            command: "connect",
-            platform: "android",
-            device: options.device,
-            adb_endpoint: options.adbEndpoint,
-            preserve_app_state: options.preserveAppState ?? false,
-            timeout_ms: timeoutMsOf(options),
+        const runtime = await getRuntime();
+        const { stream, queue } = await createBrowserSessionHandle(runtime);
+        stream.write({
+            connectMobile: {
+                platform: 1,
+                device: options.device,
+                adbEndpoint: options.adbEndpoint,
+                preserveAppState: options.preserveAppState ?? false,
+                retryOptions: retryOptions(options.timeoutMs),
+            },
         });
-        return new MobileAndroidDeviceImpl(connectInfo);
+        while (true) {
+            const event = await queue.next();
+            if (event.mobileConnected?.initialAppSessionId) {
+                return new MobileAndroidDeviceImpl(event.mobileConnected.deviceSessionId ?? event.sessionId ?? "", event.sessionId ?? "", runtime, stream, queue, event.mobileConnected.initialAppSessionId);
+            }
+            if (event.error?.message) {
+                throw new Error(event.error.message);
+            }
+        }
     }
 }
 export const mobile = {

package/dist/page.js

@@ -19,8 +19,8 @@ export class PageImpl {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             navigate: {
                 url,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
@@ -60,8 +60,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             clickElement: {
                 cssSelector: transportSelector,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
@@ -90,8 +90,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             countElements: {
                 cssSelector: transportSelector,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
@@ -120,8 +120,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             highlightElements: {
                 cssSelector: transportSelector,
                 durationMs: options.durationMs,
@@ -151,8 +151,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             focusElement: {
                 cssSelector: transportSelector,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
@@ -180,8 +180,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             fillElement: {
                 cssSelector: transportSelector,
                 value,
@@ -211,8 +211,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             hoverElement: {
                 cssSelector: transportSelector,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
@@ -240,8 +240,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             pressKey: {
                 cssSelector: transportSelector,
                 key,
@@ -278,8 +278,8 @@ export class PageImpl {
         this.#ensureOpen(handle);
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             waitForSelector: {
                 cssSelector: transportSelector,
                 visible: options.visible,
@@ -310,8 +310,8 @@ export class PageImpl {
             return;
         }
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             close: {},
         });
         while (true) {
@@ -330,8 +330,8 @@ export class PageImpl {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             ping: {
                 message,
             },
@@ -365,16 +365,16 @@ export class PageImpl {
         const transportSelector = normalizeSelectorForTransport(selector);
         handle.stream.write(textContent
             ? {
-                browserSessionId: this.browserSessionId,
-                tabSessionId: this.sessionId,
+                surfaceSessionId: this.browserSessionId,
+                contextSessionId: this.sessionId,
                 getTextContent: {
                     cssSelector: transportSelector,
                     retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
                 },
             }
             : {
-                browserSessionId: this.browserSessionId,
-                tabSessionId: this.sessionId,
+                surfaceSessionId: this.browserSessionId,
+                contextSessionId: this.sessionId,
                 getInnerText: {
                     cssSelector: transportSelector,
                     retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,

package/dist/runtime.d.ts

@@ -1,13 +1,13 @@
 import { EventQueue } from "./types.js";
-import type { BrowserSessionEvent, BrowserSessionStream, Browser, BrowserKind, LaunchOptions, PageHandle, ResolveConfigOptions, ResolvedAllwrightConfig, RuntimeClient } from "./types.js";
+import type { SurfaceSessionEvent, SurfaceSessionStream, Browser, BrowserKind, LaunchOptions, PageHandle, ResolveConfigOptions, ResolvedAllwrightConfig, RuntimeClient } from "./types.js";
 export declare function setServerAddr(serverAddr: string): void;
 export declare function shutdown(): Promise<void>;
 export declare function ping(): Promise<string>;
 export declare function getRuntime(): Promise<RuntimeClient>;
 export declare function createPageHandle(runtime: RuntimeClient): Promise<PageHandle>;
 export declare function createBrowserSessionHandle(runtime: RuntimeClient): Promise<{
-    stream: BrowserSessionStream;
-    queue: EventQueue<BrowserSessionEvent>;
+    stream: SurfaceSessionStream;
+    queue: EventQueue<SurfaceSessionEvent>;
 }>;
 export declare function launchConfiguredBrowser(config: ResolvedAllwrightConfig, launchBrowserKind: (browserKind: BrowserKind, options?: LaunchOptions) => Promise<Browser>): Promise<Browser>;
 export declare function normalizeServerAddr(raw: string): string;

package/dist/runtime.js

@@ -43,7 +43,7 @@ export async function getRuntime() {
     return runtimePromise;
 }
 export async function createPageHandle(runtime) {
-    const stream = runtime.client.TabSession();
+    const stream = runtime.client.ContextSession();
     const queue = bindStreamQueue(stream);
     return {
         stream,
@@ -52,7 +52,7 @@ export async function createPageHandle(runtime) {
     };
 }
 export async function createBrowserSessionHandle(runtime) {
-    const stream = runtime.client.BrowserSession();
+    const stream = runtime.client.SurfaceSession();
     const queue = bindStreamQueue(stream);
     return { stream, queue };
 }

package/dist/types.d.ts

@@ -128,13 +128,13 @@ export interface MobileAndroidLaunchOptions {
     timeoutMs?: number;
 }
 export interface MobileAndroidLocator {
-    readonly page: MobileAndroidPage;
+    readonly page: MobileAndroidApp;
     readonly selector: string;
     click(options?: CommandOptions): Promise<ClickResult>;
     fill(value: string, options?: CommandOptions): Promise<FillResult>;
     locator(selector: string): MobileAndroidLocator;
 }
-export interface MobileAndroidPage {
+export interface MobileAndroidApp {
     readonly sessionId: string;
     locator(selector: string): MobileAndroidLocator;
     click(selector: string, options?: CommandOptions): Promise<ClickResult>;
@@ -142,9 +142,9 @@ export interface MobileAndroidPage {
 }
 export interface MobileAndroidDevice {
     readonly sessionId: string;
-    page(): MobileAndroidPage;
-    initialPage(): MobileAndroidPage;
-    launch(options?: MobileAndroidLaunchOptions): Promise<MobileAndroidPage>;
+    app(): MobileAndroidApp;
+    initialApp(): MobileAndroidApp;
+    launch(options?: MobileAndroidLaunchOptions): Promise<MobileAndroidApp>;
 }
 export interface MobileSurfaceNamespace {
     android: {
@@ -267,22 +267,41 @@ export interface ChromeLaunchedPayload {
     note?: string;
     cdpWebsocketUrl?: string;
     userDataDir?: string;
-    initialTabSessionId?: string;
+    initialPageSessionId?: string;
 }
 export interface BrowserLaunchedPayload {
     browserKind?: number;
     browser?: string;
     note?: string;
     userDataDir?: string;
-    initialTabSessionId?: string;
+    initialPageSessionId?: string;
 }
-export interface BrowserSessionEvent {
+export interface SurfaceSessionEvent {
     sessionId?: string;
     event?: string;
     chromeLaunched?: ChromeLaunchedPayload;
     browserLaunched?: BrowserLaunchedPayload;
-    tabOpened?: {
-        tabSessionId?: string;
+    mobileConnected?: {
+        platform?: number | string;
+        deviceName?: string;
+        note?: string;
+        deviceId?: string;
+        connectionKind?: number | string;
+        backend?: string;
+        deviceSessionId?: string;
+        initialAppSessionId?: string;
+        packageName?: string;
+        activityName?: string;
+    };
+    appLaunched?: {
+        appSessionId?: string;
+        note?: string;
+        packageName?: string;
+        activityName?: string;
+        webviewContext?: string;
+    };
+    contextOpened?: {
+        contextSessionId?: string;
         note?: string;
     };
     pong?: {
@@ -295,8 +314,8 @@ export interface BrowserSessionEvent {
         message?: string;
     };
 }
-export interface TabSessionEvent {
-    tabSessionId?: string;
+export interface ContextSessionEvent {
+    contextSessionId?: string;
     event?: string;
     attached?: {
         note?: string;
@@ -387,31 +406,53 @@ export interface LaunchBrowserRequest {
         };
     };
 }
-export interface OpenTabRequest {
-    openTab: {
+export interface OpenContextRequest {
+    openContext: {
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+export interface ConnectMobileRequest {
+    connectMobile: {
+        platform: number;
+        device?: string;
+        adbEndpoint?: string;
+        preserveAppState?: boolean;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+export interface LaunchAppRequest {
+    launchApp: {
+        apkPath?: string;
+        appId?: string;
+        launchActivity?: string;
+        stopBeforeLaunch?: boolean;
         retryOptions?: {
             timeoutMs?: number;
         };
     };
 }
-export interface BrowserPingRequest {
+export interface SurfacePingRequest {
     ping: {
         message: string;
     };
 }
-export interface CloseBrowserRequest {
+export interface CloseSurfaceRequest {
     close: Record<string, never>;
 }
-export interface TabPingRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+export interface ContextPingRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
     ping: {
         message: string;
     };
 }
 export interface NavigateRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     navigate: {
         url: string;
         retryOptions?: {
@@ -420,8 +461,8 @@ export interface NavigateRequest {
     };
 }
 export interface ClickRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     clickElement: {
         cssSelector: string;
         retryOptions?: {
@@ -430,8 +471,8 @@ export interface ClickRequest {
     };
 }
 export interface CountRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     countElements: {
         cssSelector: string;
         retryOptions?: {
@@ -440,8 +481,8 @@ export interface CountRequest {
     };
 }
 export interface HighlightRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     highlightElements: {
         cssSelector: string;
         durationMs?: number;
@@ -451,8 +492,8 @@ export interface HighlightRequest {
     };
 }
 export interface FocusRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     focusElement: {
         cssSelector: string;
         retryOptions?: {
@@ -461,8 +502,8 @@ export interface FocusRequest {
     };
 }
 export interface FillRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     fillElement: {
         cssSelector: string;
         value: string;
@@ -472,8 +513,8 @@ export interface FillRequest {
     };
 }
 export interface HoverRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     hoverElement: {
         cssSelector: string;
         retryOptions?: {
@@ -482,8 +523,8 @@ export interface HoverRequest {
     };
 }
 export interface PressRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     pressKey: {
         cssSelector: string;
         key: string;
@@ -494,8 +535,8 @@ export interface PressRequest {
     };
 }
 export interface TextContentRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     getTextContent: {
         cssSelector: string;
         retryOptions?: {
@@ -504,8 +545,8 @@ export interface TextContentRequest {
     };
 }
 export interface InnerTextRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     getInnerText: {
         cssSelector: string;
         retryOptions?: {
@@ -514,8 +555,8 @@ export interface InnerTextRequest {
     };
 }
 export interface WaitForSelectorRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     waitForSelector: {
         cssSelector: string;
         visible?: boolean;
@@ -524,19 +565,19 @@ export interface WaitForSelectorRequest {
         };
     };
 }
-export interface CloseTabRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+export interface CloseContextRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
     close: Record<string, never>;
 }
-export type BrowserSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenTabRequest | BrowserPingRequest | CloseBrowserRequest;
-export type TabSessionRequest = TabPingRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | CloseTabRequest;
-export type BrowserSessionStream = grpc.ClientDuplexStream<BrowserSessionRequest, BrowserSessionEvent>;
-export type PageSessionStream = grpc.ClientDuplexStream<TabSessionRequest, TabSessionEvent>;
+export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
+export type ContextSessionRequest = ContextPingRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | CloseContextRequest;
+export type SurfaceSessionStream = grpc.ClientDuplexStream<SurfaceSessionRequest, SurfaceSessionEvent>;
+export type ContextSessionStream = grpc.ClientDuplexStream<ContextSessionRequest, ContextSessionEvent>;
 export interface EngineServiceClientShape {
     Ping(request: Record<string, never>, callback: (error: grpc.ServiceError | null, response: PingResponse) => void): void;
-    BrowserSession(): BrowserSessionStream;
-    TabSession(): PageSessionStream;
+    SurfaceSession(): SurfaceSessionStream;
+    ContextSession(): ContextSessionStream;
     close(): void;
 }
 export interface EngineProtoRoot {
@@ -553,14 +594,14 @@ export interface RuntimeClient {
 }
 export interface BrowserLaunchState {
     runtime: RuntimeClient;
-    stream: BrowserSessionStream;
-    queue: EventQueue<BrowserSessionEvent>;
+    stream: SurfaceSessionStream;
+    queue: EventQueue<SurfaceSessionEvent>;
     sessionId: string;
     launched: BrowserLaunchedPayload;
 }
 export interface PageHandle {
-    stream: PageSessionStream;
-    queue: EventQueue<TabSessionEvent>;
+    stream: ContextSessionStream;
+    queue: EventQueue<ContextSessionEvent>;
     closed: boolean;
 }
 export declare class EventQueue<T> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/core",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "example:playground": "bun run examples/playground.ts",
+    "example:web": "bun run examples/web-basic.ts",
+    "example:android": "bun run examples/android-basic.ts",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {

package/proto/core/v1/browser.proto

@@ -4,19 +4,22 @@ package allwright.engine.v1;
 option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
 
 import "core/v1/common.proto";
+import "surfaces/mobile/v1/mobile.proto";
 import "surfaces/web/v1/web.proto";
 
-message BrowserSessionCommand {
+message SurfaceSessionCommand {
   oneof command {
     LaunchChromeCommand launch_chrome = 1;
-    OpenTabCommand open_tab = 2;
+    OpenContextCommand open_context = 2;
     SessionPingCommand ping = 3;
-    CloseBrowserSessionCommand close = 4;
+    CloseSurfaceSessionCommand close = 4;
     LaunchBrowserCommand launch_browser = 5;
+    ConnectMobileCommand connect_mobile = 6;
+    LaunchAppCommand launch_app = 7;
   }
 }
 
-message OpenTabCommand {
+message OpenContextCommand {
   optional CommandRetryOptions retry_options = 1;
 }
 
@@ -24,23 +27,25 @@ message SessionPingCommand {
   string message = 1;
 }
 
-message CloseBrowserSessionCommand {}
+message CloseSurfaceSessionCommand {}
 
-message BrowserSessionEvent {
+message SurfaceSessionEvent {
   string session_id = 1;
 
   oneof event {
     ChromeLaunchedEvent chrome_launched = 2;
-    TabOpenedEvent tab_opened = 3;
+    ContextOpenedEvent context_opened = 3;
     SessionPongEvent pong = 4;
-    BrowserSessionClosedEvent closed = 5;
-    BrowserSessionErrorEvent error = 6;
+    SurfaceSessionClosedEvent closed = 5;
+    SurfaceSessionErrorEvent error = 6;
     BrowserLaunchedEvent browser_launched = 7;
+    MobileConnectedEvent mobile_connected = 8;
+    AppLaunchedEvent app_launched = 9;
   }
 }
 
-message TabOpenedEvent {
-  string tab_session_id = 1;
+message ContextOpenedEvent {
+  string context_session_id = 1;
   string note = 2;
 }
 
@@ -48,10 +53,10 @@ message SessionPongEvent {
   string message = 1;
 }
 
-message BrowserSessionClosedEvent {
+message SurfaceSessionClosedEvent {
   string reason = 1;
 }
 
-message BrowserSessionErrorEvent {
+message SurfaceSessionErrorEvent {
   string message = 1;
 }

package/proto/core/v1/tab.proto

@@ -5,14 +5,14 @@ option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
 
 import "surfaces/web/v1/web.proto";
 
-message TabSessionCommand {
-  string browser_session_id = 1;
-  string tab_session_id = 2;
+message ContextSessionCommand {
+  string surface_session_id = 1;
+  string context_session_id = 2;
 
   oneof command {
-    TabSessionPingCommand ping = 3;
-    CloseTabSessionCommand close = 4;
-    NavigateTabCommand navigate = 5;
+    ContextSessionPingCommand ping = 3;
+    CloseContextSessionCommand close = 4;
+    NavigatePageCommand navigate = 5;
     ClickElementCommand click_element = 6;
     CountElementsCommand count_elements = 7;
     HighlightElementsCommand highlight_elements = 8;
@@ -26,21 +26,21 @@ message TabSessionCommand {
   }
 }
 
-message TabSessionPingCommand {
+message ContextSessionPingCommand {
   string message = 1;
 }
 
-message CloseTabSessionCommand {}
+message CloseContextSessionCommand {}
 
-message TabSessionEvent {
-  string tab_session_id = 1;
+message ContextSessionEvent {
+  string context_session_id = 1;
 
   oneof event {
-    TabSessionAttachedEvent attached = 2;
-    TabSessionPongEvent pong = 3;
-    TabSessionClosedEvent closed = 4;
-    TabSessionErrorEvent error = 5;
-    TabNavigatedEvent navigated = 6;
+    ContextSessionAttachedEvent attached = 2;
+    ContextSessionPongEvent pong = 3;
+    ContextSessionClosedEvent closed = 4;
+    ContextSessionErrorEvent error = 5;
+    PageNavigatedEvent navigated = 6;
     ChromiumBidiInjectionEvent chromium_bidi_injection = 7;
     ElementClickedEvent element_clicked = 8;
     ElementCountedEvent element_counted = 9;
@@ -55,18 +55,18 @@ message TabSessionEvent {
   }
 }
 
-message TabSessionAttachedEvent {
+message ContextSessionAttachedEvent {
   string note = 1;
 }
 
-message TabSessionPongEvent {
+message ContextSessionPongEvent {
   string message = 1;
 }
 
-message TabSessionClosedEvent {
+message ContextSessionClosedEvent {
   string reason = 1;
 }
 
-message TabSessionErrorEvent {
+message ContextSessionErrorEvent {
   string message = 1;
 }

package/proto/engine/v1/engine.proto

@@ -9,6 +9,6 @@ import "core/v1/tab.proto";
 
 service EngineService {
   rpc Ping(PingRequest) returns (PingResponse);
-  rpc BrowserSession(stream BrowserSessionCommand) returns (stream BrowserSessionEvent);
-  rpc TabSession(stream TabSessionCommand) returns (stream TabSessionEvent);
+  rpc SurfaceSession(stream SurfaceSessionCommand) returns (stream SurfaceSessionEvent);
+  rpc ContextSession(stream ContextSessionCommand) returns (stream ContextSessionEvent);
 }

package/proto/surfaces/mobile/v1/mobile.proto

@@ -0,0 +1,56 @@
+syntax = "proto3";
+
+package allwright.engine.v1;
+option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+
+import "core/v1/common.proto";
+
+enum MobilePlatform {
+  MOBILE_PLATFORM_UNSPECIFIED = 0;
+  MOBILE_PLATFORM_ANDROID = 1;
+  MOBILE_PLATFORM_IOS = 2;
+}
+
+enum DeviceConnectionKind {
+  DEVICE_CONNECTION_KIND_UNSPECIFIED = 0;
+  DEVICE_CONNECTION_KIND_USB = 1;
+  DEVICE_CONNECTION_KIND_EMULATOR = 2;
+  DEVICE_CONNECTION_KIND_REMOTE_ADB = 3;
+}
+
+message ConnectMobileCommand {
+  MobilePlatform platform = 1;
+  optional string device = 2;
+  optional string adb_endpoint = 3;
+  bool preserve_app_state = 4;
+  optional CommandRetryOptions retry_options = 5;
+}
+
+message MobileConnectedEvent {
+  MobilePlatform platform = 1;
+  string device_name = 2;
+  string note = 3;
+  string device_id = 4;
+  DeviceConnectionKind connection_kind = 5;
+  string backend = 6;
+  string device_session_id = 7;
+  string initial_app_session_id = 8;
+  optional string package_name = 9;
+  optional string activity_name = 10;
+}
+
+message LaunchAppCommand {
+  optional string apk_path = 1;
+  optional string app_id = 2;
+  optional string launch_activity = 3;
+  bool stop_before_launch = 4;
+  optional CommandRetryOptions retry_options = 5;
+}
+
+message AppLaunchedEvent {
+  string app_session_id = 1;
+  string note = 2;
+  optional string package_name = 3;
+  optional string activity_name = 4;
+  optional string webview_context = 5;
+}

package/proto/surfaces/web/v1/web.proto

@@ -22,7 +22,7 @@ message BrowserLaunchedEvent {
   string browser = 2;
   string note = 3;
   string user_data_dir = 4;
-  string initial_tab_session_id = 5;
+  string initial_page_session_id = 5;
 }
 
 message LaunchChromeCommand {
@@ -35,10 +35,10 @@ message ChromeLaunchedEvent {
   string note = 2;
   string cdp_websocket_url = 3;
   string user_data_dir = 4;
-  string initial_tab_session_id = 5;
+  string initial_page_session_id = 5;
 }
 
-message NavigateTabCommand {
+message NavigatePageCommand {
   string url = 1;
   optional CommandRetryOptions retry_options = 2;
 }
@@ -98,7 +98,7 @@ message WaitForSelectorCommand {
   optional CommandRetryOptions retry_options = 3;
 }
 
-message TabNavigatedEvent {
+message PageNavigatedEvent {
   string url = 1;
   string note = 2;
 }