aihand 0.0.1 → 0.1.1

package/src/ui/core/action.ts

@@ -0,0 +1,747 @@
+/// <reference lib="dom" />
+// aihand actions — write capability over the existing HMR channel.
+//
+// Two layers, intentionally split:
+//   - resolveAction(): pure param validation. Runs plugin-side, unit-tested.
+//   - performAction(): real DOM mutation. Runs browser-side (client.ts imports it).
+//     References window/document — never imported plugin-side.
+
+declare global {
+    interface Window {
+        // The app's own domain projection — co-located with its consumer (doAssert) so the
+        // augmentation is present wherever action.ts is imported, not only via client.ts.
+        __AIPEEK_SCREEN__?: () => Record<string, unknown>
+    }
+}
+
+export type ActionType = 'click' | 'dblclick' | 'fill' | 'press' | 'wait' | 'screenshot' | 'realclick' | 'query' | 'assert'
+    | 'drag' | 'scrollIntoView' | 'drop' | 'clipboard' | 'hover'
+
+export interface ActionArgs {
+    sel?: string
+    text?: string
+    value?: string
+    key?: string
+    timeout?: number
+    gone?: boolean
+    // wait: poll until the matched element loses [disabled] (a button that flips enabled).
+    enabled?: boolean
+    button?: 'left' | 'right'
+    x?: number
+    y?: number
+    // assert: a domain key (from __AIPEEK_SCREEN__) or a CSS sel, checked against `equals`.
+    screen?: string
+    equals?: string
+    // drag: sel/text = source, to = destination selector. drop: sel = target, files = names.
+    to?: string
+    files?: string[]
+    // clipboard: mode read|write; value = text to write (write only).
+    mode?: 'read' | 'write'
+}
+
+export interface ActionResult {
+    ok: boolean
+    detail?: string
+    error?: string
+    dataUrl?: string
+    screen?: string
+    // For an action that triggers an async flow (send a message → stream → done), the
+    // time-stamped state trajectory: S₀ →(Δt) S₁ →(Δt) … →(Δt) Sₙ. `screen` is the net
+    // before/after diff; `flow` is *how* it got there. Absent for synchronous actions.
+    flow?: string
+    actions?: string
+    x?: number
+    y?: number
+    // realclick only: true if the page already fired the trusted click in-process (Electron).
+    // false/undefined means a plain Chrome tab couldn't, so the server drives its CDP queue.
+    fired?: boolean
+}
+
+export const TYPES: ActionType[] = ['click', 'dblclick', 'fill', 'press', 'wait', 'screenshot', 'realclick', 'query', 'assert', 'drag', 'scrollIntoView', 'drop', 'clipboard', 'hover']
+
+// --- Pure validation (plugin-side) ---
+
+export function resolveAction(type: string, args: ActionArgs): { valid: boolean, error?: string } {
+    if (!TYPES.includes(type as ActionType))
+        return { valid: false, error: `unknown action: ${type}` }
+
+    const hasTarget = !!(args.sel || args.text)
+    switch (type) {
+        case 'click':
+            return hasTarget ? { valid: true } : { valid: false, error: 'click needs sel= or text=' }
+        case 'dblclick':
+            return hasTarget ? { valid: true } : { valid: false, error: 'dblclick needs sel= or text=' }
+        case 'hover':
+            return hasTarget ? { valid: true } : { valid: false, error: 'hover needs sel= or text=' }
+        case 'realclick':
+            return hasTarget || (args.x !== undefined && args.y !== undefined) ? { valid: true } : { valid: false, error: 'realclick needs sel=, text=, or x= & y=' }
+        case 'fill':
+            if (!hasTarget)
+                return { valid: false, error: 'fill needs sel= or text=' }
+            if (args.value === undefined)
+                return { valid: false, error: 'fill needs value=' }
+            return { valid: true }
+        case 'press':
+            return args.key ? { valid: true } : { valid: false, error: 'press needs key=' }
+        case 'wait':
+            return hasTarget ? { valid: true } : { valid: false, error: 'wait needs sel= or text=' }
+        case 'screenshot':
+            return { valid: true }
+        case 'query':
+            return args.sel ? { valid: true } : { valid: false, error: 'query needs sel=' }
+        case 'assert':
+            if (!args.screen && !args.sel)
+                return { valid: false, error: 'assert needs screen= (a __AIPEEK_SCREEN__ key) or sel=' }
+            if (args.equals === undefined)
+                return { valid: false, error: 'assert needs equals=' }
+            return { valid: true }
+        case 'drag':
+            if (!hasTarget)
+                return { valid: false, error: 'drag needs sel= or text= (the source)' }
+            if (!args.to)
+                return { valid: false, error: 'drag needs to= (destination selector)' }
+            return { valid: true }
+        case 'scrollIntoView':
+            return hasTarget ? { valid: true } : { valid: false, error: 'scrollIntoView needs sel= or text=' }
+        case 'drop':
+            if (!hasTarget)
+                return { valid: false, error: 'drop needs sel= or text= (the drop target)' }
+            if (!args.files || !args.files.length)
+                return { valid: false, error: 'drop needs files= (array of file names)' }
+            return { valid: true }
+        case 'clipboard':
+            if (args.mode === 'write' && args.value === undefined)
+                return { valid: false, error: 'clipboard write needs value=' }
+            return { valid: true }
+        default:
+            return { valid: false, error: `unknown action: ${type}` }
+    }
+}
+
+// --- Browser-side execution (client.ts only) ---
+
+// 命中判定原语（INTERACTIVE/getDirectText/elementLabel/isVisible/reachable）的真身已搬进
+// DOM 命中判定原语（INTERACTIVE/getDirectText/elementLabel/isVisible/reachable）的本地副本。
+// 曾从 teact/dom 跨包 import —— 但那是运行时依赖，发布后会把一个会撞 npm 名的 teact 拉进
+// 用户机器，必炸。这 64 行是零依赖纯 DOM 函数，内联自己一份；teact 测试侧另有逻辑等价的
+// 一份，跨仓两份无运行时耦合（见 candidates.ts 头部）。re-export 让 client.ts 的
+// `from '../core/action'` 无需改路径。
+// isSensitive/safeValue moved down to candidates.ts (next to isSecretKey/redactSecretValue)
+// because elementLabel there now reads input value too — label + state suffix must share the
+// one redaction chokepoint. Re-exported so `from '../core/action'` consumers need no change.
+export { elementLabel, getDirectText, INTERACTIVE, isSecretKey, isSensitive, isVisible, reachable, safeValue } from './candidates'
+import { elementLabel, INTERACTIVE, isBusyKey, isSensitive, isVisible, pickByText, reachable, safeValue } from './candidates'
+
+export function findElement(sel?: string, text?: string): Element | null {
+    if (sel) {
+        try {
+            return document.querySelector(sel)
+        }
+        catch {
+            throw new Error(`invalid selector: ${sel} — URL-encode it (curl -G --data-urlencode 'sel=...')`)
+        }
+    }
+    if (text) {
+        // argmax over (exactness, reachability, tightness) — see candidates.matchScore.
+        // A covered/off-viewport target still resolves (reach just scores lower), so the
+        // caller can scrollIntoView/realclick; an exact tight reachable leaf always wins.
+        return pickByText(document.querySelectorAll(INTERACTIVE), text)
+    }
+    return null
+}
+
+function clickableList(): string {
+    // Clip to the open modal's subtree when present — the layer beneath is
+    // unreachable, so listing it (e.g. 90 chat items) is pure noise.
+    const root = document.querySelector('[role="dialog"][data-state="open"]') ?? document
+    const els = Array.from(root.querySelectorAll(INTERACTIVE))
+        .filter(reachable)
+        .map(el => elementLabel(el).slice(0, 40))
+        .filter(Boolean)
+    return [...new Set(els)].slice(0, 30).join(' | ')
+}
+
+// The fillable counterpart of clickableList — the real input/textarea/contenteditable fields,
+// each with a copy-paste selector so a doFill that hit an overlay can be retargeted with sel=.
+// Prefer #id, then [name=…] (stable on forms), else the bare tag (still narrows the search).
+function fillableList(): string {
+    const root = document.querySelector('[role="dialog"][data-state="open"]') ?? document
+    const els = Array.from(root.querySelectorAll('input:not([type=hidden]), textarea, [contenteditable]'))
+        .filter(reachable)
+        .map((el) => {
+            const sel = el.id
+                ? `#${el.id}`
+                : el.getAttribute('name')
+                    ? `${el.tagName.toLowerCase()}[name="${el.getAttribute('name')}"]`
+                    : el.tagName.toLowerCase()
+            const label = elementLabel(el).slice(0, 30)
+            return `sel=${sel}${label ? ` (${label})` : ''}`
+        })
+    return [...new Set(els)].slice(0, 20).join(' | ') || '(no fillable fields found)'
+}
+
+export async function performAction(type: ActionType, args: ActionArgs): Promise<ActionResult> {
+    try {
+        switch (type) {
+            case 'click': return await doClick(args)
+            case 'dblclick': return doDblclick(args)
+            case 'hover': return doHover(args)
+            case 'realclick': return doResolveRealClick(args)
+            case 'fill': return doFill(args)
+            case 'press': return doPress(args)
+            case 'wait': return await doWait(args)
+            case 'screenshot': return await doScreenshot(args)
+            case 'query': return doQuery(args)
+            case 'assert': return doAssert(args)
+            case 'drag': return doDrag(args)
+            case 'scrollIntoView': return doScrollIntoView(args)
+            case 'drop': return doDrop(args)
+            case 'clipboard': return await doClipboard(args)
+        }
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) }
+    }
+}
+
+export interface EvalResult { ok: boolean, value?: string, error?: string, hint?: string }
+
+// Refine an eval outcome into an actionable hint — the diagnostic fiber must subdivide
+// to the action fiber, else /eval's generality swallows the better tool. Two traps with a
+// CLEAN signal (the hint is never wrong) survive:
+//   1. illegal selector → raw `SyntaxError: ... is not a valid selector` DOM stack, no
+//      cue that the *selector argument* is the problem (CJK/special chars unescaped).
+//   2. /eval used as a hand-rolled /state — reading the store via indexedDB/localStorage,
+//      when /state returns every snapshot in one read.
+// A `querySelectorAll` rule was tried and REMOVED: live QA fired it on legitimate
+// cross-element aggregation (`.map(e=>({tag,label,value}))`, `.filter`) that /query can't
+// reproduce — value beyond the noise of nagging a correct escape-hatch use was negative.
+// 元真理: a hint that misfires on valid use is worse than no hint. Pure, unit-tested.
+export function diagnoseEval(code: string, ok: boolean, error?: string): string | undefined {
+    const has = (hay: string | undefined, needle: string) => !!hay && hay.includes(needle)
+    if (!ok) {
+        if (has(error, 'is not a valid selector') || has(error, "Failed to execute 'querySelector"))
+            return 'illegal CSS selector — selectors match on class/role/attr, not text. For non-ASCII or text matching use /query?sel= or /click?text=, not a raw querySelector.'
+        return undefined
+    }
+    // store read hand-rolled over indexedDB/localStorage or the raw store registry → the /state
+    // axis does it typed: overview / per-store / nested-path, no Promise template, no truncation.
+    if (has(code, 'indexedDB.open') || has(code, 'localStorage.getItem') || has(code, 'localforage') || has(code, '__AIPEEK_STORES__'))
+        return 'reading store state by hand — the /state axis is typed: /state lists every store, /state/<name> drills into one, /state?path=store.field.0 expands a nested value (e.g. /state?path=imStore.conversations.0).'
+    return undefined
+}
+
+// /action is the green channel (knob morphism replay / named semantic fn). It is NOT the
+// simulate-a-human endpoint — that's /click /fill /press /hover. But `action` is the most
+// generic verb, so an agent that wants "do something" reaches for /action and brings /click's
+// params (text=, sel=, value=, key=). When knob= AND name= are both absent, those keys can
+// only be a misroute: refine the diagnosis to the action fiber by pointing at the right
+// endpoint, instead of the dead-end "needs knob or name" (a recoverable misroute pessimistically
+// collapsed to "rethink"). Pure, unit-tested. 元真理: only fires when both knob+name are absent,
+// so it never nags a legitimate /action?knob=X&value=8 call.
+const MISROUTE: Record<string, string> = {
+    text: '/click?text= (or /fill /press)',
+    sel: '/click?sel= (or /fill /hover)',
+    value: '/fill?sel=…&value=',
+    key: '/press?key=',
+}
+export function misroutedAction(keys: string[]): string | undefined {
+    for (const k of keys) {
+        const dest = MISROUTE[k]
+        if (dest)
+            return `\`${k}=\` is a /click·/fill·/press param, not /action. /action is the green channel (?knob= replays a panel morphism, ?name= calls a mounted fn). To simulate a human click/type, use ${dest}.`
+    }
+    return undefined
+}
+
+// Run server-supplied JS in the page with auto-return (Chrome-console / Node-REPL
+// ergonomics): try the whole code as a single expression first so `qsa(...).length`
+// or `1+1` yield a value without an explicit `return`. If that fails to *compile*
+// (multi-statement, contains `return`, etc.) fall back to a plain statement block.
+// A compile error only swaps the wrapper; a runtime throw surfaces as the error.
+// undefined results are dropped (no value); objects are JSON-stringified.
+export async function runEval(code: string): Promise<EvalResult> {
+    try {
+        let fn: () => Promise<unknown>
+        try {
+            // eslint-disable-next-line no-new-func
+            fn = new Function(`return (async () => (${code}))()`) as () => Promise<unknown>
+        }
+        catch {
+            // eslint-disable-next-line no-new-func
+            fn = new Function(`return (async () => { ${code} })()`) as () => Promise<unknown>
+        }
+        const result = await fn()
+        const value = result === undefined ? undefined : typeof result === 'string' ? result : JSON.stringify(result, null, 2)
+        return { ok: true, value, hint: diagnoseEval(code, true) }
+    }
+    catch (e) {
+        const error = e instanceof Error ? `${e.message}\n${e.stack ?? ''}` : String(e)
+        return { ok: false, error, hint: diagnoseEval(code, false, error) }
+    }
+}
+
+// Native alert/confirm/prompt are *synchronous* and freeze the whole JS thread until
+// a human dismisses them — which deadlocks the probe (it runs on that same thread, so
+// the HMR channel can never answer and every curl times out). A click that hits a
+// `copy-to-clipboard` fallback or a `confirm("delete?")` would hang aihand forever.
+// So we stub them for the duration of `fn`: auto-answer (confirm→true, prompt→default,
+// alert→noop) and return what was suppressed so the caller can report it. Always
+// restored in finally — the page's own dialogs work again after the action settles.
+export async function withDialogGuard<T>(fn: () => Promise<T>): Promise<{ result: T, dialogs: string[] }> {
+    const realAlert = window.alert
+    const realConfirm = window.confirm
+    const realPrompt = window.prompt
+    const dialogs: string[] = []
+    window.alert = (m?: unknown) => { dialogs.push(`alert: ${String(m ?? '')}`.slice(0, 80)) }
+    window.confirm = (m?: unknown) => { dialogs.push(`confirm→true: ${String(m ?? '')}`.slice(0, 80)); return true }
+    window.prompt = (m?: unknown, d?: string) => { dialogs.push(`prompt→default: ${String(m ?? '')}`.slice(0, 80)); return d ?? '' }
+    try {
+        return { result: await fn(), dialogs }
+    }
+    finally {
+        window.alert = realAlert
+        window.confirm = realConfirm
+        window.prompt = realPrompt
+    }
+}
+
+// Click like a human, not like el.click(). A real click is a *position* the browser
+// hit-tests, then a full event sequence at that point — hover, pointerdown/mousedown,
+// browser-decided focus, pointerup/mouseup, click. Two things matter that el.click()
+// skips entirely:
+//   1. The target is whatever sits at (x,y) per elementFromPoint — so overlays,
+//      portals, and pointer-events:none are honored exactly as a mouse would.
+//   2. mousedown is cancelable and moves focus; if a handler preventDefault()s it,
+//      focus does NOT move (radix triggers rely on this). We replicate that contract.
+// This is what makes aihand catch focus/dismiss bugs that synthetic clicks hide.
+const MOUSE_SEQUENCE = ['pointerover', 'pointerenter', 'mouseover', 'pointermove'] as const
+
+function focusableAncestor(el: Element | null): HTMLElement | null {
+    return el?.closest<HTMLElement>('button, a[href], input, textarea, select, [tabindex], [contenteditable=""], [contenteditable="true"]') ?? null
+}
+
+function realClickAt(x: number, y: number): Element | null {
+    // The element a real mouse would hit at this point — not necessarily the one we
+    // searched for (it may be covered, or be a portal target).
+    const target = (document.elementFromPoint(x, y) as HTMLElement | null) ?? document.body
+    const base = { bubbles: true, cancelable: true, composed: true, clientX: x, clientY: y, view: window, button: 0, detail: 1 }
+    const ptr = { ...base, pointerId: 1, pointerType: 'mouse', isPrimary: true, width: 1, height: 1 }
+
+    for (const type of MOUSE_SEQUENCE)
+        target.dispatchEvent(type.startsWith('pointer') ? new PointerEvent(type, ptr) : new MouseEvent(type, base))
+
+    target.dispatchEvent(new PointerEvent('pointerdown', { ...ptr, buttons: 1 }))
+    const mousedownLive = target.dispatchEvent(new MouseEvent('mousedown', { ...base, buttons: 1 }))
+
+    // Browser focus rule: mousedown moves focus to the nearest focusable ancestor,
+    // UNLESS a handler called preventDefault() on mousedown. Match that exactly —
+    // this is the contract radix's PopoverTrigger depends on.
+    if (mousedownLive) {
+        const focusable = focusableAncestor(target)
+        if (focusable && document.activeElement !== focusable)
+            focusable.focus()
+    }
+
+    target.dispatchEvent(new PointerEvent('pointerup', { ...ptr, buttons: 0 }))
+    target.dispatchEvent(new MouseEvent('mouseup', { ...base, buttons: 0 }))
+    target.dispatchEvent(new MouseEvent('click', base))
+    return target
+}
+
+function realClick(el: HTMLElement): Element | null {
+    const r = el.getBoundingClientRect()
+    return realClickAt(r.left + r.width / 2, r.top + r.height / 2)
+}
+
+// What sits at the element's center, and whether it's an unrelated thing covering it.
+// "Unrelated" = not the element, not its descendant, not its ancestor — i.e. a portal/
+// overlay on top. This is the same predicate realClick reports, computed *before* the click.
+function coveredBy(el: Element): Element | null {
+    const r = el.getBoundingClientRect()
+    const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2)
+    return top && top !== el && !el.contains(top) && !top.contains(el) ? top : null
+}
+
+async function doClick(args: ActionArgs): Promise<ActionResult> {
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text}`, detail: clickableList() }
+    // A close→open sequence leaves the previous Radix dialog's overlay in the DOM during
+    // its exit animation (~150-300ms, variable). It covers the target's center point, so a
+    // real hit-test lands on the overlay, not the button. Don't click blind and report a
+    // false success — wait for the overlay to clear, then click the real target.
+    let cover = coveredBy(el)
+    for (let waited = 0; cover && waited < 400; waited += 16) {
+        await new Promise(r => setTimeout(r, 16))
+        cover = coveredBy(el)
+    }
+    // Still covered after the budget = not a clearing exit animation but a STABLE overlay (an
+    // open modal sitting on top of the target). The click cannot reach the target — a mouse
+    // would hit the overlay, not the button. Report failure, not a false success: ok=true must
+    // mean the click landed on the target. Name what blocks it so the caller can dismiss it
+    // first (the common cause is a dialog left open by a prior step).
+    if (cover)
+        return { ok: false, error: `target "${elementLabel(el).slice(0, 40) || el.tagName.toLowerCase()}" is covered by <${cover.tagName.toLowerCase()}>${elementLabel(cover) ? ` "${elementLabel(cover).slice(0, 30)}"` : ''} — an overlay/modal is on top; dismiss it first` }
+    const hit = realClick(el as HTMLElement)
+    const note = hit && hit !== el && !el.contains(hit) && !hit.contains(el) ? ` (hit <${hit.tagName.toLowerCase()}> on top)` : ''
+    return { ok: true, detail: `clicked ${elementLabel(el).slice(0, 40) || el.tagName.toLowerCase()}${note}` }
+}
+
+// Hover without clicking — the move-only prefix of realClick. Dispatches the pointer/mouse
+// over sequence at the element's center so hover-only UI (dropdown menus, tooltips, :hover
+// reveals) appears. No down/up/click, so it doesn't activate anything. Resolves the target
+// the mouse would actually hit at that point (overlays/portals honored), like realClickAt.
+function doHover(args: ActionArgs): ActionResult {
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text}`, detail: clickableList() }
+    const r = el.getBoundingClientRect()
+    const x = r.left + r.width / 2
+    const y = r.top + r.height / 2
+    const target = (document.elementFromPoint(x, y) as HTMLElement | null) ?? el as HTMLElement
+    const base = { bubbles: true, cancelable: true, composed: true, clientX: x, clientY: y, view: window }
+    const ptr = { ...base, pointerId: 1, pointerType: 'mouse', isPrimary: true, width: 1, height: 1 }
+    for (const type of MOUSE_SEQUENCE)
+        target.dispatchEvent(type.startsWith('pointer') ? new PointerEvent(type, ptr) : new MouseEvent(type, base))
+    return { ok: true, detail: `hovered ${elementLabel(el).slice(0, 40) || el.tagName.toLowerCase()}` }
+}
+
+// Double-click — inline-edit (TodoMVC label→input, file rename, spreadsheet cell), text
+// select, map zoom. A real dblclick is two full click sequences followed by one `dblclick`
+// event (detail:2) at the same point; el.click() twice never fires `dblclick`, so handlers
+// listening for it (the common case) never fire. Reuse realClick for the two clicks, then
+// dispatch dblclick at the element center.
+function doDblclick(args: ActionArgs): ActionResult {
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text}`, detail: clickableList() }
+    realClick(el as HTMLElement)
+    const hit = realClick(el as HTMLElement)
+    const r = el.getBoundingClientRect()
+    const x = r.left + r.width / 2
+    const y = r.top + r.height / 2
+    const target = (document.elementFromPoint(x, y) as HTMLElement | null) ?? el as HTMLElement
+    target.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true, composed: true, clientX: x, clientY: y, view: window, button: 0, detail: 2 }))
+    const note = hit && hit !== el && !el.contains(hit) && !hit.contains(el) ? ` (hit <${hit.tagName.toLowerCase()}> on top)` : ''
+    return { ok: true, detail: `double-clicked ${elementLabel(el).slice(0, 40) || el.tagName.toLowerCase()}${note}` }
+}
+
+
+// The trusted click is fired by whichever channel can produce isTrusted=true input:
+// Electron's webContents.sendInputEvent (via electronAPI.invoke, in client.ts) or a Chrome
+// extension's chrome.debugger (via the server's CDP queue). Synthetic events can't open a
+// Radix ContextMenu — that's the whole reason this path exists. When x= & y= are given
+// directly we pass them through unchanged.
+function doResolveRealClick(args: ActionArgs): ActionResult {
+    if (args.x !== undefined && args.y !== undefined)
+        return { ok: true, x: args.x, y: args.y, detail: `resolved (${args.x}, ${args.y})` }
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text}`, detail: clickableList() }
+    const r = el.getBoundingClientRect()
+    const x = Math.round(r.left + r.width / 2)
+    const y = Math.round(r.top + r.height / 2)
+    return { ok: true, x, y, detail: `resolved ${elementLabel(el).slice(0, 40) || el.tagName.toLowerCase()} at (${x}, ${y})` }
+}
+
+function doFill(args: ActionArgs): ActionResult {
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text}`, detail: clickableList() }
+    const value = args.value ?? ''
+    const html = el as HTMLElement
+    html.focus()
+
+    if (html.isContentEditable) {
+        // ProseMirror/tiptap listen on beforeinput — select-all then insertText
+        const sel = window.getSelection()
+        const range = document.createRange()
+        range.selectNodeContents(html)
+        sel?.removeAllRanges()
+        sel?.addRange(range)
+        document.execCommand('insertText', false, value)
+        if (html.textContent !== value && !value.includes(html.textContent ?? '\0')) {
+            // execCommand may be a no-op under some setups — fall back to direct text + input event
+            html.textContent = value
+            html.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: value }))
+        }
+        return { ok: true, detail: `filled contenteditable, ${value.length} chars` }
+    }
+
+    // <select>: value= matches an option by its visible text first, then by its value attr
+    // (text is what a human reads in the dropdown). Set selectedIndex + dispatch change so
+    // React/Vue bindings update.
+    if (el.tagName === 'SELECT') {
+        const select = el as HTMLSelectElement
+        const opts = Array.from(select.options)
+        const lower = value.toLowerCase()
+        const match = opts.find(o => o.text.trim().toLowerCase() === lower)
+            ?? opts.find(o => o.value === value)
+            ?? opts.find(o => o.text.toLowerCase().includes(lower))
+        if (!match)
+            return { ok: false, error: `no <option> matching "${value}" — options: ${opts.map(o => o.text.trim()).join(' | ')}` }
+        select.selectedIndex = match.index
+        select.dispatchEvent(new Event('input', { bubbles: true }))
+        select.dispatchEvent(new Event('change', { bubbles: true }))
+        return { ok: true, detail: `selected "${match.text.trim()}"` }
+    }
+
+    // Only INPUT/TEXTAREA value setters are legal to .call() here. text= often matches a
+    // styled overlay (GitHub's query-builder paints typed tokens into a <span> sitting over a
+    // transparent input) or a <label> — calling the input setter on those throws the opaque
+    // native `Illegal invocation`, which tells the agent nothing. Refine to the action
+    // (ker 诊断⊆ker 动作): name the matched tag, point at the real fillable inputs nearby.
+    if (el.tagName !== 'INPUT' && el.tagName !== 'TEXTAREA')
+        return { ok: false, error: `matched <${el.tagName.toLowerCase()}>, not a fillable input — text= likely hit a label/overlay painted over the real field. Target it with sel=`, detail: fillableList() }
+
+    // React overrides the value setter on the element *instance* to track changes; a plain
+    // `input.value = x` writes through it so React's tracker never sees a diff and onChange
+    // never fires (controlled inputs stay empty). Call the *prototype* setter instead — the
+    // tracker observes the change and the synthetic onChange fires.
+    const input = el as HTMLInputElement
+    const proto = el.tagName === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+    const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set
+    if (setter)
+        setter.call(input, value)
+    else input.value = value
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+    input.dispatchEvent(new Event('change', { bubbles: true }))
+    return { ok: true, detail: `filled ${value.length} chars` }
+}
+
+function doPress(args: ActionArgs): ActionResult {
+    const parts = (args.key ?? '').split('+')
+    const key = parts[parts.length - 1]
+    const mods = parts.slice(0, -1).map(m => m.toLowerCase())
+    const init: KeyboardEventInit = {
+        key,
+        bubbles: true,
+        cancelable: true,
+        ctrlKey: mods.includes('control') || mods.includes('ctrl'),
+        shiftKey: mods.includes('shift'),
+        altKey: mods.includes('alt'),
+        metaKey: mods.includes('meta') || mods.includes('cmd'),
+    }
+    const target = (document.activeElement as HTMLElement) || document.body
+    target.dispatchEvent(new KeyboardEvent('keydown', init))
+    target.dispatchEvent(new KeyboardEvent('keyup', init))
+    return { ok: true, detail: `pressed ${args.key} on ${target.tagName.toLowerCase()}` }
+}
+
+function doWait(args: ActionArgs): Promise<ActionResult> {
+    const timeout = args.timeout ?? 5000
+    const start = performance.now()
+    // Three modes: enabled (element present AND not [disabled]), gone, or appeared (default).
+    const isDisabled = (el: Element) => (el as HTMLInputElement).disabled || el.getAttribute('aria-disabled') === 'true'
+    const verb = args.enabled ? 'enabled' : args.gone ? 'disappeared' : 'appeared'
+    return new Promise((resolve) => {
+        const tick = () => {
+            const el = findElement(args.sel, args.text)
+            const done = args.enabled ? (!!el && !isDisabled(el)) : (!!el !== !!args.gone)
+            if (done) {
+                resolve({ ok: true, detail: `${verb} after ${Math.round(performance.now() - start)}ms` })
+                return
+            }
+            if (performance.now() - start > timeout) {
+                resolve({ ok: false, error: `timeout ${timeout}ms waiting for ${args.sel || args.text} to be ${verb}` })
+                return
+            }
+            setTimeout(tick, 100)
+        }
+        tick()
+    })
+}
+
+async function doScreenshot(args: ActionArgs): Promise<ActionResult> {
+    const target = args.sel ? document.querySelector(args.sel) : document.body
+    if (!target)
+        return { ok: false, error: `no element for ${args.sel}` }
+    const { toPng } = await import('html-to-image')
+    // html-to-image re-fetches every <img> to inline it; one cross-origin or
+    // rate-limited (429) image rejects the whole render. Drop external/broken
+    // images from the capture — a screenshot minus a few avatars beats no screenshot.
+    const sameOrigin = (src: string) => {
+        try {
+            return new URL(src, location.href).origin === location.origin
+        }
+        catch {
+            return false
+        }
+    }
+    const filter = (n: HTMLElement) => !(n instanceof HTMLImageElement && (!n.complete || n.naturalWidth === 0 || !sameOrigin(n.src)))
+    try {
+        const dataUrl = await toPng(target as HTMLElement, { filter, imagePlaceholder: 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==' })
+        return { ok: true, dataUrl, detail: `${target.tagName.toLowerCase()} captured` }
+    }
+    catch (e) {
+        const msg = e instanceof Event ? `image load failed (${(e.target as HTMLImageElement)?.src?.slice(0, 80) || 'unknown'})` : e instanceof Error ? e.message : String(e)
+        return { ok: false, error: `screenshot failed: ${msg}` }
+    }
+}
+
+// The read-side twin of click/fill's `sel=`: instead of acting on the matched
+// element, report the facts you'd otherwise reach for via /eval — count of
+// matches, and per-element text / visible / assertion-relevant attrs. /wait
+// answers "appears over time"; query answers "what is it now". Attrs are a
+// whitelist (role, data-state, data-*, aria-*, value, disabled, checked, href,
+// title) — a node's full class/style set is noise. Capped at 20 matches.
+const QUERY_ATTRS = ['role', 'data-state', 'value', 'href', 'title']
+const QUERY_PREFIXES = ['data-', 'aria-']
+
+function elAttrs(el: Element): Record<string, string> {
+    const sensitive = isSensitive(el)
+    const out: Record<string, string> = {}
+    for (const attr of Array.from(el.attributes)) {
+        if (QUERY_ATTRS.includes(attr.name) || QUERY_PREFIXES.some(p => attr.name.startsWith(p)))
+            out[attr.name] = attr.name === 'value' && sensitive ? `‹redacted ${attr.value.length} chars›` : attr.value
+    }
+    const input = el as HTMLInputElement
+    if (typeof input.value === 'string' && out.value === undefined && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT'))
+        out.value = safeValue(el)
+    if (input.disabled)
+        out.disabled = 'true'
+    if (input.checked)
+        out.checked = 'true'
+    return out
+}
+
+function doQuery(args: ActionArgs): ActionResult {
+    let els: Element[]
+    try {
+        els = Array.from(document.querySelectorAll(args.sel!))
+    }
+    catch {
+        return { ok: false, error: `invalid selector: ${args.sel} — URL-encode it (curl -G --data-urlencode 'sel=...')` }
+    }
+    const count = els.length
+    const matches = els.slice(0, 20).map(el => ({
+        text: elementLabel(el).slice(0, 80),
+        visible: isVisible(el),
+        attrs: elAttrs(el),
+    }))
+    const head = count > 20 ? `(showing 20 of ${count})\n` : ''
+    return { ok: true, detail: head + JSON.stringify({ count, matches }, null, 2) }
+}
+
+// Assert a domain variable (from __AIPEEK_SCREEN__) or a DOM element's text equals the
+// expected value. Pass/fail with the actual value on failure — the chain stops and says
+// "asserted X==Y, actual Z", not "the next step happened to miss".
+function doAssert(args: ActionArgs): ActionResult {
+    let actual: string
+    if (args.screen) {
+        let domain: Record<string, unknown> = {}
+        try {
+            domain = window.__AIPEEK_SCREEN__?.() ?? {}
+        }
+        catch (e) {
+            return { ok: false, error: `__AIPEEK_SCREEN__ threw: ${e instanceof Error ? e.message : String(e)}` }
+        }
+        if (!(args.screen in domain))
+            return { ok: false, error: `no domain key "${args.screen}" — available: ${Object.keys(domain).join(', ') || '(none — app injected no __AIPEEK_SCREEN__)'}` }
+        actual = String(domain[args.screen])
+    }
+    else {
+        const el = findElement(args.sel, args.text)
+        if (!el)
+            return { ok: false, error: `no element for ${args.sel || args.text}` }
+        actual = elementLabel(el)
+    }
+    const target = args.screen ? `screen.${args.screen}` : (args.sel || args.text)
+    if (actual === args.equals)
+        return { ok: true, detail: `${target} == ${args.equals}` }
+    // Time-ordering fiber: a mismatch on a busy-named key (streaming/loading/流式中…) most likely
+    // means the assert ran before the async flow settled, not that the value is permanently wrong.
+    // Distinguish "still mid-flight, wait for it" from "settled to the wrong value" so the agent
+    // inserts a `wait` instead of concluding the action failed. isBusyKey is the same classifier
+    // settle uses — generic, bilingual, no per-app field hard-coding.
+    const hint = args.screen && isBusyKey(args.screen)
+        ? ` — "${args.screen}" is an in-flight field; if it's still settling, insert a {"type":"wait",...} before this assert`
+        : ''
+    return { ok: false, error: `asserted ${target} == "${args.equals}", actual "${actual}"${hint}` }
+}
+
+// Scroll an element into the viewport so it can be clicked. In a virtual list (tanstack-
+// virtual, dnd-kit) a row off-screen isn't in the DOM at all — but a row rendered yet
+// scrolled out of view is the common case, and this brings it back. Honest about the
+// virtual case: if the element isn't found, say so (the row may need the list scrolled
+// first via a container scroll, which /eval can do).
+function doScrollIntoView(args: ActionArgs): ActionResult {
+    const el = findElement(args.sel, args.text)
+    if (!el)
+        return { ok: false, error: `no element for ${args.sel || args.text} — if it's in a virtual list it may not be rendered yet`, detail: clickableList() }
+    el.scrollIntoView({ block: 'center', inline: 'center' })
+    const r = el.getBoundingClientRect()
+    const inView = r.top >= 0 && r.left >= 0 && r.bottom <= innerHeight && r.right <= innerWidth
+    return { ok: true, detail: `scrolled ${elementLabel(el).slice(0, 40) || el.tagName.toLowerCase()} into view${inView ? '' : ' (still partly off-screen)'}` }
+}
+
+// Drag via a synthetic pointer sequence: pointerdown on source → a few pointermove steps
+// (dnd-kit's PointerSensor has an activation distance constraint, so we move in increments
+// past it) → pointerup on destination. Also fires the HTML5 drag events for libraries that
+// use the native DnD API. dnd-kit relies on pointer capture + isTrusted in some paths; when
+// synthetic events don't trigger the reorder, fall back to realclick's trusted channel
+// (caller sees needsTrusted in the detail). Best-effort, honestly reported.
+function doDrag(args: ActionArgs): ActionResult {
+    const src = findElement(args.sel, args.text)
+    if (!src)
+        return { ok: false, error: `no source element for ${args.sel || args.text}`, detail: clickableList() }
+    const dst = args.to ? document.querySelector(args.to) : null
+    if (!dst)
+        return { ok: false, error: `no destination element for to=${args.to}` }
+    const sr = src.getBoundingClientRect()
+    const dr = dst.getBoundingClientRect()
+    const sx = sr.left + sr.width / 2
+    const sy = sr.top + sr.height / 2
+    const dx = dr.left + dr.width / 2
+    const dy = dr.top + dr.height / 2
+    const ptr = (x: number, y: number, extra: PointerEventInit = {}) =>
+        ({ bubbles: true, cancelable: true, composed: true, clientX: x, clientY: y, view: window, pointerId: 1, pointerType: 'mouse', isPrimary: true, button: 0, ...extra })
+
+    src.dispatchEvent(new PointerEvent('pointerdown', ptr(sx, sy, { buttons: 1 })))
+    // Step through the path so dnd-kit clears its activation-distance constraint.
+    const steps = 8
+    for (let i = 1; i <= steps; i++) {
+        const x = sx + (dx - sx) * (i / steps)
+        const y = sy + (dy - sy) * (i / steps)
+        const over = (document.elementFromPoint(x, y) as HTMLElement | null) ?? dst as HTMLElement
+        over.dispatchEvent(new PointerEvent('pointermove', ptr(x, y, { buttons: 1 })))
+    }
+    ;(dst as HTMLElement).dispatchEvent(new PointerEvent('pointerup', ptr(dx, dy, { buttons: 0 })))
+    return { ok: true, detail: `dragged ${elementLabel(src).slice(0, 30) || src.tagName.toLowerCase()} → ${elementLabel(dst).slice(0, 30) || dst.tagName.toLowerCase()} (synthetic; if no reorder, retry with realclick — dnd-kit may need trusted pointer events)` }
+}
+
+// Drop synthetic files onto a target — the file-upload path without a native file picker
+// (which synthetic clicks can't drive). Builds a DataTransfer with empty File objects of
+// the given names and fires the dragenter→dragover→drop sequence libraries listen for.
+function doDrop(args: ActionArgs): ActionResult {
+    const target = findElement(args.sel, args.text)
+    if (!target)
+        return { ok: false, error: `no drop target for ${args.sel || args.text}`, detail: clickableList() }
+    const dt = new DataTransfer()
+    for (const name of args.files ?? [])
+        dt.items.add(new File([''], name, { type: 'application/octet-stream' }))
+    const r = target.getBoundingClientRect()
+    const init = { bubbles: true, cancelable: true, composed: true, clientX: r.left + r.width / 2, clientY: r.top + r.height / 2, dataTransfer: dt }
+    for (const type of ['dragenter', 'dragover', 'drop'] as const)
+        target.dispatchEvent(new DragEvent(type, init))
+    return { ok: true, detail: `dropped ${dt.items.length} file(s) [${(args.files ?? []).join(', ')}] on ${elementLabel(target).slice(0, 30) || target.tagName.toLowerCase()}` }
+}
+
+// Read or write the clipboard. write seeds it (so a subsequent paste can be tested);
+// read reports what the page put there (so a "copy" button can be verified). navigator.
+// clipboard needs a focused document and (for read) permission — degrade with a clear
+// error rather than hang.
+async function doClipboard(args: ActionArgs): Promise<ActionResult> {
+    try {
+        if (args.mode === 'write') {
+            await navigator.clipboard.writeText(args.value ?? '')
+            return { ok: true, detail: `clipboard ← "${(args.value ?? '').slice(0, 60)}"` }
+        }
+        const text = await navigator.clipboard.readText()
+        return { ok: true, detail: `clipboard: "${text.slice(0, 200)}"` }
+    }
+    catch (e) {
+        return { ok: false, error: `clipboard ${args.mode ?? 'read'} failed: ${e instanceof Error ? e.message : String(e)} (needs document focus / permission)` }
+    }
+}