dp-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{dp_cli-0.3.0 → dp_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more.
 License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mofanx/dp-cli
@@ -119,8 +119,13 @@ Results are deduplicated by `backendNodeId` and rendered with confidence markers
 | Marker | Confidence | Triggers |
 |--------|-----------|----------|
 | none   | **high**   | `<a href>`, `<button>`, `<input>`, `role=button/link/...`, `contenteditable` |
-| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>` |
-| `?`    | **low**    | `cursor:pointer` / class keyword match (`btn` / `click` / `toggle` / …) |
+| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>`, or `cursor:pointer` + heuristic (aria-label / icon child / small square / class keyword) — **catches most React/Vue icon buttons** |
+| `?`    | **low**    | bare `cursor:pointer` / class keyword only (no other signals); hidden unless `--include-low` |
+
+Output includes helpful context:
+- `@top-left`, `@top-right`, `@center`, `@bottom` … — position in the 9-region viewport grid
+- `(icon)` — icon-only button (no visible label, has `<svg>` / `<img>` child)
+- Shadow DOM is traversed automatically (open shadow roots)
 
 Every element gets an `[N]` ref usable in any command: `dp click "ref:5"`.
 

{dp_cli-0.3.0 → dp_cli-0.3.1}/README.md

@@ -98,8 +98,13 @@ Results are deduplicated by `backendNodeId` and rendered with confidence markers
 | Marker | Confidence | Triggers |
 |--------|-----------|----------|
 | none   | **high**   | `<a href>`, `<button>`, `<input>`, `role=button/link/...`, `contenteditable` |
-| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>` |
-| `?`    | **low**    | `cursor:pointer` / class keyword match (`btn` / `click` / `toggle` / …) |
+| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>`, or `cursor:pointer` + heuristic (aria-label / icon child / small square / class keyword) — **catches most React/Vue icon buttons** |
+| `?`    | **low**    | bare `cursor:pointer` / class keyword only (no other signals); hidden unless `--include-low` |
+
+Output includes helpful context:
+- `@top-left`, `@top-right`, `@center`, `@bottom` … — position in the 9-region viewport grid
+- `(icon)` — icon-only button (no visible label, has `<svg>` / `<img>` child)
+- Shadow DOM is traversed automatically (open shadow roots)
 
 Every element gets an `[N]` ref usable in any command: `dp click "ref:5"`.
 

{dp_cli-0.3.0 → dp_cli-0.3.1}/dp_cli/commands/snapshot_cmd.py

@@ -105,7 +105,9 @@ def register(cli):
     @click.option('--format', 'fmt', type=click.Choice(['text', 'json']),
                   default='text', show_default=True, help='输出格式')
     @click.option('--filename', default=None, help='保存到文件路径')
-    def scan(session, viewport_only, confidence, max_elements, fmt, filename):
+    @click.option('--verbose', '-v', is_flag=True, default=False,
+                  help='显示 detection reason 和像素尺寸（调试用）')
+    def scan(session, viewport_only, confidence, max_elements, fmt, filename, verbose):
         """Vimium 风格扫描当前页面的可交互元素（纯 DOM 遍历，不依赖 a11y tree）。
 
         \b
@@ -188,40 +190,26 @@ def register(cli):
             f'{len(filtered)} after filter'
             + (' (truncated)' if data.get('truncated') else '')
         )
-        rendered_lines.append('- 用 ref:N 引用元素（⚡ = medium, ? = low）')
+        rendered_lines.append(
+            '- ⚡ = medium, ? = low；@zone = 位置区域（top-left/top-right/… 9 宫格）；'
+            '(icon) = 仅图标按钮；用 ref:N 引用'
+        )
         rendered_lines.append('')
 
-        # 置信度标记
-        marker_map = {'high': '', 'medium': '⚡ ', 'low': '? '}
+        from ..snapshot.clickable import format_clickable_record
 
         for i, rec in enumerate(filtered, start=1):
             refs[str(i)] = {
                 'locator': rec.get('locator') or '',
                 'role': f"clickable/{rec.get('tag', '')}",
-                'name': (rec.get('text') or '')[:100],
+                'name': (rec.get('label') or rec.get('text') or '')[:100],
                 'backendNodeId': rec.get('backendNodeId'),
                 'confidence': rec.get('confidence'),
                 'reason': rec.get('reason'),
+                'zone': rec.get('zone'),
+                'iconOnly': bool(rec.get('iconOnly')),
             }
-            marker = marker_map.get(rec.get('confidence'), '')
-            tag = rec.get('tag', '')
-            text = (rec.get('text') or '').strip()
-            reason = rec.get('reason') or ''
-            rect = rec.get('rect') or {}
-            loc = rec.get('locator') or ''
-
-            parts = [f'- [{i}] {marker}{tag}']
-            if text:
-                disp = text[:80] + '…' if len(text) > 80 else text
-                parts.append(f'"{disp}"')
-            meta_bits = [reason]
-            if rect.get('w'):
-                meta_bits.append(f'{rect["w"]}x{rect["h"]}')
-                meta_bits.append(f'@{rect.get("x", 0)},{rect.get("y", 0)}')
-            parts.append(f'({", ".join(meta_bits)})')
-            if loc:
-                parts.append(f'→ {loc}')
-            rendered_lines.append(' '.join(parts))
+            rendered_lines.append('- ' + format_clickable_record(rec, i, verbose=verbose))
 
         # 保存 refs 到 session
         if refs:

{dp_cli-0.3.0 → dp_cli-0.3.1}/dp_cli/snapshot/a11y.py

@@ -219,7 +219,7 @@ def render_a11y_text(snapshot: dict, verbose: bool = False,
     # ── 追加 clickable_extras（a11y tree 漏掉的可交互元素）──
     extras = snapshot.get('clickable_extras') or []
     if extras:
-        from .clickable import CONFIDENCE_MARKER
+        from .clickable import format_clickable_record
         lines.append('')
         meta = snapshot.get('clickable_meta') or {}
         header_suffix = []
@@ -232,38 +232,23 @@ def render_a11y_text(snapshot: dict, verbose: bool = False,
         lines.append(f'### Additional Interactive Elements'
                      f' (Vimium-style, not in a11y tree){suffix_str}')
         lines.append(f'- 共 {len(extras)} 个；⚡ = medium 置信, ? = low 置信；'
-                     f'用 ref:N 引用')
+                     f'@zone=位置区域（top-left/top-right/center/… 9 宫格）；'
+                     f'(icon)=仅图标；用 ref:N 引用')
         lines.append('')
         for rec in extras:
             ctx['counter'] += 1
             rid = ctx['counter']
-            marker = CONFIDENCE_MARKER.get(rec.get('confidence'), '')
-            tag = rec.get('tag', '')
-            text = (rec.get('text') or '').strip()
-            reason = rec.get('reason') or ''
-            loc = rec.get('locator') or ''
-            rect = rec.get('rect') or {}
-
-            parts = [f'- [{rid}] {marker}{tag}']
-            if text:
-                display_text = text[:80] + '…' if len(text) > 80 else text
-                parts.append(f'"{display_text}"')
-            meta_parts = [reason]
-            if rect.get('w'):
-                meta_parts.append(f'{rect["w"]}x{rect["h"]}')
-            parts.append(f'({", ".join(meta_parts)})')
-            if loc:
-                parts.append(f'→ {loc}')
-            lines.append(' '.join(parts))
-
+            lines.append('- ' + format_clickable_record(rec, rid))
             # 记入 refs 以便 click/fill 引用
             ctx['refs'][str(rid)] = {
-                'locator': loc,
-                'role': f'clickable/{tag}',
-                'name': text[:100],
+                'locator': rec.get('locator') or '',
+                'role': f"clickable/{rec.get('tag', '')}",
+                'name': (rec.get('label') or rec.get('text') or '')[:100],
                 'backendNodeId': rec.get('backendNodeId'),
                 'confidence': rec.get('confidence'),
-                'reason': reason,
+                'reason': rec.get('reason'),
+                'zone': rec.get('zone'),
+                'iconOnly': bool(rec.get('iconOnly')),
             }
 
     if snapshot.get('clickable_warning'):

{dp_cli-0.3.0 → dp_cli-0.3.1}/dp_cli/snapshot/clickable.py

@@ -106,6 +106,9 @@ def detect_clickables(page,
             'confidence': e.get('confidence'),
             'reason': e.get('reason'),
             'text': e.get('text'),
+            'label': e.get('label'),
+            'iconOnly': bool(e.get('iconOnly')),
+            'zone': e.get('zone'),
             'rect': e.get('rect'),
             'inViewport': e.get('inViewport'),
             'backendNodeId': backend_node_id,
@@ -167,31 +170,41 @@ CONFIDENCE_MARKER = {
 }
 
 
-def format_clickable_record(rec: dict, ref_id: int) -> str:
+def format_clickable_record(rec: dict, ref_id: int, verbose: bool = False) -> str:
     """把一条 ClickableRecord 渲染成一行文本。
 
-    示例：
-      [42] ⚡ button "Sign in" (role=button, pos=120,340, 80x32) → #signin
-      [43] ? span "•••" (cursor:pointer, pos=200,150, 24x24) → .more-icon
+    默认紧凑格式（给 AI / 用户看，强调有用信息）：
+      [5] button "Sign in" @top-right → #signin
+      [8] ⚡ div "User profile" @top-left (icon) → .user-menu-btn
+      [9] ⚡ svg @top-right (icon) → xpath://header//svg[3]
+      [12] ? span "see more" @bottom → css:.footer > span:nth-child(3)
+
+    verbose=True 时追加 reason + 尺寸，用于调试：
+      [5] button "Sign in" @top-right (button, 80x32) → #signin
     """
     marker = CONFIDENCE_MARKER.get(rec.get('confidence'), '')
     tag = rec.get('tag', '')
-    text = rec.get('text') or ''
+    label = (rec.get('label') or rec.get('text') or '').strip()
+    zone = rec.get('zone') or ''
+    icon_only = bool(rec.get('iconOnly'))
     reason = rec.get('reason') or ''
     rect = rec.get('rect') or {}
     loc = rec.get('locator') or ''
 
     parts = [f'[{ref_id}]', f'{marker}{tag}']
-    if text:
-        parts.append(f'"{text[:80]}"')
-    rect_str = ''
-    if rect:
-        rect_str = f'{rect.get("w", 0)}x{rect.get("h", 0)}@{rect.get("x", 0)},{rect.get("y", 0)}'
-    meta = f'({reason}'
-    if rect_str:
-        meta += f', {rect_str}'
-    meta += ')'
-    parts.append(meta)
+    if label:
+        display = label[:80] + '…' if len(label) > 80 else label
+        parts.append(f'"{display}"')
+    elif icon_only:
+        # 无 label 但有 icon：标注 (icon) 提示这是图标按钮
+        parts.append('(icon)')
+    if zone:
+        parts.append(f'@{zone}')
+    if verbose:
+        meta_bits = [reason]
+        if rect.get('w'):
+            meta_bits.append(f'{rect["w"]}x{rect["h"]}')
+        parts.append(f'({", ".join(meta_bits)})')
     if loc:
         parts.append(f'→ {loc}')
     return ' '.join(parts)

dp_cli-0.3.1/dp_cli/snapshot/clickable_js.py

@@ -0,0 +1,381 @@
+# -*- coding:utf-8 -*-
+"""
+Vimium-C 风格的可点击元素探测 JS 脚本（v2）
+
+改进点（相比 v1）：
+  1. 递归遍历 Shadow DOM（open shadow root），React/Vue 组件和 Web Components 都能看见
+  2. cursor:pointer 启发式升级：
+     满足下列任一 → MEDIUM（默认显示，不再必须 --include-low）：
+       · 有 aria-label / title / data-tooltip 等 label 属性
+       · 包含 svg / img / i / [class*=icon] 子元素（图标按钮特征）
+       · 本身就是 svg / i 标签
+       · rect 是小方形（12-80px、宽高差 ≤16）—— 图标按钮尺寸特征
+       · class 名匹配 btn/click/toggle/menu... 关键词
+     都不满足的普通 cursor:pointer 仍为 LOW
+  3. 父子 cursor:pointer 去重更严：子元素覆盖父元素 ≥50% 面积时，父元素让位
+  4. 新增字段：
+     · label: aria-label / title / svg <title> 等无障碍名（优先于 innerText）
+     · zone: 位置区域（top-left / top-right / center / bottom 等 9 宫格）
+     · iconOnly: 布尔值，无文字但有图标子元素
+  5. 更强的 label 回退：svg > title、子 img alt、data-tooltip、data-tippy-content
+  6. 识别更多框架 click 属性：@click（Vue）、v-on:click、(click)（Angular）
+
+注意：DrissionPage.run_js(code) 会把 code 包成函数体，只有顶层 return 才能
+得到返回值；IIFE 返回值会被丢弃，所以用 `const __r = ...; return __r;`。
+"""
+
+DETECT_CLICKABLES_JS = r"""
+const __dp_detect_result = (function() {
+  const VIEWPORT_ONLY = %(viewport_only)s;
+  const MAX_ELEMENTS = %(max_elements)d;
+  const INCLUDE_LOW = %(include_low)s;
+
+  const CLICKABLE_ROLES = /^(button|link|checkbox|radio|combobox|menu|menuitem|menuitemcheckbox|menuitemradio|tab|option|switch|slider|spinbutton|searchbox|textbox|treeitem|row|cell|gridcell|listbox|listitem|article|tooltip)$/i;
+
+  const CLASS_PATTERN = /(?:^|[\s_-])(btn|button|click|action|select|link|menu|toggle|tab|close|open|expand|collapse|dropdown|trigger|hoverable|selectable|clickable|chip|pill|tag|card|avatar|icon|ico)(?:$|[\s_-])/i;
+
+  const ICON_CLASS_PATTERN = /(?:^|[\s_-])(icon|ico|fa|fa-|glyphicon|material-icons|anticon|lucide|svg)/i;
+
+  function isElementVisible(el) {
+    const rects = el.getClientRects();
+    if (!rects.length) return null;
+    const rect = el.getBoundingClientRect();
+    if (rect.width < 2 || rect.height < 2) return null;
+    let style;
+    try { style = getComputedStyle(el); } catch (e) { return null; }
+    if (style.display === 'none' || style.visibility === 'hidden') return null;
+    const op = parseFloat(style.opacity);
+    if (op < 0.05) return null;
+    return { rect: rect, style: style };
+  }
+
+  function inViewport(rect) {
+    return rect.top < window.innerHeight && rect.bottom > 0
+      && rect.left < window.innerWidth && rect.right > 0;
+  }
+
+  function classNameString(el) {
+    const cn = el.className;
+    if (typeof cn === 'string') return cn;
+    if (cn && typeof cn.baseVal === 'string') return cn.baseVal;  // SVGAnimatedString
+    return '';
+  }
+
+  // 计算 9 宫格区域名（基于元素中心点和视口）
+  function computeZone(rect) {
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const W = window.innerWidth || 1, H = window.innerHeight || 1;
+    const xPart = cx < W / 3 ? 'left' : cx > W * 2 / 3 ? 'right' : 'center';
+    const yPart = cy < H / 3 ? 'top' : cy > H * 2 / 3 ? 'bottom' : 'middle';
+    if (yPart === 'middle' && xPart === 'center') return 'center';
+    if (yPart === 'middle') return xPart;
+    if (xPart === 'center') return yPart;
+    return yPart + '-' + xPart;
+  }
+
+  // 父元素是否也 cursor:pointer —— 若是则本元素应让位给父（保留最外层 pointer）
+  // 这样能避免 <div style="cursor:pointer"><svg><use/></svg></div> 里 svg/use 被重复登记
+  function parentIsPointer(el) {
+    const p = el.parentElement;
+    if (!p) return false;
+    try { return getComputedStyle(p).cursor === 'pointer'; } catch (e) { return false; }
+  }
+
+  // 获取元素的"无障碍名"——优先级 aria-label > aria-labelledby > 控件专属 > innerText > title/alt > 图标兜底
+  function getAccessibleText(el) {
+    let t = el.getAttribute && el.getAttribute('aria-label');
+    if (t && t.trim()) return t.trim();
+
+    const lbi = el.getAttribute && el.getAttribute('aria-labelledby');
+    if (lbi) {
+      const ids = lbi.split(/\s+/);
+      const texts = [];
+      for (const id of ids) {
+        const ref = document.getElementById(id);
+        if (ref) texts.push((ref.innerText || ref.textContent || '').trim());
+      }
+      const joined = texts.filter(Boolean).join(' ').trim();
+      if (joined) return joined;
+    }
+
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'input') {
+      const type = (el.type || 'text').toLowerCase();
+      if (type === 'submit' || type === 'button') return (el.value || '').trim();
+      return (el.getAttribute('placeholder') || el.getAttribute('aria-placeholder') || '').trim();
+    }
+
+    // innerText（优先取，很多图标按钮实际上有 sr-only 文字）
+    const it = ((el.innerText || el.textContent) || '').trim().replace(/\s+/g, ' ');
+    if (it && it.length <= 120) return it;
+    if (it) return it.slice(0, 120);
+
+    // 各种 tooltip / title 属性
+    t = el.getAttribute('title')
+      || el.getAttribute('alt')
+      || el.getAttribute('data-tooltip')
+      || el.getAttribute('data-tippy-content')
+      || el.getAttribute('data-original-title')
+      || el.getAttribute('data-bs-original-title')
+      || el.getAttribute('data-title');
+    if (t && t.trim()) return t.trim();
+
+    // svg > title 子节点
+    try {
+      const svgTitle = el.querySelector('svg > title, svg > desc');
+      if (svgTitle) {
+        const st = (svgTitle.textContent || '').trim();
+        if (st) return st;
+      }
+      // 子节点 aria-label
+      const innerLabeled = el.querySelector('[aria-label]');
+      if (innerLabeled) {
+        const al = innerLabeled.getAttribute('aria-label');
+        if (al && al.trim()) return al.trim();
+      }
+      // 子 img alt
+      const imgAlt = el.querySelector('img[alt]');
+      if (imgAlt) {
+        const alt = imgAlt.getAttribute('alt');
+        if (alt && alt.trim()) return alt.trim();
+      }
+    } catch (e) {}
+
+    return '';
+  }
+
+  // 判断是否是"仅图标"的按钮（无有效文字，但包含图标子元素）
+  function detectIconOnly(el, accessibleText) {
+    if (accessibleText) return false;
+    try {
+      if (el.querySelector('svg, img, :scope > i, :scope > [class*="icon"], :scope > [class*="Icon"]')) {
+        return true;
+      }
+    } catch (e) {}
+    return false;
+  }
+
+  // 核心分类
+  function classify(el, style, rect) {
+    const tag = el.tagName.toLowerCase();
+
+    // HIGH 级：原生交互标签
+    if (tag === 'a') {
+      if (!el.hasAttribute('href') && !el.hasAttribute('onclick')) return null;
+      return { confidence: 'high', reason: 'a' };
+    }
+    if (tag === 'button' && !el.disabled) return { confidence: 'high', reason: 'button' };
+    if (tag === 'select' && !el.disabled) return { confidence: 'high', reason: 'select' };
+    if (tag === 'textarea' && !el.disabled) {
+      return { confidence: 'high', reason: el.readOnly ? 'textarea[ro]' : 'textarea' };
+    }
+    if (tag === 'input' && !el.disabled) {
+      const type = (el.type || 'text').toLowerCase();
+      if (type === 'hidden') return null;
+      return { confidence: 'high', reason: 'input[' + type + ']' };
+    }
+    if (tag === 'summary' || tag === 'details') {
+      return { confidence: 'high', reason: tag };
+    }
+    if (tag === 'label') {
+      if (el.htmlFor || el.control) return { confidence: 'high', reason: 'label' };
+      return null;
+    }
+    if (tag === 'audio' || tag === 'video') {
+      return { confidence: 'medium', reason: tag };
+    }
+    if (tag === 'iframe' || tag === 'frame') {
+      return { confidence: 'low', reason: tag };
+    }
+
+    // contenteditable
+    const ce = el.getAttribute('contenteditable');
+    if (ce !== null && ce !== 'false' && ce !== 'inherit') {
+      return { confidence: 'high', reason: 'contenteditable' };
+    }
+
+    // role 白名单
+    const role = el.getAttribute('role');
+    if (role && CLICKABLE_ROLES.test(role.trim())) {
+      return { confidence: 'high', reason: 'role=' + role };
+    }
+
+    // MEDIUM 级：显式事件 / 框架 click / tabindex / aria-selected
+    if (el.hasAttribute('onclick') || el.hasAttribute('onmousedown') || el.hasAttribute('onpointerdown')) {
+      return { confidence: 'medium', reason: 'onclick-attr' };
+    }
+    if (el.hasAttribute('jsaction')) {
+      return { confidence: 'medium', reason: 'jsaction' };
+    }
+    if (el.hasAttribute('ng-click') || el.hasAttribute('(click)')
+        || el.hasAttribute('@click') || el.hasAttribute('v-on:click')) {
+      return { confidence: 'medium', reason: 'fw-click' };
+    }
+    const ti = el.getAttribute('tabindex');
+    if (ti !== null) {
+      const tiNum = parseInt(ti, 10);
+      if (!isNaN(tiNum) && tiNum >= 0) {
+        return { confidence: 'medium', reason: 'tabindex=' + tiNum };
+      }
+    }
+    if (el.hasAttribute('aria-selected') || el.hasAttribute('aria-checked')) {
+      return { confidence: 'medium', reason: 'aria-state' };
+    }
+
+    // cursor:pointer + 启发式 —— 这是 React/Vue 图标按钮的主要特征
+    const isPointer = style.cursor === 'pointer';
+    if (isPointer) {
+      // 父元素也是 cursor:pointer → 让位给父（保留最外层，Vimium 同策略）
+      if (parentIsPointer(el)) return null;
+
+      const ariaLabel = el.getAttribute('aria-label');
+      const title = el.getAttribute('title');
+      const tooltip = el.getAttribute('data-tooltip')
+        || el.getAttribute('data-tippy-content')
+        || el.getAttribute('data-original-title');
+      const hasLabel = !!(ariaLabel || title || tooltip);
+
+      let hasIconChild = false;
+      try {
+        hasIconChild = !!el.querySelector('svg, img, i.fa, i[class*="icon"], [class*="icon"]:not(body)');
+      } catch (e) {}
+
+      const isIconTag = tag === 'svg' || tag === 'i';
+      const widthOk = rect.width >= 12 && rect.width <= 80;
+      const heightOk = rect.height >= 12 && rect.height <= 80;
+      const aspectOk = Math.abs(rect.width - rect.height) <= 24;
+      const smallSquare = widthOk && heightOk && aspectOk;
+
+      const cn = classNameString(el);
+      const hasClassHint = cn && (CLASS_PATTERN.test(cn) || ICON_CLASS_PATTERN.test(cn));
+
+      if (hasLabel) return { confidence: 'medium', reason: 'cursor+label' };
+      if (hasIconChild && smallSquare) return { confidence: 'medium', reason: 'cursor+icon' };
+      if (hasIconChild) return { confidence: 'medium', reason: 'cursor+icon-child' };
+      if (isIconTag) return { confidence: 'medium', reason: 'cursor+' + tag };
+      if (smallSquare) return { confidence: 'medium', reason: 'cursor+square' };
+      if (hasClassHint) return { confidence: 'medium', reason: 'cursor+class' };
+
+      // 兜底：普通 cursor:pointer（文字链接类样式） → LOW
+      if (!INCLUDE_LOW) return null;
+      return { confidence: 'low', reason: 'cursor:pointer' };
+    }
+
+    // LOW 级：class 名关键词匹配（无 cursor:pointer）
+    if (!INCLUDE_LOW) return null;
+    const cn = classNameString(el);
+    if (cn && CLASS_PATTERN.test(cn)) {
+      const p = el.parentElement;
+      if (!p || !CLASS_PATTERN.test(classNameString(p))) {
+        return { confidence: 'low', reason: 'class-pattern' };
+      }
+    }
+
+    return null;
+  }
+
+  // 遍历所有元素（含 open Shadow DOM）
+  function collectAll() {
+    const out = [];
+    function walk(root) {
+      let nodes;
+      try { nodes = root.querySelectorAll('*'); } catch (e) { return; }
+      for (let i = 0; i < nodes.length; i++) {
+        const el = nodes[i];
+        out.push(el);
+        if (el.shadowRoot) {
+          try { walk(el.shadowRoot); } catch (e) {}
+        }
+      }
+    }
+    walk(document);
+    return out;
+  }
+
+  // 清理上次残留
+  try {
+    document.querySelectorAll('[data-dp-scan-id]').forEach(el => el.removeAttribute('data-dp-scan-id'));
+  } catch (e) {}
+
+  const results = [];
+  let counter = 0;
+  let truncated = false;
+
+  const all = collectAll();
+  for (let i = 0; i < all.length; i++) {
+    if (results.length >= MAX_ELEMENTS) { truncated = true; break; }
+    const el = all[i];
+
+    const vis = isElementVisible(el);
+    if (!vis) continue;
+    const rect = vis.rect;
+    const style = vis.style;
+
+    if (VIEWPORT_ONLY && !inViewport(rect)) continue;
+
+    const cls = classify(el, style, rect);
+    if (!cls) continue;
+
+    counter++;
+    try { el.setAttribute('data-dp-scan-id', String(counter)); } catch (e) { continue; }
+
+    const text = getAccessibleText(el).slice(0, 150);
+    const iconOnly = detectIconOnly(el, text);
+    const zone = computeZone(rect);
+
+    results.push({
+      scanId: counter,
+      tag: el.tagName.toLowerCase(),
+      confidence: cls.confidence,
+      reason: cls.reason,
+      text: text,
+      label: text,
+      iconOnly: iconOnly,
+      zone: zone,
+      rect: {
+        x: Math.round(rect.left),
+        y: Math.round(rect.top),
+        w: Math.round(rect.width),
+        h: Math.round(rect.height)
+      },
+      inViewport: inViewport(rect)
+    });
+  }
+
+  return { elements: results, total: results.length, truncated: truncated };
+})();
+return __dp_detect_result;
+"""
+
+CLEANUP_CLICKABLES_JS = r"""
+const __dp_cleanup_result = (function() {
+  let n = 0;
+  function walk(root) {
+    let nodes;
+    try { nodes = root.querySelectorAll('[data-dp-scan-id]'); } catch (e) { return; }
+    nodes.forEach(el => { el.removeAttribute('data-dp-scan-id'); n++; });
+    // 清理 shadow DOM 里的
+    try {
+      const all = root.querySelectorAll('*');
+      for (let i = 0; i < all.length; i++) {
+        if (all[i].shadowRoot) walk(all[i].shadowRoot);
+      }
+    } catch (e) {}
+  }
+  walk(document);
+  return { cleaned: n };
+})();
+return __dp_cleanup_result;
+"""
+
+
+def build_detect_js(viewport_only: bool = False,
+                    max_elements: int = 1000,
+                    include_low: bool = False) -> str:
+    """按参数填充模板，返回可注入的 JS 代码。"""
+    return DETECT_CLICKABLES_JS % {
+        'viewport_only': 'true' if viewport_only else 'false',
+        'max_elements': int(max_elements),
+        'include_low': 'true' if include_low else 'false',
+    }

{dp_cli-0.3.0 → dp_cli-0.3.1}/dp_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more.
 License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mofanx/dp-cli
@@ -119,8 +119,13 @@ Results are deduplicated by `backendNodeId` and rendered with confidence markers
 | Marker | Confidence | Triggers |
 |--------|-----------|----------|
 | none   | **high**   | `<a href>`, `<button>`, `<input>`, `role=button/link/...`, `contenteditable` |
-| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>` |
-| `?`    | **low**    | `cursor:pointer` / class keyword match (`btn` / `click` / `toggle` / …) |
+| `⚡`   | **medium** | `onclick` / `jsaction` / `tabindex>=0` / `aria-selected` / `<audio>/<video>`, or `cursor:pointer` + heuristic (aria-label / icon child / small square / class keyword) — **catches most React/Vue icon buttons** |
+| `?`    | **low**    | bare `cursor:pointer` / class keyword only (no other signals); hidden unless `--include-low` |
+
+Output includes helpful context:
+- `@top-left`, `@top-right`, `@center`, `@bottom` … — position in the 9-region viewport grid
+- `(icon)` — icon-only button (no visible label, has `<svg>` / `<img>` child)
+- Shadow DOM is traversed automatically (open shadow roots)
 
 Every element gets an `[N]` ref usable in any command: `dp click "ref:5"`.
 

{dp_cli-0.3.0 → dp_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dp-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more."
 readme = "README.md"
 requires-python = ">=3.8"

{dp_cli-0.3.0 → dp_cli-0.3.1}/tests/test_clickable.py

@@ -50,21 +50,30 @@ def test_detect_js_is_raw_string_no_percent_collision():
 def test_detect_js_covers_vimium_rules():
     """快速核查关键规则都在脚本里，避免被误删。"""
     body = DETECT_CLICKABLES_JS
-    # HIGH
+    # HIGH 级
     assert "tag === 'a'" in body
     assert "tag === 'button'" in body
     assert "tag === 'input'" in body
     assert "tag === 'select'" in body
     assert "contenteditable" in body
     assert "CLICKABLE_ROLES.test" in body
-    # MEDIUM
+    # MEDIUM 级
     assert "'onclick'" in body
     assert "'jsaction'" in body
     assert "'tabindex'" in body
     assert "'aria-selected'" in body
-    # LOW
-    assert "cursor:pointer" in body.lower() or "'pointer'" in body
+    # 框架 click 属性（Vue / Angular）
+    assert "@click" in body
+    assert "v-on:click" in body
+    # cursor:pointer 启发式
+    assert "isPointer" in body
     assert "CLASS_PATTERN.test" in body
+    assert "ICON_CLASS_PATTERN" in body
+    assert "parentIsPointer" in body
+    # 新字段：zone / iconOnly / shadow DOM
+    assert "computeZone" in body
+    assert "detectIconOnly" in body
+    assert "shadowRoot" in body
     # 可见性
     assert "getClientRects" in body
     assert "getBoundingClientRect" in body
@@ -72,6 +81,15 @@ def test_detect_js_covers_vimium_rules():
     assert "data-dp-scan-id" in body
 
 
+def test_detect_js_shadow_dom_traversal():
+    """Shadow DOM 递归：collectAll 必须检查 shadowRoot。"""
+    body = DETECT_CLICKABLES_JS
+    assert "collectAll" in body
+    assert "shadowRoot" in body
+    # 清理脚本也要覆盖 shadow DOM
+    assert "shadowRoot" in CLEANUP_CLICKABLES_JS
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # 置信度标记 & 渲染
 # ─────────────────────────────────────────────────────────────────────────────
@@ -88,32 +106,54 @@ def test_format_clickable_record_high():
         'confidence': 'high',
         'reason': 'button',
         'text': 'Sign in',
+        'label': 'Sign in',
+        'zone': 'top-right',
+        'iconOnly': False,
         'rect': {'x': 10, 'y': 20, 'w': 80, 'h': 32},
         'locator': '#signin',
     }
     s = format_clickable_record(rec, ref_id=5)
     assert s.startswith('[5] button')
     assert '"Sign in"' in s
-    assert 'button' in s  # reason
-    assert '80x32' in s
+    assert '@top-right' in s
     assert '→ #signin' in s
-    # high 不带标记
+    # 默认紧凑格式不含 reason / 尺寸
+    assert 'button,' not in s
+    assert '80x32' not in s
+    # high 不带置信度标记
     assert '⚡' not in s
     assert '?' not in s
 
 
-def test_format_clickable_record_medium_has_marker():
+def test_format_clickable_record_verbose_shows_reason_and_size():
+    rec = {
+        'tag': 'button', 'confidence': 'high', 'reason': 'button',
+        'label': 'OK', 'zone': 'center', 'iconOnly': False,
+        'rect': {'w': 80, 'h': 32}, 'locator': '#ok',
+    }
+    s = format_clickable_record(rec, ref_id=1, verbose=True)
+    assert '(button, 80x32)' in s
+
+
+def test_format_clickable_record_icon_only_no_label():
     rec = {
         'tag': 'div',
         'confidence': 'medium',
-        'reason': 'onclick-attr',
-        'text': 'Open',
-        'rect': {'x': 0, 'y': 0, 'w': 24, 'h': 24},
-        'locator': '.open-btn',
+        'reason': 'cursor+icon',
+        'text': '',
+        'label': '',
+        'zone': 'top-left',
+        'iconOnly': True,
+        'rect': {'w': 32, 'h': 32},
+        'locator': '.sidebar-toggle',
     }
     s = format_clickable_record(rec, ref_id=3)
     assert '⚡' in s
-    assert 'onclick-attr' in s
+    assert '(icon)' in s
+    assert '@top-left' in s
+    assert '→ .sidebar-toggle' in s
+    # 无 label 不应出现空引号
+    assert '""' not in s
 
 
 def test_format_clickable_record_low_has_marker():
@@ -121,10 +161,14 @@ def test_format_clickable_record_low_has_marker():
         'tag': 'span',
         'confidence': 'low',
         'reason': 'cursor:pointer',
-        'text': '…',
-        'rect': {'x': 0, 'y': 0, 'w': 16, 'h': 16},
+        'text': 'See more',
+        'label': 'See more',
+        'zone': 'bottom',
+        'iconOnly': False,
+        'rect': {'w': 60, 'h': 16},
         'locator': '.more',
     }
     s = format_clickable_record(rec, ref_id=9)
     assert '?' in s
-    assert 'cursor:pointer' in s
+    assert '"See more"' in s
+    assert '@bottom' in s

dp_cli-0.3.0/dp_cli/snapshot/clickable_js.py

@@ -1,273 +0,0 @@
-# -*- coding:utf-8 -*-
-"""
-Vimium-C 风格的可点击元素探测 JS 脚本
-
-运行在浏览器内通过 CDP Runtime.evaluate；遍历可见 DOM 节点，
-按多级规则识别可交互元素并打上临时属性 `data-dp-scan-id`，便于
-Python 端通过 CDP DOM 树将其映射到 backendNodeId。
-
-三级置信度：
-  high    — 明确可点击（<a href>, <button>, role=button 等）
-  medium  — 很可能可点击（onclick/jsaction/tabindex>=0/aria-selected）
-  low     — 启发式（cursor:pointer 或 class 名匹配 btn/click/… 规则）
-
-规则参考：vimium-c/content/local_links.ts
-"""
-
-# 探测脚本：返回 {elements: [...], total: N, truncated: bool}
-# 模板占位符：%(viewport_only)s, %(max_elements)d, %(include_low)s
-#
-# 注意：DrissionPage.run_js(code) 会把 code 包成函数体，只有顶层 return 才能
-# 获得返回值；单纯 IIFE `(()=>{...})()` 的返回值会被丢弃。所以下面用
-# `const __r = (function(){...})(); return __r;` 的形式。
-DETECT_CLICKABLES_JS = r"""
-const __dp_detect_result = (function() {
-  const VIEWPORT_ONLY = %(viewport_only)s;
-  const MAX_ELEMENTS = %(max_elements)d;
-  const INCLUDE_LOW = %(include_low)s;
-
-  const CLICKABLE_ROLES = /^(button|link|checkbox|radio|combobox|menu|menuitem|menuitemcheckbox|menuitemradio|tab|option|switch|slider|spinbutton|searchbox|textbox|treeitem|row|cell|gridcell|listbox|listitem)$/i;
-
-  // 类名关键词正则：btn/button/click/action/link/menu/toggle/tab/close/open/expand/collapse/dropdown/trigger
-  const CLASS_PATTERN = /(?:^|[\s_-])(btn|button|click|action|select|link|menu|toggle|tab|close|open|expand|collapse|dropdown|trigger|hoverable|selectable|clickable)(?:$|[\s_-])/i;
-
-  // 非可编辑 input 类型
-  const UNEDITABLE_INPUT = new Set(['hidden', 'submit', 'reset', 'button', 'checkbox', 'radio', 'image', 'file', 'color', 'range']);
-
-  function isElementVisible(el) {
-    const rects = el.getClientRects();
-    if (!rects.length) return null;
-    const rect = el.getBoundingClientRect();
-    if (rect.width < 2 || rect.height < 2) return null;
-    const style = getComputedStyle(el);
-    if (style.display === 'none' || style.visibility === 'hidden') return null;
-    const op = parseFloat(style.opacity);
-    if (op < 0.05) return null;
-    return rect;
-  }
-
-  function inViewport(rect) {
-    return rect.top < window.innerHeight && rect.bottom > 0
-      && rect.left < window.innerWidth && rect.right > 0;
-  }
-
-  function classNameString(el) {
-    const cn = el.className;
-    if (typeof cn === 'string') return cn;
-    // SVGAnimatedString
-    if (cn && typeof cn.baseVal === 'string') return cn.baseVal;
-    return '';
-  }
-
-  function parentHasMatchingCursor(el) {
-    const p = el.parentElement;
-    if (!p) return false;
-    try { return getComputedStyle(p).cursor === 'pointer'; } catch (e) { return false; }
-  }
-
-  function parentHasMatchingClass(el) {
-    const p = el.parentElement;
-    if (!p) return false;
-    return CLASS_PATTERN.test(classNameString(p));
-  }
-
-  // 判断一个元素是否可交互，返回 {confidence, reason} 或 null
-  function classify(el) {
-    const tag = el.tagName.toLowerCase();
-
-    // HIGH
-    if (tag === 'a') {
-      if (!el.hasAttribute('href') && !el.hasAttribute('onclick')) return null;
-      return { confidence: 'high', reason: 'a' };
-    }
-    if (tag === 'button') {
-      if (el.disabled) return null;
-      return { confidence: 'high', reason: 'button' };
-    }
-    if (tag === 'select') {
-      if (el.disabled) return null;
-      return { confidence: 'high', reason: 'select' };
-    }
-    if (tag === 'textarea') {
-      if (el.disabled) return null;
-      return { confidence: 'high', reason: el.readOnly ? 'textarea[readonly]' : 'textarea' };
-    }
-    if (tag === 'input') {
-      if (el.disabled) return null;
-      const type = (el.type || 'text').toLowerCase();
-      if (type === 'hidden') return null;
-      return { confidence: 'high', reason: 'input[' + type + ']' };
-    }
-    if (tag === 'summary' || tag === 'details') {
-      return { confidence: 'high', reason: tag };
-    }
-    if (tag === 'label') {
-      // 仅当关联到实际控件时，<label> 本身可点击触发控件
-      if (el.htmlFor || el.control) return { confidence: 'high', reason: 'label' };
-      // 没有关联的 label 不登记（点击无效）
-      return null;
-    }
-    if (tag === 'audio' || tag === 'video') {
-      return { confidence: 'medium', reason: tag };
-    }
-    if (tag === 'iframe' || tag === 'frame') {
-      return { confidence: 'low', reason: tag };  // 一般不直接点击
-    }
-
-    // contenteditable
-    const ce = el.getAttribute('contenteditable');
-    if (ce !== null && ce !== 'false' && ce !== 'inherit') {
-      return { confidence: 'high', reason: 'contenteditable' };
-    }
-
-    // role 白名单
-    const role = el.getAttribute('role');
-    if (role && CLICKABLE_ROLES.test(role.trim())) {
-      return { confidence: 'high', reason: 'role=' + role };
-    }
-
-    // onclick / onmousedown / jsaction / ng-click
-    if (el.hasAttribute('onclick') || el.hasAttribute('onmousedown')) {
-      return { confidence: 'medium', reason: 'onclick-attr' };
-    }
-    if (el.hasAttribute('jsaction')) {
-      return { confidence: 'medium', reason: 'jsaction' };
-    }
-    if (el.hasAttribute('ng-click') || el.hasAttribute('(click)')) {
-      return { confidence: 'medium', reason: 'framework-click' };
-    }
-
-    // tabindex >= 0
-    const ti = el.getAttribute('tabindex');
-    if (ti !== null) {
-      const tiNum = parseInt(ti, 10);
-      if (!isNaN(tiNum) && tiNum >= 0) {
-        return { confidence: 'medium', reason: 'tabindex=' + tiNum };
-      }
-    }
-
-    // aria-selected / aria-checked
-    if (el.hasAttribute('aria-selected') || el.hasAttribute('aria-checked')) {
-      return { confidence: 'medium', reason: 'aria-selected' };
-    }
-
-    // LOW 级需要 include_low 开关
-    if (!INCLUDE_LOW) return null;
-
-    // cursor:pointer（父元素也 pointer 则跳过避免冗余）
-    let style;
-    try { style = getComputedStyle(el); } catch (e) { return null; }
-    if (style.cursor === 'pointer' && !parentHasMatchingCursor(el)) {
-      return { confidence: 'low', reason: 'cursor:pointer' };
-    }
-
-    // class 名关键词
-    const cn = classNameString(el);
-    if (cn && CLASS_PATTERN.test(cn) && !parentHasMatchingClass(el)) {
-      return { confidence: 'low', reason: 'class-pattern' };
-    }
-
-    // SVG 且 cursor:pointer（上面已处理，但 SVG 有时 cursor 继承）
-    if (tag === 'svg' && style.cursor === 'pointer') {
-      return { confidence: 'low', reason: 'svg-cursor' };
-    }
-
-    return null;
-  }
-
-  function getAccessibleText(el) {
-    // aria-label 优先
-    let t = el.getAttribute('aria-label');
-    if (t) return t.trim();
-    // aria-labelledby
-    const lbi = el.getAttribute('aria-labelledby');
-    if (lbi) {
-      const ids = lbi.split(/\s+/);
-      const texts = [];
-      for (const id of ids) {
-        const ref = document.getElementById(id);
-        if (ref) texts.push((ref.innerText || ref.textContent || '').trim());
-      }
-      const joined = texts.filter(Boolean).join(' ').trim();
-      if (joined) return joined;
-    }
-    // input 的 value / placeholder / type
-    const tag = el.tagName.toLowerCase();
-    if (tag === 'input') {
-      const type = (el.type || 'text').toLowerCase();
-      if (type === 'submit' || type === 'button') return (el.value || '').trim();
-      return (el.getAttribute('placeholder') || el.getAttribute('aria-placeholder') || '').trim();
-    }
-    // innerText（截断）
-    const it = (el.innerText || '').trim().replace(/\s+/g, ' ');
-    if (it) return it.slice(0, 120);
-    // title / alt
-    return (el.getAttribute('title') || el.getAttribute('alt') || '').trim();
-  }
-
-  // 去掉之前可能残留的 data-dp-scan-id（比如上次调用异常中断）
-  document.querySelectorAll('[data-dp-scan-id]').forEach(el => el.removeAttribute('data-dp-scan-id'));
-
-  const results = [];
-  let counter = 0;
-  let truncated = false;
-
-  // 遍历所有元素
-  const all = document.querySelectorAll('*');
-  for (let i = 0; i < all.length; i++) {
-    if (results.length >= MAX_ELEMENTS) { truncated = true; break; }
-    const el = all[i];
-
-    const cls = classify(el);
-    if (!cls) continue;
-
-    const rect = isElementVisible(el);
-    if (!rect) continue;
-
-    if (VIEWPORT_ONLY && !inViewport(rect)) continue;
-
-    counter++;
-    try { el.setAttribute('data-dp-scan-id', String(counter)); } catch (e) { continue; }
-
-    results.push({
-      scanId: counter,
-      tag: el.tagName.toLowerCase(),
-      confidence: cls.confidence,
-      reason: cls.reason,
-      text: getAccessibleText(el).slice(0, 150),
-      rect: {
-        x: Math.round(rect.left),
-        y: Math.round(rect.top),
-        w: Math.round(rect.width),
-        h: Math.round(rect.height)
-      },
-      inViewport: inViewport(rect)
-    });
-  }
-
-  return { elements: results, total: results.length, truncated: truncated };
-})();
-return __dp_detect_result;
-"""
-
-# 清理脚本：移除所有 data-dp-scan-id 属性
-CLEANUP_CLICKABLES_JS = r"""
-const __dp_cleanup_result = (function() {
-  const nodes = document.querySelectorAll('[data-dp-scan-id]');
-  let n = 0;
-  nodes.forEach(el => { el.removeAttribute('data-dp-scan-id'); n++; });
-  return { cleaned: n };
-})();
-return __dp_cleanup_result;
-"""
-
-
-def build_detect_js(viewport_only: bool = False,
-                    max_elements: int = 1000,
-                    include_low: bool = False) -> str:
-    """按参数填充模板，返回可注入的 JS 代码。"""
-    return DETECT_CLICKABLES_JS % {
-        'viewport_only': 'true' if viewport_only else 'false',
-        'max_elements': int(max_elements),
-        'include_low': 'true' if include_low else 'false',
-    }