aihand 0.0.1 → 0.1.0

package/src/ui/probe/cli.ts

@@ -0,0 +1,139 @@
+/* eslint-disable no-console -- this is a CLI; stdout is its output channel */
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import pc from 'picocolors'
+
+// 出口2 CLI:`aihand probe open <url>` / `screen` / `click --text=…`。
+// open 确保常驻 server(probe/server.ts)起着——多次 CLI 连同一 server = 同一 page(会话保持)。
+// screen/click 只 curl 常驻 server,与出口1 的 cli.ts 同形(positional 子命令 + --flag query)。
+
+const PORT = 5179
+const base = `http://localhost:${PORT}`
+
+function parseFlags(a: string[]) {
+    return Object.fromEntries(
+        a.filter(x => x.startsWith('--')).map((x) => {
+            const body = x.slice(2)
+            const eq = body.indexOf('=')
+            return eq === -1 ? [body, 'true'] : [body.slice(0, eq), body.slice(eq + 1)]
+        }),
+    )
+}
+
+async function alive(): Promise<boolean> {
+    try {
+        await fetch(`${base}/__nope`)
+        return true // 任何回复(含 404)= server 在
+    }
+    catch {
+        return false
+    }
+}
+
+async function waitAlive(ms: number): Promise<boolean> {
+    const deadline = Date.now() + ms
+    while (Date.now() < deadline) {
+        if (await alive())
+            return true
+        await new Promise(r => setTimeout(r, 200))
+    }
+    return false
+}
+
+function spawnServer() {
+    // server 入口在哪取决于运行形态:dev(jiti 跑 src)= 同目录 server.ts;built = tsup 把
+    // 本 cli 打进 dist 根的 chunk(here=dist/),server 单列 entry 落 dist/ui/probe/server.js。
+    // 两种都试,第一个存在的赢——不赌单一相对路径(tsup chunk 名不稳)。
+    const here = dirname(fileURLToPath(import.meta.url))
+    const candidates = [
+        resolve(here, 'server.ts'), // dev:同目录源码
+        resolve(here, 'server.js'), // built(若 cli 与 server 同目录)
+        resolve(here, 'ui/probe/server.js'), // built:cli chunk 在 dist 根,server 在 dist/ui/probe
+    ]
+    const entry = candidates.find(existsSync)
+    if (!entry)
+        throw new Error('probe server entry not found near ' + here)
+    // node 自身不解析 TS:entry 是 .ts(dev,jiti 跑 src)时,跑 node + jiti CLI 入口转译;
+    // .js(built)裸 node 直跑。jiti CLI 路径从包根解析(dev 下 jiti 必在——它就是用 jiti 起的)。
+    const argv = entry.endsWith('.ts') ? [jitiCli(here), entry] : [entry]
+    const child = spawn(process.execPath, argv, { detached: true, stdio: 'ignore' })
+    child.unref()
+}
+
+// jiti 的可执行 CLI 入口(lib/jiti-cli.mjs):exports 不导出子路径,故从 package.json 解析其目录再拼。
+function jitiCli(near: string): string {
+    const req = createRequire(resolve(near, 'cli.ts'))
+    return resolve(dirname(req.resolve('jiti/package.json')), 'lib/jiti-cli.mjs')
+}
+
+async function main() {
+    const argv = process.argv.slice(2)
+    const sub = argv.filter(a => !a.startsWith('--'))[0] || ''
+    const positional = argv.filter(a => !a.startsWith('--'))
+    const flags = parseFlags(argv)
+
+    if (!sub || flags.help) {
+        console.log(`
+${pc.bold('aihand probe')} — drive ANY external website (out-of-app, self-contained)
+
+  aihand probe open <url>          Launch chromium, parachute the probe, navigate
+                                  (--headed to see a real browser window pop up)
+  aihand probe screen              Semantic layout + view/modal/focus + region fingerprint
+  aihand probe click --text=…      Click by visible text (also fill/press/hover/wait)
+  aihand probe eval --code=…       Run JS in the page, auto-return the value (read exact
+                                  text/numbers the sketch clips, query closures)
+  aihand probe screenshot          Save a PNG (pixels, not the sketch) — returns the path
+                                  (--sel=… one element · --fullPage=1 whole scroll height)
+
+The page handle lives in a resident server (:${PORT}) — repeated commands hit the same
+page (login/scroll/menus persist). Same kernel as the in-app probe, CDP transport.
+`)
+        process.exit(0)
+    }
+
+    if (sub === 'open') {
+        const target = positional[1]
+        if (!target) {
+            console.error(pc.red('open needs a url: aihand probe open https://example.com'))
+            process.exit(1)
+        }
+        if (!(await alive())) {
+            spawnServer()
+            if (!(await waitAlive(8000))) {
+                console.error(pc.red('probe server failed to start on :' + PORT))
+                process.exit(1)
+            }
+        }
+        // --headed:弹出真浏览器窗口,人眼盯着看 aihand 驱动(默认无头,后台跑不画像素)。
+        const headed = flags.headed ? '&headed=1' : ''
+        const r = await fetch(`${base}/open?url=${encodeURIComponent(target)}${headed}`)
+        console.log(await r.text())
+        process.exit(r.ok ? 0 : 1)
+    }
+
+    // screen / click / fill / press / hover / wait → curl resident server
+    const reserved = new Set(['port', 'help'])
+    const query = Object.entries(flags)
+        .filter(([k]) => !reserved.has(k))
+        .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+        .join('&')
+    const r = await fetch(`${base}/${sub}${query ? `?${query}` : ''}`).catch(() => null)
+    if (!r) {
+        console.error(pc.red(`no probe server on :${PORT} — run \`aihand probe open <url>\` first`))
+        process.exit(1)
+    }
+    console.log(await r.text())
+    process.exit(r.ok ? 0 : 1)
+}
+
+export async function run(argv: string[]) {
+    process.argv = [process.argv[0], process.argv[1], ...argv]
+    await main().catch((err) => {
+        console.error(pc.red(`Error: ${err.message}`))
+        process.exit(1)
+    })
+}

package/src/ui/probe/server.ts

@@ -0,0 +1,468 @@
+/* eslint-disable no-console -- resident server; stdout is its log channel */
+import http from 'node:http'
+import os from 'node:os'
+import path from 'node:path'
+import { chromium } from 'playwright-core'
+import type { Browser, Page } from 'playwright-core'
+import type { ServerBridge } from '../bridge/transport'
+import { cdpBridge } from '../bridge/cdp-bridge'
+import { compileProbe } from '../bridge/compile-probe'
+import { diagnoseEval } from '../core/action'
+import { isRouteChange } from '../core/util'
+import { argsFromQuery, dispatchAction, dispatchChainStep, dispatchScreen, isDispatchAction, runChain } from '../server/dispatch'
+import type { ChainStep } from '../server/dispatch'
+
+// 出口2 常驻 server:launch chromium、空降探针、serve HTTP。复用 dispatch(cdpBridge)——与出口1
+// (Vite)同一内核。page 句柄活在本进程不退出 = 保持会话(登录态/滚动/打开的菜单都在),多次 CLI
+// 连同一 server = 同一 page。这是「驱动运行中的浏览器」语义,不是「每命令 launch 一次」。
+
+const PORT = 5179
+
+let browser: Browser | undefined
+let page: Page | undefined
+let bridge: ServerBridge | undefined
+// 主帧同文档路由切换订阅(随 page 重建而重赋,navProbe 的 awaitSameDocNav 经此 arm)。
+let onSameDocNav: ((cb: () => void) => () => void) | undefined
+let actionId = 0
+
+async function launchChromium(headed: boolean): Promise<Browser> {
+    // 优先 playwright 自带 chromium;没下载(`playwright install chromium` 未跑)就退回系统 Chrome
+    // (channel:'chrome')——真实用户装了 aihand 不该被强制下一份浏览器。两者都没才抛。
+    // headed:`probe open --headed` 时为真,弹出真窗口让人眼盯着看 aihand 驱动;默认无头。
+    const headless = !headed
+    try {
+        return await chromium.launch({ headless })
+    }
+    catch (err) {
+        try {
+            return await chromium.launch({ headless, channel: 'chrome' })
+        }
+        catch {
+            throw err
+        }
+    }
+}
+
+async function ensurePage(url: string, headed: boolean): Promise<void> {
+    // browser/page 崩了(用户关窗、chromium 进程被杀)但引用还在 → 引用非空但已死。playwright 的
+    // isConnected() 是 browser 活性地面真值;page.isClosed() 判页。死了就清空三引用,落到下面重启分支
+    // 透明重 launch——否则复用死句柄,newPage()/goto() 抛 "Target closed",每个 open 都炸。
+    if (browser && !browser.isConnected())
+        browser = page = bridge = undefined
+    if (page && page.isClosed())
+        page = bridge = undefined
+    if (!browser)
+        browser = await launchChromium(headed)
+    if (!page) {
+        page = await browser.newPage()
+        // CDP session:拿 Page.frameRequestedNavigation(导航意图,先于 reply)。整页一份,随 page 活。
+        const cdp = await page.context().newCDPSession(page)
+        await cdp.send('Page.enable')
+        // 主帧 id 取自 getFrameTree 根帧(CDP 公开,非内部字段);用于过滤子 iframe 导航。
+        const mainFrameId = (await cdp.send('Page.getFrameTree')).frameTree.frame.id
+        // 主帧导航意图监听器表:request 飞行期注册一个,intent fire 时全调一遍(锁存,不 settle)。
+        const navIntentCbs = new Set<() => void>()
+        cdp.on('Page.frameRequestedNavigation', (e: { frameId: string }) => {
+            if (e.frameId === mainFrameId)
+                for (const cb of navIntentCbs) cb()
+        })
+        // 主帧同文档路由切换(SPA pushState)监听器表:dispatch 在动作前 arm 一个(见 awaitSameDocNav),
+        // navigatedWithinDocument fire 且 isRouteChange(URL path/search 真变)时全调一遍。lastMainUrl
+        // 随事件滚动,作下一次 isRouteChange 的 from——CDP 不带 from,要自己记。整页导航(frameNavigated)
+        // 也滚一下,免得换页后第一次 SPA 跳被拿旧 path 比错。
+        const sameDocNavCbs = new Set<() => void>()
+        let lastMainUrl = url
+        cdp.on('Page.navigatedWithinDocument', (e: { frameId: string, url: string }) => {
+            if (e.frameId !== mainFrameId)
+                return
+            const changed = isRouteChange(lastMainUrl, e.url)
+            lastMainUrl = e.url
+            if (changed)
+                for (const cb of sameDocNavCbs) cb()
+        })
+        cdp.on('Page.frameNavigated', (e: { frame: { id: string, url: string } }) => {
+            if (e.frame.id === mainFrameId)
+                lastMainUrl = e.frame.url
+        })
+        // bridge 的 waiters 表与 binding 的 deliver 必须共享同一实例,整页生命周期一份。
+        const wired = cdpBridge({
+            evaluate: (fn, arg) => page!.evaluate(fn, arg),
+            // 整页导航撞上下文销毁时,bridge 调这个等新文档真正可查询(body 挂上)再重试。
+            // 只等 domcontentloaded 不够:旧文档刚销毁、新文档 body 尚未 attach 的瞬间,
+            // collectScreen 的 body.querySelectorAll 仍 NPE。waitForFunction 等到 body 在。
+            settle: async () => {
+                await page!.waitForLoadState('domcontentloaded')
+                await page!.waitForFunction(() => Boolean(document.body))
+            },
+            // 主帧导航意图地面真值(先于 reply ~0.3ms):动作触发整页导航时 CDP 同步 fire,锁存置位
+            // 调用方 navigated 标记,不 settle request(reply 仍唯一 settle)。同文档动作永不 fire → 零延迟。
+            onMainFrameNavIntent: (cb) => {
+                navIntentCbs.add(cb)
+                return () => navIntentCbs.delete(cb)
+            },
+            // 同文档路由切换订阅:dispatch 在动作前 arm,reply 后等(awaitSameDocNav)。出口1 无此事件。
+            onMainFrameSameDocNav: (cb) => {
+                sameDocNavCbs.add(cb)
+                return () => sameDocNavCbs.delete(cb)
+            },
+        })
+        bridge = wired.bridge
+        // navProbe 的 awaitSameDocNav 经此 arm(sameDocNavCbs 随 page 生命周期一份)。
+        onSameDocNav = (cb) => {
+            sameDocNavCbs.add(cb)
+            return () => sameDocNavCbs.delete(cb)
+        }
+        // exposeBinding 必须在 addInitScript 之前——binding 是探针 send 的落点,先注册才能在新文档可用。
+        await page.exposeBinding('__aihandSend', (_src, event: string, payload: { id?: number }) => {
+            wired.deliver(event, payload)
+        })
+        await page.addInitScript(compileProbe())
+    }
+    await page.goto(url, { waitUntil: 'domcontentloaded' })
+    // addInitScript 只在新文档导航前注入;goto 后再补一发当前页注入,保证首个 open 即活。
+    await page.evaluate(compileProbe())
+}
+
+function send(res: http.ServerResponse, status: number, body: string) {
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' })
+    res.end(body)
+}
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+    return new Promise((resolve) => {
+        let body = ''
+        req.on('data', chunk => (body += chunk))
+        req.on('end', () => resolve(body))
+    })
+}
+
+// page.evaluate 有 page 句柄但**无 per-call 超时**——若被驱动页面的主线程/JS 上下文被某段死循环或
+// 重 SPA(实测 tanstack 嵌入式沙箱 example 把主线程转死)卡住,`await page.evaluate` 永不 resolve,
+// /eval 的 curl 无限挂死(exit 28),与 /screen 探针有 3s reply cap 形成不对称。in-page 探针卡了会
+// 超时回诊断,page.evaluate 卡了却静默吊死。这里把它 race 一个计时器:卡过 cap 就 reject 一个**可
+// 诊断**的错误(refine 到动作:页面主线程可能被阻塞),而非吊死——ker(诊断)⊆ker(动作)。
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout>
+    const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms — page main thread may be blocked (heavy SPA / infinite loop). try a fresh \`open <url>\` to recover.`)), ms)
+    })
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer))
+}
+
+// CDP 可信拖拽(出口2 独有)。SortableJS/dnd-kit/原生 DnD 用 isTrusted 门控:合成 PointerEvent
+// (doDrag)无法满足——in-page dispatchEvent 的 isTrusted 恒 false,这些库的 activation 判据/原生
+// drag 都不响应(live:SortableJS 合成拖拽不 reorder)。出口2 握着 playwright page 句柄,page.mouse
+// 产**真实**指针事件(isTrusted=true,经浏览器输入管线),正是 trusted 门控动作需要的。先 in-page
+// 解析 src/dst 视口中心坐标(复用 findElement 同款 sel/text 命中,一次 evaluate),再 page.mouse
+// move→down→分步 move→up 驱动(8 步与 doDrag 同,清 dnd activation distance),最后采 screen delta。
+// realclick 同理(trusted click)走 page.mouse.click。两者是仅有的真需 trusted 的动作,其余合成路径不动。
+async function resolveDragCoords(srcSel: string | undefined, srcText: string | undefined, toSel: string): Promise<{ ok: true, sx: number, sy: number, dx: number, dy: number, srcLabel: string, dstLabel: string } | { ok: false, error: string }> {
+    return page!.evaluate(({ sel, text, to }) => {
+        const w = window as unknown as { __aihandFindForDrag?: (s?: string, t?: string) => Element | null }
+        // 探针已注入 findElement/elementLabel 到 window?用现成的;否则退一个最小 sel/text 命中。
+        const pick = (s?: string, t?: string): Element | null => {
+            if (s) return document.querySelector(s)
+            if (t) {
+                const els = Array.from(document.querySelectorAll('a,button,li,div,span,[role],[draggable]'))
+                return els.find(e => (e.textContent || '').trim().includes(t)) ?? null
+            }
+            return null
+        }
+        const finder = w.__aihandFindForDrag ?? pick
+        const src = finder(sel, text)
+        if (!src) return { ok: false as const, error: `no source element for ${sel || text}` }
+        const dst = document.querySelector(to)
+        if (!dst) return { ok: false as const, error: `no destination element for to=${to}` }
+        // page.mouse 用视口坐标:元素在视口外(scrollY 偏移)时 rect 是负的/越界,真实指针落到空处。
+        // 先把 source 滚进视口中部再读 rect —— trusted 拖拽必须落在可见坐标上(合成 doDrag 直接 dispatch
+        // 到元素绕过坐标,所以没暴露这个;真实指针没有这条捷径)。
+        src.scrollIntoView({ block: 'center', inline: 'center' })
+        const sr = src.getBoundingClientRect()
+        const dr = dst.getBoundingClientRect()
+        const lbl = (e: Element) => (e.getAttribute('aria-label') || (e.textContent || '').trim() || e.tagName.toLowerCase()).slice(0, 30)
+        return { ok: true as const, sx: sr.left + sr.width / 2, sy: sr.top + sr.height / 2, dx: dr.left + dr.width / 2, dy: dr.top + dr.height / 2, srcLabel: lbl(src), dstLabel: lbl(dst) }
+    }, { sel: srcSel, text: srcText, to: toSel })
+}
+
+async function trustedDrag(srcSel: string | undefined, srcText: string | undefined, toSel: string): Promise<{ status: number, body: string }> {
+    const c = await resolveDragCoords(srcSel, srcText, toSel)
+    if (!c.ok)
+        return { status: 422, body: c.error }
+    // SortableJS/dnd-kit 的拖拽检测需要:按下后先有一个**小幅初动**越过 activation 阈值,再逐帧
+    // 移动(每帧之间留 dispatch 间隙让库的 mousemove handler 跑),到目标后**停一拍**让 onMove/insert
+    // 计算落位,最后才松手。无间隙的瞬时移动会被多数 dnd 库判为「没动」或越过整段不触发中间 onMove。
+    const pause = (ms: number) => new Promise(r => setTimeout(r, ms))
+    await page!.mouse.move(c.sx, c.sy)
+    await page!.mouse.down()
+    await pause(30)
+    // 初动:朝目标方向先挪 6px,越过 SortableJS/dnd-kit 的 activation distance。
+    const len = Math.hypot(c.dx - c.sx, c.dy - c.sy) || 1
+    await page!.mouse.move(c.sx + (c.dx - c.sx) / len * 6, c.sy + (c.dy - c.sy) / len * 6)
+    await pause(20)
+    const steps = 12
+    for (let i = 1; i <= steps; i++) {
+        await page!.mouse.move(c.sx + (c.dx - c.sx) * (i / steps), c.sy + (c.dy - c.sy) * (i / steps))
+        await pause(16)
+    }
+    await pause(60) // 停一拍:让 dnd 库在目标位算好插入点
+    await page!.mouse.up()
+    const { result } = await dispatchScreen(bridge!)
+    return { status: 200, body: `dragged ${c.srcLabel} → ${c.dstLabel} (trusted page.mouse)\n\n--- changed ---\n${result.body}` }
+}
+
+// afterNav:出口2 独有的跨整页导航回填(见动作端点注释)。/action 与 /chain 共用同一份——
+// 链里的某步点链接触发换页,同样采新页全貌回填,不漏。
+function navProbe() {
+    return {
+        url: async () => page!.url(),
+        // 同文档路由切换事后等待。两段:arm 必须在动作派发前调(此刻订阅 → 监听就位,免得 @0.2s 的快
+        // 信号在 reply 后才订阅而漏);wait(capMs) 在 reply 后调,与 capMs 竞速。SPA 换页(URL 真变)在
+        // capMs 内 fire → resolve(true) 立即短路;否则到 capMs → resolve(false)。两条都退订 + 清定时器
+        // (幂等,无泄漏)。无订阅能力(出口1/未接线)时恒返回一个立刻 false 的 wait。
+        armSameDocNav: (): { wait: (capMs: number) => Promise<boolean>, cancel: () => void } => {
+            if (!onSameDocNav)
+                return { wait: () => Promise.resolve(false), cancel: () => {} }
+            let fired = false
+            let onFire: (() => void) | undefined // wait() 装上;arm→wait 之间若已 fire 走 fired 标志
+            const unsub = onSameDocNav(() => { fired = true; onFire?.() })
+            return {
+                wait: (capMs: number) => new Promise<boolean>((resolve) => {
+                    let done = false
+                    let cap: ReturnType<typeof setTimeout> | undefined
+                    const finish = (v: boolean) => { if (done) return; done = true; if (cap) clearTimeout(cap); unsub(); resolve(v) }
+                    if (fired) return finish(true) // arm 后、wait 前就 fire 了(快信号),立即结清(cap 尚未装,finish 守 undefined)
+                    onFire = () => finish(true)
+                    cap = setTimeout(() => finish(false), capMs)
+                }),
+                // 门控未命中(整页导航 / 非平凡 diff)→ 不等,直接退订,不留悬挂监听。
+                cancel: unsub,
+            }
+        },
+        renavScreen: async (fromUrl: string): Promise<string | undefined> => {
+            await page!.waitForFunction(() => Boolean(document.body))
+            // body attach ≠ 内容就绪:MPA(服务端渲染)body 在时内容已在,但 SPA 结果页(DDG/Google/
+            // 现代站)body attach 时内容还在异步 fetch,立刻采帧得空壳(实战:press Enter 搜索后 afterNav
+            // 采到空树,2s 后手动 screen 才有 20 结果)。等 DOM 子树节点数趋稳再采 —— 通用判据不写死
+            // 选择器,同 traceFlow 的 DOM 静默律;有上限防长轮询/分析心跳站永不静而挂死。
+            // SPA 导航后 body 先挂空骨架(几节点)再 JS fetch 灌数据。「增量趋稳」会在骨架期假稳
+            // (5 节点两帧不变),要等内容真到:节点数涨过空壳门槛(>50)且两帧趋稳。networkidle 不可靠
+            // (分析心跳/长轮询站永不 idle),DOM 门槛 + 趋稳是纯结构判据,有上限防永不满足而挂死。
+            await page!.waitForFunction(() => {
+                const n = document.body.querySelectorAll('*').length
+                const w = window as unknown as { __aihandPrevN?: number }
+                const stable = n > 50 && w.__aihandPrevN !== undefined && Math.abs(n - w.__aihandPrevN) < 5
+                w.__aihandPrevN = n
+                return stable
+            }, { timeout: 3000, polling: 150 }).catch(() => {})
+            await page!.evaluate(compileProbe())
+            const toUrl = page!.url()
+            const { result } = await dispatchScreen(bridge!)
+            return `navigated: ${fromUrl} → ${toUrl}\n${result.body}`
+        },
+    }
+}
+
+const server = http.createServer(async (req, res) => {
+    try {
+        const url = new URL(req.url || '/', `http://localhost:${PORT}`)
+        const parts = url.pathname.split('/').filter(Boolean)
+
+        if (parts[0] === 'open') {
+            const target = url.searchParams.get('url') || ''
+            if (!target) {
+                send(res, 400, 'open needs ?url=')
+                return
+            }
+            // headed 由首个 open 决定(browser 整进程一份):后续 open 复用已起的 browser,headed 不变。
+            await ensurePage(target, url.searchParams.get('headed') === '1')
+            // open 落到的结果就是页面本身——回执直接带语义树+@kN,不回一句空转的 "opened"。
+            // 「打开→看页面」坍缩成一轮:agent 一轮就看到页面、拿到可寻址旋钮,下一步直接 click。
+            const { result } = await dispatchScreen(bridge!)
+            send(res, 200, `opened ${target}\n${result.body}`)
+            return
+        }
+
+        if (!page || !bridge) {
+            send(res, 409, 'no page open — run `aihand probe open <url>` first')
+            return
+        }
+
+        if (parts[0] === 'screen') {
+            const { result } = await dispatchScreen(bridge, { form: url.searchParams.get('form') || undefined })
+            send(res, 200, result.body)
+            return
+        }
+
+        // /eval — the escape hatch for any value the spatial /screen can't surface: read exact
+        // text/numbers, query closures, install listeners. Runs in the REAL page via playwright's
+        // page.evaluate (not the parachuted probe, not Node) — same auto-return as exit-1's /eval:
+        // try the code as a single expression first (`document.title`, `qsa('.x').length` yield a
+        // value without `return`); on compile failure fall back to a statement block. diagnoseEval
+        // (pure, shared with exit-1) refines the eval fiber → typed twin on the two strong signals.
+        if (parts[0] === 'eval') {
+            let code = url.searchParams.get('code') || ''
+            if (!code && req.method === 'POST')
+                code = await readBody(req)
+            if (!code) {
+                send(res, 400, 'eval needs ?code= or a POST body')
+                return
+            }
+            let r: { ok: boolean, value?: string, error?: string }
+            // Expression-first, statement-block fallback — but the two wrappers must be SEPARATE
+            // page.evaluate calls. A single string with a runtime try/catch can't recover: the
+            // whole string is ONE parse unit, so a multi-statement body (`const n=5; n*2`) makes
+            // the expression branch `(async()=>(const n=5; n*2))()` a *syntax* error that aborts
+            // parsing before the catch can ever run (mirrors exit-1 runEval's two new Function()s).
+            const fmt = (value: unknown) => value === undefined ? undefined : typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+            // 8s cap:足够慢页面真算完(在线 demo/重渲染),又不会让卡死页面把 curl 吊到天荒地老。
+            // timeout error 的 message 含 'timed out' 不含 'SyntaxError' → 不会触发语句块重试(重跑卡死
+            // 页面只会再挂一次),直接当 422 报回可诊断信息。
+            try {
+                // page.evaluate JSON-clones the return so objects round-trip.
+                r = { ok: true, value: fmt(await withTimeout(page!.evaluate(`(async () => (${code}))()`), 8000, 'eval')) }
+            }
+            catch (e1) {
+                const m1 = e1 instanceof Error ? e1.message : String(e1)
+                if (m1.includes('SyntaxError')) {
+                    try {
+                        r = { ok: true, value: fmt(await withTimeout(page!.evaluate(`(async () => { ${code} })()`), 8000, 'eval')) }
+                    }
+                    catch (e2) {
+                        r = { ok: false, error: e2 instanceof Error ? e2.message : String(e2) }
+                    }
+                }
+                else {
+                    r = { ok: false, error: m1 }
+                }
+            }
+            const hint = diagnoseEval(code, r.ok, r.error)
+            const body = r.ok ? (r.value ?? 'undefined') : `error: ${r.error}`
+            send(res, r.ok ? 200 : 422, hint ? `${body}\n\nhint: ${hint}` : body)
+            return
+        }
+
+        // /screenshot — pixels, not the character sketch. The escape hatch for visual verification
+        // (a chart, a captcha, a layout the降采样 sketch clips). Writes a PNG to a temp file and
+        // returns the path — the agent reads it, a human opens it. ?sel= shoots one element;
+        // ?fullPage=1 captures the whole scroll height (default: viewport only).
+        if (parts[0] === 'screenshot') {
+            const sel = url.searchParams.get('sel')
+            const fullPage = url.searchParams.get('fullPage') === '1'
+            const file = path.join(os.tmpdir(), `aihand-shot-${++actionId}.png`)
+            try {
+                if (sel) {
+                    const el = page!.locator(sel).first()
+                    if (await el.count() === 0) {
+                        send(res, 404, `screenshot: no element matches ${sel}`)
+                        return
+                    }
+                    await el.screenshot({ path: file })
+                }
+                else {
+                    await page!.screenshot({ path: file, fullPage })
+                }
+                send(res, 200, `screenshot saved: ${file}`)
+            }
+            catch (e) {
+                send(res, 500, `screenshot failed: ${e instanceof Error ? e.message : String(e)}`)
+            }
+            return
+        }
+
+        // /chain — POST 一串动作,一往返跑完整个交互(每步 settle 后再下一步,fail-fast)。
+        // 驱动外部站点的已知多步序列(登录:fill→fill→click;搜索:fill→press)免逐步往返。
+        // 循环/渲染/skipped 汇报走内核 runChain;出口2 的单步执行器纯 dispatchAction(无 knob 特例)。
+        if (parts[0] === 'chain') {
+            let steps: ChainStep[]
+            try {
+                steps = JSON.parse(await readBody(req))
+                if (!Array.isArray(steps))
+                    throw new Error('body must be a JSON array')
+            }
+            catch (e) {
+                send(res, 400, `invalid chain body: ${e instanceof Error ? e.message : String(e)}`)
+                return
+            }
+            const dr = await runChain(steps, (type, args) =>
+                dispatchChainStep(bridge!, type, args, { nextId: () => ++actionId, afterNav: navProbe() }))
+            send(res, dr.status, dr.body)
+            return
+        }
+
+        // trusted 门控动作(drag/realclick)走 page.mouse 真实指针事件,不下沉到合成 in-page 路径
+        // —— SortableJS/dnd-kit/原生 DnD/isTrusted-gated handler 只认真实事件。出口2 独有(握 page 句柄)。
+        if (parts[0] === 'drag') {
+            if (!page || !bridge) {
+                send(res, 400, 'no page open — run `aihand probe open <url>` first')
+                return
+            }
+            const to = url.searchParams.get('to')
+            if (!to) {
+                send(res, 400, 'drag needs to= (destination selector)')
+                return
+            }
+            const dr = await trustedDrag(url.searchParams.get('sel') || undefined, url.searchParams.get('text') || undefined, to)
+            send(res, dr.status, dr.body)
+            return
+        }
+        if (parts[0] === 'realclick') {
+            if (!page || !bridge) {
+                send(res, 400, 'no page open — run `aihand probe open <url>` first')
+                return
+            }
+            const c = await resolveDragCoords(url.searchParams.get('sel') || undefined, url.searchParams.get('text') || undefined, url.searchParams.get('sel') || url.searchParams.get('text') || '')
+            // resolveDragCoords 的 to 这里复用 src(realclick 只需一个目标);src 解析失败即报。
+            if (!c.ok) {
+                send(res, 422, c.error)
+                return
+            }
+            await page.mouse.click(c.sx, c.sy, { button: url.searchParams.get('button') === 'right' ? 'right' : 'left' })
+            const { result } = await dispatchScreen(bridge)
+            send(res, 200, `realclicked ${c.srcLabel} (trusted page.mouse)\n\n--- changed ---\n${result.body}`)
+            return
+        }
+
+        if (isDispatchAction(parts[0])) {
+            const args = argsFromQuery(url.searchParams)
+            // afterNav:出口2 独有。点链接触发整页导航时,探针随旧文档死,它的 after 帧采的是旧页残影。
+            // 导航信号由 cdpBridge 派发动作撞上下文销毁时经 onNav 交给 dispatch(零轮询),这里只在
+            // 确实导航后被调:url() 读新页 URL、renavScreen 采新页全貌,换页确认 + 新页并回这一往返
+            // (对齐出口1 的「行动+确认一次结清」)。同文档动作 onNav 不触发 → 这俩都不被调,零延迟。
+            const dr = await dispatchAction(bridge, parts[0], args, { nextId: () => ++actionId, afterNav: navProbe() })
+            send(res, dr.status, dr.body)
+            return
+        }
+
+        // 绿色通道(/action?knob=)是 app 自驱能力——replay app 自己的 store 态射,依赖 app 暴露
+        // __AIPEEK_STORES__ + build-time knobSem schema。CDP 空降到外部站零合作,二者皆不存在,
+        // @kN 旋钮也不存在(numberKnobs 只编号 kind:'knob' 的 Box)。误导消息会让 agent 看不懂
+        // 又不知替代;细分到动作:点名 knob 专属性 + 指向外部站该用的 DOM 寻址(ker 诊断⊆ker 动作)。
+        if (parts[0] === 'action' || parts[0] === 'knob') {
+            send(res, 422, 'knob green channel replays the app\'s own store morphisms — '
+                + 'unavailable when driving an external site (no app store schema). '
+                + 'use click/fill/press with text= or sel= instead.')
+            return
+        }
+
+        send(res, 404, `unknown probe command: ${parts[0]}`)
+    }
+    catch (err) {
+        send(res, 500, `probe error: ${(err as Error).message}`)
+    }
+})
+
+server.listen(PORT, () => console.log(`aihand probe server on :${PORT}`))
+
+// 优雅退出:kill/Ctrl-C 时关 browser,不留 chromium 僵尸进程(否则反复 spawn server 会堆积无头 chromium)。
+// browser?.close() 对一个已断连的 browser 可能永不 resolve(playwright 等关闭确认等不到),故 1s
+// 兜底无论如何强制 exit——清不掉总比挂死强(实测:不兜底则首个 SIGTERM 被 close() 吞住,进程不退)。
+let exiting = false
+for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+    process.on(sig, () => {
+        if (exiting)
+            process.exit(0) // 第二次信号:别再等,立刻走
+        exiting = true
+        setTimeout(() => process.exit(0), 1000).unref()
+        browser?.close().catch(() => {}).finally(() => process.exit(0))
+    })
+}

package/src/ui/self/act.ts

@@ -0,0 +1,47 @@
+// self-act —— 第三原语。delta = 两次 self-rep 投影的差。
+//
+// self-act 不是新机制:一次动作发生后,self 从 before 投影变到 after 投影,delta 就是
+// 「这次动作引起了什么」。这正是 aihand 的 diffState 在做的事 —— view/modal/focus 转移
+// + domain 状态机转移。但 diffState diff 的是 panel/knob 投影,act diff 的是 Self;
+// 两者语义不同,故内联同一套 stringify+逐键比较,而非复用 diff.ts(强合=耦合两个不同的 diff)。
+//
+// 贡献不是这个 diff,而是「两次投影差」这个接法 + 被 diff 的 domain 来自静态引擎长出的
+// 声明(见 screen-hook),不是手挂。三原语的第三个:self-rep(感知)/ self-log(物理)/ self-act(变化)。
+
+import type { Self } from './self'
+
+// 一行、有界、比较稳定的 domain 值字符串化。既用于探测变化(字符串相等),也用于渲染转移。
+function stringifyDomain(v: unknown): string {
+    if (v === null || v === undefined)
+        return String(v)
+    if (typeof v === 'object')
+        return JSON.stringify(v).slice(0, 80)
+    return String(v).slice(0, 80)
+}
+
+// before → after 的 self-rep 投影差。view/modal/focus 转移 + state(domain)逐键转移。
+// 返回人类/AI 可读的 delta 行;无变化返回空数组(「这次动作什么也没动」)。
+export function act(before: Self, after: Self): string[] {
+    const lines: string[] = []
+    if (after.view !== before.view)
+        lines.push(`view: ${before.view} → ${after.view}`)
+    if (after.modal !== before.modal) {
+        if (after.modal === null)
+            lines.push(`modal: closed (${before.modal})`)
+        else if (before.modal === null)
+            lines.push(`modal: opened ${after.modal}`)
+        else
+            lines.push(`modal: ${before.modal} → ${after.modal}`)
+    }
+    if (after.focus !== before.focus)
+        lines.push(`focus: ${after.focus}`)
+    // state 即 domain —— app 自己的语义状态机。这些转移(如 流式 false→true)
+    // 是纯 DOM 投影看不见的,正是 self-rep 让它们可见。
+    for (const key of new Set([...Object.keys(before.state), ...Object.keys(after.state)])) {
+        const b = stringifyDomain(before.state[key])
+        const a = stringifyDomain(after.state[key])
+        if (b !== a)
+            lines.push(`${key}: ${b} → ${a}`)
+    }
+    return lines
+}