@allwright.dev/core 0.0.34 → 0.0.36

package/dist/bootstrap.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureRuntimeReady(serverAddr: string): Promise<void>;
+export declare function shutdownManagedServer(): Promise<void>;

package/dist/bootstrap.js

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import grpc from "@grpc/grpc-js";
+import protoLoader from "@grpc/proto-loader";
+const ALLWRIGHT_AUTO_INSTALL_ENV_VAR = "ALLWRIGHT_AUTO_INSTALL";
+const ALLWRIGHT_CLI_PATH_ENV_VAR = "ALLWRIGHT_CLI_PATH";
+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.0.1";
+const STARTUP_TIMEOUT_MS = 20_000;
+const PING_TIMEOUT_MS = 1_000;
+const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));
+const ENGINE_PROTO_PATH = fileURLToPath(new URL("../proto/engine/v1/engine.proto", import.meta.url));
+let managedServer = null;
+let managedServerAddr = null;
+export async function ensureRuntimeReady(serverAddr) {
+    if (await pingServer(serverAddr)) {
+        return;
+    }
+    if (!isLocalServerAddr(serverAddr)) {
+        throw new Error(`allwright could not reach engine server at ${serverAddr}. Automatic startup is only supported for local addresses.`);
+    }
+    if (managedServer && !managedServer.killed && managedServer.exitCode === null && managedServerAddr === serverAddr) {
+        await waitForServer(serverAddr);
+        return;
+    }
+    const cliPath = await ensureCliAvailable();
+    ensureWebPlugin(cliPath);
+    managedServer = spawn(cliPath, ["serve", "--listen-addr", cliListenAddr(serverAddr)], {
+        stdio: "ignore",
+    });
+    managedServerAddr = serverAddr;
+    await waitForServer(serverAddr);
+}
+export async function shutdownManagedServer() {
+    if (managedServer && managedServer.exitCode === null && !managedServer.killed) {
+        managedServer.kill("SIGTERM");
+    }
+    managedServer = null;
+    managedServerAddr = null;
+}
+async function waitForServer(serverAddr) {
+    const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await pingServer(serverAddr)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    await shutdownManagedServer();
+    throw new Error(`timed out waiting for allwright server at ${serverAddr} to become ready`);
+}
+async function pingServer(serverAddr) {
+    const loaded = protoLoader.loadSync(ENGINE_PROTO_PATH, {
+        includeDirs: [PROTO_ROOT],
+        keepCase: false,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    const proto = grpc.loadPackageDefinition(loaded);
+    const client = new proto.allwright.engine.v1.EngineService(serverAddr, grpc.credentials.createInsecure());
+    return await new Promise((resolve) => {
+        client.Ping({}, new grpc.Metadata(), { deadline: new Date(Date.now() + PING_TIMEOUT_MS) }, (error) => {
+            client.close();
+            resolve(!error);
+        });
+    });
+}
+async function ensureCliAvailable() {
+    const envPath = process.env[ALLWRIGHT_CLI_PATH_ENV_VAR]?.trim();
+    if (envPath && isFile(envPath)) {
+        return envPath;
+    }
+    const bundled = path.join(allwrightHome(), "bin", cliFilename());
+    if (isFile(bundled)) {
+        return bundled;
+    }
+    const fromPath = resolveFromPath(cliFilename());
+    if (fromPath) {
+        return fromPath;
+    }
+    if (!autoInstallEnabled()) {
+        throw new Error("allwright CLI was not found. Install it first or set ALLWRIGHT_CLI_PATH.");
+    }
+    return await installCli();
+}
+async function installCli() {
+    const installDir = path.join(allwrightHome(), "bin");
+    fs.mkdirSync(installDir, { recursive: true });
+    const cliPath = path.join(installDir, cliFilename());
+    const versionTag = await resolveReleaseTag();
+    const assetName = cliAssetName(versionTag);
+    const assetPath = path.join(os.tmpdir(), assetName);
+    const response = await fetch(`https://github.com/${releaseRepository()}/releases/download/${versionTag}/${assetName}`, { headers: { "user-agent": `allwright-ts/${DEFAULT_RELEASE_VERSION}` } });
+    if (!response.ok) {
+        throw new Error(`failed to download allwright CLI asset ${assetName}: ${response.status} ${response.statusText}`);
+    }
+    fs.writeFileSync(assetPath, Buffer.from(await response.arrayBuffer()));
+    extractCliArchive(assetPath, cliPath);
+    fs.chmodSync(cliPath, 0o755);
+    fs.rmSync(assetPath, { force: true });
+    return cliPath;
+}
+function ensureWebPlugin(cliPath) {
+    const pluginPath = path.join(allwrightHome(), "plugins", "web", "lib", webPluginFilename());
+    if (isFile(pluginPath)) {
+        return;
+    }
+    const version = process.env[ALLWRIGHT_VERSION_ENV_VAR]?.trim() || DEFAULT_RELEASE_VERSION;
+    const result = spawnSync(cliPath, ["plugin", "install", "web", "--version", normalizeReleaseVersion(version)], {
+        stdio: "ignore",
+    });
+    if (result.status !== 0 || !isFile(pluginPath)) {
+        throw new Error("allwright attempted to install the `web` plugin automatically, but the install did not complete successfully");
+    }
+}
+async function resolveReleaseTag() {
+    const version = process.env[ALLWRIGHT_VERSION_ENV_VAR]?.trim() || DEFAULT_RELEASE_VERSION;
+    if (version !== "latest") {
+        return normalizeReleaseTag(version);
+    }
+    const response = await fetch(`https://api.github.com/repos/${releaseRepository()}/releases/latest`, {
+        headers: { "user-agent": `allwright-ts/${DEFAULT_RELEASE_VERSION}` },
+    });
+    if (!response.ok) {
+        throw new Error(`failed to resolve latest allwright release: ${response.status} ${response.statusText}`);
+    }
+    const payload = (await response.json());
+    if (!payload.tag_name?.trim()) {
+        throw new Error("latest allwright release metadata did not include tag_name");
+    }
+    return payload.tag_name;
+}
+function extractCliArchive(archivePath, cliPath) {
+    if (archivePath.endsWith(".zip")) {
+        const result = spawnSync("powershell", [
+            "-NoProfile",
+            "-Command",
+            `Expand-Archive -Path '${archivePath.replaceAll("'", "''")}' -DestinationPath '${path.dirname(cliPath).replaceAll("'", "''")}' -Force`,
+        ], { stdio: "ignore" });
+        if (result.status !== 0) {
+            throw new Error("failed to extract allwright CLI zip archive");
+        }
+        const extracted = path.join(path.dirname(cliPath), "bin", cliFilename());
+        fs.copyFileSync(extracted, cliPath);
+        fs.rmSync(path.join(path.dirname(cliPath), "bin"), { recursive: true, force: true });
+        return;
+    }
+    const result = spawnSync("tar", [
+        "-xzf",
+        archivePath,
+        "-C",
+        path.dirname(cliPath),
+        `bin/${cliFilename()}`,
+    ], { stdio: "ignore" });
+    if (result.status !== 0) {
+        throw new Error("failed to extract allwright CLI tar archive");
+    }
+    const extracted = path.join(path.dirname(cliPath), "bin", cliFilename());
+    fs.copyFileSync(extracted, cliPath);
+    fs.rmSync(path.join(path.dirname(cliPath), "bin"), { recursive: true, force: true });
+}
+function cliAssetName(versionTag) {
+    const targets = new Map([
+        ["darwin/arm64", "aarch64-apple-darwin"],
+        ["darwin/x64", "x86_64-apple-darwin"],
+        ["linux/arm64", "aarch64-unknown-linux-gnu"],
+        ["linux/x64", "x86_64-unknown-linux-gnu"],
+        ["win32/arm64", "aarch64-pc-windows-msvc"],
+        ["win32/x64", "x86_64-pc-windows-msvc"],
+    ]);
+    const target = targets.get(`${process.platform}/${process.arch}`);
+    if (!target) {
+        throw new Error(`automatic allwright CLI install is not supported on ${process.platform}/${process.arch}`);
+    }
+    const extension = process.platform === "win32" ? "zip" : "tar.gz";
+    return `allwright-${versionTag}-${target}.${extension}`;
+}
+function normalizeReleaseTag(version) {
+    return version.startsWith("v") ? version : `v${version}`;
+}
+function normalizeReleaseVersion(version) {
+    return version.replace(/^v/, "");
+}
+function cliListenAddr(serverAddr) {
+    return serverAddr.replace(/^https?:\/\//, "");
+}
+function isLocalServerAddr(serverAddr) {
+    const host = cliListenAddr(serverAddr).split(":")[0]?.replace(/^\[|\]$/g, "") ?? "";
+    return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+function allwrightHome() {
+    return process.env[ALLWRIGHT_HOME_ENV_VAR]?.trim() || path.join(os.homedir(), ".allwright");
+}
+function cliFilename() {
+    return process.platform === "win32" ? "allwright.exe" : "allwright";
+}
+function webPluginFilename() {
+    if (process.platform === "darwin") {
+        return "liballwright_surface_web.dylib";
+    }
+    if (process.platform === "win32") {
+        return "allwright_surface_web.dll";
+    }
+    return "liballwright_surface_web.so";
+}
+function autoInstallEnabled() {
+    const raw = process.env[ALLWRIGHT_AUTO_INSTALL_ENV_VAR]?.trim().toLowerCase();
+    return raw !== "0" && raw !== "false" && raw !== "no";
+}
+function resolveFromPath(filename) {
+    for (const entry of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!entry) {
+            continue;
+        }
+        const candidate = path.join(entry, filename);
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function releaseRepository() {
+    return process.env[ALLWRIGHT_REPOSITORY_ENV_VAR]?.trim() || DEFAULT_RELEASE_REPOSITORY;
+}
+function isFile(candidate) {
+    try {
+        return fs.statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/browser.js

@@ -1,4 +1,5 @@
 import { PageImpl } from "./page.js";
+import { formatActionError } from "./errors.js";
 export class BrowserTypeImpl {
     #browserKind;
     constructor(browserKind = "chromium") {
@@ -61,7 +62,7 @@ export class BrowserImpl {
                 return this.#createPage(event.tabOpened.tabSessionId);
             }
             if (event.error?.message) {
-                throw new Error(`browser session error while opening tab: ${event.error.message}`);
+                throw formatActionError("open tab", event.error.message);
             }
         }
     }
@@ -80,7 +81,7 @@ export class BrowserImpl {
                 return;
             }
             if (event.error?.message) {
-                throw new Error(`browser session error while closing: ${event.error.message}`);
+                throw formatActionError("close browser", event.error.message);
             }
         }
     }
@@ -97,7 +98,7 @@ export class BrowserImpl {
                 return event.pong.message;
             }
             if (event.error?.message) {
-                throw new Error(`browser session error while pinging: ${event.error.message}`);
+                throw formatActionError("ping browser", event.error.message);
             }
         }
     }
@@ -131,7 +132,7 @@ export class BrowserImpl {
     }
     #ensureOpen() {
         if (this.#closed) {
-            throw new Error(`browser session ${this.sessionId} is closed`);
+            throw formatActionError("use browser", `browser session ${this.sessionId} is closed`);
         }
     }
 }

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class AllwrightError extends Error {
+    readonly debugDetails?: string;
+    constructor(message: string, debugDetails?: string);
+}
+export declare function formatStreamError(raw: string): AllwrightError;
+export declare function formatActionError(action: string, raw: string, locator?: string): AllwrightError;

package/dist/errors.js

@@ -0,0 +1,120 @@
+export class AllwrightError extends Error {
+    debugDetails;
+    constructor(message, debugDetails) {
+        super(message);
+        this.name = "AllwrightError";
+        this.debugDetails = debugDetails;
+    }
+}
+export function formatStreamError(raw) {
+    const normalized = stripTransportPrefix(raw);
+    const evaluated = extractEvaluateMessage(normalized);
+    return createError(evaluated.userMessage, raw, evaluated.debugDetails);
+}
+export function formatActionError(action, raw, locator) {
+    const normalized = stripTransportPrefix(raw);
+    const evaluated = extractEvaluateMessage(normalized);
+    const locatorLabel = locator ? ` for locator ${formatLocator(locator)}` : "";
+    const message = evaluated.userMessage
+        ? `${capitalize(action)} failed${locatorLabel}: ${evaluated.userMessage}`
+        : `${capitalize(action)} failed${locatorLabel}.`;
+    return createError(message, raw, evaluated.debugDetails);
+}
+function createError(message, raw, debugDetails) {
+    if (debugEnabled()) {
+        return new AllwrightError(`${message}\n\nDebug details: ${debugDetails ?? raw}`, debugDetails ?? raw);
+    }
+    return new AllwrightError(message, debugDetails ?? raw);
+}
+function extractEvaluateMessage(raw) {
+    const exceptionMarker = "Runtime.evaluate failed with exception details:";
+    const mapperMarker = "mapper Runtime.evaluate raised exception details:";
+    const marker = raw.includes(exceptionMarker)
+        ? exceptionMarker
+        : raw.includes(mapperMarker)
+            ? mapperMarker
+            : null;
+    if (!marker) {
+        return { userMessage: cleanupUserMessage(raw) };
+    }
+    const payload = raw.slice(raw.indexOf(marker) + marker.length).trim();
+    const parsed = tryParseJson(payload);
+    const message = pickString(parsed, ["exception", "message"]) ??
+        pickPreviewProperty(parsed, "message") ??
+        pickString(parsed, ["exception", "description"]) ??
+        raw;
+    return {
+        userMessage: cleanupUserMessage(message),
+        debugDetails: payload,
+    };
+}
+function cleanupUserMessage(message) {
+    const compact = message.replace(/\s+/g, " ").trim();
+    const invalidQuerySelector = compact.match(/Failed to execute 'querySelector(All)?' on 'Document': '(.+?)' is not a valid selector\.?/);
+    if (invalidQuerySelector) {
+        return `invalid selector ${invalidQuerySelector[2]}`;
+    }
+    return compact
+        .replace(/^SyntaxError:\s*/i, "")
+        .replace(/^DOMException:\s*/i, "")
+        .replace(/^Error:\s*/i, "");
+}
+function stripTransportPrefix(raw) {
+    return raw
+        .replace(/^grpc stream error:\s*/i, "")
+        .replace(/^\d+\s+INTERNAL:\s*/i, "")
+        .trim();
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function formatLocator(locator) {
+    return JSON.stringify(locator.trim());
+}
+function debugEnabled() {
+    const raw = process.env.ALLWRIGHT_DEBUG?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+function tryParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function pickString(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (!current || typeof current !== "object" || !(segment in current)) {
+            return null;
+        }
+        current = current[segment];
+    }
+    return typeof current === "string" && current.trim() ? current.trim() : null;
+}
+function pickPreviewProperty(root, name) {
+    const properties = pickUnknown(root, ["exception", "preview", "properties"]);
+    if (!Array.isArray(properties)) {
+        return null;
+    }
+    for (const property of properties) {
+        if (property &&
+            typeof property === "object" &&
+            property.name === name &&
+            typeof property.value === "string") {
+            return (property.value ?? "").trim() || null;
+        }
+    }
+    return null;
+}
+function pickUnknown(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (!current || typeof current !== "object" || !(segment in current)) {
+            return null;
+        }
+        current = current[segment];
+    }
+    return current;
+}

package/dist/index.js

@@ -1,4 +1,5 @@
 import { BrowserImpl, BrowserTypeImpl } from "./browser.js";
+import { formatActionError } from "./errors.js";
 import { findConfigFile, loadConfigFile, resolveConfig } from "./config.js";
 import { PageImpl } from "./page.js";
 import { createBrowserSessionHandle, getRuntime, launchConfiguredBrowser as launchConfiguredBrowserWithResolver, ping as runtimePing, resolveLaunchBrowserArgs, setServerAddr, shutdown, } from "./runtime.js";
@@ -42,7 +43,7 @@ export async function launchBrowser(browserKindOrOptions, options = {}) {
             });
         }
         if (event.error?.message) {
-            throw new Error(`browser session error during launch: ${event.error.message}`);
+            throw formatActionError("launch browser", event.error.message);
         }
     }
 }

package/dist/page.js

@@ -1,4 +1,5 @@
 import { LocatorImpl } from "./locator.js";
+import { formatActionError } from "./errors.js";
 import { normalizeSelectorForTransport } from "./selectors.js";
 import { createPageHandle } from "./runtime.js";
 export class PageImpl {
@@ -36,7 +37,7 @@ export class PageImpl {
                 injection = event.chromiumBidiInjection;
             }
             if (event.error?.message) {
-                throw new Error(`page session error while navigating: ${event.error.message}`);
+                throw formatActionError("navigate", event.error.message);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -76,7 +77,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while clicking: ${event.error.message}`);
+                throw formatActionError("click", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -106,7 +107,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while counting elements: ${event.error.message}`);
+                throw formatActionError("count elements", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -137,7 +138,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while highlighting elements: ${event.error.message}`);
+                throw formatActionError("highlight elements", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -166,7 +167,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while focusing: ${event.error.message}`);
+                throw formatActionError("focus", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -197,7 +198,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while filling: ${event.error.message}`);
+                throw formatActionError("fill", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -226,7 +227,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while hovering: ${event.error.message}`);
+                throw formatActionError("hover", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -258,7 +259,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while pressing key: ${event.error.message}`);
+                throw formatActionError("press key", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -295,7 +296,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while waiting for selector: ${event.error.message}`);
+                throw formatActionError("wait for selector", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -321,7 +322,7 @@ export class PageImpl {
                 return;
             }
             if (event.error?.message) {
-                throw new Error(`page session error while closing: ${event.error.message}`);
+                throw formatActionError("close page", event.error.message);
             }
         }
     }
@@ -341,7 +342,7 @@ export class PageImpl {
                 return event.pong.message;
             }
             if (event.error?.message) {
-                throw new Error(`page session error while pinging: ${event.error.message}`);
+                throw formatActionError("ping page", event.error.message);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -396,7 +397,7 @@ export class PageImpl {
                 };
             }
             if (event.error?.message) {
-                throw new Error(`page session error while reading text: ${event.error.message}`);
+                throw formatActionError("read text", event.error.message, selector);
             }
             if (event.closed) {
                 handle.closed = true;
@@ -406,7 +407,7 @@ export class PageImpl {
     }
     #ensureOpen(handle) {
         if (handle.closed) {
-            throw new Error(`page session ${this.sessionId} is closed`);
+            throw formatActionError("use page", `page session ${this.sessionId} is closed`);
         }
     }
     async #getHandle() {

package/dist/runtime.js

@@ -1,6 +1,8 @@
 import { fileURLToPath } from "node:url";
 import grpc from "@grpc/grpc-js";
 import protoLoader from "@grpc/proto-loader";
+import { ensureRuntimeReady, shutdownManagedServer } from "./bootstrap.js";
+import { formatStreamError } from "./errors.js";
 import { EventQueue } from "./types.js";
 const DEFAULT_SERVER_ADDR = "127.0.0.1:50051";
 const SERVER_ADDR_ENV_VAR = "ALLWRIGHT_SERVER_ADDR";
@@ -11,6 +13,7 @@ let serverAddrOverride = null;
 export function setServerAddr(serverAddr) {
     serverAddrOverride = normalizeServerAddr(serverAddr);
     runtimePromise = null;
+    void shutdownManagedServer();
 }
 export async function shutdown() {
     if (!runtimePromise) {
@@ -19,6 +22,7 @@ export async function shutdown() {
     const runtime = await runtimePromise;
     runtime.client.close();
     runtimePromise = null;
+    await shutdownManagedServer();
 }
 export async function ping() {
     const runtime = await getRuntime();
@@ -34,7 +38,7 @@ export async function ping() {
 }
 export async function getRuntime() {
     if (!runtimePromise) {
-        runtimePromise = Promise.resolve(createRuntime());
+        runtimePromise = createRuntime();
     }
     return runtimePromise;
 }
@@ -72,7 +76,9 @@ export function normalizeServerAddr(raw) {
 export function resolveLaunchBrowserArgs(browserKindOrOptions) {
     return browserKindOrOptions === undefined || typeof browserKindOrOptions !== "string";
 }
-function createRuntime() {
+async function createRuntime() {
+    const serverAddr = configuredServerAddr();
+    await ensureRuntimeReady(serverAddr);
     const loaded = protoLoader.loadSync(ENGINE_PROTO_PATH, {
         includeDirs: [PROTO_ROOT],
         keepCase: false,
@@ -83,7 +89,7 @@ function createRuntime() {
     });
     const proto = grpc.loadPackageDefinition(loaded);
     const ClientCtor = proto.allwright.engine.v1.EngineService;
-    const client = new ClientCtor(configuredServerAddr(), grpc.credentials.createInsecure());
+    const client = new ClientCtor(serverAddr, grpc.credentials.createInsecure());
     return { client };
 }
 function configuredServerAddr() {
@@ -98,7 +104,7 @@ function bindStreamQueue(stream) {
         queue.push(event);
     });
     stream.on("error", (error) => {
-        queue.fail(new Error(`grpc stream error: ${error.message}`));
+        queue.fail(formatStreamError(`grpc stream error: ${error.message}`));
     });
     stream.on("end", () => {
         queue.fail(new Error("grpc stream ended"));

package/dist/selectors.js

@@ -1,11 +1,92 @@
+const SELECTOR_PREFIXES = ["xpath=", "xpath:", "css=", "css:"];
+function decodeSelectorBody(body) {
+    const candidate = body.trim();
+    if (candidate.startsWith("\"") && candidate.endsWith("\"")) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            return candidate;
+        }
+    }
+    return candidate;
+}
+function parseExplicitSelectorPrefix(selector) {
+    const lowered = selector.toLowerCase();
+    if (lowered.startsWith("xpath=") || lowered.startsWith("xpath:")) {
+        return { flavor: "xpath", prefixLength: 6 };
+    }
+    if (lowered.startsWith("css=") || lowered.startsWith("css:")) {
+        return { flavor: "css", prefixLength: 4 };
+    }
+    return null;
+}
+function findJsonStringEnd(value) {
+    if (!value.startsWith("\"")) {
+        return null;
+    }
+    let escaped = false;
+    for (let index = 1; index < value.length; index += 1) {
+        const char = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === "\"") {
+            return index + 1;
+        }
+    }
+    return null;
+}
+function isNormalizedTransportSelector(selector) {
+    const trimmed = selector.trim();
+    if (!trimmed) {
+        return false;
+    }
+    let index = 0;
+    while (index < trimmed.length) {
+        const prefix = parseExplicitSelectorPrefix(trimmed.slice(index));
+        if (!prefix) {
+            return false;
+        }
+        index += prefix.prefixLength;
+        const remainder = trimmed.slice(index);
+        if (!remainder.startsWith("\"")) {
+            return false;
+        }
+        const jsonEnd = findJsonStringEnd(remainder);
+        if (!jsonEnd) {
+            return false;
+        }
+        index += jsonEnd;
+        const tail = trimmed.slice(index);
+        if (!tail) {
+            return true;
+        }
+        if (!/^\s+/.test(tail)) {
+            return false;
+        }
+        const nextIndex = index + tail.match(/^\s+/)?.[0].length;
+        const nextSegment = trimmed.slice(nextIndex).toLowerCase();
+        if (!SELECTOR_PREFIXES.some((prefixValue) => nextSegment.startsWith(prefixValue))) {
+            return false;
+        }
+        index = nextIndex;
+    }
+    return true;
+}
 export function parseSelectorForTransport(selector) {
     const trimmed = selector.trim();
     const lower = trimmed.toLowerCase();
     if (lower.startsWith("xpath=") || lower.startsWith("xpath:")) {
-        return { flavor: "xpath", body: trimmed.slice(6).trim() };
+        return { flavor: "xpath", body: decodeSelectorBody(trimmed.slice(6)) };
     }
     if (lower.startsWith("css=") || lower.startsWith("css:")) {
-        return { flavor: "css", body: trimmed.slice(4).trim() };
+        return { flavor: "css", body: decodeSelectorBody(trimmed.slice(4)) };
     }
     if (trimmed.startsWith("//") ||
         trimmed.startsWith(".//") ||
@@ -17,6 +98,10 @@ export function parseSelectorForTransport(selector) {
     return { flavor: "css", body: trimmed };
 }
 export function normalizeSelectorForTransport(selector) {
+    const trimmed = selector.trim();
+    if (isNormalizedTransportSelector(trimmed)) {
+        return trimmed;
+    }
     const parsed = parseSelectorForTransport(selector);
     return `${parsed.flavor}=${JSON.stringify(parsed.body)}`;
 }

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import grpc from "@grpc/grpc-js";
+export { AllwrightError } from "./errors.js";
 export interface LaunchOptions {
     browserBinary?: string;
     timeoutMs?: number;

package/dist/types.js

@@ -1,3 +1,4 @@
+export { AllwrightError } from "./errors.js";
 export class EventQueue {
     #items = [];
     #waiters = [];

package/package.json

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