@allwright.dev/core 0.0.35 → 0.0.37

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

@@ -2,6 +2,7 @@ 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";
@@ -103,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.35",
+  "version": "0.0.37",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",