@allwright.dev/core 0.0.52 → 0.0.54

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,
@@ -304,21 +304,48 @@ export class PageImpl {
             }
         }
     }
+    async screenshot(options = {}) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
+            screenshot: {
+                retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
+            },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.screenshotCaptured?.pngData) {
+                return {
+                    pngData: event.screenshotCaptured.pngData,
+                    note: event.screenshotCaptured.note ?? "",
+                };
+            }
+            if (event.error?.message) {
+                throw formatActionError("screenshot", event.error.message);
+            }
+            if (event.closed) {
+                handle.closed = true;
+                throw new Error(`page session ${this.sessionId} closed while waiting for screenshot`);
+            }
+        }
+    }
     async close() {
         const handle = await this.#getHandle();
         if (handle.closed) {
             return;
         }
         handle.stream.write({
-            browserSessionId: this.browserSessionId,
-            tabSessionId: this.sessionId,
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
             close: {},
         });
         while (true) {
             const event = await handle.queue.next();
             if (event.closed) {
                 handle.closed = true;
-                handle.stream.end();
+                this.dispose();
                 return;
             }
             if (event.error?.message) {
@@ -330,8 +357,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 +392,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,
@@ -416,4 +443,28 @@ export class PageImpl {
         }
         return this.#handlePromise;
     }
+    dispose() {
+        const handlePromise = this.#handlePromise;
+        if (!handlePromise) {
+            return;
+        }
+        void handlePromise.then((handle) => {
+            if (handle.closed) {
+                return;
+            }
+            handle.closed = true;
+            try {
+                handle.stream.end();
+            }
+            catch {
+                // Best-effort local teardown during page disposal.
+            }
+            try {
+                handle.stream.cancel();
+            }
+            catch {
+                // grpc-js may reject cancel/end ordering depending on stream state.
+            }
+        });
+    }
 }

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

@@ -20,6 +20,10 @@ export async function shutdown() {
         return;
     }
     const runtime = await runtimePromise;
+    for (const stream of runtime.openStreams ?? []) {
+        closeTrackedStream(stream);
+        runtime.unregisterStream(stream);
+    }
     runtime.client.close();
     runtimePromise = null;
     await shutdownManagedServer();
@@ -43,7 +47,12 @@ export async function getRuntime() {
     return runtimePromise;
 }
 export async function createPageHandle(runtime) {
-    const stream = runtime.client.TabSession();
+    const stream = runtime.client.ContextSession();
+    runtime.registerStream(stream);
+    const unregister = () => runtime.unregisterStream(stream);
+    stream.on("close", unregister);
+    stream.on("end", unregister);
+    stream.on("error", unregister);
     const queue = bindStreamQueue(stream);
     return {
         stream,
@@ -52,7 +61,12 @@ export async function createPageHandle(runtime) {
     };
 }
 export async function createBrowserSessionHandle(runtime) {
-    const stream = runtime.client.BrowserSession();
+    const stream = runtime.client.SurfaceSession();
+    runtime.registerStream(stream);
+    const unregister = () => runtime.unregisterStream(stream);
+    stream.on("close", unregister);
+    stream.on("end", unregister);
+    stream.on("error", unregister);
     const queue = bindStreamQueue(stream);
     return { stream, queue };
 }
@@ -93,7 +107,17 @@ async function createRuntime() {
     const proto = grpc.loadPackageDefinition(loaded);
     const ClientCtor = proto.allwright.engine.v1.EngineService;
     const client = new ClientCtor(resolvedServerAddr, grpc.credentials.createInsecure());
-    return { client };
+    const openStreams = new Set();
+    return {
+        client,
+        openStreams,
+        registerStream(stream) {
+            openStreams.add(stream);
+        },
+        unregisterStream(stream) {
+            openStreams.delete(stream);
+        },
+    };
 }
 function configuredServerAddr() {
     if (serverAddrOverride) {
@@ -114,3 +138,17 @@ function bindStreamQueue(stream) {
     });
     return queue;
 }
+function closeTrackedStream(stream) {
+    try {
+        stream.end();
+    }
+    catch {
+        // Some grpc-js stream states reject end() during teardown; keep going.
+    }
+    try {
+        stream.cancel();
+    }
+    catch {
+        // Best-effort shutdown so dangling streams do not keep the process alive.
+    }
+}

package/dist/types.d.ts

@@ -67,6 +67,10 @@ export interface WaitForSelectorResult {
     visible: boolean;
     note: string;
 }
+export interface ScreenshotResult {
+    pngData: Uint8Array;
+    note: string;
+}
 export interface BrowserInfo {
     sessionId: string;
     browserName: string;
@@ -110,6 +114,7 @@ export interface Page extends PageInfo {
     textContent(selector: string, options?: CommandOptions): Promise<TextResult>;
     innerText(selector: string, options?: CommandOptions): Promise<TextResult>;
     waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
+    screenshot(options?: CommandOptions): Promise<ScreenshotResult>;
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     pageInfo(): PageInfo;
@@ -128,23 +133,24 @@ 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>;
     fill(selector: string, value: string, options?: CommandOptions): Promise<FillResult>;
+    screenshot(options?: CommandOptions): Promise<ScreenshotResult>;
 }
 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 +273,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 +320,8 @@ export interface BrowserSessionEvent {
         message?: string;
     };
 }
-export interface TabSessionEvent {
-    tabSessionId?: string;
+export interface ContextSessionEvent {
+    contextSessionId?: string;
     event?: string;
     attached?: {
         note?: string;
@@ -369,6 +394,10 @@ export interface TabSessionEvent {
         visible?: boolean;
         note?: string;
     };
+    screenshotCaptured?: {
+        pngData?: Uint8Array;
+        note?: string;
+    };
 }
 export interface LaunchChromeRequest {
     launchChrome: {
@@ -387,31 +416,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 BrowserPingRequest {
+export interface LaunchAppRequest {
+    launchApp: {
+        apkPath?: string;
+        appId?: string;
+        launchActivity?: string;
+        stopBeforeLaunch?: boolean;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+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 +471,8 @@ export interface NavigateRequest {
     };
 }
 export interface ClickRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     clickElement: {
         cssSelector: string;
         retryOptions?: {
@@ -430,8 +481,8 @@ export interface ClickRequest {
     };
 }
 export interface CountRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     countElements: {
         cssSelector: string;
         retryOptions?: {
@@ -440,8 +491,8 @@ export interface CountRequest {
     };
 }
 export interface HighlightRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     highlightElements: {
         cssSelector: string;
         durationMs?: number;
@@ -451,8 +502,8 @@ export interface HighlightRequest {
     };
 }
 export interface FocusRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     focusElement: {
         cssSelector: string;
         retryOptions?: {
@@ -461,8 +512,8 @@ export interface FocusRequest {
     };
 }
 export interface FillRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     fillElement: {
         cssSelector: string;
         value: string;
@@ -472,8 +523,8 @@ export interface FillRequest {
     };
 }
 export interface HoverRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     hoverElement: {
         cssSelector: string;
         retryOptions?: {
@@ -482,8 +533,8 @@ export interface HoverRequest {
     };
 }
 export interface PressRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     pressKey: {
         cssSelector: string;
         key: string;
@@ -494,8 +545,8 @@ export interface PressRequest {
     };
 }
 export interface TextContentRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     getTextContent: {
         cssSelector: string;
         retryOptions?: {
@@ -504,8 +555,8 @@ export interface TextContentRequest {
     };
 }
 export interface InnerTextRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     getInnerText: {
         cssSelector: string;
         retryOptions?: {
@@ -514,8 +565,8 @@ export interface InnerTextRequest {
     };
 }
 export interface WaitForSelectorRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+    surfaceSessionId: string;
+    contextSessionId: string;
     waitForSelector: {
         cssSelector: string;
         visible?: boolean;
@@ -524,19 +575,28 @@ export interface WaitForSelectorRequest {
         };
     };
 }
-export interface CloseTabRequest {
-    browserSessionId: string;
-    tabSessionId: string;
+export interface ScreenshotRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    screenshot: {
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
+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 | ScreenshotRequest | 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 {
@@ -550,17 +610,20 @@ export interface EngineProtoRoot {
 }
 export interface RuntimeClient {
     client: EngineServiceClientShape;
+    openStreams: Set<SurfaceSessionStream | ContextSessionStream>;
+    registerStream(stream: SurfaceSessionStream | ContextSessionStream): void;
+    unregisterStream(stream: SurfaceSessionStream | ContextSessionStream): void;
 }
 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.52",
+  "version": "0.0.54",
   "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": {