mooncat-browser 0.1.0

package/browser-op/webplater/entrypoints/content.ts

@@ -0,0 +1,1150 @@
+/**
+ * Content script — ISOLATED world。
+ *
+ * 接收 background 转发的页面动作命令，操作当前页 DOM。
+ * 全域名注入，不做任何安全/域名过滤（通用插件）。
+ *
+ * 元素定位两种方式：
+ *   - CSS selector（click/fill 等）
+ *   - aria ref（snapshot 返回的 eN，*Ref 动作）
+ */
+
+import { ariaSnapshot, getElementByRef } from '../lib/snapshot'
+
+interface ContentResponse {
+  ok: boolean
+  error?: string
+  [k: string]: unknown
+}
+
+function asResponse<T extends ContentResponse>(fn: () => T | Promise<T>): Promise<ContentResponse> {
+  return Promise.resolve()
+    .then(() => fn())
+    .then((r) => r as ContentResponse)
+    .catch(
+      (err): ContentResponse => ({
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      }),
+    )
+}
+
+/**
+ * 统一元素定位，对齐 playwright locator 语义。
+ * selector 支持两种：
+ *   - "aria-ref=e6"  → 从 snapshot 的 ref 映射查元素
+ *   - 其他（CSS）     → document.querySelector
+ *
+ * 判别：以 "aria-ref=" 开头 → ref；否则按 CSS。
+ * 合法 CSS selector 不会以 aria-ref= 开头，互不冲突。
+ */
+function requireEl<T extends Element = HTMLElement>(selector: string): T {
+  return locateEl(selector) as T
+}
+
+/**
+ * 统一元素定位，对齐 playwright locator 语义。
+ * selector 支持两种定位源 + 后缀索引：
+ *   定位源：
+ *     - "aria-ref=e6"        → 从 snapshot 的 ref 映射查元素
+ *     - 其他（CSS）          → querySelectorAll
+ *   后缀索引（可附加在定位源后，用 >> 分隔）：
+ *     - ">>first"            → 第一个匹配（默认）
+ *     - ">>last"             → 最后一个
+ *     - ">>nth(3)"           → 第 N 个（从 0 开始）
+ *   例：".item>>nth(2)" / "aria-ref=e6>>last"
+ */
+function locateEl(selector: string): Element {
+  const idx = selector.indexOf('>>')
+  let base = selector
+  let suffix = ''
+  if (idx >= 0) {
+    base = selector.slice(0, idx)
+    suffix = selector.slice(idx + 2).trim().toLowerCase()
+  }
+
+  let el: Element | null
+  if (base.startsWith('aria-ref=')) {
+    const ref = base.slice('aria-ref='.length).trim()
+    el = getElementByRef(ref) ?? null
+    if (!el) throw new Error(`stale ref: ${ref} (call snapshot first)`)
+    if (!document.contains(el)) throw new Error(`detached ref: ${ref}`)
+    // ref 指向唯一元素，后缀索引无意义（原样返回）
+    return el
+  }
+
+  // CSS：按后缀索引取元素
+  const list = Array.from(document.querySelectorAll(base))
+  if (list.length === 0) throw new Error(`element not found: ${base}`)
+
+  let target: Element
+  if (suffix === 'last') {
+    target = list[list.length - 1]
+  } else if (suffix.startsWith('nth(') && suffix.endsWith(')')) {
+    const n = Number(suffix.slice(4, -1))
+    if (!Number.isInteger(n)) throw new Error(`invalid nth index: ${suffix}`)
+    target = list[n]
+    if (!target) throw new Error(`nth(${n}) out of range: ${base} has ${list.length} matches`)
+  } else {
+    // first 或无后缀：默认第一个
+    target = list[0]
+  }
+  return target
+}
+
+/** 统一元素计数（对齐 playwright locator.count()） */
+function locateCount(selector: string): number {
+  const idx = selector.indexOf('>>')
+  const base = idx >= 0 ? selector.slice(0, idx) : selector
+  if (base.startsWith('aria-ref=')) {
+    // ref 指向唯一元素，计数恒为 1（存在）或 0（失效）
+    const ref = base.slice('aria-ref='.length).trim()
+    const el = getElementByRef(ref)
+    return el && document.contains(el) ? 1 : 0
+  }
+  return document.querySelectorAll(base).length
+}
+
+// 检测元素是否在当前 viewport 内 (不滚动! 滚动统一由 ScrollController 处理)
+// 不在视口返回 false, 调用方应抛 ELEMENT_OUT_OF_VIEWPORT 让 browser 技能滚动
+function inViewport(el: Element): boolean {
+  const r = (el as HTMLElement).getBoundingClientRect()
+  const vh = window.innerHeight || document.documentElement.clientHeight
+  const vw = window.innerWidth || document.documentElement.clientWidth
+  // 容差: 元素中心在视口内即可 (允许边缘略出)
+  const cx = r.left + r.width / 2
+  const cy = r.top + r.height / 2
+  return cy >= 0 && cy <= vh && cx >= 0 && cx <= vw
+}
+
+// 废弃: 原 intoView 直接 scrollIntoView 造成跳变。保留空函数防意外调用, 但不滚动
+function intoView(el: Element): void {
+  // no-op: 滚动统一由 ScrollController 处理。插件不再自己滚动页面
+}
+
+/** 当前页面状态 */
+function status(): ContentResponse {
+  return {
+    ok: true,
+    url: location.href,
+    title: document.title,
+    readyState: document.readyState,
+    textLength: document.body?.innerText?.length ?? 0,
+  }
+}
+
+// ── L2 输入原语：对齐 playwright page.mouse / page.keyboard ──
+// 不绑 DOM 元素的坐标级/按键级事件序列。click/hover/fill/type/press 等高层动作基于它们实现，
+// 使 behavior 模块的拟人轨迹/打字节奏能通过 operate 的高层动作自然注入，而非定向补 action。
+
+const MOUSE_BUTTON_TO_NUM: Record<string, number> = { left: 0, middle: 1, right: 2 }
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}
+
+function buttonNum(button: string): number {
+  return MOUSE_BUTTON_TO_NUM[button] ?? 0
+}
+
+function pointerInit(x: number, y: number, button: number, buttons: number) {
+  return {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    clientX: x,
+    clientY: y,
+    button,
+    buttons,
+    pointerType: 'mouse',
+    isPrimary: true,
+    view: window,
+  }
+}
+
+function targetAt(x: number, y: number): Element {
+  return document.elementFromPoint(x, y) || document.body
+}
+
+function centerOf(el: Element): { x: number; y: number } {
+  const r = el.getBoundingClientRect()
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2 }
+}
+
+/** 纯移动：pointermove + mousemove（behavior 轨迹多点序列用） */
+function mouseMove(x: number, y: number): void {
+  const init = pointerInit(x, y, 0, 0)
+  const t = targetAt(x, y)
+  t.dispatchEvent(new PointerEvent('pointermove', init))
+  t.dispatchEvent(new MouseEvent('mousemove', init))
+}
+
+/** 悬停进入：over + enter + move（hover 高层用，元素保持 hover 状态不出） */
+function mouseHover(x: number, y: number): void {
+  const init = pointerInit(x, y, 0, 0)
+  const t = targetAt(x, y)
+  t.dispatchEvent(new PointerEvent('pointerover', init))
+  t.dispatchEvent(new MouseEvent('mouseover', init))
+  t.dispatchEvent(new PointerEvent('pointerenter', init))
+  t.dispatchEvent(new MouseEvent('mouseenter', init))
+  t.dispatchEvent(new PointerEvent('pointermove', init))
+  t.dispatchEvent(new MouseEvent('mousemove', init))
+}
+
+/** 按下：over + enter + down（进入元素后按下） */
+function mouseDown(x: number, y: number, button: string): void {
+  const btn = buttonNum(button)
+  const init = pointerInit(x, y, btn, 1 << btn)
+  const t = targetAt(x, y)
+  t.dispatchEvent(new PointerEvent('pointerover', init))
+  t.dispatchEvent(new MouseEvent('mouseover', init))
+  t.dispatchEvent(new PointerEvent('pointerenter', init))
+  t.dispatchEvent(new MouseEvent('mouseenter', init))
+  t.dispatchEvent(new PointerEvent('pointerdown', init))
+  t.dispatchEvent(new MouseEvent('mousedown', init))
+  ;(t as HTMLElement).focus?.()
+}
+
+/** 抬起：up + click + out + leave（释放并离开） */
+function mouseUp(x: number, y: number, button: string): void {
+  const btn = buttonNum(button)
+  const pressed = 1 << btn
+  const t = targetAt(x, y)
+  const downInit = pointerInit(x, y, btn, pressed)
+  const releaseInit = pointerInit(x, y, btn, 0)
+  t.dispatchEvent(new PointerEvent('pointerup', downInit))
+  t.dispatchEvent(new MouseEvent('mouseup', downInit))
+  t.dispatchEvent(new MouseEvent('click', downInit))
+  t.dispatchEvent(new PointerEvent('pointerout', releaseInit))
+  t.dispatchEvent(new MouseEvent('mouseout', releaseInit))
+  t.dispatchEvent(new PointerEvent('pointerleave', releaseInit))
+  t.dispatchEvent(new MouseEvent('mouseleave', releaseInit))
+}
+
+/** 坐标点击：down [delay] up，可重复实现多击（dblclick） */
+async function mouseClick(
+  x: number,
+  y: number,
+  opts: { button?: string; delay?: number; clickCount?: number } = {},
+): Promise<void> {
+  const button = opts.button ?? 'left'
+  const delay = opts.delay ?? 0
+  const count = opts.clickCount ?? 1
+  for (let i = 0; i < count; i++) {
+    mouseDown(x, y, button)
+    if (delay > 0) await sleep(delay)
+    mouseUp(x, y, button)
+    if (i < count - 1 && delay > 0) await sleep(delay)
+  }
+  // 多击: dispatch 原生 dblclick 事件（很多库如 jQuery 靠 dblclick 或 click.detail===2 判定）
+  if (count >= 2) {
+    const btn = buttonNum(button)
+    const detail = count
+    // 补发带 detail 的 click，并 dispatch dblclick
+    const t = targetAt(x, y)
+    const init = { bubbles: true, cancelable: true, clientX: x, clientY: y, button: btn, buttons: 0, detail, view: window }
+    t.dispatchEvent(new MouseEvent('dblclick', init))
+  }
+}
+
+/** 当前接收键盘事件的元素（activeElement 兜底 body） */
+function keyTarget(): HTMLElement {
+  return (document.activeElement as HTMLElement) || document.body
+}
+
+/** 向可输入元素插入一个字符（input/textarea 用原生 setter，contenteditable 用 execCommand） */
+function insertChar(el: HTMLElement, ch: string): void {
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    const proto =
+      el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+    Object.getOwnPropertyDescriptor(proto, 'value')?.set?.call(el, el.value + ch)
+  } else if (el.isContentEditable) {
+    try {
+      document.execCommand('insertText', false, ch)
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/** 按键 down：keydown + keypress */
+function keyboardDown(key: string): void {
+  const t = keyTarget()
+  t.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }))
+  t.dispatchEvent(new KeyboardEvent('keypress', { key, bubbles: true, cancelable: true }))
+}
+
+/** 按键 up */
+function keyboardUp(key: string): void {
+  keyTarget().dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true, cancelable: true }))
+}
+
+/** 单次按键：down + up */
+async function keyboardPress(key: string): Promise<void> {
+  keyboardDown(key)
+  await sleep(0)
+  keyboardUp(key)
+}
+
+/** 向 activeElement 逐字符输入（模拟人类打字，可选延迟） */
+async function keyboardType(text: string, delay = 50): Promise<void> {
+  const t = keyTarget()
+  if (t && typeof t.focus === 'function') t.focus()
+  for (const ch of text) {
+    const target = keyTarget()
+    target.dispatchEvent(new KeyboardEvent('keydown', { key: ch, bubbles: true, cancelable: true }))
+    target.dispatchEvent(new KeyboardEvent('keypress', { key: ch, bubbles: true, cancelable: true }))
+    insertChar(target, ch)
+    target.dispatchEvent(
+      new InputEvent('input', {
+        bubbles: true,
+        cancelable: true,
+        data: ch,
+        inputType: 'insertText',
+      }),
+    )
+    target.dispatchEvent(new KeyboardEvent('keyup', { key: ch, bubbles: true, cancelable: true }))
+    if (delay > 0) await sleep(delay)
+  }
+}
+
+/** 点击 */
+async function click(selector: string, x?: number, y?: number): ContentResponse {
+  // 有坐标则直接坐标点击（对齐 playwright page.mouse.click(x,y)）；否则定位元素取中心。
+  // 这样 behavior 的坐标点击与按 selector 点击走同一套 mouse 原语。
+  let cx: number
+  let cy: number
+  if (x != null && y != null) {
+    cx = Number(x)
+    cy = Number(y)
+  } else {
+    const el = requireEl<HTMLElement>(selector)
+    if (!inViewport(el)) throw new Error('ELEMENT_OUT_OF_VIEWPORT: ' + selector + ' (scroll via ScrollController first)')
+    const c = centerOf(el)
+    cx = c.x
+    cy = c.y
+  }
+  await mouseClick(cx, cy, { button: 'left' })
+  return { ok: true, selector, x: cx, y: cy }
+}
+
+/** 填充输入框（覆盖原值） */
+function fill(selector: string, value: string): ContentResponse {
+  const el = requireEl<HTMLInputElement | HTMLTextAreaElement>(selector)
+  el.focus()
+  const proto =
+    el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+  Object.getOwnPropertyDescriptor(proto, 'value')?.set?.call(el, value)
+  el.dispatchEvent(new InputEvent('input', { bubbles: true, data: value, inputType: 'insertText' }))
+  el.dispatchEvent(new Event('change', { bubbles: true }))
+  return { ok: true, selector, value }
+}
+
+/** 逐字符输入（模拟人类打字，带可选延迟 ms） */
+async function type(selector: string, value: string, delay = 50): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  // 可输入元素 focus 后输入；非输入元素（如 body）向当前 activeElement 输入，
+  // 支持 behavior.typeText 的“无目标纯打字”场景。
+  const isInput =
+    el instanceof HTMLInputElement ||
+    el instanceof HTMLTextAreaElement ||
+    el.isContentEditable
+  if (isInput) {
+    el.focus()
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) el.value = ''
+  }
+  await keyboardType(value, delay)
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    el.dispatchEvent(new Event('change', { bubbles: true }))
+  }
+  return { ok: true, selector, value }
+}
+
+/** 在元素上按键（Enter/Escape/Tab 等） */
+async function press(selector: string, key: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  el.focus()
+  await keyboardPress(key)
+  // Enter 提交表单容错
+  if (key === 'Enter' && el instanceof HTMLInputElement) {
+    const form = el.form
+    if (form) form.requestSubmit?.()
+  }
+  return { ok: true, selector, key }
+}
+
+/** 悬停（触发 hover 进入事件 + mousemove） */
+function hover(selector: string, x?: number, y?: number): ContentResponse {
+  let cx: number
+  let cy: number
+  if (x != null && y != null) {
+    cx = Number(x)
+    cy = Number(y)
+  } else {
+    const el = requireEl<HTMLElement>(selector)
+    if (!inViewport(el)) throw new Error('ELEMENT_OUT_OF_VIEWPORT: ' + selector + ' (scroll via ScrollController first)')
+    const c = centerOf(el)
+    cx = c.x
+    cy = c.y
+  }
+  mouseHover(cx, cy)
+  return { ok: true, selector, x: cx, y: cy }
+}
+
+/** 聚焦元素 */
+function focus(selector: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  if (!inViewport(el)) throw new Error('ELEMENT_OUT_OF_VIEWPORT: ' + selector + ' (scroll via ScrollController first)')
+  el.focus()
+  return { ok: true, selector }
+}
+
+/** 纯移动到坐标（不点击）：behavior 拟人轨迹多点序列注入用 */
+function mouseMoveTo(x: number, y: number): ContentResponse {
+  mouseMove(Number(x), Number(y))
+  return { ok: true, x: Number(x), y: Number(y) }
+}
+
+/** 勾选复选框 / 单选框 */
+function check(selector: string, checked = true): ContentResponse {
+  const el = requireEl<HTMLInputElement>(selector)
+  if (el.checked !== checked) {
+    el.checked = checked
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+    el.dispatchEvent(new Event('change', { bubbles: true }))
+  }
+  return { ok: true, selector, checked: el.checked }
+}
+
+/** 取消勾选 */
+function uncheck(selector: string): ContentResponse {
+  return check(selector, false)
+}
+
+/** 下拉选择（支持单值字符串） */
+function selectOption(selector: string, value: string): ContentResponse {
+  const el = requireEl<HTMLSelectElement>(selector)
+  const matched = Array.from(el.options).find((o) => o.value === value || o.text === value)
+  if (!matched) throw new Error(`selectOption: option not found for value="${value}"`)
+  el.value = matched.value
+  el.dispatchEvent(new Event('input', { bubbles: true }))
+  el.dispatchEvent(new Event('change', { bubbles: true }))
+  return { ok: true, selector, value: el.value }
+}
+
+/** 等待选择器出现（轮询，默认超时 30s） */
+async function waitForSelector(selector: string, timeout = 30000): ContentResponse {
+  const deadline = Date.now() + timeout
+  while (Date.now() < deadline) {
+    const el = document.querySelector(selector)
+    if (el) {
+      // 不滚动 (滚动统一由 ScrollController)。返回是否在视口
+      return { ok: true, selector, visible: true, inViewport: inViewport(el) }
+    }
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  throw new Error(`waitForSelector timeout (${timeout}ms): ${selector}`)
+}
+
+// ── 读取类（对齐 playwright 的 innerHTML/innerText/textContent 等）──
+
+/** 读取元素 innerHTML */
+function innerHTML(selector: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  return { ok: true, selector, value: el.innerHTML }
+}
+
+/** 读取元素 innerText */
+function innerText(selector: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  return { ok: true, selector, value: el.innerText }
+}
+
+/** 读取元素 textContent */
+function textContent(selector: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  return { ok: true, selector, value: el.textContent ?? '' }
+}
+
+/** 读取元素属性 */
+function getAttribute(selector: string, name: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  return { ok: true, selector, name, value: el.getAttribute(name) }
+}
+
+/** 读取输入框当前值 */
+function inputValue(selector: string): ContentResponse {
+  const el = requireEl<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>(selector)
+  return { ok: true, selector, value: el.value }
+}
+
+/** 读取元素包围盒（位置 + 尺寸） */
+function boundingBox(selector: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  const rect = el.getBoundingClientRect()
+  return {
+    ok: true,
+    selector,
+    x: Math.round(rect.x),
+    y: Math.round(rect.y),
+    width: Math.round(rect.width),
+    height: Math.round(rect.height),
+  }
+}
+
+/** 元素计数（配合 selector 后缀语义：count 忽略后缀，返回匹配总数） */
+function count(selector: string): ContentResponse {
+  return { ok: true, selector, count: locateCount(selector) }
+}
+
+/**
+ * 文件上传。files 是 base64 编码的字节流数组。
+ * 构造 File 对象赋予 <input type=file> 的 files 属性，触发 change。
+ * 支持多文件。
+ *
+ * 注意：HTMLInputElement.files 是只读的，直接赋值在受控组件上会被忽略。
+ * 这里用 Object.getOwnPropertyDescriptor 拿到原生 setter 强制写入，
+ * 这是 playwright 等所有扩展上传库的标准做法。
+ */
+function setInputFiles(selector: string, files: Array<{ name: string; mime: string; data: string; webkitRelativePath?: string }>): ContentResponse {
+  const el = requireEl<HTMLInputElement>(selector)
+  if (el.tagName !== 'INPUT' || el.type !== 'file') {
+    throw new Error(`not a file input: ${selector} (tag=${el.tagName} type=${el.type})`)
+  }
+
+  const dt = new DataTransfer()
+  const builtNames: string[] = []
+  let totalBytes = 0
+  for (const f of files) {
+    // base64 → bytes（兼容 data: 前缀，但协议要求纯 base64）
+    const b64 = f.data.split(',').pop() ?? f.data
+    const bin = atob(b64)
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    totalBytes += bytes.length
+    const file = new File([bytes], f.name, { type: f.mime || 'application/octet-stream' })
+    // 文件夹上传（webkitdirectory input）：File.webkitRelativePath 只读，强设以表达目录结构
+    if (f.webkitRelativePath) {
+      try {
+        Object.defineProperty(file, 'webkitRelativePath', {
+          configurable: true,
+          value: f.webkitRelativePath,
+        })
+      } catch {
+        // 部分浏览器不允许覆盖，忽略（文件夹场景可能失效，但不阻塞文件上传）
+      }
+    }
+    dt.items.add(file)
+    builtNames.push(f.name)
+  }
+
+  // DataTransfer 本身的文件数（不受 input 状态影响，是“构造成功”的真相）
+  const builtCount = dt.files.length
+
+  // 强制写入 files（绕过只读限制）
+  const proto = Object.getPrototypeOf(el)
+  const descriptor = Object.getOwnPropertyDescriptor(proto, 'files')
+  if (descriptor?.set) {
+    descriptor.set.call(el, dt.files)
+  } else {
+    el.files = dt.files
+  }
+
+  el.dispatchEvent(new Event('input', { bubbles: true }))
+  el.dispatchEvent(new Event('change', { bubbles: true }))
+
+  // 同步读取赋值后、事件后的 input.files（用于诊断）
+  const onInput = el.files?.length ?? 0
+  const onInputNames = el.files ? Array.from(el.files).map((f) => f.name) : []
+
+  return {
+    ok: builtCount > 0,
+    selector,
+    requested: files.length,
+    built: builtCount,            // 成功构造进 DataTransfer 的文件数（必须 == requested）
+    onInput,                      // 赋值+事件后 input.files 里的文件数（可能被框架清空）
+    names: builtNames,
+    onInputNames,
+    totalBytes,
+    note:
+      onInput === 0 && builtCount > 0
+        ? 'files constructed and set, but input.files now empty — 框架可能已接收并清空，看页面 UI 是否出现文件'
+        : undefined,
+  }
+}
+
+// ── localStorage 读写 ──
+
+function getLocalStorage(keys?: string[]): ContentResponse {
+  const result: Record<string, string | null> = {}
+  const targetKeys = keys && keys.length > 0 ? keys : Object.keys(localStorage)
+  for (const k of targetKeys) result[k] = localStorage.getItem(k)
+  return { ok: true, storage: result }
+}
+
+function setLocalStorage(items: Record<string, string>): ContentResponse {
+  let n = 0
+  for (const [k, v] of Object.entries(items)) {
+    localStorage.setItem(k, v)
+    n++
+  }
+  return { ok: true, count: n }
+}
+
+function removeLocalStorage(keys?: string[]): ContentResponse {
+  const targetKeys = keys && keys.length > 0 ? keys : Object.keys(localStorage)
+  for (const k of targetKeys) localStorage.removeItem(k)
+  return { ok: true, count: targetKeys.length }
+}
+
+function clearLocalStorage(): ContentResponse {
+  localStorage.clear()
+  return { ok: true }
+}
+
+/** 双击 */
+async function dblclick(selector: string): ContentResponse {
+  const el = requireEl<HTMLElement>(selector)
+  if (!inViewport(el)) throw new Error('ELEMENT_OUT_OF_VIEWPORT: ' + selector + ' (scroll via ScrollController first)')
+  const { x, y } = centerOf(el)
+  await mouseClick(x, y, { clickCount: 2 })
+  return { ok: true, selector }
+}
+
+/** 拖拽：从源选择器拖到目标选择器。
+ * 两种实现叠加，兼容两类站点：
+ * 1) mouse 事件序列 (mousedown/mousemove/mouseup) —— jQuery UI draggable/droppable
+ *    这类监听 mouse 事件 (非原生 HTML5 drag)
+ * 2) HTML5 drag 事件 dispatch —— 原生 drag/drop 监听者
+ */
+function dragTo(sourceSelector: string, targetSelector: string): ContentResponse {
+  const source = requireEl<HTMLElement>(sourceSelector)
+  const target = requireEl<HTMLElement>(targetSelector)
+  // dragTo 不检测视口: 拖拽可能跨视口, 滚动由 browser 技能在调用前用 ScrollController 处理
+  const s = centerOf(source)
+  const t = centerOf(target)
+
+  // 1) mouse 序列：source 上 down，分步 move 到 target，最后 up
+  mouseDown(s.x, s.y, 'left')
+  const steps = 10
+  for (let i = 1; i <= steps; i++) {
+    const mx = s.x + (t.x - s.x) * i / steps
+    const my = s.y + (t.y - s.y) * i / steps
+    mouseMove(mx, my)
+  }
+  mouseUp(t.x, t.y, 'left')
+
+  // 2) HTML5 drag 事件 dispatch (兼容原生 drag 监听者)
+  const dataTransfer = new DataTransfer()
+  for (const type of ['dragstart', 'drag', 'dragenter', 'dragover', 'drop', 'dragend'] as const) {
+    const evt = new DragEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      dataTransfer,
+      clientX: 0,
+      clientY: 0,
+    })
+    ;(type === 'drop' || type === 'dragover' || type === 'dragenter' ? target : source).dispatchEvent(evt)
+  }
+  return { ok: true, source: sourceSelector, target: targetSelector }
+}
+
+// ── 等待类（对齐 playwright 的 waitForFunction / waitForURL / waitForTimeout）──
+
+/** 等待自定义条件（函数源码在 content 内执行，返回 truthy 即完成） */
+async function waitForFunction(source: string, timeout = 30000, args?: unknown): ContentResponse {
+  if (!source) throw new Error('waitForFunction requires source')
+  // eslint-disable-next-line no-eval
+  const fn = (0, eval)(`(${source})`) as (args: unknown) => unknown
+  const deadline = Date.now() + timeout
+  while (Date.now() < deadline) {
+    let truthy = false
+    let value: unknown
+    try {
+      value = fn(args)
+      truthy = !!value
+    } catch {
+      // 条件报错继续等
+    }
+    if (truthy) return { ok: true, source, value }
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  throw new Error(`waitForFunction timeout (${timeout}ms)`)
+}
+
+/** 等待当前页 URL 匹配（字符串包含或正则） */
+async function waitForURL(urlMatch: string, timeout = 30000): ContentResponse {
+  const deadline = Date.now() + timeout
+  let re: RegExp | null = null
+  try {
+    re = new RegExp(urlMatch)
+  } catch {
+    re = null // 不是合法正则，当作字符串包含匹配
+  }
+  while (Date.now() < deadline) {
+    const href = location.href
+    if ((re && re.test(href)) || (!re && href.includes(urlMatch))) {
+      return { ok: true, url: href }
+    }
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  throw new Error(`waitForURL timeout (${timeout}ms): ${urlMatch}`)
+}
+
+/** 等待固定时长 */
+async function waitForTimeout(ms: number): ContentResponse {
+  await new Promise((r) => setTimeout(r, Math.min(ms, 120000)))
+  return { ok: true, ms }
+}
+
+// ── dialog 自动处理（页面级 window.alert/confirm/prompt 拦截）──
+
+/** 全局 dialog 处理策略。不调用本方法时，页面默认弹窗行为不变。 */
+let dialogHandler: ((type: string, message: string) => 'accept' | 'dismiss') | null = null
+
+function setDialogHandler(handlerSource: string | null): ContentResponse {
+  if (!handlerSource) {
+    dialogHandler = null
+    return { ok: true, enabled: false }
+  }
+  // eslint-disable-next-line no-eval
+  dialogHandler = (0, eval)(`(${handlerSource})`) as (
+    type: string,
+    message: string,
+  ) => 'accept' | 'dismiss'
+  return { ok: true, enabled: true }
+}
+
+// content 加载时接管 window 的三个对话框方法
+;['alert', 'confirm', 'prompt'].forEach((m) => {
+  const original = (window as unknown as Record<string, unknown>)[m] as Function
+  Object.defineProperty(window, m, {
+    configurable: true,
+    value(message?: unknown) {
+      if (dialogHandler) {
+        const action = dialogHandler(m, String(message ?? ''))
+        if (action === 'dismiss') return m === 'prompt' ? null : false
+      }
+        // 默认 accept：调用原生行为
+        return m === 'alert' ? undefined : m === 'confirm' ? true : ''
+        void original
+      },
+    })
+  })
+
+// ── aria snapshot（playwright ariaSnapshot 兼容）──
+
+/** 默认每块字符数 */
+const SNAPSHOT_CHUNK_SIZE = 10000
+
+/**
+ * snapshot 缓存：同一份参数（rootSelector+depth+interactiveOnly）只扫一次，
+ * 分块共享同一份 ref 映射，保证 ref 在所有块中稳定一致。
+ * 页面变化后调用方传 refresh=true 重扫。
+ */
+let snapshotCache: {
+  key: string
+  yaml: string
+  lines: string[]
+  chunkSize: number
+  chunkCount: number
+} | null = null
+
+function makeCacheKey(opts: {
+  rootSelector?: string
+  depth?: number
+  interactiveOnly?: boolean
+}): string {
+  return [opts.rootSelector ?? '', String(opts.depth ?? ''), String(opts.interactiveOnly ?? false)].join('|')
+}
+
+/** 按行 + 字数分块。块边界落在行边界，不切断行。 */
+function chunkLines(lines: string[], chunkSize: number): string[][] {
+  const chunks: string[][] = []
+  let cur: string[] = []
+  let curLen = 0
+  for (const line of lines) {
+    if (curLen + line.length > chunkSize && cur.length > 0) {
+      chunks.push(cur)
+      cur = []
+      curLen = 0
+    }
+    cur.push(line)
+    curLen += line.length + 1 // +1 for newline
+  }
+  if (cur.length > 0) chunks.push(cur)
+  return chunks
+}
+
+function snapshot(opts: {
+  rootSelector?: string
+  depth?: number
+  interactiveOnly?: boolean
+  chunkId?: number
+  chunkSize?: number
+  refresh?: boolean
+}): ContentResponse {
+  const key = makeCacheKey(opts)
+  const chunkSize = opts.chunkSize && opts.chunkSize > 0 ? opts.chunkSize : SNAPSHOT_CHUNK_SIZE
+
+  // 缓存未命中或强制刷新 → 重扫
+  if (!snapshotCache || snapshotCache.key !== key || snapshotCache.chunkSize !== chunkSize || opts.refresh) {
+    const result = ariaSnapshot({
+      rootSelector: opts.rootSelector,
+      depth: opts.depth,
+      interactiveOnly: opts.interactiveOnly,
+    })
+    const lines = result.yaml.length > 0 ? result.yaml.split('\n') : []
+    const chunks = chunkLines(lines, chunkSize)
+    snapshotCache = {
+      key,
+      yaml: result.yaml,
+      lines,
+      chunkSize,
+      chunkCount: chunks.length,
+    }
+    // 缓存分块内容到闭包变量（供取块用）
+    snapshotChunks = chunks
+  }
+
+  const cache = snapshotCache!
+  const id = opts.chunkId ?? 0
+  const chunk = snapshotChunks[id]
+  const yaml = chunk ? chunk.join('\n') : ''
+  const hasMore = id + 1 < cache.chunkCount
+
+  return {
+    ok: true,
+    yaml,
+    chunkId: id,
+    chunkCount: cache.chunkCount,
+    chunkSize: cache.chunkSize,
+    hasMore,
+    totalChars: cache.yaml.length,
+    hint: hasMore ? `还有 ${cache.chunkCount - id - 1} 块，用 snapshot({chunkId: ${id + 1}}) 续取` : undefined,
+  }
+}
+
+/** 分块缓存（snapshot 扫描后填充） */
+let snapshotChunks: string[][] = []
+
+export default defineContentScript({
+  matches: ['<all_urls>'],
+  allFrames: true,
+  runAt: 'document_idle',
+  main() {
+    chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+      if (message?.source !== 'bee-plugin') return
+
+      const method = message.method as string
+      const params = (message.params ?? {}) as Record<string, unknown>
+
+      let p: Promise<ContentResponse>
+      switch (method) {
+        // ping: 只证明 listener 已注册, 不碰复杂 DOM, 不抛业务错。
+        // background 用它判 content script 是否就绪 (不就绪则注入后重试)。
+        case 'ping':
+          p = Promise.resolve({ ok: true, route: 'extension-content', url: location.href, readyState: document.readyState })
+          break
+        case 'status':
+          p = asResponse(() => status())
+          break
+        case 'click':
+          p = asResponse(() =>
+            click(
+              String(params.selector ?? ''),
+              typeof params.x === 'number' ? params.x : undefined,
+              typeof params.y === 'number' ? params.y : undefined,
+            ),
+          )
+          break
+        case 'fill':
+          p = asResponse(() => fill(String(params.selector ?? ''), String(params.value ?? '')))
+          break
+        case 'type':
+          p = asResponse(() =>
+            type(String(params.selector ?? ''), String(params.value ?? ''), Number(params.delay ?? 50)),
+          )
+          break
+        case 'press':
+          p = asResponse(() => press(String(params.selector ?? ''), String(params.key ?? '')))
+          break
+        case 'hover':
+          p = asResponse(() =>
+            hover(
+              String(params.selector ?? ''),
+              typeof params.x === 'number' ? params.x : undefined,
+              typeof params.y === 'number' ? params.y : undefined,
+            ),
+          )
+          break
+        case 'focus':
+          p = asResponse(() => focus(String(params.selector ?? '')))
+          break
+        case 'mouseMove':
+          p = asResponse(() => mouseMoveTo(Number(params.x ?? 0), Number(params.y ?? 0)))
+          break
+        case 'check':
+          p = asResponse(() => check(String(params.selector ?? '')))
+          break
+        case 'uncheck':
+          p = asResponse(() => uncheck(String(params.selector ?? '')))
+          break
+        case 'selectOption':
+          p = asResponse(() =>
+            selectOption(String(params.selector ?? ''), String(params.value ?? '')),
+          )
+          break
+        case 'waitForSelector':
+          p = asResponse(() =>
+            waitForSelector(String(params.selector ?? ''), Number(params.timeout ?? 30000)),
+          )
+          break
+        // 读取类
+        case 'innerHTML':
+          p = asResponse(() => innerHTML(String(params.selector ?? '')))
+          break
+        case 'innerText':
+          p = asResponse(() => innerText(String(params.selector ?? '')))
+          break
+        case 'textContent':
+          p = asResponse(() => textContent(String(params.selector ?? '')))
+          break
+        case 'getAttribute':
+          p = asResponse(() =>
+            getAttribute(String(params.selector ?? ''), String(params.name ?? '')),
+          )
+          break
+        case 'inputValue':
+          p = asResponse(() => inputValue(String(params.selector ?? '')))
+          break
+        case 'boundingBox':
+          p = asResponse(() => boundingBox(String(params.selector ?? '')))
+          break
+        // 元素计数
+        case 'count':
+          p = asResponse(() => count(String(params.selector ?? '')))
+          break
+        // 文件上传
+        case 'setInputFiles':
+          p = asResponse(() =>
+            setInputFiles(
+              String(params.selector ?? ''),
+              Array.isArray(params.files) ? (params.files as Array<Record<string, string>>) : [],
+            ),
+          )
+          break
+        // localStorage
+        case 'getLocalStorage':
+          p = asResponse(() =>
+            getLocalStorage(Array.isArray(params.keys) ? (params.keys as string[]) : undefined),
+          )
+          break
+        case 'setLocalStorage':
+          p = asResponse(() =>
+            setLocalStorage((params.items ?? {}) as Record<string, string>),
+          )
+          break
+        case 'removeLocalStorage':
+          p = asResponse(() =>
+            removeLocalStorage(Array.isArray(params.keys) ? (params.keys as string[]) : undefined),
+          )
+          break
+        case 'clearLocalStorage':
+          p = asResponse(() => clearLocalStorage())
+          break
+        // 交互进阶
+        case 'dblclick':
+          p = asResponse(() => dblclick(String(params.selector ?? '')))
+          break
+        case 'dragTo':
+          p = asResponse(() =>
+            dragTo(String(params.source ?? ''), String(params.target ?? '')),
+          )
+          break
+        // 等待类
+        case 'waitForFunction':
+          p = asResponse(() =>
+            waitForFunction(
+              String(params.source ?? ''),
+              Number(params.timeout ?? 30000),
+              params.args,
+            ),
+          )
+          break
+        case 'waitForURL':
+          p = asResponse(() =>
+            waitForURL(String(params.url ?? ''), Number(params.timeout ?? 30000)),
+          )
+          break
+        case 'waitForTimeout':
+          p = asResponse(() => waitForTimeout(Number(params.ms ?? 1000)))
+          break
+        // dialog
+        case 'setDialogHandler':
+          p = asResponse(() =>
+            setDialogHandler(params.handler == null ? null : String(params.handler)),
+          )
+          break
+        // ── aria snapshot ──
+        case 'snapshot':
+          p = asResponse(() =>
+            snapshot({
+              rootSelector: params.rootSelector == null ? undefined : String(params.rootSelector),
+              depth: typeof params.depth === 'number' ? params.depth : undefined,
+              interactiveOnly: params.interactiveOnly === true,
+              chunkId: typeof params.chunkId === 'number' ? params.chunkId : 0,
+              chunkSize: typeof params.chunkSize === 'number' ? params.chunkSize : undefined,
+              refresh: params.refresh === true,
+            }),
+          )
+          break
+        // ── 可见文本定位 (返回 bbox, 不返回 DOM handle) ──
+        case 'locateVisibleText':
+          p = asResponse(() =>
+            locateVisibleTextInContent({
+              text: String(params.text ?? ''),
+              exact: params.exact === true,
+              index: typeof params.index === 'number' ? params.index : undefined,
+            }),
+          )
+          break
+        // ── 坐标点击 (合成 pointer/mouse 事件序列, route=extension-content) ──
+        case 'clickAt':
+          p = asResponse(async () => {
+            const x = Number(params.x), y = Number(params.y)
+            if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error('clickAt: x/y must be finite')
+            const t = targetAt(x, y)
+            await mouseClick(x, y, { button: (params.button as string) || 'left', clickCount: Number(params.clickCount ?? 1) })
+            return { ok: true, x, y, route: 'extension-content', trusted: false, targetTag: t?.tagName, targetText: (t?.textContent || '').trim().slice(0, 40) } as any
+          })
+          break
+        // ── 定位可见文本 → 立即点击 (content script 原子完成, 防 DOM 重渲染) ──
+        case 'clickByText':
+          p = asResponse(async () => {
+            const loc = locateVisibleTextInContent({
+              text: String(params.text ?? ''),
+              exact: params.exact === true,
+              index: typeof params.index === 'number' ? params.index : undefined,
+            })
+            if (!loc.matches || loc.matches.length === 0) {
+              throw new Error('clickByText: text not visible: ' + params.text)
+            }
+            const idx = Math.max(0, Math.min(loc.matches.length - 1, Number(params.index ?? 0)))
+            const m = loc.matches[idx]
+            const x = Math.round(m.centerX + Number(params.offsetX ?? 0))
+            const y = Math.round(m.centerY + Number(params.offsetY ?? 0))
+            const t = targetAt(x, y)
+            await mouseClick(x, y, { button: (params.button as string) || 'left', clickCount: Number(params.clickCount ?? 1) })
+            return { ok: true, text: params.text, x, y, match: m, route: 'extension-content', trusted: false, targetTag: t?.tagName, targetText: (t?.textContent || '').trim().slice(0, 40) } as any
+          })
+          break
+        default:
+          p = Promise.resolve({ ok: false, error: `unknown method: ${method}` })
+      }
+
+      p.then((res) => sendResponse(res))
+      return true // 异步响应
+    })
+
+    console.log('[WebPlater] content script loaded', location.href)
+  },
+})
+
+// ── locateVisibleText: 扫描可见文本节点, 返回 bbox (不返回 DOM handle) ────
+//
+// 用 Range.getBoundingClientRect() 取文本节点的精确 bbox (比 element.getBoundingClientRect
+// 更准, 能定位到单元格内的文字而非整个 td)。
+// 过滤: display:none / visibility:hidden / opacity:0 / 零面积 / 不在 viewport。
+// 匹配: exact (===) 或 contains (includes)。返回所有 match 的 bbox 列表。
+function locateVisibleTextInContent(opts: {
+  text: string
+  exact?: boolean
+  index?: number
+}): { ok: true; matches: Array<{
+  text: string
+  x: number
+  y: number
+  width: number
+  height: number
+  centerX: number
+  centerY: number
+  visible: boolean
+}> } {
+  const { text, exact = false } = opts
+  const wantIndex = typeof opts.index === 'number' ? opts.index : 0
+  const matches: Array<{
+    text: string
+    x: number
+    y: number
+    width: number
+    height: number
+    centerX: number
+    centerY: number
+    visible: boolean
+  }> = []
+
+  // 可见性判定: 沿祖先链查 display/visibility/opacity + 零面积
+  const isVisible = (el: Element | null): boolean => {
+    let cur: Element | null = el
+    while (cur && cur !== document.body) {
+      const cs = getComputedStyle(cur)
+      if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) {
+        return false
+      }
+      cur = cur.parentElement
+    }
+    return true
+  }
+
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) => {
+      const t = (node.nodeValue || '').trim()
+      if (!t) return NodeFilter.FILTER_REJECT
+      // 文本匹配预筛
+      const hit = exact ? t === text : t.includes(text)
+      if (!hit) return NodeFilter.FILTER_REJECT
+      const parent = node.parentElement
+      if (!parent || !isVisible(parent)) return NodeFilter.FILTER_REJECT
+      return NodeFilter.FILTER_ACCEPT
+    },
+  })
+
+  const vh = window.innerHeight || document.documentElement.clientHeight
+  const vw = window.innerWidth || document.documentElement.clientWidth
+
+  while (walker.nextNode()) {
+    const node = walker.currentNode as Text
+    const parent = node.parentElement
+    if (!parent) continue
+    // 用 Range 取文字精确 bbox
+    let rect: DOMRect | null = null
+    try {
+      const range = document.createRange()
+      range.selectNodeContents(node)
+      rect = range.getBoundingClientRect()
+    } catch {
+      rect = parent.getBoundingClientRect()
+    }
+    if (!rect || rect.width <= 0 || rect.height <= 0) continue
+    const centerX = rect.x + rect.width / 2
+    const centerY = rect.y + rect.height / 2
+    // 在 viewport 内才算 (允许部分露出: 中心点在视口)
+    const inViewport = centerY >= 0 && centerY <= vh && centerX >= 0 && centerX <= vw
+    if (!inViewport) continue
+    matches.push({
+      text: (node.nodeValue || '').trim().slice(0, 80),
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+      centerX: Math.round(centerX),
+      centerY: Math.round(centerY),
+      visible: true,
+    })
+  }
+
+  // 按 index 选 (默认 0), 但返回全部 match 供调用方决策
+  void wantIndex
+  return { ok: true, matches }
+}