@jackwener/opencli 1.7.3 → 1.7.5

package/clis/youtube/utils.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { extractJsonAssignmentFromHtml, prepareYoutubeApiPage } from './utils.js';
+import { extractJsonAssignmentFromHtml, extractSubscriptionChannel, prepareYoutubeApiPage } from './utils.js';
 describe('youtube utils', () => {
     it('extractJsonAssignmentFromHtml parses bootstrap objects with nested braces in strings', () => {
         const html = `
@@ -34,4 +34,35 @@ describe('youtube utils', () => {
         expect(page.goto).toHaveBeenCalledWith('https://www.youtube.com', { waitUntil: 'none' });
         expect(page.wait).toHaveBeenCalledWith(2);
     });
+    it('extractSubscriptionChannel prefers explicit handle and subscriber count fields', () => {
+        expect(extractSubscriptionChannel({
+            title: { simpleText: 'OpenAI' },
+            channelHandleText: { runs: [{ text: '@openai' }] },
+            subscriberCountText: { simpleText: '1.23M subscribers' },
+            videoCountText: { simpleText: '123 videos' },
+            navigationEndpoint: { browseEndpoint: { canonicalBaseUrl: '/channel/UC123' } },
+            channelId: 'UC123',
+        })).toEqual({
+            name: 'OpenAI',
+            handle: '@openai',
+            subscribers: '1.23M subscribers',
+            url: 'https://www.youtube.com/channel/UC123',
+        });
+    });
+    it('extractSubscriptionChannel falls back when handle/count fields are overloaded', () => {
+        expect(extractSubscriptionChannel({
+            title: {
+                runs: [{ text: 'OpenAI' }],
+            },
+            subscriberCountText: { simpleText: '@openai' },
+            videoCountText: { simpleText: '1.23M subscribers' },
+            navigationEndpoint: { browseEndpoint: { canonicalBaseUrl: '/@openai' } },
+            channelId: 'UC123',
+        })).toEqual({
+            name: 'OpenAI',
+            handle: '@openai',
+            subscribers: '1.23M subscribers',
+            url: 'https://www.youtube.com/@openai',
+        });
+    });
 });

package/clis/youtube/watch-later.js

@@ -0,0 +1,76 @@
+/**
+ * YouTube watch-later — the user's Watch Later queue.
+ * Navigates to /playlist?list=WL and reads ytInitialData directly.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { FETCH_BROWSE_FN, extractPlaylistVideos } from './utils.js';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+cli({
+    site: 'youtube',
+    name: 'watch-later',
+    description: 'Get your YouTube Watch Later queue',
+    domain: 'www.youtube.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'limit', type: 'int', default: 50, help: 'Max videos to return (default 50, max 200)' },
+    ],
+    columns: ['rank', 'title', 'channel', 'duration', 'views', 'published', 'url'],
+    func: async (page, kwargs) => {
+        const limit = Math.min(kwargs.limit || 50, 200);
+        await page.goto('https://www.youtube.com/playlist?list=WL');
+        await page.wait(3);
+        const data = await page.evaluate(`
+      (async () => {
+        const d = window.ytInitialData;
+        if (!d) return { error: 'YouTube data not found — are you logged in?' };
+
+        const limit = ${limit};
+        const cfg = window.ytcfg?.data_ || {};
+        const apiKey = cfg.INNERTUBE_API_KEY;
+        const context = cfg.INNERTUBE_CONTEXT;
+
+        const header = d.header?.playlistHeaderRenderer;
+        const title = header?.title?.simpleText || 'Watch Later';
+        const stats = (header?.stats || [])
+          .map(s => s.runs?.map(r => r.text)?.join('') || s.simpleText || '')
+          .filter(Boolean);
+
+        const tabs = d.contents?.twoColumnBrowseResultsRenderer?.tabs || [];
+        let listContents = tabs[0]?.tabRenderer?.content?.sectionListRenderer?.contents?.[0]?.itemSectionRenderer?.contents?.[0]?.playlistVideoListRenderer?.contents || [];
+
+        ${FETCH_BROWSE_FN}
+
+        const extractVideos = ${extractPlaylistVideos.toString()};
+
+        let videos = extractVideos(listContents);
+
+        let contItem = listContents[listContents.length - 1];
+        while (videos.length < limit && contItem?.continuationItemRenderer && apiKey && context) {
+          const token = contItem.continuationItemRenderer?.continuationEndpoint?.continuationCommand?.token;
+          if (!token) break;
+          const contData = await fetchBrowse(apiKey, { context, continuation: token });
+          if (contData.error) break;
+          const newItems = contData.onResponseReceivedActions?.[0]?.appendContinuationItemsAction?.continuationItems || [];
+          if (!newItems.length) break;
+          videos = videos.concat(extractVideos(newItems));
+          contItem = newItems[newItems.length - 1];
+        }
+
+        return { title, stats, videos: videos.slice(0, limit) };
+      })()
+    `);
+        if (!data || typeof data !== 'object') {
+            throw new CommandExecutionError('Failed to fetch Watch Later — make sure you are logged into YouTube');
+        }
+        if (data.error) {
+            throw new CommandExecutionError(String(data.error));
+        }
+        if (!data.videos?.length) {
+            throw new EmptyResultError('youtube watch-later');
+        }
+        const statsStr = (data.stats || []).join(' | ');
+        process.stderr.write(`${data.title}  ${statsStr}\n`);
+        return data.videos;
+    },
+});

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/base-page.js

@@ -8,8 +8,10 @@
  * Subclasses implement the transport-specific methods: goto, evaluate,
  * getCookies, screenshot, tabs, etc.
  */
-import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
-import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { generateSnapshotJs, getFormStateJs } from './dom-snapshot.js';
+import { pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs } from './target-resolver.js';
+import { TargetError } from './target-errors.js';
 import { formatSnapshot } from '../snapshotFormatter.js';
 export class BasePage {
     _lastUrl = null;
@@ -36,7 +38,13 @@ export class BasePage {
     }
     // ── Shared DOM helper implementations ──
     async click(ref) {
-        const result = await this.evaluate(clickJs(ref));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Execute click on resolved element
+        const result = await this.evaluate(clickResolvedJs());
         // Backwards compat: old format returned 'clicked' string
         if (typeof result === 'string' || result == null)
             return;
@@ -56,13 +64,25 @@ export class BasePage {
         return false;
     }
     async typeText(ref, text) {
-        await this.evaluate(typeTextJs(ref, text));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Execute type on resolved element
+        await this.evaluate(typeResolvedJs(text));
     }
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
     async scrollTo(ref) {
-        return this.evaluate(scrollToRefJs(ref));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Scroll to resolved element
+        return this.evaluate(scrollResolvedJs());
     }
     async getFormState() {
         return (await this.evaluate(getFormStateJs()));

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

@@ -15,9 +15,12 @@ export declare class BrowserBridge implements IBrowserFactory {
     connect(opts?: {
         timeout?: number;
         workspace?: string;
+        idleTimeout?: number;
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;
+    /** Poll until daemon is fully stopped (port released). */
+    private _waitForDaemonStop;
     /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
     private _pollUntilReady;
 }

package/dist/src/browser/bridge.js

@@ -6,9 +6,10 @@ import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Page } from './page.js';
-import { getDaemonHealth } from './daemon-client.js';
+import { getDaemonHealth, requestDaemonShutdown } from './daemon-client.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { BrowserConnectError } from '../errors.js';
+import { PKG_VERSION } from '../version.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
@@ -32,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;
         }
@@ -57,18 +58,42 @@ export class BrowserBridge {
         // Fast path: everything ready
         if (health.state === 'ready')
             return;
-        // Daemon running but no extension — wait for extension with progress
+        // Daemon running but no extension
         if (health.state === 'no-extension') {
-            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
-                process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
-                process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
+            // Detect stale daemon: version mismatch OR missing daemonVersion (pre-version daemon)
+            const daemonVersion = health.status?.daemonVersion;
+            const isStale = !daemonVersion || daemonVersion !== PKG_VERSION;
+            if (isStale) {
+                // Stale daemon — restart it so extension gets a fresh WebSocket endpoint
+                const reason = daemonVersion
+                    ? `v${daemonVersion} ≠ v${PKG_VERSION}`
+                    : `pre-version daemon, CLI is v${PKG_VERSION}`;
+                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                    process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
+                }
+                const shutdownAccepted = await requestDaemonShutdown();
+                const portReleased = shutdownAccepted && await this._waitForDaemonStop(3000);
+                if (!portReleased) {
+                    // Stale daemon replacement failed — don't blindly spawn on an occupied port
+                    throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down.\n` +
+                        '  Run manually: opencli daemon stop && opencli doctor', 'daemon-not-running');
+                }
+                // Port released — fall through to spawn a fresh daemon
+            }
+            else {
+                // Same version — wait for extension to connect
+                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                    process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
+                    process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
+                }
+                if (await this._pollUntilReady(timeoutMs))
+                    return;
+                throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
+                    'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
+                    'If not installed:\n' +
+                    '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                    '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
             }
-            if (await this._pollUntilReady(timeoutMs))
-                return;
-            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
-                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
-                '  Then run: opencli doctor', 'extension-not-connected');
         }
         // No daemon — spawn one
         const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -94,13 +119,25 @@ export class BrowserBridge {
             return;
         const finalHealth = await getDaemonHealth();
         if (finalHealth.state === 'no-extension') {
-            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
+                'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
+                'If not installed:\n' +
                 '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
-                '  Then run: opencli doctor', 'extension-not-connected');
+                '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
         }
         throw new BrowserConnectError('Failed to start opencli daemon', `Try running manually:\n  node ${daemonPath}\nMake sure port ${DEFAULT_DAEMON_PORT} is available.`, 'daemon-not-running');
     }
+    /** Poll until daemon is fully stopped (port released). */
+    async _waitForDaemonStop(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+            const h = await getDaemonHealth();
+            if (h.state === 'stopped')
+                return true;
+        }
+        return false;
+    }
     /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
     async _pollUntilReady(timeoutMs) {
         const deadline = Date.now() + timeoutMs;

package/dist/src/browser/cdp.js

@@ -255,6 +255,7 @@ class CDPPage extends BasePage {
             });
             this._networkCapturing = true;
         }
+        return true;
     }
     async readNetworkCapture() {
         // Await all in-flight body fetches so entries have responsePreview populated
@@ -295,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;
@@ -47,6 +49,7 @@ export interface DaemonStatus {
     ok: boolean;
     pid: number;
     uptime: number;
+    daemonVersion?: string;
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: 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

@@ -575,7 +575,9 @@ export function generateSnapshotJs(opts = {}) {
   const lines = [];
   const hiddenInteractives = [];
   const currentHashes = [];
+  const refIdentity = {};
   let iframeCount = 0;
+  let crossOriginIndex = 0;
 
   function walk(el, depth, parentPropagatingRect) {
     if (depth > MAX_DEPTH) return false;
@@ -709,11 +711,20 @@ export function generateSnapshotJs(opts = {}) {
     // Scroll marker
     if (isScrollable && !interactive) line += '|scroll|';
 
-    // Interactive index + data-ref
+    // Interactive index + data-ref + fingerprint
     if (interactive) {
       interactiveIndex++;
       if (ANNOTATE_REFS) el.setAttribute('data-opencli-ref', '' + interactiveIndex);
       line += isScrollable ? '|scroll[' + interactiveIndex + ']|' : '[' + interactiveIndex + ']';
+      // Store fingerprint for stale-ref detection
+      refIdentity['' + interactiveIndex] = {
+        tag: tag,
+        role: el.getAttribute('role') || '',
+        text: (el.textContent || '').trim().slice(0, 30),
+        ariaLabel: el.getAttribute('aria-label') || '',
+        id: el.id || '',
+        testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || '',
+      };
     }
 
     // Tag + attributes
@@ -747,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++;
@@ -760,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;
     }
   }
@@ -797,6 +812,8 @@ export function generateSnapshotJs(opts = {}) {
 
   // Store hashes on window for next diff snapshot
   try { window.__opencli_prev_hashes = JSON.stringify(currentHashes); } catch {}
+  // Store ref identity map for stale-ref detection by target resolver
+  try { window.__opencli_ref_identity = refIdentity; } catch {}
 
   return lines.join('\\n');
 })()

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

@@ -15,9 +15,12 @@ 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;
+    private _networkCaptureWarned;
     /** Helper: spread workspace into command params */
     private _wsOpt;
     /** Helper: spread workspace + page identity into command params */
@@ -28,8 +31,9 @@ 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?: {
         domain?: string;
@@ -38,12 +42,14 @@ 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.
      */
     screenshot(options?: ScreenshotOptions): Promise<string>;
-    startNetworkCapture(pattern?: string): Promise<void>;
+    startNetworkCapture(pattern?: string): Promise<boolean>;
     readNetworkCapture(): Promise<unknown[]>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
@@ -52,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>;