gologin-agent-browser-cli 0.2.0

package/dist/daemon/browser.js

@@ -0,0 +1,818 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConnectUrl = buildConnectUrl;
+exports.toPlaywrightCdpUrl = toPlaywrightCdpUrl;
+exports.createQuickProfile = createQuickProfile;
+exports.createManagedProfile = createManagedProfile;
+exports.deleteProfile = deleteProfile;
+exports.getCloudLiveViewUrl = getCloudLiveViewUrl;
+exports.getCloudProfileProxy = getCloudProfileProxy;
+exports.connectToBrowser = connectToBrowser;
+exports.navigatePage = navigatePage;
+exports.resolveDescriptorLocator = resolveDescriptorLocator;
+exports.resolveSelectorLocator = resolveSelectorLocator;
+exports.resolveSemanticLocator = resolveSemanticLocator;
+exports.performLocatorAction = performLocatorAction;
+exports.actionMutatesSnapshot = actionMutatesSnapshot;
+exports.pressKey = pressKey;
+exports.waitForTarget = waitForTarget;
+exports.waitForPageText = waitForPageText;
+exports.waitForPageUrl = waitForPageUrl;
+exports.waitForPageLoad = waitForPageLoad;
+exports.readLocatorValue = readLocatorValue;
+exports.scrollPage = scrollPage;
+exports.scrollElement = scrollElement;
+exports.scrollLocatorIntoView = scrollLocatorIntoView;
+exports.uploadFiles = uploadFiles;
+exports.savePdf = savePdf;
+exports.captureScreenshot = captureScreenshot;
+exports.listTabs = listTabs;
+exports.openTab = openTab;
+exports.focusTab = focusTab;
+exports.closeTab = closeTab;
+exports.navigateHistory = navigateHistory;
+exports.readCookies = readCookies;
+exports.importCookies = importCookies;
+exports.clearCookies = clearCookies;
+exports.exportStorageState = exportStorageState;
+exports.importStorageState = importStorageState;
+exports.clearStorageState = clearStorageState;
+exports.evaluateExpression = evaluateExpression;
+exports.annotatePageWithRefs = annotatePageWithRefs;
+exports.clearPageAnnotations = clearPageAnnotations;
+exports.closeSessionHandles = closeSessionHandles;
+const playwright_1 = require("playwright");
+const errors_1 = require("../lib/errors");
+function asAriaRole(role) {
+    return role && role !== "paragraph" ? role : undefined;
+}
+const GOLOGIN_API_BASE = "https://api.gologin.com";
+function trimToUndefined(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function normalizeProxySummary(proxy, fallback) {
+    if (!proxy || typeof proxy !== "object") {
+        return fallback
+            ? {
+                mode: fallback.mode,
+                country: fallback.country,
+                host: fallback.host,
+                port: fallback.port,
+                username: fallback.username
+            }
+            : undefined;
+    }
+    const value = proxy;
+    const mode = trimToUndefined(value.mode) ?? fallback?.mode;
+    if (!mode) {
+        return undefined;
+    }
+    const host = trimToUndefined(value.host) ?? fallback?.host;
+    const country = trimToUndefined(value.autoProxyRegion) ?? trimToUndefined(value.country) ?? fallback?.country;
+    const username = trimToUndefined(value.username) ?? fallback?.username;
+    const port = typeof value.port === "number"
+        ? value.port
+        : typeof fallback?.port === "number"
+            ? fallback.port
+            : undefined;
+    return {
+        mode,
+        country,
+        host,
+        port,
+        username
+    };
+}
+function buildCloudProfileBody(sessionId, proxy) {
+    const body = {
+        name: `gologin-agent-browser-${sessionId}`,
+        os: "lin"
+    };
+    if (!proxy) {
+        return body;
+    }
+    if (proxy.mode === "gologin") {
+        body.proxy = {
+            mode: "gologin",
+            autoProxyRegion: (proxy.country ?? "us").toLowerCase()
+        };
+        return body;
+    }
+    body.proxy = {
+        mode: proxy.mode,
+        host: proxy.host,
+        port: proxy.port,
+        username: proxy.username ?? "",
+        password: proxy.password ?? ""
+    };
+    return body;
+}
+async function pickContextAndPage(browser) {
+    const existingContext = browser.contexts()[0] ?? (await browser.newContext());
+    const page = existingContext.pages()[0] ?? (await existingContext.newPage());
+    return { context: existingContext, page };
+}
+async function ensureLocatorReady(locator, description, timeoutMs) {
+    const count = await locator.count();
+    if (count === 0) {
+        throw new errors_1.AppError("BAD_REQUEST", `${description} did not match any element`, 404);
+    }
+    const resolved = locator.first();
+    await resolved.waitFor({ state: "visible", timeout: timeoutMs });
+    return resolved;
+}
+function buildConnectUrl(config, token, profileId) {
+    const url = new URL(config.connectBase);
+    url.searchParams.set("token", token);
+    if (profileId) {
+        url.searchParams.set("profile", profileId);
+    }
+    return url.toString();
+}
+function toPlaywrightCdpUrl(connectUrl) {
+    const url = new URL(connectUrl);
+    if (url.protocol === "https:") {
+        url.protocol = "wss:";
+    }
+    else if (url.protocol === "http:") {
+        url.protocol = "ws:";
+    }
+    return url.toString();
+}
+function extractProfileId(payload) {
+    if (typeof payload === "string" && payload.length > 0) {
+        return payload;
+    }
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const value = payload;
+    if (typeof value.id === "string" && value.id.length > 0) {
+        return value.id;
+    }
+    if (typeof value._id === "string" && value._id.length > 0) {
+        return value._id;
+    }
+    return undefined;
+}
+async function createQuickProfile(token, sessionId) {
+    const response = await fetch(`${GOLOGIN_API_BASE}/browser/quick`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+            name: `gologin-agent-browser-${sessionId}`,
+            os: "lin"
+        })
+    });
+    if (!response.ok) {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to create Gologin profile: ${response.status}`, 502);
+    }
+    const payload = (await response.json());
+    const profileId = extractProfileId(payload);
+    if (!profileId) {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", "Gologin profile creation returned no profile id", 502);
+    }
+    return profileId;
+}
+async function createManagedProfile(token, sessionId, proxy) {
+    if (!proxy) {
+        return {
+            profileId: await createQuickProfile(token, sessionId)
+        };
+    }
+    const response = await fetch(`${GOLOGIN_API_BASE}/browser/custom`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(buildCloudProfileBody(sessionId, proxy))
+    });
+    if (!response.ok) {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to create Gologin cloud profile: ${response.status}`, 502);
+    }
+    const payload = (await response.json());
+    const profileId = extractProfileId(payload);
+    if (!profileId) {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", "Gologin profile creation returned no profile id", 502);
+    }
+    let proxySummary;
+    if (payload && typeof payload === "object") {
+        proxySummary = normalizeProxySummary(payload.proxy, proxy);
+    }
+    return {
+        profileId,
+        proxy: proxySummary ?? normalizeProxySummary(undefined, proxy)
+    };
+}
+async function deleteProfile(token, profileId) {
+    const response = await fetch(`${GOLOGIN_API_BASE}/browser/${profileId}`, {
+        method: "DELETE",
+        headers: {
+            Authorization: `Bearer ${token}`
+        }
+    });
+    if (!response.ok) {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", `Failed to delete Gologin profile ${profileId}`, 502, {
+            profileId
+        });
+    }
+}
+async function getCloudLiveViewUrl(token, profileId) {
+    const response = await fetch(`${GOLOGIN_API_BASE}/browser/${profileId}/web`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({})
+    });
+    if (!response.ok) {
+        return undefined;
+    }
+    const payload = (await response.json());
+    return trimToUndefined(payload.remoteOrbitaUrl);
+}
+async function getCloudProfileProxy(token, profileId) {
+    const response = await fetch(`${GOLOGIN_API_BASE}/browser/${profileId}`, {
+        headers: {
+            Authorization: `Bearer ${token}`
+        }
+    });
+    if (!response.ok) {
+        return undefined;
+    }
+    const payload = (await response.json());
+    return normalizeProxySummary(payload.proxy);
+}
+async function connectToBrowser(config, token, profileId) {
+    const connectUrl = toPlaywrightCdpUrl(buildConnectUrl(config, token, profileId));
+    try {
+        const browser = await playwright_1.chromium.connectOverCDP(connectUrl);
+        const { context, page } = await pickContextAndPage(browser);
+        return { browser, context, page, connectUrl };
+    }
+    catch (error) {
+        throw new errors_1.AppError("BROWSER_CONNECTION_FAILED", error instanceof Error ? error.message : String(error), 502, {
+            profileId
+        });
+    }
+}
+async function navigatePage(page, url, timeoutMs) {
+    try {
+        await page.goto(url, {
+            waitUntil: "domcontentloaded",
+            timeout: timeoutMs
+        });
+        await page.waitForLoadState("networkidle", { timeout: 5_000 }).catch(() => undefined);
+        return page.url();
+    }
+    catch (error) {
+        throw new errors_1.AppError("NAVIGATION_TIMEOUT", error instanceof Error ? error.message : `Failed to navigate to ${url}`, 504, {
+            url
+        });
+    }
+}
+async function locatorFromRole(page, descriptor) {
+    const role = asAriaRole(descriptor.role);
+    const name = descriptor.accessibleName ?? descriptor.text;
+    if (!role || !name) {
+        return undefined;
+    }
+    const locator = page.getByRole(role, { name });
+    const count = await locator.count();
+    if (count === 0) {
+        return undefined;
+    }
+    if (count === 1) {
+        return locator.first();
+    }
+    if (descriptor.nth !== undefined && descriptor.nth < count) {
+        return locator.nth(descriptor.nth);
+    }
+    return undefined;
+}
+async function locatorFromLabel(page, descriptor) {
+    const label = descriptor.ariaLabel ?? descriptor.accessibleName;
+    if (!label) {
+        return undefined;
+    }
+    const locator = page.getByLabel(label);
+    const count = await locator.count();
+    if (count === 0) {
+        return undefined;
+    }
+    if (count === 1) {
+        return locator.first();
+    }
+    if (descriptor.nth !== undefined && descriptor.nth < count) {
+        return locator.nth(descriptor.nth);
+    }
+    return undefined;
+}
+async function locatorFromPlaceholder(page, descriptor) {
+    if (!descriptor.placeholder) {
+        return undefined;
+    }
+    const locator = page.getByPlaceholder(descriptor.placeholder);
+    const count = await locator.count();
+    if (count === 0) {
+        return undefined;
+    }
+    if (count === 1) {
+        return locator.first();
+    }
+    if (descriptor.nth !== undefined && descriptor.nth < count) {
+        return locator.nth(descriptor.nth);
+    }
+    return undefined;
+}
+async function locatorFromTagAndText(page, descriptor) {
+    const text = descriptor.text ?? descriptor.accessibleName;
+    if (!text) {
+        return undefined;
+    }
+    const locator = page.locator(descriptor.tag).filter({ hasText: text });
+    const count = await locator.count();
+    if (count === 0) {
+        return undefined;
+    }
+    if (count === 1) {
+        return locator.first();
+    }
+    if (descriptor.nth !== undefined && descriptor.nth < count) {
+        return locator.nth(descriptor.nth);
+    }
+    return undefined;
+}
+async function locatorFromFallbackTag(page, descriptor) {
+    const locator = page.locator(descriptor.tag);
+    const count = await locator.count();
+    if (count === 0) {
+        return undefined;
+    }
+    if (count === 1) {
+        return locator.first();
+    }
+    if (descriptor.nth !== undefined && descriptor.nth < count) {
+        return locator.nth(descriptor.nth);
+    }
+    return undefined;
+}
+async function resolveDescriptorLocator(page, descriptor) {
+    const strategies = [
+        locatorFromRole,
+        locatorFromLabel,
+        locatorFromPlaceholder,
+        locatorFromTagAndText,
+        locatorFromFallbackTag
+    ];
+    for (const strategy of strategies) {
+        const locator = await strategy(page, descriptor);
+        if (locator) {
+            return locator;
+        }
+    }
+    throw new errors_1.AppError("REF_NOT_FOUND", `ref ${descriptor.ref} is stale or unavailable on the current page; run snapshot again`, 404, {
+        ref: descriptor.ref
+    });
+}
+async function resolveSelectorLocator(page, selector, timeoutMs) {
+    return ensureLocatorReady(page.locator(selector), `selector ${selector}`, timeoutMs);
+}
+async function resolveSemanticLocator(page, query, timeoutMs) {
+    switch (query.strategy) {
+        case "role":
+            if (!query.role) {
+                throw new errors_1.AppError("BAD_REQUEST", "find role requires a role value", 400);
+            }
+            return ensureLocatorReady(query.name
+                ? page.getByRole(query.role, { name: query.name, exact: query.exact })
+                : page.getByRole(query.role), `role ${query.role}`, timeoutMs);
+        case "text":
+            if (!query.text) {
+                throw new errors_1.AppError("BAD_REQUEST", "find text requires a text value", 400);
+            }
+            return ensureLocatorReady(page.getByText(query.text, { exact: query.exact }), `text ${query.text}`, timeoutMs);
+        case "label":
+            if (!query.label) {
+                throw new errors_1.AppError("BAD_REQUEST", "find label requires a label value", 400);
+            }
+            return ensureLocatorReady(page.getByLabel(query.label, { exact: query.exact }), `label ${query.label}`, timeoutMs);
+        case "placeholder":
+            if (!query.placeholder) {
+                throw new errors_1.AppError("BAD_REQUEST", "find placeholder requires a placeholder value", 400);
+            }
+            return ensureLocatorReady(page.getByPlaceholder(query.placeholder, { exact: query.exact }), `placeholder ${query.placeholder}`, timeoutMs);
+        case "first":
+            if (!query.selector) {
+                throw new errors_1.AppError("BAD_REQUEST", "find first requires a selector value", 400);
+            }
+            return ensureLocatorReady(page.locator(query.selector).first(), `first ${query.selector}`, timeoutMs);
+        case "last":
+            if (!query.selector) {
+                throw new errors_1.AppError("BAD_REQUEST", "find last requires a selector value", 400);
+            }
+            return ensureLocatorReady(page.locator(query.selector).last(), `last ${query.selector}`, timeoutMs);
+        case "nth":
+            if (!query.selector || query.nth === undefined) {
+                throw new errors_1.AppError("BAD_REQUEST", "find nth requires both an index and selector", 400);
+            }
+            return ensureLocatorReady(page.locator(query.selector).nth(query.nth), `nth ${query.nth} ${query.selector}`, timeoutMs);
+    }
+}
+async function performLocatorAction(page, locator, action, timeoutMs, value) {
+    switch (action) {
+        case "click":
+            await locator.click({ timeout: timeoutMs });
+            await page.waitForLoadState("domcontentloaded", { timeout: 5_000 }).catch(() => undefined);
+            return undefined;
+        case "fill":
+            await locator.fill(value ?? "", { timeout: timeoutMs });
+            return undefined;
+        case "type":
+            await locator.pressSequentially(value ?? "", { timeout: timeoutMs });
+            return undefined;
+        case "hover":
+            await locator.hover({ timeout: timeoutMs });
+            return undefined;
+        case "focus":
+            await locator.focus({ timeout: timeoutMs });
+            return undefined;
+        case "dblclick":
+            await locator.dblclick({ timeout: timeoutMs });
+            await page.waitForLoadState("domcontentloaded", { timeout: 5_000 }).catch(() => undefined);
+            return undefined;
+        case "select":
+            await locator.selectOption(value ?? "", { timeout: timeoutMs });
+            return undefined;
+        case "check":
+            await locator.check({ timeout: timeoutMs });
+            return undefined;
+        case "uncheck":
+            await locator.uncheck({ timeout: timeoutMs });
+            return undefined;
+        case "text":
+            return await locator.innerText({ timeout: timeoutMs });
+    }
+}
+function actionMutatesSnapshot(action) {
+    return action !== "text";
+}
+async function pressKey(page, key, timeoutMs) {
+    void timeoutMs;
+    await page.keyboard.press(key);
+}
+async function waitForTarget(locator, timeoutMs) {
+    await locator.waitFor({ state: "visible", timeout: timeoutMs });
+}
+async function waitForPageText(page, text, timeoutMs, exact = false) {
+    await page.getByText(text, { exact }).first().waitFor({ state: "visible", timeout: timeoutMs });
+}
+async function waitForPageUrl(page, urlPattern, timeoutMs) {
+    await page.waitForURL(urlPattern, { timeout: timeoutMs });
+}
+async function waitForPageLoad(page, state, timeoutMs) {
+    await page.waitForLoadState(state, { timeout: timeoutMs });
+}
+async function readLocatorValue(locator, kind, timeoutMs) {
+    switch (kind) {
+        case "text":
+            return await locator.innerText({ timeout: timeoutMs });
+        case "value":
+            return await locator.inputValue({ timeout: timeoutMs });
+        case "html":
+            return await locator.innerHTML({ timeout: timeoutMs });
+        default:
+            throw new errors_1.AppError("BAD_REQUEST", `Unsupported get kind for element target: ${kind}`, 400);
+    }
+}
+function scrollDelta(direction, pixels) {
+    switch (direction) {
+        case "up":
+            return { dx: 0, dy: -pixels };
+        case "down":
+            return { dx: 0, dy: pixels };
+        case "left":
+            return { dx: -pixels, dy: 0 };
+        case "right":
+            return { dx: pixels, dy: 0 };
+    }
+}
+async function scrollPage(page, direction, pixels) {
+    const { dx, dy } = scrollDelta(direction, pixels);
+    await page.mouse.wheel(dx, dy);
+}
+async function scrollElement(locator, direction, pixels) {
+    const { dx, dy } = scrollDelta(direction, pixels);
+    await locator.evaluate((element, delta) => {
+        if (element instanceof HTMLElement) {
+            element.scrollBy(delta.dx, delta.dy);
+        }
+    }, { dx, dy });
+}
+async function scrollLocatorIntoView(locator, timeoutMs) {
+    await locator.scrollIntoViewIfNeeded({ timeout: timeoutMs });
+}
+async function uploadFiles(locator, files, timeoutMs) {
+    await locator.setInputFiles(files, { timeout: timeoutMs });
+}
+async function savePdf(page, targetPath) {
+    await page.pdf({
+        path: targetPath,
+        format: "A4",
+        printBackground: true
+    });
+}
+async function captureScreenshot(page, targetPath, timeoutMs) {
+    await page.screenshot({
+        path: targetPath,
+        fullPage: true,
+        timeout: timeoutMs
+    });
+}
+function resolvePageOrigin(page) {
+    const currentUrl = page.url();
+    try {
+        const origin = new URL(currentUrl).origin;
+        if (!origin || origin === "null") {
+            throw new Error("non-origin URL");
+        }
+        return origin;
+    }
+    catch {
+        throw new errors_1.AppError("BAD_REQUEST", `Current tab URL ${currentUrl || "about:blank"} does not have a usable origin for storage operations`, 400);
+    }
+}
+function normalizeStorageScope(scope) {
+    return scope ?? "both";
+}
+function hasLocalScope(scope) {
+    return scope === "local" || scope === "both";
+}
+function hasSessionScope(scope) {
+    return scope === "session" || scope === "both";
+}
+async function listTabs(session) {
+    const pages = session.context.pages();
+    return Promise.all(pages.map(async (page, index) => ({
+        index: index + 1,
+        url: page.url(),
+        title: await page.title().catch(() => undefined),
+        active: page === session.page
+    })));
+}
+function requireTabIndex(session, index) {
+    if (!Number.isInteger(index) || index <= 0) {
+        throw new errors_1.AppError("BAD_REQUEST", "tab index must be a positive integer", 400);
+    }
+    const page = session.context.pages()[index - 1];
+    if (!page) {
+        throw new errors_1.AppError("BAD_REQUEST", `tab ${index} does not exist`, 404, { tabIndex: index });
+    }
+    return page;
+}
+async function openTab(session, url, timeoutMs) {
+    const page = await session.context.newPage();
+    if (url) {
+        await navigatePage(page, url, timeoutMs);
+    }
+    await page.bringToFront().catch(() => undefined);
+    const tabIndex = session.context.pages().indexOf(page) + 1;
+    return {
+        page,
+        tabIndex
+    };
+}
+async function focusTab(session, index) {
+    const page = requireTabIndex(session, index);
+    await page.bringToFront().catch(() => undefined);
+    return {
+        page,
+        tabIndex: index
+    };
+}
+async function closeTab(session, index) {
+    const pagesBefore = session.context.pages();
+    const currentIndex = pagesBefore.indexOf(session.page) + 1;
+    const resolvedIndex = index ?? currentIndex;
+    const target = requireTabIndex(session, resolvedIndex);
+    if (pagesBefore.length === 1) {
+        const replacement = await session.context.newPage();
+        await replacement.goto("about:blank").catch(() => undefined);
+        await target.close({ runBeforeUnload: false });
+        await replacement.bringToFront().catch(() => undefined);
+        return {
+            page: replacement,
+            closedTabIndex: resolvedIndex,
+            activeTabIndex: 1
+        };
+    }
+    await target.close({ runBeforeUnload: false });
+    const pagesAfter = session.context.pages();
+    const nextIndex = Math.min(resolvedIndex, pagesAfter.length);
+    const page = pagesAfter[nextIndex - 1];
+    if (!page) {
+        throw new errors_1.AppError("INTERNAL_ERROR", "No tab remained after close", 500);
+    }
+    await page.bringToFront().catch(() => undefined);
+    return {
+        page,
+        closedTabIndex: resolvedIndex,
+        activeTabIndex: nextIndex
+    };
+}
+async function navigateHistory(page, direction, timeoutMs) {
+    try {
+        if (direction === "back") {
+            await page.goBack({ waitUntil: "domcontentloaded", timeout: timeoutMs }).catch(() => null);
+        }
+        else if (direction === "forward") {
+            await page.goForward({ waitUntil: "domcontentloaded", timeout: timeoutMs }).catch(() => null);
+        }
+        else {
+            await page.reload({ waitUntil: "domcontentloaded", timeout: timeoutMs });
+        }
+        await page.waitForLoadState("networkidle", { timeout: 5_000 }).catch(() => undefined);
+        return page.url();
+    }
+    catch (error) {
+        throw new errors_1.AppError("NAVIGATION_TIMEOUT", error instanceof Error ? error.message : `Failed to navigate ${direction}`, 504, { direction });
+    }
+}
+async function readCookies(session) {
+    const cookies = await session.context.cookies();
+    return cookies
+        .map((cookie) => ({
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain,
+        path: cookie.path,
+        expires: cookie.expires,
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        sameSite: cookie.sameSite
+    }))
+        .sort((left, right) => `${left.domain}|${left.path}|${left.name}`.localeCompare(`${right.domain}|${right.path}|${right.name}`));
+}
+async function importCookies(session, cookies) {
+    await session.context.addCookies(cookies);
+    return cookies.length;
+}
+async function clearCookies(session) {
+    const existing = await session.context.cookies();
+    await session.context.clearCookies();
+    return existing.length;
+}
+async function exportStorageState(page, scope) {
+    const resolvedScope = normalizeStorageScope(scope);
+    const origin = resolvePageOrigin(page);
+    const state = await page.evaluate((requestedScope) => {
+        const localEntries = [];
+        const sessionEntries = [];
+        if (requestedScope === "local" || requestedScope === "both") {
+            for (let index = 0; index < localStorage.length; index += 1) {
+                const key = localStorage.key(index);
+                if (key !== null) {
+                    localEntries.push([key, localStorage.getItem(key) ?? ""]);
+                }
+            }
+            localEntries.sort(([left], [right]) => left.localeCompare(right));
+        }
+        if (requestedScope === "session" || requestedScope === "both") {
+            for (let index = 0; index < sessionStorage.length; index += 1) {
+                const key = sessionStorage.key(index);
+                if (key !== null) {
+                    sessionEntries.push([key, sessionStorage.getItem(key) ?? ""]);
+                }
+            }
+            sessionEntries.sort(([left], [right]) => left.localeCompare(right));
+        }
+        return {
+            localStorage: Object.fromEntries(localEntries),
+            sessionStorage: Object.fromEntries(sessionEntries)
+        };
+    }, resolvedScope);
+    return {
+        origin,
+        localStorage: state.localStorage,
+        sessionStorage: state.sessionStorage
+    };
+}
+async function importStorageState(page, state, scope, clear = false) {
+    const resolvedScope = normalizeStorageScope(scope);
+    const origin = resolvePageOrigin(page);
+    if (origin !== state.origin) {
+        throw new errors_1.AppError("BAD_REQUEST", `Storage state origin ${state.origin} does not match current tab origin ${origin}`, 400, {
+            expectedOrigin: origin,
+            actualOrigin: state.origin
+        });
+    }
+    const localStorageState = hasLocalScope(resolvedScope) ? state.localStorage : {};
+    const sessionStorageState = hasSessionScope(resolvedScope) ? state.sessionStorage : {};
+    await page.evaluate(({ incoming, requestedScope, shouldClear }) => {
+        if (shouldClear) {
+            if (requestedScope === "local" || requestedScope === "both") {
+                localStorage.clear();
+            }
+            if (requestedScope === "session" || requestedScope === "both") {
+                sessionStorage.clear();
+            }
+        }
+        if (requestedScope === "local" || requestedScope === "both") {
+            for (const [key, value] of Object.entries(incoming.localStorage)) {
+                localStorage.setItem(key, value);
+            }
+        }
+        if (requestedScope === "session" || requestedScope === "both") {
+            for (const [key, value] of Object.entries(incoming.sessionStorage)) {
+                sessionStorage.setItem(key, value);
+            }
+        }
+    }, {
+        incoming: {
+            localStorage: localStorageState,
+            sessionStorage: sessionStorageState
+        },
+        requestedScope: resolvedScope,
+        shouldClear: clear
+    });
+    return {
+        origin,
+        localKeys: Object.keys(localStorageState).length,
+        sessionKeys: Object.keys(sessionStorageState).length
+    };
+}
+async function clearStorageState(page, scope) {
+    const resolvedScope = normalizeStorageScope(scope);
+    const origin = resolvePageOrigin(page);
+    await page.evaluate((requestedScope) => {
+        if (requestedScope === "local" || requestedScope === "both") {
+            localStorage.clear();
+        }
+        if (requestedScope === "session" || requestedScope === "both") {
+            sessionStorage.clear();
+        }
+    }, resolvedScope);
+    return {
+        origin,
+        scope: resolvedScope
+    };
+}
+async function evaluateExpression(page, expression) {
+    try {
+        return await page.evaluate((userExpression) => {
+            const fn = new Function(`return (${userExpression});`);
+            return fn();
+        }, expression);
+    }
+    catch (error) {
+        throw new errors_1.AppError("BAD_REQUEST", error instanceof Error ? error.message : String(error), 400, {
+            expression
+        });
+    }
+}
+async function annotatePageWithRefs(page, refs) {
+    await page.evaluate((labels) => {
+        document.getElementById("__gologin-agent-browser-annotations")?.remove();
+        const root = document.createElement("div");
+        root.id = "__gologin-agent-browser-annotations";
+        root.style.position = "absolute";
+        root.style.left = "0";
+        root.style.top = "0";
+        root.style.width = "100%";
+        root.style.height = "100%";
+        root.style.pointerEvents = "none";
+        root.style.zIndex = "2147483647";
+        for (const label of labels) {
+            const node = document.createElement("div");
+            node.textContent = label.ref;
+            node.style.position = "absolute";
+            node.style.left = `${Math.max(0, label.x)}px`;
+            node.style.top = `${Math.max(0, label.y)}px`;
+            node.style.padding = "2px 6px";
+            node.style.borderRadius = "999px";
+            node.style.background = "#ffcf33";
+            node.style.color = "#111";
+            node.style.font = "600 12px/1.2 Menlo, Monaco, monospace";
+            node.style.boxShadow = "0 1px 2px rgba(0,0,0,0.3)";
+            node.style.border = "1px solid rgba(0,0,0,0.35)";
+            root.appendChild(node);
+        }
+        document.body.appendChild(root);
+    }, refs);
+}
+async function clearPageAnnotations(page) {
+    await page.evaluate(() => {
+        document.getElementById("__gologin-agent-browser-annotations")?.remove();
+    });
+}
+async function closeSessionHandles(session) {
+    await session.browser.close().catch(async () => {
+        await session.page.close().catch(() => undefined);
+        await session.context.close().catch(() => undefined);
+    });
+}