@allwright.dev/core 0.2.0 → 0.2.1

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.2.0";
+const DEFAULT_RELEASE_VERSION = "0.2.1";
 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

@@ -1,2 +1,17 @@
-import type { DesktopSurfaceNamespace } from "./types.js";
+import { NativeAppImpl } from "./mobile.js";
+import type { DesktopApp, DesktopSurfaceNamespace, Hook, HookType, RuntimeClient } from "./types.js";
+export declare class DesktopWindowImpl extends NativeAppImpl {
+    readonly windowId: string;
+    readonly title: string;
+    readonly isMain: boolean;
+    constructor(runtime: RuntimeClient, surfaceSessionId: string, sessionId: string, windowId: string, title: string, isMain: boolean);
+    close(): Promise<void>;
+}
+export declare class DesktopAppImpl extends NativeAppImpl implements DesktopApp {
+    windows(): Promise<DesktopWindowImpl[]>;
+    mainWindow(): Promise<DesktopWindowImpl>;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
+    private waitForWindow;
+    private windowFromResult;
+}
 export declare const desktop: DesktopSurfaceNamespace;

package/dist/desktop.js

@@ -3,6 +3,109 @@ import { NativeAppImpl } from "./mobile.js";
 function retryOptions(timeoutMs) {
     return timeoutMs === undefined ? undefined : { timeoutMs };
 }
+export class DesktopWindowImpl extends NativeAppImpl {
+    windowId;
+    title;
+    isMain;
+    constructor(runtime, surfaceSessionId, sessionId, windowId, title, isMain) {
+        super(runtime, surfaceSessionId, sessionId);
+        this.windowId = windowId;
+        this.title = title;
+        this.isMain = isMain;
+    }
+    async close() {
+        const handle = await this.contextHandle();
+        this.assertContextOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.nativeSurfaceSessionId,
+            contextSessionId: this.sessionId,
+            closeDesktopWindow: {},
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.desktopWindowClosed?.windowId === this.windowId)
+                return;
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+}
+export class DesktopAppImpl extends NativeAppImpl {
+    async windows() {
+        const handle = await this.contextHandle();
+        this.assertContextOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.nativeSurfaceSessionId,
+            contextSessionId: this.sessionId,
+            listDesktopWindows: {},
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.desktopWindowsResolved) {
+                return (event.desktopWindowsResolved.windows ?? []).map((window) => this.windowFromResult(window));
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async mainWindow() {
+        const windows = await this.windows();
+        const main = windows.find((window) => window.isMain);
+        if (!main)
+            throw new Error("desktop application does not currently expose a main window");
+        return main;
+    }
+    async registerHook(type) {
+        if (type.name !== "window")
+            return super.registerHook(type);
+        const handle = await this.contextHandle();
+        this.assertContextOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.nativeSurfaceSessionId,
+            contextSessionId: this.sessionId,
+            registerHook: { desktopWindow: {} },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.hookRegistered?.hookId) {
+                const hookId = event.hookRegistered.hookId;
+                return {
+                    id: hookId,
+                    type,
+                    wait: (options = {}) => this.waitForWindow(hookId, options),
+                };
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    async waitForWindow(hookId, options) {
+        const handle = await this.contextHandle();
+        this.assertContextOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.nativeSurfaceSessionId,
+            contextSessionId: this.sessionId,
+            waitForHook: { hookId, retryOptions: retryOptions(options.timeoutMs) },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.hookCompleted?.hookId === hookId) {
+                const window = event.hookCompleted.desktopWindow?.window;
+                if (!window)
+                    throw new Error("desktop window hook returned an invalid result");
+                return this.windowFromResult(window);
+            }
+            if (event.error?.message)
+                throw new Error(event.error.message);
+        }
+    }
+    windowFromResult(window) {
+        if (!window.contextSessionId || !window.windowId) {
+            throw new Error("desktop window result is missing its context or window id");
+        }
+        return new DesktopWindowImpl(this.runtimeClient, this.nativeSurfaceSessionId, window.contextSessionId, window.windowId, window.title ?? "", window.isMain ?? false);
+    }
+}
 class DesktopMacImpl {
     sessionId;
     surfaceSessionId;
@@ -19,7 +122,7 @@ class DesktopMacImpl {
         this.stream = stream;
         this.queue = queue;
         this.platformLabel = platformLabel;
-        this.#currentApp = new NativeAppImpl(runtime, surfaceSessionId, initialAppSessionId);
+        this.#currentApp = new DesktopAppImpl(runtime, surfaceSessionId, initialAppSessionId);
     }
     app() {
         return this.#currentApp;
@@ -37,7 +140,7 @@ class DesktopMacImpl {
         while (true) {
             const event = await this.queue.next();
             if (event.desktopAppLaunched?.appSessionId) {
-                this.#currentApp = new NativeAppImpl(this.runtime, this.surfaceSessionId, event.desktopAppLaunched.appSessionId);
+                this.#currentApp = new DesktopAppImpl(this.runtime, this.surfaceSessionId, event.desktopAppLaunched.appSessionId);
                 return this.#currentApp;
             }
             if (event.error?.message)

package/dist/index.d.ts

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

package/dist/index.js

@@ -13,6 +13,7 @@ export const hooks = {
     newPage: Object.freeze({ name: "newPage" }),
     fileChooser: Object.freeze({ name: "fileChooser" }),
     download: Object.freeze({ name: "download" }),
+    window: Object.freeze({ name: "window" }),
 };
 export { mobile };
 export { desktop };

package/dist/mobile.d.ts

@@ -1,9 +1,13 @@
 import { type RoleOptions, type TextMatcher, type TextOptions } from "./web-locators.js";
-import type { AccessibilitySnapshotOptions, BoundingBox, CommandOptions, Hook, HookType, MobileSurfaceNamespace, NativeApp, NativeAppLocator, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
+import type { AccessibilitySnapshotOptions, BoundingBox, CommandOptions, Hook, HookType, MobileSurfaceNamespace, NativeApp, NativeAppLocator, PageHandle, PressOptions, RuntimeClient, ScreenshotOptions, WaitForSelectorOptions } from "./types.js";
 export declare class NativeAppImpl implements NativeApp {
     #private;
     readonly sessionId: string;
     constructor(runtime: RuntimeClient, surfaceSessionId: string, sessionId: string);
+    protected get runtimeClient(): RuntimeClient;
+    protected get nativeSurfaceSessionId(): string;
+    protected contextHandle(): Promise<PageHandle>;
+    protected assertContextOpen(handle: PageHandle): void;
     locator(selector: string): NativeAppLocator;
     getByRole(role: string, options?: RoleOptions): NativeAppLocator;
     getByText(text: TextMatcher, options?: TextOptions): NativeAppLocator;

package/dist/mobile.js

@@ -17,6 +17,10 @@ export class NativeAppImpl {
         this.#runtime = runtime;
         this.#surfaceSessionId = surfaceSessionId;
     }
+    get runtimeClient() { return this.#runtime; }
+    get nativeSurfaceSessionId() { return this.#surfaceSessionId; }
+    contextHandle() { return this.#getHandle(); }
+    assertContextOpen(handle) { this.#ensureOpen(handle); }
     locator(selector) {
         return new NativeAppLocatorImpl(this, normalizeMobileSelectorForTransport(selector));
     }

package/dist/types.d.ts

@@ -235,6 +235,16 @@ export interface NativeApp {
     screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
 }
+export interface DesktopWindow extends NativeApp {
+    readonly windowId: string;
+    readonly title: string;
+    readonly isMain: boolean;
+    close(): Promise<void>;
+}
+export interface DesktopApp extends NativeApp {
+    windows(): Promise<DesktopWindow[]>;
+    mainWindow(): Promise<DesktopWindow>;
+}
 export type MobileAndroidLocator = NativeAppLocator;
 export type MobileAndroidApp = NativeApp;
 export interface MobileAndroidDevice {
@@ -280,7 +290,8 @@ export interface DesktopMacLaunchOptions {
     terminateRunning?: boolean;
     timeoutMs?: number;
 }
-export type DesktopMacApp = NativeApp;
+export type DesktopMacApp = DesktopApp;
+export type DesktopMacWindow = DesktopWindow;
 export type DesktopMacLocator = NativeAppLocator;
 export interface DesktopMacDesktop {
     readonly sessionId: string;
@@ -289,7 +300,8 @@ export interface DesktopMacDesktop {
 }
 export type DesktopWindowsConnectOptions = DesktopMacConnectOptions;
 export type DesktopWindowsLaunchOptions = DesktopMacLaunchOptions;
-export type DesktopWindowsApp = NativeApp;
+export type DesktopWindowsApp = DesktopApp;
+export type DesktopWindowsWindow = DesktopWindow;
 export type DesktopWindowsLocator = NativeAppLocator;
 export interface DesktopWindowsDesktop {
     readonly sessionId: string;
@@ -556,6 +568,25 @@ export interface ContextSessionEvent {
             suggestedFilename?: string;
             note?: string;
         };
+        desktopWindow?: {
+            window?: {
+                contextSessionId?: string;
+                windowId?: string;
+                title?: string;
+                isMain?: boolean;
+            };
+        };
+    };
+    desktopWindowsResolved?: {
+        windows?: Array<{
+            contextSessionId?: string;
+            windowId?: string;
+            title?: string;
+            isMain?: boolean;
+        }>;
+    };
+    desktopWindowClosed?: {
+        windowId?: string;
     };
     fileChooserFilesSet?: {
         fileChooserId?: string;
@@ -703,6 +734,7 @@ export interface RegisterHookRequest {
         download?: Record<string, never>;
         mobileFileChooser?: Record<string, never>;
         mobileDownload?: Record<string, never>;
+        desktopWindow?: Record<string, never>;
     };
 }
 export interface SaveDownloadRequest {
@@ -975,6 +1007,16 @@ export interface CloseContextRequest {
     contextSessionId: string;
     close: Record<string, never>;
 }
+export interface ListDesktopWindowsRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    listDesktopWindows: Record<string, never>;
+}
+export interface CloseDesktopWindowRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    closeDesktopWindow: Record<string, never>;
+}
 export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | ConnectDesktopRequest | LaunchDesktopAppRequest | SurfacePingRequest | CloseSurfaceRequest;
 export type ContextSessionRequest = {
     surfaceSessionId: string;
@@ -996,7 +1038,7 @@ export type ContextSessionRequest = {
             timeoutMs: number;
         };
     };
-} | ContextPingRequest | RegisterHookRequest | WaitForHookRequest | HandleDialogRequest | SetFileChooserFilesRequest | SaveDownloadRequest | UploadFileChunkRequest | ReadFileChunkRequest | SetMobileFileChooserFilesRequest | SaveMobileDownloadRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | AccessibilitySnapshotRequest | ScreenshotRequest | CloseContextRequest;
+} | ContextPingRequest | RegisterHookRequest | WaitForHookRequest | HandleDialogRequest | SetFileChooserFilesRequest | SaveDownloadRequest | UploadFileChunkRequest | ReadFileChunkRequest | SetMobileFileChooserFilesRequest | SaveMobileDownloadRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | AccessibilitySnapshotRequest | ScreenshotRequest | ListDesktopWindowsRequest | CloseDesktopWindowRequest | CloseContextRequest;
 export type SurfaceSessionStream = grpc.ClientDuplexStream<SurfaceSessionRequest, SurfaceSessionEvent>;
 export type ContextSessionStream = grpc.ClientDuplexStream<ContextSessionRequest, ContextSessionEvent>;
 export interface EngineServiceClientShape {

package/package.json

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

package/proto/core/v1/context.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";
 
@@ -40,6 +41,8 @@ message ContextSessionCommand {
     ResolveFrameCommand resolve_frame = 26;
     CaptureCommand capture = 27;
     HandleDialogCommand handle_dialog = 28;
+    ListDesktopWindowsCommand list_desktop_windows = 29;
+    CloseDesktopWindowCommand close_desktop_window = 30;
   }
 }
 
@@ -82,6 +85,8 @@ message ContextSessionEvent {
     FrameResolvedEvent frame_resolved = 28;
     CaptureResolvedEvent capture_resolved = 29;
     DialogHandledEvent dialog_handled = 30;
+    DesktopWindowsResolvedEvent desktop_windows_resolved = 31;
+    DesktopWindowClosedEvent desktop_window_closed = 32;
   }
 }
 
@@ -109,6 +114,7 @@ message RegisterHookCommand {
     RegisterMobileFileChooserHook mobile_file_chooser = 4;
     RegisterMobileDownloadHook mobile_download = 5;
     RegisterDialogHook dialog = 6;
+    RegisterDesktopWindowHook desktop_window = 7;
   }
 }
 
@@ -131,6 +137,7 @@ message HookCompletedEvent {
     MobileFileChooserHookResult mobile_file_chooser = 5;
     MobileDownloadHookResult mobile_download = 6;
     DialogHookResult dialog = 7;
+    DesktopWindowHookResult desktop_window = 8;
   }
 }
 

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

@@ -38,3 +38,26 @@ message DesktopAppLaunchedEvent {
   string app_id = 2;
   string note = 3;
 }
+
+message ListDesktopWindowsCommand {}
+message CloseDesktopWindowCommand {}
+message RegisterDesktopWindowHook {}
+
+message DesktopWindowInfo {
+  string context_session_id = 1;
+  string window_id = 2;
+  string title = 3;
+  bool is_main = 4;
+}
+
+message DesktopWindowsResolvedEvent {
+  repeated DesktopWindowInfo windows = 1;
+}
+
+message DesktopWindowClosedEvent {
+  string window_id = 1;
+}
+
+message DesktopWindowHookResult {
+  DesktopWindowInfo window = 1;
+}