aihand 0.0.1 → 0.1.1

package/src/ui/server/help-text.ts

@@ -0,0 +1,237 @@
+// The /__aihand/help body — the full curl playbook for the runtime probe (read state →
+// reverse morphism → drive → chain → escape hatch). Pure: port → string, no closure deps.
+// Lifted out of plugin.ts verbatim so the two real plugin functions lead the file.
+export function helpText(port: number) {
+    const base = `http://localhost:${port}/__aihand`
+    return `
+# aihand — Runtime Browser Inspector
+
+IMPORTANT: Before debugging any UI issue, visual bug, or runtime error, ALWAYS fetch the live app state first. Do NOT guess — look at the actual browser state.
+
+## Read state — cheapest first
+
+\`\`\`bash
+curl ${base}/screen   # semantic layout tree (indent=nesting, 左/中/右) + {view, modal, focus, knobs} — START HERE (returns token: tN)
+curl '${base}/screen?form=visual' # same screen as an ASCII art sketch instead of the layout tree
+curl '${base}/screen?form=knobs'  # only the control surface: clickable knobs + their store morphisms, grouped by column
+curl '${base}/screen?since=tN'  # only what moved since that token (view/modal/focus + new errors), not a full snapshot
+curl ${base}/ui                  # React component tree — deep-dive when /screen isn't enough
+curl '${base}/dom?scope=ChatInput' # semantic DOM scoped to a component — UI as text, src locations
+curl ${base}          # high-density summary (ok sections → 1 line, issues → expanded)
+curl ${base}?full     # full dump: UI tree + console + network + errors + state
+curl ${base}/check    # pass/fail health check — use after code changes
+curl ${base}/console  # console logs (errors, warnings, info)
+curl ${base}/network  # fetch/XHR requests with status and timing
+curl ${base}/errors   # uncaught errors and unhandled rejections
+curl ${base}/state    # registered store snapshots (overview)
+curl ${base}/state/imStore           # drill into one store (domain)
+curl '${base}/state?path=imStore.conversations.0' # expand a nested value the overview collapsed to Array(N) (point)
+curl ${base}/tabs     # list live tabs (id, visible/background, title) for ?tab= addressing
+curl ${base}/timeline # interleaved action stream across all tabs (who clicked what, in order)
+curl '${base}/query?sel=[role=menuitem]' # this selector right now: count + each element's text/visible/attrs
+curl ${base}/profile  # performance profiler: which component/function is burning frames (+ source lines with AIPEEK_LINES=1)
+curl ${base}/profile/reset  # clear the profiler window, then reproduce the interaction
+curl ${base}/profile/diff  # closed loop: 1st call marks baseline, fix+reproduce, 2nd call → IMPROVED/REGRESSED verdict
+\`\`\`
+
+\`/profile\` is a verdict, not a flame graph — read it, fix, re-read, don't eyeball frames.
+Three tiers, escalate only as needed:
+
+\`\`\`bash
+# 1. Diagnose — one read names the component/function burning frames (self-time × render count)
+curl ${base}/profile
+
+# 2. Closed-loop A/B — proves a fix worked instead of guessing
+curl ${base}/profile/reset   # clear the window
+#   …reproduce the slow interaction (scroll, stream, type)…
+curl ${base}/profile         # 1st call = baseline snapshot
+#   …edit code + reproduce the SAME interaction…
+curl ${base}/profile/diff    # 2nd call → IMPROVED / REGRESSED / NO DATA verdict
+
+# 3. Line-level — break a hot component down to the exact source line
+AIPEEK_LINES=1 <your dev command>   # opt-in: line instrumentation taxes every render, off by default
+curl ${base}/profile
+\`\`\`
+
+Profiling is the ONE read that needs the tab FOREGROUND + FOCUSED — the OS throttles rAF
+for backgrounded/unfocused windows, so timing there is a lie. The profiler refuses to launder
+that lie: a throttled window reads \`Frames: none sampled\` and a window that didn't reproduce
+the workload reads \`NO DATA\`, never a fabricated \`0.0% dropped\` / \`IMPROVED\`. A real verdict
+requires: tab in front, \`/profile/reset\`, then repeat the exact interaction. (\`/screen\` and
+\`/dom\` work fine backgrounded — only profiling needs focus.)
+
+\`/query\` is the read-side twin of click/fill's \`sel=\` — assert on a specific element
+(how many match, its text, \`data-state\`, \`aria-*\`/\`data-*\`, value, disabled) without \`/eval\`.
+Secret fields (password inputs, API-key/token fields) show \`‹redacted N chars›\` instead of
+their value across \`/dom\`, \`/query\` and \`/screen\` — length stays visible, the secret doesn't.
+
+\`/screen\` projects the whole UI to a few state variables — start there, not \`/ui\`. Append
+\`?full\` for untruncated output. Each read prints a \`token: tN\` line; pass it back as
+\`/screen?since=tN\` to get only the transition since that read (view/modal/focus + new
+errors/failed requests), \`(no state change)\` if nothing moved — the cheap "what changed
+after I acted" read, without re-paying for the unchanged 99%.
+
+To inspect or edit a component, work top-down — the full DOM is huge, a scoped view is
+accurate: \`/screen\` or \`/ui\` to find the component, then \`/dom?scope=<Name>\` (matches the
+source path) or \`/dom?sel=<css>\` for just that subtree. Each line carries its source
+location (\`@File.tsx:line\`), so the DOM view tells you exactly where to edit.
+
+## UI → code reason (reverse morphism)
+
+\`\`\`bash
+curl '${base}/source?path=src/features/Sidebar/index.tsx:78'  # which symbol owns this line + its callers/callees
+curl -G ${base}/source --data-urlencode 'path=<data-insp-path>'  # feed /dom's data-insp-path raw (rel:line:col:Name)
+\`\`\`
+
+\`/dom\` tells you *where* a UI element lives (\`@File.tsx:line\`); \`/source\` tells you *what code
+backs it* — the enclosing symbol, who calls it, what it calls. Paste a \`data-insp-path\`
+(\`rel:line:col:Name\`) straight from \`/dom\`. This is the static twin of \`/open\` (which sends the
+same coordinate to your editor): point at a rendered element → get its code reason, without grepping.
+
+## Drive the page (acts on the currently-open tab — no separate browser)
+
+Pass \`text=\`/\`sel=\`/\`value=\` via \`-G --data-urlencode\` — **always**, not just for CJK. A raw
+\`?text=群聊\` is an illegal HTTP request-target, rejected with an empty 400 *before aihand runs*
+(a wasted round-trip); \`--data-urlencode\` escapes it for you, so the same form works for \`New\`
+and \`群聊\` alike — write it right the first time.
+
+\`\`\`bash
+curl -G ${base}/click  --data-urlencode 'text=New'              # click by visible text (or 'sel=<css>')
+curl -G ${base}/dblclick --data-urlencode 'text=todo'          # double-click (inline edit / rename / select); fires dblclick handlers click can't
+curl -G ${base}/hover  --data-urlencode 'text=More'             # hover only (reveal a menu/tooltip; no click)
+curl -G ${base}/fill   --data-urlencode 'sel=textarea' --data-urlencode 'value=hi'  # set input/textarea; <select> matches by option text
+curl -G ${base}/press  --data-urlencode 'key=Enter'            # key on focused element (e.g. Control+a)
+curl -G ${base}/wait   --data-urlencode 'text=Done' -d 'timeout=8000'  # poll until text/sel appears (gone=1 until it disappears; enabled=1 until not [disabled])
+curl '${base}/screenshot?out=shot.png'                          # DOM→PNG into .aidev/ (html-to-image; lossy)
+\`\`\`
+
+ASCII-only values may use the bare \`?text=New\` form, but \`-G --data-urlencode\` is never wrong —
+prefer it so a value that turns out to contain CJK/space/\`&\` doesn't silently 400.
+
+\`click\`/\`fill\`/\`press\` settle the DOM and append \`--- changed ---\`: only the state-machine
+transition this action caused (\`view: a → b\`, \`modal: opened X\`, \`focus: …\`) plus any new
+errors/failed requests — not a fresh snapshot. \`(no state change)\` means nothing moved. Read
+the delta, then drill into /ui or /dom for detail if you need it. On a miss, the response lists
+the reachable clickable elements so you can re-target.
+
+Each \`click\`/\`fill\`/\`press\` response also carries a \`--- recent actions ---\` timeline:
+the semantic page actions (yours and the user's) in order, \`T\`=trusted human / \`S\`=synthetic
+aihand, each with its resulting UI change (\`→ 弹窗打开「…」\`/\`→ 弹窗关闭\`). Your own action is
+bracketed by \`你当前的行为\` dividers. So if the user closed a dialog you just opened, you see
+their \`T key:Escape → 弹窗关闭\` right after your \`S\` action — no need to query for it.
+
+**Beyond click/fill/press** — four more interactions for what those can't reach:
+
+\`\`\`bash
+curl '${base}/scrollIntoView?text=Row 99'              # scroll a target into view (off-screen list rows)
+curl '${base}/drag?sel=.item&to=.slot'                 # synthetic pointer drag, source → destination
+curl '${base}/drop?sel=.dropzone&files=a.png,b.pdf'    # fire a file-drop (DataTransfer) on a target
+curl '${base}/clipboard?mode=write&value=hi'           # seed the clipboard (mode=read reports it back)
+\`\`\`
+
+\`drag\` fires a real pointer sequence (down → stepped moves past dnd-kit's activation
+distance → up); if a dnd-kit reorder doesn't take, retry the same gesture via \`realclick\`
+(trusted events). \`drop\` delivers the drop event with the named files (synthetic Files have
+no byte content — fine for triggering handlers, not for real uploads). \`clipboard\` needs the
+tab focused (browser security) and says so plainly when it isn't, rather than hanging.
+
+A control tagged \`{needs-trusted?}\` in \`/screen\` or \`/dom\` opens a popup (\`aria-haspopup\`)
+that a synthetic click may not trigger — reach for \`realclick\` on it from the start instead
+of discovering it via a dead click. (Right-click-only menus carry no DOM marker, so they
+still surface only on a miss — use \`realclick\` with \`button=right\` there.)
+
+**Green channel — replay a knob's morphism, no DOM.** \`/screen?form=knobs\` lists every
+control with its store morphism (\`「群聊」→ appUIStore.{ mode=im }\`). \`/action?knob=<label>\`
+replays that morphism by writing the store directly — bypassing selector resolution, disabled
+gating, and the silent-false-success a covered \`/click\` can return. It's smoother than
+\`/click\`+\`/fill\` for any control whose effect is a store write:
+
+\`\`\`bash
+curl -G ${base}/action --data-urlencode 'knob=群聊'            # literal:  appUIStore.mode='im'
+curl -G ${base}/action --data-urlencode 'knob=深度研究'        # toggle:   flips the bool
+curl -G ${base}/action --data-urlencode 'knob=最大Token' --data-urlencode 'value=8'   # param: needs ?value=
+curl ${base}/action?knob=@k3                                   # @kN: addressable ref from /screen, no CJK escaping
+\`\`\`
+
+Every \`/screen\` projection tags each knob with a stable \`@kN\` ref (the number in \`?form=knobs\`,
+shared across the ASCII art / tree / legend). \`/action?knob=@k3\` resolves it back to the label —
+saving the CJK \`--data-urlencode\` round-trip and any \`&file=\` disambiguation. A stale/unknown
+\`@kN\` is refused (422 listing the current numbers) — re-read \`/screen\` for fresh ones; it never
+silently hits the wrong knob.
+
+Returns the same \`--- changed ---\` trajectory a \`/click\` does (waitForStable + diffScreen),
+not a full state dump. A knob whose value depends on runtime context (\`e.target.value\`, a
+mapped array, a method with args) is **refused** (422 + reason) — fall back to \`/click\`/\`/fill\`
+there; it never fake-replays. A label two components share returns 422 + candidates; add
+\`&file=<path-fragment>\` to disambiguate.
+
+**Multiple tabs.** Every read/drive command takes \`?tab=<id>\` to address one specific tab —
+including a **background** one (you can drive the Chat tab while the user is looking at a
+different tab). Run \`${base}/tabs\` to see the live ids. With one tab open, omit \`?tab=\` and
+it just works. With several tabs open and no \`?tab=\`, the command returns \`409\` + the tab
+list (rather than randomly hitting one) — pick an id from it and retry with \`?tab=\`.
+
+**Multiple servers (federation).** When several dev servers run at once — a micro-frontend,
+separate front/back servers, or a teammate's machine — every command also takes
+\`?host=<host:port>\` to reach a *sibling* aihand. The plugin you curl reverse-proxies the
+request to that peer (server-side, no browser): \`${base}/screen?host=localhost:5174\` reads
+the app on :5174; combine with \`?tab=\` to point at one tab over there
+(\`?host=192.168.1.9:5173&tab=t3\`). Omit \`?host=\` and it's the local server as always. There's
+no registry — you name the peer, so list its tabs with \`/tabs?host=<host:port>\` first.
+
+**Cross-tab timeline.** \`${base}/timeline\` interleaves the semantic actions of *every* tab
+in time order — each line \`<tab> [T|S] <action> → <ui change>\` (\`T\`=trusted human,
+\`S\`=synthetic aihand). The per-action \`--- recent actions ---\` tail only shows the acting
+tab; \`/timeline\` is the group view, so an A/B comparison across two tabs (drive A, watch B
+react) is one read. \`?tab=<id>\` filters to one tab's history.
+
+**Chain — a whole interaction in one round-trip.** POST a JSON array; runs in sequence,
+each step settles before the next, stops on first failure. A failed step carries the same
+\`clickable:\` fallback list a single-shot \`/click\` gives, and a trailing
+\`[n..m] skipped (… not run)\` line names every step the fail-fast stop left unrun — the page
+is parked in a half-done state, not rolled back (page actions aren't transactional):
+
+\`\`\`bash
+curl -X POST ${base}/chain -d '[
+  {"type":"knob","knob":"群聊"},
+  {"type":"assert","screen":"appUIStore.mode","equals":"im"},
+  {"type":"click","sel":"button[title=\\"知识库\\"]"},
+  {"type":"wait","text":"Done"},
+  {"type":"fill","sel":"textarea","value":"hi"},
+  {"type":"assert","screen":"<a domain key from /screen>","equals":"false"},
+  {"type":"press","key":"Enter"}
+]'
+\`\`\`
+
+The \`screen\` key in an \`assert\` must be a real field from \`/screen\`'s \`domain:\` block (e.g.
+\`streaming\`, \`appUIStore.mode\`) — copy it verbatim, the names are app-specific. A wrong key
+fails with \`no domain key "X" — available: …\` listing every real one.
+
+A \`knob\` step (\`{type:"knob",knob:"<panel label>"[,value,file]}\`) replays a panel morphism
+via the green channel — the store-direct optimal path \`/action?knob=\` takes, now inside a
+batch. Prefer it over \`click\` when a knob exists: no selector resolution, no overlay gating.
+
+\`assert\` is the chain's mid-step judge: \`{type,screen,equals}\` checks a domain variable
+(from the app's \`window.__AIPEEK_SCREEN__\`), or \`{type,sel,equals}\` an element's text. On
+mismatch the chain stops and reports \`asserted X=="Y", actual "Z"\` — a test, not a guess.
+Domain variables also show up in \`/screen\`'s \`domain:\` block and in every \`--- changed ---\`
+diff (e.g. \`流式中: false → true\`) — the app's own state machine, which a DOM-only inspector
+can't see. The app opts in by setting \`window.__AIPEEK_SCREEN__ = () => ({...})\`.
+
+**Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
+JS in the page and returns the result — for what the typed endpoints can't do (install listeners,
+read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
+When the code is a hand-rolled \`/state\` (or the selector is illegal), the response tail carries a \`hint:\` line pointing at the typed twin.
+
+aihand auto-detects errors after HMR and prints them to the terminal — watch for \`[aihand]\` messages.
+
+**Iterating on aihand itself.** Editing this server's own code (\`plugin.ts\` and anything in the Vite
+config dependency graph) makes Vite AUTO-restart the dev server in-process — terminal prints
+\`…changed, restarting server…\` then \`server restarted.\`, PID unchanged. You do NOT restart it by
+hand and you do NOT ask the user to; just edit and wait ~2-4s, then poll \`${base}/tabs\` for the page
+to re-register (it self-heals via an unthrottled heartbeat). The client probe (\`client.ts\`) instead
+hot-swaps in place keeping app state. Server stdout goes to the user's terminal (you can't read it) —
+to make server-side state curl-observable, add a temporary debug route, let Vite auto-restart, then
+remove it.
+`
+}

package/src/ui/server/knob-schema.ts

@@ -0,0 +1,87 @@
+// aihand/vite — 旋钮语义的 build 时投影,活的 /screen 的输入端零件。
+//
+// 对偶于 aiself storeSchema(状态/输出端):那个把 store 的值域从类型注解长出,这个把
+// 旋钮的态射(拨它 → store.{field=to})从组件 onClick 长出。两者都是「build 时 AST、
+// 运行时纯 JSON」—— tree-sitter 只在这里(Node 侧)跑,浏览器只收一张 join 表。
+//
+// 为什么 build 时:extractKnobs 走 web-tree-sitter,绝不进浏览器(同 aiself §0.3.0 铁律)。
+// /screen 运行时只有 DOM 候选(label + @File:line);语义这一半在这里备好,运行时按
+// join 键 label+file 拼回去。join 键不是 file:line —— host 行 ≠ handler 行,组件边界处错位。
+
+import type { KnobArity, KnobOp } from '../../read/panel.js'
+import { globSync } from 'glob'
+import { buildPanel, classifyKnob, fmtTransitions } from '../../read/panel.js'
+
+const VIRTUAL = 'virtual:aihand-knobs'
+const RESOLVED = '\0' + VIRTUAL
+
+interface Options {
+    // 扫哪些组件文件(glob,相对 vite root)。默认全 src 下的 tsx/jsx。
+    include?: string[]
+}
+
+// 一个旋钮在浏览器侧需要的最小投影:渲染好的态射 + store + 坐标 + 可执行算子。
+// key 由 label+file 拼成(join 键),client 用 DOM 候选的 label+file 查它。
+// transitions(人读串)供 /screen morphism 渲染;ops/arity/executable 供绿色通道 executeKnob 直接执行。
+export interface KnobProjection {
+    transitions: string // 'mode=im' / 'showSideBar=!showSideBar'
+    store: string
+    line: number
+    ops: KnobOp[] // 结构化算子(field+kind+arity+to/reason),executeKnob 按 kind 分派
+    arity: KnobArity // 整钮:nullary(直接 replay) / param(需 ?value=)
+    executable: boolean // false = 任一 op 依赖运行时上下文,诚实拒绝
+}
+
+// 旋钮 join 键:label + file。label 为 null(纯图标旋钮)时退回 tag,仍带 file 区分。
+// 与 client 侧从 @File:line 取 file 段、从 DOM 取 label 的拼法必须一致。
+function keyOf(label: string | null, tag: string, file: string): string {
+    return `${label ?? `<${tag}>`} ${file}`
+}
+
+export function knobSchema(options: Options = {}) {
+    const include = options.include ?? ['src/**/*.tsx', 'src/**/*.jsx']
+    let cache: Record<string, KnobProjection> | null = null
+
+    const build = async (): Promise<Record<string, KnobProjection>> => {
+        if (cache)
+            return cache
+        const files = globSync(include, { nodir: true, ignore: ['**/node_modules/**'] })
+        const knobs = await buildPanel(files)
+        const byKey: Record<string, KnobProjection> = {}
+        for (const k of knobs) {
+            // filePath 是 glob 给的相对/绝对路径;client 侧的 file 来自 babel data-insp-path,
+            // 通常是末两段(如 Sidebar/index.tsx)。统一成末两段做 join 键。
+            const file = k.filePath.split('/').slice(-2).join('/')
+            const { ops, arity, executable } = classifyKnob(k.transitions)
+            byKey[keyOf(k.label, k.tag, file)] = {
+                transitions: fmtTransitions(k.transitions),
+                store: k.store,
+                line: k.line,
+                ops,
+                arity,
+                executable,
+            }
+        }
+        cache = byKey
+        return byKey
+    }
+
+    return {
+        name: 'aihand:knob-schema',
+        resolveId(id: string) {
+            if (id === VIRTUAL)
+                return RESOLVED
+        },
+        async load(id: string) {
+            if (id !== RESOLVED)
+                return
+            const knobs = await build()
+            return `export const knobs = ${JSON.stringify(knobs)}\n`
+        },
+        // 组件改动 → 失效缓存,HMR 重投影(onClick 改了 → 态射跟着变)。
+        handleHotUpdate(ctx: { file: string }) {
+            if (ctx.file.endsWith('.tsx') || ctx.file.endsWith('.jsx'))
+                cache = null
+        },
+    }
+}