@jackwener/opencli 1.7.4 → 1.7.5

package/clis/xiaoyuzhou/download.test.js

@@ -2,17 +2,19 @@ import path from 'node:path';
 import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 
-const { mockFetchPageProps, mockHttpDownload, mockMkdirSync } = vi.hoisted(() => ({
-    mockFetchPageProps: vi.fn(),
+const { mockRequestJson, mockLoadCredentials, mockHttpDownload, mockMkdirSync } = vi.hoisted(() => ({
+    mockRequestJson: vi.fn(),
+    mockLoadCredentials: vi.fn(),
     mockHttpDownload: vi.fn(),
     mockMkdirSync: vi.fn(),
 }));
 
-vi.mock('./utils.js', async () => {
-    const actual = await vi.importActual('./utils.js');
+vi.mock('./auth.js', async () => {
+    const actual = await vi.importActual('./auth.js');
     return {
         ...actual,
-        fetchPageProps: mockFetchPageProps,
+        requestXiaoyuzhouJson: mockRequestJson,
+        loadXiaoyuzhouCredentials: mockLoadCredentials,
     };
 });
 
@@ -44,14 +46,17 @@ beforeAll(() => {
 
 describe('xiaoyuzhou download', () => {
     beforeEach(() => {
-        mockFetchPageProps.mockReset();
+        mockRequestJson.mockReset();
+        mockLoadCredentials.mockReset();
         mockHttpDownload.mockReset();
         mockMkdirSync.mockReset();
+        mockLoadCredentials.mockReturnValue({});
     });
 
     it('downloads audio from media.source.url into an episode subdirectory', async () => {
-        mockFetchPageProps.mockResolvedValue({
-            episode: {
+        mockRequestJson.mockResolvedValue({
+            credentials: {},
+            data: {
                 title: 'Hello World',
                 podcast: { title: 'OpenCLI FM' },
                 media: {
@@ -68,7 +73,10 @@ describe('xiaoyuzhou download', () => {
             output: '/tmp/xiaoyuzhou-test',
         });
 
-        expect(mockFetchPageProps).toHaveBeenCalledWith('/episode/ep123');
+        expect(mockRequestJson).toHaveBeenCalledWith('/v1/episode/get', {
+            query: { eid: 'ep123' },
+            credentials: {},
+        });
         expect(toPosixPath(mockMkdirSync.mock.calls[0][0])).toBe('/tmp/xiaoyuzhou-test/ep123');
         expect(mockMkdirSync.mock.calls[0][1]).toEqual({ recursive: true });
         expect(mockHttpDownload).toHaveBeenCalledWith('https://media.xyzcdn.net/audio/hello-world.mp3?sign=abc', expect.stringContaining('/tmp/xiaoyuzhou-test/ep123/ep123_Hello_World.mp3'), {
@@ -84,8 +92,9 @@ describe('xiaoyuzhou download', () => {
     });
 
     it('preserves non-mp3 extensions from media.source.url', async () => {
-        mockFetchPageProps.mockResolvedValue({
-            episode: {
+        mockRequestJson.mockResolvedValue({
+            credentials: {},
+            data: {
                 title: 'Lossless Episode',
                 podcast: { title: 'OpenCLI FM' },
                 media: {
@@ -107,8 +116,9 @@ describe('xiaoyuzhou download', () => {
     });
 
     it('throws when media.source.url is missing', async () => {
-        mockFetchPageProps.mockResolvedValue({
-            episode: {
+        mockRequestJson.mockResolvedValue({
+            credentials: {},
+            data: {
                 title: 'No Audio',
                 podcast: { title: 'OpenCLI FM' },
                 media: {},

package/clis/xiaoyuzhou/episode.js

@@ -1,18 +1,23 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
-import { fetchPageProps, formatDuration, formatDate } from './utils.js';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';
+import { formatDuration, formatDate } from './utils.js';
 cli({
     site: 'xiaoyuzhou',
     name: 'episode',
     description: 'View details of a Xiaoyuzhou podcast episode',
     domain: 'www.xiaoyuzhoufm.com',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'id', positional: true, required: true, help: 'Episode ID (eid from podcast-episodes output)' }],
     columns: ['title', 'podcast', 'duration', 'plays', 'comments', 'likes', 'date'],
     func: async (_page, args) => {
-        const pageProps = await fetchPageProps(`/episode/${args.id}`);
-        const ep = pageProps.episode;
+        const credentials = loadXiaoyuzhouCredentials();
+        const response = await requestXiaoyuzhouJson('/v1/episode/get', {
+            query: { eid: args.id },
+            credentials,
+        });
+        const ep = response.data;
         if (!ep)
             throw new CliError('NOT_FOUND', 'Episode not found', 'Please check the ID');
         return [{

package/clis/xiaoyuzhou/podcast-episodes.js

@@ -1,30 +1,34 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
-import { fetchPageProps, formatDuration, formatDate } from './utils.js';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';
+import { formatDuration, formatDate } from './utils.js';
 cli({
     site: 'xiaoyuzhou',
     name: 'podcast-episodes',
-    description: 'List recent episodes of a Xiaoyuzhou podcast (up to 15, SSR limit)',
+    description: 'List episodes of a Xiaoyuzhou podcast',
     domain: 'www.xiaoyuzhoufm.com',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [
         { name: 'id', positional: true, required: true, help: 'Podcast ID (from xiaoyuzhoufm.com URL)' },
-        { name: 'limit', type: 'int', default: 15, help: 'Max episodes to show (up to 15, SSR limit)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max episodes to show' },
     ],
     columns: ['eid', 'title', 'duration', 'plays', 'date'],
     func: async (_page, args) => {
-        const pageProps = await fetchPageProps(`/podcast/${args.id}`);
-        const podcast = pageProps.podcast;
-        if (!podcast)
-            throw new CliError('NOT_FOUND', 'Podcast not found', 'Please check the ID');
-        const allEpisodes = podcast.episodes ?? [];
         const requestedLimit = Number(args.limit);
         if (!Number.isInteger(requestedLimit) || requestedLimit < 1) {
             throw new CliError('INVALID_ARGUMENT', 'limit must be a positive integer', 'Example: --limit 5');
         }
-        const limit = Math.min(requestedLimit, allEpisodes.length);
-        const episodes = allEpisodes.slice(0, limit);
+        const credentials = loadXiaoyuzhouCredentials();
+        const response = await requestXiaoyuzhouJson('/v1/podcast/listEpisode', {
+            method: 'POST',
+            body: { pid: args.id, limit: requestedLimit },
+            credentials,
+        });
+        const episodes = response.data ?? [];
+        if (!Array.isArray(episodes)) {
+            throw new CliError('PARSE_ERROR', 'Unexpected API response format', 'Expected an array of episodes');
+        }
         return episodes.map((ep) => ({
             eid: ep.eid,
             title: ep.title,

package/clis/xiaoyuzhou/podcast.js

@@ -1,18 +1,23 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
-import { fetchPageProps, formatDate } from './utils.js';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson } from './auth.js';
+import { formatDate } from './utils.js';
 cli({
     site: 'xiaoyuzhou',
     name: 'podcast',
     description: 'View a Xiaoyuzhou podcast profile',
     domain: 'www.xiaoyuzhoufm.com',
-    strategy: Strategy.PUBLIC,
+    strategy: Strategy.LOCAL,
     browser: false,
     args: [{ name: 'id', positional: true, required: true, help: 'Podcast ID (from xiaoyuzhoufm.com URL)' }],
     columns: ['title', 'author', 'description', 'subscribers', 'episodes', 'updated'],
     func: async (_page, args) => {
-        const pageProps = await fetchPageProps(`/podcast/${args.id}`);
-        const p = pageProps.podcast;
+        const credentials = loadXiaoyuzhouCredentials();
+        const response = await requestXiaoyuzhouJson('/v1/podcast/get', {
+            query: { pid: args.id },
+            credentials,
+        });
+        const p = response.data;
         if (!p)
             throw new CliError('NOT_FOUND', 'Podcast not found', 'Please check the ID');
         return [{

package/clis/xiaoyuzhou/utils.js

@@ -1,43 +1,3 @@
-/**
- * Shared Xiaoyuzhou utilities — page data extraction and formatting.
- *
- * Xiaoyuzhou (小宇宙) is a Next.js app that embeds full page data in
- * <script id="__NEXT_DATA__">. We fetch the HTML and extract that JSON
- * instead of using their authenticated API.
- */
-import { CliError } from '@jackwener/opencli/errors';
-/**
- * Fetch a Xiaoyuzhou page and extract __NEXT_DATA__.props.pageProps.
- * @param path - URL path, e.g. '/podcast/xxx' or '/episode/xxx'
- */
-export async function fetchPageProps(path) {
-    const url = `https://www.xiaoyuzhoufm.com${path}`;
-    // Node.js fetch sends UA "node" which gets blocked; use a browser-like UA
-    const resp = await fetch(url, {
-        headers: { 'User-Agent': 'Mozilla/5.0 (compatible; opencli)' },
-    });
-    if (!resp.ok) {
-        throw new CliError('FETCH_ERROR', `HTTP ${resp.status} for ${path}`, 'Please check the ID — you can find it in xiaoyuzhoufm.com URLs');
-    }
-    const html = await resp.text();
-    // [\s\S]*? for multiline safety (JSON may span lines)
-    const match = html.match(/<script id="__NEXT_DATA__"[^>]*>([\s\S]*?)<\/script>/);
-    if (!match) {
-        throw new CliError('PARSE_ERROR', 'Failed to extract __NEXT_DATA__', 'Page structure may have changed');
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(match[1]);
-    }
-    catch {
-        throw new CliError('PARSE_ERROR', 'Malformed __NEXT_DATA__ JSON', 'Page structure may have changed');
-    }
-    const pageProps = parsed.props?.pageProps;
-    if (!pageProps || Object.keys(pageProps).length === 0) {
-        throw new CliError('NOT_FOUND', 'Resource not found', 'Please check the ID — you can find it in xiaoyuzhoufm.com URLs');
-    }
-    return pageProps;
-}
 /** Format seconds to mm:ss (e.g. 3890 → "64:50"). Returns '-' for invalid input. */
 export function formatDuration(seconds) {
     if (!Number.isFinite(seconds) || seconds < 0)

package/clis/xiaoyuzhou/utils.test.js

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { formatDuration, formatDate, fetchPageProps } from './utils.js';
+import { describe, it, expect } from 'vitest';
+import { formatDuration, formatDate } from './utils.js';
 describe('formatDuration', () => {
     it('formats typical duration', () => {
         expect(formatDuration(3890)).toBe('64:50');
@@ -8,13 +8,13 @@ describe('formatDuration', () => {
         expect(formatDuration(0)).toBe('0:00');
     });
     it('pads single-digit seconds', () => {
-        expect(formatDuration(65)).toBe('1:05');
+        expect(formatDuration(62)).toBe('1:02');
     });
-    it('formats exact minutes', () => {
-        expect(formatDuration(3600)).toBe('60:00');
+    it('handles exact minutes', () => {
+        expect(formatDuration(120)).toBe('2:00');
     });
-    it('rounds floating-point seconds', () => {
-        expect(formatDuration(3890.7)).toBe('64:51');
+    it('rounds fractional seconds', () => {
+        expect(formatDuration(65.7)).toBe('1:06');
     });
     it('returns dash for NaN', () => {
         expect(formatDuration(NaN)).toBe('-');
@@ -22,78 +22,18 @@ describe('formatDuration', () => {
     it('returns dash for negative', () => {
         expect(formatDuration(-1)).toBe('-');
     });
+    it('returns dash for Infinity', () => {
+        expect(formatDuration(Infinity)).toBe('-');
+    });
 });
 describe('formatDate', () => {
-    it('extracts YYYY-MM-DD from ISO string', () => {
-        expect(formatDate('2026-03-13T11:00:06.686Z')).toBe('2026-03-13');
-    });
-    it('handles date-only string', () => {
-        expect(formatDate('2025-01-01')).toBe('2025-01-01');
+    it('slices ISO string to date', () => {
+        expect(formatDate('2026-03-15T12:00:00Z')).toBe('2026-03-15');
     });
-    it('returns dash for undefined/empty', () => {
+    it('returns dash for empty string', () => {
         expect(formatDate('')).toBe('-');
-        expect(formatDate(undefined)).toBe('-');
-    });
-});
-describe('fetchPageProps', () => {
-    beforeEach(() => {
-        vi.restoreAllMocks();
-    });
-    it('extracts pageProps from valid HTML', async () => {
-        const mockHtml = `<html><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"podcast":{"title":"Test"}}}}</script></html>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        const result = await fetchPageProps('/podcast/abc123');
-        expect(result).toEqual({ podcast: { title: 'Test' } });
     });
-    it('throws on HTTP error', async () => {
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: false,
-            status: 404,
-            text: () => Promise.resolve('Not Found'),
-        }));
-        await expect(fetchPageProps('/podcast/invalid')).rejects.toThrow('HTTP 404');
-    });
-    it('throws when __NEXT_DATA__ is missing', async () => {
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve('<html><body>No data here</body></html>'),
-        }));
-        await expect(fetchPageProps('/podcast/abc')).rejects.toThrow('Failed to extract');
-    });
-    it('throws when pageProps is empty', async () => {
-        const mockHtml = `<script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{}}}</script>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        await expect(fetchPageProps('/podcast/abc')).rejects.toThrow('Resource not found');
-    });
-    it('throws on malformed JSON in __NEXT_DATA__', async () => {
-        const mockHtml = `<script id="__NEXT_DATA__" type="application/json">{broken json</script>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        await expect(fetchPageProps('/podcast/abc')).rejects.toThrow('Malformed __NEXT_DATA__');
-    });
-    it('handles multiline JSON in __NEXT_DATA__', async () => {
-        const mockHtml = `<script id="__NEXT_DATA__" type="application/json">
-{
-  "props": {
-    "pageProps": {
-      "episode": {"title": "Multiline Test"}
-    }
-  }
-}
-</script>`;
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-            ok: true,
-            text: () => Promise.resolve(mockHtml),
-        }));
-        const result = await fetchPageProps('/episode/abc');
-        expect(result).toEqual({ episode: { title: 'Multiline Test' } });
+    it('returns dash for undefined', () => {
+        expect(formatDate(undefined)).toBe('-');
     });
 });

package/clis/zsxq/dynamics.js

@@ -37,7 +37,7 @@ cli({
                 time: d.create_time || topic.create_time || '',
                 group: topic.group?.name || '',
                 author: getTopicAuthor(topic),
-                title: getTopicText(topic).slice(0, 120),
+                title: getTopicText(topic),
                 comments: topic.comments_count ?? 0,
                 likes: topic.likes_count ?? 0,
                 url: getTopicUrl(topic.topic_id),

package/clis/zsxq/utils.js

@@ -186,8 +186,11 @@ export function getTopicAuthor(topic) {
         '');
 }
 export function getTopicText(topic) {
+    const title = (topic.title || '').replace(/\s+/g, ' ').trim();
+    return title || getTopicContent(topic);
+}
+export function getTopicContent(topic) {
     const primary = [
-        topic.title,
         topic.talk?.text,
         topic.question?.text,
         topic.answer?.text,
@@ -218,8 +221,8 @@ export function toTopicRow(topic) {
         type: topic.type || '',
         group: topic.group?.name || '',
         author: getTopicAuthor(topic),
-        title: getTopicText(topic).slice(0, 120),
-        content: getTopicText(topic),
+        title: getTopicText(topic),
+        content: getTopicContent(topic),
         comments: topic.comments_count ?? comments.length ?? 0,
         likes: topic.likes_count ?? 0,
         readers: topic.readers_count ?? topic.reading_count ?? 0,

package/clis/zsxq/utils.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { getTopicText, toTopicRow } from './utils.js';
+
+describe('zsxq utils', () => {
+    it('keeps title and content separate when both fields exist', () => {
+        const topic = {
+            topic_id: '123',
+            title: 'A full title that should not be truncated',
+            talk: { text: 'This is the full body text.' },
+        };
+
+        expect(getTopicText(topic)).toBe('A full title that should not be truncated');
+        expect(toTopicRow(topic)).toMatchObject({
+            title: 'A full title that should not be truncated',
+            content: 'This is the full body text.',
+        });
+    });
+
+    it('falls back to body text for title when explicit title is absent', () => {
+        const topic = {
+            topic_id: '456',
+            talk: { text: 'Body-only topic text should still appear as the title preview.' },
+        };
+
+        expect(getTopicText(topic)).toBe('Body-only topic text should still appear as the title preview.');
+        expect(toTopicRow(topic)).toMatchObject({
+            title: 'Body-only topic text should still appear as the title preview.',
+            content: 'Body-only topic text should still appear as the title preview.',
+        });
+    });
+});

package/dist/src/browser/base-page.d.ts

@@ -33,7 +33,7 @@ export declare abstract class BasePage implements IPage {
     }): Promise<BrowserCookie[]>;
     abstract screenshot(options?: ScreenshotOptions): Promise<string>;
     abstract tabs(): Promise<unknown[]>;
-    abstract selectTab(index: number): Promise<void>;
+    abstract selectTab(target: number | string): Promise<void>;
     click(ref: string): Promise<void>;
     /** Override in subclasses with CDP native click support */
     protected tryNativeClick(_x: number, _y: number): Promise<boolean>;

package/dist/src/browser/bridge.d.ts

@@ -15,6 +15,7 @@ export declare class BrowserBridge implements IBrowserFactory {
     connect(opts?: {
         timeout?: number;
         workspace?: string;
+        idleTimeout?: number;
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;

package/dist/src/browser/bridge.js

@@ -33,7 +33,7 @@ export class BrowserBridge {
         this._state = 'connecting';
         try {
             await this._ensureDaemon(opts.timeout);
-            this._page = new Page(opts.workspace);
+            this._page = new Page(opts.workspace, opts.idleTimeout);
             this._state = 'connected';
             return this._page;
         }

package/dist/src/browser/cdp.js

@@ -296,7 +296,7 @@ class CDPPage extends BasePage {
     async tabs() {
         return [];
     }
-    async selectTab(_index) {
+    async selectTab(_target) {
         // Not supported in direct CDP mode
     }
 }

package/dist/src/browser/daemon-client.d.ts

@@ -6,11 +6,9 @@
 import type { BrowserSessionInfo } from '../types.js';
 export interface DaemonCommand {
     id: string;
-    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind-current' | 'network-capture-start' | 'network-capture-read' | 'cdp';
-    /** Target page identity (targetId). Cross-layer contract — preferred over tabId. */
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind-current' | 'network-capture-start' | 'network-capture-read' | 'cdp' | 'frames';
+    /** Target page identity (targetId). Cross-layer contract with the extension. */
     page?: string;
-    /** @deprecated Legacy tab ID — use `page` (targetId) instead. */
-    tabId?: number;
     code?: string;
     workspace?: string;
     url?: string;
@@ -34,6 +32,10 @@ export interface DaemonCommand {
     cdpParams?: Record<string, unknown>;
     /** When true, automation windows are created in the foreground */
     windowFocused?: boolean;
+    /** Custom idle timeout in seconds for this workspace session. Overrides the default. */
+    idleTimeout?: number;
+    /** Frame index for cross-frame operations (0-based, from 'frames' action) */
+    frameIndex?: number;
 }
 export interface DaemonResult {
     id: string;

package/dist/src/browser/daemon-client.js

@@ -11,7 +11,7 @@ const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const OPENCLI_HEADERS = { 'X-OpenCLI': '1' };
 let _idCounter = 0;
 function generateId() {
-    return `cmd_${Date.now()}_${++_idCounter}`;
+    return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
 }
 async function requestDaemon(pathname, init) {
     const { timeout = 2000, headers, ...rest } = init ?? {};
@@ -85,6 +85,11 @@ async function sendCommandRaw(action, params) {
             });
             const result = (await res.json());
             if (!result.ok) {
+                const isDuplicateCommandId = res.status === 409
+                    || (result.error ?? '').includes('Duplicate command id');
+                if (isDuplicateCommandId && attempt < maxRetries) {
+                    continue;
+                }
                 const advice = classifyBrowserError(new Error(result.error ?? ''));
                 if (advice.retryable && attempt < maxRetries) {
                     await sleep(advice.delayMs);

package/dist/src/browser/daemon-client.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, } from './daemon-client.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, sendCommand, } from './daemon-client.js';
 describe('daemon-client', () => {
     beforeEach(() => {
         vi.stubGlobal('fetch', vi.fn());
@@ -78,4 +78,43 @@ describe('daemon-client', () => {
         });
         await expect(getDaemonHealth()).resolves.toEqual({ state: 'ready', status });
     });
+    it('sendCommand includes the current pid in generated command ids', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await expect(sendCommand('exec', { code: '1 + 1' })).resolves.toBe('ok');
+        await expect(sendCommand('exec', { code: '2 + 2' })).resolves.toBe('ok');
+        const ids = vi.mocked(fetch).mock.calls.map(([, init]) => {
+            const body = JSON.parse(String(init?.body));
+            return body.id;
+        });
+        expect(ids).toHaveLength(2);
+        expect(ids[0]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
+        expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
+        expect(ids[0]).not.toBe(ids[1]);
+    });
+    it('sendCommand retries with a new id when daemon reports a duplicate pending id', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
+        const fetchMock = vi.mocked(fetch);
+        fetchMock
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 409,
+            json: () => Promise.resolve({ ok: false, error: 'Duplicate command id already pending; retry' }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 42 }),
+        });
+        await expect(sendCommand('exec', { code: '6 * 7' })).resolves.toBe(42);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        const ids = fetchMock.mock.calls.map(([, init]) => {
+            const body = JSON.parse(String(init?.body));
+            return body.id;
+        });
+        expect(ids[0]).not.toBe(ids[1]);
+    });
 });

package/dist/src/browser/dom-snapshot.js

@@ -577,6 +577,7 @@ export function generateSnapshotJs(opts = {}) {
   const currentHashes = [];
   const refIdentity = {};
   let iframeCount = 0;
+  let crossOriginIndex = 0;
 
   function walk(el, depth, parentPropagatingRect) {
     if (depth > MAX_DEPTH) return false;
@@ -757,7 +758,9 @@ export function generateSnapshotJs(opts = {}) {
       const doc = el.contentDocument;
       if (!doc || !doc.body) {
         const attrs = serializeAttrs(el);
-        lines.push(indent + '|iframe|<iframe' + (attrs ? ' ' + attrs : '') + ' /> (cross-origin)');
+        const frameLabel = '[F' + crossOriginIndex + ']';
+        lines.push(indent + '|iframe|' + frameLabel + '<iframe' + (attrs ? ' ' + attrs : '') + ' /> (cross-origin, use: opencli browser frames + browser eval --frame <index>)');
+        crossOriginIndex++;
         return false;
       }
       iframeCount++;
@@ -770,7 +773,9 @@ export function generateSnapshotJs(opts = {}) {
       return has;
     } catch {
       const attrs = serializeAttrs(el);
-      lines.push(indent + '|iframe|<iframe' + (attrs ? ' ' + attrs : '') + ' /> (blocked)');
+      const frameLabel = '[F' + crossOriginIndex + ']';
+      lines.push(indent + '|iframe|' + frameLabel + '<iframe' + (attrs ? ' ' + attrs : '') + ' /> (blocked, use: opencli browser frames + browser eval --frame <index>)');
+      crossOriginIndex++;
       return false;
     }
   }

package/dist/src/browser/page.d.ts

@@ -15,7 +15,8 @@ import { BasePage } from './base-page.js';
  */
 export declare class Page extends BasePage {
     private readonly workspace;
-    constructor(workspace?: string);
+    private readonly _idleTimeout;
+    constructor(workspace?: string, idleTimeout?: number);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;
@@ -30,8 +31,8 @@ export declare class Page extends BasePage {
     }): Promise<void>;
     /** Get the active page identity (targetId) */
     getActivePage(): string | undefined;
-    /** @deprecated Use getActivePage() instead */
-    getActiveTabId(): number | undefined;
+    /** Bind this Page instance to a specific page identity (targetId). */
+    setActivePage(page?: string): void;
     private _markUnsupportedNetworkCapture;
     evaluate(js: string): Promise<unknown>;
     getCookies(opts?: {
@@ -41,7 +42,9 @@ export declare class Page extends BasePage {
     /** Close the automation window in the extension */
     closeWindow(): Promise<void>;
     tabs(): Promise<unknown[]>;
-    selectTab(index: number): Promise<void>;
+    newTab(url?: string): Promise<string | undefined>;
+    closeTab(target?: number | string): Promise<void>;
+    selectTab(target: number | string): Promise<void>;
     /**
      * Capture a screenshot via CDP Page.captureScreenshot.
      */
@@ -55,6 +58,13 @@ export declare class Page extends BasePage {
      */
     setFileInput(files: string[], selector?: string): Promise<void>;
     insertText(text: string): Promise<void>;
+    frames(): Promise<Array<{
+        index: number;
+        frameId: string;
+        url: string;
+        name: string;
+    }>>;
+    evaluateInFrame(js: string, frameIndex: number): Promise<unknown>;
     cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
     /** CDP native click fallback — called when JS el.click() fails */
     protected tryNativeClick(x: number, y: number): Promise<boolean>;