dsh-browser-view 0.4.1 → 0.7.0

package/lib/types/browser/session.d.ts

@@ -1,5 +1,11 @@
 import type { BrowserContext, Page } from "playwright-core";
-import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry, RefEntry, ReplayStep, SelectorHint } from "./types.js";
+import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry } from "./types.js";
+export * from "./session/cache.js";
+export * from "./session/collaboration.js";
+export * from "./session/recorder.js";
+export * from "./session/screenshot.js";
+export * from "./session/target.js";
+export * from "./session/semantic.js";
 /** 当前活动 profile 名(默认 "default")。 */
 export declare let currentProfile: string;
 /** 多配置文件浏览器会话:name → 会话状态。 */
@@ -8,129 +14,6 @@ export declare const profileStates: Map<string, ProfileState>;
 export declare const savedForms: Map<string, FormField[]>;
 /** 最近一次 browser_form 填充的字段(供 browser_form_save 无参保存)。 */
 export declare let lastFormFields: FormField[];
-/** 记录一次 aria 快照分配的 ref(整表替换)。 */
-export declare function setPageRefs(page: Page, refs: Map<string, RefEntry>): void;
-/** 查询某个 ref 的定位信息;未注册返回 undefined。 */
-export declare function pageRef(page: Page, ref: string): RefEntry | undefined;
-/** 清空页面的 ref 表(导航/新快照时调用)。 */
-export declare function clearPageRefs(page: Page): void;
-/** 取页面当前完整 ref 表(browser_find 增量续号合并用;无则空 Map)。 */
-export declare function pageRefsOf(page: Page): Map<string, RefEntry>;
-/** 一个历史版本的快照内容(text/aria 两种模式共用同一条版本序列)。 */
-export interface SnapshotEntry {
-    version: number;
-    text: string;
-    aria: string;
-}
-/**
- * F3 增量快照历史:per-page 环形数组保存最近 K 个版本(K = snapshotHistory,
- * 默认 5,上限 20;text 模式 ≤20KB/版本 → 内存上界 ≈100KB/page)。
- * 任意 since ∈ [latest-K+1, latest] 都能 diff;更旧版本回落全量标 stale。
- */
-export interface SnapshotCache {
-    /** 最新版本号(单调递增,不因环形淘汰回退)。 */
-    version: number;
-    /** 最近 K 个版本,按 version 升序;长度 ≤ K。 */
-    history: SnapshotEntry[];
-}
-export declare function snapshotCacheOf(page: Page): SnapshotCache | undefined;
-export declare function setSnapshotCache(page: Page, cache: SnapshotCache): void;
-/** 环形容量钳制(1..20,非法值回落默认 5)。导出供测试。 */
-export declare function snapshotCapacity(k: unknown): number;
-/**
- * 追加一个新版本并淘汰超限的最旧版本(纯逻辑,导出供测试)。
- * cache 为 undefined 时从 version 1 开始;返回新缓存(不修改入参)。
- */
-export declare function pushSnapshotVersion(cache: SnapshotCache | undefined, content: {
-    text: string;
-    aria: string;
-}, capacity: unknown): SnapshotCache;
-/** 按版本号取历史条目;不在环形窗口内(更旧/未知)返回 undefined。 */
-export declare function snapshotVersionEntry(cache: SnapshotCache | undefined, version: number): SnapshotEntry | undefined;
-/** 已保存的录制脚本:name → 步骤数组。 */
-export declare const savedRecordings: Map<string, {
-    steps: ReplayStep[];
-    savedAt: number;
-}>;
-/** 一次工具调用的记录(操作轨迹 / 录制 / 回放共用)。 */
-export interface TestCall {
-    tool: string;
-    args: Record<string, any>;
-    ok: boolean;
-    ms: number;
-    ts: number;
-    error?: string;
-    /** 录制时采集的选择器指纹(回放自愈用;register 包装层异步补齐)。 */
-    meta?: {
-        hint?: SelectorHint;
-        source?: "human";
-    };
-    /** source: "human" 表示这条来自用户在浏览器中的手动操作(混合录制)。 */
-    source?: "human";
-}
-export declare function isRecording(): boolean;
-export declare function startRecording(): void;
-export declare function stopRecording(): TestCall[];
-/** 最近一次完整录制(start→stop)的 buffer;从未录制过返回 null。 */
-export declare function lastRecordingOf(): TestCall[] | null;
-/** 操作轨迹追加(同时写入录制 buffer,排除 record/replay 自身)。返回存入的调用对象(供调用方补 meta)。 */
-export declare function recordCall(call: TestCall): TestCall;
-/** 操作轨迹(按时间倒序,最新在前)。 */
-export declare function testLogOf(): TestCall[];
-export declare function setPauseInstruction(instruction: string): void;
-export declare function clearPauseInstruction(): void;
-export declare function currentPause(): {
-    instruction: string;
-    startedAt: number;
-} | null;
-/** 一次待审批的敏感操作(browser_confirm 等待期间供面板展示与提交决策)。 */
-export interface PendingConfirm {
-    id: string;
-    reason: string;
-    tool?: string;
-    args?: Record<string, any>;
-    startedAt: number;
-    decision?: "allowed" | "denied";
-}
-export declare function setPendingConfirm(entry: PendingConfirm): void;
-export declare function getPendingConfirm(): PendingConfirm | null;
-export declare function clearPendingConfirm(): void;
-/** 面板提交审批决策;id 不匹配(已被新审批取代/超时清理)时返回 false。 */
-export declare function resolveConfirm(id: string, decision: "allowed" | "denied"): boolean;
-export declare function clearTestLog(): void;
-/** live 工具调用开始(register 包装层调用)。 */
-export declare function noteToolStart(): void;
-/** live 工具调用结束(成功/失败都算结束)。 */
-export declare function noteToolEnd(): void;
-/** 当前在途的 live 工具调用数(0 = agent 空闲)。 */
-export declare function activeToolCalls(): number;
-/** window 上的回传 binding 名(须为合法 JS 标识符)。 */
-export declare const HUMAN_BINDING = "__dshBrowserHumanEvent";
-/** agent 即将/刚刚执行了 DOM 操作(register 包装层调用);1.5s 内的页内事件视为工具回声。 */
-export declare function noteAgentAction(): void;
-/** 导出供测试:距上次 agent 操作是否在去重窗口内。 */
-export declare function agentActionRecent(now?: number, windowMs?: number): boolean;
-/**
- * 页内人工操作事件 → 录制步骤(纯函数,导出供测试)。
- * payload 由 installHumanRecorder 生成:{ kind, selector, value?, testid?, role?, name?, id?, text?, tag? }。
- * 无法映射(缺 selector / 未知 kind / 空输入)返回 null。
- */
-export declare function humanEventToStep(payload: unknown): {
-    tool: string;
-    args: Record<string, any>;
-    meta: {
-        hint: SelectorHint;
-        source: "human";
-    };
-} | null;
-/**
- * 页内注入的人工操作监听(addInitScript 序列化;每次导航自动重装)。
- * 监听常驻但 node 侧只在录制中生效,关闭录制等价于"移除"。
- * 只上报可交互元素上的 click 与表单控件的 change,避免逐键噪音。
- * F5 收敛:cssPath 等元素描述来自 walker.ts 单一来源(构建期拼装注入),
- * 不再持有内联副本;payload 字段语义与 v0.3 完全一致。
- */
-export declare const installHumanRecorder: (payload: unknown) => void;
 /** 网络请求/响应记录。 */
 export interface NetworkEntry {
     url: string;
@@ -190,20 +73,4 @@ export declare function pageIdentity(page: Page): Promise<{
 export declare function setLastFormFields(fields: FormField[]): void;
 /** 切换当前 profile。 */
 export declare function setCurrentProfile(name: string): void;
-/** 记录最近一次截图目录(截图工具调用时写入)。 */
-export declare function noteScreenshotDir(dir: string): void;
-/** 定时清扫入口:若已知截图目录则按当前配置清理。 */
-export declare function sweepScreenshotDir(opts: {
-    maxAgeDays?: number;
-    maxCount?: number;
-}): number;
-/**
- * 清理截图目录里的 .png 文件:按修改时间保留最新的 maxCount 个,
- * 并删除超过 maxAgeDays 天的旧文件。只处理目录直属文件,不递归;
- * 单个文件删除失败(被占用等)静默跳过。返回删除数量。
- */
-export declare function cleanupScreenshots(dir: string, opts: {
-    maxAgeDays?: number;
-    maxCount?: number;
-}): number;
 //# sourceMappingURL=session.d.ts.map

package/lib/types/browser/stealth/keyboard.d.ts

@@ -0,0 +1,13 @@
+import type { Page } from "playwright-core";
+export interface TypeOptions {
+    speed?: "slow" | "normal" | "fast";
+}
+/**
+ * 基于 Box-Muller 变换的高斯分布随机数生成器
+ */
+export declare function gaussianRandom(mean?: number, stdev?: number, min?: number, max?: number): number;
+/**
+ * 拟人化敲击键盘输入文本
+ */
+export declare function humanType(page: Page, text: string, options?: TypeOptions): Promise<void>;
+//# sourceMappingURL=keyboard.d.ts.map

package/lib/types/browser/stealth/mouse.d.ts

@@ -0,0 +1,28 @@
+import type { Locator, Page } from "playwright-core";
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface MouseOptions {
+    speed?: "slow" | "normal" | "fast";
+    steps?: number;
+}
+/**
+ * 获取当前页面记录的鼠标坐标，若未记录则默认返回初始点 (100, 100)
+ */
+export declare function getMousePosition(page: Page): Point;
+export declare function setMousePosition(page: Page, pos: Point): void;
+/**
+ * 生成起点到终点的三次贝塞尔平滑轨迹点序列
+ * B(t) = (1-t)^3 * P0 + 3(1-t)^2 * t * P1 + 3(1-t) * t^2 * P2 + t^3 * P3
+ */
+export declare function generateBezierPath(start: Point, end: Point, stepCount?: number): Point[];
+/**
+ * 拟人化平滑移动鼠标至指定像素坐标
+ */
+export declare function humanMove(page: Page, target: Point, options?: MouseOptions): Promise<void>;
+/**
+ * 拟人化微偏随机点击元素
+ */
+export declare function humanClick(page: Page, locator: Locator, options?: MouseOptions): Promise<boolean>;
+//# sourceMappingURL=mouse.d.ts.map

package/lib/types/browser/tools/collaboration.d.ts

@@ -0,0 +1,73 @@
+import type { Page } from "playwright-core";
+import type { BrowserConfig } from "../types.js";
+/**
+ * 操作预告高亮:agent 即将 click/type/select/press 的元素在页面上琥珀色描边
+ * ~1.5 秒。异步不阻塞(fire-and-forget,任何失败静默),不影响操作时序。
+ */
+export declare function previewHighlight(page: Page | null, selector: string, label: string): void;
+/**
+ * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
+ * 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
+ * successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
+ * 超时返回 loggedIn:false(不抛错)。
+ */
+export declare function waitForLoginTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    loggedIn: boolean;
+}>;
+/**
+ * 人工接管等待(通用版 wait_for_login):agent 把控制权交还给用户(验证码 /
+ * 二次确认 / 人工复核等)。instruction 会显示在实时画面面板;完成条件三选一:
+ * successSelector(元素出现)/ successUrl(URL 正则)/ 两者都不给则以
+ * URL 变化或页面内容签名变化视为完成。轮询间隔 2 秒,超时返回 completed:false
+ * (不抛错)。导出 runPauseOnPage 供测试注入 fake page。
+ */
+export declare function runPauseOnPage(page: Page, args: Record<string, any>): Promise<{
+    completed: boolean;
+    waitedMs: number;
+    detail: string;
+}>;
+/** 人工接管等待工具入口(缺 instruction 在启动浏览器前即校验,失败更快)。 */
+export declare function pauseForHumanTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    completed: boolean;
+    status: "completed" | "timedOut";
+    instruction: string;
+    detail: string;
+    waitedMs: number;
+}>;
+/**
+ * 敏感操作审批:agent 在执行提交/删除/支付类动作前调用,把审批请求推到实时
+ * 画面面板,挂起等待用户点「允许/拒绝」。超时视为拒绝(fail-closed)。
+ * 用户允许时返回 { decision: "allowed", ... };拒绝/超时**抛错**(消息含原因),
+ * 使 live 调用与 replay/batch 步骤统一按失败处理,agent 不应继续敏感动作。
+ * 决策通过 session.resolveConfirm(面板 POST)写入。
+ */
+export declare function confirmTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    decision: "allowed";
+    id: string;
+    reason: string;
+    waitedMs: number;
+    detail: string;
+}>;
+/**
+ * 面板点选教学工具:等待用户在实时画面大图上点选目标元素,返回其统一描述、
+ * 稳定 selector、选择器指纹(与录制自愈 healCandidates 兼容)与可直接使用
+ * 的 ref。坐标换算:cssX = imgPx * viewportWidth / imgW / pageScaleFactor(elementFromPoint 收
+ * 视口相对坐标,无需 scroll 换算)。
+ * 导出 pickToolOnPage 供测试注入 fake page。
+ */
+export declare function pickToolOnPage(page: Page, config: BrowserConfig, args: Record<string, any>): Promise<Record<string, any>>;
+/** 面板点选教学工具入口。 */
+export declare function pickTool(config: BrowserConfig, args: Record<string, any>): Promise<Record<string, any>>;
+import { sensitiveHits, DEFAULT_SENSITIVE_PATTERNS, DEFAULT_SENSITIVE_TOOLS, type SensitiveDesc } from "../policy/engine.js";
+export { sensitiveHits, DEFAULT_SENSITIVE_PATTERNS, DEFAULT_SENSITIVE_TOOLS, type SensitiveDesc };
+/**
+ * 策略引擎审批闸: 命中 auto 级别策略时经 confirmTool 弹审批等待用户决策,
+ * 拒绝/超时抛错(调用方该步失败), 允许则返回继续执行原工具。
+ * page 参数仅供测试注入; 缺省取当前活动页。
+ */
+export declare function confirmGate(config: BrowserConfig, tool: string, args: Record<string, any>, page?: Page | null): Promise<void>;
+//# sourceMappingURL=collaboration.d.ts.map

package/lib/types/browser/tools/common.d.ts

@@ -0,0 +1,67 @@
+/** 组件库下拉框的可见选项选择器并集 (基于通用 WAI-ARIA 与主流组件库规范)。 */
+export declare const DROPDOWN_OPTION_SELECTOR: string;
+/** 读取 PNG 文件头(IHDR)中的宽高,不解码像素(导出供测试)。 */
+export declare function pngSize(buf: Buffer): {
+    width: number;
+    height: number;
+};
+/** 按缩放比例换算 mask 矩形(导出供测试;与页内比对共用同一套坐标语义)。 */
+export declare function scaleRects(rects: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}[], scale: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}[];
+/**
+ * 快照文本压缩(导出供测试):
+ *   - 去掉首尾空白行;
+ *   - 连续空白行折叠为 1 行;
+ *   - 连续重复的非空行(表格空单元格/占位行产生的噪音)折叠为「首行 + …(重复 N 行)」。
+ * 只折叠完全相同的相邻行,不重排、不删改非重复内容。
+ */
+export declare function compressText(text: string): string;
+/** 最长公共子串长度(小写比较;零依赖,导出供测试)。 */
+export declare function lcsScore(a: string, b: string): number;
+/** 零命中时按相似度挑 top5 候选(导出供测试)。 */
+export declare function topSuggestions(query: string, candidates: {
+    role: string;
+    name: string;
+}[], count?: number): {
+    role: string;
+    name: string;
+    score: number;
+}[];
+/**
+ * 行级 diff:掐掉公共前缀/后缀,返回变化区。导出供测试。
+ * 全等返回 { unchanged: true };否则 changedFrom 为新文本中变化区首行(1 起)。
+ */
+export declare function diffLines(oldText: string, newText: string): {
+    unchanged: boolean;
+    changedFrom?: number;
+    lines?: string[];
+    removed?: number;
+};
+/** 给本身无超时的 Playwright 调用(evaluate/allTextContents)加有界保护,防页面主线程忙时无限挂起。 */
+export declare function withTimeout<T>(p: Promise<T>, ms: number, what: string): Promise<T>;
+/**
+ * 防御性解码 eval 脚本:模型/人工偶发把脚本 JSON.stringify 一次再传
+ * (脚本以 \" 开头、换行变字面 \\n),回放/录制链路不纠错会导致语法错误。
+ * 识别条件:字符串以引号包裹且含反斜杠转义,且 JSON.parse 结果仍是字符串。
+ * 无法解析或语义不变场景原样返回(裸字符串字面量如 "hello" 不含转义,不受影响)。
+ */
+export declare function unwrapDoubleEncodedScript(script: string): {
+    script: string;
+    unwrapped: boolean;
+};
+/** 工作区内落盘路径解析(拒绝穿越到工作区之外)。 */
+export declare function workspaceFilePath(cwd: string, file: string): string;
+/**
+ * 规则化抽取:fields 定义抽取结构,next 选择器驱动翻页(maxPages 上限),
+ * 行数超 maxRows 截断;format/file 控制序列化与落盘(json/csv/jsonl/markdown)。
+ */
+//# sourceMappingURL=common.d.ts.map

package/lib/types/browser/tools/doctor.d.ts

@@ -0,0 +1,31 @@
+import type { ToolRunContext } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+/** 一项诊断结果(ok=false 时附 advice 修复建议)。导出供测试。 */
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    advice?: string;
+}
+export declare function setDoctorProbe(fn: ((basePath: string) => Promise<{
+    ok: boolean;
+    detail: string;
+    advice?: string;
+}>) | null): void;
+/** 目录可写性检查(mkdir + 写探针文件 + 删除)。导出供测试。 */
+export declare function checkWritableDir(dir: string): {
+    ok: boolean;
+    detail: string;
+};
+/** 可执行文件存在性检查(executablePath 显式配置用)。导出供测试。 */
+export declare function checkExecutable(path: string): DoctorCheck;
+/** 一次性健康诊断:不启动浏览器,只做静态/本地检查。 */
+export declare function doctorTool(config: BrowserConfig, _args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    checks: DoctorCheck[];
+    summary: {
+        ok: boolean;
+        passed: number;
+        failed: number;
+    };
+}>;
+//# sourceMappingURL=doctor.d.ts.map

package/lib/types/browser/tools/extract.d.ts

@@ -0,0 +1,92 @@
+import type { ToolRunContext } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export interface ExtractField {
+    name: string;
+    selector: string;
+    attr?: string;
+    multiple?: boolean;
+    fields?: ExtractField[];
+}
+/**
+ * 把单页抽取结果规整为行数组:恰好一个顶层 multiple 字段时,其数组即行
+ * (行内嵌套对象为行,标量包装成 { [name]: value });否则整页算一行。
+ */
+export declare function rowsOfExtract(result: Record<string, any>, fields: ExtractField[]): Record<string, any>[];
+/** suggest 采集的表格单元格信息(页内采集,纯函数消费)。 */
+export interface SuggestCell {
+    text: string;
+    href?: string;
+    src?: string;
+}
+/** suggest 页内分析结果(自包含 injectWalker 注入采集)。 */
+export interface SuggestAnalysis {
+    ok: boolean;
+    /** table: 表格行模式;list: 重复卡片/列表项模式。 */
+    kind?: "table" | "list";
+    /** 行/卡片选择器(抽取 fields 顶层的 multiple selector)。 */
+    rowSelector?: string;
+    headerTexts?: string[];
+    cells?: SuggestCell[];
+    item?: SuggestCell;
+    reason?: string;
+    overview?: {
+        links: number;
+        images: number;
+        buttons: number;
+        headings: number;
+        rows: number;
+        textChars: number;
+    };
+}
+/** 字段名净化:空白→下划线,限长 30,空回落 col_N。导出供测试。 */
+export declare function suggestFieldName(header: string | undefined, index: number): string;
+/**
+ * 纯逻辑:由表头与首行单元格特征推断表格 fields(单元格文本/链接 href/图片 src)。
+ * 返回可直接放进 rows.fields 的嵌套字段数组。导出供测试。
+ */
+export declare function fieldsFromCells(headerTexts: string[], cells: SuggestCell[]): ExtractField[];
+/**
+ * 纯逻辑:由首条卡片信息推断列表 fields(项文本/链接/图片)。
+ * 文本取第一个子元素(项自身无法用 querySelector 自选)。导出供测试。
+ */
+export declare function fieldsFromCard(item: SuggestCell): ExtractField[];
+/** 纯逻辑:由 fields 与单元格样本拼出首行样例(与抽取输出同构;按 td 序号对位)。导出供测试。 */
+export declare function sampleOfFields(fields: ExtractField[], cells: SuggestCell[]): Record<string, unknown>;
+/**
+ * suggest 汇总(纯逻辑):由页内分析结果组装「可直接交给抽取模式」的顶层 fields
+ * (单个 multiple rows 字段 + 行内嵌套字段)与样本。推断失败原样返回。导出供测试。
+ */
+export declare function suggestWrap(analysis: SuggestAnalysis): {
+    suggested: boolean;
+    kind?: "table" | "list";
+    rowSelector?: string;
+    headerTexts?: string[];
+    fields?: ExtractField[];
+    sample?: Record<string, unknown>;
+    reason?: string;
+    overview?: SuggestAnalysis["overview"];
+};
+export declare function extractTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    url: string;
+    title: string;
+    suggested: boolean;
+    kind?: "table" | "list";
+    rowSelector?: string;
+    headerTexts?: string[];
+    fields?: ExtractField[];
+    sample?: Record<string, unknown>;
+    reason?: string;
+    overview?: SuggestAnalysis["overview"];
+    action: string;
+} | {
+    url: string;
+    title: string;
+    file?: string | undefined;
+    bytes?: number | undefined;
+    truncated: boolean;
+    rows: Record<string, any>[];
+    count: number;
+    pages: number;
+    format: string;
+}>;
+//# sourceMappingURL=extract.d.ts.map

package/lib/types/browser/tools/inspection.d.ts

@@ -0,0 +1,93 @@
+import type { ToolRunContext } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+import { assignRefs as assignRefsImpl } from "../session/cache.js";
+export declare const assignRefs: typeof assignRefsImpl;
+/**
+ * 页内语义扫描已收敛到 session/semantic.ts 的 scanInteractive(walker 单一
+ * 来源 + 打分排序),browser_find 与 what 语义定位共用同一匹配语义。
+ */
+/**
+ * 语义元素定位:按名称(或 id/data-testid)在可交互元素中查找,只返回命中的
+ * ref + 区域上下文,不输出全量 aria 树 —— 大页面定位单个目标时 token 开销
+ * 远小于 browser_snapshot { mode: "aria" }。返回的 ref 可直接用于
+ * click/type/select/press。零命中不抛错,附最相近候选供二次定位。
+ */
+export declare function findTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    scanned: number;
+    url: string;
+    title: string;
+    truncated?: true | undefined;
+    suggestions?: {
+        role: string;
+        name: string;
+        score: number;
+    }[] | undefined;
+    found: number;
+    matches: {
+        ref: string;
+        role: string;
+        name: string;
+        ancestors: string[] | undefined;
+    }[];
+}>;
+export declare function snapshotTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    url: string;
+    title: string;
+    scope?: string | undefined;
+    unchanged: boolean;
+    contentVersion: number;
+} | {
+    url: string;
+    title: string;
+    truncated: boolean;
+    scope?: string | undefined;
+    diff: boolean;
+    contentVersion: number;
+    changedFrom: number | undefined;
+    removed: number | undefined;
+} | {
+    url: string;
+    title: string;
+    truncated: boolean;
+    scope?: string | undefined;
+    stale?: boolean | undefined;
+    contentVersion: number;
+}>;
+export declare function screenshotTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
+    path: string;
+    bytes: number;
+    width: number;
+    height: number;
+    baseline: string;
+} | {
+    som?: boolean | undefined;
+    somMarks?: {
+        id: number;
+        role: string;
+        name: string;
+    }[] | undefined;
+    path: string;
+    bytes: number;
+    width: number;
+    height: number;
+    baseline?: undefined;
+}>;
+/**
+ * 语义定位零命中时的 SoM 兜底截图(clickTool 失败路径调用,somFallback 配置
+ * 控制):截一张带标徽的视口图,供多模态模型看图后 browser_click { mark: N }
+ * 一次往返完成定位。无活动页面或截图失败返回 null(不放大错误)。
+ */
+export declare function somFallbackShot(config: BrowserConfig, exec?: ToolRunContext): Promise<{
+    screenshot: string;
+    marks: Array<{
+        id: number;
+        role: string;
+        name: string;
+    }>;
+} | null>;
+export declare function elementsTool(config: BrowserConfig, args: Record<string, any>): Promise<{
+    count: number;
+    elements: Record<string, unknown>[];
+    dropdownOptions: string[];
+}>;
+//# sourceMappingURL=inspection.d.ts.map