aihand 0.0.1 → 0.1.0

package/src/ui/babel/source-loc.ts

@@ -0,0 +1,68 @@
+// Source NodePath + types from @babel/core so they share one module identity. Mixing
+// @babel/traverse's NodePath with a standalone @babel/types import pins them to
+// different @babel/types copies when versions resolve (JSX node variance error).
+import type { NodePath, PluginObj, types as BabelTypes } from '@babel/core'
+import path from 'path'
+
+type JSXOpeningElement = BabelTypes.JSXOpeningElement
+
+// Babel plugin: stamp every host JSX element with a `data-insp-path` source-location
+// attribute — the same attribute aihand's client already consumes (client.ts inspPath /
+// scopeRoot) to print `@File.tsx:line` and to power `/dom?scope=`. aihand now produces the
+// marker it reads, so one plugin covers both click-to-source (the overlay in client.ts) and
+// the AI's source-aware DOM — no separate source-location plugin needed.
+//
+// Format is "relative/path.tsx:line:col:Name". aihand only reads
+// segs[0] (file) + segs[1] (line); the trailing name is the file basename, informational only.
+//
+// Only HOST elements (lowercase tag → a real DOM node) get the attribute — a component
+// element (<Foo>) renders to its own host children, which carry their own marks. Fragments
+// and elements that already declare data-insp-path are skipped.
+//
+// Takes the babel `types` builder as a param (the standard plugin-API form) instead of a
+// static `import * as t from '@babel/types'`. That keeps this module free of any runtime
+// babel import, so plugin.ts (which IS bundled into dist) can import it without pulling
+// @babel/types into both output formats and breaking the dual-format contract.
+export function sourceLocPlugin(t: typeof BabelTypes): PluginObj {
+    return {
+        name: 'aihand-source-loc',
+        visitor: {
+            JSXOpeningElement(nodePath: NodePath<JSXOpeningElement>, state) {
+                const filename: string = state.file?.opts?.filename ?? ''
+                if (!filename || filename.includes('node_modules'))
+                    return
+                if (filename.includes('packages/aidev/'))
+                    return
+
+                const nameNode = nodePath.node.name
+                // host element only: <div>, <span> — a lowercase JSXIdentifier. Skip <Foo>,
+                // <Foo.Bar> (member expression), and namespaced names.
+                if (!t.isJSXIdentifier(nameNode))
+                    return
+                const tag = nameNode.name
+                if (tag[0] === tag[0].toUpperCase())
+                    return
+
+                if (hasInspAttr(t, nodePath.node))
+                    return
+
+                const loc = nodePath.node.loc
+                if (!loc)
+                    return
+
+                const root: string = state.file?.opts?.root ?? ''
+                const rel = root ? path.relative(root, filename) : filename
+                const value = `${rel}:${loc.start.line}:${loc.start.column + 1}:${path.basename(rel, path.extname(rel))}`
+
+                nodePath.node.attributes.push(
+                    t.jsxAttribute(t.jsxIdentifier('data-insp-path'), t.stringLiteral(value)),
+                )
+            },
+        },
+    }
+}
+
+function hasInspAttr(t: typeof BabelTypes, node: JSXOpeningElement): boolean {
+    return node.attributes.some(a =>
+        t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === 'data-insp-path')
+}

package/src/ui/bridge/cdp-bridge.ts

@@ -0,0 +1,138 @@
+import type { ServerBridge } from './transport'
+
+// 出口2 桥:把一个 playwright Page 包成 ServerBridge。与 viteBridge 同构,但单页直连——
+// 没有多 tab、没有 requireVisible、没有 twoPhase 两段投递。是 twoPhase 的退化版「evaluate 派发 + 超时」。
+//
+//   server→browser 发请求 = page.evaluate(window.__aihandRecv, reqEvent, {id,...})
+//   browser→server 回回复 = 探针 window.__aihandSend(replyEvent, {id,...}),由 page.exposeBinding
+//                          注册的 binding 收,按 event 分发到等同一 replyEvent + id 的 request。
+//
+// exposeBinding('__aihandSend') 必须在 addInitScript(探针) 之前注册(见 probe/server.ts)。
+
+// playwright Page 的最小依赖面——只用 evaluate(传 [event,payload] 元组进页面),不引整个
+// playwright 类型(出口2 独占)。exposeBinding 接线在 probe/server.ts 做,bridge 不碰。
+// settle:整页导航把旧文档执行上下文销毁,evaluate 撞 "Execution context was destroyed";
+// bridge 调 settle()(server 注入 = waitForLoadState)等新文档就绪后重试一次。
+export interface ProbePage {
+    evaluate: (fn: (a: [string, object]) => unknown, arg: [string, object]) => Promise<unknown>
+    settle?: () => Promise<void>
+    // 主帧「导航意图」订阅(出口2 由 CDP Page.frameRequestedNavigation 接线,出口1 不实现 → 恒不 fire)。
+    // 实测:锚点 click 的 reply 在 ~62ms 先回(探针 handler 已跑完),framenavigated(commit)要等
+    // ~1500ms 网络往返才到——太晚抓不住。frameRequestedNavigation(intent)在 click handler 同步设
+    // location 时即 fire(~61.7ms,先于 reply),带目标 URL。这是「动作触发整页导航」唯一与动作同源、
+    // 先于 reply 的地面真值。竞速语义:fire 既置 navigated 标记又 settle request(合成 {ok:true})——
+    // 导航场景 reply 从被销毁的旧文档发出必丢,不竞速就死等超时(见 request)。request 飞行期订阅一次,
+    // settle 时退订;reply 先到则退订本闩,迟到 intent 落空。返回退订 fn。
+    onMainFrameNavIntent?: (cb: () => void) => () => void
+    // 主帧「同文档路由切换」订阅(SPA pushState:Turbo/React Router,URL 变但文档不销毁)。与上面的
+    // 整页导航闩对偶——整页导航销毁上下文让 reply 丢失故能竞速,同文档导航上下文存活、reply 快速带残缺
+    // screen 先回赢竞速,真正的换页 morph 在 reply 后 ~0.2~1.4s 才到(CDP Page.navigatedWithinDocument)。
+    // 故这个信号必须 outlive reply:不接进 request 竞速,由 dispatch 在动作前 arm、reply 后等(见
+    // NavProbe.awaitSameDocNav)。回调仅在主帧 ∧ URL path 真变(非纯 #hash 锚点滚动)时触发,实测对
+    // 普通非导航 click 零误报。出口1 不实现 → 恒不 fire,零回归。返回退订 fn。
+    onMainFrameSameDocNav?: (cb: () => void) => () => void
+}
+
+type Waiter = { id?: number, resolve: (v: any) => void }
+
+// 整页导航瞬态:旧文档上下文销毁 / 页面正导航中。撞上就 settle + 重试一次,不是真失败。
+function isNavTransient(err: unknown): boolean {
+    const m = (err as Error)?.message ?? ''
+    return m.includes('Execution context was destroyed') || m.includes('because of a navigation')
+}
+
+// evaluate 派发,撞导航瞬态(派发撞上一个正在 settle 的页面)则 settle(等新文档) + 重试一次。
+// 一次足够:settle 后探针随 init script 已在新文档重注入,第二次必落在稳定上下文。
+// 此处 onNav 是次要信号(派发本身撞销毁);「动作触发整页导航」的主信号走 request 的 onceMainFrameNav
+// 闩——因为派发消息的那次 evaluate 干净返回(消息已落地),才轮到导航销毁上下文,这里不会抛。
+async function evalWithSettle(page: ProbePage, arg: [string, object], onNav?: () => void): Promise<void> {
+    const fn = ([e, p]: [string, object]) => (window as { __aihandRecv?: (e: string, p: unknown) => void }).__aihandRecv?.(e, p)
+    try {
+        await page.evaluate(fn, arg)
+    }
+    catch (err) {
+        if (!isNavTransient(err) || !page.settle)
+            throw err
+        onNav?.()
+        await page.settle()
+        await page.evaluate(fn, arg)
+    }
+}
+
+// page 与 exposeBinding 的接线在 probe/server.ts 启动时做一次;这里只需 page + 一个
+// 共享的 waiters 表(server 把 __aihandSend 收到的回复喂进 deliver)。
+export function cdpBridge(page: ProbePage): { bridge: ServerBridge, deliver: (event: string, payload: { id?: number, [k: string]: unknown }) => void } {
+    // replyEvent → 等待者集合。一次 request 装一个 waiter,deliver 命中即 resolve + 摘除。
+    const waiters = new Map<string, Set<Waiter>>()
+
+    const deliver = (event: string, payload: { id?: number, [k: string]: unknown }) => {
+        const set = waiters.get(event)
+        if (!set)
+            return
+        for (const w of set) {
+            if (w.id !== undefined && payload.id !== w.id)
+                continue
+            set.delete(w)
+            w.resolve(payload)
+            return
+        }
+    }
+
+    const request = <T>(
+        reqEvent: string,
+        replyEvent: string,
+        payload: object,
+        opts?: { timeoutMs?: number, onNav?: () => void },
+    ): Promise<T> => {
+        const fullMs = opts?.timeoutMs ?? 3000
+        const id = (payload as { id?: number }).id
+        return new Promise<T>((resolve, reject) => {
+            const waiter: Waiter = { id, resolve }
+            let set = waiters.get(replyEvent)
+            if (!set) {
+                set = new Set()
+                waiters.set(replyEvent, set)
+            }
+            set.add(waiter)
+            // reply / 超时 / 派发异常 汇进一个幂等 finish:恰好一个 settle,全路径 clearTimeout + 摘
+            // waiter + 退订导航意图闩,无定时器/监听器泄漏。导航不参与 settle(见下,锁存非竞速)。
+            let unsubNav: (() => void) | undefined
+            let done = false
+            const finish = (fn: () => void) => {
+                if (done)
+                    return
+                done = true
+                clearTimeout(timer)
+                set!.delete(waiter)
+                unsubNav?.()
+                fn()
+            }
+            const timer = setTimeout(() => finish(() => reject(new Error(`probe: no reply on ${replyEvent} within ${fullMs}ms`))), fullMs)
+            waiter.resolve = v => finish(() => resolve(v))
+            // 导航意图闩:三方竞速(reply / 导航意图 / 超时),谁先到谁 settle。动作触发整页导航时,
+            // 探针的 reply 从旧文档发出而上下文已被导航销毁 → reply 必丢。若闩只置位不 settle,request
+            // 就死等丢失的 reply 到 5s 超时(实测 example→iana 5027ms 假超时,而页面其实已导航成功)。
+            // 故 intent fire 既调 onNav 置位 navigated、又合成 {ok:true} 走 finish settle:reply 丢了也不死等,
+            // dispatch 读 result.ok && navigated → renavScreen 回填新页全貌。reply 先到则透传真 reply 并退订
+            // 本闩(intent 后到落空,done 已 true);无导航则 intent 永不 fire,零延迟。合成体仅 {ok:true} 不带
+            // detail/screen——renavScreen 的新页全貌已是 changed,加 detail 会与 navigated 行语义重复。
+            // 仅 opts.onNav 在时武装(只 dispatchAction 要 nav-backfill;collect-screen/emit/renavScreen
+            // 内部采帧都不传 → 不武装,纯 reply 等待,新文档 settle 期采帧不被误合成)。
+            unsubNav = opts?.onNav
+                ? page.onMainFrameNavIntent?.(() => finish(() => { opts.onNav!(); resolve({ ok: true } as T) }))
+                : undefined
+            // 派发进页面:探针的 onMsg(reqEvent) handler 收。撞整页导航瞬态(派发撞已在 settle 的页面)
+            // 则 settle + 重试一次,并经 onNav 把导航信号交给调用方(与意图闩幂等双置无害)。
+            evalWithSettle(page, [reqEvent, payload], opts?.onNav).catch(err => finish(() => reject(err)))
+        })
+    }
+
+    const emit = (event: string, payload: object) => {
+        page.evaluate(
+            ([e, p]: [string, object]) => (window as { __aihandRecv?: (e: string, p: unknown) => void }).__aihandRecv?.(e, p),
+            [event, payload],
+        ).catch(() => {})
+    }
+
+    return { bridge: { request, emit }, deliver }
+}

package/src/ui/bridge/compile-probe.ts

@@ -0,0 +1,80 @@
+import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { buildSync } from 'esbuild'
+
+// 出口2 探针字符串:把 client.ts 的 installProbe(连 core/* 一起)bundle 成自包含 IIFE,
+// 注入任意外部站点。对偶出口1(Vite dev server 内联随模块图加载)——出口2 没有 Vite,
+// 没有 HMR,没有 virtual:aihand-knobs,所以:
+//   · define import.meta.hot = undefined → client.ts 末尾的 Vite shim(if(import.meta.hot){…})
+//     整段 dead-code 消除(hello 报到、HMR 自愈、accept 字面量、virtual import 全不进 bundle)。
+//   · bundle 入口 = 一段 stdin 合成代码,import { installProbe } 后拼 CDP transport bootstrap:
+//       send  → window.__aihandSend(event, payload)(cdpBridge 的 exposeBinding 收)
+//       onMsg → 注册进本地 handler map,window.__aihandRecv(event,payload) 由 server 经
+//               page.evaluate 调进来分发。
+//   · knobSem 留空——外部站无 app schema,/screen knobs 退回纯 label+坐标(行为不变)。
+// compilePatch(plugin.ts)是 transformSync 单文件;这里必须 buildSync bundle(client.ts 引 core/*)。
+
+// client.ts 源码位置随运行形态变:dev(jiti 跑 src,本文件在 src/ui/bridge)= ../client;
+// built(tsup 把本文件打进 dist/ui/probe/server.js)__dirname=dist/ui/probe,而源码经 package.json
+// files:["dist","src"] 一并发布在 <root>/src/ui/client。从 __dirname 向上逐层找 src/ui/client/client.ts。
+function findClientDir(): string {
+    const local = [resolve(__dirname, '../client'), resolve(__dirname, 'client')]
+    for (const d of local) {
+        if (existsSync(resolve(d, 'client.ts')))
+            return d
+    }
+    // 向上找含 src/ui/client/client.ts 的祖先(dist 与 src 同处 package root)。
+    let dir = __dirname
+    for (let i = 0; i < 8; i++) {
+        const cand = resolve(dir, 'src/ui/client')
+        if (existsSync(resolve(cand, 'client.ts')))
+            return cand
+        const parent = resolve(dir, '..')
+        if (parent === dir)
+            break
+        dir = parent
+    }
+    return resolve(__dirname, '../client')
+}
+const clientDir = findClientDir()
+const clientPath = resolve(clientDir, 'client.ts')
+
+const BOOTSTRAP = `
+import { installProbe } from ${JSON.stringify(clientPath)}
+const handlers = new Map()
+const transport = {
+    send: (event, payload) => window.__aihandSend(event, payload),
+    onMsg: (event, handler) => {
+        let list = handlers.get(event)
+        if (!list) { list = new Set(); handlers.set(event, list) }
+        list.add(handler)
+        return () => list.delete(handler)
+    },
+}
+window.__aihandRecv = (event, payload) => {
+    const list = handlers.get(event)
+    if (list) for (const h of list) h(payload)
+}
+installProbe(transport)
+`
+
+let cached: string | undefined
+
+export function compileProbe(): string {
+    if (cached !== undefined)
+        return cached
+    const result = buildSync({
+        stdin: { contents: BOOTSTRAP, resolveDir: clientDir, loader: 'ts' },
+        bundle: true,
+        format: 'iife',
+        target: 'es2020',
+        define: { 'import.meta.hot': 'undefined' },
+        // minifySyntax 开 DCE/常量折叠(不改名,bundle 仍可读):没它 define 把 import.meta.hot
+        // 换成 undefined 后 `if (undefined){…}` 仍原样留在 bundle——Vite shim(HMR 自愈、accept、
+        // hello)全被打进外部站点。开了才把整段 if(undefined) 死代码消除。
+        minifySyntax: true,
+        write: false,
+    })
+    cached = result.outputFiles[0].text
+    return cached
+}

package/src/ui/bridge/transport.ts

@@ -0,0 +1,26 @@
+// 内核与出口之间的唯一耦合面。两层,只为已确定的两个 transport 抽,不预造第三个:
+//   Transport   —— 探针端(浏览器内)持有,双向消息的最小公约数,fire-and-forget,id 匹配不在这层。
+//   ServerBridge —— server 端持有,发一个 event 等一个 id 匹配的回复。
+//
+// 出口1(Vite)与出口2(CDP)是同一内核的两个适配器:viteBridge 把回复经 HMR WebSocket 广播
+// 按 id 收敛,cdpBridge 把回复经 page.exposeBinding 单页直连按 id 收敛——两者实现 ServerBridge,
+// dispatch 对二者无感知。
+
+export interface Transport {
+    send: (event: string, payload: unknown) => void
+    onMsg: (event: string, handler: (payload: any) => void) => () => void // 返回 off()
+}
+
+export interface ServerBridge {
+    // 发 reqEvent(带 server 生成的 id),等探针回 replyEvent 中 id 匹配的那条。
+    request: <T>(reqEvent: string, replyEvent: string, payload: object, opts?: {
+        tab?: string
+        timeoutMs?: number
+        lastProgress?: () => number | undefined
+        // 动作派发撞整页导航(旧文档上下文销毁)时调一次——出口2 的导航信号副产物。
+        // 出口1(Vite)SPA 路由无整页导航销毁,viteBridge 永不调,navigated 恒 false。
+        onNav?: () => void
+    }) => Promise<T>
+    // 单向广播,不等回复(perf-reset 等)。
+    emit: (event: string, payload: object) => void
+}

package/src/ui/bridge/vite-bridge.ts

@@ -0,0 +1,116 @@
+import type { ViteDevServer } from 'vite'
+import type { TabInfo } from '../core/types'
+import type { ServerBridge } from './transport'
+import { isLive } from '../core/util'
+
+// 出口1 桥:把 Vite HMR WebSocket 包成 ServerBridge。dispatch 对它无感知,只调 request/emit。
+//
+// twoPhase 双段投递逐字搬自 plugin.ts(行为不变):
+//   有 tab(?tab= 寻址)→ 跳过 requireVisible 段,只那个 tab 答;live 静默过 fullMs = 真 miss 快拒,
+//                       absent(server 刚重启/页面自愈中)→ 每 RETRY_MS 重投到 re-register,封顶 ABSENT_CEILING。
+//   无 tab          → 先 requireVisible 段(只前台 tab 答),VISIBLE_MS 内没人答 → 第二段问所有人。
+// 回复匹配:有 id 的(action/eval/semantic/knob)按 id 收;无 id 的(collect/dom/screen/state-path)
+// 收第一条匹配 replyEvent 的回复(原 plugin.ts 单 pending 槽 last-write-wins 的等价收敛)。
+// 每次 request 装一次性 server.hot.on(replyEvent) listener,settle 即自摘,不再散落常驻 listener + 命名槽。
+
+const VISIBLE_MS = 400
+
+export interface ViteBridgeDeps {
+    tabs: Map<string, TabInfo>
+    diagnose: (tab?: string) => string
+}
+
+export function viteBridge(server: ViteDevServer, deps: ViteBridgeDeps): ServerBridge {
+    // 异步流(发消息→流式→结束)合法地把动作开很久,客户端每帧 ping aihand:action-progress;
+    // 在此盖最新时戳,twoPhase 的 live-tab deadline 从最后生命迹象起算,而非派发起算——真挂的
+    // handler 仍会(无 ping → deadline 触发)拒。progress 收敛进桥,dispatch 无需手传 lastProgress。
+    const progressAt = new Map<number, number>()
+    server.hot.on('aihand:action-progress', (data: { id?: number }) => {
+        if (typeof data.id === 'number')
+            progressAt.set(data.id, Date.now())
+    })
+
+    const request = <T>(
+        reqEvent: string,
+        replyEvent: string,
+        payload: object,
+        opts?: { tab?: string, timeoutMs?: number, lastProgress?: () => number | undefined },
+    ): Promise<T> => {
+        const tab = opts?.tab
+        const fullMs = opts?.timeoutMs ?? 3000
+        const id = (payload as { id?: number }).id
+        const lastProgress = opts?.lastProgress ?? (id !== undefined ? () => progressAt.get(id) : undefined)
+        return new Promise<T>((resolve, reject) => {
+            let settled = false
+            const onReply = (data: T & { id?: number, tab?: string }) => {
+                if (settled)
+                    return
+                // id-bearing replies match by id; id-less replies (collect/dom/screen/state-path)
+                // take the first reply on this event — the prior single-slot last-write-wins.
+                if (id !== undefined && data.id !== id)
+                    return
+                settled = true
+                cleanup()
+                resolve(data)
+            }
+            server.hot.on(replyEvent, onReply)
+            const cleanup = () => {
+                server.hot.off(replyEvent, onReply)
+                if (id !== undefined)
+                    progressAt.delete(id)
+            }
+
+            // Addressed at one tab: skip the requireVisible round entirely — only that tab answers.
+            if (tab) {
+                const RETRY_MS = 500
+                const ABSENT_CEILING_MS = 10000
+                const startedAt = Date.now()
+                const deliver = () => server.hot.send(reqEvent, { ...payload, tab })
+                deliver()
+                const iv = setInterval(() => {
+                    if (settled) {
+                        clearInterval(iv)
+                        return
+                    }
+                    const t = deps.tabs.get(tab)
+                    const live = !!t && isLive(t, Date.now())
+                    const progress = lastProgress?.()
+                    const sinceLife = Date.now() - Math.max(startedAt, progress ?? 0)
+                    const elapsed = Date.now() - startedAt
+                    if (live) {
+                        if (sinceLife > fullMs) {
+                            clearInterval(iv)
+                            cleanup()
+                            reject(new Error(deps.diagnose(tab)))
+                        }
+                    }
+                    else if (elapsed > ABSENT_CEILING_MS) {
+                        clearInterval(iv)
+                        cleanup()
+                        reject(new Error(deps.diagnose(tab)))
+                    }
+                    else {
+                        deliver()
+                    }
+                }, RETRY_MS)
+                return
+            }
+            server.hot.send(reqEvent, { ...payload, requireVisible: true })
+            setTimeout(() => {
+                if (settled)
+                    return
+                server.hot.send(reqEvent, { ...payload, requireVisible: false })
+                setTimeout(() => {
+                    if (settled)
+                        return
+                    cleanup()
+                    reject(new Error(deps.diagnose(tab)))
+                }, fullMs)
+            }, VISIBLE_MS)
+        })
+    }
+
+    const emit = (event: string, payload: object) => server.hot.send(event, payload)
+
+    return { request, emit }
+}