@opentiny/next-sdk 0.4.0 → 0.4.2

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

@@ -0,0 +1,10 @@
+import { A11yTreeOptions, A11yTreeResult } from './types';
+import { A11yConfig } from './config';
+
+/**
+ * 生成当前页面的语义化 ARIA YAML 树
+ *
+ * @param root 遍历起点，默认 document.body
+ * @param config 统一无障碍配置（角色/状态规则、白/黑名单、自定义属性等）+ 树形状选项（pruneUnnamed/preserveRoles）
+ */
+export declare function buildA11yTree(root?: Element, config?: A11yConfig & A11yTreeOptions): A11yTreeResult;

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

@@ -0,0 +1,96 @@
+/**
+ * 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[];
+    /** 模态弹窗 CSS 选择器（用于 detectPageDialog 检测阻塞交互的弹窗） */
+    dialogSelectors?: 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[];
+    dialogSelectors: 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;
+/** 从状态规则中提取纯 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

@@ -0,0 +1,11 @@
+/**
+ * a11y/constants.ts
+ *
+ * 存放无障碍树依赖的静态常量配置、默认选择器及角色映射表。
+ */
+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[];
+export declare const TAG_ROLE_MAP: Record<string, string>;
+export declare const INPUT_TYPE_ROLE: Record<string, string>;

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

@@ -0,0 +1,17 @@
+import { SearchA11yTreeOptions, SearchA11yTreeResult } from './types';
+
+/**
+ * 在无障碍树中按关键词搜索，返回带行号的匹配结果和上下文
+ *
+ * 支持的搜索维度（均对同一个 query 字符串做包含匹配）：
+ *   - role：如 `button`、`link`、`heading`
+ *   - accessible name：节点的语义化名称（引号内文本）
+ *   - state token：如 `checked`、`disabled`、`expanded`
+ *   - ref 索引：如 `#5`
+ *
+ * @example
+ *   searchA11yTree('button')    // 找全部按钮
+ *   searchA11yTree('提交')      // 找名称含"提交"的节点
+ *   searchA11yTree('#3')        // 找 ref #3
+ */
+export declare function searchA11yTree(query: string, root?: Element, options?: SearchA11yTreeOptions): SearchA11yTreeResult;

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

@@ -0,0 +1,95 @@
+import { A11yConfig } from './config';
+
+/** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
+export type RefMap = Map<number, HTMLElement>;
+/** 内部中间态节点，与 DOM 解耦，便于剪枝和序列化 */
+export interface VNode {
+    /** 节点的 ARIA 角色 (如 'button', 'link', 'textbox') */
+    role: string;
+    /** W3C AccName 算法计算出的语义化名称 */
+    name: string;
+    /** 元素相关的状态和属性标记 (如 'checked', 'disabled', 'value="xxx"') */
+    tokens: string[];
+    /** 只有交互节点才有 ref (内部索引，用于标识可在其上执行交互动作的元素) */
+    ref?: number;
+    /** 关联的 DOM 元素实例 */
+    el: HTMLElement;
+    /** 包含的子节点列表 */
+    children: VNode[];
+}
+/**
+ * 构建无障碍树时的配置选项。
+ * 继承统一的 A11yConfig（角色/状态规则、白/黑名单、自定义暴露属性、弹窗选择器），
+ * 并额外提供两个控制树"形状"（而非无障碍语义）的选项。
+ */
+export interface A11yTreeOptions extends A11yConfig {
+    /**
+     * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
+     * 默认 true（推荐）
+     */
+    pruneUnnamed?: boolean;
+    /**
+     * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
+     * 例如：['table', 'row'] 用于保留表格结构
+     */
+    preserveRoles?: string[];
+}
+/** 序列化 YAML 树时实际用到的形状选项（与无障碍语义解析无关，独立于 A11yConfig） */
+export interface A11yTreeShapeOptions {
+    pruneUnnamed: boolean;
+    preserveRoles: string[];
+}
+/** 构建无障碍树的返回结果 */
+export interface A11yTreeResult {
+    /** 语义化 YAML 文本（供 AI 阅读和 Diff 计算） */
+    yaml: string;
+    /** ref 索引 → HTMLElement 映射（供后续操作使用） */
+    refMap: RefMap;
+    /** 可交互元素总数 */
+    interactiveCount: number;
+    /** 原始行数组（不含 yaml 代码块包裹），供搜索使用 */
+    lines: string[];
+}
+/** 关键词搜索选项 */
+export interface SearchA11yTreeOptions extends A11yTreeOptions {
+    /**
+     * 每个匹配行前后保留的上下文行数（类似 grep -C N）
+     * 默认 2
+     */
+    contextLines?: number;
+    /**
+     * 是否大小写不敏感，默认 true
+     */
+    caseInsensitive?: boolean;
+    /**
+     * 最大返回匹配分组数（防止命中过多撑爆上下文），默认 20
+     */
+    maxMatches?: number;
+}
+/** 单个搜索匹配的分组结构 */
+export interface A11ySearchMatch {
+    /** 主命中行行号（1-based） */
+    lineNumber: number;
+    /** 主命中行内容 */
+    line: string;
+    /** 含上下文的行列表（带行号） */
+    context: Array<{
+        lineNumber: number;
+        line: string;
+    }>;
+}
+/** searchA11yTree 函数的返回结果 */
+export interface SearchA11yTreeResult {
+    /** 格式化后可直接发给 LLM 的文本 */
+    text: string;
+    /** 结构化匹配列表 */
+    matches: A11ySearchMatch[];
+    /** 无障碍树总行数 */
+    totalLines: number;
+    /** 原始命中行数（去重前） */
+    matchCount: number;
+    /** 返回搜索时的 ref 映射 */
+    refMap: RefMap;
+    /** 返回搜索时的 yaml 状态，用于更新缓存 */
+    yaml: string;
+}

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

@@ -0,0 +1,55 @@
+import { ResolvedA11yConfig } from './config';
+
+export declare function isNonContentElement(el: Element): boolean;
+/**
+ * 判断元素是否"自身"呈现 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;
+/**
+ * 收集页面中"仅在 :hover/:focus/:active 等交互态下声明 cursor:pointer"的元素集合。
+ *
+ * 背景（华为云控制台实测）：大量可点击卡片（如 `.container-wrapper .shadow:hover{cursor:pointer}`）
+ * 只在鼠标悬停时才显示手势，静止态 `getComputedStyle(el).cursor` 读到的是 `auto`，
+ * 因此仅凭 computed cursor 的判定（含业界 getComputedStyle 方案）会漏判这类元素。
+ * 这里通过扫描样式表把这类"交互态手势"补齐，作为可点击性的兜底信号。
+ *
+ * 每次构建树只调用一次（O(规则数) 扫描 + 一次合并查询），避免逐元素扫描样式表。
+ */
+export declare function collectHoverPointerElements(root: Element): Set<Element>;
+/** 判断元素是否应被跳过（不可见、非内容或在黑名单中） */
+export declare function isHidden(el: Element): boolean;
+/**
+ * 收集元素自身或子孙节点的 title，用作图标按钮等无文本节点的名字兜底。
+ * 云控制台常见模式：可点击容器无 aria-label，title 挂在内部 span 上。
+ */
+export declare function collectTitleLabel(el: Element): string;
+/**
+ * 收集子孙节点的文本内容，用作无障碍名字的兜底。
+ * 当普通计算无法提取文本时，遍历后代并拼接可见文本。
+ * @param config 已规整的无障碍配置；传入后角色判断会尊重页面自定义 roles 规则
+ */
+export declare function collectDescendantText(el: Element, config?: ResolvedA11yConfig): string;
+/**
+ * 获取元素在 composed tree（组合树）中的有效子元素
+ *
+ * Shadow DOM 场景下，简单拼接 el.children + el.shadowRoot.children 不符合浏览器
+ * 实际渲染和无障碍树使用的组合树语义：slotted 节点应出现在 <slot> 的位置而非
+ * host 下，<slot> 本身不应作为噪音节点出现，未被任何 slot 接收的 light children
+ * 在组合树中不可见。
+ *
+ * 因此：有 shadowRoot 时遍历 shadow tree，遇到 <slot> 用 assignedElements 替换；
+ * 无 shadowRoot 时直接遍历 light DOM children。
+ */
+export declare function getComposedChildren(el: Element): Element[];

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

@@ -0,0 +1,40 @@
+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 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>, config: ResolvedA11yConfig, hoverPointerSet?: Set<Element>): VNode | null;
+/**
+ * 判断 VNode 子树是否包含任何有价值的节点（有 ref 或有 accessible name）
+ * 用于过滤空容器子树，避免输出无内容的嵌套层级
+ */
+export declare function hasValue(vnode: VNode): boolean;
+/**
+ * 判断节点是否需要透明穿透（跳过本节点但保留子节点）
+ *
+ * 统一规则：无 ref（非交互）且无 accessible name → 穿透
+ * 这样可以同时：
+ * - 去掉 generic/list/listitem 等纯布局噪音（无 name 时穿透）
+ * - 保留有 name 的 listitem（有 name 时保留，兼顾内容理解场景）
+ */
+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: A11yTreeShapeOptions): string[];

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

@@ -1,103 +1,13 @@
 /**
  * a11y-tree.ts
  *
- * 浏览器内语义化 ARIA 树生成器（重构版）
- *
- * 核心改进：
- * 1. 两阶段处理：buildVNode（构建中间树）→ serializeVNode（剪枝序列化）
- * 2. 统一剪枝规则：无 ref 且无 accessible name → 透明穿透（跳过本节点，保留子节点）
- *    - 兼顾操作场景（去掉 generic/list/listitem 噪音）
- *    - 兼顾内容理解场景（有 name 的 listitem 等节点保留）
- * 3. 修复全局可变状态：refCounter 改为局部对象，消除并发调用隐患
- *
- * 依赖：
- *   - dom-accessibility-api: W3C AccName 规范 JS 实现（计算 accessible name）
- *   - tabbable: 可交互/可聚焦元素检测（工业级，处理所有边界情况）
- */
-/** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
-export type RefMap = Map<number, HTMLElement>;
-export interface A11yTreeOptions {
-    /**
-     * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
-     * 默认 true（推荐）
-     */
-    pruneUnnamed?: boolean;
-    /**
-     * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
-     * 例如：['table', 'row'] 用于保留表格结构
-     */
-    preserveRoles?: string[];
-}
-export interface A11yTreeResult {
-    /** 语义化 YAML 文本（供 AI 阅读和 Diff 计算） */
-    yaml: string;
-    /** ref 索引 → HTMLElement 映射（供后续操作使用） */
-    refMap: RefMap;
-    /** 可交互元素总数 */
-    interactiveCount: number;
-    /** 原始行数组（不含 yaml 代码块包裹），供搜索使用 */
-    lines: string[];
-}
-/** 关键词搜索选项 */
-export interface SearchA11yTreeOptions extends A11yTreeOptions {
-    /**
-     * 每个匹配行前后保留的上下文行数（类似 grep -C N）
-     * 默认 2
-     */
-    contextLines?: number;
-    /**
-     * 是否大小写不敏感，默认 true
-     */
-    caseInsensitive?: boolean;
-    /**
-     * 最大返回匹配分组数（防止命中过多撑爆上下文），默认 20
-     */
-    maxMatches?: number;
-}
-/** 单个匹配分组 */
-export interface A11ySearchMatch {
-    /** 主命中行行号（1-based） */
-    lineNumber: number;
-    /** 主命中行内容 */
-    line: string;
-    /** 含上下文的行列表（带行号） */
-    context: Array<{
-        lineNumber: number;
-        line: string;
-    }>;
-}
-/** searchA11yTree 返回值 */
-export interface SearchA11yTreeResult {
-    /** 格式化后可直接发给 LLM 的文本 */
-    text: string;
-    /** 结构化匹配列表 */
-    matches: A11ySearchMatch[];
-    /** 无障碍树总行数 */
-    totalLines: number;
-    /** 原始命中行数（去重前） */
-    matchCount: number;
-}
-/**
- * 生成当前页面的语义化 ARIA YAML 树
- *
- * @param root 遍历起点，默认 document.body
- * @param blacklist 需要跳过的元素（用户自定义黑名单）
- * @param whitelist 需要识别为可交互的白名单元素列表
- * @param options 过滤选项
- */
-export declare function buildA11yTree(root?: Element, blacklist?: Element[], whitelist?: Element[], options?: A11yTreeOptions): A11yTreeResult;
-/**
- * 在无障碍树中按关键词搜索，返回带行号的匹配结果和上下文
- *
- * 支持的搜索维度（均对同一个 query 字符串做包含匹配）：
- *   - role：如 `button`、`link`、`heading`
- *   - accessible name：节点的语义化名称（引号内文本）
- *   - state token：如 `checked`、`disabled`、`expanded`
- *   - ref 索引：如 `#5`
- *
- * @example
- *   searchA11yTree('button')    // 找全部按钮
- *   searchA11yTree('提交')      // 找名称含"提交"的节点
- *   searchA11yTree('#3')        // 找 ref #3
+ * 此文件为 A11y Tree 模块的汇总出口，
+ * 方便外部直接从 './a11y-tree' 引入相关类型及方法，而无需调整现有的引用路径。
  */
-export declare function searchA11yTree(query: string, root?: Element, blacklist?: Element[], whitelist?: Element[], options?: SearchA11yTreeOptions): SearchA11yTreeResult;
+export * from './a11y/types';
+export * from './a11y/constants';
+export * from './a11y/config';
+export * from './a11y/utils';
+export * from './a11y/vnode';
+export * from './a11y/build';
+export * from './a11y/search';

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

@@ -0,0 +1,10 @@
+/** 校验错误默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源为 a11y/constants.ts，此处重新导出保持旧路径可用） */
+export { DEFAULT_ERROR_SELECTORS, DEFAULT_DIALOG_SELECTORS } from './a11y/constants';
+/** registerPageAgentTool(options) 的入参类型，定义见 tool-config.ts（与运行期 setPageAgentToolConfig 的补丁类型一致） */
+export type { PageAgentToolOptions } from './tool-config';
+declare global {
+    interface Window {
+        /** 指定网站可覆盖该函数，在每次 getBrowserState 之前调用，常用于配合 setPageAgentToolConfig 动态调整当前页面的配置 */
+        __webmcpcli_beforeGetBrowserState?: (() => void) | null;
+    }
+}

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

@@ -0,0 +1,40 @@
+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;
+};
+export declare function createActionErrorResult(message: string, buildBrowserStateResponse: ActionContext['buildBrowserStateResponse']): Promise<PageAgentToolErrorResult>;
+export interface ActionContext {
+    pageController: PageController;
+    stateCache: PageStateCache;
+    getRefMap: () => RefMap;
+    setRefMap: (map: RefMap) => void;
+    buildBrowserStateResponse: (mode?: 'full' | 'diff' | 'both') => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
+    refreshOnStaleRef: (action: string, index: number) => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
+    errContent: (msg: string) => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
+    actionError: (msg: string) => Promise<PageAgentToolErrorResult>;
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,21 @@
+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;
+/** 全局监听变化，随时准备移除高亮, 可反复调用 */
+export declare const globalRemoveListener: () => void;

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

@@ -0,0 +1,16 @@
+import { Motion } from 'ai-motion';
+
+export declare class SimulatorMask extends EventTarget {
+    #private;
+    shown: boolean;
+    wrapper: HTMLDivElement;
+    motion: Motion | null;
+    constructor();
+    setCursorPosition(x: number, y: number): void;
+    triggerClickAnimation(): void;
+    show(): void;
+    hide(): void;
+    dispose(): void;
+    borderElement(targetElement: HTMLElement): void;
+    removeBorderElement(): void;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * A comprehensive function to determine if the page is currently in a dark theme.
+ * Heuristic check. Only work for common patterns. Return false by default.
+ */
+export declare function isPageDark(): boolean;

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 {};