dsh-browser-view 0.7.0 → 0.7.4

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

@@ -35,6 +35,7 @@ export declare const scanInteractive: (payload: {
     scope: string;
     limit: number;
     dialogSelector?: string;
+    preferredRoles?: string[];
 }) => {
     matches: SemanticMatch[];
     candidates: {
@@ -65,6 +66,7 @@ export declare function resolveSemanticTarget(page: Page, what: string, opts?: {
     scope?: string;
     limit?: number;
     maxRefs?: number;
+    preferredRoles?: string[];
 }): Promise<TargetResolution | SemanticMiss>;
 /**
  * 全量可交互元素扫描(SPA ref 重锚定的数据源):返回页面(或 scope 内)全部

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

@@ -10,7 +10,9 @@ export declare function buildFlexibleTextPattern(text: string): RegExp;
  * 自动识别 selector 或 ref；若 ref 标记位于子 Frame，自动绑定到对应子 Frame 上下文。
  * 具备路径防漂移校验与 getByRole 自愈降级能力。
  */
-export declare function resolveTargetLocator(page: Page, args: Record<string, any>): Promise<TargetResolution>;
+export declare function resolveTargetLocator(page: Page, args: Record<string, any>, opts?: {
+    preferredRoles?: string[];
+}): Promise<TargetResolution>;
 /** 兼容旧版签名的目标定位快捷方式 */
 export declare function targetLocator(page: Page, args: Record<string, any>): Promise<Locator>;
 //# sourceMappingURL=target.d.ts.map

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

@@ -49,7 +49,9 @@ export interface NamedContext {
     createdAt: number;
 }
 export declare function namedContextsOf(): Map<string, NamedContext>;
-/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。 */
+/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。
+ * 唯一注册路径:同时挂 close 监听幂等摘除外部关闭的页(否则僵尸句柄会永久占用
+ * activeId,所有工具连报 "Target page...closed" 而 tabs list 仍显示存活)。 */
 export declare function registerTabPage(state: ProfileState, page: Page): number;
 /** 新建一个页面(当前 profile 会话未启动时先启动)。 */
 export declare function newPage(config: BrowserConfig): Promise<Page>;
@@ -57,8 +59,9 @@ export declare function newPage(config: BrowserConfig): Promise<Page>;
 export declare function getPage(config: BrowserConfig): Promise<Page>;
 /** 活动页面(可能为 null,不触发启动)。 */
 export declare function activePage(): Page | null;
-/** 投影当前 profile 的标签列表。 */
+/** 投影当前 profile 的标签列表(先摘除僵尸页,附注册时间)。 */
 export declare function tabList(): Promise<{
+    createdAt?: number | undefined;
     id: number;
     url: string;
     title: string;

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

@@ -5,16 +5,38 @@ import type { BrowserConfig } from "../types.js";
  * ~1.5 秒。异步不阻塞(fire-and-forget,任何失败静默),不影响操作时序。
  */
 export declare function previewHighlight(page: Page | null, selector: string, label: string): void;
+/**
+ * 常见认证/登录相关的 URL 特征正则，用于防止跳板页提前误判。
+ */
+export declare const AUTH_URL_PATTERN: RegExp;
+export interface WaitForLoginResult {
+    loggedIn: boolean;
+    waitedMs: number;
+    detail: string;
+    targetPage: Page;
+}
+/**
+ * 等待人工登录底层执行(独立导出供测试注入 fake page)。
+ * 协同机制:
+ * 1. 挂起等待期间置入 instruction 至实时画面面板(setPauseInstruction),结束后统一清理;
+ * 2. 存活标签感知:感知 context 内所有存活页面,原标签关闭时自动迁移至存活页,新标签出现时通知外层注册;
+ * 3. 稳态判定:
+ *    - 显式 successSelector / successUrl 优先;
+ *    - 缺省时,检测 URL 离开登录页(非 AUTH_URL_PATTERN)、登录密码框消除、或 SPA 内容签名稳态变化,防范跳板页误判与 SPA 弹窗漏判。
+ */
+export declare function runWaitForLoginOnPage(initialPage: Page, args: Record<string, any>, onNewPageDetected?: (page: Page) => void): Promise<WaitForLoginResult>;
 /**
  * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
- * 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
- * successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
- * 超时返回 loggedIn:false(不抛错)。
+ * 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。支持 instruction 提示语
+ * 与右下角实时画面面板联动显示横幅,支持多标签感知与 SPA 签名自适应判定。
+ * 超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。
  */
 export declare function waitForLoginTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
     loggedIn: boolean;
+    waitedMs: number;
+    detail: string;
 }>;
 /**
  * 人工接管等待(通用版 wait_for_login):agent 把控制权交还给用户(验证码 /

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

@@ -7,6 +7,7 @@ export declare function isBotSensitiveUrl(url: string): boolean;
 export declare function clickTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
     url: string;
     title: string;
+    viaBridge?: boolean | undefined;
     effectHint?: string | undefined;
     clicked: string;
     effect: {
@@ -23,6 +24,7 @@ export declare function clickTool(config: BrowserConfig, args: Record<string, an
 } | {
     url: string;
     title: string;
+    viaBridge?: boolean | undefined;
     clicked: string;
 }>;
 export declare function typeTool(config: BrowserConfig, args: Record<string, any>): Promise<{

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

@@ -1,5 +1,6 @@
 import type { BrowserConfig } from "../types.js";
 export declare function openTool(configOrArgs: BrowserConfig | Record<string, any>, maybeArgs?: Record<string, any>): Promise<{
+    recovered?: string | undefined;
     url: string;
     title: string;
     status: string;
@@ -90,6 +91,7 @@ export declare function statusTool(): Promise<{
 export declare function tabsTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     action: any;
     tabs: {
+        createdAt?: number | undefined;
         id: number;
         url: string;
         title: string;
@@ -104,11 +106,12 @@ export declare function tabsTool(config: BrowserConfig, args: Record<string, any
         title: string;
     };
     tabs: {
+        createdAt?: number | undefined;
         id: number;
         url: string;
         title: string;
     }[];
-    activeId: number;
+    activeId: number | null;
 }>;
 export declare function profileTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     current: string;

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

@@ -9,12 +9,13 @@ export declare function waitTool(config: BrowserConfig, args: Record<string, any
 /**
  * 条件检查引擎(测试原语共用)。
  *
- * cond 支持四类(每类内部互斥,取第一个存在的字段):
+ * cond 支持六类(每类内部互斥,取第一个存在的字段):
  *   { selector: "#btn", state: "visible|hidden|attached|detached" }  元素状态(默认 visible)
  *   { url: "正则字符串" }                                            当前 URL 匹配
  *   { text: "子串" }                                                  body 可见文本包含
  *   { count: { selector, op: "eq|gt|gte|lt|lte", value: n } }         元素数量比较
  *   { eval: "JS 表达式" }                                            表达式求值 truthy
+ *   { bridge: { method, args?, expect?/expectContains? } }           页内调用 __DSH_BRIDGE__ 方法并断言返回
  */
 export type TestCondition = Record<string, any>;
 /** 单次检查:返回 { ok, detail }。不抛错,失败时 detail 给出原因。 */
@@ -56,6 +57,7 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     waitMs?: undefined;
     stats?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 } | {
     matched: import("../session.js").NetworkEntry;
     waitMs: number;
@@ -63,6 +65,7 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     entries?: undefined;
     stats?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 } | {
     stats: {
         host: string;
@@ -76,13 +79,31 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     matched?: undefined;
     waitMs?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 } | {
     failed: import("../session.js").NetworkEntry[];
+    suggestions: string[];
     cleared?: undefined;
     entries?: undefined;
     matched?: undefined;
     waitMs?: undefined;
     stats?: undefined;
+} | {
+    failed: import("../session.js").NetworkEntry[];
+    cleared?: undefined;
+    entries?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    stats?: undefined;
+    suggestions?: undefined;
+} | {
+    entries: import("../session.js").NetworkEntry[];
+    suggestions: string[];
+    cleared?: undefined;
+    matched?: undefined;
+    waitMs?: undefined;
+    stats?: undefined;
+    failed?: undefined;
 } | {
     entries: import("../session.js").NetworkEntry[];
     cleared?: undefined;
@@ -90,5 +111,6 @@ export declare function networkTool(configOrArgs?: Record<string, any>, maybeArg
     waitMs?: undefined;
     stats?: undefined;
     failed?: undefined;
+    suggestions?: undefined;
 }>;
 //# sourceMappingURL=testing.d.ts.map

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

@@ -92,6 +92,10 @@ export interface ProfileState {
     activeId: number | null;
     counter: number;
     channel?: string;
+    /** 标签元数据(id → createdAt);随 pages 同步增删,僵尸标签治理用。 */
+    tabMeta?: Map<number, {
+        createdAt: number;
+    }>;
 }
 /** 一次页面下载的记录。 */
 export interface DownloadEntry {
@@ -173,6 +177,8 @@ export interface TargetResolution {
     visibleCount?: number;
     /** 语义定位的备选目标(按打分次序,最多 2 个);点击效果验证无变化时自动换选。 */
     alternates?: Locator[];
+    /** 经 window.__DSH_BRIDGE__.resolveActionTarget 兜底命中(vite-plugin-dsh-bridge 反哺)。 */
+    viaBridge?: boolean;
 }
 /** 录制时采集的选择器指纹(回放自愈的降级候选来源)。 */
 export interface SelectorHint {

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

@@ -20,6 +20,7 @@ declare function __walkerCore(): {
     };
     composedParent: (el: Element) => Element | null;
     deepChildren: (el: Element) => Element[];
+    isProbablyClickable: (el: Element) => boolean;
 };
 /** walker 核心注入后暴露给 entry 的 API(类型层)。 */
 export type WalkerApi = ReturnType<typeof __walkerCore>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.7.0",
+  "version": "0.7.4",
   "description": "DSH 插件:共享 Playwright 浏览器自动化(38 个 browser_* 工具,含 what 意图语义定位(一次调用替代快照→查找→点击)、SoM 标徽看图点击与零命中截图兜底、SPA ref 软失效重锚定、open Shadow DOM 组合树穿透、跨 Frame/IFrame 定位、视口感知动态快照、批量表单智能填充、点击效果验证与定位失败遥测、Playwright 规范代码导出、批处理、视觉回归、选择器自愈、增量快照)+ 人机协作(面板点选教学 browser_pick_element、人工接管等待、敏感操作审批硬拦截、人机混合录制、面板一键重跑)+ CDP 流式推流、拟人化轨迹与高斯击键、全景时光机、企业富控件矩阵。仅依赖 playwright-core。",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,6 +34,7 @@
     "test:enterprise": "tsx scripts/test-dev-server-enterprise.ts",
     "test:energy": "tsx scripts/test-dev-server-energy.ts",
     "test:shadow": "tsx scripts/test-dev-server-shadow.ts",
+    "test:span": "tsx scripts/test-dev-server-clickable-span.ts",
     "test:pick": "tsx scripts/test-panel-pick.ts",
     "dev:server": "tsx scripts/dev-server.ts",
     "verify": "npm run typecheck && npm run lint && npm run test && npm run build",