@allwright.dev/core 0.0.26 → 0.0.28

package/README.md

@@ -2,11 +2,46 @@
 
 High-level TypeScript client for the allwright automation engine.
 
+Install:
+
+```bash
+npm install @allwright.dev/core
+```
+
 ```ts
-import { chromium } from "@allwright.dev/core";
+import { firefox } from "@allwright.dev/core";
 
-const browser = await chromium.launch();
+const browser = await firefox.launch();
 const page = browser.page();
 await page.goto("https://example.com");
 await browser.close();
 ```
+
+A small runnable example also lives in [examples/basic.ts](./examples/basic.ts), and the fuller end-to-end playground lives in [examples/playground.ts](./examples/playground.ts).
+
+Shared config files are stack-agnostic and can live in `allwright.config.yaml` or `allwright.config.json`.
+The shared schema lives at the repo root in `allwright.schema.json`.
+
+```yaml
+schemaVersion: 1
+
+server:
+  addr: 127.0.0.1:50051
+
+browser:
+  name: firefox
+  binary: /Applications/Firefox.app/Contents/MacOS/firefox
+  launchOptions:
+    timeoutMs: 30000
+
+expect:
+  timeoutMs: 5000
+  intervalMs: 100
+
+suites:
+  smoke:
+    browser:
+      name: chromium
+```
+
+The TypeScript package exports `findConfigFile()`, `loadConfigFile()`, `resolveConfig()`, and `launchConfiguredBrowser()` so runner packages can consume the same config model without inventing language-specific config files.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import grpc from "@grpc/grpc-js";
 export interface LaunchOptions {
-    chromeBinary?: string;
+    browserBinary?: string;
     timeoutMs?: number;
 }
+export type BrowserKind = "chromium" | "firefox";
 export interface CommandOptions {
     timeoutMs?: number;
 }
@@ -80,315 +80,24 @@ export interface LocatorInfo {
     page: Page;
     selector: string;
 }
-interface PingResponse {
-    message?: string;
-}
-interface ChromeLaunchedPayload {
-    browser?: string;
-    note?: string;
-    cdpWebsocketUrl?: string;
-    userDataDir?: string;
-    initialTabSessionId?: string;
-}
-interface BrowserSessionEvent {
-    sessionId?: string;
-    event?: string;
-    chromeLaunched?: ChromeLaunchedPayload;
-    tabOpened?: {
-        tabSessionId?: string;
-        note?: string;
-    };
-    pong?: {
-        message?: string;
-    };
-    closed?: {
-        reason?: string;
-    };
-    error?: {
-        message?: string;
-    };
-}
-interface TabSessionEvent {
-    tabSessionId?: string;
-    event?: string;
-    attached?: {
-        note?: string;
-    };
-    pong?: {
-        message?: string;
-    };
-    closed?: {
-        reason?: string;
-    };
-    error?: {
-        message?: string;
-    };
-    navigated?: {
-        url?: string;
-        note?: string;
-    };
-    chromiumBidiInjection?: {
-        note?: string;
-        bidiSessionId?: string;
-        mapperTargetId?: string;
-        mapperSessionId?: string;
-        packageVersion?: string;
-    };
-    elementClicked?: {
-        cssSelector?: string;
-        note?: string;
-        bidiSessionId?: string;
-    };
-    elementCounted?: {
-        cssSelector?: string;
-        count?: number;
-        note?: string;
-    };
-    elementsHighlighted?: {
-        cssSelector?: string;
-        count?: number;
-        note?: string;
-    };
-    elementFocused?: {
-        cssSelector?: string;
-        note?: string;
-    };
-    elementFilled?: {
-        cssSelector?: string;
-        value?: string;
-        note?: string;
-    };
-    elementHovered?: {
-        cssSelector?: string;
-        note?: string;
-    };
-    keyPressed?: {
-        cssSelector?: string;
-        key?: string;
-        note?: string;
-    };
-    textContentResolved?: {
-        cssSelector?: string;
-        text?: string;
-        note?: string;
-    };
-    innerTextResolved?: {
-        cssSelector?: string;
-        text?: string;
-        note?: string;
-    };
-    selectorWaitSatisfied?: {
-        cssSelector?: string;
-        visible?: boolean;
-        note?: string;
-    };
-}
-interface LaunchChromeRequest {
-    launchChrome: {
-        chromeBinary?: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface OpenTabRequest {
-    openTab: {
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface BrowserPingRequest {
-    ping: {
-        message: string;
-    };
-}
-interface CloseBrowserRequest {
-    close: Record<string, never>;
-}
-interface TabPingRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    ping: {
-        message: string;
-    };
-}
-interface NavigateRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    navigate: {
-        url: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface ClickRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    clickElement: {
-        cssSelector: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface CountRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    countElements: {
-        cssSelector: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface HighlightRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    highlightElements: {
-        cssSelector: string;
-        durationMs?: number;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface FocusRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    focusElement: {
-        cssSelector: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface FillRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    fillElement: {
-        cssSelector: string;
-        value: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface HoverRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    hoverElement: {
-        cssSelector: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface PressRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    pressKey: {
-        cssSelector: string;
-        key: string;
-        text?: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface TextContentRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    getTextContent: {
-        cssSelector: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface InnerTextRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    getInnerText: {
-        cssSelector: string;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface WaitForSelectorRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    waitForSelector: {
-        cssSelector: string;
-        visible?: boolean;
-        retryOptions?: {
-            timeoutMs?: number;
-        };
-    };
-}
-interface CloseTabRequest {
-    browserSessionId: string;
-    tabSessionId: string;
-    close: Record<string, never>;
-}
-type BrowserSessionRequest = LaunchChromeRequest | OpenTabRequest | BrowserPingRequest | CloseBrowserRequest;
-type TabSessionRequest = TabPingRequest | NavigateRequest | ClickRequest | CountRequest | HighlightRequest | FocusRequest | FillRequest | HoverRequest | PressRequest | TextContentRequest | InnerTextRequest | WaitForSelectorRequest | CloseTabRequest;
-type BrowserSessionStream = grpc.ClientDuplexStream<BrowserSessionRequest, BrowserSessionEvent>;
-type PageSessionStream = grpc.ClientDuplexStream<TabSessionRequest, TabSessionEvent>;
-interface EngineServiceClientShape {
-    Ping(request: Record<string, never>, callback: (error: grpc.ServiceError | null, response: PingResponse) => void): void;
-    BrowserSession(): BrowserSessionStream;
-    TabSession(): PageSessionStream;
-    close(): void;
-}
-interface RuntimeClient {
-    client: EngineServiceClientShape;
-}
-interface BrowserLaunchState {
-    runtime: RuntimeClient;
-    stream: BrowserSessionStream;
-    queue: EventQueue<BrowserSessionEvent>;
-    sessionId: string;
-    chromeLaunched: ChromeLaunchedPayload;
-}
-declare class EventQueue<T> {
-    #private;
-    push(item: T): void;
-    fail(error: Error): void;
-    next(): Promise<T>;
-}
-export declare class BrowserType {
+export interface BrowserType {
     launch(options?: LaunchOptions): Promise<Browser>;
 }
-export declare class Browser {
-    #private;
-    constructor(state: BrowserLaunchState);
-    readonly sessionId: string;
-    readonly browserName: string;
-    readonly launchNote: string;
-    readonly cdpWebSocketURL: string;
-    readonly userDataDir: string;
+export interface Browser extends BrowserInfo {
     page(): Page;
     initialPage(): Page;
+    initialTab(): Page;
     pages(): Page[];
     newPage(options?: CommandOptions): Promise<Page>;
+    newTab(options?: CommandOptions): Promise<Page>;
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     browserInfo(): BrowserInfo;
-    initialTab(): Page;
-    newTab(options?: CommandOptions): Promise<Page>;
 }
-export declare class Page {
-    #private;
-    constructor(input: PageInfo & {
-        runtime: RuntimeClient;
-    });
-    readonly sessionId: string;
-    readonly browserSessionId: string;
+export interface Page extends PageInfo {
     locator(selector: string): Locator;
     goto(url: string, options?: CommandOptions): Promise<NavigateResult>;
+    navigate(url: string, options?: CommandOptions): Promise<NavigateResult>;
     click(selector: string, options?: CommandOptions): Promise<ClickResult>;
     count(selector: string, options?: CommandOptions): Promise<CountResult>;
     highlight(selector: string, options?: HighlightOptions): Promise<HighlightResult>;
@@ -402,12 +111,10 @@ export declare class Page {
     close(): Promise<void>;
     ping(message?: string): Promise<string>;
     pageInfo(): PageInfo;
-    navigate(url: string, options?: CommandOptions): Promise<NavigateResult>;
 }
-export declare class Locator {
+export interface Locator {
     readonly page: Page;
     readonly selector: string;
-    constructor(input: LocatorInfo);
     click(options?: CommandOptions): Promise<ClickResult>;
     count(options?: CommandOptions): Promise<CountResult>;
     highlight(options?: HighlightOptions): Promise<HighlightResult>;
@@ -420,10 +127,57 @@ export declare class Locator {
     waitFor(options?: WaitForSelectorOptions): Promise<WaitForSelectorResult>;
     locator(selector: string): Locator;
 }
+export interface AllwrightConfig {
+    schemaVersion?: 1;
+    server?: {
+        addr?: string;
+    };
+    browser?: {
+        name?: BrowserKind;
+        binary?: string;
+        launchOptions?: LaunchOptions;
+    };
+    expect?: RetryConfig;
+    suites?: Record<string, AllwrightSuiteConfig>;
+}
+export interface AllwrightSuiteConfig {
+    server?: {
+        addr?: string;
+    };
+    browser?: {
+        name?: BrowserKind;
+        binary?: string;
+        launchOptions?: LaunchOptions;
+    };
+    expect?: RetryConfig;
+}
+export interface RetryConfig {
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+export interface ResolvedAllwrightConfig {
+    configFilePath: string | null;
+    suiteName: string | null;
+    serverAddr?: string;
+    browserName: BrowserKind;
+    browserBinary?: string;
+    launchOptions: LaunchOptions;
+    expect: RetryConfig;
+}
+export interface ResolveConfigOptions {
+    cwd?: string;
+    configFile?: string;
+    suite?: string;
+}
 export declare const chromium: BrowserType;
+export declare const firefox: BrowserType;
 export type Tab = Page;
 export declare function ping(): Promise<string>;
 export declare function launchChrome(options?: LaunchOptions): Promise<Browser>;
+export declare function launchConfiguredBrowser(config: ResolvedAllwrightConfig): Promise<Browser>;
+export declare function launchBrowser(browserKind: BrowserKind, options?: LaunchOptions): Promise<Browser>;
 export declare function setServerAddr(serverAddr: string): void;
 export declare function shutdown(): Promise<void>;
-export {};
+export declare function findConfigFile(startDir?: string): string | null;
+export declare function loadConfigFile(configFile: string): AllwrightConfig;
+export declare function resolveConfig(options?: ResolveConfigOptions): ResolvedAllwrightConfig;

package/dist/index.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import grpc from "@grpc/grpc-js";
 import protoLoader from "@grpc/proto-loader";
@@ -11,6 +12,14 @@ const PROTO_ROOT = path.join(PACKAGE_ROOT, "proto");
 const ENGINE_PROTO_PATH = path.join(PROTO_ROOT, "engine", "v1", "engine.proto");
 let runtimePromise = null;
 let serverAddrOverride = null;
+const CONFIG_FILENAMES = [
+    "allwright.config.yaml",
+    "allwright.config.yml",
+    "allwright.config.json",
+    ".allwright/config.yaml",
+    ".allwright/config.yml",
+    ".allwright/config.json",
+];
 class EventQueue {
     #items = [];
     #waiters = [];
@@ -44,12 +53,16 @@ class EventQueue {
         });
     }
 }
-export class BrowserType {
+class BrowserTypeImpl {
+    #browserKind;
+    constructor(browserKind = "chromium") {
+        this.#browserKind = browserKind;
+    }
     async launch(options = {}) {
-        return launchChrome(options);
+        return launchBrowser(this.#browserKind, options);
     }
 }
-export class Browser {
+class BrowserImpl {
     #closed = false;
     #runtime;
     #stream;
@@ -59,10 +72,10 @@ export class Browser {
     constructor(state) {
         const browserInfo = {
             sessionId: state.sessionId,
-            browserName: state.chromeLaunched.browser ?? "",
-            launchNote: state.chromeLaunched.note ?? "",
-            cdpWebSocketURL: state.chromeLaunched.cdpWebsocketUrl ?? "",
-            userDataDir: state.chromeLaunched.userDataDir ?? "",
+            browserName: state.launched.browser ?? "",
+            launchNote: state.launched.note ?? "",
+            cdpWebSocketURL: "",
+            userDataDir: state.launched.userDataDir ?? "",
         };
         this.#runtime = state.runtime;
         this.#stream = state.stream;
@@ -72,7 +85,7 @@ export class Browser {
         this.launchNote = browserInfo.launchNote;
         this.cdpWebSocketURL = browserInfo.cdpWebSocketURL;
         this.userDataDir = browserInfo.userDataDir;
-        this.#initialPage = this.#createPage(state.chromeLaunched.initialTabSessionId ?? "");
+        this.#initialPage = this.#createPage(state.launched.initialTabSessionId ?? "");
     }
     sessionId;
     browserName;
@@ -161,7 +174,7 @@ export class Browser {
         if (existing) {
             return existing;
         }
-        const page = new Page({
+        const page = new PageImpl({
             runtime: this.#runtime,
             browserSessionId: this.sessionId,
             sessionId,
@@ -175,7 +188,7 @@ export class Browser {
         }
     }
 }
-export class Page {
+class PageImpl {
     #runtime;
     #handlePromise = null;
     constructor(input) {
@@ -186,7 +199,7 @@ export class Page {
     sessionId;
     browserSessionId;
     locator(selector) {
-        return new Locator({ page: this, selector });
+        return new LocatorImpl({ page: this, selector });
     }
     async goto(url, options = {}) {
         const handle = await this.#getHandle();
@@ -581,7 +594,7 @@ export class Page {
         return this.#handlePromise;
     }
 }
-export class Locator {
+class LocatorImpl {
     page;
     selector;
     constructor(input) {
@@ -619,13 +632,14 @@ export class Locator {
         return this.page.waitForSelector(this.selector, options);
     }
     locator(selector) {
-        return new Locator({
+        return new LocatorImpl({
             page: this.page,
             selector: `${this.selector} ${selector}`,
         });
     }
 }
-export const chromium = new BrowserType();
+export const chromium = new BrowserTypeImpl("chromium");
+export const firefox = new BrowserTypeImpl("firefox");
 export async function ping() {
     const runtime = await getRuntime();
     return new Promise((resolve, reject) => {
@@ -639,24 +653,34 @@ export async function ping() {
     });
 }
 export async function launchChrome(options = {}) {
+    return launchBrowser("chromium", options);
+}
+export async function launchConfiguredBrowser(config) {
+    return launchBrowser(config.browserName, {
+        ...config.launchOptions,
+        browserBinary: config.browserBinary ?? config.launchOptions.browserBinary,
+    });
+}
+export async function launchBrowser(browserKind, options = {}) {
     const runtime = await getRuntime();
     const stream = runtime.client.BrowserSession();
     const queue = bindStreamQueue(stream);
     stream.write({
-        launchChrome: {
-            chromeBinary: options.chromeBinary,
+        launchBrowser: {
+            browserKind: browserKind === "firefox" ? 2 : 1,
+            browserBinary: options.browserBinary,
             retryOptions: options.timeoutMs ? { timeoutMs: options.timeoutMs } : undefined,
         },
     });
     while (true) {
         const event = await queue.next();
-        if (event.chromeLaunched) {
-            return new Browser({
+        if (event.browserLaunched) {
+            return new BrowserImpl({
                 runtime,
                 stream,
                 queue,
                 sessionId: event.sessionId ?? "",
-                chromeLaunched: event.chromeLaunched,
+                launched: event.browserLaunched,
             });
         }
         if (event.error?.message) {
@@ -676,6 +700,55 @@ export async function shutdown() {
     runtime.client.close();
     runtimePromise = null;
 }
+export function findConfigFile(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        for (const filename of CONFIG_FILENAMES) {
+            const candidate = path.join(currentDir, filename);
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+export function loadConfigFile(configFile) {
+    const resolved = path.resolve(configFile);
+    const raw = fs.readFileSync(resolved, "utf8");
+    const parsed = parseConfigContents(raw, resolved);
+    validateConfigShape(parsed, resolved);
+    return parsed;
+}
+export function resolveConfig(options = {}) {
+    const configFilePath = options.configFile ? path.resolve(options.configFile) : findConfigFile(options.cwd);
+    const fileConfig = configFilePath ? loadConfigFile(configFilePath) : {};
+    const suiteName = options.suite?.trim() || null;
+    const suiteConfig = suiteName ? fileConfig.suites?.[suiteName] : undefined;
+    if (suiteName && !suiteConfig) {
+        throw new Error(`allwright config suite "${suiteName}" was not found in ${configFilePath ?? "the resolved config file"}`);
+    }
+    const serverAddr = suiteConfig?.server?.addr ?? fileConfig.server?.addr;
+    const browserName = suiteConfig?.browser?.name ?? fileConfig.browser?.name ?? "chromium";
+    const browserBinary = suiteConfig?.browser?.binary ?? fileConfig.browser?.binary;
+    const launchOptions = mergeLaunchOptions(fileConfig.browser?.launchOptions, suiteConfig?.browser?.launchOptions);
+    const expect = {
+        ...(fileConfig.expect ?? {}),
+        ...(suiteConfig?.expect ?? {}),
+    };
+    return {
+        configFilePath,
+        suiteName,
+        serverAddr,
+        browserName,
+        browserBinary,
+        launchOptions: browserBinary ? { ...launchOptions, browserBinary } : launchOptions,
+        expect,
+    };
+}
 async function getRuntime() {
     if (!runtimePromise) {
         runtimePromise = Promise.resolve(createRuntime());
@@ -702,6 +775,124 @@ function configuredServerAddr() {
     }
     return normalizeServerAddr(process.env[SERVER_ADDR_ENV_VAR] ?? DEFAULT_SERVER_ADDR);
 }
+function mergeLaunchOptions(base, override) {
+    return {
+        ...(base ?? {}),
+        ...(override ?? {}),
+    };
+}
+function validateConfigShape(value, source) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`allwright config ${source} must contain a top-level object`);
+    }
+    const config = value;
+    if (config.schemaVersion !== undefined && config.schemaVersion !== 1) {
+        throw new Error(`allwright config ${source} has unsupported schemaVersion ${String(config.schemaVersion)}; expected 1`);
+    }
+    const browserName = config.browser?.name;
+    if (browserName !== undefined && browserName !== "chromium" && browserName !== "firefox") {
+        throw new Error(`allwright config ${source} has unsupported browser.name ${String(browserName)}; use "chromium" or "firefox"`);
+    }
+}
+function parseConfigContents(raw, source) {
+    const extension = path.extname(source).toLowerCase();
+    if (extension === ".json") {
+        return JSON.parse(raw);
+    }
+    if (extension === ".yaml" || extension === ".yml") {
+        return parseSimpleYaml(raw, source);
+    }
+    throw new Error(`unsupported allwright config file extension ${extension || "<none>"} for ${source}`);
+}
+function parseSimpleYaml(raw, source) {
+    const root = {};
+    const stack = [
+        { indent: -1, value: root },
+    ];
+    for (const [index, originalLine] of raw.split(/\r?\n/).entries()) {
+        const lineNumber = index + 1;
+        const line = stripYamlComment(originalLine);
+        if (!line.trim()) {
+            continue;
+        }
+        const indent = countLeadingSpaces(line);
+        if (indent % 2 !== 0) {
+            throw new Error(`invalid YAML indentation in ${source}:${lineNumber}; use multiples of 2 spaces`);
+        }
+        while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+            stack.pop();
+        }
+        const current = stack[stack.length - 1];
+        const trimmed = line.trim();
+        const separatorIndex = trimmed.indexOf(":");
+        if (separatorIndex <= 0) {
+            throw new Error(`invalid YAML mapping in ${source}:${lineNumber}`);
+        }
+        const key = trimmed.slice(0, separatorIndex).trim();
+        const rawValue = trimmed.slice(separatorIndex + 1).trim();
+        if (!key) {
+            throw new Error(`empty YAML key in ${source}:${lineNumber}`);
+        }
+        if (!rawValue) {
+            const child = {};
+            current.value[key] = child;
+            stack.push({ indent, value: child });
+            continue;
+        }
+        current.value[key] = parseYamlScalar(rawValue, source, lineNumber);
+    }
+    return root;
+}
+function stripYamlComment(line) {
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+            continue;
+        }
+        if (char === "\"" && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+            continue;
+        }
+        if (char === "#" && !inSingleQuote && !inDoubleQuote) {
+            return line.slice(0, index);
+        }
+    }
+    return line;
+}
+function countLeadingSpaces(line) {
+    let count = 0;
+    while (count < line.length && line[count] === " ") {
+        count += 1;
+    }
+    return count;
+}
+function parseYamlScalar(value, source, lineNumber) {
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    if (value === "null") {
+        return null;
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    if (/^-?\d+\.\d+$/.test(value)) {
+        return Number.parseFloat(value);
+    }
+    if (value.startsWith("[") || value.startsWith("{")) {
+        throw new Error(`unsupported YAML collection syntax in ${source}:${lineNumber}; use nested mappings instead`);
+    }
+    return value;
+}
 function normalizeServerAddr(raw) {
     const trimmed = raw.trim();
     if (trimmed.startsWith("dns:") || trimmed.startsWith("unix:")) {

package/package.json

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

package/proto/core/v1/browser.proto

@@ -12,6 +12,7 @@ message BrowserSessionCommand {
     OpenTabCommand open_tab = 2;
     SessionPingCommand ping = 3;
     CloseBrowserSessionCommand close = 4;
+    LaunchBrowserCommand launch_browser = 5;
   }
 }
 
@@ -34,6 +35,7 @@ message BrowserSessionEvent {
     SessionPongEvent pong = 4;
     BrowserSessionClosedEvent closed = 5;
     BrowserSessionErrorEvent error = 6;
+    BrowserLaunchedEvent browser_launched = 7;
   }
 }
 

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

@@ -5,6 +5,26 @@ option go_package = "allwright.dev/gen/allwright/engine/v1;enginev1";
 
 import "core/v1/common.proto";
 
+enum BrowserKind {
+  BROWSER_KIND_UNSPECIFIED = 0;
+  BROWSER_KIND_CHROMIUM = 1;
+  BROWSER_KIND_FIREFOX = 2;
+}
+
+message LaunchBrowserCommand {
+  BrowserKind browser_kind = 1;
+  optional string browser_binary = 2;
+  optional CommandRetryOptions retry_options = 3;
+}
+
+message BrowserLaunchedEvent {
+  BrowserKind browser_kind = 1;
+  string browser = 2;
+  string note = 3;
+  string user_data_dir = 4;
+  string initial_tab_session_id = 5;
+}
+
 message LaunchChromeCommand {
   optional string chrome_binary = 1;
   optional CommandRetryOptions retry_options = 2;