@opentiny/next-sdk 0.4.1 → 0.4.2

package/page-tools/constants.ts

@@ -1,72 +1,12 @@
-/** 校验错误默认选择器：ARIA 标准 + 主流 UI 框架 */
-export const DEFAULT_ERROR_SELECTORS: string[] = [
-  // W3C ARIA 标准（最可靠，框架无关）
-  '[role="alert"]',
-  '[aria-invalid="true"]',
-  // Tiny3 / Lego（华为云）
-  '.ti3-unifyvalid-error',
-  '.ti3-error',
-  '.ti-error',
-  '.lego-text-error',
-  '.lego-error',
-  // Element UI / Element Plus
-  '.el-form-item__error',
-  // Ant Design
-  '.ant-form-item-explain-error',
-  // Bootstrap
-  '.is-invalid',
-  '.invalid-feedback',
-  // Angular
-  '.ng-invalid',
-  // 通用命名约定
-  '.error-msg',
-  '.error-message',
-  '.error-text',
-  '.field-error',
-  '.form-error',
-  '.is-error',
-  '.has-error',
-  '.validate-error',
-  '.valid-error'
-]
+/** 校验错误默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源为 a11y/constants.ts，此处重新导出保持旧路径可用） */
+export { DEFAULT_ERROR_SELECTORS, DEFAULT_DIALOG_SELECTORS } from './a11y/constants'
 
-/** 模态弹窗默认选择器：ARIA 标准 + 主流 UI 框架 */
-export const DEFAULT_DIALOG_SELECTORS: string[] = [
-  // W3C ARIA 标准
-  '[role="dialog"]',
-  '[role="alertdialog"]',
-  // Tiny3 / Lego（华为云）
-  '[class*="ti3-modal"]',
-  '[class*="ti3-message-box"]',
-  // Element UI / Element Plus
-  '[class*="el-dialog"]',
-  '[class*="el-message-box"]',
-  // Ant Design
-  '[class*="ant-modal"]',
-  // Bootstrap
-  '[class*="modal-content"]',
-  // Vuetify
-  '[class*="v-dialog"]',
-  // Naive UI
-  '[class*="n-modal"]'
-]
-
-export interface PageAgentToolOptions {
-  /** 允许在无障碍树节点中额外暴露的 DOM 属性白名单 */
-  exposedAttributes?: string[]
-  /** 是否启用元素高亮 */
-  enableHighlight?: boolean
-}
+/** 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/page-tools/context.ts

@@ -2,12 +2,49 @@ import type { PageController } from '@page-agent/page-controller'
 import type { PageStateCache } from './page-state-cache'
 import type { RefMap } from './a11y-tree'
 
+export type PageAgentToolContentResult = {
+  content: Array<{ type: 'text'; text: string }>
+}
+
+export type PageAgentToolErrorResult = PageAgentToolContentResult & {
+  isError: true
+  error: string
+}
+
+export async function createActionErrorResult(
+  message: string,
+  buildBrowserStateResponse: ActionContext['buildBrowserStateResponse']
+): Promise<PageAgentToolErrorResult> {
+  try {
+    const browserState = await buildBrowserStateResponse('full')
+    return {
+      isError: true,
+      error: message,
+      content: [{ type: 'text', text: `${message}\n\n${browserState.content[0].text}` }]
+    }
+  } catch (error) {
+    return {
+      isError: true,
+      error: message,
+      content: [
+        {
+          type: 'text',
+          text: `${message}\n\n获取最新浏览器状态失败: ${error instanceof Error ? error.message : String(error)}`
+        }
+      ]
+    }
+  }
+}
+
 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 }> }>
+  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/page-tools/handlers/click.ts

@@ -4,9 +4,13 @@ import type { ActionContext } from '../context'
 
 export async function handleClick(args: any, ctx: ActionContext) {
   const mode = args.responseMode ?? 'diff'
-  if (args.index === undefined) return ctx.errContent('点击结果: 缺少元素索引')
+  if (args.index === undefined) return ctx.actionError('点击结果: 缺少元素索引')
   const el = ctx.getRefMap().get(args.index)
-  if (!el) return ctx.refreshOnStaleRef('点击', args.index)
+  if (!el) {
+    return ctx.actionError(
+      `点击失败: ref 索引 ${args.index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。`
+    )
+  }
 
   // 若 ref 指向 shadow host，解析其内部真正的可点击元素
   let targetEl = el as HTMLElement

package/page-tools/handlers/fill.ts

@@ -4,15 +4,20 @@ import type { ActionContext } from '../context'
 
 export async function handleFill(args: any, ctx: ActionContext) {
   const mode = args.responseMode ?? 'diff'
-  if (args.index === undefined || typeof args.text !== 'string') return ctx.errContent('填写结果: 缺少元素索引或文本内容')
+  if (args.index === undefined || typeof args.text !== 'string')
+    return ctx.actionError('填写结果: 缺少元素索引或文本内容')
   const el = ctx.getRefMap().get(args.index)
-  if (!el) return ctx.refreshOnStaleRef('填写', args.index)
+  if (!el) {
+    return ctx.actionError(
+      `填写失败: ref 索引 ${args.index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。`
+    )
+  }
 
   let targetEl = el
   if (!(targetEl instanceof HTMLInputElement) && !(targetEl instanceof HTMLTextAreaElement)) {
     // querySelector 不穿透 shadow boundary，对 shadow host 补查其 shadowRoot
-    const innerInput = el.querySelector('input, textarea')
-      ?? (el.shadowRoot?.querySelector('input, textarea') as HTMLElement | null)
+    const innerInput =
+      el.querySelector('input, textarea') ?? (el.shadowRoot?.querySelector('input, textarea') as HTMLElement | null)
     if (innerInput) {
       targetEl = innerInput as HTMLElement
     }
@@ -46,7 +51,7 @@ export async function handleFill(args: any, ctx: ActionContext) {
       }
     }
     if (!fillSuccess) {
-      return ctx.errContent(`填写结果: 无法填写元素 ${args.index}，元素不是 input、textarea 或 contenteditable`)
+      return ctx.actionError(`填写结果: 无法填写元素 ${args.index}，元素不是 input、textarea 或 contenteditable`)
     }
     // shadow DOM 内元素：inputTextElement 派发的合成事件 composed:false，
     // 补发 composed:true 事件确保事件委托框架（如 React）能收到

package/page-tools/handlers/searchTree.ts

@@ -1,23 +1,20 @@
 import { searchA11yTree } from '../a11y-tree'
 import { detectPageDialog, detectValidationErrors } from '../utils/dom'
-import { DEFAULT_ERROR_SELECTORS } from '../constants'
+import { getPageAgentToolConfig } from '../tool-config'
 import type { ActionContext } from '../context'
+import type { PageAgentToolInput } from '../schema'
 
-export async function handleSearchTree(args: any, ctx: ActionContext) {
+export async function handleSearchTree(args: PageAgentToolInput, ctx: ActionContext) {
   if (!args.query) return ctx.errContent('搜索失败: 缺少 query 参数')
-  const blacklist = (window.__webmcpcli_interactiveBlacklist ?? []) as Element[]
-  const whitelist = (window.__webmcpcli_interactiveWhitelist ?? []) as Element[]
-  const exposedAttributes = (window.__webmcpcli_exposedAttributes ?? []) as string[]
-  const result = searchA11yTree(args.query, document.body, blacklist, whitelist, {
+  const result = searchA11yTree(args.query, document.body, {
+    ...getPageAgentToolConfig().a11yConfig,
     contextLines: args.contextLines,
     maxMatches: args.maxMatches,
-    exposedAttributes,
-    errorSelectors: (window.__webmcpcli_errorSelectors ?? DEFAULT_ERROR_SELECTORS).join(', '),
   })
-  
+
   ctx.setRefMap(result.refMap)
   ctx.stateCache.update(window.location.href, result.yaml)
-  
+
   await ctx.pageController.hideMask()
   // 检测页面弹窗/遮罩层，帮助 AI 发现可能遮挡目标的确认弹窗
   const dialogAlert = detectPageDialog()

package/page-tools/handlers/select.ts

@@ -4,23 +4,28 @@ import type { ActionContext } from '../context'
 
 export async function handleSelect(args: any, ctx: ActionContext) {
   const mode = args.responseMode ?? 'diff'
-  if (args.index === undefined || typeof args.text !== 'string') return ctx.errContent('选择结果: 缺少元素索引或文本内容')
+  if (args.index === undefined || typeof args.text !== 'string')
+    return ctx.actionError('选择结果: 缺少元素索引或文本内容')
   let el = ctx.getRefMap().get(args.index) as HTMLSelectElement | HTMLElement | undefined
-  if (!el) return ctx.refreshOnStaleRef('选择', args.index)
+  if (!el) {
+    return ctx.actionError(
+      `选择失败: ref 索引 ${args.index} 已失效（页面可能已刷新），已自动重新加载页面状态，请使用新的 ref 索引重试。`
+    )
+  }
   // 若 ref 指向 shadow host，解析其内部真正的 <select>（与 fill 一致）
   let targetSelect: HTMLSelectElement | null = null
   if (el instanceof HTMLSelectElement) {
     targetSelect = el
   } else {
-    const innerSelect = el.querySelector('select')
-      ?? (el.shadowRoot?.querySelector('select') as HTMLSelectElement | null)
+    const innerSelect =
+      el.querySelector('select') ?? (el.shadowRoot?.querySelector('select') as HTMLSelectElement | null)
     if (innerSelect) {
       targetSelect = innerSelect
     }
   }
 
   if (!targetSelect) {
-    return ctx.errContent(`选择结果: 无法选择元素 ${args.index}，未找到对应的 <select> 元素`)
+    return ctx.actionError(`选择结果: 无法选择元素 ${args.index}，未找到对应的 <select> 元素`)
   }
 
   await selectOptionElement(targetSelect, args.text)

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

@@ -50,14 +50,62 @@ const injectStyles = `
       }
   `
 
-function isElementViewport(element: HTMLElement) {
-  const rect = element.getBoundingClientRect()
-  return (
-    rect.top >= 0 &&
-    rect.left >= 0 &&
-    rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) &&
-    rect.right <= (window.innerWidth || document.documentElement.clientWidth)
-  )
+/** 图标热区回退时父节点宽高上限，避免用到整行容器 */
+const MAX_ICON_FALLBACK_SIZE = 48
+
+export type HighlightRect = { top: number; left: number; width: number; height: number }
+
+/**
+ * 解析高亮矩形。
+ * Tiny3 `ti-icon` / `tp-icon` 字形常画在 ::before 上，宿主 getBoundingClientRect 宽或高为 0，
+ * 旧逻辑直接跳过导致帮助中心关闭/全屏等图标有 ref 却不高亮。
+ */
+export function resolveHighlightRect(el: HTMLElement): HighlightRect | null {
+  const rect = el.getBoundingClientRect()
+  if (rect.width > 0 && rect.height > 0) {
+    return { top: rect.top, left: rect.left, width: rect.width, height: rect.height }
+  }
+
+  // 优先用紧凑父节点（帮助中心 header 图标外包 28×28 的可点区域）
+  let parent: HTMLElement | null = el.parentElement
+  for (let depth = 0; depth < 3 && parent; depth++) {
+    const pr = parent.getBoundingClientRect()
+    if (
+      pr.width > 0 &&
+      pr.height > 0 &&
+      pr.width <= MAX_ICON_FALLBACK_SIZE &&
+      pr.height <= MAX_ICON_FALLBACK_SIZE
+    ) {
+      return { top: pr.top, left: pr.left, width: pr.width, height: pr.height }
+    }
+    parent = parent.parentElement
+  }
+
+  // 单边有尺寸时，用 font-size 补齐另一边
+  if (rect.width > 0 || rect.height > 0) {
+    try {
+      const fs = parseFloat(getComputedStyle(el).fontSize) || 16
+      const width = rect.width > 0 ? rect.width : fs
+      const height = rect.height > 0 ? rect.height : fs
+      return {
+        top: rect.height > 0 ? rect.top : rect.top - (height - rect.height) / 2,
+        left: rect.width > 0 ? rect.left : rect.left - (width - rect.width) / 2,
+        width,
+        height,
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return null
+}
+
+/** 与视口有交集即可（侧栏轻微负 left、贴边控件不应被整框剔除） */
+function isRectInViewport(rect: HighlightRect): boolean {
+  const vh = window.innerHeight || document.documentElement.clientHeight
+  const vw = window.innerWidth || document.documentElement.clientWidth
+  return rect.top < vh && rect.top + rect.height > 0 && rect.left < vw && rect.left + rect.width > 0
 }
 
 const doHighlight = (refMap: RefMap, parentIframe: HTMLIFrameElement | null = null) => {
@@ -87,23 +135,23 @@ const doHighlight = (refMap: RefMap, parentIframe: HTMLIFrameElement | null = nu
     iframeOffset.y = iframeRect.top
   }
   const fragment = document.createDocumentFragment()
-  const overlays = []
 
   // 3、 遍历 refMap
   for (const [index, el] of refMap.entries()) {
-    if (!isElementViewport(el)) continue
+    const rect = resolveHighlightRect(el)
+    if (!rect) continue
+
+    const top = rect.top + iframeOffset.y
+    const left = rect.left + iframeOffset.x
+    const viewportRect = { top, left, width: rect.width, height: rect.height }
+    if (!isRectInViewport(viewportRect)) continue
 
     const color = colors[index % colors.length]
     const textColor = color + opacity
 
-    const rect = el.getBoundingClientRect()
-    if (rect.width === 0 || rect.height === 0) continue
-
     const overlay = document.createElement('div')
     overlay.style.border = `2px solid ${textColor}`
-
-    const top = rect.top + iframeOffset.y
-    const left = rect.left + iframeOffset.x
+    overlay.dataset.refIndex = String(index)
 
     overlay.style.top = `${top}px`
     overlay.style.left = `${left}px`
@@ -113,13 +161,12 @@ const doHighlight = (refMap: RefMap, parentIframe: HTMLIFrameElement | null = nu
     // 文字
     const text = document.createElement('span')
     text.style.backgroundColor = textColor
-    text.style.height = `${rect.height - 4}px`
-    text.style.lineHeight = `${rect.height - 4}px`
+    text.style.height = `${Math.max(rect.height - 4, 0)}px`
+    text.style.lineHeight = `${Math.max(rect.height - 4, 0)}px`
     text.textContent = index.toString()
     overlay.appendChild(text)
 
     fragment.appendChild(overlay)
-    overlays.push({ element: overlay, initialRect: rect })
   }
 
   container.appendChild(fragment)

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

@@ -11,31 +11,15 @@ const injectStyles = `
 	z-index: 10000;
 }
 
-.webmcp-page-agent-cursorBorder {
-	position: absolute;
-	width: 100%;
-	height: 100%;
-	background: linear-gradient(45deg, rgb(57, 182, 255), rgb(189, 69, 251));
-	mask-image: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20100%20100'%20fill='none'%3e%3cg%3e%3cpath%20d='M%2015%2042%20L%2015%2036.99%20Q%2015%2031.99%2023.7%2031.99%20L%2028.05%2031.99%20Q%2032.41%2031.99%2032.41%2021.99%20L%2032.41%2017%20Q%2032.41%2012%2041.09%2016.95%20L%2076.31%2037.05%20Q%2085%2042%2076.31%2046.95%20L%2041.09%2067.05%20Q%2032.41%2072%2032.41%2062.01%20L%2032.41%2057.01%20Q%2032.41%2052.01%2023.7%2052.01%20L%2019.35%2052.01%20Q%2015%2052.01%2015%2047.01%20Z'%20fill='none'%20stroke='%23000000'%20stroke-width='6'%20stroke-miterlimit='10'%20style='stroke:%20light-dark(rgb(0,%200,%200),%20rgb(255,%20255,%20255));'/%3e%3c/g%3e%3c/svg%3e");
-	mask-size: 100% 100%;
-	mask-repeat: no-repeat;
-
-	transform-origin: center;
-	transform: rotate(-90deg) scale(0.8);
-	margin-left: -10px;
-	margin-top: -18px;
-}
-
 .webmcp-page-agent-cursorFilling {
 	position: absolute;
 	width: 100%;
 	height: 100%;
-	background: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20100%20100'%3e%3cdefs%3e%3c/defs%3e%3cg%20xmlns='http://www.w3.org/2000/svg'%20style='filter:%20drop-shadow(light-dark(rgba(0,%200,%200,%200.4),%20rgba(237,%20237,%20237,%200.4))%203px%204px%204px);'%3e%3cpath%20d='M%2015%2042%20L%2015%2036.99%20Q%2015%2031.99%2023.7%2031.99%20L%2028.05%2031.99%20Q%2032.41%2031.99%2032.41%2021.99%20L%2032.41%2017%20Q%2032.41%2012%2041.09%2016.95%20L%2076.31%2037.05%20Q%2085%2042%2076.31%2046.95%20L%2041.09%2067.05%20Q%2032.41%2072%2032.41%2062.01%20L%2032.41%2057.01%20Q%2032.41%2052.01%2023.7%2052.01%20L%2019.35%2052.01%20Q%2015%2052.01%2015%2047.01%20Z'%20fill='%23ffffff'%20stroke='none'%20style='fill:%20%23ffffff;'/%3e%3c/g%3e%3c/svg%3e");
-	background-size: 100% 100%;
+	background: url("data:image/svg+xml,%3Csvg%20viewBox%3D%270%200%2079.0834%2079.4553%27%20xmlns%3D%27http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%27%20%20width%3D%2779.083374%27%20height%3D%2779.455322%27%20fill%3D%27none%27%20%3E--%3Cdefs%3E%3Cfilter%20id%3D%27filter_0%27%20width%3D%2779.083374%27%20height%3D%2779.455322%27%20x%3D%270.000000%27%20y%3D%270.000000%27%20filterUnits%3D%27userSpaceOnUse%27%20%20color-interpolation-filters%3D%27sRGB%27%3E%3CfeFlood%20flood-opacity%3D%270%27%20result%3D%27BackgroundImageFix%27%20%2F%3E%3CfeOffset%20dx%3D%276.000000%27%20dy%3D%276.000000%27%20in%3D%27SourceAlpha%27%20%2F%3E%3CfeGaussianBlur%20stdDeviation%3D%276.66666651%27%20%2F%3E%3CfeColorMatrix%20type%3D%27matrix%27%20values%3D%270%200%200%200%200%200%200%200%200%200%200%200%200%200%200%200%200%200%200.18%200%20%27%20%2F%3E%3CfeBlend%20result%3D%27effect_dropShadow_1%27%20in2%3D%27BackgroundImageFix%27%20mode%3D%27normal%27%20%2F%3E%3CfeBlend%20result%3D%27shape%27%20in%3D%27SourceGraphic%27%20in2%3D%27effect_dropShadow_1%27%20mode%3D%27normal%27%20%2F%3E%3C%2Ffilter%3E%3ClinearGradient%20id%3D%27paint_linear_0%27%20x1%3D%2718.4743214%27%20x2%3D%2718.4213886%27%20y1%3D%27-1.86264515e-09%27%20y2%3D%2734.9221306%27%20gradientUnits%3D%27userSpaceOnUse%27%3E%3Cstop%20stop-color%3D%27rgb%28255%2C181%2C96%29%27%20offset%3D%270%27%20stop-opacity%3D%271%27%20%2F%3E%3Cstop%20stop-color%3D%27rgb%28255%2C120%2C114%29%27%20offset%3D%270.5%27%20stop-opacity%3D%271%27%20%2F%3E%3Cstop%20stop-color%3D%27rgb%28241%2C109%2C237%29%27%20offset%3D%271%27%20stop-opacity%3D%271%27%20%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Cg%20filter%3D%27url%28%23filter_0%29%27%3E%3Cpath%20d%3D%27M20.2632%203.57771L34.6257%2032.3027C35.4444%2033.9402%2033.8152%2035.7258%2032.1097%2035.0603L19.2014%2030.0229C18.7339%2029.8404%2018.2148%2029.8404%2017.7472%2030.0229L4.83891%2035.0603C3.13343%2035.7258%201.50423%2033.9402%202.32297%2032.3027L16.6855%203.57771C17.4225%202.10361%2019.5261%202.10361%2020.2632%203.57771Z%27%20fill%3D%27url%28%23paint_linear_0%29%27%20fill-rule%3D%27evenodd%27%20transform%3D%27matrix%280.719908%2C-0.69407%2C0.69407%2C0.719908%2C2.00256%2C28.0095%29%27%20%2F%3E%3Cpath%20d%3D%27M37.2169%2032.6848C37.1578%2032.189%2037.0096%2031.7039%2036.7723%2031.2294L22.4098%202.5044C22.1973%202.07946%2021.9328%201.70554%2021.6163%201.38261C21.3524%201.11342%2021.0524%200.879671%2020.7162%200.681366C20.3925%200.490407%2020.0558%200.34434%2019.7061%200.243163C19.312%200.129145%2018.9014%200.0721366%2018.4743%200.0721366C18.0472%200.0721366%2017.6367%200.129145%2017.2426%200.243163C16.8929%200.34434%2016.5562%200.490407%2016.2324%200.681366C15.8962%200.879671%2015.5962%201.11342%2015.3323%201.38261C15.0158%201.70553%2014.7513%202.07946%2014.5388%202.5044L0.176342%2031.2294C-0.0609121%2031.7039%20-0.209128%2032.189%20-0.268305%2032.6848C-0.316251%2033.0865%20-0.305747%2033.4951%20-0.236792%2033.9108C-0.171059%2034.307%20-0.0570567%2034.6809%200.105216%2035.0326C0.292784%2035.4391%200.544845%2035.8158%200.861397%2036.1627C1.17794%2036.5097%201.53001%2036.7951%201.91761%2037.0191C2.25297%2037.2128%202.61492%2037.3606%203.00348%2037.4623C3.41106%2037.5689%203.81704%2037.6168%204.22142%2037.6058C4.72053%2037.5922%205.21719%2037.4889%205.71141%2037.2961L18.4743%2032.3154L31.2372%2037.2961C31.7315%2037.4889%2032.2281%2037.5922%2032.7272%2037.6058C33.1316%2037.6168%2033.5376%2037.5689%2033.9452%2037.4623C34.3337%2037.3606%2034.6957%2037.2128%2035.0311%2037.0191C35.4187%2036.7951%2035.7707%2036.5097%2036.0873%2036.1627C36.4038%2035.8158%2036.6558%2035.4391%2036.8434%2035.0327C37.0057%2034.681%2037.1197%2034.307%2037.1854%2033.9108C37.2544%2033.4951%2037.2649%2033.0865%2037.2169%2032.6848ZM34.6257%2032.3027L20.2632%203.57771C19.5261%202.10361%2017.4225%202.10361%2016.6855%203.57771L2.32297%2032.3027C1.50423%2033.9402%203.13343%2035.7258%204.83891%2035.0603L17.7472%2030.0229C18.2148%2029.8404%2018.7339%2029.8404%2019.2014%2030.0229L32.1097%2035.0603C33.8152%2035.7258%2035.4444%2033.9402%2034.6257%2032.3027Z%27%20fill%3D%27rgb%28255%2C255%2C255%29%27%20fill-rule%3D%27evenodd%27%20transform%3D%27matrix%280.719908%2C-0.69407%2C0.69407%2C0.719908%2C2.00256%2C28.0095%29%27%20%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E");
+  background-size: 100% 100%;
 	background-repeat: no-repeat;
 
 	transform-origin: center;
-	transform: rotate(-90deg) scale(0.8);
 	margin-left: -10px;
 	margin-top: -18px;
 }
@@ -117,7 +101,10 @@ export class SimulatorMask extends EventTarget {
     try {
       const motion = new Motion({
         mode: isPageDark() ? 'dark' : 'light',
-        styles: { position: 'absolute', inset: '0' }
+        styles: { position: 'absolute', inset: '0' },
+        glowWidth: 80,
+        borderWidth: 8,
+        colors: ['rgb(121, 216, 247)', 'rgb(171, 219, 110)', 'rgb(252, 188, 114)', 'rgb(235, 117, 231)']
       })
       this.motion = motion
       this.wrapper.appendChild(motion.element)
@@ -186,9 +173,9 @@ export class SimulatorMask extends EventTarget {
     this.#cursor.appendChild(fillingLayer)
 
     // Create border layer
-    const borderLayer = document.createElement('div')
-    borderLayer.className = 'webmcp-page-agent-cursorBorder'
-    this.#cursor.appendChild(borderLayer)
+    // const borderLayer = document.createElement('div')
+    // borderLayer.className = 'webmcp-page-agent-cursorBorder'
+    // this.#cursor.appendChild(borderLayer)
 
     this.wrapper.appendChild(this.#cursor)
   }
@@ -276,4 +263,37 @@ export class SimulatorMask extends EventTarget {
     this.wrapper.remove()
     this.dispatchEvent(new Event('dispose'))
   }
+  // 根据目标元素大小，在 wrapper 添加绝对定位边框：2px 宽、与目标间距 2px，对角渐变 (0,0 → 1,1)
+  borderElement(targetElement: HTMLElement) {
+    if (!targetElement) return
+
+    this.wrapper.querySelector('.webmcp-page-agent-border')?.remove()
+
+    const rect = targetElement.getBoundingClientRect()
+    const gap = 2
+    const borderWidth = 2
+    const offset = gap + borderWidth
+
+    const el = document.createElement('div')
+    el.className = 'webmcp-page-agent-border'
+    el.style.position = 'absolute'
+    el.style.left = `${rect.left - offset}px`
+    el.style.top = `${rect.top - offset}px`
+    el.style.width = `${rect.width + offset * 2}px`
+    el.style.height = `${rect.height + offset * 2}px`
+    el.style.boxSizing = 'border-box'
+    el.style.pointerEvents = 'none'
+    el.style.zIndex = '10000'
+    el.style.border = `${borderWidth}px solid transparent`
+    // 对角渐变：左上 (0,0) → 右下 (1,1)
+    el.style.borderImageSource = 'linear-gradient(to bottom right, #79D8F7, #ABDB6E, #FCBC72, #FA8682, #EB75E7)'
+    el.style.borderImageSlice = '1'
+    el.style.borderImageWidth = `${borderWidth}px`
+
+    this.wrapper.appendChild(el)
+  }
+
+  removeBorderElement() {
+    this.wrapper.querySelector('.webmcp-page-agent-border')?.remove()
+  }
 }

package/page-tools/page-agent-mask/hauwei.svg

@@ -0,0 +1,25 @@
+<svg viewBox="0 0 79.0834 79.4553" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="79.083374" height="79.455322" fill="none" customFrame="#000000">
+--
+<defs>
+<g id="pixso_custom_effect_0">
+<effect x="6.000000" y="6.000000" visibility="visible" fill="rgb(0,0,0)" fill-opacity="0.180000007" effectType="dropShadow" stdDeviation="20" radius="0" />
+</g>
+<filter id="filter_0" width="79.083374" height="79.455322" x="0.000000" y="0.000000" filterUnits="userSpaceOnUse" customEffect="url(#pixso_custom_effect_0)" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix" />
+<feOffset dx="6.000000" dy="6.000000" in="SourceAlpha" />
+<feGaussianBlur stdDeviation="6.66666651" />
+<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.18 0 " />
+<feBlend result="effect_dropShadow_1" in2="BackgroundImageFix" mode="normal" />
+<feBlend result="shape" in="SourceGraphic" in2="effect_dropShadow_1" mode="normal" />
+</filter>
+<linearGradient id="paint_linear_0" x1="18.4743214" x2="18.4213886" y1="-1.86264515e-09" y2="34.9221306" gradientUnits="userSpaceOnUse">
+<stop stop-color="rgb(255,181,96)" offset="0" stop-opacity="1" />
+<stop stop-color="rgb(255,120,114)" offset="0.5" stop-opacity="1" />
+<stop stop-color="rgb(241,109,237)" offset="1" stop-opacity="1" />
+</linearGradient>
+</defs>
+<g filter="url(#filter_0)">
+<path id="多边形 11" d="M20.2632 3.57771L34.6257 32.3027C35.4444 33.9402 33.8152 35.7258 32.1097 35.0603L19.2014 30.0229C18.7339 29.8404 18.2148 29.8404 17.7472 30.0229L4.83891 35.0603C3.13343 35.7258 1.50423 33.9402 2.32297 32.3027L16.6855 3.57771C17.4225 2.10361 19.5261 2.10361 20.2632 3.57771Z" fill="url(#paint_linear_0)" fill-rule="evenodd" transform="matrix(0.719908,-0.69407,0.69407,0.719908,2.00256,28.0095)" />
+<path id="多边形 11" d="M37.2169 32.6848C37.1578 32.189 37.0096 31.7039 36.7723 31.2294L22.4098 2.5044C22.1973 2.07946 21.9328 1.70554 21.6163 1.38261C21.3524 1.11342 21.0524 0.879671 20.7162 0.681366C20.3925 0.490407 20.0558 0.34434 19.7061 0.243163C19.312 0.129145 18.9014 0.0721366 18.4743 0.0721366C18.0472 0.0721366 17.6367 0.129145 17.2426 0.243163C16.8929 0.34434 16.5562 0.490407 16.2324 0.681366C15.8962 0.879671 15.5962 1.11342 15.3323 1.38261C15.0158 1.70553 14.7513 2.07946 14.5388 2.5044L0.176342 31.2294C-0.0609121 31.7039 -0.209128 32.189 -0.268305 32.6848C-0.316251 33.0865 -0.305747 33.4951 -0.236792 33.9108C-0.171059 34.307 -0.0570567 34.6809 0.105216 35.0326C0.292784 35.4391 0.544845 35.8158 0.861397 36.1627C1.17794 36.5097 1.53001 36.7951 1.91761 37.0191C2.25297 37.2128 2.61492 37.3606 3.00348 37.4623C3.41106 37.5689 3.81704 37.6168 4.22142 37.6058C4.72053 37.5922 5.21719 37.4889 5.71141 37.2961L18.4743 32.3154L31.2372 37.2961C31.7315 37.4889 32.2281 37.5922 32.7272 37.6058C33.1316 37.6168 33.5376 37.5689 33.9452 37.4623C34.3337 37.3606 34.6957 37.2128 35.0311 37.0191C35.4187 36.7951 35.7707 36.5097 36.0873 36.1627C36.4038 35.8158 36.6558 35.4391 36.8434 35.0327C37.0057 34.681 37.1197 34.307 37.1854 33.9108C37.2544 33.4951 37.2649 33.0865 37.2169 32.6848ZM34.6257 32.3027L20.2632 3.57771C19.5261 2.10361 17.4225 2.10361 16.6855 3.57771L2.32297 32.3027C1.50423 33.9402 3.13343 35.7258 4.83891 35.0603L17.7472 30.0229C18.2148 29.8404 18.7339 29.8404 19.2014 30.0229L32.1097 35.0603C33.8152 35.7258 35.4444 33.9402 34.6257 32.3027Z" fill="rgb(255,255,255)" fill-rule="evenodd" transform="matrix(0.719908,-0.69407,0.69407,0.719908,2.00256,28.0095)" />
+</g>
+</svg>

package/page-tools/page-agent-prompt.md

@@ -43,7 +43,7 @@
 - `- role #N [token1] [token2] "accessible name"`
 - `role`：ARIA 语义角色（如 button/link/radio/heading/listitem/generic 等）
 - `#N`：可交互元素的唯一操作索引，**只有带 `#N` 的节点才能被操作**，操作时将 N 作为 `index` 参数传入
-- `[token]`：可选 token，包括状态标记（如 `[checked]` `[selected]` `[disabled]` `[cursor=pointer]`）和定制属性（如 `[cf-uba="..."]`）
+- `[token]`：可选 token，包括状态标记（如 `[checked]` `[selected]` `[pressed]` `[current]` `[expanded]` `[disabled]` `[readonly]` `[required]` `[invalid]` `[busy]` `[error]` `[warning]` `[cursor=pointer]`）和定制属性（如 `[cf-uba="..."]`）
 - `"accessible name"`：元素的语义化名称，**用双引号包裹**（通过 aria-label/aria-labelledby/innerText 等计算得出）；无名称的节点此字段省略
 - 缩进表示父子关系
 

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

@@ -0,0 +1,113 @@
+import { inputSchema, type PageAgentToolInput, type PageAgentToolRawInput } from './schema'
+import { PageController } from '@page-agent/page-controller'
+
+export const PAGE_AGENT_TOOL_CALL_EVENT = 'page-agent-tool-call'
+export const PAGE_AGENT_TOOL_RESULT_EVENT = 'page-agent-tool-result'
+export 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>
+
+function isPageAgentToolErrorResult(result: unknown): result is { isError: true; error: string } {
+  return (
+    typeof result === 'object' &&
+    result !== null &&
+    'isError' in result &&
+    result.isError === true &&
+    'error' in result &&
+    typeof result.error === 'string'
+  )
+}
+
+declare global {
+  interface Window {
+    __nextSdkPageAgentToolEventCleanup?: () => void
+  }
+}
+
+function dispatchPageAgentToolResult(detail: PageAgentToolResultEventDetail) {
+  window.dispatchEvent(new CustomEvent(PAGE_AGENT_TOOL_RESULT_EVENT, { detail }))
+}
+
+export function setupPageAgentToolEventBridge(
+  executePageAgentTool: ExecutePageAgentTool,
+  pageController: PageController
+) {
+  window.__nextSdkPageAgentToolEventCleanup?.()
+
+  const handleToolCall = async (event: Event) => {
+    const detail = (event as CustomEvent<PageAgentToolCallEventDetail>).detail
+    const requestId = detail?.requestId
+
+    if (!requestId) {
+      dispatchPageAgentToolResult({
+        requestId: '',
+        data: {
+          success: false,
+          error: '缺少 requestId'
+        }
+      })
+      return
+    }
+
+    try {
+      const data = inputSchema.parse(detail.data)
+      const result = await executePageAgentTool(data)
+      if (isPageAgentToolErrorResult(result)) {
+        dispatchPageAgentToolResult({
+          requestId,
+          data: {
+            success: false,
+            error: result.error,
+            result
+          }
+        })
+        return
+      }
+      dispatchPageAgentToolResult({
+        requestId,
+        data: {
+          success: true,
+          result
+        }
+      })
+    } catch (error) {
+      dispatchPageAgentToolResult({
+        requestId,
+        data: {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        }
+      })
+    }
+  }
+
+  // 聊天结束事件，用于在聊天结束时移除遮罩
+  const handleChatEnd = async () => {
+    try {
+      await pageController.hideMask()
+    } catch (error) {}
+  }
+
+  window.addEventListener(PAGE_AGENT_TOOL_CALL_EVENT, handleToolCall)
+  window.addEventListener(PAGE_AGENT_CHAT_END_EVENT, handleChatEnd)
+
+  window.__nextSdkPageAgentToolEventCleanup = () => {
+    window.removeEventListener(PAGE_AGENT_TOOL_CALL_EVENT, handleToolCall)
+    window.removeEventListener(PAGE_AGENT_CHAT_END_EVENT, handleChatEnd)
+    window.__nextSdkPageAgentToolEventCleanup = undefined
+  }
+}