@allwright.dev/core 0.1.11 → 0.1.13

package/README.md

@@ -79,3 +79,19 @@ suites:
 ```
 
 The TypeScript package exports `findConfigFile()`, `loadConfigFile()`, `resolveConfig()`, and `launchConfiguredBrowser()` so runner packages can consume the same config model without inventing language-specific config files.
+
+### Iframes
+
+An iframe resolves to a normal `Page`, including nested and cross-origin frames:
+
+```ts
+const frame = await page.locator("#checkout-frame").Frame({ timeoutMs: 10_000 });
+await frame.locator("input[name=email]").fill("buyer@example.com");
+const nested = await frame.locator("iframe").frame({ timeoutMs: 5_000 });
+```
+
+`Frame()` and `frame()` are aliases. The timeout covers finding exactly one iframe,
+resolving its browsing context, and waiting for a fully loaded document with 200 ms
+without DOM mutations. The default is 10 seconds. Closing the frame page releases
+its session; it does not remove the iframe or close the parent tab. Resolve a new
+frame page after the iframe is replaced.

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

package/dist/locator.d.ts

@@ -4,6 +4,8 @@ export declare class LocatorImpl extends WebLocatorBuilders implements Locator {
     readonly page: Page;
     readonly selector: string;
     constructor(input: LocatorInfo);
+    frame(options?: CommandOptions): Promise<Page>;
+    Frame(options?: CommandOptions): Promise<Page>;
     click(options?: CommandOptions): Promise<ClickResult>;
     count(options?: CommandOptions): Promise<CountResult>;
     highlight(options?: HighlightOptions): Promise<HighlightResult>;

package/dist/locator.js

@@ -8,6 +8,8 @@ export class LocatorImpl extends WebLocatorBuilders {
         this.page = input.page;
         this.selector = input.selector;
     }
+    frame(options = {}) { return this.page.frame(this.selector, options); }
+    Frame(options = {}) { return this.frame(options); }
     async click(options = {}) {
         return this.page.click(this.selector, options);
     }

package/dist/page.d.ts

@@ -8,6 +8,7 @@ export declare class PageImpl extends WebLocatorBuilders implements Page {
     });
     readonly sessionId: string;
     readonly browserSessionId: string;
+    frame(selector: string, options?: CommandOptions): Promise<Page>;
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
     setFileChooserFiles(fileChooserId: string, files: string[], options?: CommandOptions): Promise<void>;
     saveDownload(downloadId: string, path: string, options?: CommandOptions): Promise<void>;

package/dist/page.js

@@ -24,6 +24,23 @@ export class PageImpl extends WebLocatorBuilders {
     }
     sessionId;
     browserSessionId;
+    async frame(selector, options = {}) {
+        const handle = await this.#getHandle();
+        this.#ensureOpen(handle);
+        handle.stream.write({ surfaceSessionId: this.browserSessionId, contextSessionId: this.sessionId,
+            resolveFrame: { cssSelector: normalizeSelectorForTransport(selector), retryOptions: options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : undefined } });
+        while (true) {
+            const event = await handle.queue.next();
+            if (event.frameResolved?.contextSessionId)
+                return this.#createPage(event.frameResolved.contextSessionId);
+            if (event.error?.message)
+                throw formatActionError("resolve frame", event.error.message, selector);
+            if (event.closed) {
+                handle.closed = true;
+                throw new Error("page closed while resolving frame");
+            }
+        }
+    }
     async registerHook(type) {
         if (type.name !== "newPage" && type.name !== "fileChooser" && type.name !== "download") {
             throw formatActionError("register hook", `unsupported hook type: ${type.name}`);

package/dist/types.d.ts

@@ -133,6 +133,7 @@ export interface Browser extends BrowserInfo {
     browserInfo(): BrowserInfo;
 }
 export interface Page extends PageInfo, WebLocators {
+    frame(selector: string, options?: CommandOptions): Promise<Page>;
     registerHook<T>(type: HookType<T>): Promise<Hook<T>>;
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
     locator(selector: string, options?: LocatorFilterOptions): Locator;
@@ -206,6 +207,8 @@ export interface MobileSurfaceNamespace {
     };
 }
 export interface Locator extends WebLocators {
+    frame(options?: CommandOptions): Promise<Page>;
+    Frame(options?: CommandOptions): Promise<Page>;
     not(other: Locator): Locator;
     filter(options?: LocatorFilterOptions): Locator;
     nth(index: number): Locator;
@@ -374,6 +377,9 @@ export interface SurfaceSessionEvent {
     };
 }
 export interface ContextSessionEvent {
+    frameResolved?: {
+        contextSessionId?: string;
+    };
     accessibilitySnapshotCaptured?: {
         snapshot?: string;
         format?: string;
@@ -809,7 +815,16 @@ export interface CloseContextRequest {
     close: Record<string, never>;
 }
 export type SurfaceSessionRequest = LaunchBrowserRequest | LaunchChromeRequest | OpenContextRequest | ConnectMobileRequest | LaunchAppRequest | SurfacePingRequest | CloseSurfaceRequest;
-export type ContextSessionRequest = ContextPingRequest | RegisterHookRequest | WaitForHookRequest | SetFileChooserFilesRequest | SaveDownloadRequest | UploadFileChunkRequest | ReadFileChunkRequest | SetMobileFileChooserFilesRequest | SaveMobileDownloadRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | AccessibilitySnapshotRequest | ScreenshotRequest | CloseContextRequest;
+export type ContextSessionRequest = {
+    surfaceSessionId: string;
+    contextSessionId: string;
+    resolveFrame: {
+        cssSelector: string;
+        retryOptions?: {
+            timeoutMs: number;
+        };
+    };
+} | ContextPingRequest | RegisterHookRequest | WaitForHookRequest | SetFileChooserFilesRequest | SaveDownloadRequest | UploadFileChunkRequest | ReadFileChunkRequest | SetMobileFileChooserFilesRequest | SaveMobileDownloadRequest | 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.11",
+  "version": "0.1.13",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",

package/proto/core/v1/context.proto

@@ -37,6 +37,7 @@ message ContextSessionCommand {
     ReadFileChunkCommand read_file_chunk = 23;
     SetMobileFileChooserFilesCommand set_mobile_file_chooser_files = 24;
     SaveMobileDownloadCommand save_mobile_download = 25;
+    ResolveFrameCommand resolve_frame = 26;
   }
 }
 
@@ -76,6 +77,7 @@ message ContextSessionEvent {
     FileChunkEvent file_chunk = 25;
     MobileFileChooserFilesSetEvent mobile_file_chooser_files_set = 26;
     MobileDownloadSavedEvent mobile_download_saved = 27;
+    FrameResolvedEvent frame_resolved = 28;
   }
 }
 

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

@@ -88,3 +88,12 @@ message DownloadSavedEvent {
   uint64 size = 4;
   string note = 5;
 }
+
+// Resolve an iframe locator to a page after its document has loaded and settled.
+message ResolveFrameCommand {
+  string css_selector = 1;
+  optional CommandRetryOptions retry_options = 2;
+}
+message FrameResolvedEvent {
+  string context_session_id = 1;
+}