gologin-agent-browser-cli 0.1.2 → 0.1.3

package/README.md

@@ -148,6 +148,10 @@ gologin-agent-browser click @e3
 
 Refs are best-effort and should be regenerated after navigation or major DOM changes.
 
+Most mutating commands will leave the page in `snapshot=stale` state. When that happens, run `snapshot` again before using old refs.
+
+On dynamic pages, `find ...` is usually a better fallback than stale refs because it re-resolves against the live page instead of the last snapshot.
+
 ## More Examples
 
 ```bash
@@ -164,6 +168,7 @@ gologin-agent-browser scrollintoview "#submit"
 gologin-agent-browser find label "Email" fill "test@example.com"
 gologin-agent-browser upload "input[type='file']" /absolute/path/to/avatar.png
 gologin-agent-browser wait --text "Welcome"
+gologin-agent-browser screenshot page.png --annotate --press-escape
 ```
 
 ## Commands
@@ -188,7 +193,7 @@ gologin-agent-browser wait --text "Welcome"
 - `find <role|text|label|placeholder|first|last|nth> ...`
 - `upload <target> <file...> [--session <sessionId>]`
 - `pdf <path> [--session <sessionId>]`
-- `screenshot <path> [--annotate] [--session <sessionId>]`
+- `screenshot <path> [--annotate] [--press-escape] [--session <sessionId>]`
 - `close [--session <sessionId>]`
 - `sessions`
 - `current`
@@ -218,6 +223,8 @@ gologin-agent-browser screenshot page.png --annotate
 
 Targets can be either snapshot refs like `@e4` or raw Playwright/CSS selectors. `find` adds semantic locator flows similar to agent-browser.
 
+If a ref stops resolving after navigation or a DOM update, prefer a fresh `snapshot` or use a semantic `find ...` command instead.
+
 `open`, `current`, and `sessions` also expose session metadata in a shell-friendly form:
 
 ```text
@@ -240,6 +247,7 @@ Supported aliases:
 - Snapshot and ref resolution are best-effort. Dynamic pages can invalidate refs after heavy DOM changes or navigation.
 - Snapshot output is compact and accessibility-informed, but it is not a full accessibility tree dump.
 - Annotated screenshots are based on the current snapshot/ref model, so labels are also best-effort on highly dynamic pages.
+- `screenshot` has a hard timeout and supports `--press-escape` for pages with modals, chat widgets, or overlay-driven render issues.
 - The daemon keeps only the latest snapshot ref map for each session.
 - Real browser sessions require a valid Gologin Cloud Browser account and token. A profile id is optional.
 - Token-only mode works by provisioning a temporary cloud profile through the Gologin API before connecting to Cloud Browser.

package/dist/cli.js

@@ -61,7 +61,7 @@ function printUsage() {
         "  find <role|text|label|placeholder|first|last|nth> ... [--exact]",
         "  upload <target> <file...> [--session <sessionId>]",
         "  pdf <path> [--session <sessionId>]",
-        "  screenshot <path> [--annotate] [--session <sessionId>]",
+        "  screenshot <path> [--annotate] [--press-escape] [--session <sessionId>]",
         "  close [--session <sessionId>] (aliases: quit, exit)",
         "  sessions",
         "  current",

package/dist/commands/screenshot.js

@@ -9,12 +9,14 @@ async function runScreenshotCommand(context, argv) {
     const inputPath = parsed.positional[0];
     const sessionId = (0, utils_1.getFlagString)(parsed, "session");
     const annotate = (0, utils_1.getFlagBoolean)(parsed, "annotate");
+    const pressEscape = (0, utils_1.getFlagBoolean)(parsed, "press-escape");
     if (!inputPath) {
-        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser screenshot <path> [--session <sessionId>]", 400);
+        throw new errors_1.AppError("BAD_REQUEST", "Usage: gologin-agent-browser screenshot <path> [--annotate] [--press-escape] [--session <sessionId>]", 400);
     }
     const resolvedSessionId = await (0, shared_1.resolveSessionId)(context, sessionId);
     const targetPath = (0, utils_1.ensureAbsolutePath)(context.cwd, inputPath);
-    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/screenshot`, { path: targetPath, annotate });
+    const response = await context.client.request("POST", `/sessions/${resolvedSessionId}/screenshot`, { path: targetPath, annotate, pressEscape });
     const annotated = response.annotated ? " annotated=yes" : "";
-    context.stdout.write(`screenshot=${response.path} session=${response.sessionId}${annotated}\n`);
+    const escaped = response.pressedEscape ? " escape=yes" : "";
+    context.stdout.write(`screenshot=${response.path} session=${response.sessionId}${annotated}${escaped}\n`);
 }

package/dist/daemon/browser.d.ts

@@ -28,6 +28,7 @@ export declare function scrollElement(locator: Locator, direction: ScrollDirecti
 export declare function scrollLocatorIntoView(locator: Locator, timeoutMs: number): Promise<void>;
 export declare function uploadFiles(locator: Locator, files: string[], timeoutMs: number): Promise<void>;
 export declare function savePdf(page: Page, targetPath: string): Promise<void>;
+export declare function captureScreenshot(page: Page, targetPath: string, timeoutMs: number): Promise<void>;
 export declare function annotatePageWithRefs(page: Page, refs: Array<{
     ref: string;
     x: number;

package/dist/daemon/browser.js

@@ -25,6 +25,7 @@ exports.scrollElement = scrollElement;
 exports.scrollLocatorIntoView = scrollLocatorIntoView;
 exports.uploadFiles = uploadFiles;
 exports.savePdf = savePdf;
+exports.captureScreenshot = captureScreenshot;
 exports.annotatePageWithRefs = annotatePageWithRefs;
 exports.clearPageAnnotations = clearPageAnnotations;
 exports.closeSessionHandles = closeSessionHandles;
@@ -363,7 +364,7 @@ async function resolveDescriptorLocator(page, descriptor) {
             return locator;
         }
     }
-    throw new errors_1.AppError("REF_NOT_FOUND", `ref ${descriptor.ref} is not available on the current page`, 404, {
+    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
     });
 }
@@ -514,6 +515,13 @@ async function savePdf(page, targetPath) {
         printBackground: true
     });
 }
+async function captureScreenshot(page, targetPath, timeoutMs) {
+    await page.screenshot({
+        path: targetPath,
+        fullPage: true,
+        timeout: timeoutMs
+    });
+}
 async function annotatePageWithRefs(page, refs) {
     await page.evaluate((labels) => {
         document.getElementById("__gologin-agent-browser-annotations")?.remove();

package/dist/daemon/server.js

@@ -151,7 +151,7 @@ async function handleRequest(request, response) {
         const screenshotSessionId = matchSessionRoute(pathname, "screenshot");
         if (method === "POST" && screenshotSessionId) {
             const body = (await (0, utils_1.readJsonBody)(request));
-            (0, utils_1.writeJsonResponse)(response, 200, await sessionManager.screenshot(screenshotSessionId, body.path, body.annotate === true));
+            (0, utils_1.writeJsonResponse)(response, 200, await sessionManager.screenshot(screenshotSessionId, body.path, body.annotate === true, body.pressEscape === true));
             return;
         }
         const uploadSessionId = matchSessionRoute(pathname, "upload");

package/dist/daemon/sessionManager.d.ts

@@ -41,7 +41,7 @@ export declare class SessionManager {
     }): Promise<WaitResponse>;
     get(sessionId: string | undefined, kind: GetKind, target?: string): Promise<GetResponse>;
     find(sessionId: string | undefined, request: FindRequest): Promise<FindResponse>;
-    screenshot(sessionId: string | undefined, targetPath: string, annotate?: boolean): Promise<ScreenshotResponse>;
+    screenshot(sessionId: string | undefined, targetPath: string, annotate?: boolean, pressEscape?: boolean): Promise<ScreenshotResponse>;
     pdf(sessionId: string | undefined, targetPath: string): Promise<PdfResponse>;
     close(sessionId?: string): Promise<CloseSessionResponse>;
     listSessions(): Promise<SessionsResponse>;

package/dist/daemon/sessionManager.js

@@ -110,7 +110,7 @@ class SessionManager {
         if ((0, utils_1.isRefTarget)(target)) {
             const descriptor = this.refStore.get(session.sessionId, target);
             if (!descriptor) {
-                throw new errors_1.AppError("REF_NOT_FOUND", `ref ${target} is not available in session ${session.sessionId}`, 404, {
+                throw new errors_1.AppError("REF_NOT_FOUND", `ref ${target} is stale or unavailable in session ${session.sessionId}; run snapshot again`, 404, {
                     ref: target,
                     sessionId: session.sessionId
                 });
@@ -412,10 +412,16 @@ class SessionManager {
             value
         };
     }
-    async screenshot(sessionId, targetPath, annotate = false) {
+    async screenshot(sessionId, targetPath, annotate = false, pressEscape = false) {
         const session = await this.getSessionOrThrow(sessionId);
+        let pressedEscape = false;
         try {
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(targetPath), { recursive: true });
+            if (pressEscape) {
+                await (0, browser_1.pressKey)(session.page, "Escape", this.config.actionTimeoutMs);
+                await new Promise((resolve) => setTimeout(resolve, 200));
+                pressedEscape = true;
+            }
             if (annotate) {
                 const snapshot = await (0, snapshot_1.buildSnapshot)(session.page, { interactive: true });
                 this.refStore.set(session.sessionId, snapshot.refs);
@@ -439,10 +445,7 @@ class SessionManager {
                 }
                 await (0, browser_1.annotatePageWithRefs)(session.page, labels);
             }
-            await session.page.screenshot({
-                path: targetPath,
-                fullPage: true
-            });
+            await (0, browser_1.captureScreenshot)(session.page, targetPath, this.config.navigationTimeoutMs);
             if (annotate) {
                 await (0, browser_1.clearPageAnnotations)(session.page).catch(() => undefined);
             }
@@ -451,17 +454,26 @@ class SessionManager {
             if (annotate) {
                 await (0, browser_1.clearPageAnnotations)(session.page).catch(() => undefined);
             }
-            throw new errors_1.AppError("SCREENSHOT_FAILED", error instanceof Error ? error.message : String(error), 500, {
-                path: targetPath
+            const baseMessage = error instanceof Error ? error.message : String(error);
+            const hint = pressEscape
+                ? "Screenshot timed out or failed even after pressing Escape"
+                : "Screenshot timed out or failed; try pressing Escape first or re-run with --press-escape";
+            throw new errors_1.AppError("SCREENSHOT_FAILED", `${hint}: ${baseMessage}`, 500, {
+                path: targetPath,
+                pressEscape
             });
         }
+        if (pressedEscape && !annotate && session.hasSnapshot) {
+            session.staleSnapshot = true;
+        }
         session.lastScreenshotPath = targetPath;
         this.touchSession(session);
         return {
             sessionId: session.sessionId,
             path: targetPath,
             url: session.currentUrl,
-            annotated: annotate
+            annotated: annotate,
+            pressedEscape
         };
     }
     async pdf(sessionId, targetPath) {

package/dist/lib/types.d.ts

@@ -169,12 +169,14 @@ export interface PressResponse extends ActionResponse {
 export interface ScreenshotRequest {
     path: string;
     annotate?: boolean;
+    pressEscape?: boolean;
 }
 export interface ScreenshotResponse {
     sessionId: string;
     path: string;
     url: string;
     annotated?: boolean;
+    pressedEscape?: boolean;
 }
 export interface CloseSessionResponse {
     sessionId: string;

package/dist/lib/utils.js

@@ -26,7 +26,7 @@ const errors_1 = require("./errors");
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
-    const booleanFlags = new Set(["interactive", "exact", "annotate"]);
+    const booleanFlags = new Set(["interactive", "exact", "annotate", "press-escape"]);
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === "-i") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gologin-agent-browser-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agent-native cloud browser automation CLI for Gologin",
   "main": "dist/cli.js",
   "types": "dist/lib/types.d.ts",