@aria-cli/tools 1.0.12 → 1.0.13

package/dist-cjs/definitions/browser/pw-interactions.js

@@ -1,213 +0,0 @@
-"use strict";
-// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
-// https://github.com/openclaw/openclaw
-// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.refLocator = refLocator;
-exports.clickViaPlaywright = clickViaPlaywright;
-exports.hoverViaPlaywright = hoverViaPlaywright;
-exports.dragViaPlaywright = dragViaPlaywright;
-exports.typeViaPlaywright = typeViaPlaywright;
-exports.selectOptionViaPlaywright = selectOptionViaPlaywright;
-exports.pressKeyViaPlaywright = pressKeyViaPlaywright;
-exports.evaluateViaPlaywright = evaluateViaPlaywright;
-exports.takeScreenshot = takeScreenshot;
-exports.scrollPage = scrollPage;
-exports.waitForCondition = waitForCondition;
-exports.uploadFiles = uploadFiles;
-const pw_shared_js_1 = require("./pw-shared.js");
-// ── Ref locator ───────────────────────────────────────────────────────
-/**
- * Resolve a ref string (e.g. "e1") into a Playwright Locator using the
- * role-ref map from the last snapshot.
- */
-function refLocator(page, ref, refs) {
-    const normalized = ref.startsWith("@")
-        ? ref.slice(1)
-        : ref.startsWith("ref=")
-            ? ref.slice(4)
-            : ref;
-    if (/^e\d+$/.test(normalized)) {
-        const info = refs[normalized];
-        if (!info) {
-            throw new Error(`Unknown ref "${normalized}". Run a new snapshot and use a ref from that snapshot.`);
-        }
-        const locator = info.name
-            ? page.getByRole(info.role, { name: info.name, exact: true })
-            : page.getByRole(info.role);
-        return info.nth !== undefined ? locator.nth(info.nth) : locator;
-    }
-    // Fallback: treat as CSS selector
-    return page.locator(normalized);
-}
-// ── Click ─────────────────────────────────────────────────────────────
-async function clickViaPlaywright(opts) {
-    const ref = (0, pw_shared_js_1.requireRef)(opts.ref);
-    const locator = refLocator(opts.page, ref, opts.refs);
-    const timeout = (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeoutMs, 8000);
-    try {
-        if (opts.doubleClick) {
-            await locator.dblclick({
-                timeout,
-                button: opts.button,
-                modifiers: opts.modifiers,
-            });
-        }
-        else {
-            await locator.click({
-                timeout,
-                button: opts.button,
-                modifiers: opts.modifiers,
-            });
-        }
-    }
-    catch (err) {
-        throw (0, pw_shared_js_1.toAIFriendlyError)(err, ref);
-    }
-}
-// ── Hover ─────────────────────────────────────────────────────────────
-async function hoverViaPlaywright(opts) {
-    const ref = (0, pw_shared_js_1.requireRef)(opts.ref);
-    try {
-        await refLocator(opts.page, ref, opts.refs).hover({
-            timeout: (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeoutMs, 8000),
-        });
-    }
-    catch (err) {
-        throw (0, pw_shared_js_1.toAIFriendlyError)(err, ref);
-    }
-}
-// ── Drag ──────────────────────────────────────────────────────────────
-async function dragViaPlaywright(opts) {
-    const startRef = (0, pw_shared_js_1.requireRef)(opts.startRef);
-    const endRef = (0, pw_shared_js_1.requireRef)(opts.endRef);
-    try {
-        await refLocator(opts.page, startRef, opts.refs).dragTo(refLocator(opts.page, endRef, opts.refs), { timeout: (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeoutMs, 8000) });
-    }
-    catch (err) {
-        throw (0, pw_shared_js_1.toAIFriendlyError)(err, `${startRef} -> ${endRef}`);
-    }
-}
-// ── Type ──────────────────────────────────────────────────────────────
-async function typeViaPlaywright(opts) {
-    const text = String(opts.text ?? "");
-    const ref = (0, pw_shared_js_1.requireRef)(opts.ref);
-    const locator = refLocator(opts.page, ref, opts.refs);
-    const timeout = (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeoutMs, 8000);
-    try {
-        if (opts.slowly) {
-            await locator.click({ timeout });
-            await locator.type(text, { timeout, delay: 75 });
-        }
-        else {
-            await locator.fill(text, { timeout });
-        }
-        if (opts.submit) {
-            await locator.press("Enter", { timeout });
-        }
-    }
-    catch (err) {
-        throw (0, pw_shared_js_1.toAIFriendlyError)(err, ref);
-    }
-}
-// ── Select option ─────────────────────────────────────────────────────
-async function selectOptionViaPlaywright(opts) {
-    const ref = (0, pw_shared_js_1.requireRef)(opts.ref);
-    if (!opts.values?.length) {
-        throw new Error("values are required");
-    }
-    try {
-        await refLocator(opts.page, ref, opts.refs).selectOption(opts.values, {
-            timeout: (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeoutMs, 8000),
-        });
-    }
-    catch (err) {
-        throw (0, pw_shared_js_1.toAIFriendlyError)(err, ref);
-    }
-}
-// ── Key press ─────────────────────────────────────────────────────────
-async function pressKeyViaPlaywright(opts) {
-    const key = String(opts.key ?? "").trim();
-    if (!key) {
-        throw new Error("key is required");
-    }
-    await opts.page.keyboard.press(key);
-}
-// ── Evaluate ──────────────────────────────────────────────────────────
-async function evaluateViaPlaywright(opts) {
-    const script = String(opts.script ?? "").trim();
-    if (!script) {
-        throw new Error("script is required");
-    }
-    const evaluateTimeout = (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeoutMs, 20_000);
-    // Inject a timeout wrapper into the browser context so async scripts
-    // don't block the Playwright command queue indefinitely.
-    // We use a string-form evaluate to avoid TypeScript signature conflicts
-    // with our minimal PwPage interface.
-    const wrappedScript = `
-    (function() {
-      var fnBody = ${JSON.stringify(script)};
-      var timeoutMs = ${evaluateTimeout};
-      try {
-        var candidate = eval("(" + fnBody + ")");
-        var result = typeof candidate === "function" ? candidate() : candidate;
-        if (result && typeof result === "object" && typeof result.then === "function") {
-          return Promise.race([
-            result,
-            new Promise(function(_, reject) {
-              setTimeout(function() { reject(new Error("evaluate timed out after " + timeoutMs + "ms")); }, timeoutMs);
-            })
-          ]);
-        }
-        return result;
-      } catch (err) {
-        throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
-      }
-    })()
-  `;
-    const result = await opts.page.evaluate(wrappedScript);
-    return result;
-}
-// ── Screenshot ────────────────────────────────────────────────────────
-async function takeScreenshot(opts) {
-    return opts.page.screenshot({
-        type: "png",
-        fullPage: Boolean(opts.fullPage),
-    });
-}
-// ── Scroll ────────────────────────────────────────────────────────────
-async function scrollPage(opts) {
-    const pixels = Math.max(100, Math.min(5000, opts.amount ?? 500));
-    const deltaY = opts.direction === "up" ? -pixels : pixels;
-    await opts.page.mouse.wheel(0, deltaY);
-    // Give the page a moment to process the scroll
-    await opts.page.waitForTimeout(300);
-}
-// ── Wait ──────────────────────────────────────────────────────────────
-async function waitForCondition(opts) {
-    const timeout = (0, pw_shared_js_1.normalizeTimeoutMs)(opts.timeout, 10_000);
-    if (opts.text) {
-        await opts.page.locator(`text=${opts.text}`).first().waitFor({ state: "visible", timeout });
-        return;
-    }
-    if (opts.selector) {
-        await opts.page.locator(opts.selector).first().waitFor({ state: "visible", timeout });
-        return;
-    }
-    // Default: wait for network idle
-    await opts.page.waitForLoadState("networkidle", { timeout });
-}
-// ── Upload ────────────────────────────────────────────────────────────
-async function uploadFiles(opts) {
-    if (!opts.paths?.length) {
-        throw new Error("paths are required");
-    }
-    const ref = (0, pw_shared_js_1.requireRef)(opts.ref);
-    const locator = refLocator(opts.page, ref, opts.refs);
-    try {
-        await locator.setInputFiles(opts.paths);
-    }
-    catch (err) {
-        throw (0, pw_shared_js_1.toAIFriendlyError)(err, ref);
-    }
-}

package/dist-cjs/definitions/browser/pw-responses.js

@@ -1,84 +0,0 @@
-"use strict";
-// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
-// https://github.com/openclaw/openclaw
-// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_PAGE_ERRORS = exports.MAX_NETWORK_REQUESTS = exports.MAX_CONSOLE_MESSAGES = void 0;
-exports.filterConsoleMessages = filterConsoleMessages;
-exports.filterNetworkRequests = filterNetworkRequests;
-exports.formatConsoleMessages = formatConsoleMessages;
-exports.formatNetworkRequests = formatNetworkRequests;
-exports.formatPageErrors = formatPageErrors;
-// ── Circular buffer limits ────────────────────────────────────────────
-exports.MAX_CONSOLE_MESSAGES = 500;
-exports.MAX_NETWORK_REQUESTS = 500;
-exports.MAX_PAGE_ERRORS = 200;
-// ── Console message filtering ─────────────────────────────────────────
-function consolePriority(level) {
-    switch (level) {
-        case "error":
-            return 3;
-        case "warning":
-            return 2;
-        case "info":
-        case "log":
-            return 1;
-        case "debug":
-            return 0;
-        default:
-            return 1;
-    }
-}
-/**
- * Filter console messages by minimum severity level.
- */
-function filterConsoleMessages(messages, level) {
-    if (!level) {
-        return [...messages];
-    }
-    const min = consolePriority(level);
-    return messages.filter((msg) => consolePriority(msg.type) >= min);
-}
-/**
- * Filter network requests by URL substring match.
- */
-function filterNetworkRequests(requests, filter) {
-    const pattern = typeof filter === "string" ? filter.trim() : "";
-    if (!pattern) {
-        return [...requests];
-    }
-    return requests.filter((r) => r.url.includes(pattern));
-}
-/**
- * Format console messages for tool output.
- */
-function formatConsoleMessages(messages) {
-    if (!messages.length) {
-        return "No console messages captured.";
-    }
-    return messages.map((m) => `[${m.type.toUpperCase()}] ${m.text}`).join("\n");
-}
-/**
- * Format network requests for tool output.
- */
-function formatNetworkRequests(requests) {
-    if (!requests.length) {
-        return "No network requests captured.";
-    }
-    return requests
-        .map((r) => {
-        const status = r.status !== undefined ? ` ${r.status}` : "";
-        const failure = r.failureText ? ` (FAILED: ${r.failureText})` : "";
-        return `${r.method}${status} ${r.url}${failure}`;
-    })
-        .join("\n");
-}
-/**
- * Format page errors for tool output.
- */
-function formatPageErrors(errors) {
-    if (!errors.length) {
-        return "No page errors captured.";
-    }
-    return errors.map((e) => `${e.name ?? "Error"}: ${e.message}`).join("\n");
-}

package/dist-cjs/definitions/browser/pw-session.js

@@ -1,326 +0,0 @@
-"use strict";
-// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
-// https://github.com/openclaw/openclaw
-// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSession = getSession;
-exports.getRefs = getRefs;
-exports.setRefs = setRefs;
-exports.getConsoleMessages = getConsoleMessages;
-exports.getNetworkRequests = getNetworkRequests;
-exports.getPageErrors = getPageErrors;
-exports.setPlaywrightLoaderForTest = setPlaywrightLoaderForTest;
-exports.resolveChromiumLauncher = resolveChromiumLauncher;
-exports.launchBrowser = launchBrowser;
-exports.closeBrowser = closeBrowser;
-exports.listTabs = listTabs;
-exports.newTab = newTab;
-exports.selectTab = selectTab;
-exports.closeTab = closeTab;
-const pw_responses_js_1 = require("./pw-responses.js");
-// ── Module-level state (singleton per Node process) ───────────────────
-let currentSession = null;
-let currentRefs = {};
-const consoleMessages = [];
-const networkRequests = [];
-const pageErrors = [];
-let nextRequestId = 0;
-const DEFAULT_NAVIGATION_OPTIONS = {
-    timeout: 20_000,
-    waitUntil: "domcontentloaded",
-};
-// ── Accessors ─────────────────────────────────────────────────────────
-function getSession() {
-    return currentSession;
-}
-function getRefs() {
-    return currentRefs;
-}
-function setRefs(refs) {
-    currentRefs = refs;
-}
-function getConsoleMessages() {
-    return consoleMessages;
-}
-function getNetworkRequests() {
-    return networkRequests;
-}
-function getPageErrors() {
-    return pageErrors;
-}
-const defaultPlaywrightLoader = () => Function('return import("playwright")')();
-let playwrightLoader = defaultPlaywrightLoader;
-/**
- * Test seam for injecting a mocked playwright loader.
- * Passing null restores the production loader.
- */
-function setPlaywrightLoaderForTest(loader) {
-    playwrightLoader = loader ?? defaultPlaywrightLoader;
-}
-// ── Page listener wiring ──────────────────────────────────────────────
-const observedPages = new WeakSet();
-function wirePageListeners(page) {
-    if (observedPages.has(page)) {
-        return;
-    }
-    observedPages.add(page);
-    page.on("console", (...args) => {
-        const msg = args[0];
-        if (!msg)
-            return;
-        const entry = {
-            type: typeof msg.type === "function" ? msg.type() : "log",
-            text: typeof msg.text === "function" ? msg.text() : String(msg),
-            timestamp: new Date().toISOString(),
-        };
-        consoleMessages.push(entry);
-        if (consoleMessages.length > pw_responses_js_1.MAX_CONSOLE_MESSAGES) {
-            consoleMessages.shift();
-        }
-    });
-    page.on("pageerror", (...args) => {
-        const err = args[0];
-        pageErrors.push({
-            message: err?.message ? String(err.message) : String(err),
-            name: err?.name ? String(err.name) : undefined,
-            timestamp: new Date().toISOString(),
-        });
-        if (pageErrors.length > pw_responses_js_1.MAX_PAGE_ERRORS) {
-            pageErrors.shift();
-        }
-    });
-    page.on("request", (...args) => {
-        const req = args[0];
-        if (!req)
-            return;
-        nextRequestId += 1;
-        const entry = {
-            id: `r${nextRequestId}`,
-            timestamp: new Date().toISOString(),
-            method: typeof req.method === "function" ? req.method() : "GET",
-            url: typeof req.url === "function" ? req.url() : "",
-            resourceType: typeof req.resourceType === "function" ? req.resourceType() : undefined,
-        };
-        networkRequests.push(entry);
-        if (networkRequests.length > pw_responses_js_1.MAX_NETWORK_REQUESTS) {
-            networkRequests.shift();
-        }
-    });
-    page.on("response", (...args) => {
-        const resp = args[0];
-        if (!resp)
-            return;
-        const respUrl = typeof resp.url === "function" ? resp.url() : "";
-        // Match by URL (find most recent matching request)
-        for (let i = networkRequests.length - 1; i >= 0; i -= 1) {
-            const rec = networkRequests[i];
-            if (rec && rec.url === respUrl && rec.status === undefined) {
-                rec.status = typeof resp.status === "function" ? resp.status() : undefined;
-                rec.ok = typeof resp.ok === "function" ? resp.ok() : undefined;
-                break;
-            }
-        }
-    });
-    page.on("requestfailed", (...args) => {
-        const req = args[0];
-        if (!req)
-            return;
-        const failUrl = typeof req.url === "function" ? req.url() : "";
-        for (let i = networkRequests.length - 1; i >= 0; i -= 1) {
-            const rec = networkRequests[i];
-            if (rec && rec.url === failUrl && rec.ok === undefined) {
-                rec.ok = false;
-                rec.failureText = typeof req.failure === "function" ? req.failure()?.errorText : undefined;
-                break;
-            }
-        }
-    });
-}
-function isChromiumLike(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        typeof value.launch === "function");
-}
-/**
- * Resolve Playwright's chromium launcher across module interop shapes.
- * Some runtimes expose `{ chromium }`, others only `{ default: { chromium } }`.
- */
-function resolveChromiumLauncher(moduleValue) {
-    const pw = moduleValue;
-    const chromium = pw?.chromium ?? pw?.default?.chromium;
-    if (isChromiumLike(chromium)) {
-        return chromium;
-    }
-    const keys = pw && typeof pw === "object"
-        ? Object.keys(pw)
-            .sort()
-            .join(", ")
-        : String(pw);
-    throw new Error(`Invalid playwright module shape: missing chromium.launch (module keys: ${keys || "(none)"}).`);
-}
-/**
- * Launch a new Playwright browser session.
- * Uses dynamic import so the tool module loads even without playwright installed.
- */
-async function launchBrowser(options) {
-    if (currentSession) {
-        // Already have a session — navigate if URL given, otherwise return existing
-        if (options?.url) {
-            try {
-                await currentSession.page.goto(options.url, DEFAULT_NAVIGATION_OPTIONS);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                throw new Error(`Navigation to ${options.url} failed: ${message}. Session remains active; use 'snapshot' or retry 'navigate'.`);
-            }
-        }
-        return currentSession;
-    }
-    // Dynamic import: playwright is an optional peer dependency.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let pw;
-    try {
-        pw = await playwrightLoader();
-    }
-    catch {
-        throw new Error("playwright is not installed. Run: npx playwright install chromium\n" +
-            "Or: npm install playwright && npx playwright install chromium");
-    }
-    const chromium = resolveChromiumLauncher(pw);
-    const browser = await chromium.launch({
-        headless: options?.headless !== false, // default headless
-    });
-    const context = browser.newContext
-        ? await browser.newContext({
-            viewport: { width: 1280, height: 720 },
-            userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
-        })
-        : (browser.contexts()[0] ??
-            (() => {
-                throw new Error("No browser context available");
-            })());
-    const page = context.pages?.().length
-        ? context.pages()[0]
-        : await context.newPage();
-    wirePageListeners(page);
-    // Persist session state before first navigation so launch+goto timeout
-    // cannot leave the tool in a "no session" state.
-    currentSession = { browser, context, page };
-    currentRefs = {};
-    consoleMessages.length = 0;
-    networkRequests.length = 0;
-    pageErrors.length = 0;
-    nextRequestId = 0;
-    if (options?.url) {
-        try {
-            await page.goto(options.url, DEFAULT_NAVIGATION_OPTIONS);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Browser launched, but initial navigation to ${options.url} failed: ${message}. Session remains active; use 'snapshot' or retry 'navigate'.`);
-        }
-    }
-    return currentSession;
-}
-/**
- * Close the current browser session and clean up all state.
- */
-async function closeBrowser() {
-    const session = currentSession;
-    currentSession = null;
-    currentRefs = {};
-    consoleMessages.length = 0;
-    networkRequests.length = 0;
-    pageErrors.length = 0;
-    nextRequestId = 0;
-    if (session) {
-        try {
-            await session.browser.close();
-        }
-        catch {
-            // Best-effort close.
-        }
-    }
-}
-// ── Tab management ────────────────────────────────────────────────────
-/**
- * List all open tabs (pages) in the current context.
- */
-function listTabs() {
-    if (!currentSession) {
-        return [];
-    }
-    const pages = currentSession.context.pages();
-    return pages.map((p, i) => ({
-        index: i,
-        url: p.url(),
-        active: p === currentSession.page,
-    }));
-}
-/**
- * Open a new tab, optionally navigating to a URL.
- */
-async function newTab(url) {
-    if (!currentSession) {
-        const launched = await launchBrowser({ url });
-        return { index: 0, url: launched.page.url() };
-    }
-    const page = await currentSession.context.newPage();
-    wirePageListeners(page);
-    currentSession.page = page;
-    currentRefs = {};
-    if (url) {
-        await page.goto(url, DEFAULT_NAVIGATION_OPTIONS);
-    }
-    const pages = currentSession.context.pages();
-    return { index: pages.length - 1, url: page.url() };
-}
-/**
- * Switch to a tab by index.
- */
-async function selectTab(index) {
-    if (!currentSession) {
-        await launchBrowser();
-    }
-    if (!currentSession) {
-        throw new Error("No tabs open.");
-    }
-    const pages = currentSession.context.pages();
-    if (index < 0 || index >= pages.length) {
-        throw new Error(`Tab index ${index} out of range (0..${pages.length - 1})`);
-    }
-    const page = pages[index];
-    currentSession.page = page;
-    wirePageListeners(page);
-    currentRefs = {};
-    return { url: page.url() };
-}
-/**
- * Close a tab by index (defaults to current tab).
- */
-async function closeTab(index) {
-    if (!currentSession) {
-        throw new Error("No tabs open.");
-    }
-    const pages = currentSession.context.pages();
-    const targetIndex = index ?? pages.indexOf(currentSession.page);
-    if (targetIndex < 0 || targetIndex >= pages.length) {
-        throw new Error(`Tab index ${targetIndex} out of range`);
-    }
-    const targetPage = pages[targetIndex];
-    await targetPage.close();
-    // Update current page if we closed the active one
-    const remaining = currentSession.context.pages();
-    if (!remaining.length) {
-        // All tabs closed — create a fresh one
-        const page = await currentSession.context.newPage();
-        currentSession.page = page;
-        wirePageListeners(page);
-    }
-    else if (targetPage === currentSession.page) {
-        const newIndex = Math.min(targetIndex, remaining.length - 1);
-        currentSession.page = remaining[newIndex];
-        wirePageListeners(currentSession.page);
-    }
-    currentRefs = {};
-}

package/dist-cjs/definitions/browser/pw-shared.js

@@ -1,72 +0,0 @@
-"use strict";
-// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
-// https://github.com/openclaw/openclaw
-// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseRoleRef = parseRoleRef;
-exports.requireRef = requireRef;
-exports.normalizeTimeoutMs = normalizeTimeoutMs;
-exports.toAIFriendlyError = toAIFriendlyError;
-/**
- * Shared utilities for Playwright-based browser tool functions.
- * Ported from OpenClaw's pw-tools-core.shared.ts.
- */
-/**
- * Parse a raw ref string into its canonical "eN" form.
- * Accepts: "e1", "@e1", "ref=e1" -> "e1". Returns null if invalid.
- */
-function parseRoleRef(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed) {
-        return null;
-    }
-    const normalized = trimmed.startsWith("@")
-        ? trimmed.slice(1)
-        : trimmed.startsWith("ref=")
-            ? trimmed.slice(4)
-            : trimmed;
-    return /^e\d+$/.test(normalized) ? normalized : null;
-}
-/**
- * Validate and normalize a ref string. Throws if the ref is empty/invalid.
- */
-function requireRef(value) {
-    const raw = typeof value === "string" ? value.trim() : "";
-    const roleRef = raw ? parseRoleRef(raw) : null;
-    const ref = roleRef ?? (raw.startsWith("@") ? raw.slice(1) : raw);
-    if (!ref) {
-        throw new Error("ref is required");
-    }
-    return ref;
-}
-/**
- * Clamp a timeout value to a safe range (500ms .. 120s).
- */
-function normalizeTimeoutMs(timeoutMs, fallback) {
-    return Math.max(500, Math.min(120_000, timeoutMs ?? fallback));
-}
-/**
- * Rewrite Playwright errors into messages that guide the LLM to take
- * corrective action (re-snapshot, scroll, etc.).
- */
-function toAIFriendlyError(error, selector) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (message.includes("strict mode violation")) {
-        const countMatch = message.match(/resolved to (\d+) elements/);
-        const count = countMatch ? countMatch[1] : "multiple";
-        return new Error(`Selector "${selector}" matched ${count} elements. ` +
-            `Run a new snapshot to get updated refs, or use a different ref.`);
-    }
-    if ((message.includes("Timeout") || message.includes("waiting for")) &&
-        (message.includes("to be visible") || message.includes("not visible"))) {
-        return new Error(`Element "${selector}" not found or not visible. ` +
-            `Run a new snapshot to see current page elements.`);
-    }
-    if (message.includes("intercepts pointer events") ||
-        message.includes("not visible") ||
-        message.includes("not receive pointer events")) {
-        return new Error(`Element "${selector}" is not interactable (hidden or covered). ` +
-            `Try scrolling it into view, closing overlays, or re-snapshotting.`);
-    }
-    return error instanceof Error ? error : new Error(message);
-}