@jackwener/opencli 1.1.0 → 1.2.0

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opencli
-description: "OpenCLI — Make any website or Electron App your CLI. Zero risk, AI-powered, reuse Chrome login. 80+ commands across 19 sites."
+description: "OpenCLI — Make any website or Electron App your CLI. Zero risk, AI-powered, reuse Chrome login. 150+ commands across 30+ sites."
 version: 1.1.0
 author: jackwener
 tags: [cli, browser, web, chrome-extension, cdp, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, xueqiu, youtube, boss, coupang, AI, agent]
@@ -39,7 +39,7 @@ Browser commands require:
 
 > **Note**: You must be logged into the target website in Chrome before running commands. Tabs opened during command execution are auto-closed afterwards.
 
-Public API commands (`hackernews`, `github search`, `v2ex`) need no browser.
+Public API commands (`hackernews`, `v2ex`) need no browser.
 
 ## Commands Reference
 
@@ -48,7 +48,7 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser.
 ```bash
 # Bilibili (browser)
 opencli bilibili hot --limit 10          # B站热门视频
-opencli bilibili search --keyword "rust"  # 搜索视频
+opencli bilibili search "rust"            # 搜索视频 (query positional)
 opencli bilibili me                       # 我的信息
 opencli bilibili favorite                 # 我的收藏
 opencli bilibili history --limit 20       # 观看历史
@@ -61,15 +61,19 @@ opencli bilibili following --limit 20     # 我的关注列表 (支持 --uid 查
 
 # 知乎 (browser)
 opencli zhihu hot --limit 10             # 知乎热榜
-opencli zhihu search --keyword "AI"      # 搜索
-opencli zhihu question --id 34816524     # 问题详情和回答
+opencli zhihu search "AI"                # 搜索 (query positional)
+opencli zhihu question 34816524            # 问题详情和回答 (id positional)
 
 # 小红书 (browser)
-opencli xiaohongshu search --keyword "美食"  # 搜索笔记
+opencli xiaohongshu search "美食"           # 搜索笔记 (query positional)
 opencli xiaohongshu notifications             # 通知（mentions/likes/connections）
 opencli xiaohongshu feed --limit 10           # 推荐 Feed
-opencli xiaohongshu me                        # 我的信息
-opencli xiaohongshu user --uid xxx             # 用户主页
+opencli xiaohongshu user xxx               # 用户主页 (id positional)
+opencli xiaohongshu creator-notes --limit 10   # 创作者笔记列表
+opencli xiaohongshu creator-note-detail --note-id xxx  # 笔记详情
+opencli xiaohongshu creator-notes-summary      # 笔记数据概览
+opencli xiaohongshu creator-profile            # 创作者资料
+opencli xiaohongshu creator-stats              # 创作者数据统计
 
 # 雪球 Xueqiu (browser)
 opencli xueqiu hot-stock --limit 10      # 雪球热门股票榜
@@ -77,15 +81,17 @@ opencli xueqiu stock --symbol SH600519   # 查看股票实时行情
 opencli xueqiu watchlist                 # 获取自选股/持仓列表
 opencli xueqiu feed                      # 我的关注 timeline
 opencli xueqiu hot --limit 10            # 雪球热榜
-opencli xueqiu search --keyword "特斯拉"  # 搜索
+opencli xueqiu search "特斯拉"            # 搜索 (query positional)
 
-# GitHub (public)
-opencli github search --keyword "cli"    # 搜索仓库
+# GitHub (via gh External CLI)
+opencli gh repo list                     # 列出仓库 (passthrough to gh)
+opencli gh pr list --limit 5             # PR 列表
+opencli gh issue list                    # Issue 列表
 
 # Twitter/X (browser)
 opencli twitter trending --limit 10      # 热门话题
 opencli twitter bookmarks --limit 20     # 获取收藏的书签推文
-opencli twitter search --keyword "AI"    # 搜索推文
+opencli twitter search "AI"              # 搜索推文 (query positional)
 opencli twitter profile elonmusk         # 用户资料
 opencli twitter timeline --limit 20      # 时间线
 opencli twitter thread 1234567890        # 推文 thread（原文 + 回复）
@@ -100,15 +106,15 @@ opencli reddit hot --limit 10            # 热门帖子
 opencli reddit hot --subreddit programming  # 指定子版块
 opencli reddit frontpage --limit 10      # 首页 /r/all
 opencli reddit popular --limit 10        # /r/popular 热门
-opencli reddit search --query "AI" --sort top --time week  # 搜索（支持排序+时间过滤）
-opencli reddit subreddit --name rust --sort top --time month  # 子版块浏览（支持时间过滤）
-opencli reddit read --post_id 1abc123    # 阅读帖子 + 评论
-opencli reddit user --username spez      # 用户资料（karma、注册时间）
-opencli reddit user-posts --username spez  # 用户发帖历史
-opencli reddit user-comments --username spez  # 用户评论历史
-opencli reddit upvote --post_id xxx --direction up  # 投票（up/down/none）
-opencli reddit save --post_id xxx        # 收藏帖子
-opencli reddit comment --post_id xxx --text "Great!"  # 发表评论
+opencli reddit search "AI" --sort top --time week  # 搜索（支持排序+时间过滤）
+opencli reddit subreddit rust --sort top --time month  # 子版块浏览（支持时间过滤）
+opencli reddit read --post-id 1abc123    # 阅读帖子 + 评论
+opencli reddit user spez                 # 用户资料（karma、注册时间）
+opencli reddit user-posts spez           # 用户发帖历史
+opencli reddit user-comments spez        # 用户评论历史
+opencli reddit upvote --post-id xxx --direction up  # 投票（up/down/none）
+opencli reddit save --post-id xxx        # 收藏帖子
+opencli reddit comment --post-id xxx "Great!"  # 发表评论 (text positional)
 opencli reddit subscribe --subreddit python  # 订阅子版块
 opencli reddit saved --limit 10          # 我的收藏
 opencli reddit upvoted --limit 10        # 我的赞
@@ -116,7 +122,7 @@ opencli reddit upvoted --limit 10        # 我的赞
 # V2EX (public + browser)
 opencli v2ex hot --limit 10              # 热门话题
 opencli v2ex latest --limit 10           # 最新话题
-opencli v2ex topic --id 1024             # 主题详情
+opencli v2ex topic 1024                  # 主题详情 (id positional)
 opencli v2ex daily                       # 每日签到 (browser)
 opencli v2ex me                          # 我的信息 (browser)
 opencli v2ex notifications --limit 10    # 通知 (browser)
@@ -131,14 +137,26 @@ opencli bbc news --limit 10             # BBC News RSS headlines
 opencli weibo hot --limit 10            # 微博热搜
 
 # BOSS直聘 (browser)
-opencli boss search --query "AI agent"  # 搜索职位
-opencli boss detail --securityId xxx    # 职位详情
+opencli boss search "AI agent"          # 搜索职位 (query positional)
+opencli boss detail --security-id xxx    # 职位详情
+opencli boss recommend --limit 10        # 推荐职位
+opencli boss joblist --limit 10          # 职位列表
+opencli boss greet --security-id xxx     # 打招呼
+opencli boss batchgreet --job-id xxx     # 批量打招呼
+opencli boss send --uid xxx "消息内容"    # 发消息 (text positional)
+opencli boss chatlist --limit 10         # 聊天列表
+opencli boss chatmsg --security-id xxx   # 聊天记录
+opencli boss invite --security-id xxx    # 邀请沟通
+opencli boss mark --security-id xxx      # 标记管理
+opencli boss exchange --security-id xxx  # 交换联系方式
+opencli boss resume                    # 简历管理
+opencli boss stats                     # 数据统计
 
 # YouTube (browser)
-opencli youtube search --query "rust"   # 搜索视频
-opencli youtube video --url "https://www.youtube.com/watch?v=xxx"  # 视频元数据（标题、播放量、描述等）
-opencli youtube transcript --url "https://www.youtube.com/watch?v=xxx"  # 获取视频字幕/转录
-opencli youtube transcript --url "xxx" --lang zh-Hans --mode raw  # 指定语言 + 原始时间戳模式
+opencli youtube search "rust"            # 搜索视频 (query positional)
+opencli youtube video "https://www.youtube.com/watch?v=xxx"  # 视频元数据
+opencli youtube transcript "https://www.youtube.com/watch?v=xxx"  # 获取视频字幕/转录
+opencli youtube transcript "xxx" --lang zh-Hans --mode raw  # 指定语言 + 原始时间戳模式
 
 # Yahoo Finance (browser)
 opencli yahoo-finance quote --symbol AAPL  # 股票行情
@@ -147,22 +165,73 @@ opencli yahoo-finance quote --symbol AAPL  # 股票行情
 opencli sinafinance news --limit 10 --type 1  # 7x24实时快讯 (0=全部 1=A股 2=宏观 3=公司 4=数据 5=市场 6=国际 7=观点 8=央行 9=其它)
 
 # Reuters (browser)
-opencli reuters search --query "AI"     # 路透社搜索
+opencli reuters search "AI"              # 路透社搜索 (query positional)
 
 # 什么值得买 (browser)
-opencli smzdm search --keyword "耳机"    # 搜索好价
+opencli smzdm search "耳机"              # 搜索好价 (query positional)
 
 # 携程 (browser)
-opencli ctrip search --query "三亚"      # 搜索目的地
+opencli ctrip search "三亚"              # 搜索目的地 (query positional)
 
 # Antigravity (Electron/CDP)
 opencli antigravity status              # 检查 CDP 连接
 opencli antigravity send "hello"        # 发送文本到当前 agent 聊天框
 opencli antigravity read                # 读取整个聊天记录面板
 opencli antigravity new                 # 清空聊天、开启新对话
+opencli antigravity dump               # 导出 DOM 和快照调试信息
 opencli antigravity extract-code        # 自动抽取 AI 回复中的代码块
 opencli antigravity model claude        # 切换底层模型
 opencli antigravity watch               # 流式监听增量消息
+opencli antigravity serve --port 8082  # 启动 Anthropic 兼容代理
+
+# Barchart (browser)
+opencli barchart quote --symbol AAPL     # 股票行情
+opencli barchart options --symbol AAPL   # 期权链
+opencli barchart greeks --symbol AAPL    # 期权 Greeks
+opencli barchart flow --limit 20         # 异常期权活动
+
+# Jike 即刻 (browser)
+opencli jike feed --limit 10             # 动态流
+opencli jike search "AI"                 # 搜索 (query positional)
+opencli jike create "内容"                # 发布动态 (text positional)
+opencli jike like xxx                    # 点赞 (id positional)
+opencli jike comment xxx "评论"           # 评论 (id + text positional)
+opencli jike repost xxx                  # 转发 (id positional)
+opencli jike notifications               # 通知
+
+# Linux.do (public)
+opencli linux-do hot --limit 10          # 热门话题
+opencli linux-do latest --limit 10       # 最新话题
+opencli linux-do search "rust"           # 搜索 (query positional)
+opencli linux-do topic 1024              # 主题详情 (id positional)
+
+# StackOverflow (public)
+opencli stackoverflow hot --limit 10     # 热门问题
+opencli stackoverflow search "typescript"  # 搜索 (query positional)
+opencli stackoverflow bounties --limit 10  # 悬赏问题
+
+# WeRead 微信读书 (browser)
+opencli weread shelf --limit 10          # 书架
+opencli weread search "AI"               # 搜索图书 (query positional)
+opencli weread book xxx                  # 图书详情 (book-id positional)
+opencli weread highlights xxx            # 划线笔记 (book-id positional)
+opencli weread notes xxx                 # 想法笔记 (book-id positional)
+opencli weread ranking --limit 10        # 排行榜
+
+# Jimeng 即梦 AI (browser)
+opencli jimeng generate --prompt "描述"  # AI 生图
+opencli jimeng history --limit 10        # 生成历史
+
+# Grok (default + explicit web)
+opencli grok ask --prompt "问题"         # 提问 Grok（兼容默认路径）
+opencli grok ask --prompt "问题" --web   # 显式 grok.com consumer web UI 路径
+
+# HuggingFace (public)
+opencli hf top --limit 10                # 热门模型
+
+# 超星学习通 (browser)
+opencli chaoxing assignments             # 作业列表
+opencli chaoxing exams                   # 考试列表
 ```
 
 ### Management Commands
@@ -300,7 +369,7 @@ cli({
   site: 'mysite',
   name: 'search',
   strategy: Strategy.INTERCEPT, // Or COOKIE
-  args: [{ name: 'keyword', required: true }],
+  args: [{ name: 'query', required: true, positional: true }],
   columns: ['rank', 'title', 'url'],
   func: async (page, kwargs) => {
     await page.goto('https://www.mysite.com/search');
@@ -351,7 +420,7 @@ cli({
 
 ```yaml
 # Arguments with defaults
-${{ args.keyword }}
+${{ args.query }}
 ${{ args.limit | default(20) }}
 
 # Current item (in map/filter)

package/dist/browser/cdp.d.ts

@@ -25,13 +25,13 @@ export declare class CDPBridge {
     }): Promise<IPage>;
     close(): Promise<void>;
     /** Send a CDP command with timeout guard (P0 fix #4) */
-    send(method: string, params?: any, timeoutMs?: number): Promise<any>;
+    send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     /** Listen for a CDP event */
-    on(event: string, handler: (params: any) => void): void;
+    on(event: string, handler: (params: unknown) => void): void;
     /** Remove a CDP event listener */
-    off(event: string, handler: (params: any) => void): void;
+    off(event: string, handler: (params: unknown) => void): void;
     /** Wait for a CDP event to fire (one-shot) */
-    waitForEvent(event: string, timeoutMs?: number): Promise<any>;
+    waitForEvent(event: string, timeoutMs?: number): Promise<unknown>;
 }
 declare function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined;
 declare function scoreCDPTarget(target: CDPTarget, preferredPattern?: RegExp): number;

package/dist/browser/cdp.js

@@ -9,6 +9,7 @@
  */
 import { WebSocket } from 'ws';
 import { wrapForEval } from './utils.js';
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, } from './dom-helpers.js';
 const CDP_SEND_TIMEOUT = 30_000; // 30s per command
 export class CDPBridge {
@@ -35,7 +36,8 @@ export class CDPBridge {
         }
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(wsUrl);
-            const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), opts?.timeout ?? 10000);
+            const timeoutMs = (opts?.timeout ?? 10) * 1000; // opts.timeout is in seconds
+            const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), timeoutMs);
             ws.on('open', () => {
                 clearTimeout(timeout);
                 this._ws = ws;
@@ -137,12 +139,17 @@ class CDPPage {
         this.bridge = bridge;
     }
     /** Navigate with proper load event waiting (P1 fix #3) */
-    async goto(url) {
+    async goto(url, options) {
         await this.bridge.send('Page.enable');
         const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000)
             .catch(() => { }); // Don't fail if event times out
         await this.bridge.send('Page.navigate', { url });
         await loadPromise;
+        // Post-load settle: SPA frameworks need extra time to render after load event
+        if (options?.waitUntil !== 'none') {
+            const settleMs = options?.settleMs ?? 1000;
+            await new Promise(resolve => setTimeout(resolve, settleMs));
+        }
     }
     async evaluate(js) {
         const expression = wrapForEval(js);
@@ -158,14 +165,22 @@ class CDPPage {
     }
     async getCookies(opts = {}) {
         const result = await this.bridge.send('Network.getCookies', opts.url ? { urls: [opts.url] } : {});
-        const cookies = Array.isArray(result?.cookies) ? result.cookies : [];
-        return opts.domain
-            ? cookies.filter((cookie) => typeof cookie.domain === 'string' && cookie.domain.includes(opts.domain))
+        const cookies = isRecord(result) && Array.isArray(result.cookies) ? result.cookies : [];
+        const domain = opts.domain;
+        return domain
+            ? cookies.filter((cookie) => isCookie(cookie) && cookie.domain.includes(domain))
             : cookies;
     }
-    async snapshot(_opts) {
-        // CDP doesn't have a built-in accessibility tree equivalent without additional setup
-        return '(snapshot not available in CDP mode)';
+    async snapshot(opts = {}) {
+        const snapshotJs = generateSnapshotJs({
+            viewportExpand: opts.viewportExpand ?? 800,
+            maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
+            interactiveOnly: opts.interactive ?? false,
+            maxTextLength: opts.maxTextLength ?? 120,
+            includeScrollInfo: true,
+            bboxDedup: true,
+        });
+        return this.evaluate(snapshotJs);
     }
     // ── Shared DOM operations (P1 fix #5 — using dom-helpers.ts) ──
     async click(ref) {
@@ -177,13 +192,20 @@ class CDPPage {
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
+    async scrollTo(ref) {
+        return this.evaluate(scrollToRefJs(ref));
+    }
+    async getFormState() {
+        return (await this.evaluate(getFormStateJs()));
+    }
     async wait(options) {
         if (typeof options === 'number') {
             await new Promise(resolve => setTimeout(resolve, options * 1000));
             return;
         }
-        if (options.time) {
-            await new Promise(resolve => setTimeout(resolve, options.time * 1000));
+        if (typeof options.time === 'number') {
+            const waitTime = options.time;
+            await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
             return;
         }
         if (options.text) {
@@ -206,7 +228,7 @@ class CDPPage {
             quality: options.format === 'jpeg' ? (options.quality ?? 80) : undefined,
             captureBeyondViewport: options.fullPage ?? false,
         });
-        const base64 = result.data;
+        const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
         if (options.path) {
             const fs = await import('node:fs');
             const path = await import('node:path');
@@ -217,7 +239,8 @@ class CDPPage {
         return base64;
     }
     async networkRequests(includeStatic = false) {
-        return this.evaluate(networkRequestsJs(includeStatic));
+        const result = await this.evaluate(networkRequestsJs(includeStatic));
+        return Array.isArray(result) ? result : [];
     }
     async tabs() {
         return [];
@@ -244,9 +267,18 @@ class CDPPage {
     async getInterceptedRequests() {
         const { generateReadInterceptedJs } = await import('../interceptor.js');
         const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
-        return result || [];
+        return Array.isArray(result) ? result : [];
     }
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCookie(value) {
+    return isRecord(value)
+        && typeof value.name === 'string'
+        && typeof value.value === 'string'
+        && typeof value.domain === 'string';
+}
 // ── CDP target selection (unchanged) ──
 function selectCDPTarget(targets) {
     const preferredPattern = compilePreferredPattern(process.env.OPENCLI_CDP_TARGET);
@@ -306,8 +338,6 @@ function scoreCDPTarget(target, preferredPattern) {
         score += 120;
     if (title.includes('discord'))
         score += 120;
-    if (title.includes('netease'))
-        score += 120;
     if (url.includes('antigravity'))
         score += 100;
     if (url.includes('codex'))
@@ -320,8 +350,6 @@ function scoreCDPTarget(target, preferredPattern) {
         score += 100;
     if (url.includes('discord'))
         score += 100;
-    if (url.includes('netease'))
-        score += 100;
     return score;
 }
 function compilePreferredPattern(raw) {

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

@@ -36,4 +36,5 @@ export declare function isExtensionConnected(): Promise<boolean>;
  * Retries up to 3 times with 500ms delay for transient failures.
  */
 export declare function sendCommand(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<unknown>;
-export declare function listSessions(): Promise<any[]>;
+export declare function listSessions(): Promise<BrowserSessionInfo[]>;
+import type { BrowserSessionInfo } from '../types.js';

package/dist/browser/dom-helpers.js

@@ -10,8 +10,21 @@ export function clickJs(ref) {
     return `
     (() => {
       const ref = ${safeRef};
-      const el = document.querySelector('[data-ref="' + ref + '"]')
-        || document.querySelectorAll('a, button, input, [role="button"], [tabindex]')[parseInt(ref, 10) || 0];
+      // 1. data-opencli-ref (set by snapshot engine)
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      // 2. data-ref (legacy)
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      // 3. CSS selector
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      // 4. Numeric index into interactive elements
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('a, button, input, select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])')[idx];
+        }
+      }
       if (!el) throw new Error('Element not found: ' + ref);
       el.scrollIntoView({ behavior: 'instant', block: 'center' });
       el.click();
@@ -26,13 +39,31 @@ export function typeTextJs(ref, text) {
     return `
     (() => {
       const ref = ${safeRef};
-      const el = document.querySelector('[data-ref="' + ref + '"]')
-        || document.querySelectorAll('input, textarea, [contenteditable]')[parseInt(ref, 10) || 0];
+      // 1. data-opencli-ref (set by snapshot engine)
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      // 2. data-ref (legacy)
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      // 3. CSS selector
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      // 4. Numeric index into typeable elements
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('input, textarea, [contenteditable="true"]')[idx];
+        }
+      }
       if (!el) throw new Error('Element not found: ' + ref);
       el.focus();
-      el.value = ${safeText};
-      el.dispatchEvent(new Event('input', { bubbles: true }));
-      el.dispatchEvent(new Event('change', { bubbles: true }));
+      if (el.isContentEditable) {
+        el.textContent = ${safeText};
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      } else {
+        el.value = ${safeText};
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      }
       return 'typed';
     })()
   `;

package/dist/browser/dom-snapshot.d.ts

@@ -0,0 +1,86 @@
+/**
+ * DOM Snapshot Engine — Advanced DOM pruning for LLM consumption.
+ *
+ * Inspired by browser-use's multi-layer pruning pipeline, adapted for opencli's
+ * Chrome Extension + CDP architecture. Runs entirely in-page via Runtime.evaluate.
+ *
+ * Pipeline:
+ *   1. Walk DOM tree, collect visibility + layout + interactivity signals
+ *   2. Prune invisible, zero-area, non-content elements
+ *   3. SVG & decoration collapse
+ *   4. Shadow DOM traversal
+ *   5. Same-origin iframe content extraction
+ *   6. Bounding-box parent-child dedup (link/button wrapping children)
+ *   7. Paint-order occlusion detection (overlay/modal coverage)
+ *   8. Attribute whitelist filtering
+ *   9. Table-aware serialization (markdown tables)
+ *  10. Token-efficient serialization with interactive indices
+ *  11. data-ref annotation for click/type targeting
+ *  12. Hidden interactive element hints (scroll-to-reveal)
+ *  13. Incremental diff (mark new elements with *)
+ *
+ * Additional tools:
+ *   - scrollToRefJs(ref) — scroll to a data-opencli-ref element
+ *   - getFormStateJs()  — extract all form fields as structured JSON
+ */
+export interface SnapshotOptions {
+    /** Extra pixels beyond viewport to include (default 800) */
+    viewportExpand?: number;
+    /** Maximum DOM depth to traverse (default 50) */
+    maxDepth?: number;
+    /** Only emit interactive elements and their landmark ancestors */
+    interactiveOnly?: boolean;
+    /** Maximum text content length per node (default 120) */
+    maxTextLength?: number;
+    /** Include scroll position info on scrollable containers (default true) */
+    includeScrollInfo?: boolean;
+    /** Enable bounding-box parent-child dedup (default true) */
+    bboxDedup?: boolean;
+    /** Traverse Shadow DOM roots (default true) */
+    includeShadowDom?: boolean;
+    /** Extract same-origin iframe content (default true) */
+    includeIframes?: boolean;
+    /** Maximum number of iframes to process (default 5) */
+    maxIframes?: number;
+    /** Enable paint-order occlusion detection (default true) */
+    paintOrderCheck?: boolean;
+    /** Annotate interactive elements with data-opencli-ref (default true) */
+    annotateRefs?: boolean;
+    /** Report hidden interactive elements outside viewport (default true) */
+    reportHidden?: boolean;
+    /** Filter ad/noise elements (default true) */
+    filterAds?: boolean;
+    /** Serialize tables as markdown (default true) */
+    markdownTables?: boolean;
+    /** Previous snapshot hash set (JSON array of hashes) for diff marking (default null) */
+    previousHashes?: string | null;
+}
+/**
+ * Generate JS to scroll to an element identified by data-opencli-ref.
+ * Completes the snapshot→action loop: snapshot identifies `[3]<button>`,
+ * caller can then `scrollToRef('3')` to bring it into view.
+ */
+export declare function scrollToRefJs(ref: string): string;
+/**
+ * Generate JS to extract all form field values from the page.
+ * Returns structured JSON: { forms: [{ id, action, fields: [{ tag, type, name, value, ... }] }] }
+ */
+export declare function getFormStateJs(): string;
+/**
+ * Generate JavaScript code that, when evaluated in a page context via CDP
+ * Runtime.evaluate, returns a pruned DOM snapshot string optimised for LLMs.
+ *
+ * The snapshot output format:
+ *   [42]<button type=submit>Search</button>
+ *   |scroll|<div> (0.5↑ 3.2↓)
+ *     *[58]<a href=/r/1>Result 1</a>
+ *     [59]<a href=/r/2>Result 2</a>
+ *
+ * - `[id]` — interactive element with backend index for targeting
+ * - `*` prefix — newly appeared element (incremental diff)
+ * - `|scroll|` — scrollable container with page counts
+ * - `|shadow|` — Shadow DOM boundary
+ * - `|iframe|` — iframe content
+ * - `|table|` — markdown table rendering
+ */
+export declare function generateSnapshotJs(opts?: SnapshotOptions): string;