@allwright.dev/core 0.1.1 → 0.1.3

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.1";
+const DEFAULT_RELEASE_VERSION = "0.1.3";
 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/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();
@@ -306,6 +309,10 @@ export class PageImpl {
         }
     }
     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'");
@@ -317,6 +324,7 @@ export class PageImpl {
             contextSessionId: this.sessionId,
             accessibilitySnapshot: {
                 format,
+                mode,
                 retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
             },
         });

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 {
@@ -10,6 +11,7 @@ export interface CommandOptions {
 }
 export interface AccessibilitySnapshotOptions extends CommandOptions {
     format?: "json" | "yaml";
+    mode?: "default" | "ai" | "autoexpect" | "codegen";
 }
 export interface NavigateResult {
     url: string;
@@ -107,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>;
@@ -177,7 +179,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>;
@@ -190,7 +197,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;
@@ -604,6 +611,7 @@ export interface AccessibilitySnapshotRequest {
     contextSessionId: string;
     accessibilitySnapshot: {
         format: string;
+        mode: string;
         retryOptions?: {
             timeoutMs?: number;
         };

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.1",
+  "version": "0.1.3",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",

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

@@ -42,6 +42,9 @@ message ChromeLaunchedEvent {
 
 // 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;
 }