@opentiny/next-sdk 0.4.1 → 0.4.3

package/dist/page-tools/a11y/build.d.ts

@@ -1,11 +1,10 @@
 import { A11yTreeOptions, A11yTreeResult } from './types';
+import { A11yConfig } from './config';
 
 /**
  * 生成当前页面的语义化 ARIA YAML 树
  *
  * @param root 遍历起点，默认 document.body
- * @param blacklist 需要跳过的元素（用户自定义黑名单）
- * @param whitelist 需要识别为可交互的白名单元素列表
- * @param options 过滤选项
+ * @param config 统一无障碍配置（角色/状态规则、白/黑名单、自定义属性等）+ 树形状选项（pruneUnnamed/preserveRoles）
  */
-export declare function buildA11yTree(root?: Element, blacklist?: Element[], whitelist?: Element[], options?: A11yTreeOptions): A11yTreeResult;
+export declare function buildA11yTree(root?: Element, config?: A11yConfig & A11yTreeOptions): A11yTreeResult;

package/dist/page-tools/a11y/config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * a11y/config.ts
+ *
+ * 统一无障碍配置（A11yConfig）：把角色推断、状态推断、白/黑名单、自定义属性、
+ * 弹窗选择器等配置项收敛为一个对象，并提供：
+ * 1. 声明式规则（roles/states）的合并与匹配逻辑
+ * 2. 底层的逐元素解析函数（resolveA11yRole/resolveA11yStates/resolveA11yInfo）
+ *
+ * 运行期读写 API 统一由 ../tool-config.ts 的 getPageAgentToolConfig/setPageAgentToolConfig 提供
+ * （a11yConfig 是其中一个字段），这里不再单独维护一套 get/set。
+ */
+export interface A11yMatcher {
+    /**
+     * 标准 CSS 选择器。优先使用 selector，仅当选择器表达不了时再写 match。
+     * - **states**：用 `closest` 判断自身或祖先是否命中（适合 error/selected 等挂在容器上的状态）
+     * - **roles**：用 `matches` 仅判断自身是否命中（避免角色传染给子孙节点）
+     * 支持标签/属性/id/组合选择器，也支持字符串数组（任意一个命中即可）。
+     */
+    selector?: string | string[];
+    /** 自定义判断函数，优先级高于 selector，用于读取计算样式、组合条件等选择器表达不了的场景 */
+    match?: (el: Element) => boolean;
+}
+export type A11yStateName = 'checked' | 'selected' | 'pressed' | 'current' | 'expanded' | 'hasPopup' | 'disabled' | 'readonly' | 'required' | 'invalid' | 'busy' | 'error' | 'warning' | (string & {});
+export interface A11yRoleRule extends A11yMatcher {
+    /** 命中后赋予的 ARIA 角色，如 'tab' | 'tabpanel' | 'switch' | 'treeitem' */
+    role: string;
+    /** 为 true 时覆盖元素已有的显式 role 属性，默认 false（不覆盖开发者显式设置） */
+    force?: boolean;
+}
+export interface A11yConfig {
+    /** 角色推断规则：用于弥补页面缺失的语义 role（如自定义 Tab 组件没有 role=tab） */
+    roles?: A11yRoleRule[];
+    /** 状态推断规则：key 为状态名，value 为一条或多条规则（命中任意一条即成立），与标准 aria-* 检测结果取"或" */
+    states?: Partial<Record<A11yStateName, A11yMatcher | A11yMatcher[]>>;
+    /** 白名单：强制识别为可交互元素并纳入无障碍树。支持 Element 引用或 CSS 选择器字符串（字符串每次动态解析，适配 SPA 重渲染） */
+    whitelist?: Array<Element | string>;
+    /** 黑名单：强制从无障碍树中排除，规则同上 */
+    blacklist?: Array<Element | string>;
+    /** 额外暴露的自定义 DOM 属性（作为 token 输出，如 [data-testid="xxx"]） */
+    exposedAttributes?: string[];
+}
+/** 单个元素解析出的完整无障碍信息 */
+export interface A11yInfo {
+    role: string;
+    tokens: string[];
+}
+/** 标记已与默认值合并并规整过的配置，避免热路径上二次 merge 导致默认规则翻倍 */
+declare const RESOLVED_A11Y_BRAND: unique symbol;
+/**
+ * 合并/规整后的完整无障碍配置：与用户书写的 {@link A11yConfig} 的唯一区别是
+ * states 的每个状态名都统一规范化为数组（不再是 `A11yMatcher | A11yMatcher[]`）。
+ * resolveA11yInfo 内部与 getPageAgentToolConfig().a11yConfig 读取到的都是这个类型。
+ */
+export interface ResolvedA11yConfig {
+    roles: A11yRoleRule[];
+    states: Partial<Record<A11yStateName, A11yMatcher[]>>;
+    whitelist: Array<Element | string>;
+    blacklist: Array<Element | string>;
+    exposedAttributes: string[];
+    readonly [RESOLVED_A11Y_BRAND]?: true;
+}
+/** 是否为 {@link mergeA11yConfig}/{@link mergeA11yConfigs} 产出的已规整配置 */
+export declare function isResolvedA11yConfig(config?: A11yConfig | ResolvedA11yConfig | null): config is ResolvedA11yConfig;
+/** 默认生效的无障碍配置：零配置即可覆盖 ARIA 标准 + 主流 UI 框架的常见错误/警告/选中态检测 */
+export declare const DEFAULT_A11Y_CONFIG: ResolvedA11yConfig;
+/**
+ * 从 roles 规则中提取指定角色的所有 CSS 选择器（展平为一维 string[]）。
+ * 供 DOM 检测函数（detectPageDialog / getVisibleTooltipElements）复用：
+ * 这些函数需要选择器字符串做 deepQuerySelectorAll，而非 matches 判断。
+ */
+export declare function getSelectorsForRole(roles: A11yRoleRule[], targetRole: string): string[];
+/** 从状态规则中提取纯 CSS 选择器列表（忽略只有 match 函数、没有 selector 的规则；数组 selector 会被展开），供页面级选择器扫描场景复用 */
+export declare function extractSelectors(rules?: A11yMatcher | A11yMatcher[]): string[];
+/** 合并两份 A11yConfig：数组类字段拼接（additive，不丢失 base 中已有的规则），states 按 key 独立合并 */
+export declare function mergeA11yConfigs(base: A11yConfig, patch: A11yConfig): ResolvedA11yConfig;
+/**
+ * 将用户配置与默认配置合并（additive），得到最终生效的完整配置。
+ * 若入参已是 {@link ResolvedA11yConfig}，直接返回（幂等，避免默认规则被再次拼接）。
+ */
+export declare function mergeA11yConfig(user?: A11yConfig | ResolvedA11yConfig): ResolvedA11yConfig;
+/**
+ * 保证拿到已与默认值合并的配置：已规整则原样返回（同引用，零开销），否则与默认配置合并。
+ * buildA11yTree / resolveA11yInfo 热路径应优先走此函数，避免对运行期配置反复 merge。
+ */
+export declare function ensureResolvedA11yConfig(config?: A11yConfig | ResolvedA11yConfig): ResolvedA11yConfig;
+/** 恒等函数，仅用于书写配置时获得 TS 类型提示/校验（风格对齐 defineConfig） */
+export declare function defineA11yConfig(config: A11yConfig): A11yConfig;
+export declare function resolveA11yRole(el: Element, config?: A11yConfig | ResolvedA11yConfig): string;
+export declare function resolveA11yStates(el: Element, config?: A11yConfig | ResolvedA11yConfig): string[];
+/**
+ * 统一入口（供用户直接调用的底层函数）：读取配置 -> 依据 roles/states 规则计算出该元素的
+ * 完整无障碍信息（角色 + 状态 token）。buildA11yTree 内部对每个 DOM 节点也是调用这一个函数，
+ * 是声明式规则与树生成结果之间唯一的桥接点；用户也可以直接调用它来调试/复用同一套解析逻辑。
+ *
+ * 若传入已是 {@link ResolvedA11yConfig}（如 getPageAgentToolConfig().a11yConfig），则跳过合并，
+ * 避免在整树遍历时对每个节点重复 array spread / 默认规则翻倍。
+ */
+export declare function resolveA11yInfo(el: Element, config?: A11yConfig | ResolvedA11yConfig): A11yInfo;
+export {};

package/dist/page-tools/a11y/constants.d.ts

@@ -5,5 +5,27 @@
  */
 export declare const DEFAULT_ERROR_SELECTORS: string[];
 export declare const DEFAULT_WARNING_SELECTORS: string[];
+/** 模态弹窗默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源，顶层 constants.ts 从此处重新导出） */
+export declare const DEFAULT_DIALOG_SELECTORS: string[];
+/** 可见 tooltip / 浮层提示默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源，顶层 constants.ts 从此处重新导出） */
+export declare const DEFAULT_TOOLTIP_SELECTORS: string[];
 export declare const TAG_ROLE_MAP: Record<string, string>;
+/**
+ * 框架级 role 覆盖规则
+ *
+ * 当元素没有显式 role 属性时，按 CSS 选择器匹配框架特有 class 模式，
+ * 推断出符合 ARIA 语义的 role，使无障碍树能正确识别非标准 UI 组件。
+ *
+ * 优先级：显式 role 属性 > 框架 role 覆盖 > 标签隐式映射 > generic
+ *
+ * 注意：框架特有规则（如 Tiny3 Tabs、tp-helptip）应放在各框架预设配置中
+ *（如 configs/console-cloud.ts），此处仅保留通用规则。
+ */
+export interface RoleOverride {
+    /** CSS 选择器，匹配则应用该 role */
+    selector: string;
+    /** 覆盖后的 ARIA 角色 */
+    role: string;
+}
+export declare const DEFAULT_ROLE_OVERRIDES: RoleOverride[];
 export declare const INPUT_TYPE_ROLE: Record<string, string>;

package/dist/page-tools/a11y/search.d.ts

@@ -14,4 +14,4 @@ import { SearchA11yTreeOptions, SearchA11yTreeResult } from './types';
  *   searchA11yTree('提交')      // 找名称含"提交"的节点
  *   searchA11yTree('#3')        // 找 ref #3
  */
-export declare function searchA11yTree(query: string, root?: Element, blacklist?: Element[], whitelist?: Element[], options?: SearchA11yTreeOptions): SearchA11yTreeResult;
+export declare function searchA11yTree(query: string, root?: Element, options?: SearchA11yTreeOptions): SearchA11yTreeResult;

package/dist/page-tools/a11y/types.d.ts

@@ -1,8 +1,5 @@
-/**
- * a11y/types.ts
- *
- * 定义无障碍树模块（A11y Tree）的核心接口和类型。
- */
+import { A11yConfig } from './config';
+
 /** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
 export type RefMap = Map<number, HTMLElement>;
 /** 内部中间态节点，与 DOM 解耦，便于剪枝和序列化 */
@@ -20,8 +17,12 @@ export interface VNode {
     /** 包含的子节点列表 */
     children: VNode[];
 }
-/** 构建无障碍树时的配置选项 */
-export interface A11yTreeOptions {
+/**
+ * 构建无障碍树时的配置选项。
+ * 继承统一的 A11yConfig（角色/状态规则、白/黑名单、自定义暴露属性、弹窗选择器），
+ * 并额外提供两个控制树"形状"（而非无障碍语义）的选项。
+ */
+export interface A11yTreeOptions extends A11yConfig {
     /**
      * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
      * 默认 true（推荐）
@@ -32,21 +33,11 @@ export interface A11yTreeOptions {
      * 例如：['table', 'row'] 用于保留表格结构
      */
     preserveRoles?: string[];
-    /**
-     * 允许在无障碍树节点中作为 token 额外输出的 DOM 属性白名单
-     * 包含这些属性的节点会被自动视为需要暴露/交互的节点（分配 ref 并保留），
-     * 且属性及其值会显示在节点的 token 列表中，如 [cf-uba="cloudShell"]
-     */
-    exposedAttributes?: string[];
-    /**
-     * 校验错误元素 CSS 选择器（逗号分隔或选择器数组），用于在 token 中标记 [error]
-     * 默认覆盖 ARIA 标准 + 主流 UI 框架
-     */
-    errorSelectors?: string | string[];
-    /**
-     * 校验警告元素 CSS 选择器（逗号分隔或选择器数组）
-     */
-    warningSelectors?: string | string[];
+}
+/** 序列化 YAML 树时实际用到的形状选项（与无障碍语义解析无关，独立于 A11yConfig） */
+export interface A11yTreeShapeOptions {
+    pruneUnnamed: boolean;
+    preserveRoles: string[];
 }
 /** 构建无障碍树的返回结果 */
 export interface A11yTreeResult {

package/dist/page-tools/a11y/utils.d.ts

@@ -1,25 +1,46 @@
+import { ResolvedA11yConfig } from './config';
+
+export declare function isNonContentElement(el: Element): boolean;
 /**
- * a11y/utils.ts
+ * 判断元素是否"自身"呈现 cursor:pointer（而非从祖先继承而来）。
  *
- * 存放生成无障碍树时的通用工具函数：节点解析、状态获取、角色推断及纯文本兜底等。
+ * 背景：CSS 的 `cursor` 属性会向子孙继承。可点击容器（如 <a>、自定义卡片 .card-wrapper）
+ * 一旦设置 cursor:pointer，其内部所有子孙的 computed cursor 都会变成 pointer。
+ * 若仅凭「computed cursor === pointer」判定交互性，会让容器的可点击性"传染"给全部子孙，
+ * 产生大量误报 ref（父容器 cursor:pointer 泛滥到每个子节点）。
+ *
+ * 业界主流 DOM 提取器（如 browser-use 的 doesElementHaveInteractivePointer）同样以
+ * cursor:pointer 作为可点击性的核心兜底信号，并通过与父元素对比来定位真正的可点击"边界元素"。
+ * 因此这里的判定为：元素自身 computed cursor 为 pointer，且其父元素不是 pointer —— 说明
+ * 该元素（或命中它的 CSS 规则）主动声明了指针手势，是真正意义上的可点击目标。
+ *
+ * 无父元素（如 shadow host 边界、游离节点）时，没有可继承来源，视为自身声明。
  */
+export declare function hasOwnPointerCursor(el: Element): boolean;
 /**
- * 获取元素的 ARIA 角色
- * 优先级：显式 role 属性 > 标签隐式角色 > 'generic'
+ * 收集页面中"仅在 :hover/:focus/:active 等交互态下声明 cursor:pointer"的元素集合。
+ *
+ * 背景（华为云控制台实测）：大量可点击卡片（如 `.container-wrapper .shadow:hover{cursor:pointer}`）
+ * 只在鼠标悬停时才显示手势，静止态 `getComputedStyle(el).cursor` 读到的是 `auto`，
+ * 因此仅凭 computed cursor 的判定（含业界 getComputedStyle 方案）会漏判这类元素。
+ * 这里通过扫描样式表把这类"交互态手势"补齐，作为可点击性的兜底信号。
+ *
+ * 每次构建树只调用一次（O(规则数) 扫描 + 一次合并查询），避免逐元素扫描样式表。
  */
-export declare function inferRole(el: Element): string;
+export declare function collectHoverPointerElements(root: Element): Set<Element>;
+/** 判断元素是否应被跳过（不可见、非内容或在黑名单中） */
+export declare function isHidden(el: Element): boolean;
 /**
- * 收集节点的 ARIA 状态 token
- * 格式：[checked] [selected] [disabled] [hasPopup] [cursor=pointer] [value="..."]
+ * 收集元素自身或子孙节点的 title，用作图标按钮等无文本节点的名字兜底。
+ * 云控制台常见模式：可点击容器无 aria-label，title 挂在内部 span 上。
  */
-export declare function getStateTokens(el: Element, exposedAttributes?: string[], errorSelectors?: string | string[], warningSelectors?: string | string[]): string[];
-/** 判断元素是否应被跳过（不可见或在黑名单中） */
-export declare function isHidden(el: Element): boolean;
+export declare function collectTitleLabel(el: Element): string;
 /**
  * 收集子孙节点的文本内容，用作无障碍名字的兜底。
  * 当普通计算无法提取文本时，遍历后代并拼接可见文本。
+ * @param config 已规整的无障碍配置；传入后角色判断会尊重页面自定义 roles 规则
  */
-export declare function collectDescendantText(el: Element): string;
+export declare function collectDescendantText(el: Element, config?: ResolvedA11yConfig): string;
 /**
  * 获取元素在 composed tree（组合树）中的有效子元素
  *
@@ -32,3 +53,17 @@ export declare function collectDescendantText(el: Element): string;
  * 无 shadowRoot 时直接遍历 light DOM children。
  */
 export declare function getComposedChildren(el: Element): Element[];
+/**
+ * 提取元素的 tooltip / 帮助提示文本
+ *
+ * 按以下优先级查找（返回首个非空结果）：
+ * 1. title 属性
+ * 2. aria-describedby 引用的元素文本
+ * 3. data-tooltip / data-tips 自定义属性
+ * 4. 框架级 tooltip 内容（如 Tiny3 tp-helptip 内的 .tp-helptip-label 文本）
+ * 4b. 框架级 overflow 指令（Tiny3 tioverflow / Angular Material matTooltip）
+ *
+ * 即使 tooltip 容器被隐藏（display:none / opacity:0），也提取其文本内容，
+ * 让 AI 无需 hover 即可获取帮助信息。
+ */
+export declare function extractTooltipText(el: Element): string;

package/dist/page-tools/a11y/vnode.d.ts

@@ -1,21 +1,19 @@
-import { VNode, RefMap, A11yTreeOptions } from './types';
+import { VNode, RefMap, A11yTreeShapeOptions } from './types';
+import { ResolvedA11yConfig } from './config';
 
 /**
  * 递归将 DOM 元素转换为 VNode 中间表示
  * @param el 当前 DOM 元素
  * @param refCounter 引用计数器（使用对象引用避免全局可变状态）
  * @param refMap ref 索引 → 元素映射
- * @param blacklistSet 用户自定义黑名单
- * @param whitelistSet 用户自定义白名单
- * @param exposedAttributes 需要暴露的自定义属性
- * @param errorSelectors 错误选择器
- * @param warningSelectors 警告选择器
+ * @param blacklistSet 已解析的黑名单元素集合
+ * @param whitelistSet 已解析的白名单元素集合
+ * @param config 已与默认值合并的统一无障碍配置
+ * @param hoverPointerSet 只在 :hover/:focus/:active 下声明 cursor:pointer 的元素集合（静止态读不到手势，靠样式表扫描兜底）
  */
 export declare function buildVNode(el: Element, refCounter: {
     value: number;
-}, refMap: RefMap, blacklistSet: Set<Element>, whitelistSet: Set<Element>, exposedAttributes?: string[], errorSelectors?: string | string[], warningSelectors?: string | string[], 
-/** 祖先节点是否已是可交互节点（已分配 ref）。为 true 时，纯 CSS 继承的 cursor=pointer 不再额外分配 ref */
-ancestorIsInteractive?: boolean): VNode | null;
+}, refMap: RefMap, blacklistSet: Set<Element>, whitelistSet: Set<Element>, config: ResolvedA11yConfig, hoverPointerSet?: Set<Element>): VNode | null;
 /**
  * 判断 VNode 子树是否包含任何有价值的节点（有 ref 或有 accessible name）
  * 用于过滤空容器子树，避免输出无内容的嵌套层级
@@ -29,9 +27,14 @@ export declare function hasValue(vnode: VNode): boolean;
  * - 去掉 generic/list/listitem 等纯布局噪音（无 name 时穿透）
  * - 保留有 name 的 listitem（有 name 时保留，兼顾内容理解场景）
  */
-export declare function shouldPassThrough(vnode: VNode, opts: Required<A11yTreeOptions>): boolean;
+export declare function shouldPassThrough(vnode: VNode, opts: A11yTreeShapeOptions): boolean;
 /**
  * 将 VNode 序列化为 YAML 行数组
  * 穿透节点时，子节点在当前 depth 平铺输出（不增加缩进层级）
+ *
+ * 文本折叠规则（Static-Lift + Interactive-Keep，保字优先）：
+ * 1. 子树全静态 → 省略子节点，文字保留在父节点
+ * 2. 混合子树 → 静态文案上提到父 name（成功才省略静态子节点）；交互分支递归保留；
+ *    禁止把交互文案并入父 name；上提失败则静态子节点独立输出，绝不丢字
  */
-export declare function serializeVNode(vnode: VNode, depth: number, opts: Required<A11yTreeOptions>): string[];
+export declare function serializeVNode(vnode: VNode, depth: number, opts: A11yTreeShapeOptions): string[];

package/dist/page-tools/a11y-tree.d.ts

@@ -6,6 +6,7 @@
  */
 export * from './a11y/types';
 export * from './a11y/constants';
+export * from './a11y/config';
 export * from './a11y/utils';
 export * from './a11y/vnode';
 export * from './a11y/build';

package/dist/page-tools/configs/console-cloud.d.ts

@@ -0,0 +1,6 @@
+import { PageAgentToolOptions } from '../tool-config';
+
+/** 云控制台 page-agent-tool 预设配置 */
+export declare const consoleCloudPageAgentToolOptions: PageAgentToolOptions;
+/** 判断当前页面是否应使用云控制台（consoleCloud）预设 */
+export declare function isConsoleCloudHost(hostname?: string): boolean;

package/dist/page-tools/constants.d.ts

@@ -1,22 +1,12 @@
-/** 校验错误默认选择器：ARIA 标准 + 主流 UI 框架 */
-export declare const DEFAULT_ERROR_SELECTORS: string[];
-/** 模态弹窗默认选择器：ARIA 标准 + 主流 UI 框架 */
-export declare const DEFAULT_DIALOG_SELECTORS: string[];
-export interface PageAgentToolOptions {
-    /** 允许在无障碍树节点中额外暴露的 DOM 属性白名单 */
-    exposedAttributes?: string[];
-    /** 是否启用元素高亮 */
-    enableHighlight?: boolean;
-}
+/** 校验错误/弹窗/tooltip 默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源为 a11y/constants.ts，此处重新导出保持旧路径可用） */
+export { DEFAULT_ERROR_SELECTORS, DEFAULT_DIALOG_SELECTORS, DEFAULT_TOOLTIP_SELECTORS } from './a11y/constants';
+/** 框架级 role 覆盖规则：为非标准 UI 组件推断 ARIA 角色（已纳入 DEFAULT_A11Y_CONFIG.roles，此处重新导出保持旧路径可用） */
+export { DEFAULT_ROLE_OVERRIDES, type RoleOverride } from './a11y/constants';
+/** registerPageAgentTool(options) 的入参类型，定义见 tool-config.ts（与运行期 setPageAgentToolConfig 的补丁类型一致） */
+export type { PageAgentToolOptions } from './tool-config';
 declare global {
     interface Window {
-        __webmcpcli_interactiveWhitelist?: Element[];
-        __webmcpcli_interactiveBlacklist?: Element[];
-        __webmcpcli_exposedAttributes?: string[];
+        /** 指定网站可覆盖该函数，在每次 getBrowserState 之前调用，常用于配合 setPageAgentToolConfig 动态调整当前页面的配置 */
         __webmcpcli_beforeGetBrowserState?: (() => void) | null;
-        /** 校验错误元素 CSS 选择器列表（覆盖默认，用于检测页面可见的校验错误） */
-        __webmcpcli_errorSelectors?: string[];
-        /** 模态弹窗元素 CSS 选择器列表（覆盖默认，用于检测阻塞交互的弹窗） */
-        __webmcpcli_dialogSelectors?: string[];
     }
 }

package/dist/page-tools/context.d.ts

@@ -2,6 +2,19 @@ import { PageController } from '@page-agent/page-controller';
 import { PageStateCache } from './page-state-cache';
 import { RefMap } from './a11y-tree';
 
+export type PageAgentToolContentResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export type PageAgentToolErrorResult = PageAgentToolContentResult & {
+    isError: true;
+    error: string;
+};
+/** 将额外字段合并进 browserState JSON，保持整段可反序列化 */
+export declare function withStateFields(stateText: string, extra: Record<string, unknown>): string;
+export declare function createActionErrorResult(message: string, buildBrowserStateResponse: ActionContext['buildBrowserStateResponse']): Promise<PageAgentToolErrorResult>;
 export interface ActionContext {
     pageController: PageController;
     stateCache: PageStateCache;
@@ -25,4 +38,5 @@ export interface ActionContext {
             text: string;
         }>;
     }>;
+    actionError: (msg: string) => Promise<PageAgentToolErrorResult>;
 }

package/dist/page-tools/handlers/hover.d.ts

@@ -0,0 +1,9 @@
+import { ActionContext } from '../context';
+import { PageAgentToolInput } from '../schema';
+
+export declare function handleHover(args: PageAgentToolInput, ctx: ActionContext): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;

package/dist/page-tools/handlers/searchTree.d.ts

@@ -1,6 +1,7 @@
 import { ActionContext } from '../context';
+import { PageAgentToolInput } from '../schema';
 
-export declare function handleSearchTree(args: any, ctx: ActionContext): Promise<{
+export declare function handleSearchTree(args: PageAgentToolInput, ctx: ActionContext): Promise<{
     content: Array<{
         type: "text";
         text: string;

package/dist/page-tools/page-agent-highlight/index.d.ts

@@ -2,6 +2,18 @@ import { RefMap } from '../a11y-tree';
 
 export declare const HIGHLIGHT_CONTAINER_ID = "webmcpcli-highlight-container";
 export declare const HIGHLIGHT_CONTAINER_STYLE_ID = "webmcpcli-highlight-container-style";
+export type HighlightRect = {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};
+/**
+ * 解析高亮矩形。
+ * Tiny3 `ti-icon` / `tp-icon` 字形常画在 ::before 上，宿主 getBoundingClientRect 宽或高为 0，
+ * 旧逻辑直接跳过导致帮助中心关闭/全屏等图标有 ref 却不高亮。
+ */
+export declare function resolveHighlightRect(el: HTMLElement): HighlightRect | null;
 export declare const highlight: (refMap: RefMap, parentIframe?: HTMLIFrameElement | null) => void;
 /** 移除高亮， 可反复调用 */
 export declare const unhighlight: () => void;

package/dist/page-tools/page-agent-mask/SimulatorMask.d.ts

@@ -11,4 +11,6 @@ export declare class SimulatorMask extends EventTarget {
     show(): void;
     hide(): void;
     dispose(): void;
+    borderElement(targetElement: HTMLElement): void;
+    removeBorderElement(): void;
 }

package/dist/page-tools/page-agent-tool-event.d.ts

@@ -0,0 +1,26 @@
+import { PageAgentToolInput, PageAgentToolRawInput } from './schema';
+import { PageController } from '@page-agent/page-controller';
+
+export declare const PAGE_AGENT_TOOL_CALL_EVENT = "page-agent-tool-call";
+export declare const PAGE_AGENT_TOOL_RESULT_EVENT = "page-agent-tool-result";
+export declare const PAGE_AGENT_CHAT_END_EVENT = "page-agent-chat-end";
+export type PageAgentToolCallEventDetail = {
+    data?: PageAgentToolRawInput;
+    requestId: string;
+};
+export type PageAgentToolResultEventDetail = {
+    data: {
+        success: boolean;
+        result?: unknown;
+        error?: string;
+    };
+    requestId: string;
+};
+type ExecutePageAgentTool = (data: PageAgentToolInput) => Promise<unknown>;
+declare global {
+    interface Window {
+        __nextSdkPageAgentToolEventCleanup?: () => void;
+    }
+}
+export declare function setupPageAgentToolEventBridge(executePageAgentTool: ExecutePageAgentTool, pageController: PageController): void;
+export {};

package/dist/page-tools/schema.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 export declare const inputSchema: z.ZodObject<{
-    action: z.ZodEnum<["browserState", "click", "fill", "select", "scroll", "executeJavascript", "searchTree"]>;
+    action: z.ZodEnum<["browserState", "click", "fill", "select", "scroll", "executeJavascript", "searchTree", "hover"]>;
     index: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodString>;
     down: z.ZodOptional<z.ZodBoolean>;
@@ -14,7 +14,7 @@ export declare const inputSchema: z.ZodObject<{
     maxMatches: z.ZodDefault<z.ZodNumber>;
     responseMode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["full", "diff", "both"]>>>;
 }, "strip", z.ZodTypeAny, {
-    action: "fill" | "click" | "select" | "scroll" | "browserState" | "executeJavascript" | "searchTree";
+    action: "fill" | "hover" | "click" | "select" | "scroll" | "browserState" | "executeJavascript" | "searchTree";
     contextLines: number;
     maxMatches: number;
     responseMode: "full" | "diff" | "both";
@@ -27,7 +27,7 @@ export declare const inputSchema: z.ZodObject<{
     pixels?: number | undefined;
     query?: string | undefined;
 }, {
-    action: "fill" | "click" | "select" | "scroll" | "browserState" | "executeJavascript" | "searchTree";
+    action: "fill" | "hover" | "click" | "select" | "scroll" | "browserState" | "executeJavascript" | "searchTree";
     text?: string | undefined;
     right?: boolean | undefined;
     script?: string | undefined;
@@ -41,3 +41,4 @@ export declare const inputSchema: z.ZodObject<{
     responseMode?: "full" | "diff" | "both" | undefined;
 }>;
 export type PageAgentToolInput = z.infer<typeof inputSchema>;
+export type PageAgentToolRawInput = z.input<typeof inputSchema>;

package/dist/page-tools/tool-config.d.ts

@@ -0,0 +1,50 @@
+import { A11yConfig, ResolvedA11yConfig } from './a11y/config';
+
+export interface PageAgentToolConfig {
+    /** 是否启用元素高亮 */
+    enableHighlight: boolean;
+    /** 是否在工具调用后移除遮罩， 默认值为 true 移除 */
+    removeMaskAfterToolCall?: boolean;
+    /**
+     * 统一无障碍配置：按角色（roles）、状态（states：selected/disabled/error/warning 等）自定义规则，
+     * 以及白名单/黑名单/自定义暴露属性/弹窗选择器。已与默认配置合并（数组类字段是拼接结果）。
+     */
+    a11yConfig: ResolvedA11yConfig;
+}
+/**
+ * 用于初始化（registerPageAgentTool 的入参）或运行期 setPageAgentToolConfig 的补丁对象：
+ * enableHighlight 为覆盖式更新；a11yConfig 为拼接式合并（数组类字段追加，不丢已有规则，语义见 a11y/config.ts）。
+ */
+export interface PageAgentToolConfigPatch {
+    /** 是否启用元素高亮 */
+    enableHighlight?: boolean;
+    /** 是否在工具调用后移除遮罩， 默认值为 true 移除 */
+    removeMaskAfterToolCall?: boolean;
+    /** 是否在工具调用后移除遮罩 */
+    /** 统一无障碍配置，会与当前生效的 a11yConfig 按数组拼接合并 */
+    a11yConfig?: A11yConfig;
+}
+/** registerPageAgentTool(options) 的入参类型，与运行期补丁 {@link PageAgentToolConfigPatch} 完全一致 */
+export type PageAgentToolOptions = PageAgentToolConfigPatch;
+/** 默认生效的完整工具配置 */
+export declare const DEFAULT_PAGE_AGENT_TOOL_CONFIG: PageAgentToolConfig;
+declare global {
+    interface Window {
+        /** 运行期唯一生效的 page-agent-tool 完整配置（已与默认值合并），可通过 getPageAgentToolConfig/setPageAgentToolConfig 读写 */
+        __webmcpcli_toolConfig?: PageAgentToolConfig;
+    }
+}
+/** 读取当前生效的完整工具配置（已与默认值合并）。未初始化时返回默认配置 */
+export declare function getPageAgentToolConfig(): PageAgentToolConfig;
+/**
+ * 更新当前生效配置。
+ * - patch 为对象时：enableHighlight 覆盖式更新；a11yConfig 与当前配置按数组拼接合并（不丢已有规则）
+ * - patch 为函数时：入参为当前生效配置，返回值直接与默认配置合并（而不是再与 current 相加）。
+ *   这样函数体内可以对 current.a11yConfig 做任意过滤/裁剪（如按条件"移除"某条旧规则），
+ *   返回值即为最终生效的配置，不会因为再与 current 相加而让被过滤掉的旧规则"复活"
+ * - options.mode = 'replace' 时（仅影响对象类型的 patch）：不与"当前生效配置"合并，而是与默认配置重新合并
+ * 返回合并后的最新完整配置，并写回运行期存储供 buildBrowserStateResponse/buildA11yTree 等读取。
+ */
+export declare function setPageAgentToolConfig(patch: PageAgentToolConfigPatch | ((current: PageAgentToolConfig) => PageAgentToolConfigPatch), options?: {
+    mode?: 'merge' | 'replace';
+}): PageAgentToolConfig;

package/dist/page-tools/utils/dom.d.ts

@@ -2,5 +2,11 @@ export declare function isInShadowDom(el: Element): boolean;
 export declare function dispatchComposedEvents(el: Element, ...types: string[]): void;
 export declare function deepQuerySelectorAll(selector: string, root?: Document | Element | ShadowRoot): Element[];
 export declare function waitForDomSettled(timeout?: number, settleTime?: number): Promise<void>;
-export declare function detectPageDialog(): string;
-export declare function detectValidationErrors(): string;
+/** 页面级模态弹窗检测结果 */
+export interface DetectedDialog {
+    text: string;
+    buttons: string[];
+}
+export declare function detectPageDialog(): DetectedDialog[];
+export declare function detectValidationErrors(): string[];
+export declare function detectVisibleTooltips(): string[];

package/dist/runtime.d.ts

@@ -1,4 +1,7 @@
 import { initializeBuiltinWebMCP } from './page-tools/initialize-builtin-WebMCP';
 import { registerPageAgentTool } from './page-tools/page-agent-tool';
+import { getPageAgentToolConfig, setPageAgentToolConfig } from './page-tools/tool-config';
+import { defineA11yConfig } from './page-tools/a11y/config';
+import { consoleCloudPageAgentToolOptions, isConsoleCloudHost } from './page-tools/configs/console-cloud';
 
-export { initializeBuiltinWebMCP, registerPageAgentTool };
+export { initializeBuiltinWebMCP, registerPageAgentTool, getPageAgentToolConfig, setPageAgentToolConfig, defineA11yConfig, consoleCloudPageAgentToolOptions, isConsoleCloudHost, };