@allwright.dev/core 0.1.4 → 0.1.6

package/README.md

@@ -20,6 +20,19 @@ await page.click(
 await browser.close();
 ```
 
+Register a typed hook before an action that opens a tab, then wait for its
+typed result afterward:
+
+```ts
+import { firefox, hooks } from "@allwright.dev/core";
+
+const browser = await firefox.launch();
+const page = browser.page();
+const hook = await page.registerHook(hooks.newPage);
+await page.click("a[target=_blank]");
+const newPage = await hook.wait();
+```
+
 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`.

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.4";
+const DEFAULT_RELEASE_VERSION = "0.1.6";
 const STARTUP_TIMEOUT_MS = 20_000;
 const PING_TIMEOUT_MS = 1_000;
 const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));

package/dist/browser.js

@@ -129,6 +129,7 @@ export class BrowserImpl {
             runtime: this.#runtime,
             browserSessionId: this.sessionId,
             sessionId,
+            createPage: (newSessionId) => this.#createPage(newSessionId),
         });
         this.#pages.set(sessionId, page);
         return page;

package/dist/index.d.ts

@@ -3,11 +3,14 @@ import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
 import { mobile } from "./mobile.js";
 import { PageImpl } from "./page.js";
 import { setServerAddr, shutdown } from "./runtime.js";
-import type { Browser, BrowserKind, BrowserType, LaunchOptions, Page, ResolveConfigOptions, ResolvedAllwrightConfig } from "./types.js";
+import type { Browser, BrowserKind, BrowserType, LaunchOptions, Page, HookType, ResolveConfigOptions, ResolvedAllwrightConfig } from "./types.js";
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
-export type { AccessibilitySnapshotOptions, 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, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult, } from "./types.js";
+export type { AccessibilitySnapshotOptions, AllwrightConfig, Browser, BrowserInfo, BrowserKind, BrowserType, Hook, HookType, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, LaunchOptions, MobileAndroidConnectOptions, MobileAndroidDevice, MobileAndroidLaunchOptions, MobileAndroidLocator, MobileAndroidApp, Locator, LocatorInfo, MobileSurfaceNamespace, 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: {
+    newPage: HookType<Page>;
+};
 export { mobile };
 export type Tab = Page;
 export declare function ping(): Promise<string>;

package/dist/index.js

@@ -7,6 +7,9 @@ import { createBrowserSessionHandle, getRuntime, launchConfiguredBrowser as laun
 export { findConfigFile, loadConfigFile, resolveConfig, setServerAddr, shutdown };
 export const chromium = new BrowserTypeImpl("chromium");
 export const firefox = new BrowserTypeImpl("firefox");
+export const hooks = {
+    newPage: Object.freeze({ name: "newPage" }),
+};
 export { mobile };
 export async function ping() {
     return runtimePing();

package/dist/page.d.ts

@@ -1,12 +1,14 @@
 import { WebLocatorBuilders, type LocatorFilterOptions } from "./web-locators.js";
-import type { AccessibilitySnapshotOptions, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, Locator, NavigateResult, Page, PageInfo, PressOptions, PressResult, RuntimeClient, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult } from "./types.js";
+import type { AccessibilitySnapshotOptions, ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, Hook, HookType, Locator, NavigateResult, Page, PageInfo, PressOptions, PressResult, RuntimeClient, ScreenshotOptions, ScreenshotResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult } from "./types.js";
 export declare class PageImpl extends WebLocatorBuilders implements Page {
     #private;
     constructor(input: PageInfo & {
         runtime: RuntimeClient;
+        createPage?: (sessionId: string) => Page;
     });
     readonly sessionId: string;
     readonly browserSessionId: string;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
     locator(selector: string, options?: LocatorFilterOptions): Locator;
     goto(url: string, options?: CommandOptions): Promise<NavigateResult>;
     click(selector: string, options?: CommandOptions): Promise<ClickResult>;

package/dist/page.js

@@ -7,14 +7,71 @@ import { createPageHandle } from "./runtime.js";
 export class PageImpl extends WebLocatorBuilders {
     #runtime;
     #handlePromise = null;
+    #createPage;
     constructor(input) {
         super();
         this.#runtime = input.runtime;
         this.sessionId = input.sessionId;
         this.browserSessionId = input.browserSessionId;
+        this.#createPage = input.createPage ?? ((sessionId) => new PageImpl({
+            runtime: this.#runtime,
+            browserSessionId: this.browserSessionId,
+            sessionId,
+            createPage: this.#createPage,
+        }));
     }
     sessionId;
     browserSessionId;
+    async registerHook(type) {
+        if (type.name !== "newPage") {
+            throw formatActionError("register hook", `unsupported hook type: ${type.name}`);
+        }
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
+            registerHook: { newPage: {} },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.hookRegistered?.hookId) {
+                const hookId = event.hookRegistered.hookId;
+                return {
+                    id: hookId,
+                    type,
+                    wait: (options = {}) => this.#waitForHook(hookId, type, options),
+                };
+            }
+            if (event.error?.message) {
+                throw formatActionError(`register ${type.name} hook`, event.error.message);
+            }
+        }
+    }
+    async #waitForHook(hookId, type, options) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.browserSessionId,
+            contextSessionId: this.sessionId,
+            waitForHook: {
+                hookId,
+                retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
+            },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.hookCompleted?.hookId === hookId) {
+                if (type.name === "newPage" && event.hookCompleted.newPage?.contextSessionId) {
+                    return this.#createPage(event.hookCompleted.newPage.contextSessionId);
+                }
+                throw formatActionError(`wait for ${type.name} hook`, "hook returned an invalid result");
+            }
+            if (event.error?.message) {
+                throw formatActionError(`wait for ${type.name} hook`, event.error.message);
+            }
+        }
+    }
     locator(selector, options) {
         const result = new LocatorImpl({ page: this, selector: normalizeSelectorForTransport(selector) });
         return options ? result.filter(options) : result;

package/dist/types.d.ts

@@ -98,6 +98,16 @@ export interface LocatorInfo {
 export interface BrowserType {
     launch(options?: LaunchOptions): Promise<Browser>;
 }
+declare const hookOutput: unique symbol;
+export interface HookType<T> {
+    readonly name: string;
+    readonly [hookOutput]: T;
+}
+export interface Hook<T> {
+    readonly id: string;
+    readonly type: HookType<T>;
+    wait(options?: CommandOptions): Promise<T>;
+}
 export interface Browser extends BrowserInfo {
     page(): Page;
     initialPage(): Page;
@@ -110,6 +120,7 @@ export interface Browser extends BrowserInfo {
     browserInfo(): BrowserInfo;
 }
 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>;
@@ -367,6 +378,16 @@ export interface ContextSessionEvent {
     error?: {
         message?: string;
     };
+    hookRegistered?: {
+        hookId?: string;
+    };
+    hookCompleted?: {
+        hookId?: string;
+        newPage?: {
+            contextSessionId?: string;
+            note?: string;
+        };
+    };
     navigated?: {
         url?: string;
         note?: string;
@@ -455,6 +476,23 @@ export interface OpenContextRequest {
         };
     };
 }
+export interface RegisterHookRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    registerHook: {
+        newPage?: Record<string, never>;
+    };
+}
+export interface WaitForHookRequest {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    waitForHook: {
+        hookId: string;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
 export interface ConnectMobileRequest {
     connectMobile: {
         platform: number;
@@ -634,7 +672,7 @@ export interface CloseContextRequest {
     close: Record<string, never>;
 }
 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 | AccessibilitySnapshotRequest | ScreenshotRequest | CloseContextRequest;
+export type ContextSessionRequest = ContextPingRequest | RegisterHookRequest | WaitForHookRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | AccessibilitySnapshotRequest | ScreenshotRequest | 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.1.4",
+  "version": "0.1.6",
   "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/web/v1/web.proto";
 
 message ContextSessionCommand {
   string surface_session_id = 1;
@@ -27,6 +28,8 @@ message ContextSessionCommand {
     WaitForSelectorCommand wait_for_selector = 15;
     ScreenshotCommand screenshot = 16;
     AccessibilitySnapshotCommand accessibility_snapshot = 17;
+    RegisterHookCommand register_hook = 18;
+    WaitForHookCommand wait_for_hook = 19;
   }
 }
 
@@ -58,6 +61,8 @@ message ContextSessionEvent {
     SelectorWaitSatisfiedEvent selector_wait_satisfied = 17;
     ScreenshotCapturedEvent screenshot_captured = 18;
     AccessibilitySnapshotCapturedEvent accessibility_snapshot_captured = 19;
+    HookRegisteredEvent hook_registered = 20;
+    HookCompletedEvent hook_completed = 21;
   }
 }
 
@@ -77,6 +82,29 @@ message ContextSessionErrorEvent {
   string message = 1;
 }
 
+message RegisterHookCommand {
+  oneof hook {
+    RegisterNewPageHook new_page = 1;
+  }
+}
+
+message WaitForHookCommand {
+  string hook_id = 1;
+  optional CommandRetryOptions retry_options = 2;
+}
+
+message HookRegisteredEvent {
+  string hook_id = 1;
+}
+
+message HookCompletedEvent {
+  string hook_id = 1;
+
+  oneof result {
+    NewPageHookResult new_page = 2;
+  }
+}
+
 message NavigatePageCommand {
   string url = 1;
   optional CommandRetryOptions retry_options = 2;

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

@@ -39,3 +39,10 @@ message ChromeLaunchedEvent {
   string user_data_dir = 4;
   string initial_page_session_id = 5;
 }
+
+message RegisterNewPageHook {}
+
+message NewPageHookResult {
+  string context_session_id = 1;
+  string note = 2;
+}