@opentiny/next-sdk 0.4.1 → 0.4.2

package/page-tools/a11y/constants.ts

@@ -25,6 +25,27 @@ export const DEFAULT_WARNING_SELECTORS = [
   '.warning-msg', '.warning-text', '.is-warning', '.has-warning',
 ]
 
+/** 模态弹窗默认选择器：ARIA 标准 + 主流 UI 框架（唯一来源，顶层 constants.ts 从此处重新导出） */
+export const DEFAULT_DIALOG_SELECTORS = [
+  // 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"]',
+]
+
 // ─── ARIA 隐式角色静态映射表（覆盖页面 95%+ 的常用标签）───────────────────────
 
 export const TAG_ROLE_MAP: Record<string, string> = {

package/page-tools/a11y/search.ts

@@ -24,8 +24,6 @@ import { buildA11yTree } from './build'
 export function searchA11yTree(
   query: string,
   root: Element = document.body,
-  blacklist: Element[] = [],
-  whitelist: Element[] = [],
   options?: SearchA11yTreeOptions,
 ): SearchA11yTreeResult {
   const {
@@ -39,7 +37,7 @@ export function searchA11yTree(
   const safeMaxMatches = Math.max(1, maxMatches)
 
   // 复用 buildA11yTree 生成完整树，直接取 lines 数组（不重复构建 DOM 遍历）
-  const { lines, refMap, yaml } = buildA11yTree(root, blacklist, whitelist, treeOptions)
+  const { lines, refMap, yaml } = buildA11yTree(root, treeOptions)
 
   const needle = caseInsensitive ? query.toLowerCase() : query
   const totalLines = lines.length

package/page-tools/a11y/types.ts

@@ -4,6 +4,8 @@
  * 定义无障碍树模块（A11y Tree）的核心接口和类型。
  */
 
+import type { A11yConfig } from './config'
+
 /** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
 export type RefMap = Map<number, HTMLElement>
 
@@ -23,8 +25,12 @@ export interface VNode {
   children: VNode[]
 }
 
-/** 构建无障碍树时的配置选项 */
-export interface A11yTreeOptions {
+/**
+ * 构建无障碍树时的配置选项。
+ * 继承统一的 A11yConfig（角色/状态规则、白/黑名单、自定义暴露属性、弹窗选择器），
+ * 并额外提供两个控制树"形状"（而非无障碍语义）的选项。
+ */
+export interface A11yTreeOptions extends A11yConfig {
   /**
    * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
    * 默认 true（推荐）
@@ -35,21 +41,12 @@ 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[]
 }
 
 /** 构建无障碍树的返回结果 */

package/page-tools/a11y/utils.ts

@@ -1,181 +1,137 @@
 /**
  * a11y/utils.ts
  *
- * 存放生成无障碍树时的通用工具函数：节点解析、状态获取、角色推断及纯文本兜底等。
+ * 存放生成无障碍树时的通用工具函数：可见性判断、纯文本兜底、Shadow DOM 组合树遍历等。
+ * 角色推断与状态 token 解析已统一迁移到 ./config（resolveA11yRole/resolveA11yStates/resolveA11yInfo）。
  */
 
-import { isFocusable, isTabbable } from 'tabbable'
-import { TAG_ROLE_MAP, INPUT_TYPE_ROLE, DEFAULT_ERROR_SELECTORS, DEFAULT_WARNING_SELECTORS } from './constants'
+import { isTabbable } from 'tabbable'
+import { resolveA11yRole, type ResolvedA11yConfig } from './config'
+import { deepQuerySelectorAll } from '../utils/dom'
 
 /**
- * 获取元素的 ARIA 角色
- * 优先级：显式 role 属性 > 标签隐式角色 > 'generic'
+ * 非内容元素：不应进入无障碍树，其内部文本也不得被 AccName / textContent 兜底吸收。
+ * 云控制台常见在 body 内联 `<style>@font-face { src: url(data:font/...;base64,...) }</style>`，
+ * 若不剔除，整段 base64 会变成 generic 的 name，严重浪费 LLM token。
  */
-export function inferRole(el: Element): string {
-  const explicit = el.getAttribute('role')
-  if (explicit && explicit !== 'presentation' && explicit !== 'none') {
-    return explicit
-  }
-  const tag = el.tagName.toLowerCase()
-  if (tag === 'input') {
-    const inputType = (el as HTMLInputElement).type?.toLowerCase() ?? 'text'
-    return INPUT_TYPE_ROLE[inputType] ?? 'textbox'
-  }
-  return TAG_ROLE_MAP[tag] ?? 'generic'
+const NON_CONTENT_TAGS = new Set([
+  'script',
+  'style',
+  'noscript',
+  'template',
+  'link',
+  'meta',
+  'head',
+  'title',
+])
+
+export function isNonContentElement(el: Element): boolean {
+  return NON_CONTENT_TAGS.has(el.tagName.toLowerCase())
 }
 
 /**
- * 收集节点的 ARIA 状态 token
- * 格式：[checked] [selected] [disabled] [hasPopup] [cursor=pointer] [value="..."]
+ * 判断元素是否"自身"呈现 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 function getStateTokens(
-  el: Element,
-  exposedAttributes?: string[],
-  errorSelectors?: string | string[],
-  warningSelectors?: string | string[],
-): string[] {
-  const tokens: string[] = []
-  const aria = (k: string) => el.getAttribute(k)
-
-  // 选中状态：优先 aria-checked，其次原生 input.checked
-  // 对 <label for="X"> 检测关联 checkbox/radio 的选中状态，帮助 AI 识别复选框当前状态
-  const ariaChecked = aria('aria-checked')
-  if (ariaChecked === 'true') {
-    tokens.push('checked')
-  } else if (ariaChecked === 'false') {
-    tokens.push('unchecked')
-  } else {
-    const elTag = el.tagName.toLowerCase()
-    let nativeChecked: boolean | undefined
-    if (elTag === 'input' && ((el as HTMLInputElement).type === 'checkbox' || (el as HTMLInputElement).type === 'radio')) {
-      nativeChecked = (el as HTMLInputElement).checked
-    } else if (elTag === 'label' && el.hasAttribute('for')) {
-      const target = document.getElementById(el.getAttribute('for')!)
-      if (target instanceof HTMLInputElement && (target.type === 'checkbox' || target.type === 'radio')) {
-        nativeChecked = target.checked
-      }
-    }
-    if (nativeChecked !== undefined) {
-      tokens.push(nativeChecked ? 'checked' : 'unchecked')
-    }
-  }
-
-  if (aria('aria-selected') === 'true') tokens.push('selected')
-
-  const disabled = aria('aria-disabled') === 'true' || (el as HTMLInputElement).disabled
-  if (disabled) tokens.push('disabled')
-
-  const hasPopup = aria('aria-haspopup')
-  if (hasPopup && hasPopup !== 'false') tokens.push('hasPopup')
-
-  if (aria('aria-expanded') === 'true') tokens.push('expanded')
-
-  // heading level（h1-h6）
-  const headingMatch = el.tagName.match(/^H([1-6])$/)
-  if (headingMatch) tokens.push(`level=${headingMatch[1]}`)
-  const ariaLevel = aria('aria-level')
-  if (ariaLevel && !headingMatch) tokens.push(`level=${ariaLevel}`)
-
-  // cursor=pointer 表示"视觉上可点击"
+export function hasOwnPointerCursor(el: Element): boolean {
   try {
-    const style = window.getComputedStyle(el as HTMLElement)
-    if (style.cursor === 'pointer') tokens.push('cursor=pointer')
+    if (window.getComputedStyle(el as HTMLElement).cursor !== 'pointer') return false
+    const parent = el.parentElement
+    if (!parent) return true
+    return window.getComputedStyle(parent).cursor !== 'pointer'
   } catch {
-    // 某些元素 getComputedStyle 可能抛异常，忽略
-  }
-
-  // 记录输入元素的值，以便在 fill/输入后在 A11y 树中显示并产生 Diff
-  const tag = el.tagName.toLowerCase()
-  if (tag === 'input' || tag === 'textarea' || tag === 'select') {
-    const val = (el as HTMLInputElement).value
-    if (val !== undefined && val !== '') {
-      tokens.push(`value="${val}"`)
-    }
-  }
-  const valuenow = el.getAttribute('aria-valuenow')
-  if (valuenow) {
-    tokens.push(`valuenow="${valuenow}"`)
-  }
-
-  // link 元素：检测 target=_blank，提示 Agent 该链接会在新标签页打开
-  if (el.tagName.toLowerCase() === 'a' && el.getAttribute('target') === '_blank') {
-    tokens.push('opens-new-tab')
+    // 忽略跨域 iframe 等无法访问 style 的场景
+    return false
   }
+}
 
-  // 检测 CSS 激活/选中状态类名（用于未使用标准 ARIA 的 Tab/选项组件，如华为云镜像选择）
-  // 若元素携带常见激活类名，输出 [active] token，帮助 Agent 判断当前选中项
-  const cls = typeof el.className === 'string' ? el.className : ''
-  const ACTIVE_CLASS_PATTERNS = [
-    'is-active', 'isActive',
-    'is-selected', 'isSelected',
-    'is-current', 'isCurrent',
-    'active-item', 'activeItem',
-    'tab-active', 'tabActive',
-    // 仅当作为独立 class 词或有连字符前缀时匹配 "active"，避免误匹配 "interactive" 等
-    /\bactive\b/,
-    /\bselected\b/,
-    /\bcurrent\b/,
-  ]
-  const hasActiveClass = ACTIVE_CLASS_PATTERNS.some(p =>
-    typeof p === 'string' ? cls.split(/\s+/).includes(p) : p.test(cls)
-  )
-  // 只对有 cursor=pointer 或明确角色的元素输出 active token，避免太多噪音
-  const roleForActive = el.getAttribute('role') || el.tagName.toLowerCase()
-  const roles = roleForActive.split(/\s+/)
-  const isTabLike = roles.some(r => ['button', 'option', 'a', 'li', 'generic'].includes(r) || r.startsWith('tab'))
-  if (hasActiveClass && isTabLike && !tokens.includes('checked') && !tokens.includes('selected')) {
-    tokens.push('active')
-  }
+/** 交互态伪类：cursor 常只在这些状态下声明为 pointer（如卡片 hover 时才显示手势） */
+const INTERACTION_PSEUDO_RE = /:(hover|focus|focus-visible|focus-within|active)\b/gi
 
-  // 检测校验错误/警告状态（ARIA 标准 + 主流 UI 框架，可配置）
-  // 输出 [error] / [warning] token，让 AI 能区分校验错误与普通说明文字
-  // 使用 closest() 向上查找，确保嵌套在错误容器内的子元素也能获得 error 语义
-  const errorSelector = Array.isArray(errorSelectors)
-    ? errorSelectors.join(', ')
-    : (errorSelectors || DEFAULT_ERROR_SELECTORS.join(', '))
-  const warningSelector = Array.isArray(warningSelectors)
-    ? warningSelectors.join(', ')
-    : (warningSelectors || DEFAULT_WARNING_SELECTORS.join(', '))
-  let errorAncestor = null
-  if (errorSelector) {
-    try {
-      errorAncestor = el.closest(errorSelector)
-    } catch {
-      // ignore
+/**
+ * 递归遍历样式表规则（含 @media / @supports 等分组规则），收集在交互伪类下声明
+ * cursor:pointer 的选择器，并去掉伪类得到"主体选择器"。
+ */
+function collectInteractivePointerSelectors(rules: CSSRuleList, out: Set<string>): void {
+  for (const rule of Array.from(rules)) {
+    const styleRule = rule as CSSStyleRule
+    const grouping = rule as CSSGroupingRule
+    // @media / @supports 等分组规则：自身无 selectorText，递归其子规则
+    if (!styleRule.selectorText && grouping.cssRules) {
+      collectInteractivePointerSelectors(grouping.cssRules, out)
+      continue
+    }
+    const sel = styleRule.selectorText
+    if (!sel || !styleRule.style || styleRule.style.cursor !== 'pointer') continue
+    if (!/:(hover|focus|focus-visible|focus-within|active)\b/i.test(sel)) continue
+    for (const part of sel.split(',')) {
+      const base = part.replace(INTERACTION_PSEUDO_RE, '').trim()
+      // 去掉伪类后可能为空（如 `:hover`）或过宽（`*`），跳过以免误伤全页
+      if (base && base !== '*') out.add(base)
     }
   }
-  
-  if (errorAncestor) {
-    tokens.push('error')
-  } else {
-    let warningAncestor = null
-    if (warningSelector) {
+}
+
+/**
+ * 收集页面中"仅在 :hover/:focus/:active 等交互态下声明 cursor:pointer"的元素集合。
+ *
+ * 背景（华为云控制台实测）：大量可点击卡片（如 `.container-wrapper .shadow:hover{cursor:pointer}`）
+ * 只在鼠标悬停时才显示手势，静止态 `getComputedStyle(el).cursor` 读到的是 `auto`，
+ * 因此仅凭 computed cursor 的判定（含业界 getComputedStyle 方案）会漏判这类元素。
+ * 这里通过扫描样式表把这类"交互态手势"补齐，作为可点击性的兜底信号。
+ *
+ * 每次构建树只调用一次（O(规则数) 扫描 + 一次合并查询），避免逐元素扫描样式表。
+ */
+export function collectHoverPointerElements(root: Element): Set<Element> {
+  const set = new Set<Element>()
+  const selectorSet = new Set<string>()
+  try {
+    for (const sheet of Array.from(document.styleSheets)) {
+      let rules: CSSRuleList | null = null
       try {
-        warningAncestor = el.closest(warningSelector)
+        rules = sheet.cssRules
       } catch {
-        // ignore
+        // 跨域样式表无法访问 cssRules，跳过
+        continue
       }
+      if (rules) collectInteractivePointerSelectors(rules, selectorSet)
     }
-    if (warningAncestor) {
-      tokens.push('warning')
-    }
+  } catch {
+    return set
   }
+  if (selectorSet.size === 0) return set
 
-  // 额外暴露的自定义属性白名单
-  if (exposedAttributes) {
-    for (const attr of exposedAttributes) {
-      const val = el.getAttribute(attr)
-      if (val !== null) {
-        tokens.push(`${attr}="${val}"`)
+  const selectors = Array.from(selectorSet)
+  // 优先合并为单条选择器一次性查询；若含非法片段导致整体失败，退化为逐条查询保证鲁棒
+  try {
+    for (const el of deepQuerySelectorAll(selectors.join(', '), root)) set.add(el)
+    return set
+  } catch {
+    for (const sel of selectors) {
+      try {
+        for (const el of deepQuerySelectorAll(sel, root)) set.add(el)
+      } catch {
+        // 忽略非法选择器
       }
     }
   }
-
-  return tokens
+  return set
 }
 
-/** 判断元素是否应被跳过（不可见或在黑名单中） */
+/** 判断元素是否应被跳过（不可见、非内容或在黑名单中） */
 export function isHidden(el: Element): boolean {
+  if (isNonContentElement(el)) return true
   if (el.getAttribute('aria-hidden') === 'true') return true
   if ((el as HTMLElement).hidden) return true
   try {
@@ -196,32 +152,49 @@ export function isHidden(el: Element): boolean {
 }
 
 
+/**
+ * 收集元素自身或子孙节点的 title，用作图标按钮等无文本节点的名字兜底。
+ * 云控制台常见模式：可点击容器无 aria-label，title 挂在内部 span 上。
+ */
+export function collectTitleLabel(el: Element): string {
+  const selfTitle = el.getAttribute('title')?.trim()
+  if (selfTitle) return selfTitle
+
+  const titled = el.querySelector('[title]')
+  const childTitle = titled?.getAttribute('title')?.trim()
+  if (childTitle) return childTitle
+
+  return ''
+}
+
 /**
  * 收集子孙节点的文本内容，用作无障碍名字的兜底。
  * 当普通计算无法提取文本时，遍历后代并拼接可见文本。
+ * @param config 已规整的无障碍配置；传入后角色判断会尊重页面自定义 roles 规则
  */
-export function collectDescendantText(el: Element): string {
+export function collectDescendantText(el: Element, config?: ResolvedA11yConfig): string {
   let text = ''
   const walk = (node: Node) => {
     if (node.nodeType === Node.TEXT_NODE) {
       text += (node.textContent ?? '') + ' '
     } else if (node.nodeType === Node.ELEMENT_NODE) {
       const element = node as Element
-      if (isHidden(element)) return
+      // 根节点若是 style/script 则整段丢弃；子孙遇到非内容标签则跳过子树
+      if (element !== el && isNonContentElement(element)) return
+      if (isHidden(element) && element !== el) return
+      // 根为非内容元素时不收集（防御）
+      if (element === el && isNonContentElement(element)) return
 
       // 如果遇到嵌套的列表项或其他交互/语义节点，停止向下遍历该子树，避免兜底文本重复吸收
       if (element !== el) {
         const tag = element.tagName.toLowerCase()
-        const role = inferRole(element)
+        const role = resolveA11yRole(element, config)
         const isInteractiveTag = ['button', 'a', 'input', 'select', 'textarea', 'li', 'option'].includes(tag)
         const isInteractiveRole = ['button', 'link', 'checkbox', 'radio', 'textbox', 'listitem', 'option', 'combobox', 'listbox'].includes(role)
         const isTrulyInteractive = isTabbable(element as HTMLElement)
-        let isCursorPointer = false
-        try {
-          isCursorPointer = window.getComputedStyle(element as HTMLElement).cursor === 'pointer'
-        } catch { /* ignore */ }
-        const isMeaningfullyInteractive = isTrulyInteractive && !(role === 'generic' && !isCursorPointer)
-        
+        const isOwnPointer = hasOwnPointerCursor(element)
+        const isMeaningfullyInteractive = isTrulyInteractive && !(role === 'generic' && !isOwnPointer)
+
         if (isMeaningfullyInteractive || isInteractiveTag || isInteractiveRole) {
           return
         }