@opentiny/next-sdk 0.3.3 → 0.4.1

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

@@ -0,0 +1,11 @@
+import { A11yTreeOptions, A11yTreeResult } from './types';
+
+/**
+ * 生成当前页面的语义化 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;

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

@@ -0,0 +1,9 @@
+/**
+ * a11y/constants.ts
+ *
+ * 存放无障碍树依赖的静态常量配置、默认选择器及角色映射表。
+ */
+export declare const DEFAULT_ERROR_SELECTORS: string[];
+export declare const DEFAULT_WARNING_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, blacklist?: Element[], whitelist?: Element[], options?: SearchA11yTreeOptions): SearchA11yTreeResult;

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

@@ -0,0 +1,104 @@
+/**
+ * a11y/types.ts
+ *
+ * 定义无障碍树模块（A11y Tree）的核心接口和类型。
+ */
+/** 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[];
+}
+/** 构建无障碍树时的配置选项 */
+export interface A11yTreeOptions {
+    /**
+     * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
+     * 默认 true（推荐）
+     */
+    pruneUnnamed?: boolean;
+    /**
+     * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
+     * 例如：['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[];
+}
+/** 构建无障碍树的返回结果 */
+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,34 @@
+/**
+ * a11y/utils.ts
+ *
+ * 存放生成无障碍树时的通用工具函数：节点解析、状态获取、角色推断及纯文本兜底等。
+ */
+/**
+ * 获取元素的 ARIA 角色
+ * 优先级：显式 role 属性 > 标签隐式角色 > 'generic'
+ */
+export declare function inferRole(el: Element): string;
+/**
+ * 收集节点的 ARIA 状态 token
+ * 格式：[checked] [selected] [disabled] [hasPopup] [cursor=pointer] [value="..."]
+ */
+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 collectDescendantText(el: Element): 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,37 @@
+import { VNode, RefMap, A11yTreeOptions } from './types';
+
+/**
+ * 递归将 DOM 元素转换为 VNode 中间表示
+ * @param el 当前 DOM 元素
+ * @param refCounter 引用计数器（使用对象引用避免全局可变状态）
+ * @param refMap ref 索引 → 元素映射
+ * @param blacklistSet 用户自定义黑名单
+ * @param whitelistSet 用户自定义白名单
+ * @param exposedAttributes 需要暴露的自定义属性
+ * @param errorSelectors 错误选择器
+ * @param warningSelectors 警告选择器
+ */
+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;
+/**
+ * 判断 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: Required<A11yTreeOptions>): boolean;
+/**
+ * 将 VNode 序列化为 YAML 行数组
+ * 穿透节点时，子节点在当前 depth 平铺输出（不增加缩进层级）
+ */
+export declare function serializeVNode(vnode: VNode, depth: number, opts: Required<A11yTreeOptions>): string[];

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

@@ -0,0 +1,12 @@
+/**
+ * a11y-tree.ts
+ *
+ * 此文件为 A11y Tree 模块的汇总出口，
+ * 方便外部直接从 './a11y-tree' 引入相关类型及方法，而无需调整现有的引用路径。
+ */
+export * from './a11y/types';
+export * from './a11y/constants';
+export * from './a11y/utils';
+export * from './a11y/vnode';
+export * from './a11y/build';
+export * from './a11y/search';

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

@@ -131,10 +131,4 @@ export type RegisterPageToolByHandlersOptions = {
     handlers: PageToolHandlers;
 };
 export declare function registerPageTool(options: RegisterPageToolByHandlersOptions): () => void;
-/**
- * 建立浏览器原生或 polyfill 与 next-sdk 页面工具桥接的联系。
- * 若用户或第三方库直接操作 navigator.modelContext 进行工具注册，
- * 我们通过此函数进行拦截劫持，并同步到 next-sdk 的握手线路 (MSG_TOOL_REGISTERED / MSG_TOOL_UNREGISTERED)，
- * 从而保证无论浏览器是否原生支持，均能正常完成 WebMCP 握手交互。
- */
 export declare function setupModelContextBridge(): void;

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

@@ -0,0 +1,22 @@
+/** 校验错误默认选择器：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;
+}
+declare global {
+    interface Window {
+        __webmcpcli_interactiveWhitelist?: Element[];
+        __webmcpcli_interactiveBlacklist?: Element[];
+        __webmcpcli_exposedAttributes?: string[];
+        __webmcpcli_beforeGetBrowserState?: (() => void) | null;
+        /** 校验错误元素 CSS 选择器列表（覆盖默认，用于检测页面可见的校验错误） */
+        __webmcpcli_errorSelectors?: string[];
+        /** 模态弹窗元素 CSS 选择器列表（覆盖默认，用于检测阻塞交互的弹窗） */
+        __webmcpcli_dialogSelectors?: string[];
+    }
+}

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

@@ -0,0 +1,28 @@
+import { PageController } from '@page-agent/page-controller';
+import { PageStateCache } from './page-state-cache';
+import { RefMap } from './a11y-tree';
+
+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;
+        }>;
+    }>;
+}

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,8 @@
+import { ActionContext } from '../context';
+
+export declare function handleSearchTree(args: any, 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/initialize-builtin-WebMCP.d.ts

@@ -0,0 +1 @@
+export declare const initializeBuiltinWebMCP: () => void;

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

@@ -0,0 +1,9 @@
+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 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,14 @@
+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;
+}

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.d.ts

@@ -0,0 +1,4 @@
+import { PageAgentToolOptions } from './constants';
+
+/** 在浏览器页面中注册 page-agent-tool, 用于页面的内容获取和操作，页面的动效 */
+export declare function registerPageAgentTool(options?: PageAgentToolOptions): void;

package/dist/page-tools/page-state-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * page-state-cache.ts
+ *
+ * 页面状态 Diff 缓存模块
+ * - 缓存上一次 buildA11yTree 生成的 YAML 文本
+ * - 每次操作后计算 diff，只返回 +/- 变化行，大幅节省 Token
+ */
+export interface PageSnapshot {
+    url: string;
+    yaml: string;
+}
+export interface DiffResult {
+    /** 是否为全量刷新（首次加载或 URL 变化） */
+    isFullRefresh: boolean;
+    /** 上一次的 URL（用于拼接 URL 变化提示） */
+    prevUrl: string;
+    /** 新增行数 */
+    addedLines: number;
+    /** 删除行数 */
+    removedLines: number;
+    /** 只含 +/- 行的 diff 文本（不含相同行，节省 Token） */
+    diffText: string;
+}
+export declare class PageStateCache {
+    private prev;
+    /** URL 变化或首次调用时，需要全量输出 */
+    isFullRefresh(currentUrl: string): boolean;
+    /**
+     * 更新缓存并返回 diff 结果
+     * @param url 当前页面 URL
+     * @param yaml 当前 YAML 树文本
+     */
+    update(url: string, yaml: string): DiffResult;
+    /** 强制清空缓存（页面刷新 / 手动重置场景） */
+    invalidate(): void;
+}

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

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

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

@@ -0,0 +1,6 @@
+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;

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

@@ -0,0 +1,15 @@
+export declare function getScrollInfo(target?: Window | Element): {
+    scrollY: number;
+    scrollX: number;
+    pixelsAbove: number;
+    pixelsBelow: number;
+    pixelsLeft: number;
+    pixelsRight: number;
+    pagesAbove: number;
+    pagesBelow: number;
+    atTop: boolean;
+    atBottom: boolean;
+    atLeft: boolean;
+    atRight: boolean;
+};
+export declare function waitForScrollEnd(target: Window | Element, timeout?: number): Promise<void>;

package/dist/runtime.d.ts

@@ -0,0 +1,4 @@
+import { initializeBuiltinWebMCP } from './page-tools/initialize-builtin-WebMCP';
+import { registerPageAgentTool } from './page-tools/page-agent-tool';
+
+export { initializeBuiltinWebMCP, registerPageAgentTool };