@petukhovart/agent-view 0.16.1 → 0.17.1

package/dist/server/locator.d.ts

@@ -0,0 +1,19 @@
+import type { PageSession } from '../cdp/types.js';
+export declare function testIdAttributes(configured: string | undefined): readonly string[];
+export type Locator = {
+    css: string;
+    label: string;
+};
+export declare function locatorFromArgs(args: Record<string, unknown>): Locator | undefined;
+export declare function testIdLocator(testid: string, testIdAttribute: string | undefined): Locator;
+/**
+ * The first visible element a locator names. The label says when it was one of
+ * several, since acting on the first of many usually means the locator is too broad.
+ */
+export declare function findByLocator(conn: PageSession, locator: Locator): Promise<{
+    backendDOMNodeId: number;
+    label: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=locator.d.ts.map

package/dist/server/locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../../src/server/locator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AASlD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,CAGlF;AAED,MAAM,MAAM,OAAO,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAIlF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAG1F;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAK1E"}

package/dist/server/locator.js

@@ -0,0 +1,33 @@
+/**
+ * Attributes tried when `testIdAttribute` is not configured, in order. Projects
+ * rarely set more than one, so accepting all of them spares every project the
+ * config line.
+ */
+const DEFAULT_TEST_ID_ATTRIBUTES = ['data-testid', 'data-test-id', 'data-test', 'data-qa', 'data-cy'];
+export function testIdAttributes(configured) {
+    // The DOM reports attribute names lowercased; a camel-cased config would match nothing.
+    return configured ? [configured.toLowerCase()] : DEFAULT_TEST_ID_ATTRIBUTES;
+}
+export function locatorFromArgs(args) {
+    const { testid, selector, testIdAttribute } = args;
+    if (typeof testid === 'string')
+        return testIdLocator(testid, typeof testIdAttribute === 'string' ? testIdAttribute : undefined);
+    return typeof selector === 'string' ? { css: selector, label: `selector "${selector}"` } : undefined;
+}
+export function testIdLocator(testid, testIdAttribute) {
+    const value = `"${testid.replace(/["\\]/g, '\\$&')}"`;
+    return { css: testIdAttributes(testIdAttribute).map(attr => `[${attr}=${value}]`).join(','), label: `testid "${testid}"` };
+}
+/**
+ * The first visible element a locator names. The label says when it was one of
+ * several, since acting on the first of many usually means the locator is too broad.
+ */
+export async function findByLocator(conn, locator) {
+    const { backendDOMNodeId, count } = await conn.queryVisible(locator.css);
+    if (count === 0)
+        return { error: `No element matches ${locator.label}` };
+    if (backendDOMNodeId === null)
+        return { error: `None of ${count} element(s) matching ${locator.label} is visible` };
+    return { backendDOMNodeId, label: count > 1 ? `${locator.label} (first visible of ${count})` : locator.label };
+}
+//# sourceMappingURL=locator.js.map

package/dist/server/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../../src/server/locator.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,0BAA0B,GAAG,CAAC,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,CAAU,CAAA;AAE9G,MAAM,UAAU,gBAAgB,CAAC,UAA8B;IAC7D,wFAAwF;IACxF,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAA;AAC7E,CAAC;AAID,MAAM,UAAU,eAAe,CAAC,IAA6B;IAC3D,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,IAAI,CAAA;IAClD,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,MAAM,EAAE,OAAO,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC/H,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AACtG,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,eAAmC;IAC/E,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAA;IACrD,OAAO,EAAE,GAAG,EAAE,gBAAgB,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,MAAM,GAAG,EAAE,CAAA;AAC5H,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAiB,EACjB,OAAgB;IAEhB,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACxE,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,sBAAsB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAA;IACxE,IAAI,gBAAgB,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,WAAW,KAAK,wBAAwB,OAAO,CAAC,KAAK,aAAa,EAAE,CAAA;IACnH,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,sBAAsB,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;AAChH,CAAC"}

package/dist/server/port.d.ts

@@ -0,0 +1,7 @@
+/** `AGENT_VIEW_SERVER_PORT` runs a dev build next to the installed server. The spawned server inherits it. */
+export declare const SERVER_PORT: number;
+/** Home of the token files and saved act scripts. */
+export declare const AGENT_VIEW_DIR: string;
+/** Per-port token, so a dev server never overwrites the live server's token. */
+export declare const TOKEN_PATH: string;
+//# sourceMappingURL=port.d.ts.map

package/dist/server/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/server/port.ts"],"names":[],"mappings":"AAKA,8GAA8G;AAC9G,eAAO,MAAM,WAAW,QAAiD,CAAA;AAEzE,qDAAqD;AACrD,eAAO,MAAM,cAAc,QAAiC,CAAA;AAE5D,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAA+F,CAAA"}

package/dist/server/port.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_SERVER_PORT = 47922;
+/** `AGENT_VIEW_SERVER_PORT` runs a dev build next to the installed server. The spawned server inherits it. */
+export const SERVER_PORT = serverPort(process.env.AGENT_VIEW_SERVER_PORT);
+/** Home of the token files and saved act scripts. */
+export const AGENT_VIEW_DIR = join(homedir(), '.agent-view');
+/** Per-port token, so a dev server never overwrites the live server's token. */
+export const TOKEN_PATH = join(AGENT_VIEW_DIR, SERVER_PORT === DEFAULT_SERVER_PORT ? 'token' : `token-${SERVER_PORT}`);
+function serverPort(raw) {
+    if (raw === undefined || raw === '')
+        return DEFAULT_SERVER_PORT;
+    const port = Number(raw);
+    // A typo must not fall back to the default: that is the live server the variable exists to avoid.
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Error(`AGENT_VIEW_SERVER_PORT=${raw} is not a port`);
+    return port;
+}
+//# sourceMappingURL=port.js.map

package/dist/server/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/server/port.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,mBAAmB,GAAG,KAAK,CAAA;AAEjC,8GAA8G;AAC9G,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;AAEzE,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,CAAA;AAE5D,gFAAgF;AAChF,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,KAAK,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;AAEtH,SAAS,UAAU,CAAC,GAAuB;IACzC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,mBAAmB,CAAA;IAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;IACxB,kGAAkG;IAClG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,gBAAgB,CAAC,CAAA;IACxH,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/server/server.d.ts

@@ -69,6 +69,7 @@ export declare class AgentViewServer {
     private handleDom;
     private findByFilter;
     private handleClick;
+    private handleAct;
     private handleDrag;
     private resolveDragPoint;
     private handleFill;

package/dist/server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAcA,OAAO,EAKL,KAAK,WAAW,EAEhB,KAAK,UAAU,EAKhB,MAAM,iBAAiB,CAAA;AAgExB,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAK/F;AA6BD,KAAK,YAAY,GACb;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIzG;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B5F;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAaxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAUhG;AAqBD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,YAAY,CAA4B;IAChD,wGAAwG;IACxG,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,aAAa,CAA0B;IAE/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAuB2D;IAEpF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0C;IAC5E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2F;IAEnH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,mDAAmD;IACnD,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,YAAY;YAmBN,cAAc;YA2Cd,aAAa;IAM3B;;;;OAIG;YACW,eAAe;IA+B7B,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,mBAAmB;YAOb,aAAa;YA4Bb,cAAc;YAcd,iBAAiB;YAiBjB,cAAc;YASd,YAAY;IAmC1B;;;;OAIG;YACW,qBAAqB;YAkBrB,SAAS;YAoDT,YAAY;YAqGZ,WAAW;YA0DX,SAAS;YAcT,UAAU;YA+BV,gBAAgB;YA0BhB,UAAU;IA8CxB;;;;OAIG;YACW,YAAY;IA4C1B;;;;;;OAMG;YACW,YAAY;IAyD1B;;;;OAIG;YACW,cAAc;YA2Cd,mBAAmB;IAQjC;;;;;OAKG;YACW,cAAc;IA2B5B;;;;OAIG;YACW,UAAU;IAiDxB,0DAA0D;IAC1D,OAAO,CAAC,oBAAoB;IAM5B,0HAA0H;IAC1H,OAAO,CAAC,gBAAgB;IAcxB,uEAAuE;YACzD,eAAe;YAgCf,UAAU;YA2CV,uBAAuB;YAWvB,gBAAgB;YAwChB,WAAW;YA2CX,UAAU;YAsCV,aAAa;YASb,aAAa;YA2Bb,UAAU;YAwCV,oBAAoB;IAsFlC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;;;OAIG;YACW,oBAAoB;YAgCpB,aAAa;YAiGb,aAAa;IA2D3B,OAAO,CAAC,iBAAiB;YASX,aAAa;IA4C3B;;;;OAIG;YACW,UAAU;YAuBV,iBAAiB;YAkEjB,gBAAgB;YAUhB,YAAY;YAcZ,WAAW;YAuCX,UAAU;YAKV,QAAQ;CAwBvB;AAID,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAAA;AAIhD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAgB7E;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAMpF"}

package/dist/server/server.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:net';
 import { writeFile, unlink } from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
-import { homedir, tmpdir } from 'node:os';
+import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { getAdapter } from '../adapters/registry.js';
@@ -28,8 +28,10 @@ import { AxTreeCache } from '../cdp/ax-cache.js';
 import { WatchSession } from './watch-session.js';
 import { StopReason, WATCH_MIN_INTERVAL_MS } from '../inspectors/watch/index.js';
 import { buildMatcher } from './pattern.js';
+import { findByLocator, locatorFromArgs, testIdAttributes } from './locator.js';
+import { SERVER_PORT, AGENT_VIEW_DIR, TOKEN_PATH } from './port.js';
+import { runAct } from './act-session.js';
 import { DEFAULT_TAIL_LINES, LogRecorder, filterLogLines, localStamp, parseSinceToken, readFeedLines, resolveLogFile, } from './log-recorder.js';
-const SERVER_PORT = 47922;
 /**
  * Every non-streaming command answers within this budget (plus its own `--timeout`,
  * for the commands that poll). A CDP call that never returns used to leave the CLI
@@ -43,8 +45,6 @@ const VALID_ENGINES = new Set(Object.values(WebGLEngine));
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
 const DELIMITER = '\n';
 const MAX_BUFFER_SIZE = 1_048_576; // 1 MB
-const TOKEN_DIR = join(homedir(), '.agent-view');
-const TOKEN_PATH = join(TOKEN_DIR, 'token');
 const EVAL_OUTPUT_CAP = 64 * 1024;
 const DEFAULT_CONSOLE_TARGETS = [TargetType.Page, TargetType.SharedWorker, TargetType.ServiceWorker];
 const DEFAULT_NETWORK_BUFFER = 200;
@@ -194,13 +194,14 @@ export class AgentViewServer {
         coverage: (req) => this.handleCoverage(req),
         listeners: (req) => this.handleListeners(req),
         heap: (req) => this.handleHeap(req),
+        act: (req) => this.handleAct(req),
         stop: () => this.handleStop(),
     };
     streamingCommands = new Set(['watch']);
     validCommands = new Set([...Object.keys(this.handlers), ...this.streamingCommands]);
     async start() {
         installCDPErrorGuard();
-        mkdirSync(TOKEN_DIR, { recursive: true });
+        mkdirSync(AGENT_VIEW_DIR, { recursive: true });
         this.token = randomBytes(32).toString('hex');
         // Publish the token only after winning the port. A server that loses the bind race
         // must not overwrite the live server's token — that leaves every CLI call
@@ -225,6 +226,7 @@ export class AgentViewServer {
                 networkRefs: new Map(),
                 networkNextRef: 1,
                 logRecorder: null,
+                act: null,
             };
             this.portStates.set(port, state);
         }
@@ -509,6 +511,7 @@ export class AgentViewServer {
             startRef: this.refStore.getNextRef(),
             compact,
             maxLines: argNum(req.args, 'maxLines'),
+            testIds: await conn.getTestIds(testIdAttributes(argStr(req.args, 'testIdAttribute'))),
         });
         this.refStore.store(refs, req.port, targetId, nextRef);
         if (isDiff) {
@@ -634,6 +637,15 @@ export class AgentViewServer {
             this.axTreeCache.invalidate(cacheKey);
             return { ok: true, data: `${verb} at (${x}, ${y})` };
         }
+        const locator = locatorFromArgs(req.args);
+        if (locator) {
+            const found = await findByLocator(conn, locator);
+            if ('error' in found)
+                return { ok: false, error: found.error };
+            await conn.clickByNodeId(found.backendDOMNodeId, clickOpts);
+            this.axTreeCache.invalidate(cacheKey);
+            return { ok: true, data: `${verb} ${found.label}` };
+        }
         const clickFilter = argStr(req.args, 'filter');
         if (clickFilter) {
             const filter = clickFilter;
@@ -648,7 +660,7 @@ export class AgentViewServer {
         }
         const ref = argNum(req.args, 'ref');
         if (ref === undefined) {
-            return { ok: false, error: 'click requires --ref, --filter, or --pos' };
+            return { ok: false, error: 'click requires --ref, --filter, --testid, --selector, or --pos' };
         }
         const entry = this.refStore.get(ref);
         if (!entry) {
@@ -658,6 +670,19 @@ export class AgentViewServer {
         this.axTreeCache.invalidate(cacheKey);
         return { ok: true, data: `${verb} ref ${ref}` };
     }
+    async handleAct(req) {
+        const { targetId } = await this.resolveWindow(req);
+        const cacheKey = `${req.port}:${targetId}`;
+        return runAct(this.stateFor(req.port), req.args, {
+            conn: await this.getPageSession(req, targetId),
+            invalidateAxCache: () => this.axTreeCache.invalidate(cacheKey),
+            // A login that reloads the window kills the cached socket before its disconnect event lands.
+            reconnect: async () => {
+                this.dropSessionsForPort(req.port);
+                return this.getPageSession(req, (await this.resolveWindow(req)).targetId);
+            },
+        });
+    }
     async handleDrag(req) {
         const { targetId } = await this.resolveWindow(req);
         const conn = await this.getPageSession(req, targetId);
@@ -712,6 +737,15 @@ export class AgentViewServer {
         if (value === undefined) {
             return { ok: false, error: 'fill requires --value' };
         }
+        const locator = locatorFromArgs(req.args);
+        if (locator) {
+            const found = await findByLocator(conn, locator);
+            if ('error' in found)
+                return { ok: false, error: found.error };
+            await conn.fillByNodeId(found.backendDOMNodeId, value);
+            this.axTreeCache.invalidate(cacheKey);
+            return { ok: true, data: `Filled ${found.label} with "${value}"` };
+        }
         const fillFilter = argStr(req.args, 'filter');
         if (fillFilter) {
             const filter = fillFilter;
@@ -726,7 +760,7 @@ export class AgentViewServer {
         }
         const fillRef = argNum(req.args, 'ref');
         if (fillRef === undefined) {
-            return { ok: false, error: 'fill requires --ref or --filter' };
+            return { ok: false, error: 'fill requires --ref, --filter, --testid, or --selector' };
         }
         const entry = this.refStore.get(fillRef);
         if (!entry) {
@@ -1035,14 +1069,25 @@ export class AgentViewServer {
     }
     async handleWait(req) {
         const filter = argStr(req.args, 'filter');
-        if (!filter) {
-            return { ok: false, error: 'wait requires --filter' };
+        const locator = locatorFromArgs(req.args);
+        if (!filter && !locator) {
+            return { ok: false, error: 'wait requires --filter, --testid, or --selector' };
         }
         const timeout = argNum(req.args, 'timeout') ?? 10;
         const interval = 500;
         const maxAttempts = Math.ceil((timeout * 1000) / interval);
         const { targetId } = await this.resolveWindow(req);
         const conn = await this.getPageSession(req, targetId);
+        if (locator) {
+            let found = await findByLocator(conn, locator);
+            for (let i = 1; i < maxAttempts && 'error' in found; i++) {
+                await new Promise(resolve => setTimeout(resolve, interval));
+                found = await findByLocator(conn, locator);
+            }
+            return 'error' in found
+                ? { ok: false, error: `Timeout after ${timeout}s: ${found.error}` }
+                : { ok: true, data: `Found ${found.label}` };
+        }
         for (let i = 0; i < maxAttempts; i++) {
             const nodes = await conn.getAccessibilityTree();
             const { refs, text, nextRef } = formatAccessibilityTree(nodes, {
@@ -1069,20 +1114,33 @@ export class AgentViewServer {
         const conn = await this.getPageSession(req, targetId);
         const scale = argNum(req.args, 'scale');
         const cropFilter = argStr(req.args, 'crop');
+        const locator = locatorFromArgs(req.args);
         let warning;
         let clip;
-        if (cropFilter !== undefined) {
+        let cropNode;
+        if (locator) {
+            // Unlike a text filter, an exact locator that misses is a wrong locator: a
+            // full-window fallback would spend ~19k vision tokens on the wrong question.
+            const found = await findByLocator(conn, locator);
+            if ('error' in found)
+                return { ok: false, error: found.error };
+            cropNode = found.backendDOMNodeId;
+        }
+        else if (cropFilter !== undefined) {
             const found = await this.findByFilter(conn, cropFilter, req, targetId);
-            if (!found) {
-                warning = `crop filter '${cropFilter}' matched nothing — capturing full window`;
+            if (found) {
+                cropNode = found.backendDOMNodeId;
             }
             else {
-                const cropUp = argNum(req.args, 'cropUp') ?? 0;
-                clip = await conn.getBoxRect(found.backendDOMNodeId, { scrollIntoView: true, ancestorLevels: cropUp });
-                if (clip.height < TEXT_LINE_HEIGHT_PX && cropUp === 0) {
-                    warning = `crop matched a text-sized box (${Math.round(clip.width)}×${Math.round(clip.height)}) — `
-                        + `pass --crop-up 1 (or 2) to capture the surrounding container instead`;
-                }
+                warning = `crop filter '${cropFilter}' matched nothing — capturing full window`;
+            }
+        }
+        if (cropNode !== undefined) {
+            const cropUp = argNum(req.args, 'cropUp') ?? 0;
+            clip = await conn.getBoxRect(cropNode, { scrollIntoView: true, ancestorLevels: cropUp });
+            if (clip.height < TEXT_LINE_HEIGHT_PX && cropUp === 0) {
+                warning = `crop matched a text-sized box (${Math.round(clip.width)}×${Math.round(clip.height)}) — `
+                    + `pass --crop-up 1 (or 2) to capture the surrounding container instead`;
             }
         }
         const filepath = await this.captureScreenshotToFile(conn, { scale, clip });