dsh-browser-view 0.8.0 → 0.8.1

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

@@ -1,12 +1,29 @@
 import type { Locator, Page } from "playwright-core";
+/** 精确层 = 标准层 + 库精确层(ui-library 注册表单一来源,新增 UI 库 = 追加 spec)。 */
+export declare const DIALOG_PRECISE_SELECTORS: string;
+/** 通用模糊层(未注册库兜底):子串词 + :not() 排除子节点。 */
+export declare const DIALOG_FUZZY_SELECTORS: string;
 /**
- * 通用活动弹窗/对话框/抽屉选择器列表
- * 基于 W3C WAI-ARIA 规范 (role="dialog", aria-modal="true") 与现代 Web 通用命名规范
+ * 历史并集 = 精确层 + 模糊层。semantic.ts 弹窗上下文检测与 getActiveDialog 的
+ * domOrder 兜底消费(行为与抽取前的并集等价)。
  */
 export declare const ACTIVE_DIALOG_SELECTORS: string;
+/** 活动弹窗解析结果:locator + 实际仲裁通道(诊断线索)。 */
+export interface ActiveDialog {
+    locator: Locator;
+    via: "zIndex" | "domOrder";
+    z?: number;
+    tier?: "precise" | "fuzzy";
+}
 /**
- * 获取当前页面上处于活动状态的最顶层弹窗容器 (Locator)
+ * 获取当前页面上处于活动状态的最顶层弹窗容器;无弹窗返回 null。
+ * ① 快速通道——并集零命中(绝大多数无弹窗的工具调用)直接返回 null,与旧行为
+ * 「空 locator + 下游 count 0」等价,零额外 evaluate 往返;
+ * ② 有弹窗时走分层选择器 + 页内 z-index/可见性仲裁(walker pickTopDialog,
+ * 页内逻辑单一来源),单次 round-trip;
+ * ③ evaluate 失败(极端 CSP/销毁竞态)或复核计数为 0 时回退文档序 last()
+ * 旧行为并标 via: "domOrder",不阻断主流程。
  */
-export declare function getActiveDialog(page: Page): Locator;
+export declare function getActiveDialog(page: Page): Promise<ActiveDialog | null>;
 export declare function getActiveDialogSelectors(): string;
 //# sourceMappingURL=dialog.d.ts.map

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

@@ -1,3 +1,13 @@
-import type { Page } from "playwright-core";
-export declare function dragAndDropHelper(page: Page, sourceSelector: string, targetSelector: string): Promise<boolean>;
+import type { Locator, Page } from "playwright-core";
+export type DragChannel = "dragTo" | "mouse";
+/**
+ * 核心:在两个已解析的 Locator 之间执行拖拽。
+ * 优先 Playwright dragTo(覆盖 HTML5 DnD 与多数组件库);
+ * 失败或调用方指定 preferMouse(如跨 Frame,dragTo 的已知限制)时
+ * 降级为物理鼠标序列。返回实际使用的通道。失败抛错(带可定位的诊断信息)。
+ */
+export declare function dragAndDropLocators(page: Page, source: Locator, target: Locator, opts?: {
+    timeoutMs?: number;
+    preferMouse?: boolean;
+}): Promise<DragChannel>;
 //# sourceMappingURL=drag.d.ts.map

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

@@ -1,6 +1,7 @@
 export * from "./types.js";
 export * from "./dom.js";
 export * from "./dialog.js";
+export * from "./ui-library.js";
 export * from "./select.js";
 export * from "./virtual.js";
 export * from "./editor.js";

package/lib/types/browser/primitives/ui-library.d.ts

@@ -0,0 +1,72 @@
+export declare const GENERIC: {
+    readonly dialogWords: readonly ["modal", "drawer", "dialog"];
+    readonly dialogExcludedParts: readonly ["mask", "wrap", "root", "header", "footer", "title", "close", "body", "btn"];
+    /** 下拉触发器内部件(点它展开) */
+    readonly dropdownTriggerParts: "[class*='selector'], [role='combobox']";
+    /** 下拉浮层容器的子串词(portal 挂载的面板) */
+    readonly dropdownFloatWords: readonly ["select-dropdown", "popper"];
+    /** 通用下拉选项行(select 状态机消费;库精确层另补) */
+    readonly dropdownOptionRows: "[class*='item-option']:not([class*='empty']), [class*='select-dropdown'] li:not([class*='empty'])";
+    /** 可交互「选项」枚举(elements 工具下拉选项清单消费) */
+    readonly dropdownOptionEnumeration: string;
+    /** 多选标签清除按钮 */
+    readonly dropdownClearButtons: "[class*='clear'], [aria-label*='clear']";
+    /** 多选标签移除按钮 */
+    readonly dropdownRemoveButtons: "[class*='remove'], [class*='close'], [aria-label*='close']";
+    /** 空态指示器 */
+    readonly emptyStates: "[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']";
+    /** 表单项容器(宽松:BEM/-item 子串 + group + form 元素;label 反查主用) */
+    readonly formItemContainers: "[class*='form-item'], [class*='form__item'], [role='group'], form, .form-group";
+    /**
+     * 表单项容器(严格:带分隔符前缀,避免 platform-item 之类无关门类误命中;
+     * elements 工具页内 labelOf 消费)
+     */
+    readonly formItemContainersStrict: "[class*='-form-item'], [class*='__form-item'], form, .form-group";
+    /** 表单项宿主判定(目标是否处于表单语境;含 label 本身) */
+    readonly formItemHosts: "label, [class*='form-item'], [class*='form__item'], [class*='form-group']";
+    /** 表单项 label(dom 原语 label 反查消费) */
+    readonly formItemLabels: "[class*='form-item-label'], [class*='form-item__label'], [class*='label'], label";
+    /** 表单 label(简化集;elements 工具页内 labelOf 消费) */
+    readonly formLabelSimple: "[class*='label'], label";
+};
+export interface UILibrarySpec {
+    /** 库标识(诊断与文档)。 */
+    name: string;
+    /** 模态弹窗容器(参与顶层仲裁的容器级节点)。 */
+    modalContainers: string[];
+    /** 抽屉容器。 */
+    drawerContainers: string[];
+    /** 下拉浮层容器(portal 挂载的下拉面板)。 */
+    dropdownContainers: string[];
+    /** 下拉选项行。 */
+    dropdownOptions: string[];
+}
+/**
+ * 注册新库(示例:naive-ui):
+ *   const naiveUi: UILibrarySpec = {
+ *     name: "naive-ui",
+ *     modalContainers: [".n-modal-container"],
+ *     drawerContainers: [".n-drawer-container"],
+ *     dropdownContainers: [".n-base-select-menu"],
+ *     dropdownOptions: [".n-base-select-option"],
+ *   };
+ * 追加到 UI_LIBRARIES 即可,弹窗顶层仲裁与下拉浮层发现自动获得该库精确层支持;
+ * 未注册的库仍由通用子串层兜底。配套要求:补一个该库真页面的 e2e
+ * (playground 模式照抄 test:enterprise),防止想当然的类名污染仲裁。
+ */
+export declare const UI_LIBRARIES: readonly UILibrarySpec[];
+/** 弹窗/抽屉容器(库精确层原料,未加 display:none 预过滤)。 */
+export declare function dialogContainersOf(libs?: readonly UILibrarySpec[]): string[];
+/** 弹窗模糊层选择器串:子串词 + 子节点排除(:not 双命名)+ display:none 预过滤。 */
+export declare function composeDialogFuzzy(words?: readonly string[], excludedParts?: readonly string[]): string;
+/** 下拉浮层容器选择器列表(库精确层 + 通用子串层,均带 display:none 预过滤)。 */
+export declare function dropdownFloatSelectors(libs?: readonly UILibrarySpec[]): string[];
+/** 下拉选项行选择器列表(标准层 role=option 由消费方自带 + 库精确层 + 通用子串层)。 */
+export declare function dropdownOptionRowsOf(libs?: readonly UILibrarySpec[]): string[];
+/** 预组合聚合常量(消费方直接 import)。 */
+export declare const LIBRARY_DIALOG_CONTAINERS: readonly string[];
+export declare const LIBRARY_DROPDOWN_CONTAINERS: readonly string[];
+export declare const LIBRARY_DROPDOWN_OPTIONS: readonly string[];
+/** walker 核心源里应包含的表单词表 token(drift-guard 测试用,见 test/ui-library.test.ts)。 */
+export declare const WALKER_FORM_TOKENS: readonly string[];
+//# sourceMappingURL=ui-library.d.ts.map

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

@@ -100,4 +100,16 @@ export declare function pushSnapshotVersion(cache: SnapshotCache | undefined, co
 }, capacity: unknown): SnapshotCache;
 /** 按版本号取历史条目;不在环形窗口内(更旧/未知)返回 undefined。 */
 export declare function snapshotVersionEntry(cache: SnapshotCache | undefined, version: number): SnapshotEntry | undefined;
+/** 记录"最近一次成功操作"的导航代际(pageIdentity 打点,零成本)。 */
+export declare function markStableNav(page: Page): void;
+/** 当前代际距最近成功操作代际的差值(≥1 = 期间发生过导航)。 */
+export declare function navSinceStable(page: Page): number;
+export interface ExternalNavNote {
+    url: string;
+    at: number;
+}
+/** 记录一次疑似外部导航(非工具窗口内发生的 framenavigated)。 */
+export declare function noteExternalNav(page: Page, url: string): void;
+/** 读取并清空疑似外部导航记录,拼装 warning 文案;无记录返回 undefined。 */
+export declare function drainExternalNavWarning(page: Page): string | undefined;
 //# sourceMappingURL=cache.d.ts.map

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

@@ -1,4 +1,4 @@
-/** 组件库下拉框的可见选项选择器并集 (基于通用 WAI-ARIA 与主流组件库规范)。 */
+/** 组件库下拉框的可见选项枚举(ui-library 注册表单一来源,值与抽取前等价)。 */
 export declare const DROPDOWN_OPTION_SELECTOR: string;
 /** 读取 PNG 文件头(IHDR)中的宽高,不解码像素(导出供测试)。 */
 export declare function pngSize(buf: Buffer): {
@@ -60,8 +60,21 @@ export declare function unwrapDoubleEncodedScript(script: string): {
 };
 /** 工作区内落盘路径解析(拒绝穿越到工作区之外)。 */
 export declare function workspaceFilePath(cwd: string, file: string): string;
+export type EvalWrapMode = "expression" | "statements-auto-return" | "statements";
+export interface EvalWrapResult {
+    code: string;
+    mode: EvalWrapMode;
+}
+/**
+ * 把 eval 脚本包装成可直接交给 page.evaluate 的代码串,并标明实际执行形态。
+ * 语法非法时在 Node 侧抛出引擎原始错误(消息与页内 V8 同源,提前暴露)。
+ */
+export declare function buildEvalScript(script: string): EvalWrapResult;
 /**
  * 规则化抽取:fields 定义抽取结构,next 选择器驱动翻页(maxPages 上限),
  * 行数超 maxRows 截断;format/file 控制序列化与落盘(json/csv/jsonl/markdown)。
  */
+export declare function assertExpectedUrl(page: {
+    url(): string;
+}, expectUrl: unknown, action: string): Promise<void>;
 //# sourceMappingURL=common.d.ts.map

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

@@ -2,12 +2,14 @@ import type { ToolRunContext } from "../../lib/types.js";
 import type { BrowserConfig } from "../types.js";
 import { targetLocator, resolveTargetLocator } from "../session.js";
 import { type FormFillResult } from "../primitives/index.js";
+import * as primitives from "../primitives/index.js";
 export { targetLocator, resolveTargetLocator };
 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;
+    warning?: string | undefined;
     effectHint?: string | undefined;
     clicked: string;
     effect: {
@@ -25,20 +27,24 @@ export declare function clickTool(config: BrowserConfig, args: Record<string, an
     url: string;
     title: string;
     viaBridge?: boolean | undefined;
+    warning?: string | undefined;
     clicked: string;
 }>;
 export declare function typeTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
     typed: boolean;
-    editor: boolean;
+    typedVia: "editor";
     selector: string;
 } | {
     url: string;
     title: string;
-    typed: boolean;
     selector: string;
     submit: boolean;
+    warning?: string | undefined;
+    focusedElement?: string | undefined;
+    typed: boolean;
+    typedVia: "fill" | "clicked" | "focus-kept";
 }>;
 export declare function pressTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
@@ -53,12 +59,14 @@ export declare function pressTool(config: BrowserConfig, args: Record<string, an
 export declare function selectTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
+    warning?: string | undefined;
     selected: string;
     selector: string;
 }>;
 export declare function evalTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     scriptUnwrapped?: boolean | undefined;
     result: unknown;
+    mode: import("./common.js").EvalWrapMode;
 }>;
 export declare function downloadTool(config: BrowserConfig, args: Record<string, any>, exec?: ToolRunContext): Promise<{
     path: string;
@@ -140,10 +148,17 @@ export declare function transferTool(config: BrowserConfig, args: Record<string,
     direction: string;
     items: string[];
 }>;
+/**
+ * browser_drag:在页面里把源元素拖到目标元素上。
+ * 源/目标各自走统一定位管线(selector / ref / what+scope / mark 四选一前缀),
+ * 支持 HTML5 原生拖放(dragTo)与鼠标拖动类控件(物理鼠标序列降级);
+ * 跨 Frame 拖拽自动绕过 dragTo 的同 Frame 限制。
+ */
 export declare function dragTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
     dragged: boolean;
+    via: primitives.DragChannel;
     source: string;
     target: string;
 }>;

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

@@ -24,11 +24,21 @@ declare function __walkerCore(): {
 };
 /** walker 核心注入后暴露给 entry 的 API(类型层)。 */
 export type WalkerApi = ReturnType<typeof __walkerCore>;
+/** walker 核心序列化源(导出供 drift-guard 测试核对表单词表与注册表一致性)。 */
+export declare const WALKER_CORE_SRC: string;
 /**
  * 把消费方 entry(自包含函数,签名 (payload, w: WalkerApi) => R)拼装成
  * 可被 page.evaluate 序列化的独立函数 (payload: P) => R。
  * 拼装发生在模块加载期(new Function 一次性),调用期零开销。
  */
 export declare function injectWalker<P, R>(entry: (payload: P, w: WalkerApi) => R): (payload: P) => R;
+export declare const pickTopDialog: (payload: {
+    precise: string;
+    fuzzy: string;
+}) => {
+    selector: string;
+    z: number;
+    tier: "precise" | "fuzzy";
+} | null;
 export {};
 //# sourceMappingURL=walker.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "DSH 插件:共享 Playwright 浏览器自动化(38 个 browser_* 工具,含 what 意图语义定位(一次调用替代快照→查找→点击)、SoM 标徽看图点击与零命中截图兜底、SPA ref 软失效重锚定、open Shadow DOM 组合树穿透、跨 Frame/IFrame 定位、视口感知动态快照、批量表单智能填充、点击效果验证与定位失败遥测、Playwright 规范代码导出、批处理、视觉回归、选择器自愈、增量快照)+ 人机协作(面板点选教学 browser_pick_element、人工接管等待、敏感操作审批硬拦截、人机混合录制、面板一键重跑)+ CDP 流式推流、拟人化轨迹与高斯击键、全景时光机、企业富控件矩阵。另附独立 MCP server 入口(bin dsh-browser-mcp,stdio),任意 MCP 客户端可直接调用全部工具。运行时依赖 playwright-core 与 @modelcontextprotocol/sdk(仅 MCP 入口,不进 DSH 插件加载链)。",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,6 +43,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:drag": "tsx scripts/test-dev-server-drag.ts",
     "test:span": "tsx scripts/test-dev-server-clickable-span.ts",
     "test:pick": "tsx scripts/test-panel-pick.ts",
     "test:stream": "tsx scripts/test-panel-stream.ts",