@jackwener/opencli 1.5.2 → 1.5.3

package/docs/superpowers/specs/2026-03-28-perf-smart-wait-design.md

@@ -0,0 +1,170 @@
+# Performance: Smart Wait & INTERCEPT Fix
+
+**Date**: 2026-03-28
+**Status**: Approved
+
+## Problem
+
+Three distinct performance/correctness issues:
+
+1. **INTERCEPT strategy semantic bug**: After `installInterceptor()` + `goto()`, adapters call `wait(N)` — which now uses `waitForDomStableJs` and returns early when the DOM settles. But DOM-settle != network capture. The API response may arrive *after* DOM is stable, causing `getInterceptedRequests()` to return an empty array.
+
+2. **Blind `wait(N)` in adapters**: ~30 high-traffic adapters (Twitter family, Medium, Substack, etc.) call `wait(5)` waiting for React/Vue to hydrate. These should wait for a specific DOM element to appear, not a fixed cap.
+
+3. **Daemon cold-start polling**: Fixed 300ms poll loop means ~600ms before first successful `isExtensionConnected()` check, even though the daemon is typically ready in 500–800ms.
+
+## Design
+
+### Layer 1 — `waitForCapture()` (correctness fix + perf)
+
+Add `waitForCapture(timeout?: number): Promise<void>` to `IPage`.
+
+Polls `window.__opencli_xhr.length > 0` every 100ms inside the browser tab. Resolves as soon as ≥1 capture arrives; rejects after `timeout` seconds.
+
+```typescript
+// dom-helpers.ts
+export function waitForCaptureJs(maxMs: number): string {
+  return `
+    new Promise((resolve, reject) => {
+      const deadline = Date.now() + ${maxMs};
+      const check = () => {
+        if ((window.__opencli_xhr || []).length > 0) return resolve('captured');
+        if (Date.now() > deadline) return reject(new Error('No capture within ${maxMs / 1000}s'));
+        setTimeout(check, 100);
+      };
+      check();
+    })
+  `;
+}
+```
+
+`page.ts` and `cdp.ts` implement `waitForCapture()` by calling `waitForCaptureJs`.
+
+**All INTERCEPT adapters** replace `wait(N)` → `waitForCapture(N+2)` (slightly longer timeout as safety margin).
+
+`stepIntercept` in `pipeline/steps/intercept.ts` replaces its internal `wait(timeout)` with `waitForCapture(timeout)`.
+
+**Expected gain**: 36kr hot/search: 6s → ~1–2s. Twitter search/followers: 5–8s → ~1–3s.
+
+### Layer 2 — `wait({ selector })` (semantic precision)
+
+Extend `WaitOptions` with `selector?: string`.
+
+Add `waitForSelectorJs(selector, timeoutMs)` to `dom-helpers.ts` — polls `document.querySelector(selector)` every 100ms, resolves on first match, rejects on timeout.
+
+```typescript
+// types.ts
+export interface WaitOptions {
+  text?: string;
+  selector?: string;   // NEW
+  time?: number;
+  timeout?: number;
+}
+```
+
+```typescript
+// dom-helpers.ts
+export function waitForSelectorJs(selector: string, timeoutMs: number): string {
+  return `
+    new Promise((resolve, reject) => {
+      const deadline = Date.now() + ${timeoutMs};
+      const check = () => {
+        if (document.querySelector(${JSON.stringify(selector)})) return resolve('found');
+        if (Date.now() > deadline) return reject(new Error('Selector not found: ' + ${JSON.stringify(selector)}));
+        setTimeout(check, 100);
+      };
+      check();
+    })
+  `;
+}
+```
+
+`page.ts` and `cdp.ts` handle `selector` branch in `wait()`.
+
+**High-impact adapter changes**:
+
+| Adapter | Old | New |
+|---------|-----|-----|
+| `twitter/*` (15 adapters) | `wait(5)` | `wait({ selector: '[data-testid="primaryColumn"]', timeout: 6 })` |
+| `twitter/reply.ts` | `wait(5)` | `wait({ selector: '[data-testid="tweetTextarea_0"]', timeout: 8 })` |
+| `medium/utils.ts` | `wait(5)` + inline 3s setTimeout | `wait({ selector: 'article', timeout: 8 })` + remove inline sleep |
+| `substack/utils.ts` | `wait(5)` × 2 | `wait({ selector: 'article', timeout: 8 })` |
+| `bloomberg/news.ts` | `wait(5)` | `wait({ selector: 'article', timeout: 6 })` |
+| `sinablog/utils.ts` | `wait(5)` | `wait({ selector: 'article, .article', timeout: 6 })` |
+| `producthunt` (already covered by layer 1) | — | — |
+
+**Expected gain**: Twitter commands: 5s → ~0.5–2s. Medium: 8s → ~1–3s.
+
+### Layer 3 — Daemon exponential backoff (cold-start)
+
+Replace fixed 300ms poll in `_ensureDaemon()` (`browser/mcp.ts`) with exponential backoff:
+
+```typescript
+// before
+while (Date.now() < deadline) {
+  await new Promise(resolve => setTimeout(resolve, 300));
+  if (await isExtensionConnected()) return;
+}
+
+// after
+const backoffs = [50, 100, 200, 400, 800, 1500, 3000];
+let i = 0;
+while (Date.now() < deadline) {
+  await new Promise(resolve => setTimeout(resolve, backoffs[Math.min(i++, backoffs.length - 1)]));
+  if (await isExtensionConnected()) return;
+}
+```
+
+**Expected gain**: First cold-start check succeeds at ~150ms instead of ~600ms.
+
+## Files Changed
+
+### New / Modified (framework)
+- `src/types.ts` — `WaitOptions.selector`, `IPage.waitForCapture()`
+- `src/browser/dom-helpers.ts` — `waitForCaptureJs()`, `waitForSelectorJs()`
+- `src/browser/page.ts` — `waitForCapture()`, `wait()` selector branch
+- `src/browser/cdp.ts` — `waitForCapture()`, `wait()` selector branch
+- `src/browser/mcp.ts` — exponential backoff in `_ensureDaemon()`
+- `src/pipeline/steps/intercept.ts` — use `waitForCapture()`
+
+### Modified (adapters — Layer 1, INTERCEPT)
+- `src/clis/36kr/hot.ts`
+- `src/clis/36kr/search.ts`
+- `src/clis/twitter/search.ts`
+- `src/clis/twitter/followers.ts`
+- `src/clis/twitter/following.ts`
+- `src/clis/producthunt/hot.ts`
+- `src/clis/producthunt/browse.ts`
+
+### Modified (adapters — Layer 2, selector)
+- `src/clis/twitter/reply.ts`
+- `src/clis/twitter/follow.ts`
+- `src/clis/twitter/unfollow.ts`
+- `src/clis/twitter/like.ts`
+- `src/clis/twitter/bookmark.ts`
+- `src/clis/twitter/unbookmark.ts`
+- `src/clis/twitter/block.ts`
+- `src/clis/twitter/unblock.ts`
+- `src/clis/twitter/hide-reply.ts`
+- `src/clis/twitter/notifications.ts`
+- `src/clis/twitter/profile.ts`
+- `src/clis/twitter/thread.ts`
+- `src/clis/twitter/timeline.ts`
+- `src/clis/twitter/delete.ts`
+- `src/clis/twitter/reply-dm.ts`
+- `src/clis/medium/utils.ts`
+- `src/clis/substack/utils.ts`
+- `src/clis/bloomberg/news.ts`
+- `src/clis/sinablog/utils.ts`
+
+## Delivery Order
+
+1. Layer 1 (`waitForCapture`) — correctness fix, highest ROI
+2. Layer 3 (backoff) — 3-line change, zero risk
+3. Layer 2 (`wait({ selector })`) — largest adapter surface, can be done per-site
+
+## Testing
+
+- Unit tests: `waitForCaptureJs`, `waitForSelectorJs` exported and tested in `dom-helpers.test.ts` (if exists) or new test file
+- Adapter tests: existing tests must continue to pass (mock `page.wait` / `page.waitForCapture`)
+- Run: `npx vitest run --project unit --project adapter`

package/extension/dist/background.js

@@ -232,7 +232,7 @@ async function getAutomationWindow(workspace) {
     width: 1280,
     height: 900,
     type: "normal",
-    state: "minimized"
+    state: "normal"
   });
   const session = {
     windowId: win.id,

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "OpenCLI",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Browser automation bridge for the OpenCLI CLI tool. Executes commands in isolated Chrome windows via a local daemon.",
   "permissions": [
     "debugger",

package/extension/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "opencli-extension",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "opencli-extension",
-      "version": "1.5.2",
+      "version": "1.5.3",
       "devDependencies": {
         "@types/chrome": "^0.0.287",
         "typescript": "^5.7.0",

package/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencli-extension",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "private": true,
   "type": "module",
   "scripts": {

package/extension/src/background.ts

@@ -152,7 +152,7 @@ async function getAutomationWindow(workspace: string): Promise<number> {
     width: 1280,
     height: 900,
     type: 'normal',
-    state: 'minimized',
+    state: 'normal',
   });
   const session: AutomationSession = {
     windowId: win.id!,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "publishConfig": {
     "access": "public"
   },
@@ -58,6 +58,7 @@
     "commander": "^14.0.3",
     "js-yaml": "^4.1.0",
     "turndown": "^7.2.2",
+    "undici": "^7.24.6",
     "ws": "^8.18.0"
   },
   "devDependencies": {

package/src/browser/cdp.ts

@@ -25,6 +25,8 @@ import {
   autoScrollJs,
   networkRequestsJs,
   waitForDomStableJs,
+  waitForCaptureJs,
+  waitForSelectorJs,
 } from './dom-helpers.js';
 import { isRecord, saveBase64ToFile } from '../utils.js';
 
@@ -247,6 +249,15 @@ class CDPPage implements IPage {
 
   async wait(options: number | WaitOptions): Promise<void> {
     if (typeof options === 'number') {
+      if (options >= 1) {
+        try {
+          const maxMs = options * 1000;
+          await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+          return;
+        } catch {
+          // Fallback: fixed sleep
+        }
+      }
       await new Promise((resolve) => setTimeout(resolve, options * 1000));
       return;
     }
@@ -255,6 +266,11 @@ class CDPPage implements IPage {
       await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
       return;
     }
+    if (options.selector) {
+      const timeout = (options.timeout ?? 10) * 1000;
+      await this.evaluate(waitForSelectorJs(options.selector, timeout));
+      return;
+    }
     if (options.text) {
       const timeout = (options.timeout ?? 30) * 1000;
       await this.evaluate(waitForTextJs(options.text, timeout));
@@ -326,6 +342,11 @@ class CDPPage implements IPage {
     const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
     return Array.isArray(result) ? result : [];
   }
+
+  async waitForCapture(timeout: number = 10): Promise<void> {
+    const maxMs = timeout * 1000;
+    await this.evaluate(waitForCaptureJs(maxMs));
+  }
 }
 
 function isCookie(value: unknown): value is BrowserCookie {

package/src/browser/daemon-client.ts

@@ -6,6 +6,7 @@
 
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import type { BrowserSessionInfo } from '../types.js';
+import { sleep } from '../utils.js';
 
 const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
@@ -114,7 +115,7 @@ export async function sendCommand(
           || errMsg.includes('no longer exists');
         if (isTransient && attempt < maxRetries) {
           // Longer delay for extension recovery (service worker restart)
-          await new Promise(r => setTimeout(r, 1500));
+          await sleep(1500);
           continue;
         }
         throw new Error(result.error ?? 'Daemon command failed');
@@ -125,7 +126,7 @@ export async function sendCommand(
       const isRetryable = err instanceof TypeError  // fetch network error
         || (err instanceof Error && err.name === 'AbortError');
       if (isRetryable && attempt < maxRetries) {
-        await new Promise(r => setTimeout(r, 500));
+        await sleep(500);
         continue;
       }
       throw err;

package/src/browser/dom-helpers.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { waitForCaptureJs, waitForSelectorJs } from './dom-helpers.js';
+
+describe('waitForCaptureJs', () => {
+  it('returns a non-empty string', () => {
+    const code = waitForCaptureJs(1000);
+    expect(typeof code).toBe('string');
+    expect(code.length).toBeGreaterThan(0);
+    expect(code).toContain('__opencli_xhr');
+    expect(code).toContain('resolve');
+    expect(code).toContain('reject');
+  });
+
+  it('resolves "captured" when __opencli_xhr is populated before deadline', async () => {
+    const g = globalThis as any;
+    g.__opencli_xhr = [];
+    g.window = g; // stub window for Node eval
+    const code = waitForCaptureJs(1000);
+    const promise = eval(code) as Promise<string>;
+    g.__opencli_xhr.push({ data: 'test' });
+    await expect(promise).resolves.toBe('captured');
+    delete g.__opencli_xhr;
+    delete g.window;
+  });
+
+  it('rejects when __opencli_xhr stays empty past deadline', async () => {
+    const g = globalThis as any;
+    g.__opencli_xhr = [];
+    g.window = g;
+    const code = waitForCaptureJs(50); // 50ms timeout
+    const promise = eval(code) as Promise<string>;
+    await expect(promise).rejects.toThrow('No network capture within 0.05s');
+    delete g.__opencli_xhr;
+    delete g.window;
+  });
+
+  it('resolves immediately when __opencli_xhr already has data', async () => {
+    const g = globalThis as any;
+    g.__opencli_xhr = [{ data: 'already here' }];
+    g.window = g;
+    const code = waitForCaptureJs(1000);
+    await expect(eval(code) as Promise<string>).resolves.toBe('captured');
+    delete g.__opencli_xhr;
+    delete g.window;
+  });
+});
+
+describe('waitForSelectorJs', () => {
+  it('returns a non-empty string', () => {
+    const code = waitForSelectorJs('#app', 1000);
+    expect(typeof code).toBe('string');
+    expect(code).toContain('#app');
+    expect(code).toContain('querySelector');
+    expect(code).toContain('MutationObserver');
+  });
+
+  it('resolves "found" immediately when selector already present', async () => {
+    const g = globalThis as any;
+    const fakeEl = { tagName: 'DIV' };
+    g.document = { querySelector: (_: string) => fakeEl };
+    const code = waitForSelectorJs('[data-testid="primaryColumn"]', 1000);
+    await expect(eval(code) as Promise<string>).resolves.toBe('found');
+    delete g.document;
+  });
+
+  it('resolves "found" when selector appears after DOM mutation', async () => {
+    const g = globalThis as any;
+    let mutationCallback!: () => void;
+    g.MutationObserver = class {
+      constructor(cb: () => void) { mutationCallback = cb; }
+      observe() {}
+      disconnect() {}
+    };
+    let calls = 0;
+    g.document = {
+      querySelector: (_: string) => (calls++ > 0 ? { tagName: 'DIV' } : null),
+      body: {},
+    };
+    const code = waitForSelectorJs('#app', 1000);
+    const promise = eval(code) as Promise<string>;
+    mutationCallback(); // simulate DOM mutation
+    await expect(promise).resolves.toBe('found');
+    delete g.document;
+    delete g.MutationObserver;
+  });
+
+  it('rejects when selector never appears within timeout', async () => {
+    const g = globalThis as any;
+    g.MutationObserver = class {
+      constructor(_cb: () => void) {}
+      observe() {}
+      disconnect() {}
+    };
+    g.document = { querySelector: (_: string) => null, body: {} };
+    const code = waitForSelectorJs('#missing', 50);
+    await expect(eval(code) as Promise<string>).rejects.toThrow('Selector not found: #missing');
+    delete g.document;
+    delete g.MutationObserver;
+  });
+});

package/src/browser/dom-helpers.ts

@@ -179,3 +179,47 @@ export function waitForDomStableJs(maxMs: number, quietMs: number): string {
     })
   `;
 }
+
+/**
+ * Generate JS to wait until window.__opencli_xhr has ≥1 captured response.
+ * Polls every 100ms. Resolves 'captured' on success; rejects after maxMs.
+ * Used after installInterceptor() + goto() instead of a fixed sleep.
+ */
+export function waitForCaptureJs(maxMs: number): string {
+  return `
+    new Promise((resolve, reject) => {
+      const deadline = Date.now() + ${maxMs};
+      const check = () => {
+        if ((window.__opencli_xhr || []).length > 0) return resolve('captured');
+        if (Date.now() > deadline) return reject(new Error('No network capture within ${maxMs / 1000}s'));
+        setTimeout(check, 100);
+      };
+      check();
+    })
+  `;
+}
+
+/**
+ * Generate JS to wait until document.querySelector(selector) returns a match.
+ * Uses MutationObserver for near-instant resolution; falls back to reject after timeoutMs.
+ */
+export function waitForSelectorJs(selector: string, timeoutMs: number): string {
+  return `
+    new Promise((resolve, reject) => {
+      const sel = ${JSON.stringify(selector)};
+      if (document.querySelector(sel)) return resolve('found');
+      const cap = setTimeout(() => {
+        obs.disconnect();
+        reject(new Error('Selector not found: ' + sel));
+      }, ${timeoutMs});
+      const obs = new MutationObserver(() => {
+        if (document.querySelector(sel)) {
+          clearTimeout(cap);
+          obs.disconnect();
+          resolve('found');
+        }
+      });
+      obs.observe(document.body || document.documentElement, { childList: true, subtree: true });
+    })
+  `;
+}

package/src/browser/index.ts

@@ -12,18 +12,3 @@ export { isDaemonRunning } from './daemon-client.js';
 export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 export { generateStealthJs } from './stealth.js';
 export type { DomSnapshotOptions } from './dom-snapshot.js';
-
-import { extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
-import { __test__ as cdpTest } from './cdp.js';
-import { isRetryableSettleError } from './page.js';
-import { withTimeoutMs } from '../runtime.js';
-
-export const __test__ = {
-  extractTabEntries,
-  diffTabIndexes,
-  appendLimited,
-  withTimeoutMs,
-  selectCDPTarget: cdpTest.selectCDPTarget,
-  scoreCDPTarget: cdpTest.scoreCDPTarget,
-  isRetryableSettleError,
-};

package/src/browser/mcp.ts

@@ -96,10 +96,11 @@ export class BrowserBridge implements IBrowserFactory {
     });
     this._daemonProc.unref();
 
-    // Wait for daemon to be ready AND extension to connect
+    // Wait for daemon to be ready AND extension to connect (exponential backoff)
+    const backoffs = [50, 100, 200, 400, 800, 1500, 3000];
     const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      await new Promise(resolve => setTimeout(resolve, 300));
+    for (let i = 0; Date.now() < deadline; i++) {
+      await new Promise(resolve => setTimeout(resolve, backoffs[Math.min(i, backoffs.length - 1)]));
       if (await isExtensionConnected()) return;
     }
 

package/src/browser/page.ts

@@ -22,6 +22,8 @@ import {
   typeTextJs,
   pressKeyJs,
   waitForTextJs,
+  waitForCaptureJs,
+  waitForSelectorJs,
   scrollJs,
   autoScrollJs,
   networkRequestsJs,
@@ -236,6 +238,12 @@ export class Page implements IPage {
       await new Promise(resolve => setTimeout(resolve, options.time! * 1000));
       return;
     }
+    if (options.selector) {
+      const timeout = (options.timeout ?? 10) * 1000;
+      const code = waitForSelectorJs(options.selector, timeout);
+      await sendCommand('exec', { code, ...this._cmdOpts() });
+      return;
+    }
     if (options.text) {
       const timeout = (options.timeout ?? 30) * 1000;
       const code = waitForTextJs(options.text, timeout);
@@ -330,6 +338,14 @@ export class Page implements IPage {
     const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
     return Array.isArray(result) ? result : [];
   }
+
+  async waitForCapture(timeout: number = 10): Promise<void> {
+    const maxMs = timeout * 1000;
+    await sendCommand('exec', {
+      code: waitForCaptureJs(maxMs),
+      ...this._cmdOpts(),
+    });
+  }
 }
 
 // (End of file)

package/src/browser.test.ts

@@ -1,10 +1,14 @@
-import { afterEach, describe, it, expect, vi } from 'vitest';
-import { BrowserBridge, __test__, generateStealthJs } from './browser/index.js';
+import { describe, it, expect, vi } from 'vitest';
+import { BrowserBridge, generateStealthJs } from './browser/index.js';
+import { extractTabEntries, diffTabIndexes, appendLimited } from './browser/tabs.js';
+import { withTimeoutMs } from './runtime.js';
+import { __test__ as cdpTest } from './browser/cdp.js';
+import { isRetryableSettleError } from './browser/page.js';
 import * as daemonClient from './browser/daemon-client.js';
 
 describe('browser helpers', () => {
   it('extracts tab entries from string snapshots', () => {
-    const entries = __test__.extractTabEntries('Tab 0 https://example.com\nTab 1 Chrome Extension');
+    const entries = extractTabEntries('Tab 0 https://example.com\nTab 1 Chrome Extension');
 
     expect(entries).toEqual([
       { index: 0, identity: 'https://example.com' },
@@ -13,7 +17,7 @@ describe('browser helpers', () => {
   });
 
   it('extracts tab entries from MCP markdown format', () => {
-    const entries = __test__.extractTabEntries(
+    const entries = extractTabEntries(
       '- 0: (current) [Playwright MCP extension](chrome-extension://abc/connect.html)\n- 1: [知乎 - 首页](https://www.zhihu.com/)'
     );
 
@@ -24,7 +28,7 @@ describe('browser helpers', () => {
   });
 
   it('closes only tabs that were opened during the session', () => {
-    const tabsToClose = __test__.diffTabIndexes(
+    const tabsToClose = diffTabIndexes(
       ['https://example.com', 'Chrome Extension'],
       [
         { index: 0, identity: 'https://example.com' },
@@ -38,21 +42,21 @@ describe('browser helpers', () => {
   });
 
   it('keeps only the tail of stderr buffers', () => {
-    expect(__test__.appendLimited('12345', '67890', 8)).toBe('34567890');
+    expect(appendLimited('12345', '67890', 8)).toBe('34567890');
   });
 
   it('times out slow promises', async () => {
-    await expect(__test__.withTimeoutMs(new Promise(() => {}), 10, 'timeout')).rejects.toThrow('timeout');
+    await expect(withTimeoutMs(new Promise(() => {}), 10, 'timeout')).rejects.toThrow('timeout');
   });
 
   it('retries settle only for target-invalidated errors', () => {
-    expect(__test__.isRetryableSettleError(new Error('{"code":-32000,"message":"Inspected target navigated or closed"}'))).toBe(true);
-    expect(__test__.isRetryableSettleError(new Error('attach failed: target no longer exists'))).toBe(false);
-    expect(__test__.isRetryableSettleError(new Error('malformed exec payload'))).toBe(false);
+    expect(isRetryableSettleError(new Error('{"code":-32000,"message":"Inspected target navigated or closed"}'))).toBe(true);
+    expect(isRetryableSettleError(new Error('attach failed: target no longer exists'))).toBe(false);
+    expect(isRetryableSettleError(new Error('malformed exec payload'))).toBe(false);
   });
 
   it('prefers the real Electron app target over DevTools and blank pages', () => {
-    const target = __test__.selectCDPTarget([
+    const target = cdpTest.selectCDPTarget([
       {
         type: 'page',
         title: 'DevTools - localhost:9224',
@@ -79,7 +83,7 @@ describe('browser helpers', () => {
   it('honors OPENCLI_CDP_TARGET when multiple inspectable targets exist', () => {
     vi.stubEnv('OPENCLI_CDP_TARGET', 'codex');
 
-    const target = __test__.selectCDPTarget([
+    const target = cdpTest.selectCDPTarget([
       {
         type: 'app',
         title: 'Cursor',

package/src/clis/36kr/hot.ts

@@ -60,7 +60,7 @@ cli({
 
     await page.installInterceptor('36kr.com/api');
     await page.goto(url);
-    await page.wait(6);
+    await page.waitForCapture(6);
 
     // Scrape rendered article links from DOM (deduplicated)
     const domItems: any = await page.evaluate(`

package/src/clis/36kr/search.ts

@@ -24,7 +24,7 @@ cli({
 
     await page.installInterceptor('36kr.com/api');
     await page.goto(`https://www.36kr.com/search/articles/${query}`);
-    await page.wait(6);
+    await page.waitForCapture(6);
 
     const domItems: any = await page.evaluate(`
       (() => {

package/src/clis/_shared/common.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared utilities for CLI adapters.
+ */
+
+/**
+ * Clamp a numeric value to [min, max].
+ * Matches the signature of lodash.clamp and Rust's clamp.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}

package/src/clis/bloomberg/news.ts

@@ -23,7 +23,7 @@ cli({
 
     // Navigate and wait for the page to hydrate before extracting story data.
     await page.goto(url);
-    await page.wait(5);
+    await page.wait({ selector: 'article', timeout: 5 });
 
     const loadStory = async () => page.evaluate(`(() => {
       const isRobot = /Are you a robot/i.test(document.title)