dsh-browser-view 0.4.1 → 0.7.0

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

@@ -0,0 +1,14 @@
+import type { Page } from "playwright-core";
+import { BaseUIAdapter } from "./engine.js";
+import type { FormFieldItem } from "./types.js";
+export declare class AntDesignAdapter extends BaseUIAdapter {
+    constructor();
+    /**
+     * Ant Design 专有复合组件字段填充 (支持 DatePicker 与 Cascader)
+     */
+    fillFormField(page: Page, field: FormFieldItem, scope?: string): Promise<{
+        handled: boolean;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=antd.d.ts.map

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

@@ -0,0 +1,93 @@
+import type { Page } from "playwright-core";
+/**
+ * 交互目标提升规则 (Target Lifting)
+ */
+export interface LiftingRule {
+    /** 目标标识，如 "checkbox-radio" 或 "combobox-input" */
+    kind: string;
+    /**
+     * 浏览器端元素特征判定
+     */
+    matches: (el: Element) => boolean;
+    /**
+     * 提升后的目标 Locator XPath 或选择器表达式
+     */
+    liftSelector: string;
+}
+/**
+ * UI 框架声明式描述符接口 (UIFrameworkDescriptor)
+ * 允许针对任何现代前端框架 (Ant Design, Element Plus, Arco Design, TDesign, Mantine 等)
+ * 仅通过声明式配置即可获得完整的语义提取、弹窗隔离、目标提升、下拉与交互自愈能力。
+ */
+export interface UIFrameworkDescriptor {
+    /** 适配器唯一名称，如 "ant-design", "element-plus", "generic", "arco-design" */
+    name: string;
+    /** 框架探测规则 */
+    detection: {
+        /** 页面特征选择器，如 "[class*='ant-'], #__ANTD_PRO__" */
+        selector?: string;
+        /** 全局变量判定，如 "__ANTD_PRO__" */
+        globalVar?: string;
+        /** 自定义匹配函数 */
+        customCheck?: (page: Page) => Promise<boolean>;
+    };
+    /** 弹窗与抽屉浮层隔离 */
+    dialogs: {
+        /** 活动状态弹窗/抽屉选择器列表，如 [".ant-modal:not([style*='display: none'])"] */
+        activeSelectors: string[];
+        /** 弹窗标题选择器，如 ".ant-modal-title, .ant-drawer-title" */
+        titleSelector?: string;
+    };
+    /** 表单与 Label 关联 */
+    forms: {
+        /** 表单项包装容器选择器，如 ".ant-form-item" */
+        itemSelector: string;
+        /** 表单项 Label 选择器，如 ".ant-form-item-label, label" */
+        labelSelector: string;
+        /** 单选/多选/开关包装选择器，如 "label, .ant-radio-wrapper, .ant-checkbox-wrapper, [class*='wrapper']" */
+        wrapperSelector?: string;
+    };
+    /** 下拉与浮层交互规范 */
+    select: {
+        /** 下拉触发器外层宿主选择器，如 ".ant-select, .ant-select-selector" */
+        triggerSelector: string;
+        /** controlsId 匹配模式，如 /^rc_select_/ */
+        controlsIdPattern?: RegExp;
+        /** 展开状态的 class 名称列表，如 ["ant-select-open", "is-focus"] */
+        openClassNames?: string[];
+        /** 点击展开时优先点击的子选择器，如 ".ant-select-selector" */
+        clickTargetSelector?: string;
+        /** 激活状态的下拉浮层容器选择器，如 ".ant-select-dropdown:not(.ant-select-dropdown-hidden):not([style*='display: none'])" */
+        dropdownSelector: string;
+        /** 下拉浮层基础类名(用于 controlsId 逆向查找)，如 "ant-select-dropdown" */
+        dropdownBaseClass?: string;
+        /** 选项条目选择器，如 ".ant-select-item-option, [role='option']" */
+        optionSelector: string;
+        /** 清除所有选中项按钮选择器，如 ".ant-select-clear, .el-select__clear, [class*='-clear']" */
+        clearSelector?: string;
+        /** 多选模式下单个标签的移除按钮选择器，如 ".ant-select-selection-item-remove, .el-tag__close, [class*='item-remove']" */
+        removeTagSelector?: string;
+        /** 数据为空时的指示容器选择器，如 ".ant-select-dropdown-empty, .ant-empty, .ant-select-item-empty" */
+        emptySelector?: string;
+    };
+    /** 目标提升规则 (Target Lifting) */
+    lifting?: LiftingRule[];
+    /** DOM Class -> ARIA Role 角色增强映射 */
+    roleMappings?: Record<string, string>;
+    /** 框架特异性隐藏类名判定 (如 "-hidden", "is-hidden") */
+    hiddenClassSubstrings?: string[];
+    /** 交互错误自愈策略 */
+    recovery?: {
+        /** 遮罩层 class 特征，如 ["ant-modal-wrap", "ant-modal-mask", "ant-drawer-mask"] */
+        maskClassSubstrings?: string[];
+        /** 框架元素 class 前缀，用于判断是否由动画未结束挂起，如 "ant-" */
+        targetClassSubstring?: string;
+    };
+}
+/** 内置 Ant Design (Vue / React) 描述符 */
+export declare const antdDescriptor: UIFrameworkDescriptor;
+/** 内置 Element Plus / Element UI 描述符 */
+export declare const elementPlusDescriptor: UIFrameworkDescriptor;
+/** 内置 Generic W3C 标准描述符 */
+export declare const genericDescriptor: UIFrameworkDescriptor;
+//# sourceMappingURL=archetypes.d.ts.map

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

@@ -0,0 +1,6 @@
+import type { Locator, Page } from "playwright-core";
+import { extractElementLabel, isElementDisabled } from "../primitives/index.js";
+export { extractElementLabel, isElementDisabled };
+export declare const ACTIVE_DIALOG_SELECTORS: string;
+export declare function getActiveDialog(page: Page): Locator;
+//# sourceMappingURL=dom.d.ts.map

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

@@ -0,0 +1,5 @@
+import { BaseUIAdapter } from "./engine.js";
+export declare class ElementPlusAdapter extends BaseUIAdapter {
+    constructor();
+}
+//# sourceMappingURL=element.d.ts.map

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

@@ -0,0 +1,51 @@
+import type { Locator, Page } from "playwright-core";
+import type { ActionContext, ActionInterceptor, ActionResult, FormFieldItem, QuiescenceOptions, SelectContext, SelectResult, SemanticExtractionHook, UIAdapter, VirtualExtractOptions } from "./types.js";
+import type { LiftingRule, UIFrameworkDescriptor } from "./archetypes.js";
+/**
+ * 通用下拉选择状态机引擎
+ * 参数化适配任何符合 UIFrameworkDescriptor 规范的 UI 组件库
+ */
+export declare function executeArchetypeSelect(desc: UIFrameworkDescriptor, ctx: SelectContext): Promise<SelectResult>;
+/**
+ * 目标提升执行器
+ */
+export declare function executeArchetypeLifting(rules: LiftingRule[] | undefined, ctx: ActionContext): Promise<Locator | void>;
+/**
+ * 交互错误自愈执行器
+ */
+export declare function executeArchetypeRecovery(desc: UIFrameworkDescriptor, ctx: ActionContext, error: Error): Promise<ActionResult | void>;
+/**
+ * 语义抽取钩子工厂
+ */
+export declare function createArchetypeSemanticHook(desc: UIFrameworkDescriptor): SemanticExtractionHook;
+/**
+ * 统一基底组件库适配器 (BaseUIAdapter)
+ * 接受任何 UIFrameworkDescriptor，直接提供完整的 UIAdapter 协议实现
+ */
+export declare class BaseUIAdapter implements UIAdapter {
+    readonly name: string;
+    readonly descriptor: UIFrameworkDescriptor;
+    readonly activeDialogSelector: string;
+    readonly extractionHook: SemanticExtractionHook;
+    readonly actionInterceptor: ActionInterceptor;
+    constructor(descriptor: UIFrameworkDescriptor);
+    matches(page: Page): Promise<boolean>;
+    waitForQuiescence(page: Page, options?: QuiescenceOptions): Promise<boolean>;
+    matchesSelect(ctx: SelectContext): Promise<boolean>;
+    selectOption(ctx: SelectContext): Promise<SelectResult>;
+    fillFormField(page: Page, field: FormFieldItem, scope?: string): Promise<{
+        handled: boolean;
+        error?: string;
+    }>;
+    fillDate(ctx: ActionContext, field: string, dateValue: string | [string, string]): Promise<boolean>;
+    selectPath(ctx: ActionContext, field: string, path: string[]): Promise<boolean>;
+    transferItems(ctx: ActionContext, selector: string, direction: "left" | "right", items: string[]): Promise<boolean>;
+    extractVirtualList(page: Page, options: VirtualExtractOptions): Promise<Record<string, any>[]>;
+    fillEditorContent(ctx: ActionContext, selector: string, content: string): Promise<boolean>;
+    dragAndDrop(ctx: ActionContext, sourceSelector: string, targetSelector: string): Promise<boolean>;
+}
+/**
+ * 声明式 UI 适配器工厂函数
+ */
+export declare function defineUIAdapter(descriptor: UIFrameworkDescriptor, overrides?: Partial<UIAdapter>): UIAdapter;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1,5 @@
+import { BaseUIAdapter } from "./engine.js";
+export declare class GenericAdapter extends BaseUIAdapter {
+    constructor();
+}
+//# sourceMappingURL=generic.d.ts.map

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

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./archetypes.js";
+export * from "./engine.js";
+export * from "./registry.js";
+export { waitForDOMQuiescence } from "./quiescence.js";
+export * from "./antd.js";
+export * from "./element.js";
+export * from "./generic.js";
+export * from "./dom.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/types/browser/adapters/modules/drag.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright-core";
+export declare function dragAndDropHelper(page: Page, sourceSelector: string, targetSelector: string): Promise<boolean>;
+//# sourceMappingURL=drag.d.ts.map

package/lib/types/browser/adapters/modules/editor.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright-core";
+export declare function fillEditorHelper(page: Page, selector: string, content: string): Promise<boolean>;
+//# sourceMappingURL=editor.d.ts.map

package/lib/types/browser/adapters/modules/hierarchy.d.ts

@@ -0,0 +1,3 @@
+import type { Locator, Page } from "playwright-core";
+export declare function selectPathHelper(page: Page, trigger: string | Locator, path: string[]): Promise<boolean>;
+//# sourceMappingURL=hierarchy.d.ts.map

package/lib/types/browser/adapters/modules/temporal.d.ts

@@ -0,0 +1,3 @@
+import type { Locator, Page } from "playwright-core";
+export declare function fillDateRangeHelper(page: Page, container: string | Locator, dateValue: string | [string, string]): Promise<boolean>;
+//# sourceMappingURL=temporal.d.ts.map

package/lib/types/browser/adapters/modules/transfer.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright-core";
+export declare function transferItemsHelper(page: Page, containerSelector: string, direction: "left" | "right", items: string[]): Promise<boolean>;
+//# sourceMappingURL=transfer.d.ts.map

package/lib/types/browser/adapters/modules/virtual.d.ts

@@ -0,0 +1,4 @@
+import type { Page } from "playwright-core";
+import type { VirtualExtractOptions } from "../types.js";
+export declare function extractVirtualListHelper(page: Page, options: VirtualExtractOptions): Promise<Record<string, any>[]>;
+//# sourceMappingURL=virtual.d.ts.map

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

@@ -0,0 +1,3 @@
+export { waitForDOMQuiescence } from "../primitives/index.js";
+export type { QuiescenceOptions } from "../primitives/index.js";
+//# sourceMappingURL=quiescence.d.ts.map

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

@@ -0,0 +1,64 @@
+import type { Page } from "playwright-core";
+import type { UIFrameworkDescriptor } from "./archetypes.js";
+import type { ActionContext, ActionResult, FormFieldItem, SelectContext, SelectResult, UIAdapter, VirtualExtractOptions } from "./types.js";
+declare class UIAdapterRegistryImpl {
+    private adapters;
+    private pageAdapterCache;
+    constructor();
+    /** 注册新的 UI 适配器插件 */
+    register(adapter: UIAdapter): void;
+    /** 声明式注册新的 UI 框架描述符 (自动生成对应 UIAdapter) */
+    registerDescriptor(descriptor: UIFrameworkDescriptor, overrides?: Partial<UIAdapter>): UIAdapter;
+    /** 获取指定适配器 */
+    get(name: string): UIAdapter | undefined;
+    /**
+     * 自动探测并获取当前页面对应的适配器
+     * 结果绑定到 Page 弱引用缓存中，避免重复探测
+     */
+    getActiveAdapter(page: Page): Promise<UIAdapter>;
+    /**
+     * 聚合所有已注册适配器的活动弹窗/对话框选择器
+     */
+    getActiveDialogSelectors(): string;
+    /**
+     * 聚合所有已注册适配器的表单项容器选择器
+     */
+    getFormItemSelectors(): string;
+    /**
+     * 聚合所有已注册适配器的表单项 Label 选择器
+     */
+    getFormLabelSelectors(): string;
+    /**
+     * 调度器入口: 自动根据目标节点特征解析最合适的 UI 适配器执行下拉交互
+     */
+    executeSelect(ctx: SelectContext): Promise<SelectResult>;
+    /**
+     * 清理页面的适配器缓存 (通常在页面发生整页导航时调用)
+     */
+    clearCache(page: Page): void;
+    /**
+     * 动作预处理管道 (执行目标提升等)
+     */
+    beforeAction(ctx: ActionContext): Promise<void | import("playwright-core").Locator>;
+    /**
+     * 动作异常自愈管道 (处理遮罩层、阻挡重试等)
+     */
+    onActionError(ctx: ActionContext, error: Error): Promise<ActionResult | void>;
+    /**
+     * 表单项智能填充调度：
+     * 优先尝试当前匹配的 UI 框架特异性适配器，若未处理则交由通用适配器兜底
+     */
+    fillFormField(page: Page, field: FormFieldItem, scope?: string): Promise<{
+        handled: boolean;
+        error?: string;
+    }>;
+    fillDate(ctx: ActionContext, field: string, dateValue: string | [string, string]): Promise<boolean>;
+    selectPath(ctx: ActionContext, field: string, path: string[]): Promise<boolean>;
+    transferItems(ctx: ActionContext, selector: string, direction: "left" | "right", items: string[]): Promise<boolean>;
+    extractVirtualList(page: Page, options: VirtualExtractOptions): Promise<Record<string, any>[]>;
+    fillEditorContent(ctx: ActionContext, selector: string, content: string): Promise<boolean>;
+    dragAndDrop(ctx: ActionContext, sourceSelector: string, targetSelector: string): Promise<boolean>;
+}
+export declare const adapterRegistry: UIAdapterRegistryImpl;
+export {};
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1,15 @@
+import type { SelectContext, SelectResult } from "./types.js";
+export type { SelectContext, SelectResult };
+/**
+ * 下拉适配器接口 (向后兼容类型导出)
+ */
+export interface SelectAdapter {
+    readonly name: string;
+    matches(ctx: SelectContext): Promise<boolean>;
+    select(ctx: SelectContext): Promise<SelectResult>;
+}
+/**
+ * 调度器入口: 自动委托给 adapterRegistry 解析最合适的 UI 适配器执行交互。
+ */
+export declare function executeSelectAdapter(ctx: SelectContext): Promise<SelectResult>;
+//# sourceMappingURL=select.d.ts.map

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

@@ -0,0 +1,134 @@
+import type { Locator, Page } from "playwright-core";
+import type { BrowserConfig } from "../types.js";
+/** 动作执行上下文 */
+export interface ActionContext {
+    page: Page;
+    config: BrowserConfig;
+    target: Locator;
+    action: "click" | "type" | "select" | "press";
+    args: Record<string, any>;
+    retries?: number;
+}
+/** 动作执行自愈结果 */
+export interface ActionResult {
+    handled: boolean;
+    result?: any;
+    retryWith?: {
+        force?: boolean;
+        timeoutMs?: number;
+        target?: Locator;
+    };
+}
+/**
+ * 语义抽取钩子 (在页内注入执行，必须为自包含逻辑)
+ * 用于扩展 walker.ts 的 nameOf、roleOf 与 isVisible
+ */
+export interface SemanticExtractionHook {
+    /** 根据元素与角色提取语义名称，返回 null 表示未命中由默认逻辑处理 */
+    resolveName?(el: Element, role: string): string | null;
+    /** 识别特异性角色，返回 null 表示由默认逻辑处理 */
+    resolveRole?(el: Element): string | null;
+    /** 快速可见性启发式判定，返回 null 表示由默认逻辑处理 */
+    checkVisible?(el: Element): boolean | null;
+}
+/**
+ * 交互动作拦截器 (在 Node.js 主机侧执行)
+ */
+export interface ActionInterceptor {
+    /** 交互发生前的预处理，如点击目标提升(Target Lifting) */
+    beforeAction?(ctx: ActionContext): Promise<Locator | void>;
+    /** 交互抛出错误时的自愈拦截器，如处理遮罩层拦截 */
+    onActionError?(ctx: ActionContext, error: Error): Promise<ActionResult | void>;
+}
+/**
+ * 页面稳态等待选项
+ */
+export interface QuiescenceOptions {
+    /** 连续无 DOM 变更的静默时间(ms)，默认 80ms */
+    quietMs?: number;
+    /** 最大等待超时(ms)，默认 2500ms */
+    maxTimeoutMs?: number;
+    /** 检查的根节点选择器，默认 document.body */
+    scope?: string;
+}
+/**
+ * 下拉选择交互上下文
+ */
+export interface SelectContext {
+    page: Page;
+    target: Locator;
+    label: string;
+    want: string;
+    exact: boolean;
+    timeout: number;
+    clear?: boolean;
+}
+/**
+ * 下拉选择结果
+ */
+export interface SelectResult {
+    selected: string;
+}
+/** 单个表单项填充参数 */
+export interface FormFieldItem {
+    key: string;
+    value: any;
+}
+/** 批量表单填充汇总结果 */
+export interface FormFillResult {
+    filled: string[];
+    skipped: string[];
+    errors: Record<string, string>;
+    submitted?: boolean;
+}
+/** 虚拟滚动长列表抽取选项 */
+export interface VirtualExtractOptions {
+    scope?: string;
+    fields: Record<string, string>;
+    maxRows: number;
+    stepPixels?: number;
+}
+/**
+ * 统一组件库适配器接口 (Pluggable UI Adapter Protocol v2)
+ */
+export interface UIAdapter {
+    /** 适配器唯一标识，如 "ant-design", "element-plus", "generic" */
+    readonly name: string;
+    /**
+     * 页内环境探测：判断当前页面是否命中该 UI 框架特征
+     * 在 page.evaluate 中运行
+     */
+    matches(page: Page): Promise<boolean>;
+    /** 语义抽取扩展钩子 (页内序列化注入) */
+    readonly extractionHook?: SemanticExtractionHook;
+    /** 交互动作拦截器 (主机侧) */
+    readonly actionInterceptor?: ActionInterceptor;
+    /** 稳态等待策略 */
+    waitForQuiescence?(page: Page, options?: QuiescenceOptions): Promise<boolean>;
+    /** 活动弹窗/对话框的选择器列表 (用于限制作用域) */
+    readonly activeDialogSelector?: string;
+    /** 是否匹配该 UI 框架的下拉/浮层触发器 */
+    matchesSelect?(ctx: SelectContext): Promise<boolean>;
+    /** 执行下拉/浮层选择 */
+    selectOption?(ctx: SelectContext): Promise<SelectResult>;
+    /**
+     * 组件库特异性表单字段填充 (如 AntD a-form-item、Checkbox、DatePicker 等)
+     */
+    fillFormField?(page: Page, field: FormFieldItem, scope?: string): Promise<{
+        handled: boolean;
+        error?: string;
+    }>;
+    /** 1. 时序组件: 处理日期/时间/范围选择 */
+    fillDate?(ctx: ActionContext, field: string, dateValue: string | [string, string]): Promise<boolean>;
+    /** 2. 层级组件: 处理级联与树选择 (路径驱动) */
+    selectPath?(ctx: ActionContext, field: string, path: string[]): Promise<boolean>;
+    /** 3. 穿梭组件: 批量移动左/右项 */
+    transferItems?(ctx: ActionContext, selector: string, direction: "left" | "right", items: string[]): Promise<boolean>;
+    /** 4. 虚拟滚动: 接管长列表滚动抽取 */
+    extractVirtualList?(page: Page, options: VirtualExtractOptions): Promise<Record<string, any>[]>;
+    /** 5. 编辑器组件: 富文本与代码编辑器安全设值 */
+    fillEditorContent?(ctx: ActionContext, selector: string, content: string): Promise<boolean>;
+    /** 6. 拖拽组件: 物理轨迹跨容器拖拽 */
+    dragAndDrop?(ctx: ActionContext, sourceSelector: string, targetSelector: string): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,10 @@
+import type { ReplayStep } from "../types.js";
+export interface CompileOptions {
+    title?: string;
+    baseUrl?: string;
+}
+/**
+ * 将录制序列转译为符合行业标准规范的原生 Playwright TypeScript 测试代码
+ */
+export declare function compileToPlaywrightSpec(steps: ReplayStep[], options?: CompileOptions): string;
+//# sourceMappingURL=playwright.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getCollaborationTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=collaboration.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getDoctorTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getExtractTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=extract.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getInspectionTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=inspection.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getInteractionTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=interaction.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getNavigationTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=navigation.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getRecorderTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=recorder.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { PlainToolDefinition } from "../../lib/types.js";
+import type { BrowserConfig } from "../types.js";
+export declare function getTestingTools(config: BrowserConfig, timeout: (ms?: number) => number, stepImpls?: Record<string, (a: any) => Promise<unknown>>): PlainToolDefinition[];
+//# sourceMappingURL=testing.d.ts.map

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

@@ -0,0 +1,26 @@
+import type { BrowserConfig } from "../types.js";
+import type { PolicyDecision, PolicyEvaluationContext, PolicyRule } from "./types.js";
+export declare const DEFAULT_SENSITIVE_PATTERNS: string[];
+export declare const DEFAULT_SENSITIVE_TOOLS: string[];
+export interface SensitiveDesc {
+    role?: string;
+    name?: string;
+    text?: string;
+    id?: string;
+    testid?: string;
+    tag?: string;
+}
+/**
+ * 纯逻辑: 元素描述命中了哪些敏感模式(role/name/text/id/testid/tag 拼接后
+ * 子串匹配, 大小写不敏感; 空白模式忽略)。返回命中的模式列表(空 = 放行)。
+ */
+export declare function sensitiveHits(desc?: SensitiveDesc | null, patterns?: string[]): string[];
+/**
+ * 判定单条策略规则是否匹配当前上下文
+ */
+export declare function matchPolicyRule(rule: PolicyRule, ctx: PolicyEvaluationContext): boolean;
+/**
+ * 策略引擎评估入口: 按规则链顺序判定，优先匹配第一条命中的规则
+ */
+export declare function evaluatePolicy(config: BrowserConfig, ctx: PolicyEvaluationContext): PolicyDecision;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1,36 @@
+export interface PolicyRule {
+    /** 规则名称/标识 */
+    name: string;
+    /** 页面 URL 正则模式，如 ".*(localhost|127\\.0\\.0\\.1|\\.test\\.|\\.qa\\.).*" */
+    urlPattern?: string;
+    /** 动作/工具正则模式，如 "browser_click", "browser_.*" */
+    actionPattern?: string;
+    /** 选择器正则模式，如 "#danger-action.*" */
+    selectorPattern?: string;
+    /** 敏感文本模式数组，如 ["提交", "删除", "支付"] */
+    patterns?: string[];
+    /** 拦截级别：off(直接放行) | manual(提示) | auto(强制审批弹卡) */
+    level: "off" | "manual" | "auto";
+    /** 审批超时时间 (毫秒)，覆盖全局 confirmTimeoutMs */
+    timeoutMs?: number;
+}
+export interface PolicyEvaluationContext {
+    url: string;
+    tool: string;
+    selector: string;
+    desc?: {
+        role?: string;
+        name?: string;
+        text?: string;
+        id?: string;
+        testid?: string;
+        tag?: string;
+    } | null;
+}
+export interface PolicyDecision {
+    matchedRule?: PolicyRule;
+    level: "off" | "manual" | "auto";
+    reason?: string;
+    timeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { Locator, Page } from "playwright-core";
+/**
+ * 通用活动弹窗/对话框/抽屉选择器列表
+ * 基于 W3C WAI-ARIA 规范 (role="dialog", aria-modal="true") 与现代 Web 通用命名规范
+ */
+export declare const ACTIVE_DIALOG_SELECTORS: string;
+/**
+ * 获取当前页面上处于活动状态的最顶层弹窗容器 (Locator)
+ */
+export declare function getActiveDialog(page: Page): Locator;
+export declare function getActiveDialogSelectors(): string;
+//# sourceMappingURL=dialog.d.ts.map

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

@@ -0,0 +1,43 @@
+import type { Locator, Page } from "playwright-core";
+import type { QuiescenceOptions } from "./types.js";
+/**
+ * 提取表单元素关联的语义 Label:
+ * 覆盖原生 label、aria-labelledby、以及各类主流组件库的表单包装结构。
+ * 供 targetLocator 及无障碍名称校验在浏览器端(evaluate)执行。
+ */
+export declare function extractElementLabel(el: Element): string;
+/**
+ * 统一判定元素或其上下文是否处于禁用状态 (Native disabled, WAI-ARIA aria-disabled, 以及通用 disabled class)
+ */
+export declare function isElementDisabled(el: Element): boolean;
+/**
+ * 等待页面 DOM 达到稳定状态 (基于 MutationObserver 静默期)
+ */
+export declare function waitForDOMQuiescence(page: Page, options?: QuiescenceOptions): Promise<boolean>;
+/**
+ * 目标提升原语 (Target Lifting):
+ * 现代 Web 页面中自定义 checkbox / radio 的原生 <input> 通常设置了 opacity: 0 或宽高为 0，
+ * 并由外层 label 或 wrapper 承载视觉与交互。当目标为隐藏 input 时，自动提升定位至可见的外层宿主容器。
+ */
+export declare function liftTargetIfHiddenInput(target: Locator, evalTimeout?: number): Promise<Locator>;
+/**
+ * 遮罩与过渡拦截自愈:
+ * 处理弹窗打开/关闭动画期间遮罩层 (mask) 暂时拦截指针事件的偶发异常
+ */
+export declare function isMaskInterceptionError(error: Error): boolean;
+/**
+ * 开始记录 DOM 变化(点击前调用):在页内装 MutationObserver,变化累积到
+ * window.__dshWatch。失败静默(endChangeWatch 会返回空摘要,不放大错误)。
+ */
+export declare function beginChangeWatch(page: Page): Promise<void>;
+/**
+ * 收口变化记录(点击后调用):graceMs 宽限(默认 600ms,等异步涟漪)后断开
+ * 观察器,返回去重截断(≤30)的变化元素选择器列表。未曾 begin 时返回空摘要。
+ */
+export declare function endChangeWatch(page: Page, options?: {
+    graceMs?: number;
+}): Promise<{
+    mutations: string[];
+    domChanged: boolean;
+}>;
+//# sourceMappingURL=dom.d.ts.map

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

@@ -0,0 +1,3 @@
+import type { Page } from "playwright-core";
+export declare function dragAndDropHelper(page: Page, sourceSelector: string, targetSelector: string): Promise<boolean>;
+//# sourceMappingURL=drag.d.ts.map

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

@@ -0,0 +1,3 @@
+import type { Page } from "playwright-core";
+export declare function fillEditorHelper(page: Page, selector: string, content: string): Promise<boolean>;
+//# sourceMappingURL=editor.d.ts.map

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

@@ -0,0 +1,7 @@
+import type { Page } from "playwright-core";
+import type { FormFieldItem } from "./types.js";
+export declare function fillFormFieldHelper(page: Page, field: FormFieldItem, scope?: string): Promise<{
+    handled: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=form.d.ts.map