@allwright.dev/core 0.1.2 → 0.1.4

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

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export declare function launchBrowser(): Promise<Browser>;
 export declare function launchBrowser(options: ResolveConfigOptions): Promise<Browser>;
 export declare function launchBrowser(browserKind: BrowserKind, options?: LaunchOptions): Promise<Browser>;
 export { BrowserImpl, BrowserTypeImpl, PageImpl };
+export type { TextMatcher, TextOptions, RoleOptions, LocatorFilterOptions } from "./web-locators.js";

package/dist/locator.d.ts

@@ -1,5 +1,6 @@
+import { WebLocatorBuilders, type LocatorFilterOptions } from "./web-locators.js";
 import type { ClickResult, CommandOptions, CountResult, ElementResult, FillResult, HighlightOptions, HighlightResult, Locator, LocatorInfo, Page, PressOptions, PressResult, TextResult, WaitForSelectorOptions, WaitForSelectorResult } from "./types.js";
-export declare class LocatorImpl implements Locator {
+export declare class LocatorImpl extends WebLocatorBuilders implements Locator {
     readonly page: Page;
     readonly selector: string;
     constructor(input: LocatorInfo);
@@ -13,5 +14,10 @@ export declare class LocatorImpl implements Locator {
     textContent(options?: CommandOptions): Promise<TextResult>;
     innerText(options?: CommandOptions): Promise<TextResult>;
     waitFor(options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
-    locator(selector: string): Locator;
+    not(other: Locator): Locator;
+    filter(options?: LocatorFilterOptions): Locator;
+    nth(index: number): Locator;
+    first(): Locator;
+    last(): Locator;
+    locator(selector: string, options?: LocatorFilterOptions): Locator;
 }

package/dist/locator.js

@@ -1,8 +1,10 @@
+import { WebLocatorBuilders, semanticSelector } from "./web-locators.js";
 import { chainSelectorForTransport } from "./selectors.js";
-export class LocatorImpl {
+export class LocatorImpl extends WebLocatorBuilders {
     page;
     selector;
     constructor(input) {
+        super();
         this.page = input.page;
         this.selector = input.selector;
     }
@@ -36,10 +38,30 @@ export class LocatorImpl {
     async waitFor(options = {}) {
         return this.page.waitForSelector(this.selector, options);
     }
-    locator(selector) {
-        return new LocatorImpl({
+    not(other) {
+        if (other.page !== this.page)
+            throw new Error('Excluded locators must belong to the same page');
+        return this.locator(semanticSelector({ kind: 'exclude', selector: other.selector }));
+    }
+    filter(options = {}) {
+        for (const inner of [options.has, options.hasNot]) {
+            if (inner && inner.page !== this.page)
+                throw new Error('Filter locators must belong to the same page');
+        }
+        return this.locator(semanticSelector({ ...options, kind: 'filter', has: options.has?.selector, hasNot: options.hasNot?.selector }));
+    }
+    nth(index) {
+        if (!Number.isInteger(index))
+            throw new Error('Locator index must be an integer');
+        return this.locator(semanticSelector({ kind: 'nth', index }));
+    }
+    first() { return this.nth(0); }
+    last() { return this.nth(-1); }
+    locator(selector, options) {
+        const result = new LocatorImpl({
             page: this.page,
             selector: chainSelectorForTransport(this.selector, selector),
         });
+        return options ? result.filter(options) : result;
     }
 }

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/page.d.ts

@@ -1,12 +1,13 @@
+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";
-export declare class PageImpl implements Page {
+export declare class PageImpl extends WebLocatorBuilders implements Page {
     #private;
     constructor(input: PageInfo & {
         runtime: RuntimeClient;
     });
     readonly sessionId: string;
     readonly browserSessionId: string;
-    locator(selector: string): Locator;
+    locator(selector: string, options?: LocatorFilterOptions): Locator;
     goto(url: string, options?: CommandOptions): Promise<NavigateResult>;
     click(selector: string, options?: CommandOptions): Promise<ClickResult>;
     count(selector: string, options?: CommandOptions): Promise<CountResult>;

package/dist/page.js

@@ -1,20 +1,23 @@
+import { WebLocatorBuilders } from "./web-locators.js";
 import { LocatorImpl } from "./locator.js";
 import { writeFile } from "node:fs/promises";
 import { formatActionError } from "./errors.js";
 import { normalizeSelectorForTransport } from "./selectors.js";
 import { createPageHandle } from "./runtime.js";
-export class PageImpl {
+export class PageImpl extends WebLocatorBuilders {
     #runtime;
     #handlePromise = null;
     constructor(input) {
+        super();
         this.#runtime = input.runtime;
         this.sessionId = input.sessionId;
         this.browserSessionId = input.browserSessionId;
     }
     sessionId;
     browserSessionId;
-    locator(selector) {
-        return new LocatorImpl({ page: this, selector: normalizeSelectorForTransport(selector) });
+    locator(selector, options) {
+        const result = new LocatorImpl({ page: this, selector: normalizeSelectorForTransport(selector) });
+        return options ? result.filter(options) : result;
     }
     async goto(url, options = {}) {
         const handle = await this.#getHandle();

package/dist/selectors.d.ts

@@ -1,4 +1,4 @@
-export type SelectorFlavor = "css" | "xpath";
+export type SelectorFlavor = "css" | "xpath" | "aw";
 export declare function parseSelectorForTransport(selector: string): {
     flavor: SelectorFlavor;
     body: string;

package/dist/selectors.js

@@ -1,4 +1,4 @@
-const SELECTOR_PREFIXES = ["xpath=", "xpath:", "css=", "css:"];
+const SELECTOR_PREFIXES = ["aw=", "xpath=", "xpath:", "css=", "css:"];
 function decodeSelectorBody(body) {
     const candidate = body.trim();
     if (candidate.startsWith("\"") && candidate.endsWith("\"")) {
@@ -13,6 +13,8 @@ function decodeSelectorBody(body) {
 }
 function parseExplicitSelectorPrefix(selector) {
     const lowered = selector.toLowerCase();
+    if (lowered.startsWith("aw="))
+        return { flavor: "aw", prefixLength: 3 };
     if (lowered.startsWith("xpath=") || lowered.startsWith("xpath:")) {
         return { flavor: "xpath", prefixLength: 6 };
     }

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { WebLocators, LocatorFilterOptions } from "./web-locators.js";
 import grpc from "@grpc/grpc-js";
 export { AllwrightError } from "./errors.js";
 export interface LaunchOptions {
@@ -108,9 +109,9 @@ export interface Browser extends BrowserInfo {
     ping(message?: string): Promise<string>;
     browserInfo(): BrowserInfo;
 }
-export interface Page extends PageInfo {
+export interface Page extends PageInfo, WebLocators {
     accessibilitySnapshot(options?: AccessibilitySnapshotOptions): Promise<string>;
-    locator(selector: string): Locator;
+    locator(selector: string, options?: LocatorFilterOptions): Locator;
     goto(url: string, options?: CommandOptions): Promise<NavigateResult>;
     navigate(url: string, options?: CommandOptions): Promise<NavigateResult>;
     click(selector: string, options?: CommandOptions): Promise<ClickResult>;
@@ -155,6 +156,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>;
@@ -178,7 +180,12 @@ export interface MobileSurfaceNamespace {
         connect(options?: MobileAndroidConnectOptions): Promise<MobileAndroidDevice>;
     };
 }
-export interface Locator {
+export interface Locator extends WebLocators {
+    not(other: Locator): Locator;
+    filter(options?: LocatorFilterOptions): Locator;
+    nth(index: number): Locator;
+    first(): Locator;
+    last(): Locator;
     readonly page: Page;
     readonly selector: string;
     click(options?: CommandOptions): Promise<ClickResult>;
@@ -191,7 +198,7 @@ export interface Locator {
     textContent(options?: CommandOptions): Promise<TextResult>;
     innerText(options?: CommandOptions): Promise<TextResult>;
     waitFor(options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
-    locator(selector: string): Locator;
+    locator(selector: string, options?: LocatorFilterOptions): Locator;
 }
 export interface AllwrightConfig {
     schemaVersion?: 1;

package/dist/web-locators.d.ts

@@ -0,0 +1,43 @@
+import type { Locator } from './types.js';
+export type TextMatcher = string | RegExp;
+export interface TextOptions {
+    exact?: boolean;
+}
+export interface RoleOptions extends TextOptions {
+    name?: TextMatcher;
+    checked?: boolean;
+    disabled?: boolean;
+    expanded?: boolean;
+    includeHidden?: boolean;
+    level?: number;
+    pressed?: boolean;
+    selected?: boolean;
+}
+export interface LocatorFilterOptions {
+    has?: Locator;
+    hasNot?: Locator;
+    hasText?: TextMatcher;
+    hasNotText?: TextMatcher;
+    visible?: boolean;
+}
+export interface WebLocators {
+    getByRole(role: string, options?: RoleOptions): Locator;
+    getByText(text: TextMatcher, options?: TextOptions): Locator;
+    getByLabel(text: TextMatcher, options?: TextOptions): Locator;
+    getByPlaceholder(text: TextMatcher, options?: TextOptions): Locator;
+    getByAltText(text: TextMatcher, options?: TextOptions): Locator;
+    getByTitle(text: TextMatcher, options?: TextOptions): Locator;
+    getByTestId(text: TextMatcher): Locator;
+}
+export declare function semanticSelector(spec: Record<string, unknown>): string;
+/** Locator construction only; DOM matching belongs to the web plugin. */
+export declare abstract class WebLocatorBuilders implements WebLocators {
+    abstract locator(selector: string, options?: LocatorFilterOptions): Locator;
+    getByRole(role: string, options?: RoleOptions): Locator;
+    getByText(text: TextMatcher, options?: TextOptions): Locator;
+    getByLabel(text: TextMatcher, options?: TextOptions): Locator;
+    getByPlaceholder(text: TextMatcher, options?: TextOptions): Locator;
+    getByAltText(text: TextMatcher, options?: TextOptions): Locator;
+    getByTitle(text: TextMatcher, options?: TextOptions): Locator;
+    getByTestId(text: TextMatcher): Locator;
+}

package/dist/web-locators.js

@@ -0,0 +1,18 @@
+export function semanticSelector(spec) {
+    return `aw=${JSON.stringify(JSON.stringify(spec, (_key, value) => value instanceof RegExp ? { regex: value.source, flags: value.flags } : value))}`;
+}
+/** Locator construction only; DOM matching belongs to the web plugin. */
+export class WebLocatorBuilders {
+    getByRole(role, options = {}) {
+        if (options.level !== undefined && (!Number.isInteger(options.level) || options.level < 1)) {
+            throw new Error('Role level must be a positive integer');
+        }
+        return this.locator(semanticSelector({ ...options, kind: 'role', role }));
+    }
+    getByText(text, options = {}) { return this.locator(semanticSelector({ ...options, kind: 'text', text })); }
+    getByLabel(text, options = {}) { return this.locator(semanticSelector({ ...options, kind: 'label', text })); }
+    getByPlaceholder(text, options = {}) { return this.locator(semanticSelector({ ...options, kind: 'placeholder', text })); }
+    getByAltText(text, options = {}) { return this.locator(semanticSelector({ ...options, kind: 'altText', text })); }
+    getByTitle(text, options = {}) { return this.locator(semanticSelector({ ...options, kind: 'title', text })); }
+    getByTestId(text) { return this.locator(semanticSelector({ kind: 'testId', text })); }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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";

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

@@ -39,18 +39,3 @@ message ChromeLaunchedEvent {
   string user_data_dir = 4;
   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;
-}
-
-// Both formats encode the same versioned, structured document.
-message AccessibilitySnapshotCapturedEvent {
-  string snapshot = 1;
-  string format = 2;
-}