@jackwener/opencli 1.5.1 → 1.5.3

package/dist/browser/dom-helpers.test.js

@@ -0,0 +1,92 @@
+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;
+        g.__opencli_xhr = [];
+        g.window = g; // stub window for Node eval
+        const code = waitForCaptureJs(1000);
+        const promise = eval(code);
+        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;
+        g.__opencli_xhr = [];
+        g.window = g;
+        const code = waitForCaptureJs(50); // 50ms timeout
+        const promise = eval(code);
+        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;
+        g.__opencli_xhr = [{ data: 'already here' }];
+        g.window = g;
+        const code = waitForCaptureJs(1000);
+        await expect(eval(code)).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;
+        const fakeEl = { tagName: 'DIV' };
+        g.document = { querySelector: (_) => fakeEl };
+        const code = waitForSelectorJs('[data-testid="primaryColumn"]', 1000);
+        await expect(eval(code)).resolves.toBe('found');
+        delete g.document;
+    });
+    it('resolves "found" when selector appears after DOM mutation', async () => {
+        const g = globalThis;
+        let mutationCallback;
+        g.MutationObserver = class {
+            constructor(cb) { mutationCallback = cb; }
+            observe() { }
+            disconnect() { }
+        };
+        let calls = 0;
+        g.document = {
+            querySelector: (_) => (calls++ > 0 ? { tagName: 'DIV' } : null),
+            body: {},
+        };
+        const code = waitForSelectorJs('#app', 1000);
+        const promise = eval(code);
+        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;
+        g.MutationObserver = class {
+            constructor(_cb) { }
+            observe() { }
+            disconnect() { }
+        };
+        g.document = { querySelector: (_) => null, body: {} };
+        const code = waitForSelectorJs('#missing', 50);
+        await expect(eval(code)).rejects.toThrow('Selector not found: #missing');
+        delete g.document;
+        delete g.MutationObserver;
+    });
+});

package/dist/browser/index.d.ts

@@ -11,13 +11,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 { withTimeoutMs } from '../runtime.js';
-export declare const __test__: {
-    extractTabEntries: typeof extractTabEntries;
-    diffTabIndexes: typeof diffTabIndexes;
-    appendLimited: typeof appendLimited;
-    withTimeoutMs: typeof withTimeoutMs;
-    selectCDPTarget: (targets: import("./cdp.js").CDPTarget[]) => import("./cdp.js").CDPTarget | undefined;
-    scoreCDPTarget: (target: import("./cdp.js").CDPTarget, preferredPattern?: RegExp) => number;
-};

package/dist/browser/index.js

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

package/dist/browser/mcp.js

@@ -82,10 +82,11 @@ export class BrowserBridge {
             env: { ...process.env },
         });
         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/dist/browser/page.d.ts

@@ -10,6 +10,7 @@
  * chrome-extension:// tab that can't be debugged.
  */
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+export declare function isRetryableSettleError(err: unknown): boolean;
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
  */
@@ -71,4 +72,5 @@ export declare class Page implements IPage {
     }): Promise<void>;
     installInterceptor(pattern: string): Promise<void>;
     getInterceptedRequests(): Promise<unknown[]>;
+    waitForCapture(timeout?: number): Promise<void>;
 }

package/dist/browser/page.js

@@ -15,7 +15,12 @@ import { wrapForEval } from './utils.js';
 import { saveBase64ToFile } from '../utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { generateStealthJs } from './stealth.js';
-import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+export function isRetryableSettleError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes('Inspected target navigated or closed')
+        || (message.includes('-32000') && message.toLowerCase().includes('target'));
+}
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
  */
@@ -63,10 +68,31 @@ export class Page {
         // settleMs is now a timeout cap (default 1000ms), not a fixed wait.
         if (options?.waitUntil !== 'none') {
             const maxMs = options?.settleMs ?? 1000;
-            await sendCommand('exec', {
+            const settleOpts = {
                 code: waitForDomStableJs(maxMs, Math.min(500, maxMs)),
                 ...this._cmdOpts(),
-            });
+            };
+            try {
+                await sendCommand('exec', settleOpts);
+            }
+            catch (err) {
+                if (!isRetryableSettleError(err))
+                    throw err;
+                // SPA client-side redirects can invalidate the CDP target after
+                // chrome.tabs reports 'complete'. Wait briefly for the new document
+                // to load, then retry the settle probe once.
+                try {
+                    await new Promise((r) => setTimeout(r, 200));
+                    await sendCommand('exec', settleOpts);
+                }
+                catch (retryErr) {
+                    if (!isRetryableSettleError(retryErr))
+                        throw retryErr;
+                    // Retry also failed — give up silently. Settle is best-effort
+                    // after successful navigation; the next real command will surface
+                    // any persistent target error immediately.
+                }
+            }
         }
     }
     async getCurrentUrl() {
@@ -193,6 +219,12 @@ export class Page {
             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);
@@ -276,5 +308,12 @@ export class Page {
         const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
         return Array.isArray(result) ? result : [];
     }
+    async waitForCapture(timeout = 10) {
+        const maxMs = timeout * 1000;
+        await sendCommand('exec', {
+            code: waitForCaptureJs(maxMs),
+            ...this._cmdOpts(),
+        });
+    }
 }
 // (End of file)

package/dist/browser.test.js

@@ -1,23 +1,27 @@
 import { describe, it, expect, vi } from 'vitest';
-import { BrowserBridge, __test__, generateStealthJs } from './browser/index.js';
+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' },
             { index: 1, identity: 'Chrome Extension' },
         ]);
     });
     it('extracts tab entries from MCP markdown format', () => {
-        const entries = __test__.extractTabEntries('- 0: (current) [Playwright MCP extension](chrome-extension://abc/connect.html)\n- 1: [知乎 - 首页](https://www.zhihu.com/)');
+        const entries = extractTabEntries('- 0: (current) [Playwright MCP extension](chrome-extension://abc/connect.html)\n- 1: [知乎 - 首页](https://www.zhihu.com/)');
         expect(entries).toEqual([
             { index: 0, identity: '(current) [Playwright MCP extension](chrome-extension://abc/connect.html)' },
             { index: 1, identity: '[知乎 - 首页](https://www.zhihu.com/)' },
         ]);
     });
     it('closes only tabs that were opened during the session', () => {
-        const tabsToClose = __test__.diffTabIndexes(['https://example.com', 'Chrome Extension'], [
+        const tabsToClose = diffTabIndexes(['https://example.com', 'Chrome Extension'], [
             { index: 0, identity: 'https://example.com' },
             { index: 1, identity: 'Chrome Extension' },
             { index: 2, identity: 'https://target.example/page' },
@@ -26,13 +30,18 @@ describe('browser helpers', () => {
         expect(tabsToClose).toEqual([3, 2]);
     });
     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(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',
@@ -56,7 +65,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/dist/cli-manifest.json

@@ -10900,7 +10900,7 @@
     "description": "V2EX 热门话题",
     "domain": "www.v2ex.com",
     "strategy": "public",
-    "browser": true,
+    "browser": false,
     "args": [
       {
         "name": "limit",
@@ -10918,10 +10918,9 @@
     ],
     "pipeline": [
       {
-        "navigate": "https://www.v2ex.com/"
-      },
-      {
-        "evaluate": "(async () => {\n  const response = await fetch('/api/topics/hot.json', {\n    credentials: 'include',\n    headers: {\n      accept: 'application/json, text/plain, */*',\n      'x-requested-with': 'XMLHttpRequest',\n    },\n  });\n  if (!response.ok) {\n    throw new Error(`V2EX hot API request failed: ${response.status}`);\n  }\n  return await response.json();\n})()\n"
+        "fetch": {
+          "url": "https://www.v2ex.com/api/topics/hot.json"
+        }
       },
       {
         "map": {

package/dist/clis/36kr/hot.js

@@ -48,7 +48,7 @@ cli({
         const url = buildHotListUrl(listType);
         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 = await page.evaluate(`
       (() => {

package/dist/clis/36kr/search.js

@@ -21,7 +21,7 @@ cli({
         const query = encodeURIComponent(String(args.query ?? ''));
         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 = await page.evaluate(`
       (() => {
         const seen = new Set();

package/dist/clis/_shared/common.d.ts

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

package/dist/clis/_shared/common.js

@@ -0,0 +1,10 @@
+/**
+ * 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, min, max) {
+    return Math.max(min, Math.min(value, max));
+}

package/dist/clis/apple-podcasts/commands.test.js

@@ -31,13 +31,14 @@ describe('apple-podcasts search command', () => {
         });
         expect(fetchMock).toHaveBeenCalledWith('https://itunes.apple.com/search?term=machine%20learning&media=podcast&limit=5');
         expect(result).toEqual([
-            {
+            expect.objectContaining({
                 id: 42,
                 title: 'Machine Learning Guide',
                 author: 'OpenCLI',
                 episodes: 12,
                 genre: 'Technology',
-            },
+                url: '',
+            }),
         ]);
     });
 });
@@ -45,6 +46,26 @@ describe('apple-podcasts top command', () => {
     beforeEach(() => {
         vi.restoreAllMocks();
     });
+    it('adds a timeout signal to chart fetches', async () => {
+        const cmd = getRegistry().get('apple-podcasts/top');
+        expect(cmd?.func).toBeTypeOf('function');
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({
+                feed: {
+                    results: [
+                        { id: '100', name: 'Top Show', artistName: 'Host A' },
+                    ],
+                },
+            }),
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        await cmd.func(null, { country: 'US', limit: 1 });
+        const [, options] = fetchMock.mock.calls[0] ?? [];
+        expect(options).toBeDefined();
+        expect(options.signal).toBeDefined();
+        expect(options.signal).toHaveProperty('aborted', false);
+    });
     it('uses the canonical Apple charts host and maps ranked results', async () => {
         const cmd = getRegistry().get('apple-podcasts/top');
         expect(cmd?.func).toBeTypeOf('function');
@@ -61,7 +82,9 @@ describe('apple-podcasts top command', () => {
         });
         vi.stubGlobal('fetch', fetchMock);
         const result = await cmd.func(null, { country: 'US', limit: 2 });
-        expect(fetchMock).toHaveBeenCalledWith('https://rss.marketingtools.apple.com/api/v2/us/podcasts/top/2/podcasts.json');
+        expect(fetchMock).toHaveBeenCalledWith('https://rss.marketingtools.apple.com/api/v2/us/podcasts/top/2/podcasts.json', expect.objectContaining({
+            signal: expect.any(Object),
+        }));
         expect(result).toEqual([
             { rank: 1, title: 'Top Show', author: 'Host A', id: '100' },
             { rank: 2, title: 'Second Show', author: 'Host B', id: '101' },

package/dist/clis/apple-podcasts/top.js

@@ -2,6 +2,7 @@ import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
 // Apple Marketing Tools RSS API — public, no key required
 const CHARTS_URL = 'https://rss.marketingtools.apple.com/api/v2';
+const CHARTS_TIMEOUT_MS = 15_000;
 cli({
     site: 'apple-podcasts',
     name: 'top',
@@ -19,7 +20,9 @@ cli({
         const url = `${CHARTS_URL}/${country}/podcasts/top/${limit}/podcasts.json`;
         let resp;
         try {
-            resp = await fetch(url);
+            resp = await fetch(url, {
+                signal: AbortSignal.timeout(CHARTS_TIMEOUT_MS),
+            });
         }
         catch (error) {
             const reason = error?.cause?.code ?? error?.message ?? 'unknown network error';

package/dist/clis/bloomberg/news.js

@@ -16,7 +16,7 @@ cli({
         const url = validateBloombergLink(kwargs.link);
         // 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)
         || /unusual activity/i.test(document.body.innerText)

package/dist/clis/douban/utils.js

@@ -2,14 +2,11 @@
  * Douban adapter utilities.
  */
 import { ArgumentError, CliError, EmptyResultError } from '../../errors.js';
+import { clamp } from '../_shared/common.js';
 const DOUBAN_PHOTO_PAGE_SIZE = 30;
 const MAX_DOUBAN_PHOTOS = 500;
-function clampLimit(limit) {
-    return Math.max(1, Math.min(limit || 20, 50));
-}
-function clampPhotoLimit(limit) {
-    return Math.max(1, Math.min(limit || 120, MAX_DOUBAN_PHOTOS));
-}
+const clampLimit = (limit) => clamp(limit || 20, 1, 50);
+const clampPhotoLimit = (limit) => clamp(limit || 120, 1, MAX_DOUBAN_PHOTOS);
 async function ensureDoubanReady(page) {
     const state = await page.evaluate(`
     (() => {

package/dist/clis/medium/utils.js

@@ -12,7 +12,7 @@ export async function loadMediumPosts(page, url, limit) {
     if (!page)
         throw new CommandExecutionError('Browser session required for medium posts');
     await page.goto(url);
-    await page.wait(5);
+    await page.wait({ selector: 'article', timeout: 5 });
     const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 3000));

package/dist/clis/producthunt/browse.js

@@ -29,7 +29,7 @@ cli({
         const slug = String(args.category || '').trim().toLowerCase();
         await page.installInterceptor('producthunt.com');
         await page.goto(`https://www.producthunt.com/categories/${slug}`);
-        await page.wait(5);
+        await page.waitForCapture(5);
         const domItems = await page.evaluate(`
       (() => {
         const seen = new Set();

package/dist/clis/producthunt/hot.js

@@ -20,7 +20,7 @@ cli({
         const count = Math.min(Number(args.limit) || 20, 50);
         await page.installInterceptor('producthunt.com');
         await page.goto('https://www.producthunt.com');
-        await page.wait(5);
+        await page.waitForCapture(5);
         const domItems = await page.evaluate(`
       (() => {
         const seen = new Set();

package/dist/clis/sinablog/utils.js

@@ -1,6 +1,5 @@
-function clampLimit(limit) {
-    return Math.max(1, Math.min(limit || 20, 50));
-}
+import { clamp } from '../_shared/common.js';
+const clampLimit = (limit) => clamp(limit || 20, 1, 50);
 export function buildSinaBlogSearchUrl(keyword) {
     return `https://search.sina.com.cn/search?q=${encodeURIComponent(keyword)}&tp=mix`;
 }
@@ -9,7 +8,7 @@ export function buildSinaBlogUserUrl(uid) {
 }
 export async function loadSinaBlogArticle(page, url) {
     await page.goto(url);
-    await page.wait(3);
+    await page.wait({ selector: 'h1', timeout: 3 });
     return page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 1500));
@@ -46,7 +45,7 @@ export async function loadSinaBlogArticle(page, url) {
 export async function loadSinaBlogHot(page, limit) {
     const safeLimit = clampLimit(limit);
     await page.goto('https://blog.sina.com.cn/');
-    await page.wait(3);
+    await page.wait({ selector: 'h1', timeout: 3 });
     const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 1500));
@@ -114,7 +113,7 @@ export async function loadSinaBlogHot(page, limit) {
 export async function loadSinaBlogSearch(page, keyword, limit) {
     const safeLimit = clampLimit(limit);
     await page.goto(buildSinaBlogSearchUrl(keyword));
-    await page.wait(5);
+    await page.wait({ selector: '.result-item', timeout: 5 });
     const data = await page.evaluate(`
     (async () => {
       const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -149,7 +148,7 @@ export async function loadSinaBlogSearch(page, keyword, limit) {
 export async function loadSinaBlogUser(page, uid, limit) {
     const safeLimit = clampLimit(limit);
     await page.goto(buildSinaBlogUserUrl(uid));
-    await page.wait(3);
+    await page.wait({ selector: 'h1', timeout: 3 });
     const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 1000));

package/dist/clis/substack/utils.js

@@ -9,7 +9,7 @@ export async function loadSubstackFeed(page, url, limit) {
     if (!page)
         throw new CommandExecutionError('Browser session required for substack feed');
     await page.goto(url);
-    await page.wait(5);
+    await page.wait({ selector: 'article', timeout: 5 });
     const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 3000));
@@ -77,7 +77,7 @@ export async function loadSubstackArchive(page, baseUrl, limit) {
     if (!page)
         throw new CommandExecutionError('Browser session required for substack archive');
     await page.goto(`${baseUrl}/archive`);
-    await page.wait(5);
+    await page.wait({ selector: 'article', timeout: 5 });
     const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 3000));

package/dist/clis/twitter/block.js

@@ -16,7 +16,7 @@ cli({
             throw new CommandExecutionError('Browser session required for twitter block');
         const username = kwargs.username.replace(/^@/, '');
         await page.goto(`https://x.com/${username}`);
-        await page.wait(5);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
         const result = await page.evaluate(`(async () => {
         try {
             let attempts = 0;

package/dist/clis/twitter/bookmark.js

@@ -15,7 +15,7 @@ cli({
         if (!page)
             throw new CommandExecutionError('Browser session required for twitter bookmark');
         await page.goto(kwargs.url);
-        await page.wait(5);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
         const result = await page.evaluate(`(async () => {
         try {
             let attempts = 0;

package/dist/clis/twitter/delete.js

@@ -15,7 +15,7 @@ cli({
         if (!page)
             throw new CommandExecutionError('Browser session required for twitter delete');
         await page.goto(kwargs.url);
-        await page.wait(5); // Wait for tweet to load completely
+        await page.wait({ selector: '[data-testid="primaryColumn"]' }); // Wait for tweet to load completely
         const result = await page.evaluate(`(async () => {
         try {
             // Wait for caret button (which has 'More' aria-label) within the main tweet body

package/dist/clis/twitter/follow.js

@@ -16,7 +16,7 @@ cli({
             throw new CommandExecutionError('Browser session required for twitter follow');
         const username = kwargs.username.replace(/^@/, '');
         await page.goto(`https://x.com/${username}`);
-        await page.wait(5);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
         const result = await page.evaluate(`(async () => {
         try {
             let attempts = 0;

package/dist/clis/twitter/followers.js

@@ -17,7 +17,7 @@ cli({
         // If no user is specified, figure out the logged-in user's handle
         if (!targetUser) {
             await page.goto('https://x.com/home');
-            await page.wait(5);
+            await page.wait({ selector: '[data-testid="primaryColumn"]' });
             const href = await page.evaluate(`() => {
             const link = document.querySelector('a[data-testid="AppTabBar_Profile_Link"]');
             return link ? link.getAttribute('href') : null;
@@ -51,7 +51,7 @@ cli({
         if (!clicked) {
             throw new SelectorError('Twitter followers link', 'Twitter may have changed the layout.');
         }
-        await page.wait(5);
+        await page.waitForCapture(5);
         // 4. Scroll to trigger pagination API calls
         await page.autoScroll({ times: Math.ceil(kwargs.limit / 20), delayMs: 2000 });
         // 5. Retrieve intercepted data

package/dist/clis/twitter/following.js

@@ -17,7 +17,7 @@ cli({
         // If no user is specified, figure out the logged-in user's handle
         if (!targetUser) {
             await page.goto('https://x.com/home');
-            await page.wait(5);
+            await page.wait({ selector: '[data-testid="primaryColumn"]' });
             const href = await page.evaluate(`() => {
             const link = document.querySelector('a[data-testid="AppTabBar_Profile_Link"]');
             return link ? link.getAttribute('href') : null;
@@ -44,7 +44,7 @@ cli({
         if (!clicked) {
             throw new SelectorError('Twitter following link', 'Twitter may have changed the layout.');
         }
-        await page.wait(5);
+        await page.waitForCapture(5);
         // 4. Scroll to trigger pagination API calls
         await page.autoScroll({ times: Math.ceil(kwargs.limit / 20), delayMs: 2000 });
         // 5. Retrieve intercepted data

package/dist/clis/twitter/hide-reply.js

@@ -15,7 +15,7 @@ cli({
         if (!page)
             throw new CommandExecutionError('Browser session required for twitter hide-reply');
         await page.goto(kwargs.url);
-        await page.wait(5);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
         const result = await page.evaluate(`(async () => {
         try {
             let attempts = 0;