@vforsh/argus-client 0.2.0 → 0.3.0

package/dist/client/methods/page.js

@@ -0,0 +1,38 @@
+import { requestWatcher } from '../watcherRequest.js';
+/** Page interaction methods: click, visibility lock, reload. */
+export const createPageMethods = (ctx) => ({
+    domClick: async (watcherId, options) => {
+        const hasTarget = Boolean(options?.selector || options?.ref) || options?.x != null || options?.y != null;
+        if (!hasTarget) {
+            throw new Error('selector, ref, or x,y coordinates are required');
+        }
+        const { data } = await requestWatcher(ctx, watcherId, {
+            path: '/dom/click',
+            timeoutMs: ctx.requestTimeoutMs,
+            method: 'POST',
+            body: options,
+        });
+        return { matches: data.matches, clicked: data.clicked };
+    },
+    visibility: async (watcherId, options) => {
+        if (options?.action !== 'show' && options?.action !== 'hide') {
+            throw new Error("action must be 'show' or 'hide'");
+        }
+        const { data } = await requestWatcher(ctx, watcherId, {
+            path: '/visibility',
+            timeoutMs: ctx.requestTimeoutMs,
+            method: 'POST',
+            body: options,
+        });
+        return { attached: data.attached, state: data.state };
+    },
+    reload: async (watcherId, options = {}) => {
+        await requestWatcher(ctx, watcherId, {
+            path: '/reload',
+            timeoutMs: ctx.requestTimeoutMs,
+            method: 'POST',
+            body: { ignoreCache: options.ignoreCache ?? false },
+        });
+    },
+});
+//# sourceMappingURL=page.js.map

package/dist/client/methods/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../../src/client/methods/page.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAkB,EAAE,EAAE,CAAC,CAAC;IACzD,QAAQ,EAAE,KAAK,EAAE,SAAiB,EAAE,OAAwB,EAA2B,EAAE;QACxF,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC,IAAI,IAAI,IAAI,OAAO,EAAE,CAAC,IAAI,IAAI,CAAA;QACxG,IAAI,CAAC,SAAS,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;QAClE,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,cAAc,CAAmB,GAAG,EAAE,SAAS,EAAE;YACvE,IAAI,EAAE,YAAY;YAClB,SAAS,EAAE,GAAG,CAAC,gBAAgB;YAC/B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,OAAO;SACb,CAAC,CAAA;QAEF,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;IACxD,CAAC;IAED,UAAU,EAAE,KAAK,EAAE,SAAiB,EAAE,OAA0B,EAA6B,EAAE;QAC9F,IAAI,OAAO,EAAE,MAAM,KAAK,MAAM,IAAI,OAAO,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;QACnD,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,cAAc,CAAqB,GAAG,EAAE,SAAS,EAAE;YACzE,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,GAAG,CAAC,gBAAgB;YAC/B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,OAAO;SACb,CAAC,CAAA;QAEF,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAA;IACtD,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,SAAiB,EAAE,UAAyB,EAAE,EAAiB,EAAE;QAC/E,MAAM,cAAc,CAAiB,GAAG,EAAE,SAAS,EAAE;YACpD,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,GAAG,CAAC,gBAAgB;YAC/B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,KAAK,EAAE;SACnD,CAAC,CAAA;IACH,CAAC;CACD,CAAC,CAAA"}

package/dist/client/watcherHandle.d.ts

@@ -0,0 +1,9 @@
+import type { ArgusClient, WatcherClient } from '../types.js';
+/**
+ * Build a {@link WatcherClient}: the same API with `watcherId` pre-bound.
+ *
+ * `evalValue` is bound by hand rather than through {@link bind} so its generic
+ * type parameter survives.
+ */
+export declare const createWatcherClient: (client: ArgusClient, watcherId: string) => WatcherClient;
+//# sourceMappingURL=watcherHandle.d.ts.map

package/dist/client/watcherHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcherHandle.d.ts","sourceRoot":"","sources":["../../src/client/watcherHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAoB,aAAa,EAAE,MAAM,aAAa,CAAA;AAQ/E;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,WAAW,EAAE,WAAW,MAAM,KAAG,aAmB3E,CAAA"}

package/dist/client/watcherHandle.js

@@ -0,0 +1,29 @@
+/** Pre-apply `watcherId` as the first argument of a watcher-scoped method. */
+const bind = (method, watcherId) => (...args) => method(watcherId, ...args);
+/**
+ * Build a {@link WatcherClient}: the same API with `watcherId` pre-bound.
+ *
+ * `evalValue` is bound by hand rather than through {@link bind} so its generic
+ * type parameter survives.
+ */
+export const createWatcherClient = (client, watcherId) => ({
+    logs: bind(client.logs, watcherId),
+    logCursor: bind(client.logCursor, watcherId),
+    beginLogEpoch: bind(client.beginLogEpoch, watcherId),
+    net: bind(client.net, watcherId),
+    netRequest: bind(client.netRequest, watcherId),
+    netClear: bind(client.netClear, watcherId),
+    eval: bind(client.eval, watcherId),
+    evalValue: (expression, options) => client.evalValue(watcherId, expression, options),
+    evalUntil: bind(client.evalUntil, watcherId),
+    domClick: bind(client.domClick, watcherId),
+    visibility: bind(client.visibility, watcherId),
+    reload: bind(client.reload, watcherId),
+    traceStart: bind(client.traceStart, watcherId),
+    traceStop: bind(client.traceStop, watcherId),
+    screenshot: bind(client.screenshot, watcherId),
+    record: bind(client.record, watcherId),
+    recordStart: bind(client.recordStart, watcherId),
+    recordStop: bind(client.recordStop, watcherId),
+});
+//# sourceMappingURL=watcherHandle.js.map

package/dist/client/watcherHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcherHandle.js","sourceRoot":"","sources":["../../src/client/watcherHandle.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,IAAI,GACT,CAAyB,MAA4C,EAAE,SAAiB,EAAE,EAAE,CAC5F,CAAC,GAAG,IAAO,EAAK,EAAE,CACjB,MAAM,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAmB,EAAE,SAAiB,EAAiB,EAAE,CAAC,CAAC;IAC9F,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC;IAC5C,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,CAAC;IACpD,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC;IAChC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;IAC9C,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC1C,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;IAClC,SAAS,EAAE,CAAc,UAAkB,EAAE,OAA0B,EAAc,EAAE,CAAC,MAAM,CAAC,SAAS,CAAI,SAAS,EAAE,UAAU,EAAE,OAAO,CAAC;IAC3I,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC;IAC5C,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC1C,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;IAC9C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IACtC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;IAC9C,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC;IAC5C,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;IAC9C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IACtC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC;IAChD,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;CAC9C,CAAC,CAAA"}

package/dist/client/watcherRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcherRequest.d.ts","sourceRoot":"","sources":["../../src/client/watcherRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAIvD,KAAK,eAAe,GAAG;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,qBAAqB,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAA;CACd,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,CAAC,EAAE,SAAS,eAAe,EAAE,WAAW,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAQ7I,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,CAAC,EACrC,SAAS,eAAe,EACxB,WAAW,MAAM,EACjB,SAAS,qBAAqB,KAC5B,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAa3C,CAAA"}
+{"version":3,"file":"watcherRequest.d.ts","sourceRoot":"","sources":["../../src/client/watcherRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAIvD,KAAK,eAAe,GAAG;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,qBAAqB,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAA;CACd,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,CAAC,EAAE,SAAS,eAAe,EAAE,WAAW,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAQ7I,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,CAAC,EACrC,SAAS,eAAe,EACxB,WAAW,MAAM,EACjB,SAAS,qBAAqB,KAC5B,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAoB3C,CAAA"}

package/dist/client/watcherRequest.js

@@ -1,3 +1,4 @@
+import { isHttpResponseError } from '@vforsh/argus-core';
 import { fetchJson } from '../http/fetchJson.js';
 import { readAndPruneRegistry, removeWatcherAndPersist } from '../registry/readAndPruneRegistry.js';
 export const withWatcher = async (context, watcherId, callback) => {
@@ -18,6 +19,12 @@ export const requestWatcher = async (context, watcherId, options) => withWatcher
         return { watcher, data };
     }
     catch (error) {
+        // The watcher answered and rejected this request, so it is demonstrably alive.
+        // Evicting it here would break every later call in the process over one bad
+        // selector or a page that happens to be mid-navigation.
+        if (isHttpResponseError(error)) {
+            throw new Error(`${watcher.id}: ${error.message}`);
+        }
         await removeWatcherAndPersist(watcher.id, context.registryPath);
         throw new Error(formatWatcherTransportError(watcher, error));
     }

package/dist/client/watcherRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"watcherRequest.js","sourceRoot":"","sources":["../../src/client/watcherRequest.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAA;AAenG,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAK,OAAwB,EAAE,SAAiB,EAAE,QAAgD,EAAc,EAAE;IACjJ,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;IACzG,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sBAAsB,SAAS,EAAE,CAAC,CAAA;IACnD,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAA;AACzB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAClC,OAAwB,EACxB,SAAiB,EACjB,OAA8B,EACiB,EAAE,CACjD,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;IACjD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,MAAM,SAAS,CAAI,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE;YACtF,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;SAClB,CAAC,CAAA;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,uBAAuB,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;QAC/D,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;IAC7D,CAAC;AACF,CAAC,CAAC,CAAA;AAEH,MAAM,eAAe,GAAG,CAAC,OAA6C,EAAE,IAAY,EAAE,KAAuB,EAAU,EAAE;IACxH,MAAM,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAA;IAC5B,OAAO,UAAU,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC5E,CAAC,CAAA;AAED,MAAM,2BAA2B,GAAG,CAAC,OAAkC,EAAE,KAAc,EAAU,EAAE,CAClG,GAAG,OAAO,CAAC,EAAE,8BAA8B,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAA;AAExE,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAU,EAAE;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,eAAe,CAAA;IACvB,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,OAAO,CAAA;IACrB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACrB,CAAC,CAAA"}
+{"version":3,"file":"watcherRequest.js","sourceRoot":"","sources":["../../src/client/watcherRequest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAExD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAA;AAenG,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAK,OAAwB,EAAE,SAAiB,EAAE,QAAgD,EAAc,EAAE;IACjJ,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;IACzG,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sBAAsB,SAAS,EAAE,CAAC,CAAA;IACnD,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAA;AACzB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAClC,OAAwB,EACxB,SAAiB,EACjB,OAA8B,EACiB,EAAE,CACjD,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;IACjD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,MAAM,SAAS,CAAI,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE;YACtF,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;SAClB,CAAC,CAAA;QACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,+EAA+E;QAC/E,4EAA4E;QAC5E,wDAAwD;QACxD,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,EAAE,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;QACnD,CAAC;QAED,MAAM,uBAAuB,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;QAC/D,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;IAC7D,CAAC;AACF,CAAC,CAAC,CAAA;AAEH,MAAM,eAAe,GAAG,CAAC,OAA6C,EAAE,IAAY,EAAE,KAAuB,EAAU,EAAE;IACxH,MAAM,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAA;IAC5B,OAAO,UAAU,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC5E,CAAC,CAAA;AAED,MAAM,2BAA2B,GAAG,CAAC,OAAkC,EAAE,KAAc,EAAU,EAAE,CAClG,GAAG,OAAO,CAAC,EAAE,8BAA8B,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAA;AAExE,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAU,EAAE;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,eAAe,CAAA;IACvB,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,OAAO,CAAA;IACrB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACrB,CAAC,CAAA"}

package/dist/eval/ArgusEvalError.d.ts

@@ -0,0 +1,30 @@
+/** The page exception shape carried by `EvalResponse.exception`. */
+type EvalException = {
+    text: string;
+    details?: unknown;
+};
+/**
+ * Thrown when an expression raises inside the page.
+ *
+ * Only value-returning eval APIs (`evalValue`, `evalUntil`) throw this. Raw
+ * `client.eval` keeps reporting page exceptions in its `exception` field so callers
+ * can inspect a failure without a try/catch.
+ */
+export declare class ArgusEvalError extends Error {
+    /** Structured exception detail from the page, when the transport provided one. */
+    readonly details?: unknown;
+    /**
+     * @param text Page-side exception text, used as the error message.
+     * @param details Optional structured exception detail from CDP.
+     */
+    constructor(text: string, details?: unknown);
+    /**
+     * Build an error from a watcher exception payload.
+     *
+     * CDP reports `text` as a bare `"Uncaught"` for thrown errors and puts the real
+     * message plus stack in `details.description`, so prefer that when present.
+     */
+    static fromException(exception: EvalException): ArgusEvalError;
+}
+export {};
+//# sourceMappingURL=ArgusEvalError.d.ts.map

package/dist/eval/ArgusEvalError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgusEvalError.d.ts","sourceRoot":"","sources":["../../src/eval/ArgusEvalError.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,KAAK,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAExD;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAE1B;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAM3C;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,aAAa,GAAG,cAAc;CAG9D"}

package/dist/eval/ArgusEvalError.js

@@ -0,0 +1,37 @@
+/**
+ * Thrown when an expression raises inside the page.
+ *
+ * Only value-returning eval APIs (`evalValue`, `evalUntil`) throw this. Raw
+ * `client.eval` keeps reporting page exceptions in its `exception` field so callers
+ * can inspect a failure without a try/catch.
+ */
+export class ArgusEvalError extends Error {
+    /** Structured exception detail from the page, when the transport provided one. */
+    details;
+    /**
+     * @param text Page-side exception text, used as the error message.
+     * @param details Optional structured exception detail from CDP.
+     */
+    constructor(text, details) {
+        super(text);
+        this.name = 'ArgusEvalError';
+        this.details = details;
+    }
+    /**
+     * Build an error from a watcher exception payload.
+     *
+     * CDP reports `text` as a bare `"Uncaught"` for thrown errors and puts the real
+     * message plus stack in `details.description`, so prefer that when present.
+     */
+    static fromException(exception) {
+        return new ArgusEvalError(readExceptionDescription(exception.details) ?? exception.text, exception.details);
+    }
+}
+const readExceptionDescription = (details) => {
+    if (details == null || typeof details !== 'object' || !('description' in details)) {
+        return undefined;
+    }
+    const { description } = details;
+    return typeof description === 'string' && description.trim() ? description : undefined;
+};
+//# sourceMappingURL=ArgusEvalError.js.map

package/dist/eval/ArgusEvalError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgusEvalError.js","sourceRoot":"","sources":["../../src/eval/ArgusEvalError.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACxC,kFAAkF;IACzE,OAAO,CAAU;IAE1B;;;OAGG;IACH,YAAY,IAAY,EAAE,OAAiB;QAC1C,KAAK,CAAC,IAAI,CAAC,CAAA;QACX,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACvB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,SAAwB;QAC5C,OAAO,IAAI,cAAc,CAAC,wBAAwB,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC5G,CAAC;CACD;AAED,MAAM,wBAAwB,GAAG,CAAC,OAAgB,EAAsB,EAAE;IACzE,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,aAAa,IAAI,OAAO,CAAC,EAAE,CAAC;QACnF,OAAO,SAAS,CAAA;IACjB,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,GAAG,OAAoC,CAAA;IAC5D,OAAO,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAA;AACvF,CAAC,CAAA"}

package/dist/eval/pollEval.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Transport-agnostic eval polling loop shared by the CLI (`eval --interval`,
+ * `eval-until`) and the SDK (`evalUntil`), so loop semantics stay identical.
+ *
+ * The loop owns only timing and stop conditions. Everything environment-specific —
+ * how an eval is performed, retry policy, signal handling, output — is injected by
+ * the caller. In particular this module installs no process listeners: cancellation
+ * is an `AbortSignal` so it stays safe to use inside a library.
+ */
+/** Per-iteration context handed to stop conditions and result observers. */
+export type EvalPollContext<TResponse> = {
+    response: TResponse;
+    /** 1-based poll iteration. */
+    iteration: number;
+    /** 1-based attempt number within the iteration, when the caller retries. */
+    attempt: number;
+};
+/** Verdict from a stop condition: matched, not matched, or the condition itself failed. */
+export type EvalPollStopDecision = {
+    ok: true;
+    matched: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** Outcome of one injected eval attempt. */
+export type EvalPollAttempt<TResponse, TFailure> = {
+    ok: true;
+    response: TResponse;
+    attempt: number;
+} | {
+    ok: false;
+    failure: TFailure;
+    attempt: number;
+};
+/** Inputs for {@link pollEval}. */
+export type EvalPollInput<TResponse, TFailure> = {
+    /** Perform one eval. Callers wrap their own retry policy in here. */
+    runEval: (iteration: number) => Promise<EvalPollAttempt<TResponse, TFailure>>;
+    /** Delay between polls in milliseconds. */
+    intervalMs: number;
+    /** Stop after this many polls. Unlimited when omitted. */
+    count?: number;
+    /** Give up after this much wall-clock time. Unlimited when omitted. */
+    totalTimeoutMs?: number;
+    /** Decide whether to stop. Omitted means "never match" — useful for streaming. */
+    shouldStop?: (context: EvalPollContext<TResponse>) => EvalPollStopDecision;
+    /** Observe every result, including the matching one. */
+    onResult?: (response: TResponse, context: EvalPollContext<TResponse>) => void | Promise<void>;
+    /** Cancel the loop. Yields an `interrupted` outcome rather than throwing. */
+    signal?: AbortSignal;
+};
+/** Terminal state of a poll loop. */
+export type EvalPollOutcome<TResponse, TFailure> = {
+    kind: 'matched';
+    response: TResponse;
+    iteration: number;
+    attempt: number;
+} | {
+    kind: 'exhausted';
+    iterations: number;
+} | {
+    kind: 'timeout';
+    elapsedMs: number;
+} | {
+    kind: 'interrupted';
+} | {
+    kind: 'eval-error';
+    failure: TFailure;
+} | {
+    kind: 'condition-error';
+    error: string;
+};
+/**
+ * Poll `runEval` until a stop condition matches, the budget runs out, or the signal aborts.
+ *
+ * Results are reported to `onResult` before stop conditions are checked, so streaming
+ * callers print the matching iteration too.
+ */
+export declare const pollEval: <TResponse, TFailure>(input: EvalPollInput<TResponse, TFailure>) => Promise<EvalPollOutcome<TResponse, TFailure>>;
+//# sourceMappingURL=pollEval.d.ts.map

package/dist/eval/pollEval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollEval.d.ts","sourceRoot":"","sources":["../../src/eval/pollEval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,eAAe,CAAC,SAAS,IAAI;IACxC,QAAQ,EAAE,SAAS,CAAA;IACnB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;CACf,CAAA;AAED,2FAA2F;AAC3F,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhG,4CAA4C;AAC5C,MAAM,MAAM,eAAe,CAAC,SAAS,EAAE,QAAQ,IAC5C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD,mCAAmC;AACnC,MAAM,MAAM,aAAa,CAAC,SAAS,EAAE,QAAQ,IAAI;IAChD,qEAAqE;IACrE,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC7E,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kFAAkF;IAClF,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,oBAAoB,CAAA;IAC1E,wDAAwD;IACxD,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7F,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,CAAC,SAAS,EAAE,QAAQ,IAC5C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAU,SAAS,EAAE,QAAQ,EAAE,OAAO,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAG,OAAO,CAAC,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,CAwC3I,CAAA"}

package/dist/eval/pollEval.js

@@ -0,0 +1,65 @@
+/**
+ * Transport-agnostic eval polling loop shared by the CLI (`eval --interval`,
+ * `eval-until`) and the SDK (`evalUntil`), so loop semantics stay identical.
+ *
+ * The loop owns only timing and stop conditions. Everything environment-specific —
+ * how an eval is performed, retry policy, signal handling, output — is injected by
+ * the caller. In particular this module installs no process listeners: cancellation
+ * is an `AbortSignal` so it stays safe to use inside a library.
+ */
+/**
+ * Poll `runEval` until a stop condition matches, the budget runs out, or the signal aborts.
+ *
+ * Results are reported to `onResult` before stop conditions are checked, so streaming
+ * callers print the matching iteration too.
+ */
+export const pollEval = async (input) => {
+    const startTime = Date.now();
+    let iteration = 0;
+    while (!input.signal?.aborted) {
+        if (input.totalTimeoutMs != null) {
+            const elapsedMs = Date.now() - startTime;
+            if (elapsedMs >= input.totalTimeoutMs) {
+                return { kind: 'timeout', elapsedMs };
+            }
+        }
+        iteration += 1;
+        const result = await input.runEval(iteration);
+        if (!result.ok) {
+            return { kind: 'eval-error', failure: result.failure };
+        }
+        const context = { response: result.response, iteration, attempt: result.attempt };
+        // Streaming callers print the matched iteration too, so emit before checking stop conditions.
+        await input.onResult?.(result.response, context);
+        const decision = input.shouldStop?.(context);
+        if (decision) {
+            if (!decision.ok) {
+                return { kind: 'condition-error', error: decision.error };
+            }
+            if (decision.matched) {
+                return { kind: 'matched', response: result.response, iteration, attempt: result.attempt };
+            }
+        }
+        if (input.count != null && iteration >= input.count) {
+            return { kind: 'exhausted', iterations: iteration };
+        }
+        await sleep(input.intervalMs, input.signal);
+    }
+    return { kind: 'interrupted' };
+};
+/** Resolve after `durationMs`, or immediately once `signal` aborts. */
+const sleep = async (durationMs, signal) => {
+    if (signal?.aborted) {
+        return;
+    }
+    await new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, durationMs);
+        signal?.addEventListener('abort', finish, { once: true });
+    });
+};
+//# sourceMappingURL=pollEval.js.map

package/dist/eval/pollEval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollEval.js","sourceRoot":"","sources":["../../src/eval/pollEval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8CH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAuB,KAAyC,EAAiD,EAAE;IAC/I,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAC5B,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;YACxC,IAAI,SAAS,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;gBACvC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAA;YACtC,CAAC;QACF,CAAC;QAED,SAAS,IAAI,CAAC,CAAA;QACd,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAC7C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YAChB,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;QACvD,CAAC;QAED,MAAM,OAAO,GAA+B,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;QAC7G,8FAA8F;QAC9F,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAEhD,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAA;QAC5C,IAAI,QAAQ,EAAE,CAAC;YACd,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAClB,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAA;YAC1D,CAAC;YACD,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;YAC1F,CAAC;QACF,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI,IAAI,SAAS,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACrD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,CAAA;QACpD,CAAC;QAED,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAA;AAC/B,CAAC,CAAA;AAED,uEAAuE;AACvE,MAAM,KAAK,GAAG,KAAK,EAAE,UAAkB,EAAE,MAAoB,EAAiB,EAAE;IAC/E,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACrB,OAAM;IACP,CAAC;IAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YAC5C,OAAO,EAAE,CAAA;QACV,CAAC,CAAA;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;QAC5C,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1D,CAAC,CAAC,CAAA;AACH,CAAC,CAAA"}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-export type { ArgusClient, ArgusClientOptions, EvalOptions, EvalResult, ListOptions, ListResult, LogsMode, LogsOptions, LogsResult, LogCursorResult, LogEpochResult, NetOptions, NetResult, ScreenshotOptions, ScreenshotResult, TraceStartOptions, TraceStartResult, TraceStopOptions, TraceStopResult, } from './types.js';
+export type { ArgusClient, ArgusClientOptions, DomClickOptions, DomClickResult, EvalOptions, EvalResult, EvalUntilOptions, EvalUntilResult, EvalValueOptions, ListOptions, ListResult, LogsMode, LogsOptions, LogsResult, LogCursorResult, LogEpochResult, NetClearResult, NetOptions, NetResult, RecordCaptureOptions, RecordOptions, RecordStartResult, RecordStopOptions, RecordStopResult, ReloadOptions, ScreenshotOptions, ScreenshotResult, TraceStartOptions, TraceStartResult, TraceStopOptions, TraceStopResult, VisibilityOptions, VisibilityResult, WatcherClient, } from './types.js';
 export { createArgusClient } from './client/createArgusClient.js';
+export { ArgusEvalError } from './eval/ArgusEvalError.js';
+export { pollEval } from './eval/pollEval.js';
+export type { EvalPollAttempt, EvalPollContext, EvalPollInput, EvalPollOutcome, EvalPollStopDecision } from './eval/pollEval.js';
 export type { LogEpoch } from '@vforsh/argus-core';
 export type { NetworkRequestDetail } from '@vforsh/argus-core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,eAAe,EACf,cAAc,EACd,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GACf,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,GACb,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAChI,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -1,2 +1,4 @@
 export { createArgusClient } from './client/createArgusClient.js';
+export { ArgusEvalError } from './eval/ArgusEvalError.js';
+export { pollEval } from './eval/pollEval.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { LogEvent, LogEpoch, LogLevel, NetworkRequestDetail, NetworkRequestSummary, ScreenshotClipRegion, StatusResponse, WatcherRecord } from '@vforsh/argus-core';
+import type { ElementRef, LogEvent, LogEpoch, LogLevel, MouseButton, NetworkRequestDetail, NetworkRequestSummary, RecordClipRegion, RecordFormat, ScreenshotClipRegion, StatusResponse, VisibilityLock, WatcherRecord } from '@vforsh/argus-core';
 /** Options for configuring the Argus client. */
 export type ArgusClientOptions = {
     /** Override registry path instead of using `ARGUS_REGISTRY_PATH` / default. */
@@ -100,6 +100,14 @@ export type EvalOptions = {
     timeoutMs?: number;
     /** Return by value when possible. Defaults to true. */
     returnByValue?: boolean;
+    /**
+     * Serialize the result inside the page and return that JSON string as `result`,
+     * wrapped as `{"v":<value>}`. Defaults to false.
+     *
+     * Prefer {@link ArgusClient.evalValue}, which sets this and parses the envelope
+     * for you. See {@link EvalValueOptions.jsonValue} for why the mode exists.
+     */
+    jsonValue?: boolean;
     /** Install the temporary host bridge expected by bundled Argus scenario code. */
     scenario?: boolean;
 };
@@ -149,6 +157,153 @@ export type ScreenshotResult = {
     outFile: string;
     clipped: boolean;
 };
+/** Options for clicking in the connected page. Mirrors CLI `argus click` semantics. */
+export type DomClickOptions = {
+    /** CSS selector to match element(s). */
+    selector?: string;
+    /** Stable element ref to click. Mutually exclusive with `selector`. */
+    ref?: ElementRef;
+    /** Allow multiple matches. If false and >1 match, the watcher errors. Defaults to false. */
+    all?: boolean;
+    /** Viewport x-coordinate, or x-offset from element top-left when `selector` is set. */
+    x?: number;
+    /** Viewport y-coordinate, or y-offset from element top-left when `selector` is set. */
+    y?: number;
+    /** Mouse button to click. Defaults to 'left'. */
+    button?: MouseButton;
+    /** Filter elements by trimmed textContent. Plain string = exact match, `/regex/flags` = regex test. */
+    text?: string;
+    /** Wait up to this many ms for the selector to appear before clicking. */
+    wait?: number;
+};
+/** Result of a click, reporting selector matches separately from actual clicks. */
+export type DomClickResult = {
+    /** Number of elements matched by the selector. */
+    matches: number;
+    /** Number of elements actually clicked. */
+    clicked: number;
+};
+/** Result of clearing the watcher's buffered network log. */
+export type NetClearResult = {
+    /** Number of buffered requests removed. */
+    cleared: number;
+};
+/** Options for the page visibility lock. */
+export type VisibilityOptions = {
+    /** `show` locks the page shown+focused; `hide` releases the lock. */
+    action: 'show' | 'hide';
+};
+/**
+ * Visibility lock result. The desired lock is sticky across detach/reattach:
+ * the watcher remembers it and re-applies on the next attach when `attached` is false.
+ */
+export type VisibilityResult = {
+    /** Whether the watcher was attached to a CDP target at response time. */
+    attached: boolean;
+    /** Current desired visibility lock. */
+    state: VisibilityLock;
+};
+/** Options for reloading the connected page. */
+export type ReloadOptions = {
+    /** Bypass the browser cache. Defaults to false. */
+    ignoreCache?: boolean;
+};
+/** Shared options for video recording requests. */
+export type RecordOptions = {
+    /** Destination path on the watcher host. Extension may determine `format`. */
+    outFile?: string;
+    /** Record only the element matched by this CSS selector. Mutually exclusive with `clip`. */
+    selector?: string;
+    /** Viewport-relative crop rectangle in CSS pixels. Mutually exclusive with `selector`. */
+    clip?: RecordClipRegion;
+    /** Output frames per second (1-60). Defaults to 30. */
+    fps?: number;
+    /** Output container. Defaults to mp4 unless inferred from the `outFile` extension. */
+    format?: RecordFormat;
+};
+/** Options for a fixed-duration one-shot recording. */
+export type RecordCaptureOptions = RecordOptions & {
+    /** Capture duration in milliseconds. Must be greater than 0. */
+    durationMs: number;
+};
+/** Metadata returned when a recording starts. */
+export type RecordStartResult = {
+    /** Handle for the active recording, accepted by `recordStop`. */
+    recordId: string;
+    sessionName: string;
+    outFile: string;
+    format: RecordFormat;
+    fps: number;
+    /** Whether a `selector` or `clip` crop was applied. */
+    clipped: boolean;
+};
+/** Metadata returned when a recording is finalized. */
+export type RecordStopResult = RecordStartResult & {
+    /** Number of frames written to `outFile`. */
+    frameCount: number;
+    /** Wall-clock capture duration in milliseconds. */
+    durationMs: number;
+};
+/** Options for stopping an active recording. */
+export type RecordStopOptions = {
+    /** Recording to stop. Defaults to the watcher's active recording. */
+    recordId?: string;
+    /** Move the finalized file to this path before returning. */
+    outFile?: string;
+};
+/**
+ * Options for {@link ArgusClient.evalValue}.
+ *
+ * Omits `returnByValue` (always true) and adds {@link EvalValueOptions.jsonValue}.
+ */
+export type EvalValueOptions = Omit<EvalOptions, 'expression' | 'returnByValue' | 'jsonValue'> & {
+    /**
+     * Have the page serialize the result, so the JSON string — not a structured object —
+     * crosses the transport. Defaults to true.
+     *
+     * This exists because transports disagree about raw `returnByValue` results: the
+     * extension relay (Chrome's `chrome.debugger` serialization) returns object keys
+     * sorted alphabetically at every nesting level, while a direct CDP watcher preserves
+     * insertion order. Values are identical either way, but structural comparisons of the
+     * same page state produce different bytes per transport — which silently breaks
+     * snapshot assertions in verification runners. Serializing in the page normalizes both
+     * to insertion order, and makes `Date` round-trip as an ISO string (via `toJSON`)
+     * instead of `{}`.
+     *
+     * Evaluation semantics are unaffected: statement lists, top-level `await`, REPL-mode
+     * redeclaration, and promise unwrapping behave the same either way.
+     *
+     * Set to false for the raw transport-native value — one less serialization round-trip
+     * for large payloads you never compare structurally, at the cost of transport-dependent
+     * key order.
+     */
+    jsonValue?: boolean;
+};
+/** Options for {@link ArgusClient.evalUntil}. */
+export type EvalUntilOptions = EvalValueOptions & {
+    /** Delay between polls in milliseconds. Defaults to 250. */
+    intervalMs?: number;
+    /** Give up after this much wall-clock time. Defaults to 30000. */
+    totalTimeoutMs?: number;
+    /** Give up after this many polls. Unlimited when omitted. */
+    count?: number;
+    /**
+     * Stop condition evaluated against each poll's value.
+     * Defaults to a truthiness check on the returned value.
+     */
+    predicate?: (value: unknown, iteration: number) => boolean;
+    /** Abort the poll loop early. The returned promise rejects when aborted. */
+    signal?: AbortSignal;
+};
+/** Result of a successful {@link ArgusClient.evalUntil} poll. */
+export type EvalUntilResult = {
+    /** The value that satisfied the predicate. */
+    value: unknown;
+    /** 1-based poll iteration that matched. */
+    iteration: number;
+    /** Wall-clock milliseconds spent polling. */
+    elapsedMs: number;
+};
 /** Argus client API. */
 export type ArgusClient = {
     /** List registered watcher servers. */
@@ -163,13 +318,73 @@ export type ArgusClient = {
     net: (watcherId: string, options?: NetOptions) => Promise<NetResult>;
     /** Fetch the detailed record for one buffered network request. */
     netRequest: (watcherId: string, request: number | string) => Promise<NetworkRequestDetail>;
-    /** Evaluate a JS expression in the connected page. */
+    /** Clear the watcher's buffered network log. */
+    netClear: (watcherId: string) => Promise<NetClearResult>;
+    /**
+     * Evaluate a JS expression in the connected page and return the raw envelope.
+     * Page-side exceptions are reported in `exception`, not thrown.
+     */
     eval: (watcherId: string, options: EvalOptions) => Promise<EvalResult>;
+    /**
+     * Evaluate a JS expression and return its value directly.
+     *
+     * Unlike {@link ArgusClient.eval}, a page-side exception rejects with an `Error`
+     * carrying `exception.text` as its message. Results are normalized across transports
+     * by default — see {@link EvalValueOptions.jsonValue}.
+     *
+     * @throws {Error} When the expression throws in the page.
+     */
+    evalValue: <T = unknown>(watcherId: string, expression: string, options?: EvalValueOptions) => Promise<T>;
+    /**
+     * Poll an expression until it satisfies a predicate (truthy by default).
+     *
+     * @throws {Error} On page-side exceptions, total-timeout expiry, poll-count
+     * exhaustion, or abort via {@link EvalUntilOptions.signal}.
+     */
+    evalUntil: (watcherId: string, expression: string, options?: EvalUntilOptions) => Promise<EvalUntilResult>;
+    /** Click in the connected page by selector, element ref, or viewport coordinates. */
+    domClick: (watcherId: string, options: DomClickOptions) => Promise<DomClickResult>;
+    /** Lock the page shown+focused, or release the lock. */
+    visibility: (watcherId: string, options: VisibilityOptions) => Promise<VisibilityResult>;
+    /** Reload the connected page. Page-scoped even when the active target is an iframe. */
+    reload: (watcherId: string, options?: ReloadOptions) => Promise<void>;
     /** Start Chrome tracing and write to disk on the watcher. */
     traceStart: (watcherId: string, options?: TraceStartOptions) => Promise<TraceStartResult>;
     /** Stop an active Chrome trace and finalize the file. */
     traceStop: (watcherId: string, options?: TraceStopOptions) => Promise<TraceStopResult>;
     /** Capture a screenshot and write to disk on the watcher. */
     screenshot: (watcherId: string, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
+    /** Capture a fixed-duration silent video and write it to disk on the watcher. */
+    record: (watcherId: string, options: RecordCaptureOptions) => Promise<RecordStopResult>;
+    /** Begin an open-ended silent video recording. Finalize with `recordStop`. */
+    recordStart: (watcherId: string, options?: RecordOptions) => Promise<RecordStartResult>;
+    /** Stop the active recording and finalize the file. */
+    recordStop: (watcherId: string, options?: RecordStopOptions) => Promise<RecordStopResult>;
+    /** Bind every watcher-scoped method to `watcherId`, removing id-threading at call sites. */
+    watcher: (watcherId: string) => WatcherClient;
+};
+/**
+ * Watcher-scoped subset of {@link ArgusClient}: everything that takes a watcher id first.
+ * `evalValue` is excluded because a mapped type erases its generic type parameter;
+ * {@link WatcherClient} redeclares it explicitly.
+ */
+type WatcherScopedApi = Omit<ArgusClient, 'list' | 'watcher' | 'evalValue'>;
+/**
+ * The same API as {@link ArgusClient} with `watcherId` pre-bound.
+ *
+ * @example
+ * const page = client.watcher('playground')
+ * const count = await page.evalValue<number>('document.querySelectorAll("li").length')
+ */
+export type WatcherClient = {
+    [K in keyof WatcherScopedApi]: WatcherScopedApi[K] extends (watcherId: string, ...rest: infer A) => infer R ? (...args: A) => R : never;
+} & {
+    /**
+     * Evaluate a JS expression and return its value directly.
+     *
+     * @throws {Error} When the expression throws in the page.
+     */
+    evalValue: <T = unknown>(expression: string, options?: EvalValueOptions) => Promise<T>;
 };
+export {};
 //# sourceMappingURL=types.d.ts.map