@allwright.dev/core 0.1.3 → 0.1.5

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 browser.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.3";
+const DEFAULT_RELEASE_VERSION = "0.1.5";
 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.d.ts

@@ -1,4 +1,4 @@
-import type { Browser, BrowserInfo, BrowserKind, BrowserLaunchState, BrowserType, CommandOptions, LaunchOptions, Page } from "./types.js";
+import type { Browser, BrowserInfo, BrowserKind, BrowserLaunchState, BrowserType, CommandOptions, Hook, HookType, LaunchOptions, Page } from "./types.js";
 export declare class BrowserTypeImpl implements BrowserType {
     #private;
     constructor(browserKind?: BrowserKind);
@@ -16,6 +16,7 @@ export declare class BrowserImpl implements Browser {
     initialPage(): Page;
     pages(): Page[];
     newPage(options?: CommandOptions): Promise<Page>;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     browserInfo(): BrowserInfo;

package/dist/browser.js

@@ -66,6 +66,48 @@ export class BrowserImpl {
             }
         }
     }
+    async registerHook(type) {
+        this.#ensureOpen();
+        if (type.name !== "newPage") {
+            throw formatActionError("register hook", `unsupported hook type: ${type.name}`);
+        }
+        this.#stream.write({ registerHook: { newPage: {} } });
+        while (true) {
+            const event = await this.#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) {
+        this.#ensureOpen();
+        this.#stream.write({
+            waitForHook: {
+                hookId,
+                retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
+            },
+        });
+        while (true) {
+            const event = await this.#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);
+            }
+        }
+    }
     async close() {
         if (this.#closed) {
             return;

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/mobile.js

@@ -200,6 +200,38 @@ class MobileAndroidAppImpl {
             }
         }
     }
+    async accessibilitySnapshot(options = {}) {
+        const mode = options.mode ?? "default";
+        if (!["default", "ai", "autoexpect", "codegen"].includes(mode)) {
+            throw new Error("invalid accessibility snapshot mode");
+        }
+        const format = options.format ?? "json";
+        if (format !== "json" && format !== "yaml") {
+            throw new Error("accessibility snapshot format must be 'json' or 'yaml'");
+        }
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({
+            surfaceSessionId: this.#surfaceSessionId,
+            contextSessionId: this.sessionId,
+            accessibilitySnapshot: {
+                format,
+                mode,
+                retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
+            },
+        });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.accessibilitySnapshotCaptured)
+                return event.accessibilitySnapshotCaptured.snapshot ?? "";
+            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 waiting for accessibility snapshot`);
+            }
+        }
+    }
     async screenshot(options = {}) {
         const handle = await this.#getHandle();
         this.#ensureOpen(handle);

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;
@@ -105,6 +115,7 @@ export interface Browser extends BrowserInfo {
     pages(): Page[];
     newPage(options?: CommandOptions): Promise<Page>;
     newTab(options?: CommandOptions): Promise<Page>;
+    registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     browserInfo(): BrowserInfo;
@@ -156,6 +167,7 @@ export interface MobileAndroidLocator {
     locator(selector: string): MobileAndroidLocator;
 }
 export interface MobileAndroidApp {
+    accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
     readonly sessionId: string;
     locator(selector: string): MobileAndroidLocator;
     click(selector: string, options?: CommandOptions): Promise<ClickResult>;
@@ -337,6 +349,18 @@ export interface SurfaceSessionEvent {
         contextSessionId?: string;
         note?: string;
     };
+    hookRegistered?: {
+        hookId?: string;
+        hookType?: number;
+    };
+    hookCompleted?: {
+        hookId?: string;
+        hookType?: number;
+        newPage?: {
+            contextSessionId?: string;
+            note?: string;
+        };
+    };
     pong?: {
         message?: string;
     };
@@ -454,6 +478,19 @@ export interface OpenContextRequest {
         };
     };
 }
+export interface RegisterHookRequest {
+    registerHook: {
+        newPage?: Record<string, never>;
+    };
+}
+export interface WaitForHookRequest {
+    waitForHook: {
+        hookId: string;
+        retryOptions?: {
+            timeoutMs?: number;
+        };
+    };
+}
 export interface ConnectMobileRequest {
     connectMobile: {
         platform: number;
@@ -632,7 +669,7 @@ export interface CloseContextRequest {
     contextSessionId: string;
     close: Record<string, never>;
 }
-export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
+export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | RegisterHookRequest | WaitForHookRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
 export type ContextSessionRequest = ContextPingRequest | 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>;

package/package.json

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

package/proto/core/v1/common.proto

@@ -2,6 +2,8 @@ syntax = "proto3";
 
 package allwright.engine.v1;
 option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+option java_package = "dev.allwright.engine.v1";
+option java_multiple_files = true;
 
 message PingRequest {}
 

package/proto/core/v1/context.proto

@@ -6,7 +6,6 @@ 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;
@@ -218,3 +217,18 @@ message ScreenshotCapturedEvent {
   bytes png_data = 1;
   string note = 2;
 }
+
+// Empty format defaults to JSON. Accepted values are "json" and "yaml".
+message AccessibilitySnapshotCommand {
+  // Empty mode defaults to default. AI assigns queryable references; reference storage is surface-owned.
+  // Supported: default, ai, autoexpect, codegen.
+  string mode = 3;
+  string format = 1;
+  optional CommandRetryOptions retry_options = 2;
+}
+
+// Both formats encode the same versioned, structured document.
+message AccessibilitySnapshotCapturedEvent {
+  string snapshot = 1;
+  string format = 2;
+}

package/proto/core/v1/surface.proto

@@ -2,6 +2,8 @@ syntax = "proto3";
 
 package allwright.engine.v1;
 option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+option java_package = "dev.allwright.engine.v1";
+option java_multiple_files = true;
 
 import "core/v1/common.proto";
 import "surfaces/mobile/v1/mobile.proto";
@@ -16,6 +18,8 @@ message SurfaceSessionCommand {
     LaunchBrowserCommand launch_browser = 5;
     ConnectMobileCommand connect_mobile = 6;
     LaunchAppCommand launch_app = 7;
+    RegisterHookCommand register_hook = 8;
+    WaitForHookCommand wait_for_hook = 9;
   }
 }
 
@@ -29,6 +33,17 @@ message SessionPingCommand {
 
 message CloseSurfaceSessionCommand {}
 
+message RegisterHookCommand {
+  oneof hook {
+    RegisterNewPageHook new_page = 1;
+  }
+}
+
+message WaitForHookCommand {
+  string hook_id = 1;
+  optional CommandRetryOptions retry_options = 2;
+}
+
 message SurfaceSessionEvent {
   string session_id = 1;
 
@@ -41,6 +56,8 @@ message SurfaceSessionEvent {
     BrowserLaunchedEvent browser_launched = 7;
     MobileConnectedEvent mobile_connected = 8;
     AppLaunchedEvent app_launched = 9;
+    HookRegisteredEvent hook_registered = 10;
+    HookCompletedEvent hook_completed = 11;
   }
 }
 
@@ -60,3 +77,15 @@ message SurfaceSessionClosedEvent {
 message SurfaceSessionErrorEvent {
   string message = 1;
 }
+
+message HookRegisteredEvent {
+  string hook_id = 1;
+}
+
+message HookCompletedEvent {
+  string hook_id = 1;
+
+  oneof result {
+    NewPageHookResult new_page = 2;
+  }
+}

package/proto/engine/v1/engine.proto

@@ -2,6 +2,8 @@ syntax = "proto3";
 
 package allwright.engine.v1;
 option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+option java_package = "dev.allwright.engine.v1";
+option java_multiple_files = true;
 
 import "core/v1/surface.proto";
 import "core/v1/common.proto";

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

@@ -2,6 +2,8 @@ syntax = "proto3";
 
 package allwright.engine.v1;
 option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
+option java_package = "dev.allwright.engine.v1";
+option java_multiple_files = true;
 
 import "core/v1/common.proto";
 

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

@@ -40,17 +40,9 @@ message ChromeLaunchedEvent {
   string initial_page_session_id = 5;
 }
 
-// Empty format defaults to JSON. Accepted values are "json" and "yaml".
-message AccessibilitySnapshotCommand {
-  // Empty mode defaults to default. AI injects queryable aria-ref attributes.
-  // Supported: default, ai, autoexpect, codegen.
-  string mode = 3;
-  string format = 1;
-  optional CommandRetryOptions retry_options = 2;
-}
+message RegisterNewPageHook {}
 
-// Both formats encode the same versioned, structured document.
-message AccessibilitySnapshotCapturedEvent {
-  string snapshot = 1;
-  string format = 2;
+message NewPageHookResult {
+  string context_session_id = 1;
+  string note = 2;
 }